httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From humbed...@apache.org
Subject svn commit: r1334622 [17/29] - in /httpd/site/trunk: cgi-bin/ content/ content/apreq/ content/apreq/docs/ content/apreq/docs/libapreq2/ content/contributors/ content/css/ content/dev/ content/dev/images/ content/dev/whiteboard/ content/docs-project/ co...
Date Sun, 06 May 2012 13:14:50 GMT
Propchange: httpd/site/trunk/content/dev/API-dict.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: httpd/site/trunk/content/dev/API.html
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/API.html?rev=1334622&view=auto
==============================================================================
--- httpd/site/trunk/content/dev/API.html (added)
+++ httpd/site/trunk/content/dev/API.html Sun May  6 13:14:42 2012
@@ -0,0 +1,806 @@
+<HTML>
+<HEAD>
+<TITLE>Shambhala API notes</TITLE>
+</HEAD>
+<BODY>
+<H1>Shambhala API notes</H1>
+
+These are some notes on the Shambhala API and the data structures you
+have to deal with, etc.  They are not yet nearly complete, but
+hopefully, they will help you get your bearings.<P>
+
+A few notes on general pedagogical style here.  In the interest of
+conciseness, all structure declarations here are incomplete --- the
+real ones have more slots, that I'm not telling you about.  For the
+most part, these are reserved to one component of the server core or
+another, and should be altered by modules with caution.  However, in
+some cases, they really are things I just haven't gotten around to
+yet.  Welcome to the bleeding edge.<P>
+
+Finally, here's an outline, to give you some bare idea of what's
+coming up, and in what order:
+
+<UL>
+  <LI> <A HREF="#basics">Basic concepts.</A>
+       <UL>
+	 <LI> <A HREF="#HMR">Handlers, Modules, and Requests</A>
+	 <LI> <A HREF="#moduletour">A brief tour of a module</A>
+       </UL>
+  <LI> <A HREF="#handlers">How handlers work</A>
+       <UL>
+	 <LI> <A HREF="#req_tour">A brief tour of the <CODE>request_rec</CODE></A>
+	 <LI> <A HREF="#req_orig">Where request_rec structures come from</A>
+	 <LI> <A HREF="#req_return">Handling requests, declining, and returning error codes</A>
+	 <LI> <A HREF="#resp_handlers">Special considerations for response handlers</A>
+	 <LI> <A HREF="#auth_handlers">Special considerations for authentication handlers</A>
+	 <LI> <A HREF="#log_handlers">Special considerations for logging handlers</A>
+       </UL>
+  <LI> <A HREF="#pools">Resource allocation and resource pools</A>
+  <LI> <A HREF="#config">Configuration, commands and the like</A>
+       <UL>
+	 <LI> <A HREF="#per-dir">Per-directory configuration structures</A>
+	 <LI> <A HREF="#commands">Command handling</A>
+	 <LI> <A HREF="#servconf">Side notes --- per-server configuration, virtual servers, etc.</A>
+       </UL>
+</UL>
+
+<H2><A NAME="basics">Basic concepts.</A></H2>
+
+We begin with an overview of the basic concepts behind the Shambhala
+API, and how they are manifested in the code.
+
+<H3><A NAME="HMR">Handlers, Modules, and Requests</A></H3>
+
+Shambhala breaks down request handling into a series of steps, more or
+less the same way the Netscape Server API does (although Shambhala has
+a few more stages than NetSite does, as hooks for stuff I thought
+might be useful in the future).  These are:
+
+<UL>
+  <LI> URI -&gt; Filename translation
+  <LI> Auth ID checking [is the user who they say they are?]
+  <LI> Auth access checking [is the user authorized <EM>here</EM>?]
+  <LI> Access checking other than auth
+  <LI> Determining MIME type of the object requested
+  <LI> "Fixups" --- there aren't any of these yet, but the phase is
+       intended as a hook for possible extensions like
+       <CODE>SetEnv</CODE>, which don't really fit well elsewhere.
+  <LI> Actually sending a response back to the client.  
+  <LI> Logging the request
+</UL>
+
+These phases are handled by looking at each of a succession of
+<EM>modules</EM>, looking to see if each of them has a handler for the
+phase, and attempting invoking it if so.  The handler can typically do
+one of three things:
+
+<UL>
+  <LI> <EM>Handle</EM> the request, and indicate that it has done so
+       by returning the magic constant <CODE>OK</CODE>.  
+  <LI> <EM>Decline</EM> to handle the request, by returning the magic
+       integer constant <CODE>DECLINED</CODE>.  In this case, the
+       server behaves in all respects as if the handler simply hadn't
+       been there.
+  <LI> Signal an error, by returning one of the HTTP error codes.
+       This terminates normal handling of the request, although an
+       ErrorDocument may be invoked to try to mop up, and it will be
+       logged in any case.
+</UL>
+
+Most phases are terminated by the first module that handles them;
+however, for logging, "fixups", and non-access authentication
+checking, all handlers always run (barring an error).  Also, the
+response phase is unique in that modules may declare multiple handlers
+for it, via a dispatch table keyed on the MIME type of the requested
+object.  Modules may declare a response-phase handler which can handle
+<EM>any</EM> request, by giving it the key <CODE>*/*</CODE> (i.e., a
+wildcard MIME type specification).  However, wildcard handlers are
+only invoked if the server has already tried and failed to find a more
+specific response handler for the MIME type of the requested object
+(either none existed, or they all declined).<P>
+
+The handlers themselves are functions of one argument (a
+<CODE>request_rec</CODE> structure. vide infra), which returns an
+integer, as above.<P>
+
+<H3><A NAME="moduletour">A brief tour of a module</A></H3>
+
+At this point, we need to explain the structure of a module.  Our
+candidate will be one of the messier ones, the CGI module --- this
+handles both CGI scripts and the <CODE>ScriptAlias</CODE> config file
+command.  It's actually a great deal more complicated than most
+modules, but if we're going to have only one example, it might as well
+be the one with its fingers in everyplace.<P>
+
+Let's begin with handlers.  In order to handle the CGI scripts, the
+module declares a response handler for them. Because of
+<CODE>ScriptAlias</CODE>, it also has handlers for the name
+translation phase (to recognise <CODE>ScriptAlias</CODE>ed URI's), the
+type-checking phase (any <CODE>ScriptAlias</CODE>ed request is typed
+as a CGI script).<P>
+
+The module needs to maintain some per (virtual)
+server information, namely, the <CODE>ScriptAlias</CODE>es in effect;
+the module structure therefore contains pointers to a functions which
+builds these structures, and to another which combines two of them (in
+case the main server and a virtual server both have
+<CODE>ScriptAlias</CODE>es declared).<P>
+
+Finally, this module contains code to handle the
+<CODE>ScriptAlias</CODE> command itself.  This particular module only
+declares one command, but there could be more, so modules have
+<EM>command tables</EM> which declare their commands, and describe
+where they are permitted, and how they are to be invoked.  <P>
+
+A final note on the declared types of the arguments of some of these
+commands: a <CODE>pool</CODE> is a pointer to a <EM>resource pool</EM>
+structure; these are used by the server to keep track of the memory
+which has been allocated, files opened, etc., either to service a
+particular request, or to handle the process of configuring itself.
+That way, when the request is over (or, for the configuration pool,
+when the server is restarting), the memory can be freed, and the files
+closed, en masse, without anyone having to write explicit code to
+track them all down and dispose of them.  Also, a
+<CODE>cmd_parms</CODE> structure contains various information about
+the config file being read, and other status information, which is
+sometimes of use to the function which processes a config-file command
+(such as <CODE>ScriptAlias</CODE>).
+
+With no further ado, the module itself:
+ 
+<PRE>
+/* Declarations of handlers. */
+
+int translate_scriptalias (request_rec *);
+int type_scriptalias (request_rec *);
+int cgi_handler (request_rec *);
+
+/* Subsdiary dispatch table for response-phase handlers, by MIME type */
+
+handler_rec cgi_handlers[] = {
+{ "application/x-httpd-cgi", cgi_handler },
+{ NULL }
+};
+
+/* Declarations of routines to manipulate the module's configuration
+ * info.  Note that these are returned, and passed in, as void *'s;
+ * the server core keeps track of them, but it doesn't, and can't,
+ * know their internal structure.
+ */
+
+void *make_cgi_server_config (pool *);
+void *merge_cgi_server_config (pool *, void *, void *);
+
+/* Declarations of routines to handle config-file commands */
+
+char *script_alias (cmd_parms *, void *per_dir_config, char *fake, char *real);
+
+command_rec cgi_cmds[] = {
+{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,
+    "a fakename and a realname"},
+{ NULL }
+};
+
+module cgi_module = {
+   STANDARD_MODULE_STUFF,
+   NULL,			/* initializer */
+   NULL,			/* dir config creater */
+   NULL,			/* dir merger --- default is to override */
+   make_cgi_server_config,      /* server config */
+   merge_cgi_server_config,	/* merge server config */
+   cgi_cmds,			/* command table */
+   cgi_handlers,		/* handlers */
+   translate_scriptalias,	/* filename translation */
+   NULL,			/* check_user_id */
+   NULL,			/* check auth */
+   NULL,			/* check access */
+   type_scriptalias,		/* type_checker */
+   NULL,			/* fixups */
+   NULL				/* logger */
+};
+</PRE>
+
+<H2><A NAME="handlers">How handlers work</A></H2>
+
+The sole argument to handlers is a <CODE>request_rec</CODE> structure.
+This structure describes a particular request which has been made to
+the server, on behalf of a client.  In most cases, each connection to
+the client generates only one <CODE>request_rec</CODE> structure.<P>
+
+<H3><A NAME="req_tour">A brief tour of the <CODE>request_rec</CODE></A></H3>
+
+The <CODE>request_rec</CODE> contains pointers to a resource pool
+which will be cleared when the server is finished handling the
+request; to structures containing per-server and per-connection
+information, and most importantly, information on the request itself.<P>
+
+The most important such information is a small set of character
+strings describing attributes of the object being requested, including
+its URI, filename, content-type and content-encoding (these being filled
+in by the translation and type-check handlers which handle the
+request, respectively). <P>
+
+Other commonly used data items are tables giving the MIME headers on
+the client's original request, MIME headers to be sent back with the
+ppppresponse (which modules can add to at will), and environment variables
+for any subprocesses which are spawned off in the course of servicing
+the request.  These tables are manipulated using the
+<CODE>table_get</CODE> and <CODE>table_set</CODE> routines. <P>
+
+Finally, there are pointers to two data structures which, in turn,
+point to per-module configuration structures.  Specifically, these
+hold pointers to the data structures which the module has built to
+describe the way it has been configured to operate in a given
+directory (via <CODE>.htaccess</CODE> files or
+<CODE>&lt;Directory&gt;</CODE> sections), for private data it has
+built in the course of servicing the request (so modules' handlers for
+one phase can pass "notes" to their handlers for other phases).  There
+is another such configuration vector in the <CODE>server_rec</CODE>
+data structure pointed to by the <CODE>request_rec</CODE>, which
+contains per (virtual) server configuration data.<P>
+
+Here is an abridged declaration, giving the fields most commonly used:<P>
+
+<PRE>
+struct request_rec {
+
+  pool *pool;
+  conn_rec *connection;
+  server_rec *server;
+
+  /* What object is being requested */
+  
+  char *uri;
+  char *filename;
+  char *path_info;
+  char *args;			/* QUERY_ARGS, if any */
+  struct stat finfo;		/* Set by server core;
+                                 * st_mode set to zero if no such file */
+  
+  char *content_type;
+  char *content_encoding;
+  
+  /* MIME header environments, in and out.  Also, an array containing
+   * environment variables to be passed to subprocesses, so people can
+   * write modules to add to that environment.
+   *
+   * The difference between headers_out and err_headers_out is that the
+   * latter are printed even on error, and persist across internal redirects
+   * (so the headers printed for ErrorDocument handlers will have them).
+   */
+  
+  table *headers_in;
+  table *headers_out;
+  table *err_headers_out;
+  table *subprocess_env;
+
+  /* Info about the request itself... */
+  
+  int header_only;		/* HEAD request, as opposed to GET */
+  char *protocol;		/* Protocol, as given to us, or HTTP/0.9 */
+  char *method;			/* GET, HEAD, POST, etc. */
+  int method_number;		/* M_GET, M_POST, etc. */
+
+  /* Info for logging */
+
+  char *the_request;
+  int bytes_sent;
+
+  /* A flag which modules can set, to indicate that the data being
+   * returned is volatile, and clients should be told not to cache it.
+   */
+
+  int no_cache;
+
+  /* Various other config info which may change with .htaccess files
+   * These are config vectors, with one void* pointer for each module
+   * (the thing pointed to being the module's business).
+   */
+  
+  void *per_dir_config;		/* Options set in config files, etc. */
+  void *request_config;		/* Notes on *this* request */
+  
+};
+
+</PRE>
+
+<H3><A NAME="req_orig">Where request_rec structures come from</A></H3>
+
+Most <CODE>request_rec</CODE> structures are built by reading an HTTP
+request from a client, and filling in the fields.  However, there are
+a few exceptions:
+
+<UL>
+  <LI> If the request is to an imagemap, a type map (i.e., a
+       <CODE>*.var</CODE> file), or a CGI script which returned a
+       local "Location:", then the resource which the user requested
+       is going to be ultimately located by some URI other than what
+       the client originally supplied.  In this case, the server does
+       an <EM>internal redirect</EM>, constructing a new
+       <CODE>request_rec</CODE> for the new URI, and processing it
+       almost exactly as if the client had requested the new URI
+       directly. <P>
+
+  <LI> If some handler signaled an error, and an
+       <CODE>ErrorDocument</CODE> is in scope, the same internal
+       redirect machinery comes into play.<P>
+
+  <LI> Finally, a handler occasionally needs to investigate "what
+       would happen if" some other request were run.  For instance,
+       the directory indexing module needs to know what MIME type
+       would be assigned to a request for each directory entry, in
+       order to figure out what icon to use.<P>
+
+       Such handlers can construct a <EM>sub-request</EM>, using the
+       functions <CODE>sub_req_lookup_file</CODE> and
+       <CODE>sub_req_lookup_uri</CODE>; this constructs a new
+       <CODE>request_rec</CODE> structure and processes it as you
+       would expect, up to but not including the point of actually
+       sending a response.  (These functions skip over the access
+       checks if the sub-request is for a file in the same directory
+       as the original request).<P>
+
+       (Server-side includes work by building sub-requests and then
+       actually invoking the response handler for them, via the
+       function <CODE>run_sub_request</CODE>).
+</UL>
+
+<H3><A NAME="req_return">Handling requests, declining, and returning error codes</A></H3>
+
+As discussed above, each handler, when invoked to handle a particular
+<CODE>request_rec</CODE>, has to return an <CODE>int</CODE> to
+indicate what happened.  That can either be
+
+<UL>
+  <LI> OK --- the request was handled successfully.  This may or may
+       not terminate the phase.
+  <LI> DECLINED --- no erroneous condition exists, but the module
+       declines to handle the phase; the server tries to find another.
+  <LI> an HTTP error code, which aborts handling of the request.
+</UL>
+
+Note that if the error code returned is <CODE>REDIRECT</CODE>, then
+the module should put a <CODE>Location</CODE> in the request's
+<CODE>headers_out</CODE>, to indicate where the client should be
+redirected <EM>to</EM>. <P>
+
+<H3><A NAME="resp_handlers">Special considerations for response handlers</A></H3>
+
+Handlers for most phases do their work by simply setting a few fields
+in the <CODE>request_rec</CODE> structure (or, in the case of access
+checkers, simply by returning the correct error code).  However,
+response handlers have to actually send a request back to the client. <P>
+
+They should begin by sending an HTTP response header, using the
+function <CODE>send_http_header</CODE>.  (You don't have to do
+anything special to skip sending the header for HTTP/0.9 requests; the
+function figures out on its own that it shouldn't do anything).  If
+the request is marked <CODE>header_only</CODE>, that's all they should
+do; they should return after that, without attempting any further
+output.  <P>
+
+Otherwise, they should produce a request body which responds to the
+client as appropriate.  The primitives for this are <CODE>rputc</CODE>
+and <CODE>rprintf</CODE>, for internally generated output, and
+<CODE>send_fd</CODE>, to copy the contents of some <CODE>FILE *</CODE>
+straight to the client.  <P>
+
+One final consideration: when doing I/O to the client, there is the
+possibility of indefinite delays.  It is therefore important to arm a
+timeout before initiating I/O to the client.<P>
+
+At this point, you should more or less understand the following piece
+of code, which is the handler which handles <CODE>GET</CODE> requests
+which have no more specific handler; it also shows how conditional
+<CODE>GET</CODE>s can be handled, if it's desirable to do so in a
+particular response handler.  (The functions <CODE>pfopen</CODE> and
+<CODE>pfclose</CODE> tie the <CODE>FILE *</CODE> returned into the
+resource pool machinery, so it will be closed even if the request is
+aborted).<P>
+
+<PRE>
+int default_handler (request_rec *r)
+{
+    int errstatus;
+    FILE *f;
+    
+    if (r-&gt;method_number != M_GET) return DECLINED;
+    if (r-&gt;finfo.st_mode == 0) return NOT_FOUND;
+	
+    if ((errstatus = set_content_length (r, r-&gt;finfo.st_size))
+	|| (errstatus = set_last_modified (r, r-&gt;finfo.st_mtime)))
+        return errstatus;
+    
+    f = pfopen (r-&gt;pool, r-&gt;filename, "r");
+
+    if (f == NULL) {
+        log_reason("file permissions deny server access", r-&gt;filename, r);
+        return FORBIDDEN;
+    }
+      
+    register_timeout ("send", r);
+    send_http_header (r);
+
+    if (!r-&gt;header_only) {
+	send_fd (f, r);
+    }
+    
+    kill_timeout(r);
+    pfclose (r-&gt;pool, f);
+    return OK;
+}
+</PRE>
+
+Finally, if all of this is too much of a challenge, there are a few
+ways out of it.  First off, as shown above, a response handler which
+has not yet produced any output can simply return an error code, in
+which case the server will automatically produce an error response.
+Secondly, it can punt to some other handler by invoking
+<CODE>internal_redirect</CODE>, which is how the internal redirection
+machinery discussed above is invoked.  A response handler which has
+internally redirected should always return <CODE>OK</CODE>. <P>
+
+(Invoking <CODE>internal_redirect</CODE> from handlers which are
+<EM>not</EM> response handlers will lead to serious confusion).
+
+<H3><A NAME="auth_handlers">Special considerations for authentication handlers</A></H3>
+
+Stuff that should be discussed here in detail:
+
+<UL>
+  <LI> Authentication-phase handlers not invoked unless auth is
+       configured for the directory.
+  <LI> Common auth configuration stored in the core per-dir
+       configuration; it has accessors <CODE>auth_type</CODE>,
+       <CODE>auth_name</CODE>, and <CODE>requires</CODE>.
+  <LI> Common routines, to handle the protocol end of things, at least
+       for HTTP basic authentication (<CODE>get_basic_auth_pw</CODE>,
+       which sets the <CODE>connection-&gt;user</CODE> structure field
+       automatically, and <CODE>note_basic_auth_failure</CODE>, which
+       arranges for the proper <CODE>WWW-Authenticate:</CODE> header
+       to be sent back).
+</UL>
+
+<H3><A NAME="log_handlers">Special considerations for logging handlers</A></H3>
+
+When a request has internally redirected, there is the question of
+what to log.  Shambhala handles this by bundling the entire chain of
+redirects into a list of <CODE>request_rec</CODE> structures which are
+threaded through the <CODE>r-&gt;prev</CODE> and <CODE>r-&gt;next</CODE>
+pointers.  The <CODE>request_rec</CODE> which is passed to the logging
+handlers in such cases is the one which was originally built for the
+intial request from the client; note that the bytes_sent field will
+only be correct in the last request in the chain (the one for which a
+response was actually sent). 
+
+<H2><A NAME="pools">Resource allocation and resource pools</A></H2>
+
+One of the problems of writing and designing a server-pool server is
+that of preventing leakage, that is, allocating resources (memory,
+open files, etc.), without subsequently releasing them.  The resource
+pool machinery is designed to prevent this.  Stuff that should be
+discussed here in detail:
+
+<UL>
+  <LI> Allocating memory --- <CODE>palloc</CODE> and friends
+  <LI> The array and table stuff
+  <LI> Files and file descriptors
+  <LI> sub-pools and <CODE>destroy_sub_request</CODE>
+</UL>
+
+<H2><A NAME="config">Configuration, commands and the like</A></H2>
+
+One of the design goals for this server was to maintain external
+compatibility with the NCSA 1.3 server --- that is, to read the same
+configuration files, to process all the directives therein correctly,
+and in general to be a drop-in replacement for NCSA.  On the other
+hand, another design goal was to move as much of the server's
+functionality into modules which have as little as possible to do with
+the monolithic server core.  The only way to reconcile these goals is
+to move the handling of most commands from the central server into the
+modules.  <P>
+
+However, just giving the modules command tables is not enough to
+divorce them completely from the server core.  The server has to
+remember the commands in order to act on them later.  That involves
+maintaining data which is private to the modules, and which can be
+either per-server, or per-directory.  Most things are per-directory,
+including in particular access control and authorization information,
+but also information on how to determine file types from suffixes,
+which can be modified by <CODE>AddType</CODE> and
+<CODE>DefaultType</CODE> directives, and so forth.  In general, the
+governing philosophy is that anything which <EM>can</EM> be made
+configurable by directory should be; per-server information is
+generally used in the standard set of modules for information like
+<CODE>Alias</CODE>es and <CODE>Redirect</CODE>s which come into play
+before the request is tied to a particular place in the underlying
+file system. <P>
+
+Another requirement for emulating the NCSA server is being able to
+handle the per-directory configuration files, generally called
+<CODE>.htaccess</CODE> files, though even in the NCSA server they can
+contain directives which have nothing at all to do with access
+control.  Accordingly, after URI -&gt; filename translation, but before
+performing any other phase, the server walks down the directory
+hierarchy of the underlying filesystem, following the translated
+pathname, to read any <CODE>.htaccess</CODE> files which might be
+present.  The information which is read in then has to be
+<EM>merged</EM> with the applicable information from the server's own
+config files (either from the <CODE>&lt;Directory&gt;</CODE> sections
+in <CODE>access.conf</CODE>, or from defaults in
+<CODE>srm.conf</CODE>, which actually behaves for most purposes almost
+exactly like <CODE>&lt;Directory /&gt;</CODE>).<P>
+
+Finally, after having served a request which involved reading
+<CODE>.htaccess</CODE> files, we need to discard the storage allocated
+for handling them.  That is solved the same way it is solved wherever
+else similar problems come up, by tying those structures to the
+per-transaction resource pool.  <P>
+
+<H3><A NAME="per-dir">Per-directory configuration structures</A></H3>
+
+Let's look out how all of this plays out in <CODE>mod_mime.c</CODE>,
+which defines the file typing handler which emulates the NCSA server's
+behavior of determining file types from suffixes.  What we'll be
+looking at, here, is the code which implements the
+<CODE>AddType</CODE> and <CODE>AddEncoding</CODE> commands.  These
+commands can appear in <CODE>.htaccess</CODE> files, so they must be
+handled in the module's private per-directory data, which in fact,
+consists of two separate <CODE>table</CODE>s for MIME types and
+encoding information, and is declared as follows:
+
+<PRE>
+typedef struct {
+    table *forced_types;	/* Additional AddTyped stuff */
+    table *encoding_types;	/* Added with AddEncoding... */
+} mime_dir_config;
+</PRE>
+
+When the server is reading a configuration file, or
+<CODE>&lt;Directory&gt;</CODE> section, which includes one of the MIME
+module's commands, it needs to create a <CODE>mime_dir_config</CODE>
+structure, so those commands have something to act on.  It does this
+by invoking the function it finds in the module's "create per-dir
+config slot", with two arguments: the name of the directory to which
+this configuration information applies (or <CODE>NULL</CODE> for
+<CODE>srm.conf</CODE>), and a pointer to a resource pool in which the
+allocation should happen. <P>
+
+(If we are reading a <CODE>.htaccess</CODE> file, that resource pool
+is the per-request resource pool for the request; otherwise it is a
+resource pool which is used for configuration data, and cleared on
+restarts.  Either way, it is important for the structure being created
+to vanish when the pool is cleared, by registering a cleanup on the
+pool if necessary). <P>
+
+For the MIME module, the per-dir config creation function just
+<CODE>palloc</CODE>s the structure above, and a creates a couple of
+<CODE>table</CODE>s to fill it.  That looks like this:
+
+<PRE>
+void *create_mime_dir_config (pool *p, char *dummy)
+{
+    mime_dir_config *new =
+      (mime_dir_config *) palloc (p, sizeof(mime_dir_config));
+
+    new-&gt;forced_types = make_table (p, 4);
+    new-&gt;encoding_types = make_table (p, 4);
+    
+    return new;
+}
+</PRE>
+
+Now, suppose we've just read in a <CODE>.htaccess</CODE> file.  We
+already have the per-directory configuration structure for the next
+directory up in the hierarchy.  If the <CODE>.htaccess</CODE> file we
+just read in didn't have any <CODE>AddType</CODE> or
+<CODE>AddEncoding</CODE> commands, its per-directory config structure
+for the MIME module is still valid, and we can just use it.
+Otherwise, we need to merge the two structures somehow. <P>
+
+To do that, the server invokes the module's per-directory config merge
+function, if one is present.  That function takes three arguments:
+the two structures being merged, and a resource pool in which to
+allocate the result.  For the MIME module, all that needs to be done
+is overlay the tables from the new per-directory config structure with
+those from the parent:
+
+<PRE>
+void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
+{
+    mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
+    mime_dir_config *subdir = (mime_dir_config *)subdirv;
+    mime_dir_config *new =
+      (mime_dir_config *)palloc (p, sizeof(mime_dir_config));
+
+    new-&gt;forced_types = overlay_tables (p, subdir-&gt;forced_types,
+					parent_dir-&gt;forced_types);
+    new-&gt;encoding_types = overlay_tables (p, subdir-&gt;encoding_types,
+					  parent_dir-&gt;encoding_types);
+
+    return new;
+}
+</PRE>
+
+As a note --- if there is no per-directory merge function present, the
+server will just use the subdirectory's configuration info, and ignore
+the parent's.  For some modules, that works just fine (e.g., for the
+includes module, whose per-directory configuration information
+consists solely of the state of the <CODE>XBITHACK</CODE>), and for
+those modules, you can just not declare one, and leave the
+corresponding structure slot in the module itself <CODE>NULL</CODE>.<P>
+
+<H3><A NAME="commands">Command handling</A></H3>
+
+Now that we have these structures, we need to be able to figure out
+how to fill them.  That involves processing the actual
+<CODE>AddType</CODE> and <CODE>AddEncoding</CODE> commands.  To find
+commands, the server looks in the module's <CODE>command table</CODE>.
+That table contains information on how many arguments the commands
+take, and in what formats, where it is permitted, and so forth.  That
+information is sufficient to allow the server to invoke most
+command-handling functions with preparsed arguments.  Without further
+ado, let's look at the <CODE>AddType</CODE> command handler, which
+looks like this (the <CODE>AddEncoding</CODE> command looks basically
+the same, and won't be shown here):
+
+<PRE>
+char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)
+{
+    if (*ext == '.') ++ext;
+    table_set (m-&gt;forced_types, ext, ct);
+    return NULL;
+}
+</PRE>
+
+This command handler is unusually simple.  As you can see, it takes
+four arguments, two of which are preparsed arguments, the third being
+the per-directory configuration structure for the module in question,
+and the fourth being a pointer to a <CODE>cmd_parms</CODE> structure.
+That structure contains a bunch of arguments which are frequently of
+use to some, but not all, commands, including a resource pool (from
+which memory can be allocated, and to which cleanups should be tied),
+and the (virtual) server being configured, from which the module's
+per-server configuration data can be obtained if required.<P>
+
+Another way in which this particular command handler is unusually
+simple is that there are no error conditions which it can encounter.
+If there were, it could return an error message instead of
+<CODE>NULL</CODE>; this causes an error to be printed out on the
+server's <CODE>stderr</CODE>, followed by a quick exit, if it is in
+the main config files; for a <CODE>.htaccess</CODE> file, the syntax
+error is logged in the server error log (along with an indication of
+where it came from), and the request is bounced with a server error
+response (HTTP error status, code 500). <P>
+
+The MIME module's command table has entries for these commands, which
+look like this:
+
+<PRE>
+command_rec mime_cmds[] = {
+{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2, 
+    "a mime type followed by a file extension" },
+{ "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2, 
+    "an encoding (e.g., gzip), followed by a file extension" },
+{ NULL }
+};
+</PRE>
+
+The entries in these tables are:
+
+<UL>
+  <LI> The name of the command
+  <LI> The function which handles it
+  <LI> a <CODE>(void *)</CODE> pointer, which is passed in the
+       <CODE>cmd_parms</CODE> structure to the command handler ---
+       this is useful in case many similar commands are handled by the
+       same function.
+  <LI> A bit mask indicating where the command may appear.  There are
+       mask bits corresponding to each <CODE>AllowOverride</CODE>
+       option, and an additional mask bit, <CODE>RSRC_CONF</CODE>,
+       indicating that the command may appear in the server's own
+       config files, but <EM>not</EM> in any <CODE>.htaccess</CODE>
+       file.
+  <LI> A flag indicating how many arguments the command handler wants
+       preparsed, and how they should be passed in.
+       <CODE>TAKE2</CODE> indicates two preparsed arguments.  Other
+       options are <CODE>TAKE1</CODE>, which indicates one preparsed
+       argument, <CODE>FLAG</CODE>, which indicates that the argument
+       should be <CODE>On</CODE> or <CODE>Off</CODE>, and is passed in
+       as a boolean flag, <CODE>RAW_ARGS</CODE>, which causes the
+       server to give the command the raw, unparsed arguments
+       (everything but the command name itself).  There is also
+       <CODE>ITERATE</CODE>, which means that the handler looks the
+       same as <CODE>TAKE1</CODE>, but that if multiple arguments are
+       present, it should be called multiple times, and finally
+       <CODE>ITERATE2</CODE>, which indicates that the command handler
+       looks like a <CODE>TAKE2</CODE>, but if more arguments are
+       present, then it should be called multiple times, holding the
+       first argument constant.
+  <LI> Finally, we have a string which describes the arguments that
+       should be present.  If the arguments in the actual config file
+       are not as required, this string will be used to help give a
+       more specific error message.  (You can safely leave this
+       <CODE>NULL</CODE>). 
+</UL>
+
+Finally, having set this all up, we have to use it.  This is
+ultimately done in the module's handlers, specifically for its
+file-typing handler, which looks more or less like this; note that the
+per-directory configuration structure is extracted from the
+<CODE>request_rec</CODE>'s per-directory configuration vector by using
+the <CODE>get_module_config</CODE> function.
+
+<PRE>
+int find_ct(request_rec *r)
+{
+    int i;
+    char *fn = pstrdup (r-&gt;pool, r-&gt;filename);
+    mime_dir_config *conf =
+      (mime_dir_config *)get_module_config(r-&gt;per_dir_config, &mime_module);
+    char *type;
+
+    if (S_ISDIR(r-&gt;finfo.st_mode)) {
+        r-&gt;content_type = DIR_MAGIC_TYPE;
+	return OK;
+    }
+    
+    if((i=rind(fn,'.')) &lt; 0) return DECLINED;
+    ++i;
+
+    if ((type = table_get (conf-&gt;encoding_types, &fn[i])))
+    {
+        r-&gt;content_encoding = type;
+
+	/* go back to previous extension to try to use it as a type */
+	
+        fn[i-1] = '\0';
+	if((i=rind(fn,'.')) &lt; 0) return OK;
+	++i;
+    }
+
+    if ((type = table_get (conf-&gt;forced_types, &fn[i])))
+    {
+        r-&gt;content_type = type;
+    }
+    
+    return OK;
+}
+
+</PRE>
+
+<H3><A NAME="servconf">Side notes --- per-server configuration, virtual servers, etc.</A></H3>
+
+The basic ideas behind per-server module configuration are basically
+the same as those for per-directory configuration; there is a creation
+function and a merge function, the latter being invoked where a
+virtual server has partially overriden the base server configuration,
+and a combined structure must be computed.  (As with per-directory
+configuration, the default if no merge function is specified, and a
+module is configured in some virtual server, is that the base
+configuration is simply ignored). <P>
+
+The only substantial difference is that when a command needs to
+configure the per-server private module data, it needs to go to the
+<CODE>cmd_parms</CODE> data to get at it.  Here's an example, from the
+alias module, which also indicates how a syntax error can be returned
+(note that the per-directory configuration argument to the command
+handler is declared as a dummy, since the module doesn't actually have
+per-directory config data):
+
+<PRE>
+char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
+{
+    server_rec *s = cmd-&gt;server;
+    alias_server_conf *conf =
+        (alias_server_conf *)get_module_config(s-&gt;module_config,&amp;alias_module);
+    alias_entry *new = push_array (conf-&gt;redirects);
+
+    if (!is_url (url)) return "Redirect to non-URL";
+    
+    new-&gt;fake = f; new-&gt;real = url;
+    return NULL;
+}
+</PRE>
+</BODY>
+</HTML>

Propchange: httpd/site/trunk/content/dev/API.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: httpd/site/trunk/content/dev/debugging.xml
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/debugging.xml?rev=1334622&view=auto
==============================================================================
--- httpd/site/trunk/content/dev/debugging.xml (added)
+++ httpd/site/trunk/content/dev/debugging.xml Sun May  6 13:14:42 2012
@@ -0,0 +1,501 @@
+<?xml version="1.0"?>
+<document>
+  <properties>
+    <author email="docs@httpd.apache.org">Documentation Group</author>
+    <title>Apache HTTPD Debugging Guide</title>
+  </properties>
+<body>
+
+<section id="id">
+<title>Apache Debugging Guide</title>
+
+<p>This document is a collection of notes regarding tools and techniques
+for debugging Apache httpd and its modules.</p>
+
+<p>Got more tips?  Send 'em to
+<a href="mailto:docs@httpd.apache.org">docs@httpd.apache.org</a>.  Thanks!</p>
+
+<ol>
+<li><a href="#gdb">Using <code>gdb</code></a></li>
+<li><a href="#backtrace">Getting a live backtrace on unix</a></li>
+<li><a href="#backtrace-win">Getting a live backtrace on Windows</a></li>
+<li><a href="#crashes">Debugging intermittent crashes</a></li>
+<li><a href="#truss">Using '<code>truss/trace/strace</code>' to
+    trace system calls and signals</a></li>
+<li><a href="#gcore">Getting the server to dump core</a></li>
+<li><a href="#sol27">Solaris and coredumps</a></li>
+<li><a href="#tcpdump">Getting and analyzing a TCP packet trace</a></li>
+</ol>
+</section>
+
+<section id="gdb">
+<title>Using gdb</title>
+
+<p>If you use the gcc compiler, it is likely that the best
+debugger for your system is gdb.  This is only a brief summary of how
+to run gdb on Apache -- you should look at the info and man files for
+gdb to get more information on gdb commands and common debugging techniques.
+Before running gdb, be sure that the server is compiled with the
+<code>-g</code> option in <code>CFLAGS</code> to include the
+symbol information in the object files.</p>
+
+<p>The only tricky part of running gdb on Apache is forcing the server
+into a single-process mode so that the parent process being debugged 
+does the request-handling work instead of forking child processes.
+We have provided the <code>-X</code> option for that purpose, which will
+work fine for most cases.  However, some modules don't like starting
+up with <code>-X</code>, but are happy if you force only one child to run
+(using "<code>MaxClients 1</code>"); you can then use gdb's attach command
+to debug the child server.</p>
+
+<p>The following example, with <font color="green">user input in green</font>,
+shows the output of gdb run on a server executable (httpd) in the current
+working directory and using the server root of 
+<code>/usr/local/apache</code>:</p>
+
+<pre>
+    % <font color="green">gdb httpd</font>
+    GDB is free software and you are welcome to distribute copies of it
+     under certain conditions; type "show copying" to see the conditions.
+    There is absolutely no warranty for GDB; type "show warranty" for details.
+    GDB 4.16.gnat.1.13 (sparc-sun-solaris2.5), 
+    Copyright 1996 Free Software Foundation, Inc...
+    (gdb) <font color="green">b ap_process_request</font>
+    Breakpoint 1 at 0x49fb4: file http_request.c, line 1164.
+    (gdb) <font color="green">run -X -d /usr/local/apache</font>
+    Starting program: /usr/local/apache/src/httpd -X -d /usr/local/apache
+    
+    [at this point I make a request from another window]
+
+    Breakpoint 1, ap_process_request (r=0x95250) at http_request.c:1164
+    1164        if (ap_extended_status)
+    (gdb) <font color="green">s</font>
+    1165            ap_time_process_request(r-&gt;connection-&gt;child_num, ...
+    (gdb) <font color="green">n</font>
+    1167        process_request_internal(r);
+    (gdb) <font color="green">s</font>
+    process_request_internal (r=0x95250) at http_request.c:1028
+    1028        if (!r-&gt;proxyreq &amp;&amp; r-&gt;parsed_uri.path) {
+    (gdb) <font color="green">s</font>
+    1029            access_status = ap_unescape_url(r-&gt;parsed_uri.path);
+    (gdb) <font color="green">n</font>
+    1030            if (access_status) {
+    (gdb) <font color="green">s</font>
+    1036        ap_getparents(r-&gt;uri);     /* OK ...
+    (gdb) <font color="green">n</font>
+    1038        if ((access_status = location_walk(r))) {
+    (gdb) <font color="green">n</font>
+    1043        if ((access_status = ap_translate_name(r))) {
+    (gdb) <font color="green">n</font>
+    1048        if (!r-&gt;proxyreq) {
+    (gdb) <font color="green">n</font>
+    1053            if (r-&gt;method_number == M_TRACE) {
+    (gdb) <font color="green">n</font>
+    1062        if (r-&gt;proto_num &gt; HTTP_VERSION(1,0) &amp;&amp; ap_ ...
+    (gdb) <font color="green">n</font>
+    1071        if ((access_status = directory_walk(r))) {
+    (gdb) <font color="green">s</font>
+    directory_walk (r=0x95250) at http_request.c:288
+    288         core_server_config *sconf = ap_get_module_ ...
+    (gdb) <font color="green">b ap_send_error_response</font>
+    Breakpoint 2 at 0x47dcc: file http_protocol.c, line 2090.
+    (gdb) <font color="green">c</font>
+    Continuing.
+    
+    Breakpoint 2, ap_send_error_response (r=0x95250, recursive_error=0)
+        at http_protocol.c:2090
+    2090        BUFF *fd = r-&gt;connection-&gt;client;
+    (gdb) <font color="green">where</font>
+    #0  ap_send_error_response (r=0x95250, recursive_error=0)
+        at http_protocol.c:2090
+    #1  0x49b10 in ap_die (type=403, r=0x95250) at http_request.c:989
+    #2  0x49b60 in decl_die (status=403, phase=0x62db8 "check access", r=0x95250)
+        at http_request.c:1000
+    #3  0x49f68 in process_request_internal (r=0x95250) at http_request.c:1141
+    #4  0x49fe0 in ap_process_request (r=0x95250) at http_request.c:1167
+    #5  0x439d8 in child_main (child_num_arg=550608) at http_main.c:3826
+    #6  0x43b5c in make_child (s=0x7c3e8, slot=0, now=907958743)
+        at http_main.c:3898
+    #7  0x43ca8 in startup_children (number_to_start=6) at http_main.c:3972
+    #8  0x44260 in standalone_main (argc=392552, argv=0x75800) at http_main.c:4250
+    #9  0x449fc in main (argc=4, argv=0xefffee8c) at http_main.c:4534
+    (gdb) <font color="green">s</font>
+    2091        int status = r-&gt;status;
+    (gdb) <font color="green">p status</font>
+    $1 = 403
+    (gdb) 
+</pre>
+
+<p>There are a few things to note about the above example:</p>
+
+<ol>
+<li>the "<code>gdb httpd</code>" command does not include any command-line
+    options for httpd: those are provided when the "<code>run</code>" command
+    is done within gdb;</li>
+<li>I set a breakpoint before starting the run so that execution would stop
+    at the top of ap_process_request();</li>
+<li>the "<code>s</code>" command steps through the code and into called
+    procedures, whereas the "<code>n</code>" (next) command steps through
+    the code but not into called procedures.</li>
+<li>additional breakpoints can be set with the "<code>b</code>" command,
+    and the run continued with the "<code>c</code>" command.</li>
+<li>use the "<code>where</code>" command (a.k.a. "<code>bt</code>") to see
+    a stack backtrace that shows the order of called procedures and their
+    parameter values.</li>
+<li>use the "<code>p</code>" command to print the value of a variable.</li>
+</ol>
+
+<p>A file in the the root directory called <code>.gdbinit</code> provides
+useful macros for printing out various internal structures of httpd like tables
+(<code>dump_table</code>), brigades (<code>dump_brigade</code>) and filter chains
+(<code>dump_filters</code>).</p>
+
+<p>If you are debugging a repeatable crash, simply run gdb as above
+and make the request -- gdb should capture the crash and provide a
+prompt where it occurs.</p>
+
+<p>If you are debugging an apparent infinite loop, simply run gdb as above
+and type a Control-C -- gdb will interrupt the process and provide a
+prompt where it was stopped.</p>
+
+<p>If you are debugging a system crash and you have a core file from
+the crash, then do the following:</p>
+
+<pre>
+    % <font color="green">gdb httpd -c core</font>
+    (gdb) <font color="green">where</font>
+</pre>
+
+<p>and it will (hopefully) print a stack backtrace of where the core dump
+occurred during processing.</p>
+</section>
+
+<section id="backtrace">
+<title>Getting a live backtrace on unix</title>
+
+<p>A backtrace will let you know the hierarchy of procedures that
+were called to get to a particular point in the process.  On some platforms
+you can get a live backtrace of any process.</p>
+
+<p>For SVR4-based variants of Unix, the <code>pstack</code> command for proc can
+be used to display a a live backtrace.  For example, on Solaris it looks 
+like</p>
+
+<pre>
+    % <font color="green">/usr/proc/bin/pstack 10623</font>
+    10623:  httpd -d /usr/local/apache
+     ef5b68d8 poll     (efffcd08, 0, 3e8)
+     ef5d21e0 select   (0, ef612c28, 0, 0, 3e8, efffcd08) + 288
+     00042574 wait_or_timeout (0, 75000, 75000, 7c3e8, 60f40, 52c00) + 78
+     00044310 standalone_main (5fd68, 75800, 75c00, 75000, 2, 64) + 240
+     000449f4 main     (3, efffeee4, efffeef4, 75fe4, 1, 0) + 374
+     000162fc _start   (0, 0, 0, 0, 0, 0) + 5c
+</pre>
+
+<p>Another technique is to use gdb to attach to the running process
+and then using "where" to print the backtrace, as in</p>
+
+<pre>
+    % <font color="green">gdb httpd 10623</font>
+    GDB is free software and you are welcome to distribute copies of it
+     under certain conditions; type "show copying" to see the conditions.
+    There is absolutely no warranty for GDB; type "show warranty" for details.
+    GDB 4.16.gnat.1.13 (sparc-sun-solaris2.5), 
+    Copyright 1996 Free Software Foundation, Inc...
+    
+    /usr/local/apache/src/10623: No such file or directory.
+    Attaching to program `/usr/local/apache/src/httpd', process 10623
+    Reading symbols from /usr/lib/libsocket.so.1...done.
+    Reading symbols from /usr/lib/libnsl.so.1...done.
+    Reading symbols from /usr/lib/libc.so.1...done.
+    Reading symbols from /usr/lib/libdl.so.1...done.
+    Reading symbols from /usr/lib/libintl.so.1...done.
+    Reading symbols from /usr/lib/libmp.so.1...done.
+    Reading symbols from /usr/lib/libw.so.1...done.
+    Reading symbols from /usr/platform/SUNW,Ultra-1/lib/libc_psr.so.1...done.
+    0xef5b68d8 in   ()
+    (gdb) <font color="green">where</font>
+    #0  0xef5b68d8 in   ()
+    #1  0xef5d21e8 in select ()
+    #2  0x4257c in wait_or_timeout (status=0x0) at http_main.c:2357
+    #3  0x44318 in standalone_main (argc=392552, argv=0x75800) at ...
+    #4  0x449fc in main (argc=3, argv=0xefffeee4) at http_main.c:4534
+    (gdb) 
+</pre>
+</section>
+
+<section id="backtrace-win">
+<title>Getting a live backtrace on Windows</title>
+
+<ol>
+<li> Unzip the <code>-symbols.zip</code> files (obtained from the
+   Apache download site) in the root Apache2 directory tree (where
+   bin\, htdocs\, modules\ etc. are usually found.)  These .pdb files
+   should unpack alongside the .exe, .dll, .so binary files they
+   represent, e.g., mod_usertrack.pdb will unpack alongside
+   mod_usertrack.so.</li>
+
+<li> Invoke <code>drwtsn32</code> and ensure you are creating a crash
+   dump file, you are dumping all thread contexts, your log and crash
+   dump paths make sense, and (depending on the nature of the bug) you
+   pick an appropriate crash dump type.  (Full is quite large, but
+   necessary sometimes for a programmer-type to load your crash dump
+   into a debugger and begin unwinding exactly what has happened.
+   Mini is sufficient for your first pass through the process.)</li>
+
+<li> Note that if you previously installed and then uninstalled other debugging
+   software, you may need to invoke <code>drwtsn32 -i</code> in order to make
+   Dr Watson your default crash dump tool.  This will replace the 'report
+   problem to MS' dialogs.  (Don't do this if you have a full debugger such 
+   as Visual Studio or windbg installed on the machine, unless you back up the
+   registry value for <code>Debugger</code> under the 
+   <code>HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug</code>
+   registry tree.  Developers using multiple tools might want to keep copies
+   of their different tools Debugger entries there, for fast switching.)</li>
+
+<li> Invoke the Task Manager, Choose 'show processes from all users',
+   and modify the <code>View -> Select Columns</code> to include
+   <strong>at least</strong> the <code>PID</code> and <code>Thread
+   Count</code>.  You can change this just once and Task Manager
+   should keep your preference.</li>
+
+<li> Now, track down the errant Apache that is hanging.  The parent
+   process has about three threads, we don't care about that one.  The
+   child worker process we want has many more threads (a few more than
+   you configured with the ThreadsPerChild directive.)  The process
+   name is Apache (for 1.3 and 2.0) or httpd (for 2.2 and 2.4).  Make note of
+   the child worker's PID.</li>
+
+<li> Using the {pid} number you noted above, invoke the command
+   <blockquote><code>drwtsn32 -p {pid}</code></blockquote></li>
+</ol>
+
+<p>Voila, you will find in your 'log file path' a
+<code>drwtsn32.log</code> file, and if you choose to 'append to
+existing log file', jump through the 'App:' sections until you find
+the one for the process you just killed.  Now you can identify
+about where 'Stack Back Trace' points to help identify what the server
+is doing.</p>
+
+<p>You will note that many threads look identical, almost all of them
+polling for the next connection, and you don't care about those.  You will
+want to see the ones that are deep inside of a request at the time you
+kill them, and only the stack back trace entries for those.  This can
+give folks a clue of where that request is hanging, which handler
+module picked up the request, and what filter it might be stuck in.</p>
+</section>
+
+
+<section id="crashes">
+<title>Debugging intermittent crashes</title>
+
+<p>For situations where a child process is crashing intermittently,
+the server must be configured and started such that it produces core
+dumps which can be analyzed further.</p>
+
+<p>To ensure that a core dump is written to a directory which is
+writable by the user which child processes run as (such as
+<code>apache</code>), the <a
+href="http://httpd.apache.org/docs/current/mod/mpm_common.html#coredumpdirectory"><code>CoreDumpDirectory</code></a>
+directive must be added to <code>httpd.conf</code>; for example:</p>
+
+<pre>
+   CoreDumpDirectory /tmp
+</pre>
+
+<p>Before starting up the server, any process limits on core dump file
+size must be lifted; for example:</p>
+
+<pre>
+  # ulimit -c unlimited
+  # apachectl start
+</pre>
+
+<p>On some platforms, further steps might be needed to enable core
+dumps - see <a href="#sol27">Solaris and coredumps</a> below.</p>
+
+<p>When a child process crashes, a message like the following will be
+logged to the error_log:</p>
+
+<blockquote><code>
+[Mon Sep 05 13:35:39 2005] [notice] child pid 2027 exit signal Segmentation fault (11), possible coredump in /tmp
+</code></blockquote>
+
+<p>If the text "possible coredump in /tmp" does not appear in the
+error line, check that the ulimit was set correctly, that the
+permissions on the configured <code>CoreDumpDirectory</code> are
+suitable and that platform specific steps
+(<a href="#sol27">Solaris and coredumps</a>) have been done if needed.</p>
+
+<p>To analyse the core dump, pass the core dump filename on the gdb
+command-line, and enter the command <code>bt full</code> at the gdb
+prompt:</p>
+
+<pre>
+  % <b>gdb /usr/local/apache2/bin/httpd /tmp/core.2027</b>
+  ...
+  Core was generated by `/usr/local/apache2/bin/httpd -k start'
+  ...
+  (gdb) <b>bt full</b>
+</pre>
+
+<p>If attempting to debug a threaded server, for example when using
+the <code>worker</code> MPM, use the following gdb command:</p>
+
+<pre>
+  (gdb) <b>thread apply all bt full</b>
+</pre>
+
+</section>
+
+<section id="truss">
+<title>Using 'truss/trace/strace' to trace system calls and 
+signals</title>
+
+<p>Most Unix-based systems have at least one command for displaying
+a trace of system calls and signals as they are accessed by a running
+process.  This command is called <code>truss</code> on most SVR4-based
+systems and either <code>trace</code> or <code>strace</code> on many
+other systems.</p>
+
+<p>A useful tip for using the <code>truss</code> command on Solaris is
+the <code>-f</code> option (often also works with <code>strace</code>); it tells
+truss to follow and continue tracing any child processes forked by the main
+process. The easiest way to get a full trace of a server is to do something
+like:</p>
+
+<pre>
+    % <font color="green">truss -f httpd -d /usr/local/apache &gt;&amp; outfile</font>
+</pre>
+and let it run through a few requests before killing the parent. You can
+then view the entire trace in outfile, or use something like
+<pre>
+    % <font color="green">egrep '^10698:' outfile</font>
+</pre>
+
+<p>to view just the trace of the process id 10698.</p>
+
+<p>If attempting to truss a threaded server, for example when using
+the <code>worker</code> MPM, the <code>truss</code> option <code>-l</code>
+is very useful as it prints also the LWP id after the process id. You can use
+something like</p>
+
+<pre>
+    % <font color="green">egrep '^10698/1:' outfile</font>
+</pre>
+
+<p>to view just the trace of the process id 10698 and LWP id 1.</p>
+
+<p>Other useful options for truss are</p>
+
+<ul>
+<li>
+<code>-a</code> to print all command line parameters used for this executable.
+</li>
+<li>
+<code>-e</code> to print all environment variables used for this executable.
+</li>
+<li>
+<code>-d</code> to print timestamps.
+</li>
+</ul>
+
+</section>
+
+<section id="gcore">
+<title>Getting the server to dump core</title>
+
+<p>Strangely enough, sometimes you actually want to force the server
+to crash so that you can get a look at some nutty behavior.  Normally
+this can be done simply by using the <code>gcore</code> command.
+However, for security reasons, most Unix systems do not allow a setuid
+process to dump core, since the file contents might reveal something
+that is supposed to be protected in memory.</p>
+
+<p>Here is one way to get a core file from a setuid Apache httpd process
+on Solaris, without knowing which httpd child might be the one to die
+[note: it is probably easier to use the MaxClients trick in the first
+section above].</p>
+
+<pre>
+    # for pid in `ps -eaf | fgrep httpd | cut -d' ' -f4`
+    do
+      truss -f -l -t\!all -S SIGSEGV -p $pid 2&gt;&amp;1 | egrep SIGSEGV &amp;
+    done
+</pre>
+
+<p>The <a href="http://www.dejanews.com/=zzz_maf/getdoc.xp?AN=352257973">
+undocumented '-S' flag</a> to truss will halt the process in place
+upon receipt of a given signal (SIGSEGV in this case).  
+At this point you can use:</p>
+
+<pre>
+    # gcore <i>PID</i>
+</pre>
+
+<p>and then look at the backtrace as discussed above for 
+<a href="#gdb">gdb</a>.</p>
+</section>
+
+<section id="sol27">
+<title>Solaris and coredumps</title>
+
+<p>On Solaris use <a href="http://docs.sun.com/app/docs/doc/816-5166/coreadm-1m"
+><code>coreadm(1M)</code></a> to make
+<code>setuid()</code> processes actually dump core. By default a setuid()
+process does not dump core. This is the reason why httpd servers started as
+root with child processes running as a different user (such as
+<code>apache</code>) do not coredump even when the
+<a href="http://httpd.apache.org/docs/current/mod/mpm_common.html#coredumpdirectory">
+<code>CoreDumpDirectory</code></a>
+directive had been set to an appropriate and writable directory and
+<b><code>ulimit -c</code></b> has a sufficient size. See also
+<a href="#crashes">Debugging intermittent crashes</a> above.
+</p>
+
+<p>Example:</p>
+<pre>
+-bash-3.00# coreadm
+     global core file pattern: /var/core/core.%f.%p.u%u
+     global core file content: default
+       init core file pattern: core
+       init core file content: default
+            global core dumps: disabled
+       per-process core dumps: enabled
+      global setid core dumps: enabled
+ per-process setid core dumps: enabled
+     global core dump logging: disabled
+</pre>
+</section>
+
+<section id="tcpdump">
+<title>Getting and analyzing a TCP packet trace</title>
+
+<p>This is too deep a subject to fully describe in this documentation.
+Here are some pointers to useful discussions and tools:</p>
+
+<ul>
+<li>
+<code>snoop</code> is a packet sniffer that is part of Solaris.
+</li>
+<li>
+<a href="http://www.tcpdump.org/">tcpdump</a> is a packet sniffer that is
+available for Unix-based systems and Windows
+(<a href="http://www.winpcap.org/windump/">windump</a>).
+It is part of many free Unix-based distributions.
+</li>
+<li>
+<a href="http://www.wireshark.org/">Wireshark</a> is another packet sniffer
+that is available for Unix-based systems and Windows. It has a nice GUI and
+allows the analysis of the sniffed data.
+</li>
+<li><a href="http://jarok.cs.ohiou.edu/software/tcptrace/">
+    tcptrace</a> is a TCP dump file analysis tool.</li>
+<li><a href="http://www.tcpshow.org/">tcpshow</a> is
+    another one.</li>
+</ul>
+
+</section>
+
+</body>
+</document>

Propchange: httpd/site/trunk/content/dev/debugging.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: httpd/site/trunk/content/dev/devnotes.xml
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/devnotes.xml?rev=1334622&view=auto
==============================================================================
--- httpd/site/trunk/content/dev/devnotes.xml (added)
+++ httpd/site/trunk/content/dev/devnotes.xml Sun May  6 13:14:42 2012
@@ -0,0 +1,207 @@
+<?xml version="1.0"?>
+<document>
+  <properties>
+    <author email="docs@httpd.apache.org">Documentation Group</author>
+    <title>Apache Development Notes</title>
+  </properties>
+<body>
+<section>
+<title>Apache Development Notes</title>
+
+<p>This page is intended to provide some basic background about
+development nits and the maintenance of the developer site.</p>
+</section>
+
+<section>
+<title>Overview</title>
+
+<p>The Apache HTTP Server Project has switched to
+<a href="http://subversion.apache.org/">Subversion</a> for hosting its source
+code.</p>
+
+<p>To check out the 2.4.x branch:</p>
+<blockquote>
+<code>
+svn checkout http://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x httpd-2.4.x
+</code>
+</blockquote>
+
+<p>To check out the current development version (as of this writing, 2.5.x),
+use:</p>
+
+<blockquote>
+<code>
+svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk httpd-trunk
+</code>
+</blockquote>
+
+<p>Committers should check out via https instead of http (so that they can
+commit their changes).  For more info about Subversion, please read <a
+href="http://www.apache.org/dev/version-control.html"
+>the ASF version control FAQ</a>.</p>
+
+<p>The developers continue to seek to maintain module compatibility between
+2.4.1 and future 2.4 releases for administrators and end users, while
+continuing the forward progress that has made the 2.2 server faster and more
+scalable.</p>
+</section>
+
+<section>
+<title>Maintaining the Sources</title>
+
+<p>Almost all files relating to Apache, both the actual sources and the
+files that aren't part of the distribution, are now maintained in an
+<a href="http://subversion.apache.org/">SVN</a> repository.  Here is the way
+in which changes are applied:</p>
+
+  <ol>
+   <li>Developer checks out a copy of the files on which he wants to
+    work (in this case, the trunk), into a private working directory
+    called <samp>httpd-trunk</samp>:
+    <p>
+    <dl>
+     <dd><samp>% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk
+      httpd-trunk</samp>
+     </dd>
+    </dl>
+    </p>
+    <p>
+    This step only needs to be performed once (unless the private working
+    directory is tainted or deleted.)  Committers should use a URL prefix
+    of <samp>https</samp> on the checkout, to save themselves headaches later.
+    </p>
+   </li>
+   <li>Developer keeps his working directory synchronised with changes
+    made to the repository:
+    <p>
+    <dl>
+     <dd><samp>% svn update httpd-trunk</samp>
+     </dd>
+    </dl>
+    </p>
+    <p>
+    This should probably be done daily or even more frequently during
+    periods of high activity.
+    </p>
+   </li>
+   <li>Developer makes changes to his working copies, makes sure they
+    work, and generates a patch so others can apply the changes to test
+    them:
+    <p>
+    <dl>
+     <dd><samp>% svn diff httpd-trunk/modules/http/mod_mime.c &gt; /tmp/foo</samp>
+     </dd>
+    </dl>
+    </p>
+    <p>
+    The <samp>/tmp/foo</samp> file is mailed to the
+    <a href="http://httpd.apache.org/lists.html#http-dev">developers list</a> so
+    they can consider the value/validity of the patch.  It is worth
+    making sure your code follows the Apache style, as described in the
+    <a href="styleguide.html">style guide</a>.
+    </p>
+   </li>
+   <li>Once other developers have agreed that the change is a Good
+    Thing, the developer checks the changes into the repository:
+    <p>
+    <dl>
+     <dd><samp>% svn commit httpd-trunk/modules/http/mod_mime.c</samp>
+     </dd>
+    </dl>
+    </p>
+   </li>
+  </ol>
+</section>
+
+<section>
+<title>SVN Subtrees</title>
+  <p>There are several different branches under the <samp>httpd</samp>
+   subtree in the Apache SVN repository that pertain to the different
+   releases.  The top level can be perused with the
+   <a href="http://svn.apache.org/viewcvs.cgi/">SVN ViewCVS</a> pages.
+   The main subtrees pertaining to the <samp>httpd</samp> server source
+   are:</p>
+
+  <section><title>httpd-2.2</title>
+   <p>To create a directory tree containing the 2.2 sources,
+    and call it <samp>httpd-2.2</samp>, change your current directory
+    to the <em>parent</em> of the tree and then check the 2.2 sources
+    out as follows:</p>
+   <source>
+% cd /usr/local/apache
+% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/branches/2.2.x
+   httpd-2.2</source>
+  </section>
+
+  <section><title>httpd-2.4</title>
+   <p>To create a directory tree containing the 2.4 sources,
+    and call it <samp>httpd-2.4</samp>, change your current directory
+    to the <em>parent</em> of the tree and then check the 2.4 sources
+    out as follows:</p>
+   <source>
+% cd /usr/local/apache
+% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x
+   httpd-2.4</source>
+  </section>
+
+  <section><title>httpd-2.5</title>
+   <p>If you want to check out the bleeding edge of development, the
+     httpd-2.5 development tree (slated for a release 2.6), and call it
+     <samp>httpd-trunk</samp>, checkout as follows:</p>
+   <source>
+% cd /usr/local/apache
+% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk httpd-trunk</source>
+  </section>
+
+  <section><title>httpd-site</title>
+   <p>This subtree contains the files that live at <samp>http://httpd.apache.org/</samp>.
+    The directory on the host that maps to that URL is actually a set of
+    checked-out working copies of the SVN files.</p>
+   <p>The SVN URL is
+    <samp>https://svn.apache.org/repos/asf/httpd/site/trunk/docs</samp>.</p>
+   <make_note>
+    It is important that the files on the Web host not be modified
+    directly.  If you want or need to change one, check it out into a
+    private working copy, modify <strong>that</strong>, commit the
+    change into SVN, and then perform a <samp>svn update</samp> to
+    bring the host directory into sync with the SVN sources.
+   </make_note>
+   <p>The Web site <em>directories</em> (as opposed to files) are not
+    maintained in synch with the SVN files automatically.  They are
+    manually updated from SVN by various people as they consider
+    appropriate.  This is usually not an issue, unless a group of files
+    are being updated according to an ongoing group discussion.</p>
+  </section>
+
+  <section><title>httpd-dist</title>
+   <p>Like the <samp>httpd-site</samp> subtree, this one is used to
+    maintain the files that comprise a website - in this case,
+    <samp>http://www.apache.org/dist/httpd/</samp>.  Also like the
+    previous subtree, the directory on the server is a checked-out
+    working copy of this subtree.  However, since this is a distribution
+    directory, we only have the surrounding documentation and control
+    files checked into this subtree -- the actual tarballs are simply
+    copied to www.apache.org.</p>
+   <p>The SVN URL is
+    <samp>https://svn.apache.org/repos/asf/httpd/httpd/dist</samp>.</p>
+   <p>Committers will generally deal with this subtree when "rolling" a
+    release.  This is a series of steps taken to create a complete new
+    release of the Apache httpd software.  Amongst other things, the
+    key to this subtree is the <samp>tools/</samp> directory, which
+    contains the <samp>release.sh</samp> shell script.  More information
+    on the policies and procedures relating to rolling releases can be
+    found on the <a href="release.html">Release Guidelines</a> page.</p>
+  </section>
+</section>
+
+<section>
+<title>Setting Up Remote SVN</title>
+
+<p>A brief overview of getting started with SVN committer access can be
+found <a href="http://www.apache.org/dev/version-control.html#https-svn">
+here</a>.  One key change to note is that SSH is not used anymore for
+committer access, due to the functional differences with SVN.</p>
+</section>
+
+</body>
+</document>

Propchange: httpd/site/trunk/content/dev/devnotes.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: httpd/site/trunk/content/dev/fetch-from-cvs.txt
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/fetch-from-cvs.txt?rev=1334622&view=auto
==============================================================================
--- httpd/site/trunk/content/dev/fetch-from-cvs.txt (added)
+++ httpd/site/trunk/content/dev/fetch-from-cvs.txt Sun May  6 13:14:42 2012
@@ -0,0 +1,42 @@
+#!/usr/bin/perl -w
+#
+# Simple script to fetch the latest tarball in from-cvs/ and unpack it
+# in $dir.
+#
+# Script by Doug MacEachern <dougm@telebusiness.co.nz>
+# minor fix by Magnus Bodin <magnus@bodin.org>
+
+use strict;
+use URI::URL ();
+use HTML::LinkExtor ();
+use LWP::Simple;
+use File::Path;
+
+my $ver = '1.3';
+my $dir = shift || "/tmp/apache_$ver-dev";
+my $cvs = "http://cvs.apache.org/snapshots/apache-$ver/";
+my $filptn = "apache-$ver\_"; 
+
+rmtree $dir;
+mkpath $dir, 0755;
+
+chdir $dir;
+
+my $p = HTML::LinkExtor->new(\&cb, $cvs);
+my $cnt;
+
+sub cb {
+    my($tag, %links) = @_;
+    return unless exists $links{href} and $links{href} =~ /$fileptn/;
+    return unless ++$cnt == 4;
+
+    my $file = URI::URL->new($links{href})->rel($cvs);
+    warn "mirror $links{href} => $file\n";
+
+    mirror $links{href} => $file;
+    system "gunzip < $file | tar -xvf -";
+    unlink $file;
+}
+
+$p->parse(get $cvs);
+

Propchange: httpd/site/trunk/content/dev/fetch-from-cvs.txt
------------------------------------------------------------------------------
    svn:eol-style = native

Added: httpd/site/trunk/content/dev/footer.html
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/footer.html?rev=1334622&view=auto
==============================================================================
--- httpd/site/trunk/content/dev/footer.html (added)
+++ httpd/site/trunk/content/dev/footer.html Sun May  6 13:14:42 2012
@@ -0,0 +1 @@
+  <HR>

Propchange: httpd/site/trunk/content/dev/footer.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: httpd/site/trunk/content/dev/guidelines.xml
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/guidelines.xml?rev=1334622&view=auto
==============================================================================
--- httpd/site/trunk/content/dev/guidelines.xml (added)
+++ httpd/site/trunk/content/dev/guidelines.xml Sun May  6 13:14:42 2012
@@ -0,0 +1,458 @@
+<?xml version="1.0"?>
+<document>
+  <properties>
+    <author email="docs@httpd.apache.org">Documentation Group</author>
+    <title>Apache HTTP Server Project Guidelines and Voting Rules</title>
+  </properties>
+<body>
+
+<section><title>Apache Project Guidelines</title>
+
+<p>This document defines the guidelines for the
+<a href="http://httpd.apache.org/">Apache HTTP Server Project</a>.
+It includes definitions of how conflict is resolved by voting,
+who is able to vote, and the procedures to follow for proposing and 
+making changes to the Apache products.</p>
+
+<p>The objective here is to avoid unnecessary conflict over changes and
+continue to produce a quality system in a timely manner.  Not all conflict
+can be avoided, but at least we can agree on the procedures for conflict
+to be resolved.</p>
+</section>
+
+<section><title>People, Places, and Things</title>
+
+<dl>
+  <dt><strong>Apache HTTP Server Project Management Committee</strong></dt>
+  <dd>The group of volunteers who are responsible for managing the Apache
+      HTTP Server Project.  This includes deciding what is distributed 
+      as products of the Apache HTTP Server Project, maintaining the 
+      Project's shared resources, speaking on behalf of the Project, 
+      resolving license disputes regarding Apache products, nominating
+      new PMC members or committers, and establishing these guidelines.
+
+      <p>Membership in the Apache PMC is by invitation only and must
+      be approved by consensus of the active Apache PMC members.
+      A PMC member is considered inactive by their own declaration or by 
+      not contributing in any form to the project for over six months.  
+      An inactive member can become active again by reversing whichever
+      condition made them inactive (<em>i.e.</em>, by reversing their 
+      earlier declaration or by once again contributing toward the 
+      project's work).  Membership can be revoked by a unanimous vote of 
+      all the active PMC members other than the member in question.</p>
+  </dd>
+
+  <dt><strong>Apache HTTP Server Committers</strong></dt>
+  <dd>The group of volunteers who are responsible for the technical
+      aspects of the Apache HTTP Server Project.  This group has
+      write access to the appropriate source repositories and these
+      volunteers may cast binding votes on any technical discussion.
+
+      <p>Membership as a Committer is by invitation only and must
+      be approved by consensus of the active Apache PMC members.
+      A Committer is considered inactive by their own declaration or by 
+      not contributing in any form to the project for over six months.  
+      An inactive member can become active again by reversing whichever
+      condition made them inactive (<em>i.e.</em>, by reversing their 
+      earlier declaration or by once again contributing toward the 
+      project's work).  Membership can be revoked by a unanimous vote of 
+      all the active PMC members (except the member in question if they
+      are a PMC member).</p>
+  </dd>
+
+  <dt><strong>Apache Developers</strong></dt>
+  <dd>All of the volunteers who are contributing time, code, documentation,
+      or resources to the Apache Project.  A developer that makes sustained,
+      welcome contributions to the project for over six months is usually
+      invited to become a Committer, though the exact timing of such
+      invitations depends on many factors.</dd>
+
+  <dt><strong>mailing list</strong></dt>
+  <dd>The Apache developers' primary mailing list for discussion of issues
+      and changes related to the project (<em>dev@httpd.apache.org</em>).
+      Subscription to the list is open, but only subscribers
+      can post directly to the list.
+  </dd>
+
+  <dt><strong>private list</strong></dt>
+  <dd>The Apache PMC's private mailing list for discussion of issues
+      that are inappropriate for public discussion, such as legal, personal,
+      or security issues prior to a published fix.  Subscription to the list
+	  is only open (actually: mandatory) to Apache httpd's Project Management
+	  Comittee.
+  </dd>
+
+  <dt><strong>Subversion</strong></dt>
+  <dd>All of the Apache products are maintained in shared information
+      repositories using <a href="devnotes.html">Subversion on
+      <em>svn.apache.org</em></a>.  Only some of the Apache developers have
+      write access to these repositories; everyone has 
+      <a href="http://svn.apache.org/repos/asf/httpd/httpd">read access</a>.
+  </dd>
+</dl>
+</section>
+
+<section><title>STATUS</title>
+
+<p>Each of the Apache Project's active source code repositories contain a 
+file called "STATUS" which is used to keep track of the agenda and plans 
+for work within that repository.  The STATUS file includes information 
+about release plans, a summary of code changes committed since the last 
+release, a list of proposed changes that are under discussion, brief 
+notes about items that individual developers are working on or want 
+discussion about, and anything else that might be useful to help the 
+group track progress.  The active STATUS files are automatically posted 
+to the mailing list each week.</p>
+
+<p>Many issues will be encountered by the project, each resulting in 
+zero or more proposed action items.  Issues should be raised on the
+mailing list as soon as they are identified.  Action items 
+<strong>must</strong> be raised on the mailing list and added to the 
+relevant STATUS file.  All action items may be voted on, but not all 
+of them will require a formal vote.</p>
+</section>
+
+<section><title>Voting</title>
+
+<p>Any of the Apache Developers may vote on any issue or action item.
+However, the only binding votes are those cast by active members of the
+Apache HTTP Server; if the vote is about a change to source code or 
+documentation, the primary author of what is being changed may also 
+cast a binding vote on that issue.  All other votes are non-binding.
+All developers are encouraged to participate in decisions, but the 
+decision itself is made by those who have been long-time contributors 
+to the project.  In other words, the Apache httpd Project is a 
+minimum-threshold meritocracy.</p>
+
+<p>The act of voting carries certain obligations -- voting members are 
+not only stating their opinion, they are agreeing to help do the work of 
+the Apache Project.  Since we are all volunteers, members often become 
+inactive for periods of time in order to take care of their "real jobs" 
+or devote more time to other projects. It is therefore unlikely that the 
+entire group membership will vote on every issue.  To account for this, 
+all voting decisions are based on a minimum quorum.</p>
+
+<p>Each vote can be made in one of three flavors:</p>
+
+<dl compact="compact">
+  <dt><strong>+1</strong></dt>
+  <dd>Yes, agree, or the action should be performed.  On some issues, this
+      vote is only binding if the voter has tested the action on
+      their own system(s).
+  </dd>
+  <dt><strong>&#177;0</strong></dt>
+  <dd>Abstain, no opinion, or I am happy to let the other group members
+      decide this issue.  An abstention may have detrimental effects if
+      too many people abstain.
+  </dd>
+  <dt><strong>-1</strong></dt>
+  <dd>No. On issues where consensus is required, this vote counts as a
+      <strong>veto</strong>.  All vetos must include an explanation of
+      why the veto is appropriate.  A veto with no explanation is void.
+      No veto can be overruled. If you disagree with the veto, you
+      should lobby the person who cast the veto. Voters intending to veto
+      an action item should make their opinions known to the group immediately,
+      so that the problem can be remedied as early as possible.
+  </dd>
+</dl>
+
+<p>An action item requiring <em>consensus approval</em> must receive
+at least <strong>3 binding +1</strong> votes and <strong>no vetos</strong>.
+An action item requiring <em>majority approval</em> must receive
+at least <strong>3 binding +1</strong> votes and more <strong>+1</strong>
+votes than <strong>-1</strong> votes (<em>i.e.</em>, a majority with a minimum
+quorum of three positive votes).  All other action items are considered
+to have <em>lazy approval</em> until someone votes <strong>-1</strong>,
+after which point they are decided by either consensus or a majority vote,
+depending upon the type of action item.</p>
+
+<p>Votes are tallied within the STATUS file, adjacent to the action
+item under vote. All votes must be either sent to the mailing list
+or added directly to the STATUS file entry for that action item.</p>
+
+</section>
+
+<section><title>Types of Action Items</title>
+<dl>
+  <dt><strong>Long Term Plans</strong></dt>
+  <dd>Long term plans are simply announcements that group members
+      are working on particular issues related to the Apache software.
+      These are not voted on,
+      but group members who do not agree with a particular plan,
+      or think an alternate plan would be better, are obligated to
+      inform the group of their feelings.  In general, it is always
+      better to hear about alternate plans <strong>prior</strong> to
+      spending time on less adequate solutions.
+  </dd>
+
+  <dt><strong>Short Term Plans</strong></dt>
+  <dd>Short term plans are announcements that a developer is working on
+      a particular set of documentation or code files, with the implication
+      that other developers should avoid them or try to coordinate their
+      changes.  This is a good way to proactively avoid conflict and 
+      possible duplication of work.
+  </dd>
+
+  <dt><strong>Release Plan</strong></dt>
+  <dd>A release plan is used to keep all the developers aware of when a
+      release is desired, who will be the release manager, when the
+      repository will be frozen in order to create the release, and 
+      assorted other trivia to keep us from tripping over ourselves
+      during the final moments.  Lazy majority decides each issue in
+      the release plan.
+  </dd>
+
+  <dt><strong>Release Testing</strong></dt>
+  <dd>After a new release is built, colloquially termed a tarball, it
+      must be tested before being released to the public.  Majority
+      approval is required before the tarball can be publically released.
+  </dd>
+
+  <dt><strong>Showstoppers</strong></dt>
+  <dd>Showstoppers are issues that require a fix be in place
+      before the next public release.  They are listed in the STATUS file
+      in order to focus special attention on the problem.  An issue becomes
+      a showstopper when it is listed as such in STATUS and remains
+      so by lazy consensus.
+  </dd>
+
+  <dt><strong>Product Changes</strong></dt>
+  <dd>Changes to the Apache products, including code and documentation,
+      will appear as action items under several categories corresponding
+      to the change status:
+      <dl>
+      <dt><strong>concept/plan</strong></dt>
+      <dd>An idea or plan for a change.  These are usually only listed in
+          STATUS when the change is substantial, significantly impacts the
+          API, or is likely to be controversial.  Votes are being requested
+          early so as to uncover conflicts before too much work is done.
+      </dd>
+      <dt><strong>proposed patch</strong></dt>
+      <dd>A specific set of changes to the current product in the form
+          of <a href="#patch">input to the patch command</a> (a diff output).
+      </dd>
+      <dt><strong>committed change</strong></dt>
+      <dd>A one-line summary of a change that has been committed to the
+          repository since the last public release.
+      </dd>
+      </dl>
+      <p>All product changes to the currently active repository are subject
+      to lazy consensus.  All product changes to a prior-branch (old version)
+      repository require consensus before the change is committed.</p>
+  </dd>
+  
+  <dt><strong>Backport</strong></dt>
+  <dd>A backport is the application of a change on the Subversion
+      repository trunk to the a maintenance branch of the project. This is 
+      necessary in cases where an issue exists in multiple versions of the 
+      Apache HTTP Server. A fix for such an issue will typically be developed 
+      for the trunk, which is under active development. 
+  </dd>
+</dl>
+</section>
+
+<section><title>When to Commit a Change</title>
+
+<p>Ideas must be review-then-commit; patches can be commit-then-review.
+With a commit-then-review process, we trust that the developer doing the
+commit has a high degree of confidence in the change.  Doubtful changes,
+new features, and large-scale overhauls need to be discussed before
+being committed to a repository. Any change that affects the semantics
+of arguments to configurable directives, significantly adds to the runtime
+size of the program, or changes the semantics of an existing API function
+must receive consensus approval on the mailing list before being committed.
+</p>
+
+<p>Each developer is responsible for notifying the mailing list and 
+adding an action item to STATUS when they have an idea for a new feature 
+or major change to propose for the product.  The distributed nature of the
+Apache project requires an advance notice of 48 hours in order to properly
+review a major change -- consensus approval of either the concept or a
+specific patch is required before the change can be committed.  Note that
+a member might veto the concept (with an adequate explanation), but later
+rescind that veto if a specific patch satisfies their objections.
+No advance notice is required to commit singular bug fixes.</p>
+
+<p>Related changes should be committed as a group, or very closely 
+together.  Half-completed projects should not be committed unless 
+doing so is necessary to pass the baton to another developer who has 
+agreed to complete the project in short order.  All code changes must 
+be successfully compiled on the developer's platform before being 
+committed.</p>
+
+<p>The current source code tree should be capable of complete compilation
+at all times.  However, it is sometimes impossible for a developer on
+one platform to avoid breaking some other platform when a change is
+committed, particularly when completing the change requires access to
+a special development tool on that other platform.  If it is anticipated
+that a given change will break some other platform, the committer must
+indicate that in the commit log.</p>
+
+<p>The committer is responsible for the quality of any third-party code
+or documentation they commit to the repository.  All software committed
+to the repository must be covered by the Apache LICENSE or contain a
+copyright and license that allows redistribution under the same conditions
+as the Apache LICENSE.</p>
+
+<p>A committed change must be reversed if it is vetoed by one of the 
+voting members and the veto conditions cannot be immediately satisfied by 
+the equivalent of a "bug fix" commit.  The veto must be rescinded before 
+the change can be included in any public release.</p>
+
+</section>
+
+<section id="changelogs"><title>CHANGES file and Subversion logs</title>
+<p>Many code changes should be noted in the CHANGES file, and
+all should be documented in Subversion commit messages.
+Often the text of the Subversion log and the CHANGES entry are the same, but
+the distinct requirements sometimes result in different information.</p>
+
+<section><title>Subversion log</title>
+<p>The Subversion commit log message contains any information needed by
+<ul>
+<li>fellow developers or other people researching source code changes/fixes</li>
+<li>end users (at least point out what the implications are for end
+users; it doesn't have to be in the most user friendly wording)</li>
+</ul>
+</p>
+
+<p>If the code change was provided by a non-committer, attribute it
+using Submitted-by.  If the change was committed verbatim, identify
+the committer(s) who reviewed it with Reviewed-by.  If the change was
+committed with modifications, use the appropriate wording to document
+that, perhaps "committed with changes" if the person making the commit
+made the changes, or "committed with contributions from xxxx" if
+others made contributions to the code committed.</p>
+
+<p>Example log message:
+
+<pre>
+Check the return code from parsing the content length, to avoid a
+crash if requests contain an invalid content length.
+
+PR: 99999
+Submitted by: Jane Doe &lt;janedoe example.com&gt;
+Reviewed by: susiecommitter
+</pre>
+</p>
+
+<p>Commit messages can be minimal when making routine updates to STATUS,
+for example to propose a backport or vote.</p>
+
+</section>
+
+<section><title>CHANGES</title>
+<p>CHANGES is the subset of the information that end users need to see
+when they upgrade from one release to the next:<ul>
+<li>what can I now do that I couldn't do before</li>
+<li>what problems that we anticipate a user could have suffered from are now fixed</li>
+<li>all security fixes included, with CVE number.  (If not available at
+the time of the commit, add later.)</li>
+</ul></p>
+
+<p>The usability of CHANGES for end users decreases as information of use
+to few individuals, or which doesn't pertain to evaluating the new
+release, is added.  Specifically:<ul>
+<li>Fixes for bugs introduced after the last release don't belong in CHANGES.</li>
+<li>Fixes for bugs that we don't expect anybody noticed don't belong in
+CHANGES.  (Bend the rule a little for outside contributions, as the
+submitter may need to see their name in lights as reward for their
+efforts, which typically were undertaken with no guarantee that any
+committer would take interest.)</li>
+<li>Documentation fixes, whether for end users or developers, don't
+belong in CHANGES.</li></ul></p>
+
+<p>CHANGES applies to changes even between alpha releases, so backporting
+a change from trunk to a stable release does not generally require removing
+the change from the CHANGES file in trunk.</p>
+
+<p>The attribution for the change is anyone responsible for the code changes.</p>
+</section>
+
+<section><title>Formatting</title>
+<p>Identify non-committers by name, and their email in obfuscated
+form if available.  The obfuscation is done by replacing "@" with a 
+space and adding "&lt;" and ">" around the address.  For example,
+change <tt>user@example.com</tt> to <tt>&lt;user example.com&gt;</tt>.
+</p>
+
+<p>Identify committers with their Apache userid, e.g. <tt>xyz</tt>
+(no domain name needed).  </p>
+
+<p>If the change is related to a bugzilla issue, include the PR number
+in the log in the format:<pre>
+PR nnnnn
+</pre></p>
+
+<p>Security-related changes should start like this:<pre>
+  *) SECURITY: CVE-YYYY-NNNN (cve.mitre.org)
+  xxxxxxxxxx
+</pre></p>
+
+<p>Most changes are inserted at the top of the CHANGES file.  However,
+security-related changes should always be at the top of the list of changes
+for the relevant release, so if there are unreleased security changes
+at the top of the file, insert other changes below them.</p>
+
+<p>Example CHANGES entries:
+
+<pre>
+  *) SECURITY: CVE-2009-3095 (cve.mitre.org)
+     mod_proxy_ftp: sanity check authn credentials.
+     [Stefan Fritsch &lt;sf fritsch.de>, Joe Orton]
+
+  *) Replace AcceptMutex, LockFile, RewriteLock, SSLMutex, SSLStaplingMutex,
+     and WatchdogMutexPath with a single Mutex directive.  Add APIs to
+     simplify setup and user customization of APR proc and global mutexes.  
+     (See util_mutex.h.)  Build-time setting DEFAULT_LOCKFILE is no longer
+     respected; set DEFAULT_REL_RUNTIMEDIR instead.  [Jeff Trawick]
+</pre>
+</p>
+
+</section>
+
+</section>
+
+<section id="patch"><title>Patch Format</title>
+<p>When a specific change to the software is proposed for discussion or
+voting on the mailing list, it should be presented in the form of input 
+to the patch command.  When sent to the mailing list, the message 
+should contain a Subject beginning with <code>[PATCH]</code> and a 
+distinctive one-line summary corresponding to the action item for that 
+patch.  Afterwords, the patch summary in the STATUS file should be 
+updated to point to the Message-ID of that message.</p>
+
+<p>The patch should be created by using the <CODE>diff -u</CODE> 
+command from the original software file(s) to the modified software 
+file(s).  E.g.,</p>
+
+<pre>    diff -u http_main.c.orig http_main.c &gt;&gt; patchfile.txt</pre>
+<p>or</p>
+<pre>    svn diff http_main.c &gt;&gt; patchfile.txt</pre>
+
+<p>All patches necessary to address an action item should be concatenated
+within a single patch message.  If later modification of the patch
+proves necessary, the entire new patch should be posted and not just
+the difference between two patches.  The STATUS file entry should then
+be updated to point to the new patch message.</p>
+
+<p>The completed patchfile should produce no errors or prompts when the
+command,</p>
+<pre>    patch -s &lt; patchfile</pre>
+<p>is issued in the target repository.</p>
+</section>
+
+<section><title>Addendum</title>
+
+<p>Outstanding issues with this document</p>
+
+<ul>
+    <li>We may need a better definition for "lazy consensus".</li>
+    <li>We should clarify under what conditions a veto can be rescinded 
+        or overridden.</li>
+    <li>Should we set a time limit on vetos of patches?  Two weeks?</li>
+</ul>
+</section>
+
+</body>
+</document>

Propchange: httpd/site/trunk/content/dev/guidelines.xml
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message