httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rbo...@apache.org
Subject cvs commit: httpd-docs-1.3/htdocs/manual/misc API.html FAQ-A.html FAQ-B.html FAQ-C.html FAQ-D.html FAQ-E.html FAQ-F.html FAQ-G.html FAQ-H.html FAQ-I.html FAQ.html client_block_api.html compat_notes.html custom_errordocs.html descriptors.html fin_wait_2.html footer.html header.html howto.html index.html known_client_problems.html nopgp.html perf-bsd44.html perf-dec.html perf-hp.html perf-tuning.html perf.html rewriteguide.html security_tips.html tutorials.html vif-info.html windoz_keepalive.html
Date Mon, 08 Oct 2001 01:26:56 GMT
rbowen      01/10/07 18:26:55

  Modified:    htdocs/manual/misc API.html FAQ-A.html FAQ-B.html FAQ-C.html
                        FAQ-D.html FAQ-E.html FAQ-F.html FAQ-G.html
                        FAQ-H.html FAQ-I.html FAQ.html
                        client_block_api.html compat_notes.html
                        custom_errordocs.html descriptors.html
                        fin_wait_2.html footer.html header.html howto.html
                        index.html known_client_problems.html nopgp.html
                        perf-bsd44.html perf-dec.html perf-hp.html
                        perf-tuning.html perf.html rewriteguide.html
                        security_tips.html tutorials.html vif-info.html
                        windoz_keepalive.html
  Log:
  w3c tidy to convert to xhtml
  P/:
  
  Revision  Changes    Path
  1.19      +995 -910  httpd-docs-1.3/htdocs/manual/misc/API.html
  
  Index: API.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/API.html,v
  retrieving revision 1.18
  retrieving revision 1.19
  diff -u -r1.18 -r1.19
  --- API.html	1999/03/07 15:05:32	1.18
  +++ API.html	2001/10/08 01:26:54	1.19
  @@ -1,170 +1,213 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML><HEAD>
  -<TITLE>Apache API notes</TITLE>
  -</HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Apache API notes</H1>
  -
  -These are some notes on the Apache API and the data structures you
  -have to deal with, <EM>etc.</EM>  They are not yet nearly complete, but
  -hopefully, they will help you get your bearings.  Keep in mind that
  -the API is still subject to change as we gain experience with it.
  -(See the TODO file for what <EM>might</EM> be coming).  However,
  -it will be easy to adapt modules to any changes that are made.
  -(We have more modules to adapt than you do).
  -<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>
  -<MENU>
  - <LI> <A HREF="#HMR">Handlers, Modules, and Requests</A>
  - <LI> <A HREF="#moduletour">A brief tour of a module</A>
  -</MENU>
  -<LI> <A HREF="#handlers">How handlers work</A>
  -<MENU>
  - <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>
  -</MENU>
  -<LI> <A HREF="#pools">Resource allocation and resource pools</A>
  -<LI> <A HREF="#config">Configuration, commands and the like</A>
  -<MENU>
  - <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, <EM>etc</EM>.</A>
  -</MENU>
  -</UL>
  -
  -<H2><A NAME="basics">Basic concepts.</A></H2>
  -
  -We begin with an overview of the basic concepts behind the
  -API, and how they are manifested in the code.
  -
  -<H3><A NAME="HMR">Handlers, Modules, and Requests</A></H3>
  -
  -Apache breaks down request handling into a series of steps, more or
  -less the same way the Netscape server API does (although this API 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> (<EM>i.e.</EM>, 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 every place.<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 recognize <CODE>ScriptAlias</CODE>ed URIs), 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, <EM>etc.</EM>, 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, <EM>en masse</EM>, 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>).
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -With no further ado, the module itself:
  -
  -<PRE>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache API notes</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache API notes</h1>
  +    These are some notes on the Apache API and the data structures
  +    you have to deal with, <em>etc.</em> They are not yet nearly
  +    complete, but hopefully, they will help you get your bearings.
  +    Keep in mind that the API is still subject to change as we gain
  +    experience with it. (See the TODO file for what <em>might</em>
  +    be coming). However, it will be easy to adapt modules to any
  +    changes that are made. (We have more modules to adapt than you
  +    do). 
  +
  +    <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>
  +
  +    <p>Finally, here's an outline, to give you some bare idea of
  +    what's coming up, and in what order:</p>
  +
  +    <ul>
  +      <li>
  +        <a href="#basics">Basic concepts.</a> 
  +
  +        <ul>
  +          <li><a href="#HMR">Handlers, Modules, and
  +          Requests</a></li>
  +
  +          <li><a href="#moduletour">A brief tour of a
  +          module</a></li>
  +        </ul>
  +      </li>
  +
  +      <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>
  +
  +          <li><a href="#req_orig">Where request_rec structures come
  +          from</a></li>
  +
  +          <li><a href="#req_return">Handling requests, declining,
  +          and returning error codes</a></li>
  +
  +          <li><a href="#resp_handlers">Special considerations for
  +          response handlers</a></li>
  +
  +          <li><a href="#auth_handlers">Special considerations for
  +          authentication handlers</a></li>
  +
  +          <li><a href="#log_handlers">Special considerations for
  +          logging handlers</a></li>
  +        </ul>
  +      </li>
  +
  +      <li><a href="#pools">Resource allocation and resource
  +      pools</a></li>
  +
  +      <li>
  +        <a href="#config">Configuration, commands and the like</a> 
  +
  +        <ul>
  +          <li><a href="#per-dir">Per-directory configuration
  +          structures</a></li>
  +
  +          <li><a href="#commands">Command handling</a></li>
  +
  +          <li><a href="#servconf">Side notes --- per-server
  +          configuration, virtual servers, <em>etc</em>.</a></li>
  +        </ul>
  +      </li>
  +    </ul>
  +
  +    <h2><a id="basics" name="basics">Basic concepts.</a></h2>
  +    We begin with an overview of the basic concepts behind the API,
  +    and how they are manifested in the code. 
  +
  +    <h3><a id="HMR" name="HMR">Handlers, Modules, and
  +    Requests</a></h3>
  +    Apache breaks down request handling into a series of steps,
  +    more or less the same way the Netscape server API does
  +    (although this API 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>
  +
  +      <li>Auth ID checking [is the user who they say they
  +      are?]</li>
  +
  +      <li>Auth access checking [is the user authorized
  +      <em>here</em>?]</li>
  +
  +      <li>Access checking other than auth</li>
  +
  +      <li>Determining MIME type of the object requested</li>
  +
  +      <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>
  +
  +      <li>Actually sending a response back to the client.</li>
  +
  +      <li>Logging the request</li>
  +    </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>
  +
  +      <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>
  +
  +      <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.</li>
  +    </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> (<em>i.e.</em>, 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 id="moduletour" 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 every place. 
  +
  +    <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 recognize
  +    <code>ScriptAlias</code>ed URIs), the type-checking phase (any
  +    <code>ScriptAlias</code>ed request is typed as a CGI
  +    script).</p>
  +
  +    <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>
  +
  +    <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>
  +
  +    <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, <em>etc.</em>, 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, <em>en masse</em>, 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:</p>
  +<pre>
   /* Declarations of handlers. */
   
   int translate_scriptalias (request_rec *);
  @@ -216,59 +259,65 @@
      NULL,                     /* logger */
      NULL                      /* header parser */
   };
  -</PRE>
  -
  -<H2><A NAME="handlers">How handlers work</A></H2>
  +</pre>
   
  -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
  -response (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>ap_table_get</CODE> and <CODE>ap_table_set</CODE> routines. <P>
  -<BLOCKQUOTE>
  - Note that the <SAMP>Content-type</SAMP> header value <EM>cannot</EM> be
  - set by module content-handlers using the <SAMP>ap_table_*()</SAMP>
  - routines.  Rather, it is set by pointing the <SAMP>content_type</SAMP>
  - field in the <SAMP>request_rec</SAMP> structure to an appropriate
  - string.  <EM>E.g.</EM>,
  - <PRE>
  +    <h2><a id="handlers" 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. 
  +
  +    <h3><a id="req_tour" 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>
  +
  +    <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 response (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>ap_table_get</code> and
  +    <code>ap_table_set</code> routines.</p>
  +
  +    <blockquote>
  +      Note that the <samp>Content-type</samp> header value
  +      <em>cannot</em> be set by module content-handlers using the
  +      <samp>ap_table_*()</samp> routines. Rather, it is set by
  +      pointing the <samp>content_type</samp> field in the
  +      <samp>request_rec</samp> structure to an appropriate string.
  +      <em>E.g.</em>, 
  +<pre>
     r-&gt;content_type = "text/html";
  - </PRE>
  -</BLOCKQUOTE>
  -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>
  +</pre>
  +    </blockquote>
  +    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;
  @@ -306,8 +355,8 @@
   
     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, <EM>etc.</EM> */
  -  int method_number;   /* M_GET, M_POST, <EM>etc.</EM> */
  +  char *method;        /* GET, HEAD, POST, <em>etc.</em> */
  +  int method_number;   /* M_GET, M_POST, <em>etc.</em> */
   
     /* Info for logging */
   
  @@ -325,109 +374,115 @@
      * (the thing pointed to being the module's business).
      */
   
  -  void *per_dir_config;   /* Options set in config files, <EM>etc.</EM> */
  +  void *per_dir_config;   /* Options set in config files, <em>etc.</em> */
     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 (<EM>i.e.</EM>, 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>ap_sub_req_lookup_file</CODE>,
  -       <CODE>ap_sub_req_lookup_uri</CODE>, and
  -       <CODE>ap_sub_req_method_uri</CODE>; these construct 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>ap_run_sub_req</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>ap_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>ap_rputc</CODE>
  -and <CODE>ap_rprintf</CODE>, for internally generated output, and
  -<CODE>ap_send_fd</CODE>, to copy the contents of some <CODE>FILE *</CODE>
  -straight 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 --- <CODE>ap_set_last_modified</CODE> checks
  -against the <CODE>If-modified-since</CODE> value supplied by the
  -client, if any, and returns an appropriate code (which will, if
  -nonzero, be USE_LOCAL_COPY).   No similar considerations apply for
  -<CODE>ap_set_content_length</CODE>, but it returns an error code for
  -symmetry.<P>
  +</pre>
   
  -<PRE>
  +    <h3><a id="req_orig" 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
  +      (<em>i.e.</em>, 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.</li>
  +
  +      <li>If some handler signaled an error, and an
  +      <code>ErrorDocument</code> is in scope, the same internal
  +      redirect machinery comes into play.</li>
  +
  +      <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>ap_sub_req_lookup_file</code>,
  +        <code>ap_sub_req_lookup_uri</code>, and
  +        <code>ap_sub_req_method_uri</code>; these construct 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>
  +
  +        <p>(Server-side includes work by building sub-requests and
  +        then actually invoking the response handler for them, via
  +        the function <code>ap_run_sub_req</code>).</p>
  +      </li>
  +    </ul>
  +
  +    <h3><a id="req_return" 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>
  +
  +      <li>DECLINED --- no erroneous condition exists, but the
  +      module declines to handle the phase; the server tries to find
  +      another.</li>
  +
  +      <li>an HTTP error code, which aborts handling of the
  +      request.</li>
  +    </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>. 
  +
  +    <h3><a id="resp_handlers" 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>ap_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>
  +
  +    <p>Otherwise, they should produce a request body which responds
  +    to the client as appropriate. The primitives for this are
  +    <code>ap_rputc</code> and <code>ap_rprintf</code>, for
  +    internally generated output, and <code>ap_send_fd</code>, to
  +    copy the contents of some <code>FILE *</code> straight to the
  +    client.</p>
  +
  +    <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 ---
  +    <code>ap_set_last_modified</code> checks against the
  +    <code>If-modified-since</code> value supplied by the client, if
  +    any, and returns an appropriate code (which will, if nonzero,
  +    be USE_LOCAL_COPY). No similar considerations apply for
  +    <code>ap_set_content_length</code>, but it returns an error
  +    code for symmetry.</p>
  +<pre>
   int default_handler (request_rec *r)
   {
       int errstatus;
  @@ -437,7 +492,7 @@
       if (r-&gt;finfo.st_mode == 0) return NOT_FOUND;
   
       if ((errstatus = ap_set_content_length (r, r-&gt;finfo.st_size))
  -	|| (errstatus = ap_set_last_modified (r, r-&gt;finfo.st_mtime)))
  +    || (errstatus = ap_set_last_modified (r, r-&gt;finfo.st_mtime)))
           return errstatus;
   
       f = fopen (r-&gt;filename, "r");
  @@ -455,119 +510,125 @@
       ap_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>ap_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>ap_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>ap_auth_type</CODE>,
  -       <CODE>ap_auth_name</CODE>, and <CODE>ap_requires</CODE>.
  -  <LI> Common routines, to handle the protocol end of things, at least
  -       for HTTP basic authentication (<CODE>ap_get_basic_auth_pw</CODE>,
  -       which sets the <CODE>connection-&gt;user</CODE> structure field
  -       automatically, and <CODE>ap_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.  Apache 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
  -initial 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>
  -<P>
  -One of the problems of writing and designing a server-pool server is
  -that of preventing leakage, that is, allocating resources (memory,
  -open files, <EM>etc.</EM>), without subsequently releasing them.  The resource
  -pool machinery is designed to make it easy to prevent this from
  -happening, by allowing resource to be allocated in such a way that
  -they are <EM>automatically</EM> released when the server is done with
  -them.
  -</P>
  -<P>
  -The way this works is as follows:  the memory which is allocated, file
  -opened, <EM>etc.</EM>, to deal with a particular request are tied to a
  -<EM>resource pool</EM> which is allocated for the request.  The pool
  -is a data structure which itself tracks the resources in question.
  -</P>
  -<P>
  -When the request has been processed, the pool is <EM>cleared</EM>.  At
  -that point, all the memory associated with it is released for reuse,
  -all files associated with it are closed, and any other clean-up
  -functions which are associated with the pool are run.  When this is
  -over, we can be confident that all the resource tied to the pool have
  -been released, and that none of them have leaked.
  -</P>
  -<P>
  -Server restarts, and allocation of memory and resources for per-server
  -configuration, are handled in a similar way.  There is a
  -<EM>configuration pool</EM>, which keeps track of resources which were
  -allocated while reading the server configuration files, and handling
  -the commands therein (for instance, the memory that was allocated for
  -per-server module configuration, log files and other files that were
  -opened, and so forth).  When the server restarts, and has to reread
  -the configuration files, the configuration pool is cleared, and so the
  -memory and file descriptors which were taken up by reading them the
  -last time are made available for reuse.
  -</P>
  -<P>
  -It should be noted that use of the pool machinery isn't generally
  -obligatory, except for situations like logging handlers, where you
  -really need to register cleanups to make sure that the log file gets
  -closed when the server restarts (this is most easily done by using the
  -function <CODE><A HREF="#pool-files">ap_pfopen</A></CODE>, which also
  -arranges for the underlying file descriptor to be closed before any
  -child processes, such as for CGI scripts, are <CODE>exec</CODE>ed), or
  -in case you are using the timeout machinery (which isn't yet even
  -documented here).  However, there are two benefits to using it:
  -resources allocated to a pool never leak (even if you allocate a
  -scratch string, and just forget about it); also, for memory
  -allocation, <CODE>ap_palloc</CODE> is generally faster than
  -<CODE>malloc</CODE>.
  -</P>
  -<P>
  -We begin here by describing how memory is allocated to pools, and then
  -discuss how other resources are tracked by the resource pool
  -machinery.
  -</P>
  -<H3>Allocation of memory in pools</H3>
  -<P>
  -Memory is allocated to pools by calling the function
  -<CODE>ap_palloc</CODE>, which takes two arguments, one being a pointer to
  -a resource pool structure, and the other being the amount of memory to
  -allocate (in <CODE>char</CODE>s).  Within handlers for handling
  -requests, the most common way of getting a resource pool structure is
  -by looking at the <CODE>pool</CODE> slot of the relevant
  -<CODE>request_rec</CODE>; hence the repeated appearance of the
  -following idiom in module code:
  -</P>
  -<PRE>
  +</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>ap_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>ap_internal_redirect</code> from handlers
  +    which are <em>not</em> response handlers will lead to serious
  +    confusion).</p>
  +
  +    <h3><a id="auth_handlers" 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>
  +
  +      <li>Common auth configuration stored in the core per-dir
  +      configuration; it has accessors <code>ap_auth_type</code>,
  +      <code>ap_auth_name</code>, and <code>ap_requires</code>.</li>
  +
  +      <li>Common routines, to handle the protocol end of things, at
  +      least for HTTP basic authentication
  +      (<code>ap_get_basic_auth_pw</code>, which sets the
  +      <code>connection-&gt;user</code> structure field
  +      automatically, and <code>ap_note_basic_auth_failure</code>,
  +      which arranges for the proper <code>WWW-Authenticate:</code>
  +      header to be sent back).</li>
  +    </ul>
  +
  +    <h3><a id="log_handlers" name="log_handlers">Special
  +    considerations for logging handlers</a></h3>
  +    When a request has internally redirected, there is the question
  +    of what to log. Apache 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 initial 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 id="pools" name="pools">Resource allocation and resource
  +    pools</a></h2>
  +
  +    <p>One of the problems of writing and designing a server-pool
  +    server is that of preventing leakage, that is, allocating
  +    resources (memory, open files, <em>etc.</em>), without
  +    subsequently releasing them. The resource pool machinery is
  +    designed to make it easy to prevent this from happening, by
  +    allowing resource to be allocated in such a way that they are
  +    <em>automatically</em> released when the server is done with
  +    them.</p>
  +
  +    <p>The way this works is as follows: the memory which is
  +    allocated, file opened, <em>etc.</em>, to deal with a
  +    particular request are tied to a <em>resource pool</em> which
  +    is allocated for the request. The pool is a data structure
  +    which itself tracks the resources in question.</p>
  +
  +    <p>When the request has been processed, the pool is
  +    <em>cleared</em>. At that point, all the memory associated with
  +    it is released for reuse, all files associated with it are
  +    closed, and any other clean-up functions which are associated
  +    with the pool are run. When this is over, we can be confident
  +    that all the resource tied to the pool have been released, and
  +    that none of them have leaked.</p>
  +
  +    <p>Server restarts, and allocation of memory and resources for
  +    per-server configuration, are handled in a similar way. There
  +    is a <em>configuration pool</em>, which keeps track of
  +    resources which were allocated while reading the server
  +    configuration files, and handling the commands therein (for
  +    instance, the memory that was allocated for per-server module
  +    configuration, log files and other files that were opened, and
  +    so forth). When the server restarts, and has to reread the
  +    configuration files, the configuration pool is cleared, and so
  +    the memory and file descriptors which were taken up by reading
  +    them the last time are made available for reuse.</p>
  +
  +    <p>It should be noted that use of the pool machinery isn't
  +    generally obligatory, except for situations like logging
  +    handlers, where you really need to register cleanups to make
  +    sure that the log file gets closed when the server restarts
  +    (this is most easily done by using the function <code><a
  +    href="#pool-files">ap_pfopen</a></code>, which also arranges
  +    for the underlying file descriptor to be closed before any
  +    child processes, such as for CGI scripts, are
  +    <code>exec</code>ed), or in case you are using the timeout
  +    machinery (which isn't yet even documented here). However,
  +    there are two benefits to using it: resources allocated to a
  +    pool never leak (even if you allocate a scratch string, and
  +    just forget about it); also, for memory allocation,
  +    <code>ap_palloc</code> is generally faster than
  +    <code>malloc</code>.</p>
  +
  +    <p>We begin here by describing how memory is allocated to
  +    pools, and then discuss how other resources are tracked by the
  +    resource pool machinery.</p>
  +
  +    <h3>Allocation of memory in pools</h3>
  +
  +    <p>Memory is allocated to pools by calling the function
  +    <code>ap_palloc</code>, which takes two arguments, one being a
  +    pointer to a resource pool structure, and the other being the
  +    amount of memory to allocate (in <code>char</code>s). Within
  +    handlers for handling requests, the most common way of getting
  +    a resource pool structure is by looking at the
  +    <code>pool</code> slot of the relevant
  +    <code>request_rec</code>; hence the repeated appearance of the
  +    following idiom in module code:</p>
  +<pre>
   int my_handler(request_rec *r)
   {
       struct my_structure *foo;
  @@ -575,355 +636,374 @@
   
       foo = (foo *)ap_palloc (r-&gt;pool, sizeof(my_structure));
   }
  -</PRE>
  -<P>
  -Note that <EM>there is no <CODE>ap_pfree</CODE></EM> ---
  -<CODE>ap_palloc</CODE>ed memory is freed only when the associated
  -resource pool is cleared.  This means that <CODE>ap_palloc</CODE> does not
  -have to do as much accounting as <CODE>malloc()</CODE>; all it does in
  -the typical case is to round up the size, bump a pointer, and do a
  -range check.
  -</P>
  -<P>
  -(It also raises the possibility that heavy use of <CODE>ap_palloc</CODE>
  -could cause a server process to grow excessively large.  There are
  -two ways to deal with this, which are dealt with below; briefly, you
  -can use <CODE>malloc</CODE>, and try to be sure that all of the memory
  -gets explicitly <CODE>free</CODE>d, or you can allocate a sub-pool of
  -the main pool, allocate your memory in the sub-pool, and clear it out
  -periodically.  The latter technique is discussed in the section on
  -sub-pools below, and is used in the directory-indexing code, in order
  -to avoid excessive storage allocation when listing directories with
  -thousands of files).
  -</P>
  -<H3>Allocating initialized memory</H3>
  -<P>
  -There are functions which allocate initialized memory, and are
  -frequently useful.  The function <CODE>ap_pcalloc</CODE> has the same
  -interface as <CODE>ap_palloc</CODE>, but clears out the memory it
  -allocates before it returns it.  The function <CODE>ap_pstrdup</CODE>
  -takes a resource pool and a <CODE>char *</CODE> as arguments, and
  -allocates memory for a copy of the string the pointer points to,
  -returning a pointer to the copy.  Finally <CODE>ap_pstrcat</CODE> is a
  -varargs-style function, which takes a pointer to a resource pool, and
  -at least two <CODE>char *</CODE> arguments, the last of which must be
  -<CODE>NULL</CODE>.  It allocates enough memory to fit copies of each
  -of the strings, as a unit; for instance:
  -</P>
  -<PRE>
  +</pre>
  +
  +    <p>Note that <em>there is no <code>ap_pfree</code></em> ---
  +    <code>ap_palloc</code>ed memory is freed only when the
  +    associated resource pool is cleared. This means that
  +    <code>ap_palloc</code> does not have to do as much accounting
  +    as <code>malloc()</code>; all it does in the typical case is to
  +    round up the size, bump a pointer, and do a range check.</p>
  +
  +    <p>(It also raises the possibility that heavy use of
  +    <code>ap_palloc</code> could cause a server process to grow
  +    excessively large. There are two ways to deal with this, which
  +    are dealt with below; briefly, you can use <code>malloc</code>,
  +    and try to be sure that all of the memory gets explicitly
  +    <code>free</code>d, or you can allocate a sub-pool of the main
  +    pool, allocate your memory in the sub-pool, and clear it out
  +    periodically. The latter technique is discussed in the section
  +    on sub-pools below, and is used in the directory-indexing code,
  +    in order to avoid excessive storage allocation when listing
  +    directories with thousands of files).</p>
  +
  +    <h3>Allocating initialized memory</h3>
  +
  +    <p>There are functions which allocate initialized memory, and
  +    are frequently useful. The function <code>ap_pcalloc</code> has
  +    the same interface as <code>ap_palloc</code>, but clears out
  +    the memory it allocates before it returns it. The function
  +    <code>ap_pstrdup</code> takes a resource pool and a <code>char
  +    *</code> as arguments, and allocates memory for a copy of the
  +    string the pointer points to, returning a pointer to the copy.
  +    Finally <code>ap_pstrcat</code> is a varargs-style function,
  +    which takes a pointer to a resource pool, and at least two
  +    <code>char *</code> arguments, the last of which must be
  +    <code>NULL</code>. It allocates enough memory to fit copies of
  +    each of the strings, as a unit; for instance:</p>
  +<pre>
        ap_pstrcat (r-&gt;pool, "foo", "/", "bar", NULL);
  -</PRE>
  -<P>
  -returns a pointer to 8 bytes worth of memory, initialized to
  -<CODE>"foo/bar"</CODE>.
  -</P>
  -<H3><A NAME="pools-used">Commonly-used pools in the Apache Web server</A></H3>
  -<P>
  -A pool is really defined by its lifetime more than anything else.  There
  -are some static pools in http_main which are passed to various
  -non-http_main functions as arguments at opportune times.  Here they are:
  -</P>
  -<DL COMPACT>
  - <DT>permanent_pool
  - </DT>
  - <DD>
  -  <UL>
  -   <LI>never passed to anything else, this is the ancestor of all pools
  -   </LI>
  -  </UL>
  - </DD>
  - <DT>pconf
  - </DT>
  - <DD>
  -  <UL>
  -   <LI>subpool of permanent_pool
  -   </LI>
  -   <LI>created at the beginning of a config "cycle"; exists until the
  -    server is terminated or restarts; passed to all config-time
  -    routines, either via cmd-&gt;pool, or as the "pool *p" argument on
  -    those which don't take pools
  -   </LI>
  -   <LI>passed to the module init() functions
  -   </LI>
  -  </UL>
  - </DD>
  - <DT>ptemp
  - </DT>
  - <DD>
  -  <UL>
  -   <LI>sorry I lie, this pool isn't called this currently in 1.3, I
  -    renamed it this in my pthreads development.  I'm referring to
  -    the use of ptrans in the parent... contrast this with the later
  -    definition of ptrans in the child.
  -   </LI>
  -   <LI>subpool of permanent_pool
  -   </LI>
  -   <LI>created at the beginning of a config "cycle"; exists until the
  -    end of config parsing; passed to config-time routines <EM>via</EM>
  -    cmd-&gt;temp_pool.  Somewhat of a "bastard child" because it isn't
  -    available everywhere.  Used for temporary scratch space which
  -    may be needed by some config routines but which is deleted at
  -    the end of config.
  -   </LI>
  -  </UL>
  - </DD>
  - <DT>pchild
  - </DT>
  - <DD>
  -  <UL>
  -   <LI>subpool of permanent_pool
  -   </LI>
  -   <LI>created when a child is spawned (or a thread is created); lives
  -    until that child (thread) is destroyed
  -   </LI>
  -   <LI>passed to the module child_init functions
  -   </LI>
  -   <LI>destruction happens right after the child_exit functions are
  -    called... (which may explain why I think child_exit is redundant
  -    and unneeded)
  -   </LI>
  -  </UL>
  - </DD>
  - <DT>ptrans
  - <DT>
  - <DD>
  -  <UL>
  -   <LI>should be a subpool of pchild, but currently is a subpool of
  -    permanent_pool, see above
  -   </LI>
  -   <LI>cleared by the child before going into the accept() loop to receive
  -    a connection
  -   </LI>
  -   <LI>used as connection-&gt;pool
  -   </LI>
  -  </UL>
  - </DD>
  - <DT>r-&gt;pool
  - </DT>
  - <DD>
  -  <UL>
  -   <LI>for the main request this is a subpool of connection-&gt;pool; for
  -    subrequests it is a subpool of the parent request's pool.
  -   </LI>
  -   <LI>exists until the end of the request (<EM>i.e.</EM>,
  -    ap_destroy_sub_req, or
  -    in child_main after process_request has finished)
  -   </LI>
  -   <LI>note that r itself is allocated from r-&gt;pool; <EM>i.e.</EM>,
  -    r-&gt;pool is
  -    first created and then r is the first thing palloc()d from it
  -   </LI>
  -  </UL>
  - </DD>
  -</DL>
  -<P>
  -For almost everything folks do, r-&gt;pool is the pool to use.  But you
  -can see how other lifetimes, such as pchild, are useful to some
  -modules... such as modules that need to open a database connection once
  -per child, and wish to clean it up when the child dies.
  -</P>
  -<P>
  -You can also see how some bugs have manifested themself, such as setting
  -connection-&gt;user to a value from r-&gt;pool -- in this case
  -connection exists
  -for the lifetime of ptrans, which is longer than r-&gt;pool (especially if
  -r-&gt;pool is a subrequest!).  So the correct thing to do is to allocate
  -from connection-&gt;pool.
  -</P>
  -<P>
  -And there was another interesting bug in mod_include/mod_cgi.  You'll see
  -in those that they do this test to decide if they should use r-&gt;pool
  -or r-&gt;main-&gt;pool.  In this case the resource that they are registering
  -for cleanup is a child process.  If it were registered in r-&gt;pool,
  -then the code would wait() for the child when the subrequest finishes.
  -With mod_include this could be any old #include, and the delay can be up
  -to 3 seconds... and happened quite frequently.  Instead the subprocess
  -is registered in r-&gt;main-&gt;pool which causes it to be cleaned up when
  -the entire request is done -- <EM>i.e.</EM>, after the output has been sent to
  -the client and logging has happened.
  -</P>
  -<H3><A NAME="pool-files">Tracking open files, etc.</A></H3>
  -<P>
  -As indicated above, resource pools are also used to track other sorts
  -of resources besides memory.  The most common are open files.  The
  -routine which is typically used for this is <CODE>ap_pfopen</CODE>, which
  -takes a resource pool and two strings as arguments; the strings are
  -the same as the typical arguments to <CODE>fopen</CODE>, <EM>e.g.</EM>,
  -</P>
  -<PRE>
  +</pre>
  +
  +    <p>returns a pointer to 8 bytes worth of memory, initialized to
  +    <code>"foo/bar"</code>.</p>
  +
  +    <h3><a id="pools-used" name="pools-used">Commonly-used pools in
  +    the Apache Web server</a></h3>
  +
  +    <p>A pool is really defined by its lifetime more than anything
  +    else. There are some static pools in http_main which are passed
  +    to various non-http_main functions as arguments at opportune
  +    times. Here they are:</p>
  +
  +    <dl compact="compact">
  +      <dt>permanent_pool</dt>
  +
  +      <dd>
  +        <ul>
  +          <li>never passed to anything else, this is the ancestor
  +          of all pools</li>
  +        </ul>
  +      </dd>
  +
  +      <dt>pconf</dt>
  +
  +      <dd>
  +        <ul>
  +          <li>subpool of permanent_pool</li>
  +
  +          <li>created at the beginning of a config "cycle"; exists
  +          until the server is terminated or restarts; passed to all
  +          config-time routines, either via cmd-&gt;pool, or as the
  +          "pool *p" argument on those which don't take pools</li>
  +
  +          <li>passed to the module init() functions</li>
  +        </ul>
  +      </dd>
  +
  +      <dt>ptemp</dt>
  +
  +      <dd>
  +        <ul>
  +          <li>sorry I lie, this pool isn't called this currently in
  +          1.3, I renamed it this in my pthreads development. I'm
  +          referring to the use of ptrans in the parent... contrast
  +          this with the later definition of ptrans in the
  +          child.</li>
  +
  +          <li>subpool of permanent_pool</li>
  +
  +          <li>created at the beginning of a config "cycle"; exists
  +          until the end of config parsing; passed to config-time
  +          routines <em>via</em> cmd-&gt;temp_pool. Somewhat of a
  +          "bastard child" because it isn't available everywhere.
  +          Used for temporary scratch space which may be needed by
  +          some config routines but which is deleted at the end of
  +          config.</li>
  +        </ul>
  +      </dd>
  +
  +      <dt>pchild</dt>
  +
  +      <dd>
  +        <ul>
  +          <li>subpool of permanent_pool</li>
  +
  +          <li>created when a child is spawned (or a thread is
  +          created); lives until that child (thread) is
  +          destroyed</li>
  +
  +          <li>passed to the module child_init functions</li>
  +
  +          <li>destruction happens right after the child_exit
  +          functions are called... (which may explain why I think
  +          child_exit is redundant and unneeded)</li>
  +        </ul>
  +      </dd>
  +
  +      <dt>ptrans</dt>
  +
  +      <dd>
  +        <ul>
  +          <li>should be a subpool of pchild, but currently is a
  +          subpool of permanent_pool, see above</li>
  +
  +          <li>cleared by the child before going into the accept()
  +          loop to receive a connection</li>
  +
  +          <li>used as connection-&gt;pool</li>
  +        </ul>
  +      </dd>
  +
  +      <dt>r-&gt;pool</dt>
  +
  +      <dd>
  +        <ul>
  +          <li>for the main request this is a subpool of
  +          connection-&gt;pool; for subrequests it is a subpool of
  +          the parent request's pool.</li>
  +
  +          <li>exists until the end of the request (<em>i.e.</em>,
  +          ap_destroy_sub_req, or in child_main after
  +          process_request has finished)</li>
  +
  +          <li>note that r itself is allocated from r-&gt;pool;
  +          <em>i.e.</em>, r-&gt;pool is first created and then r is
  +          the first thing palloc()d from it</li>
  +        </ul>
  +      </dd>
  +    </dl>
  +
  +    <p>For almost everything folks do, r-&gt;pool is the pool to
  +    use. But you can see how other lifetimes, such as pchild, are
  +    useful to some modules... such as modules that need to open a
  +    database connection once per child, and wish to clean it up
  +    when the child dies.</p>
  +
  +    <p>You can also see how some bugs have manifested themself,
  +    such as setting connection-&gt;user to a value from r-&gt;pool
  +    -- in this case connection exists for the lifetime of ptrans,
  +    which is longer than r-&gt;pool (especially if r-&gt;pool is a
  +    subrequest!). So the correct thing to do is to allocate from
  +    connection-&gt;pool.</p>
  +
  +    <p>And there was another interesting bug in
  +    mod_include/mod_cgi. You'll see in those that they do this test
  +    to decide if they should use r-&gt;pool or r-&gt;main-&gt;pool.
  +    In this case the resource that they are registering for cleanup
  +    is a child process. If it were registered in r-&gt;pool, then
  +    the code would wait() for the child when the subrequest
  +    finishes. With mod_include this could be any old #include, and
  +    the delay can be up to 3 seconds... and happened quite
  +    frequently. Instead the subprocess is registered in
  +    r-&gt;main-&gt;pool which causes it to be cleaned up when the
  +    entire request is done -- <em>i.e.</em>, after the output has
  +    been sent to the client and logging has happened.</p>
  +
  +    <h3><a id="pool-files" name="pool-files">Tracking open files,
  +    etc.</a></h3>
  +
  +    <p>As indicated above, resource pools are also used to track
  +    other sorts of resources besides memory. The most common are
  +    open files. The routine which is typically used for this is
  +    <code>ap_pfopen</code>, which takes a resource pool and two
  +    strings as arguments; the strings are the same as the typical
  +    arguments to <code>fopen</code>, <em>e.g.</em>,</p>
  +<pre>
        ...
        FILE *f = ap_pfopen (r-&gt;pool, r-&gt;filename, "r");
   
        if (f == NULL) { ... } else { ... }
  -</PRE>
  -<P>
  -There is also a <CODE>ap_popenf</CODE> routine, which parallels the
  -lower-level <CODE>open</CODE> system call.  Both of these routines
  -arrange for the file to be closed when the resource pool in question
  -is cleared.
  -</P>
  -<P>
  -Unlike the case for memory, there <EM>are</EM> functions to close
  -files allocated with <CODE>ap_pfopen</CODE>, and <CODE>ap_popenf</CODE>,
  -namely <CODE>ap_pfclose</CODE> and <CODE>ap_pclosef</CODE>.  (This is
  -because, on many systems, the number of files which a single process
  -can have open is quite limited).  It is important to use these
  -functions to close files allocated with <CODE>ap_pfopen</CODE> and
  -<CODE>ap_popenf</CODE>, since to do otherwise could cause fatal errors on
  -systems such as Linux, which react badly if the same
  -<CODE>FILE*</CODE> is closed more than once.
  -</P>
  -<P>
  -(Using the <CODE>close</CODE> functions is not mandatory, since the
  -file will eventually be closed regardless, but you should consider it
  -in cases where your module is opening, or could open, a lot of files).
  -</P>
  -<H3>Other sorts of resources --- cleanup functions</H3>
  -<BLOCKQUOTE>
  -More text goes here.  Describe the the cleanup primitives in terms of
  -which the file stuff is implemented; also, <CODE>spawn_process</CODE>.
  -</BLOCKQUOTE>
  -<P>
  -Pool cleanups live until clear_pool() is called:  clear_pool(a) recursively
  -calls destroy_pool() on all subpools of a; then calls all the cleanups for a; 
  -then releases all the memory for a.  destroy_pool(a) calls clear_pool(a) 
  -and then releases the pool structure itself.  <EM>i.e.</EM>, clear_pool(a) doesn't
  -delete a, it just frees up all the resources and you can start using it
  -again immediately. 
  -</P>
  -<H3>Fine control --- creating and dealing with sub-pools, with a note
  -on sub-requests</H3>
  -
  -On rare occasions, too-free use of <CODE>ap_palloc()</CODE> and the
  -associated primitives may result in undesirably profligate resource
  -allocation.  You can deal with such a case by creating a
  -<EM>sub-pool</EM>, allocating within the sub-pool rather than the main
  -pool, and clearing or destroying the sub-pool, which releases the
  -resources which were associated with it.  (This really <EM>is</EM> a
  -rare situation; the only case in which it comes up in the standard
  -module set is in case of listing directories, and then only with
  -<EM>very</EM> large directories.  Unnecessary use of the primitives
  -discussed here can hair up your code quite a bit, with very little
  -gain). <P>
  -
  -The primitive for creating a sub-pool is <CODE>ap_make_sub_pool</CODE>,
  -which takes another pool (the parent pool) as an argument.  When the
  -main pool is cleared, the sub-pool will be destroyed.  The sub-pool
  -may also be cleared or destroyed at any time, by calling the functions
  -<CODE>ap_clear_pool</CODE> and <CODE>ap_destroy_pool</CODE>, respectively.
  -(The difference is that <CODE>ap_clear_pool</CODE> frees resources
  -associated with the pool, while <CODE>ap_destroy_pool</CODE> also
  -deallocates the pool itself.  In the former case, you can allocate new
  -resources within the pool, and clear it again, and so forth; in the
  -latter case, it is simply gone). <P>
  -
  -One final note --- sub-requests have their own resource pools, which
  -are sub-pools of the resource pool for the main request.  The polite
  -way to reclaim the resources associated with a sub request which you
  -have allocated (using the <CODE>ap_sub_req_...</CODE> functions)
  -is <CODE>ap_destroy_sub_req</CODE>, which frees the resource pool.
  -Before calling this function, be sure to copy anything that you care
  -about which might be allocated in the sub-request's resource pool into
  -someplace a little less volatile (for instance, the filename in its
  -<CODE>request_rec</CODE> structure). <P>
  -
  -(Again, under most circumstances, you shouldn't feel obliged to call
  -this function; only 2K of memory or so are allocated for a typical sub
  -request, and it will be freed anyway when the main request pool is
  -cleared.  It is only when you are allocating many, many sub-requests
  -for a single main request that you should seriously consider the
  -<CODE>ap_destroy_...</CODE> functions).
  -
  -<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>
   
  -<PRE>
  +    <p>There is also a <code>ap_popenf</code> routine, which
  +    parallels the lower-level <code>open</code> system call. Both
  +    of these routines arrange for the file to be closed when the
  +    resource pool in question is cleared.</p>
  +
  +    <p>Unlike the case for memory, there <em>are</em> functions to
  +    close files allocated with <code>ap_pfopen</code>, and
  +    <code>ap_popenf</code>, namely <code>ap_pfclose</code> and
  +    <code>ap_pclosef</code>. (This is because, on many systems, the
  +    number of files which a single process can have open is quite
  +    limited). It is important to use these functions to close files
  +    allocated with <code>ap_pfopen</code> and
  +    <code>ap_popenf</code>, since to do otherwise could cause fatal
  +    errors on systems such as Linux, which react badly if the same
  +    <code>FILE*</code> is closed more than once.</p>
  +
  +    <p>(Using the <code>close</code> functions is not mandatory,
  +    since the file will eventually be closed regardless, but you
  +    should consider it in cases where your module is opening, or
  +    could open, a lot of files).</p>
  +
  +    <h3>Other sorts of resources --- cleanup functions</h3>
  +
  +    <blockquote>
  +      More text goes here. Describe the the cleanup primitives in
  +      terms of which the file stuff is implemented; also,
  +      <code>spawn_process</code>.
  +    </blockquote>
  +
  +    <p>Pool cleanups live until clear_pool() is called:
  +    clear_pool(a) recursively calls destroy_pool() on all subpools
  +    of a; then calls all the cleanups for a; then releases all the
  +    memory for a. destroy_pool(a) calls clear_pool(a) and then
  +    releases the pool structure itself. <em>i.e.</em>,
  +    clear_pool(a) doesn't delete a, it just frees up all the
  +    resources and you can start using it again immediately.</p>
  +
  +    <h3>Fine control --- creating and dealing with sub-pools, with
  +    a note on sub-requests</h3>
  +    On rare occasions, too-free use of <code>ap_palloc()</code> and
  +    the associated primitives may result in undesirably profligate
  +    resource allocation. You can deal with such a case by creating
  +    a <em>sub-pool</em>, allocating within the sub-pool rather than
  +    the main pool, and clearing or destroying the sub-pool, which
  +    releases the resources which were associated with it. (This
  +    really <em>is</em> a rare situation; the only case in which it
  +    comes up in the standard module set is in case of listing
  +    directories, and then only with <em>very</em> large
  +    directories. Unnecessary use of the primitives discussed here
  +    can hair up your code quite a bit, with very little gain). 
  +
  +    <p>The primitive for creating a sub-pool is
  +    <code>ap_make_sub_pool</code>, which takes another pool (the
  +    parent pool) as an argument. When the main pool is cleared, the
  +    sub-pool will be destroyed. The sub-pool may also be cleared or
  +    destroyed at any time, by calling the functions
  +    <code>ap_clear_pool</code> and <code>ap_destroy_pool</code>,
  +    respectively. (The difference is that
  +    <code>ap_clear_pool</code> frees resources associated with the
  +    pool, while <code>ap_destroy_pool</code> also deallocates the
  +    pool itself. In the former case, you can allocate new resources
  +    within the pool, and clear it again, and so forth; in the
  +    latter case, it is simply gone).</p>
  +
  +    <p>One final note --- sub-requests have their own resource
  +    pools, which are sub-pools of the resource pool for the main
  +    request. The polite way to reclaim the resources associated
  +    with a sub request which you have allocated (using the
  +    <code>ap_sub_req_...</code> functions) is
  +    <code>ap_destroy_sub_req</code>, which frees the resource pool.
  +    Before calling this function, be sure to copy anything that you
  +    care about which might be allocated in the sub-request's
  +    resource pool into someplace a little less volatile (for
  +    instance, the filename in its <code>request_rec</code>
  +    structure).</p>
  +
  +    <p>(Again, under most circumstances, you shouldn't feel obliged
  +    to call this function; only 2K of memory or so are allocated
  +    for a typical sub request, and it will be freed anyway when the
  +    main request pool is cleared. It is only when you are
  +    allocating many, many sub-requests for a single main request
  +    that you should seriously consider the
  +    <code>ap_destroy_...</code> functions).</p>
  +
  +    <h2><a id="config" 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>
  +
  +    <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>
  +
  +    <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 id="per-dir" 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>ap_palloc</CODE>s the structure above, and a creates a couple of
  -<CODE>table</CODE>s to fill it.  That looks like this:
  -
  -<PRE>
  +</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>
  +
  +    <p>For the MIME module, the per-dir config creation function
  +    just <code>ap_palloc</code>s the structure above, and a creates
  +    a couple of <code>table</code>s to fill it. That looks like
  +    this:</p>
  +<pre>
   void *create_mime_dir_config (pool *p, char *dummy)
   {
       mime_dir_config *new =
  @@ -934,24 +1014,24 @@
   
       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>
  +</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:</p>
  +<pre>
   void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
   {
       mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
  @@ -966,118 +1046,121 @@
   
       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 (<EM>e.g.</EM>, 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 pre-parsed 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>
  +</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 (<em>e.g.</em>, 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>. 
  +
  +    <h3><a id="commands" 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
  +    pre-parsed 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;
       ap_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 pre-parsed 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>
  +</pre>
  +    This command handler is unusually simple. As you can see, it
  +    takes four arguments, two of which are pre-parsed 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>
  +
  +    <p>The MIME module's command table has entries for these
  +    commands, which look like this:</p>
  +<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 (<EM>e.g.</EM>, gzip), followed by a file extension" },
  +    "an encoding (<em>e.g.</em>, gzip), followed by a file extension" },
   { NULL }
   };
  -</PRE>
  +</pre>
  +    The entries in these tables are: 
   
  -The entries in these tables are:
  +    <ul>
  +      <li>The name of the command</li>
   
  -<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
  -       pre-parsed, and how they should be passed in.
  -       <CODE>TAKE2</CODE> indicates two pre-parsed arguments.  Other
  -       options are <CODE>TAKE1</CODE>, which indicates one pre-parsed
  -       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>ap_get_module_config</CODE> function.
  +      <li>The function which handles it</li>
   
  -<PRE>
  +      <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>
  +
  +      <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>
  +
  +      <li>A flag indicating how many arguments the command handler
  +      wants pre-parsed, and how they should be passed in.
  +      <code>TAKE2</code> indicates two pre-parsed arguments. Other
  +      options are <code>TAKE1</code>, which indicates one
  +      pre-parsed 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>
  +
  +      <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>).</li>
  +    </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>ap_get_module_config</code> function.
  +    
  +<pre>
   int find_ct(request_rec *r)
   {
       int i;
  @@ -1112,30 +1195,30 @@
   
       return OK;
   }
  -
  -</PRE>
   
  -<H3><A NAME="servconf">Side notes --- per-server configuration, virtual
  - servers, <EM>etc</EM>.</A></H3>
  +</pre>
   
  -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 overridden 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>
  +    <h3><a id="servconf" name="servconf">Side notes --- per-server
  +    configuration, virtual servers, <em>etc</em>.</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 overridden
  +    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):</p>
  +<pre>
   char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
   {
       server_rec *s = cmd-&gt;server;
  @@ -1148,6 +1231,8 @@
       new-&gt;fake = f; new-&gt;real = url;
       return NULL;
   }
  -</PRE>
  -<!--#include virtual="footer.html" -->
  -</BODY></HTML>
  +</pre>
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
  +
  
  
  
  1.9       +385 -331  httpd-docs-1.3/htdocs/manual/misc/FAQ-A.html
  
  Index: FAQ-A.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/FAQ-A.html,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- FAQ-A.html	2001/08/28 22:45:31	1.8
  +++ FAQ-A.html	2001/10/08 01:26:54	1.9
  @@ -1,338 +1,392 @@
   <!--#if expr="$FAQMASTER" -->
  - <!--#set var="STANDALONE" value="" -->
  - <!--#set var="INCLUDED" value="YES" -->
  - <!--#if expr="$QUERY_STRING = TOC" -->
  -  <!--#set var="TOC" value="YES" -->
  -  <!--#set var="CONTENT" value="" -->
  - <!--#else -->
  -  <!--#set var="TOC" value="" -->
  -  <!--#set var="CONTENT" value="YES" -->
  - <!--#endif -->
  +<!--#set var="STANDALONE" value="" -->
  +<!--#set var="INCLUDED" value="YES" -->
  +<!--#if expr="$QUERY_STRING = TOC" -->
  +<!--#set var="TOC" value="YES" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#else -->
  - <!--#set var="STANDALONE" value="YES" -->
  - <!--#set var="INCLUDED" value="" -->
  - <!--#set var="TOC" value="" -->
  - <!--#set var="CONTENT" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="YES" -->
   <!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  - <HEAD>
  -  <TITLE>Apache Server Frequently Asked Questions</TITLE>
  - </HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  - <BODY
  -  BGCOLOR="#FFFFFF"
  -  TEXT="#000000"
  -  LINK="#0000FF"
  -  VLINK="#000080"
  -  ALINK="#FF0000"
  - >
  -  <!--#include virtual="header.html" -->
  -  <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>
  -  <P>
  -  $Revision: 1.8 $ ($Date: 2001/08/28 22:45:31 $)
  -  </P>
  -  <P>
  -  The latest version of this FAQ is always available from the main
  -  Apache web site, at
  -  &lt;<A
  -       HREF="http://httpd.apache.org/docs/misc/FAQ.html"
  -       REL="Help"
  -      ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>&gt;.
  -  </P>
  -<!-- Notes about changes:                                           -->
  -<!--  - If adding a relative link to another part of the            -->
  -<!--    documentation, *do* include the ".html" portion.  There's a -->
  -<!--    good chance that the user will be reading the documentation -->
  -<!--    on his own system, which may not be configured for          -->
  -<!--    multiviews.                                                 -->
  -<!--  - When adding items, make sure they're put in the right place -->
  -<!--    - verify that the numbering matches up.                     -->
  -<!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  -<!--    correctly in a reliable way when this is converted to text  -->
  -<!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  -<!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  -<!--    the horizontal and vertical indenting right.                -->
  -<!--  - Don't forget to include an HR tag after the last /P tag     -->
  -<!--    but before the /LI in an item.                              -->
  -  <P>
  -  If you are reading a text-only version of this FAQ, you may find numbers
  -  enclosed in brackets (such as &quot;[12]&quot;).  These refer to the list of
  -  reference URLs to be found at the end of the document.  These references
  -  do not appear, and are not needed, for the hypertext version.
  -  </P>
  -  <H2>The Questions</H2>
  -<OL TYPE="A">
  -<!--#endif -->
  -<!--#if expr="$TOC || $STANDALONE" -->
  - <LI VALUE="1"><STRONG>Background</STRONG>
  -  <OL>
  -   <LI><A HREF="#what">What is Apache?</A>
  -   </LI>
  -   <LI><A HREF="#why">How and why was Apache created?</A>
  -   </LI>
  -   <LI><A HREF="#name">Why the name &quot;Apache&quot;?</A>
  -   </LI>
  -   <LI><A HREF="#compare">OK, so how does Apache compare to other servers?</A>
  -   </LI>
  -   <LI><A HREF="#tested">How thoroughly tested is Apache?</A>
  -   </LI>
  -   <LI><A HREF="#future">What are the future plans for Apache?</A>
  -   </LI>
  -   <LI><A HREF="#support">Whom do I contact for support?</A>
  -   </LI>
  -   <LI><A HREF="#more">Is there any more information on Apache?</A>
  -   </LI>
  -   <LI><A HREF="#where">Where can I get Apache?</A>
  -   </LI>
  -   <li><a href="#logo">May I use the Apache logo on my product or Web site?</a>
  -   </li>
  -  </OL>
  - </LI>
  +<!--#else -->
  +<!--#set var="STANDALONE" value="YES" -->
  +<!--#set var="INCLUDED" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#endif -->
   <!--#if expr="$STANDALONE" -->
  -</OL>
  -
  -<HR>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -  <H2>The Answers</H2>
  -<!--#endif -->
  -<!--#if expr="! $TOC" -->
  -  <H3>A. Background</H3>
  -<OL>
  - <LI><A NAME="what">
  -      <STRONG>What is Apache?</STRONG>
  -     </A>
  -  <p>The Apache httpd server</p>
  -
  -<UL>
  - <LI>is a powerful, flexible, HTTP/1.1 compliant web server
  - <LI>implements the latest protocols, including HTTP/1.1 (RFC2616)
  - <LI>is highly configurable and extensible with third-party modules
  - <LI>can be customised by writing 'modules' using the Apache module API
  - <LI>provides full source code and comes with an unrestrictive license
  - <LI>runs on Windows NT/9x, Netware 5.x, OS/2, and most versions of Unix, 
  -     as well as several other operating systems
  - <LI>is actively being developed
  - <LI>encourages user feedback through new ideas, bug reports and patches
  - <LI>implements many frequently requested features, including:<BR><BR>
  -  <DL>
  -    <DT>DBM databases for authentication</DT>
  -    <DD>allows you to easily set up password-protected pages with 
  -    enormous numbers of authorized users, without bogging down the server.
  -    <DT>Customized responses to errors and problems</DT>
  -     <DD>Allows you to set up files, or even CGI scripts, which are
  -      returned by the server in response
  -      to errors and problems, e.g. setup a script to intercept
  -      <STRONG>500 Server Error</STRONG>s and perform on-the-fly diagnostics for
  -      both users and yourself. </DD>
  -    <DT> Multiple DirectoryIndex directives </DT>
  -    <DD> Allows you to say <CODE>DirectoryIndex index.html
  -         index.cgi</CODE>, which instructs the server to either send
  -         back <CODE>index.html</CODE> or run <CODE>index.cgi</CODE>
  -         when a directory URL is requested, whichever it finds in the
  -          directory.
  -    <DT> Unlimited flexible URL rewriting and aliasing </DT>
  -    <DD> Apache has no fixed limit on the numbers of Aliases and
  -         Redirects which may be declared in the config files.  In addition,
  -	 a powerful rewriting engine can be used to solve most URL
  -         manipulation problems.
  -    <DT>Content negotiation</DT>
  -    <DD>i.e. the ability to automatically serve clients of varying
  -     sophistication and HTML level compliance, with documents which
  -     offer the best representation of information that the client is
  -     capable of accepting.</DD>
  -    <DT>Virtual Hosts</DT>
  -     <DD>A much requested feature, sometimes known as multi-homed servers.
  -      This allows the server to distinguish between requests made to
  -      different IP addresses or names (mapped to the same machine).  Apache
  -      also offers dynamically configurable mass-virtual hosting.
  -     </DD>
  -    <DT>Configurable Reliable Piped Logs</DT> 
  -     <DD>You can configure
  -     Apache to generate logs in the format that you want.  In addition, on
  -     most Unix architectures, Apache can send log files to a pipe, allowing
  -     for log rotation, hit filtering, real-time splitting of multiple vhosts
  -     into separate logs, and asynchronous DNS resolving on the fly.
  -  </DL>
  -</UL>
  -
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="why">
  -      <STRONG>How and why was Apache created?</STRONG>
  -     </A>
  -  <P>
  -  The <A HREF="http://httpd.apache.org/ABOUT_APACHE.html">About Apache</A>
  -  document explains how the Apache project evolved from its beginnings
  -  as an outgrowth of the NCSA httpd project to its current status as
  -  one of the fastest, most efficient, and most functional web servers
  -  in existence.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="name">
  -      <STRONG>Why the name &quot;Apache&quot;?</STRONG>
  -      </A>
  -  <P>
  -  A cute name which stuck. Apache is &quot;<STRONG>A
  -  PA</STRONG>t<STRONG>CH</STRONG>y server&quot;.  It was
  -  based on some existing code and a series of &quot;patch files&quot;.
  -  </P>
  -
  -  <P>
  -  For many developers it is also a reverent connotation to the Native
  -  American Indian tribe of Apache, <A
  -  HREF="http://www.indians.org/welker/apache.htm">well-known for their
  -  superior skills in warfare strategy and inexhaustible endurance</A>.
  -  For more information on the Apache Nation, we 
  -  suggest searching 
  -  <A HREF="http://www.google.com/search?q=Apache+Nation">Google</A>, 
  -  <A HREF="http://www.northernlight.com/nlquery.fcg?qr=Apache+Nation">Northernlight</A>, or 
  -  <A HREF="http://www.alltheweb.com/cgi-bin/asearch?query=Apache+Nation">AllTheWeb</A>.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="compare">
  -      <STRONG>OK, so how does Apache compare to other servers?</STRONG>
  -     </A>
  -  <P>
  -  For an independent assessment, see
  -  <A HREF="http://webcompare.internet.com/chart.html">Web Compare</A>'s
  -  comparison chart.
  -  </P>
  -  <P>
  -  Apache has been shown to be substantially faster, more stable, and
  -  more feature-full than many other web servers. Although certain
  -  commercial servers have claimed to surpass Apache's speed (it has
  -  not been demonstrated that any of these &quot;benchmarks&quot; are a
  -  good way of measuring WWW server speed at any rate), we feel that it
  -  is better to have a mostly-fast free server than an extremely-fast
  -  server that costs thousands of dollars. Apache is run on sites that
  -  get millions of hits per day, and they have experienced no
  -  performance difficulties.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="tested">
  -      <STRONG>How thoroughly tested is Apache?</STRONG>
  -     </A>
  -  <P>
  -  Apache is run on over 6 million Internet servers (as of February
  -  2000).  It has been tested thoroughly by both developers and
  -  users. The Apache Group maintains rigorous standards before
  -  releasing new versions of their server, and our server runs without
  -  a hitch on over one half of all WWW servers available on the
  -  Internet.  When bugs do show up, we release patches and new versions
  -  as soon as they are available.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="future">
  -      <STRONG>What are the future plans for Apache?</STRONG>
  -     </A>
  -  <P>
  -  <UL>
  -   <LI>to continue to be an "open source" no-charge-for-use HTTP server,
  -   </LI>
  -   <LI>to keep up with advances in HTTP protocol and web developments in
  -    general,
  -   </LI>
  -   <LI>to collect suggestions for fixes/improvements from its users,
  -   </LI>
  -   <LI>to respond to needs of large volume providers as well as
  -    occasional users.
  -   </LI>
  -  </UL>
  -  <P></P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="support">
  -      <STRONG>Whom do I contact for support?</STRONG>
  -     </A>
  -  <P>
  -  There is no official support for Apache. None of the developers want to
  -  be swamped by a flood of trivial questions that can be resolved elsewhere.
  -  Bug reports and suggestions should be sent <EM>via</EM>
  -  <A HREF="http://httpd.apache.org/bug_report.html">the bug report page</A>.
  -  Other questions should be directed to the
  -  <A HREF="news:comp.infosystems.www.servers.unix"
  -  >comp.infosystems.www.servers.unix</A> or <A HREF=
  -  "news:comp.infosystems.www.servers.ms-windows"
  -  >comp.infosystems.www.servers.ms-windows</A>
  -  newsgroup (as appropriate for the platform you use), where some of the 
  -  Apache team lurk, in the company of many other httpd gurus who 
  -  should be able to help.
  -  </P>
  -  <P>
  -  Commercial support for Apache is, however, available from a number
  -  of third parties.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="more">
  -      <STRONG>Is there any more information available on
  -      Apache?</STRONG>
  -     </A>
  -  <P>
  -  Indeed there is.  See the main
  -  <A HREF="http://httpd.apache.org/">Apache web site</A>.
  -  There is also a regular electronic publication called
  -  <A HREF="http://www.apacheweek.com/" REL="Help"><CITE>Apache Week</CITE></A>
  -  available.  Links to relevant <CITE>Apache Week</CITE> articles are
  -  included below where appropriate. There are also some 
  -  <A HREF="http://httpd.apache.org/info/apache_books.html"
  -  >Apache-specific books</A> available.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="where">
  -      <STRONG>Where can I get Apache?</STRONG>
  -     </A>
  -  <P>
  -  You can find out how to download the source for Apache at the
  -  project's
  -  <A HREF="http://httpd.apache.org/">main web page</A>.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <li><a name="logo">
  -      <b>May I use the Apache logo on my product or Web site?</b></a>
  -  <p>
  -  You may <b>NOT</b> use any original artwork from the Apache Software
  -  Foundation, nor make or use modified versions of such artwork, except
  -  under the following conditions:
  -  </p>
  -  <ul>
  -   <li>You may use the
  -    <a href="../../apache_pb.gif">'Powered by Apache' graphic</a>
  -    on a Web site that is being served by the Apache HTTP server software.</li>
  -   <li>You may use the aforementioned 'Powered by Apache' graphic or the
  -    <a href="http://www.apache.org/foundation/images/asf_logo.gif"
  -    >Apache Software Foundation logo</a> in product description and
  -    promotional material <b>IF and ONLY IF</b> such use can in no way
  -    be interpreted as anything other than an attribution.  Using the
  -    Apache name and artwork in a manner that implies endorsement of a
  -    product or service is <b>strictly forbidden</b>.</li>
  -  </ul>
  -  <hr>
  - </li>
  -</OL>
  -<!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -  <!-- Don't forget to add HR tags at the end of each list item.. -->
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Server Frequently Asked Questions</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache Server Frequently Asked
  +    Questions</h1>
  +
  +    <p>$Revision: 1.9 $ ($Date: 2001/10/08 01:26:54 $)</p>
  +
  +    <p>The latest version of this FAQ is always available from the
  +    main Apache web site, at &lt;<a
  +    href="http://httpd.apache.org/docs/misc/FAQ.html"
  +    rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>&gt;.</p>
  +    <!-- Notes about changes:                                           -->
  +    <!--  - If adding a relative link to another part of the            -->
  +    <!--    documentation, *do* include the ".html" portion.  There's a -->
  +    <!--    good chance that the user will be reading the documentation -->
  +    <!--    on his own system, which may not be configured for          -->
  +    <!--    multiviews.                                                 -->
  +    <!--  - When adding items, make sure they're put in the right place -->
  +    <!--    - verify that the numbering matches up.                     -->
  +    <!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  +    <!--    correctly in a reliable way when this is converted to text  -->
  +    <!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  +    <!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  +    <!--    the horizontal and vertical indenting right.                -->
  +    <!--  - Don't forget to include an HR tag after the last /P tag     -->
  +    <!--    but before the /LI in an item.                              -->
  +
  +    <p>If you are reading a text-only version of this FAQ, you may
  +    find numbers enclosed in brackets (such as "[12]"). These refer
  +    to the list of reference URLs to be found at the end of the
  +    document. These references do not appear, and are not needed,
  +    for the hypertext version.</p>
  +
  +    <h2>The Questions</h2>
  +
  +    <ol type="A">
  +      <!--#endif -->
  +      <!--#if expr="$TOC || $STANDALONE" -->
  +
  +      <li value="1">
  +        <strong>Background</strong> 
  +
  +        <ol>
  +          <li><a href="#what">What is Apache?</a></li>
  +
  +          <li><a href="#why">How and why was Apache
  +          created?</a></li>
  +
  +          <li><a href="#name">Why the name "Apache"?</a></li>
  +
  +          <li><a href="#compare">OK, so how does Apache compare to
  +          other servers?</a></li>
  +
  +          <li><a href="#tested">How thoroughly tested is
  +          Apache?</a></li>
  +
  +          <li><a href="#future">What are the future plans for
  +          Apache?</a></li>
  +
  +          <li><a href="#support">Whom do I contact for
  +          support?</a></li>
  +
  +          <li><a href="#more">Is there any more information on
  +          Apache?</a></li>
  +
  +          <li><a href="#where">Where can I get Apache?</a></li>
  +
  +          <li><a href="#logo">May I use the Apache logo on my
  +          product or Web site?</a></li>
  +        </ol>
  +      </li>
  +      <!--#endif -->
  +      <!--#if expr="$STANDALONE" -->
  +    </ol>
  +    <hr />
  +
  +    <h2>The Answers</h2>
  +    <!--#endif -->
  +    <!--#if expr="! $TOC" -->
  +
  +    <h3>A. Background</h3>
  +
  +    <ol>
  +      <li>
  +        <a id="what" name="what"><strong>What is
  +        Apache?</strong></a> 
  +
  +        <p>The Apache httpd server</p>
  +
  +        <ul>
  +          <li>is a powerful, flexible, HTTP/1.1 compliant web
  +          server</li>
  +
  +          <li>implements the latest protocols, including HTTP/1.1
  +          (RFC2616)</li>
  +
  +          <li>is highly configurable and extensible with
  +          third-party modules</li>
  +
  +          <li>can be customised by writing 'modules' using the
  +          Apache module API</li>
  +
  +          <li>provides full source code and comes with an
  +          unrestrictive license</li>
  +
  +          <li>runs on Windows NT/9x, Netware 5.x, OS/2, and most
  +          versions of Unix, as well as several other operating
  +          systems</li>
  +
  +          <li>is actively being developed</li>
  +
  +          <li>encourages user feedback through new ideas, bug
  +          reports and patches</li>
  +
  +          <li>
  +            implements many frequently requested features,
  +            including:<br />
  +            <br />
  +             
  +
  +            <dl>
  +              <dt>DBM databases for authentication</dt>
  +
  +              <dd>allows you to easily set up password-protected
  +              pages with enormous numbers of authorized users,
  +              without bogging down the server.</dd>
  +
  +              <dt>Customized responses to errors and problems</dt>
  +
  +              <dd>Allows you to set up files, or even CGI scripts,
  +              which are returned by the server in response to
  +              errors and problems, e.g. setup a script to intercept
  +              <strong>500 Server Error</strong>s and perform
  +              on-the-fly diagnostics for both users and
  +              yourself.</dd>
  +
  +              <dt>Multiple DirectoryIndex directives</dt>
  +
  +              <dd>Allows you to say <code>DirectoryIndex index.html
  +              index.cgi</code>, which instructs the server to
  +              either send back <code>index.html</code> or run
  +              <code>index.cgi</code> when a directory URL is
  +              requested, whichever it finds in the directory.</dd>
  +
  +              <dt>Unlimited flexible URL rewriting and
  +              aliasing</dt>
  +
  +              <dd>Apache has no fixed limit on the numbers of
  +              Aliases and Redirects which may be declared in the
  +              config files. In addition, a powerful rewriting
  +              engine can be used to solve most URL manipulation
  +              problems.</dd>
  +
  +              <dt>Content negotiation</dt>
  +
  +              <dd>i.e. the ability to automatically serve clients
  +              of varying sophistication and HTML level compliance,
  +              with documents which offer the best representation of
  +              information that the client is capable of
  +              accepting.</dd>
  +
  +              <dt>Virtual Hosts</dt>
  +
  +              <dd>A much requested feature, sometimes known as
  +              multi-homed servers. This allows the server to
  +              distinguish between requests made to different IP
  +              addresses or names (mapped to the same machine).
  +              Apache also offers dynamically configurable
  +              mass-virtual hosting.</dd>
  +
  +              <dt>Configurable Reliable Piped Logs</dt>
  +
  +              <dd>You can configure Apache to generate logs in the
  +              format that you want. In addition, on most Unix
  +              architectures, Apache can send log files to a pipe,
  +              allowing for log rotation, hit filtering, real-time
  +              splitting of multiple vhosts into separate logs, and
  +              asynchronous DNS resolving on the fly.</dd>
  +            </dl>
  +          </li>
  +        </ul>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="why" name="why"><strong>How and why was Apache
  +        created?</strong></a> 
  +
  +        <p>The <a
  +        href="http://httpd.apache.org/ABOUT_APACHE.html">About
  +        Apache</a> document explains how the Apache project evolved
  +        from its beginnings as an outgrowth of the NCSA httpd
  +        project to its current status as one of the fastest, most
  +        efficient, and most functional web servers in
  +        existence.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="name" name="name"><strong>Why the name
  +        "Apache"?</strong></a> 
  +
  +        <p>A cute name which stuck. Apache is "<strong>A
  +        PA</strong>t<strong>CH</strong>y server". It was based on
  +        some existing code and a series of "patch files".</p>
  +
  +        <p>For many developers it is also a reverent connotation to
  +        the Native American Indian tribe of Apache, <a
  +        href="http://www.indians.org/welker/apache.htm">well-known
  +        for their superior skills in warfare strategy and
  +        inexhaustible endurance</a>. For more information on the
  +        Apache Nation, we suggest searching <a
  +        href="http://www.google.com/search?q=Apache+Nation">Google</a>,
  +        <a
  +        href="http://www.northernlight.com/nlquery.fcg?qr=Apache+Nation">
  +        Northernlight</a>, or <a
  +        href="http://www.alltheweb.com/cgi-bin/asearch?query=Apache+Nation">
  +        AllTheWeb</a>.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="compare" name="compare"><strong>OK, so how does
  +        Apache compare to other servers?</strong></a> 
  +
  +        <p>For an independent assessment, see <a
  +        href="http://webcompare.internet.com/chart.html">Web
  +        Compare</a>'s comparison chart.</p>
  +
  +        <p>Apache has been shown to be substantially faster, more
  +        stable, and more feature-full than many other web servers.
  +        Although certain commercial servers have claimed to surpass
  +        Apache's speed (it has not been demonstrated that any of
  +        these "benchmarks" are a good way of measuring WWW server
  +        speed at any rate), we feel that it is better to have a
  +        mostly-fast free server than an extremely-fast server that
  +        costs thousands of dollars. Apache is run on sites that get
  +        millions of hits per day, and they have experienced no
  +        performance difficulties.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="tested" name="tested"><strong>How thoroughly tested
  +        is Apache?</strong></a> 
  +
  +        <p>Apache is run on over 6 million Internet servers (as of
  +        February 2000). It has been tested thoroughly by both
  +        developers and users. The Apache Group maintains rigorous
  +        standards before releasing new versions of their server,
  +        and our server runs without a hitch on over one half of all
  +        WWW servers available on the Internet. When bugs do show
  +        up, we release patches and new versions as soon as they are
  +        available.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="future" name="future"><strong>What are the future
  +        plans for Apache?</strong></a> 
  +
  +        <ul>
  +          <li>to continue to be an "open source" no-charge-for-use
  +          HTTP server,</li>
  +
  +          <li>to keep up with advances in HTTP protocol and web
  +          developments in general,</li>
  +
  +          <li>to collect suggestions for fixes/improvements from
  +          its users,</li>
  +
  +          <li>to respond to needs of large volume providers as well
  +          as occasional users.</li>
  +        </ul>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="support" name="support"><strong>Whom do I contact
  +        for support?</strong></a> 
  +
  +        <p>There is no official support for Apache. None of the
  +        developers want to be swamped by a flood of trivial
  +        questions that can be resolved elsewhere. Bug reports and
  +        suggestions should be sent <em>via</em> <a
  +        href="http://httpd.apache.org/bug_report.html">the bug
  +        report page</a>. Other questions should be directed to the
  +        <a
  +        href="news:comp.infosystems.www.servers.unix">comp.infosystems.www.servers.unix</a>
  +        or <a
  +        href="news:comp.infosystems.www.servers.ms-windows">comp.infosystems.www.servers.ms-windows</a>
  +        newsgroup (as appropriate for the platform you use), where
  +        some of the Apache team lurk, in the company of many other
  +        httpd gurus who should be able to help.</p>
  +
  +        <p>Commercial support for Apache is, however, available
  +        from a number of third parties.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="more" name="more"><strong>Is there any more
  +        information available on Apache?</strong></a> 
  +
  +        <p>Indeed there is. See the main <a
  +        href="http://httpd.apache.org/">Apache web site</a>. There
  +        is also a regular electronic publication called <a
  +        href="http://www.apacheweek.com/" rel="Help"><cite>Apache
  +        Week</cite></a> available. Links to relevant <cite>Apache
  +        Week</cite> articles are included below where appropriate.
  +        There are also some <a
  +        href="http://httpd.apache.org/info/apache_books.html">Apache-specific
  +        books</a> available.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="where" name="where"><strong>Where can I get
  +        Apache?</strong></a> 
  +
  +        <p>You can find out how to download the source for Apache
  +        at the project's <a href="http://httpd.apache.org/">main
  +        web page</a>.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="logo" name="logo"><b>May I use the Apache logo on my
  +        product or Web site?</b></a> 
  +
  +        <p>You may <b>NOT</b> use any original artwork from the
  +        Apache Software Foundation, nor make or use modified
  +        versions of such artwork, except under the following
  +        conditions:</p>
  +
  +        <ul>
  +          <li>You may use the <a
  +          href="../../apache_pb.gif">'Powered by Apache'
  +          graphic</a> on a Web site that is being served by the
  +          Apache HTTP server software.</li>
  +
  +          <li>You may use the aforementioned 'Powered by Apache'
  +          graphic or the <a
  +          href="http://www.apache.org/foundation/images/asf_logo.gif">
  +          Apache Software Foundation logo</a> in product
  +          description and promotional material <b>IF and ONLY
  +          IF</b> such use can in no way be interpreted as anything
  +          other than an attribution. Using the Apache name and
  +          artwork in a manner that implies endorsement of a product
  +          or service is <b>strictly forbidden</b>.</li>
  +        </ul>
  +        <hr />
  +      </li>
  +    </ol>
  +    <!--#endif -->
  +    <!--#if expr="$STANDALONE" -->
  +    <!-- Don't forget to add HR tags at the end of each list item.. -->
  +    <!--#include virtual="footer.html" -->
  +    <!--#endif -->
  +  </body>
  +</html>
   
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  -<!--#endif -->
  
  
  
  1.11      +448 -429  httpd-docs-1.3/htdocs/manual/misc/FAQ-B.html
  
  Index: FAQ-B.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/FAQ-B.html,v
  retrieving revision 1.10
  retrieving revision 1.11
  diff -u -r1.10 -r1.11
  --- FAQ-B.html	2001/08/22 18:20:25	1.10
  +++ FAQ-B.html	2001/10/08 01:26:54	1.11
  @@ -1,276 +1,293 @@
   <!--#if expr="$FAQMASTER" -->
  - <!--#set var="STANDALONE" value="" -->
  - <!--#set var="INCLUDED" value="YES" -->
  - <!--#if expr="$QUERY_STRING = TOC" -->
  -  <!--#set var="TOC" value="YES" -->
  -  <!--#set var="CONTENT" value="" -->
  - <!--#else -->
  -  <!--#set var="TOC" value="" -->
  -  <!--#set var="CONTENT" value="YES" -->
  - <!--#endif -->
  +<!--#set var="STANDALONE" value="" -->
  +<!--#set var="INCLUDED" value="YES" -->
  +<!--#if expr="$QUERY_STRING = TOC" -->
  +<!--#set var="TOC" value="YES" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#else -->
  - <!--#set var="STANDALONE" value="YES" -->
  - <!--#set var="INCLUDED" value="" -->
  - <!--#set var="TOC" value="" -->
  - <!--#set var="CONTENT" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="YES" -->
   <!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  - <HEAD>
  -  <TITLE>Apache Server Frequently Asked Questions</TITLE>
  - </HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  - <BODY
  -  BGCOLOR="#FFFFFF"
  -  TEXT="#000000"
  -  LINK="#0000FF"
  -  VLINK="#000080"
  -  ALINK="#FF0000"
  - >
  -  <!--#include virtual="header.html" -->
  -  <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>
  -  <P>
  -  $Revision: 1.10 $ ($Date: 2001/08/22 18:20:25 $)
  -  </P>
  -  <P>
  -  The latest version of this FAQ is always available from the main
  -  Apache web site, at
  -  &lt;<A
  -       HREF="http://httpd.apache.org/docs/misc/FAQ.html"
  -       REL="Help"
  -      ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>&gt;.
  -  </P>
  -<!-- Notes about changes:                                           -->
  -<!--  - If adding a relative link to another part of the            -->
  -<!--    documentation, *do* include the ".html" portion.  There's a -->
  -<!--    good chance that the user will be reading the documentation -->
  -<!--    on his own system, which may not be configured for          -->
  -<!--    multiviews.                                                 -->
  -<!--  - When adding items, make sure they're put in the right place -->
  -<!--    - verify that the numbering matches up.                     -->
  -<!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  -<!--    correctly in a reliable way when this is converted to text  -->
  -<!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  -<!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  -<!--    the horizontal and vertical indenting right.                -->
  -<!--  - Don't forget to include an HR tag after the last /P tag     -->
  -<!--    but before the /LI in an item.                              -->
  -  <P>
  -  If you are reading a text-only version of this FAQ, you may find numbers
  -  enclosed in brackets (such as &quot;[12]&quot;).  These refer to the list of
  -  reference URLs to be found at the end of the document.  These references
  -  do not appear, and are not needed, for the hypertext version.
  -  </P>
  -  <H2>The Questions</H2>
  -<OL TYPE="A">
  -<!--#endif -->
  -<!--#if expr="$TOC || $STANDALONE" -->
  - <LI value="2"><STRONG>General Technical Questions</STRONG>
  -  <OL>
  -   <LI><A HREF="#what2do">&quot;Why can't I ...?  Why won't ...
  -        work?&quot;  What to do in case of problems</A>
  -   </LI>
  -   <LI><A HREF="#compatible">How compatible is Apache with my existing
  -        NCSA 1.3 setup?</A>
  -   </LI>
  -   <LI><A HREF="#year2000">Is Apache Year 2000 compliant?</A>
  -   </LI>
  -   <LI><A HREF="#submit_patch">How do I submit a patch to the Apache Group?</A>
  -   </LI>
  -   <LI><A HREF="#domination">Why has Apache stolen my favourite site's
  -        Internet address?</A>
  -   </LI>
  -   <LI><A HREF="#apspam">Why am I getting spam mail from the Apache site?</A>
  -   </LI>
  -   <LI><A HREF="#redist">May I include the Apache software on a CD or other
  -        package I'm distributing?</A>
  -   </LI>
  -   <LI><A HREF="#zoom">What's the best hardware/operating system/... How do
  -        I get the most out of my Apache Web server?</A>
  -   </LI>
  -   <LI><A HREF="#regex">What are "regular expressions"?</A>
  -   </LI>
  -   <li><a href="#binaries">Why isn't there a binary for my platform?</a></li>
  -  </OL>
  - </LI>
  +<!--#else -->
  +<!--#set var="STANDALONE" value="YES" -->
  +<!--#set var="INCLUDED" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#endif -->
   <!--#if expr="$STANDALONE" -->
  -</OL>
  -
  -<HR>
  -
  -  <H2>The Answers</H2>
  -<!--#endif -->
  -<!--#if expr="! $TOC" -->
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -  <H3>B. General Technical Questions</H3>
  -<OL>
  -
  - <LI><A NAME="what2do">
  -      <STRONG>&quot;Why can't I ...?  Why won't ... work?&quot;  What to
  -      do in case of problems</STRONG>
  -     </A>
  -  <P>
  -  If you are having trouble with your Apache server software, you should
  -  take the following steps:
  -  </P>
  -  <OL>
  -   <LI><STRONG>Check the errorlog!</STRONG>
  -    <P>
  -    Apache tries to be helpful when it encounters a problem.  In many
  -    cases, it will provide some details by writing one or messages to
  -    the server error log.  Sometimes this is enough for you to diagnose
  -    &amp; fix the problem yourself (such as file permissions or the like).
  -    The default location of the error log is
  -    <SAMP>/usr/local/apache/logs/error_log</SAMP>, but see the
  -    <A HREF="../mod/core.html#errorlog"><SAMP>ErrorLog</SAMP></A>
  -    directive in your config files for the location on your server.
  -    </P>
  -   </LI>
  -   <LI><STRONG>Check the
  -    <A HREF="http://httpd.apache.org/docs/misc/FAQ.html">FAQ</A>!</STRONG>
  -    <P>
  -    The latest version of the Apache Frequently-Asked Questions list can
  -    always be found at the main Apache web site.
  -    </P>
  -   </LI>
  -   <LI><STRONG>Check the Apache bug database</STRONG>
  -    <P>
  -    Most problems that get reported to The Apache Group are recorded in
  -    the
  -    <A HREF="http://bugs.apache.org/">bug database</A>.
  -    <EM><STRONG>Please</STRONG> check the existing reports, open
  -    <STRONG>and</STRONG> closed, before adding one.</EM>  If you find
  -    that your issue has already been reported, please <EM>don't</EM> add
  -    a &quot;me, too&quot; report.  If the original report isn't closed
  -    yet, we suggest that you check it periodically.  You might also
  -    consider contacting the original submitter, because there may be an
  -    email exchange going on about the issue that isn't getting recorded
  -    in the database.
  -    </P>
  -   </LI>
  -   <LI><STRONG>Ask in the <SAMP>comp.infosystems.www.servers.unix</SAMP>
  -    or <SAMP>comp.infosystems.www.servers.ms-windows</SAMP> USENET
  -    newsgroup (as appropriate for the platform you use).</STRONG>
  -    <P>
  -    A lot of common problems never make it to the bug database because
  -    there's already high Q&amp;A traffic about them in
  -    <A HREF="news:comp.infosystems.www.servers.unix"
  -    ><SAMP>comp.infosystems.www.servers.unix</SAMP></A> and related
  -    newsgroups.  These newsgroups are also available via 
  -    <a href="http://groups.google.com/groups?group=comp.infosystems.www.servers"
  -    >Google</a>. Many Apache users, and some of the developers, can be
  -    found roaming its virtual halls, so it is suggested that you seek
  -    wisdom there.  The chances are good that you'll get a faster answer
  -    there than from the bug database, even if you <EM>don't</EM> see
  -    your question already posted.
  -    </P>
  -   </LI>
  -   <LI><STRONG>If all else fails, report the problem in the bug
  -    database</STRONG>
  -    <P>
  -    If you've gone through those steps above that are appropriate and
  -    have obtained no relief, then please <EM>do</EM> let The Apache
  -    Group know about the problem by
  -    <A HREF="http://httpd.apache.org/bug_report.html">logging a bug report</A>.
  -    </P>
  -    <P>
  -    If your problem involves the server crashing and generating a core
  -    dump, please include a backtrace (if possible).  As an example,
  -    </P>
  -    <P>
  -    <DL>
  -     <DD><CODE># cd <EM>ServerRoot</EM><BR>
  -      # dbx httpd core<BR>
  -      (dbx) where</CODE>
  -     </DD>
  -    </DL>
  -    <P></P>
  -    <P>
  -    (Substitute the appropriate locations for your
  -    <SAMP>ServerRoot</SAMP> and your <SAMP>httpd</SAMP> and
  -    <SAMP>core</SAMP> files.  You may have to use <CODE>gdb</CODE>
  -    instead of <CODE>dbx</CODE>.)
  -    </P>
  -   </LI>
  -  </OL>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="compatible">
  -      <STRONG>How compatible is Apache with my existing NCSA 1.3
  -      setup?</STRONG>
  -     </A>
  -  <P>
  -  Apache attempts to offer all the features and configuration options
  -  of NCSA httpd 1.3, as well as many of the additional features found in
  -  NCSA httpd 1.4 and NCSA httpd 1.5.
  -  </P>
  -  <P>
  -  NCSA httpd appears to be moving toward adding experimental features
  -  which are not generally required at the moment. Some of the experiments
  -  will succeed while others will inevitably be dropped. The Apache
  -  philosophy is to add what's needed as and when it is needed.
  -  </P>
  -  <P>
  -  Friendly interaction between Apache and NCSA developers should ensure
  -  that fundamental feature enhancements stay consistent between the two
  -  servers for the foreseeable future.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="year2000">
  -      <STRONG>Is Apache Year 2000 compliant?</STRONG>
  -     </A>
  -  <P>
  -  Yes, Apache is Year 2000 compliant.
  -  </P>
  -  <P>
  -  Apache internally never stores years as two digits.
  -  On the HTTP protocol level RFC1123-style addresses are generated
  -  which is the only format a HTTP/1.1-compliant server should
  -  generate. To be compatible with older applications Apache
  -  recognizes ANSI C's <CODE>asctime()</CODE> and
  -  RFC850-/RFC1036-style date formats, too.
  -  The <CODE>asctime()</CODE> format uses four-digit years,
  -  but the RFC850 and RFC1036 date formats only define a two-digit year.
  -  If Apache sees such a date with a value less than 70 it assumes that
  -  the century is <SAMP>20</SAMP> rather than <SAMP>19</SAMP>.
  -  </P>
  -  <P>
  -  Although Apache is Year 2000 compliant, you may still get problems
  -  if the underlying OS has problems with dates past year 2000
  -  (<EM>e.g.</EM>, OS calls which accept or return year numbers).
  -  Most (UNIX) systems store dates internally as signed 32-bit integers
  -  which contain the number of seconds since 1<SUP>st</SUP> January 1970, so
  -  the magic boundary to worry about is the year 2038 and not 2000.
  -  But modern operating systems shouldn't cause any trouble
  -  at all.
  -  </P>
  -  <P>
  -  Users of Apache 1.2.x should upgrade to a current version of Apache 1.3
  -  (see <A HREF="../new_features_1_3.html#misc">year-2000 improvements in
  -  Apache 1.3</A> for details).
  -  </P>
  -  <p>
  -  The Apache HTTP Server project is an open-source software product of
  -  the Apache Software Foundation.  The project and the Foundation
  -  <b>cannot</b> offer legal assurances regarding any suitability
  -  of the software for your application.  There are several commercial
  -  Apache support organizations and derivative server products available
  -  that may be able to stand behind the software and provide you with
  -  any assurances you may require.  You may find links to some of these
  -  vendors at
  -  <samp>&lt;<a href="http://www.apache.org/info/support.cgi"
  -            >http://www.apache.org/info/support.cgi</a>&gt;</samp>.
  -  </p>
  -  <p>
  -  The Apache HTTP server software is distributed with the following
  -  disclaimer, found in the software license:
  -  </p>
  -  <pre>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Server Frequently Asked Questions</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache Server Frequently Asked
  +    Questions</h1>
  +
  +    <p>$Revision: 1.11 $ ($Date: 2001/10/08 01:26:54 $)</p>
  +
  +    <p>The latest version of this FAQ is always available from the
  +    main Apache web site, at &lt;<a
  +    href="http://httpd.apache.org/docs/misc/FAQ.html"
  +    rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>&gt;.</p>
  +    <!-- Notes about changes:                                           -->
  +    <!--  - If adding a relative link to another part of the            -->
  +    <!--    documentation, *do* include the ".html" portion.  There's a -->
  +    <!--    good chance that the user will be reading the documentation -->
  +    <!--    on his own system, which may not be configured for          -->
  +    <!--    multiviews.                                                 -->
  +    <!--  - When adding items, make sure they're put in the right place -->
  +    <!--    - verify that the numbering matches up.                     -->
  +    <!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  +    <!--    correctly in a reliable way when this is converted to text  -->
  +    <!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  +    <!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  +    <!--    the horizontal and vertical indenting right.                -->
  +    <!--  - Don't forget to include an HR tag after the last /P tag     -->
  +    <!--    but before the /LI in an item.                              -->
  +
  +    <p>If you are reading a text-only version of this FAQ, you may
  +    find numbers enclosed in brackets (such as "[12]"). These refer
  +    to the list of reference URLs to be found at the end of the
  +    document. These references do not appear, and are not needed,
  +    for the hypertext version.</p>
  +
  +    <h2>The Questions</h2>
  +
  +    <ol type="A">
  +      <!--#endif -->
  +      <!--#if expr="$TOC || $STANDALONE" -->
  +
  +      <li value="2">
  +        <strong>General Technical Questions</strong> 
  +
  +        <ol>
  +          <li><a href="#what2do">"Why can't I ...? Why won't ...
  +          work?" What to do in case of problems</a></li>
  +
  +          <li><a href="#compatible">How compatible is Apache with
  +          my existing NCSA 1.3 setup?</a></li>
  +
  +          <li><a href="#year2000">Is Apache Year 2000
  +          compliant?</a></li>
  +
  +          <li><a href="#submit_patch">How do I submit a patch to
  +          the Apache Group?</a></li>
  +
  +          <li><a href="#domination">Why has Apache stolen my
  +          favourite site's Internet address?</a></li>
  +
  +          <li><a href="#apspam">Why am I getting spam mail from the
  +          Apache site?</a></li>
  +
  +          <li><a href="#redist">May I include the Apache software
  +          on a CD or other package I'm distributing?</a></li>
  +
  +          <li><a href="#zoom">What's the best hardware/operating
  +          system/... How do I get the most out of my Apache Web
  +          server?</a></li>
  +
  +          <li><a href="#regex">What are "regular
  +          expressions"?</a></li>
  +
  +          <li><a href="#binaries">Why isn't there a binary for my
  +          platform?</a></li>
  +        </ol>
  +      </li>
  +      <!--#endif -->
  +      <!--#if expr="$STANDALONE" -->
  +    </ol>
  +    <hr />
  +
  +    <h2>The Answers</h2>
  +    <!--#endif -->
  +    <!--#if expr="! $TOC" -->
  +
  +    <h3>B. General Technical Questions</h3>
  +
  +    <ol>
  +      <li>
  +        <a id="what2do" name="what2do"><strong>"Why can't I ...?
  +        Why won't ... work?" What to do in case of
  +        problems</strong></a> 
  +
  +        <p>If you are having trouble with your Apache server
  +        software, you should take the following steps:</p>
  +
  +        <ol>
  +          <li>
  +            <strong>Check the errorlog!</strong> 
  +
  +            <p>Apache tries to be helpful when it encounters a
  +            problem. In many cases, it will provide some details by
  +            writing one or messages to the server error log.
  +            Sometimes this is enough for you to diagnose &amp; fix
  +            the problem yourself (such as file permissions or the
  +            like). The default location of the error log is
  +            <samp>/usr/local/apache/logs/error_log</samp>, but see
  +            the <a
  +            href="../mod/core.html#errorlog"><samp>ErrorLog</samp></a>
  +            directive in your config files for the location on your
  +            server.</p>
  +          </li>
  +
  +          <li>
  +            <strong>Check the <a
  +            href="http://httpd.apache.org/docs/misc/FAQ.html">FAQ</a>!</strong>
  +            
  +
  +            <p>The latest version of the Apache Frequently-Asked
  +            Questions list can always be found at the main Apache
  +            web site.</p>
  +          </li>
  +
  +          <li>
  +            <strong>Check the Apache bug database</strong> 
  +
  +            <p>Most problems that get reported to The Apache Group
  +            are recorded in the <a
  +            href="http://bugs.apache.org/">bug database</a>.
  +            <em><strong>Please</strong> check the existing reports,
  +            open <strong>and</strong> closed, before adding
  +            one.</em> If you find that your issue has already been
  +            reported, please <em>don't</em> add a "me, too" report.
  +            If the original report isn't closed yet, we suggest
  +            that you check it periodically. You might also consider
  +            contacting the original submitter, because there may be
  +            an email exchange going on about the issue that isn't
  +            getting recorded in the database.</p>
  +          </li>
  +
  +          <li>
  +            <strong>Ask in the
  +            <samp>comp.infosystems.www.servers.unix</samp> or
  +            <samp>comp.infosystems.www.servers.ms-windows</samp>
  +            USENET newsgroup (as appropriate for the platform you
  +            use).</strong> 
  +
  +            <p>A lot of common problems never make it to the bug
  +            database because there's already high Q&amp;A traffic
  +            about them in <a
  +            href="news:comp.infosystems.www.servers.unix"><samp>comp.infosystems.www.servers.unix</samp></a>
  +            and related newsgroups. These newsgroups are also
  +            available via <a
  +            href="http://groups.google.com/groups?group=comp.infosystems.www.servers">
  +            Google</a>. Many Apache users, and some of the
  +            developers, can be found roaming its virtual halls, so
  +            it is suggested that you seek wisdom there. The chances
  +            are good that you'll get a faster answer there than
  +            from the bug database, even if you <em>don't</em> see
  +            your question already posted.</p>
  +          </li>
  +
  +          <li>
  +            <strong>If all else fails, report the problem in the
  +            bug database</strong> 
  +
  +            <p>If you've gone through those steps above that are
  +            appropriate and have obtained no relief, then please
  +            <em>do</em> let The Apache Group know about the problem
  +            by <a
  +            href="http://httpd.apache.org/bug_report.html">logging
  +            a bug report</a>.</p>
  +
  +            <p>If your problem involves the server crashing and
  +            generating a core dump, please include a backtrace (if
  +            possible). As an example,</p>
  +
  +            <dl>
  +              <dd><code># cd <em>ServerRoot</em><br />
  +               # dbx httpd core<br />
  +               (dbx) where</code></dd>
  +            </dl>
  +
  +            <p>(Substitute the appropriate locations for your
  +            <samp>ServerRoot</samp> and your <samp>httpd</samp> and
  +            <samp>core</samp> files. You may have to use
  +            <code>gdb</code> instead of <code>dbx</code>.)</p>
  +          </li>
  +        </ol>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="compatible" name="compatible"><strong>How compatible
  +        is Apache with my existing NCSA 1.3 setup?</strong></a> 
  +
  +        <p>Apache attempts to offer all the features and
  +        configuration options of NCSA httpd 1.3, as well as many of
  +        the additional features found in NCSA httpd 1.4 and NCSA
  +        httpd 1.5.</p>
  +
  +        <p>NCSA httpd appears to be moving toward adding
  +        experimental features which are not generally required at
  +        the moment. Some of the experiments will succeed while
  +        others will inevitably be dropped. The Apache philosophy is
  +        to add what's needed as and when it is needed.</p>
  +
  +        <p>Friendly interaction between Apache and NCSA developers
  +        should ensure that fundamental feature enhancements stay
  +        consistent between the two servers for the foreseeable
  +        future.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="year2000" name="year2000"><strong>Is Apache Year
  +        2000 compliant?</strong></a> 
  +
  +        <p>Yes, Apache is Year 2000 compliant.</p>
  +
  +        <p>Apache internally never stores years as two digits. On
  +        the HTTP protocol level RFC1123-style addresses are
  +        generated which is the only format a HTTP/1.1-compliant
  +        server should generate. To be compatible with older
  +        applications Apache recognizes ANSI C's
  +        <code>asctime()</code> and RFC850-/RFC1036-style date
  +        formats, too. The <code>asctime()</code> format uses
  +        four-digit years, but the RFC850 and RFC1036 date formats
  +        only define a two-digit year. If Apache sees such a date
  +        with a value less than 70 it assumes that the century is
  +        <samp>20</samp> rather than <samp>19</samp>.</p>
  +
  +        <p>Although Apache is Year 2000 compliant, you may still
  +        get problems if the underlying OS has problems with dates
  +        past year 2000 (<em>e.g.</em>, OS calls which accept or
  +        return year numbers). Most (UNIX) systems store dates
  +        internally as signed 32-bit integers which contain the
  +        number of seconds since 1<sup>st</sup> January 1970, so the
  +        magic boundary to worry about is the year 2038 and not
  +        2000. But modern operating systems shouldn't cause any
  +        trouble at all.</p>
  +
  +        <p>Users of Apache 1.2.x should upgrade to a current
  +        version of Apache 1.3 (see <a
  +        href="../new_features_1_3.html#misc">year-2000 improvements
  +        in Apache 1.3</a> for details).</p>
  +
  +        <p>The Apache HTTP Server project is an open-source
  +        software product of the Apache Software Foundation. The
  +        project and the Foundation <b>cannot</b> offer legal
  +        assurances regarding any suitability of the software for
  +        your application. There are several commercial Apache
  +        support organizations and derivative server products
  +        available that may be able to stand behind the software and
  +        provide you with any assurances you may require. You may
  +        find links to some of these vendors at <samp>&lt;<a
  +        href="http://www.apache.org/info/support.cgi">http://www.apache.org/info/support.cgi</a>&gt;</samp>.</p>
  +
  +        <p>The Apache HTTP server software is distributed with the
  +        following disclaimer, found in the software license:</p>
  +<pre>
      THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY
      EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
      IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  @@ -283,166 +300,168 @@
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
      ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
      OF THE POSSIBILITY OF SUCH DAMAGE.
  -  </pre>
  -  <HR>
  - </LI>
  -
  -  <LI><A NAME="submit_patch">
  -       <STRONG>How do I submit a patch to the Apache Group?</STRONG></A>
  -   <P>
  -   The Apache Group encourages patches from outside developers. There
  -   are 2 main "types" of patches: small bugfixes and general
  -   improvements. Bugfixes should be submitting using the Apache <A
  -   HREF="http://httpd.apache.org/bug_report.html">bug report page</A>.
  -   Improvements, modifications, and additions should follow the
  -   instructions below.
  -   </P>
  -   <P>
  -   In general, the first course of action is to be a member of the
  -   <SAMP>dev@httpd.apache.org</SAMP> mailing list. This indicates to
  -   the Group that you are closely following the latest Apache
  -   developments. Your patch file should be generated using either
  -   '<CODE>diff&nbsp;-c</CODE>' or '<CODE>diff&nbsp;-u</CODE>' against
  -   the latest CVS tree. To submit your patch, send email to
  -   <SAMP>dev@httpd.apache.org</SAMP> with a <SAMP>Subject:</SAMP> line
  -   that starts with <SAMP>[PATCH]</SAMP> and includes a general
  -   description of the patch. In the body of the message, the patch
  -   should be clearly described and then included at the end of the
  -   message.  If the patch-file is long, you can note a URL to the file
  -   instead of the file itself. Use of MIME enclosures/attachments
  -   should be avoided.
  -   </P>
  -   <P>
  -   Be prepared to respond to any questions about your patches and
  -   possibly defend your code. If your patch results in a lot of
  -   discussion, you may be asked to submit an updated patch that
  -   incorporate all changes and suggestions.
  -   </P>
  -   <HR>
  -  </LI>
  -
  -  <LI><A NAME="domination"><STRONG>Why has Apache stolen my favourite site's
  -       Internet address?</STRONG></A>
  -   <P>
  -   The simple answer is: "It hasn't."  This misconception is usually
  -   caused by the site in question having migrated to the Apache Web
  -   server software, but not having migrated the site's content yet.  When
  -   Apache is installed, the default page that gets installed tells the
  -   Webmaster the installation was successful.  The expectation is that
  -   this default page will be replaced with the site's real content.
  -   If it doesn't, complain to the Webmaster, not to the Apache project --
  -   we just make the software and aren't responsible for what people
  -   do (or don't do) with it.
  -   </P>
  -   <HR>
  -  </LI>
  -
  -  <LI><A NAME="apspam"><STRONG>Why am I getting spam mail from the
  -       Apache site?</STRONG></A>
  -   <P>
  -   The short answer is: "You aren't."  Usually when someone thinks the
  -   Apache site is originating spam, it's because they've traced the
  -   spam to a Web site, and the Web site says it's using Apache.  See the
  -   <A HREF="#domination">previous FAQ entry</A> for more details on this
  -   phenomenon.
  -   </P>
  -   <P>
  -   No marketing spam originates from the Apache site.  The only mail
  -   that comes from the site goes only to addresses that have been
  -   <EM>requested</EM> to receive the mail.
  -   </P>
  -   <HR>
  -  </LI>
  -
  -  <LI><A NAME="redist"><STRONG>May I include the Apache software on a
  -       CD or other package I'm distributing?</STRONG></A>
  -   <P>
  -   The detailed answer to this question can be found in the
  -   Apache license, which is included in the Apache distribution in
  -   the file <CODE>LICENSE</CODE>.  You can also find it on the Web at
  -   <SAMP>&lt;<A HREF="http://www.apache.org/LICENSE.txt"
  -             >http://www.apache.org/LICENSE.txt</A>&gt;</SAMP>.
  -   </P>
  -   <HR>
  -  </LI>
  -
  - <LI><A NAME="zoom">
  -      <STRONG>What's the best hardware/operating system/... How do
  -      I get the most out of my Apache Web server?</STRONG>
  -     </A>
  -  <P>
  -  Check out Dean Gaudet's
  -  <A HREF="perf-tuning.html">performance tuning page</A>.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="regex">
  -      <STRONG>What are "regular expressions"?</STRONG></A>
  -   <P>
  -   Regular expressions are a way of describing a pattern - for example, "all 
  -   the words that begin with the letter A" or "every 10-digit phone number" 
  -   or even "Every sentence with two commas in it, and no capital letter Q".  
  -   Regular expressions (aka "regex"s) are useful in Apache because they 
  -   let you apply certain attributes against collections of files or resources 
  -   in very flexible ways - for example, all .gif and .jpg files under
  -   any "images" directory could be written as /\/images\/.*(jpg|gif)$/.
  -   </P>
  -   <P>
  -   The best overview around is probably the one which comes with Perl.
  -   We implement a simple subset of Perl's regex support, but it's
  -   still a good way to learn what they mean.  You can start by going
  -   to the <A
  -   HREF="http://www.perl.com/CPAN-local/doc/manual/html/pod/perlre.html#Regular_Expressions"
  -   >CPAN page on regular expressions</A>, and branching out from
  -   there.
  -   </P>
  -  <HR>
  - </LI>
  -
  - <li><a name="binaries">
  -      <b>Why isn't there a binary for my platform?</b></a>
  -   <p>
  -   The developers make sure that the software builds and works
  -   correctly on the platforms available to them; this does
  -   <i>not</i> necessarily mean that <i>your</i> platform
  -   is one of them.  In addition, the Apache HTTP server project
  -   is primarily source oriented, meaning that distributing
  -   valid and buildable source code is the purpose of a release,
  -   not making sure that there is a binary package for all of the
  -   supported platforms.
  -   </p>
  -   <p>
  -   If you don't see a kit for your platform listed in the
  -   binary distribution area
  -   (&lt;URL:<a href="http://httpd.apache.org/dist/httpd/binaries/"
  -            >http://httpd.apache.org/dist/httpd/binaries/</a>&gt;),
  -   it means either that the platform isn't available to any of
  -   the developers, or that they just haven't gotten around to
  -   preparing a binary for it.  As this is a voluntary project,
  -   they are under no obligation to do so.  Users are encouraged
  -   and expected to build the software themselves.
  -   </p>
  -   <p>
  -   The sole exception to these practices is the Windows package.
  -   Unlike most Unix and Unix-like platforms, Windows systems
  -   do not come with a bundled software development environment,
  -   so we <i>do</i> prepare binary kits for Windows when we make
  -   a release.  Again, however, it's a voluntary thing and only
  -   a limited number of the developers have the capability to build
  -   the InstallShield package, so the Windows release may lag
  -   somewhat behind the source release.  This lag should be
  -   no more than a few days at most.
  -   </p>
  -  <hr>
  - </li>
  + 
  +</pre>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="submit_patch" name="submit_patch"><strong>How do I
  +        submit a patch to the Apache Group?</strong></a> 
  +
  +        <p>The Apache Group encourages patches from outside
  +        developers. There are 2 main "types" of patches: small
  +        bugfixes and general improvements. Bugfixes should be
  +        submitting using the Apache <a
  +        href="http://httpd.apache.org/bug_report.html">bug report
  +        page</a>. Improvements, modifications, and additions should
  +        follow the instructions below.</p>
  +
  +        <p>In general, the first course of action is to be a member
  +        of the <samp>dev@httpd.apache.org</samp> mailing list. This
  +        indicates to the Group that you are closely following the
  +        latest Apache developments. Your patch file should be
  +        generated using either '<code>diff&nbsp;-c</code>' or
  +        '<code>diff&nbsp;-u</code>' against the latest CVS tree. To
  +        submit your patch, send email to
  +        <samp>dev@httpd.apache.org</samp> with a
  +        <samp>Subject:</samp> line that starts with
  +        <samp>[PATCH]</samp> and includes a general description of
  +        the patch. In the body of the message, the patch should be
  +        clearly described and then included at the end of the
  +        message. If the patch-file is long, you can note a URL to
  +        the file instead of the file itself. Use of MIME
  +        enclosures/attachments should be avoided.</p>
  +
  +        <p>Be prepared to respond to any questions about your
  +        patches and possibly defend your code. If your patch
  +        results in a lot of discussion, you may be asked to submit
  +        an updated patch that incorporate all changes and
  +        suggestions.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="domination" name="domination"><strong>Why has Apache
  +        stolen my favourite site's Internet address?</strong></a> 
  +
  +        <p>The simple answer is: "It hasn't." This misconception is
  +        usually caused by the site in question having migrated to
  +        the Apache Web server software, but not having migrated the
  +        site's content yet. When Apache is installed, the default
  +        page that gets installed tells the Webmaster the
  +        installation was successful. The expectation is that this
  +        default page will be replaced with the site's real content.
  +        If it doesn't, complain to the Webmaster, not to the Apache
  +        project -- we just make the software and aren't responsible
  +        for what people do (or don't do) with it.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="apspam" name="apspam"><strong>Why am I getting spam
  +        mail from the Apache site?</strong></a> 
  +
  +        <p>The short answer is: "You aren't." Usually when someone
  +        thinks the Apache site is originating spam, it's because
  +        they've traced the spam to a Web site, and the Web site
  +        says it's using Apache. See the <a
  +        href="#domination">previous FAQ entry</a> for more details
  +        on this phenomenon.</p>
  +
  +        <p>No marketing spam originates from the Apache site. The
  +        only mail that comes from the site goes only to addresses
  +        that have been <em>requested</em> to receive the mail.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="redist" name="redist"><strong>May I include the
  +        Apache software on a CD or other package I'm
  +        distributing?</strong></a> 
  +
  +        <p>The detailed answer to this question can be found in the
  +        Apache license, which is included in the Apache
  +        distribution in the file <code>LICENSE</code>. You can also
  +        find it on the Web at <samp>&lt;<a
  +        href="http://www.apache.org/LICENSE.txt">http://www.apache.org/LICENSE.txt</a>&gt;</samp>.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="zoom" name="zoom"><strong>What's the best
  +        hardware/operating system/... How do I get the most out of
  +        my Apache Web server?</strong></a> 
  +
  +        <p>Check out Dean Gaudet's <a
  +        href="perf-tuning.html">performance tuning page</a>.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="regex" name="regex"><strong>What are "regular
  +        expressions"?</strong></a> 
  +
  +        <p>Regular expressions are a way of describing a pattern -
  +        for example, "all the words that begin with the letter A"
  +        or "every 10-digit phone number" or even "Every sentence
  +        with two commas in it, and no capital letter Q". Regular
  +        expressions (aka "regex"s) are useful in Apache because
  +        they let you apply certain attributes against collections
  +        of files or resources in very flexible ways - for example,
  +        all .gif and .jpg files under any "images" directory could
  +        be written as /\/images\/.*(jpg|gif)$/.</p>
  +
  +        <p>The best overview around is probably the one which comes
  +        with Perl. We implement a simple subset of Perl's regex
  +        support, but it's still a good way to learn what they mean.
  +        You can start by going to the <a
  +        href="http://www.perl.com/CPAN-local/doc/manual/html/pod/perlre.html#Regular_Expressions">
  +        CPAN page on regular expressions</a>, and branching out
  +        from there.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="binaries" name="binaries"><b>Why isn't there a
  +        binary for my platform?</b></a> 
  +
  +        <p>The developers make sure that the software builds and
  +        works correctly on the platforms available to them; this
  +        does <i>not</i> necessarily mean that <i>your</i> platform
  +        is one of them. In addition, the Apache HTTP server project
  +        is primarily source oriented, meaning that distributing
  +        valid and buildable source code is the purpose of a
  +        release, not making sure that there is a binary package for
  +        all of the supported platforms.</p>
  +
  +        <p>If you don't see a kit for your platform listed in the
  +        binary distribution area (&lt;URL:<a
  +        href="http://httpd.apache.org/dist/httpd/binaries/">http://httpd.apache.org/dist/httpd/binaries/</a>&gt;),
  +        it means either that the platform isn't available to any of
  +        the developers, or that they just haven't gotten around to
  +        preparing a binary for it. As this is a voluntary project,
  +        they are under no obligation to do so. Users are encouraged
  +        and expected to build the software themselves.</p>
  +
  +        <p>The sole exception to these practices is the Windows
  +        package. Unlike most Unix and Unix-like platforms, Windows
  +        systems do not come with a bundled software development
  +        environment, so we <i>do</i> prepare binary kits for
  +        Windows when we make a release. Again, however, it's a
  +        voluntary thing and only a limited number of the developers
  +        have the capability to build the InstallShield package, so
  +        the Windows release may lag somewhat behind the source
  +        release. This lag should be no more than a few days at
  +        most.</p>
  +        <hr />
  +      </li>
  +    </ol>
  +    <!--#endif -->
  +    <!--#if expr="$STANDALONE" -->
  +    <!-- Don't forget to add HR tags at the end of each list item.. -->
  +    <!--#include virtual="footer.html" -->
  +    <!--#endif -->
  +  </body>
  +</html>
   
  -</OL>
  -<!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -  <!-- Don't forget to add HR tags at the end of each list item.. -->
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  -<!--#endif -->
  
  
  
  1.3       +269 -266  httpd-docs-1.3/htdocs/manual/misc/FAQ-C.html
  
  Index: FAQ-C.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/FAQ-C.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- FAQ-C.html	2000/11/12 00:25:31	1.2
  +++ FAQ-C.html	2001/10/08 01:26:54	1.3
  @@ -1,273 +1,276 @@
   <!--#if expr="$FAQMASTER" -->
  - <!--#set var="STANDALONE" value="" -->
  - <!--#set var="INCLUDED" value="YES" -->
  - <!--#if expr="$QUERY_STRING = TOC" -->
  -  <!--#set var="TOC" value="YES" -->
  -  <!--#set var="CONTENT" value="" -->
  - <!--#else -->
  -  <!--#set var="TOC" value="" -->
  -  <!--#set var="CONTENT" value="YES" -->
  - <!--#endif -->
  +<!--#set var="STANDALONE" value="" -->
  +<!--#set var="INCLUDED" value="YES" -->
  +<!--#if expr="$QUERY_STRING = TOC" -->
  +<!--#set var="TOC" value="YES" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#else -->
  - <!--#set var="STANDALONE" value="YES" -->
  - <!--#set var="INCLUDED" value="" -->
  - <!--#set var="TOC" value="" -->
  - <!--#set var="CONTENT" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="YES" -->
   <!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  - <HEAD>
  -  <TITLE>Apache Server Frequently Asked Questions</TITLE>
  - </HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  - <BODY
  -  BGCOLOR="#FFFFFF"
  -  TEXT="#000000"
  -  LINK="#0000FF"
  -  VLINK="#000080"
  -  ALINK="#FF0000"
  - >
  -  <!--#include virtual="header.html" -->
  -  <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>
  -  <P>
  -  $Revision: 1.2 $ ($Date: 2000/11/12 00:25:31 $)
  -  </P>
  -  <P>
  -  The latest version of this FAQ is always available from the main
  -  Apache web site, at
  -  &lt;<A
  -       HREF="http://httpd.apache.org/docs/misc/FAQ.html"
  -       REL="Help"
  -      ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>&gt;.
  -  </P>
  -<!-- Notes about changes:                                           -->
  -<!--  - If adding a relative link to another part of the            -->
  -<!--    documentation, *do* include the ".html" portion.  There's a -->
  -<!--    good chance that the user will be reading the documentation -->
  -<!--    on his own system, which may not be configured for          -->
  -<!--    multiviews.                                                 -->
  -<!--  - When adding items, make sure they're put in the right place -->
  -<!--    - verify that the numbering matches up.                     -->
  -<!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  -<!--    correctly in a reliable way when this is converted to text  -->
  -<!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  -<!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  -<!--    the horizontal and vertical indenting right.                -->
  -<!--  - Don't forget to include an HR tag after the last /P tag     -->
  -<!--    but before the /LI in an item.                              -->
  -  <P>
  -  If you are reading a text-only version of this FAQ, you may find numbers
  -  enclosed in brackets (such as &quot;[12]&quot;).  These refer to the list of
  -  reference URLs to be found at the end of the document.  These references
  -  do not appear, and are not needed, for the hypertext version.
  -  </P>
  -  <H2>The Questions</H2>
  -<OL TYPE="A">
  -<!--#endif -->
  -<!--#if expr="$TOC || $STANDALONE" -->
  - <LI VALUE="3"><STRONG>Building Apache</STRONG>
  -  <OL>
  -   <LI><A HREF="#bind8.1">Why do I get an error about an undefined
  -        reference to &quot;<SAMP>__inet_ntoa</SAMP>&quot; or other
  -        <SAMP>__inet_*</SAMP> symbols?</A>
  -   </LI>
  -   <LI><A HREF="#cantbuild">Why won't Apache compile with my
  -        system's <SAMP>cc</SAMP>?</A>
  -   </LI>
  -   <LI><A HREF="#linuxiovec">Why do I get complaints about redefinition
  -        of &quot;<CODE>struct iovec</CODE>&quot; when compiling under Linux?</A>
  -   </LI>
  -   <LI><A HREF="#broken-gcc">I'm using gcc and I get some compilation errors, 
  -	what is wrong?</A>
  -   </LI>
  -   <LI><A HREF="#glibc-crypt">I'm using RedHat Linux 5.0, or some other
  -        <SAMP>glibc</SAMP>-based Linux system, and I get errors with the
  -        <CODE>crypt</CODE> function when I attempt to build Apache 1.2.</A>
  -   </LI>
  -  </OL>
  - </LI>
  +<!--#else -->
  +<!--#set var="STANDALONE" value="YES" -->
  +<!--#set var="INCLUDED" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#endif -->
   <!--#if expr="$STANDALONE" -->
  -</OL>
  -
  -<HR>
  -
  -  <H2>The Answers</H2>
  -<!--#endif -->
  -<!--#if expr="! $TOC" -->
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -  <H3>C. Building Apache</H3>
  -<OL>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Server Frequently Asked Questions</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache Server Frequently Asked
  +    Questions</h1>
  +
  +    <p>$Revision: 1.3 $ ($Date: 2001/10/08 01:26:54 $)</p>
  +
  +    <p>The latest version of this FAQ is always available from the
  +    main Apache web site, at &lt;<a
  +    href="http://httpd.apache.org/docs/misc/FAQ.html"
  +    rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>&gt;.</p>
  +    <!-- Notes about changes:                                           -->
  +    <!--  - If adding a relative link to another part of the            -->
  +    <!--    documentation, *do* include the ".html" portion.  There's a -->
  +    <!--    good chance that the user will be reading the documentation -->
  +    <!--    on his own system, which may not be configured for          -->
  +    <!--    multiviews.                                                 -->
  +    <!--  - When adding items, make sure they're put in the right place -->
  +    <!--    - verify that the numbering matches up.                     -->
  +    <!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  +    <!--    correctly in a reliable way when this is converted to text  -->
  +    <!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  +    <!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  +    <!--    the horizontal and vertical indenting right.                -->
  +    <!--  - Don't forget to include an HR tag after the last /P tag     -->
  +    <!--    but before the /LI in an item.                              -->
  +
  +    <p>If you are reading a text-only version of this FAQ, you may
  +    find numbers enclosed in brackets (such as "[12]"). These refer
  +    to the list of reference URLs to be found at the end of the
  +    document. These references do not appear, and are not needed,
  +    for the hypertext version.</p>
  +
  +    <h2>The Questions</h2>
  +
  +    <ol type="A">
  +      <!--#endif -->
  +      <!--#if expr="$TOC || $STANDALONE" -->
  +
  +      <li value="3">
  +        <strong>Building Apache</strong> 
  +
  +        <ol>
  +          <li><a href="#bind8.1">Why do I get an error about an
  +          undefined reference to "<samp>__inet_ntoa</samp>" or
  +          other <samp>__inet_*</samp> symbols?</a></li>
  +
  +          <li><a href="#cantbuild">Why won't Apache compile with my
  +          system's <samp>cc</samp>?</a></li>
  +
  +          <li><a href="#linuxiovec">Why do I get complaints about
  +          redefinition of "<code>struct iovec</code>" when
  +          compiling under Linux?</a></li>
  +
  +          <li><a href="#broken-gcc">I'm using gcc and I get some
  +          compilation errors, what is wrong?</a></li>
  +
  +          <li><a href="#glibc-crypt">I'm using RedHat Linux 5.0, or
  +          some other <samp>glibc</samp>-based Linux system, and I
  +          get errors with the <code>crypt</code> function when I
  +          attempt to build Apache 1.2.</a></li>
  +        </ol>
  +      </li>
  +      <!--#endif -->
  +      <!--#if expr="$STANDALONE" -->
  +    </ol>
  +    <hr />
  +
  +    <h2>The Answers</h2>
  +    <!--#endif -->
  +    <!--#if expr="! $TOC" -->
  +
  +    <h3>C. Building Apache</h3>
  +
  +    <ol>
  +      <li>
  +        <a id="bind8.1" name="bind8.1"><strong>Why do I get an
  +        error about an undefined reference to
  +        "<samp>__inet_ntoa</samp>" or other <samp>__inet_*</samp>
  +        symbols?</strong></a> 
  +
  +        <p>If you have installed <a
  +        href="http://www.isc.org/bind.html">BIND-8</a> then this is
  +        normally due to a conflict between your include files and
  +        your libraries. BIND-8 installs its include files and
  +        libraries <code>/usr/local/include/</code> and
  +        <code>/usr/local/lib/</code>, while the resolver that comes
  +        with your system is probably installed in
  +        <code>/usr/include/</code> and <code>/usr/lib/</code>. If
  +        your system uses the header files in
  +        <code>/usr/local/include/</code> before those in
  +        <code>/usr/include/</code> but you do not use the new
  +        resolver library, then the two versions will conflict.</p>
  +
  +        <p>To resolve this, you can either make sure you use the
  +        include files and libraries that came with your system or
  +        make sure to use the new include files and libraries.
  +        Adding <code>-lbind</code> to the
  +        <code>EXTRA_LDFLAGS</code> line in your
  +        <samp>Configuration</samp> file, then re-running
  +        <samp>Configure</samp>, should resolve the problem. (Apache
  +        versions 1.2.* and earlier use <code>EXTRA_LFLAGS</code>
  +        instead.)</p>
  +
  +        <p><strong>Note:</strong>As of BIND 8.1.1, the bind
  +        libraries and files are installed under
  +        <samp>/usr/local/bind</samp> by default, so you should not
  +        run into this problem. Should you want to use the bind
  +        resolvers you'll have to add the following to the
  +        respective lines:</p>
  +
  +        <dl>
  +          <dd><code>EXTRA_CFLAGS=-I/usr/local/bind/include<br />
  +           EXTRA_LDFLAGS=-L/usr/local/bind/lib<br />
  +           EXTRA_LIBS=-lbind</code></dd>
  +        </dl>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="cantbuild" name="cantbuild"><strong>Why won't Apache
  +        compile with my system's <samp>cc</samp>?</strong></a> 
  +
  +        <p>If the server won't compile on your system, it is
  +        probably due to one of the following causes:</p>
  +
  +        <ul>
  +          <li><strong>The <samp>Configure</samp> script doesn't
  +          recognize your system environment.</strong><br />
  +           This might be either because it's completely unknown or
  +          because the specific environment (include files, OS
  +          version, <em>et cetera</em>) isn't explicitly handled. If
  +          this happens, you may need to port the server to your OS
  +          yourself.</li>
  +
  +          <li><strong>Your system's C compiler is
  +          garbage.</strong><br />
  +           Some operating systems include a default C compiler that
  +          is either not ANSI C-compliant or suffers from other
  +          deficiencies. The usual recommendation in cases like this
  +          is to acquire, install, and use <samp>gcc</samp>.</li>
  +
  +          <li><strong>Your <samp>include</samp> files may be
  +          confused.</strong><br />
  +           In some cases, we have found that a compiler
  +          installation or system upgrade has left the C header
  +          files in an inconsistent state. Make sure that your
  +          include directory tree is in sync with the compiler and
  +          the operating system.</li>
  +
  +          <li><strong>Your operating system or compiler may be out
  +          of revision.</strong><br />
  +           Software vendors (including those that develop operating
  +          systems) issue new releases for a reason; sometimes to
  +          add functionality, but more often to fix bugs that have
  +          been discovered. Try upgrading your compiler and/or your
  +          operating system.</li>
  +        </ul>
  +
  +        <p>The Apache Group tests the ability to build the server
  +        on many different platforms. Unfortunately, we can't test
  +        all of the OS platforms there are. If you have verified
  +        that none of the above issues is the cause of your problem,
  +        and it hasn't been reported before, please submit a <a
  +        href="http://httpd.apache.org/bug_report.html">problem
  +        report</a>. Be sure to include <em>complete</em> details,
  +        such as the compiler &amp; OS versions and exact error
  +        messages.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="linuxiovec" name="linuxiovec"><strong>Why do I get
  +        complaints about redefinition of "<code>struct
  +        iovec</code>" when compiling under Linux?</strong></a> 
  +
  +        <p>This is a conflict between your C library includes and
  +        your kernel includes. You need to make sure that the
  +        versions of both are matched properly. There are two
  +        workarounds, either one will solve the problem:</p>
  +
  +        <ul>
  +          <li>Remove the definition of <code>struct iovec</code>
  +          from your C library includes. It is located in
  +          <code>/usr/include/sys/uio.h</code>.
  +          <strong>Or,</strong></li>
  +
  +          <li>Add <code>-DNO_WRITEV</code> to the
  +          <code>EXTRA_CFLAGS</code> line in your
  +          <samp>Configuration</samp> and reconfigure/rebuild. This
  +          hurts performance and should only be used as a last
  +          resort.</li>
  +        </ul>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="broken-gcc" name="broken-gcc"><strong>I'm using gcc
  +        and I get some compilation errors, what is
  +        wrong?</strong></a> 
  +
  +        <p>GCC parses your system header files and produces a
  +        modified subset which it uses for compiling. This behavior
  +        ties GCC tightly to the version of your operating system.
  +        So, for example, if you were running IRIX 5.3 when you
  +        built GCC and then upgrade to IRIX 6.2 later, you will have
  +        to rebuild GCC. Similarly for Solaris 2.4, 2.5, or 2.5.1
  +        when you upgrade to 2.6. Sometimes you can type "gcc -v"
  +        and it will tell you the version of the operating system it
  +        was built against.</p>
  +
  +        <p>If you fail to do this, then it is very likely that
  +        Apache will fail to build. One of the most common errors is
  +        with <code>readv</code>, <code>writev</code>, or
  +        <code>uio.h</code>. This is <strong>not</strong> a bug with
  +        Apache. You will need to re-install GCC.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="glibc-crypt" name="glibc-crypt"><strong>I'm using
  +        RedHat Linux 5.0, or some other <samp>glibc</samp>-based
  +        Linux system, and I get errors with the <code>crypt</code>
  +        function when I attempt to build Apache 1.2.</strong></a> 
  +
  +        <p><samp>glibc</samp> puts the <code>crypt</code> function
  +        into a separate library. Edit your
  +        <code>src/Configuration</code> file and set this:</p>
  +
  +        <dl>
  +          <dd><code>EXTRA_LIBS=-lcrypt</code></dd>
  +        </dl>
  +
  +        <p>Then re-run <samp>src/Configure</samp> and re-execute
  +        the make.</p>
  +        <hr />
  +      </li>
  +    </ol>
  +    <!--#endif -->
  +    <!--#if expr="$STANDALONE" -->
  +    <!-- Don't forget to add HR tags at the end of each list item.. -->
  +    <!--#include virtual="footer.html" -->
  +    <!--#endif -->
  +  </body>
  +</html>
   
  - <LI><A NAME="bind8.1">
  -      <STRONG>Why do I get an error about an undefined reference to
  -      &quot;<SAMP>__inet_ntoa</SAMP>&quot; or other
  -      <SAMP>__inet_*</SAMP> symbols?</STRONG>
  -     </A>
  -  <P>
  -  If you have installed <A HREF="http://www.isc.org/bind.html">BIND-8</A>
  -  then this is normally due to a conflict between your include files
  -  and your libraries.  BIND-8 installs its include files and libraries
  -  <CODE>/usr/local/include/</CODE> and <CODE>/usr/local/lib/</CODE>, while
  -  the resolver that comes with your system is probably installed in
  -  <CODE>/usr/include/</CODE> and <CODE>/usr/lib/</CODE>.  If
  -  your system uses the header files in <CODE>/usr/local/include/</CODE>
  -  before those in <CODE>/usr/include/</CODE> but you do not use the new
  -  resolver library, then the two versions will conflict.
  -  </P>
  -  <P>
  -  To resolve this, you can either make sure you use the include files
  -  and libraries that came with your system or make sure to use the
  -  new include files and libraries.  Adding <CODE>-lbind</CODE> to the
  -  <CODE>EXTRA_LDFLAGS</CODE> line in your <SAMP>Configuration</SAMP>
  -  file, then re-running <SAMP>Configure</SAMP>, should resolve the
  -  problem.  (Apache versions 1.2.* and earlier use
  -  <CODE>EXTRA_LFLAGS</CODE> instead.)
  -  </P>
  -  <P>
  -  <STRONG>Note:</STRONG>As of BIND 8.1.1, the bind libraries and files are
  -  installed under <SAMP>/usr/local/bind</SAMP> by default, so you
  -  should not run into this problem.  Should you want to use the bind
  -  resolvers you'll have to add the following to the respective lines:
  -  </P>
  -  <P>
  -  <DL>
  -   <DD><CODE>EXTRA_CFLAGS=-I/usr/local/bind/include
  -    <BR>
  -    EXTRA_LDFLAGS=-L/usr/local/bind/lib
  -    <BR>
  -    EXTRA_LIBS=-lbind</CODE>
  -   </DD>
  -  </DL>
  -  <P></P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="cantbuild">
  -      <STRONG>Why won't Apache compile with my system's
  -      <SAMP>cc</SAMP>?</STRONG>
  -     </A>
  -  <P>
  -  If the server won't compile on your system, it is probably due to one
  -  of the following causes:
  -  </P>
  -  <UL>
  -   <LI><STRONG>The <SAMP>Configure</SAMP> script doesn't recognize your system
  -    environment.</STRONG>
  -    <BR>
  -    This might be either because it's completely unknown or because
  -    the specific environment (include files, OS version, <EM>et
  -    cetera</EM>) isn't explicitly handled.  If this happens, you may
  -    need to port the server to your OS yourself.
  -   </LI>
  -   <LI><STRONG>Your system's C compiler is garbage.</STRONG>
  -    <BR>
  -    Some operating systems include a default C compiler that is either
  -    not ANSI C-compliant or suffers from other deficiencies.  The usual
  -    recommendation in cases like this is to acquire, install, and use
  -    <SAMP>gcc</SAMP>.
  -   </LI>
  -   <LI><STRONG>Your <SAMP>include</SAMP> files may be confused.</STRONG>
  -    <BR>
  -    In some cases, we have found that a compiler installation or system
  -    upgrade has left the C header files in an inconsistent state.  Make
  -    sure that your include directory tree is in sync with the compiler and
  -    the operating system.
  -   </LI>
  -   <LI><STRONG>Your operating system or compiler may be out of
  -    revision.</STRONG>
  -    <BR>
  -    Software vendors (including those that develop operating systems)
  -    issue new releases for a reason; sometimes to add functionality, but
  -    more often to fix bugs that have been discovered.  Try upgrading
  -    your compiler and/or your operating system.
  -   </LI>
  -  </UL>
  -  <P>
  -  The Apache Group tests the ability to build the server on many
  -  different platforms.  Unfortunately, we can't test all of the OS
  -  platforms there are.  If you have verified that none of the above
  -  issues is the cause of your problem, and it hasn't been reported
  -  before, please submit a
  -  <A HREF="http://httpd.apache.org/bug_report.html">problem report</A>.
  -  Be sure to include <EM>complete</EM> details, such as the compiler
  -  &amp; OS versions and exact error messages.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="linuxiovec">
  -      <STRONG>Why do I get complaints about redefinition
  -      of &quot;<CODE>struct iovec</CODE>&quot; when
  -      compiling under Linux?</STRONG>
  -     </A>
  -  <P>
  -  This is a conflict between your C library includes and your kernel
  -  includes.  You need to make sure that the versions of both are matched
  -  properly.  There are two workarounds, either one will solve the problem:
  -  </P>
  -  <P>
  -  <UL>
  -   <LI>Remove the definition of <CODE>struct iovec</CODE> from your C
  -    library includes.  It is located in <CODE>/usr/include/sys/uio.h</CODE>.
  -    <STRONG>Or,</STRONG>
  -   </LI>
  -   <LI>Add  <CODE>-DNO_WRITEV</CODE> to the <CODE>EXTRA_CFLAGS</CODE>
  -    line in your <SAMP>Configuration</SAMP> and reconfigure/rebuild.
  -    This hurts performance and should only be used as a last resort.
  -   </LI>
  -  </UL>
  -  <P></P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="broken-gcc"><STRONG>I'm using gcc and I get some
  -	compilation errors, what is wrong?</STRONG></A>
  -    <P>
  -    GCC parses your system header files and produces a modified subset which
  -    it uses for compiling.  This behaviour ties GCC tightly to the version
  -    of your operating system.  So, for example, if you were running IRIX 5.3
  -    when you built GCC and then upgrade to IRIX 6.2 later, you will have to
  -    rebuild GCC.  Similarly for Solaris 2.4, 2.5, or 2.5.1 when you upgrade
  -    to 2.6.  Sometimes you can type "gcc -v" and it will tell you the version
  -    of the operating system it was built against.
  -    </P>
  -    <P>
  -    If you fail to do this, then it is very likely that Apache will fail
  -    to build.  One of the most common errors is with <CODE>readv</CODE>,
  -    <CODE>writev</CODE>, or <CODE>uio.h</CODE>.  This is <STRONG>not</STRONG> a
  -    bug with Apache.  You will need to re-install GCC.
  -    </P>
  -   <HR>
  -  </LI>
  -
  - <LI><A NAME="glibc-crypt">
  -      <STRONG>I'm using RedHat Linux 5.0, or some other 
  -      <SAMP>glibc</SAMP>-based Linux system, and I get errors with the
  -      <CODE>crypt</CODE> function when I attempt to build Apache 1.2.</STRONG>
  -     </A>
  -
  -  <P>
  -  <SAMP>glibc</SAMP> puts the <CODE>crypt</CODE> function into a separate
  -  library.  Edit your <CODE>src/Configuration</CODE> file and set this:
  -  </P>
  -  <DL>
  -   <DD><CODE>EXTRA_LIBS=-lcrypt</CODE>
  -   </DD>
  -  </DL>
  -  <P>
  -  Then re-run <SAMP>src/Configure</SAMP> and re-execute the make.
  -  </P>
  -  <HR>
  - </LI>
  -
  -</OL>
  -<!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -  <!-- Don't forget to add HR tags at the end of each list item.. -->
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  -<!--#endif -->
  
  
  
  1.14      +482 -464  httpd-docs-1.3/htdocs/manual/misc/FAQ-D.html
  
  Index: FAQ-D.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/FAQ-D.html,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -r1.13 -r1.14
  --- FAQ-D.html	2000/12/14 15:40:49	1.13
  +++ FAQ-D.html	2001/10/08 01:26:54	1.14
  @@ -1,474 +1,492 @@
   <!--#if expr="$FAQMASTER" -->
  - <!--#set var="STANDALONE" value="" -->
  - <!--#set var="INCLUDED" value="YES" -->
  - <!--#if expr="$QUERY_STRING = TOC" -->
  -  <!--#set var="TOC" value="YES" -->
  -  <!--#set var="CONTENT" value="" -->
  - <!--#else -->
  -  <!--#set var="TOC" value="" -->
  -  <!--#set var="CONTENT" value="YES" -->
  - <!--#endif -->
  +<!--#set var="STANDALONE" value="" -->
  +<!--#set var="INCLUDED" value="YES" -->
  +<!--#if expr="$QUERY_STRING = TOC" -->
  +<!--#set var="TOC" value="YES" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#else -->
  - <!--#set var="STANDALONE" value="YES" -->
  - <!--#set var="INCLUDED" value="" -->
  - <!--#set var="TOC" value="" -->
  - <!--#set var="CONTENT" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="YES" -->
   <!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  - <HEAD>
  -  <TITLE>Apache Server Frequently Asked Questions</TITLE>
  - </HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  - <BODY
  -  BGCOLOR="#FFFFFF"
  -  TEXT="#000000"
  -  LINK="#0000FF"
  -  VLINK="#000080"
  -  ALINK="#FF0000"
  - >
  -  <!--#include virtual="header.html" -->
  -  <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>
  -  <P>
  -  $Revision: 1.13 $ ($Date: 2000/12/14 15:40:49 $)
  -  </P>
  -  <P>
  -  The latest version of this FAQ is always available from the main
  -  Apache web site, at
  -  &lt;<A
  -       HREF="http://httpd.apache.org/docs/misc/FAQ.html"
  -       REL="Help"
  -      ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>&gt;.
  -  </P>
  -<!-- Notes about changes:                                           -->
  -<!--  - If adding a relative link to another part of the            -->
  -<!--    documentation, *do* include the ".html" portion.  There's a -->
  -<!--    good chance that the user will be reading the documentation -->
  -<!--    on his own system, which may not be configured for          -->
  -<!--    multiviews.                                                 -->
  -<!--  - When adding items, make sure they're put in the right place -->
  -<!--    - verify that the numbering matches up.                     -->
  -<!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  -<!--    correctly in a reliable way when this is converted to text  -->
  -<!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  -<!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  -<!--    the horizontal and vertical indenting right.                -->
  -<!--  - Don't forget to include an HR tag after the last /P tag     -->
  -<!--    but before the /LI in an item.                              -->
  -  <P>
  -  If you are reading a text-only version of this FAQ, you may find numbers
  -  enclosed in brackets (such as &quot;[12]&quot;).  These refer to the list of
  -  reference URLs to be found at the end of the document.  These references
  -  do not appear, and are not needed, for the hypertext version.
  -  </P>
  -  <H2>The Questions</H2>
  -<OL TYPE="A">
  -<!--#endif -->
  -<!--#if expr="$TOC || $STANDALONE" -->
  - <LI VALUE="4"><STRONG>Error Log Messages and Problems Starting Apache</STRONG>
  -  <OL>
  -   <LI><A HREF="#setgid">Why do I get &quot;<SAMP>setgid: Invalid
  -        argument</SAMP>&quot; at startup?</A>
  -   </LI>
  -   <LI><A HREF="#nodelay">Why am I getting &quot;<SAMP>httpd: could not
  -        set socket option TCP_NODELAY</SAMP>&quot; in my error log?</A>
  -   </LI>
  -   <LI><A HREF="#peerreset">Why am I getting &quot;<SAMP>connection
  -        reset by peer</SAMP>&quot; in my error log?</A>
  -   </LI>
  -   <LI><A HREF="#wheres-the-dump">The errorlog says Apache dumped core,
  -        but where's the dump file?</A>
  -   </LI>
  -   <LI><A HREF="#linux-shmget">When I run it under Linux I get &quot;shmget:
  -        function not found&quot;, what should I do?</A>
  -   </LI>
  -   <LI><A HREF="#nfslocking">Server hangs, or fails to start, and/or error log
  -        fills with &quot;<SAMP>fcntl: F_SETLKW: No record locks
  -        available</SAMP>&quot; or similar messages</A>
  -   </LI>
  -   <LI><A HREF="#aixccbug">Why am I getting "<SAMP>Expected &lt;/Directory&gt;
  -        but saw &lt;/Directory&gt;</SAMP>" when I try to start Apache?</A>
  -   </LI>
  -   <LI><A HREF="#redhat">I'm using RedHat Linux and I have problems with httpd
  -        dying randomly or not restarting properly</A>
  -   </LI>
  -   <LI><A HREF="#stopping">I upgraded from an Apache version earlier
  -        than 1.2.0 and suddenly I have problems with Apache dying randomly
  -        or not restarting properly</A>
  -   </LI>
  -   <LI><A HREF="#setservername">When I try to start Apache from a DOS
  -        window, I get a message like "<samp>Cannot determine host name.
  -	Use ServerName directive to set it manually.</samp>"  What does
  -	this mean?</A>
  -   </LI>
  -   <LI><A HREF="#ws2_32dll">When I try to start Apache for Windows, I get
  -        a message like "<samp>Unable To Locate WS2_32.DLL...</samp>". What
  -	should I do?</A>
  -   </LI>
  -   <LI><A HREF="#WSADuplicateSocket">Apache for Windows does not start.
  -        Error log contains this message "<samp>[crit] (10045) The attempted
  -	operation is not supported for the type of object referenced: Parent:
  -	WSADuplicateSocket failed for socket ###</samp>".  What does this
  -	mean?</a>
  -   </LI>
  -   <li><a href="#err1067">When I try to start Apache on Windows, I get
  -        a message like &quot;<code>System error 1067 has occurred.  The process
  -	terminated unexpectedly.</code>&quot;  What does this mean?</a>
  -   </li>
  -  </OL>
  - </LI>
  +<!--#else -->
  +<!--#set var="STANDALONE" value="YES" -->
  +<!--#set var="INCLUDED" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#endif -->
   <!--#if expr="$STANDALONE" -->
  -</OL>
  -
  -<HR>
  -
  -  <H2>The Answers</H2>
  -<!--#endif -->
  -<!--#if expr="! $TOC" -->
  -
  -  <H3>D. Error Log Messages and Problems Starting Apache</H3>
  -<OL>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  - <LI><A NAME="setgid">
  -      <STRONG>Why do I get &quot;<SAMP>setgid: Invalid
  -      argument</SAMP>&quot; at startup?</STRONG>
  -     </A>
  -  <P>
  -  Your
  -  <A HREF="../mod/core.html#group"><SAMP>Group</SAMP></A>
  -  directive (probably in <SAMP>conf/httpd.conf</SAMP>) needs to name a
  -  group that actually exists in the <SAMP>/etc/group</SAMP> file (or
  -  your system's equivalent).  This problem is also frequently seen when
  -  a negative number is used in the <CODE>Group</CODE> directive
  -  (<EM>e.g.</EM>, "<CODE>Group&nbsp;#-1</CODE>").  Using a group name
  -  -- not group number -- found in your system's group database should
  -  solve this problem in all cases.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="nodelay">
  -      <STRONG>Why am I getting &quot;<SAMP>httpd: could not set socket
  -      option TCP_NODELAY</SAMP>&quot; in my error log?</STRONG>
  -     </A>
  -  <P>
  -  This message almost always indicates that the client disconnected
  -  before Apache reached the point of calling <CODE>setsockopt()</CODE>
  -  for the connection.  It shouldn't occur for more than about 1% of the
  -  requests your server handles, and it's advisory only in any case.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="peerreset">
  -      <STRONG>Why am I getting &quot;<SAMP>connection reset by
  -      peer</SAMP>&quot; in my error log?</STRONG>
  -     </A>
  -  <P>
  -  This is a normal message and nothing about which to be alarmed.  It simply
  -  means that the client canceled the connection before it had been
  -  completely set up - such as by the end-user pressing the &quot;Stop&quot;
  -  button.  People's patience being what it is, sites with response-time
  -  problems or slow network links may experiences this more than
  -  high-capacity ones or those with large pipes to the network.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="wheres-the-dump">
  -      <STRONG>The errorlog says Apache dumped core, but where's the dump
  -      file?</STRONG>
  -     </A>
  -  <P>
  -  In Apache version 1.2, the error log message
  -  about dumped core includes the directory where the dump file should be
  -  located.  However, many Unixes do not allow a process that has
  -  called <CODE>setuid()</CODE> to dump core for security reasons;
  -  the typical Apache setup has the server started as root to bind to
  -  port 80, after which it changes UIDs to a non-privileged user to
  -  serve requests.
  -  </P>
  -  <P>
  -  Dealing with this is extremely operating system-specific, and may
  -  require rebuilding your system kernel.  Consult your operating system
  -  documentation or vendor for more information about whether your system
  -  does this and how to bypass it.  If there <EM>is</EM> a documented way
  -  of bypassing it, it is recommended that you bypass it only for the
  -  <SAMP>httpd</SAMP> server process if possible.
  -  </P>
  -  <P>
  -  The canonical location for Apache's core-dump files is the
  -  <A HREF="../mod/core.html#serverroot">ServerRoot</A>
  -  directory. As of Apache version 1.3, the location can be set <EM>via</EM>
  -  the
  -  <A HREF="../mod/core.html#coredumpdirectory"
  -  ><SAMP>CoreDumpDirectory</SAMP></A>
  -  directive to a different directory. Make sure that this directory is
  -  writable by the user the server runs as (as opposed to the user the server
  -  is <EM>started</EM> as).
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="linux-shmget">
  -      <STRONG>When I run it under Linux I get &quot;shmget:
  -      function not found&quot;, what should I do?</STRONG>
  -     </A>
  -  <P>
  -  Your kernel has been built without SysV IPC support.  You will have
  -  to rebuild the kernel with that support enabled (it's under the
  -  &quot;General Setup&quot; submenu).  Documentation for kernel
  -  building is beyond the scope of this FAQ; you should consult the <A
  -  HREF="http://www.redhat.com/mirrors/LDP/HOWTO/Kernel-HOWTO.html">Kernel
  -  HOWTO</A>, or the documentation provided with your distribution, or
  -  a <A HREF="http://www.redhat.com/mirrors/LDP/HOWTO/META-FAQ.html">Linux
  -  newsgroup/mailing list</A>.  As a last-resort workaround, you can
  -  comment out the <CODE>#define&nbsp;USE_SHMGET_SCOREBOARD</CODE>
  -  definition in the <SAMP>LINUX</SAMP> section of
  -  <SAMP>src/conf.h</SAMP> and rebuild the server (prior to 1.3b4,
  -  simply removing <CODE>#define&nbsp;HAVE_SHMGET</CODE> would have
  -  sufficed).  This will produce a server which is slower and less
  -  reliable.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="nfslocking">
  -      <STRONG>Server hangs, or fails to start, and/or error log
  -      fills with &quot;<SAMP>fcntl: F_SETLKW: No record locks
  -      available</SAMP>&quot; or similar messages</STRONG>
  -     </A>
  -
  -  <P>
  -  These are symptoms of a fine locking problem, which usually means that
  -  the server is trying to use a synchronization file on an NFS filesystem.
  -  </P>
  -  <P>
  -  Because of its parallel-operation model, the Apache Web server needs to
  -  provide some form of synchronization when accessing certain resources.
  -  One of these synchronization methods involves taking out locks on a file,
  -  which means that the filesystem whereon the lockfile resides must support
  -  locking.  In many cases this means it <EM>can't</EM> be kept on an
  -  NFS-mounted filesystem.
  -  </P>
  -  <P>
  -  To cause the Web server to work around the NFS locking limitations, include
  -  a line such as the following in your server configuration files:
  -  </P>
  -  <DL>
  -   <DD><CODE>LockFile /var/run/apache-lock</CODE>
  -   </DD>
  -  </DL>
  -  <P>
  -  The directory should not be generally writable (<EM>e.g.</EM>, don't use
  -  <SAMP>/var/tmp</SAMP>).
  -  See the <A HREF="../mod/core.html#lockfile"><SAMP>LockFile</SAMP></A>
  -  documentation for more information.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="aixccbug"><STRONG>Why am I getting "<SAMP>Expected
  -       &lt;/Directory&gt; but saw &lt;/Directory&gt;</SAMP>" when
  -       I try to start Apache?</STRONG></A>
  -   <P>
  -   This is a known problem with certain versions of the AIX C compiler.
  -   IBM are working on a solution, and the issue is being tracked by
  -   <A HREF="http://bugs.apache.org/index/full/2312">problem report #2312</A>.
  -   </P>
  -   <HR>
  - </LI>
  -
  - <LI><A NAME="redhat">
  -      <STRONG>I'm using RedHat Linux and I have problems with httpd
  -      dying randomly or not restarting properly</STRONG>
  -     </A>
  -
  -  <P>
  -  RedHat Linux versions 4.x (and possibly earlier) RPMs contain
  -  various nasty scripts which do not stop or restart Apache properly.
  -  These can affect you even if you're not running the RedHat supplied
  -  RPMs.
  -  </P>
  -  <P>
  -  If you're using the default install then you're probably running
  -  Apache 1.1.3, which is outdated.  From RedHat's ftp site you can
  -  pick up a more recent RPM for Apache 1.2.x.  This will solve one of
  -  the problems.
  -  </P>
  -  <P>
  -  If you're using a custom built Apache rather than the RedHat RPMs
  -  then you should <CODE>rpm -e apache</CODE>.  In particular you want
  -  the mildly broken <CODE>/etc/logrotate.d/apache</CODE> script to be
  -  removed, and you want the broken <CODE>/etc/rc.d/init.d/httpd</CODE>
  -  (or <CODE>httpd.init</CODE>) script to be removed.  The latter is
  -  actually fixed by the apache-1.2.5 RPMs but if you're building your
  -  own Apache then you probably don't want the RedHat files.
  -  </P>
  -  <P>
  -  We can't stress enough how important it is for folks, <EM>especially
  -  vendors</EM> to follow the <A HREF="../stopping.html">stopping Apache
  -  directions</A> given in our documentation.  In RedHat's defense,
  -  the broken scripts were necessary with Apache 1.1.x because the
  -  Linux support in 1.1.x was very poor, and there were various race
  -  conditions on all platforms.  None of this should be necessary with
  -  Apache 1.2 and later.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="stopping">
  -      <STRONG>I upgraded from an Apache version earlier
  -      than 1.2.0 and suddenly I have problems with Apache dying randomly
  -      or not restarting properly</STRONG>
  -     </A>
  -
  -  <P>
  -  You should read <A HREF="#redhat">the previous note</A> about
  -  problems with RedHat installations.  It is entirely likely that your
  -  installation has start/stop/restart scripts which were built for
  -  an earlier version of Apache.  Versions earlier than 1.2.0 had
  -  various race conditions that made it necessary to use
  -  <CODE>kill -9</CODE> at times to take out all the httpd servers.
  -  But that should not be necessary any longer.  You should follow
  -  the <A HREF="../stopping.html">directions on how to stop
  -  and restart Apache</A>.
  -  </P>
  -  <P>As of Apache 1.3 there is a script
  -  <CODE>src/support/apachectl</CODE> which, after a bit of
  -  customization, is suitable for starting, stopping, and restarting
  -  your server.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A name="setservername">
  -       <b>When I try to start Apache from a DOS
  -       window, I get a message like "<samp>Cannot determine host name.
  -       Use ServerName directive to set it manually.</samp>"  What does
  -       this mean?</b></A>
  -
  -  <p>
  -  It means what it says; the Apache software can't determine the
  -  hostname of your system.  Edit your <samp>conf\httpd.conf</samp>
  -  file, look for the string "ServerName", and make sure there's an
  -  uncommented directive such as
  -  </p>
  -  <dl>
  -   <dd><code>ServerName localhost</code></dd>
  -  </dl>
  -  <p>
  -  or
  -  </p>
  -  <dl>
  -   <dd><code>ServerName www.foo.com</code></dd>
  -  </dl>
  -  <p>
  -  in the file.  Correct it if there one there with wrong information, or
  -  add one if you don't already have one.
  -  </p>
  -  <p>
  -  Also, make sure that your Windows system has DNS enabled.  See the TCP/IP
  -  setup component of the Networking or Internet Options control panel.
  -  </p>
  -  <p>
  -  After verifying that DNS is enabled and that you have a valid hostname
  -  in your <samp>ServerName</samp> directive, try to start the server
  -  again.
  -  </p>
  -  <hr>
  - </LI>
  - <LI><A name="ws2_32dll">
  -       <b>When I try to start Apache for Windows, I get a message
  -	like "<samp>Unable To Locate WS2_32.DLL...</samp>". What should I do?</b></A>
  -  <p>
  -  Short answer: You need to install Winsock 2, available from
  -  <A HREF="http://www.microsoft.com/windows95/downloads/">http://www.microsoft.com/windows95/downloads/</A>
  -  </p>
  -  <p>
  -  Detailed answer: Prior to version 1.3.9, Apache for Windows used Winsock
  -  1.1. Beginning with version 1.3.9, Apache began using Winsock 2 features
  -  (specifically, WSADuplicateSocket()).
  -  WS2_32.DLL implements the Winsock 2 API. Winsock 2 ships with Windows
  -  NT 4.0 and Windows 98.  Some of the earlier releases of Windows 95 did
  -  not include Winsock 2.
  -  </p>
  -  <hr>
  - </LI>
  - <LI><A name="WSADuplicateSocket">
  -      <b>Apache for Windows does not start. Error log contains this message:
  -      "<samp>[crit] (10045) The attempted operation is not supported for
  -      the type of object referenced: Parent: WSADuplicateSocket failed for
  -      socket ###</samp>".  What does this mean?</b></A>
  -  <p>
  -  We have seen this problem when Apache is run on systems along with
  -  Virtual Private Networking clients like Aventail Connect. Aventail Connect
  -  is a Layered Service Provider (LSP) that inserts itself, as a "shim,"
  -  between the Winsock 2 API and Window's native Winsock 2 implementation.
  -  The Aventail Connect shim does not implement WSADuplicateSocket, which is
  -  the cause of the failure.
  -  </p>
  -  <p>
  -  The shim is not unloaded when Aventail Connect is shut down. Once
  -  observed, the problem persists until the shim is either explicitly
  -  unloaded or the machine is rebooted. Instructions for temporarily
  -  removing the Aventail Connect V3.x shim can be found here:
  -  "<a href="http://support.aventail.com/akb/article00386.html"
  -   >How to Remove Aventail Connect v3.x from the LSP Order for Testing
  -    Purposes</a>."
  -  </p>
  -  <p>
  -  Another potential solution (not tested) is to add <code>apache.exe</code>
  -  to the Aventail "Connect Exclusion List".  See this link for details:
  -  "<a href="http://support.aventail.com/akb/article00586.html"
  -   >How to Add an Application to Aventail Connect's Application Exclusion
  -    List</a>."
  -  </p>
  -  <p>
  -  Apache is affected in a similar way by <em>any</em> firewall program that
  -  isn't correctly configured.  Assure you exclude your Apache server ports
  -  (usually port 80) from the list of ports to block.  Refer to your firewall
  -  program's documentation for the how-to.
  -  </p>
  -  <hr>
  - </LI>
  - <li><a name="err1067"><b>When I try to start Apache on Windows, I get
  -      a message like &quot;<code>System error 1067 has occurred.  The process
  -      terminated unexpectedly</code>.&quot;  What does this mean?</b></a>
  -  <p>
  -  This message means that the Web server was unable to start correctly
  -  for one reason or another.  To find out why, execute the following
  -  commands in a DOS window:
  -  </p>
  -  <pre>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Server Frequently Asked Questions</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache Server Frequently Asked
  +    Questions</h1>
  +
  +    <p>$Revision: 1.14 $ ($Date: 2001/10/08 01:26:54 $)</p>
  +
  +    <p>The latest version of this FAQ is always available from the
  +    main Apache web site, at &lt;<a
  +    href="http://httpd.apache.org/docs/misc/FAQ.html"
  +    rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>&gt;.</p>
  +    <!-- Notes about changes:                                           -->
  +    <!--  - If adding a relative link to another part of the            -->
  +    <!--    documentation, *do* include the ".html" portion.  There's a -->
  +    <!--    good chance that the user will be reading the documentation -->
  +    <!--    on his own system, which may not be configured for          -->
  +    <!--    multiviews.                                                 -->
  +    <!--  - When adding items, make sure they're put in the right place -->
  +    <!--    - verify that the numbering matches up.                     -->
  +    <!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  +    <!--    correctly in a reliable way when this is converted to text  -->
  +    <!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  +    <!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  +    <!--    the horizontal and vertical indenting right.                -->
  +    <!--  - Don't forget to include an HR tag after the last /P tag     -->
  +    <!--    but before the /LI in an item.                              -->
  +
  +    <p>If you are reading a text-only version of this FAQ, you may
  +    find numbers enclosed in brackets (such as "[12]"). These refer
  +    to the list of reference URLs to be found at the end of the
  +    document. These references do not appear, and are not needed,
  +    for the hypertext version.</p>
  +
  +    <h2>The Questions</h2>
  +
  +    <ol type="A">
  +      <!--#endif -->
  +      <!--#if expr="$TOC || $STANDALONE" -->
  +
  +      <li value="4">
  +        <strong>Error Log Messages and Problems Starting
  +        Apache</strong> 
  +
  +        <ol>
  +          <li><a href="#setgid">Why do I get "<samp>setgid: Invalid
  +          argument</samp>" at startup?</a></li>
  +
  +          <li><a href="#nodelay">Why am I getting "<samp>httpd:
  +          could not set socket option TCP_NODELAY</samp>" in my
  +          error log?</a></li>
  +
  +          <li><a href="#peerreset">Why am I getting
  +          "<samp>connection reset by peer</samp>" in my error
  +          log?</a></li>
  +
  +          <li><a href="#wheres-the-dump">The errorlog says Apache
  +          dumped core, but where's the dump file?</a></li>
  +
  +          <li><a href="#linux-shmget">When I run it under Linux I
  +          get "shmget: function not found", what should I
  +          do?</a></li>
  +
  +          <li><a href="#nfslocking">Server hangs, or fails to
  +          start, and/or error log fills with "<samp>fcntl:
  +          F_SETLKW: No record locks available</samp>" or similar
  +          messages</a></li>
  +
  +          <li><a href="#aixccbug">Why am I getting "<samp>Expected
  +          &lt;/Directory&gt; but saw &lt;/Directory&gt;</samp>"
  +          when I try to start Apache?</a></li>
  +
  +          <li><a href="#redhat">I'm using RedHat Linux and I have
  +          problems with httpd dying randomly or not restarting
  +          properly</a></li>
  +
  +          <li><a href="#stopping">I upgraded from an Apache version
  +          earlier than 1.2.0 and suddenly I have problems with
  +          Apache dying randomly or not restarting properly</a></li>
  +
  +          <li><a href="#setservername">When I try to start Apache
  +          from a DOS window, I get a message like "<samp>Cannot
  +          determine host name. Use ServerName directive to set it
  +          manually.</samp>" What does this mean?</a></li>
  +
  +          <li><a href="#ws2_32dll">When I try to start Apache for
  +          Windows, I get a message like "<samp>Unable To Locate
  +          WS2_32.DLL...</samp>". What should I do?</a></li>
  +
  +          <li><a href="#WSADuplicateSocket">Apache for Windows does
  +          not start. Error log contains this message "<samp>[crit]
  +          (10045) The attempted operation is not supported for the
  +          type of object referenced: Parent: WSADuplicateSocket
  +          failed for socket ###</samp>". What does this
  +          mean?</a></li>
  +
  +          <li><a href="#err1067">When I try to start Apache on
  +          Windows, I get a message like "<code>System error 1067
  +          has occurred. The process terminated
  +          unexpectedly.</code>" What does this mean?</a></li>
  +        </ol>
  +      </li>
  +      <!--#endif -->
  +      <!--#if expr="$STANDALONE" -->
  +    </ol>
  +    <hr />
  +
  +    <h2>The Answers</h2>
  +    <!--#endif -->
  +    <!--#if expr="! $TOC" -->
  +
  +    <h3>D. Error Log Messages and Problems Starting Apache</h3>
  +
  +    <ol>
  +      <li>
  +        <a id="setgid" name="setgid"><strong>Why do I get
  +        "<samp>setgid: Invalid argument</samp>" at
  +        startup?</strong></a> 
  +
  +        <p>Your <a
  +        href="../mod/core.html#group"><samp>Group</samp></a>
  +        directive (probably in <samp>conf/httpd.conf</samp>) needs
  +        to name a group that actually exists in the
  +        <samp>/etc/group</samp> file (or your system's equivalent).
  +        This problem is also frequently seen when a negative number
  +        is used in the <code>Group</code> directive (<em>e.g.</em>,
  +        "<code>Group&nbsp;#-1</code>"). Using a group name -- not
  +        group number -- found in your system's group database
  +        should solve this problem in all cases.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="nodelay" name="nodelay"><strong>Why am I getting
  +        "<samp>httpd: could not set socket option
  +        TCP_NODELAY</samp>" in my error log?</strong></a> 
  +
  +        <p>This message almost always indicates that the client
  +        disconnected before Apache reached the point of calling
  +        <code>setsockopt()</code> for the connection. It shouldn't
  +        occur for more than about 1% of the requests your server
  +        handles, and it's advisory only in any case.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="peerreset" name="peerreset"><strong>Why am I getting
  +        "<samp>connection reset by peer</samp>" in my error
  +        log?</strong></a> 
  +
  +        <p>This is a normal message and nothing about which to be
  +        alarmed. It simply means that the client canceled the
  +        connection before it had been completely set up - such as
  +        by the end-user pressing the "Stop" button. People's
  +        patience being what it is, sites with response-time
  +        problems or slow network links may experiences this more
  +        than high-capacity ones or those with large pipes to the
  +        network.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="wheres-the-dump" name="wheres-the-dump"><strong>The
  +        errorlog says Apache dumped core, but where's the dump
  +        file?</strong></a> 
  +
  +        <p>In Apache version 1.2, the error log message about
  +        dumped core includes the directory where the dump file
  +        should be located. However, many Unixes do not allow a
  +        process that has called <code>setuid()</code> to dump core
  +        for security reasons; the typical Apache setup has the
  +        server started as root to bind to port 80, after which it
  +        changes UIDs to a non-privileged user to serve
  +        requests.</p>
  +
  +        <p>Dealing with this is extremely operating
  +        system-specific, and may require rebuilding your system
  +        kernel. Consult your operating system documentation or
  +        vendor for more information about whether your system does
  +        this and how to bypass it. If there <em>is</em> a
  +        documented way of bypassing it, it is recommended that you
  +        bypass it only for the <samp>httpd</samp> server process if
  +        possible.</p>
  +
  +        <p>The canonical location for Apache's core-dump files is
  +        the <a href="../mod/core.html#serverroot">ServerRoot</a>
  +        directory. As of Apache version 1.3, the location can be
  +        set <em>via</em> the <a
  +        href="../mod/core.html#coredumpdirectory"><samp>CoreDumpDirectory</samp></a>
  +        directive to a different directory. Make sure that this
  +        directory is writable by the user the server runs as (as
  +        opposed to the user the server is <em>started</em> as).</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="linux-shmget" name="linux-shmget"><strong>When I run
  +        it under Linux I get "shmget: function not found", what
  +        should I do?</strong></a> 
  +
  +        <p>Your kernel has been built without SysV IPC support. You
  +        will have to rebuild the kernel with that support enabled
  +        (it's under the "General Setup" submenu). Documentation for
  +        kernel building is beyond the scope of this FAQ; you should
  +        consult the <a
  +        href="http://www.redhat.com/mirrors/LDP/HOWTO/Kernel-HOWTO.html">
  +        Kernel HOWTO</a>, or the documentation provided with your
  +        distribution, or a <a
  +        href="http://www.redhat.com/mirrors/LDP/HOWTO/META-FAQ.html">
  +        Linux newsgroup/mailing list</a>. As a last-resort
  +        workaround, you can comment out the
  +        <code>#define&nbsp;USE_SHMGET_SCOREBOARD</code> definition
  +        in the <samp>LINUX</samp> section of
  +        <samp>src/conf.h</samp> and rebuild the server (prior to
  +        1.3b4, simply removing
  +        <code>#define&nbsp;HAVE_SHMGET</code> would have sufficed).
  +        This will produce a server which is slower and less
  +        reliable.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="nfslocking" name="nfslocking"><strong>Server hangs,
  +        or fails to start, and/or error log fills with
  +        "<samp>fcntl: F_SETLKW: No record locks available</samp>"
  +        or similar messages</strong></a> 
  +
  +        <p>These are symptoms of a fine locking problem, which
  +        usually means that the server is trying to use a
  +        synchronization file on an NFS filesystem.</p>
  +
  +        <p>Because of its parallel-operation model, the Apache Web
  +        server needs to provide some form of synchronization when
  +        accessing certain resources. One of these synchronization
  +        methods involves taking out locks on a file, which means
  +        that the filesystem whereon the lockfile resides must
  +        support locking. In many cases this means it <em>can't</em>
  +        be kept on an NFS-mounted filesystem.</p>
  +
  +        <p>To cause the Web server to work around the NFS locking
  +        limitations, include a line such as the following in your
  +        server configuration files:</p>
  +
  +        <dl>
  +          <dd><code>LockFile /var/run/apache-lock</code></dd>
  +        </dl>
  +
  +        <p>The directory should not be generally writable
  +        (<em>e.g.</em>, don't use <samp>/var/tmp</samp>). See the
  +        <a
  +        href="../mod/core.html#lockfile"><samp>LockFile</samp></a>
  +        documentation for more information.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="aixccbug" name="aixccbug"><strong>Why am I getting
  +        "<samp>Expected &lt;/Directory&gt; but saw
  +        &lt;/Directory&gt;</samp>" when I try to start
  +        Apache?</strong></a> 
  +
  +        <p>This is a known problem with certain versions of the AIX
  +        C compiler. IBM are working on a solution, and the issue is
  +        being tracked by <a
  +        href="http://bugs.apache.org/index/full/2312">problem
  +        report #2312</a>.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="redhat" name="redhat"><strong>I'm using RedHat Linux
  +        and I have problems with httpd dying randomly or not
  +        restarting properly</strong></a> 
  +
  +        <p>RedHat Linux versions 4.x (and possibly earlier) RPMs
  +        contain various nasty scripts which do not stop or restart
  +        Apache properly. These can affect you even if you're not
  +        running the RedHat supplied RPMs.</p>
  +
  +        <p>If you're using the default install then you're probably
  +        running Apache 1.1.3, which is outdated. From RedHat's ftp
  +        site you can pick up a more recent RPM for Apache 1.2.x.
  +        This will solve one of the problems.</p>
  +
  +        <p>If you're using a custom built Apache rather than the
  +        RedHat RPMs then you should <code>rpm -e apache</code>. In
  +        particular you want the mildly broken
  +        <code>/etc/logrotate.d/apache</code> script to be removed,
  +        and you want the broken <code>/etc/rc.d/init.d/httpd</code>
  +        (or <code>httpd.init</code>) script to be removed. The
  +        latter is actually fixed by the apache-1.2.5 RPMs but if
  +        you're building your own Apache then you probably don't
  +        want the RedHat files.</p>
  +
  +        <p>We can't stress enough how important it is for folks,
  +        <em>especially vendors</em> to follow the <a
  +        href="../stopping.html">stopping Apache directions</a>
  +        given in our documentation. In RedHat's defense, the broken
  +        scripts were necessary with Apache 1.1.x because the Linux
  +        support in 1.1.x was very poor, and there were various race
  +        conditions on all platforms. None of this should be
  +        necessary with Apache 1.2 and later.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="stopping" name="stopping"><strong>I upgraded from an
  +        Apache version earlier than 1.2.0 and suddenly I have
  +        problems with Apache dying randomly or not restarting
  +        properly</strong></a> 
  +
  +        <p>You should read <a href="#redhat">the previous note</a>
  +        about problems with RedHat installations. It is entirely
  +        likely that your installation has start/stop/restart
  +        scripts which were built for an earlier version of Apache.
  +        Versions earlier than 1.2.0 had various race conditions
  +        that made it necessary to use <code>kill -9</code> at times
  +        to take out all the httpd servers. But that should not be
  +        necessary any longer. You should follow the <a
  +        href="../stopping.html">directions on how to stop and
  +        restart Apache</a>.</p>
  +
  +        <p>As of Apache 1.3 there is a script
  +        <code>src/support/apachectl</code> which, after a bit of
  +        customization, is suitable for starting, stopping, and
  +        restarting your server.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="setservername" name="setservername"><b>When I try to
  +        start Apache from a DOS window, I get a message like
  +        "<samp>Cannot determine host name. Use ServerName directive
  +        to set it manually.</samp>" What does this mean?</b></a> 
  +
  +        <p>It means what it says; the Apache software can't
  +        determine the hostname of your system. Edit your
  +        <samp>conf\httpd.conf</samp> file, look for the string
  +        "ServerName", and make sure there's an uncommented
  +        directive such as</p>
  +
  +        <dl>
  +          <dd><code>ServerName localhost</code></dd>
  +        </dl>
  +
  +        <p>or</p>
  +
  +        <dl>
  +          <dd><code>ServerName www.foo.com</code></dd>
  +        </dl>
  +
  +        <p>in the file. Correct it if there one there with wrong
  +        information, or add one if you don't already have one.</p>
  +
  +        <p>Also, make sure that your Windows system has DNS
  +        enabled. See the TCP/IP setup component of the Networking
  +        or Internet Options control panel.</p>
  +
  +        <p>After verifying that DNS is enabled and that you have a
  +        valid hostname in your <samp>ServerName</samp> directive,
  +        try to start the server again.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="ws2_32dll" name="ws2_32dll"><b>When I try to start
  +        Apache for Windows, I get a message like "<samp>Unable To
  +        Locate WS2_32.DLL...</samp>". What should I do?</b></a> 
  +
  +        <p>Short answer: You need to install Winsock 2, available
  +        from <a
  +        href="http://www.microsoft.com/windows95/downloads/">http://www.microsoft.com/windows95/downloads/</a></p>
  +
  +        <p>Detailed answer: Prior to version 1.3.9, Apache for
  +        Windows used Winsock 1.1. Beginning with version 1.3.9,
  +        Apache began using Winsock 2 features (specifically,
  +        WSADuplicateSocket()). WS2_32.DLL implements the Winsock 2
  +        API. Winsock 2 ships with Windows NT 4.0 and Windows 98.
  +        Some of the earlier releases of Windows 95 did not include
  +        Winsock 2.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="WSADuplicateSocket"
  +        name="WSADuplicateSocket"><b>Apache for Windows does not
  +        start. Error log contains this message: "<samp>[crit]
  +        (10045) The attempted operation is not supported for the
  +        type of object referenced: Parent: WSADuplicateSocket
  +        failed for socket ###</samp>". What does this mean?</b></a>
  +        
  +
  +        <p>We have seen this problem when Apache is run on systems
  +        along with Virtual Private Networking clients like Aventail
  +        Connect. Aventail Connect is a Layered Service Provider
  +        (LSP) that inserts itself, as a "shim," between the Winsock
  +        2 API and Window's native Winsock 2 implementation. The
  +        Aventail Connect shim does not implement
  +        WSADuplicateSocket, which is the cause of the failure.</p>
  +
  +        <p>The shim is not unloaded when Aventail Connect is shut
  +        down. Once observed, the problem persists until the shim is
  +        either explicitly unloaded or the machine is rebooted.
  +        Instructions for temporarily removing the Aventail Connect
  +        V3.x shim can be found here: "<a
  +        href="http://support.aventail.com/akb/article00386.html">How
  +        to Remove Aventail Connect v3.x from the LSP Order for
  +        Testing Purposes</a>."</p>
  +
  +        <p>Another potential solution (not tested) is to add
  +        <code>apache.exe</code> to the Aventail "Connect Exclusion
  +        List". See this link for details: "<a
  +        href="http://support.aventail.com/akb/article00586.html">How
  +        to Add an Application to Aventail Connect's Application
  +        Exclusion List</a>."</p>
  +
  +        <p>Apache is affected in a similar way by <em>any</em>
  +        firewall program that isn't correctly configured. Assure
  +        you exclude your Apache server ports (usually port 80) from
  +        the list of ports to block. Refer to your firewall
  +        program's documentation for the how-to.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="err1067" name="err1067"><b>When I try to start
  +        Apache on Windows, I get a message like "<code>System error
  +        1067 has occurred. The process terminated
  +        unexpectedly</code>." What does this mean?</b></a> 
  +
  +        <p>This message means that the Web server was unable to
  +        start correctly for one reason or another. To find out why,
  +        execute the following commands in a DOS window:</p>
  +<pre>
       c:
       cd "\Program Files\Apache Group\Apache"
       apache
  -  </pre>
  -  <p>
  -  (If you don't get the prompt back, hit Control-C to cause Apache to
  -  exit.)
  -  </p>
  -  <p>
  -  The error you see will probably be one of those preceding this question
  -  in the FAQ.
  -  </p>
  -  <p>
  -  As of Apache 1.3.14, first check the Windows NT Event Log for
  -  Application errors using the Windows NT/2000 Event Viewer program.
  -  Any errors that occur prior to opening the Apache error log will
  -  be stored here, if Apache is run as a Service on NT or 2000.  As with
  -  any error, also check your Apache error log.
  -  <hr>
  - </li>
  -</OL>
  -<!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -  <!-- Don't forget to add HR tags at the end of each list item.. -->
  + 
  +</pre>
   
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  -<!--#endif -->
  +        <p>(If you don't get the prompt back, hit Control-C to
  +        cause Apache to exit.)</p>
  +
  +        <p>The error you see will probably be one of those
  +        preceding this question in the FAQ.</p>
  +
  +        <p>As of Apache 1.3.14, first check the Windows NT Event
  +        Log for Application errors using the Windows NT/2000 Event
  +        Viewer program. Any errors that occur prior to opening the
  +        Apache error log will be stored here, if Apache is run as a
  +        Service on NT or 2000. As with any error, also check your
  +        Apache error log.</p>
  +        <hr />
  +      </li>
  +    </ol>
  +    <!--#endif -->
  +    <!--#if expr="$STANDALONE" -->
  +    <!-- Don't forget to add HR tags at the end of each list item.. -->
  +    <!--#include virtual="footer.html" -->
  +    <!--#endif -->
  +  </body>
  +</html>
  +
  
  
  
  1.11      +653 -647  httpd-docs-1.3/htdocs/manual/misc/FAQ-E.html
  
  Index: FAQ-E.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/FAQ-E.html,v
  retrieving revision 1.10
  retrieving revision 1.11
  diff -u -r1.10 -r1.11
  --- FAQ-E.html	2001/02/28 03:45:23	1.10
  +++ FAQ-E.html	2001/10/08 01:26:54	1.11
  @@ -1,654 +1,660 @@
   <!--#if expr="$FAQMASTER" -->
  - <!--#set var="STANDALONE" value="" -->
  - <!--#set var="INCLUDED" value="YES" -->
  - <!--#if expr="$QUERY_STRING = TOC" -->
  -  <!--#set var="TOC" value="YES" -->
  -  <!--#set var="CONTENT" value="" -->
  - <!--#else -->
  -  <!--#set var="TOC" value="" -->
  -  <!--#set var="CONTENT" value="YES" -->
  - <!--#endif -->
  +<!--#set var="STANDALONE" value="" -->
  +<!--#set var="INCLUDED" value="YES" -->
  +<!--#if expr="$QUERY_STRING = TOC" -->
  +<!--#set var="TOC" value="YES" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#else -->
  - <!--#set var="STANDALONE" value="YES" -->
  - <!--#set var="INCLUDED" value="" -->
  - <!--#set var="TOC" value="" -->
  - <!--#set var="CONTENT" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="YES" -->
   <!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  - <HEAD>
  -  <TITLE>Apache Server Frequently Asked Questions</TITLE>
  - </HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  - <BODY
  -  BGCOLOR="#FFFFFF"
  -  TEXT="#000000"
  -  LINK="#0000FF"
  -  VLINK="#000080"
  -  ALINK="#FF0000"
  - >
  -  <!--#include virtual="header.html" -->
  -  <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>
  -  <P>
  -  $Revision: 1.10 $ ($Date: 2001/02/28 03:45:23 $)
  -  </P>
  -  <P>
  -  The latest version of this FAQ is always available from the main
  -  Apache web site, at
  -  &lt;<A
  -       HREF="http://httpd.apache.org/docs/misc/FAQ.html"
  -       REL="Help"
  -      ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>&gt;.
  -  </P>
  -<!-- Notes about changes:                                           -->
  -<!--  - If adding a relative link to another part of the            -->
  -<!--    documentation, *do* include the ".html" portion.  There's a -->
  -<!--    good chance that the user will be reading the documentation -->
  -<!--    on his own system, which may not be configured for          -->
  -<!--    multiviews.                                                 -->
  -<!--  - When adding items, make sure they're put in the right place -->
  -<!--    - verify that the numbering matches up.                     -->
  -<!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  -<!--    correctly in a reliable way when this is converted to text  -->
  -<!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  -<!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  -<!--    the horizontal and vertical indenting right.                -->
  -<!--  - Don't forget to include an HR tag after the last /P tag     -->
  -<!--    but before the /LI in an item.                              -->
  -  <P>
  -  If you are reading a text-only version of this FAQ, you may find numbers
  -  enclosed in brackets (such as &quot;[12]&quot;).  These refer to the list of
  -  reference URLs to be found at the end of the document.  These references
  -  do not appear, and are not needed, for the hypertext version.
  -  </P>
  -  <H2>The Questions</H2>
  -<OL TYPE="A">
  -<!--#endif -->
  -<!--#if expr="$TOC || $STANDALONE" -->
  - <LI VALUE="5"><STRONG>Configuration Questions</STRONG>
  -  <OL>
  -   <LI><A HREF="#fdlim">Why can't I run more than &lt;<EM>n</EM>&gt;
  -        virtual hosts?</A>
  -   </LI>
  -   <LI><A HREF="#freebsd-setsize">Can I increase <SAMP>FD_SETSIZE</SAMP>
  -        on FreeBSD?</A>
  -   </LI>
  -   <LI><A HREF="#errordoc401">Why doesn't my <CODE>ErrorDocument
  -        401</CODE> work?</A>
  -   </LI>
  -   <LI><A HREF="#cookies1">Why does Apache send a cookie on every response?</A>
  -   </LI>
  -   <LI><A HREF="#cookies2">Why don't my cookies work, I even compiled in
  -        <SAMP>mod_cookies</SAMP>?</A>
  -   </LI>
  -   <LI><A HREF="#jdk1-and-http1.1">Why do my Java app[let]s give me plain text
  -        when I request an URL from an Apache server?</A>
  -   </LI>
  -   <LI><A HREF="#midi">How do I get Apache to send a MIDI file so the
  -        browser can play it?</A>
  -   </LI>
  -   <LI><A HREF="#addlog">How do I add browsers and referrers to my logs?</A>
  -   </LI>
  -   <LI><A HREF="#set-servername">Why does accessing directories only work
  -        when I include the trailing &quot;/&quot;
  -        (<EM>e.g.</EM>,&nbsp;<SAMP>http://foo.domain.com/~user/</SAMP>) but
  -        not when I omit it
  -        (<EM>e.g.</EM>,&nbsp;<SAMP>http://foo.domain.com/~user</SAMP>)?</A>
  -   </LI>
  -   <LI><A HREF="#no-info-directives">Why doesn't mod_info list any
  -        directives?</A>
  -   </LI>
  -   <LI><A HREF="#namevhost">I upgraded to Apache 1.3 and now my
  -        virtual hosts don't work!</A>
  -   </LI>
  -   <LI><A HREF="#redhat-htm">I'm using RedHat Linux and my .htm files are
  -        showing up as HTML source rather than being formatted!</A>
  -   </LI>
  -   <LI><A HREF="#htaccess-work">My <CODE>.htaccess</CODE> files are being
  -	ignored.</A>
  -   </LI>
  -   <LI><A HREF="#forbidden">Why do I get a 
  -        &quot;<SAMP>Forbidden</SAMP>&quot; message whenever I try to 
  -        access a particular directory?</A>
  -   <li><a href="#malfiles">Why do I get a 
  -        &quot;<samp>Forbidden/You don't have permission to access /
  -	on this server</samp>&quot; message whenever I try to 
  -        access my server?</a></li>
  -   <LI><A HREF="#ie-ignores-mime">Why do my files appear correctly in
  -        Internet Explorer, but show up as source or trigger a save
  -        window with Netscape?</A> 
  -  </OL>
  - </LI>
  +<!--#else -->
  +<!--#set var="STANDALONE" value="YES" -->
  +<!--#set var="INCLUDED" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#endif -->
   <!--#if expr="$STANDALONE" -->
  -</OL>
  -
  -<HR>
  -
  -  <H2>The Answers</H2>
  -<!--#endif -->
  -<!--#if expr="! $TOC" -->
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -  <H3>E. Configuration Questions</H3>
  -<OL>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Server Frequently Asked Questions</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache Server Frequently Asked
  +    Questions</h1>
  +
  +    <p>$Revision: 1.11 $ ($Date: 2001/10/08 01:26:54 $)</p>
  +
  +    <p>The latest version of this FAQ is always available from the
  +    main Apache web site, at &lt;<a
  +    href="http://httpd.apache.org/docs/misc/FAQ.html"
  +    rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>&gt;.</p>
  +    <!-- Notes about changes:                                           -->
  +    <!--  - If adding a relative link to another part of the            -->
  +    <!--    documentation, *do* include the ".html" portion.  There's a -->
  +    <!--    good chance that the user will be reading the documentation -->
  +    <!--    on his own system, which may not be configured for          -->
  +    <!--    multiviews.                                                 -->
  +    <!--  - When adding items, make sure they're put in the right place -->
  +    <!--    - verify that the numbering matches up.                     -->
  +    <!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  +    <!--    correctly in a reliable way when this is converted to text  -->
  +    <!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  +    <!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  +    <!--    the horizontal and vertical indenting right.                -->
  +    <!--  - Don't forget to include an HR tag after the last /P tag     -->
  +    <!--    but before the /LI in an item.                              -->
  +
  +    <p>If you are reading a text-only version of this FAQ, you may
  +    find numbers enclosed in brackets (such as "[12]"). These refer
  +    to the list of reference URLs to be found at the end of the
  +    document. These references do not appear, and are not needed,
  +    for the hypertext version.</p>
  +
  +    <h2>The Questions</h2>
  +
  +    <ol type="A">
  +      <!--#endif -->
  +      <!--#if expr="$TOC || $STANDALONE" -->
  +
  +      <li value="5">
  +        <strong>Configuration Questions</strong> 
  +
  +        <ol>
  +          <li><a href="#fdlim">Why can't I run more than
  +          &lt;<em>n</em>&gt; virtual hosts?</a></li>
  +
  +          <li><a href="#freebsd-setsize">Can I increase
  +          <samp>FD_SETSIZE</samp> on FreeBSD?</a></li>
  +
  +          <li><a href="#errordoc401">Why doesn't my
  +          <code>ErrorDocument 401</code> work?</a></li>
  +
  +          <li><a href="#cookies1">Why does Apache send a cookie on
  +          every response?</a></li>
  +
  +          <li><a href="#cookies2">Why don't my cookies work, I even
  +          compiled in <samp>mod_cookies</samp>?</a></li>
  +
  +          <li><a href="#jdk1-and-http1.1">Why do my Java app[let]s
  +          give me plain text when I request an URL from an Apache
  +          server?</a></li>
  +
  +          <li><a href="#midi">How do I get Apache to send a MIDI
  +          file so the browser can play it?</a></li>
  +
  +          <li><a href="#addlog">How do I add browsers and referrers
  +          to my logs?</a></li>
  +
  +          <li><a href="#set-servername">Why does accessing
  +          directories only work when I include the trailing "/"
  +          (<em>e.g.</em>,&nbsp;<samp>http://foo.domain.com/~user/</samp>)
  +          but not when I omit it
  +          (<em>e.g.</em>,&nbsp;<samp>http://foo.domain.com/~user</samp>)?</a></li>
  +
  +          <li><a href="#no-info-directives">Why doesn't mod_info
  +          list any directives?</a></li>
  +
  +          <li><a href="#namevhost">I upgraded to Apache 1.3 and now
  +          my virtual hosts don't work!</a></li>
  +
  +          <li><a href="#redhat-htm">I'm using RedHat Linux and my
  +          .htm files are showing up as HTML source rather than
  +          being formatted!</a></li>
  +
  +          <li><a href="#htaccess-work">My <code>.htaccess</code>
  +          files are being ignored.</a></li>
  +
  +          <li><a href="#forbidden">Why do I get a
  +          "<samp>Forbidden</samp>" message whenever I try to access
  +          a particular directory?</a></li>
  +
  +          <li><a href="#malfiles">Why do I get a
  +          "<samp>Forbidden/You don't have permission to access / on
  +          this server</samp>" message whenever I try to access my
  +          server?</a></li>
  +
  +          <li><a href="#ie-ignores-mime">Why do my files appear
  +          correctly in Internet Explorer, but show up as source or
  +          trigger a save window with Netscape?</a></li>
  +        </ol>
  +      </li>
  +      <!--#endif -->
  +      <!--#if expr="$STANDALONE" -->
  +    </ol>
  +    <hr />
  +
  +    <h2>The Answers</h2>
  +    <!--#endif -->
  +    <!--#if expr="! $TOC" -->
  +
  +    <h3>E. Configuration Questions</h3>
  +
  +    <ol>
  +      <li>
  +        <a id="fdlim" name="fdlim"><strong>Why can't I run more
  +        than &lt;<em>n</em>&gt; virtual hosts?</strong></a> 
  +
  +        <p>You are probably running into resource limitations in
  +        your operating system. The most common limitation is the
  +        <em>per</em>-process limit on <strong>file
  +        descriptors</strong>, which is almost always the cause of
  +        problems seen when adding virtual hosts. Apache often does
  +        not give an intuitive error message because it is normally
  +        some library routine (such as <code>gethostbyname()</code>)
  +        which needs file descriptors and doesn't complain
  +        intelligibly when it can't get them.</p>
  +
  +        <p>Each log file requires a file descriptor, which means
  +        that if you are using separate access and error logs for
  +        each virtual host, each virtual host needs two file
  +        descriptors. Each <a
  +        href="../mod/core.html#listen"><samp>Listen</samp></a>
  +        directive also needs a file descriptor.</p>
  +
  +        <p>Typical values for &lt;<em>n</em>&gt; that we've seen
  +        are in the neighborhood of 128 or 250. When the server
  +        bumps into the file descriptor limit, it may dump core with
  +        a SIGSEGV, it might just hang, or it may limp along and
  +        you'll see (possibly meaningful) errors in the error log.
  +        One common problem that occurs when you run into a file
  +        descriptor limit is that CGI scripts stop being executed
  +        properly.</p>
  +
  +        <p>As to what you can do about this:</p>
  +
  +        <ol>
  +          <li>Reduce the number of <a
  +          href="../mod/core.html#listen"><samp>Listen</samp></a>
  +          directives. If there are no other servers running on the
  +          machine on the same port then you normally don't need any
  +          Listen directives at all. By default Apache listens to
  +          all addresses on port 80.</li>
  +
  +          <li>Reduce the number of log files. You can use <a
  +          href="../mod/mod_log_config.html"><samp>mod_log_config</samp></a>
  +          to log all requests to a single log file while including
  +          the name of the virtual host in the log file. You can
  +          then write a script to split the logfile into separate
  +          files later if necessary. Such a script is provided with
  +          the Apache 1.3 distribution in the
  +          <samp>src/support/split-logfile</samp> file.</li>
  +
  +          <li>
  +            Increase the number of file descriptors available to
  +            the server (see your system's documentation on the
  +            <code>limit</code> or <code>ulimit</code> commands).
  +            For some systems, information on how to do this is
  +            available in the <a href="perf.html">performance
  +            hints</a> page. There is a specific note for <a
  +            href="#freebsd-setsize">FreeBSD</a> below. 
  +
  +            <p>For Windows 95, try modifying your
  +            <samp>C:\CONFIG.SYS</samp> file to include a line
  +            like</p>
  +
  +            <dl>
  +              <dd><code>FILES=300</code></dd>
  +            </dl>
  +
  +            <p>Remember that you'll need to reboot your Windows 95
  +            system in order for the new value to take effect.</p>
  +          </li>
  +
  +          <li>"Don't do that" - try to run with fewer virtual
  +          hosts</li>
  +
  +          <li>Spread your operation across multiple server
  +          processes (using <a
  +          href="../mod/core.html#listen"><samp>Listen</samp></a>
  +          for example, but see the first point) and/or ports.</li>
  +        </ol>
  +
  +        <p>Since this is an operating-system limitation, there's
  +        not much else available in the way of solutions.</p>
  +
  +        <p>As of 1.2.1 we have made attempts to work around various
  +        limitations involving running with many descriptors. <a
  +        href="descriptors.html">More information is
  +        available.</a></p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="freebsd-setsize" name="freebsd-setsize"><strong>Can
  +        I increase <samp>FD_SETSIZE</samp> on FreeBSD?</strong></a>
  +        
  +
  +        <p>On versions of FreeBSD before 3.0, the
  +        <samp>FD_SETSIZE</samp> define defaults to 256. This means
  +        that you will have trouble usefully using more than 256
  +        file descriptors in Apache. This can be increased, but
  +        doing so can be tricky.</p>
  +
  +        <p>If you are using a version prior to 2.2, you need to
  +        recompile your kernel with a larger
  +        <samp>FD_SETSIZE</samp>. This can be done by adding a line
  +        such as:</p>
  +
  +        <dl>
  +          <dd><code>options FD_SETSIZE <em>nnn</em></code></dd>
  +        </dl>
  +
  +        <p>to your kernel config file. Starting at version 2.2,
  +        this is no longer necessary.</p>
  +
  +        <p>If you are using a version of 2.1-stable from after
  +        1997/03/10 or 2.2 or 3.0-current from before 1997/06/28,
  +        there is a limit in the resolver library that prevents it
  +        from using more file descriptors than what
  +        <samp>FD_SETSIZE</samp> is set to when libc is compiled. To
  +        increase this, you have to recompile libc with a higher
  +        <samp>FD_SETSIZE</samp>.</p>
  +
  +        <p>In FreeBSD 3.0, the default <samp>FD_SETSIZE</samp> has
  +        been increased to 1024 and the above limitation in the
  +        resolver library has been removed.</p>
  +
  +        <p>After you deal with the appropriate changes above, you
  +        can increase the setting of <samp>FD_SETSIZE</samp> at
  +        Apache compilation time by adding
  +        "<samp>-DFD_SETSIZE=<em>nnn</em></samp>" to the
  +        <samp>EXTRA_CFLAGS</samp> line in your
  +        <samp>Configuration</samp> file.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="errordoc401" name="errordoc401"><strong>Why doesn't
  +        my <code>ErrorDocument 401</code> work?</strong></a> 
  +
  +        <p>You need to use it with a URL in the form
  +        "<samp>/foo/bar</samp>" and not one with a method and
  +        hostname such as "<samp>http://host/foo/bar</samp>". See
  +        the <a
  +        href="../mod/core.html#errordocument"><samp>ErrorDocument</samp></a>
  +        documentation for details. This was incorrectly documented
  +        in the past.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="cookies1" name="cookies1"><strong>Why does Apache
  +        send a cookie on every response?</strong></a> 
  +
  +        <p>Apache does <em>not</em> automatically send a cookie on
  +        every response, unless you have re-compiled it with the <a
  +        href="../mod/mod_usertrack.html"><samp>mod_usertrack</samp></a>
  +        module, and specifically enabled it with the <a
  +        href="../mod/mod_usertrack.html#cookietracking"><samp>CookieTracking</samp></a>
  +        directive. This module has been in Apache since version
  +        1.2. This module may help track users, and uses cookies to
  +        do this. If you are not using the data generated by
  +        <samp>mod_usertrack</samp>, do not compile it into
  +        Apache.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="cookies2" name="cookies2"><strong>Why don't my
  +        cookies work, I even compiled in
  +        <samp>mod_cookies</samp>?</strong></a> 
  +
  +        <p>Firstly, you do <em>not</em> need to compile in
  +        <samp>mod_cookies</samp> in order for your scripts to work
  +        (see the <a href="#cookies1">previous question</a> for more
  +        about <samp>mod_cookies</samp>). Apache passes on your
  +        <samp>Set-Cookie</samp> header fine, with or without this
  +        module. If cookies do not work it will be because your
  +        script does not work properly or your browser does not use
  +        cookies or is not set-up to accept them.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="jdk1-and-http1.1"
  +        name="jdk1-and-http1.1"><strong>Why do my Java app[let]s
  +        give me plain text when I request an URL from an Apache
  +        server?</strong></a> 
  +
  +        <p>As of version 1.2, Apache is an HTTP/1.1 (HyperText
  +        Transfer Protocol version 1.1) server. This fact is
  +        reflected in the protocol version that's included in the
  +        response headers sent to a client when processing a
  +        request. Unfortunately, low-level Web access classes
  +        included in the Java Development Kit (JDK) version 1.0.2
  +        expect to see the version string "HTTP/1.0" and do not
  +        correctly interpret the "HTTP/1.1" value Apache is sending
  +        (this part of the response is a declaration of what the
  +        server can do rather than a declaration of the dialect of
  +        the response). The result is that the JDK methods do not
  +        correctly parse the headers, and include them with the
  +        document content by mistake.</p>
  +
  +        <p>This is definitely a bug in the JDK 1.0.2 foundation
  +        classes from Sun, and it has been fixed in version 1.1.
  +        However, the classes in question are part of the virtual
  +        machine environment, which means they're part of the Web
  +        browser (if Java-enabled) or the Java environment on the
  +        client system - so even if you develop <em>your</em>
  +        classes with a recent JDK, the eventual users might
  +        encounter the problem. The classes involved are replaceable
  +        by vendors implementing the Java virtual machine
  +        environment, and so even those that are based upon the
  +        1.0.2 version may not have this problem.</p>
  +
  +        <p>In the meantime, a workaround is to tell Apache to
  +        "fake" an HTTP/1.0 response to requests that come from the
  +        JDK methods; this can be done by including a line such as
  +        the following in your server configuration files:</p>
  +
  +        <dl>
  +          <dd><code>BrowserMatch Java1.0 force-response-1.0<br />
  +           BrowserMatch JDK/1.0 force-response-1.0</code></dd>
  +        </dl>
  +
  +        <p>More information about this issue can be found in the <a
  +        href="http://httpd.apache.org/info/jdk-102.html"><cite>Java
  +        and HTTP/1.1</cite></a> page at the Apache web site.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="midi" name="midi"><strong>How do I get Apache to
  +        send a MIDI file so the browser can play it?</strong></a> 
  +
  +        <p>Even though the registered MIME type for MIDI files is
  +        <samp>audio/midi</samp>, some browsers are not set up to
  +        recognize it as such; instead, they look for
  +        <samp>audio/x-midi</samp>. There are two things you can do
  +        to address this:</p>
  +
  +        <ol>
  +          <li>Configure your browser to treat documents of type
  +          <samp>audio/midi</samp> correctly. This is the type that
  +          Apache sends by default. This may not be workable,
  +          however, if you have many client installations to change,
  +          or if some or many of the clients are not under your
  +          control.</li>
  +
  +          <li>
  +            Instruct Apache to send a different
  +            <samp>Content-type</samp> header for these files by
  +            adding the following line to your server's
  +            configuration files: 
  +
  +            <dl>
  +              <dd><code>AddType audio/x-midi .mid .midi
  +              .kar</code></dd>
  +            </dl>
  +
  +            <p>Note that this may break browsers that <em>do</em>
  +            recognize the <samp>audio/midi</samp> MIME type unless
  +            they're prepared to also handle
  +            <samp>audio/x-midi</samp> the same way.</p>
  +          </li>
  +        </ol>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="addlog" name="addlog"><strong>How do I add browsers
  +        and referrers to my logs?</strong></a> 
  +
  +        <p>Apache provides a couple of different ways of doing
  +        this. The recommended method is to compile the <a
  +        href="../mod/mod_log_config.html"><samp>mod_log_config</samp></a>
  +        module into your configuration and use the <a
  +        href="../mod/mod_log_config.html#customlog"><samp>CustomLog</samp></a>
  +        directive.</p>
  +
  +        <p>You can either log the additional information in files
  +        other than your normal transfer log, or you can add them to
  +        the records already being written. For example:</p>
  +
  +        <p>
  +        <code>CustomLog&nbsp;logs/access_log&nbsp;"%h&nbsp;%l&nbsp;%u&nbsp;%t&nbsp;\"%r\"&nbsp;%s&nbsp;%b&nbsp;\"%{Referer}i\"&nbsp;\"%{User-Agent}i\""</code></p>
  +
  +        <p>This will add the values of the <samp>User-agent:</samp>
  +        and <samp>Referer:</samp> headers, which indicate the
  +        client and the referring page, respectively, to the end of
  +        each line in the access log.</p>
  +
  +        <p>You may want to check out the <cite>Apache Week</cite>
  +        article entitled: "<a
  +        href="http://www.apacheweek.com/features/logfiles"
  +        rel="Help"><cite>Gathering Visitor Information: Customizing
  +        Your Logfiles</cite></a>".</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="set-servername" name="set-servername"><strong>Why
  +        does accessing directories only work when I include the
  +        trailing "/"
  +        (<em>e.g.</em>,&nbsp;<samp>http://foo.domain.com/~user/</samp>)
  +        but not when I omit it
  +        (<em>e.g.</em>,&nbsp;<samp>http://foo.domain.com/~user</samp>)?</strong></a>
  +        
  +
  +        <p>When you access a directory without a trailing "/",
  +        Apache needs to send what is called a redirect to the
  +        client to tell it to add the trailing slash. If it did not
  +        do so, relative URLs would not work properly. When it sends
  +        the redirect, it needs to know the name of the server so
  +        that it can include it in the redirect. There are two ways
  +        for Apache to find this out; either it can guess, or you
  +        can tell it. If your DNS is configured correctly, it can
  +        normally guess without any problems. If it is not, however,
  +        then you need to tell it.</p>
  +
  +        <p>Add a <a
  +        href="../mod/core.html#servername">ServerName</a> directive
  +        to the config file to tell it what the domain name of the
  +        server is.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="no-info-directives"
  +        name="no-info-directives"><strong>Why doesn't mod_info list
  +        any directives?</strong></a> 
  +
  +        <p>The <a
  +        href="../mod/mod_info.html"><samp>mod_info</samp></a>
  +        module allows you to use a Web browser to see how your
  +        server is configured. Among the information it displays is
  +        the list modules and their configuration directives. The
  +        "current" values for the directives are not necessarily
  +        those of the running server; they are extracted from the
  +        configuration files themselves at the time of the request.
  +        If the files have been changed since the server was last
  +        reloaded, the display will not match the values actively in
  +        use. If the files and the path to the files are not
  +        readable by the user as which the server is running (see
  +        the <a href="../mod/core.html#user"><samp>User</samp></a>
  +        directive), then <samp>mod_info</samp> cannot read them in
  +        order to list their values. An entry <em>will</em> be made
  +        in the error log in this event, however.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="namevhost" name="namevhost"><strong>I upgraded to
  +        Apache 1.3 and now my virtual hosts don't
  +        work!</strong></a> 
  +
  +        <p>In versions of Apache prior to 1.3b2, there was a lot of
  +        confusion regarding address-based virtual hosts and
  +        (HTTP/1.1) name-based virtual hosts, and the rules
  +        concerning how the server processed
  +        <samp>&lt;VirtualHost&gt;</samp> definitions were very
  +        complex and not well documented.</p>
  +
  +        <p>Apache 1.3b2 introduced a new directive, <a
  +        href="../mod/core.html#namevirtualhost"><samp>NameVirtualHost</samp></a>,
  +        which simplifies the rules quite a bit. However, changing
  +        the rules like this means that your existing name-based
  +        <samp>&lt;VirtualHost&gt;</samp> containers probably won't
  +        work correctly immediately following the upgrade.</p>
  +
  +        <p>To correct this problem, add the following line to the
  +        beginning of your server configuration file, before
  +        defining any virtual hosts:</p>
  +
  +        <dl>
  +          <dd><code>NameVirtualHost <em>n.n.n.n</em></code></dd>
  +        </dl>
  +
  +        <p>Replace the "<samp>n.n.n.n</samp>" with the IP address
  +        to which the name-based virtual host names resolve; if you
  +        have multiple name-based hosts on multiple addresses,
  +        repeat the directive for each address.</p>
  +
  +        <p>Make sure that your name-based
  +        <samp>&lt;VirtualHost&gt;</samp> blocks contain
  +        <samp>ServerName</samp> and possibly
  +        <samp>ServerAlias</samp> directives so Apache can be sure
  +        to tell them apart correctly.</p>
  +
  +        <p>Please see the <a href="../vhosts/">Apache Virtual Host
  +        documentation</a> for further details about
  +        configuration.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="redhat-htm" name="redhat-htm"><strong>I'm using
  +        RedHat Linux and my .htm files are showing up as HTML
  +        source rather than being formatted!</strong></a> 
  +
  +        <p>RedHat messed up and forgot to put a content type for
  +        <code>.htm</code> files into <code>/etc/mime.types</code>.
  +        Edit <code>/etc/mime.types</code>, find the line containing
  +        <code>html</code> and add <code>htm</code> to it. Then
  +        restart your httpd server:</p>
  +
  +        <dl>
  +          <dd><code>kill -HUP `cat /var/run/httpd.pid`</code></dd>
  +        </dl>
  +
  +        <p>Then <strong>clear your browsers' caches</strong>. (Many
  +        browsers won't re-examine the content type after they've
  +        reloaded a page.)</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="htaccess-work" name="htaccess-work"><strong>My
  +        <code>.htaccess</code> files are being
  +        ignored.</strong></a> 
  +
  +        <p>This is almost always due to your <a
  +        href="../mod/core.html#allowoverride">AllowOverride</a>
  +        directive being set incorrectly for the directory in
  +        question. If it is set to <code>None</code> then .htaccess
  +        files will not even be looked for. If you do have one that
  +        is set, then be certain it covers the directory you are
  +        trying to use the .htaccess file in. This is normally
  +        accomplished by ensuring it is inside the proper <a
  +        href="../mod/core.html#directory">Directory</a>
  +        container.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="forbidden" name="forbidden"><strong>Why do I get a
  +        "<samp>Forbidden</samp>" message whenever I try to access a
  +        particular directory?</strong></a> 
  +
  +        <p>This message is generally caused because either</p>
  +
  +        <ul>
  +          <li>The underlying file system permissions do not allow
  +          the User/Group under which Apache is running to access
  +          the necessary files; or</li>
  +
  +          <li>The Apache configuration has some access restrictions
  +          in place which forbid access to the files.</li>
  +        </ul>
  +
  +        <p>You can determine which case applies to your situation
  +        by checking the error log.</p>
  +
  +        <p>In the case where file system permission are at fault,
  +        remember that not only must the directory and files in
  +        question be readable, but also all parent directories must
  +        be at least searchable by the web server in order for the
  +        content to be accessible.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="malfiles" name="malfiles"><b>Why do I get a
  +        "<samp>Forbidden/You don't have permission to access / on
  +        this server</samp>" message whenever I try to access my
  +        server?</b></a> 
  +
  +        <p>Search your <code>conf/httpd.conf</code> file for this
  +        exact string: <code>&lt;Files ~&gt;</code>. If you find it,
  +        that's your problem -- that particular &lt;Files&gt;
  +        container is malformed. Delete it or replace it with
  +        <code>&lt;Files ~ "^\.ht"&gt;</code> and restart your
  +        server and things should work as expected.</p>
  +
  +        <p>This error appears to be caused by a problem with the
  +        version of linuxconf distributed with Redhat 6.x. It may
  +        reappear if you use linuxconf again.</p>
  +
  +        <p>If you don't find this string, check out the <a
  +        href="#forbidden">previous question</a>.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="ie-ignores-mime" name="ie-ignores-mime"><strong>Why
  +        do my files appear correctly in Internet Explorer, but show
  +        up as source or trigger a save window with
  +        Netscape?</strong></a> 
  +
  +        <p>Internet Explorer (IE) and Netscape handle mime type
  +        detection in different ways, and therefore will display the
  +        document differently. In particular, IE sometimes relies on
  +        the file extension to determine the mime type. This can
  +        happen when the server specifies a mime type of
  +        <code>application/octet-stream</code> or
  +        <code>text/plain</code>. (Unfortunately, this behavior
  +        makes it impossible to properly send plain text in some
  +        situations unless the file extension is <code>txt</code>.)
  +        There are more details available on IE's mime type
  +        detection behavior in an <a
  +        href="http://msdn.microsoft.com/workshop/networking/moniker/overview/appendix_a.asp">
  +        MSDN article</a>.</p>
  +
  +        <p>In order to make all browsers work correctly, you should
  +        assure that Apache sends the correct mime type for the
  +        file. This is accomplished by editing the
  +        <code>mime.types</code> file or using an <a
  +        href="../mod/mod_mime.html#addtype"><code>AddType</code></a>
  +        directive in the Apache configuration files.</p>
  +        <hr />
  +      </li>
  +    </ol>
  +    <!--#endif -->
  +    <!--#if expr="$STANDALONE" -->
  +    <!-- Don't forget to add HR tags at the end of each list item.. -->
  +    <!--#include virtual="footer.html" -->
  +    <!--#endif -->
  +  </body>
  +</html>
   
  - <LI><A NAME="fdlim">
  -      <STRONG>Why can't I run more than &lt;<EM>n</EM>&gt;
  -      virtual hosts?</STRONG>
  -     </A>
  -  <P>
  -  You are probably running into resource limitations in your
  -  operating system.  The most common limitation is the
  -  <EM>per</EM>-process limit on <STRONG>file descriptors</STRONG>,
  -  which is almost always the cause of problems seen when adding
  -  virtual hosts.  Apache often does not give an intuitive error
  -  message because it is normally some library routine (such as
  -  <CODE>gethostbyname()</CODE>) which needs file descriptors and
  -  doesn't complain intelligibly when it can't get them.
  -  </P>
  -  <P>
  -  Each log file requires a file descriptor, which means that if you are
  -  using separate access and error logs for each virtual host, each
  -  virtual host needs two file descriptors.  Each
  -  <A HREF="../mod/core.html#listen"><SAMP>Listen</SAMP></A>
  -  directive also needs a file descriptor.
  -  </P>
  -  <P>
  -  Typical values for &lt;<EM>n</EM>&gt; that we've seen are in
  -  the neighborhood of 128 or 250.  When the server bumps into the file
  -  descriptor limit, it may dump core with a SIGSEGV, it might just
  -  hang, or it may limp along and you'll see (possibly meaningful) errors
  -  in the error log.  One common problem that occurs when you run into
  -  a file descriptor limit is that CGI scripts stop being executed
  -  properly.
  -  </P>
  -  <P>
  -  As to what you can do about this:
  -  </P>
  -  <OL>
  -   <LI>Reduce the number of
  -    <A HREF="../mod/core.html#listen"><SAMP>Listen</SAMP></A>
  -    directives.  If there are no other servers running on the machine
  -    on the same port then you normally don't
  -    need any Listen directives at all.  By default Apache listens to
  -    all addresses on port 80.
  -   </LI>
  -   <LI>Reduce the number of log files.  You can use
  -    <A HREF="../mod/mod_log_config.html"><SAMP>mod_log_config</SAMP></A>
  -    to log all requests to a single log file while including the name
  -    of the virtual host in the log file.  You can then write a
  -    script to split the logfile into separate files later if
  -    necessary.  Such a script is provided with the Apache 1.3 distribution
  -    in the <SAMP>src/support/split-logfile</SAMP> file.
  -   </LI>
  -   <LI>Increase the number of file descriptors available to the server
  -    (see your system's documentation on the <CODE>limit</CODE> or
  -    <CODE>ulimit</CODE> commands).  For some systems, information on
  -    how to do this is available in the
  -    <A HREF="perf.html">performance hints</A> page.  There is a specific
  -    note for <A HREF="#freebsd-setsize">FreeBSD</A> below.
  -    <P>
  -    For Windows 95, try modifying your <SAMP>C:\CONFIG.SYS</SAMP> file to
  -    include a line like
  -    </P>
  -    <DL>
  -     <DD><CODE>FILES=300</CODE>
  -     </DD>
  -    </DL>
  -    <P>
  -    Remember that you'll need to reboot your Windows 95 system in order
  -    for the new value to take effect.
  -    </P>
  -   </LI>
  -   <LI>&quot;Don't do that&quot; - try to run with fewer virtual hosts
  -   </LI>
  -   <LI>Spread your operation across multiple server processes (using
  -    <A HREF="../mod/core.html#listen"><SAMP>Listen</SAMP></A>
  -    for example, but see the first point) and/or ports.
  -   </LI>
  -  </OL>
  -  <P>
  -  Since this is an operating-system limitation, there's not much else
  -  available in the way of solutions.
  -  </P>
  -  <P>
  -  As of 1.2.1 we have made attempts to work around various limitations
  -  involving running with many descriptors.
  -  <A HREF="descriptors.html">More information is available.</A>
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="freebsd-setsize">
  -      <STRONG>Can I increase <SAMP>FD_SETSIZE</SAMP> on FreeBSD?</STRONG>
  -     </A>
  -  <P>
  -  On versions of FreeBSD before 3.0, the <SAMP>FD_SETSIZE</SAMP> define 
  -  defaults to 256.  This means that you will have trouble usefully using
  -  more than 256 file descriptors in Apache.  This can be increased, but
  -  doing so can be tricky.
  -  </P>
  -  <P>
  -  If you are using a version prior to 2.2, you need to recompile your
  -  kernel with a larger <SAMP>FD_SETSIZE</SAMP>.  This can be done by adding a 
  -  line such as:
  -  </P>
  -  <DL>
  -   <DD><CODE>options FD_SETSIZE <EM>nnn</EM></CODE>
  -   </DD>
  -  </DL>
  -  <P>
  -  to your kernel config file.  Starting at version 2.2, this is no
  -  longer necessary.
  -  </P>
  -  <P>
  -  If you are using a version of 2.1-stable from after 1997/03/10 or
  -  2.2 or 3.0-current from before 1997/06/28, there is a limit in
  -  the resolver library that prevents it from using more file descriptors
  -  than what <SAMP>FD_SETSIZE</SAMP> is set to when libc is compiled.  To
  -  increase this, you have to recompile libc with a higher
  -  <SAMP>FD_SETSIZE</SAMP>.
  -  </P>
  -  <P>
  -  In FreeBSD 3.0, the default <SAMP>FD_SETSIZE</SAMP> has been increased to
  -  1024 and the above limitation in the resolver library
  -  has been removed.
  -  </P>
  -  <P>
  -  After you deal with the appropriate changes above, you can increase 
  -  the setting of <SAMP>FD_SETSIZE</SAMP> at Apache compilation time 
  -  by adding &quot;<SAMP>-DFD_SETSIZE=<EM>nnn</EM></SAMP>&quot; to the
  -  <SAMP>EXTRA_CFLAGS</SAMP> line in your <SAMP>Configuration</SAMP>
  -  file.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="errordoc401">
  -      <STRONG>Why doesn't my <CODE>ErrorDocument 401</CODE> work?</STRONG>
  -     </A>
  -  <P>
  -  You need to use it with a URL in the form
  -  &quot;<SAMP>/foo/bar</SAMP>&quot; and not one with a method and
  -  hostname such as &quot;<SAMP>http://host/foo/bar</SAMP>&quot;.  See the
  -  <A HREF="../mod/core.html#errordocument"><SAMP>ErrorDocument</SAMP></A>
  -  documentation for details.  This was incorrectly documented in the past.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="cookies1">
  -      <STRONG>Why does Apache send a cookie on every response?</STRONG>
  -     </A>
  -  <P>
  -  Apache does <EM>not</EM> automatically send a cookie on every
  -  response, unless you have re-compiled it with the
  -  <A HREF="../mod/mod_usertrack.html"><SAMP>mod_usertrack</SAMP></A>
  -  module, and specifically enabled it with the
  -  <A HREF="../mod/mod_usertrack.html#cookietracking"
  -  ><SAMP>CookieTracking</SAMP></A>
  -  directive.
  -  This module has been in Apache since version 1.2.
  -  This module may help track users, and uses cookies to do this. If
  -  you are not using the data generated by <SAMP>mod_usertrack</SAMP>, do
  -  not compile it into Apache. 
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="cookies2">
  -      <STRONG>Why don't my cookies work, I even compiled in
  -      <SAMP>mod_cookies</SAMP>?
  -      </STRONG>
  -     </A>
  -  <P>
  -  Firstly, you do <EM>not</EM> need to compile in
  -  <SAMP>mod_cookies</SAMP> in order for your scripts to work (see the
  -  <A HREF="#cookies1">previous question</A>
  -  for more about <SAMP>mod_cookies</SAMP>). Apache passes on your
  -  <SAMP>Set-Cookie</SAMP> header fine, with or without this module. If
  -  cookies do not work it will be because your script does not work
  -  properly or your browser does not use cookies or is not set-up to
  -  accept them.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="jdk1-and-http1.1">
  -      <STRONG>Why do my Java app[let]s give me plain text when I request
  -      an URL from an Apache server?</STRONG>
  -     </A>
  -  <P>
  -  As of version 1.2, Apache is an HTTP/1.1 (HyperText Transfer Protocol
  -  version 1.1) server.  This fact is reflected in the protocol version
  -  that's included in the response headers sent to a client when
  -  processing a request.  Unfortunately, low-level Web access classes
  -  included in the Java Development Kit (JDK) version 1.0.2 expect to see
  -  the version string &quot;HTTP/1.0&quot; and do not correctly interpret
  -  the &quot;HTTP/1.1&quot; value Apache is sending (this part of the
  -  response is a declaration of what the server can do rather than a
  -  declaration of the dialect of the response).  The result
  -  is that the JDK methods do not correctly parse the headers, and
  -  include them with the document content by mistake.
  -  </P>
  -  <P>
  -  This is definitely a bug in the JDK 1.0.2 foundation classes from Sun,
  -  and it has been fixed in version 1.1.  However, the classes in
  -  question are part of the virtual machine environment, which means
  -  they're part of the Web browser (if Java-enabled) or the Java
  -  environment on the client system - so even if you develop
  -  <EM>your</EM> classes with a recent JDK, the eventual users might
  -  encounter the problem.
  -  The classes involved are replaceable by vendors implementing the
  -  Java virtual machine environment, and so even those that are based
  -  upon the 1.0.2 version may not have this problem.
  -  </P>
  -  <P>
  -  In the meantime, a workaround is to tell
  -  Apache to &quot;fake&quot; an HTTP/1.0 response to requests that come
  -  from the JDK methods; this can be done by including a line such as the
  -  following in your server configuration files:
  -  </P>
  -  <P>
  -  <DL>
  -   <DD><CODE>BrowserMatch Java1.0 force-response-1.0
  -    <BR>
  -    BrowserMatch JDK/1.0 force-response-1.0</CODE>
  -   </DD>
  -  </DL>
  -  <P></P>
  -  <P>
  -  More information about this issue can be found in the
  -  <A HREF="http://httpd.apache.org/info/jdk-102.html"
  -  ><CITE>Java and HTTP/1.1</CITE></A>
  -  page at the Apache web site.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="midi">
  -      <STRONG>How do I get Apache to send a MIDI file so the browser can
  -      play it?</STRONG>
  -     </A>
  -  <P>
  -  Even though the registered MIME type for MIDI files is
  -  <SAMP>audio/midi</SAMP>, some browsers are not set up to recognize it
  -  as such; instead, they look for <SAMP>audio/x-midi</SAMP>.  There are
  -  two things you can do to address this:
  -  </P>
  -  <OL>
  -   <LI>Configure your browser to treat documents of type
  -    <SAMP>audio/midi</SAMP> correctly.  This is the type that Apache
  -    sends by default.  This may not be workable, however, if you have
  -    many client installations to change, or if some or many of the
  -    clients are not under your control.
  -   </LI>
  -   <LI>Instruct Apache to send a different <SAMP>Content-type</SAMP>
  -    header for these files by adding the following line to your server's
  -    configuration files:
  -    <P>
  -    <DL>
  -     <DD><CODE>AddType audio/x-midi .mid .midi .kar</CODE>
  -     </DD>
  -    </DL>
  -    <P></P>
  -    <P>
  -    Note that this may break browsers that <EM>do</EM> recognize the
  -    <SAMP>audio/midi</SAMP> MIME type unless they're prepared to also
  -    handle <SAMP>audio/x-midi</SAMP> the same way.
  -    </P>
  -   </LI>
  -  </OL>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="addlog">
  -      <STRONG>How do I add browsers and referrers to my logs?</STRONG>
  -     </A>
  -  <P>
  -  Apache provides a couple of different ways of doing this.  The
  -  recommended method is to compile the
  -  <A HREF="../mod/mod_log_config.html"><SAMP>mod_log_config</SAMP></A>
  -  module into your configuration and use the
  -  <A HREF="../mod/mod_log_config.html#customlog"><SAMP>CustomLog</SAMP></A>
  -  directive.
  -  </P>
  -  <P>
  -  You can either log the additional information in files other than your
  -  normal transfer log, or you can add them to the records already being
  -  written.  For example:
  -  </P>
  -  <P>
  -  <CODE>
  -   CustomLog&nbsp;logs/access_log&nbsp;"%h&nbsp;%l&nbsp;%u&nbsp;%t&nbsp;\"%r\"&nbsp;%s&nbsp;%b&nbsp;\"%{Referer}i\"&nbsp;\"%{User-Agent}i\""
  -  </CODE>
  -  </P>
  -  <P>
  -  This will add the values of the <SAMP>User-agent:</SAMP> and
  -  <SAMP>Referer:</SAMP> headers, which indicate the client and the
  -  referring page, respectively, to the end of each line in the access
  -  log.
  -  </P>
  -  <P>
  -  You may want to check out the <CITE>Apache Week</CITE> article
  -  entitled:
  -  &quot;<A HREF="http://www.apacheweek.com/features/logfiles" REL="Help"
  -        ><CITE>Gathering Visitor Information: Customizing Your
  -         Logfiles</CITE></A>&quot;.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="set-servername">
  -      <STRONG>Why does accessing directories only work when I include
  -      the trailing &quot;/&quot;
  -      (<EM>e.g.</EM>,&nbsp;<SAMP>http://foo.domain.com/~user/</SAMP>)
  -      but not when I omit it
  -      (<EM>e.g.</EM>,&nbsp;<SAMP>http://foo.domain.com/~user</SAMP>)?</STRONG>
  -     </A>
  -  <P>
  -  When you access a directory without a trailing &quot;/&quot;, Apache needs
  -  to send what is called a redirect to the client to tell it to
  -  add the trailing slash.  If it did not do so, relative URLs would
  -  not work properly.  When it sends the redirect, it needs to know
  -  the name of the server so that it can include it in the redirect.
  -  There are two ways for Apache to find this out; either it can guess,
  -  or you can tell it.  If your DNS is configured correctly, it can
  -  normally guess without any problems.  If it is not, however, then
  -  you need to tell it.
  -  </P>
  -  <P>
  -  Add a <A HREF="../mod/core.html#servername">ServerName</A> directive
  -  to the config file to tell it what the domain name of the server is.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="no-info-directives">
  -      <STRONG>Why doesn't mod_info list any directives?</STRONG>
  -     </A>
  -  <P>
  -  The <A HREF="../mod/mod_info.html"><SAMP>mod_info</SAMP></A>
  -  module allows you to use a Web browser to see how your server is
  -  configured.  Among the information it displays is the list modules and
  -  their configuration directives.  The &quot;current&quot; values for
  -  the directives are not necessarily those of the running server; they
  -  are extracted from the configuration files themselves at the time of
  -  the request.  If the files have been changed since the server was last
  -  reloaded, the display will not match the values actively in use.
  -  If the files and the path to the files are not readable by the user as
  -  which the server is running (see the
  -  <A HREF="../mod/core.html#user"><SAMP>User</SAMP></A>
  -  directive), then <SAMP>mod_info</SAMP> cannot read them in order to
  -  list their values.  An entry <EM>will</EM> be made in the error log in
  -  this event, however.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="namevhost">
  -      <STRONG>I upgraded to Apache 1.3 and now my virtual hosts don't
  -      work!</STRONG>
  -     </A>
  -  <P>
  -  In versions of Apache prior to 1.3b2, there was a lot of confusion
  -  regarding address-based virtual hosts and (HTTP/1.1) name-based
  -  virtual hosts, and the rules concerning how the server processed
  -  <SAMP>&lt;VirtualHost&gt;</SAMP> definitions were very complex and not
  -  well documented.
  -  </P>
  -  <P>
  -  Apache 1.3b2 introduced a new directive,
  -  <A HREF="../mod/core.html#namevirtualhost"
  -  ><SAMP>NameVirtualHost</SAMP></A>,
  -  which simplifies the rules quite a bit.  However, changing the rules
  -  like this means that your existing name-based
  -  <SAMP>&lt;VirtualHost&gt;</SAMP> containers probably won't work
  -  correctly immediately following the upgrade.
  -  </P>
  -  <P>
  -  To correct this problem, add the following line to the beginning of
  -  your server configuration file, before defining any virtual hosts:
  -  </P>
  -  <DL>
  -   <DD><CODE>NameVirtualHost <EM>n.n.n.n</EM></CODE>
  -   </DD>
  -  </DL>
  -  <P>
  -  Replace the &quot;<SAMP>n.n.n.n</SAMP>&quot; with the IP address to
  -  which the name-based virtual host names resolve; if you have multiple
  -  name-based hosts on multiple addresses, repeat the directive for each
  -  address.
  -  </P>
  -  <P>
  -  Make sure that your name-based <SAMP>&lt;VirtualHost&gt;</SAMP> blocks
  -  contain <SAMP>ServerName</SAMP> and possibly <SAMP>ServerAlias</SAMP>
  -  directives so Apache can be sure to tell them apart correctly.
  -  </P>
  -  <P>
  -  Please see the <A HREF="../vhosts/">Apache
  -  Virtual Host documentation</A> for further details about configuration.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="redhat-htm">
  -      <STRONG>I'm using RedHat Linux and my .htm files are showing
  -      up as HTML source rather than being formatted!</STRONG>
  -     </A>
  -
  -  <P>
  -  RedHat messed up and forgot to put a content type for <CODE>.htm</CODE>
  -  files into <CODE>/etc/mime.types</CODE>.  Edit <CODE>/etc/mime.types</CODE>,
  -  find the line containing <CODE>html</CODE> and add <CODE>htm</CODE> to it.
  -  Then restart your httpd server:
  -  </P>
  -  <DL>
  -   <DD><CODE>kill -HUP `cat /var/run/httpd.pid`</CODE>
  -   </DD>
  -  </DL>
  -  <P>
  -  Then <STRONG>clear your browsers' caches</STRONG>.  (Many browsers won't
  -  re-examine the content type after they've reloaded a page.)
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="htaccess-work">
  -       <STRONG>My <CODE>.htaccess</CODE> files are being ignored.</STRONG></A>
  -   <P>
  -   This is almost always due to your <A HREF="../mod/core.html#allowoverride">
  -   AllowOverride</A> directive being set incorrectly for the directory in 
  -   question.  If it is set to <CODE>None</CODE> then .htaccess files will 
  -   not even be looked for.  If you do have one that is set, then be certain 
  -   it covers the directory you are trying to use the .htaccess file in.  
  -   This is normally accomplished by ensuring it is inside the proper 
  -   <A HREF="../mod/core.html#directory">Directory</A> container.
  -   </P>
  -   <HR>
  - </LI>
  - <LI><A NAME="forbidden">
  -       <STRONG>Why do I get a &quot;<SAMP>Forbidden</SAMP>&quot; message 
  -       whenever I try to access a particular directory?</STRONG></A>
  -   <P>
  -   This message is generally caused because either
  -   </P>
  -   <UL>
  -    <LI>The underlying file system permissions do not allow the
  -     User/Group under which Apache is running to access the necessary
  -     files; or
  -    <LI>The Apache configuration has some access restrictions in 
  -     place which forbid access to the files.
  -   </UL>
  -   <P>
  -   You can determine which case applies to your situation by checking the
  -   error log.
  -   </P>
  -   <P>
  -   In the case where file system permission are at fault, remember
  -   that not only must the directory and files in question be readable,
  -   but also all parent directories must be at least searchable by the
  -   web server in order for the content to be accessible.
  -   </P>
  -   <HR>
  - </LI>
  - <li><a name="malfiles"><b>Why do I get a 
  -        &quot;<samp>Forbidden/You don't have permission to access /
  -	on this server</samp>&quot; message whenever I try to 
  -        access my server?</b></a>
  -   <p>
  -   Search your <code>conf/httpd.conf</code> file for this exact
  -   string:
  -   <code>&lt;Files ~&gt;</code>.  If you find it,
  -   that's your problem -- that particular &lt;Files&gt; container
  -   is malformed.  Delete it or replace it with 
  -   <code>&lt;Files ~ &quot;^\.ht&quot;&gt;</code> 
  -   and restart your server and things should work as expected.
  -   </p>
  -   <p>
  -   This error appears to be caused by a problem with the version of
  -   linuxconf distributed with Redhat 6.x.  It may reappear if
  -   you use linuxconf again.
  -   </p>
  -   <p>
  -   If you don't find this string, check out the
  -   <a href="#forbidden">previous question</a>.
  -   </p>
  -   <hr>
  - </li>
  - <LI><A NAME="ie-ignores-mime">
  -       <STRONG>Why do my files appear correctly in Internet
  -       Explorer, but show up as source or trigger a save window
  -       with Netscape?</STRONG></A> 
  -   <P>
  -   Internet Explorer (IE) and Netscape handle mime type detection in different
  -   ways, and therefore will display the document differently.  In particular,
  -   IE sometimes relies on the file extension to determine the mime type.  This
  -   can happen when the server specifies a mime type of
  -   <CODE>application/octet-stream</CODE> or <CODE>text/plain</CODE>.
  -   (Unfortunately, this behavior makes it impossible to properly send plain
  -   text in some situations unless the file extension is <CODE>txt</CODE>.)
  -   There are more details available on IE's mime type detection behavior in an
  -   <A HREF="http://msdn.microsoft.com/workshop/networking/moniker/overview/appendix_a.asp">MSDN
  -   article</A>.
  -   </P>
  -
  -   <P>
  -   In order to make all browsers work correctly, you should assure
  -   that Apache sends the correct mime type for the file.  This is
  -   accomplished by editing the <CODE>mime.types</CODE> file or using
  -   an <A HREF="../mod/mod_mime.html#addtype"><CODE>AddType</CODE></A>
  -   directive in the Apache configuration files.
  -   </P>
  -   <HR>
  -  </LI>
  -</OL>
  -<!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -  <!-- Don't forget to add HR tags at the end of each list item.. -->
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  -<!--#endif -->
  
  
  
  1.10      +563 -555  httpd-docs-1.3/htdocs/manual/misc/FAQ-F.html
  
  Index: FAQ-F.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/FAQ-F.html,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- FAQ-F.html	2000/12/03 03:25:06	1.9
  +++ FAQ-F.html	2001/10/08 01:26:54	1.10
  @@ -1,562 +1,570 @@
   <!--#if expr="$FAQMASTER" -->
  - <!--#set var="STANDALONE" value="" -->
  - <!--#set var="INCLUDED" value="YES" -->
  - <!--#if expr="$QUERY_STRING = TOC" -->
  -  <!--#set var="TOC" value="YES" -->
  -  <!--#set var="CONTENT" value="" -->
  - <!--#else -->
  -  <!--#set var="TOC" value="" -->
  -  <!--#set var="CONTENT" value="YES" -->
  - <!--#endif -->
  +<!--#set var="STANDALONE" value="" -->
  +<!--#set var="INCLUDED" value="YES" -->
  +<!--#if expr="$QUERY_STRING = TOC" -->
  +<!--#set var="TOC" value="YES" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#else -->
  - <!--#set var="STANDALONE" value="YES" -->
  - <!--#set var="INCLUDED" value="" -->
  - <!--#set var="TOC" value="" -->
  - <!--#set var="CONTENT" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="YES" -->
   <!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  - <HEAD>
  -  <TITLE>Apache Server Frequently Asked Questions</TITLE>
  - </HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  - <BODY
  -  BGCOLOR="#FFFFFF"
  -  TEXT="#000000"
  -  LINK="#0000FF"
  -  VLINK="#000080"
  -  ALINK="#FF0000"
  - >
  -  <!--#include virtual="header.html" -->
  -  <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>
  -  <P>
  -  $Revision: 1.9 $ ($Date: 2000/12/03 03:25:06 $)
  -  </P>
  -  <P>
  -  The latest version of this FAQ is always available from the main
  -  Apache web site, at
  -  &lt;<A
  -       HREF="http://httpd.apache.org/docs/misc/FAQ.html"
  -       REL="Help"
  -      ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>&gt;.
  -  </P>
  -<!-- Notes about changes:                                           -->
  -<!--  - If adding a relative link to another part of the            -->
  -<!--    documentation, *do* include the ".html" portion.  There's a -->
  -<!--    good chance that the user will be reading the documentation -->
  -<!--    on his own system, which may not be configured for          -->
  -<!--    multiviews.                                                 -->
  -<!--  - When adding items, make sure they're put in the right place -->
  -<!--    - verify that the numbering matches up.                     -->
  -<!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  -<!--    correctly in a reliable way when this is converted to text  -->
  -<!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  -<!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  -<!--    the horizontal and vertical indenting right.                -->
  -<!--  - Don't forget to include an HR tag after the last /P tag     -->
  -<!--    but before the /LI in an item.                              -->
  -  <P>
  -  If you are reading a text-only version of this FAQ, you may find numbers
  -  enclosed in brackets (such as &quot;[12]&quot;).  These refer to the list of
  -  reference URLs to be found at the end of the document.  These references
  -  do not appear, and are not needed, for the hypertext version.
  -  </P>
  -  <H2>The Questions</H2>
  -<OL TYPE="A">
  -<!--#endif -->
  -<!--#if expr="$TOC || $STANDALONE" -->
  - <LI VALUE="6"><STRONG>Dynamic Content (CGI and SSI)</STRONG>
  -  <OL>
  -   <LI><A HREF="#CGIoutsideScriptAlias">How do I enable CGI execution
  -        in directories other than the ScriptAlias?</A>
  -   </LI>
  -   <LI><A HREF="#premature-script-headers">What does it mean when my
  -        CGIs fail with &quot;<SAMP>Premature end of script
  -        headers</SAMP>&quot;?</A>
  -   </LI>
  -   <LI><A HREF="#POSTnotallowed">Why do I keep getting &quot;Method Not 
  -        Allowed&quot; for form POST requests?</A>
  -   </LI>
  -   <LI><A HREF="#nph-scripts">How can I get my script's output without
  -        Apache buffering it?  Why doesn't my server push work?</A>
  -   </LI>
  -   <LI><A HREF="#cgi-spec">Where can I find the &quot;CGI
  -        specification&quot;?</A>
  -   </LI>
  -   <LI><A HREF="#fastcgi">Why isn't FastCGI included with Apache any
  -        more?</A>
  -   </LI>
  -   <LI><A HREF="#ssi-part-i">How do I enable SSI (parsed HTML)?</A>
  -   </LI>
  -   <LI><A HREF="#ssi-part-ii">Why don't my parsed files get cached?</A>
  -   </LI>
  -   <LI><A HREF="#ssi-part-iii">How can I have my script output parsed?</A>
  -   </LI>
  -   <LI><A HREF="#ssi-part-iv">SSIs don't work for VirtualHosts and/or 
  -        user home directories</A>
  -   </LI>
  -   <LI><A HREF="#errordocssi">How can I use <CODE>ErrorDocument</CODE>
  -        and SSI to simplify customized error messages?</A>
  -   </LI>
  -   <LI><A HREF="#remote-user-var">Why is the environment variable
  -        <SAMP>REMOTE_USER</SAMP> not set?</A>
  -   </LI>
  -   <LI><A HREF="#user-cgi">How do I allow each of my user directories
  -     to have a cgi-bin directory?</A>
  -   </LI>
  -  </OL>
  - </LI>
  +<!--#else -->
  +<!--#set var="STANDALONE" value="YES" -->
  +<!--#set var="INCLUDED" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#endif -->
   <!--#if expr="$STANDALONE" -->
  -</OL>
  -
  -<HR>
  -
  -  <H2>The Answers</H2>
  -<!--#endif -->
  -<!--#if expr="! $TOC" -->
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -  <H3>F. Dynamic Content (CGI and SSI)</H3>
  -<OL>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Server Frequently Asked Questions</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache Server Frequently Asked
  +    Questions</h1>
  +
  +    <p>$Revision: 1.10 $ ($Date: 2001/10/08 01:26:54 $)</p>
  +
  +    <p>The latest version of this FAQ is always available from the
  +    main Apache web site, at &lt;<a
  +    href="http://httpd.apache.org/docs/misc/FAQ.html"
  +    rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>&gt;.</p>
  +    <!-- Notes about changes:                                           -->
  +    <!--  - If adding a relative link to another part of the            -->
  +    <!--    documentation, *do* include the ".html" portion.  There's a -->
  +    <!--    good chance that the user will be reading the documentation -->
  +    <!--    on his own system, which may not be configured for          -->
  +    <!--    multiviews.                                                 -->
  +    <!--  - When adding items, make sure they're put in the right place -->
  +    <!--    - verify that the numbering matches up.                     -->
  +    <!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  +    <!--    correctly in a reliable way when this is converted to text  -->
  +    <!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  +    <!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  +    <!--    the horizontal and vertical indenting right.                -->
  +    <!--  - Don't forget to include an HR tag after the last /P tag     -->
  +    <!--    but before the /LI in an item.                              -->
  +
  +    <p>If you are reading a text-only version of this FAQ, you may
  +    find numbers enclosed in brackets (such as "[12]"). These refer
  +    to the list of reference URLs to be found at the end of the
  +    document. These references do not appear, and are not needed,
  +    for the hypertext version.</p>
  +
  +    <h2>The Questions</h2>
  +
  +    <ol type="A">
  +      <!--#endif -->
  +      <!--#if expr="$TOC || $STANDALONE" -->
  +
  +      <li value="6">
  +        <strong>Dynamic Content (CGI and SSI)</strong> 
  +
  +        <ol>
  +          <li><a href="#CGIoutsideScriptAlias">How do I enable CGI
  +          execution in directories other than the
  +          ScriptAlias?</a></li>
  +
  +          <li><a href="#premature-script-headers">What does it mean
  +          when my CGIs fail with "<samp>Premature end of script
  +          headers</samp>"?</a></li>
  +
  +          <li><a href="#POSTnotallowed">Why do I keep getting
  +          "Method Not Allowed" for form POST requests?</a></li>
  +
  +          <li><a href="#nph-scripts">How can I get my script's
  +          output without Apache buffering it? Why doesn't my server
  +          push work?</a></li>
  +
  +          <li><a href="#cgi-spec">Where can I find the "CGI
  +          specification"?</a></li>
  +
  +          <li><a href="#fastcgi">Why isn't FastCGI included with
  +          Apache any more?</a></li>
  +
  +          <li><a href="#ssi-part-i">How do I enable SSI (parsed
  +          HTML)?</a></li>
  +
  +          <li><a href="#ssi-part-ii">Why don't my parsed files get
  +          cached?</a></li>
  +
  +          <li><a href="#ssi-part-iii">How can I have my script
  +          output parsed?</a></li>
  +
  +          <li><a href="#ssi-part-iv">SSIs don't work for
  +          VirtualHosts and/or user home directories</a></li>
  +
  +          <li><a href="#errordocssi">How can I use
  +          <code>ErrorDocument</code> and SSI to simplify customized
  +          error messages?</a></li>
  +
  +          <li><a href="#remote-user-var">Why is the environment
  +          variable <samp>REMOTE_USER</samp> not set?</a></li>
  +
  +          <li><a href="#user-cgi">How do I allow each of my user
  +          directories to have a cgi-bin directory?</a></li>
  +        </ol>
  +      </li>
  +      <!--#endif -->
  +      <!--#if expr="$STANDALONE" -->
  +    </ol>
  +    <hr />
  +
  +    <h2>The Answers</h2>
  +    <!--#endif -->
  +    <!--#if expr="! $TOC" -->
  +
  +    <h3>F. Dynamic Content (CGI and SSI)</h3>
  +
  +    <ol>
  +      <li>
  +        <a id="CGIoutsideScriptAlias"
  +        name="CGIoutsideScriptAlias"><strong>How do I enable CGI
  +        execution in directories other than the
  +        ScriptAlias?</strong></a> 
  +
  +        <p>Apache recognizes all files in a directory named as a <a
  +        href="../mod/mod_alias.html#scriptalias"><samp>ScriptAlias</samp></a>
  +        as being eligible for execution rather than processing as
  +        normal documents. This applies regardless of the file name,
  +        so scripts in a ScriptAlias directory don't need to be
  +        named "<samp>*.cgi</samp>" or "<samp>*.pl</samp>" or
  +        whatever. In other words, <em>all</em> files in a
  +        ScriptAlias directory are scripts, as far as Apache is
  +        concerned.</p>
  +
  +        <p>To persuade Apache to execute scripts in other
  +        locations, such as in directories where normal documents
  +        may also live, you must tell it how to recognize them - and
  +        also that it's okay to execute them. For this, you need to
  +        use something like the <a
  +        href="../mod/mod_mime.html#addhandler"><samp>AddHandler</samp></a>
  +        directive.</p>
  +
  +        <ol>
  +          <li>
  +            In an appropriate section of your server configuration
  +            files, add a line such as 
  +
  +            <dl>
  +              <dd><code>AddHandler cgi-script .cgi</code></dd>
  +            </dl>
  +
  +            <p>The server will then recognize that all files in
  +            that location (and its logical descendants) that end in
  +            "<samp>.cgi</samp>" are script files, not
  +            documents.</p>
  +          </li>
  +
  +          <li>Make sure that the directory location is covered by
  +          an <a
  +          href="../mod/core.html#options"><samp>Options</samp></a>
  +          declaration that includes the <samp>ExecCGI</samp>
  +          option.</li>
  +        </ol>
  +
  +        <p>In some situations, you might not want to actually allow
  +        all files named "<samp>*.cgi</samp>" to be executable.
  +        Perhaps all you want is to enable a particular file in a
  +        normal directory to be executable. This can be
  +        alternatively accomplished <em>via</em> <a
  +        href="../mod/mod_rewrite.html"><samp>mod_rewrite</samp></a>
  +        and the following steps:</p>
  +
  +        <ol>
  +          <li>
  +            Locally add to the corresponding <samp>.htaccess</samp>
  +            file a ruleset similar to this one: 
  +
  +            <dl>
  +              <dd><code>RewriteEngine on<br />
  +               RewriteBase /~foo/bar/<br />
  +               RewriteRule ^quux\.cgi$ -
  +              [T=application/x-httpd-cgi]</code></dd>
  +            </dl>
  +          </li>
  +
  +          <li>Make sure that the directory location is covered by
  +          an <a
  +          href="../mod/core.html#options"><samp>Options</samp></a>
  +          declaration that includes the <samp>ExecCGI</samp> and
  +          <samp>FollowSymLinks</samp> option.</li>
  +        </ol>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="premature-script-headers"
  +        name="premature-script-headers"><strong>What does it mean
  +        when my CGIs fail with "<samp>Premature end of script
  +        headers</samp>"?</strong></a> 
  +
  +        <p>It means just what it says: the server was expecting a
  +        complete set of HTTP headers (one or more followed by a
  +        blank line), and didn't get them.</p>
  +
  +        <p>The most common cause of this problem is the script
  +        dying before sending the complete set of headers, or
  +        possibly any at all, to the server. To see if this is the
  +        case, try running the script standalone from an interactive
  +        session, rather than as a script under the server. If you
  +        get error messages, this is almost certainly the cause of
  +        the "premature end of script headers" message. Even if the
  +        CGI runs fine from the command line, remember that the
  +        environment and permissions may be different when running
  +        under the web server. The CGI can only access resources
  +        allowed for the <a
  +        href="../mod/core.html#user"><code>User</code></a> and <a
  +        href="../mod/core.html#group"><code>Group</code></a>
  +        specified in your Apache configuration. In addition, the
  +        environment will not be the same as the one provided on the
  +        command line, but it can be adjusted using the directives
  +        provided by <a href="../mod/mod_env.html">mod_env</a>.</p>
  +
  +        <p>The second most common cause of this (aside from people
  +        not outputting the required headers at all) is a result of
  +        an interaction with Perl's output buffering. To make Perl
  +        flush its buffers after each output statement, insert the
  +        following statements around the <code>print</code> or
  +        <code>write</code> statements that send your HTTP
  +        headers:</p>
  +
  +        <dl>
  +          <dd><code>{<br />
  +           &nbsp;local ($oldbar) = $|;<br />
  +           &nbsp;$cfh = select (STDOUT);<br />
  +           &nbsp;$| = 1;<br />
  +           &nbsp;#<br />
  +           &nbsp;# print your HTTP headers here<br />
  +           &nbsp;#<br />
  +           &nbsp;$| = $oldbar;<br />
  +           &nbsp;select ($cfh);<br />
  +           }</code></dd>
  +        </dl>
  +
  +        <p>This is generally only necessary when you are calling
  +        external programs from your script that send output to
  +        stdout, or if there will be a long delay between the time
  +        the headers are sent and the actual content starts being
  +        emitted. To maximize performance, you should turn
  +        buffer-flushing back <em>off</em> (with <code>$| = 0</code>
  +        or the equivalent) after the statements that send the
  +        headers, as displayed above.</p>
  +
  +        <p>If your script isn't written in Perl, do the equivalent
  +        thing for whatever language you <em>are</em> using
  +        (<em>e.g.</em>, for C, call <code>fflush()</code> after
  +        writing the headers).</p>
  +
  +        <p>Another cause for the "premature end of script headers"
  +        message are the RLimitCPU and RLimitMEM directives. You may
  +        get the message if the CGI script was killed due to a
  +        resource limit.</p>
  +
  +        <p>In addition, a configuration problem in <a
  +        href="../suexec.html">suEXEC</a>, mod_perl, or another
  +        third party module can often interfere with the execution
  +        of your CGI and cause the "premature end of script headers"
  +        message.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="POSTnotallowed" name="POSTnotallowed"><strong>Why do
  +        I keep getting "Method Not Allowed" for form POST
  +        requests?</strong></a> 
  +
  +        <p>This is almost always due to Apache not being configured
  +        to treat the file you are trying to POST to as a CGI
  +        script. You can not POST to a normal HTML file; the
  +        operation has no meaning. See the FAQ entry on <a
  +        href="#CGIoutsideScriptAlias">CGIs outside ScriptAliased
  +        directories</a> for details on how to configure Apache to
  +        treat the file in question as a CGI.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="nph-scripts" name="nph-scripts"><strong>How can I
  +        get my script's output without Apache buffering it? Why
  +        doesn't my server push work?</strong></a> 
  +
  +        <p>As of Apache 1.3, CGI scripts are essentially not
  +        buffered. Every time your script does a "flush" to output
  +        data, that data gets relayed on to the client. Some
  +        scripting languages, for example Perl, have their own
  +        buffering for output - this can be disabled by setting the
  +        <code>$|</code> special variable to 1. Of course this does
  +        increase the overall number of packets being transmitted,
  +        which can result in a sense of slowness for the end
  +        user.</p>
  +
  +        <p>Prior to 1.3, you needed to use "nph-" scripts to
  +        accomplish non-buffering. Today, the only difference
  +        between nph scripts and normal scripts is that nph scripts
  +        require the full HTTP headers to be sent.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="cgi-spec" name="cgi-spec"><strong>Where can I find
  +        the "CGI specification"?</strong></a> 
  +
  +        <p>The Common Gateway Interface (CGI) specification can be
  +        found at the original NCSA site &lt; <a
  +        href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"><samp>
  +        http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</samp></a>&gt;.
  +        This version hasn't been updated since 1995, and there have
  +        been some efforts to update it.</p>
  +
  +        <p>A new draft is being worked on with the intent of making
  +        it an informational RFC; you can find out more about this
  +        project at &lt;<a
  +        href="http://web.golux.com/coar/cgi/"><samp>http://web.golux.com/coar/cgi/</samp></a>&gt;.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="fastcgi" name="fastcgi"><strong>Why isn't FastCGI
  +        included with Apache any more?</strong></a> 
  +
  +        <p>The simple answer is that it was becoming too difficult
  +        to keep the version being included with Apache synchronized
  +        with the master copy at the <a
  +        href="http://www.fastcgi.com/">FastCGI web site</a>. When a
  +        new version of Apache was released, the version of the
  +        FastCGI module included with it would soon be out of
  +        date.</p>
  +
  +        <p>You can still obtain the FastCGI module for Apache from
  +        the master FastCGI web site.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="ssi-part-i" name="ssi-part-i"><strong>How do I
  +        enable SSI (parsed HTML)?</strong></a> 
  +
  +        <p>SSI (an acronym for Server-Side Include) directives
  +        allow static HTML documents to be enhanced at run-time
  +        (<em>e.g.</em>, when delivered to a client by Apache). The
  +        format of SSI directives is covered in the <a
  +        href="../mod/mod_include.html">mod_include manual</a>;
  +        suffice it to say that Apache supports not only SSI but
  +        xSSI (eXtended SSI) directives.</p>
  +
  +        <p>Processing a document at run-time is called
  +        <em>parsing</em> it; hence the term "parsed HTML" sometimes
  +        used for documents that contain SSI instructions. Parsing
  +        tends to be resource-consumptive compared to serving static
  +        files, and is not enabled by default. It can also interfere
  +        with the cachability of your documents, which can put a
  +        further load on your server. (See the <a
  +        href="#ssi-part-ii">next question</a> for more information
  +        about this.)</p>
  +
  +        <p>To enable SSI processing, you need to</p>
  +
  +        <ul>
  +          <li>Build your server with the <a
  +          href="../mod/mod_include.html"><samp>mod_include</samp></a>
  +          module. This is normally compiled in by default.</li>
  +
  +          <li>Make sure your server configuration files have an <a
  +          href="../mod/core.html#options"><samp>Options</samp></a>
  +          directive which permits <samp>Includes</samp>.</li>
  +
  +          <li>
  +            Make sure that the directory where you want the SSI
  +            documents to live is covered by the "server-parsed"
  +            content handler, either explicitly or in some ancestral
  +            location. That can be done with the following <a
  +            href="../mod/mod_mime.html#addhandler"><samp>AddHandler</samp></a>
  +            directive: 
  +
  +            <dl>
  +              <dd><code>AddHandler server-parsed .shtml</code></dd>
  +            </dl>
  +
  +            <p>This indicates that all files ending in ".shtml" in
  +            that location (or its descendants) should be parsed.
  +            Note that using ".html" will cause all normal HTML
  +            files to be parsed, which may put an inordinate load on
  +            your server.</p>
  +          </li>
  +        </ul>
  +
  +        <p>For additional information, see the <cite>Apache
  +        Week</cite> article on <a
  +        href="http://www.apacheweek.com/features/ssi"
  +        rel="Help"><cite>Using Server Side Includes</cite></a>.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="ssi-part-ii" name="ssi-part-ii"><strong>Why don't my
  +        parsed files get cached?</strong></a> 
  +
  +        <p>Since the server is performing run-time processing of
  +        your SSI directives, which may change the content shipped
  +        to the client, it can't know at the time it starts parsing
  +        what the final size of the result will be, or whether the
  +        parsed result will always be the same. This means that it
  +        can't generate <samp>Content-Length</samp> or
  +        <samp>Last-Modified</samp> headers. Caches commonly work by
  +        comparing the <samp>Last-Modified</samp> of what's in the
  +        cache with that being delivered by the server. Since the
  +        server isn't sending that header for a parsed document,
  +        whatever's doing the caching can't tell whether the
  +        document has changed or not - and so fetches it again to be
  +        on the safe side.</p>
  +
  +        <p>You can work around this in some cases by causing an
  +        <samp>Expires</samp> header to be generated. (See the <a
  +        href="../mod/mod_expires.html"
  +        rel="Help"><samp>mod_expires</samp></a> documentation for
  +        more details.) Another possibility is to use the <a
  +        href="../mod/mod_include.html#xbithack"
  +        rel="Help"><samp>XBitHack Full</samp></a> mechanism, which
  +        tells Apache to send (under certain circumstances detailed
  +        in the XBitHack directive description) a
  +        <samp>Last-Modified</samp> header based upon the last
  +        modification time of the file being parsed. Note that this
  +        may actually be lying to the client if the parsed file
  +        doesn't change but the SSI-inserted content does; if the
  +        included content changes often, this can result in stale
  +        copies being cached.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="ssi-part-iii" name="ssi-part-iii"><strong>How can I
  +        have my script output parsed?</strong></a> 
  +
  +        <p>So you want to include SSI directives in the output from
  +        your CGI script, but can't figure out how to do it? The
  +        short answer is "you can't." This is potentially a security
  +        liability and, more importantly, it can not be cleanly
  +        implemented under the current server API. The best
  +        workaround is for your script itself to do what the SSIs
  +        would be doing. After all, it's generating the rest of the
  +        content.</p>
  +
  +        <p>This is a feature The Apache Group hopes to add in the
  +        next major release after 1.3.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="ssi-part-iv" name="ssi-part-iv"><strong>SSIs don't
  +        work for VirtualHosts and/or user home
  +        directories.</strong></a> 
  +
  +        <p>This is almost always due to having some setting in your
  +        config file that sets "Options Includes" or some other
  +        setting for your DocumentRoot but not for other
  +        directories. If you set it inside a Directory section, then
  +        that setting will only apply to that directory.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="errordocssi" name="errordocssi"><strong>How can I
  +        use <code>ErrorDocument</code> and SSI to simplify
  +        customized error messages?</strong></a> 
  +
  +        <p>Have a look at <a href="custom_errordocs.html">this
  +        document</a>. It shows in example form how you can a
  +        combination of XSSI and negotiation to tailor a set of
  +        <code>ErrorDocument</code>s to your personal taste, and
  +        returning different internationalized error responses based
  +        on the client's native language.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="remote-user-var" name="remote-user-var"><strong>Why
  +        is the environment variable <samp>REMOTE_USER</samp> not
  +        set?</strong></a> 
  +
  +        <p>This variable is set and thus available in SSI or CGI
  +        scripts <strong>if and only if</strong> the requested
  +        document was protected by access authentication. For an
  +        explanation on how to implement these restrictions, see <a
  +        href="http://www.apacheweek.com/"><cite>Apache
  +        Week</cite></a>'s articles on <a
  +        href="http://www.apacheweek.com/features/userauth"><cite>Using
  +        User Authentication</cite></a> or <a
  +        href="http://www.apacheweek.com/features/dbmauth"><cite>DBM
  +        User Authentication</cite></a>.</p>
  +
  +        <p>Hint: When using a CGI script to receive the data of a
  +        HTML <samp>FORM</samp> notice that protecting the document
  +        containing the <samp>FORM</samp> is not sufficient to
  +        provide <samp>REMOTE_USER</samp> to the CGI script. You
  +        have to protect the CGI script, too. Or alternatively only
  +        the CGI script (then authentication happens only after
  +        filling out the form).</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="user-cgi" name="user-cgi"><strong>How do I allow
  +        each of my user directories to have a cgi-bin
  +        directory?</strong></a> 
  +
  +        <p>Remember that CGI execution does not need to be
  +        restricted only to cgi-bin directories. You can <a
  +        href="#CGIoutsideScriptAlias">allow CGI script execution in
  +        arbitrary parts of your filesystem</a>.</p>
  +
  +        <p>There are many ways to give each user directory a
  +        cgi-bin directory such that anything requested as
  +        <samp>http://example.com/~user/cgi-bin/program</samp> will
  +        be executed as a CGI script. Two alternatives are:</p>
  +
  +        <ol>
  +          <li>
  +            Place the cgi-bin directory next to the public_html
  +            directory: 
  +
  +            <dl>
  +              <dd><code>ScriptAliasMatch ^/~([^/]*)/cgi-bin/(.*)
  +              /home/$1/cgi-bin/$2</code></dd>
  +            </dl>
  +          </li>
  +
  +          <li>
  +            Place the cgi-bin directory underneath the public_html
  +            directory: 
  +
  +            <dl>
  +              <dd><code>&lt;Directory
  +              /home/*/public_html/cgi-bin&gt;<br />
  +               &nbsp;&nbsp;&nbsp;&nbsp;Options ExecCGI<br />
  +               &nbsp;&nbsp;&nbsp;&nbsp;SetHandler cgi-script<br />
  +               &lt;/Directory&gt;</code></dd>
  +            </dl>
  +          </li>
  +        </ol>
  +        <hr />
  +      </li>
  +    </ol>
  +    <!--#endif -->
  +    <!--#if expr="$STANDALONE" -->
  +    <!-- Don't forget to add HR tags at the end of each list item.. -->
  +    <!--#include virtual="footer.html" -->
  +    <!--#endif -->
  +  </body>
  +</html>
   
  - <LI><A NAME="CGIoutsideScriptAlias">
  -      <STRONG>How do I enable CGI execution in directories other than
  -      the ScriptAlias?</STRONG>
  -     </A>
  -  <P>
  -  Apache recognizes all files in a directory named as a
  -  <A HREF="../mod/mod_alias.html#scriptalias"><SAMP>ScriptAlias</SAMP></A>
  -  as being eligible for execution rather than processing as normal
  -  documents.  This applies regardless of the file name, so scripts in a
  -  ScriptAlias directory don't need to be named
  -  &quot;<SAMP>*.cgi</SAMP>&quot; or &quot;<SAMP>*.pl</SAMP>&quot; or
  -  whatever.  In other words, <EM>all</EM> files in a ScriptAlias
  -  directory are scripts, as far as Apache is concerned.
  -  </P>
  -  <P>
  -  To persuade Apache to execute scripts in other locations, such as in
  -  directories where normal documents may also live, you must tell it how
  -  to recognize them - and also that it's okay to execute them.  For
  -  this, you need to use something like the
  -  <A HREF="../mod/mod_mime.html#addhandler"><SAMP>AddHandler</SAMP></A>
  -  directive.
  -  </P>
  -  <P>
  -  <OL>
  -   <LI>In an appropriate section of your server configuration files, add
  -    a line such as
  -    <P>
  -    <DL>
  -     <DD><CODE>AddHandler cgi-script .cgi</CODE>
  -     </DD>
  -    </DL>
  -    <P></P>
  -    <P>
  -    The server will then recognize that all files in that location (and
  -    its logical descendants) that end in &quot;<SAMP>.cgi</SAMP>&quot;
  -    are script files, not documents.
  -    </P>
  -   </LI>
  -   <LI>Make sure that the directory location is covered by an
  -    <A HREF="../mod/core.html#options"><SAMP>Options</SAMP></A>
  -    declaration that includes the <SAMP>ExecCGI</SAMP> option.
  -   </LI>
  -  </OL>
  -  <P></P>
  -  <P>
  -  In some situations, you might not want to actually
  -  allow all files named &quot;<SAMP>*.cgi</SAMP>&quot; to be executable.
  -  Perhaps all you want is to enable a particular file in a normal directory to
  -  be executable. This can be alternatively accomplished 
  -  <EM>via</EM> <A HREF="../mod/mod_rewrite.html"><SAMP>mod_rewrite</SAMP></A> 
  -  and the following steps:
  -  </P>
  -  <P>
  -  <OL>
  -   <LI>Locally add to the corresponding <SAMP>.htaccess</SAMP> file a ruleset
  -    similar to this one:
  -    <P>
  -    <DL>
  -     <DD><CODE>RewriteEngine on
  -      <BR>
  -      RewriteBase   /~foo/bar/
  -      <BR>
  -      RewriteRule   ^quux\.cgi$  -  [T=application/x-httpd-cgi]</CODE>
  -     </DD>
  -    </DL>
  -    <P></P>
  -   </LI>
  -   <LI>Make sure that the directory location is covered by an
  -    <A HREF="../mod/core.html#options"><SAMP>Options</SAMP></A>
  -    declaration that includes the <SAMP>ExecCGI</SAMP> and
  -    <SAMP>FollowSymLinks</SAMP> option.
  -   </LI>
  -  </OL>
  -  <P></P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="premature-script-headers">
  -      <STRONG>What does it mean when my CGIs fail with
  -      &quot;<SAMP>Premature end of script headers</SAMP>&quot;?</STRONG>
  -     </A>
  -  <P>
  -  It means just what it says: the server was expecting a complete set of
  -  HTTP headers (one or more followed by a blank line), and didn't get
  -  them.
  -  </P>
  -  <P>
  -  The most common cause of this problem is the script dying before
  -  sending the complete set of headers, or possibly any at all, to the
  -  server.  To see if this is the case, try running the script standalone
  -  from an interactive session, rather than as a script under the server.
  -  If you get error messages, this is almost certainly the cause of the
  -  &quot;premature end of script headers&quot; message.  Even if the CGI 
  -  runs fine from the command line, remember that the environment and
  -  permissions may be different when running under the web server.  The
  -  CGI can only access resources allowed for the <A 
  -  HREF="../mod/core.html#user"><CODE>User</CODE></A> and 
  -  <A HREF="../mod/core.html#group"><CODE>Group</CODE></A> specified in 
  -  your Apache configuration.  In addition, the environment will not be 
  -  the same as the one provided on the command line, but it can be 
  -  adjusted using the directives provided by <A 
  -  HREF="../mod/mod_env.html">mod_env</A>.
  -  </P>
  -  <P>
  -  The second most common cause of this (aside from people not
  -  outputting the required headers at all) is a result of an interaction
  -  with Perl's output buffering.  To make Perl flush its buffers
  -  after each output statement, insert the following statements around
  -  the <CODE>print</CODE> or <CODE>write</CODE> statements that send your
  -  HTTP headers:
  -  </P>
  -  <P>
  -  <DL>
  -   <DD><CODE>{<BR>
  -    &nbsp;local ($oldbar) = $|;<BR>
  -    &nbsp;$cfh = select (STDOUT);<BR>
  -    &nbsp;$| = 1;<BR>
  -    &nbsp;#<BR>
  -    &nbsp;# print your HTTP headers here<BR>
  -    &nbsp;#<BR>
  -    &nbsp;$| = $oldbar;<BR>
  -    &nbsp;select ($cfh);<BR>
  -    }</CODE>
  -   </DD>
  -  </DL>
  -  <P></P>
  -  <P>
  -  This is generally only necessary when you are calling external
  -  programs from your script that send output to stdout, or if there will
  -  be a long delay between the time the headers are sent and the actual
  -  content starts being emitted.  To maximize performance, you should
  -  turn buffer-flushing back <EM>off</EM> (with <CODE>$| = 0</CODE> or the
  -  equivalent) after the statements that send the headers, as displayed
  -  above.
  -  </P>
  -  <P>
  -  If your script isn't written in Perl, do the equivalent thing for
  -  whatever language you <EM>are</EM> using (<EM>e.g.</EM>, for C, call
  -  <CODE>fflush()</CODE> after writing the headers).
  -  </P>
  -  <P>
  -  Another cause for the &quot;premature end of script headers&quot;
  -  message are the RLimitCPU and RLimitMEM directives. You may
  -  get the message if the CGI script was killed due to a
  -  resource limit.
  -  </P>
  -  <P>
  -  In addition, a configuration problem in <A
  -  HREF="../suexec.html">suEXEC</A>, mod_perl, or another third party
  -  module can often interfere with the execution of your CGI and cause
  -  the &quot;premature end of script headers&quot; message.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="POSTnotallowed">
  -      <STRONG>Why do I keep getting &quot;Method Not Allowed&quot; for 
  -      form POST requests?</STRONG>
  -     </A>
  -  <P>
  -  This is almost always due to Apache not being configured to treat the
  -  file you are trying to POST to as a CGI script.  You can not POST 
  -  to a normal HTML file; the operation has no meaning.  See the FAQ 
  -  entry on <A HREF="#CGIoutsideScriptAlias">CGIs outside ScriptAliased
  -  directories</A> for details on how to configure Apache to treat the
  -  file in question as a CGI.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="nph-scripts">
  -      <STRONG>How can I get my script's output without Apache buffering
  -      it?  Why doesn't my server push work?</STRONG>
  -     </A>
  -  <P>
  -  As of Apache 1.3, CGI scripts are essentially not buffered.  Every time
  -  your script does a "flush" to output data, that data gets relayed on to
  -  the client.  Some scripting languages, for example Perl, have their own
  -  buffering for output - this can be disabled by setting the <CODE>$|</CODE>
  -  special variable to 1.  Of course this does increase the overall number
  -  of packets being transmitted, which can result in a sense of slowness for 
  -  the end user.
  -  </P>
  -  <P>Prior to 1.3, you needed to use "nph-" scripts to accomplish
  -  non-buffering.  Today, the only difference between nph scripts and
  -  normal scripts is that nph scripts require the full HTTP headers to
  -  be sent.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="cgi-spec">
  -      <STRONG>Where can I find the &quot;CGI specification&quot;?</STRONG>
  -     </A>
  -  <P>
  -  The Common Gateway Interface (CGI) specification can be found at
  -  the original NCSA site 
  -  &lt;<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">
  -  <SAMP>http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</SAMP></A>&gt;.
  -  This version hasn't been updated since 1995, and there have been
  -  some efforts to update it.  
  -  </P>
  -  <P>
  -  A new draft is being worked on with the intent of making it an informational
  -  RFC; you can find out more about this project at
  -  &lt;<A HREF="http://web.golux.com/coar/cgi/"
  -      ><SAMP>http://web.golux.com/coar/cgi/</SAMP></A>&gt;.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="fastcgi">
  -      <STRONG>Why isn't FastCGI included with Apache any more?</STRONG>
  -     </A>
  -  <P>
  -  The simple answer is that it was becoming too difficult to keep the
  -  version being included with Apache synchronized with the master copy
  -  at the
  -  <A HREF="http://www.fastcgi.com/"
  -  >FastCGI web site</A>.  When a new version of Apache was released, the
  -  version of the FastCGI module included with it would soon be out of date.
  -  </P>
  -  <P>
  -  You can still obtain the FastCGI module for Apache from the master
  -  FastCGI web site.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="ssi-part-i">
  -      <STRONG>How do I enable SSI (parsed HTML)?</STRONG>
  -     </A>
  -  <P>
  -  SSI (an acronym for Server-Side Include) directives allow static HTML
  -  documents to be enhanced at run-time (<EM>e.g.</EM>, when delivered to
  -  a client by Apache).  The format of SSI directives is covered
  -  in the <A HREF="../mod/mod_include.html">mod_include manual</A>;
  -  suffice it to say that Apache supports not only SSI but
  -  xSSI (eXtended SSI) directives.
  -  </P>
  -  <P>
  -  Processing a document at run-time is called <EM>parsing</EM> it;
  -  hence the term &quot;parsed HTML&quot; sometimes used for documents
  -  that contain SSI instructions.  Parsing tends to be
  -  resource-consumptive compared to serving static files, and is not
  -  enabled by default.  It can also interfere with the cachability of
  -  your documents, which can put a further load on your server.  (See
  -  the <A HREF="#ssi-part-ii">next question</A> for more information
  -  about this.)
  -  </P>
  -  <P>
  -  To enable SSI processing, you need to
  -  </P>
  -  <UL>
  -   <LI>Build your server with the
  -    <A HREF="../mod/mod_include.html"><SAMP>mod_include</SAMP></A>
  -    module.  This is normally compiled in by default.
  -   </LI>
  -   <LI>Make sure your server configuration files have an
  -    <A HREF="../mod/core.html#options"><SAMP>Options</SAMP></A>
  -    directive which permits <SAMP>Includes</SAMP>.
  -   </LI>
  -   <LI>Make sure that the directory where you want the SSI documents to
  -    live is covered by the &quot;server-parsed&quot; content handler,
  -    either explicitly or in some ancestral location.  That can be done
  -    with the following
  -    <A HREF="../mod/mod_mime.html#addhandler"><SAMP>AddHandler</SAMP></A>
  -    directive:
  -    <P>
  -    <DL>
  -     <DD><CODE>AddHandler server-parsed .shtml</CODE>
  -     </DD>
  -    </DL>
  -    <P></P>
  -    <P>
  -    This indicates that all files ending in &quot;.shtml&quot; in that
  -    location (or its descendants) should be parsed.  Note that using
  -    &quot;.html&quot; will cause all normal HTML files to be parsed,
  -    which may put an inordinate load on your server.
  -    </P>
  -   </LI>
  -  </UL>
  -  <P>
  -  For additional information, see the <CITE>Apache Week</CITE> article on
  -  <A HREF="http://www.apacheweek.com/features/ssi" REL="Help"
  -  ><CITE>Using Server Side Includes</CITE></A>.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="ssi-part-ii">
  -      <STRONG>Why don't my parsed files get cached?</STRONG>
  -     </A>
  -  <P>
  -  Since the server is performing run-time processing of your SSI
  -  directives, which may change the content shipped to the client, it
  -  can't know at the time it starts parsing what the final size of the
  -  result will be, or whether the parsed result will always be the same.
  -  This means that it can't generate <SAMP>Content-Length</SAMP> or
  -  <SAMP>Last-Modified</SAMP> headers.  Caches commonly work by comparing
  -  the <SAMP>Last-Modified</SAMP> of what's in the cache with that being
  -  delivered by the server.  Since the server isn't sending that header
  -  for a parsed document, whatever's doing the caching can't tell whether
  -  the document has changed or not - and so fetches it again to be on the
  -  safe side.
  -  </P>
  -  <P>
  -  You can work around this in some cases by causing an
  -  <SAMP>Expires</SAMP> header to be generated.  (See the
  -  <A HREF="../mod/mod_expires.html" REL="Help"><SAMP>mod_expires</SAMP></A>
  -  documentation for more details.)  Another possibility is to use the
  -  <A HREF="../mod/mod_include.html#xbithack" REL="Help"
  -  ><SAMP>XBitHack Full</SAMP></A>
  -  mechanism, which tells Apache to send (under certain circumstances
  -  detailed in the XBitHack directive description) a
  -  <SAMP>Last-Modified</SAMP> header based upon the last modification
  -  time of the file being parsed.  Note that this may actually be lying
  -  to the client if the parsed file doesn't change but the SSI-inserted
  -  content does; if the included content changes often, this can result
  -  in stale copies being cached.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="ssi-part-iii">
  -      <STRONG>How can I have my script output parsed?</STRONG>
  -     </A>
  -  <P>
  -  So you want to include SSI directives in the output from your CGI
  -  script, but can't figure out how to do it?
  -  The short answer is &quot;you can't.&quot;  This is potentially
  -  a security liability and, more importantly, it can not be cleanly
  -  implemented under the current server API.  The best workaround
  -  is for your script itself to do what the SSIs would be doing.
  -  After all, it's generating the rest of the content.
  -  </P>
  -  <P>
  -  This is a feature The Apache Group hopes to add in the next major
  -  release after 1.3.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="ssi-part-iv">
  -      <STRONG>SSIs don't work for VirtualHosts and/or 
  -        user home directories.</STRONG>
  -     </A>
  -  <P>
  -  This is almost always due to having some setting in your config file that
  -  sets "Options Includes" or some other setting for your DocumentRoot
  -  but not for other directories.  If you set it inside a Directory
  -  section, then that setting will only apply to that directory.  
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="errordocssi">
  -      <STRONG>How can I use <CODE>ErrorDocument</CODE>
  -      and SSI to simplify customized error messages?</STRONG>
  -     </A>
  -  <P>
  -  Have a look at <A HREF="custom_errordocs.html">this document</A>.
  -  It shows in example form how you can a combination of XSSI and
  -  negotiation to tailor a set of <CODE>ErrorDocument</CODE>s to your
  -  personal taste, and returning different internationalized error
  -  responses based on the client's native language.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="remote-user-var">
  -      <STRONG>Why is the environment variable 
  -      <SAMP>REMOTE_USER</SAMP> not set?</STRONG>
  -     </A>
  -  <P>
  -  This variable is set and thus available in SSI or CGI scripts <STRONG>if and
  -  only if</STRONG> the requested document was protected by access
  -  authentication.  For an explanation on how to implement these restrictions,
  -  see
  -  <A HREF="http://www.apacheweek.com/"><CITE>Apache Week</CITE></A>'s
  -  articles on
  -  <A HREF="http://www.apacheweek.com/features/userauth"
  -  ><CITE>Using User Authentication</CITE></A>
  -  or
  -  <A HREF="http://www.apacheweek.com/features/dbmauth"
  -  ><CITE>DBM User Authentication</CITE></A>.
  -  </P>
  -  <P>
  -  Hint: When using a CGI script to receive the data of a HTML <SAMP>FORM</SAMP>
  -  notice that protecting the document containing the <SAMP>FORM</SAMP> is not
  -  sufficient to provide <SAMP>REMOTE_USER</SAMP> to the CGI script.  You have
  -  to protect the CGI script, too. Or alternatively only the CGI script (then
  -  authentication happens only after filling out the form).
  -  </P>
  -  <HR>
  - </LI>
  - <LI><A NAME="user-cgi"><STRONG>How do I allow each of my user directories
  -     to have a cgi-bin directory?</STRONG></A>
  -  <P>
  -  Remember that CGI execution does not need to be restricted only to
  -  cgi-bin directories.  You can <A HREF="#CGIoutsideScriptAlias">allow
  -  CGI script execution in arbitrary parts of your filesystem</A>.
  -  </P>
  -  <P>
  -  There are many ways to give each user directory a cgi-bin directory
  -  such that anything requested as 
  -  <SAMP>http://example.com/~user/cgi-bin/program</SAMP> will be
  -  executed as a CGI script.
  -  Two alternatives are:
  -  <OL>
  -   <LI>Place the cgi-bin directory next to the public_html directory:
  -    <DL>
  -     <DD><CODE>ScriptAliasMatch ^/~([^/]*)/cgi-bin/(.*) /home/$1/cgi-bin/$2</CODE>
  -     </DD>
  -    </DL>
  -    </LI>
  -    <LI>Place the cgi-bin directory underneath the public_html directory:
  -     <P></p>
  -     <DL>
  -      <DD><CODE>&lt;Directory /home/*/public_html/cgi-bin&gt;<BR>
  -       &nbsp;&nbsp;&nbsp;&nbsp;Options ExecCGI<BR>
  -       &nbsp;&nbsp;&nbsp;&nbsp;SetHandler cgi-script<BR>
  -       &lt;/Directory&gt;</CODE>
  -      </DD>
  -     </DL>
  -     <p></P>
  -    </LI>
  -   </OL>
  -  <HR> 
  - </LI>
  -
  -</OL>
  -<!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -  <!-- Don't forget to add HR tags at the end of each list item.. -->
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  -<!--#endif -->
  
  
  
  1.7       +410 -398  httpd-docs-1.3/htdocs/manual/misc/FAQ-G.html
  
  Index: FAQ-G.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/FAQ-G.html,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- FAQ-G.html	2000/12/03 03:25:06	1.6
  +++ FAQ-G.html	2001/10/08 01:26:54	1.7
  @@ -1,405 +1,417 @@
   <!--#if expr="$FAQMASTER" -->
  - <!--#set var="STANDALONE" value="" -->
  - <!--#set var="INCLUDED" value="YES" -->
  - <!--#if expr="$QUERY_STRING = TOC" -->
  -  <!--#set var="TOC" value="YES" -->
  -  <!--#set var="CONTENT" value="" -->
  - <!--#else -->
  -  <!--#set var="TOC" value="" -->
  -  <!--#set var="CONTENT" value="YES" -->
  - <!--#endif -->
  +<!--#set var="STANDALONE" value="" -->
  +<!--#set var="INCLUDED" value="YES" -->
  +<!--#if expr="$QUERY_STRING = TOC" -->
  +<!--#set var="TOC" value="YES" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#else -->
  - <!--#set var="STANDALONE" value="YES" -->
  - <!--#set var="INCLUDED" value="" -->
  - <!--#set var="TOC" value="" -->
  - <!--#set var="CONTENT" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="YES" -->
   <!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  - <HEAD>
  -  <TITLE>Apache Server Frequently Asked Questions</TITLE>
  - </HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  - <BODY
  -  BGCOLOR="#FFFFFF"
  -  TEXT="#000000"
  -  LINK="#0000FF"
  -  VLINK="#000080"
  -  ALINK="#FF0000"
  - >
  -  <!--#include virtual="header.html" -->
  -  <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>
  -  <P>
  -  $Revision: 1.6 $ ($Date: 2000/12/03 03:25:06 $)
  -  </P>
  -  <P>
  -  The latest version of this FAQ is always available from the main
  -  Apache web site, at
  -  &lt;<A
  -       HREF="http://httpd.apache.org/docs/misc/FAQ.html"
  -       REL="Help"
  -      ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>&gt;.
  -  </P>
  -<!-- Notes about changes:                                           -->
  -<!--  - If adding a relative link to another part of the            -->
  -<!--    documentation, *do* include the ".html" portion.  There's a -->
  -<!--    good chance that the user will be reading the documentation -->
  -<!--    on his own system, which may not be configured for          -->
  -<!--    multiviews.                                                 -->
  -<!--  - When adding items, make sure they're put in the right place -->
  -<!--    - verify that the numbering matches up.                     -->
  -<!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  -<!--    correctly in a reliable way when this is converted to text  -->
  -<!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  -<!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  -<!--    the horizontal and vertical indenting right.                -->
  -<!--  - Don't forget to include an HR tag after the last /P tag     -->
  -<!--    but before the /LI in an item.                              -->
  -  <P>
  -  If you are reading a text-only version of this FAQ, you may find numbers
  -  enclosed in brackets (such as &quot;[12]&quot;).  These refer to the list of
  -  reference URLs to be found at the end of the document.  These references
  -  do not appear, and are not needed, for the hypertext version.
  -  </P>
  -  <H2>The Questions</H2>
  -<OL TYPE="A">
  -<!--#endif -->
  -<!--#if expr="$TOC || $STANDALONE" -->
  - <LI VALUE="7"><STRONG>Authentication and Access Restrictions</STRONG>
  -  <OL>
  -   <LI><A HREF="#dnsauth">Why isn't restricting access by host or domain name
  -        working correctly?</A>
  -   </LI>
  -   <LI><A HREF="#user-authentication">How do I set up Apache to require
  -        a username and password to access certain documents?</A>
  -   </LI>
  -   <LI><A HREF="#remote-auth-only">How do I set up Apache to allow access
  -        to certain documents only if a site is either a local site
  -        <EM>or</EM> the user supplies a password and username?</A>
  -   </LI>
  -   <LI><A HREF="#authauthoritative">Why does my authentication give
  -        me a server error?</A>
  -   </LI>
  -   <LI><A HREF="#auth-on-same-machine">Do I have to keep the (mSQL)
  -        authentication information on the same machine?</A>
  -   </LI>
  -   <LI><A HREF="#msql-slow">Why is my mSQL authentication terribly slow?</A>
  -   </LI>
  -   <LI><A HREF="#passwdauth">Can I use my <SAMP>/etc/passwd</SAMP> file
  -        for Web page authentication?</A>
  -   </LI>
  -   <LI><A HREF="#prompted-twice">Why does Apache ask for my password
  -	twice before serving a file?</a>
  -   </LI>
  -  </OL>
  - </LI>
  +<!--#else -->
  +<!--#set var="STANDALONE" value="YES" -->
  +<!--#set var="INCLUDED" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#endif -->
   <!--#if expr="$STANDALONE" -->
  -</OL>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -<HR>
  -
  -  <H2>The Answers</H2>
  -<!--#endif -->
  -<!--#if expr="! $TOC" -->
  -  <H3>G. Authentication and Access Restrictions</H3>
  -<OL>
  -
  - <LI><A NAME="dnsauth">
  -      <STRONG>Why isn't restricting access by host or domain name
  -      working correctly?</STRONG>
  -     </A>
  -  <P>
  -  Two of the most common causes of this are:
  -  </P>
  -  <OL>
  -   <LI><STRONG>An error, inconsistency, or unexpected mapping in the DNS
  -    registration</STRONG>
  -    <BR>
  -    This happens frequently: your configuration restricts access to
  -    <SAMP>Host.FooBar.Com</SAMP>, but you can't get in from that host.
  -    The usual reason for this is that <SAMP>Host.FooBar.Com</SAMP> is
  -    actually an alias for another name, and when Apache performs the
  -    address-to-name lookup it's getting the <EM>real</EM> name, not
  -    <SAMP>Host.FooBar.Com</SAMP>.  You can verify this by checking the
  -    reverse lookup yourself.  The easiest way to work around it is to
  -    specify the correct host name in your configuration.
  -   </LI>
  -   <LI><STRONG>Inadequate checking and verification in your
  -    configuration of Apache</STRONG>
  -    <BR>
  -    If you intend to perform access checking and restriction based upon
  -    the client's host or domain name, you really need to configure
  -    Apache to double-check the origin information it's supplied.  You do
  -    this by adding the <SAMP>-DMAXIMUM_DNS</SAMP> clause to the
  -    <SAMP>EXTRA_CFLAGS</SAMP> definition in your
  -    <SAMP>Configuration</SAMP> file.  For example:
  -    <P>
  -    <DL>
  -     <DD><CODE>EXTRA_CFLAGS=-DMAXIMUM_DNS</CODE>
  -     </DD>
  -    </DL>
  -    <P></P>
  -    <P>
  -    This will cause Apache to be very paranoid about making sure a
  -    particular host address is <EM>really</EM> assigned to the name it
  -    claims to be.  Note that this <EM>can</EM> incur a significant
  -    performance penalty, however, because of all the name resolution
  -    requests being sent to a nameserver.
  -    </P>
  -   </LI>
  -  </OL>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="user-authentication">
  -      <STRONG>How do I set up Apache to require a username and
  -      password to access certain documents?</STRONG>
  -     </A>
  -  <P>
  -  There are several ways to do this; some of the more popular
  -  ones are to use the <A HREF="../mod/mod_auth.html">mod_auth</A>,
  -  <A HREF="../mod/mod_auth_db.html">mod_auth_db</A>, or
  -  <A HREF="../mod/mod_auth_dbm.html">mod_auth_dbm</A> modules.
  -  </P>
  -  <P>
  -  For an explanation on how to implement these restrictions, see
  -  <A HREF="http://www.apacheweek.com/"><CITE>Apache Week</CITE></A>'s
  -  articles on
  -  <A HREF="http://www.apacheweek.com/features/userauth"
  -  ><CITE>Using User Authentication</CITE></A>
  -  or
  -  <A HREF="http://www.apacheweek.com/features/dbmauth"
  -  ><CITE>DBM User Authentication</CITE></A>.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="remote-auth-only">
  -      <STRONG>How do I set up Apache to allow access to certain
  -      documents only if a site is either a local site <EM>or</EM>
  -      the user supplies a password and username?</STRONG>
  -     </A>
  -  <P>
  -  Use the <A HREF="../mod/core.html#satisfy">Satisfy</A> directive,
  -  in particular the <CODE>Satisfy Any</CODE> directive, to require
  -  that only one of the access restrictions be met.  For example,
  -  adding the following configuration to a <SAMP>.htaccess</SAMP>
  -  or server configuration file would restrict access to people who
  -  either are accessing the site from a host under domain.com or
  -  who can supply a valid username and password:
  -  </P>
  -  <P>
  -  <DL>
  -   <DD><CODE>Deny from all
  -    <BR>
  -    Allow from .domain.com
  -    <BR>
  -    AuthType Basic
  -    <BR>
  -    AuthUserFile /usr/local/apache/conf/htpasswd.users
  -    <BR>
  -    AuthName "special directory"
  -    <BR>
  -    Require valid-user
  -    <BR>
  -    Satisfy any</CODE>
  -   </DD>
  -  </DL>
  -  <P></P>
  -  <P>
  -  See the <A HREF="#user-authentication">user authentication</A>
  -  question and the <A HREF="../mod/mod_access.html">mod_access</A>
  -  module for details on how the above directives work.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="authauthoritative">
  -      <STRONG>Why does my authentication give me a server error?</STRONG>
  -     </A>
  -  <P>
  -  Under normal circumstances, the Apache access control modules will
  -  pass unrecognized user IDs on to the next access control module in
  -  line.  Only if the user ID is recognized and the password is validated
  -  (or not) will it give the usual success or &quot;authentication
  -  failed&quot; messages.
  -  </P>
  -  <P>
  -  However, if the last access module in line 'declines' the validation
  -  request (because it has never heard of the user ID or because it is not
  -  configured), the <SAMP>http_request</SAMP> handler will give one of
  -  the following, confusing, errors:
  -  </P>
  -  <UL>
  -   <LI><SAMP>check access</SAMP>
  -   </LI>
  -   <LI><SAMP>check user.  No user file?</SAMP>
  -   </LI>
  -   <LI><SAMP>check access.  No groups file?</SAMP>
  -   </LI>
  -  </UL>
  -  <P>
  -  This does <EM>not</EM> mean that you have to add an
  -  '<SAMP>AuthUserFile&nbsp;/dev/null</SAMP>' line as some magazines suggest!
  -  </P>
  -  <P>
  -  The solution is to ensure that at least the last module is authoritative
  -  and <STRONG>CONFIGURED</STRONG>. By default, <SAMP>mod_auth</SAMP> is
  -  authoritative and will give an OK/Denied, but only if it is configured
  -  with the proper <SAMP>AuthUserFile</SAMP>.  Likewise, if a valid group
  -  is required.  (Remember that the modules are processed in the reverse
  -  order from that in which they appear in your compile-time
  -  <SAMP>Configuration</SAMP> file.)
  -  </P>
  -  <P>
  -  A typical situation for this error is when you are using the
  -  <SAMP>mod_auth_dbm</SAMP>, <SAMP>mod_auth_msql</SAMP>,
  -  <SAMP>mod_auth_mysql</SAMP>, <SAMP>mod_auth_anon</SAMP> or
  -  <SAMP>mod_auth_cookie</SAMP> modules on their own.  These are by
  -  default <STRONG>not</STRONG> authoritative, and this will pass the
  -  buck on to the (non-existent) next authentication module when the
  -  user ID is not in their respective database.  Just add the appropriate
  -  '<SAMP><EM>XXX</EM>Authoritative yes</SAMP>' line to the configuration.
  -  </P>
  -  <P>
  -  In general it is a good idea (though not terribly efficient) to have the
  -  file-based <SAMP>mod_auth</SAMP> a module of last resort. This allows
  -  you to access the web server with a few special passwords even if the
  -  databases are down or corrupted.  This does cost a
  -  file open/seek/close for each request in a protected area.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="auth-on-same-machine">
  -      <STRONG>Do I have to keep the (mSQL) authentication information
  -      on the same machine?</STRONG>
  -     </A>
  -  <P>
  -  Some organizations feel very strongly about keeping the authentication
  -  information on a different machine than the webserver. With the
  -  <SAMP>mod_auth_msql</SAMP>, <SAMP>mod_auth_mysql</SAMP>, and other SQL
  -  modules connecting to (R)DBMses this is quite possible. Just configure
  -  an explicit host to contact.
  -  </P>
  -  <P>
  -  Be aware that with mSQL and Oracle, opening and closing these database
  -  connections is very expensive and time consuming. You might want to
  -  look at the code in the <SAMP>auth_*</SAMP> modules and play with the
  -  compile time flags to alleviate this somewhat, if your RDBMS licences
  -  allow for it.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="msql-slow">
  -      <STRONG>Why is my mSQL authentication terribly slow?</STRONG>
  -     </A>
  -  <P>
  -  You have probably configured the Host by specifying a FQHN,
  -  and thus the <SAMP>libmsql</SAMP> will use a full blown TCP/IP socket
  -  to talk to the database, rather than a fast internal device.  The
  -  <SAMP>libmsql</SAMP>, the mSQL FAQ, and the <SAMP>mod_auth_msql</SAMP>
  -  documentation warn you about this.  If you have to use different
  -  hosts, check out the <SAMP>mod_auth_msql</SAMP> code for
  -  some compile time flags which might - or might not - suit you.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="passwdauth">
  -      <STRONG>Can I use my <SAMP>/etc/passwd</SAMP> file
  -      for Web page authentication?</STRONG>
  -     </A>
  -  <P>
  -  Yes, you can - but it's a <STRONG>very bad idea</STRONG>.  Here are
  -  some of the reasons:
  -  </P>
  -  <UL>
  -   <LI>The Web technology provides no governors on how often or how
  -    rapidly password (authentication failure) retries can be made.  That
  -    means that someone can hammer away at your system's
  -    <SAMP>root</SAMP> password using the Web, using a dictionary or
  -    similar mass attack, just as fast as the wire and your server can
  -    handle the requests.  Most operating systems these days include
  -    attack detection (such as <EM>n</EM> failed passwords for the same
  -    account within <EM>m</EM> seconds) and evasion (breaking the
  -    connection, disabling the account under attack, disabling
  -    <EM>all</EM> logins from that source, <EM>et cetera</EM>), but the
  -    Web does not.
  -   </LI>
  -   <LI>An account under attack isn't notified (unless the server is
  -    heavily modified); there's no &quot;You have 19483 login
  -    failures&quot; message when the legitimate owner logs in.
  -   </LI>
  -   <LI>Without an exhaustive and error-prone examination of the server
  -    logs, you can't tell whether an account has been compromised.
  -    Detecting that an attack has occurred, or is in progress, is fairly
  -    obvious, though - <EM>if</EM> you look at the logs.
  -   </LI>
  -   <LI>Web authentication passwords (at least for Basic authentication)
  -    generally fly across the wire, and through intermediate proxy
  -    systems, in what amounts to plain text.  &quot;O'er the net we
  -    go/Caching all the way;/O what fun it is to surf/Giving my password
  -    away!&quot;
  -   </LI>
  -   <LI>Since HTTP is stateless, information about the authentication is
  -    transmitted <EM>each and every time</EM> a request is made to the
  -    server.  Essentially, the client caches it after the first
  -    successful access, and transmits it without asking for all
  -    subsequent requests to the same server.
  -   </LI>
  -   <LI>It's relatively trivial for someone on your system to put up a
  -    page that will steal the cached password from a client's cache
  -    without them knowing.  Can you say &quot;password grabber&quot;?
  -   </LI>
  -  </UL>
  -  <P>
  -  If you still want to do this in light of the above disadvantages, the
  -  method is left as an exercise for the reader.  It'll void your Apache
  -  warranty, though, and you'll lose all accumulated UNIX guru points.
  -  </P>
  -  <HR>
  - </LI>
  - <LI><A NAME="prompted-twice"><STRONG>Why does Apache ask for my password
  -	      twice before serving a file?</STRONG></a>
  -  <P>
  -  If the hostname under which you are accessing the server is
  -  different than the hostname specified in the 
  -  <A HREF="../mod/core.html#servername"><CODE>ServerName</CODE></A>
  -  directive, then depending on the setting of the
  -  <A HREF="../mod/core.html#usecanonicalname"><CODE>UseCanonicalName</CODE></A>
  -  directive, Apache will redirect you to a new hostname when
  -  constructing self-referential URLs.  This happens, for example, in
  -  the case where you request a directory without including the
  -  trailing slash.
  -  </P>
  -  <P>
  -  When this happens, Apache will ask for authentication once under the
  -  original hostname, perform the redirect, and then ask again under the
  -  new hostname.  For security reasons, the browser must prompt again
  -  for the password when the host name changes.
  -  </P>
  -  <P>
  -  To eliminate this problem you should
  -  </P>
  -  <OL>
  -    <LI>Always use the trailing slash when requesting directories;
  -    <LI>Change the <CODE>ServerName</CODE> to match the name you are
  -        using in the URL; and/or
  -    <LI>Set <CODE>UseCanonicalName off</CODE>.
  -  </OL>
  -  <HR>
  - </LI>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Server Frequently Asked Questions</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache Server Frequently Asked
  +    Questions</h1>
  +
  +    <p>$Revision: 1.7 $ ($Date: 2001/10/08 01:26:54 $)</p>
  +
  +    <p>The latest version of this FAQ is always available from the
  +    main Apache web site, at &lt;<a
  +    href="http://httpd.apache.org/docs/misc/FAQ.html"
  +    rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>&gt;.</p>
  +    <!-- Notes about changes:                                           -->
  +    <!--  - If adding a relative link to another part of the            -->
  +    <!--    documentation, *do* include the ".html" portion.  There's a -->
  +    <!--    good chance that the user will be reading the documentation -->
  +    <!--    on his own system, which may not be configured for          -->
  +    <!--    multiviews.                                                 -->
  +    <!--  - When adding items, make sure they're put in the right place -->
  +    <!--    - verify that the numbering matches up.                     -->
  +    <!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  +    <!--    correctly in a reliable way when this is converted to text  -->
  +    <!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  +    <!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  +    <!--    the horizontal and vertical indenting right.                -->
  +    <!--  - Don't forget to include an HR tag after the last /P tag     -->
  +    <!--    but before the /LI in an item.                              -->
  +
  +    <p>If you are reading a text-only version of this FAQ, you may
  +    find numbers enclosed in brackets (such as "[12]"). These refer
  +    to the list of reference URLs to be found at the end of the
  +    document. These references do not appear, and are not needed,
  +    for the hypertext version.</p>
  +
  +    <h2>The Questions</h2>
  +
  +    <ol type="A">
  +      <!--#endif -->
  +      <!--#if expr="$TOC || $STANDALONE" -->
  +
  +      <li value="7">
  +        <strong>Authentication and Access Restrictions</strong> 
  +
  +        <ol>
  +          <li><a href="#dnsauth">Why isn't restricting access by
  +          host or domain name working correctly?</a></li>
  +
  +          <li><a href="#user-authentication">How do I set up Apache
  +          to require a username and password to access certain
  +          documents?</a></li>
  +
  +          <li><a href="#remote-auth-only">How do I set up Apache to
  +          allow access to certain documents only if a site is
  +          either a local site <em>or</em> the user supplies a
  +          password and username?</a></li>
  +
  +          <li><a href="#authauthoritative">Why does my
  +          authentication give me a server error?</a></li>
  +
  +          <li><a href="#auth-on-same-machine">Do I have to keep the
  +          (mSQL) authentication information on the same
  +          machine?</a></li>
  +
  +          <li><a href="#msql-slow">Why is my mSQL authentication
  +          terribly slow?</a></li>
  +
  +          <li><a href="#passwdauth">Can I use my
  +          <samp>/etc/passwd</samp> file for Web page
  +          authentication?</a></li>
  +
  +          <li><a href="#prompted-twice">Why does Apache ask for my
  +          password twice before serving a file?</a></li>
  +        </ol>
  +      </li>
  +      <!--#endif -->
  +      <!--#if expr="$STANDALONE" -->
  +    </ol>
  +    <hr />
  +
  +    <h2>The Answers</h2>
  +    <!--#endif -->
  +    <!--#if expr="! $TOC" -->
  +
  +    <h3>G. Authentication and Access Restrictions</h3>
  +
  +    <ol>
  +      <li>
  +        <a id="dnsauth" name="dnsauth"><strong>Why isn't
  +        restricting access by host or domain name working
  +        correctly?</strong></a> 
  +
  +        <p>Two of the most common causes of this are:</p>
  +
  +        <ol>
  +          <li><strong>An error, inconsistency, or unexpected
  +          mapping in the DNS registration</strong><br />
  +           This happens frequently: your configuration restricts
  +          access to <samp>Host.FooBar.Com</samp>, but you can't get
  +          in from that host. The usual reason for this is that
  +          <samp>Host.FooBar.Com</samp> is actually an alias for
  +          another name, and when Apache performs the
  +          address-to-name lookup it's getting the <em>real</em>
  +          name, not <samp>Host.FooBar.Com</samp>. You can verify
  +          this by checking the reverse lookup yourself. The easiest
  +          way to work around it is to specify the correct host name
  +          in your configuration.</li>
  +
  +          <li>
  +            <strong>Inadequate checking and verification in your
  +            configuration of Apache</strong><br />
  +             If you intend to perform access checking and
  +            restriction based upon the client's host or domain
  +            name, you really need to configure Apache to
  +            double-check the origin information it's supplied. You
  +            do this by adding the <samp>-DMAXIMUM_DNS</samp> clause
  +            to the <samp>EXTRA_CFLAGS</samp> definition in your
  +            <samp>Configuration</samp> file. For example: 
  +
  +            <dl>
  +              <dd><code>EXTRA_CFLAGS=-DMAXIMUM_DNS</code></dd>
  +            </dl>
  +
  +            <p>This will cause Apache to be very paranoid about
  +            making sure a particular host address is
  +            <em>really</em> assigned to the name it claims to be.
  +            Note that this <em>can</em> incur a significant
  +            performance penalty, however, because of all the name
  +            resolution requests being sent to a nameserver.</p>
  +          </li>
  +        </ol>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="user-authentication"
  +        name="user-authentication"><strong>How do I set up Apache
  +        to require a username and password to access certain
  +        documents?</strong></a> 
  +
  +        <p>There are several ways to do this; some of the more
  +        popular ones are to use the <a
  +        href="../mod/mod_auth.html">mod_auth</a>, <a
  +        href="../mod/mod_auth_db.html">mod_auth_db</a>, or <a
  +        href="../mod/mod_auth_dbm.html">mod_auth_dbm</a>
  +        modules.</p>
  +
  +        <p>For an explanation on how to implement these
  +        restrictions, see <a
  +        href="http://www.apacheweek.com/"><cite>Apache
  +        Week</cite></a>'s articles on <a
  +        href="http://www.apacheweek.com/features/userauth"><cite>Using
  +        User Authentication</cite></a> or <a
  +        href="http://www.apacheweek.com/features/dbmauth"><cite>DBM
  +        User Authentication</cite></a>.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="remote-auth-only"
  +        name="remote-auth-only"><strong>How do I set up Apache to
  +        allow access to certain documents only if a site is either
  +        a local site <em>or</em> the user supplies a password and
  +        username?</strong></a> 
  +
  +        <p>Use the <a href="../mod/core.html#satisfy">Satisfy</a>
  +        directive, in particular the <code>Satisfy Any</code>
  +        directive, to require that only one of the access
  +        restrictions be met. For example, adding the following
  +        configuration to a <samp>.htaccess</samp> or server
  +        configuration file would restrict access to people who
  +        either are accessing the site from a host under domain.com
  +        or who can supply a valid username and password:</p>
  +
  +        <dl>
  +          <dd><code>Deny from all<br />
  +           Allow from .domain.com<br />
  +           AuthType Basic<br />
  +           AuthUserFile /usr/local/apache/conf/htpasswd.users<br />
  +           AuthName "special directory"<br />
  +           Require valid-user<br />
  +           Satisfy any</code></dd>
  +        </dl>
  +
  +        <p>See the <a href="#user-authentication">user
  +        authentication</a> question and the <a
  +        href="../mod/mod_access.html">mod_access</a> module for
  +        details on how the above directives work.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="authauthoritative"
  +        name="authauthoritative"><strong>Why does my authentication
  +        give me a server error?</strong></a> 
  +
  +        <p>Under normal circumstances, the Apache access control
  +        modules will pass unrecognized user IDs on to the next
  +        access control module in line. Only if the user ID is
  +        recognized and the password is validated (or not) will it
  +        give the usual success or "authentication failed"
  +        messages.</p>
  +
  +        <p>However, if the last access module in line 'declines'
  +        the validation request (because it has never heard of the
  +        user ID or because it is not configured), the
  +        <samp>http_request</samp> handler will give one of the
  +        following, confusing, errors:</p>
  +
  +        <ul>
  +          <li><samp>check access</samp></li>
  +
  +          <li><samp>check user. No user file?</samp></li>
  +
  +          <li><samp>check access. No groups file?</samp></li>
  +        </ul>
  +
  +        <p>This does <em>not</em> mean that you have to add an
  +        '<samp>AuthUserFile&nbsp;/dev/null</samp>' line as some
  +        magazines suggest!</p>
  +
  +        <p>The solution is to ensure that at least the last module
  +        is authoritative and <strong>CONFIGURED</strong>. By
  +        default, <samp>mod_auth</samp> is authoritative and will
  +        give an OK/Denied, but only if it is configured with the
  +        proper <samp>AuthUserFile</samp>. Likewise, if a valid
  +        group is required. (Remember that the modules are processed
  +        in the reverse order from that in which they appear in your
  +        compile-time <samp>Configuration</samp> file.)</p>
  +
  +        <p>A typical situation for this error is when you are using
  +        the <samp>mod_auth_dbm</samp>, <samp>mod_auth_msql</samp>,
  +        <samp>mod_auth_mysql</samp>, <samp>mod_auth_anon</samp> or
  +        <samp>mod_auth_cookie</samp> modules on their own. These
  +        are by default <strong>not</strong> authoritative, and this
  +        will pass the buck on to the (non-existent) next
  +        authentication module when the user ID is not in their
  +        respective database. Just add the appropriate
  +        '<samp><em>XXX</em>Authoritative yes</samp>' line to the
  +        configuration.</p>
  +
  +        <p>In general it is a good idea (though not terribly
  +        efficient) to have the file-based <samp>mod_auth</samp> a
  +        module of last resort. This allows you to access the web
  +        server with a few special passwords even if the databases
  +        are down or corrupted. This does cost a file
  +        open/seek/close for each request in a protected area.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="auth-on-same-machine"
  +        name="auth-on-same-machine"><strong>Do I have to keep the
  +        (mSQL) authentication information on the same
  +        machine?</strong></a> 
  +
  +        <p>Some organizations feel very strongly about keeping the
  +        authentication information on a different machine than the
  +        webserver. With the <samp>mod_auth_msql</samp>,
  +        <samp>mod_auth_mysql</samp>, and other SQL modules
  +        connecting to (R)DBMses this is quite possible. Just
  +        configure an explicit host to contact.</p>
  +
  +        <p>Be aware that with mSQL and Oracle, opening and closing
  +        these database connections is very expensive and time
  +        consuming. You might want to look at the code in the
  +        <samp>auth_*</samp> modules and play with the compile time
  +        flags to alleviate this somewhat, if your RDBMS licences
  +        allow for it.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="msql-slow" name="msql-slow"><strong>Why is my mSQL
  +        authentication terribly slow?</strong></a> 
  +
  +        <p>You have probably configured the Host by specifying a
  +        FQHN, and thus the <samp>libmsql</samp> will use a full
  +        blown TCP/IP socket to talk to the database, rather than a
  +        fast internal device. The <samp>libmsql</samp>, the mSQL
  +        FAQ, and the <samp>mod_auth_msql</samp> documentation warn
  +        you about this. If you have to use different hosts, check
  +        out the <samp>mod_auth_msql</samp> code for some compile
  +        time flags which might - or might not - suit you.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="passwdauth" name="passwdauth"><strong>Can I use my
  +        <samp>/etc/passwd</samp> file for Web page
  +        authentication?</strong></a> 
  +
  +        <p>Yes, you can - but it's a <strong>very bad
  +        idea</strong>. Here are some of the reasons:</p>
  +
  +        <ul>
  +          <li>The Web technology provides no governors on how often
  +          or how rapidly password (authentication failure) retries
  +          can be made. That means that someone can hammer away at
  +          your system's <samp>root</samp> password using the Web,
  +          using a dictionary or similar mass attack, just as fast
  +          as the wire and your server can handle the requests. Most
  +          operating systems these days include attack detection
  +          (such as <em>n</em> failed passwords for the same account
  +          within <em>m</em> seconds) and evasion (breaking the
  +          connection, disabling the account under attack, disabling
  +          <em>all</em> logins from that source, <em>et
  +          cetera</em>), but the Web does not.</li>
  +
  +          <li>An account under attack isn't notified (unless the
  +          server is heavily modified); there's no "You have 19483
  +          login failures" message when the legitimate owner logs
  +          in.</li>
  +
  +          <li>Without an exhaustive and error-prone examination of
  +          the server logs, you can't tell whether an account has
  +          been compromised. Detecting that an attack has occurred,
  +          or is in progress, is fairly obvious, though -
  +          <em>if</em> you look at the logs.</li>
  +
  +          <li>Web authentication passwords (at least for Basic
  +          authentication) generally fly across the wire, and
  +          through intermediate proxy systems, in what amounts to
  +          plain text. "O'er the net we go/Caching all the way;/O
  +          what fun it is to surf/Giving my password away!"</li>
  +
  +          <li>Since HTTP is stateless, information about the
  +          authentication is transmitted <em>each and every
  +          time</em> a request is made to the server. Essentially,
  +          the client caches it after the first successful access,
  +          and transmits it without asking for all subsequent
  +          requests to the same server.</li>
  +
  +          <li>It's relatively trivial for someone on your system to
  +          put up a page that will steal the cached password from a
  +          client's cache without them knowing. Can you say
  +          "password grabber"?</li>
  +        </ul>
  +
  +        <p>If you still want to do this in light of the above
  +        disadvantages, the method is left as an exercise for the
  +        reader. It'll void your Apache warranty, though, and you'll
  +        lose all accumulated UNIX guru points.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="prompted-twice" name="prompted-twice"><strong>Why
  +        does Apache ask for my password twice before serving a
  +        file?</strong></a> 
  +
  +        <p>If the hostname under which you are accessing the server
  +        is different than the hostname specified in the <a
  +        href="../mod/core.html#servername"><code>ServerName</code></a>
  +        directive, then depending on the setting of the <a
  +        href="../mod/core.html#usecanonicalname"><code>UseCanonicalName</code></a>
  +        directive, Apache will redirect you to a new hostname when
  +        constructing self-referential URLs. This happens, for
  +        example, in the case where you request a directory without
  +        including the trailing slash.</p>
  +
  +        <p>When this happens, Apache will ask for authentication
  +        once under the original hostname, perform the redirect, and
  +        then ask again under the new hostname. For security
  +        reasons, the browser must prompt again for the password
  +        when the host name changes.</p>
  +
  +        <p>To eliminate this problem you should</p>
  +
  +        <ol>
  +          <li>Always use the trailing slash when requesting
  +          directories;</li>
  +
  +          <li>Change the <code>ServerName</code> to match the name
  +          you are using in the URL; and/or</li>
  +
  +          <li>Set <code>UseCanonicalName off</code>.</li>
  +        </ol>
  +        <hr />
  +      </li>
  +    </ol>
  +    <!--#endif -->
  +    <!--#if expr="$STANDALONE" -->
  +    <!-- Don't forget to add HR tags at the end of each list item.. -->
  +    <!--#include virtual="footer.html" -->
  +    <!--#endif -->
  +  </body>
  +</html>
   
  -</OL>
  -<!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -  <!-- Don't forget to add HR tags at the end of each list item.. -->
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  -<!--#endif -->
  
  
  
  1.4       +265 -260  httpd-docs-1.3/htdocs/manual/misc/FAQ-H.html
  
  Index: FAQ-H.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/FAQ-H.html,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- FAQ-H.html	2000/11/12 00:25:31	1.3
  +++ FAQ-H.html	2001/10/08 01:26:54	1.4
  @@ -1,267 +1,272 @@
   <!--#if expr="$FAQMASTER" -->
  - <!--#set var="STANDALONE" value="" -->
  - <!--#set var="INCLUDED" value="YES" -->
  - <!--#if expr="$QUERY_STRING = TOC" -->
  -  <!--#set var="TOC" value="YES" -->
  -  <!--#set var="CONTENT" value="" -->
  - <!--#else -->
  -  <!--#set var="TOC" value="" -->
  -  <!--#set var="CONTENT" value="YES" -->
  - <!--#endif -->
  +<!--#set var="STANDALONE" value="" -->
  +<!--#set var="INCLUDED" value="YES" -->
  +<!--#if expr="$QUERY_STRING = TOC" -->
  +<!--#set var="TOC" value="YES" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#else -->
  - <!--#set var="STANDALONE" value="YES" -->
  - <!--#set var="INCLUDED" value="" -->
  - <!--#set var="TOC" value="" -->
  - <!--#set var="CONTENT" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="YES" -->
   <!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  - <HEAD>
  -  <TITLE>Apache Server Frequently Asked Questions</TITLE>
  - </HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  - <BODY
  -  BGCOLOR="#FFFFFF"
  -  TEXT="#000000"
  -  LINK="#0000FF"
  -  VLINK="#000080"
  -  ALINK="#FF0000"
  - >
  -  <!--#include virtual="header.html" -->
  -  <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>
  -  <P>
  -  $Revision: 1.3 $ ($Date: 2000/11/12 00:25:31 $)
  -  </P>
  -  <P>
  -  The latest version of this FAQ is always available from the main
  -  Apache web site, at
  -  &lt;<A
  -       HREF="http://httpd.apache.org/docs/misc/FAQ.html"
  -       REL="Help"
  -      ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>&gt;.
  -  </P>
  -<!-- Notes about changes:                                           -->
  -<!--  - If adding a relative link to another part of the            -->
  -<!--    documentation, *do* include the ".html" portion.  There's a -->
  -<!--    good chance that the user will be reading the documentation -->
  -<!--    on his own system, which may not be configured for          -->
  -<!--    multiviews.                                                 -->
  -<!--  - When adding items, make sure they're put in the right place -->
  -<!--    - verify that the numbering matches up.                     -->
  -<!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  -<!--    correctly in a reliable way when this is converted to text  -->
  -<!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  -<!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  -<!--    the horizontal and vertical indenting right.                -->
  -<!--  - Don't forget to include an HR tag after the last /P tag     -->
  -<!--    but before the /LI in an item.                              -->
  -  <P>
  -  If you are reading a text-only version of this FAQ, you may find numbers
  -  enclosed in brackets (such as &quot;[12]&quot;).  These refer to the list of
  -  reference URLs to be found at the end of the document.  These references
  -  do not appear, and are not needed, for the hypertext version.
  -  </P>
  -  <H2>The Questions</H2>
  -<OL TYPE="A">
  -<!--#endif -->
  -<!--#if expr="$TOC || $STANDALONE" -->
  - <LI VALUE="8"><STRONG>URL Rewriting</STRONG>
  -  <OL>
  -   <LI><A HREF="#rewrite-more-config">Where can I find mod_rewrite rulesets
  -        which already solve particular URL-related problems?</A>
  -   </LI>
  -   <LI><A HREF="#rewrite-article">Where can I find any published information
  -        about URL-manipulations and mod_rewrite?</A>
  -   </LI>
  -   <LI><A HREF="#rewrite-complexity">Why is mod_rewrite so difficult to learn
  -        and seems so complicated?</A>
  -   </LI>
  -   <LI><A HREF="#rewrite-dontwork">What can I do if my RewriteRules don't work
  -        as expected?</A>
  -   </LI>
  -   <LI><A HREF="#rewrite-prefixdocroot">Why don't some of my URLs get
  -        prefixed with DocumentRoot when using mod_rewrite?</A>
  -   </LI>
  -   <LI><A HREF="#rewrite-nocase">How can I make all my URLs case-insensitive
  -        with mod_rewrite?</A>
  -   </LI>
  -   <LI><A HREF="#rewrite-virthost">Why are RewriteRules in my VirtualHost
  -        parts ignored?</A>
  -   </LI>
  -   <LI><A HREF="#rewrite-envwhitespace">How can I use strings with whitespaces
  -        in RewriteRule's ENV flag?</A>
  -   </LI>
  -  </OL>
  - </LI>
  +<!--#else -->
  +<!--#set var="STANDALONE" value="YES" -->
  +<!--#set var="INCLUDED" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#endif -->
   <!--#if expr="$STANDALONE" -->
  -</OL>
  -
  -<HR>
  -
  -  <H2>The Answers</H2>
  -<!--#endif -->
  -<!--#if expr="! $TOC" -->
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -  <H3>H. URL Rewriting</H3>
  -<OL>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Server Frequently Asked Questions</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache Server Frequently Asked
  +    Questions</h1>
  +
  +    <p>$Revision: 1.4 $ ($Date: 2001/10/08 01:26:54 $)</p>
  +
  +    <p>The latest version of this FAQ is always available from the
  +    main Apache web site, at &lt;<a
  +    href="http://httpd.apache.org/docs/misc/FAQ.html"
  +    rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>&gt;.</p>
  +    <!-- Notes about changes:                                           -->
  +    <!--  - If adding a relative link to another part of the            -->
  +    <!--    documentation, *do* include the ".html" portion.  There's a -->
  +    <!--    good chance that the user will be reading the documentation -->
  +    <!--    on his own system, which may not be configured for          -->
  +    <!--    multiviews.                                                 -->
  +    <!--  - When adding items, make sure they're put in the right place -->
  +    <!--    - verify that the numbering matches up.                     -->
  +    <!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  +    <!--    correctly in a reliable way when this is converted to text  -->
  +    <!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  +    <!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  +    <!--    the horizontal and vertical indenting right.                -->
  +    <!--  - Don't forget to include an HR tag after the last /P tag     -->
  +    <!--    but before the /LI in an item.                              -->
  +
  +    <p>If you are reading a text-only version of this FAQ, you may
  +    find numbers enclosed in brackets (such as "[12]"). These refer
  +    to the list of reference URLs to be found at the end of the
  +    document. These references do not appear, and are not needed,
  +    for the hypertext version.</p>
  +
  +    <h2>The Questions</h2>
  +
  +    <ol type="A">
  +      <!--#endif -->
  +      <!--#if expr="$TOC || $STANDALONE" -->
  +
  +      <li value="8">
  +        <strong>URL Rewriting</strong> 
  +
  +        <ol>
  +          <li><a href="#rewrite-more-config">Where can I find
  +          mod_rewrite rulesets which already solve particular
  +          URL-related problems?</a></li>
  +
  +          <li><a href="#rewrite-article">Where can I find any
  +          published information about URL-manipulations and
  +          mod_rewrite?</a></li>
  +
  +          <li><a href="#rewrite-complexity">Why is mod_rewrite so
  +          difficult to learn and seems so complicated?</a></li>
  +
  +          <li><a href="#rewrite-dontwork">What can I do if my
  +          RewriteRules don't work as expected?</a></li>
  +
  +          <li><a href="#rewrite-prefixdocroot">Why don't some of my
  +          URLs get prefixed with DocumentRoot when using
  +          mod_rewrite?</a></li>
  +
  +          <li><a href="#rewrite-nocase">How can I make all my URLs
  +          case-insensitive with mod_rewrite?</a></li>
  +
  +          <li><a href="#rewrite-virthost">Why are RewriteRules in
  +          my VirtualHost parts ignored?</a></li>
  +
  +          <li><a href="#rewrite-envwhitespace">How can I use
  +          strings with whitespaces in RewriteRule's ENV
  +          flag?</a></li>
  +        </ol>
  +      </li>
  +      <!--#endif -->
  +      <!--#if expr="$STANDALONE" -->
  +    </ol>
  +    <hr />
  +
  +    <h2>The Answers</h2>
  +    <!--#endif -->
  +    <!--#if expr="! $TOC" -->
  +
  +    <h3>H. URL Rewriting</h3>
  +
  +    <ol>
  +      <li>
  +        <a id="rewrite-more-config"
  +        name="rewrite-more-config"><strong>Where can I find
  +        mod_rewrite rulesets which already solve particular
  +        URL-related problems?</strong></a> 
  +
  +        <p>There is a collection of <a
  +        href="http://www.engelschall.com/pw/apache/rewriteguide/">Practical
  +        Solutions for URL-Manipulation</a> where you can find all
  +        typical solutions the author of <a
  +        href="../mod/mod_rewrite.html"><samp>mod_rewrite</samp></a>
  +        currently knows of. If you have more interesting rulesets
  +        which solve particular problems not currently covered in
  +        this document, send it to <a
  +        href="mailto:rse@apache.org">Ralf S. Engelschall</a> for
  +        inclusion. The other webmasters will thank you for avoiding
  +        the reinvention of the wheel.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="rewrite-article"
  +        name="rewrite-article"><strong>Where can I find any
  +        published information about URL-manipulations and
  +        mod_rewrite?</strong></a> 
  +
  +        <p>There is an article from <a
  +        href="mailto:rse@apache.org">Ralf S. Engelschall</a> about
  +        URL-manipulations based on <a
  +        href="../mod/mod_rewrite.html"><samp>mod_rewrite</samp></a>
  +        in the "iX Multiuser Multitasking Magazin" issue #12/96.
  +        The german (original) version can be read online at &lt;<a
  +        href="http://www.heise.de/ix/artikel/9612149/">http://www.heise.de/ix/artikel/9612149/</a>&gt;,
  +        the English (translated) version can be found at &lt;<a
  +        href="http://www.heise.de/ix/artikel/E/9612149/">http://www.heise.de/ix/artikel/E/9612149/</a>&gt;.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="rewrite-complexity"
  +        name="rewrite-complexity"><strong>Why is mod_rewrite so
  +        difficult to learn and seems so complicated?</strong></a> 
  +
  +        <p>Hmmm... there are a lot of reasons. First, mod_rewrite
  +        itself is a powerful module which can help you in really
  +        <strong>all</strong> aspects of URL rewriting, so it can be
  +        no trivial module per definition. To accomplish its hard
  +        job it uses software leverage and makes use of a powerful
  +        regular expression library by Henry Spencer which is an
  +        integral part of Apache since its version 1.2. And regular
  +        expressions itself can be difficult to newbies, while
  +        providing the most flexible power to the advanced
  +        hacker.</p>
  +
  +        <p>On the other hand mod_rewrite has to work inside the
  +        Apache API environment and needs to do some tricks to fit
  +        there. For instance the Apache API as of 1.x really was not
  +        designed for URL rewriting at the <tt>.htaccess</tt> level
  +        of processing. Or the problem of multiple rewrites in
  +        sequence, which is also not handled by the API per design.
  +        To provide this features mod_rewrite has to do some special
  +        (but API compliant!) handling which leads to difficult
  +        processing inside the Apache kernel. While the user usually
  +        doesn't see anything of this processing, it can be
  +        difficult to find problems when some of your RewriteRules
  +        seem not to work.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="rewrite-dontwork"
  +        name="rewrite-dontwork"><strong>What can I do if my
  +        RewriteRules don't work as expected?</strong></a> 
  +
  +        <p>Use "<samp>RewriteLog somefile</samp>" and
  +        "<samp>RewriteLogLevel 9</samp>" and have a precise look at
  +        the steps the rewriting engine performs. This is really the
  +        only one and best way to debug your rewriting
  +        configuration.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="rewrite-prefixdocroot"
  +        name="rewrite-prefixdocroot"><strong>Why don't some of my
  +        URLs get prefixed with DocumentRoot when using
  +        mod_rewrite?</strong></a> 
  +
  +        <p>If the rule starts with <samp>/somedir/...</samp> make
  +        sure that really no <samp>/somedir</samp> exists on the
  +        filesystem if you don't want to lead the URL to match this
  +        directory, <em>i.e.</em>, there must be no root directory
  +        named <samp>somedir</samp> on the filesystem. Because if
  +        there is such a directory, the URL will not get prefixed
  +        with DocumentRoot. This behavior looks ugly, but is really
  +        important for some other aspects of URL rewriting.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="rewrite-nocase" name="rewrite-nocase"><strong>How
  +        can I make all my URLs case-insensitive with
  +        mod_rewrite?</strong></a> 
  +
  +        <p>You can't! The reasons are: first, that, case
  +        translations for arbitrary length URLs cannot be done
  +        <em>via</em> regex patterns and corresponding
  +        substitutions. One needs a per-character pattern like the
  +        sed/Perl <samp>tr|..|..|</samp> feature. Second, just
  +        making URLs always upper or lower case does not solve the
  +        whole problem of case-INSENSITIVE URLs, because URLs
  +        actually have to be rewritten to the correct case-variant
  +        for the file residing on the filesystem in order to allow
  +        Apache to access the file. And the Unix filesystem is
  +        always case-SENSITIVE.</p>
  +
  +        <p>But there is a module named <code><a
  +        href="../mod/mod_speling.html">mod_speling.c</a></code> in
  +        the Apache distribution. Try this module to help correct
  +        people who use mis-cased URLs.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="rewrite-virthost"
  +        name="rewrite-virthost"><strong>Why are RewriteRules in my
  +        VirtualHost parts ignored?</strong></a> 
  +
  +        <p>Because you have to enable the engine for every virtual
  +        host explicitly due to security concerns. Just add a
  +        "RewriteEngine on" to your virtual host configuration
  +        parts.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="rewrite-envwhitespace"
  +        name="rewrite-envwhitespace"><strong>How can I use strings
  +        with whitespaces in RewriteRule's ENV flag?</strong></a> 
  +
  +        <p>There is only one ugly solution: You have to surround
  +        the complete flag argument by quotation marks
  +        (<samp>"[E=...]"</samp>). Notice: The argument to quote
  +        here is not the argument to the E-flag, it is the argument
  +        of the Apache config file parser, <em>i.e.</em>, the third
  +        argument of the RewriteRule here. So you have to write
  +        <samp>"[E=any text with whitespaces]"</samp>.</p>
  +        <hr />
  +      </li>
  +    </ol>
  +    <!--#endif -->
  +    <!--#if expr="$STANDALONE" -->
  +    <!-- Don't forget to add HR tags at the end of each list item.. -->
  +    <!--#include virtual="footer.html" -->
  +    <!--#endif -->
  +  </body>
  +</html>
   
  - <LI><A NAME="rewrite-more-config">
  -      <STRONG>Where can I find mod_rewrite rulesets which already solve
  -      particular URL-related problems?</STRONG>
  -     </A>
  -  <P>
  -  There is a collection of 
  -  <A HREF="http://www.engelschall.com/pw/apache/rewriteguide/"
  -  >Practical Solutions for URL-Manipulation</A>
  -  where you can
  -  find all typical solutions the author of 
  -  <A HREF="../mod/mod_rewrite.html"><SAMP>mod_rewrite</SAMP></A> 
  -  currently knows of. If you have more
  -  interesting rulesets which solve particular problems not currently covered in
  -  this document, send it to 
  -  <A HREF="mailto:rse@apache.org">Ralf S. Engelschall</A>
  -  for inclusion. The
  -  other webmasters will thank you for avoiding the reinvention of the wheel.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="rewrite-article">
  -      <STRONG>Where can I find any published information about
  -      URL-manipulations and mod_rewrite?</STRONG>
  -     </A>
  -  <P>
  -  There is an article from 
  -  <A HREF="mailto:rse@apache.org"
  -  >Ralf S. Engelschall</A>
  -  about URL-manipulations based on
  -  <A HREF="../mod/mod_rewrite.html"><SAMP>mod_rewrite</SAMP></A> 
  -  in the &quot;iX Multiuser Multitasking Magazin&quot; issue #12/96. The
  -  german (original) version
  -  can be read online at 
  -  &lt;<A HREF="http://www.heise.de/ix/artikel/9612149/"
  -      >http://www.heise.de/ix/artikel/9612149/</A>&gt;,
  -  the English (translated) version can be found at 
  -  &lt;<A HREF="http://www.heise.de/ix/artikel/E/9612149/"
  -      >http://www.heise.de/ix/artikel/E/9612149/</A>&gt;.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="rewrite-complexity">
  -      <STRONG>Why is mod_rewrite so difficult to learn and seems so
  -      complicated?</STRONG>
  -     </A>
  -  <P>
  -  Hmmm... there are a lot of reasons. First, mod_rewrite itself is a powerful
  -  module which can help you in really <STRONG>all</STRONG> aspects of URL
  -  rewriting, so it can be no trivial module per definition. To accomplish
  -  its hard job it uses software leverage and makes use of a powerful regular
  -  expression
  -  library by Henry Spencer which is an integral part of Apache since its
  -  version 1.2.  And regular expressions itself can be difficult to newbies,
  -  while providing the most flexible power to the advanced hacker. 
  -  </P>
  -  <P>
  -  On the other hand mod_rewrite has to work inside the Apache API environment
  -  and needs to do some tricks to fit there. For instance the Apache API as of
  -  1.x really was not designed for URL rewriting at the <TT>.htaccess</TT>
  -  level of processing. Or the problem of multiple rewrites in sequence, which
  -  is also not handled by the API per design. To provide this features
  -  mod_rewrite has to do some special (but API compliant!) handling which leads
  -  to difficult processing inside the Apache kernel. While the user usually
  -  doesn't see anything of this processing, it can be difficult to find
  -  problems when some of your RewriteRules seem not to work.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="rewrite-dontwork">
  -      <STRONG>What can I do if my RewriteRules don't work as expected?
  -      </STRONG>
  -     </A>
  -  <P>
  -  Use &quot;<SAMP>RewriteLog somefile</SAMP>&quot; and
  -  &quot;<SAMP>RewriteLogLevel 9</SAMP>&quot; and have a precise look at the
  -  steps the rewriting engine performs. This is really the only one and best
  -  way to debug your rewriting configuration.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="rewrite-prefixdocroot"><STRONG>Why don't some of my URLs
  -      get prefixed with DocumentRoot when using mod_rewrite?</STRONG>
  -     </A>
  -  <P>
  -  If the rule starts with <SAMP>/somedir/...</SAMP> make sure that
  -  really no <SAMP>/somedir</SAMP> exists on the filesystem if you
  -  don't want to lead the URL to match this directory, <EM>i.e.</EM>,
  -  there must be no root directory named <SAMP>somedir</SAMP> on the
  -  filesystem. Because if there is such a directory, the URL will not
  -  get prefixed with DocumentRoot. This behaviour looks ugly, but is
  -  really important for some other aspects of URL rewriting.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="rewrite-nocase">
  -      <STRONG>How can I make all my URLs case-insensitive with mod_rewrite?
  -      </STRONG>
  -     </A>
  -  <P>
  -  You can't! The reasons are: first, that, case translations for
  -  arbitrary length URLs cannot be done <EM>via</EM> regex patterns and
  -  corresponding substitutions.  One needs a per-character pattern like
  -  the sed/Perl <SAMP>tr|..|..|</SAMP> feature.  Second, just making
  -  URLs always upper or lower case does not solve the whole problem of
  -  case-INSENSITIVE URLs, because URLs actually have to be rewritten to
  -  the correct case-variant for the file residing on the filesystem
  -  in order to allow Apache to access the file.  And
  -  the Unix filesystem is always case-SENSITIVE.
  -  </P>
  -  <P>
  -  But there is a module named <CODE><A
  -  HREF="../mod/mod_speling.html">mod_speling.c</A></CODE> in the
  -  Apache distribution. Try this module to help correct people who use
  -  mis-cased URLs.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="rewrite-virthost">
  -      <STRONG> Why are RewriteRules in my VirtualHost parts ignored?</STRONG>
  -     </A>
  -  <P>
  -  Because you have to enable the engine for every virtual host explicitly due
  -  to security concerns. Just add a &quot;RewriteEngine on&quot; to your
  -  virtual host configuration parts.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="rewrite-envwhitespace">
  -      <STRONG> How can I use strings with whitespaces in RewriteRule's ENV
  -      flag?</STRONG>
  -     </A>
  -  <P>
  -  There is only one ugly solution: You have to surround the complete
  -  flag argument by quotation marks (<SAMP>"[E=...]"</SAMP>). Notice:
  -  The argument to quote here is not the argument to the E-flag, it is
  -  the argument of the Apache config file parser, <EM>i.e.</EM>, the
  -  third argument of the RewriteRule here.  So you have to write
  -  <SAMP>"[E=any text with whitespaces]"</SAMP>.
  -  </P>
  -  <HR>
  - </LI>
  -
  -</OL>
  -<!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -  <!-- Don't forget to add HR tags at the end of each list item.. -->
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  -<!--#endif -->
  
  
  
  1.15      +319 -298  httpd-docs-1.3/htdocs/manual/misc/FAQ-I.html
  
  Index: FAQ-I.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/FAQ-I.html,v
  retrieving revision 1.14
  retrieving revision 1.15
  diff -u -r1.14 -r1.15
  --- FAQ-I.html	2001/01/28 00:16:01	1.14
  +++ FAQ-I.html	2001/10/08 01:26:54	1.15
  @@ -1,305 +1,326 @@
   <!--#if expr="$FAQMASTER" -->
  - <!--#set var="STANDALONE" value="" -->
  - <!--#set var="INCLUDED" value="YES" -->
  - <!--#if expr="$QUERY_STRING = TOC" -->
  -  <!--#set var="TOC" value="YES" -->
  -  <!--#set var="CONTENT" value="" -->
  - <!--#else -->
  -  <!--#set var="TOC" value="" -->
  -  <!--#set var="CONTENT" value="YES" -->
  - <!--#endif -->
  +<!--#set var="STANDALONE" value="" -->
  +<!--#set var="INCLUDED" value="YES" -->
  +<!--#if expr="$QUERY_STRING = TOC" -->
  +<!--#set var="TOC" value="YES" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#else -->
  - <!--#set var="STANDALONE" value="YES" -->
  - <!--#set var="INCLUDED" value="" -->
  - <!--#set var="TOC" value="" -->
  - <!--#set var="CONTENT" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="YES" -->
   <!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  - <HEAD>
  -  <TITLE>Apache Server Frequently Asked Questions</TITLE>
  - </HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  - <BODY
  -  BGCOLOR="#FFFFFF"
  -  TEXT="#000000"
  -  LINK="#0000FF"
  -  VLINK="#000080"
  -  ALINK="#FF0000"
  - >
  -  <!--#include virtual="header.html" -->
  -  <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>
  -  <P>
  -  $Revision: 1.14 $ ($Date: 2001/01/28 00:16:01 $)
  -  </P>
  -  <P>
  -  The latest version of this FAQ is always available from the main
  -  Apache web site, at
  -  &lt;<A
  -       HREF="http://httpd.apache.org/docs/misc/FAQ.html"
  -       REL="Help"
  -      ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>&gt;.
  -  </P>
  -<!-- Notes about changes:                                           -->
  -<!--  - If adding a relative link to another part of the            -->
  -<!--    documentation, *do* include the ".html" portion.  There's a -->
  -<!--    good chance that the user will be reading the documentation -->
  -<!--    on his own system, which may not be configured for          -->
  -<!--    multiviews.                                                 -->
  -<!--  - When adding items, make sure they're put in the right place -->
  -<!--    - verify that the numbering matches up.                     -->
  -<!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  -<!--    correctly in a reliable way when this is converted to text  -->
  -<!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  -<!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  -<!--    the horizontal and vertical indenting right.                -->
  -<!--  - Don't forget to include an HR tag after the last /P tag     -->
  -<!--    but before the /LI in an item.                              -->
  -  <P>
  -  If you are reading a text-only version of this FAQ, you may find numbers
  -  enclosed in brackets (such as &quot;[12]&quot;).  These refer to the list of
  -  reference URLs to be found at the end of the document.  These references
  -  do not appear, and are not needed, for the hypertext version.
  -  </P>
  -  <H2>The Questions</H2>
  -<OL TYPE="A">
  -<!--#endif -->
  -<!--#if expr="$TOC || $STANDALONE" -->
  - <LI VALUE="9"><STRONG>Features</STRONG>
  -  <OL>
  -   <LI><A HREF="#proxy">Does or will Apache act as a Proxy server?</A>
  -   </LI>
  -   <LI><A HREF="#multiviews">What are &quot;multiviews&quot;?</A>
  -   </LI>
  -   <LI><A HREF="#putsupport">Why can't I publish to my Apache server
  -        using PUT on Netscape Gold and other programs?</A>
  -   </LI>
  -   <LI><A HREF="#SSL-i">Why doesn't Apache include SSL?</A>
  -   </LI>
  -   <LI><A HREF="#footer">How can I attach a footer to my documents
  -        without using SSI?</A>
  -   </LI>
  -   <LI><A HREF="#search">Does Apache include a search engine?</A>
  -   </LI>
  -   <LI><A HREF="#rotate">How can I rotate my log files?</A>
  -   </LI>
  -   <LI><A HREF="#conditional-logging">How do I keep certain requests from
  -        appearing in my logs?</A>
  -   </LI>
  -   <li><a href="#dbinteg">Does Apache include any sort of database
  -        integration?</a>
  -   </li>
  -   <li><a href="#asp">Can I use Active Server Pages (ASP) with Apache?</a>
  -   </li>
  -   <li><a href="#java">Does Apache come with Java support?</a></li>
  -  </OL>
  - </LI>
  +<!--#else -->
  +<!--#set var="STANDALONE" value="YES" -->
  +<!--#set var="INCLUDED" value="" -->
  +<!--#set var="TOC" value="" -->
  +<!--#set var="CONTENT" value="" -->
   <!--#endif -->
   <!--#if expr="$STANDALONE" -->
  -</OL>
  -
  -<HR>
  -
  -  <H2>The Answers</H2>
  -<!--#endif -->
  -<!--#if expr="! $TOC" -->
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -  <H3>I. Features</H3>
  -<OL>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Server Frequently Asked Questions</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache Server Frequently Asked
  +    Questions</h1>
  +
  +    <p>$Revision: 1.15 $ ($Date: 2001/10/08 01:26:54 $)</p>
  +
  +    <p>The latest version of this FAQ is always available from the
  +    main Apache web site, at &lt;<a
  +    href="http://httpd.apache.org/docs/misc/FAQ.html"
  +    rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>&gt;.</p>
  +    <!-- Notes about changes:                                           -->
  +    <!--  - If adding a relative link to another part of the            -->
  +    <!--    documentation, *do* include the ".html" portion.  There's a -->
  +    <!--    good chance that the user will be reading the documentation -->
  +    <!--    on his own system, which may not be configured for          -->
  +    <!--    multiviews.                                                 -->
  +    <!--  - When adding items, make sure they're put in the right place -->
  +    <!--    - verify that the numbering matches up.                     -->
  +    <!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  +    <!--    correctly in a reliable way when this is converted to text  -->
  +    <!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  +    <!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  +    <!--    the horizontal and vertical indenting right.                -->
  +    <!--  - Don't forget to include an HR tag after the last /P tag     -->
  +    <!--    but before the /LI in an item.                              -->
  +
  +    <p>If you are reading a text-only version of this FAQ, you may
  +    find numbers enclosed in brackets (such as "[12]"). These refer
  +    to the list of reference URLs to be found at the end of the
  +    document. These references do not appear, and are not needed,
  +    for the hypertext version.</p>
  +
  +    <h2>The Questions</h2>
  +
  +    <ol type="A">
  +      <!--#endif -->
  +      <!--#if expr="$TOC || $STANDALONE" -->
  +
  +      <li value="9">
  +        <strong>Features</strong> 
  +
  +        <ol>
  +          <li><a href="#proxy">Does or will Apache act as a Proxy
  +          server?</a></li>
  +
  +          <li><a href="#multiviews">What are "multiviews"?</a></li>
  +
  +          <li><a href="#putsupport">Why can't I publish to my
  +          Apache server using PUT on Netscape Gold and other
  +          programs?</a></li>
  +
  +          <li><a href="#SSL-i">Why doesn't Apache include
  +          SSL?</a></li>
  +
  +          <li><a href="#footer">How can I attach a footer to my
  +          documents without using SSI?</a></li>
  +
  +          <li><a href="#search">Does Apache include a search
  +          engine?</a></li>
  +
  +          <li><a href="#rotate">How can I rotate my log
  +          files?</a></li>
  +
  +          <li><a href="#conditional-logging">How do I keep certain
  +          requests from appearing in my logs?</a></li>
  +
  +          <li><a href="#dbinteg">Does Apache include any sort of
  +          database integration?</a></li>
  +
  +          <li><a href="#asp">Can I use Active Server Pages (ASP)
  +          with Apache?</a></li>
  +
  +          <li><a href="#java">Does Apache come with Java
  +          support?</a></li>
  +        </ol>
  +      </li>
  +      <!--#endif -->
  +      <!--#if expr="$STANDALONE" -->
  +    </ol>
  +    <hr />
  +
  +    <h2>The Answers</h2>
  +    <!--#endif -->
  +    <!--#if expr="! $TOC" -->
  +
  +    <h3>I. Features</h3>
  +
  +    <ol>
  +      <li>
  +        <a id="proxy" name="proxy"><strong>Does or will Apache act
  +        as a Proxy server?</strong></a> 
  +
  +        <p>Apache version 1.1 and above comes with a <a
  +        href="../mod/mod_proxy.html">proxy module</a>. If compiled
  +        in, this will make Apache act as a caching-proxy
  +        server.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="multiviews" name="multiviews"><strong>What are
  +        "multiviews"?</strong></a> 
  +
  +        <p>"Multiviews" is the general name given to the Apache
  +        server's ability to provide language-specific document
  +        variants in response to a request. This is documented quite
  +        thoroughly in the <a href="../content-negotiation.html"
  +        rel="Help">content negotiation</a> description page. In
  +        addition, <cite>Apache Week</cite> carried an article on
  +        this subject entitled "<a
  +        href="http://www.apacheweek.com/features/negotiation"
  +        rel="Help"><cite>Content Negotiation
  +        Explained</cite></a>".</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="putsupport" name="putsupport"><strong>Why can't I
  +        publish to my Apache server using PUT on Netscape Gold and
  +        other programs?</strong></a> 
  +
  +        <p>Because you need to install and configure a script to
  +        handle the uploaded files. This script is often called a
  +        "PUT" handler. There are several available, but they may
  +        have security problems. Using FTP uploads may be easier and
  +        more secure, at least for now. For more information, see
  +        the <cite>Apache Week</cite> article <a
  +        href="http://www.apacheweek.com/features/put"><cite>Publishing
  +        Pages with PUT</cite></a>.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="SSL-i" name="SSL-i"><strong>Why doesn't Apache
  +        include SSL?</strong></a> 
  +
  +        <p>SSL (Secure Socket Layer) data transport requires
  +        encryption, and many governments have restrictions upon the
  +        import, export, and use of encryption technology. If Apache
  +        included SSL in the base package, its distribution would
  +        involve all sorts of legal and bureaucratic issues, and it
  +        would no longer be freely available. Also, some of the
  +        technology required to talk to current clients using SSL is
  +        patented by <a href="http://www.rsa.com/">RSA Data
  +        Security</a>, who restricts its use without a license.</p>
  +
  +        <p>Some SSL implementations of Apache are available,
  +        however; see the "<a
  +        href="http://httpd.apache.org/related_projects.html">related
  +        projects</a>" page at the main Apache web site.</p>
  +
  +        <p>You can find out more about this topic in the
  +        <cite>Apache Week</cite> article about <a
  +        href="http://www.apacheweek.com/features/ssl"
  +        rel="Help"><cite>Apache and Secure
  +        Transactions</cite></a>.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="footer" name="footer"><strong>How can I attach a
  +        footer to my documents without using SSI?</strong></a> 
  +
  +        <p>You can make arbitrary changes to static documents by
  +        configuring an <a
  +        href="../mod/mod_actions.html#action">Action</a> which
  +        launches a CGI script. The CGI is then responsible for
  +        setting a content-type and delivering the requested
  +        document (the location of which is passed in the
  +        <samp>PATH_TRANSLATED</samp> environment variable), along
  +        with whatever footer is needed.</p>
  +
  +        <p>Busy sites may not want to run a CGI script on every
  +        request, and should consider using an Apache module to add
  +        the footer. There are several third party modules available
  +        through the <a href="http://modules.apache.org/">Apache
  +        Module Registry</a> which will add footers to documents.
  +        These include mod_trailer, PHP
  +        (<samp>php3_auto_append_file</samp>), mod_layout, and
  +        mod_perl (<samp>Apache::Sandwich</samp>).</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="search" name="search"><strong>Does Apache include a
  +        search engine?</strong></a> 
  +
  +        <p>Apache does not include a search engine, but there are
  +        many good commercial and free search engines which can be
  +        used easily with Apache. Some of them are listed on the <a
  +        href="http://www.searchtools.com/tools/tools.html">Web Site
  +        Search Tools</a> page. Open source search engines that are
  +        often used with Apache include <a
  +        href="http://www.htdig.org/">ht://Dig</a> and <a
  +        href="http://sunsite.berkeley.edu/SWISH-E/">SWISH-E</a>.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="rotate" name="rotate"><strong>How can I rotate my
  +        log files?</strong></a> 
  +
  +        <p>The simple answer: by piping the transfer log into an
  +        appropriate log file rotation utility.</p>
  +
  +        <p>The longer answer: In the src/support/ directory, you
  +        will find a utility called <a
  +        href="../programs/rotatelogs.html">rotatelogs</a> which can
  +        be used like this:</p>
  +<pre>
  +   TransferLog "|/path/to/rotatelogs /path/to/logs/access_log 86400"
  +</pre>
  +
  +        <p>to enable daily rotation of the log files.<br />
  +         A more sophisticated solution of a logfile rotation
  +        utility is available under the name <code>cronolog</code>
  +        from Andrew Ford's site at <a
  +        href="http://www.ford-mason.co.uk/resources/cronolog/">http://www.ford-mason.co.uk/resources/cronolog/</a>.
  +        It can automatically create logfile subdirectories based on
  +        time and date, and can have a constant symlink point to the
  +        rotating logfiles. (As of version 1.6.1, cronolog is
  +        available under the <a href="../LICENSE">Apache
  +        License</a>). Use it like this:</p>
  +<pre>
  +   CustomLog "|/path/to/cronolog --symlink=/usr/local/apache/logs/access_log /usr/local/apache/logs/%Y/%m/access_log" combined
  +</pre>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="conditional-logging"
  +        name="conditional-logging"><strong>How do I keep certain
  +        requests from appearing in my logs?</strong></a> 
  +
  +        <p>The maximum flexibility for removing unwanted
  +        information from log files is obtained by post-processing
  +        the logs, or using piped-logs to feed the logs through a
  +        program which does whatever you want. However, Apache does
  +        offer the ability to prevent requests from ever appearing
  +        in the log files. You can do this by using the <a
  +        href="../mod/mod_setenvif.html#SetEnvIf"><code>SetEnvIf</code></a>
  +        directive to set an environment variable for certain
  +        requests and then using the conditional <a
  +        href="../mod/mod_log_config.html#customlog-conditional"><code>
  +        CustomLog</code></a> syntax to prevent logging when the
  +        environment variable is set.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="dbinteg" name="dbinteg"><b>Does Apache support any
  +        sort of database integration?</b></a> 
  +
  +        <p>No. Apache is a Web (HTTP) server, not an application
  +        server. The base package does not include any such
  +        functionality. See the <a href="http://www.php.net/">PHP
  +        project</a> and the <a
  +        href="http://perl.apache.org/">mod_perl project</a> for
  +        examples of modules that allow you to work with databases
  +        from within the Apache environment.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="asp" name="asp"><b>Can I use Active Server Pages
  +        (ASP) with Apache?</b></a> 
  +
  +        <p>The base Apache Web server package does not include ASP
  +        support. However, there are a couple of after-market
  +        solutions that let you add this functionality; see the <a
  +        href="http://httpd.apache.org/related_projects.html">related
  +        projects</a> page to find out more.</p>
  +        <hr />
  +      </li>
  +
  +      <li>
  +        <a id="java" name="java"><b>Does Apache come with Java
  +        support?</b></a> 
  +
  +        <p>The base Apache Web server package does not include
  +        support for Java, Java Server Pages, Enterprise Java Beans,
  +        or Java servlets. Those features are available as add-ons
  +        from the Apache/Java project site, &lt;URL:<a
  +        href="http://jakarta.apache.org">http://jakarta.apache.org/</a>&gt;.</p>
  +        <hr />
  +      </li>
  +    </ol>
  +    <!--#endif -->
  +    <!--#if expr="$STANDALONE" -->
  +    <!-- Don't forget to add HR tags at the end of each list item.. -->
  +    <!--#include virtual="footer.html" -->
  +    <!--#endif -->
  +  </body>
  +</html>
   
  - <LI><A NAME="proxy">
  -      <STRONG>Does or will Apache act as a Proxy server?</STRONG>
  -     </A>
  -  <P>
  -  Apache version 1.1 and above comes with a
  -  <A HREF="../mod/mod_proxy.html">proxy module</A>.
  -  If compiled in, this will make Apache act as a caching-proxy server.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="multiviews">
  -      <STRONG>What are &quot;multiviews&quot;?</STRONG>
  -     </A>
  -  <P>
  -  &quot;Multiviews&quot; is the general name given to the Apache
  -  server's ability to provide language-specific document variants in
  -  response to a request.  This is documented quite thoroughly in the
  -  <A HREF="../content-negotiation.html" REL="Help">content negotiation</A>
  -  description page.  In addition, <CITE>Apache Week</CITE> carried an
  -  article on this subject entitled
  -  &quot;<A HREF="http://www.apacheweek.com/features/negotiation" REL="Help"
  -        ><CITE>Content Negotiation Explained</CITE></A>&quot;.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="putsupport">
  -      <STRONG>Why can't I publish to my Apache server using PUT on
  -      Netscape Gold and other programs?</STRONG>
  -     </A>
  -  <P>
  -  Because you need to install and configure a script to handle
  -  the uploaded files.  This script is often called a &quot;PUT&quot; handler.
  -  There are several available, but they may have security problems.
  -  Using FTP uploads may be easier and more secure, at least for now.
  -  For more information, see the <CITE>Apache Week</CITE> article
  -  <A HREF="http://www.apacheweek.com/features/put"
  -  ><CITE>Publishing Pages with PUT</CITE></A>.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <LI><A NAME="SSL-i">
  -      <STRONG>Why doesn't Apache include SSL?</STRONG>
  -     </A>
  -  <P>
  -  SSL (Secure Socket Layer) data transport requires encryption, and many
  -  governments have restrictions upon the import, export, and use of
  -  encryption technology.  If Apache included SSL in the base package,
  -  its distribution would involve all sorts of legal and bureaucratic
  -  issues, and it would no longer be freely available.  Also, some of
  -  the technology required to talk to current clients using SSL is
  -  patented by <A HREF="http://www.rsa.com/">RSA Data Security</A>,
  -  who restricts its use without a license.
  -  </P>
  -  <P>
  -  Some SSL implementations of Apache are available, however; see the
  -  &quot;<A HREF="http://httpd.apache.org/related_projects.html"
  -        >related projects</A>&quot;
  -  page at the main Apache web site.
  -  </P>
  -  <P>
  -  You can find out more about this topic in the <CITE>Apache Week</CITE>
  -  article about
  -  <A HREF="http://www.apacheweek.com/features/ssl" REL="Help"
  -  ><CITE>Apache and Secure Transactions</CITE></A>.
  -  </P>
  -  <HR>
  - </LI>
  - <LI><A NAME="footer">
  -      <STRONG>How can I attach a footer to my documents
  -        without using SSI?</STRONG>
  -     </A>
  -  <P>
  -  You can make arbitrary changes to static documents by configuring an
  -  <A HREF="../mod/mod_actions.html#action">
  -  Action</A> which launches a CGI script.  The CGI is then
  -  responsible for setting a content-type and delivering the requested
  -  document (the location of which is passed in the
  -  <SAMP>PATH_TRANSLATED</SAMP> environment variable), along with
  -  whatever footer is needed.
  -  </P>
  -  <P>
  -  Busy sites may not want to run a CGI script on every request, and
  -  should consider using an Apache module to add the footer.  There are
  -  several third party modules available through the <A
  -  HREF="http://modules.apache.org/">Apache Module Registry</A> which
  -  will add footers to documents.  These include mod_trailer, PHP
  -  (<SAMP>php3_auto_append_file</SAMP>), mod_layout, and mod_perl
  -  (<SAMP>Apache::Sandwich</SAMP>).
  -  </P>
  -  <HR>
  - </LI>
  - <LI><A NAME="search">
  -      <STRONG>Does Apache include a search engine?</STRONG>
  -     </A>
  -  <P>Apache does not include a search engine, but there are many good
  -  commercial and free search engines which can be used easily with
  -  Apache.  Some of them are listed on the <A
  -  HREF="http://www.searchtools.com/tools/tools.html">Web Site Search
  -  Tools</A> page.  Open source search engines that are often used with
  -  Apache include <A HREF="http://www.htdig.org/">ht://Dig</A> and <A
  -  HREF="http://sunsite.berkeley.edu/SWISH-E/">SWISH-E</A>.
  -  </P>
  -  <HR>
  - </LI>
  - <LI><A NAME="rotate">
  -      <STRONG>How can I rotate my log files?</STRONG>
  -     </A>
  -  <P>The simple answer: by piping the transfer log into an appropriate
  -  log file rotation utility.</P> <P>The longer answer: In the
  -  src/support/ directory, you will find a utility called <a
  -  href="../programs/rotatelogs.html">rotatelogs</a> which can be used
  -  like this:</p>
  -
  -<PRE>   TransferLog "|/path/to/rotatelogs /path/to/logs/access_log 86400"</PRE>
  -
  -  <p>to enable daily rotation of the log files.<BR>
  -  A more sophisticated solution of a logfile rotation utility is
  -  available under the name <CODE>cronolog</CODE> from Andrew Ford's site at
  -  <A HREF="http://www.ford-mason.co.uk/resources/cronolog/"
  -  >http://www.ford-mason.co.uk/resources/cronolog/</A>. It can automatically
  -  create logfile subdirectories based on time and date, and can have a
  -  constant symlink point to the rotating logfiles. (As of version 1.6.1,
  -  cronolog is available under the <A HREF="../LICENSE">Apache License</A>).
  -  Use it like this:</P>
  -
  -<PRE>   CustomLog "|/path/to/cronolog --symlink=/usr/local/apache/logs/access_log /usr/local/apache/logs/%Y/%m/access_log" combined</PRE>
  -
  -  <HR>
  - </LI>
  - <LI><A NAME="conditional-logging">
  -      <STRONG>How do I keep certain requests from appearing
  -      in my logs?</STRONG></A> 
  -  <P>
  -  The maximum flexibility for removing unwanted information from
  -  log files is obtained by post-processing the logs, or using
  -  piped-logs to feed the logs through a program which does whatever
  -  you want.  However, Apache does offer the ability to prevent
  -  requests from ever appearing in the log files.  You can do this by
  -  using the
  -  <A HREF="../mod/mod_setenvif.html#SetEnvIf"><CODE>SetEnvIf</CODE></A>
  -  directive to set an environment variable for certain requests and
  -  then using the conditional
  -  <A HREF="../mod/mod_log_config.html#customlog-conditional"><CODE>CustomLog</CODE></A>
  -  syntax to prevent logging when the environment variable is set.
  -  </P>
  -  <HR>
  - </LI>
  -
  - <li><a name="dbinteg"><b>Does Apache support any sort of database
  -      integration?</b></a>
  -  <p>
  -  No.  Apache is a Web (HTTP) server, not an application server.  The
  -  base package does not include any such functionality.  See the
  -  <a href="http://www.php.net/">PHP project</a> and the
  -  <a href="http://perl.apache.org/">mod_perl project</a>
  -  for examples of modules that allow you to work with databases
  -  from within the Apache environment.
  -  </p>
  -  <hr>
  - </li>
  -
  - <li><a name="asp"><b>Can I use Active Server Pages (ASP) with Apache?</b></a>
  -  <p>
  -  The base Apache Web server package does not include ASP support.
  -  However, there are a couple of after-market solutions that let you
  -  add this functionality; see the
  -  <a href="http://httpd.apache.org/related_projects.html"
  -  >related projects</a> page to find out more.
  -  </p>
  -  <hr>
  - </li>
  -
  - <li><a name="java"><b>Does Apache come with Java support?</b></a>
  -  <p>
  -  The base Apache Web server package does not include support for
  -  Java, Java Server Pages, Enterprise Java Beans, or Java servlets.
  -  Those features are available as add-ons from the Apache/Java project
  -  site, &lt;URL:<a href="http://jakarta.apache.org"
  -                >http://jakarta.apache.org/</a>&gt;.
  -  </p>
  -  <hr>
  - </li>
  -
  -</OL>
  -<!--#endif -->
  -<!--#if expr="$STANDALONE" -->
  -  <!-- Don't forget to add HR tags at the end of each list item.. -->
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  -<!--#endif -->
  
  
  
  1.149     +110 -111  httpd-docs-1.3/htdocs/manual/misc/FAQ.html
  
  Index: FAQ.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/FAQ.html,v
  retrieving revision 1.148
  retrieving revision 1.149
  diff -u -r1.148 -r1.149
  --- FAQ.html	2001/02/28 03:45:23	1.148
  +++ FAQ.html	2001/10/08 01:26:54	1.149
  @@ -1,111 +1,110 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  - <HEAD>
  -  <TITLE>Apache Server Frequently Asked Questions</TITLE>
  -<!--#set var="FAQMASTER" value="YES" -->
  - </HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  - <BODY
  -  BGCOLOR="#FFFFFF"
  -  TEXT="#000000"
  -  LINK="#0000FF"
  -  VLINK="#000080"
  -  ALINK="#FF0000"
  - >
  -  <!--#include virtual="header.html" -->
  -  <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>
  -  <P>
  -  $Revision: 1.148 $ ($Date: 2001/02/28 03:45:23 $)
  -  </P>
  -  <P>
  -  The latest version of this FAQ is always available from the main
  -  Apache web site, at
  -  &lt;<A
  -       HREF="http://httpd.apache.org/docs/misc/FAQ.html"
  -       REL="Help"
  -      ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>&gt;.
  -  </P>
  -<!-- Notes about changes:                                           -->
  -<!--  - If adding a relative link to another part of the            -->
  -<!--    documentation, *do* include the ".html" portion.  There's a -->
  -<!--    good chance that the user will be reading the documentation -->
  -<!--    on his own system, which may not be configured for          -->
  -<!--    multiviews.                                                 -->
  -<!--  - When adding items, make sure they're put in the right place -->
  -<!--    - verify that the numbering matches up.                     -->
  -<!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  -<!--    correctly in a reliable way when this is converted to text  -->
  -<!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  -<!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  -<!--    the horizontal and vertical indenting right.                -->
  -<!--  - Don't forget to include an HR tag after the last /P tag     -->
  -<!--    but before the /LI in an item.                              -->
  -  <P>
  -  If you are reading a text-only version of this FAQ, you may find numbers
  -  enclosed in brackets (such as &quot;[12]&quot;).  These refer to the list of
  -  reference URLs to be found at the end of the document.  These references
  -  do not appear, and are not needed, for the hypertext version.
  -  </P>
  -  <H2>The Questions</H2>
  -<!-- Stuff to Add:                                                  -->
  -<!-- - can't bind to port 80                                        -->
  -<!--   - permission denied                                          -->
  -<!--   - address already in use                                     -->
  -<!-- - mod_auth & passwd lines "user:pw:.*" - ++1st colon onward is -->
  -<!--   treated as pw, not just ++1st to \-\-2nd.                    -->
  -<!-- - SSL:                                                         -->
  -<!--   - Can I use Apache-SSL for free in Canada?                   -->
  -<!--   - Why can't I use Apache-SSL in the U.S.?                    -->
  -<!-- - How can I found out how many visitors my site gets?          -->
  -<!-- - How do I add a counter?                                      -->
  -<!-- - How do I configure Apache as a proxy?                        -->
  -<!-- - What browsers support HTTP/1.1?                              -->
  -<!-- - What's the point of vhosts-by-name is there aren't any       -->
  -<!--   HTTP/1.1 browsers?                                           -->
  -<!-- - Is there an Apache for W95/WNT?                              -->
  -<!-- - Why does Apache die when a vhost can't be DNS-resolved?      -->
  -<!-- - Why do I get "send lost connection" messages in my error     -->
  -<!--   log?                                                         -->
  -<!--   - specifically consider .pdf files which seem to cause this  -->
  -<!--     a lot when accessed via the plugin ... and also mention    -->
  -<!--     how range-requests can cause bytes served < file size      -->
  -<!-- - Why do directory indexes appear as garbage?  (A: -lucb)      -->
  -<!-- - How do I add a footer to all pages offered by my server?     -->
  -<!-- - Fix midi question; a bigger problem than midi vs. x-midi is  -->
  -<!--   the simple fact that older versions of Apache (and new ones  -->
  -<!--   that have been upgraded without upgrading the mime.types     -->
  -<!--   file) don't have the type listed at all.                     -->
  -<!-- - RewriteRule /~fraggle/* /cgi-bin/fraggle.pl does not work    -->
  -<!-- - how do I disable authentication for a subdirectory?          -->
  -<!--   (A: you can't but "Satisfy any; Allow from all" can be close -->
  -<!-- - '400 malformed request' on Win32 might mean stale proxy; see -->
  -<!--   PR #2300.                                                    -->
  -<!-- - how do I tell what version of Apache I am running?           -->
  -<OL TYPE="A">
  -<!--#include virtual="FAQ-A.html?TOC" -->
  -<!--#include virtual="FAQ-B.html?TOC" -->
  -<!--#include virtual="FAQ-C.html?TOC" -->
  -<!--#include virtual="FAQ-D.html?TOC" -->
  -<!--#include virtual="FAQ-E.html?TOC" -->
  -<!--#include virtual="FAQ-F.html?TOC" -->
  -<!--#include virtual="FAQ-G.html?TOC" -->
  -<!--#include virtual="FAQ-H.html?TOC" -->
  -<!--#include virtual="FAQ-I.html?TOC" -->
  -</OL>
  -
  -<HR>
  -
  -  <H2>The Answers</H2>
  -<!--#include virtual="FAQ-A.html?" -->
  -<!--#include virtual="FAQ-B.html?" -->
  -<!--#include virtual="FAQ-C.html?" -->
  -<!--#include virtual="FAQ-D.html?" -->
  -<!--#include virtual="FAQ-E.html?" -->
  -<!--#include virtual="FAQ-F.html?" -->
  -<!--#include virtual="FAQ-G.html?" -->
  -<!--#include virtual="FAQ-H.html?" -->
  -<!--#include virtual="FAQ-I.html?" -->
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  +
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Server Frequently Asked Questions</title>
  +    <!--#set var="FAQMASTER" value="YES" -->
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache Server Frequently Asked
  +    Questions</h1>
  +
  +    <p>$Revision: 1.149 $ ($Date: 2001/10/08 01:26:54 $)</p>
  +
  +    <p>The latest version of this FAQ is always available from the
  +    main Apache web site, at &lt;<a
  +    href="http://httpd.apache.org/docs/misc/FAQ.html"
  +    rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>&gt;.</p>
  +    <!-- Notes about changes:                                           -->
  +    <!--  - If adding a relative link to another part of the            -->
  +    <!--    documentation, *do* include the ".html" portion.  There's a -->
  +    <!--    good chance that the user will be reading the documentation -->
  +    <!--    on his own system, which may not be configured for          -->
  +    <!--    multiviews.                                                 -->
  +    <!--  - When adding items, make sure they're put in the right place -->
  +    <!--    - verify that the numbering matches up.                     -->
  +    <!--  - *Don't* use <PRE></PRE> blocks - they don't appear          -->
  +    <!--    correctly in a reliable way when this is converted to text  -->
  +    <!--    with Lynx.  Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL>    -->
  +    <!--    blocks inside a <P></P> instead.  This is necessary to get  -->
  +    <!--    the horizontal and vertical indenting right.                -->
  +    <!--  - Don't forget to include an HR tag after the last /P tag     -->
  +    <!--    but before the /LI in an item.                              -->
  +
  +    <p>If you are reading a text-only version of this FAQ, you may
  +    find numbers enclosed in brackets (such as "[12]"). These refer
  +    to the list of reference URLs to be found at the end of the
  +    document. These references do not appear, and are not needed,
  +    for the hypertext version.</p>
  +
  +    <h2>The Questions</h2>
  +    <!-- Stuff to Add:                                                  -->
  +    <!-- - can't bind to port 80                                        -->
  +    <!--   - permission denied                                          -->
  +    <!--   - address already in use                                     -->
  +    <!-- - mod_auth & passwd lines "user:pw:.*" - ++1st colon onward is -->
  +    <!--   treated as pw, not just ++1st to \-\-2nd.                    -->
  +    <!-- - SSL:                                                         -->
  +    <!--   - Can I use Apache-SSL for free in Canada?                   -->
  +    <!--   - Why can't I use Apache-SSL in the U.S.?                    -->
  +    <!-- - How can I found out how many visitors my site gets?          -->
  +    <!-- - How do I add a counter?                                      -->
  +    <!-- - How do I configure Apache as a proxy?                        -->
  +    <!-- - What browsers support HTTP/1.1?                              -->
  +    <!-- - What's the point of vhosts-by-name is there aren't any       -->
  +    <!--   HTTP/1.1 browsers?                                           -->
  +    <!-- - Is there an Apache for W95/WNT?                              -->
  +    <!-- - Why does Apache die when a vhost can't be DNS-resolved?      -->
  +    <!-- - Why do I get "send lost connection" messages in my error     -->
  +    <!--   log?                                                         -->
  +    <!--   - specifically consider .pdf files which seem to cause this  -->
  +    <!--     a lot when accessed via the plugin ... and also mention    -->
  +    <!--     how range-requests can cause bytes served < file size      -->
  +    <!-- - Why do directory indexes appear as garbage?  (A: -lucb)      -->
  +    <!-- - How do I add a footer to all pages offered by my server?     -->
  +    <!-- - Fix midi question; a bigger problem than midi vs. x-midi is  -->
  +    <!--   the simple fact that older versions of Apache (and new ones  -->
  +    <!--   that have been upgraded without upgrading the mime.types     -->
  +    <!--   file) don't have the type listed at all.                     -->
  +    <!-- - RewriteRule /~fraggle/* /cgi-bin/fraggle.pl does not work    -->
  +    <!-- - how do I disable authentication for a subdirectory?          -->
  +    <!--   (A: you can't but "Satisfy any; Allow from all" can be close -->
  +    <!-- - '400 malformed request' on Win32 might mean stale proxy; see -->
  +    <!--   PR #2300.                                                    -->
  +    <!-- - how do I tell what version of Apache I am running?           -->
  +
  +    <ol type="A">
  +      <!--#include virtual="FAQ-A.html?TOC" -->
  +      <!--#include virtual="FAQ-B.html?TOC" -->
  +      <!--#include virtual="FAQ-C.html?TOC" -->
  +      <!--#include virtual="FAQ-D.html?TOC" -->
  +      <!--#include virtual="FAQ-E.html?TOC" -->
  +      <!--#include virtual="FAQ-F.html?TOC" -->
  +      <!--#include virtual="FAQ-G.html?TOC" -->
  +      <!--#include virtual="FAQ-H.html?TOC" -->
  +      <!--#include virtual="FAQ-I.html?TOC" -->
  +    </ol>
  +    <hr />
  +
  +    <h2>The Answers</h2>
  +    <!--#include virtual="FAQ-A.html?" -->
  +    <!--#include virtual="FAQ-B.html?" -->
  +    <!--#include virtual="FAQ-C.html?" -->
  +    <!--#include virtual="FAQ-D.html?" -->
  +    <!--#include virtual="FAQ-E.html?" -->
  +    <!--#include virtual="FAQ-F.html?" -->
  +    <!--#include virtual="FAQ-G.html?" -->
  +    <!--#include virtual="FAQ-H.html?" -->
  +    <!--#include virtual="FAQ-I.html?" -->
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
  +
  
  
  
  1.13      +76 -76    httpd-docs-1.3/htdocs/manual/misc/client_block_api.html
  
  Index: client_block_api.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/client_block_api.html,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- client_block_api.html	1998/09/17 12:33:01	1.12
  +++ client_block_api.html	2001/10/08 01:26:54	1.13
  @@ -1,87 +1,87 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>Reading Client Input in Apache 1.2</TITLE>
  -</HEAD>
  -
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Reading Client Input in Apache 1.2</H1>
  -
  -<HR>
  -
  -<P>Apache 1.1 and earlier let modules handle POST and PUT requests by
  -themselves. The module would, on its own, determine whether the
  -request had an entity, how many bytes it was, and then called a
  -function (<CODE>read_client_block</CODE>) to get the data.
  -
  -<P>However, HTTP/1.1 requires several things of POST and PUT request
  -handlers that did not fit into this module, and all existing modules
  -have to be rewritten. The API calls for handling this have been
  -further abstracted, so that future HTTP protocol changes can be
  -accomplished while remaining backwards-compatible.</P>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -<HR>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Reading Client Input in Apache 1.2</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Reading Client Input in Apache 1.2</h1>
  +    <hr />
  +
  +    <p>Apache 1.1 and earlier let modules handle POST and PUT
  +    requests by themselves. The module would, on its own, determine
  +    whether the request had an entity, how many bytes it was, and
  +    then called a function (<code>read_client_block</code>) to get
  +    the data.</p>
  +
  +    <p>However, HTTP/1.1 requires several things of POST and PUT
  +    request handlers that did not fit into this module, and all
  +    existing modules have to be rewritten. The API calls for
  +    handling this have been further abstracted, so that future HTTP
  +    protocol changes can be accomplished while remaining
  +    backwards-compatible.</p>
  +    <hr />
   
  -<H3>The New API Functions</H3>
  -
  -<PRE>
  +    <h3>The New API Functions</h3>
  +<pre>
      int ap_setup_client_block (request_rec *, int read_policy);
      int ap_should_client_block (request_rec *);
      long ap_get_client_block (request_rec *, char *buffer, int buffer_size);
  -</PRE>
  +</pre>
   
  -<OL>
  -<LI>Call <CODE>ap_setup_client_block()</CODE> near the beginning of the request
  -    handler. This will set up all the necessary properties, and
  -    will return either OK, or an error code. If the latter,
  -    the module should return that error code. The second parameter
  -    selects the policy to apply if the request message indicates a
  -    body, and how a chunked
  -    transfer-coding should be interpreted. Choose one of
  -<PRE>
  +    <ol>
  +      <li>
  +        Call <code>ap_setup_client_block()</code> near the
  +        beginning of the request handler. This will set up all the
  +        necessary properties, and will return either OK, or an
  +        error code. If the latter, the module should return that
  +        error code. The second parameter selects the policy to
  +        apply if the request message indicates a body, and how a
  +        chunked transfer-coding should be interpreted. Choose one
  +        of 
  +<pre>
       REQUEST_NO_BODY          Send 413 error if message has any body
       REQUEST_CHUNKED_ERROR    Send 411 error if body without Content-Length
       REQUEST_CHUNKED_DECHUNK  If chunked, remove the chunks for me.
       REQUEST_CHUNKED_PASS     Pass the chunks to me without removal.
  -</PRE>
  -    In order to use the last two options, the caller MUST provide a buffer
  -    large enough to hold a chunk-size line, including any extensions.
  -
  -
  +</pre>
  +        In order to use the last two options, the caller MUST
  +        provide a buffer large enough to hold a chunk-size line,
  +        including any extensions.
  +      </li>
  +
  +      <li>When you are ready to possibly accept input, call
  +      <code>ap_should_client_block()</code>. This will tell the
  +      module whether or not to read input. If it is 0, the module
  +      should assume that the input is of a non-entity type
  +      (<em>e.g.</em>, a GET request). A nonzero response indicates
  +      that the module should proceed (to step 3). This step also
  +      sends a 100 Continue response to HTTP/1.1 clients, so should
  +      not be called until the module is
  +      <strong>*definitely*</strong> ready to read content.
  +      (otherwise, the point of the 100 response is defeated). Never
  +      call this function more than once.</li>
  +
  +      <li>Finally, call <code>ap_get_client_block</code> in a loop.
  +      Pass it a buffer and its size. It will put data into the
  +      buffer (not necessarily the full buffer, in the case of
  +      chunked inputs), and return the length of the input block.
  +      When it is done reading, it will return 0 if EOF, or -1 if
  +      there was an error.</li>
  +    </ol>
  +
  +    <p>As an example, please look at the code in
  +    <code>mod_cgi.c</code>. This is properly written to the new API
  +    guidelines.</p>
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
   
  -<LI>When you are ready to possibly accept input, call
  -    <CODE>ap_should_client_block()</CODE>.
  -    This will tell the module whether or not to read input. If it is 0,
  -    the module should assume that the input is of a non-entity type
  -    (<EM>e.g.</EM>, a GET request). A nonzero response indicates that the module
  -    should proceed (to step 3).
  -    This step also sends a 100 Continue response
  -    to HTTP/1.1 clients, so should not be called until the module
  -    is <STRONG>*definitely*</STRONG> ready to read content. (otherwise, the
  -    point of the
  -    100 response is defeated). Never call this function more than once.
  -
  -<LI>Finally, call <CODE>ap_get_client_block</CODE> in a loop. Pass it a
  -    buffer and its
  -    size. It will put data into the buffer (not necessarily the full
  -    buffer, in the case of chunked inputs), and return the length of
  -    the input block. When it is done reading, it will
  -    return 0 if EOF, or -1 if there was an error.
  -
  -</OL>
  -
  -<P>As an example, please look at the code in
  -<CODE>mod_cgi.c</CODE>. This is properly written to the new API
  -guidelines.</P>
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  
  
  
  1.29      +125 -131  httpd-docs-1.3/htdocs/manual/misc/compat_notes.html
  
  Index: compat_notes.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/compat_notes.html,v
  retrieving revision 1.28
  retrieving revision 1.29
  diff -u -r1.28 -r1.29
  --- compat_notes.html	2001/09/24 01:36:41	1.28
  +++ compat_notes.html	2001/10/08 01:26:54	1.29
  @@ -1,131 +1,125 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
  - "http://www.w3.org/TR/REC-html40/loose.dtd">
  -<HTML>
  -<HEAD>
  -<TITLE>Apache HTTP Server: Notes about Compatibility with NCSA's Server</TITLE>
  -</HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Compatibility Notes with NCSA's Server</H1>
  -
  -<HR>
  -
  -While Apache is for the most part a drop-in replacement for NCSA's
  -httpd, there are a couple gotcha's to watch out for.  These are mostly
  -due to the fact that the parser for config and access control files
  -was rewritten from scratch, so certain liberties the earlier servers
  -took may not be available here.  These are all easily fixable.  If you
  -know of other problems that belong here, <A
  -HREF="http://httpd.apache.org/bug_report.html">let us know.</A>
  -
  -<P>Please also check the <A HREF="known_client_problems.html">known
  -client problems</A> page.
  -
  -<OL>
  -<LI>As of Apache 1.3.1, methods named in a
  -    <A HREF="../mod/core.html#limit"><SAMP>&lt;Limit&gt;</SAMP></A>
  -    section <EM>must</EM> be listed in upper-case.  Lower- or mixed-case
  -    method names will result in a configuration error.
  -    <P>
  -    </P>
  -</LI>
  -
  -<LI>The basic mod_auth <CODE>AuthGroupFile</CODE>-specified group file
  -    format allows commas between user names - Apache does not.
  -
  -<P>
  -<LI>If you follow the NCSA guidelines for setting up access
  -    restrictions based on client domain, you may well have added
  -    entries for <CODE>AuthType, AuthName, AuthUserFile</CODE> or
  -    <CODE>AuthGroupFile</CODE>.  <STRONG>None</STRONG> of these are
  -    needed (or appropriate) for restricting access based on client
  -    domain.  When Apache sees <CODE>AuthType</CODE> it (reasonably)
  -    assumes you are using some authorization type based on username
  -    and password.  Please remove <CODE>AuthType</CODE>, it's
  -    unnecessary even for NCSA.
  -
  -<P>
  -<LI><CODE>OldScriptAlias</CODE> is no longer supported.
  -
  -<P>
  -<LI><CODE>exec cgi=""</CODE> produces reasonable <STRONG>malformed
  -  header</STRONG> responses when used to invoke non-CGI scripts.<BR>
  -  The NCSA code ignores the missing header (bad idea).
  -  <BR>Solution: write CGI to the CGI spec and use
  -  <CODE>include&nbsp;virtual</CODE>, or use <CODE>exec cmd=""</CODE> instead.
  -
  -<P>
  -<LI>Icons for FancyIndexing broken - well, no, they're not broken,
  -    we've just upgraded the icons from flat .xbm files to pretty and
  -    much smaller .gif files, courtesy of <A
  -    HREF="mailto:kevinh@eit.com">Kevin Hughes</A> at <A
  -    HREF="http://www.eit.com/">EIT</A>.  If you are using the same
  -    srm.conf from an old distribution, make sure you add the new <A
  -    HREF="../mod/mod_autoindex.html#addicon">AddIcon</A>, <A
  -    HREF="../mod/mod_autoindex.html#addiconbytype">AddIconByType</A>,
  -    and <A
  -    HREF="../mod/mod_autoindex.html#defaulticon">DefaultIcon</A>
  -    directives.
  -
  -<P>
  -<LI>Apache versions before 1.2b1 will ignore the last line of configuration
  -    files if the last line does not have a trailing newline. This affects
  -    configuration files (httpd.conf, access.conf and srm.conf), and
  -    htpasswd and htgroup files.
  -
  -<P>
  -<LI>Apache does not permit commas delimiting the methods in &lt;Limit&gt;.
  -
  -<P>
  -<LI>Apache's <CODE>&lt;VirtualHost&gt;</CODE> treats all addresses as
  -    "optional" (<EM>i.e.</EM>, the server should continue booting if it can't
  -    resolve the address).  Whereas in NCSA the default is to fail
  -    booting unless an added <CODE>optional</CODE> keyword is included.
  -
  -<P>
  -<LI>Apache does not implement <CODE>OnDeny</CODE>; use
  -    <A HREF="../mod/core.html#errordocument"><CODE>ErrorDocument</CODE></A>
  -    instead.
  -
  -<P>
  -<LI>Apache (as of 1.3) always performs the equivalent of
  -    <CODE>HostnameLookups minimal</CODE>.  <CODE>minimal</CODE> is not an
  -    option to <A HREF="../mod/core.html#hostnamelookups"><CODE>
  -    HostnameLookups</CODE></A>.
  -
  -<P>
  -<LI>To embed spaces in directive arguments NCSA used a backslash
  -    before the space. Apache treats backslashes as normal characters. To
  -    embed spaces surround the argument with double-quotes instead.
  -
  -<P>
  -<LI>Apache does not implement the NCSA <CODE>referer</CODE>
  -    directive.  See <A HREF="http://bugs.apache.org/index/full/968">
  -    PR#968</A> for a few brief suggestions on alternative ways to 
  -    implement the same thing under Apache.
  -
  -<P>
  -<LI>Apache does not allow ServerRoot settings inside a VirtualHost
  -    container.  There is only one global ServerRoot in Apache; any desired
  -    changes in paths for virtual hosts need to be made with the explicit
  -    directives, <em>e.g.</em>, DocumentRoot, TransferLog, <EM>etc.</EM>
  -
  -<P>
  -<LI>The <CODE>AddType</CODE> directive cannot be used to set the type of 
  -particular files.  Instead, you can scope you directives using
  -&lt;Files&gt; blocks.
  -
  -</OL>
  -
  -More to come when we notice them....
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  +
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache HTTP Server: Notes about Compatibility with
  +    NCSA's Server</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Compatibility Notes with NCSA's Server</h1>
  +    <hr />
  +    While Apache is for the most part a drop-in replacement for
  +    NCSA's httpd, there are a couple gotcha's to watch out for.
  +    These are mostly due to the fact that the parser for config and
  +    access control files was rewritten from scratch, so certain
  +    liberties the earlier servers took may not be available here.
  +    These are all easily fixable. If you know of other problems
  +    that belong here, <a
  +    href="http://httpd.apache.org/bug_report.html">let us know.</a>
  +    
  +
  +    <p>Please also check the <a
  +    href="known_client_problems.html">known client problems</a>
  +    page.</p>
  +
  +    <ol>
  +      <li>As of Apache 1.3.1, methods named in a <a
  +      href="../mod/core.html#limit"><samp>&lt;Limit&gt;</samp></a>
  +      section <em>must</em> be listed in upper-case. Lower- or
  +      mixed-case method names will result in a configuration
  +      error.</li>
  +
  +      <li>The basic mod_auth <code>AuthGroupFile</code>-specified
  +      group file format allows commas between user names - Apache
  +      does not.</li>
  +
  +      <li>If you follow the NCSA guidelines for setting up access
  +      restrictions based on client domain, you may well have added
  +      entries for <code>AuthType, AuthName, AuthUserFile</code> or
  +      <code>AuthGroupFile</code>. <strong>None</strong> of these
  +      are needed (or appropriate) for restricting access based on
  +      client domain. When Apache sees <code>AuthType</code> it
  +      (reasonably) assumes you are using some authorization type
  +      based on username and password. Please remove
  +      <code>AuthType</code>, it's unnecessary even for NCSA.</li>
  +
  +      <li><code>OldScriptAlias</code> is no longer supported.</li>
  +
  +      <li><code>exec cgi=""</code> produces reasonable
  +      <strong>malformed header</strong> responses when used to
  +      invoke non-CGI scripts.<br />
  +       The NCSA code ignores the missing header (bad idea).<br />
  +       Solution: write CGI to the CGI spec and use
  +      <code>include&nbsp;virtual</code>, or use <code>exec
  +      cmd=""</code> instead.</li>
  +
  +      <li>Icons for FancyIndexing broken - well, no, they're not
  +      broken, we've just upgraded the icons from flat .xbm files to
  +      pretty and much smaller .gif files, courtesy of <a
  +      href="mailto:kevinh@eit.com">Kevin Hughes</a> at <a
  +      href="http://www.eit.com/">EIT</a>. If you are using the same
  +      srm.conf from an old distribution, make sure you add the new
  +      <a href="../mod/mod_autoindex.html#addicon">AddIcon</a>, <a
  +      href="../mod/mod_autoindex.html#addiconbytype">AddIconByType</a>,
  +      and <a
  +      href="../mod/mod_autoindex.html#defaulticon">DefaultIcon</a>
  +      directives.</li>
  +
  +      <li>Apache versions before 1.2b1 will ignore the last line of
  +      configuration files if the last line does not have a trailing
  +      newline. This affects configuration files (httpd.conf,
  +      access.conf and srm.conf), and htpasswd and htgroup
  +      files.</li>
  +
  +      <li>Apache does not permit commas delimiting the methods in
  +      &lt;Limit&gt;.</li>
  +
  +      <li>Apache's <code>&lt;VirtualHost&gt;</code> treats all
  +      addresses as "optional" (<em>i.e.</em>, the server should
  +      continue booting if it can't resolve the address). Whereas in
  +      NCSA the default is to fail booting unless an added
  +      <code>optional</code> keyword is included.</li>
  +
  +      <li>Apache does not implement <code>OnDeny</code>; use <a
  +      href="../mod/core.html#errordocument"><code>ErrorDocument</code></a>
  +      instead.</li>
  +
  +      <li>Apache (as of 1.3) always performs the equivalent of
  +      <code>HostnameLookups minimal</code>. <code>minimal</code> is
  +      not an option to <a
  +      href="../mod/core.html#hostnamelookups"><code>HostnameLookups</code></a>.</li>
  +
  +      <li>To embed spaces in directive arguments NCSA used a
  +      backslash before the space. Apache treats backslashes as
  +      normal characters. To embed spaces surround the argument with
  +      double-quotes instead.</li>
  +
  +      <li>Apache does not implement the NCSA <code>referer</code>
  +      directive. See <a
  +      href="http://bugs.apache.org/index/full/968">PR#968</a> for a
  +      few brief suggestions on alternative ways to implement the
  +      same thing under Apache.</li>
  +
  +      <li>Apache does not allow ServerRoot settings inside a
  +      VirtualHost container. There is only one global ServerRoot in
  +      Apache; any desired changes in paths for virtual hosts need
  +      to be made with the explicit directives, <em>e.g.</em>,
  +      DocumentRoot, TransferLog, <em>etc.</em></li>
  +
  +      <li>The <code>AddType</code> directive cannot be used to set
  +      the type of particular files. Instead, you can scope you
  +      directives using &lt;Files&gt; blocks.</li>
  +    </ol>
  +    More to come when we notice them.... 
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
  +
  
  
  
  1.10      +366 -316  httpd-docs-1.3/htdocs/manual/misc/custom_errordocs.html
  
  Index: custom_errordocs.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/custom_errordocs.html,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- custom_errordocs.html	2000/12/03 03:28:37	1.9
  +++ custom_errordocs.html	2001/10/08 01:26:54	1.10
  @@ -1,146 +1,182 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>International Customized Server Error Messages</TITLE>
  -</HEAD>
  -
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -
  -<H1 ALIGN="CENTER">Using XSSI and <SAMP>ErrorDocument</SAMP> to configure
  -customized international server error responses</H1>
  -<P>
  -<H2>Index</H2>
  -<UL>
  - <LI><A HREF="#intro">Introduction</A>
  - <LI><A HREF="#createdir">Creating an ErrorDocument directory</A>
  - <LI><A HREF="#docnames">Naming the individual error document files</A>
  - <LI><A HREF="#headfoot">The common header and footer files</A>
  - <LI><A HREF="#createdocs">Creating ErrorDocuments in different languages</A>
  - <LI><A HREF="#fallback">The fallback language</A>
  - <LI><A HREF="#proxy">Customizing Proxy Error Messages</A>
  - <LI><A HREF="#listings">HTML listing of the discussed example</A>
  -</UL>
  -<HR>
  -<H2><A NAME="intro">Introduction</A></H2>
  -<p>
  -This document describes an easy way to provide your apache WWW server
  -with a set of customized error messages which take advantage of
  -<A HREF="../content-negotiation.html">Content Negotiation</A>
  -and <A HREF="../mod/mod_include.html">eXtended Server Side Includes (XSSI)</A>
  -to return error messages generated by the server in the client's
  -native language.
  -</P>
  -<P>
  -By using XSSI, all
  -<A HREF="../mod/core.html#errordocument">customized messages</A>
  -can share a homogenous and consistent style and layout, and maintenance work
  -(changing images, changing links) is kept to a minimum because all layout
  -information can be kept in a single file.<BR>
  -Error documents can be shared across different servers, or even hosts,
  -because all varying information is inserted at the time the error document
  -is returned on behalf of a failed request.
  -</P>
  -<P>
  -Content Negotiation then selects the appropriate language version of a
  -particular error message text, honoring the language preferences passed
  -in the client's request. (Users usually select their favorite languages
  -in the preferences options menu of today's browsers). When an error
  -document in the client's primary language version is unavailable, the 
  -secondary languages are tried or a default (fallback) version is used.
  -</P>
  -<P>
  -You have full flexibility in designing your error documents to
  -your personal taste (or your company's conventions). For demonstration
  -purposes, we present a simple generic error document scheme.
  -For this hypothetic server, we assume that all error messages...
  -</P>
  -
  -<UL>
  -<LI>possibly are served by different virtual hosts (different host name,
  -    different IP address, or different port) on the server machine,
  -<LI>show a predefined company logo in the right top of the message
  -    (selectable by virtual host),
  -<LI>print the error title first, followed by an explanatory text and
  -    (depending on the error context) help on how to resolve the error,
  -<LI>have some kind of standardized background image,
  -<LI>display an apache logo and a feedback email address at the bottom
  -    of the error message.
  -</UL>
  -
  -<P>
  -An example of a "document not found" message for a german client might
  -look like this:<BR>
  -<IMG SRC="../images/custom_errordocs.gif"
  - ALT="[Needs graphics capability to display]"><BR>
  -All links in the document as well as links to the server's administrator
  -mail address, and even the name and port of the serving virtual host
  -are inserted in the error document at "run-time", <EM>i.e.</EM>, when the error
  -actually occurs.
  -</P>
  -
  -<H2><A NAME="createdir">Creating an ErrorDocument directory</A></H2>
  -
  -For this concept to work as easily as possible, we must take advantage
  -of as much server support as we can get:
  -<OL>
  - <LI>By defining the <A HREF="../mod/core.html#options">MultiViews option</A>,
  -     we enable the language selection of the most appropriate language
  -     alternative (content negotiation). 
  - <LI>By setting the
  -     <A HREF="../mod/mod_negotiation.html#languagepriority"
  -     >LanguagePriority</A> 
  -     directive we define a set of default fallback languages in the situation
  -     where the client's browser did not express any preference at all.
  - <LI>By enabling <A HREF="../mod/mod_include.html">Server Side Includes</A>
  -     (and disallowing execution of cgi scripts for security reasons),
  -     we allow the server to include building blocks of the error message,
  -     and to substitute the value of certain environment variables into the
  -     generated document (dynamic HTML) or even to conditionally include
  -     or omit parts of the text.
  - <LI>The <A HREF="../mod/mod_mime.html#addhandler">AddHandler</A> and
  -     <A HREF="../mod/mod_mime.html#addtype">AddType</A> directives are useful
  -     for automatically XSSI-expanding all files with a <SAMP>.shtml</SAMP>
  -     suffix to <EM>text/html</EM>.
  - <LI>By using the <A HREF="../mod/mod_alias.html#alias">Alias</A> directive,
  -     we keep the error document directory outside of the document tree
  -     because it can be regarded more as a server part than part of
  -     the document tree.
  - <LI>The <A HREF="../mod/core.html#directory">&lt;Directory&gt;</A>-Block
  -     restricts these "special" settings to the error document directory
  -     and avoids an impact on any of the settings for the regular document tree.
  - <LI>For each of the error codes to be handled (see RFC2068 for an exact
  -     description of each error code, or look at
  -     <CODE>src/main/http_protocol.c</CODE>
  -     if you wish to see apache's standard messages), an
  -     <A HREF="../mod/core.html#errordocument">ErrorDocument</A>
  -     in the aliased <SAMP>/errordocs</SAMP> directory is defined.
  -     Note that we only define the basename of the document here
  -     because the MultiViews option will select the best candidate
  -     based on the language suffixes and the client's preferences.
  -     Any error situation with an error code <EM>not</EM> handled by a
  -     custom document will be dealt with by the server in the standard way
  -     (<EM>i.e.</EM>, a plain error message in english).
  - <LI>Finally, the <A HREF="../mod/core.html#allowoverride">AllowOverride</A>
  -     directive tells apache that it is not necessary to look for 
  -     a .htaccess file in the /errordocs directory: a minor speed 
  -     optimization.
  -</OL>
  -The resulting <SAMP>httpd.conf</SAMP> configuration would then look
  -similar to this: <SMALL>(Note that you can define your own error
  -messages using this method for only part of the document tree,
  -e.g., a /~user/ subtree. In this case, the configuration could as well
  -be put into the .htaccess file at the root of the subtree, and
  -the &lt;Directory&gt; and &lt;/Directory&gt; directives -but not
  -the contained directives- must be omitted.)</SMALL>
  -<PRE>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  +
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>International Customized Server Error Messages</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Using XSSI and <samp>ErrorDocument</samp> to
  +    configure customized international server error responses</h1>
  +
  +    <h2>Index</h2>
  +
  +    <ul>
  +      <li><a href="#intro">Introduction</a></li>
  +
  +      <li><a href="#createdir">Creating an ErrorDocument
  +      directory</a></li>
  +
  +      <li><a href="#docnames">Naming the individual error document
  +      files</a></li>
  +
  +      <li><a href="#headfoot">The common header and footer
  +      files</a></li>
  +
  +      <li><a href="#createdocs">Creating ErrorDocuments in
  +      different languages</a></li>
  +
  +      <li><a href="#fallback">The fallback language</a></li>
  +
  +      <li><a href="#proxy">Customizing Proxy Error
  +      Messages</a></li>
  +
  +      <li><a href="#listings">HTML listing of the discussed
  +      example</a></li>
  +    </ul>
  +    <hr />
  +
  +    <h2><a id="intro" name="intro">Introduction</a></h2>
  +
  +    <p>This document describes an easy way to provide your apache
  +    WWW server with a set of customized error messages which take
  +    advantage of <a href="../content-negotiation.html">Content
  +    Negotiation</a> and <a href="../mod/mod_include.html">eXtended
  +    Server Side Includes (XSSI)</a> to return error messages
  +    generated by the server in the client's native language.</p>
  +
  +    <p>By using XSSI, all <a
  +    href="../mod/core.html#errordocument">customized messages</a>
  +    can share a homogenous and consistent style and layout, and
  +    maintenance work (changing images, changing links) is kept to a
  +    minimum because all layout information can be kept in a single
  +    file.<br />
  +     Error documents can be shared across different servers, or
  +    even hosts, because all varying information is inserted at the
  +    time the error document is returned on behalf of a failed
  +    request.</p>
  +
  +    <p>Content Negotiation then selects the appropriate language
  +    version of a particular error message text, honoring the
  +    language preferences passed in the client's request. (Users
  +    usually select their favorite languages in the preferences
  +    options menu of today's browsers). When an error document in
  +    the client's primary language version is unavailable, the
  +    secondary languages are tried or a default (fallback) version
  +    is used.</p>
  +
  +    <p>You have full flexibility in designing your error documents
  +    to your personal taste (or your company's conventions). For
  +    demonstration purposes, we present a simple generic error
  +    document scheme. For this hypothetic server, we assume that all
  +    error messages...</p>
  +
  +    <ul>
  +      <li>possibly are served by different virtual hosts (different
  +      host name, different IP address, or different port) on the
  +      server machine,</li>
  +
  +      <li>show a predefined company logo in the right top of the
  +      message (selectable by virtual host),</li>
  +
  +      <li>print the error title first, followed by an explanatory
  +      text and (depending on the error context) help on how to
  +      resolve the error,</li>
  +
  +      <li>have some kind of standardized background image,</li>
  +
  +      <li>display an apache logo and a feedback email address at
  +      the bottom of the error message.</li>
  +    </ul>
  +
  +    <p>An example of a "document not found" message for a german
  +    client might look like this:<br />
  +     <img src="../images/custom_errordocs.gif"
  +    alt="[Needs graphics capability to display]" /><br />
  +     All links in the document as well as links to the server's
  +    administrator mail address, and even the name and port of the
  +    serving virtual host are inserted in the error document at
  +    "run-time", <em>i.e.</em>, when the error actually occurs.</p>
  +
  +    <h2><a id="createdir" name="createdir">Creating an
  +    ErrorDocument directory</a></h2>
  +    For this concept to work as easily as possible, we must take
  +    advantage of as much server support as we can get: 
  +
  +    <ol>
  +      <li>By defining the <a
  +      href="../mod/core.html#options">MultiViews option</a>, we
  +      enable the language selection of the most appropriate
  +      language alternative (content negotiation).</li>
  +
  +      <li>By setting the <a
  +      href="../mod/mod_negotiation.html#languagepriority">LanguagePriority</a>
  +      directive we define a set of default fallback languages in
  +      the situation where the client's browser did not express any
  +      preference at all.</li>
  +
  +      <li>By enabling <a href="../mod/mod_include.html">Server Side
  +      Includes</a> (and disallowing execution of cgi scripts for
  +      security reasons), we allow the server to include building
  +      blocks of the error message, and to substitute the value of
  +      certain environment variables into the generated document
  +      (dynamic HTML) or even to conditionally include or omit parts
  +      of the text.</li>
  +
  +      <li>The <a
  +      href="../mod/mod_mime.html#addhandler">AddHandler</a> and <a
  +      href="../mod/mod_mime.html#addtype">AddType</a> directives
  +      are useful for automatically XSSI-expanding all files with a
  +      <samp>.shtml</samp> suffix to <em>text/html</em>.</li>
  +
  +      <li>By using the <a
  +      href="../mod/mod_alias.html#alias">Alias</a> directive, we
  +      keep the error document directory outside of the document
  +      tree because it can be regarded more as a server part than
  +      part of the document tree.</li>
  +
  +      <li>The <a
  +      href="../mod/core.html#directory">&lt;Directory&gt;</a>-Block
  +      restricts these "special" settings to the error document
  +      directory and avoids an impact on any of the settings for the
  +      regular document tree.</li>
  +
  +      <li>For each of the error codes to be handled (see RFC2068
  +      for an exact description of each error code, or look at
  +      <code>src/main/http_protocol.c</code> if you wish to see
  +      apache's standard messages), an <a
  +      href="../mod/core.html#errordocument">ErrorDocument</a> in
  +      the aliased <samp>/errordocs</samp> directory is defined.
  +      Note that we only define the basename of the document here
  +      because the MultiViews option will select the best candidate
  +      based on the language suffixes and the client's preferences.
  +      Any error situation with an error code <em>not</em> handled
  +      by a custom document will be dealt with by the server in the
  +      standard way (<em>i.e.</em>, a plain error message in
  +      english).</li>
  +
  +      <li>Finally, the <a
  +      href="../mod/core.html#allowoverride">AllowOverride</a>
  +      directive tells apache that it is not necessary to look for a
  +      .htaccess file in the /errordocs directory: a minor speed
  +      optimization.</li>
  +    </ol>
  +    The resulting <samp>httpd.conf</samp> configuration would then
  +    look similar to this: <small>(Note that you can define your own
  +    error messages using this method for only part of the document
  +    tree, e.g., a /~user/ subtree. In this case, the configuration
  +    could as well be put into the .htaccess file at the root of the
  +    subtree, and the &lt;Directory&gt; and &lt;/Directory&gt;
  +    directives -but not the contained directives- must be
  +    omitted.)</small> 
  +<pre>
     LanguagePriority en fr de 
     Alias  /errordocs  /usr/local/apache/errordocs
     &lt;Directory /usr/local/apache/errordocs&gt;
  @@ -159,152 +195,162 @@
     ErrorDocument  404  /errordocs/404
     #    "500 Internal Server Error",
     ErrorDocument  500  /errordocs/500
  -</PRE>
  -The directory for the error messages (here:
  -<SAMP>/usr/local/apache/errordocs/</SAMP>) must then be created with the
  -appropriate permissions (readable and executable by the server uid or gid, 
  -only writable for the administrator).
  -
  -<H3><A NAME="docnames">Naming the individual error document files</A></H3>
  -
  -By defining the <SAMP>MultiViews</SAMP> option, the server was told to
  -automatically scan the directory for matching variants (looking at language
  -and content type suffixes) when a requested document was not found.
  -In the configuration, we defined the names for the error documents to be
  -just their error number (without any suffix).
  -<P>
  -The names of the individual error documents are now determined like this
  -(I'm using 403 as an example, think of it as a placeholder for any of
  -the configured error documents):
  -<UL>
  - <LI>No file errordocs/403 should exist. Otherwise, it would be found and
  -     served (with the DefaultType, usually text/plain), all negotiation
  -     would be bypassed.
  - <LI>For each language for which we have an internationalized version
  -     (note that this need not be the same set of languages for each
  -     error code - you can get by with a single language version until
  -     you actually <EM>have</EM> translated versions), a document
  -     <SAMP>errordocs/403.shtml.<EM>lang</EM></SAMP> is created and
  -     filled with the error text in that language (<A HREF="#createdocs">see
  -     below</A>).
  - <LI>One fallback document called <SAMP>errordocs/403.shtml</SAMP> is
  -     created, usually by creating a symlink to the default language
  -     variant (<A HREF="#fallback">see below</A>).
  -</UL>
  -
  -<H3><A NAME="headfoot">The common header and footer files</A></H3>
  -
  -By putting as much layout information in two special "include files", 
  -the error documents can be reduced to a bare minimum.
  -<P>
  -One of these layout files defines the HTML document header
  -and a configurable list of paths to the icons to be shown in the resulting
  -error document. These paths are exported as a set of XSSI environment
  -variables and are later evaluated by the "footer" special file.
  -The title of the current error (which is
  -put into the TITLE tag and an H1 header) is simply passed in from the main
  -error document in a variable called <CODE>title</CODE>.<BR>
  -<STRONG>By changing this file, the layout of all generated error
  -messages can be changed in a second.</STRONG>
  -(By exploiting the features of XSSI, you can easily define different
  -layouts based on the current virtual host, or even based on the
  -client's domain name).
  -<P>
  -The second layout file describes the footer to be displayed at the bottom
  -of every error message. In this example, it shows an apache logo, the current
  -server time, the server version string and adds a mail reference to the
  -site's webmaster.
  -<P>
  -For simplicity, the header file is simply called <CODE>head.shtml</CODE>
  -because it contains server-parsed content but no language specific
  -information. The footer file exists once for each language translation,
  -plus a symlink for the default language.<P>
  -<STRONG>Example:</STRONG> for English, French and German versions
  -(default english)<BR>
  -<CODE>foot.shtml.en</CODE>,<BR>
  -<CODE>foot.shtml.fr</CODE>,<BR>
  -<CODE>foot.shtml.de</CODE>,<BR>
  -<CODE>foot.shtml</CODE> symlink to <CODE>foot.shtml.en</CODE><P>
  -Both files are included into the error document by using the
  -directives <CODE>&lt;!--#include virtual="head" --&gt;</CODE>
  -and        <CODE>&lt;!--#include virtual="foot" --&gt;</CODE>
  -respectively: the rest of the magic occurs in mod_negotiation and
  -in mod_include.
  -<P>
  -
  -See <A HREF="#listings">the listings below</A> to see an actual HTML
  -implementation of the discussed example.
  -
  -
  -<H3><A NAME="createdocs">Creating ErrorDocuments in different languages</A>
  -</H3>
  -
  -After all this preparation work, little remains to be said about the
  -actual documents. They all share a simple common structure:
  -<PRE>
  -&lt;!--#set var="title" value="<EM>error description title</EM>" --&gt;
  +</pre>
  +    The directory for the error messages (here:
  +    <samp>/usr/local/apache/errordocs/</samp>) must then be created
  +    with the appropriate permissions (readable and executable by
  +    the server uid or gid, only writable for the administrator). 
  +
  +    <h3><a id="docnames" name="docnames">Naming the individual
  +    error document files</a></h3>
  +    By defining the <samp>MultiViews</samp> option, the server was
  +    told to automatically scan the directory for matching variants
  +    (looking at language and content type suffixes) when a
  +    requested document was not found. In the configuration, we
  +    defined the names for the error documents to be just their
  +    error number (without any suffix). 
  +
  +    <p>The names of the individual error documents are now
  +    determined like this (I'm using 403 as an example, think of it
  +    as a placeholder for any of the configured error
  +    documents):</p>
  +
  +    <ul>
  +      <li>No file errordocs/403 should exist. Otherwise, it would
  +      be found and served (with the DefaultType, usually
  +      text/plain), all negotiation would be bypassed.</li>
  +
  +      <li>For each language for which we have an internationalized
  +      version (note that this need not be the same set of languages
  +      for each error code - you can get by with a single language
  +      version until you actually <em>have</em> translated
  +      versions), a document
  +      <samp>errordocs/403.shtml.<em>lang</em></samp> is created and
  +      filled with the error text in that language (<a
  +      href="#createdocs">see below</a>).</li>
  +
  +      <li>One fallback document called
  +      <samp>errordocs/403.shtml</samp> is created, usually by
  +      creating a symlink to the default language variant (<a
  +      href="#fallback">see below</a>).</li>
  +    </ul>
  +
  +    <h3><a id="headfoot" name="headfoot">The common header and
  +    footer files</a></h3>
  +    By putting as much layout information in two special "include
  +    files", the error documents can be reduced to a bare minimum. 
  +
  +    <p>One of these layout files defines the HTML document header
  +    and a configurable list of paths to the icons to be shown in
  +    the resulting error document. These paths are exported as a set
  +    of XSSI environment variables and are later evaluated by the
  +    "footer" special file. The title of the current error (which is
  +    put into the TITLE tag and an H1 header) is simply passed in
  +    from the main error document in a variable called
  +    <code>title</code>.<br />
  +     <strong>By changing this file, the layout of all generated
  +    error messages can be changed in a second.</strong> (By
  +    exploiting the features of XSSI, you can easily define
  +    different layouts based on the current virtual host, or even
  +    based on the client's domain name).</p>
  +
  +    <p>The second layout file describes the footer to be displayed
  +    at the bottom of every error message. In this example, it shows
  +    an apache logo, the current server time, the server version
  +    string and adds a mail reference to the site's webmaster.</p>
  +
  +    <p>For simplicity, the header file is simply called
  +    <code>head.shtml</code> because it contains server-parsed
  +    content but no language specific information. The footer file
  +    exists once for each language translation, plus a symlink for
  +    the default language.</p>
  +
  +    <p><strong>Example:</strong> for English, French and German
  +    versions (default english)<br />
  +     <code>foot.shtml.en</code>,<br />
  +     <code>foot.shtml.fr</code>,<br />
  +     <code>foot.shtml.de</code>,<br />
  +     <code>foot.shtml</code> symlink to
  +    <code>foot.shtml.en</code></p>
  +
  +    <p>Both files are included into the error document by using the
  +    directives <code>&lt;!--#include virtual="head" --&gt;</code>
  +    and <code>&lt;!--#include virtual="foot" --&gt;</code>
  +    respectively: the rest of the magic occurs in mod_negotiation
  +    and in mod_include.</p>
  +
  +    <p>See <a href="#listings">the listings below</a> to see an
  +    actual HTML implementation of the discussed example.</p>
  +
  +    <h3><a id="createdocs" name="createdocs">Creating
  +    ErrorDocuments in different languages</a></h3>
  +    After all this preparation work, little remains to be said
  +    about the actual documents. They all share a simple common
  +    structure: 
  +<pre>
  +&lt;!--#set var="title" value="<em>error description title</em>" --&gt;
   &lt;!--#include virtual="head" --&gt;
  -   <EM>explanatory error text</EM>
  +   <em>explanatory error text</em>
   &lt;!--#include virtual="foot" --&gt;
  -</PRE>
  -In the <A HREF="#listings">listings section</A>, you can see an example
  -of a [400 Bad Request] error document. Documents as simple as that
  -certainly cause no problems to translate or expand.
  -
  -<H3><A NAME="fallback">The fallback language</A></H3>
  -
  -Do we need a special handling for languages other than those we have
  -translations for? We did set the LanguagePriority, didn't we?!
  -<P>
  -Well, the LanguagePriority directive is for the case where the client does
  -not express any language priority at all. But what
  -happens in the situation where the client wants one
  -of the languages we do not have, and none of those we do have?
  -<P>
  -Without doing anything, the Apache server will usually return a
  -[406 no acceptable variant] error, listing the choices from which the client
  -may select. But we're in an error message already, and important error
  -information might get lost when the client had to choose a language
  -representation first.
  -<P>
  -So, in this situation it appears to be easier to define a fallback language
  -(by copying or linking, <EM>e.g.</EM>, the english version to a language-less version).
  -Because the negotiation algorithm prefers "more specialized" variants over
  -"more generic" variants, these generic alternatives will only be chosen
  -when the normal negotiation did not succeed.
  -<P> 
  -A simple shell script to do it (execute within the errordocs/ dir):
  -<PRE>
  +</pre>
  +    In the <a href="#listings">listings section</a>, you can see an
  +    example of a [400 Bad Request] error document. Documents as
  +    simple as that certainly cause no problems to translate or
  +    expand. 
  +
  +    <h3><a id="fallback" name="fallback">The fallback
  +    language</a></h3>
  +    Do we need a special handling for languages other than those we
  +    have translations for? We did set the LanguagePriority, didn't
  +    we?! 
  +
  +    <p>Well, the LanguagePriority directive is for the case where
  +    the client does not express any language priority at all. But
  +    what happens in the situation where the client wants one of the
  +    languages we do not have, and none of those we do have?</p>
  +
  +    <p>Without doing anything, the Apache server will usually
  +    return a [406 no acceptable variant] error, listing the choices
  +    from which the client may select. But we're in an error message
  +    already, and important error information might get lost when
  +    the client had to choose a language representation first.</p>
  +
  +    <p>So, in this situation it appears to be easier to define a
  +    fallback language (by copying or linking, <em>e.g.</em>, the
  +    english version to a language-less version). Because the
  +    negotiation algorithm prefers "more specialized" variants over
  +    "more generic" variants, these generic alternatives will only
  +    be chosen when the normal negotiation did not succeed.</p>
  +
  +    <p>A simple shell script to do it (execute within the
  +    errordocs/ dir):</p>
  +<pre>
     for f in *.shtml.en
     do
        ln -s $f `basename $f .en`
     done
  -</PRE>
  -
  -<P>
  -</P>
  +</pre>
   
  -<H2><A NAME="proxy">Customizing Proxy Error Messages</A></H2>
  +    <h2><a id="proxy" name="proxy">Customizing Proxy Error
  +    Messages</a></h2>
   
  -<P>
  - As of Apache-1.3, it is possible to use the <CODE>ErrorDocument</CODE>
  - mechanism for proxy error messages as well (previous versions always
  - returned fixed predefined error messages).
  -</P>
  -<P>
  - Most proxy errors return an error code of [500 Internal Server Error].
  - To find out whether a particular error document was invoked on behalf
  - of a proxy error or because of some other server error, and what the reason
  - for the failure was, you can check the contents of the new
  - <CODE>ERROR_NOTES</CODE> CGI environment variable:
  - if invoked for a proxy error, this variable will contain the actual proxy
  - error message text in HTML form.
  -</P>
  -<P>
  - The following excerpt demonstrates how to exploit the <CODE>ERROR_NOTES</CODE>
  - variable within an error document:
  -</P>
  -<PRE>
  +    <p>As of Apache-1.3, it is possible to use the
  +    <code>ErrorDocument</code> mechanism for proxy error messages
  +    as well (previous versions always returned fixed predefined
  +    error messages).</p>
  +
  +    <p>Most proxy errors return an error code of [500 Internal
  +    Server Error]. To find out whether a particular error document
  +    was invoked on behalf of a proxy error or because of some other
  +    server error, and what the reason for the failure was, you can
  +    check the contents of the new <code>ERROR_NOTES</code> CGI
  +    environment variable: if invoked for a proxy error, this
  +    variable will contain the actual proxy error message text in
  +    HTML form.</p>
  +
  +    <p>The following excerpt demonstrates how to exploit the
  +    <code>ERROR_NOTES</code> variable within an error document:</p>
  +<pre>
    &lt;!--#if expr="$REDIRECT_ERROR_NOTES = ''" --&gt;
     &lt;p&gt;
      The server encountered an unexpected condition
  @@ -321,16 +367,18 @@
    &lt;!--#else --&gt;
     &lt;!--#echo var="REDIRECT_ERROR_NOTES" --&gt;
    &lt;!--#endif --&gt;
  -</PRE>
  +</pre>
   
  -<H2><A NAME="listings">HTML listing of the discussed example</A></H2>
  -
  -So, to summarize our example, here's the complete listing of the
  -<SAMP>400.shtml.en</SAMP> document. You will notice that it contains
  -almost nothing but the error text (with conditional additions).
  -Starting with this example, you will find it easy to add more error
  -documents, or to translate the error documents to different languages.
  -<HR><PRE>
  +    <h2><a id="listings" name="listings">HTML listing of the
  +    discussed example</a></h2>
  +    So, to summarize our example, here's the complete listing of
  +    the <samp>400.shtml.en</samp> document. You will notice that it
  +    contains almost nothing but the error text (with conditional
  +    additions). Starting with this example, you will find it easy
  +    to add more error documents, or to translate the error
  +    documents to different languages. 
  +    <hr />
  +<pre>
   &lt;!--#set var="title" value="Bad Request"
   --&gt;&lt;!--#include virtual="head" --&gt;&lt;P&gt;
      Your browser sent a request that this server could not understand:
  @@ -351,18 +399,21 @@
      &lt;!--#endif --&gt;
      &lt;/P&gt;
   &lt;!--#include virtual="foot" --&gt;
  -</PRE><HR>
  -
  -Here is the complete <SAMP>head.shtml</SAMP> file (the funny line
  -breaks avoid empty lines in the document after XSSI processing). Note the 
  -configuration section at top. That's where you configure the images and logos
  -as well as the apache documentation directory. Look how this file displays
  -two different logos depending on the content of the virtual host name
  -($SERVER_NAME), and that an animated apache logo is shown if the browser
  -appears to support it (the latter requires server configuration lines
  -of the form <BR><CODE>BrowserMatch "^Mozilla/[2-4]" anigif</CODE><BR>
  -for browser types which support animated GIFs).
  -<HR><PRE>
  +</pre>
  +    <hr />
  +    Here is the complete <samp>head.shtml</samp> file (the funny
  +    line breaks avoid empty lines in the document after XSSI
  +    processing). Note the configuration section at top. That's
  +    where you configure the images and logos as well as the apache
  +    documentation directory. Look how this file displays two
  +    different logos depending on the content of the virtual host
  +    name ($SERVER_NAME), and that an animated apache logo is shown
  +    if the browser appears to support it (the latter requires
  +    server configuration lines of the form <br />
  +     <code>BrowserMatch "^Mozilla/[2-4]" anigif</code><br />
  +     for browser types which support animated GIFs). 
  +    <hr />
  +<pre>
   &lt;!--#if expr="$SERVER_NAME = /.*\.mycompany\.com/" 
   --&gt;&lt;!--#set var="IMG_CorpLogo"
               value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif" 
  @@ -394,10 +445,11 @@
     &lt;/H1&gt;
     &lt;HR&gt;&lt;!-- ======================================================== --&gt;
     &lt;DIV&gt;
  -</PRE><HR>
  - and this is the <SAMP>foot.shtml.en</SAMP> file:
  -<HR><PRE>
  -
  +</pre>
  +    <hr />
  +    and this is the <samp>foot.shtml.en</samp> file: 
  +    <hr />
  +<pre>
     &lt;/DIV&gt;
     &lt;HR&gt;
     &lt;DIV ALIGN="right"&gt;&lt;SMALL&gt;&lt;SUP&gt;Local Server time:
  @@ -419,15 +471,13 @@
     &lt;/ADDRESS&gt;
    &lt;/UL&gt;&lt;/BODY&gt;
   &lt;/HTML&gt;
  -</PRE><HR>
  -
  -
  -<H3>More welcome!</H3>
  -
  -If you have tips to contribute, send mail to <A
  -HREF="mailto:martin@apache.org">martin@apache.org</A>
  +</pre>
  +    <hr />
   
  -  <!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  +    <h3>More welcome!</h3>
  +    If you have tips to contribute, send mail to <a
  +    href="mailto:martin@apache.org">martin@apache.org</a> 
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
   
  
  
  
  1.12      +193 -178  httpd-docs-1.3/htdocs/manual/misc/descriptors.html
  
  Index: descriptors.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/descriptors.html,v
  retrieving revision 1.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- descriptors.html	2001/09/24 01:36:41	1.11
  +++ descriptors.html	2001/10/08 01:26:54	1.12
  @@ -1,182 +1,197 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>Descriptors and Apache</TITLE>
  -</HEAD>
  -
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Descriptors and Apache</H1>
  -
  -<P>A <EM>descriptor</EM>, also commonly called a <EM>file handle</EM> is
  -an object that a program uses to read or write an open file, or open
  -network socket, or a variety of other devices.  It is represented
  -by an integer, and you may be familiar with <CODE>stdin</CODE>,
  -<CODE>stdout</CODE>, and <CODE>stderr</CODE> which are descriptors 0,
  -1, and 2 respectively.
  -Apache needs a descriptor for each log file, plus one for each
  -network socket that it listens on, plus a handful of others.  Libraries
  -that Apache uses may also require descriptors.  Normal programs don't
  -open up many descriptors at all, and so there are some latent problems
  -that you may experience should you start running Apache with many
  -descriptors (<EM>i.e.</EM>, with many virtual hosts).
  -
  -<P>The operating system enforces a limit on the number of descriptors
  -that a program can have open at a time.  There are typically three limits
  -involved here.  One is a kernel limitation, depending on your operating
  -system you will either be able to tune the number of descriptors available
  -to higher numbers (this is frequently called <EM>FD_SETSIZE</EM>).  Or you
  -may be stuck with a (relatively) low amount.  The second limit is called
  -the <EM>hard resource</EM> limit, and it is sometimes set by root in an
  -obscure operating system file, but frequently is the same as the kernel
  -limit.  The third limit is called the <EM>soft
  -resource</EM> limit.  The soft limit is always less than or equal to
  -the hard limit.  For example, the hard limit may be 1024, but the soft
  -limit only 64.  Any user can raise their soft limit up to the hard limit.
  -Root can raise the hard limit up to the system maximum limit.  The soft
  -limit is the actual limit that is used when enforcing the maximum number
  -of files a process can have open.
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -<P>To summarize:
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Descriptors and Apache</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Descriptors and Apache</h1>
  +
  +    <p>A <em>descriptor</em>, also commonly called a <em>file
  +    handle</em> is an object that a program uses to read or write
  +    an open file, or open network socket, or a variety of other
  +    devices. It is represented by an integer, and you may be
  +    familiar with <code>stdin</code>, <code>stdout</code>, and
  +    <code>stderr</code> which are descriptors 0, 1, and 2
  +    respectively. Apache needs a descriptor for each log file, plus
  +    one for each network socket that it listens on, plus a handful
  +    of others. Libraries that Apache uses may also require
  +    descriptors. Normal programs don't open up many descriptors at
  +    all, and so there are some latent problems that you may
  +    experience should you start running Apache with many
  +    descriptors (<em>i.e.</em>, with many virtual hosts).</p>
  +
  +    <p>The operating system enforces a limit on the number of
  +    descriptors that a program can have open at a time. There are
  +    typically three limits involved here. One is a kernel
  +    limitation, depending on your operating system you will either
  +    be able to tune the number of descriptors available to higher
  +    numbers (this is frequently called <em>FD_SETSIZE</em>). Or you
  +    may be stuck with a (relatively) low amount. The second limit
  +    is called the <em>hard resource</em> limit, and it is sometimes
  +    set by root in an obscure operating system file, but frequently
  +    is the same as the kernel limit. The third limit is called the
  +    <em>soft resource</em> limit. The soft limit is always less
  +    than or equal to the hard limit. For example, the hard limit
  +    may be 1024, but the soft limit only 64. Any user can raise
  +    their soft limit up to the hard limit. Root can raise the hard
  +    limit up to the system maximum limit. The soft limit is the
  +    actual limit that is used when enforcing the maximum number of
  +    files a process can have open.</p>
   
  -<CENTER><PRE>
  +    <p>To summarize:</p>
  +
  +    <center>
  +<pre>
     #open files  &lt;=  soft limit  &lt;=  hard limit  &lt;=  kernel limit
  -</PRE></CENTER>
  +</pre>
  +    </center>
  +
  +    <p>You control the hard and soft limits using the
  +    <code>limit</code> (csh) or <code>ulimit</code> (sh)
  +    directives. See the respective man pages for more information.
  +    For example you can probably use <code>ulimit -n
  +    unlimited</code> to raise your soft limit up to the hard limit.
  +    You should include this command in a shell script which starts
  +    your webserver.</p>
  +
  +    <p>Unfortunately, it's not always this simple. As mentioned
  +    above, you will probably run into some system limitations that
  +    will need to be worked around somehow. Work was done in version
  +    1.2.1 to improve the situation somewhat. Here is a partial list
  +    of systems and workarounds (assuming you are using 1.2.1 or
  +    later):</p>
  +
  +    <dl>
  +      <dt><strong>BSDI 2.0</strong></dt>
  +
  +      <dd>Under BSDI 2.0 you can build Apache to support more
  +      descriptors by adding <code>-DFD_SETSIZE=nnn</code> to
  +      <code>EXTRA_CFLAGS</code> (where nnn is the number of
  +      descriptors you wish to support, keep it less than the hard
  +      limit). But it will run into trouble if more than
  +      approximately 240 Listen directives are used. This may be
  +      cured by rebuilding your kernel with a higher
  +      FD_SETSIZE.</dd>
  +
  +      <dt><strong>FreeBSD 2.2, BSDI 2.1+</strong></dt>
  +
  +      <dd>Similar to the BSDI 2.0 case, you should define
  +      <code>FD_SETSIZE</code> and rebuild. But the extra Listen
  +      limitation doesn't exist.</dd>
  +
  +      <dt><strong>Linux</strong></dt>
  +
  +      <dd>By default Linux has a kernel maximum of 256 open
  +      descriptors per process. There are several patches available
  +      for the 2.0.x series which raise this to 1024 and beyond, and
  +      you can find them in the "unofficial patches" section of <a
  +      href="http://www.linuxhq.com/">the Linux Information HQ</a>.
  +      None of these patches are perfect, and an entirely different
  +      approach is likely to be taken during the 2.1.x development.
  +      Applying these patches will raise the FD_SETSIZE used to
  +      compile all programs, and unless you rebuild all your
  +      libraries you should avoid running any other program with a
  +      soft descriptor limit above 256. As of this writing the
  +      patches available for increasing the number of descriptors do
  +      not take this into account. On a dedicated webserver you
  +      probably won't run into trouble.</dd>
  +
  +      <dt><strong>Solaris through 2.5.1</strong></dt>
  +
  +      <dd>Solaris has a kernel hard limit of 1024 (may be lower in
  +      earlier versions). But it has a limitation that files using
  +      the stdio library cannot have a descriptor above 255. Apache
  +      uses the stdio library for the ErrorLog directive. When you
  +      have more than approximately 110 virtual hosts (with an error
  +      log and an access log each) you will need to build Apache
  +      with <code>-DHIGH_SLACK_LINE=256</code> added to
  +      <code>EXTRA_CFLAGS</code>. You will be limited to
  +      approximately 240 error logs if you do this.</dd>
  +
  +      <dt><strong>AIX</strong></dt>
  +
  +      <dd>AIX version 3.2?? appears to have a hard limit of 128
  +      descriptors. End of story. Version 4.1.5 has a hard limit of
  +      2000.</dd>
  +
  +      <dt><strong>SCO OpenServer</strong></dt>
  +
  +      <dd>Edit the <code>/etc/conf/cf.d/stune</code> file or use
  +      <code>/etc/conf/cf.d/configure</code> choice 7 (User and
  +      Group configuration) and modify the <code>NOFILES</code>
  +      kernel parameter to a suitably higher value. SCO recommends a
  +      number between 60 and 11000, the default is 110. Relink and
  +      reboot, and the new number of descriptors will be
  +      available.</dd>
  +
  +      <dt><strong>Compaq Tru64 UNIX/Digital UNIX/OSF</strong></dt>
  +
  +      <dd>
  +        <ol>
  +          <li>Raise <code>open_max_soft</code> and
  +          <code>open_max_hard</code> to 4096 in the proc subsystem.
  +          Do a man on sysconfig, sysconfigdb, and
  +          sysconfigtab.</li>
  +
  +          <li>Raise <code>max-vnodes</code> to a large number which
  +          is greater than the number of apache processes * 4096
  +          (Setting it to 250,000 should be good for most people).
  +          Do a man on sysconfig, sysconfigdb, and
  +          sysconfigtab.</li>
  +
  +          <li>If you are using Tru64 5.0, 5.0A, or 5.1, define
  +          <code>NO_SLACK</code> to work around a bug in the OS.
  +          <code>CFLAGS="-DNO_SLACK" ./configure</code></li>
  +        </ol>
  +      </dd>
  +
  +      <dt><strong>Others</strong></dt>
  +
  +      <dd>If you have details on another operating system, please
  +      submit it through our <a
  +      href="http://httpd.apache.org/bug_report.html">Bug Report
  +      Page</a>.</dd>
  +    </dl>
  +
  +    <p>In addition to the problems described above there are
  +    problems with many libraries that Apache uses. The most common
  +    example is the bind DNS resolver library that is used by pretty
  +    much every unix, which fails if it ends up with a descriptor
  +    above 256. We suspect there are other libraries that similar
  +    limitations. So the code as of 1.2.1 takes a defensive stance
  +    and tries to save descriptors less than 16 for use while
  +    processing each request. This is called the <em>low slack
  +    line</em>.</p>
  +
  +    <p>Note that this shouldn't waste descriptors. If you really
  +    are pushing the limits and Apache can't get a descriptor above
  +    16 when it wants it, it will settle for one below 16.</p>
  +
  +    <p>In extreme situations you may want to lower the low slack
  +    line, but you shouldn't ever need to. For example, lowering it
  +    can increase the limits 240 described above under Solaris and
  +    BSDI 2.0. But you'll play a delicate balancing game with the
  +    descriptors needed to serve a request. Should you want to play
  +    this game, the compile time parameter is
  +    <code>LOW_SLACK_LINE</code> and there's a tiny bit of
  +    documentation in the header file <code>httpd.h</code>.</p>
  +
  +    <p>Finally, if you suspect that all this slack stuff is causing
  +    you problems, you can disable it. Add <code>-DNO_SLACK</code>
  +    to <code>EXTRA_CFLAGS</code> and rebuild. But please report it
  +    to our <a href="http://httpd.apache.org/bug_report.html">Bug
  +    Report Page</a> so that we can investigate. 
  +    <!--#include virtual="footer.html" -->
  +    </p>
  +  </body>
  +</html>
   
  -<P>You control the hard and soft limits using the <CODE>limit</CODE> (csh)
  -or <CODE>ulimit</CODE> (sh) directives.  See the respective man pages
  -for more information.  For example you can probably use
  -<CODE>ulimit -n unlimited</CODE> to raise your soft limit up to the
  -hard limit.  You should include this command in a shell script which
  -starts your webserver.
  -
  -<P>Unfortunately, it's not always this simple.  As mentioned above,
  -you will probably run into some system limitations that will need to be
  -worked around somehow.  Work was done in version 1.2.1 to improve the
  -situation somewhat.  Here is a partial list of systems and workarounds
  -(assuming you are using 1.2.1 or later):
  -
  -<DL>
  -
  -    <DT><STRONG>BSDI 2.0</STRONG>
  -    <DD>Under BSDI 2.0 you can build Apache to support more descriptors
  -        by adding <CODE>-DFD_SETSIZE=nnn</CODE> to
  -        <CODE>EXTRA_CFLAGS</CODE> (where nnn is the number of descriptors
  -        you wish to support, keep it less than the hard limit).  But it
  -        will run into trouble if more than approximately 240 Listen
  -        directives are used.  This may be cured by rebuilding your kernel
  -        with a higher FD_SETSIZE.
  -    <P>
  -
  -    <DT><STRONG>FreeBSD 2.2, BSDI 2.1+</STRONG>
  -    <DD>Similar to the BSDI 2.0 case, you should define
  -        <CODE>FD_SETSIZE</CODE> and rebuild.  But the extra
  -        Listen limitation doesn't exist.
  -    <P>
  -
  -    <DT><STRONG>Linux</STRONG>
  -    <DD>By default Linux has a kernel maximum of 256 open descriptors
  -        per process.  There are several patches available for the
  -        2.0.x series which raise this to 1024 and beyond, and you
  -        can find them in the "unofficial patches" section of <A
  -        HREF="http://www.linuxhq.com/">the Linux Information HQ</A>.
  -        None of these patches are perfect, and an entirely different
  -        approach is likely to be taken during the 2.1.x development.
  -        Applying these patches will raise the FD_SETSIZE used to compile
  -        all programs, and unless you rebuild all your libraries you should
  -        avoid running any other program with a soft descriptor limit above
  -        256.  As of this writing the patches available for increasing
  -        the number of descriptors do not take this into account.  On a
  -        dedicated webserver you probably won't run into trouble.
  -    <P>
  -
  -    <DT><STRONG>Solaris through 2.5.1</STRONG>
  -    <DD>Solaris has a kernel hard limit of 1024 (may be lower in earlier
  -        versions).  But it has a limitation that files using
  -        the stdio library cannot have a descriptor above 255.
  -        Apache uses the stdio library for the ErrorLog directive.
  -        When you have more than approximately 110 virtual hosts
  -        (with an error log and an access log each) you will need to
  -        build Apache with <CODE>-DHIGH_SLACK_LINE=256</CODE> added to
  -        <CODE>EXTRA_CFLAGS</CODE>.  You will be limited to approximately
  -        240 error logs if you do this.
  -    <P>
  -
  -    <DT><STRONG>AIX</STRONG>
  -    <DD>AIX version 3.2?? appears to have a hard limit of 128 descriptors.
  -	End of story.  Version 4.1.5 has a hard limit of 2000.
  -    <P>
  -
  -    <DT><STRONG>SCO OpenServer</STRONG> 
  -    <DD>Edit the
  -    <CODE>/etc/conf/cf.d/stune</CODE> file or use 
  -    <CODE>/etc/conf/cf.d/configure</CODE> choice 7
  -    (User and Group configuration) and modify the <CODE>NOFILES</CODE> kernel
  -    parameter to a suitably higher value.  SCO recommends a number
  -    between 60 and 11000, the default is 110.  Relink and reboot, 
  -    and the new number of descriptors will be available.
  -
  -    <P>
  -
  -    <DT><STRONG>Compaq Tru64 UNIX/Digital UNIX/OSF</STRONG>
  -    <DD><OL>
  -    <LI>Raise <code>open_max_soft</code> and <code>open_max_hard</code>
  -        to 4096 in the proc subsystem.
  -        Do a man on sysconfig, sysconfigdb, and sysconfigtab.
  -    <LI>Raise <code>max-vnodes</code> to a large number which is greater 
  -        than the number of apache processes * 4096
  -        (Setting it to 250,000 should be good for most people).
  -        Do a man on sysconfig, sysconfigdb, and sysconfigtab.
  -    <LI>If you are using Tru64 5.0, 5.0A, or 5.1, define 
  -        <code>NO_SLACK</code> to work around a bug in the OS.
  -        <code>CFLAGS="-DNO_SLACK" ./configure</code>
  -    </OL>
  -
  -    <P>
  -
  -    <DT><STRONG>Others</STRONG>
  -    <DD>If you have details on another operating system, please submit
  -        it through our <A HREF="http://httpd.apache.org/bug_report.html">Bug
  -        Report Page</A>.
  -    <P>
  -
  -</DL>
  -
  -<P>In addition to the problems described above there are problems with
  -many libraries that Apache uses.  The most common example is the bind
  -DNS resolver library that is used by pretty much every unix, which
  -fails if it ends up with a descriptor above 256.  We suspect there
  -are other libraries that similar limitations.  So the code as of 1.2.1
  -takes a defensive stance and tries to save descriptors less than 16
  -for use while processing each request.  This is called the <EM>low
  -slack line</EM>.
  -
  -<P>Note that this shouldn't waste descriptors.  If you really are pushing
  -the limits and Apache can't get a descriptor above 16 when it wants
  -it, it will settle for one below 16.
  -
  -<P>In extreme situations you may want to lower the low slack line,
  -but you shouldn't ever need to.  For example, lowering it can
  -increase the limits 240 described above under Solaris and BSDI 2.0.
  -But you'll play a delicate balancing game with the descriptors needed
  -to serve a request.  Should you want to play this game, the compile
  -time parameter is <CODE>LOW_SLACK_LINE</CODE> and there's a tiny
  -bit of documentation in the header file <CODE>httpd.h</CODE>.
  -
  -<P>Finally, if you suspect that all this slack stuff is causing you
  -problems, you can disable it.  Add <CODE>-DNO_SLACK</CODE> to
  -<CODE>EXTRA_CFLAGS</CODE> and rebuild.  But please report it to
  -our <A HREF="http://httpd.apache.org/bug_report.html">Bug
  -Report Page</A> so that
  -we can investigate.
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  
  
  
  1.18      +399 -324  httpd-docs-1.3/htdocs/manual/misc/fin_wait_2.html
  
  Index: fin_wait_2.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/fin_wait_2.html,v
  retrieving revision 1.17
  retrieving revision 1.18
  diff -u -r1.17 -r1.18
  --- fin_wait_2.html	2001/03/28 21:25:44	1.17
  +++ fin_wait_2.html	2001/10/08 01:26:54	1.18
  @@ -1,324 +1,399 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>Connections in FIN_WAIT_2 and Apache</TITLE>
  -<LINK REV="made" HREF="mailto:marc@apache.org">
  -
  -</HEAD>
  -
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -
  -<H1 ALIGN="CENTER">Connections in the FIN_WAIT_2 state and Apache</H1>
  -<OL>
  -<LI><H2>What is the FIN_WAIT_2 state?</H2>
  -Starting with the Apache 1.2 betas, people are reporting many more
  -connections in the FIN_WAIT_2 state (as reported by
  -<CODE>netstat</CODE>) than they saw using older versions.  When the
  -server closes a TCP connection, it sends a packet with the FIN bit
  -sent to the client, which then responds with a packet with the ACK bit
  -set.  The client then sends a packet with the FIN bit set to the
  -server, which responds with an ACK and the connection is closed.  The
  -state that the connection is in during the period between when the
  -server gets the ACK from the client and the server gets the FIN from
  -the client is known as FIN_WAIT_2.  See the <A
  -HREF="ftp://ds.internic.net/rfc/rfc793.txt">TCP RFC</A> for the
  -technical details of the state transitions.<P>
  -
  -The FIN_WAIT_2 state is somewhat unusual in that there is no timeout
  -defined in the standard for it.  This means that on many operating
  -systems, a connection in the FIN_WAIT_2 state will stay around until
  -the system is rebooted.  If the system does not have a timeout and
  -too many FIN_WAIT_2 connections build up, it can fill up the space
  -allocated for storing information about the connections and crash
  -the kernel.  The connections in FIN_WAIT_2 do not tie up an httpd
  -process.<P>
  -
  -<LI><H2>But why does it happen?</H2>
  -
  -There are numerous reasons for it happening, some of them may not
  -yet be fully clear.  What is known follows.<P>
  -
  -<H3>Buggy clients and persistent connections</H3>
  -
  -Several clients have a bug which pops up when dealing with
  -<A HREF="../keepalive.html">persistent connections</A> (aka keepalives).
  -When the connection is idle and the server closes the connection
  -(based on the <A HREF="../mod/core.html#keepalivetimeout">
  -KeepAliveTimeout</A>), the client is programmed so that the client does
  -not send back a FIN and ACK to the server.  This means that the
  -connection stays in the FIN_WAIT_2 state until one of the following
  -happens:<P>
  -<UL>
  -        <LI>The client opens a new connection to the same or a different
  -            site, which causes it to fully close the older connection on
  -            that socket.
  -        <LI>The user exits the client, which on some (most?) clients
  -            causes the OS to fully shutdown the connection.
  -        <LI>The FIN_WAIT_2 times out, on servers that have a timeout
  -            for this state.
  -</UL><P>
  -If you are lucky, this means that the buggy client will fully close the
  -connection and release the resources on your server.  However, there
  -are some cases where the socket is never fully closed, such as a dialup
  -client disconnecting from their provider before closing the client.
  -In addition, a client might sit idle for days without making another
  -connection, and thus may hold its end of the socket open for days
  -even though it has no further use for it.
  -<STRONG>This is a bug in the browser or in its operating system's
  -TCP implementation.</STRONG>  <P>
  -
  -The clients on which this problem has been verified to exist:<P>
  -<UL>
  -        <LI>Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE i386)
  -        <LI>Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE i386)
  -        <LI>Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m)
  -        <LI>MSIE 3.01 on the Macintosh
  -        <LI>MSIE 3.01 on Windows 95
  -</UL><P>
  -
  -This does not appear to be a problem on:
  -<UL>
  -        <LI>Mozilla/3.01 (Win95; I)
  -</UL>
  -<P>
  -
  -It is expected that many other clients have the same problem. What a
  -client <STRONG>should do</STRONG> is periodically check its open
  -socket(s) to see if they have been closed by the server, and close their
  -side of the connection if the server has closed.  This check need only
  -occur once every few seconds, and may even be detected by a OS signal
  -on some systems (<EM>e.g.</EM>, Win95 and NT clients have this capability, but
  -they seem to be ignoring it).<P>
  -
  -Apache <STRONG>cannot</STRONG> avoid these FIN_WAIT_2 states unless it
  -disables persistent connections for the buggy clients, just
  -like we recommend doing for Navigator 2.x clients due to other bugs.
  -However, non-persistent connections increase the total number of
  -connections needed per client and slow retrieval of an image-laden
  -web page.  Since non-persistent connections have their own resource
  -consumptions and a short waiting period after each closure, a busy server
  -may need persistence in order to best serve its clients.<P>
  -
  -As far as we know, the client-caused FIN_WAIT_2 problem is present for
  -all servers that support persistent connections, including Apache 1.1.x
  -and 1.2.<P>
  -
  -<H3>A necessary bit of code introduced in 1.2</H3>
  -
  -While the above bug is a problem, it is not the whole problem.
  -Some users have observed no FIN_WAIT_2 problems with Apache 1.1.x,
  -but with 1.2b enough connections build up in the FIN_WAIT_2 state to
  -crash their server.  
  -
  -The most likely source for additional FIN_WAIT_2 states
  -is a function called <CODE>lingering_close()</CODE> which was added
  -between 1.1 and 1.2.  This function is necessary for the proper
  -handling of persistent connections and any request which includes
  -content in the message body (<EM>e.g.</EM>, PUTs and POSTs).
  -What it does is read any data sent by the client for
  -a certain time after the server closes the connection.  The exact
  -reasons for doing this are somewhat complicated, but involve what
  -happens if the client is making a request at the same time the
  -server sends a response and closes the connection. Without lingering,
  -the client might be forced to reset its TCP input buffer before it
  -has a chance to read the server's response, and thus understand why
  -the connection has closed.
  -See the <A HREF="#appendix">appendix</A> for more details.<P>
  -
  -The code in <CODE>lingering_close()</CODE> appears to cause problems
  -for a number of factors, including the change in traffic patterns
  -that it causes.  The code has been thoroughly reviewed and we are
  -not aware of any bugs in it.  It is possible that there is some
  -problem in the BSD TCP stack, aside from the lack of a timeout
  -for the FIN_WAIT_2 state, exposed by the <CODE>lingering_close</CODE>
  -code that causes the observed problems.<P>
  -
  -<H2><LI>What can I do about it?</H2>
  -
  -There are several possible workarounds to the problem, some of
  -which work better than others.<P>
  -
  -<H3>Add a timeout for FIN_WAIT_2</H3>
  -
  -The obvious workaround is to simply have a timeout for the FIN_WAIT_2 state.
  -This is not specified by the RFC, and could be claimed to be a
  -violation of the RFC, but it is widely recognized as being necessary.
  -The following systems are known to have a timeout:
  -<P>
  -<UL>
  -        <LI><A HREF="http://www.freebsd.org/">FreeBSD</A> versions starting at
  -            2.0 or possibly earlier.
  -        <LI><A HREF="http://www.netbsd.org/">NetBSD</A> version 1.2(?)
  -        <LI><A HREF="http://www.openbsd.org/">OpenBSD</A> all versions(?)
  -        <LI><A HREF="http://www.bsdi.com/">BSD/OS</A> 2.1, with the
  -            <A HREF="ftp://ftp.bsdi.com/bsdi/patches/patches-2.1/K210-027">
  -            K210-027</A> patch installed.
  -        <LI><A HREF="http://www.sun.com/">Solaris</A> as of around version
  -            2.2.  The timeout can be tuned by using <CODE>ndd</CODE> to
  -            modify <CODE>tcp_fin_wait_2_flush_interval</CODE>, but the
  -            default should be appropriate for most servers and improper
  -            tuning can have negative impacts.
  -        <LI><A HREF="http://www.linux.org/">Linux</A> 2.0.x and
  -            earlier(?)
  -        <LI><A HREF="http://www.hp.com/">HP-UX</A> 10.x defaults to
  -            terminating connections in the FIN_WAIT_2 state after the
  -            normal keepalive timeouts.  This does not
  -            refer to the persistent connection or HTTP keepalive
  -            timeouts, but the <CODE>SO_LINGER</CODE> socket option
  -            which is enabled by Apache.  This parameter can be adjusted
  -            by using <CODE>nettune</CODE> to modify parameters such as
  -            <CODE>tcp_keepstart</CODE> and <CODE>tcp_keepstop</CODE>.
  -            In later revisions, there is an explicit timer for
  -            connections in FIN_WAIT_2 that can be modified; contact HP
  -            support for details.
  -        <LI><A HREF="http://www.sgi.com/">SGI IRIX</A> can be patched to
  -            support a timeout.  For IRIX 5.3, 6.2, and 6.3,
  -            use patches 1654, 1703 and 1778 respectively.  If you
  -            have trouble locating these patches, please contact your
  -            SGI support channel for help.
  -        <LI><A HREF="http://www.ncr.com/">NCR's MP RAS Unix</A> 2.xx and
  -            3.xx both have FIN_WAIT_2 timeouts.  In 2.xx it is non-tunable
  -            at 600 seconds, while in 3.xx it defaults to 600 seconds and
  -            is calculated based on the tunable "max keep alive probes"
  -            (default of 8) multiplied by the "keep alive interval" (default
  -            75 seconds).
  -        <LI><A HREF="http://www.sequent.com">Sequent's ptx/TCP/IP for
  -            DYNIX/ptx</A> has had a FIN_WAIT_2 timeout since around
  -            release 4.1 in mid-1994.
  -</UL>
  -<P>
  -The following systems are known to not have a timeout:
  -<P>
  -<UL>
  -        <LI><A HREF="http://www.sun.com/">SunOS 4.x</A> does not and
  -            almost certainly never will have one because it as at the
  -            very end of its development cycle for Sun.  If you have kernel
  -            source should be easy to patch.
  -</UL>
  -<P>
  -There is a
  -<A HREF="http://www.apache.org/dist/httpd/contrib/patches/1.2/fin_wait_2.patch"
  ->patch available</A> for adding a timeout to the FIN_WAIT_2 state; it
  -was originally intended for BSD/OS, but should be adaptable to most
  -systems using BSD networking code.  You need kernel source code to be
  -able to use it.  If you do adapt it to work for any other systems,
  -please drop me a note at <A HREF="mailto:marc@apache.org">marc@apache.org</A>.
  -<P>
  -<H3>Compile without using <CODE>lingering_close()</CODE></H3>
  -
  -It is possible to compile Apache 1.2 without using the
  -<CODE>lingering_close()</CODE> function.  This will result in that
  -section of code being similar to that which was in 1.1.  If you do
  -this, be aware that it can cause problems with PUTs, POSTs and
  -persistent connections, especially if the client uses pipelining.
  -That said, it is no worse than on 1.1, and we understand that keeping your
  -server running is quite important.<P>
  -
  -To compile without the <CODE>lingering_close()</CODE> function, add
  -<CODE>-DNO_LINGCLOSE</CODE> to the end of the
  -<CODE>EXTRA_CFLAGS</CODE> line in your <CODE>Configuration</CODE> file,
  -rerun <CODE>Configure</CODE> and rebuild the server.
  -<P>
  -<H3>Use <CODE>SO_LINGER</CODE> as an alternative to
  -<CODE>lingering_close()</CODE></H3>
  -
  -On most systems, there is an option called <CODE>SO_LINGER</CODE> that
  -can be set with <CODE>setsockopt(2)</CODE>.  It does something very
  -similar to <CODE>lingering_close()</CODE>, except that it is broken
  -on many systems so that it causes far more problems than
  -<CODE>lingering_close</CODE>.  On some systems, it could possibly work
  -better so it may be worth a try if you have no other alternatives. <P>
  -
  -To try it, add <CODE>-DUSE_SO_LINGER -DNO_LINGCLOSE</CODE>  to the end of the
  -<CODE>EXTRA_CFLAGS</CODE> line in your <CODE>Configuration</CODE>
  -file, rerun <CODE>Configure</CODE> and rebuild the server.  <P>
  -
  -<STRONG>NOTE:</STRONG> Attempting to use <CODE>SO_LINGER</CODE> and
  -<CODE>lingering_close()</CODE> at the same time is very likely to do
  -very bad things, so don't.<P>
  -
  -<H3>Increase the amount of memory used for storing connection state</H3>
  -<DL>
  -<DT>BSD based networking code:
  -<DD>BSD stores network data, such as connection states,
  -in something called an mbuf.  When you get so many connections
  -that the kernel does not have enough mbufs to put them all in, your
  -kernel will likely crash.  You can reduce the effects of the problem
  -by increasing the number of mbufs that are available; this will not
  -prevent the problem, it will just make the server go longer before
  -crashing.<P>
  -
  -The exact way to increase them may depend on your OS; look
  -for some reference to the number of "mbufs" or "mbuf clusters".  On
  -many systems, this can be done by adding the line
  -<CODE>NMBCLUSTERS="n"</CODE>, where <CODE>n</CODE> is the number of
  -mbuf clusters you want to your kernel config file and rebuilding your
  -kernel.<P>
  -</DL>
  -
  -<H3>Disable KeepAlive</H3>
  -<P>If you are unable to do any of the above then you should, as a last
  -resort, disable KeepAlive.  Edit your httpd.conf and change "KeepAlive On"
  -to "KeepAlive Off".
  -
  -<H2><LI>Feedback</H2>
  -
  -If you have any information to add to this page, please contact me at
  -<A HREF="mailto:marc@apache.org">marc@apache.org</A>.<P>
  -
  -<H2><A NAME="appendix"><LI>Appendix</A></H2>
  -<P>
  -Below is a message from Roy Fielding, one of the authors of HTTP/1.1.
  -
  -<H3>Why the lingering close functionality is necessary with HTTP</H3>
  -
  -The need for a server to linger on a socket after a close is noted a couple
  -times in the HTTP specs, but not explained.  This explanation is based on
  -discussions between myself, Henrik Frystyk, Robert S. Thau, Dave Raggett,
  -and John C. Mallery in the hallways of MIT while I was at W3C.<P>
  -
  -If a server closes the input side of the connection while the client
  -is sending data (or is planning to send data), then the server's TCP
  -stack will signal an RST (reset) back to the client.  Upon
  -receipt of the RST, the client will flush its own incoming TCP buffer
  -back to the un-ACKed packet indicated by the RST packet argument.
  -If the server has sent a message, usually an error response, to the
  -client just before the close, and the client receives the RST packet
  -before its application code has read the error message from its incoming
  -TCP buffer and before the server has received the ACK sent by the client
  -upon receipt of that buffer, then the RST will flush the error message
  -before the client application has a chance to see it. The result is
  -that the client is left thinking that the connection failed for no
  -apparent reason.<P>
  -
  -There are two conditions under which this is likely to occur:
  -<OL>
  -<LI>sending POST or PUT data without proper authorization
  -<LI>sending multiple requests before each response (pipelining)
  -    and one of the middle requests resulting in an error or
  -    other break-the-connection result.
  -</OL>
  -<P>
  -The solution in all cases is to send the response, close only the
  -write half of the connection (what shutdown is supposed to do), and
  -continue reading on the socket until it is either closed by the
  -client (signifying it has finally read the response) or a timeout occurs.
  -That is what the kernel is supposed to do if SO_LINGER is set.
  -Unfortunately, SO_LINGER has no effect on some systems; on some other
  -systems, it does not have its own timeout and thus the TCP memory
  -segments just pile-up until the next reboot (planned or not).<P>
  -
  -Please note that simply removing the linger code will not solve the
  -problem -- it only moves it to a different and much harder one to detect.
  -</OL>
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  +
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Connections in FIN_WAIT_2 and Apache</title>
  +    <link rev="made" href="mailto:marc@apache.org" />
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Connections in the FIN_WAIT_2 state and
  +    Apache</h1>
  +
  +    <ol>
  +      <li>
  +        <h2>What is the FIN_WAIT_2 state?</h2>
  +        Starting with the Apache 1.2 betas, people are reporting
  +        many more connections in the FIN_WAIT_2 state (as reported
  +        by <code>netstat</code>) than they saw using older
  +        versions. When the server closes a TCP connection, it sends
  +        a packet with the FIN bit sent to the client, which then
  +        responds with a packet with the ACK bit set. The client
  +        then sends a packet with the FIN bit set to the server,
  +        which responds with an ACK and the connection is closed.
  +        The state that the connection is in during the period
  +        between when the server gets the ACK from the client and
  +        the server gets the FIN from the client is known as
  +        FIN_WAIT_2. See the <a
  +        href="ftp://ds.internic.net/rfc/rfc793.txt">TCP RFC</a> for
  +        the technical details of the state transitions. 
  +
  +        <p>The FIN_WAIT_2 state is somewhat unusual in that there
  +        is no timeout defined in the standard for it. This means
  +        that on many operating systems, a connection in the
  +        FIN_WAIT_2 state will stay around until the system is
  +        rebooted. If the system does not have a timeout and too
  +        many FIN_WAIT_2 connections build up, it can fill up the
  +        space allocated for storing information about the
  +        connections and crash the kernel. The connections in
  +        FIN_WAIT_2 do not tie up an httpd process.</p>
  +      </li>
  +
  +      <li>
  +        <h2>But why does it happen?</h2>
  +        There are numerous reasons for it happening, some of them
  +        may not yet be fully clear. What is known follows. 
  +
  +        <h3>Buggy clients and persistent connections</h3>
  +        Several clients have a bug which pops up when dealing with
  +        <a href="../keepalive.html">persistent connections</a> (aka
  +        keepalives). When the connection is idle and the server
  +        closes the connection (based on the <a
  +        href="../mod/core.html#keepalivetimeout">KeepAliveTimeout</a>),
  +        the client is programmed so that the client does not send
  +        back a FIN and ACK to the server. This means that the
  +        connection stays in the FIN_WAIT_2 state until one of the
  +        following happens: 
  +
  +        <ul>
  +          <li>The client opens a new connection to the same or a
  +          different site, which causes it to fully close the older
  +          connection on that socket.</li>
  +
  +          <li>The user exits the client, which on some (most?)
  +          clients causes the OS to fully shutdown the
  +          connection.</li>
  +
  +          <li>The FIN_WAIT_2 times out, on servers that have a
  +          timeout for this state.</li>
  +        </ul>
  +
  +        <p>If you are lucky, this means that the buggy client will
  +        fully close the connection and release the resources on
  +        your server. However, there are some cases where the socket
  +        is never fully closed, such as a dialup client
  +        disconnecting from their provider before closing the
  +        client. In addition, a client might sit idle for days
  +        without making another connection, and thus may hold its
  +        end of the socket open for days even though it has no
  +        further use for it. <strong>This is a bug in the browser or
  +        in its operating system's TCP implementation.</strong></p>
  +
  +        <p>The clients on which this problem has been verified to
  +        exist:</p>
  +
  +        <ul>
  +          <li>Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE
  +          i386)</li>
  +
  +          <li>Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE
  +          i386)</li>
  +
  +          <li>Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m)</li>
  +
  +          <li>MSIE 3.01 on the Macintosh</li>
  +
  +          <li>MSIE 3.01 on Windows 95</li>
  +        </ul>
  +
  +        <p>This does not appear to be a problem on:</p>
  +
  +        <ul>
  +          <li>Mozilla/3.01 (Win95; I)</li>
  +        </ul>
  +
  +        <p>It is expected that many other clients have the same
  +        problem. What a client <strong>should do</strong> is
  +        periodically check its open socket(s) to see if they have
  +        been closed by the server, and close their side of the
  +        connection if the server has closed. This check need only
  +        occur once every few seconds, and may even be detected by a
  +        OS signal on some systems (<em>e.g.</em>, Win95 and NT
  +        clients have this capability, but they seem to be ignoring
  +        it).</p>
  +
  +        <p>Apache <strong>cannot</strong> avoid these FIN_WAIT_2
  +        states unless it disables persistent connections for the
  +        buggy clients, just like we recommend doing for Navigator
  +        2.x clients due to other bugs. However, non-persistent
  +        connections increase the total number of connections needed
  +        per client and slow retrieval of an image-laden web page.
  +        Since non-persistent connections have their own resource
  +        consumptions and a short waiting period after each closure,
  +        a busy server may need persistence in order to best serve
  +        its clients.</p>
  +
  +        <p>As far as we know, the client-caused FIN_WAIT_2 problem
  +        is present for all servers that support persistent
  +        connections, including Apache 1.1.x and 1.2.</p>
  +
  +        <h3>A necessary bit of code introduced in 1.2</h3>
  +        While the above bug is a problem, it is not the whole
  +        problem. Some users have observed no FIN_WAIT_2 problems
  +        with Apache 1.1.x, but with 1.2b enough connections build
  +        up in the FIN_WAIT_2 state to crash their server. The most
  +        likely source for additional FIN_WAIT_2 states is a
  +        function called <code>lingering_close()</code> which was
  +        added between 1.1 and 1.2. This function is necessary for
  +        the proper handling of persistent connections and any
  +        request which includes content in the message body
  +        (<em>e.g.</em>, PUTs and POSTs). What it does is read any
  +        data sent by the client for a certain time after the server
  +        closes the connection. The exact reasons for doing this are
  +        somewhat complicated, but involve what happens if the
  +        client is making a request at the same time the server
  +        sends a response and closes the connection. Without
  +        lingering, the client might be forced to reset its TCP
  +        input buffer before it has a chance to read the server's
  +        response, and thus understand why the connection has
  +        closed. See the <a href="#appendix">appendix</a> for more
  +        details. 
  +
  +        <p>The code in <code>lingering_close()</code> appears to
  +        cause problems for a number of factors, including the
  +        change in traffic patterns that it causes. The code has
  +        been thoroughly reviewed and we are not aware of any bugs
  +        in it. It is possible that there is some problem in the BSD
  +        TCP stack, aside from the lack of a timeout for the
  +        FIN_WAIT_2 state, exposed by the
  +        <code>lingering_close</code> code that causes the observed
  +        problems.</p>
  +      </li>
  +
  +      <li>
  +        What can I do about it? There are several possible
  +        workarounds to the problem, some of which work better than
  +        others. 
  +
  +        <h3>Add a timeout for FIN_WAIT_2</h3>
  +        The obvious workaround is to simply have a timeout for the
  +        FIN_WAIT_2 state. This is not specified by the RFC, and
  +        could be claimed to be a violation of the RFC, but it is
  +        widely recognized as being necessary. The following systems
  +        are known to have a timeout: 
  +
  +        <ul>
  +          <li><a href="http://www.freebsd.org/">FreeBSD</a>
  +          versions starting at 2.0 or possibly earlier.</li>
  +
  +          <li><a href="http://www.netbsd.org/">NetBSD</a> version
  +          1.2(?)</li>
  +
  +          <li><a href="http://www.openbsd.org/">OpenBSD</a> all
  +          versions(?)</li>
  +
  +          <li><a href="http://www.bsdi.com/">BSD/OS</a> 2.1, with
  +          the <a
  +          href="ftp://ftp.bsdi.com/bsdi/patches/patches-2.1/K210-027">
  +          K210-027</a> patch installed.</li>
  +
  +          <li><a href="http://www.sun.com/">Solaris</a> as of
  +          around version 2.2. The timeout can be tuned by using
  +          <code>ndd</code> to modify
  +          <code>tcp_fin_wait_2_flush_interval</code>, but the
  +          default should be appropriate for most servers and
  +          improper tuning can have negative impacts.</li>
  +
  +          <li><a href="http://www.linux.org/">Linux</a> 2.0.x and
  +          earlier(?)</li>
  +
  +          <li><a href="http://www.hp.com/">HP-UX</a> 10.x defaults
  +          to terminating connections in the FIN_WAIT_2 state after
  +          the normal keepalive timeouts. This does not refer to the
  +          persistent connection or HTTP keepalive timeouts, but the
  +          <code>SO_LINGER</code> socket option which is enabled by
  +          Apache. This parameter can be adjusted by using
  +          <code>nettune</code> to modify parameters such as
  +          <code>tcp_keepstart</code> and <code>tcp_keepstop</code>.
  +          In later revisions, there is an explicit timer for
  +          connections in FIN_WAIT_2 that can be modified; contact
  +          HP support for details.</li>
  +
  +          <li><a href="http://www.sgi.com/">SGI IRIX</a> can be
  +          patched to support a timeout. For IRIX 5.3, 6.2, and 6.3,
  +          use patches 1654, 1703 and 1778 respectively. If you have
  +          trouble locating these patches, please contact your SGI
  +          support channel for help.</li>
  +
  +          <li><a href="http://www.ncr.com/">NCR's MP RAS Unix</a>
  +          2.xx and 3.xx both have FIN_WAIT_2 timeouts. In 2.xx it
  +          is non-tunable at 600 seconds, while in 3.xx it defaults
  +          to 600 seconds and is calculated based on the tunable
  +          "max keep alive probes" (default of 8) multiplied by the
  +          "keep alive interval" (default 75 seconds).</li>
  +
  +          <li><a href="http://www.sequent.com">Sequent's ptx/TCP/IP
  +          for DYNIX/ptx</a> has had a FIN_WAIT_2 timeout since
  +          around release 4.1 in mid-1994.</li>
  +        </ul>
  +
  +        <p>The following systems are known to not have a
  +        timeout:</p>
  +
  +        <ul>
  +          <li><a href="http://www.sun.com/">SunOS 4.x</a> does not
  +          and almost certainly never will have one because it as at
  +          the very end of its development cycle for Sun. If you
  +          have kernel source should be easy to patch.</li>
  +        </ul>
  +
  +        <p>There is a <a
  +        href="http://www.apache.org/dist/httpd/contrib/patches/1.2/fin_wait_2.patch">
  +        patch available</a> for adding a timeout to the FIN_WAIT_2
  +        state; it was originally intended for BSD/OS, but should be
  +        adaptable to most systems using BSD networking code. You
  +        need kernel source code to be able to use it. If you do
  +        adapt it to work for any other systems, please drop me a
  +        note at <a
  +        href="mailto:marc@apache.org">marc@apache.org</a>.</p>
  +
  +        <h3>Compile without using
  +        <code>lingering_close()</code></h3>
  +        It is possible to compile Apache 1.2 without using the
  +        <code>lingering_close()</code> function. This will result
  +        in that section of code being similar to that which was in
  +        1.1. If you do this, be aware that it can cause problems
  +        with PUTs, POSTs and persistent connections, especially if
  +        the client uses pipelining. That said, it is no worse than
  +        on 1.1, and we understand that keeping your server running
  +        is quite important. 
  +
  +        <p>To compile without the <code>lingering_close()</code>
  +        function, add <code>-DNO_LINGCLOSE</code> to the end of the
  +        <code>EXTRA_CFLAGS</code> line in your
  +        <code>Configuration</code> file, rerun
  +        <code>Configure</code> and rebuild the server.</p>
  +
  +        <h3>Use <code>SO_LINGER</code> as an alternative to
  +        <code>lingering_close()</code></h3>
  +        On most systems, there is an option called
  +        <code>SO_LINGER</code> that can be set with
  +        <code>setsockopt(2)</code>. It does something very similar
  +        to <code>lingering_close()</code>, except that it is broken
  +        on many systems so that it causes far more problems than
  +        <code>lingering_close</code>. On some systems, it could
  +        possibly work better so it may be worth a try if you have
  +        no other alternatives. 
  +
  +        <p>To try it, add <code>-DUSE_SO_LINGER
  +        -DNO_LINGCLOSE</code> to the end of the
  +        <code>EXTRA_CFLAGS</code> line in your
  +        <code>Configuration</code> file, rerun
  +        <code>Configure</code> and rebuild the server.</p>
  +
  +        <p><strong>NOTE:</strong> Attempting to use
  +        <code>SO_LINGER</code> and <code>lingering_close()</code>
  +        at the same time is very likely to do very bad things, so
  +        don't.</p>
  +
  +        <h3>Increase the amount of memory used for storing
  +        connection state</h3>
  +
  +        <dl>
  +          <dt>BSD based networking code:</dt>
  +
  +          <dd>
  +            BSD stores network data, such as connection states, in
  +            something called an mbuf. When you get so many
  +            connections that the kernel does not have enough mbufs
  +            to put them all in, your kernel will likely crash. You
  +            can reduce the effects of the problem by increasing the
  +            number of mbufs that are available; this will not
  +            prevent the problem, it will just make the server go
  +            longer before crashing. 
  +
  +            <p>The exact way to increase them may depend on your
  +            OS; look for some reference to the number of "mbufs" or
  +            "mbuf clusters". On many systems, this can be done by
  +            adding the line <code>NMBCLUSTERS="n"</code>, where
  +            <code>n</code> is the number of mbuf clusters you want
  +            to your kernel config file and rebuilding your
  +            kernel.</p>
  +          </dd>
  +        </dl>
  +
  +        <h3>Disable KeepAlive</h3>
  +
  +        <p>If you are unable to do any of the above then you
  +        should, as a last resort, disable KeepAlive. Edit your
  +        httpd.conf and change "KeepAlive On" to "KeepAlive
  +        Off".</p>
  +      </li>
  +
  +      <li>
  +        Feedback If you have any information to add to this page,
  +        please contact me at <a
  +        href="mailto:marc@apache.org">marc@apache.org</a>. 
  +
  +        <h2><a id="appendix" name="appendix"></a></h2>
  +      </li>
  +
  +      <li>
  +        Appendix 
  +
  +        <p>Below is a message from Roy Fielding, one of the authors
  +        of HTTP/1.1.</p>
  +
  +        <h3>Why the lingering close functionality is necessary with
  +        HTTP</h3>
  +        The need for a server to linger on a socket after a close
  +        is noted a couple times in the HTTP specs, but not
  +        explained. This explanation is based on discussions between
  +        myself, Henrik Frystyk, Robert S. Thau, Dave Raggett, and
  +        John C. Mallery in the hallways of MIT while I was at W3C. 
  +
  +        <p>If a server closes the input side of the connection
  +        while the client is sending data (or is planning to send
  +        data), then the server's TCP stack will signal an RST
  +        (reset) back to the client. Upon receipt of the RST, the
  +        client will flush its own incoming TCP buffer back to the
  +        un-ACKed packet indicated by the RST packet argument. If
  +        the server has sent a message, usually an error response,
  +        to the client just before the close, and the client
  +        receives the RST packet before its application code has
  +        read the error message from its incoming TCP buffer and
  +        before the server has received the ACK sent by the client
  +        upon receipt of that buffer, then the RST will flush the
  +        error message before the client application has a chance to
  +        see it. The result is that the client is left thinking that
  +        the connection failed for no apparent reason.</p>
  +
  +        <p>There are two conditions under which this is likely to
  +        occur:</p>
  +
  +        <ol>
  +          <li>sending POST or PUT data without proper
  +          authorization</li>
  +
  +          <li>sending multiple requests before each response
  +          (pipelining) and one of the middle requests resulting in
  +          an error or other break-the-connection result.</li>
  +        </ol>
  +
  +        <p>The solution in all cases is to send the response, close
  +        only the write half of the connection (what shutdown is
  +        supposed to do), and continue reading on the socket until
  +        it is either closed by the client (signifying it has
  +        finally read the response) or a timeout occurs. That is
  +        what the kernel is supposed to do if SO_LINGER is set.
  +        Unfortunately, SO_LINGER has no effect on some systems; on
  +        some other systems, it does not have its own timeout and
  +        thus the TCP memory segments just pile-up until the next
  +        reboot (planned or not).</p>
  +
  +        <p>Please note that simply removing the linger code will
  +        not solve the problem -- it only moves it to a different
  +        and much harder one to detect.</p>
  +      </li>
  +    </ol>
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
  +
  
  
  
  1.4       +17 -6     httpd-docs-1.3/htdocs/manual/misc/footer.html
  
  Index: footer.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/footer.html,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- footer.html	1997/11/04 01:17:58	1.3
  +++ footer.html	2001/10/08 01:26:54	1.4
  @@ -1,8 +1,19 @@
  -<HR>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -<H3 ALIGN="CENTER">
  - Apache HTTP Server Version 1.3
  -</H3>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
   
  -<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A>
  -<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A>
  +    <title></title>
  +  </head>
  +
  +  <body>
  +    <hr />
  +
  +    <h3 align="CENTER">Apache HTTP Server Version 1.3</h3>
  +    <a href="./"><img src="../images/index.gif" alt="Index" /></a>
  +    <a href="../"><img src="../images/home.gif" alt="Home" /></a>
  +  </body>
  +</html>
  +
  
  
  
  1.4       +19 -6     httpd-docs-1.3/htdocs/manual/misc/header.html
  
  Index: header.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/header.html,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- header.html	1997/11/04 01:17:59	1.3
  +++ header.html	2001/10/08 01:26:54	1.4
  @@ -1,6 +1,19 @@
  -<DIV ALIGN="CENTER">
  - <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]">
  - <H3>
  -  Apache HTTP Server Version 1.3
  - </H3>
  -</DIV>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  +
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title></title>
  +  </head>
  +
  +  <body>
  +    <div align="CENTER">
  +      <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> 
  +
  +      <h3>Apache HTTP Server Version 1.3</h3>
  +    </div>
  +  </body>
  +</html>
  +
  
  
  
  1.14      +214 -193  httpd-docs-1.3/htdocs/manual/misc/howto.html
  
  Index: howto.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/howto.html,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -r1.13 -r1.14
  --- howto.html	2000/11/06 22:45:25	1.13
  +++ howto.html	2001/10/08 01:26:54	1.14
  @@ -1,208 +1,229 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<META NAME="description"
  - CONTENT="Some 'how to' tips for the Apache httpd server">
  -<META NAME="keywords" CONTENT="apache,redirect,robots,rotate,logfiles">
  -<TITLE>Apache HOWTO documentation</TITLE>
  -</HEAD>
  -
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Apache HOWTO documentation</H1>
  -
  -How to:
  -<UL>
  -<LI><A HREF="#redirect">redirect an entire server or directory to a single
  -    URL</A>
  -<LI><A HREF="#logreset">reset your log files</A>
  -<LI><A HREF="#stoprob">stop/restrict robots</A>
  -<LI><A HREF="#proxyssl">proxy SSL requests <EM>through</EM> your non-SSL
  -    server</A>
  -</UL>
  -
  -<HR>
  -<H2><A NAME="redirect">How to redirect an entire server or directory to a
  -single URL</A></H2>
  -
  -<P>There are two chief ways to redirect all requests for an entire
  -server to a single location: one which requires the use of
  -<CODE>mod_rewrite</CODE>, and another which uses a CGI script.
  -
  -<P>First: if all you need to do is migrate a server from one name to
  -another, simply use the <CODE>Redirect</CODE> directive, as supplied
  -by <CODE>mod_alias</CODE>:
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -<BLOCKQUOTE><PRE>
  -  Redirect / http://www.apache.org/
  -</PRE></BLOCKQUOTE>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +    <meta name="description"
  +    content="Some 'how to' tips for the Apache httpd server" />
  +    <meta name="keywords"
  +    content="apache,redirect,robots,rotate,logfiles" />
  +
  +    <title>Apache HOWTO documentation</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache HOWTO documentation</h1>
  +    How to: 
  +
  +    <ul>
  +      <li><a href="#redirect">redirect an entire server or
  +      directory to a single URL</a></li>
  +
  +      <li><a href="#logreset">reset your log files</a></li>
  +
  +      <li><a href="#stoprob">stop/restrict robots</a></li>
  +
  +      <li><a href="#proxyssl">proxy SSL requests <em>through</em>
  +      your non-SSL server</a></li>
  +    </ul>
  +    <hr />
  +
  +    <h2><a id="redirect" name="redirect">How to redirect an entire
  +    server or directory to a single URL</a></h2>
  +
  +    <p>There are two chief ways to redirect all requests for an
  +    entire server to a single location: one which requires the use
  +    of <code>mod_rewrite</code>, and another which uses a CGI
  +    script.</p>
  +
  +    <p>First: if all you need to do is migrate a server from one
  +    name to another, simply use the <code>Redirect</code>
  +    directive, as supplied by <code>mod_alias</code>:</p>
   
  -<P>Since <CODE>Redirect</CODE> will forward along the complete path,
  -however, it may not be appropriate - for example, when the directory
  -structure has changed after the move, and you simply want to direct people
  -to the home page.
  -
  -<P>The best option is to use the standard Apache module
  -<CODE>mod_rewrite</CODE>.
  -If that module is compiled in, the following lines
  +    <blockquote>
  +<pre>
  +  Redirect / http://www.apache.org/
  +</pre>
  +    </blockquote>
   
  -<BLOCKQUOTE><PRE>RewriteEngine On
  +    <p>Since <code>Redirect</code> will forward along the complete
  +    path, however, it may not be appropriate - for example, when
  +    the directory structure has changed after the move, and you
  +    simply want to direct people to the home page.</p>
  +
  +    <p>The best option is to use the standard Apache module
  +    <code>mod_rewrite</code>. If that module is compiled in, the
  +    following lines</p>
  +
  +    <blockquote>
  +<pre>
  +RewriteEngine On
   RewriteRule /.* http://www.apache.org/ [R]
  -</PRE></BLOCKQUOTE>
  -
  -will send an HTTP 302 Redirect back to the client, and no matter
  -what they gave in the original URL, they'll be sent to
  -"http://www.apache.org/".
  -
  -<p>The second option is to set up a <CODE>ScriptAlias</CODE> pointing to
  -a <STRONG>CGI script</STRONG> which outputs a 301 or 302 status and the
  -location
  -of the other server.</P>
  -
  -<P>By using a <STRONG>CGI script</STRONG> you can intercept various requests
  -and
  -treat them specially, <EM>e.g.</EM>, you might want to intercept
  -<STRONG>POST</STRONG>
  -requests, so that the client isn't redirected to a script on the other
  -server which expects POST information (a redirect will lose the POST
  -information.) You might also want to use a CGI script if you don't
  -want to compile mod_rewrite into your server.
  -
  -<P>Here's how to redirect all requests to a script... In the server
  -configuration file,
  -<BLOCKQUOTE><PRE>ScriptAlias / /usr/local/httpd/cgi-bin/redirect_script/</PRE>
  -</BLOCKQUOTE>
  +</pre>
  +    </blockquote>
  +    will send an HTTP 302 Redirect back to the client, and no
  +    matter what they gave in the original URL, they'll be sent to
  +    "http://www.apache.org/". 
  +
  +    <p>The second option is to set up a <code>ScriptAlias</code>
  +    pointing to a <strong>CGI script</strong> which outputs a 301
  +    or 302 status and the location of the other server.</p>
  +
  +    <p>By using a <strong>CGI script</strong> you can intercept
  +    various requests and treat them specially, <em>e.g.</em>, you
  +    might want to intercept <strong>POST</strong> requests, so that
  +    the client isn't redirected to a script on the other server
  +    which expects POST information (a redirect will lose the POST
  +    information.) You might also want to use a CGI script if you
  +    don't want to compile mod_rewrite into your server.</p>
  +
  +    <p>Here's how to redirect all requests to a script... In the
  +    server configuration file,</p>
  +
  +    <blockquote>
  +<pre>
  +ScriptAlias / /usr/local/httpd/cgi-bin/redirect_script/
  +</pre>
  +    </blockquote>
  +    and here's a simple perl script to redirect requests: 
   
  -and here's a simple perl script to redirect requests:
  -
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   #!/usr/local/bin/perl
   
   print "Status: 302 Moved Temporarily\r\n" .
         "Location: http://www.some.where.else.com/\r\n" .
         "\r\n";
  -
  -</PRE></BLOCKQUOTE>
  -
  -<HR>
   
  -<H2><A NAME="logreset">How to reset your log files</A></H2>
  -
  -<P>Sooner or later, you'll want to reset your log files (access_log and
  -error_log) because they are too big, or full of old information you don't
  -need.</P>
  -
  -<P><CODE>access.log</CODE> typically grows by 1Mb for each 10,000 requests.</P>
  -
  -<P>Most people's first attempt at replacing the logfile is to just move the
  -logfile or remove the logfile. This doesn't work.</P>
  -
  -<P>Apache will continue writing to the logfile at the same offset as before the
  -logfile moved. This results in a new logfile being created which is just
  -as big as the old one, but it now contains thousands (or millions) of null
  -characters.</P>
  -
  -<P>The correct procedure is to move the logfile, then signal Apache to tell
  -it to reopen the logfiles.</P>
  -
  -<P>Apache is signaled using the <STRONG>SIGHUP</STRONG> (-1) signal.
  -<EM>e.g.</EM>
  -<BLOCKQUOTE><CODE>
  -mv access_log access_log.old<BR>
  -kill -1 `cat httpd.pid`
  -</CODE></BLOCKQUOTE>
  -
  -<P>Note: <CODE>httpd.pid</CODE> is a file containing the
  -<STRONG>p</STRONG>rocess <STRONG>id</STRONG>
  -of the Apache httpd daemon, Apache saves this in the same directory as the log
  -files.</P>
  -
  -<P>Many people use this method to replace (and backup) their logfiles on a
  -nightly or weekly basis.</P>
  -<HR>
  -
  -<H2><A NAME="stoprob">How to stop or restrict robots</A></H2>
  -
  -<P>Ever wondered why so many clients are interested in a file called
  -<CODE>robots.txt</CODE> which you don't have, and never did have?</P>
  -
  -<P>These clients are called <STRONG>robots</STRONG> (also known as crawlers,
  -spiders and other cute names) - special automated clients which
  -wander around the web looking for interesting resources.</P>
  -
  -<P>Most robots are used to generate some kind of <EM>web index</EM> which
  -is then used by a <EM>search engine</EM> to help locate information.</P>
  -
  -<P><CODE>robots.txt</CODE> provides a means to request that robots limit their
  -activities at the site, or more often than not, to leave the site alone.</P>
  -
  -<P>When the first robots were developed, they had a bad reputation for
  -sending hundreds/thousands of requests to each site, often resulting
  -in the site being overloaded. Things have improved dramatically since
  -then, thanks to <A
  -HREF="http://info.webcrawler.com/mak/projects/robots/guidelines.html">
  -Guidelines for Robot Writers</A>, but even so, some robots may exhibit
  -unfriendly behavior which the webmaster isn't willing to tolerate, and
  -will want to stop.</P>
  -
  -<P>Another reason some webmasters want to block access to robots, is to
  -stop them indexing dynamic information. Many search engines will use the
  -data collected from your pages for months to come - not much use if you're
  -serving stock quotes, news, weather reports or anything else that will be
  -stale by the time people find it in a search engine.</P>
  -
  -<P>If you decide to exclude robots completely, or just limit the areas
  -in which they can roam, create a <CODE>robots.txt</CODE> file; refer
  -to the <A HREF="http://info.webcrawler.com/mak/projects/robots/robots.html"
  ->robot information pages</A> provided by Martijn Koster for the syntax.</P>
  -
  -<HR>
  -<H2><A NAME="proxyssl">How to proxy SSL requests <EM>through</EM>
  -    your non-SSL Apache server</A>
  -    <BR>
  -    <SMALL>(<EM>submitted by David Sedlock</EM>)</SMALL>
  -</H2>
  -<P>
  -SSL uses port 443 for requests for secure pages. If your browser just
  -sits there for a long time when you attempt to access a secure page
  -over your Apache proxy, then the proxy may not be configured to handle
  -SSL. You need to instruct Apache to listen on port 443 in addition to
  -any of the ports on which it is already listening:
  -</P>
  -<PRE>
  +</pre>
  +    </blockquote>
  +    <hr />
  +
  +    <h2><a id="logreset" name="logreset">How to reset your log
  +    files</a></h2>
  +
  +    <p>Sooner or later, you'll want to reset your log files
  +    (access_log and error_log) because they are too big, or full of
  +    old information you don't need.</p>
  +
  +    <p><code>access.log</code> typically grows by 1Mb for each
  +    10,000 requests.</p>
  +
  +    <p>Most people's first attempt at replacing the logfile is to
  +    just move the logfile or remove the logfile. This doesn't
  +    work.</p>
  +
  +    <p>Apache will continue writing to the logfile at the same
  +    offset as before the logfile moved. This results in a new
  +    logfile being created which is just as big as the old one, but
  +    it now contains thousands (or millions) of null characters.</p>
  +
  +    <p>The correct procedure is to move the logfile, then signal
  +    Apache to tell it to reopen the logfiles.</p>
  +
  +    <p>Apache is signaled using the <strong>SIGHUP</strong> (-1)
  +    signal. <em>e.g.</em></p>
  +
  +    <blockquote>
  +      <code>mv access_log access_log.old<br />
  +       kill -1 `cat httpd.pid`</code>
  +    </blockquote>
  +
  +    <p>Note: <code>httpd.pid</code> is a file containing the
  +    <strong>p</strong>rocess <strong>id</strong> of the Apache
  +    httpd daemon, Apache saves this in the same directory as the
  +    log files.</p>
  +
  +    <p>Many people use this method to replace (and backup) their
  +    logfiles on a nightly or weekly basis.</p>
  +    <hr />
  +
  +    <h2><a id="stoprob" name="stoprob">How to stop or restrict
  +    robots</a></h2>
  +
  +    <p>Ever wondered why so many clients are interested in a file
  +    called <code>robots.txt</code> which you don't have, and never
  +    did have?</p>
  +
  +    <p>These clients are called <strong>robots</strong> (also known
  +    as crawlers, spiders and other cute names) - special automated
  +    clients which wander around the web looking for interesting
  +    resources.</p>
  +
  +    <p>Most robots are used to generate some kind of <em>web
  +    index</em> which is then used by a <em>search engine</em> to
  +    help locate information.</p>
  +
  +    <p><code>robots.txt</code> provides a means to request that
  +    robots limit their activities at the site, or more often than
  +    not, to leave the site alone.</p>
  +
  +    <p>When the first robots were developed, they had a bad
  +    reputation for sending hundreds/thousands of requests to each
  +    site, often resulting in the site being overloaded. Things have
  +    improved dramatically since then, thanks to <a
  +    href="http://info.webcrawler.com/mak/projects/robots/guidelines.html">
  +    Guidelines for Robot Writers</a>, but even so, some robots may
  +    exhibit unfriendly behavior which the webmaster isn't willing
  +    to tolerate, and will want to stop.</p>
  +
  +    <p>Another reason some webmasters want to block access to
  +    robots, is to stop them indexing dynamic information. Many
  +    search engines will use the data collected from your pages for
  +    months to come - not much use if you're serving stock quotes,
  +    news, weather reports or anything else that will be stale by
  +    the time people find it in a search engine.</p>
  +
  +    <p>If you decide to exclude robots completely, or just limit
  +    the areas in which they can roam, create a
  +    <code>robots.txt</code> file; refer to the <a
  +    href="http://info.webcrawler.com/mak/projects/robots/robots.html">
  +    robot information pages</a> provided by Martijn Koster for the
  +    syntax.</p>
  +    <hr />
  +
  +    <h2><a id="proxyssl" name="proxyssl">How to proxy SSL requests
  +    <em>through</em> your non-SSL Apache server</a><br />
  +     <small>(<em>submitted by David Sedlock</em>)</small></h2>
  +
  +    <p>SSL uses port 443 for requests for secure pages. If your
  +    browser just sits there for a long time when you attempt to
  +    access a secure page over your Apache proxy, then the proxy may
  +    not be configured to handle SSL. You need to instruct Apache to
  +    listen on port 443 in addition to any of the ports on which it
  +    is already listening:</p>
  +<pre>
       Listen 80
       Listen 443
  -</PRE>
  -<P>
  -Then set the security proxy in your browser to 443. That might be it!
  -</P>
  -<P>
  -If your proxy is sending requests to another proxy, then you may have
  -to set the directive ProxyRemote differently. Here are my settings:
  -</P>
  -<PRE>
  +</pre>
  +
  +    <p>Then set the security proxy in your browser to 443. That
  +    might be it!</p>
  +
  +    <p>If your proxy is sending requests to another proxy, then you
  +    may have to set the directive ProxyRemote differently. Here are
  +    my settings:</p>
  +<pre>
       ProxyRemote http://nicklas:80/ http://proxy.mayn.franken.de:8080
       ProxyRemote http://nicklas:443/ http://proxy.mayn.franken.de:443
  -</PRE>
  -<P>
  -Requests on port 80 of my proxy <SAMP>nicklas</SAMP> are forwarded to
  -<SAMP>proxy.mayn.franken.de:8080</SAMP>, while requests on port 443 are
  -forwarded to <SAMP>proxy.mayn.franken.de:443</SAMP>.
  -If the remote proxy is not set up to
  -handle port 443, then the last directive can be left out. SSL requests
  -will only go over the first proxy.
  -</P>
  -<P>
  -Note that your Apache does NOT have to be set up to serve secure pages
  -with SSL. Proxying SSL is a different thing from using it.
  -</P>
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  +</pre>
  +
  +    <p>Requests on port 80 of my proxy <samp>nicklas</samp> are
  +    forwarded to <samp>proxy.mayn.franken.de:8080</samp>, while
  +    requests on port 443 are forwarded to
  +    <samp>proxy.mayn.franken.de:443</samp>. If the remote proxy is
  +    not set up to handle port 443, then the last directive can be
  +    left out. SSL requests will only go over the first proxy.</p>
  +
  +    <p>Note that your Apache does NOT have to be set up to serve
  +    secure pages with SSL. Proxying SSL is a different thing from
  +    using it.</p>
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
  +
  
  
  
  1.13      +138 -151  httpd-docs-1.3/htdocs/manual/misc/index.html
  
  Index: index.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/index.html,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- index.html	1998/08/10 18:00:03	1.12
  +++ index.html	2001/10/08 01:26:54	1.13
  @@ -1,151 +1,138 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  - <HEAD>
  -  <TITLE>Apache Miscellaneous Documentation</TITLE>
  - </HEAD>
  -
  - <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  - <BODY
  -  BGCOLOR="#FFFFFF"
  -  TEXT="#000000"
  -  LINK="#0000FF"
  -  VLINK="#000080"
  -  ALINK="#FF0000"
  - >
  -  <!--#include virtual="header.html" -->
  -  <H1 ALIGN="CENTER">Apache Miscellaneous Documentation</H1>
  -
  -  <P>
  -  Below is a list of additional documentation pages that apply to the
  -  Apache web server development project.
  -  </P>
  -  <DL>
  -   <DT><A
  -        HREF="API.html"
  -       >API</A>
  -   </DT>
  -   <DD>Description of Apache's Application Programming Interface.
  -   </DD>
  -   <DT><A
  -        HREF="FAQ.html"
  -       >FAQ</A>
  -   </DT>
  -   <DD>Frequently-Asked Questions concerning the Apache project and server.
  -   </DD>
  -   <DT><A
  -        HREF="client_block_api.html"
  -       >Reading Client Input in Apache 1.2</A>
  -   </DT>
  -   <DD>Describes differences between Apache 1.1 and 1.2 in how modules
  -    read information from the client.
  -   </DD>
  -   <DT><A
  -        HREF="compat_notes.html"
  -       >Compatibility with NCSA</A>
  -   </DT>
  -   <DD>Notes about Apache's compatibility with the NCSA server.
  -   </DD>
  -   <DT><A HREF="custom_errordocs.html">How to use XSSI and Negotiation 
  -	for custom ErrorDocuments</A>
  -   </DT>
  -   <DD>Describes a solution which uses XSSI and negotiation
  -    to custom-tailor the Apache ErrorDocuments to taste, adding the
  -    advantage of returning internationalized versions of the error
  -    messages depending on the client's language preferences.
  -   </DD>
  -   <DT><A HREF="descriptors.html">File Descriptor use in Apache</A>
  -   <DD>Describes how Apache uses file descriptors and talks about various
  -    limits imposed on the number of descriptors available by various 
  -    operating systems.
  -   </DD>
  -   <DT><A
  -        HREF="fin_wait_2.html"
  -       ><SAMP>FIN_WAIT_2</SAMP></A>
  -   </DT>
  -   <DD>A description of the causes of Apache processes going into the
  -    <SAMP>FIN_WAIT_2</SAMP> state, and what you can do about it.
  -   </DD>
  -   <DT><A
  -        HREF="howto.html"
  -       >&quot;How-To&quot;</A>
  -   </DT>
  -   <DD>Instructions about how to accomplish some commonly-desired server
  -    functionality changes.
  -   </DD>
  -   <DT><A HREF="HTTP_Features.tsv">HTTP Features list</A></DT>
  -     <DD>A tab-separate table of HTTP features implemented and tested in Apache.
  -     </DD> 
  -   <DT><A
  -        HREF="known_client_problems.html"
  -       >Known Client Problems</A>
  -   </DT>
  -   <DD>A list of problems in HTTP clients which can be mitigated by Apache.
  -   </DD>
  -   <DT><A
  -        HREF="nopgp.html"
  -       >No PGP</A>
  -   </DT>
  -   <DD>Why we took PEM and PGP support out of the base Apache distribution.
  -   </DD>
  -   <DT><A
  -        HREF="perf-bsd44.html"
  -       >Performance Notes (BSD 4.4)</A>
  -   </DT>
  -   <DD>Some notes about ways to improve/optimize Apache performance on
  -    BSD 4.4 systems.
  -   </DD>
  -   <DT><A
  -        HREF="perf-dec.html"
  -       >Performance Notes (Digital UNIX)</A>
  -   </DT>
  -   <DD>Extracts of USENET postings describing how to optimize Apache
  -    performance on Digital UNIX systems.
  -   </DD>
  -   <DT><A
  -        HREF="perf-hp.html"
  -       >Performance Notes (HPUX)</A>
  -   </DT>
  -   <DD>Email from an HP engineer on how to optimize HP-UX 10.20.
  -   </DD>
  -   <DT><A
  -        HREF="perf.html"
  -       >Performance Notes (General)</A>
  -   </DT>
  -   <DD>Some generic notes about how to improve the performance of your
  -       machine/OS.
  -   </DD>
  -   <DT><A
  -        HREF="perf-tuning.html"
  -       >Performance Notes -- Apache Tuning</A>
  -   </DT>
  -   <DD>Notes about how to (run-time and compile-time) configure
  -       Apache for highest performance.  Notes explaining why Apache does
  -       some things, and why it doesn't do other things (which make it
  -       slower/faster).
  -   </DD>
  -   <DT><A
  -        HREF="security_tips.html"
  -       >Security Tips</A>
  -   </DT>
  -   <DD>Some &quot;do&quot;s  - and &quot;don't&quot;s - for keeping your
  -    Apache web site secure.
  -   </DD>
  -   <DT><A
  -        HREF="vif-info.html"
  -       >Virtual Hosts (IP-based)</A>
  -   </DT>
  -   <DD>Excerpts and notes about configuring and using Apache IP-based virtual
  -    hosts.
  -   </DD>
  -   <DT><A
  -        HREF="windoz_keepalive.html"
  -       >Windows Bug with Web Keepalive</A>
  -   </DT>
  -   <DD>A brief description of a known problem with Microsoft Windows and
  -    web sites accessed using keepalive connections.
  -   </DD>
  -  </DL>
  -
  -  <!--#include virtual="footer.html" -->
  - </BODY>
  -</HTML>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  +
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Miscellaneous Documentation</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache Miscellaneous Documentation</h1>
  +
  +    <p>Below is a list of additional documentation pages that apply
  +    to the Apache web server development project.</p>
  +
  +    <dl>
  +      <dt><a href="API.html">API</a></dt>
  +
  +      <dd>Description of Apache's Application Programming
  +      Interface.</dd>
  +
  +      <dt><a href="FAQ.html">FAQ</a></dt>
  +
  +      <dd>Frequently-Asked Questions concerning the Apache project
  +      and server.</dd>
  +
  +      <dt><a href="client_block_api.html">Reading Client Input in
  +      Apache 1.2</a></dt>
  +
  +      <dd>Describes differences between Apache 1.1 and 1.2 in how
  +      modules read information from the client.</dd>
  +
  +      <dt><a href="compat_notes.html">Compatibility with
  +      NCSA</a></dt>
  +
  +      <dd>Notes about Apache's compatibility with the NCSA
  +      server.</dd>
  +
  +      <dt><a href="custom_errordocs.html">How to use XSSI and
  +      Negotiation for custom ErrorDocuments</a></dt>
  +
  +      <dd>Describes a solution which uses XSSI and negotiation to
  +      custom-tailor the Apache ErrorDocuments to taste, adding the
  +      advantage of returning internationalized versions of the
  +      error messages depending on the client's language
  +      preferences.</dd>
  +
  +      <dt><a href="descriptors.html">File Descriptor use in
  +      Apache</a></dt>
  +
  +      <dd>Describes how Apache uses file descriptors and talks
  +      about various limits imposed on the number of descriptors
  +      available by various operating systems.</dd>
  +
  +      <dt><a
  +      href="fin_wait_2.html"><samp>FIN_WAIT_2</samp></a></dt>
  +
  +      <dd>A description of the causes of Apache processes going
  +      into the <samp>FIN_WAIT_2</samp> state, and what you can do
  +      about it.</dd>
  +
  +      <dt><a href="howto.html">"How-To"</a></dt>
  +
  +      <dd>Instructions about how to accomplish some
  +      commonly-desired server functionality changes.</dd>
  +
  +      <dt><a href="HTTP_Features.tsv">HTTP Features list</a></dt>
  +
  +      <dd>A tab-separate table of HTTP features implemented and
  +      tested in Apache.</dd>
  +
  +      <dt><a href="known_client_problems.html">Known Client
  +      Problems</a></dt>
  +
  +      <dd>A list of problems in HTTP clients which can be mitigated
  +      by Apache.</dd>
  +
  +      <dt><a href="nopgp.html">No PGP</a></dt>
  +
  +      <dd>Why we took PEM and PGP support out of the base Apache
  +      distribution.</dd>
  +
  +      <dt><a href="perf-bsd44.html">Performance Notes (BSD
  +      4.4)</a></dt>
  +
  +      <dd>Some notes about ways to improve/optimize Apache
  +      performance on BSD 4.4 systems.</dd>
  +
  +      <dt><a href="perf-dec.html">Performance Notes (Digital
  +      UNIX)</a></dt>
  +
  +      <dd>Extracts of USENET postings describing how to optimize
  +      Apache performance on Digital UNIX systems.</dd>
  +
  +      <dt><a href="perf-hp.html">Performance Notes (HPUX)</a></dt>
  +
  +      <dd>Email from an HP engineer on how to optimize HP-UX
  +      10.20.</dd>
  +
  +      <dt><a href="perf.html">Performance Notes (General)</a></dt>
  +
  +      <dd>Some generic notes about how to improve the performance
  +      of your machine/OS.</dd>
  +
  +      <dt><a href="perf-tuning.html">Performance Notes -- Apache
  +      Tuning</a></dt>
  +
  +      <dd>Notes about how to (run-time and compile-time) configure
  +      Apache for highest performance. Notes explaining why Apache
  +      does some things, and why it doesn't do other things (which
  +      make it slower/faster).</dd>
  +
  +      <dt><a href="security_tips.html">Security Tips</a></dt>
  +
  +      <dd>Some "do"s - and "don't"s - for keeping your Apache web
  +      site secure.</dd>
  +
  +      <dt><a href="vif-info.html">Virtual Hosts (IP-based)</a></dt>
  +
  +      <dd>Excerpts and notes about configuring and using Apache
  +      IP-based virtual hosts.</dd>
  +
  +      <dt><a href="windoz_keepalive.html">Windows Bug with Web
  +      Keepalive</a></dt>
  +
  +      <dd>A brief description of a known problem with Microsoft
  +      Windows and web sites accessed using keepalive
  +      connections.</dd>
  +    </dl>
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
  +
  
  
  
  1.20      +343 -302  httpd-docs-1.3/htdocs/manual/misc/known_client_problems.html
  
  Index: known_client_problems.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/known_client_problems.html,v
  retrieving revision 1.19
  retrieving revision 1.20
  diff -u -r1.19 -r1.20
  --- known_client_problems.html	2001/03/28 21:25:44	1.19
  +++ known_client_problems.html	2001/10/08 01:26:54	1.20
  @@ -1,305 +1,346 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>Apache HTTP Server Project</TITLE>
  -</HEAD>
  -
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Known Problems in Clients</H1>
  -
  -<P>Over time the Apache Group has discovered or been notified of problems
  -with various clients which we have had to work around, or explain.
  -This document describes these problems and the workarounds available.
  -It's not arranged in any particular order.  Some familiarity with the
  -standards is assumed, but not necessary.
  -
  -<P>For brevity, <EM>Navigator</EM> will refer to Netscape's Navigator
  -product (which in later versions was renamed "Communicator" and
  -various other names), and <EM>MSIE</EM> will refer to Microsoft's
  -Internet Explorer product.  All trademarks and copyrights belong to
  -their respective companies.  We welcome input from the various client
  -authors to correct inconsistencies in this paper, or to provide us with
  -exact version numbers where things are broken/fixed.
  -
  -<P>For reference,
  -<A HREF="ftp://ds.internic.net/rfc/rfc1945.txt">RFC1945</A>
  -defines HTTP/1.0, and
  -<A HREF="ftp://ds.internic.net/rfc/rfc2068.txt">RFC2068</A>
  -defines HTTP/1.1.  Apache as of version 1.2 is an HTTP/1.1 server (with an 
  -optional HTTP/1.0 proxy).
  -
  -<P>Various of these workarounds are triggered by environment variables.
  -The admin typically controls which are set, and for which clients, by using 
  -<A HREF="../mod/mod_browser.html">mod_browser</A>.  Unless otherwise
  -noted all of these workarounds exist in versions 1.2 and later.
  -
  -<H3><A NAME="trailing-crlf">Trailing CRLF on POSTs</A></H3>
  -
  -<P>This is a legacy issue.  The CERN webserver required <CODE>POST</CODE>
  -data to have an extra <CODE>CRLF</CODE> following it.  Thus many
  -clients send an extra <CODE>CRLF</CODE> that
  -is not included in the <CODE>Content-Length</CODE> of the request.
  -Apache works around this problem by eating any empty lines which
  -appear before a request.
  -
  -<H3><A NAME="broken-keepalive">Broken keepalive</A></H3>
  -
  -<P>Various clients have had broken implementations of <EM>keepalive</EM>
  -(persistent connections).  In particular the Windows versions of
  -Navigator 2.0 get very confused when the server times out an
  -idle connection.  The workaround is present in the default config files:
  -<BLOCKQUOTE><CODE>
  -BrowserMatch Mozilla/2 nokeepalive
  -</CODE></BLOCKQUOTE>
  -Note that this matches some earlier versions of MSIE, which began the
  -practice of calling themselves <EM>Mozilla</EM> in their user-agent
  -strings just like Navigator.
  -
  -<P>MSIE 4.0b2, which claims to support HTTP/1.1, does not properly
  -support keepalive when it is used on 301 or 302 (redirect)
  -responses.  Unfortunately Apache's <CODE>nokeepalive</CODE> code
  -prior to 1.2.2 would not work with HTTP/1.1 clients.  You must apply
  -<A
  -HREF="http://www.apache.org/dist/httpd/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch"
  ->this patch</A> to version 1.2.1.  Then add this to your config:
  -<BLOCKQUOTE><CODE>
  -BrowserMatch "MSIE 4\.0b2;" nokeepalive
  -</CODE></BLOCKQUOTE>
  -
  -<H3><A NAME="force-response-1.0">Incorrect interpretation of
  -<CODE>HTTP/1.1</CODE> in response</A></H3>
  -
  -<P>To quote from section 3.1 of RFC1945:
  -<BLOCKQUOTE>
  -HTTP uses a "&lt;MAJOR&gt;.&lt;MINOR&gt;" numbering scheme to indicate versions
  -of the protocol. The protocol versioning policy is intended to allow
  -the sender to indicate the format of a message and its capacity for
  -understanding further HTTP communication, rather than the features
  -obtained via that communication.
  -</BLOCKQUOTE>
  -Since Apache is an HTTP/1.1 server, it indicates so as part of its
  -response.  Many client authors mistakenly treat this part of the response
  -as an indication of the protocol that the response is in, and then refuse
  -to accept the response.
  -
  -<P>The first major indication of this problem was with AOL's proxy servers.
  -When Apache 1.2 went into beta it was the first wide-spread HTTP/1.1
  -server.  After some discussion, AOL fixed their proxies.  In
  -anticipation of similar problems, the <CODE>force-response-1.0</CODE>
  -environment variable was added to Apache.  When present Apache will
  -indicate "HTTP/1.0" in response to an HTTP/1.0 client,
  -but will not in any other way change the response.
  -
  -<P>The pre-1.1 Java Development Kit (JDK) that is used in many clients
  -(including Navigator 3.x and MSIE 3.x) exhibits this problem.  As do some
  -of the early pre-releases of the 1.1 JDK.  We think it is fixed in the
  -1.1 JDK release.  In any event the workaround:
  -<BLOCKQUOTE><CODE>
  -BrowserMatch Java/1.0 force-response-1.0 <BR>
  -BrowserMatch JDK/1.0 force-response-1.0 
  -</CODE></BLOCKQUOTE>
  -
  -<P>RealPlayer 4.0 from Progressive Networks also exhibits this problem.
  -However they have fixed it in version 4.01 of the player, but version
  -4.01 uses the same <CODE>User-Agent</CODE> as version 4.0.  The
  -workaround is still:
  -<BLOCKQUOTE><CODE>
  -BrowserMatch "RealPlayer 4.0" force-response-1.0
  -</CODE></BLOCKQUOTE>
  -
  -<H3><A NAME="msie4.0b2">Requests use HTTP/1.1 but responses must be
  -in HTTP/1.0</A></H3>
  -
  -<P>MSIE 4.0b2 has this problem.  Its Java VM makes requests in HTTP/1.1
  -format but the responses must be in HTTP/1.0 format (in particular, it
  -does not understand <EM>chunked</EM> responses).  The workaround
  -is to fool Apache into believing the request came in HTTP/1.0 format.
  -<BLOCKQUOTE><CODE>
  -BrowserMatch "MSIE 4\.0b2;" downgrade-1.0 force-response-1.0
  -</CODE></BLOCKQUOTE>
  -This workaround is available in 1.2.2, and in a
  -<A
  -HREF="http://www.apache.org/dist/httpd/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch"
  ->patch</A> against 1.2.1.
  -
  -<H3><A NAME="257th-byte">Boundary problems with header parsing</A></H3>
  -
  -<P>All versions of Navigator from 2.0 through 4.0b2 (and possibly later)
  -have a problem if the trailing CRLF of the response header starts at
  -offset 256, 257 or 258 of the response.  A BrowserMatch for this would
  -match on nearly every hit, so the workaround is enabled automatically
  -on all responses.  The workaround implemented detects when this condition would
  -occur in a response and adds extra padding to the header to push the
  -trailing CRLF past offset 258 of the response.
  -
  -<H3><A NAME="boundary-string">Multipart responses and Quoted Boundary
  -Strings</A></H3>
  -
  -<P>On multipart responses some clients will not accept quotes (")
  -around the boundary string.  The MIME standard recommends that
  -such quotes be used.  But the clients were probably written based
  -on one of the examples in RFC2068, which does not include quotes.
  -Apache does not include quotes on its boundary strings to workaround
  -this problem.
  -
  -<H3><A NAME="byterange-requests">Byterange requests</A></H3>
  -
  -<P>A byterange request is used when the client wishes to retrieve a
  -portion of an object, not necessarily the entire object.  There
  -was a very old draft which included these byteranges in the URL.
  -Old clients such as Navigator 2.0b1 and MSIE 3.0 for the MAC
  -exhibit this behaviour, and
  -it will appear in the servers' access logs as (failed) attempts to
  -retrieve a URL with a trailing ";xxx-yyy".  Apache does not attempt
  -to implement this at all.
  -
  -<P>A subsequent draft of this standard defines a header
  -<CODE>Request-Range</CODE>, and a response type
  -<CODE>multipart/x-byteranges</CODE>.  The HTTP/1.1 standard includes
  -this draft with a few fixes, and it defines the header
  -<CODE>Range</CODE> and type <CODE>multipart/byteranges</CODE>.
  -
  -<P>Navigator (versions 2 and 3) sends both <CODE>Range</CODE> and
  -<CODE>Request-Range</CODE> headers (with the same value), but does not
  -accept a <CODE>multipart/byteranges</CODE> response.  The response must
  -be <CODE>multipart/x-byteranges</CODE>.  As a workaround, if Apache
  -receives a <CODE>Request-Range</CODE> header it considers it "higher
  -priority" than a <CODE>Range</CODE> header and in response uses
  -<CODE>multipart/x-byteranges</CODE>.
  -
  -<P>The Adobe Acrobat Reader plugin makes extensive use of byteranges and
  -prior to version 3.01 supports only the <CODE>multipart/x-byterange</CODE>
  -response.  Unfortunately there is no clue that it is the plugin
  -making the request.  If the plugin is used with Navigator, the above
  -workaround works fine.  But if the plugin is used with MSIE 3 (on
  -Windows) the workaround won't work because MSIE 3 doesn't give the
  -<CODE>Range-Request</CODE> clue that Navigator does.  To workaround this,
  -Apache special cases "MSIE 3" in the <CODE>User-Agent</CODE> and serves
  -<CODE>multipart/x-byteranges</CODE>.  Note that the necessity for this
  -with MSIE 3 is actually due to the Acrobat plugin, not due to the browser.
  -
  -<P>Netscape Communicator appears to not issue the non-standard
  -<CODE>Request-Range</CODE> header.  When an Acrobat plugin prior to
  -version 3.01 is used with it, it will not properly understand byteranges.
  -The user must upgrade their Acrobat reader to 3.01.
  -
  -<H3><A NAME="cookie-merge"><CODE>Set-Cookie</CODE> header is
  -unmergeable</A></H3>
  -
  -<P>The HTTP specifications say that it is legal to merge headers with
  -duplicate names into one (separated by commas).  Some browsers
  -that support Cookies don't like merged headers and prefer that each
  -<CODE>Set-Cookie</CODE> header is sent separately.  When parsing the
  -headers returned by a CGI, Apache will explicitly avoid merging any
  -<CODE>Set-Cookie</CODE> headers.
  -
  -<H3><A NAME="gif89-expires"><CODE>Expires</CODE> headers and GIF89A
  -animations</A></H3>
  -
  -<P>Navigator versions 2 through 4 will erroneously re-request
  -GIF89A animations on each loop of the animation if the first
  -response included an <CODE>Expires</CODE> header.  This happens
  -regardless of how far in the future the expiry time is set.  There
  -is no workaround supplied with Apache, however there are hacks for <A
  -HREF="http://www.arctic.org/~dgaudet/patches/apache-1.2-gif89-expires-hack.patch">1.2</A>
  -and for <A
  -HREF="http://www.arctic.org/~dgaudet/patches/apache-1.3-gif89-expires-hack.patch">1.3</A>.
  -
  -<H3><A NAME="no-content-length"><CODE>POST</CODE> without
  -<CODE>Content-Length</CODE></A></H3>
  -
  -<P>In certain situations Navigator 3.01 through 3.03 appear to incorrectly
  -issue a POST without the request body.  There is no
  -known workaround.  It has been fixed in Navigator 3.04, Netscapes
  -provides some
  -<A HREF="http://help.netscape.com/kb/client/971014-42.html">information</A>.
  -There's also
  -<A HREF="http://www.arctic.org/~dgaudet/apache/no-content-length/">
  -some information</A> about the actual problem.
  -
  -<H3><A NAME="jdk-12-bugs">JDK 1.2 betas lose parts of responses.</A></H3>
  -
  -<P>The http client in the JDK1.2beta2 and beta3 will throw away the first part of
  -the response body when both the headers and the first part of the body are sent
  -in the same network packet AND keep-alive's are being used. If either condition
  -is not met then it works fine.
  -
  -<P>See also Bug-ID's 4124329 and 4125538 at the java developer connection.
  -
  -<P>If you are seeing this bug yourself, you can add the following BrowserMatch
  -directive to work around it:
  -
  -<BLOCKQUOTE><CODE>
  -BrowserMatch "Java1\.2beta[23]" nokeepalive
  -</CODE></BLOCKQUOTE>
  -
  -<P>We don't advocate this though since bending over backwards for beta software
  -is usually not a good idea; ideally it gets fixed, new betas or a final release
  -comes out, and no one uses the broken old software anymore.  In theory.
  -
  -<H3><A NAME="content-type-persistence"><CODE>Content-Type</CODE> change
  -is not noticed after reload</A></H3>
  -
  -<P>Navigator (all versions?) will cache the <CODE>content-type</CODE>
  -for an object "forever".  Using reload or shift-reload will not cause
  -Navigator to notice a <CODE>content-type</CODE> change.  The only
  -work-around is for the user to flush their caches (memory and disk).  By
  -way of an example, some folks may be using an old <CODE>mime.types</CODE>
  -file which does not map <CODE>.htm</CODE> to <CODE>text/html</CODE>,
  -in this case Apache will default to sending <CODE>text/plain</CODE>.
  -If the user requests the page and it is served as <CODE>text/plain</CODE>.
  -After the admin fixes the server, the user will have to flush their caches
  -before the object will be shown with the correct <CODE>text/html</CODE>
  -type.
  -
  -<h3><a name="msie-cookie-y2k">MSIE Cookie problem with expiry date in
  -the year 2000</a></h3>
  -
  -<p>MSIE versions 3.00 and 3.02 (without the Y2K patch) do not handle
  -cookie expiry dates in the year 2000 properly.  Years after 2000 and
  -before 2000 work fine.  This is fixed in IE4.01 service pack 1, and in
  -the Y2K patch for IE3.02.  Users should avoid using expiry dates in the
  -year 2000.
  -
  -<h3><a name="lynx-negotiate-trans">Lynx incorrectly asking for transparent
  -content negotiation</a></h3>
  -
  -<p>The Lynx browser versions 2.7 and 2.8 send a "negotiate: trans" header
  -in their requests, which is an indication the browser supports transparent
  -content negotiation (TCN).  However the browser does not support TCN.
  -As of version 1.3.4, Apache supports TCN, and this causes problems with
  -these versions of Lynx.  As a workaround future versions of Apache will
  -ignore this header when sent by the Lynx client.
  -
  -<h3><a name="ie40-vary">MSIE 4.0 mishandles Vary response header</a></h3>
  -
  -<p>MSIE 4.0 does not handle a Vary header properly.  The Vary header is
  -generated by mod_rewrite in apache 1.3.  The result is an error from MSIE
  -saying it cannot download the requested file.  There are more details
  -in <a href="http://bugs.apache.org/index/full/4118">PR#4118</a>.
  -</P>
  -<P>
  -A workaround is to add the following to your server's configuration
  -files:
  -</P>
  -<PRE>
  -    BrowserMatch "MSIE 4\.0" force-no-vary
  -</PRE>
  -<P>
  -(This workaround is only available with releases <STRONG>after</STRONG>
  -1.3.6 of the Apache Web server.)
  -</P>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache HTTP Server Project</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Known Problems in Clients</h1>
  +
  +    <p>Over time the Apache Group has discovered or been notified
  +    of problems with various clients which we have had to work
  +    around, or explain. This document describes these problems and
  +    the workarounds available. It's not arranged in any particular
  +    order. Some familiarity with the standards is assumed, but not
  +    necessary.</p>
  +
  +    <p>For brevity, <em>Navigator</em> will refer to Netscape's
  +    Navigator product (which in later versions was renamed
  +    "Communicator" and various other names), and <em>MSIE</em> will
  +    refer to Microsoft's Internet Explorer product. All trademarks
  +    and copyrights belong to their respective companies. We welcome
  +    input from the various client authors to correct
  +    inconsistencies in this paper, or to provide us with exact
  +    version numbers where things are broken/fixed.</p>
  +
  +    <p>For reference, <a
  +    href="ftp://ds.internic.net/rfc/rfc1945.txt">RFC1945</a>
  +    defines HTTP/1.0, and <a
  +    href="ftp://ds.internic.net/rfc/rfc2068.txt">RFC2068</a>
  +    defines HTTP/1.1. Apache as of version 1.2 is an HTTP/1.1
  +    server (with an optional HTTP/1.0 proxy).</p>
  +
  +    <p>Various of these workarounds are triggered by environment
  +    variables. The admin typically controls which are set, and for
  +    which clients, by using <a
  +    href="../mod/mod_browser.html">mod_browser</a>. Unless
  +    otherwise noted all of these workarounds exist in versions 1.2
  +    and later.</p>
  +
  +    <h3><a id="trailing-crlf" name="trailing-crlf">Trailing CRLF on
  +    POSTs</a></h3>
  +
  +    <p>This is a legacy issue. The CERN webserver required
  +    <code>POST</code> data to have an extra <code>CRLF</code>
  +    following it. Thus many clients send an extra <code>CRLF</code>
  +    that is not included in the <code>Content-Length</code> of the
  +    request. Apache works around this problem by eating any empty
  +    lines which appear before a request.</p>
  +
  +    <h3><a id="broken-keepalive" name="broken-keepalive">Broken
  +    keepalive</a></h3>
  +
  +    <p>Various clients have had broken implementations of
  +    <em>keepalive</em> (persistent connections). In particular the
  +    Windows versions of Navigator 2.0 get very confused when the
  +    server times out an idle connection. The workaround is present
  +    in the default config files:</p>
  +
  +    <blockquote>
  +      <code>BrowserMatch Mozilla/2 nokeepalive</code>
  +    </blockquote>
  +    Note that this matches some earlier versions of MSIE, which
  +    began the practice of calling themselves <em>Mozilla</em> in
  +    their user-agent strings just like Navigator. 
  +
  +    <p>MSIE 4.0b2, which claims to support HTTP/1.1, does not
  +    properly support keepalive when it is used on 301 or 302
  +    (redirect) responses. Unfortunately Apache's
  +    <code>nokeepalive</code> code prior to 1.2.2 would not work
  +    with HTTP/1.1 clients. You must apply <a
  +    href="http://www.apache.org/dist/httpd/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch">
  +    this patch</a> to version 1.2.1. Then add this to your
  +    config:</p>
  +
  +    <blockquote>
  +      <code>BrowserMatch "MSIE 4\.0b2;" nokeepalive</code>
  +    </blockquote>
  +
  +    <h3><a id="force-response-1.0"
  +    name="force-response-1.0">Incorrect interpretation of
  +    <code>HTTP/1.1</code> in response</a></h3>
  +
  +    <p>To quote from section 3.1 of RFC1945:</p>
  +
  +    <blockquote>
  +      HTTP uses a "&lt;MAJOR&gt;.&lt;MINOR&gt;" numbering scheme to
  +      indicate versions of the protocol. The protocol versioning
  +      policy is intended to allow the sender to indicate the format
  +      of a message and its capacity for understanding further HTTP
  +      communication, rather than the features obtained via that
  +      communication.
  +    </blockquote>
  +    Since Apache is an HTTP/1.1 server, it indicates so as part of
  +    its response. Many client authors mistakenly treat this part of
  +    the response as an indication of the protocol that the response
  +    is in, and then refuse to accept the response. 
  +
  +    <p>The first major indication of this problem was with AOL's
  +    proxy servers. When Apache 1.2 went into beta it was the first
  +    wide-spread HTTP/1.1 server. After some discussion, AOL fixed
  +    their proxies. In anticipation of similar problems, the
  +    <code>force-response-1.0</code> environment variable was added
  +    to Apache. When present Apache will indicate "HTTP/1.0" in
  +    response to an HTTP/1.0 client, but will not in any other way
  +    change the response.</p>
  +
  +    <p>The pre-1.1 Java Development Kit (JDK) that is used in many
  +    clients (including Navigator 3.x and MSIE 3.x) exhibits this
  +    problem. As do some of the early pre-releases of the 1.1 JDK.
  +    We think it is fixed in the 1.1 JDK release. In any event the
  +    workaround:</p>
  +
  +    <blockquote>
  +      <code>BrowserMatch Java/1.0 force-response-1.0<br />
  +       BrowserMatch JDK/1.0 force-response-1.0</code>
  +    </blockquote>
  +
  +    <p>RealPlayer 4.0 from Progressive Networks also exhibits this
  +    problem. However they have fixed it in version 4.01 of the
  +    player, but version 4.01 uses the same <code>User-Agent</code>
  +    as version 4.0. The workaround is still:</p>
  +
  +    <blockquote>
  +      <code>BrowserMatch "RealPlayer 4.0" force-response-1.0</code>
  +    </blockquote>
  +
  +    <h3><a id="msie4.0b2" name="msie4.0b2">Requests use HTTP/1.1
  +    but responses must be in HTTP/1.0</a></h3>
  +
  +    <p>MSIE 4.0b2 has this problem. Its Java VM makes requests in
  +    HTTP/1.1 format but the responses must be in HTTP/1.0 format
  +    (in particular, it does not understand <em>chunked</em>
  +    responses). The workaround is to fool Apache into believing the
  +    request came in HTTP/1.0 format.</p>
  +
  +    <blockquote>
  +      <code>BrowserMatch "MSIE 4\.0b2;" downgrade-1.0
  +      force-response-1.0</code>
  +    </blockquote>
  +    This workaround is available in 1.2.2, and in a <a
  +    href="http://www.apache.org/dist/httpd/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch">
  +    patch</a> against 1.2.1. 
  +
  +    <h3><a id="257th-byte" name="257th-byte">Boundary problems with
  +    header parsing</a></h3>
  +
  +    <p>All versions of Navigator from 2.0 through 4.0b2 (and
  +    possibly later) have a problem if the trailing CRLF of the
  +    response header starts at offset 256, 257 or 258 of the
  +    response. A BrowserMatch for this would match on nearly every
  +    hit, so the workaround is enabled automatically on all
  +    responses. The workaround implemented detects when this
  +    condition would occur in a response and adds extra padding to
  +    the header to push the trailing CRLF past offset 258 of the
  +    response.</p>
  +
  +    <h3><a id="boundary-string" name="boundary-string">Multipart
  +    responses and Quoted Boundary Strings</a></h3>
  +
  +    <p>On multipart responses some clients will not accept quotes
  +    (") around the boundary string. The MIME standard recommends
  +    that such quotes be used. But the clients were probably written
  +    based on one of the examples in RFC2068, which does not include
  +    quotes. Apache does not include quotes on its boundary strings
  +    to workaround this problem.</p>
  +
  +    <h3><a id="byterange-requests"
  +    name="byterange-requests">Byterange requests</a></h3>
  +
  +    <p>A byterange request is used when the client wishes to
  +    retrieve a portion of an object, not necessarily the entire
  +    object. There was a very old draft which included these
  +    byteranges in the URL. Old clients such as Navigator 2.0b1 and
  +    MSIE 3.0 for the MAC exhibit this behavior, and it will appear
  +    in the servers' access logs as (failed) attempts to retrieve a
  +    URL with a trailing ";xxx-yyy". Apache does not attempt to
  +    implement this at all.</p>
  +
  +    <p>A subsequent draft of this standard defines a header
  +    <code>Request-Range</code>, and a response type
  +    <code>multipart/x-byteranges</code>. The HTTP/1.1 standard
  +    includes this draft with a few fixes, and it defines the header
  +    <code>Range</code> and type
  +    <code>multipart/byteranges</code>.</p>
  +
  +    <p>Navigator (versions 2 and 3) sends both <code>Range</code>
  +    and <code>Request-Range</code> headers (with the same value),
  +    but does not accept a <code>multipart/byteranges</code>
  +    response. The response must be
  +    <code>multipart/x-byteranges</code>. As a workaround, if Apache
  +    receives a <code>Request-Range</code> header it considers it
  +    "higher priority" than a <code>Range</code> header and in
  +    response uses <code>multipart/x-byteranges</code>.</p>
  +
  +    <p>The Adobe Acrobat Reader plugin makes extensive use of
  +    byteranges and prior to version 3.01 supports only the
  +    <code>multipart/x-byterange</code> response. Unfortunately
  +    there is no clue that it is the plugin making the request. If
  +    the plugin is used with Navigator, the above workaround works
  +    fine. But if the plugin is used with MSIE 3 (on Windows) the
  +    workaround won't work because MSIE 3 doesn't give the
  +    <code>Range-Request</code> clue that Navigator does. To
  +    workaround this, Apache special cases "MSIE 3" in the
  +    <code>User-Agent</code> and serves
  +    <code>multipart/x-byteranges</code>. Note that the necessity
  +    for this with MSIE 3 is actually due to the Acrobat plugin, not
  +    due to the browser.</p>
  +
  +    <p>Netscape Communicator appears to not issue the non-standard
  +    <code>Request-Range</code> header. When an Acrobat plugin prior
  +    to version 3.01 is used with it, it will not properly
  +    understand byteranges. The user must upgrade their Acrobat
  +    reader to 3.01.</p>
  +
  +    <h3><a id="cookie-merge"
  +    name="cookie-merge"><code>Set-Cookie</code> header is
  +    unmergeable</a></h3>
  +
  +    <p>The HTTP specifications say that it is legal to merge
  +    headers with duplicate names into one (separated by commas).
  +    Some browsers that support Cookies don't like merged headers
  +    and prefer that each <code>Set-Cookie</code> header is sent
  +    separately. When parsing the headers returned by a CGI, Apache
  +    will explicitly avoid merging any <code>Set-Cookie</code>
  +    headers.</p>
  +
  +    <h3><a id="gif89-expires"
  +    name="gif89-expires"><code>Expires</code> headers and GIF89A
  +    animations</a></h3>
  +
  +    <p>Navigator versions 2 through 4 will erroneously re-request
  +    GIF89A animations on each loop of the animation if the first
  +    response included an <code>Expires</code> header. This happens
  +    regardless of how far in the future the expiry time is set.
  +    There is no workaround supplied with Apache, however there are
  +    hacks for <a
  +    href="http://www.arctic.org/~dgaudet/patches/apache-1.2-gif89-expires-hack.patch">
  +    1.2</a> and for <a
  +    href="http://www.arctic.org/~dgaudet/patches/apache-1.3-gif89-expires-hack.patch">
  +    1.3</a>.</p>
  +
  +    <h3><a id="no-content-length"
  +    name="no-content-length"><code>POST</code> without
  +    <code>Content-Length</code></a></h3>
  +
  +    <p>In certain situations Navigator 3.01 through 3.03 appear to
  +    incorrectly issue a POST without the request body. There is no
  +    known workaround. It has been fixed in Navigator 3.04,
  +    Netscapes provides some <a
  +    href="http://help.netscape.com/kb/client/971014-42.html">information</a>.
  +    There's also <a
  +    href="http://www.arctic.org/~dgaudet/apache/no-content-length/">
  +    some information</a> about the actual problem.</p>
  +
  +    <h3><a id="jdk-12-bugs" name="jdk-12-bugs">JDK 1.2 betas lose
  +    parts of responses.</a></h3>
  +
  +    <p>The http client in the JDK1.2beta2 and beta3 will throw away
  +    the first part of the response body when both the headers and
  +    the first part of the body are sent in the same network packet
  +    AND keep-alive's are being used. If either condition is not met
  +    then it works fine.</p>
  +
  +    <p>See also Bug-ID's 4124329 and 4125538 at the java developer
  +    connection.</p>
  +
  +    <p>If you are seeing this bug yourself, you can add the
  +    following BrowserMatch directive to work around it:</p>
  +
  +    <blockquote>
  +      <code>BrowserMatch "Java1\.2beta[23]" nokeepalive</code>
  +    </blockquote>
  +
  +    <p>We don't advocate this though since bending over backwards
  +    for beta software is usually not a good idea; ideally it gets
  +    fixed, new betas or a final release comes out, and no one uses
  +    the broken old software anymore. In theory.</p>
  +
  +    <h3><a id="content-type-persistence"
  +    name="content-type-persistence"><code>Content-Type</code>
  +    change is not noticed after reload</a></h3>
  +
  +    <p>Navigator (all versions?) will cache the
  +    <code>content-type</code> for an object "forever". Using reload
  +    or shift-reload will not cause Navigator to notice a
  +    <code>content-type</code> change. The only work-around is for
  +    the user to flush their caches (memory and disk). By way of an
  +    example, some folks may be using an old <code>mime.types</code>
  +    file which does not map <code>.htm</code> to
  +    <code>text/html</code>, in this case Apache will default to
  +    sending <code>text/plain</code>. If the user requests the page
  +    and it is served as <code>text/plain</code>. After the admin
  +    fixes the server, the user will have to flush their caches
  +    before the object will be shown with the correct
  +    <code>text/html</code> type.</p>
  +
  +    <h3><a id="msie-cookie-y2k" name="msie-cookie-y2k">MSIE Cookie
  +    problem with expiry date in the year 2000</a></h3>
  +
  +    <p>MSIE versions 3.00 and 3.02 (without the Y2K patch) do not
  +    handle cookie expiry dates in the year 2000 properly. Years
  +    after 2000 and before 2000 work fine. This is fixed in IE4.01
  +    service pack 1, and in the Y2K patch for IE3.02. Users should
  +    avoid using expiry dates in the year 2000.</p>
  +
  +    <h3><a id="lynx-negotiate-trans"
  +    name="lynx-negotiate-trans">Lynx incorrectly asking for
  +    transparent content negotiation</a></h3>
  +
  +    <p>The Lynx browser versions 2.7 and 2.8 send a "negotiate:
  +    trans" header in their requests, which is an indication the
  +    browser supports transparent content negotiation (TCN). However
  +    the browser does not support TCN. As of version 1.3.4, Apache
  +    supports TCN, and this causes problems with these versions of
  +    Lynx. As a workaround future versions of Apache will ignore
  +    this header when sent by the Lynx client.</p>
  +
  +    <h3><a id="ie40-vary" name="ie40-vary">MSIE 4.0 mishandles Vary
  +    response header</a></h3>
  +
  +    <p>MSIE 4.0 does not handle a Vary header properly. The Vary
  +    header is generated by mod_rewrite in apache 1.3. The result is
  +    an error from MSIE saying it cannot download the requested
  +    file. There are more details in <a
  +    href="http://bugs.apache.org/index/full/4118">PR#4118</a>.</p>
  +
  +    <p>A workaround is to add the following to your server's
  +    configuration files:</p>
  +<pre>
  +    BrowserMatch "MSIE 4\.0" force-no-vary
  +</pre>
   
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  +    <p>(This workaround is only available with releases
  +    <strong>after</strong> 1.3.6 of the Apache Web server.)</p>
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
   
  
  
  
  1.11      +89 -90    httpd-docs-1.3/htdocs/manual/misc/nopgp.html
  
  Index: nopgp.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/nopgp.html,v
  retrieving revision 1.10
  retrieving revision 1.11
  diff -u -r1.10 -r1.11
  --- nopgp.html	2000/05/29 16:20:03	1.10
  +++ nopgp.html	2001/10/08 01:26:54	1.11
  @@ -1,90 +1,89 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>Why We Took PEM Out of Apache</TITLE>
  -</HEAD>
  -
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Why We Took PEM Out of Apache</H1>
  -
  -On May 17th, 1995, we were asked by a representative of NCSA to remove
  -any copies of NCSA httpd prior to 1.4.1 from our web site.  They
  -were mandated by the NSA to inform us that redistribution of pre-1.4.1
  -code violated the same laws that make distributing Phill Zimmerman's
  -PGP package to other countries illegal.  There was <STRONG>no</STRONG>
  -encryption in NCSA's httpd, only hooks to publicly available libraries
  -of PEM code.  By the NSA's rules, even hooks to this type of
  -application is illegal.
  -
  -<P>
  -
  -Because Apache is based on NCSA code, and we had basically not touched
  -that part of the software, we were informed that Apache was also
  -illegal to distribute to foreign countries, and advised (not mandated)
  -by NCSA to remove it.  So, we removed both the copies of the NCSA
  -httpd we had, and all versions of Apache previous to 0.6.5.
  -
  -<P>
  -
  -The Apache members are strong advocates of the right to digital
  -privacy, so the decision to submit to the NSA and remove the code was
  -not an easy one.  Here are some elements in our rationale:
  -
  -<UL>
  -
  -<LI>The PEM code in httpd was not widely used.  No major site relied
  -upon its use, so its loss is not a blow to encryption and security on
  -the world wide web.  There are other efforts designed to give much
  -more flexible security - SSL and SHTTP - so this wasn't a function
  -whose absence would really be missed on a functional level.
  -
  -<LI>We didn't feel like being just a couple more martyrs in a fight
  -being fought very well by many other people.  Rather than have the
  -machine that supports the project confiscated or relocated to South
  -Africa, <EM>etc.</EM>, we think there are more efficient methods to address the
  -issue.
  -
  -</UL>
  -
  -It kind of sickens us that we had to do it, but so be it.
  -
  -<P>
  -
  -Patches that re-implement the PEM code may be available at a foreign
  -site soon.  If it does show up, we'll point to it - that can't be illegal!
  -
  -<P>
  -
  -Finally, here is a compendium of pointers to sites related to
  -encryption and export law.  We can't promise this list will be up to
  -date, so send us mail when you see a problem or want a link added.
  -Thanks.
  -
  -<UL>
  -<LI>
  -<A HREF="http://www.yahoo.com/Computers_and_Internet/Security_and_Encryption/"
  ->Yahoo - Science: Mathematics: Security and Encryption</A>
  -<LI><A HREF="http://www.eff.org/pub/Privacy/Crypto/">
  -EFF Crypto/Privacy/Security Archive</A>
  -<LI><A HREF="http://www.quadralay.com/www/Crypt/Crypt.html">
  -Crypto page at Quadralay</A>
  -<LI><A HREF="ftp://ftp.cygnus.com/pub/export/export.html">
  -Cryptography Export Control Archives (Cygnus)</A>
  -<LI><A HREF="http://www.law.indiana.edu/law/iclu.html">
  -ICLU - Your Rights in Cyberspace</A>
  -</UL>
  -
  -<A HREF="http://www.behlendorf.com/~brian/">Brian</A>,
  -<A HREF="mailto:brian@hyperreal.com">brian@hyperreal.com</A>
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  +
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Why We Took PEM Out of Apache</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Why We Took PEM Out of Apache</h1>
  +    On May 17th, 1995, we were asked by a representative of NCSA to
  +    remove any copies of NCSA httpd prior to 1.4.1 from our web
  +    site. They were mandated by the NSA to inform us that
  +    redistribution of pre-1.4.1 code violated the same laws that
  +    make distributing Phill Zimmerman's PGP package to other
  +    countries illegal. There was <strong>no</strong> encryption in
  +    NCSA's httpd, only hooks to publicly available libraries of PEM
  +    code. By the NSA's rules, even hooks to this type of
  +    application is illegal. 
  +
  +    <p>Because Apache is based on NCSA code, and we had basically
  +    not touched that part of the software, we were informed that
  +    Apache was also illegal to distribute to foreign countries, and
  +    advised (not mandated) by NCSA to remove it. So, we removed
  +    both the copies of the NCSA httpd we had, and all versions of
  +    Apache previous to 0.6.5.</p>
  +
  +    <p>The Apache members are strong advocates of the right to
  +    digital privacy, so the decision to submit to the NSA and
  +    remove the code was not an easy one. Here are some elements in
  +    our rationale:</p>
  +
  +    <ul>
  +      <li>The PEM code in httpd was not widely used. No major site
  +      relied upon its use, so its loss is not a blow to encryption
  +      and security on the world wide web. There are other efforts
  +      designed to give much more flexible security - SSL and SHTTP
  +      - so this wasn't a function whose absence would really be
  +      missed on a functional level.</li>
  +
  +      <li>We didn't feel like being just a couple more martyrs in a
  +      fight being fought very well by many other people. Rather
  +      than have the machine that supports the project confiscated
  +      or relocated to South Africa, <em>etc.</em>, we think there
  +      are more efficient methods to address the issue.</li>
  +    </ul>
  +    It kind of sickens us that we had to do it, but so be it. 
  +
  +    <p>Patches that re-implement the PEM code may be available at a
  +    foreign site soon. If it does show up, we'll point to it - that
  +    can't be illegal!</p>
  +
  +    <p>Finally, here is a compendium of pointers to sites related
  +    to encryption and export law. We can't promise this list will
  +    be up to date, so send us mail when you see a problem or want a
  +    link added. Thanks.</p>
  +
  +    <ul>
  +      <li><a
  +      href="http://www.yahoo.com/Computers_and_Internet/Security_and_Encryption/">
  +      Yahoo - Science: Mathematics: Security and
  +      Encryption</a></li>
  +
  +      <li><a href="http://www.eff.org/pub/Privacy/Crypto/">EFF
  +      Crypto/Privacy/Security Archive</a></li>
  +
  +      <li><a
  +      href="http://www.quadralay.com/www/Crypt/Crypt.html">Crypto
  +      page at Quadralay</a></li>
  +
  +      <li><a
  +      href="ftp://ftp.cygnus.com/pub/export/export.html">Cryptography
  +      Export Control Archives (Cygnus)</a></li>
  +
  +      <li><a href="http://www.law.indiana.edu/law/iclu.html">ICLU -
  +      Your Rights in Cyberspace</a></li>
  +    </ul>
  +    <a href="http://www.behlendorf.com/~brian/">Brian</a>, <a
  +    href="mailto:brian@hyperreal.com">brian@hyperreal.com</a> 
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
  +
  
  
  
  1.17      +241 -281  httpd-docs-1.3/htdocs/manual/misc/perf-bsd44.html
  
  Index: perf-bsd44.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/perf-bsd44.html,v
  retrieving revision 1.16
  retrieving revision 1.17
  diff -u -r1.16 -r1.17
  --- perf-bsd44.html	2001/07/13 07:37:35	1.16
  +++ perf-bsd44.html	2001/10/08 01:26:54	1.17
  @@ -1,114 +1,96 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>Running a High-Performance Web Server for BSD</TITLE>
  -</HEAD>
  -
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<A NAME="initial">
  -<!--#include virtual="header.html" -->
  -</A>
  -<H1 ALIGN="CENTER">Running a High-Performance Web Server for BSD</H1>
  -
  -Like other OS's, the listen queue is often the <STRONG>first limit
  -hit</STRONG>.  The
  -following are comments from "Aaron Gifford &lt;agifford@InfoWest.COM&gt;"
  -on how to fix this on BSDI 1.x, 2.x,  and FreeBSD 2.0 (and earlier):
  -
  -<P>
  -
  -Edit the following two files:
  -<BLOCKQUOTE><CODE>  /usr/include/sys/socket.h <BR>
  -  /usr/src/sys/sys/socket.h </CODE></BLOCKQUOTE>
  -In each file, look for the following:
  -<PRE>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  +
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Running a High-Performance Web Server for BSD</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <a id="initial" name="initial">
  +    <!--#include virtual="header.html" -->
  +    </a> 
  +
  +    <h1 align="CENTER">Running a High-Performance Web Server for
  +    BSD</h1>
  +    Like other OS's, the listen queue is often the <strong>first
  +    limit hit</strong>. The following are comments from "Aaron
  +    Gifford &lt;agifford@InfoWest.COM&gt;" on how to fix this on
  +    BSDI 1.x, 2.x, and FreeBSD 2.0 (and earlier): 
  +
  +    <p>Edit the following two files:</p>
  +
  +    <blockquote>
  +      <code>/usr/include/sys/socket.h<br />
  +       /usr/src/sys/sys/socket.h</code>
  +    </blockquote>
  +    In each file, look for the following: 
  +<pre>
       /*
        * Maximum queue length specifiable by listen.
        */
       #define SOMAXCONN       5
  -</PRE>
  -
  -Just change the "5" to whatever appears to work.  I bumped the two
  -machines I was having problems with up to 32 and haven't noticed the
  -problem since.
  -
  -<P>
  -
  -After the edit, recompile the kernel and recompile the Apache server
  -then reboot.
  -
  -<P>
  -
  -FreeBSD 2.1 seems to be perfectly happy, with SOMAXCONN
  -set to 32 already.
  -
  -<P>
  -
  -<A NAME="detail">
  -<STRONG>Addendum for <EM>very</EM> heavily loaded BSD servers</STRONG><BR>
  -</A>
  -from Chuck Murcko &lt;chuck@telebase.com&gt;
  -
  -<P>
  -
  -If you're running a really busy BSD Apache server, the following are useful
  -things to do if the system is acting sluggish:<P>
  -
  -<UL>
  -
  -<LI> Run vmstat to check memory usage, page/swap rates, <EM>etc.</EM>
  -
  -<LI> Run netstat -m to check mbuf usage
  -
  -<LI> Run fstat to check file descriptor usage
  -
  -</UL>
  -
  -These utilities give you an idea what you'll need to tune in your kernel,
  -and whether it'll help to buy more RAM.
  -
  -Here are some BSD kernel config parameters (actually BSDI, but pertinent to
  -FreeBSD and other 4.4-lite derivatives) from a system getting heavy usage.
  -The tools mentioned above were used, and the system memory was increased to
  -48 MB before these tuneups. Other system parameters remained unchanged.
  -
  -<P>
  -
  -<PRE>
  +</pre>
  +    Just change the "5" to whatever appears to work. I bumped the
  +    two machines I was having problems with up to 32 and haven't
  +    noticed the problem since. 
  +
  +    <p>After the edit, recompile the kernel and recompile the
  +    Apache server then reboot.</p>
  +
  +    <p>FreeBSD 2.1 seems to be perfectly happy, with SOMAXCONN set
  +    to 32 already.</p>
  +
  +    <p><a id="detail" name="detail"><strong>Addendum for
  +    <em>very</em> heavily loaded BSD servers</strong><br />
  +    </a> from Chuck Murcko &lt;chuck@telebase.com&gt;</p>
  +
  +    <p>If you're running a really busy BSD Apache server, the
  +    following are useful things to do if the system is acting
  +    sluggish:</p>
  +
  +    <ul>
  +      <li>Run vmstat to check memory usage, page/swap rates,
  +      <em>etc.</em></li>
  +
  +      <li>Run netstat -m to check mbuf usage</li>
  +
  +      <li>Run fstat to check file descriptor usage</li>
  +    </ul>
  +    These utilities give you an idea what you'll need to tune in
  +    your kernel, and whether it'll help to buy more RAM. Here are
  +    some BSD kernel config parameters (actually BSDI, but pertinent
  +    to FreeBSD and other 4.4-lite derivatives) from a system
  +    getting heavy usage. The tools mentioned above were used, and
  +    the system memory was increased to 48 MB before these tuneups.
  +    Other system parameters remained unchanged. 
  +<pre>
   maxusers        256
  -</PRE>
  -
  -Maxusers drives a <EM>lot</EM> of other kernel parameters:
  -
  -<UL>
  -
  -<LI> Maximum # of processes
  -
  -<LI> Maximum # of processes per user
  +</pre>
  +    Maxusers drives a <em>lot</em> of other kernel parameters: 
   
  -<LI> System wide open files limit
  +    <ul>
  +      <li>Maximum # of processes</li>
   
  -<LI> Per-process open files limit
  +      <li>Maximum # of processes per user</li>
   
  -<LI> Maximum # of mbuf clusters
  +      <li>System wide open files limit</li>
   
  -<LI> Proc/pgrp hash table size
  +      <li>Per-process open files limit</li>
   
  -</UL>
  +      <li>Maximum # of mbuf clusters</li>
   
  -The actual formulae for these derived parameters are in
  -<EM>/usr/src/sys/conf/param.c</EM>.
  -These calculated parameters can also be overridden (in part) by specifying
  -your own values in the kernel configuration file:
  -
  -<PRE>
  +      <li>Proc/pgrp hash table size</li>
  +    </ul>
  +    The actual formulae for these derived parameters are in
  +    <em>/usr/src/sys/conf/param.c</em>. These calculated parameters
  +    can also be overridden (in part) by specifying your own values
  +    in the kernel configuration file: 
  +<pre>
   # Network options. NMBCLUSTERS defines the number of mbuf clusters and
   # defaults to 256. This machine is a server that handles lots of traffic,
   # so we crank that value.
  @@ -119,24 +101,21 @@
   #
   options         CHILD_MAX=512           # maximum number of child processes
   options         OPEN_MAX=512            # maximum fds (breaks RPC svcs)
  -</PRE>
  -
  -<P>
  -
  -In many cases, NMBCLUSTERS must be set much larger than would appear
  -necessary at first glance. The reason for this is that if the browser
  -disconnects in mid-transfer, the socket fd associated with that particular
  -connection ends up in the TIME_WAIT state for several minutes, during
  -which time its mbufs are not yet freed. Another reason is that, on server
  -timeouts, some connections end up in FIN_WAIT_2 state forever, because
  -this state doesn't time out on the server, and the browser never sent
  -a final FIN.  For more details see the
  -<A HREF="fin_wait_2.html">FIN_WAIT_2</A> page.
  +</pre>
   
  -<P>
  +    <p>In many cases, NMBCLUSTERS must be set much larger than
  +    would appear necessary at first glance. The reason for this is
  +    that if the browser disconnects in mid-transfer, the socket fd
  +    associated with that particular connection ends up in the
  +    TIME_WAIT state for several minutes, during which time its
  +    mbufs are not yet freed. Another reason is that, on server
  +    timeouts, some connections end up in FIN_WAIT_2 state forever,
  +    because this state doesn't time out on the server, and the
  +    browser never sent a final FIN. For more details see the <a
  +    href="fin_wait_2.html">FIN_WAIT_2</a> page.</p>
   
  -Some more info on mbuf clusters (from sys/mbuf.h):
  -<PRE>
  +    <p>Some more info on mbuf clusters (from sys/mbuf.h):</p>
  +<pre>
   /*
    * Mbufs are of a single size, MSIZE (machine/machparam.h), which
    * includes overhead.  An mbuf may add a single "mbuf cluster" of size
  @@ -144,178 +123,159 @@
    * and is used instead of the internal data area; this is done when
    * at least MINCLSIZE of data must be stored.
    */
  -</PRE>
  +</pre>
   
  -<P>
  -
  -CHILD_MAX and OPEN_MAX are set to allow up to 512 child processes (different
  -than the maximum value for processes per user ID) and file descriptors.
  -These values may change for your particular configuration (a higher OPEN_MAX
  -value if you've got modules or CGI scripts opening lots of connections or
  -files). If you've got a lot of other activity besides httpd on the same
  -machine, you'll have to set NPROC higher still. In this example, the NPROC
  -value derived from maxusers proved sufficient for our load.
  -
  -<P>
  -
  -To increase the size of the <CODE>listen()</CODE> queue, you need to
  -adjust the value of SOMAXCONN. SOMAXCONN is not derived from maxusers,
  -so you'll always need to increase that yourself. We use a value guaranteed
  -to be larger than Apache's default for the listen() of 128, currently.
  -The actual value for SOMAXCONN is set in <CODE>sys/socket.h</CODE>.
  -The best way to adjust this parameter is run-time, rather than changing
  -it in this header file and thus hardcoding a value in the kernel and
  -elsewhere.  To do this, edit <CODE>/etc/rc.local</CODE> and add the
  -following line:
  -<PRE>
  +    <p>CHILD_MAX and OPEN_MAX are set to allow up to 512 child
  +    processes (different than the maximum value for processes per
  +    user ID) and file descriptors. These values may change for your
  +    particular configuration (a higher OPEN_MAX value if you've got
  +    modules or CGI scripts opening lots of connections or files).
  +    If you've got a lot of other activity besides httpd on the same
  +    machine, you'll have to set NPROC higher still. In this
  +    example, the NPROC value derived from maxusers proved
  +    sufficient for our load.</p>
  +
  +    <p>To increase the size of the <code>listen()</code> queue, you
  +    need to adjust the value of SOMAXCONN. SOMAXCONN is not derived
  +    from maxusers, so you'll always need to increase that yourself.
  +    We use a value guaranteed to be larger than Apache's default
  +    for the listen() of 128, currently. The actual value for
  +    SOMAXCONN is set in <code>sys/socket.h</code>. The best way to
  +    adjust this parameter is run-time, rather than changing it in
  +    this header file and thus hardcoding a value in the kernel and
  +    elsewhere. To do this, edit <code>/etc/rc.local</code> and add
  +    the following line:</p>
  +<pre>
       /usr/sbin/sysctl -w kern.somaxconn=256
  -</PRE>
  -
  -<P>
  -
  -We used <CODE>256</CODE> but you can tune it for your own setup. In
  -many cases, however, even the default value of <CODE>128</CODE> (for
  -later versions of FreeBSD) is OK.
  -
  -<P>
  -
  -<STRONG>Caveats</STRONG>
  -
  -<P>
  -
  -Be aware that your system may not boot with a kernel that is configured
  -to use more resources than you have available system RAM.
  -<STRONG>ALWAYS</STRONG>
  -have a known bootable kernel available when tuning your system this way,
  -and use the system tools beforehand to learn if you need to buy more
  -memory before tuning.
  -
  -<P>
  +</pre>
   
  -RPC services will fail when the value of OPEN_MAX is larger than 256.
  -This is a function of the original implementations of the RPC library,
  -which used a byte value for holding file descriptors. BSDI has partially
  -addressed this limit in its 2.1 release, but a real fix may well await
  -the redesign of RPC itself.
  -
  -<P>
  -
  -Finally, there's the hard limit of child processes configured in Apache.
  -
  -<P>
  -
  -For versions of Apache later than 1.0.5 you'll need to change the
  -definition for <STRONG>HARD_SERVER_LIMIT</STRONG> in <EM>httpd.h</EM> and
  -recompile if you need to run more than the default 150 instances of httpd.
  -
  -<P>
  -
  -From conf/httpd.conf-dist:
  -
  -<PRE>
  -# Limit on total number of servers running, <EM>i.e.</EM>, limit on the number
  +    <p>We used <code>256</code> but you can tune it for your own
  +    setup. In many cases, however, even the default value of
  +    <code>128</code> (for later versions of FreeBSD) is OK.</p>
  +
  +    <p><strong>Caveats</strong></p>
  +
  +    <p>Be aware that your system may not boot with a kernel that is
  +    configured to use more resources than you have available system
  +    RAM. <strong>ALWAYS</strong> have a known bootable kernel
  +    available when tuning your system this way, and use the system
  +    tools beforehand to learn if you need to buy more memory before
  +    tuning.</p>
  +
  +    <p>RPC services will fail when the value of OPEN_MAX is larger
  +    than 256. This is a function of the original implementations of
  +    the RPC library, which used a byte value for holding file
  +    descriptors. BSDI has partially addressed this limit in its 2.1
  +    release, but a real fix may well await the redesign of RPC
  +    itself.</p>
  +
  +    <p>Finally, there's the hard limit of child processes
  +    configured in Apache.</p>
  +
  +    <p>For versions of Apache later than 1.0.5 you'll need to
  +    change the definition for <strong>HARD_SERVER_LIMIT</strong> in
  +    <em>httpd.h</em> and recompile if you need to run more than the
  +    default 150 instances of httpd.</p>
  +
  +    <p>From conf/httpd.conf-dist:</p>
  +<pre>
  +# Limit on total number of servers running, <em>i.e.</em>, limit on the number
   # of clients who can simultaneously connect --- if this limit is ever
   # reached, clients will be LOCKED OUT, so it should NOT BE SET TOO LOW.
   # It is intended mainly as a brake to keep a runaway server from taking
   # Unix with it as it spirals down...
   
   MaxClients 150
  -</PRE>
  -
  -Know what you're doing if you bump this value up, and make sure you've
  -done your system monitoring, RAM expansion, and kernel tuning beforehand.
  -Then you're ready to service some serious hits!
  -
  -<P>
  -
  -Thanks to <EM>Tony Sanders</EM> and <EM>Chris Torek</EM> at BSDI for their
  -helpful suggestions and information.
  -
  -<P>
  -
  -"M. Teterin" &lt;mi@ALDAN.ziplink.net&gt; writes:<P>
  -<BLOCKQUOTE>It really does help if your kernel and frequently used utilities
  -are fully optimized. Rebuilding the FreeBSD kernel on an AMD-133
  -(486-class CPU) web-server with<BR>
  -<CODE>    -m486 -fexpensive-optimizations -fomit-frame-pointer -O2</CODE><BR>
  -helped reduce the number of "unable" errors, because the CPU was
  -often maxed out.</BLOCKQUOTE>
  -<P>
  -
  -<H2><A NAME="accf">Accept filtering on FreeBSD</A></H2>
  -
  -<P>
  -
  -Versions of FreeBSD from August 2000 onwards include a feature called
  -&quot;accept filters&quot; which delay the return from accept() until
  -a condition has been met, e.g. an HTTP request has arrived. This
  -postpones the requirement for a child process to handle the new
  -connection which therefore increases the number of connections that a
  -given number of child processes can handle. It also allows a child
  -process to accomplish more immediately after accept() returns (because
  -the request is already available to be read) so there is less context
  -switching.
  -
  -<P>
  -
  -There are two filters in FreeBSD at the time of writing:
  -&quot;dataready&quot; and &quot;httpready&quot;. The former just waits
  -for the first packet to arrive from the client; the latter waits for
  -the end of the HTTP headers. Unfortunately the &quot;httpready&quot;
  -filter breaks support for HTTP/0.9 (which doesn't have headers) so
  -Apache doesn't use it, but the &quot;dataready&quot; filter gives the
  -same benefit in the majority of cases so Apache attempts to use that
  -instead.
  -
  -<P>
  -
  -Accept filters provide the most benefit on servers that are already so
  -busy that they are configured with &quot;<CODE>KeepAlive Off</CODE>&quot;.
  -<A HREF="../keepalive.html">HTTP KeepAlive (aka persistent connections)</A>
  -avoids the cost of setting up a new connection for every request, but
  -connections that are being kept alive use up one of the available
  -child processes. Since there is a limited number of child processes
  -this can significantly reduce the capacity of the server. The viewers
  -of a web site will still get a lot of the benefit of persistent
  -connections even with a very small <CODE>KeepAliveTimeout</CODE> so
  -you should try reducing it before turning it off altogether.
  -
  -<P>
  -
  -To enable accept filtering, you must either load the appropriate
  -accept filter module,
  -e.g. with the command <CODE>kldload accf_data</CODE>,
  -or compile a kernel with <CODE>options ACCEPT_FILTER_DATA</CODE>.
  -Apache will then enable filtering when it is restarted.
  -<P>
  -Accept filters ar compiled in if the symbol <code>SO_ACCEPTFILTER</code>
  -is defined on the machine apache is build.
  -<p>
  -Additionally there is a directive <a href="../mod/core.html#acceptfilter">AcceptFilter</a> to switch the filters on or off. The default is on; except
  -when apache is compiled with <code>-D AP_ACCEPTFILTER_ON</code>.
  -<P>
  -
  -If you are more concerned about performance than compatibility with
  -absurdly obsolete HTTP/0.9 user agents then you can recompile Apache
  -to use the &quot;httpready&quot; filter. This may be particularly
  -helpful if your web site uses really big cookies, for example.
  -If you are using <CODE>src/Configure</CODE> then add
  -<CODE>-DACCEPT_FILTER_NAME=\&quot;httpready\&quot;</CODE> to the
  -<CODE>EXTRA_CFLAGS</CODE> line in the <CODE>src/Configuration</CODE>
  -file.
  -If you are using APACI (aka <CODE>./configure</CODE>) then use the command
  -<CODE>CFLAGS=-DACCEPT_FILTER_NAME=\'\&quot;httpready\&quot;\' ./configure</CODE>
  -(with all the funky backslashed quotes).
  -
  -<P>
  -
  -<HR>
  -
  -<H3>More welcome!</H3>
  -
  -If you have tips to contribute, send mail to
  -<A HREF="mailto:apache@apache.org">apache@apache.org</A>
  -
  -<!--#include virtual="footer.html" -->
  -</BODY></HTML>
  +</pre>
  +    Know what you're doing if you bump this value up, and make sure
  +    you've done your system monitoring, RAM expansion, and kernel
  +    tuning beforehand. Then you're ready to service some serious
  +    hits! 
  +
  +    <p>Thanks to <em>Tony Sanders</em> and <em>Chris Torek</em> at
  +    BSDI for their helpful suggestions and information.</p>
  +
  +    <p>"M. Teterin" &lt;mi@ALDAN.ziplink.net&gt; writes:</p>
  +
  +    <blockquote>
  +      It really does help if your kernel and frequently used
  +      utilities are fully optimized. Rebuilding the FreeBSD kernel
  +      on an AMD-133 (486-class CPU) web-server with<br />
  +       <code>-m486 -fexpensive-optimizations -fomit-frame-pointer
  +      -O2</code><br />
  +       helped reduce the number of "unable" errors, because the CPU
  +      was often maxed out.
  +    </blockquote>
  +
  +    <h2><a id="accf" name="accf">Accept filtering on
  +    FreeBSD</a></h2>
  +
  +    <p>Versions of FreeBSD from August 2000 onwards include a
  +    feature called "accept filters" which delay the return from
  +    accept() until a condition has been met, e.g. an HTTP request
  +    has arrived. This postpones the requirement for a child process
  +    to handle the new connection which therefore increases the
  +    number of connections that a given number of child processes
  +    can handle. It also allows a child process to accomplish more
  +    immediately after accept() returns (because the request is
  +    already available to be read) so there is less context
  +    switching.</p>
  +
  +    <p>There are two filters in FreeBSD at the time of writing:
  +    "dataready" and "httpready". The former just waits for the
  +    first packet to arrive from the client; the latter waits for
  +    the end of the HTTP headers. Unfortunately the "httpready"
  +    filter breaks support for HTTP/0.9 (which doesn't have headers)
  +    so Apache doesn't use it, but the "dataready" filter gives the
  +    same benefit in the majority of cases so Apache attempts to use
  +    that instead.</p>
  +
  +    <p>Accept filters provide the most benefit on servers that are
  +    already so busy that they are configured with "<code>KeepAlive
  +    Off</code>". <a href="../keepalive.html">HTTP KeepAlive (aka
  +    persistent connections)</a> avoids the cost of setting up a new
  +    connection for every request, but connections that are being
  +    kept alive use up one of the available child processes. Since
  +    there is a limited number of child processes this can
  +    significantly reduce the capacity of the server. The viewers of
  +    a web site will still get a lot of the benefit of persistent
  +    connections even with a very small
  +    <code>KeepAliveTimeout</code> so you should try reducing it
  +    before turning it off altogether.</p>
  +
  +    <p>To enable accept filtering, you must either load the
  +    appropriate accept filter module, e.g. with the command
  +    <code>kldload accf_data</code>, or compile a kernel with
  +    <code>options ACCEPT_FILTER_DATA</code>. Apache will then
  +    enable filtering when it is restarted.</p>
  +
  +    <p>Accept filters ar compiled in if the symbol
  +    <code>SO_ACCEPTFILTER</code> is defined on the machine apache
  +    is build.</p>
  +
  +    <p>Additionally there is a directive <a
  +    href="../mod/core.html#acceptfilter">AcceptFilter</a> to switch
  +    the filters on or off. The default is on; except when apache is
  +    compiled with <code>-D AP_ACCEPTFILTER_ON</code>.</p>
  +
  +    <p>If you are more concerned about performance than
  +    compatibility with absurdly obsolete HTTP/0.9 user agents then
  +    you can recompile Apache to use the "httpready" filter. This
  +    may be particularly helpful if your web site uses really big
  +    cookies, for example. If you are using
  +    <code>src/Configure</code> then add
  +    <code>-DACCEPT_FILTER_NAME=\"httpready\"</code> to the
  +    <code>EXTRA_CFLAGS</code> line in the
  +    <code>src/Configuration</code> file. If you are using APACI
  +    (aka <code>./configure</code>) then use the command
  +    <code>CFLAGS=-DACCEPT_FILTER_NAME=\'\"httpready\"\'
  +    ./configure</code> (with all the funky backslashed quotes).</p>
  +    <hr />
  +
  +    <h3>More welcome!</h3>
  +    If you have tips to contribute, send mail to <a
  +    href="mailto:apache@apache.org">apache@apache.org</a> 
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
   
  
  
  
  1.11      +64 -60    httpd-docs-1.3/htdocs/manual/misc/perf-dec.html
  
  Index: perf-dec.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/perf-dec.html,v
  retrieving revision 1.10
  retrieving revision 1.11
  diff -u -r1.10 -r1.11
  --- perf-dec.html	2000/12/03 03:28:37	1.10
  +++ perf-dec.html	2001/10/08 01:26:54	1.11
  @@ -1,55 +1,57 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>Performance Tuning Tips for Digital Unix</TITLE>
  -</HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Performance Tuning Tips for Digital Unix</H1>
  -
  -Below is a set of newsgroup posts made by an engineer from DEC in
  -response to queries about how to modify DEC's Digital Unix OS for more
  -heavily loaded web sites.  Copied with permission.
  -
  -<HR>
  -
  -<H2>Update</H2>
  -From: Jeffrey Mogul &lt;mogul@pa.dec.com&gt;<BR>
  -Date: Fri, 28 Jun 96 16:07:56 MDT<BR>
  -
  -<OL>
  -<LI> The advice given in the README file regarding the
  -        "tcbhashsize" variable is incorrect.  The largest value
  -        this should be set to is 1024.  Setting it any higher
  -        will have the perverse result of disabling the hashing
  -        mechanism.
  -
  -<LI>Patch ID OSF350-146 has been superseded by
  -<BLOCKQUOTE>
  -                Patch ID OSF350-195 for V3.2C<BR>
  -                Patch ID OSF360-350195 for V3.2D
  -</BLOCKQUOTE>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  +
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Performance Tuning Tips for Digital Unix</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Performance Tuning Tips for Digital
  +    Unix</h1>
  +    Below is a set of newsgroup posts made by an engineer from DEC
  +    in response to queries about how to modify DEC's Digital Unix
  +    OS for more heavily loaded web sites. Copied with permission. 
  +    <hr />
  +
  +    <h2>Update</h2>
  +    From: Jeffrey Mogul &lt;mogul@pa.dec.com&gt;<br />
  +     Date: Fri, 28 Jun 96 16:07:56 MDT<br />
  +     
  +
  +    <ol>
  +      <li>The advice given in the README file regarding the
  +      "tcbhashsize" variable is incorrect. The largest value this
  +      should be set to is 1024. Setting it any higher will have the
  +      perverse result of disabling the hashing mechanism.</li>
  +
  +      <li>
  +        Patch ID OSF350-146 has been superseded by 
  +
  +        <blockquote>
  +          Patch ID OSF350-195 for V3.2C<br />
  +           Patch ID OSF360-350195 for V3.2D
  +        </blockquote>
           Patch IDs for V3.2E and V3.2F should be available soon.
           There is no known reason why the Patch ID OSF360-350195
  -        won't work on these releases, but such use is not officially
  -        supported by Digital.  This patch kit will not be needed for
  -        V3.2G when it is released.
  -</OL>
  -<HR>
  -
  -
  -<PRE>
  +        won't work on these releases, but such use is not
  +        officially supported by Digital. This patch kit will not be
  +        needed for V3.2G when it is released.
  +      </li>
  +    </ol>
  +    <hr />
  +<pre>
   From           mogul@pa.dec.com (Jeffrey Mogul)
   Organization   DEC Western Research
   Date           30 May 1996 00:50:25 GMT
  -Newsgroups     <A HREF="news:comp.unix.osf.osf1">comp.unix.osf.osf1</A>
  +Newsgroups     <a
  +href="news:comp.unix.osf.osf1">comp.unix.osf.osf1</a>
   Message-ID     &lt;4oirch$bc8@usenet.pa.dec.com&gt;
   Subject        Re: Web Site Performance
   References     1
  @@ -63,10 +65,10 @@
   &gt;runing DEC UNIX 3.2C, which run DEC's seal firewall and behind
   &gt;that Alpha 1000 and 2100 webservers.
   
  -Our experience (running such Web servers as <A
  - HREF="http://altavista.digital.com">altavista.digital.com</A>
  -and <A HREF="http://www.digital.com"
  -    >www.digital.com</A>) is that there is one important kernel tuning
  +Our experience (running such Web servers as <a
  +href="http://altavista.digital.com">altavista.digital.com</a>
  +and <a
  +href="http://www.digital.com">www.digital.com</a>) is that there is one important kernel tuning
   knob to adjust in order to get good performance on V3.2C.  You
   need to patch the kernel global variable "somaxconn" (use dbx -k
   to do this) from its default value of 8 to something much larger.
  @@ -102,7 +104,7 @@
   We have some Webstone performance results available at
           http://www.digital.com/info/alphaserver/news/webff.html
   
  -<EM>[The document referenced above is no longer at that URL -- Ed.]</EM>
  +<em>[The document referenced above is no longer at that URL -- Ed.]</em>
   
   I'm not sure if these were done using V4.0 or an earlier version
   of Digital UNIX, although I suspect they were done using a test
  @@ -115,7 +117,8 @@
   From           mogul@pa.dec.com (Jeffrey Mogul)
   Organization   DEC Western Research
   Date           31 May 1996 21:01:01 GMT
  -Newsgroups     <A HREF="news:comp.unix.osf.osf1">comp.unix.osf.osf1</A>
  +Newsgroups     <a
  +href="news:comp.unix.osf.osf1">comp.unix.osf.osf1</a>
   Message-ID     &lt;4onmmd$mmd@usenet.pa.dec.com&gt;
   Subject        Digital UNIX V3.2C Internet tuning patch info
   
  @@ -139,8 +142,8 @@
   file might be useful to people running V4.0 systems.
   
   This patch kit does not appear to be available (yet?) from
  -        <A HREF="http://www.service.digital.com/html/patch_service.html"
  -        >http://www.service.digital.com/html/patch_service.html</A>
  +        <a
  +href="http://www.service.digital.com/html/patch_service.html">http://www.service.digital.com/html/patch_service.html</a>
   so I guess you'll have to call Digital's Customer Support to get it.
   
   -Jeff
  @@ -211,7 +214,7 @@
   
           tcp_keepinit            This is the amount of time a partially
                                   established connection will sit on the listen
  -                                queue before timing out (<EM>e.g.</EM>, if a client
  +                                queue before timing out (<em>e.g.</em>, if a client
                                   sends a SYN but never answers our SYN/ACK).
                                   Partially established connections tie up slots
                                   on the listen queue.  If the queue starts to
  @@ -276,8 +279,9 @@
   ipport_userreserved         -      X      -
   sysconfig -q inet           -      -      X
   sysconfig -q socket         -      -      X
  +
  +</pre>
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
   
  -</PRE>
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  
  
  
  1.7       +85 -101   httpd-docs-1.3/htdocs/manual/misc/perf-hp.html
  
  Index: perf-hp.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/perf-hp.html,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- perf-hp.html	2001/07/23 12:24:31	1.6
  +++ perf-hp.html	2001/10/08 01:26:54	1.7
  @@ -1,113 +1,97 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<html>
  -<head>
  -<title>Running a High-Performance Web Server on HPUX</title>
  -</head>
  -
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<body
  - bgcolor="#ffffff"
  - text="#000000"
  - link="#0000ff"
  - vlink="#000080"
  - alink="#ff0000"
  ->
  -<a name="initial">&nbsp;</A>
  -<!--#include virtual="header.html" -->
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -<h1 align="center">Running a High-Performance Web Server for HPUX</h1>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Running a High-Performance Web Server on HPUX</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#ffffff" text="#000000" link="#0000ff"
  +  vlink="#000080" alink="#ff0000">
  +    <a id="initial" name="initial">&nbsp;</a> 
  +    <!--#include virtual="header.html" -->
  +     
   
  +    <h1 align="center">Running a High-Performance Web Server for
  +    HPUX</h1>
   <pre>
   Date: Wed, 05 Nov 1997 16:59:34 -0800
  -From: Rick Jones &lt;<a href="mailto:raj@cup.hp.com">raj@cup.hp.com</a>&gt;
  +From: Rick Jones &lt;<a
  +href="mailto:raj@cup.hp.com">raj@cup.hp.com</a>&gt;
   Reply-To: raj@cup.hp.com
   Organization: Network Performance
   Subject: HP-UX tuning tips
   </pre>
  +    Here are some tuning tips for HP-UX to add to the tuning page. 
   
  -Here are some tuning tips for HP-UX to add to the tuning page.
  +    <p>For HP-UX 9.X: Upgrade to 10.20<br />
  +     For HP-UX 10.[00|01|10]: Upgrade to 10.20</p>
   
  -<p>
  +    <p>For HP-UX 10.20:</p>
   
  -For HP-UX 9.X: Upgrade to 10.20<br>
  -For HP-UX 10.[00|01|10]: Upgrade to 10.20
  +    <p>Install the latest cumulative ARPA Transport Patch. This
  +    will allow you to configure the size of the TCP connection
  +    lookup hash table. The default is 256 buckets and must be set
  +    to a power of two. This is accomplished with adb against the
  +    *disc* image of the kernel. The variable name is tcp_hash_size.
  +    Notice that it's critically important that you use "W" to write
  +    a 32 bit quantity, not "w" to write a 16 bit value when
  +    patching the disc image because the tcp_hash_size variable is a
  +    32 bit quantity.</p>
  +
  +    <p>How to pick the value? Examine the output of <a
  +    href="ftp://ftp.cup.hp.com/dist/networking/tools/connhist">ftp://ftp.cup.hp.com/dist/networking/tools/connhist</a>
  +    and see how many total TCP connections exist on the system. You
  +    probably want that number divided by the hash table size to be
  +    reasonably small, say less than 10. Folks can look at HP's
  +    SPECweb96 disclosures for some common settings. These can be
  +    found at <a
  +    href="http://www.specbench.org/">http://www.specbench.org/</a>.
  +    If an HP-UX system was performing at 1000 SPECweb96 connections
  +    per second, the TIME_WAIT time of 60 seconds would mean 60,000
  +    TCP "connections" being tracked.</p>
  +
  +    <p>Folks can check their listen queue depths with <a
  +    href="ftp://ftp.cup.hp.com/dist/networking/misc/listenq">ftp://ftp.cup.hp.com/dist/networking/misc/listenq</a>.</p>
  +
  +    <p>If folks are running Apache on a PA-8000 based system, they
  +    should consider "chatr'ing" the Apache executable to have a
  +    large page size. This would be "chatr +pi L &lt;BINARY&gt;."
  +    The GID of the running executable must have MLOCK privileges.
  +    Setprivgrp(1m) should be consulted for assigning MLOCK. The
  +    change can be validated by running Glance and examining the
  +    memory regions of the server(s) to make sure that they show a
  +    non-trivial fraction of the text segment being locked.</p>
  +
  +    <p>If folks are running Apache on MP systems, they might
  +    consider writing a small program that uses mpctl() to bind
  +    processes to processors. A simple pid % numcpu algorithm is
  +    probably sufficient. This might even go into the source
  +    code.</p>
  +
  +    <p>If folks are concerned about the number of FIN_WAIT_2
  +    connections, they can use nettune to shrink the value of
  +    tcp_keepstart. However, they should be careful there -
  +    certainly do not make it less than oh two to four minutes. If
  +    tcp_hash_size has been set well, it is probably OK to let the
  +    FIN_WAIT_2's take longer to timeout (perhaps even the default
  +    two hours) - they will not on average have a big impact on
  +    performance.</p>
  +
  +    <p>There are other things that could go into the code base, but
  +    that might be left for another email. Feel free to drop me a
  +    message if you or others are interested.</p>
  +
  +    <p>sincerely,</p>
  +
  +    <p>rick jones<br />
  +     <a
  +    href="http://www.cup.hp.com/netperf/NetperfPage.html">http://www.cup.hp.com/netperf/NetperfPage.html</a>
  +    <!--#include virtual="footer.html" -->
  +    </p>
  +  </body>
  +</html>
   
  -<p>
  -
  -For HP-UX 10.20: 
  -
  -<p>
  -
  -Install the latest cumulative ARPA Transport Patch. This will allow you
  -to configure the size of the TCP connection lookup hash table. The
  -default is 256 buckets and must be set to a power of two. This is
  -accomplished with adb against the *disc* image of the kernel. The
  -variable name is tcp_hash_size.
  -
  -Notice that it's critically important that you use "W" to write a 32 bit
  -quantity, not "w" to write a 16 bit value when patching the disc image because
  -the tcp_hash_size variable is a 32 bit quantity.
  -
  -<p>
  -
  -How to pick the value? Examine the output of
  -<a href="ftp://ftp.cup.hp.com/dist/networking/tools/connhist">
  -ftp://ftp.cup.hp.com/dist/networking/tools/connhist</a> and see how many
  -total TCP connections exist on the system. You probably want that number
  -divided by the hash table size to be reasonably small, say less than 10.
  -Folks can look at HP's SPECweb96 disclosures for some common settings.
  -These can be found at <a href="http://www.specbench.org/">
  -http://www.specbench.org/</a>. If an HP-UX system was
  -performing at 1000 SPECweb96 connections per second, the TIME_WAIT time
  -of 60 seconds would mean 60,000 TCP "connections" being tracked. 
  -
  -<p>
  -
  -Folks can check their listen queue depths with
  -<a href="ftp://ftp.cup.hp.com/dist/networking/misc/listenq">
  -ftp://ftp.cup.hp.com/dist/networking/misc/listenq</a>.
  -
  -<p>
  -
  -If folks are running Apache on a PA-8000 based system, they should
  -consider "chatr'ing" the Apache executable to have a large page size.
  -This would be "chatr +pi L &lt;BINARY&gt;." The GID of the running executable
  -must have MLOCK privileges. Setprivgrp(1m) should be consulted for
  -assigning MLOCK. The change can be validated by running Glance and
  -examining the memory regions of the server(s) to make sure that they
  -show a non-trivial fraction of the text segment being locked.
  -
  -<p>
  -
  -If folks are running Apache on MP systems, they might consider writing a
  -small program that uses mpctl() to bind processes to processors. A
  -simple pid % numcpu algorithm is probably sufficient. This might even go
  -into the source code.
  -
  -<p>
  -
  -If folks are concerned about the number of FIN_WAIT_2 connections, they
  -can use nettune to shrink the value of tcp_keepstart. However, they
  -should be careful there - certainly do not make it less than oh two to
  -four minutes. If tcp_hash_size has been set well, it is probably OK to
  -let the FIN_WAIT_2's take longer to timeout (perhaps even the default
  -two hours) - they will not on average have a big impact on performance.
  -
  -<p>
  -
  -There are other things that could go into the code base, but that might
  -be left for another email. Feel free to drop me a message if you or
  -others are interested.
  -
  -<p>
  -
  -sincerely,
  -
  -<p>
  -
  -rick jones<br>
  -<a href="http://www.cup.hp.com/netperf/NetperfPage.html">
  -http://www.cup.hp.com/netperf/NetperfPage.html</a>
  -
  -<!--#include virtual="footer.html" -->
  -</body></html>
  
  
  
  1.27      +882 -769  httpd-docs-1.3/htdocs/manual/misc/perf-tuning.html
  
  Index: perf-tuning.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/perf-tuning.html,v
  retrieving revision 1.26
  retrieving revision 1.27
  diff -u -r1.26 -r1.27
  --- perf-tuning.html	2001/09/13 04:37:41	1.26
  +++ perf-tuning.html	2001/10/08 01:26:54	1.27
  @@ -1,151 +1,179 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  - <TITLE>Apache Performance Notes</TITLE>
  -</HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 align="center">Apache Performance Notes</H1>
  -
  -<P>Author: Dean Gaudet
  -
  -<ul>
  -<li><a href="#introduction">Introduction</a></li>
  -<li><a href="#hardware">Hardware and Operating System Issues</a></li>
  -<li><a href="#runtime">Run-Time Configuration Issues</a></li>
  -<li><a href="#compiletime">Compile-Time Configuration Issues</a></li>
  -<li>Appendixes
  -  <ul>
  -  <li><a href="#trace">Detailed Analysis of a Trace</a></li>
  -  <li><a href="#patches">Patches Available</a></li>
  -  <li><a href="#preforking">The Pre-Forking Model</a></li>
  -  </ul></li>
  -</ul>
  -
  -<hr>
  -
  -<H3><a name="introduction">Introduction</A></H3>
  -<P>Apache is a general webserver, which is designed to be correct first, and
  -fast second.  Even so, its performance is quite satisfactory.  Most
  -sites have less than 10Mbits of outgoing bandwidth, which Apache can
  -fill using only a low end Pentium-based webserver.  In practice sites
  -with more bandwidth require more than one machine to fill the bandwidth
  -due to other constraints (such as CGI or database transaction overhead).
  -For these reasons the development focus has been mostly on correctness
  -and configurability.
  -
  -<P>Unfortunately many folks overlook these facts and cite raw performance
  -numbers as if they are some indication of the quality of a web server
  -product.  There is a bare minimum performance that is acceptable, beyond
  -that extra speed only caters to a much smaller segment of the market.
  -But in order to avoid this hurdle to the acceptance of Apache in some
  -markets, effort was put into Apache 1.3 to bring performance up to a
  -point where the difference with other high-end webservers is minimal.
  -
  -<P>Finally there are the folks who just plain want to see how fast something
  -can go.  The author falls into this category.  The rest of this document
  -is dedicated to these folks who want to squeeze every last bit of
  -performance out of Apache's current model, and want to understand why
  -it does some things which slow it down.
  -
  -<P>Note that this is tailored towards Apache 1.3 on Unix.  Some of it applies
  -to Apache on NT.  Apache on NT has not been tuned for performance yet;
  -in fact it probably performs very poorly because NT performance requires
  -a different programming model.
  -
  -<hr>
  -
  -<H3><a name="hardware">Hardware and Operating System Issues</a></H3>
  -
  -<P>The single biggest hardware issue affecting webserver performance
  -is RAM.  A webserver should never ever have to swap, swapping increases
  -the latency of each request beyond a point that users consider "fast
  -enough".  This causes users to hit stop and reload, further increasing
  -the load.  You can, and should, control the <CODE>MaxClients</CODE>
  -setting so that your server does not spawn so many children it starts
  -swapping.
  -
  -<P>Beyond that the rest is mundane:  get a fast enough CPU, a fast enough
  -network card, and fast enough disks, where "fast enough" is something
  -that needs to be determined by experimentation.
  -
  -<P>Operating system choice is largely a matter of local concerns.  But
  -a general guideline is to always apply the latest vendor TCP/IP patches.
  -HTTP serving completely breaks many of the assumptions built into Unix
  -kernels up through 1994 and even 1995.  Good choices include
  -recent FreeBSD, and Linux.
  -
  -<hr>
  -
  -<H3><a name="runtime">Run-Time Configuration Issues</a></H3>
  -
  -<H4>HostnameLookups</H4>
  -<P>Prior to Apache 1.3, <CODE>HostnameLookups</CODE> defaulted to On.
  -This adds latency
  -to every request because it requires a DNS lookup to complete before
  -the request is finished.  In Apache 1.3 this setting defaults to Off.
  -However (1.3 or later), if you use any <CODE>Allow from domain</CODE> or
  -<CODE>Deny from domain</CODE> directives then you will pay for a
  -double reverse DNS lookup (a reverse, followed by a forward to make sure
  -that the reverse is not being spoofed).  So for the highest performance
  -avoid using these directives (it's fine to use IP addresses rather than
  -domain names).
  -
  -<P>Note that it's possible to scope the directives, such as within
  -a <CODE>&lt;Location /server-status&gt;</CODE> section.  In this
  -case the DNS lookups are only performed on requests matching the
  -criteria.  Here's an example which disables
  -lookups except for .html and .cgi files:
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -<BLOCKQUOTE><PRE>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Performance Notes</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="center">Apache Performance Notes</h1>
  +
  +    <p>Author: Dean Gaudet</p>
  +
  +    <ul>
  +      <li><a href="#introduction">Introduction</a></li>
  +
  +      <li><a href="#hardware">Hardware and Operating System
  +      Issues</a></li>
  +
  +      <li><a href="#runtime">Run-Time Configuration Issues</a></li>
  +
  +      <li><a href="#compiletime">Compile-Time Configuration
  +      Issues</a></li>
  +
  +      <li>
  +        Appendixes 
  +
  +        <ul>
  +          <li><a href="#trace">Detailed Analysis of a
  +          Trace</a></li>
  +
  +          <li><a href="#patches">Patches Available</a></li>
  +
  +          <li><a href="#preforking">The Pre-Forking Model</a></li>
  +        </ul>
  +      </li>
  +    </ul>
  +    <hr />
  +
  +    <h3><a id="introduction"
  +    name="introduction">Introduction</a></h3>
  +
  +    <p>Apache is a general webserver, which is designed to be
  +    correct first, and fast second. Even so, its performance is
  +    quite satisfactory. Most sites have less than 10Mbits of
  +    outgoing bandwidth, which Apache can fill using only a low end
  +    Pentium-based webserver. In practice sites with more bandwidth
  +    require more than one machine to fill the bandwidth due to
  +    other constraints (such as CGI or database transaction
  +    overhead). For these reasons the development focus has been
  +    mostly on correctness and configurability.</p>
  +
  +    <p>Unfortunately many folks overlook these facts and cite raw
  +    performance numbers as if they are some indication of the
  +    quality of a web server product. There is a bare minimum
  +    performance that is acceptable, beyond that extra speed only
  +    caters to a much smaller segment of the market. But in order to
  +    avoid this hurdle to the acceptance of Apache in some markets,
  +    effort was put into Apache 1.3 to bring performance up to a
  +    point where the difference with other high-end webservers is
  +    minimal.</p>
  +
  +    <p>Finally there are the folks who just plain want to see how
  +    fast something can go. The author falls into this category. The
  +    rest of this document is dedicated to these folks who want to
  +    squeeze every last bit of performance out of Apache's current
  +    model, and want to understand why it does some things which
  +    slow it down.</p>
  +
  +    <p>Note that this is tailored towards Apache 1.3 on Unix. Some
  +    of it applies to Apache on NT. Apache on NT has not been tuned
  +    for performance yet; in fact it probably performs very poorly
  +    because NT performance requires a different programming
  +    model.</p>
  +    <hr />
  +
  +    <h3><a id="hardware" name="hardware">Hardware and Operating
  +    System Issues</a></h3>
  +
  +    <p>The single biggest hardware issue affecting webserver
  +    performance is RAM. A webserver should never ever have to swap,
  +    swapping increases the latency of each request beyond a point
  +    that users consider "fast enough". This causes users to hit
  +    stop and reload, further increasing the load. You can, and
  +    should, control the <code>MaxClients</code> setting so that
  +    your server does not spawn so many children it starts
  +    swapping.</p>
  +
  +    <p>Beyond that the rest is mundane: get a fast enough CPU, a
  +    fast enough network card, and fast enough disks, where "fast
  +    enough" is something that needs to be determined by
  +    experimentation.</p>
  +
  +    <p>Operating system choice is largely a matter of local
  +    concerns. But a general guideline is to always apply the latest
  +    vendor TCP/IP patches. HTTP serving completely breaks many of
  +    the assumptions built into Unix kernels up through 1994 and
  +    even 1995. Good choices include recent FreeBSD, and Linux.</p>
  +    <hr />
  +
  +    <h3><a id="runtime" name="runtime">Run-Time Configuration
  +    Issues</a></h3>
  +
  +    <h4>HostnameLookups</h4>
  +
  +    <p>Prior to Apache 1.3, <code>HostnameLookups</code> defaulted
  +    to On. This adds latency to every request because it requires a
  +    DNS lookup to complete before the request is finished. In
  +    Apache 1.3 this setting defaults to Off. However (1.3 or
  +    later), if you use any <code>Allow from domain</code> or
  +    <code>Deny from domain</code> directives then you will pay for
  +    a double reverse DNS lookup (a reverse, followed by a forward
  +    to make sure that the reverse is not being spoofed). So for the
  +    highest performance avoid using these directives (it's fine to
  +    use IP addresses rather than domain names).</p>
  +
  +    <p>Note that it's possible to scope the directives, such as
  +    within a <code>&lt;Location /server-status&gt;</code> section.
  +    In this case the DNS lookups are only performed on requests
  +    matching the criteria. Here's an example which disables lookups
  +    except for .html and .cgi files:</p>
  +
  +    <blockquote>
  +<pre>
   HostnameLookups off
   &lt;Files ~ "\.(html|cgi)$"&gt;
       HostnameLookups on
   &lt;/Files&gt;
  -</PRE></BLOCKQUOTE>
  -
  -But even still, if you just need DNS names
  -in some CGIs you could consider doing the
  -<CODE>gethostbyname</CODE> call in the specific CGIs that need it.
  -
  -<p>Similarly, if you need to have hostname information in your server
  -logs in order to generate reports of this information, you can
  -postprocess your log file with <a href="../programs/logresolve.html"
  ->logresolve</a>, so that these lookups can be done without making the
  -client wait. It is recommended that you do this postprocessing, and any
  -other statistical analysis of the log file, somewhere other than your
  -production web server machine, in order that this activity does not
  -adversely affect server performance.</p>
  -
  -<H4>FollowSymLinks and SymLinksIfOwnerMatch</H4>
  -<P>Wherever in your URL-space you do not have an
  -<CODE>Options FollowSymLinks</CODE>, or you do have an
  -<CODE>Options SymLinksIfOwnerMatch</CODE> Apache will have to
  -issue extra system calls to check up on symlinks.  One extra call per
  -filename component.  For example, if you had:
  +</pre>
  +    </blockquote>
  +    But even still, if you just need DNS names in some CGIs you
  +    could consider doing the <code>gethostbyname</code> call in the
  +    specific CGIs that need it. 
  +
  +    <p>Similarly, if you need to have hostname information in your
  +    server logs in order to generate reports of this information,
  +    you can postprocess your log file with <a
  +    href="../programs/logresolve.html">logresolve</a>, so that
  +    these lookups can be done without making the client wait. It is
  +    recommended that you do this postprocessing, and any other
  +    statistical analysis of the log file, somewhere other than your
  +    production web server machine, in order that this activity does
  +    not adversely affect server performance.</p>
  +
  +    <h4>FollowSymLinks and SymLinksIfOwnerMatch</h4>
  +
  +    <p>Wherever in your URL-space you do not have an <code>Options
  +    FollowSymLinks</code>, or you do have an <code>Options
  +    SymLinksIfOwnerMatch</code> Apache will have to issue extra
  +    system calls to check up on symlinks. One extra call per
  +    filename component. For example, if you had:</p>
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   DocumentRoot /www/htdocs
   &lt;Directory /&gt;
       Options SymLinksIfOwnerMatch
   &lt;/Directory&gt;
  -</PRE></BLOCKQUOTE>
  -
  -and a request is made for the URI <CODE>/index.html</CODE>.
  -Then Apache will perform <CODE>lstat(2)</CODE> on <CODE>/www</CODE>,
  -<CODE>/www/htdocs</CODE>, and <CODE>/www/htdocs/index.html</CODE>.  The
  -results of these <CODE>lstats</CODE> are never cached,
  -so they will occur on every single request.  If you really desire the
  -symlinks security checking you can do something like this:
  +</pre>
  +    </blockquote>
  +    and a request is made for the URI <code>/index.html</code>.
  +    Then Apache will perform <code>lstat(2)</code> on
  +    <code>/www</code>, <code>/www/htdocs</code>, and
  +    <code>/www/htdocs/index.html</code>. The results of these
  +    <code>lstats</code> are never cached, so they will occur on
  +    every single request. If you really desire the symlinks
  +    security checking you can do something like this: 
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   DocumentRoot /www/htdocs
   &lt;Directory /&gt;
       Options FollowSymLinks
  @@ -153,438 +181,485 @@
   &lt;Directory /www/htdocs&gt;
       Options -FollowSymLinks +SymLinksIfOwnerMatch
   &lt;/Directory&gt;
  -</PRE></BLOCKQUOTE>
  +</pre>
  +    </blockquote>
  +    This at least avoids the extra checks for the
  +    <code>DocumentRoot</code> path. Note that you'll need to add
  +    similar sections if you have any <code>Alias</code> or
  +    <code>RewriteRule</code> paths outside of your document root.
  +    For highest performance, and no symlink protection, set
  +    <code>FollowSymLinks</code> everywhere, and never set
  +    <code>SymLinksIfOwnerMatch</code>. 
  +
  +    <h4>AllowOverride</h4>
  +
  +    <p>Wherever in your URL-space you allow overrides (typically
  +    <code>.htaccess</code> files) Apache will attempt to open
  +    <code>.htaccess</code> for each filename component. For
  +    example,</p>
   
  -This at least avoids the extra checks for the <CODE>DocumentRoot</CODE>
  -path.  Note that you'll need to add similar sections if you have any
  -<CODE>Alias</CODE> or <CODE>RewriteRule</CODE> paths outside of your
  -document root.  For highest performance, and no symlink protection,
  -set <CODE>FollowSymLinks</CODE> everywhere, and never set
  -<CODE>SymLinksIfOwnerMatch</CODE>.
  -
  -<H4>AllowOverride</H4>
  -
  -<P>Wherever in your URL-space you allow overrides (typically
  -<CODE>.htaccess</CODE> files) Apache will attempt to open
  -<CODE>.htaccess</CODE> for each filename component.  For example,
  -
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   DocumentRoot /www/htdocs
   &lt;Directory /&gt;
       AllowOverride all
   &lt;/Directory&gt;
  -</PRE></BLOCKQUOTE>
  -
  -and a request is made for the URI <CODE>/index.html</CODE>.  Then
  -Apache will attempt to open <CODE>/.htaccess</CODE>,
  -<CODE>/www/.htaccess</CODE>, and <CODE>/www/htdocs/.htaccess</CODE>.
  -The solutions are similar to the previous case of <CODE>Options
  -FollowSymLinks</CODE>.  For highest performance use
  -<CODE>AllowOverride None</CODE> everywhere in your filesystem.
  -
  -<H4>Negotiation</H4>
  -
  -<P>If at all possible, avoid content-negotiation if you're really
  -interested in every last ounce of performance.  In practice the
  -benefits of negotiation outweigh the performance penalties.  There's
  -one case where you can speed up the server.  Instead of using
  -a wildcard such as:
  +</pre>
  +    </blockquote>
  +    and a request is made for the URI <code>/index.html</code>.
  +    Then Apache will attempt to open <code>/.htaccess</code>,
  +    <code>/www/.htaccess</code>, and
  +    <code>/www/htdocs/.htaccess</code>. The solutions are similar
  +    to the previous case of <code>Options FollowSymLinks</code>.
  +    For highest performance use <code>AllowOverride None</code>
  +    everywhere in your filesystem. 
  +
  +    <h4>Negotiation</h4>
  +
  +    <p>If at all possible, avoid content-negotiation if you're
  +    really interested in every last ounce of performance. In
  +    practice the benefits of negotiation outweigh the performance
  +    penalties. There's one case where you can speed up the server.
  +    Instead of using a wildcard such as:</p>
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   DirectoryIndex index
  -</PRE></BLOCKQUOTE>
  +</pre>
  +    </blockquote>
  +    Use a complete list of options: 
   
  -Use a complete list of options:
  -
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   DirectoryIndex index.cgi index.pl index.shtml index.html
  -</PRE></BLOCKQUOTE>
  -
  -where you list the most common choice first.
  -
  -<H4>Process Creation</H4>
  +</pre>
  +    </blockquote>
  +    where you list the most common choice first. 
  +
  +    <h4>Process Creation</h4>
  +
  +    <p>Prior to Apache 1.3 the <code>MinSpareServers</code>,
  +    <code>MaxSpareServers</code>, and <code>StartServers</code>
  +    settings all had drastic effects on benchmark results. In
  +    particular, Apache required a "ramp-up" period in order to
  +    reach a number of children sufficient to serve the load being
  +    applied. After the initial spawning of
  +    <code>StartServers</code> children, only one child per second
  +    would be created to satisfy the <code>MinSpareServers</code>
  +    setting. So a server being accessed by 100 simultaneous
  +    clients, using the default <code>StartServers</code> of 5 would
  +    take on the order 95 seconds to spawn enough children to handle
  +    the load. This works fine in practice on real-life servers,
  +    because they aren't restarted frequently. But does really
  +    poorly on benchmarks which might only run for ten minutes.</p>
  +
  +    <p>The one-per-second rule was implemented in an effort to
  +    avoid swamping the machine with the startup of new children. If
  +    the machine is busy spawning children it can't service
  +    requests. But it has such a drastic effect on the perceived
  +    performance of Apache that it had to be replaced. As of Apache
  +    1.3, the code will relax the one-per-second rule. It will spawn
  +    one, wait a second, then spawn two, wait a second, then spawn
  +    four, and it will continue exponentially until it is spawning
  +    32 children per second. It will stop whenever it satisfies the
  +    <code>MinSpareServers</code> setting.</p>
  +
  +    <p>This appears to be responsive enough that it's almost
  +    unnecessary to twiddle the <code>MinSpareServers</code>,
  +    <code>MaxSpareServers</code> and <code>StartServers</code>
  +    knobs. When more than 4 children are spawned per second, a
  +    message will be emitted to the <code>ErrorLog</code>. If you
  +    see a lot of these errors then consider tuning these settings.
  +    Use the <code>mod_status</code> output as a guide.</p>
  +
  +    <p>Related to process creation is process death induced by the
  +    <code>MaxRequestsPerChild</code> setting. By default this is 0,
  +    which means that there is no limit to the number of requests
  +    handled per child. If your configuration currently has this set
  +    to some very low number, such as 30, you may want to bump this
  +    up significantly. If you are running SunOS or an old version of
  +    Solaris, limit this to 10000 or so because of memory leaks.</p>
  +
  +    <p>When keep-alives are in use, children will be kept busy
  +    doing nothing waiting for more requests on the already open
  +    connection. The default <code>KeepAliveTimeout</code> of 15
  +    seconds attempts to minimize this effect. The tradeoff here is
  +    between network bandwidth and server resources. In no event
  +    should you raise this above about 60 seconds, as <a
  +    href="http://www.research.digital.com/wrl/techreports/abstracts/95.4.html">
  +    most of the benefits are lost</a>.</p>
  +    <hr />
  +
  +    <h3><a id="compiletime" name="compiletime">Compile-Time
  +    Configuration Issues</a></h3>
  +
  +    <h4>mod_status and ExtendedStatus On</h4>
  +
  +    <p>If you include <code>mod_status</code> and you also set
  +    <code>ExtendedStatus On</code> when building and running
  +    Apache, then on every request Apache will perform two calls to
  +    <code>gettimeofday(2)</code> (or <code>times(2)</code>
  +    depending on your operating system), and (pre-1.3) several
  +    extra calls to <code>time(2)</code>. This is all done so that
  +    the status report contains timing indications. For highest
  +    performance, set <code>ExtendedStatus off</code> (which is the
  +    default).</p>
  +
  +    <h4>accept Serialization - multiple sockets</h4>
  +
  +    <p>This discusses a shortcoming in the Unix socket API. Suppose
  +    your web server uses multiple <code>Listen</code> statements to
  +    listen on either multiple ports or multiple addresses. In order
  +    to test each socket to see if a connection is ready Apache uses
  +    <code>select(2)</code>. <code>select(2)</code> indicates that a
  +    socket has <em>zero</em> or <em>at least one</em> connection
  +    waiting on it. Apache's model includes multiple children, and
  +    all the idle ones test for new connections at the same time. A
  +    naive implementation looks something like this (these examples
  +    do not match the code, they're contrived for pedagogical
  +    purposes):</p>
   
  -<P>Prior to Apache 1.3 the <CODE>MinSpareServers</CODE>,
  -<CODE>MaxSpareServers</CODE>, and <CODE>StartServers</CODE> settings
  -all had drastic effects on benchmark results.  In particular, Apache
  -required a "ramp-up" period in order to reach a number of children
  -sufficient to serve the load being applied.  After the initial
  -spawning of <CODE>StartServers</CODE> children, only one child per
  -second would be created to satisfy the <CODE>MinSpareServers</CODE>
  -setting.  So a server being accessed by 100 simultaneous clients,
  -using the default <CODE>StartServers</CODE> of 5 would take on
  -the order 95 seconds to spawn enough children to handle the load.  This
  -works fine in practice on real-life servers, because they aren't restarted
  -frequently.  But does really poorly on benchmarks which might only run
  -for ten minutes.
  -
  -<P>The one-per-second rule was implemented in an effort to avoid
  -swamping the machine with the startup of new children.  If the machine
  -is busy spawning children it can't service requests.  But it has such
  -a drastic effect on the perceived performance of Apache that it had
  -to be replaced.  As of Apache 1.3,
  -the code will relax the one-per-second rule.  It
  -will spawn one, wait a second, then spawn two, wait a second, then spawn
  -four, and it will continue exponentially until it is spawning 32 children
  -per second.  It will stop whenever it satisfies the
  -<CODE>MinSpareServers</CODE> setting.
  -
  -<P>This appears to be responsive enough that it's
  -almost unnecessary to twiddle the <CODE>MinSpareServers</CODE>,
  -<CODE>MaxSpareServers</CODE> and <CODE>StartServers</CODE> knobs.  When
  -more than 4 children are spawned per second, a message will be emitted
  -to the <CODE>ErrorLog</CODE>.  If you see a lot of these errors then
  -consider tuning these settings.  Use the <CODE>mod_status</CODE> output
  -as a guide.
  -
  -<P>Related to process creation is process death induced by the
  -<CODE>MaxRequestsPerChild</CODE> setting.  By default this is 0, which
  -means that there is no limit to the number of requests handled
  -per child. If your configuration currently has this set to some
  -very low number, such as 30, you may want to bump this up significantly.
  -If you are running SunOS or an old version of Solaris, limit this
  -to 10000 or so because of memory leaks.
  -
  -<P>When keep-alives are in use, children will be kept busy
  -doing nothing waiting for more requests on the already open
  -connection.  The default <CODE>KeepAliveTimeout</CODE> of
  -15 seconds attempts to minimize this effect.  The tradeoff
  -here is between network bandwidth and server resources.
  -In no event should you raise this above about 60 seconds, as
  -<A HREF="http://www.research.digital.com/wrl/techreports/abstracts/95.4.html"
  ->most of the benefits are lost</A>.
  -
  -<hr>
  -
  -<H3><a name="compiletime">Compile-Time Configuration Issues</a></H3>
  -
  -<H4>mod_status and ExtendedStatus On</H4>
  -
  -<P>If you include <CODE>mod_status</CODE>
  -and you also set <CODE>ExtendedStatus On</CODE> when building and running
  -Apache, then on every request Apache will perform two calls to
  -<CODE>gettimeofday(2)</CODE> (or <CODE>times(2)</CODE> depending
  -on your operating system), and (pre-1.3) several extra calls to
  -<CODE>time(2)</CODE>.  This is all done so that the status report
  -contains timing indications.  For highest performance, set
  -<CODE>ExtendedStatus off</CODE> (which is the default).
  -
  -<H4>accept Serialization - multiple sockets</H4>
  -
  -<P>This discusses a shortcoming in the Unix socket API.
  -Suppose your
  -web server uses multiple <CODE>Listen</CODE> statements to listen on
  -either multiple ports or multiple addresses.  In order to test each
  -socket to see if a connection is ready Apache uses <CODE>select(2)</CODE>.
  -<CODE>select(2)</CODE> indicates that a socket has <EM>zero</EM> or
  -<EM>at least one</EM> connection waiting on it.  Apache's model includes
  -multiple children, and all the idle ones test for new connections at the
  -same time.  A naive implementation looks something like this
  -(these examples do not match the code, they're contrived for
  -pedagogical purposes):
  -
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
  +    for (;;) {
       for (;;) {
  -	for (;;) {
  -	    fd_set accept_fds;
  +        fd_set accept_fds;
   
  -	    FD_ZERO (&amp;accept_fds);
  -	    for (i = first_socket; i &lt;= last_socket; ++i) {
  -		FD_SET (i, &amp;accept_fds);
  -	    }
  -	    rc = select (last_socket+1, &amp;accept_fds, NULL, NULL, NULL);
  -	    if (rc &lt; 1) continue;
  -	    new_connection = -1;
  -	    for (i = first_socket; i &lt;= last_socket; ++i) {
  -		if (FD_ISSET (i, &amp;accept_fds)) {
  -		    new_connection = accept (i, NULL, NULL);
  -		    if (new_connection != -1) break;
  -		}
  -	    }
  -	    if (new_connection != -1) break;
  -	}
  -	process the new_connection;
  +        FD_ZERO (&amp;accept_fds);
  +        for (i = first_socket; i &lt;= last_socket; ++i) {
  +        FD_SET (i, &amp;accept_fds);
  +        }
  +        rc = select (last_socket+1, &amp;accept_fds, NULL, NULL, NULL);
  +        if (rc &lt; 1) continue;
  +        new_connection = -1;
  +        for (i = first_socket; i &lt;= last_socket; ++i) {
  +        if (FD_ISSET (i, &amp;accept_fds)) {
  +            new_connection = accept (i, NULL, NULL);
  +            if (new_connection != -1) break;
  +        }
  +        }
  +        if (new_connection != -1) break;
       }
  -</PRE></BLOCKQUOTE>
  -
  -But this naive implementation has a serious starvation problem.  Recall
  -that multiple children execute this loop at the same time, and so multiple
  -children will block at <CODE>select</CODE> when they are in between
  -requests.  All those blocked children will awaken and return from
  -<CODE>select</CODE> when a single request appears on any socket
  -(the number of children which awaken varies depending on the operating
  -system and timing issues).
  -They will all then fall down into the loop and try to <CODE>accept</CODE>
  -the connection.  But only one will succeed (assuming there's still only
  -one connection ready), the rest will be <EM>blocked</EM> in
  -<CODE>accept</CODE>.
  -This effectively locks those children into serving requests from that
  -one socket and no other sockets, and they'll be stuck there until enough
  -new requests appear on that socket to wake them all up.
  -This starvation problem was first documented in
  -<A HREF="http://bugs.apache.org/index/full/467">PR#467</A>.  There
  -are at least two solutions.
  -
  -<P>One solution is to make the sockets non-blocking.  In this case the
  -<CODE>accept</CODE> won't block the children, and they will be allowed
  -to continue immediately.  But this wastes CPU time.  Suppose you have
  -ten idle children in <CODE>select</CODE>, and one connection arrives.
  -Then nine of those children will wake up, try to <CODE>accept</CODE> the
  -connection, fail, and loop back into <CODE>select</CODE>, accomplishing
  -nothing.  Meanwhile none of those children are servicing requests that
  -occurred on other sockets until they get back up to the <CODE>select</CODE>
  -again.  Overall this solution does not seem very fruitful unless you
  -have as many idle CPUs (in a multiprocessor box) as you have idle children,
  -not a very likely situation.
  -
  -<P>Another solution, the one used by Apache, is to serialize entry into
  -the inner loop.  The loop looks like this (differences highlighted):
  +    process the new_connection;
  +    }
  +</pre>
  +    </blockquote>
  +    But this naive implementation has a serious starvation problem.
  +    Recall that multiple children execute this loop at the same
  +    time, and so multiple children will block at
  +    <code>select</code> when they are in between requests. All
  +    those blocked children will awaken and return from
  +    <code>select</code> when a single request appears on any socket
  +    (the number of children which awaken varies depending on the
  +    operating system and timing issues). They will all then fall
  +    down into the loop and try to <code>accept</code> the
  +    connection. But only one will succeed (assuming there's still
  +    only one connection ready), the rest will be <em>blocked</em>
  +    in <code>accept</code>. This effectively locks those children
  +    into serving requests from that one socket and no other
  +    sockets, and they'll be stuck there until enough new requests
  +    appear on that socket to wake them all up. This starvation
  +    problem was first documented in <a
  +    href="http://bugs.apache.org/index/full/467">PR#467</a>. There
  +    are at least two solutions. 
  +
  +    <p>One solution is to make the sockets non-blocking. In this
  +    case the <code>accept</code> won't block the children, and they
  +    will be allowed to continue immediately. But this wastes CPU
  +    time. Suppose you have ten idle children in
  +    <code>select</code>, and one connection arrives. Then nine of
  +    those children will wake up, try to <code>accept</code> the
  +    connection, fail, and loop back into <code>select</code>,
  +    accomplishing nothing. Meanwhile none of those children are
  +    servicing requests that occurred on other sockets until they
  +    get back up to the <code>select</code> again. Overall this
  +    solution does not seem very fruitful unless you have as many
  +    idle CPUs (in a multiprocessor box) as you have idle children,
  +    not a very likely situation.</p>
  +
  +    <p>Another solution, the one used by Apache, is to serialize
  +    entry into the inner loop. The loop looks like this
  +    (differences highlighted):</p>
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
       for (;;) {
  -	<STRONG>accept_mutex_on ();</STRONG>
  -	for (;;) {
  -	    fd_set accept_fds;
  -
  -	    FD_ZERO (&amp;accept_fds);
  -	    for (i = first_socket; i &lt;= last_socket; ++i) {
  -		FD_SET (i, &amp;accept_fds);
  -	    }
  -	    rc = select (last_socket+1, &amp;accept_fds, NULL, NULL, NULL);
  -	    if (rc &lt; 1) continue;
  -	    new_connection = -1;
  -	    for (i = first_socket; i &lt;= last_socket; ++i) {
  -		if (FD_ISSET (i, &amp;accept_fds)) {
  -		    new_connection = accept (i, NULL, NULL);
  -		    if (new_connection != -1) break;
  -		}
  -	    }
  -	    if (new_connection != -1) break;
  -	}
  -	<STRONG>accept_mutex_off ();</STRONG>
  -	process the new_connection;
  -    }
  -</PRE></BLOCKQUOTE>
  +    <strong>accept_mutex_on ();</strong>
  +    for (;;) {
  +        fd_set accept_fds;
   
  -<A NAME="serialize">The functions</A>
  -<CODE>accept_mutex_on</CODE> and <CODE>accept_mutex_off</CODE>
  -implement a mutual exclusion semaphore.  Only one child can have the
  -mutex at any time.  There are several choices for implementing these
  -mutexes.  The choice is defined in <CODE>src/conf.h</CODE> (pre-1.3) or
  -<CODE>src/include/ap_config.h</CODE> (1.3 or later).  Some architectures
  -do not have any locking choice made, on these architectures it is unsafe
  -to use multiple <CODE>Listen</CODE> directives.
  -
  -<DL>
  -<DT><CODE>HAVE_FLOCK_SERIALIZED_ACCEPT</CODE>
  -<DD>This method uses the <CODE>flock(2)</CODE> system call to lock a
  -lock file (located by the <CODE>LockFile</CODE> directive).
  -
  -<DT><CODE>HAVE_FCNTL_SERIALIZED_ACCEPT</CODE>
  -<DD>This method uses the <CODE>fcntl(2)</CODE> system call to lock a
  -lock file (located by the <CODE>LockFile</CODE> directive).
  -
  -<DT><CODE>HAVE_SYSVSEM_SERIALIZED_ACCEPT</CODE>
  -<DD>(1.3 or later) This method uses SysV-style semaphores to implement the
  -mutex.  Unfortunately SysV-style semaphores have some bad side-effects.
  -One is that it's possible Apache will die without cleaning up the semaphore
  -(see the <CODE>ipcs(8)</CODE> man page).  The other is that the semaphore
  -API allows for a denial of service attack by any CGIs running under the
  -same uid as the webserver (<EM>i.e.</EM>, all CGIs, unless you use something
  -like suexec or cgiwrapper).  For these reasons this method is not used
  -on any architecture except IRIX (where the previous two are prohibitively
  -expensive on most IRIX boxes).
  -
  -<DT><CODE>HAVE_USLOCK_SERIALIZED_ACCEPT</CODE>
  -<DD>(1.3 or later) This method is only available on IRIX, and uses
  -<CODE>usconfig(2)</CODE> to create a mutex.  While this method avoids
  -the hassles of SysV-style semaphores, it is not the default for IRIX.
  -This is because on single processor IRIX boxes (5.3 or 6.2) the
  -uslock code is two orders of magnitude slower than the SysV-semaphore
  -code.  On multi-processor IRIX boxes the uslock code is an order of magnitude
  -faster than the SysV-semaphore code.  Kind of a messed up situation.
  -So if you're using a multiprocessor IRIX box then you should rebuild your
  -webserver with <CODE>-DHAVE_USLOCK_SERIALIZED_ACCEPT</CODE> on the
  -<CODE>EXTRA_CFLAGS</CODE>.
  -
  -<DT><CODE>HAVE_PTHREAD_SERIALIZED_ACCEPT</CODE>
  -<DD>(1.3 or later) This method uses POSIX mutexes and should work on
  -any architecture implementing the full POSIX threads specification,
  -however appears to only work on Solaris (2.5 or later), and even then
  -only in certain configurations.  If you experiment with this you should
  -watch out for your server hanging and not responding.  Static content
  -only servers may work just fine.
  -</DL>
  -
  -<P>If your system has another method of serialization which isn't in the
  -above list then it may be worthwhile adding code for it (and submitting
  -a patch back to Apache). The above <code>HAVE_METHOD_SERIALIZED_ACCEPT</code>
  -defines specify which method is available and works on the platform (you
  -can have more than one); <code>USE_METHOD_SERIALIZED_ACCEPT</code> is
  -used to specify the default method (see the <code>AcceptMutex</code> directive).
  -
  -<P>Another solution that has been considered but never implemented is
  -to partially serialize the loop -- that is, let in a certain number
  -of processes.  This would only be of interest on multiprocessor boxes
  -where it's possible multiple children could run simultaneously, and the
  -serialization actually doesn't take advantage of the full bandwidth.
  -This is a possible area of future investigation, but priority remains
  -low because highly parallel web servers are not the norm.
  -
  -<P>Ideally you should run servers without multiple <CODE>Listen</CODE>
  -statements if you want the highest performance.  But read on.
  -
  -<H4>accept Serialization - single socket</H4>
  -
  -<P>The above is fine and dandy for multiple socket servers, but what
  -about single socket servers?  In theory they shouldn't experience
  -any of these same problems because all children can just block in
  -<CODE>accept(2)</CODE> until a connection arrives, and no starvation
  -results.  In practice this hides almost the same "spinning" behaviour
  -discussed above in the non-blocking solution.  The way that most TCP
  -stacks are implemented, the kernel actually wakes up all processes blocked
  -in <CODE>accept</CODE> when a single connection arrives.  One of those
  -processes gets the connection and returns to user-space, the rest spin in
  -the kernel and go back to sleep when they discover there's no connection
  -for them.  This spinning is hidden from the user-land code, but it's
  -there nonetheless.  This can result in the same load-spiking wasteful
  -behaviour that a non-blocking solution to the multiple sockets case can.
  -
  -<P>For this reason we have found that many architectures behave more
  -"nicely" if we serialize even the single socket case.  So this is
  -actually the default in almost all cases.  Crude experiments under
  -Linux (2.0.30 on a dual Pentium pro 166 w/128Mb RAM) have shown that
  -the serialization of the single socket case causes less than a 3%
  -decrease in requests per second over unserialized single-socket.
  -But unserialized single-socket showed an extra 100ms latency on
  -each request.  This latency is probably a wash on long haul lines,
  -and only an issue on LANs.  If you want to override the single socket
  -serialization you can define <CODE>SINGLE_LISTEN_UNSERIALIZED_ACCEPT</CODE>
  -and then single-socket servers will not serialize at all.
  -
  -<H4>Lingering Close</H4>
  -
  -<P>As discussed in
  -<A
  - HREF="http://www.ics.uci.edu/pub/ietf/http/draft-ietf-http-connection-00.txt"
  ->draft-ietf-http-connection-00.txt</A> section 8,
  -in order for an HTTP server to <STRONG>reliably</STRONG> implement the protocol
  -it needs to shutdown each direction of the communication independently
  -(recall that a TCP connection is bi-directional, each half is independent
  -of the other).  This fact is often overlooked by other servers, but
  -is correctly implemented in Apache as of 1.2.
  -
  -<P>When this feature was added to Apache it caused a flurry of
  -problems on various versions of Unix because of a shortsightedness.
  -The TCP specification does not state that the FIN_WAIT_2 state has a
  -timeout, but it doesn't prohibit it.  On systems without the timeout,
  -Apache 1.2 induces many sockets stuck forever in the FIN_WAIT_2 state.
  -In many cases this can be avoided by simply upgrading to the latest
  -TCP/IP patches supplied by the vendor.  In cases where the vendor has
  -never released patches (<EM>i.e.</EM>,  SunOS4 -- although folks with a source
  -license can patch it themselves) we have decided to disable this feature.
  -
  -<P>There are two ways of accomplishing this.  One is the
  -socket option <CODE>SO_LINGER</CODE>.  But as fate would have it,
  -this has never been implemented properly in most TCP/IP stacks.  Even
  -on those stacks with a proper implementation (<EM>i.e.</EM>, Linux 2.0.31) this
  -method proves to be more expensive (cputime) than the next solution.
  -
  -<P>For the most part, Apache implements this in a function called
  -<CODE>lingering_close</CODE> (in <CODE>http_main.c</CODE>).  The
  -function looks roughly like this:
  +        FD_ZERO (&amp;accept_fds);
  +        for (i = first_socket; i &lt;= last_socket; ++i) {
  +        FD_SET (i, &amp;accept_fds);
  +        }
  +        rc = select (last_socket+1, &amp;accept_fds, NULL, NULL, NULL);
  +        if (rc &lt; 1) continue;
  +        new_connection = -1;
  +        for (i = first_socket; i &lt;= last_socket; ++i) {
  +        if (FD_ISSET (i, &amp;accept_fds)) {
  +            new_connection = accept (i, NULL, NULL);
  +            if (new_connection != -1) break;
  +        }
  +        }
  +        if (new_connection != -1) break;
  +    }
  +    <strong>accept_mutex_off ();</strong>
  +    process the new_connection;
  +    }
  +</pre>
  +    </blockquote>
  +    <a id="serialize" name="serialize">The functions</a>
  +    <code>accept_mutex_on</code> and <code>accept_mutex_off</code>
  +    implement a mutual exclusion semaphore. Only one child can have
  +    the mutex at any time. There are several choices for
  +    implementing these mutexes. The choice is defined in
  +    <code>src/conf.h</code> (pre-1.3) or
  +    <code>src/include/ap_config.h</code> (1.3 or later). Some
  +    architectures do not have any locking choice made, on these
  +    architectures it is unsafe to use multiple <code>Listen</code>
  +    directives. 
  +
  +    <dl>
  +      <dt><code>HAVE_FLOCK_SERIALIZED_ACCEPT</code></dt>
  +
  +      <dd>This method uses the <code>flock(2)</code> system call to
  +      lock a lock file (located by the <code>LockFile</code>
  +      directive).</dd>
  +
  +      <dt><code>HAVE_FCNTL_SERIALIZED_ACCEPT</code></dt>
  +
  +      <dd>This method uses the <code>fcntl(2)</code> system call to
  +      lock a lock file (located by the <code>LockFile</code>
  +      directive).</dd>
  +
  +      <dt><code>HAVE_SYSVSEM_SERIALIZED_ACCEPT</code></dt>
  +
  +      <dd>(1.3 or later) This method uses SysV-style semaphores to
  +      implement the mutex. Unfortunately SysV-style semaphores have
  +      some bad side-effects. One is that it's possible Apache will
  +      die without cleaning up the semaphore (see the
  +      <code>ipcs(8)</code> man page). The other is that the
  +      semaphore API allows for a denial of service attack by any
  +      CGIs running under the same uid as the webserver
  +      (<em>i.e.</em>, all CGIs, unless you use something like
  +      suexec or cgiwrapper). For these reasons this method is not
  +      used on any architecture except IRIX (where the previous two
  +      are prohibitively expensive on most IRIX boxes).</dd>
  +
  +      <dt><code>HAVE_USLOCK_SERIALIZED_ACCEPT</code></dt>
  +
  +      <dd>(1.3 or later) This method is only available on IRIX, and
  +      uses <code>usconfig(2)</code> to create a mutex. While this
  +      method avoids the hassles of SysV-style semaphores, it is not
  +      the default for IRIX. This is because on single processor
  +      IRIX boxes (5.3 or 6.2) the uslock code is two orders of
  +      magnitude slower than the SysV-semaphore code. On
  +      multi-processor IRIX boxes the uslock code is an order of
  +      magnitude faster than the SysV-semaphore code. Kind of a
  +      messed up situation. So if you're using a multiprocessor IRIX
  +      box then you should rebuild your webserver with
  +      <code>-DHAVE_USLOCK_SERIALIZED_ACCEPT</code> on the
  +      <code>EXTRA_CFLAGS</code>.</dd>
  +
  +      <dt><code>HAVE_PTHREAD_SERIALIZED_ACCEPT</code></dt>
  +
  +      <dd>(1.3 or later) This method uses POSIX mutexes and should
  +      work on any architecture implementing the full POSIX threads
  +      specification, however appears to only work on Solaris (2.5
  +      or later), and even then only in certain configurations. If
  +      you experiment with this you should watch out for your server
  +      hanging and not responding. Static content only servers may
  +      work just fine.</dd>
  +    </dl>
  +
  +    <p>If your system has another method of serialization which
  +    isn't in the above list then it may be worthwhile adding code
  +    for it (and submitting a patch back to Apache). The above
  +    <code>HAVE_METHOD_SERIALIZED_ACCEPT</code> defines specify
  +    which method is available and works on the platform (you can
  +    have more than one); <code>USE_METHOD_SERIALIZED_ACCEPT</code>
  +    is used to specify the default method (see the
  +    <code>AcceptMutex</code> directive).</p>
  +
  +    <p>Another solution that has been considered but never
  +    implemented is to partially serialize the loop -- that is, let
  +    in a certain number of processes. This would only be of
  +    interest on multiprocessor boxes where it's possible multiple
  +    children could run simultaneously, and the serialization
  +    actually doesn't take advantage of the full bandwidth. This is
  +    a possible area of future investigation, but priority remains
  +    low because highly parallel web servers are not the norm.</p>
  +
  +    <p>Ideally you should run servers without multiple
  +    <code>Listen</code> statements if you want the highest
  +    performance. But read on.</p>
  +
  +    <h4>accept Serialization - single socket</h4>
  +
  +    <p>The above is fine and dandy for multiple socket servers, but
  +    what about single socket servers? In theory they shouldn't
  +    experience any of these same problems because all children can
  +    just block in <code>accept(2)</code> until a connection
  +    arrives, and no starvation results. In practice this hides
  +    almost the same "spinning" behavior discussed above in the
  +    non-blocking solution. The way that most TCP stacks are
  +    implemented, the kernel actually wakes up all processes blocked
  +    in <code>accept</code> when a single connection arrives. One of
  +    those processes gets the connection and returns to user-space,
  +    the rest spin in the kernel and go back to sleep when they
  +    discover there's no connection for them. This spinning is
  +    hidden from the user-land code, but it's there nonetheless.
  +    This can result in the same load-spiking wasteful behavior
  +    that a non-blocking solution to the multiple sockets case
  +    can.</p>
  +
  +    <p>For this reason we have found that many architectures behave
  +    more "nicely" if we serialize even the single socket case. So
  +    this is actually the default in almost all cases. Crude
  +    experiments under Linux (2.0.30 on a dual Pentium pro 166
  +    w/128Mb RAM) have shown that the serialization of the single
  +    socket case causes less than a 3% decrease in requests per
  +    second over unserialized single-socket. But unserialized
  +    single-socket showed an extra 100ms latency on each request.
  +    This latency is probably a wash on long haul lines, and only an
  +    issue on LANs. If you want to override the single socket
  +    serialization you can define
  +    <code>SINGLE_LISTEN_UNSERIALIZED_ACCEPT</code> and then
  +    single-socket servers will not serialize at all.</p>
  +
  +    <h4>Lingering Close</h4>
  +
  +    <p>As discussed in <a
  +    href="http://www.ics.uci.edu/pub/ietf/http/draft-ietf-http-connection-00.txt">
  +    draft-ietf-http-connection-00.txt</a> section 8, in order for
  +    an HTTP server to <strong>reliably</strong> implement the
  +    protocol it needs to shutdown each direction of the
  +    communication independently (recall that a TCP connection is
  +    bi-directional, each half is independent of the other). This
  +    fact is often overlooked by other servers, but is correctly
  +    implemented in Apache as of 1.2.</p>
  +
  +    <p>When this feature was added to Apache it caused a flurry of
  +    problems on various versions of Unix because of a
  +    shortsightedness. The TCP specification does not state that the
  +    FIN_WAIT_2 state has a timeout, but it doesn't prohibit it. On
  +    systems without the timeout, Apache 1.2 induces many sockets
  +    stuck forever in the FIN_WAIT_2 state. In many cases this can
  +    be avoided by simply upgrading to the latest TCP/IP patches
  +    supplied by the vendor. In cases where the vendor has never
  +    released patches (<em>i.e.</em>, SunOS4 -- although folks with
  +    a source license can patch it themselves) we have decided to
  +    disable this feature.</p>
  +
  +    <p>There are two ways of accomplishing this. One is the socket
  +    option <code>SO_LINGER</code>. But as fate would have it, this
  +    has never been implemented properly in most TCP/IP stacks. Even
  +    on those stacks with a proper implementation (<em>i.e.</em>,
  +    Linux 2.0.31) this method proves to be more expensive (cputime)
  +    than the next solution.</p>
  +
  +    <p>For the most part, Apache implements this in a function
  +    called <code>lingering_close</code> (in
  +    <code>http_main.c</code>). The function looks roughly like
  +    this:</p>
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
       void lingering_close (int s)
       {
  -	char junk_buffer[2048];
  -
  -	/* shutdown the sending side */
  -	shutdown (s, 1);
  +    char junk_buffer[2048];
   
  -	signal (SIGALRM, lingering_death);
  -	alarm (30);
  +    /* shutdown the sending side */
  +    shutdown (s, 1);
   
  -	for (;;) {
  -	    select (s for reading, 2 second timeout);
  -	    if (error) break;
  -	    if (s is ready for reading) {
  -		if (read (s, junk_buffer, sizeof (junk_buffer)) &lt;= 0) {
  -		    break;
  -		}
  -		/* just toss away whatever is read */
  -	    }
  -	}
  +    signal (SIGALRM, lingering_death);
  +    alarm (30);
   
  -	close (s);
  +    for (;;) {
  +        select (s for reading, 2 second timeout);
  +        if (error) break;
  +        if (s is ready for reading) {
  +        if (read (s, junk_buffer, sizeof (junk_buffer)) &lt;= 0) {
  +            break;
  +        }
  +        /* just toss away whatever is read */
  +        }
       }
  -</PRE></BLOCKQUOTE>
  -
  -This naturally adds some expense at the end of a connection, but it
  -is required for a reliable implementation.  As HTTP/1.1 becomes more
  -prevalent, and all connections are persistent, this expense will be
  -amortized over more requests.  If you want to play with fire and
  -disable this feature you can define <CODE>NO_LINGCLOSE</CODE>, but
  -this is not recommended at all.  In particular, as HTTP/1.1 pipelined
  -persistent connections come into use <CODE>lingering_close</CODE>
  -is an absolute necessity (and
  -<A HREF="http://www.w3.org/Protocols/HTTP/Performance/Pipeline.html">
  -pipelined connections are faster</A>, so you
  -want to support them).
  -
  -<H4>Scoreboard File</H4>
  -
  -<P>Apache's parent and children communicate with each other through
  -something called the scoreboard.  Ideally this should be implemented
  -in shared memory.  For those operating systems that we either have
  -access to, or have been given detailed ports for, it typically is
  -implemented using shared memory.  The rest default to using an
  -on-disk file.  The on-disk file is not only slow, but it is unreliable
  -(and less featured).  Peruse the <CODE>src/main/conf.h</CODE> file
  -for your architecture and look for either <CODE>USE_MMAP_SCOREBOARD</CODE> or
  -<CODE>USE_SHMGET_SCOREBOARD</CODE>.  Defining one of those two (as
  -well as their companions <CODE>HAVE_MMAP</CODE> and <CODE>HAVE_SHMGET</CODE>
  -respectively) enables the supplied shared memory code.  If your system has
  -another type of shared memory, edit the file <CODE>src/main/http_main.c</CODE>
  -and add the hooks necessary to use it in Apache.  (Send us back a patch
  -too please.)
  -
  -<P>Historical note:  The Linux port of Apache didn't start to use
  -shared memory until version 1.2 of Apache.  This oversight resulted
  -in really poor and unreliable behaviour of earlier versions of Apache
  -on Linux.
  -
  -<H4><CODE>DYNAMIC_MODULE_LIMIT</CODE></H4>
  -
  -<P>If you have no intention of using dynamically loaded modules
  -(you probably don't if you're reading this and tuning your
  -server for every last ounce of performance) then you should add
  -<CODE>-DDYNAMIC_MODULE_LIMIT=0</CODE> when building your server.
  -This will save RAM that's allocated only for supporting dynamically
  -loaded modules.
   
  -<hr>
  -
  -<H3><a name="trace">Appendix: Detailed Analysis of a Trace</a></H3>
  -
  -Here is a system call trace of Apache 1.3 running on Linux.  The run-time
  -configuration file is essentially the default plus:
  +    close (s);
  +    }
  +</pre>
  +    </blockquote>
  +    This naturally adds some expense at the end of a connection,
  +    but it is required for a reliable implementation. As HTTP/1.1
  +    becomes more prevalent, and all connections are persistent,
  +    this expense will be amortized over more requests. If you want
  +    to play with fire and disable this feature you can define
  +    <code>NO_LINGCLOSE</code>, but this is not recommended at all.
  +    In particular, as HTTP/1.1 pipelined persistent connections
  +    come into use <code>lingering_close</code> is an absolute
  +    necessity (and <a
  +    href="http://www.w3.org/Protocols/HTTP/Performance/Pipeline.html">
  +    pipelined connections are faster</a>, so you want to support
  +    them). 
  +
  +    <h4>Scoreboard File</h4>
  +
  +    <p>Apache's parent and children communicate with each other
  +    through something called the scoreboard. Ideally this should be
  +    implemented in shared memory. For those operating systems that
  +    we either have access to, or have been given detailed ports
  +    for, it typically is implemented using shared memory. The rest
  +    default to using an on-disk file. The on-disk file is not only
  +    slow, but it is unreliable (and less featured). Peruse the
  +    <code>src/main/conf.h</code> file for your architecture and
  +    look for either <code>USE_MMAP_SCOREBOARD</code> or
  +    <code>USE_SHMGET_SCOREBOARD</code>. Defining one of those two
  +    (as well as their companions <code>HAVE_MMAP</code> and
  +    <code>HAVE_SHMGET</code> respectively) enables the supplied
  +    shared memory code. If your system has another type of shared
  +    memory, edit the file <code>src/main/http_main.c</code> and add
  +    the hooks necessary to use it in Apache. (Send us back a patch
  +    too please.)</p>
  +
  +    <p>Historical note: The Linux port of Apache didn't start to
  +    use shared memory until version 1.2 of Apache. This oversight
  +    resulted in really poor and unreliable behavior of earlier
  +    versions of Apache on Linux.</p>
  +
  +    <h4><code>DYNAMIC_MODULE_LIMIT</code></h4>
  +
  +    <p>If you have no intention of using dynamically loaded modules
  +    (you probably don't if you're reading this and tuning your
  +    server for every last ounce of performance) then you should add
  +    <code>-DDYNAMIC_MODULE_LIMIT=0</code> when building your
  +    server. This will save RAM that's allocated only for supporting
  +    dynamically loaded modules.</p>
  +    <hr />
  +
  +    <h3><a id="trace" name="trace">Appendix: Detailed Analysis of a
  +    Trace</a></h3>
  +    Here is a system call trace of Apache 1.3 running on Linux. The
  +    run-time configuration file is essentially the default plus: 
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   &lt;Directory /&gt;
       AllowOverride none
       Options FollowSymLinks
   &lt;/Directory&gt;
  -</PRE></BLOCKQUOTE>
  +</pre>
  +    </blockquote>
  +    The file being requested is a static 6K file of no particular
  +    content. Traces of non-static requests or requests with content
  +    negotiation look wildly different (and quite ugly in some
  +    cases). First the entire trace, then we'll examine details.
  +    (This was generated by the <code>strace</code> program, other
  +    similar programs include <code>truss</code>,
  +    <code>ktrace</code>, and <code>par</code>.) 
   
  -The file being requested is a static 6K file of no particular content.
  -Traces of non-static requests or requests with content negotiation
  -look wildly different (and quite ugly in some cases).  First the
  -entire trace, then we'll examine details.  (This was generated by
  -the <CODE>strace</CODE> program, other similar programs include
  -<CODE>truss</CODE>, <CODE>ktrace</CODE>, and <CODE>par</CODE>.)
  -
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   accept(15, {sin_family=AF_INET, sin_port=htons(22283), sin_addr=inet_addr("127.0.0.1")}, [16]) = 3
   flock(18, LOCK_UN)                      = 0
   sigaction(SIGUSR1, {SIG_IGN}, {0x8059954, [], SA_INTERRUPT}) = 0
  @@ -610,203 +685,232 @@
   sigaction(SIGUSR1, {0x8059954, [], SA_INTERRUPT}, {SIG_IGN}) = 0
   munmap(0x400ee000, 6144)                = 0
   flock(18, LOCK_EX)                      = 0
  -</PRE></BLOCKQUOTE>
  +</pre>
  +    </blockquote>
   
  -<P>Notice the accept serialization:
  +    <p>Notice the accept serialization:</p>
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   flock(18, LOCK_UN)                      = 0
   ...
   flock(18, LOCK_EX)                      = 0
  -</PRE></BLOCKQUOTE>
  -
  -These two calls can be removed by defining
  -<CODE>SINGLE_LISTEN_UNSERIALIZED_ACCEPT</CODE> as described earlier.
  +</pre>
  +    </blockquote>
  +    These two calls can be removed by defining
  +    <code>SINGLE_LISTEN_UNSERIALIZED_ACCEPT</code> as described
  +    earlier. 
   
  -<P>Notice the <CODE>SIGUSR1</CODE> manipulation:
  +    <p>Notice the <code>SIGUSR1</code> manipulation:</p>
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   sigaction(SIGUSR1, {SIG_IGN}, {0x8059954, [], SA_INTERRUPT}) = 0
   ...
   sigaction(SIGUSR1, {SIG_IGN}, {SIG_IGN}) = 0
   ...
   sigaction(SIGUSR1, {0x8059954, [], SA_INTERRUPT}, {SIG_IGN}) = 0
  -</PRE></BLOCKQUOTE>
  +</pre>
  +    </blockquote>
  +    This is caused by the implementation of graceful restarts. When
  +    the parent receives a <code>SIGUSR1</code> it sends a
  +    <code>SIGUSR1</code> to all of its children (and it also
  +    increments a "generation counter" in shared memory). Any
  +    children that are idle (between connections) will immediately
  +    die off when they receive the signal. Any children that are in
  +    keep-alive connections, but are in between requests will die
  +    off immediately. But any children that have a connection and
  +    are still waiting for the first request will not die off
  +    immediately. 
  +
  +    <p>To see why this is necessary, consider how a browser reacts
  +    to a closed connection. If the connection was a keep-alive
  +    connection and the request being serviced was not the first
  +    request then the browser will quietly reissue the request on a
  +    new connection. It has to do this because the server is always
  +    free to close a keep-alive connection in between requests
  +    (<em>i.e.</em>, due to a timeout or because of a maximum number
  +    of requests). But, if the connection is closed before the first
  +    response has been received the typical browser will display a
  +    "document contains no data" dialogue (or a broken image icon).
  +    This is done on the assumption that the server is broken in
  +    some way (or maybe too overloaded to respond at all). So Apache
  +    tries to avoid ever deliberately closing the connection before
  +    it has sent a single response. This is the cause of those
  +    <code>SIGUSR1</code> manipulations.</p>
  +
  +    <p>Note that it is theoretically possible to eliminate all
  +    three of these calls. But in rough tests the gain proved to be
  +    almost unnoticeable.</p>
   
  -This is caused by the implementation of graceful restarts.  When the
  -parent receives a <CODE>SIGUSR1</CODE> it sends a <CODE>SIGUSR1</CODE>
  -to all of its children (and it also increments a "generation counter"
  -in shared memory).  Any children that are idle (between connections)
  -will immediately die
  -off when they receive the signal.  Any children that are in keep-alive
  -connections, but are in between requests will die off immediately.  But
  -any children that have a connection and are still waiting for the first
  -request will not die off immediately.
  -
  -<P>To see why this is necessary, consider how a browser reacts to a closed
  -connection.  If the connection was a keep-alive connection and the request
  -being serviced was not the first request then the browser will quietly
  -reissue the request on a new connection.  It has to do this because the
  -server is always free to close a keep-alive connection in between requests
  -(<EM>i.e.</EM>, due to a timeout or because of a maximum number of requests).
  -But, if the connection is closed before the first response has been
  -received the typical browser will display a "document contains no data"
  -dialogue (or a broken image icon).  This is done on the assumption that
  -the server is broken in some way (or maybe too overloaded to respond
  -at all).  So Apache tries to avoid ever deliberately closing the connection
  -before it has sent a single response.  This is the cause of those
  -<CODE>SIGUSR1</CODE> manipulations.
  +    <p>In order to implement virtual hosts, Apache needs to know
  +    the local socket address used to accept the connection:</p>
   
  -<P>Note that it is theoretically possible to eliminate all three of
  -these calls.  But in rough tests the gain proved to be almost unnoticeable.
  -
  -<P>In order to implement virtual hosts, Apache needs to know the
  -local socket address used to accept the connection:
  -
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0
  -</PRE></BLOCKQUOTE>
  -
  -It is possible to eliminate this call in many situations (such as when
  -there are no virtual hosts, or when <CODE>Listen</CODE> directives are
  -used which do not have wildcard addresses).  But no effort has yet been
  -made to do these optimizations.
  +</pre>
  +    </blockquote>
  +    It is possible to eliminate this call in many situations (such
  +    as when there are no virtual hosts, or when <code>Listen</code>
  +    directives are used which do not have wildcard addresses). But
  +    no effort has yet been made to do these optimizations. 
   
  -<P>Apache turns off the Nagle algorithm:
  +    <p>Apache turns off the Nagle algorithm:</p>
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   setsockopt(3, IPPROTO_TCP1, [1], 4)     = 0
  -</PRE></BLOCKQUOTE>
  +</pre>
  +    </blockquote>
  +    because of problems described in <a
  +    href="http://www.isi.edu/~johnh/PAPERS/Heidemann97a.html">a
  +    paper by John Heidemann</a>. 
   
  -because of problems described in 
  -<A HREF="http://www.isi.edu/~johnh/PAPERS/Heidemann97a.html">a
  -paper by John Heidemann</A>.
  +    <p>Notice the two <code>time</code> calls:</p>
   
  -<P>Notice the two <CODE>time</CODE> calls:
  -
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   time(NULL)                              = 873959960
   ...
   time(NULL)                              = 873959960
  -</PRE></BLOCKQUOTE>
  -
  -One of these occurs at the beginning of the request, and the other occurs
  -as a result of writing the log.  At least one of these is required to
  -properly implement the HTTP protocol.  The second occurs because the
  -Common Log Format dictates that the log record include a timestamp of the
  -end of the request.  A custom logging module could eliminate one of the
  -calls.  Or you can use a method which moves the time into shared memory,
  -see the <A HREF="#patches">patches section below</A>.
  +</pre>
  +    </blockquote>
  +    One of these occurs at the beginning of the request, and the
  +    other occurs as a result of writing the log. At least one of
  +    these is required to properly implement the HTTP protocol. The
  +    second occurs because the Common Log Format dictates that the
  +    log record include a timestamp of the end of the request. A
  +    custom logging module could eliminate one of the calls. Or you
  +    can use a method which moves the time into shared memory, see
  +    the <a href="#patches">patches section below</a>. 
  +
  +    <p>As described earlier, <code>ExtendedStatus On</code> causes
  +    two <code>gettimeofday</code> calls and a call to
  +    <code>times</code>:</p>
   
  -<P>As described earlier, <CODE>ExtendedStatus On</CODE> causes two
  -<CODE>gettimeofday</CODE> calls and a call to <CODE>times</CODE>:
  -
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   gettimeofday({873959960, 404935}, NULL) = 0
   ...
   gettimeofday({873959960, 417742}, NULL) = 0
   times({tms_utime=5, tms_stime=0, tms_cutime=0, tms_cstime=0}) = 446747
  -</PRE></BLOCKQUOTE>
  -
  -These can be removed by setting <CODE>ExtendedStatus Off</CODE> (which
  -is the default).
  +</pre>
  +    </blockquote>
  +    These can be removed by setting <code>ExtendedStatus Off</code>
  +    (which is the default). 
   
  -<P>It might seem odd to call <CODE>stat</CODE>:
  +    <p>It might seem odd to call <code>stat</code>:</p>
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   stat("/home/dgaudet/ap/apachen/htdocs/6k", {st_mode=S_IFREG|0644, st_size=6144, ...}) = 0
  -</PRE></BLOCKQUOTE>
  -
  -This is part of the algorithm which calculates the
  -<CODE>PATH_INFO</CODE> for use by CGIs.  In fact if the request had been
  -for the URI <CODE>/cgi-bin/printenv/foobar</CODE> then there would be
  -two calls to <CODE>stat</CODE>.  The first for
  -<CODE>/home/dgaudet/ap/apachen/cgi-bin/printenv/foobar</CODE>
  -which does not exist, and the second for
  -<CODE>/home/dgaudet/ap/apachen/cgi-bin/printenv</CODE>, which does exist.
  -Regardless, at least one <CODE>stat</CODE> call is necessary when
  -serving static files because the file size and modification times are
  -used to generate HTTP headers (such as <CODE>Content-Length</CODE>,
  -<CODE>Last-Modified</CODE>) and implement protocol features (such
  -as <CODE>If-Modified-Since</CODE>).  A somewhat more clever server
  -could avoid the <CODE>stat</CODE> when serving non-static files,
  -however doing so in Apache is very difficult given the modular structure.
  +</pre>
  +    </blockquote>
  +    This is part of the algorithm which calculates the
  +    <code>PATH_INFO</code> for use by CGIs. In fact if the request
  +    had been for the URI <code>/cgi-bin/printenv/foobar</code> then
  +    there would be two calls to <code>stat</code>. The first for
  +    <code>/home/dgaudet/ap/apachen/cgi-bin/printenv/foobar</code>
  +    which does not exist, and the second for
  +    <code>/home/dgaudet/ap/apachen/cgi-bin/printenv</code>, which
  +    does exist. Regardless, at least one <code>stat</code> call is
  +    necessary when serving static files because the file size and
  +    modification times are used to generate HTTP headers (such as
  +    <code>Content-Length</code>, <code>Last-Modified</code>) and
  +    implement protocol features (such as
  +    <code>If-Modified-Since</code>). A somewhat more clever server
  +    could avoid the <code>stat</code> when serving non-static
  +    files, however doing so in Apache is very difficult given the
  +    modular structure. 
   
  -<P>All static files are served using <CODE>mmap</CODE>:
  +    <p>All static files are served using <code>mmap</code>:</p>
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   mmap(0, 6144, PROT_READ, MAP_PRIVATE, 4, 0) = 0x400ee000
   ...
   munmap(0x400ee000, 6144)                = 0
  -</PRE></BLOCKQUOTE>
  +</pre>
  +    </blockquote>
  +    On some architectures it's slower to <code>mmap</code> small
  +    files than it is to simply <code>read</code> them. The define
  +    <code>MMAP_THRESHOLD</code> can be set to the minimum size
  +    required before using <code>mmap</code>. By default it's set to
  +    0 (except on SunOS4 where experimentation has shown 8192 to be
  +    a better value). Using a tool such as <a
  +    href="http://www.bitmover.com/lmbench/">lmbench</a> you can
  +    determine the optimal setting for your environment. 
  +
  +    <p>You may also wish to experiment with
  +    <code>MMAP_SEGMENT_SIZE</code> (default 32768) which determines
  +    the maximum number of bytes that will be written at a time from
  +    mmap()d files. Apache only resets the client's
  +    <code>Timeout</code> in between write()s. So setting this large
  +    may lock out low bandwidth clients unless you also increase the
  +    <code>Timeout</code>.</p>
  +
  +    <p>It may even be the case that <code>mmap</code> isn't used on
  +    your architecture; if so then defining
  +    <code>USE_MMAP_FILES</code> and <code>HAVE_MMAP</code> might
  +    work (if it works then report back to us).</p>
  +
  +    <p>Apache does its best to avoid copying bytes around in
  +    memory. The first write of any request typically is turned into
  +    a <code>writev</code> which combines both the headers and the
  +    first hunk of data:</p>
   
  -On some architectures it's slower to <CODE>mmap</CODE> small
  -files than it is to simply <CODE>read</CODE> them.  The define
  -<CODE>MMAP_THRESHOLD</CODE> can be set to the minimum
  -size required before using <CODE>mmap</CODE>.  By default
  -it's set to 0 (except on SunOS4 where experimentation has
  -shown 8192 to be a better value).  Using a tool such as <A
  -HREF="http://www.bitmover.com/lmbench/">lmbench</A> you
  -can determine the optimal setting for your environment.
  -
  -<P>You may also wish to experiment with <CODE>MMAP_SEGMENT_SIZE</CODE>
  -(default 32768) which determines the maximum number of bytes that
  -will be written at a time from mmap()d files.  Apache only resets the
  -client's <CODE>Timeout</CODE> in between write()s.  So setting this
  -large may lock out low bandwidth clients unless you also increase the
  -<CODE>Timeout</CODE>.
  -
  -<P>It may even be the case that <CODE>mmap</CODE> isn't
  -used on your architecture; if so then defining <CODE>USE_MMAP_FILES</CODE>
  -and <CODE>HAVE_MMAP</CODE> might work (if it works then report back to us).
  -
  -<P>Apache does its best to avoid copying bytes around in memory.  The
  -first write of any request typically is turned into a <CODE>writev</CODE>
  -which combines both the headers and the first hunk of data:
  -
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   writev(3, [{"HTTP/1.1 200 OK\r\nDate: Thu, 11"..., 245}, {"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 6144}], 2) = 6389
  -</PRE></BLOCKQUOTE>
  -
  -When doing HTTP/1.1 chunked encoding Apache will generate up to four
  -element <CODE>writev</CODE>s.  The goal is to push the byte copying
  -into the kernel, where it typically has to happen anyhow (to assemble
  -network packets).  On testing, various Unixes (BSDI 2.x, Solaris 2.5,
  -Linux 2.0.31+) properly combine the elements into network packets.
  -Pre-2.0.31 Linux will not combine, and will create a packet for
  -each element, so upgrading is a good idea.  Defining <CODE>NO_WRITEV</CODE>
  -will disable this combining, but result in very poor chunked encoding
  -performance.
  +</pre>
  +    </blockquote>
  +    When doing HTTP/1.1 chunked encoding Apache will generate up to
  +    four element <code>writev</code>s. The goal is to push the byte
  +    copying into the kernel, where it typically has to happen
  +    anyhow (to assemble network packets). On testing, various
  +    Unixes (BSDI 2.x, Solaris 2.5, Linux 2.0.31+) properly combine
  +    the elements into network packets. Pre-2.0.31 Linux will not
  +    combine, and will create a packet for each element, so
  +    upgrading is a good idea. Defining <code>NO_WRITEV</code> will
  +    disable this combining, but result in very poor chunked
  +    encoding performance. 
   
  -<P>The log write:
  +    <p>The log write:</p>
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   write(17, "127.0.0.1 - - [10/Sep/1997:23:39"..., 71) = 71
  -</PRE></BLOCKQUOTE>
  +</pre>
  +    </blockquote>
  +    can be deferred by defining <code>BUFFERED_LOGS</code>. In this
  +    case up to <code>PIPE_BUF</code> bytes (a POSIX defined
  +    constant) of log entries are buffered before writing. At no
  +    time does it split a log entry across a <code>PIPE_BUF</code>
  +    boundary because those writes may not be atomic.
  +    (<em>i.e.</em>, entries from multiple children could become
  +    mixed together). The code does its best to flush this buffer
  +    when a child dies. 
   
  -can be deferred by defining <CODE>BUFFERED_LOGS</CODE>.  In this case
  -up to <CODE>PIPE_BUF</CODE> bytes (a POSIX defined constant) of log entries
  -are buffered before writing.  At no time does it split a log entry
  -across a <CODE>PIPE_BUF</CODE> boundary because those writes may not
  -be atomic.  (<EM>i.e.</EM>, entries from multiple children could become mixed together).
  -The code does its best to flush this buffer when a child dies.
  +    <p>The lingering close code causes four system calls:</p>
   
  -<P>The lingering close code causes four system calls:
  -
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   shutdown(3, 1 /* send */)               = 0
   oldselect(4, [3], NULL, [3], {2, 0})    = 1 (in [3], left {2, 0})
   read(3, "", 2048)                       = 0
   close(3)                                = 0
  -</PRE></BLOCKQUOTE>
  -
  -which were described earlier.
  -
  -<P>Let's apply some of these optimizations:
  -<CODE>-DSINGLE_LISTEN_UNSERIALIZED_ACCEPT -DBUFFERED_LOGS</CODE> and
  -<CODE>ExtendedStatus Off</CODE>.  Here's the final trace:
  +</pre>
  +    </blockquote>
  +    which were described earlier. 
  +
  +    <p>Let's apply some of these optimizations:
  +    <code>-DSINGLE_LISTEN_UNSERIALIZED_ACCEPT
  +    -DBUFFERED_LOGS</code> and <code>ExtendedStatus Off</code>.
  +    Here's the final trace:</p>
   
  -<BLOCKQUOTE><PRE>
  +    <blockquote>
  +<pre>
   accept(15, {sin_family=AF_INET, sin_port=htons(22286), sin_addr=inet_addr("127.0.0.1")}, [16]) = 3
   sigaction(SIGUSR1, {SIG_IGN}, {0x8058c98, [], SA_INTERRUPT}) = 0
   getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0
  @@ -826,85 +930,94 @@
   close(3)                                = 0
   sigaction(SIGUSR1, {0x8058c98, [], SA_INTERRUPT}, {SIG_IGN}) = 0
   munmap(0x400e3000, 6144)                = 0
  -</PRE></BLOCKQUOTE>
  -
  -That's 19 system calls, of which 4 remain relatively easy to remove,
  -but don't seem worth the effort.
  -
  -<H3><A NAME="patches">Appendix: Patches Available</A></H3>
  +</pre>
  +    </blockquote>
  +    That's 19 system calls, of which 4 remain relatively easy to
  +    remove, but don't seem worth the effort. 
  +
  +    <h3><a id="patches" name="patches">Appendix: Patches
  +    Available</a></h3>
  +    There are <a
  +    href="http://www.arctic.org/~dgaudet/apache/1.3/">several
  +    performance patches available for 1.3.</a> Although they may
  +    not apply cleanly to the current version, it shouldn't be
  +    difficult for someone with a little C knowledge to update them.
  +    In particular: 
  +
  +    <ul>
  +      <li>A <a
  +      href="http://www.arctic.org/~dgaudet/apache/1.3/shared_time.patch">
  +      patch</a> to remove all <code>time(2)</code> system
  +      calls.</li>
  +
  +      <li>A <a
  +      href="http://www.arctic.org/~dgaudet/apache/1.3/mod_include_speedups.patch">
  +      patch</a> to remove various system calls from
  +      <code>mod_include</code>, these calls are used by few sites
  +      but required for backwards compatibility.</li>
  +
  +      <li>A <a
  +      href="http://www.arctic.org/~dgaudet/apache/1.3/top_fuel.patch">
  +      patch</a> which integrates the above two plus a few other
  +      speedups at the cost of removing some functionality.</li>
  +    </ul>
  +
  +    <h3><a id="preforking" name="preforking">Appendix: The
  +    Pre-Forking Model</a></h3>
  +
  +    <p>Apache (on Unix) is a <em>pre-forking</em> model server. The
  +    <em>parent</em> process is responsible only for forking
  +    <em>child</em> processes, it does not serve any requests or
  +    service any network sockets. The child processes actually
  +    process connections, they serve multiple connections (one at a
  +    time) before dying. The parent spawns new or kills off old
  +    children in response to changes in the load on the server (it
  +    does so by monitoring a scoreboard which the children keep up
  +    to date).</p>
  +
  +    <p>This model for servers offers a robustness that other models
  +    do not. In particular, the parent code is very simple, and with
  +    a high degree of confidence the parent will continue to do its
  +    job without error. The children are complex, and when you add
  +    in third party code via modules, you risk segmentation faults
  +    and other forms of corruption. Even should such a thing happen,
  +    it only affects one connection and the server continues serving
  +    requests. The parent quickly replaces the dead child.</p>
  +
  +    <p>Pre-forking is also very portable across dialects of Unix.
  +    Historically this has been an important goal for Apache, and it
  +    continues to remain so.</p>
  +
  +    <p>The pre-forking model comes under criticism for various
  +    performance aspects. Of particular concern are the overhead of
  +    forking a process, the overhead of context switches between
  +    processes, and the memory overhead of having multiple
  +    processes. Furthermore it does not offer as many opportunities
  +    for data-caching between requests (such as a pool of
  +    <code>mmapped</code> files). Various other models exist and
  +    extensive analysis can be found in the <a
  +    href="http://www.cs.wustl.edu/~jxh/research/research.html">papers
  +    of the JAWS project</a>. In practice all of these costs vary
  +    drastically depending on the operating system.</p>
  +
  +    <p>Apache's core code is already multithread aware, and Apache
  +    version 1.3 is multithreaded on NT. There have been at least
  +    two other experimental implementations of threaded Apache, one
  +    using the 1.3 code base on DCE, and one using a custom
  +    user-level threads package and the 1.0 code base; neither is
  +    publicly available. There is also an experimental port of
  +    Apache 1.3 to <a
  +    href="http://www.mozilla.org/docs/refList/refNSPR/">Netscape's
  +    Portable Run Time</a>, which <a
  +    href="http://www.arctic.org/~dgaudet/apache/2.0/">is
  +    available</a> (but you're encouraged to join the <a
  +    href="http://dev.apache.org/mailing-lists">new-httpd mailing
  +    list</a> if you intend to use it). Part of our redesign for
  +    version 2.0 of Apache will include abstractions of the server
  +    model so that we can continue to support the pre-forking model,
  +    and also support various threaded models. 
  +    <!--#include virtual="footer.html" -->
  +    </p>
  +  </body>
  +</html>
   
  -There are
  -<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/">
  -several performance patches available for 1.3.</A>  Although they may
  -not apply cleanly to the current version,
  -it shouldn't be difficult for someone with a little C knowledge to
  -update them.  In particular:
  -
  -<UL>
  -<LI>A 
  -<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/shared_time.patch"
  ->patch</A> to remove all <CODE>time(2)</CODE> system calls.
  -<LI>A
  -<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/mod_include_speedups.patch"
  ->patch</A> to remove various system calls from <CODE>mod_include</CODE>,
  -these calls are used by few sites but required for backwards compatibility.
  -<LI>A
  -<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/top_fuel.patch"
  ->patch</A> which integrates the above two plus a few other speedups at the
  -cost of removing some functionality.
  -</UL>
  -
  -<H3><a name="preforking">Appendix: The Pre-Forking Model</a></H3>
  -
  -<P>Apache (on Unix) is a <EM>pre-forking</EM> model server.  The
  -<EM>parent</EM> process is responsible only for forking <EM>child</EM>
  -processes, it does not serve any requests or service any network
  -sockets.  The child processes actually process connections, they serve
  -multiple connections (one at a time) before dying.
  -The parent spawns new or kills off old
  -children in response to changes in the load on the server (it does so
  -by monitoring a scoreboard which the children keep up to date).
  -
  -<P>This model for servers offers a robustness that other models do
  -not.  In particular, the parent code is very simple, and with a high
  -degree of confidence the parent will continue to do its job without
  -error.  The children are complex, and when you add in third party
  -code via modules, you risk segmentation faults and other forms of
  -corruption.  Even should such a thing happen, it only affects one
  -connection and the server continues serving requests.  The parent
  -quickly replaces the dead child.
  -
  -<P>Pre-forking is also very portable across dialects of Unix.
  -Historically this has been an important goal for Apache, and it continues
  -to remain so.
  -
  -<P>The pre-forking model comes under criticism for various
  -performance aspects.  Of particular concern are the overhead
  -of forking a process, the overhead of context switches between
  -processes, and the memory overhead of having multiple processes.
  -Furthermore it does not offer as many opportunities for data-caching
  -between requests (such as a pool of <CODE>mmapped</CODE> files).
  -Various other models exist and extensive analysis can be found in the
  -<A HREF="http://www.cs.wustl.edu/~jxh/research/research.html"> papers
  -of the JAWS project</A>.  In practice all of these costs vary drastically
  -depending on the operating system.
  -
  -<P>Apache's core code is already multithread aware, and Apache version
  -1.3 is multithreaded on NT.  There have been at least two other experimental
  -implementations of threaded Apache, one using the 1.3 code base on DCE,
  -and one using a custom user-level threads package and the 1.0 code base;
  -neither is publicly available.  There is also an experimental port of
  -Apache 1.3 to <A HREF="http://www.mozilla.org/docs/refList/refNSPR/">
  -Netscape's Portable Run Time</A>, which
  -<A HREF="http://www.arctic.org/~dgaudet/apache/2.0/">is available</A>
  -(but you're encouraged to join the
  -<A HREF="http://dev.apache.org/mailing-lists">new-httpd mailing list</A>
  -if you intend to use it).
  -Part of our redesign for version 2.0
  -of Apache will include abstractions of the server model so that we
  -can continue to support the pre-forking model, and also support various
  -threaded models.
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  
  
  
  1.26      +165 -173  httpd-docs-1.3/htdocs/manual/misc/perf.html
  
  Index: perf.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/perf.html,v
  retrieving revision 1.25
  retrieving revision 1.26
  diff -u -r1.25 -r1.26
  --- perf.html	2000/08/19 01:52:50	1.25
  +++ perf.html	2001/10/08 01:26:54	1.26
  @@ -1,176 +1,168 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>Hints on Running a High-Performance Web Server</TITLE>
  -</HEAD>
  -
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Hints on Running a High-Performance Web Server</H1>
  -
  -Running Apache on a heavily loaded web server, one often encounters
  -problems related to the machine and OS configuration.  "Heavy" is
  -relative, of course - but if you are seeing more than a couple hits
  -per second on a sustained basis you should consult the pointers on
  -this page.  In general the suggestions involve how to tune your kernel
  -for the heavier TCP load, hardware/software conflicts that arise, <EM>etc.</EM>
  -
  -<UL>
  -<LI><A HREF="#AUX">A/UX (Apple's UNIX)</A>
  -<LI><A HREF="#BSD">BSD-based (BSDI, FreeBSD, etc)</A>
  -<LI><A HREF="#DEC">Digital UNIX</A>
  -<LI><A HREF="perf-hp.html">HPUX</A>
  -<LI><A HREF="#Linux">Linux</A>
  -<LI><A HREF="#Solaris">Solaris</A>
  -<LI><A HREF="#SunOS">SunOS 4.x</A>
  -<LI><A HREF="#SVR4">SVR4</A>
  -</UL>
  -
  -<HR>
  -
  -<H3><A NAME="AUX">
  -A/UX (Apple's UNIX)
  -</A></H3>
  -
  -If you are running Apache on A/UX, a page that gives some helpful
  -performance hints (concerning the <EM>listen()</EM> queue and using
  -virtual hosts)
  -<A HREF="http://www.jaguNET.com/apache.html">can be found here</A>
  -
  -<P><HR>
  -
  -<H3><A NAME="BSD">
  -BSD-based (BSDI, FreeBSD, etc)
  -</A></H3>
  -
  -<A HREF="perf-bsd44.html#initial">Quick</A> and
  -<A HREF="perf-bsd44.html#detail">detailed</A>
  -performance tuning hints for BSD-derived systems.
  -<A HREF="perf-bsd44.html#accf">Accept filtering</A> on FreeBSD.
  -
  -<P><HR>
  -
  -<H3><A NAME="DEC">
  -Digital UNIX
  -</A></H3>
  -
  -<UL>
  -  <LI><A
  -       HREF="http://www.digital.com/info/internet/document/ias/tuning.html"
  -      >DIGITAL UNIX Tuning Parameters for Web Servers</A>
  -  <LI>We have some <A HREF="perf-dec.html">newsgroup postings</A> on how
  -      to tune Digital UNIX 3.2 and 4.0.
  -</UL>
  -
  -<P><HR>
  -
  -<H3><A NAME="Linux">
  -Linux
  -</A></H3>
  -
  -There are no known problems with heavily loaded systems running Linux
  -kernels 2.0.32 or later.  Earlier kernels have some problems, and an
  -upgrade to the latest 2.0.x is a good idea to eliminate various security
  -and denial of service attacks.
  -
  -<P><HR>
  -
  -<H3><A NAME="Solaris">
  -Solaris 2.4
  -</A></H3>
  -
  -The Solaris 2.4 TCP implementation has a few inherent limitations that
  -only became apparent under heavy loads.  This has been fixed to some
  -extent in 2.5 (and completely revamped in 2.6), but for now consult
  -the following URL for tips on how to expand the capabilities if you
  -are finding slowdowns and lags are hurting performance.
  -
  -<P>
  -
  -Other links:
  -
  -<UL>
  -
  -<LI><A HREF="http://www.sun.com/sun-on-net/performance.html">
  -World Wide Web Server Performance,
  -&lt;http://www.sun.com/sun-on-net/performance.html&gt;</A>
  -<LI><A HREF="http://www.rvs.uni-hannover.de/people/voeckler/tune/EN/tune.html">
  -Solaris 2.x - tuning your TCP/IP stack</A> contains some good technical
  -information about tuning various Solaris TCP/IP parameters.
  -</UL>
  -
  -<P><HR>
  -
  -<H3><A NAME="SunOS">
  -SunOS 4.x
  -</A></H3>
  -
  -More information on tuning SOMAXCONN on SunOS can be found at
  -<A HREF="http://www.islandnet.com/~mark/somaxconn.html">
  -http://www.islandnet.com/~mark/somaxconn.html</A>.
  -
  -<P><HR>
  -
  -<H3><A NAME="SVR4">
  -SVR4
  -</A></H3>
  -
  -Some SVR4 versions waste three system calls on every
  -<SAMP>gettimeofday()</SAMP> call. Depending on the syntactic
  -form of the <SAMP>TZ</SAMP> environment variable, these
  -systems have several different algorithms to determine the
  -local time zone (presumably <EM>compatible</EM> with
  -something). The following example uses the central european
  -time zone to demonstrate this:
  -<DL>
  - <DT><STRONG>TZ=:MET</STRONG>
  - <DD>This form delegates the knowledge of the time zone
  -     information to an external compiled zoneinfo file
  -     (&agrave; la BSD).<BR>
  -     <STRONG>Caveat:</STRONG> Each time the gettimeofday()
  -     function is called, the external zone info is read in
  -     again (at least on some SVR4 systems). That results in
  -     three wasted system calls with every apache request
  -     served.<PRE>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  +
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Hints on Running a High-Performance Web Server</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Hints on Running a High-Performance Web
  +    Server</h1>
  +    Running Apache on a heavily loaded web server, one often
  +    encounters problems related to the machine and OS
  +    configuration. "Heavy" is relative, of course - but if you are
  +    seeing more than a couple hits per second on a sustained basis
  +    you should consult the pointers on this page. In general the
  +    suggestions involve how to tune your kernel for the heavier TCP
  +    load, hardware/software conflicts that arise, <em>etc.</em> 
  +
  +    <ul>
  +      <li><a href="#AUX">A/UX (Apple's UNIX)</a></li>
  +
  +      <li><a href="#BSD">BSD-based (BSDI, FreeBSD, etc)</a></li>
  +
  +      <li><a href="#DEC">Digital UNIX</a></li>
  +
  +      <li><a href="perf-hp.html">HPUX</a></li>
  +
  +      <li><a href="#Linux">Linux</a></li>
  +
  +      <li><a href="#Solaris">Solaris</a></li>
  +
  +      <li><a href="#SunOS">SunOS 4.x</a></li>
  +
  +      <li><a href="#SVR4">SVR4</a></li>
  +    </ul>
  +    <hr />
  +
  +    <h3><a id="AUX" name="AUX">A/UX (Apple's UNIX)</a></h3>
  +    If you are running Apache on A/UX, a page that gives some
  +    helpful performance hints (concerning the <em>listen()</em>
  +    queue and using virtual hosts) <a
  +    href="http://www.jaguNET.com/apache.html">can be found here</a>
  +    
  +    <hr />
  +
  +    <h3><a id="BSD" name="BSD">BSD-based (BSDI, FreeBSD,
  +    etc)</a></h3>
  +    <a href="perf-bsd44.html#initial">Quick</a> and <a
  +    href="perf-bsd44.html#detail">detailed</a> performance tuning
  +    hints for BSD-derived systems. <a
  +    href="perf-bsd44.html#accf">Accept filtering</a> on FreeBSD. 
  +    <hr />
  +
  +    <h3><a id="DEC" name="DEC">Digital UNIX</a></h3>
  +
  +    <ul>
  +      <li><a
  +      href="http://www.digital.com/info/internet/document/ias/tuning.html">
  +      DIGITAL UNIX Tuning Parameters for Web Servers</a></li>
  +
  +      <li>We have some <a href="perf-dec.html">newsgroup
  +      postings</a> on how to tune Digital UNIX 3.2 and 4.0.</li>
  +    </ul>
  +    <hr />
  +
  +    <h3><a id="Linux" name="Linux">Linux</a></h3>
  +    There are no known problems with heavily loaded systems running
  +    Linux kernels 2.0.32 or later. Earlier kernels have some
  +    problems, and an upgrade to the latest 2.0.x is a good idea to
  +    eliminate various security and denial of service attacks. 
  +    <hr />
  +
  +    <h3><a id="Solaris" name="Solaris">Solaris 2.4</a></h3>
  +    The Solaris 2.4 TCP implementation has a few inherent
  +    limitations that only became apparent under heavy loads. This
  +    has been fixed to some extent in 2.5 (and completely revamped
  +    in 2.6), but for now consult the following URL for tips on how
  +    to expand the capabilities if you are finding slowdowns and
  +    lags are hurting performance. 
  +
  +    <p>Other links:</p>
  +
  +    <ul>
  +      <li><a
  +      href="http://www.sun.com/sun-on-net/performance.html">World
  +      Wide Web Server Performance,
  +      &lt;http://www.sun.com/sun-on-net/performance.html&gt;</a></li>
  +
  +      <li><a
  +      href="http://www.rvs.uni-hannover.de/people/voeckler/tune/EN/tune.html">
  +      Solaris 2.x - tuning your TCP/IP stack</a> contains some good
  +      technical information about tuning various Solaris TCP/IP
  +      parameters.</li>
  +    </ul>
  +    <hr />
  +
  +    <h3><a id="SunOS" name="SunOS">SunOS 4.x</a></h3>
  +    More information on tuning SOMAXCONN on SunOS can be found at
  +    <a
  +    href="http://www.islandnet.com/~mark/somaxconn.html">http://www.islandnet.com/~mark/somaxconn.html</a>.
  +    
  +    <hr />
  +
  +    <h3><a id="SVR4" name="SVR4">SVR4</a></h3>
  +    Some SVR4 versions waste three system calls on every
  +    <samp>gettimeofday()</samp> call. Depending on the syntactic
  +    form of the <samp>TZ</samp> environment variable, these systems
  +    have several different algorithms to determine the local time
  +    zone (presumably <em>compatible</em> with something). The
  +    following example uses the central european time zone to
  +    demonstrate this: 
  +
  +    <dl>
  +      <dt><strong>TZ=:MET</strong></dt>
  +
  +      <dd>
  +        This form delegates the knowledge of the time zone
  +        information to an external compiled zoneinfo file (&agrave;
  +        la BSD).<br />
  +         <strong>Caveat:</strong> Each time the gettimeofday()
  +        function is called, the external zone info is read in again
  +        (at least on some SVR4 systems). That results in three
  +        wasted system calls with every apache request served. 
  +<pre>
        open("/usr/lib/locale/TZ/MET", O_RDONLY) = 3
        read(3, "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 7944) = 778
  -     close(3)                                = 0</PRE>
  -
  - <DT><STRONG>TZ=MET-1MDT,M3.5.0/02:00:00,M10.5.0/03:00:00</STRONG>
  - <DD>This syntax form (&agrave; la SYSV) contains all the
  -     knowledge about time zone beginning and ending times in
  -     its external representation. It has to be parsed each
  -     time it is evaluated, resulting in a slight computing
  -     overhead, but it requires no system call. Though the
  -     table lookup &agrave; la BSD is the more sophisticated
  -     technical solution, the bad SVR4 implementation makes
  -     this the preferred syntax on systems which otherwise
  -     access the external zone info file repeatedly.
  -</DL>
  -You should use the <SAMP>truss</SAMP> utility on a
  -single-process apache server (started with the <SAMP>-X</SAMP>
  -debugging switch) to determine whether your system can profit
  -from the second form of the <SAMP>TZ</SAMP> environment
  -variable. If it does, you could integrate the setting of the
  -preferred <SAMP>TZ</SAMP> syntax into the httpd startup
  -script, which is usually simply a copy of (or symbolic link
  -to) the <SAMP>apachectl</SAMP> utility script, or into the
  -system's <SAMP>/etc/TIMEZONE</SAMP> script.
  -
  -<P><HR>
  -
  -<H3>More welcome!</H3>
  -
  -If you have tips to contribute, send mail to <A
  -HREF="mailto:apache@apache.org">apache@apache.org</A>
  -
  -<!--#include virtual="footer.html" -->
  -</BODY></HTML>
  +     close(3)                                = 0
  +</pre>
  +      </dd>
  +
  +      <dt>
  +      <strong>TZ=MET-1MDT,M3.5.0/02:00:00,M10.5.0/03:00:00</strong></dt>
  +
  +      <dd>This syntax form (&agrave; la SYSV) contains all the
  +      knowledge about time zone beginning and ending times in its
  +      external representation. It has to be parsed each time it is
  +      evaluated, resulting in a slight computing overhead, but it
  +      requires no system call. Though the table lookup &agrave; la
  +      BSD is the more sophisticated technical solution, the bad
  +      SVR4 implementation makes this the preferred syntax on
  +      systems which otherwise access the external zone info file
  +      repeatedly.</dd>
  +    </dl>
  +    You should use the <samp>truss</samp> utility on a
  +    single-process apache server (started with the <samp>-X</samp>
  +    debugging switch) to determine whether your system can profit
  +    from the second form of the <samp>TZ</samp> environment
  +    variable. If it does, you could integrate the setting of the
  +    preferred <samp>TZ</samp> syntax into the httpd startup script,
  +    which is usually simply a copy of (or symbolic link to) the
  +    <samp>apachectl</samp> utility script, or into the system's
  +    <samp>/etc/TIMEZONE</samp> script. 
  +    <hr />
  +
  +    <h3>More welcome!</h3>
  +    If you have tips to contribute, send mail to <a
  +    href="mailto:apache@apache.org">apache@apache.org</a> 
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
   
  
  
  
  1.14      +1877 -1396httpd-docs-1.3/htdocs/manual/misc/rewriteguide.html
  
  Index: rewriteguide.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/rewriteguide.html,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -r1.13 -r1.14
  --- rewriteguide.html	2001/10/01 08:21:44	1.13
  +++ rewriteguide.html	2001/10/08 01:26:54	1.14
  @@ -1,114 +1,129 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML><HEAD>
  -<TITLE>Apache 1.3 URL Rewriting Guide</TITLE>
  -</HEAD>
  -
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<BLOCKQUOTE>
  -<!--#include virtual="header.html" -->
  -
  -<DIV ALIGN=CENTER>
  -
  -<H1>
  -Apache 1.3<BR>
  -URL Rewriting Guide<BR>
  -</H1>
  -
  -<ADDRESS>Originally written by<BR>
  -Ralf S. Engelschall &lt;rse@apache.org&gt;<BR>
  -December 1997</ADDRESS>
  -
  -</DIV>
  -
  -<P>
  -This document supplements the mod_rewrite <A
  -HREF="../mod/mod_rewrite.html">reference documentation</A>. It describes
  -how one can use Apache's mod_rewrite to solve typical URL-based problems
  -webmasters are usually confronted with in practice. I give detailed
  -descriptions on how to solve each problem by configuring URL rewriting
  -rulesets.
  -
  -<H2><A name="ToC1">Introduction to mod_rewrite</A></H2>
  -
  -The Apache module mod_rewrite is a killer one, i.e. it is a really
  -sophisticated module which provides a powerful way to do URL manipulations.
  -With it you can nearly do all types of URL manipulations you ever dreamed
  -about. The price you have to pay is to accept complexity, because
  -mod_rewrite's major drawback is that it is not easy to understand and use for
  -the beginner. And even Apache experts sometimes discover new aspects where
  -mod_rewrite can help.
  -<P>
  -In other words: With mod_rewrite you either shoot yourself in the foot the
  -first time and never use it again or love it for the rest of your life because
  -of its power. This paper tries to give you a few initial success events to
  -avoid the first case by presenting already invented solutions to you.
  -
  -<H2><A name="ToC2">Practical Solutions</A></H2>
  -
  -Here come a lot of practical solutions I've either invented myself or
  -collected from other peoples solutions in the past. Feel free to learn the
  -black magic of URL rewriting from these examples.
  -
  -<P>
  -<TABLE BGCOLOR="#FFE0E0" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD>
  -ATTENTION: Depending on your server-configuration it can be necessary to
  -slightly change the examples for your situation, e.g. adding the [PT] flag
  -when additionally using mod_alias and mod_userdir, etc. Or rewriting a ruleset
  -to fit in <CODE>.htaccess</CODE> context instead of per-server context. Always try
  -to understand what a particular ruleset really does before you use it. It
  -avoid problems.
  -</TD></TR></TABLE>
  -
  -<H1>URL Layout</H1>
  -
  -<P>
  -<H2>Canonical URLs</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -On some webservers there are more than one URL for a resource.  Usually there
  -are canonical URLs (which should be actually used and distributed) and those
  -which are just shortcuts, internal ones, etc. Independent which URL the user
  -supplied with the request he should finally see the canonical one only.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We do an external HTTP redirect for all non-canonical URLs to fix them in the
  -location view of the Browser and for all subsequent requests. In the example
  -ruleset below we replace <CODE>/~user</CODE> by the canonical <CODE>/u/user</CODE> and
  -fix a missing trailing slash for <CODE>/u/user</CODE>.
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  -RewriteRule   ^/<STRONG>~</STRONG>([^/]+)/?(.*)    /<STRONG>u</STRONG>/$1/$2  [<STRONG>R</STRONG>]
  -RewriteRule   ^/([uge])/(<STRONG>[^/]+</STRONG>)$  /$1/$2<STRONG>/</STRONG>   [<STRONG>R</STRONG>]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Canonical Hostnames</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -...
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache 1.3 URL Rewriting Guide</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <blockquote>
  +      <!--#include virtual="header.html" -->
  +
  +      <div align="CENTER">
  +        <h1>Apache 1.3<br />
  +         URL Rewriting Guide<br />
  +        </h1>
  +
  +        <address>
  +          Originally written by<br />
  +           Ralf S. Engelschall &lt;rse@apache.org&gt;<br />
  +           December 1997
  +        </address>
  +      </div>
  +
  +      <p>This document supplements the mod_rewrite <a
  +      href="../mod/mod_rewrite.html">reference documentation</a>.
  +      It describes how one can use Apache's mod_rewrite to solve
  +      typical URL-based problems webmasters are usually confronted
  +      with in practice. I give detailed descriptions on how to
  +      solve each problem by configuring URL rewriting rulesets.</p>
  +
  +      <h2><a id="ToC1" name="ToC1">Introduction to
  +      mod_rewrite</a></h2>
  +      The Apache module mod_rewrite is a killer one, i.e. it is a
  +      really sophisticated module which provides a powerful way to
  +      do URL manipulations. With it you can nearly do all types of
  +      URL manipulations you ever dreamed about. The price you have
  +      to pay is to accept complexity, because mod_rewrite's major
  +      drawback is that it is not easy to understand and use for the
  +      beginner. And even Apache experts sometimes discover new
  +      aspects where mod_rewrite can help. 
  +
  +      <p>In other words: With mod_rewrite you either shoot yourself
  +      in the foot the first time and never use it again or love it
  +      for the rest of your life because of its power. This paper
  +      tries to give you a few initial success events to avoid the
  +      first case by presenting already invented solutions to
  +      you.</p>
  +
  +      <h2><a id="ToC2" name="ToC2">Practical Solutions</a></h2>
  +      Here come a lot of practical solutions I've either invented
  +      myself or collected from other peoples solutions in the past.
  +      Feel free to learn the black magic of URL rewriting from
  +      these examples. 
  +
  +      <table bgcolor="#FFE0E0" border="0" cellspacing="0"
  +      cellpadding="5">
  +        <tr>
  +          <td>ATTENTION: Depending on your server-configuration it
  +          can be necessary to slightly change the examples for your
  +          situation, e.g. adding the [PT] flag when additionally
  +          using mod_alias and mod_userdir, etc. Or rewriting a
  +          ruleset to fit in <code>.htaccess</code> context instead
  +          of per-server context. Always try to understand what a
  +          particular ruleset really does before you use it. It
  +          avoid problems.</td>
  +        </tr>
  +      </table>
  +
  +      <h1>URL Layout</h1>
  +
  +      <h2>Canonical URLs</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>On some webservers there are more than one URL for a
  +        resource. Usually there are canonical URLs (which should be
  +        actually used and distributed) and those which are just
  +        shortcuts, internal ones, etc. Independent which URL the
  +        user supplied with the request he should finally see the
  +        canonical one only.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We do an external HTTP redirect for all non-canonical
  +          URLs to fix them in the location view of the Browser and
  +          for all subsequent requests. In the example ruleset below
  +          we replace <code>/~user</code> by the canonical
  +          <code>/u/user</code> and fix a missing trailing slash for
  +          <code>/u/user</code>. 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
  +RewriteRule   ^/<strong>~</strong>([^/]+)/?(.*)    /<strong>u</strong>/$1/$2  [<strong>R</strong>]
  +RewriteRule   ^/([uge])/(<strong>[^/]+</strong>)$  /$1/$2<strong>/</strong>   [<strong>R</strong>]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Canonical Hostnames</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>...</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteCond %{HTTP_HOST}   !^fully\.qualified\.domain\.name [NC]
   RewriteCond %{HTTP_HOST}   !^$
   RewriteCond %{SERVER_PORT} !^80$
  @@ -116,228 +131,281 @@
   RewriteCond %{HTTP_HOST}   !^fully\.qualified\.domain\.name [NC]
   RewriteCond %{HTTP_HOST}   !^$
   RewriteRule ^/(.*)         http://fully.qualified.domain.name/$1 [L,R]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Moved DocumentRoot</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Usually the DocumentRoot of the webserver directly relates to the URL
  -``<CODE>/</CODE>''. But often this data is not really of top-level priority, it is
  -perhaps just one entity of a lot of data pools. For instance at our Intranet
  -sites there are <CODE>/e/www/</CODE> (the homepage for WWW), <CODE>/e/sww/</CODE> (the
  -homepage for the Intranet) etc. Now because the data of the DocumentRoot stays
  -at <CODE>/e/www/</CODE> we had to make sure that all inlined images and other
  -stuff inside this data pool work for subsequent requests. 
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We just redirect the URL <CODE>/</CODE> to <CODE>/e/www/</CODE>.  While is seems
  -trivial it is actually trivial with mod_rewrite, only.  Because the typical
  -old mechanisms of URL <EM>Aliases</EM> (as provides by mod_alias and friends)
  -only used <EM>prefix</EM> matching. With this you cannot do such a redirection
  -because the DocumentRoot is a prefix of all URLs. With mod_rewrite it is
  -really trivial:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Moved DocumentRoot</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Usually the DocumentRoot of the webserver directly
  +        relates to the URL ``<code>/</code>''. But often this data
  +        is not really of top-level priority, it is perhaps just one
  +        entity of a lot of data pools. For instance at our Intranet
  +        sites there are <code>/e/www/</code> (the homepage for
  +        WWW), <code>/e/sww/</code> (the homepage for the Intranet)
  +        etc. Now because the data of the DocumentRoot stays at
  +        <code>/e/www/</code> we had to make sure that all inlined
  +        images and other stuff inside this data pool work for
  +        subsequent requests.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We just redirect the URL <code>/</code> to
  +          <code>/e/www/</code>. While is seems trivial it is
  +          actually trivial with mod_rewrite, only. Because the
  +          typical old mechanisms of URL <em>Aliases</em> (as
  +          provides by mod_alias and friends) only used
  +          <em>prefix</em> matching. With this you cannot do such a
  +          redirection because the DocumentRoot is a prefix of all
  +          URLs. With mod_rewrite it is really trivial: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
  -RewriteRule   <STRONG>^/$</STRONG>  /e/www/  [<STRONG>R</STRONG>]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Trailing Slash Problem</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Every webmaster can sing a song about the problem of the trailing slash on
  -URLs referencing directories. If they are missing, the server dumps an error,
  -because if you say <CODE>/~quux/foo</CODE> instead of
  -<CODE>/~quux/foo/</CODE> then the server searches for a <EM>file</EM> named
  -<CODE>foo</CODE>. And because this file is a directory it complains. Actually
  -is tries to fix it themself in most of the cases, but sometimes this mechanism
  -need to be emulated by you. For instance after you have done a lot of
  -complicated URL rewritings to CGI scripts etc. 
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -The solution to this subtle problem is to let the server add the trailing
  -slash automatically. To do this correctly we have to use an external redirect,
  -so the browser correctly requests subsequent images etc. If we only did a
  -internal rewrite, this would only work for the directory page, but would go
  -wrong when any images are included into this page with relative URLs, because
  -the browser would request an in-lined object. For instance, a request for
  -<CODE>image.gif</CODE> in <CODE>/~quux/foo/index.html</CODE> would become
  -<CODE>/~quux/image.gif</CODE> without the external redirect!
  -<P>
  -So, to do this trick we write:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule   <strong>^/$</strong>  /e/www/  [<strong>R</strong>]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Trailing Slash Problem</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Every webmaster can sing a song about the problem of
  +        the trailing slash on URLs referencing directories. If they
  +        are missing, the server dumps an error, because if you say
  +        <code>/~quux/foo</code> instead of <code>/~quux/foo/</code>
  +        then the server searches for a <em>file</em> named
  +        <code>foo</code>. And because this file is a directory it
  +        complains. Actually is tries to fix it themself in most of
  +        the cases, but sometimes this mechanism need to be emulated
  +        by you. For instance after you have done a lot of
  +        complicated URL rewritings to CGI scripts etc.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          The solution to this subtle problem is to let the server
  +          add the trailing slash automatically. To do this
  +          correctly we have to use an external redirect, so the
  +          browser correctly requests subsequent images etc. If we
  +          only did a internal rewrite, this would only work for the
  +          directory page, but would go wrong when any images are
  +          included into this page with relative URLs, because the
  +          browser would request an in-lined object. For instance, a
  +          request for <code>image.gif</code> in
  +          <code>/~quux/foo/index.html</code> would become
  +          <code>/~quux/image.gif</code> without the external
  +          redirect! 
  +
  +          <p>So, to do this trick we write:</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine  on
   RewriteBase    /~quux/
  -RewriteRule    ^foo<STRONG>$</STRONG>  foo<STRONG>/</STRONG>  [<STRONG>R</STRONG>]
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -The crazy and lazy can even do the following in the top-level
  -<CODE>.htaccess</CODE> file of their homedir. But notice that this creates some
  -processing overhead.
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule    ^foo<strong>$</strong>  foo<strong>/</strong>  [<strong>R</strong>]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>The crazy and lazy can even do the following in the
  +          top-level <code>.htaccess</code> file of their homedir.
  +          But notice that this creates some processing
  +          overhead.</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine  on
   RewriteBase    /~quux/
  -RewriteCond    %{REQUEST_FILENAME}  <STRONG>-d</STRONG>
  -RewriteRule    ^(.+<STRONG>[^/]</STRONG>)$           $1<STRONG>/</STRONG>  [R]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Webcluster through Homogeneous URL Layout</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -We want to create a homogenous and consistent URL layout over all WWW servers
  -on a Intranet webcluster, i.e. all URLs (per definition server local and thus
  -server dependent!) become actually server <EM>independed</EM>!  What we want is
  -to give the WWW namespace a consistent server-independend layout: no URL
  -should have to include any physically correct target server. The cluster
  -itself should drive us automatically to the physical target host.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -First, the knowledge of the target servers come from (distributed) external
  -maps which contain information where our users, groups and entities stay.  
  -The have the form
  -
  -<P><PRE>
  +RewriteCond    %{REQUEST_FILENAME}  <strong>-d</strong>
  +RewriteRule    ^(.+<strong>[^/]</strong>)$           $1<strong>/</strong>  [R]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Webcluster through Homogeneous URL Layout</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>We want to create a homogenous and consistent URL
  +        layout over all WWW servers on a Intranet webcluster, i.e.
  +        all URLs (per definition server local and thus server
  +        dependent!) become actually server <em>independed</em>!
  +        What we want is to give the WWW namespace a consistent
  +        server-independend layout: no URL should have to include
  +        any physically correct target server. The cluster itself
  +        should drive us automatically to the physical target
  +        host.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          First, the knowledge of the target servers come from
  +          (distributed) external maps which contain information
  +          where our users, groups and entities stay. The have the
  +          form 
  +<pre>
   user1  server_of_user1
   user2  server_of_user2
   :      :
  -</PRE><P>
  -
  -We put them into files <CODE>map.xxx-to-host</CODE>.  Second we need to instruct
  -all servers to redirect URLs of the forms
  +</pre>
   
  -<P><PRE>
  +          <p>We put them into files <code>map.xxx-to-host</code>.
  +          Second we need to instruct all servers to redirect URLs
  +          of the forms</p>
  +<pre>
   /u/user/anypath
   /g/group/anypath
   /e/entity/anypath
  -</PRE><P>
  -
  -to
  +</pre>
   
  -<P><PRE>
  +          <p>to</p>
  +<pre>
   http://physical-host/u/user/anypath
   http://physical-host/g/group/anypath
   http://physical-host/e/entity/anypath
  -</PRE><P>
  +</pre>
   
  -when the URL is not locally valid to a server.  The following ruleset does
  -this for us by the help of the map files (assuming that server0 is a default
  -server which will be used if a user has no entry in the map):
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +          <p>when the URL is not locally valid to a server. The
  +          following ruleset does this for us by the help of the map
  +          files (assuming that server0 is a default server which
  +          will be used if a user has no entry in the map):</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
   
   RewriteMap      user-to-host   txt:/path/to/map.user-to-host
   RewriteMap     group-to-host   txt:/path/to/map.group-to-host
   RewriteMap    entity-to-host   txt:/path/to/map.entity-to-host
   
  -RewriteRule   ^/u/<STRONG>([^/]+)</STRONG>/?(.*)   http://<STRONG>${user-to-host:$1|server0}</STRONG>/u/$1/$2
  -RewriteRule   ^/g/<STRONG>([^/]+)</STRONG>/?(.*)  http://<STRONG>${group-to-host:$1|server0}</STRONG>/g/$1/$2
  -RewriteRule   ^/e/<STRONG>([^/]+)</STRONG>/?(.*) http://<STRONG>${entity-to-host:$1|server0}</STRONG>/e/$1/$2
  +RewriteRule   ^/u/<strong>([^/]+)</strong>/?(.*)   http://<strong>${user-to-host:$1|server0}</strong>/u/$1/$2
  +RewriteRule   ^/g/<strong>([^/]+)</strong>/?(.*)  http://<strong>${group-to-host:$1|server0}</strong>/g/$1/$2
  +RewriteRule   ^/e/<strong>([^/]+)</strong>/?(.*) http://<strong>${entity-to-host:$1|server0}</strong>/e/$1/$2
   
   RewriteRule   ^/([uge])/([^/]+)/?$          /$1/$2/.www/
   RewriteRule   ^/([uge])/([^/]+)/([^.]+.+)   /$1/$2/.www/$3\
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Move Homedirs to Different Webserver</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -A lot of webmaster aksed for a solution to the following situation: They
  -wanted to redirect just all homedirs on a webserver to another webserver.
  -They usually need such things when establishing a newer webserver which will
  -replace the old one over time.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -The solution is trivial with mod_rewrite. On the old webserver we just
  -redirect all <CODE>/~user/anypath</CODE> URLs to
  -<CODE>http://newserver/~user/anypath</CODE>.
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Move Homedirs to Different Webserver</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>A lot of webmaster aksed for a solution to the
  +        following situation: They wanted to redirect just all
  +        homedirs on a webserver to another webserver. They usually
  +        need such things when establishing a newer webserver which
  +        will replace the old one over time.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          The solution is trivial with mod_rewrite. On the old
  +          webserver we just redirect all
  +          <code>/~user/anypath</code> URLs to
  +          <code>http://newserver/~user/anypath</code>. 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
  -RewriteRule   ^/~(.+)  http://<STRONG>newserver</STRONG>/~$1  [R,L]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Structured Homedirs</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Some sites with thousend of users usually use a structured homedir layout,
  -i.e.  each homedir is in a subdirectory which begins for instance with the
  -first character of the username. So, <CODE>/~foo/anypath</CODE> is
  -<CODE>/home/<STRONG>f</STRONG>/foo/.www/anypath</CODE> while <CODE>/~bar/anypath</CODE> is
  -<CODE>/home/<STRONG>b</STRONG>/bar/.www/anypath</CODE>.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We use the following ruleset to expand the tilde URLs into exactly the above
  -layout.
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule   ^/~(.+)  http://<strong>newserver</strong>/~$1  [R,L]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Structured Homedirs</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Some sites with thousend of users usually use a
  +        structured homedir layout, i.e. each homedir is in a
  +        subdirectory which begins for instance with the first
  +        character of the username. So, <code>/~foo/anypath</code>
  +        is <code>/home/<strong>f</strong>/foo/.www/anypath</code>
  +        while <code>/~bar/anypath</code> is
  +        <code>/home/<strong>b</strong>/bar/.www/anypath</code>.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We use the following ruleset to expand the tilde URLs
  +          into exactly the above layout. 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
  -RewriteRule   ^/~(<STRONG>([a-z])</STRONG>[a-z0-9]+)(.*)  /home/<STRONG>$2</STRONG>/$1/.www$3
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Filesystem Reorganisation</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -This really is a hardcore example: a killer application which heavily uses
  -per-directory <CODE>RewriteRules</CODE> to get a smooth look and feel on the Web
  -while its data structure is never touched or adjusted.
  -
  -Background: <STRONG><EM>net.sw</EM></STRONG> is my archive of freely available Unix
  -software packages, which I started to collect in 1992. It is both my hobby and
  -job to to this, because while I'm studying computer science I have also worked
  -for many years as a system and network administrator in my spare time. Every
  -week I need some sort of software so I created a deep hierarchy of
  -directories where I stored the packages: 
  -
  -<P><PRE>
  +RewriteRule   ^/~(<strong>([a-z])</strong>[a-z0-9]+)(.*)  /home/<strong>$2</strong>/$1/.www$3
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Filesystem Reorganisation</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>
  +          This really is a hardcore example: a killer application
  +          which heavily uses per-directory
  +          <code>RewriteRules</code> to get a smooth look and feel
  +          on the Web while its data structure is never touched or
  +          adjusted. Background: <strong><em>net.sw</em></strong> is
  +          my archive of freely available Unix software packages,
  +          which I started to collect in 1992. It is both my hobby
  +          and job to to this, because while I'm studying computer
  +          science I have also worked for many years as a system and
  +          network administrator in my spare time. Every week I need
  +          some sort of software so I created a deep hierarchy of
  +          directories where I stored the packages: 
  +<pre>
   drwxrwxr-x   2 netsw  users    512 Aug  3 18:39 Audio/
   drwxrwxr-x   2 netsw  users    512 Jul  9 14:37 Benchmark/
   drwxrwxr-x  12 netsw  users    512 Jul  9 00:34 Crypto/
  @@ -354,24 +422,27 @@
   drwxrwxr-x   7 netsw  users    512 Jul  9 12:17 System/
   drwxrwxr-x  12 netsw  users    512 Aug  3 20:15 Typesetting/
   drwxrwxr-x  10 netsw  users    512 Jul  9 14:08 X11/
  -</PRE><P>
  -
  -In July 1996 I decided to make this archive public to the world via a
  -nice Web interface. "Nice" means that I wanted to
  -offer an interface where you can browse directly through the archive hierarchy.
  -And "nice" means that I didn't wanted to change anything inside this hierarchy
  -- not even by putting some CGI scripts at the top of it.  Why? Because the
  -above structure should be later accessible via FTP as well, and I didn't
  -want any Web or CGI stuff to be there.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -The solution has two parts: The first is a set of CGI scripts which create all
  -the pages at all directory levels on-the-fly. I put them under
  -<CODE>/e/netsw/.www/</CODE> as follows:
  +</pre>
   
  -<P><PRE>
  +          <p>In July 1996 I decided to make this archive public to
  +          the world via a nice Web interface. "Nice" means that I
  +          wanted to offer an interface where you can browse
  +          directly through the archive hierarchy. And "nice" means
  +          that I didn't wanted to change anything inside this
  +          hierarchy - not even by putting some CGI scripts at the
  +          top of it. Why? Because the above structure should be
  +          later accessible via FTP as well, and I didn't want any
  +          Web or CGI stuff to be there.</p>
  +        </dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          The solution has two parts: The first is a set of CGI
  +          scripts which create all the pages at all directory
  +          levels on-the-fly. I put them under
  +          <code>/e/netsw/.www/</code> as follows: 
  +<pre>
   -rw-r--r--   1 netsw  users    1318 Aug  1 18:10 .wwwacl
   drwxr-xr-x  18 netsw  users     512 Aug  5 15:51 DATA/
   -rw-rw-rw-   1 netsw  users  372982 Aug  5 16:35 LOGFILE
  @@ -385,32 +456,45 @@
   -rwxr-xr-x   1 netsw  users    1589 Aug  3 18:43 netsw-search.cgi
   -rwxr-xr-x   1 netsw  users    1885 Aug  1 17:41 netsw-tree.cgi
   -rw-r--r--   1 netsw  users     234 Jul 30 16:35 netsw-unlimit.lst
  -</PRE><P>
  +</pre>
   
  -The <CODE>DATA/</CODE> subdirectory holds the above directory structure, i.e.  the
  -real <STRONG><EM>net.sw</EM></STRONG> stuff and gets automatically updated via
  -<CODE>rdist</CODE> from time to time. 
  -
  -The second part of the problem remains: how to link these two structures
  -together into one smooth-looking URL tree? We want to hide the <CODE>DATA/</CODE>
  -directory from the user while running the appropriate CGI scripts for the
  -various URLs. 
  -
  -Here is the solution: first I put the following into the per-directory
  -configuration file in the Document Root of the server to rewrite the announced
  -URL <CODE>/net.sw/</CODE> to the internal path <CODE>/e/netsw</CODE>:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +          <p>The <code>DATA/</code> subdirectory holds the above
  +          directory structure, i.e. the real
  +          <strong><em>net.sw</em></strong> stuff and gets
  +          automatically updated via <code>rdist</code> from time to
  +          time. The second part of the problem remains: how to link
  +          these two structures together into one smooth-looking URL
  +          tree? We want to hide the <code>DATA/</code> directory
  +          from the user while running the appropriate CGI scripts
  +          for the various URLs. Here is the solution: first I put
  +          the following into the per-directory configuration file
  +          in the Document Root of the server to rewrite the
  +          announced URL <code>/net.sw/</code> to the internal path
  +          <code>/e/netsw</code>:</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteRule  ^net.sw$       net.sw/        [R]
   RewriteRule  ^net.sw/(.*)$  e/netsw/$1
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -The first rule is for requests which miss the trailing slash!  The second rule
  -does the real thing. And then comes the killer configuration which stays in
  -the per-directory config file <CODE>/e/netsw/.www/.wwwacl</CODE>:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>The first rule is for requests which miss the trailing
  +          slash! The second rule does the real thing. And then
  +          comes the killer configuration which stays in the
  +          per-directory config file
  +          <code>/e/netsw/.www/.wwwacl</code>:</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   Options       ExecCGI FollowSymLinks Includes MultiViews 
   
   RewriteEngine on
  @@ -439,239 +523,309 @@
   #  by another cgi script
   RewriteRule   !^netsw-lsdir\.cgi.*     -                  [C]
   RewriteRule   (.*)                     netsw-lsdir.cgi/$1
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -Some hints for interpretation:
  -    <ol>
  -    <li> Notice the L (last) flag and no substitution field ('-') in the
  -         forth part
  -    <li> Notice the ! (not) character and the C (chain) flag
  -         at the first rule in the last part
  -    <li> Notice the catch-all pattern in the last rule
  -    </ol>
  -
  -</DL>
  -
  -<P>
  -<H2>NCSA imagemap to Apache mod_imap</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -When switching from the NCSA webserver to the more modern Apache webserver a
  -lot of people want a smooth transition. So they want pages which use their old
  -NCSA <CODE>imagemap</CODE> program to work under Apache with the modern
  -<CODE>mod_imap</CODE>. The problem is that there are a lot of
  -hyperlinks around which reference the <CODE>imagemap</CODE> program via
  -<CODE>/cgi-bin/imagemap/path/to/page.map</CODE>. Under Apache this
  -has to read just <CODE>/path/to/page.map</CODE>.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We use a global rule to remove the prefix on-the-fly for all requests:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>Some hints for interpretation:</p>
  +
  +          <ol>
  +            <li>Notice the L (last) flag and no substitution field
  +            ('-') in the forth part</li>
  +
  +            <li>Notice the ! (not) character and the C (chain) flag
  +            at the first rule in the last part</li>
  +
  +            <li>Notice the catch-all pattern in the last rule</li>
  +          </ol>
  +        </dd>
  +      </dl>
  +
  +      <h2>NCSA imagemap to Apache mod_imap</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>When switching from the NCSA webserver to the more
  +        modern Apache webserver a lot of people want a smooth
  +        transition. So they want pages which use their old NCSA
  +        <code>imagemap</code> program to work under Apache with the
  +        modern <code>mod_imap</code>. The problem is that there are
  +        a lot of hyperlinks around which reference the
  +        <code>imagemap</code> program via
  +        <code>/cgi-bin/imagemap/path/to/page.map</code>. Under
  +        Apache this has to read just
  +        <code>/path/to/page.map</code>.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We use a global rule to remove the prefix on-the-fly for
  +          all requests: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine  on
   RewriteRule    ^/cgi-bin/imagemap(.*)  $1  [PT]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Search pages in more than one directory</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Sometimes it is neccessary to let the webserver search for pages in more than
  -one directory. Here MultiViews or other techniques cannot help.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We program a explicit ruleset which searches for the files in the directories.
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Search pages in more than one directory</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Sometimes it is neccessary to let the webserver search
  +        for pages in more than one directory. Here MultiViews or
  +        other techniques cannot help.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We program a explicit ruleset which searches for the
  +          files in the directories. 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
   
   #   first try to find it in custom/...
   #   ...and if found stop and be happy:
  -RewriteCond         /your/docroot/<STRONG>dir1</STRONG>/%{REQUEST_FILENAME}  -f
  -RewriteRule  ^(.+)  /your/docroot/<STRONG>dir1</STRONG>/$1  [L]
  +RewriteCond         /your/docroot/<strong>dir1</strong>/%{REQUEST_FILENAME}  -f
  +RewriteRule  ^(.+)  /your/docroot/<strong>dir1</strong>/$1  [L]
   
   #   second try to find it in pub/...
   #   ...and if found stop and be happy:
  -RewriteCond         /your/docroot/<STRONG>dir2</STRONG>/%{REQUEST_FILENAME}  -f
  -RewriteRule  ^(.+)  /your/docroot/<STRONG>dir2</STRONG>/$1  [L]
  +RewriteCond         /your/docroot/<strong>dir2</strong>/%{REQUEST_FILENAME}  -f
  +RewriteRule  ^(.+)  /your/docroot/<strong>dir2</strong>/$1  [L]
   
   #   else go on for other Alias or ScriptAlias directives,
   #   etc.
   RewriteRule   ^(.+)  -  [PT]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Set Environment Variables According To URL Parts</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Perhaps you want to keep status information between requests and use the URL
  -to encode it. But you don't want to use a CGI wrapper for all pages just to
  -strip out this information.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We use a rewrite rule to strip out the status information and remember it via
  -an environment variable which can be later dereferenced from within XSSI or
  -CGI. This way a URL <CODE>/foo/S=java/bar/</CODE> gets translated to
  -<CODE>/foo/bar/</CODE> and the environment variable named <CODE>STATUS</CODE> is set
  -to the value "java".
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Set Environment Variables According To URL Parts</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Perhaps you want to keep status information between
  +        requests and use the URL to encode it. But you don't want
  +        to use a CGI wrapper for all pages just to strip out this
  +        information.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We use a rewrite rule to strip out the status information
  +          and remember it via an environment variable which can be
  +          later dereferenced from within XSSI or CGI. This way a
  +          URL <code>/foo/S=java/bar/</code> gets translated to
  +          <code>/foo/bar/</code> and the environment variable named
  +          <code>STATUS</code> is set to the value "java". 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
  -RewriteRule   ^(.*)/<STRONG>S=([^/]+)</STRONG>/(.*)    $1/$3 [E=<STRONG>STATUS:$2</STRONG>]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Virtual User Hosts</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Assume that you want to provide <CODE>www.<STRONG>username</STRONG>.host.domain.com</CODE>
  -for the homepage of username via just DNS A records to the same machine and
  -without any virtualhosts on this machine. 
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -For HTTP/1.0 requests there is no solution, but for HTTP/1.1 requests which
  -contain a Host: HTTP header we can use the following ruleset to rewrite
  -<CODE>http://www.username.host.com/anypath</CODE> internally to
  -<CODE>/home/username/anypath</CODE>:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule   ^(.*)/<strong>S=([^/]+)</strong>/(.*)    $1/$3 [E=<strong>STATUS:$2</strong>]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Virtual User Hosts</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Assume that you want to provide
  +        <code>www.<strong>username</strong>.host.domain.com</code>
  +        for the homepage of username via just DNS A records to the
  +        same machine and without any virtualhosts on this
  +        machine.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          For HTTP/1.0 requests there is no solution, but for
  +          HTTP/1.1 requests which contain a Host: HTTP header we
  +          can use the following ruleset to rewrite
  +          <code>http://www.username.host.com/anypath</code>
  +          internally to <code>/home/username/anypath</code>: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
  -RewriteCond   %{<STRONG>HTTP_HOST</STRONG>}                 ^www\.<STRONG>[^.]+</STRONG>\.host\.com$
  +RewriteCond   %{<strong>HTTP_HOST</strong>}                 ^www\.<strong>[^.]+</strong>\.host\.com$
   RewriteRule   ^(.+)                        %{HTTP_HOST}$1          [C]
  -RewriteRule   ^www\.<STRONG>([^.]+)</STRONG>\.host\.com(.*) /home/<STRONG>$1</STRONG>$2
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Redirect Homedirs For Foreigners</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -We want to redirect homedir URLs to another webserver
  -<CODE>www.somewhere.com</CODE> when the requesting user does not stay in the local
  -domain <CODE>ourdomain.com</CODE>. This is sometimes used in virtual host
  -contexts.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -Just a rewrite condition:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule   ^www\.<strong>([^.]+)</strong>\.host\.com(.*) /home/<strong>$1</strong>$2
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Redirect Homedirs For Foreigners</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>We want to redirect homedir URLs to another webserver
  +        <code>www.somewhere.com</code> when the requesting user
  +        does not stay in the local domain
  +        <code>ourdomain.com</code>. This is sometimes used in
  +        virtual host contexts.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          Just a rewrite condition: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
  -RewriteCond   %{REMOTE_HOST}  <STRONG>!^.+\.ourdomain\.com$</STRONG>
  +RewriteCond   %{REMOTE_HOST}  <strong>!^.+\.ourdomain\.com$</strong>
   RewriteRule   ^(/~.+)         http://www.somewhere.com/$1 [R,L]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Redirect Failing URLs To Other Webserver</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -A typical FAQ about URL rewriting is how to redirect failing requests on
  -webserver A to webserver B.  Usually this is done via ErrorDocument
  -CGI-scripts in Perl, but there is also a mod_rewrite solution. But notice that
  -this is less performant than using a ErrorDocument CGI-script!
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -The first solution has the best performance but less flexibility and is less
  -error safe:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Redirect Failing URLs To Other Webserver</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>A typical FAQ about URL rewriting is how to redirect
  +        failing requests on webserver A to webserver B. Usually
  +        this is done via ErrorDocument CGI-scripts in Perl, but
  +        there is also a mod_rewrite solution. But notice that this
  +        is less performant than using a ErrorDocument
  +        CGI-script!</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          The first solution has the best performance but less
  +          flexibility and is less error safe: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
  -RewriteCond   /your/docroot/%{REQUEST_FILENAME} <STRONG>!-f</STRONG>
  -RewriteRule   ^(.+)                             http://<STRONG>webserverB</STRONG>.dom/$1
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -The problem here is that this will only work for pages inside the
  -DocumentRoot. While you can add more Conditions (for instance to also handle
  -homedirs, etc.) there is better variant:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteCond   /your/docroot/%{REQUEST_FILENAME} <strong>!-f</strong>
  +RewriteRule   ^(.+)                             http://<strong>webserverB</strong>.dom/$1
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>The problem here is that this will only work for pages
  +          inside the DocumentRoot. While you can add more
  +          Conditions (for instance to also handle homedirs, etc.)
  +          there is better variant:</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
  -RewriteCond   %{REQUEST_URI} <STRONG>!-U</STRONG>
  -RewriteRule   ^(.+)          http://<STRONG>webserverB</STRONG>.dom/$1
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -This uses the URL look-ahead feature of mod_rewrite. The result is that this
  -will work for all types of URLs and is a safe way.  But it does a performance
  -impact on the webserver, because for every request there is one more internal
  -subrequest. So, if your webserver runs on a powerful CPU, use this one. If it
  -is a slow machine, use the first approach or better a ErrorDocument
  -CGI-script.
  -
  -</DL>
  -
  -<P>
  -<H2>Extended Redirection</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Sometimes we need more control (concerning the character escaping mechanism)
  -of URLs on redirects. Usually the Apache kernels URL escape function also
  -escapes anchors, i.e. URLs like "url#anchor". You cannot use this directly on
  -redirects with mod_rewrite because the uri_escape() function of Apache would
  -also escape the hash character. How can we redirect to such a URL?
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We have to use a kludge by the use of a NPH-CGI script which does the redirect
  -itself. Because here no escaping is done (NPH=non-parseable headers).  First
  -we introduce a new URL scheme <CODE>xredirect:</CODE> by the following per-server
  -config-line (should be one of the last rewrite rules):
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteCond   %{REQUEST_URI} <strong>!-U</strong>
  +RewriteRule   ^(.+)          http://<strong>webserverB</strong>.dom/$1
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>This uses the URL look-ahead feature of mod_rewrite.
  +          The result is that this will work for all types of URLs
  +          and is a safe way. But it does a performance impact on
  +          the webserver, because for every request there is one
  +          more internal subrequest. So, if your webserver runs on a
  +          powerful CPU, use this one. If it is a slow machine, use
  +          the first approach or better a ErrorDocument
  +          CGI-script.</p>
  +        </dd>
  +      </dl>
  +
  +      <h2>Extended Redirection</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Sometimes we need more control (concerning the
  +        character escaping mechanism) of URLs on redirects. Usually
  +        the Apache kernels URL escape function also escapes
  +        anchors, i.e. URLs like "url#anchor". You cannot use this
  +        directly on redirects with mod_rewrite because the
  +        uri_escape() function of Apache would also escape the hash
  +        character. How can we redirect to such a URL?</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We have to use a kludge by the use of a NPH-CGI script
  +          which does the redirect itself. Because here no escaping
  +          is done (NPH=non-parseable headers). First we introduce a
  +          new URL scheme <code>xredirect:</code> by the following
  +          per-server config-line (should be one of the last rewrite
  +          rules): 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteRule ^xredirect:(.+) /path/to/nph-xredirect.cgi/$1 \
               [T=application/x-httpd-cgi,L]
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -This forces all URLs prefixed with <CODE>xredirect:</CODE> to be piped through the
  -<CODE>nph-xredirect.cgi</CODE> program. And this program just looks like:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  -<PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>This forces all URLs prefixed with
  +          <code>xredirect:</code> to be piped through the
  +          <code>nph-xredirect.cgi</code> program. And this program
  +          just looks like:</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   #!/path/to/perl
   ##
   ##  nph-xredirect.cgi -- NPH/CGI script for extended redirects
  @@ -697,55 +851,79 @@
   print "&lt;/html&gt;\n";
   
   ##EOF##
  -</PRE>
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -This provides you with the functionality to do redirects to all URL schemes,
  -i.e. including the one which are not directly accepted by mod_rewrite. For
  -instance you can now also redirect to <CODE>news:newsgroup</CODE> via
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>This provides you with the functionality to do
  +          redirects to all URL schemes, i.e. including the one
  +          which are not directly accepted by mod_rewrite. For
  +          instance you can now also redirect to
  +          <code>news:newsgroup</code> via</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteRule ^anyurl  xredirect:news:newsgroup
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -Notice: You have not to put [R] or [R,L] to the above rule because the
  -<CODE>xredirect:</CODE> need to be expanded later by our special "pipe through"
  -rule above.
  -
  -</DL>
  -
  -<P>
  -<H2>Archive Access Multiplexer</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Do you know the great CPAN (Comprehensive Perl Archive Network) under <A
  -HREF="http://www.perl.com/CPAN">http://www.perl.com/CPAN</A>? This does a
  -redirect to one of several FTP servers around the world which carry a CPAN
  -mirror and is approximately near the location of the requesting client.
  -Actually this can be called an FTP access multiplexing service. While CPAN
  -runs via CGI scripts, how can a similar approach implemented via mod_rewrite?
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -First we notice that from version 3.0.0 mod_rewrite can also use the "ftp:"
  -scheme on redirects. And second, the location approximation can be done by a
  -rewritemap over the top-level domain of the client. With a tricky chained
  -ruleset we can use this top-level domain as a key to our multiplexing map.
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>Notice: You have not to put [R] or [R,L] to the above
  +          rule because the <code>xredirect:</code> need to be
  +          expanded later by our special "pipe through" rule
  +          above.</p>
  +        </dd>
  +      </dl>
  +
  +      <h2>Archive Access Multiplexer</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Do you know the great CPAN (Comprehensive Perl Archive
  +        Network) under <a
  +        href="http://www.perl.com/CPAN">http://www.perl.com/CPAN</a>?
  +        This does a redirect to one of several FTP servers around
  +        the world which carry a CPAN mirror and is approximately
  +        near the location of the requesting client. Actually this
  +        can be called an FTP access multiplexing service. While
  +        CPAN runs via CGI scripts, how can a similar approach
  +        implemented via mod_rewrite?</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          First we notice that from version 3.0.0 mod_rewrite can
  +          also use the "ftp:" scheme on redirects. And second, the
  +          location approximation can be done by a rewritemap over
  +          the top-level domain of the client. With a tricky chained
  +          ruleset we can use this top-level domain as a key to our
  +          multiplexing map. 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
   RewriteMap    multiplex                txt:/path/to/map.cxan
   RewriteRule   ^/CxAN/(.*)              %{REMOTE_HOST}::$1                 [C]
  -RewriteRule   ^.+\.<STRONG>([a-zA-Z]+)</STRONG>::(.*)$  ${multiplex:<STRONG>$1</STRONG>|ftp.default.dom}$2  [R,L]
  -</PRE></TD></TR></TABLE>
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule   ^.+\.<strong>([a-zA-Z]+)</strong>::(.*)$  ${multiplex:<strong>$1</strong>|ftp.default.dom}$2  [R,L]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   ##
   ##  map.cxan -- Multiplexing Map for CxAN
   ##
  @@ -755,62 +933,77 @@
   com       ftp://ftp.cxan.com/CxAN/
    :
   ##EOF##
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Time-Dependend Rewriting</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -When tricks like time-dependend content should happen a lot of webmasters
  -still use CGI scripts which do for instance redirects to specialized pages.
  -How can it be done via mod_rewrite?
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -There are a lot of variables named <CODE>TIME_xxx</CODE> for rewrite conditions.
  -In conjunction with the special lexicographic comparison patterns &lt;STRING,
  -&gt;STRING and =STRING we can do time-dependend redirects:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Time-Dependend Rewriting</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>When tricks like time-dependend content should happen a
  +        lot of webmasters still use CGI scripts which do for
  +        instance redirects to specialized pages. How can it be done
  +        via mod_rewrite?</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          There are a lot of variables named <code>TIME_xxx</code>
  +          for rewrite conditions. In conjunction with the special
  +          lexicographic comparison patterns &lt;STRING, &gt;STRING
  +          and =STRING we can do time-dependend redirects: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
   RewriteCond   %{TIME_HOUR}%{TIME_MIN} &gt;0700
   RewriteCond   %{TIME_HOUR}%{TIME_MIN} &lt;1900
   RewriteRule   ^foo\.html$             foo.day.html
   RewriteRule   ^foo\.html$             foo.night.html
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -This provides the content of <CODE>foo.day.html</CODE> under the URL
  -<CODE>foo.html</CODE> from 07:00-19:00 and at the remaining time the contents of
  -<CODE>foo.night.html</CODE>. Just a nice feature for a homepage...
  -
  -</DL>
  -
  -<P>
  -<H2>Backward Compatibility for YYYY to XXXX migration</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -How can we make URLs backward compatible (still existing virtually) after
  -migrating document.YYYY to document.XXXX, e.g. after translating a bunch of
  -.html files to .phtml?
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We just rewrite the name to its basename and test for existence of the new
  -extension. If it exists, we take that name, else we rewrite the URL to its
  -original state. 
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>This provides the content of <code>foo.day.html</code>
  +          under the URL <code>foo.html</code> from 07:00-19:00 and
  +          at the remaining time the contents of
  +          <code>foo.night.html</code>. Just a nice feature for a
  +          homepage...</p>
  +        </dd>
  +      </dl>
  +
  +      <h2>Backward Compatibility for YYYY to XXXX migration</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>How can we make URLs backward compatible (still
  +        existing virtually) after migrating document.YYYY to
  +        document.XXXX, e.g. after translating a bunch of .html
  +        files to .phtml?</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We just rewrite the name to its basename and test for
  +          existence of the new extension. If it exists, we take
  +          that name, else we rewrite the URL to its original state.
  +          
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   #   backward compatibility ruleset for 
   #   rewriting document.html to document.phtml
   #   when and only when document.phtml exists
  @@ -825,237 +1018,307 @@
   #   else reverse the previous basename cutout
   RewriteCond   %{ENV:WasHTML}            ^yes$
   RewriteRule   ^(.*)$ $1.html
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<H1>Content Handling</H1>
  -
  -<P>
  -<H2>From Old to New (intern)</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Assume we have recently renamed the page <CODE>bar.html</CODE> to
  -<CODE>foo.html</CODE> and now want to provide the old URL for backward
  -compatibility. Actually we want that users of the old URL even not recognize
  -that the pages was renamed.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We rewrite the old URL to the new one internally via the following rule:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h1>Content Handling</h1>
  +
  +      <h2>From Old to New (intern)</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Assume we have recently renamed the page
  +        <code>bar.html</code> to <code>foo.html</code> and now want
  +        to provide the old URL for backward compatibility. Actually
  +        we want that users of the old URL even not recognize that
  +        the pages was renamed.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We rewrite the old URL to the new one internally via the
  +          following rule: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine  on
   RewriteBase    /~quux/
  -RewriteRule    ^<STRONG>foo</STRONG>\.html$  <STRONG>bar</STRONG>.html
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>From Old to New (extern)</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Assume again that we have recently renamed the page <CODE>bar.html</CODE> to
  -<CODE>foo.html</CODE> and now want to provide the old URL for backward
  -compatibility. But this time we want that the users of the old URL get hinted
  -to the new one, i.e. their browsers Location field should change, too.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We force a HTTP redirect to the new URL which leads to a change of the
  -browsers and thus the users view:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule    ^<strong>foo</strong>\.html$  <strong>bar</strong>.html
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>From Old to New (extern)</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Assume again that we have recently renamed the page
  +        <code>bar.html</code> to <code>foo.html</code> and now want
  +        to provide the old URL for backward compatibility. But this
  +        time we want that the users of the old URL get hinted to
  +        the new one, i.e. their browsers Location field should
  +        change, too.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We force a HTTP redirect to the new URL which leads to a
  +          change of the browsers and thus the users view: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine  on
   RewriteBase    /~quux/
  -RewriteRule    ^<STRONG>foo</STRONG>\.html$  <STRONG>bar</STRONG>.html  [<STRONG>R</STRONG>]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Browser Dependend Content</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -At least for important top-level pages it is sometimes necesarry to provide
  -the optimum of browser dependend content, i.e. one has to provide a maximum
  -version for the latest Netscape variants, a minimum version for the Lynx
  -browsers and a average feature version for all others.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We cannot use content negotiation because the browsers do not provide their
  -type in that form. Instead we have to act on the HTTP header "User-Agent".
  -The following condig does the following: If the HTTP header "User-Agent"
  -begins with "Mozilla/3", the page <CODE>foo.html</CODE> is rewritten to
  -<CODE>foo.NS.html</CODE> and and the rewriting stops.  If the browser is "Lynx" or
  -"Mozilla" of version 1 or 2 the URL becomes <CODE>foo.20.html</CODE>.  All other
  -browsers receive page <CODE>foo.32.html</CODE>. This is done by the following
  -ruleset:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  -RewriteCond %{HTTP_USER_AGENT}  ^<STRONG>Mozilla/3</STRONG>.*
  -RewriteRule ^foo\.html$         foo.<STRONG>NS</STRONG>.html          [<STRONG>L</STRONG>]
  -
  -RewriteCond %{HTTP_USER_AGENT}  ^<STRONG>Lynx/</STRONG>.*         [OR]
  -RewriteCond %{HTTP_USER_AGENT}  ^<STRONG>Mozilla/[12]</STRONG>.*
  -RewriteRule ^foo\.html$         foo.<STRONG>20</STRONG>.html          [<STRONG>L</STRONG>]
  -
  -RewriteRule ^foo\.html$         foo.<STRONG>32</STRONG>.html          [<STRONG>L</STRONG>]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Dynamic Mirror</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Assume there are nice webpages on remote hosts we want to bring into our
  -namespace. For FTP servers we would use the <CODE>mirror</CODE> program which
  -actually maintains an explicit up-to-date copy of the remote data on the local
  -machine. For a webserver we could use the program <CODE>webcopy</CODE> which acts
  -similar via HTTP. But both techniques have one major drawback: The local copy
  -is always just as up-to-date as often we run the program. It would be much
  -better if the mirror is not a static one we have to establish explicitly.
  -Instead we want a dynamic mirror with data which gets updated automatically
  -when there is need (updated data on the remote host).
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -To provide this feature we map the remote webpage or even the complete remote
  -webarea to our namespace by the use of the <I>Proxy Throughput</I> feature
  -(flag [P]):
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule    ^<strong>foo</strong>\.html$  <strong>bar</strong>.html  [<strong>R</strong>]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Browser Dependend Content</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>At least for important top-level pages it is sometimes
  +        necesarry to provide the optimum of browser dependend
  +        content, i.e. one has to provide a maximum version for the
  +        latest Netscape variants, a minimum version for the Lynx
  +        browsers and a average feature version for all others.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We cannot use content negotiation because the browsers do
  +          not provide their type in that form. Instead we have to
  +          act on the HTTP header "User-Agent". The following condig
  +          does the following: If the HTTP header "User-Agent"
  +          begins with "Mozilla/3", the page <code>foo.html</code>
  +          is rewritten to <code>foo.NS.html</code> and and the
  +          rewriting stops. If the browser is "Lynx" or "Mozilla" of
  +          version 1 or 2 the URL becomes <code>foo.20.html</code>.
  +          All other browsers receive page <code>foo.32.html</code>.
  +          This is done by the following ruleset: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
  +RewriteCond %{HTTP_USER_AGENT}  ^<strong>Mozilla/3</strong>.*
  +RewriteRule ^foo\.html$         foo.<strong>NS</strong>.html          [<strong>L</strong>]
  +
  +RewriteCond %{HTTP_USER_AGENT}  ^<strong>Lynx/</strong>.*         [OR]
  +RewriteCond %{HTTP_USER_AGENT}  ^<strong>Mozilla/[12]</strong>.*
  +RewriteRule ^foo\.html$         foo.<strong>20</strong>.html          [<strong>L</strong>]
  +
  +RewriteRule ^foo\.html$         foo.<strong>32</strong>.html          [<strong>L</strong>]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Dynamic Mirror</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Assume there are nice webpages on remote hosts we want
  +        to bring into our namespace. For FTP servers we would use
  +        the <code>mirror</code> program which actually maintains an
  +        explicit up-to-date copy of the remote data on the local
  +        machine. For a webserver we could use the program
  +        <code>webcopy</code> which acts similar via HTTP. But both
  +        techniques have one major drawback: The local copy is
  +        always just as up-to-date as often we run the program. It
  +        would be much better if the mirror is not a static one we
  +        have to establish explicitly. Instead we want a dynamic
  +        mirror with data which gets updated automatically when
  +        there is need (updated data on the remote host).</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          To provide this feature we map the remote webpage or even
  +          the complete remote webarea to our namespace by the use
  +          of the <i>Proxy Throughput</i> feature (flag [P]): 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine  on
   RewriteBase    /~quux/
  -RewriteRule    ^<STRONG>hotsheet/</STRONG>(.*)$  <STRONG>http://www.tstimpreso.com/hotsheet/</STRONG>$1  [<STRONG>P</STRONG>]
  -</PRE></TD></TR></TABLE>
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule    ^<strong>hotsheet/</strong>(.*)$  <strong>http://www.tstimpreso.com/hotsheet/</strong>$1  [<strong>P</strong>]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine  on
   RewriteBase    /~quux/
  -RewriteRule    ^<STRONG>usa-news\.html</STRONG>$   <STRONG>http://www.quux-corp.com/news/index.html</STRONG>  [<STRONG>P</STRONG>]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Reverse Dynamic Mirror</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -...
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule    ^<strong>usa-news\.html</strong>$   <strong>http://www.quux-corp.com/news/index.html</strong>  [<strong>P</strong>]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Reverse Dynamic Mirror</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>...</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
   RewriteCond   /mirror/of/remotesite/$1           -U 
   RewriteRule   ^http://www\.remotesite\.com/(.*)$ /mirror/of/remotesite/$1
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Retrieve Missing Data from Intranet</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -This is a tricky way of virtually running a corporates (external) Internet
  -webserver (<CODE>www.quux-corp.dom</CODE>), while actually keeping and maintaining
  -its data on a (internal) Intranet webserver
  -(<CODE>www2.quux-corp.dom</CODE>) which is protected by a firewall.  The
  -trick is that on the external webserver we retrieve the requested data
  -on-the-fly from the internal one.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -First, we have to make sure that our firewall still protects the internal
  -webserver and that only the external webserver is allowed to retrieve data
  -from it. For a packet-filtering firewall we could for instance configure a
  -firewall ruleset like the following:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  -<STRONG>ALLOW</STRONG> Host www.quux-corp.dom Port &gt;1024 --&gt; Host www2.quux-corp.dom Port <STRONG>80</STRONG>  
  -<STRONG>DENY</STRONG>  Host *                 Port *     --&gt; Host www2.quux-corp.dom Port <STRONG>80</STRONG>
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -Just adjust it to your actual configuration syntax. Now we can establish the
  -mod_rewrite rules which request the missing data in the background through the
  -proxy throughput feature:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Retrieve Missing Data from Intranet</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>This is a tricky way of virtually running a corporates
  +        (external) Internet webserver
  +        (<code>www.quux-corp.dom</code>), while actually keeping
  +        and maintaining its data on a (internal) Intranet webserver
  +        (<code>www2.quux-corp.dom</code>) which is protected by a
  +        firewall. The trick is that on the external webserver we
  +        retrieve the requested data on-the-fly from the internal
  +        one.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          First, we have to make sure that our firewall still
  +          protects the internal webserver and that only the
  +          external webserver is allowed to retrieve data from it.
  +          For a packet-filtering firewall we could for instance
  +          configure a firewall ruleset like the following: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
  +<strong>ALLOW</strong> Host www.quux-corp.dom Port &gt;1024 --&gt; Host www2.quux-corp.dom Port <strong>80</strong>  
  +<strong>DENY</strong>  Host *                 Port *     --&gt; Host www2.quux-corp.dom Port <strong>80</strong>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>Just adjust it to your actual configuration syntax.
  +          Now we can establish the mod_rewrite rules which request
  +          the missing data in the background through the proxy
  +          throughput feature:</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteRule ^/~([^/]+)/?(.*)          /home/$1/.www/$2
  -RewriteCond %{REQUEST_FILENAME}       <STRONG>!-f</STRONG>
  -RewriteCond %{REQUEST_FILENAME}       <STRONG>!-d</STRONG>
  -RewriteRule ^/home/([^/]+)/.www/?(.*) http://<STRONG>www2</STRONG>.quux-corp.dom/~$1/pub/$2 [<STRONG>P</STRONG>]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Load Balancing</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Suppose we want to load balance the traffic to <CODE>www.foo.com</CODE> over
  -<CODE>www[0-5].foo.com</CODE> (a total of 6 servers). How can this be done?
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -There are a lot of possible solutions for this problem. We will discuss first
  -a commonly known DNS-based variant and then the special one with mod_rewrite:
  -
  -<ol>
  -<li><STRONG>DNS Round-Robin</STRONG>
  -
  -<P>
  -The simplest method for load-balancing is to use the DNS round-robin feature
  -of BIND. Here you just configure <CODE>www[0-9].foo.com</CODE> as usual in your
  -DNS with A(address) records, e.g.
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteCond %{REQUEST_FILENAME}       <strong>!-f</strong>
  +RewriteCond %{REQUEST_FILENAME}       <strong>!-d</strong>
  +RewriteRule ^/home/([^/]+)/.www/?(.*) http://<strong>www2</strong>.quux-corp.dom/~$1/pub/$2 [<strong>P</strong>]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Load Balancing</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Suppose we want to load balance the traffic to
  +        <code>www.foo.com</code> over <code>www[0-5].foo.com</code>
  +        (a total of 6 servers). How can this be done?</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          There are a lot of possible solutions for this problem.
  +          We will discuss first a commonly known DNS-based variant
  +          and then the special one with mod_rewrite: 
  +
  +          <ol>
  +            <li>
  +              <strong>DNS Round-Robin</strong> 
  +
  +              <p>The simplest method for load-balancing is to use
  +              the DNS round-robin feature of BIND. Here you just
  +              configure <code>www[0-9].foo.com</code> as usual in
  +              your DNS with A(address) records, e.g.</p>
  +
  +              <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +              cellpadding="5">
  +                <tr>
  +                  <td>
  +<pre>
   www0   IN  A       1.2.3.1
   www1   IN  A       1.2.3.2
   www2   IN  A       1.2.3.3
   www3   IN  A       1.2.3.4
   www4   IN  A       1.2.3.5
   www5   IN  A       1.2.3.6
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -Then you additionally add the following entry:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +                  </td>
  +                </tr>
  +              </table>
  +
  +              <p>Then you additionally add the following entry:</p>
  +
  +              <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +              cellpadding="5">
  +                <tr>
  +                  <td>
  +<pre>
   www    IN  CNAME   www0.foo.com.
          IN  CNAME   www1.foo.com.
          IN  CNAME   www2.foo.com.
  @@ -1063,60 +1326,89 @@
          IN  CNAME   www4.foo.com.
          IN  CNAME   www5.foo.com.
          IN  CNAME   www6.foo.com.
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -Notice that this seems wrong, but is actually an intended feature of BIND and
  -can be used in this way. However, now when <CODE>www.foo.com</CODE> gets resolved,
  -BIND gives out <CODE>www0-www6</CODE> - but in a slightly permutated/rotated order
  -every time.  This way the clients are spread over the various servers.
  -
  -But notice that this not a perfect load balancing scheme, because DNS resolve
  -information gets cached by the other nameservers on the net, so once a client
  -has resolved <CODE>www.foo.com</CODE> to a particular <CODE>wwwN.foo.com</CODE>, all
  -subsequent requests also go to this particular name <CODE>wwwN.foo.com</CODE>. But
  -the final result is ok, because the total sum of the requests are really
  -spread over the various webservers.
  -
  -<P>
  -<li><STRONG>DNS Load-Balancing</STRONG>
  -
  -<P>
  -A sophisticated DNS-based method for load-balancing is to use the program
  -<CODE>lbnamed</CODE> which can be found at <A
  -HREF="http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html">http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html</A>.
  -It is a Perl 5 program in conjunction with auxilliary tools which provides a
  -real load-balancing for DNS.
  -
  -<P>
  -<li><STRONG>Proxy Throughput Round-Robin</STRONG>
  -
  -<P>
  -In this variant we use mod_rewrite and its proxy throughput feature.  First we
  -dedicate <CODE>www0.foo.com</CODE> to be actually <CODE>www.foo.com</CODE> by using a
  -single
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +                  </td>
  +                </tr>
  +              </table>
  +
  +              <p>Notice that this seems wrong, but is actually an
  +              intended feature of BIND and can be used in this way.
  +              However, now when <code>www.foo.com</code> gets
  +              resolved, BIND gives out <code>www0-www6</code> - but
  +              in a slightly permutated/rotated order every time.
  +              This way the clients are spread over the various
  +              servers. But notice that this not a perfect load
  +              balancing scheme, because DNS resolve information
  +              gets cached by the other nameservers on the net, so
  +              once a client has resolved <code>www.foo.com</code>
  +              to a particular <code>wwwN.foo.com</code>, all
  +              subsequent requests also go to this particular name
  +              <code>wwwN.foo.com</code>. But the final result is
  +              ok, because the total sum of the requests are really
  +              spread over the various webservers.</p>
  +            </li>
  +
  +            <li>
  +              <strong>DNS Load-Balancing</strong> 
  +
  +              <p>A sophisticated DNS-based method for
  +              load-balancing is to use the program
  +              <code>lbnamed</code> which can be found at <a
  +              href="http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html">
  +              http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html</a>.
  +              It is a Perl 5 program in conjunction with auxilliary
  +              tools which provides a real load-balancing for
  +              DNS.</p>
  +            </li>
  +
  +            <li>
  +              <strong>Proxy Throughput Round-Robin</strong> 
  +
  +              <p>In this variant we use mod_rewrite and its proxy
  +              throughput feature. First we dedicate
  +              <code>www0.foo.com</code> to be actually
  +              <code>www.foo.com</code> by using a single</p>
  +
  +              <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +              cellpadding="5">
  +                <tr>
  +                  <td>
  +<pre>
   www    IN  CNAME   www0.foo.com.
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -entry in the DNS. Then we convert <CODE>www0.foo.com</CODE> to a proxy-only
  -server, i.e. we configure this machine so all arriving URLs are just pushed
  -through the internal proxy to one of the 5 other servers (<CODE>www1-www5</CODE>).
  -To accomplish this we first establish a ruleset which contacts a load
  -balancing script <CODE>lb.pl</CODE> for all URLs.
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +                  </td>
  +                </tr>
  +              </table>
  +
  +              <p>entry in the DNS. Then we convert
  +              <code>www0.foo.com</code> to a proxy-only server,
  +              i.e. we configure this machine so all arriving URLs
  +              are just pushed through the internal proxy to one of
  +              the 5 other servers (<code>www1-www5</code>). To
  +              accomplish this we first establish a ruleset which
  +              contacts a load balancing script <code>lb.pl</code>
  +              for all URLs.</p>
  +
  +              <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +              cellpadding="5">
  +                <tr>
  +                  <td>
  +<pre>
   RewriteEngine on
   RewriteMap    lb      prg:/path/to/lb.pl
   RewriteRule   ^/(.+)$ ${lb:$1}           [P,L]
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -Then we write <CODE>lb.pl</CODE>:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +                  </td>
  +                </tr>
  +              </table>
  +
  +              <p>Then we write <code>lb.pl</code>:</p>
  +
  +              <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +              cellpadding="5">
  +                <tr>
  +                  <td>
  +<pre>
   #!/path/to/perl
   ##
   ##  lb.pl -- load balancing script
  @@ -1137,41 +1429,48 @@
   }
   
   ##EOF##
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -A last notice: Why is this useful? Seems like <CODE>www0.foo.com</CODE> still is
  -overloaded? The answer is yes, it is overloaded, but with plain proxy
  -throughput requests, only! All SSI, CGI, ePerl, etc. processing is completely
  -done on the other machines. This is the essential point.
  -
  -<P>
  -<li><STRONG>Hardware/TCP Round-Robin</STRONG>
  -
  -<P>
  -There is a hardware solution available, too. Cisco has a beast called
  -LocalDirector which does a load balancing at the TCP/IP level. Actually this
  -is some sort of a circuit level gateway in front of a webcluster.  If you have
  -enough money and really need a solution with high performance, use this one.
  -
  -</ol>
  -
  -</DL>
  -
  -<P>
  -<H2>Reverse Proxy</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -...
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +                  </td>
  +                </tr>
  +              </table>
  +
  +              <p>A last notice: Why is this useful? Seems like
  +              <code>www0.foo.com</code> still is overloaded? The
  +              answer is yes, it is overloaded, but with plain proxy
  +              throughput requests, only! All SSI, CGI, ePerl, etc.
  +              processing is completely done on the other machines.
  +              This is the essential point.</p>
  +            </li>
  +
  +            <li>
  +              <strong>Hardware/TCP Round-Robin</strong> 
  +
  +              <p>There is a hardware solution available, too. Cisco
  +              has a beast called LocalDirector which does a load
  +              balancing at the TCP/IP level. Actually this is some
  +              sort of a circuit level gateway in front of a
  +              webcluster. If you have enough money and really need
  +              a solution with high performance, use this one.</p>
  +            </li>
  +          </ol>
  +        </dd>
  +      </dl>
  +
  +      <h2>Reverse Proxy</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>...</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   ##
   ##  apache-rproxy.conf -- Apache configuration for Reverse Proxy Usage
   ##
  @@ -1256,9 +1555,16 @@
   ProxyPassReverse  /  http://www4.foo.dom/
   ProxyPassReverse  /  http://www5.foo.dom/
   ProxyPassReverse  /  http://www6.foo.dom/
  -</PRE></TD></TR></TABLE>
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   ##
   ##  apache-rproxy.conf-servers -- Apache/mod_rewrite selection table
   ##
  @@ -1270,182 +1576,227 @@
   #   list of backend servers which serve dynamically 
   #   generated page (CGI programs or mod_perl scripts)
   dynamic   www5.foo.dom|www6.foo.dom
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>New MIME-type, New Service</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -On the net there are a lot of nifty CGI programs. But their usage is usually
  -boring, so a lot of webmaster don't use them.  Even Apache's Action handler
  -feature for MIME-types is only appropriate when the CGI programs don't need
  -special URLs (actually PATH_INFO and QUERY_STRINGS) as their input. 
  -
  -First, let us configure a new file type with extension <CODE>.scgi</CODE>
  -(for secure CGI) which will be processed by the popular <CODE>cgiwrap</CODE>
  -program. The problem here is that for instance we use a Homogeneous URL Layout
  -(see above) a file inside the user homedirs has the URL
  -<CODE>/u/user/foo/bar.scgi</CODE>. But <CODE>cgiwrap</CODE> needs the URL in the form
  -<CODE>/~user/foo/bar.scgi/</CODE>. The following rule solves the problem:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  -RewriteRule ^/[uge]/<STRONG>([^/]+)</STRONG>/\.www/(.+)\.scgi(.*) ...
  -... /internal/cgi/user/cgiwrap/~<STRONG>$1</STRONG>/$2.scgi$3  [NS,<STRONG>T=application/x-http-cgi</STRONG>]
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -Or assume we have some more nifty programs:
  -<CODE>wwwlog</CODE> (which displays the <CODE>access.log</CODE> for a URL subtree and
  -<CODE>wwwidx</CODE> (which runs Glimpse on a URL subtree). We have to
  -provide the URL area to these programs so they know on which area
  -they have to act on. But usually this ugly, because they are all the
  -times still requested from that areas, i.e. typically we would run
  -the <CODE>swwidx</CODE> program from within <CODE>/u/user/foo/</CODE> via
  -hyperlink to
  -
  -<P><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>New MIME-type, New Service</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>
  +          On the net there are a lot of nifty CGI programs. But
  +          their usage is usually boring, so a lot of webmaster
  +          don't use them. Even Apache's Action handler feature for
  +          MIME-types is only appropriate when the CGI programs
  +          don't need special URLs (actually PATH_INFO and
  +          QUERY_STRINGS) as their input. First, let us configure a
  +          new file type with extension <code>.scgi</code> (for
  +          secure CGI) which will be processed by the popular
  +          <code>cgiwrap</code> program. The problem here is that
  +          for instance we use a Homogeneous URL Layout (see above)
  +          a file inside the user homedirs has the URL
  +          <code>/u/user/foo/bar.scgi</code>. But
  +          <code>cgiwrap</code> needs the URL in the form
  +          <code>/~user/foo/bar.scgi/</code>. The following rule
  +          solves the problem: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
  +RewriteRule ^/[uge]/<strong>([^/]+)</strong>/\.www/(.+)\.scgi(.*) ...
  +... /internal/cgi/user/cgiwrap/~<strong>$1</strong>/$2.scgi$3  [NS,<strong>T=application/x-http-cgi</strong>]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>Or assume we have some more nifty programs:
  +          <code>wwwlog</code> (which displays the
  +          <code>access.log</code> for a URL subtree and
  +          <code>wwwidx</code> (which runs Glimpse on a URL
  +          subtree). We have to provide the URL area to these
  +          programs so they know on which area they have to act on.
  +          But usually this ugly, because they are all the times
  +          still requested from that areas, i.e. typically we would
  +          run the <code>swwidx</code> program from within
  +          <code>/u/user/foo/</code> via hyperlink to</p>
  +<pre>
   /internal/cgi/user/swwidx?i=/u/user/foo/
  -</PRE><P>
  +</pre>
   
  -which is ugly. Because we have to hard-code <STRONG>both</STRONG> the location of the
  -area <STRONG>and</STRONG> the location of the CGI inside the hyperlink. When we have to
  -reorganise or area, we spend a lot of time changing the various hyperlinks.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -The solution here is to provide a special new URL format which automatically
  -leads to the proper CGI invocation. We configure the following:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +          <p>which is ugly. Because we have to hard-code
  +          <strong>both</strong> the location of the area
  +          <strong>and</strong> the location of the CGI inside the
  +          hyperlink. When we have to reorganise or area, we spend a
  +          lot of time changing the various hyperlinks.</p>
  +        </dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          The solution here is to provide a special new URL format
  +          which automatically leads to the proper CGI invocation.
  +          We configure the following: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteRule   ^/([uge])/([^/]+)(/?.*)/\*  /internal/cgi/user/wwwidx?i=/$1/$2$3/
   RewriteRule   ^/([uge])/([^/]+)(/?.*):log /internal/cgi/user/wwwlog?f=/$1/$2$3
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -Now the hyperlink to search at <CODE>/u/user/foo/</CODE> reads only
  -
  -<P><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>Now the hyperlink to search at
  +          <code>/u/user/foo/</code> reads only</p>
  +<pre>
   HREF="*"
  -</PRE><P>
  -
  -which internally gets automatically transformed to 
  +</pre>
   
  -<P><PRE>
  +          <p>which internally gets automatically transformed to</p>
  +<pre>
   /internal/cgi/user/wwwidx?i=/u/user/foo/
  -</PRE><P>
  -
  -The same approach leads to an invocation for the access log CGI
  -program when the hyperlink <CODE>:log</CODE> gets used.
  -
  -</DL>
  +</pre>
   
  -<P>
  -<H2>From Static to Dynamic</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -How can we transform a static page <CODE>foo.html</CODE> into a dynamic variant
  -<CODE>foo.cgi</CODE> in a seemless way, i.e.  without notice by the browser/user.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We just rewrite the URL to the CGI-script and force the correct MIME-type so
  -it gets really run as a CGI-script. This way a request to
  -<CODE>/~quux/foo.html</CODE> internally leads to the invokation of
  -<CODE>/~quux/foo.cgi</CODE>.
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +          <p>The same approach leads to an invocation for the
  +          access log CGI program when the hyperlink
  +          <code>:log</code> gets used.</p>
  +        </dd>
  +      </dl>
  +
  +      <h2>From Static to Dynamic</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>How can we transform a static page
  +        <code>foo.html</code> into a dynamic variant
  +        <code>foo.cgi</code> in a seemless way, i.e. without notice
  +        by the browser/user.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We just rewrite the URL to the CGI-script and force the
  +          correct MIME-type so it gets really run as a CGI-script.
  +          This way a request to <code>/~quux/foo.html</code>
  +          internally leads to the invokation of
  +          <code>/~quux/foo.cgi</code>. 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine  on
   RewriteBase    /~quux/
  -RewriteRule    ^foo\.<STRONG>html</STRONG>$  foo.<STRONG>cgi</STRONG>  [T=<STRONG>application/x-httpd-cgi</STRONG>]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>On-the-fly Content-Regeneration</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Here comes a really esoteric feature: Dynamically generated but statically
  -served pages, i.e. pages should be delivered as pure static pages (read from
  -the filesystem and just passed through), but they have to be generated
  -dynamically by the webserver if missing. This way you can have CGI-generated
  -pages which are statically served unless one (or a cronjob) removes the static
  -contents. Then the contents gets refreshed.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -This is done via the following ruleset:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  -RewriteCond %{REQUEST_FILENAME}   <STRONG>!-s</STRONG>
  -RewriteRule ^page\.<STRONG>html</STRONG>$          page.<STRONG>cgi</STRONG>   [T=application/x-httpd-cgi,L]
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -Here a request to <CODE>page.html</CODE> leads to a internal run of a
  -corresponding <CODE>page.cgi</CODE> if <CODE>page.html</CODE> is still missing or has
  -filesize null. The trick here is that <CODE>page.cgi</CODE> is a usual CGI script
  -which (additionally to its STDOUT) writes its output to the file
  -<CODE>page.html</CODE>. Once it was run, the server sends out the data of
  -<CODE>page.html</CODE>. When the webmaster wants to force a refresh the contents,
  -he just removes <CODE>page.html</CODE> (usually done by a cronjob).
  -
  -</DL>
  -
  -<P>
  -<H2>Document With Autorefresh</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Wouldn't it be nice while creating a complex webpage if the webbrowser would
  -automatically refresh the page every time we write a new version from within
  -our editor? Impossible?
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -No! We just combine the MIME multipart feature, the webserver NPH feature and
  -the URL manipulation power of mod_rewrite. First, we establish a new URL
  -feature: Adding just <CODE>:refresh</CODE> to any URL causes this to be refreshed
  -every time it gets updated on the filesystem.
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule    ^foo\.<strong>html</strong>$  foo.<strong>cgi</strong>  [T=<strong>application/x-httpd-cgi</strong>]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>On-the-fly Content-Regeneration</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Here comes a really esoteric feature: Dynamically
  +        generated but statically served pages, i.e. pages should be
  +        delivered as pure static pages (read from the filesystem
  +        and just passed through), but they have to be generated
  +        dynamically by the webserver if missing. This way you can
  +        have CGI-generated pages which are statically served unless
  +        one (or a cronjob) removes the static contents. Then the
  +        contents gets refreshed.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          This is done via the following ruleset: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
  +RewriteCond %{REQUEST_FILENAME}   <strong>!-s</strong>
  +RewriteRule ^page\.<strong>html</strong>$          page.<strong>cgi</strong>   [T=application/x-httpd-cgi,L]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>Here a request to <code>page.html</code> leads to a
  +          internal run of a corresponding <code>page.cgi</code> if
  +          <code>page.html</code> is still missing or has filesize
  +          null. The trick here is that <code>page.cgi</code> is a
  +          usual CGI script which (additionally to its STDOUT)
  +          writes its output to the file <code>page.html</code>.
  +          Once it was run, the server sends out the data of
  +          <code>page.html</code>. When the webmaster wants to force
  +          a refresh the contents, he just removes
  +          <code>page.html</code> (usually done by a cronjob).</p>
  +        </dd>
  +      </dl>
  +
  +      <h2>Document With Autorefresh</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Wouldn't it be nice while creating a complex webpage if
  +        the webbrowser would automatically refresh the page every
  +        time we write a new version from within our editor?
  +        Impossible?</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          No! We just combine the MIME multipart feature, the
  +          webserver NPH feature and the URL manipulation power of
  +          mod_rewrite. First, we establish a new URL feature:
  +          Adding just <code>:refresh</code> to any URL causes this
  +          to be refreshed every time it gets updated on the
  +          filesystem. 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteRule   ^(/[uge]/[^/]+/?.*):refresh  /internal/cgi/apache/nph-refresh?f=$1
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -Now when we reference the URL
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
   
  -<P><PRE>
  +          <p>Now when we reference the URL</p>
  +<pre>
   /u/foo/bar/page.html:refresh
  -</PRE><P>
  +</pre>
   
  -this leads to the internal invocation of the URL
  -
  -<P><PRE>
  +          <p>this leads to the internal invocation of the URL</p>
  +<pre>
   /internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html
  -</PRE><P>
  -
  -The only missing part is the NPH-CGI script. Although one would usually say
  -"left as an exercise to the reader" ;-) I will provide this, too.
  +</pre>
   
  -<P><PRE>
  +          <p>The only missing part is the NPH-CGI script. Although
  +          one would usually say "left as an exercise to the reader"
  +          ;-) I will provide this, too.</p>
  +<pre>
   #!/sw/bin/perl
   ##
   ##  nph-refresh -- NPH/CGI script for auto refreshing pages
  @@ -1547,29 +1898,33 @@
   exit(0);
   
   ##EOF##
  -</PRE>
  -
  -</DL>
  -
  -<P>
  -<H2>Mass Virtual Hosting</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -The <CODE>&lt;VirtualHost&gt;</CODE> feature of Apache is nice and works great
  -when you just have a few dozens virtual hosts. But when you are an ISP and
  -have hundreds of virtual hosts to provide this feature is not the best choice.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -To provide this feature we map the remote webpage or even the complete remote
  -webarea to our namespace by the use of the <I>Proxy Throughput</I> feature
  -(flag [P]):
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +        </dd>
  +      </dl>
  +
  +      <h2>Mass Virtual Hosting</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>The <code>&lt;VirtualHost&gt;</code> feature of Apache
  +        is nice and works great when you just have a few dozens
  +        virtual hosts. But when you are an ISP and have hundreds of
  +        virtual hosts to provide this feature is not the best
  +        choice.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          To provide this feature we map the remote webpage or even
  +          the complete remote webarea to our namespace by the use
  +          of the <i>Proxy Throughput</i> feature (flag [P]): 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   ##
   ##  vhost.map 
   ## 
  @@ -1577,9 +1932,16 @@
   www.vhost2.dom:80  /path/to/docroot/vhost2
        :
   www.vhostN.dom:80  /path/to/docroot/vhostN
  -</PRE></TD></TR></TABLE>
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   ##
   ##  httpd.conf
   ##
  @@ -1627,101 +1989,135 @@
   #      and remember the virtual host for logging puposes
   RewriteRule   ^/(.*)$   %1/$1  [E=VHOST:${lowercase:%{HTTP_HOST}}]
       : 
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<H1>Access Restriction</H1>
  -
  -<P>
  -<H2>Blocking of Robots</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -How can we block a really annoying robot from retrieving pages of a specific
  -webarea? A <CODE>/robots.txt</CODE> file containing entries of the "Robot
  -Exclusion Protocol" is typically not enough to get rid of such a robot.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We use a ruleset which forbids the URLs of the webarea
  -<CODE>/~quux/foo/arc/</CODE> (perhaps a very deep directory indexed area where the
  -robot traversal would create big server load).   We have to make sure that we
  -forbid access only to the particular robot, i.e. just forbidding the host
  -where the robot runs is not enough. This would block users from this host,
  -too. We accomplish this by also matching the User-Agent HTTP header
  -information.
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  -RewriteCond %{HTTP_USER_AGENT}   ^<STRONG>NameOfBadRobot</STRONG>.*      
  -RewriteCond %{REMOTE_ADDR}       ^<STRONG>123\.45\.67\.[8-9]</STRONG>$
  -RewriteRule ^<STRONG>/~quux/foo/arc/</STRONG>.+   -   [<STRONG>F</STRONG>]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Blocked Inline-Images</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Assume we have under http://www.quux-corp.de/~quux/ some pages with inlined
  -GIF graphics. These graphics are nice, so others directly incorporate them via
  -hyperlinks to their pages. We don't like this practice because it adds useless
  -traffic to our server.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -While we cannot 100% protect the images from inclusion, we
  -can at least restrict the cases where the browser sends
  -a HTTP Referer header.
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  -RewriteCond %{HTTP_REFERER} <STRONG>!^$</STRONG>                                  
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h1>Access Restriction</h1>
  +
  +      <h2>Blocking of Robots</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>How can we block a really annoying robot from
  +        retrieving pages of a specific webarea? A
  +        <code>/robots.txt</code> file containing entries of the
  +        "Robot Exclusion Protocol" is typically not enough to get
  +        rid of such a robot.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We use a ruleset which forbids the URLs of the webarea
  +          <code>/~quux/foo/arc/</code> (perhaps a very deep
  +          directory indexed area where the robot traversal would
  +          create big server load). We have to make sure that we
  +          forbid access only to the particular robot, i.e. just
  +          forbidding the host where the robot runs is not enough.
  +          This would block users from this host, too. We accomplish
  +          this by also matching the User-Agent HTTP header
  +          information. 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
  +RewriteCond %{HTTP_USER_AGENT}   ^<strong>NameOfBadRobot</strong>.*      
  +RewriteCond %{REMOTE_ADDR}       ^<strong>123\.45\.67\.[8-9]</strong>$
  +RewriteRule ^<strong>/~quux/foo/arc/</strong>.+   -   [<strong>F</strong>]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Blocked Inline-Images</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Assume we have under http://www.quux-corp.de/~quux/
  +        some pages with inlined GIF graphics. These graphics are
  +        nice, so others directly incorporate them via hyperlinks to
  +        their pages. We don't like this practice because it adds
  +        useless traffic to our server.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          While we cannot 100% protect the images from inclusion,
  +          we can at least restrict the cases where the browser
  +          sends a HTTP Referer header. 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
  +RewriteCond %{HTTP_REFERER} <strong>!^$</strong>                                  
   RewriteCond %{HTTP_REFERER} !^http://www.quux-corp.de/~quux/.*$ [NC]
  -RewriteRule <STRONG>.*\.gif$</STRONG>        -                                    [F]
  -</PRE></TD></TR></TABLE>
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule <strong>.*\.gif$</strong>        -                                    [F]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteCond %{HTTP_REFERER}         !^$                                  
   RewriteCond %{HTTP_REFERER}         !.*/foo-with-gif\.html$
  -RewriteRule <STRONG>^inlined-in-foo\.gif$</STRONG>   -                        [F]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Host Deny</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -How can we forbid a list of externally configured hosts from using our server?
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -
  -For Apache &gt;= 1.3b6:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteRule <strong>^inlined-in-foo\.gif$</strong>   -                        [F]
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Host Deny</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>How can we forbid a list of externally configured hosts
  +        from using our server?</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          For Apache &gt;= 1.3b6: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
   RewriteMap    hosts-deny  txt:/path/to/hosts.deny
   RewriteCond   ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND [OR]
   RewriteCond   ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND
   RewriteRule   ^/.*  -  [F]
  -</PRE></TD></TR></TABLE><P>
  -
  -For Apache &lt;= 1.3b6:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>For Apache &lt;= 1.3b6:</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
   RewriteMap    hosts-deny  txt:/path/to/hosts.deny
   RewriteRule   ^/(.*)$ ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND}/$1
  @@ -1729,9 +2125,16 @@
   RewriteRule   ^NOT-FOUND/(.*)$ ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND}/$1 
   RewriteRule   !^NOT-FOUND/.* - [F]
   RewriteRule   ^NOT-FOUND/(.*)$ /$1
  -</PRE></TD></TR></TABLE>
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   ##
   ##  hosts.deny 
   ##
  @@ -1743,34 +2146,44 @@
   193.102.180.41 -
   bsdti1.sdm.de  -
   192.76.162.40  -
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>URL-Restricted Proxy</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -How can we restrict the proxy to allow access to a configurable set of
  -internet sites only? The site list is extracted from a prepared bookmarks file.
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We first have to make sure mod_rewrite is below(!) mod_proxy in the
  -<CODE>Configuration</CODE> file when compiling the Apache webserver
  -(or in the <CODE>AddModule</CODE> list of <CODE>httpd.conf</CODE>
  -in the case of dynamically loaded modules), as it must get called
  -<em>_before_</em> mod_proxy.
  -<P>
  -For simplicity, we generate the site list as a textfile map (but see the
  -<a href="../mod/mod_rewrite.html#RewriteMap">mod_rewrite documentation</a>
  -for a conversion script to DBM format). A typical Netscape bookmarks file
  -can be converted to a list of sites with a shell script like this:
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>URL-Restricted Proxy</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>How can we restrict the proxy to allow access to a
  +        configurable set of internet sites only? The site list is
  +        extracted from a prepared bookmarks file.</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We first have to make sure mod_rewrite is below(!)
  +          mod_proxy in the <code>Configuration</code> file when
  +          compiling the Apache webserver (or in the
  +          <code>AddModule</code> list of <code>httpd.conf</code> in
  +          the case of dynamically loaded modules), as it must get
  +          called <em>_before_</em> mod_proxy. 
  +
  +          <p>For simplicity, we generate the site list as a
  +          textfile map (but see the <a
  +          href="../mod/mod_rewrite.html#RewriteMap">mod_rewrite
  +          documentation</a> for a conversion script to DBM format).
  +          A typical Netscape bookmarks file can be converted to a
  +          list of sites with a shell script like this:</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   #!/bin/sh
   cat ${1:-~/.netscape/bookmarks.html} |
   tr -d '\015' | tr '[A-Z]' '[a-z]' | grep href=\" |
  @@ -1778,23 +2191,40 @@
       -e 's|^.*href="[^:]*://\([^:/"]*\).*$|\1 OK|;' \
       -e '/href="/s|^.*href="\([^:/"]*\).*$|\1 OK|;' |
   sort -u
  -</PRE></TD></TR></TABLE>
  -
  -<P>We redirect the resulting output into a text file called
  -<CODE>goodsites.txt</CODE>. It now looks similar to this:
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>We redirect the resulting output into a text file
  +          called <code>goodsites.txt</code>. It now looks similar
  +          to this:</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   www.apache.org OK
   xml.apache.org OK
   jakarta.apache.org OK
   perl.apache.org OK
   ...
  -</PRE></TD></TR></TABLE>
  -
  -<P>We reference this site file within the configuration for the
  -<CODE>VirtualHost</CODE> which is responsible for serving as a proxy
  -(often not port 80, but 81, 8080 or 8008).
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>We reference this site file within the configuration
  +          for the <code>VirtualHost</code> which is responsible for
  +          serving as a proxy (often not port 80, but 81, 8080 or
  +          8008).</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   &lt;VirtualHost *:8008&gt;
     ...
     RewriteEngine   On
  @@ -1815,84 +2245,110 @@
     RewriteRule  ^proxy:                      -              [F]
     ...
   &lt;/VirtualHost&gt;
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Proxy Deny</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -How can we forbid a certain host or even a user of a special host from using
  -the Apache proxy?
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We first have to make sure mod_rewrite is below(!) mod_proxy in the
  -<CODE>Configuration</CODE> file when compiling the Apache webserver.  This way it
  -gets called <em>_before_</em> mod_proxy. Then we configure the following for a
  -host-dependend deny...
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  -RewriteCond %{REMOTE_HOST} <STRONG>^badhost\.mydomain\.com$</STRONG> 
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Proxy Deny</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>How can we forbid a certain host or even a user of a
  +        special host from using the Apache proxy?</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We first have to make sure mod_rewrite is below(!)
  +          mod_proxy in the <code>Configuration</code> file when
  +          compiling the Apache webserver. This way it gets called
  +          <em>_before_</em> mod_proxy. Then we configure the
  +          following for a host-dependend deny... 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
  +RewriteCond %{REMOTE_HOST} <strong>^badhost\.mydomain\.com$</strong> 
   RewriteRule !^http://[^/.]\.mydomain.com.*  - [F]
  -</PRE></TD></TR></TABLE>
  -
  -<P>...and this one for a user@host-dependend deny:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  -RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST}  <STRONG>^badguy@badhost\.mydomain\.com$</STRONG>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>...and this one for a user@host-dependend deny:</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
  +RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST}  <strong>^badguy@badhost\.mydomain\.com$</strong>
   RewriteRule !^http://[^/.]\.mydomain.com.*  - [F]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Special Authentication Variant</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -Sometimes a very special authentication is needed, for instance a
  -authentication which checks for a set of explicitly configured users. Only
  -these should receive access and without explicit prompting (which would occur
  -when using the Basic Auth via mod_access).
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -We use a list of rewrite conditions to exclude all except our friends:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  -RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <STRONG>!^friend1@client1.quux-corp\.com$</STRONG> 
  -RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <STRONG>!^friend2</STRONG>@client2.quux-corp\.com$ 
  -RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <STRONG>!^friend3</STRONG>@client3.quux-corp\.com$ 
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Special Authentication Variant</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>Sometimes a very special authentication is needed, for
  +        instance a authentication which checks for a set of
  +        explicitly configured users. Only these should receive
  +        access and without explicit prompting (which would occur
  +        when using the Basic Auth via mod_access).</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          We use a list of rewrite conditions to exclude all except
  +          our friends: 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
  +RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend1@client1.quux-corp\.com$</strong> 
  +RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend2</strong>@client2.quux-corp\.com$ 
  +RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend3</strong>@client3.quux-corp\.com$ 
   RewriteRule ^/~quux/only-for-friends/      -                                 [F]
  -</PRE></TD></TR></TABLE>
  -
  -</DL>
  -
  -<P>
  -<H2>Referer-based Deflector</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -How can we program a flexible URL Deflector which acts on the "Referer" HTTP
  -header and can be configured with as many referring pages as we like?
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -Use the following really tricky ruleset...
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +        </dd>
  +      </dl>
  +
  +      <h2>Referer-based Deflector</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>How can we program a flexible URL Deflector which acts
  +        on the "Referer" HTTP header and can be configured with as
  +        many referring pages as we like?</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          Use the following really tricky ruleset... 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteMap  deflector txt:/path/to/deflector.map
   
   RewriteCond %{HTTP_REFERER} !=""
  @@ -1902,12 +2358,19 @@
   RewriteCond %{HTTP_REFERER} !=""
   RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND
   RewriteRule ^.* ${deflector:%{HTTP_REFERER}} [R,L]
  -</PRE></TD></TR></TABLE>
  -
  -<P>...
  -in conjunction with a corresponding rewrite map:
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>... in conjunction with a corresponding rewrite
  +          map:</p>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   ##
   ##  deflector.map
   ##
  @@ -1915,41 +2378,55 @@
   http://www.badguys.com/bad/index.html    -
   http://www.badguys.com/bad/index2.html   -
   http://www.badguys.com/bad/index3.html   http://somewhere.com/
  -</PRE></TD></TR></TABLE>
  -
  -<P>
  -This automatically redirects the request back to the referring page (when "-"
  -is used as the value in the map) or to a specific URL (when an URL is
  -specified in the map as the second argument).
  -
  -</DL>
  -
  -<H1>Other</H1>
  -
  -<P>
  -<H2>External Rewriting Engine</H2>
  -<P>
  -
  -<DL>
  -<DT><STRONG>Description:</STRONG>
  -<DD>
  -A FAQ: How can we solve the FOO/BAR/QUUX/etc. problem? There seems no solution
  -by the use of mod_rewrite...
  -
  -<P>
  -<DT><STRONG>Solution:</STRONG>
  -<DD>
  -Use an external rewrite map, i.e. a program which acts like a rewrite map.  It
  -is run once on startup of Apache receives the requested URLs on STDIN and has
  -to put the resulting (usually rewritten) URL on STDOUT (same order!).
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>This automatically redirects the request back to the
  +          referring page (when "-" is used as the value in the map)
  +          or to a specific URL (when an URL is specified in the map
  +          as the second argument).</p>
  +        </dd>
  +      </dl>
  +
  +      <h1>Other</h1>
  +
  +      <h2>External Rewriting Engine</h2>
  +
  +      <dl>
  +        <dt><strong>Description:</strong></dt>
  +
  +        <dd>A FAQ: How can we solve the FOO/BAR/QUUX/etc. problem?
  +        There seems no solution by the use of mod_rewrite...</dd>
  +
  +        <dt><strong>Solution:</strong></dt>
  +
  +        <dd>
  +          Use an external rewrite map, i.e. a program which acts
  +          like a rewrite map. It is run once on startup of Apache
  +          receives the requested URLs on STDIN and has to put the
  +          resulting (usually rewritten) URL on STDOUT (same
  +          order!). 
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   RewriteEngine on
  -RewriteMap    quux-map       <STRONG>prg:</STRONG>/path/to/map.quux.pl
  -RewriteRule   ^/~quux/(.*)$  /~quux/<STRONG>${quux-map:$1}</STRONG>
  -</PRE></TD></TR></TABLE>
  -
  -<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
  +RewriteMap    quux-map       <strong>prg:</strong>/path/to/map.quux.pl
  +RewriteRule   ^/~quux/(.*)$  /~quux/<strong>${quux-map:$1}</strong>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <table bgcolor="#E0E5F5" border="0" cellspacing="0"
  +          cellpadding="5">
  +            <tr>
  +              <td>
  +<pre>
   #!/path/to/perl
   
   #   disable buffered I/O which would lead 
  @@ -1962,17 +2439,21 @@
       s|^foo/|bar/|;
       print $_;
   }
  -</PRE></TD></TR></TABLE>
  +</pre>
  +              </td>
  +            </tr>
  +          </table>
  +
  +          <p>This is a demonstration-only example and just rewrites
  +          all URLs <code>/~quux/foo/...</code> to
  +          <code>/~quux/bar/...</code>. Actually you can program
  +          whatever you like. But notice that while such maps can be
  +          <strong>used</strong> also by an average user, only the
  +          system administrator can <strong>define</strong> it.</p>
  +        </dd>
  +      </dl>
  +      <!--#include virtual="footer.html" -->
  +    </blockquote>
  +  </body>
  +</html>
   
  -<P>
  -This is a demonstration-only example and just rewrites all URLs
  -<CODE>/~quux/foo/...</CODE> to <CODE>/~quux/bar/...</CODE>. Actually you can program
  -whatever you like. But notice that while such maps can be <STRONG>used</STRONG> also by
  -an average user, only the system administrator can <STRONG>define</STRONG> it.
  -
  -</DL>
  -
  -<!--#include virtual="footer.html" -->
  -</BLOCKQUOTE>
  -</BODY>
  -</HTML>
  
  
  
  1.27      +57 -60    httpd-docs-1.3/htdocs/manual/misc/security_tips.html
  
  Index: security_tips.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/security_tips.html,v
  retrieving revision 1.26
  retrieving revision 1.27
  diff -u -r1.26 -r1.27
  --- security_tips.html	2001/10/05 21:23:46	1.26
  +++ security_tips.html	2001/10/08 01:26:54	1.27
  @@ -4,6 +4,7 @@
   <html xmlns="http://www.w3.org/1999/xhtml">
     <head>
       <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
       <title>Apache HTTP Server: Security Tips</title>
     </head>
     <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  @@ -50,9 +51,9 @@
       modification by non-root users. Not only must the files
       themselves be writeable only by root, but so must the
       directories, and parents of all directories. For example, if
  -    you choose to place ServerRoot in <code>
  -    /usr/local/apache</code> then it is suggested that you create
  -    that directory as root, with commands like these:</p>
  +    you choose to place ServerRoot in
  +    <code>/usr/local/apache</code> then it is suggested that you
  +    create that directory as root, with commands like these:</p>
   
       <blockquote>
   <pre>
  @@ -94,50 +95,47 @@
       <hr />
   
       <h2><a id="ssi" name="ssi">Server Side Includes</a></h2>
  +
  +    <p>Server Side Includes (SSI) present a server administrator
  +    with several potential security risks.</p>
   
  -    <p>Server Side Includes (SSI) present a server administrator with
  -    several potential security risks.</p>
  +    <p>The first risk is the increased load on the server. All
  +    SSI-enabled files have to be parsed by Apache, whether or not
  +    there are any SSI directives included within the files. While
  +    this load increase is minor, in a shared server environment it
  +    can become significant.</p>
  +
  +    <p>SSI files also pose the same risks that are associated with
  +    CGI scripts in general. Using the "exec cmd" element,
  +    SSI-enabled files can execute any CGI script or program under
  +    the permissions of the user and group Apache runs as, as
  +    configured in httpd.conf. That should definitely give server
  +    administrators pause.</p>
   
  -    <p>
  -    The first risk is the increased load on the server.  All SSI-enabled
  -    files have to be parsed by Apache, whether or not there are any SSI
  -    directives included within the files.  While this load increase is
  -    minor, in a shared server environment it can become significant.</p>
  -
  -    <p>
  -    SSI files also pose the same risks that are associated with CGI
  -    scripts in general.  Using the "exec cmd" element, SSI-enabled
  -    files can execute any CGI script or program under the permissions
  -    of the user and group Apache runs as, as configured in httpd.conf.
  -    That should definitely give server administrators pause.</p>
  -
  -    <p>
  -    There are ways to enhance the security of SSI files while still taking
  -    advantage of the benefits they provide.</p>
  +    <p>There are ways to enhance the security of SSI files while
  +    still taking advantage of the benefits they provide.</p>
   
       <p>To isolate the damage a wayward SSI file can cause, a server
  -    administrator can enable <a href="../docs/suexec.html"
  -    >suexec</a> as described in the <a href="#cgi">CGI in General</a>
  -    section.</p>
  -
  -    <p>
  -    Enabling SSI for files with .html or .htm extensions can be
  -    dangerous.  This is especially true in a shared, or high traffic,
  -    server environment.  SSI-enabled files should have a separate
  -    extension, such as the conventional .shtml.  This helps keep
  -    server load at a minimum and allows for easier management of
  -    risk.</p>
  -
  -
  -    <p>Another solution is to disable the ability to run scripts and
  -    programs from SSI pages. To do this replace <code>Includes</code>
  -    with <code>IncludesNOEXEC</code> in the <a
  -    href="../mod/core.html#options">Options</a> directive.  Note that
  -    users may still use &lt;--#include virtual="..." --&gt; to execute
  -    CGI scripts if these scripts are in directories desginated by a <a
  +    administrator can enable <a
  +    href="../docs/suexec.html">suexec</a> as described in the <a
  +    href="#cgi">CGI in General</a> section.</p>
  +
  +    <p>Enabling SSI for files with .html or .htm extensions can be
  +    dangerous. This is especially true in a shared, or high
  +    traffic, server environment. SSI-enabled files should have a
  +    separate extension, such as the conventional .shtml. This helps
  +    keep server load at a minimum and allows for easier management
  +    of risk.</p>
  +
  +    <p>Another solution is to disable the ability to run scripts
  +    and programs from SSI pages. To do this replace
  +    <code>Includes</code> with <code>IncludesNOEXEC</code> in the
  +    <a href="../mod/core.html#options">Options</a> directive. Note
  +    that users may still use &lt;--#include virtual="..." --&gt; to
  +    execute CGI scripts if these scripts are in directories
  +    desginated by a <a
       href="../mod/mod_alias.html#ScriptAlias">ScriptAlias</a>
       directive.</p>
  -
       <hr />
   
       <h2><a id="nsaliasedcgi" name="nsaliasedcgi">Non Script Aliased
  @@ -172,8 +170,6 @@
   
       <p>Most sites choose this option over the non script aliased
       CGI approach.</p>
  -
  -    <p></p>
       <hr />
   
       <h2><a id="cgi" name="cgi">CGI in General</a></h2>
  @@ -191,8 +187,6 @@
       as of 1.2 and is called from special hooks in the Apache server
       code. Another popular way of doing this is with <a
       href="http://wwwcgi.umr.edu/~cgiwrap/">CGIWrap</a>.</p>
  -
  -    <p></p>
       <hr />
   
       <h2><a id="systemsettings" name="systemsettings">Protecting
  @@ -213,14 +207,15 @@
          &lt;/Directory&gt;<br />
         </code>
       </blockquote>
  -    Then setup for specific directories
  +    Then setup for specific directories 
   
       <p>This stops all overrides, Includes and accesses in all
       directories apart from those named.</p>
       <hr />
   
  -    <h2><a id="protectserverfiles" name="protectserverfiles">
  -    Protect Server Files by Default</a></h2>
  +    <h2><a id="protectserverfiles"
  +    name="protectserverfiles">Protect Server Files by
  +    Default</a></h2>
   
       <p>One aspect of Apache which is occasionally misunderstood is
       the feature of default access. That is, unless you take steps
  @@ -246,9 +241,10 @@
   </pre>
   
       <p>This will forbid default access to filesystem locations. Add
  -    appropriate <a href="../mod/core.html#directory"><samp>
  -    &lt;Directory&gt;</samp></a> blocks to allow access only in
  -    those areas you wish. For example,</p>
  +    appropriate <a
  +    href="../mod/core.html#directory"><samp>&lt;Directory&gt;</samp></a>
  +    blocks to allow access only in those areas you wish. For
  +    example,</p>
   <pre>
    &lt;Directory /usr/users/*/public_html&gt;
        Order Deny,Allow
  @@ -261,12 +257,12 @@
   </pre>
   
       <p>Pay particular attention to the interactions of <a
  -    href="../mod/core.html#location"><samp>
  -    &lt;Location&gt;</samp></a> and <a
  -    href="../mod/core.html#directory"><samp>
  -    &lt;Directory&gt;</samp></a> directives; for instance, even if
  -    <samp>&lt;Directory /&gt;</samp> denies access, a <samp>
  -    &lt;Location /&gt;</samp> directive might overturn it.</p>
  +    href="../mod/core.html#location"><samp>&lt;Location&gt;</samp></a>
  +    and <a
  +    href="../mod/core.html#directory"><samp>&lt;Directory&gt;</samp></a>
  +    directives; for instance, even if <samp>&lt;Directory
  +    /&gt;</samp> denies access, a <samp>&lt;Location /&gt;</samp>
  +    directive might overturn it.</p>
   
       <p>Also be wary of playing games with the <a
       href="../mod/mod_userdir.html#userdir">UserDir</a> directive;
  @@ -282,9 +278,10 @@
       <hr />
   
       <p>Please send any other useful security tips to The Apache
  -    Group by filling out a <a href="http://bugs.apache.org/">
  -    problem report</a>. If you are confident you have found a
  -    security bug in the Apache source code itself, <a
  +    Group by filling out a <a
  +    href="http://bugs.apache.org/">problem report</a>. If you are
  +    confident you have found a security bug in the Apache source
  +    code itself, <a
       href="http://httpd.apache.org/bug_report.html">please let us
       know</a>.</p>
   
  
  
  
  1.9       +204 -198  httpd-docs-1.3/htdocs/manual/misc/tutorials.html
  
  Index: tutorials.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/tutorials.html,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- tutorials.html	2001/05/20 17:21:32	1.8
  +++ tutorials.html	2001/10/08 01:26:54	1.9
  @@ -1,200 +1,206 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>Apache Tutorials</TITLE>
  -</HEAD>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Apache Tutorials</H1>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Apache Tutorials</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Apache Tutorials</h1>
  +
  +    <p>The following documents give you step-by-step instructions
  +    on how to accomplish common tasks with the Apache http server.
  +    Many of these documents are located at external sites and are
  +    not the work of the Apache Software Foundation. Copyright to
  +    documents on external sites is owned by the authors or their
  +    assignees. Please consult the <a href="../">official Apache
  +    Server documentation</a> to verify what you read on external
  +    sites.</p>
  +
  +    <h2>Installation &amp; Getting Started</h2>
  +
  +    <ul>
  +      <li><a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-06-1-001-01-NW-DP-LF">
  +      Getting Started with Apache 1.3</a> (ApacheToday)</li>
  +
  +      <li><a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-07-10-001-01-NW-LF-SW">
  +      Configuring Your Apache Server Installation</a>
  +      (ApacheToday)</li>
  +
  +      <li><a
  +      href="http://www.onlamp.com/pub/a/apache/2000/02/24/installing_apache.html">
  +      Getting, Installing, and Running Apache (on Unix)</a>
  +      (O'Reilly Network Apache DevCenter)</li>
  +
  +      <li><a
  +      href="http://www.builder.com/Servers/Apache/ss01.html">Maximum
  +      Apache: Getting Started</a> (CNET Builder.com)</li>
  +
  +      <li><a
  +      href="http://www.devshed.com/Server_Side/Administration/APACHE/">
  +      How to Build the Apache of Your Dreams</a> (Developer
  +      Shed)</li>
  +    </ul>
  +
  +    <h2>Basic Configuration</h2>
  +
  +    <ul>
  +      <li><a
  +      href="http://www.onlamp.com/pub/a/apache/2000/03/02/configuring_apache.html">
  +      An Amble Through Apache Configuration</a> (O'Reilly Network
  +      Apache DevCenter)</li>
  +
  +      <li><a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-07-19-002-01-NW-LF-SW">
  +      Using .htaccess Files with Apache</a> (ApacheToday)</li>
  +
  +      <li><a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-07-17-001-01-PS">
  +      Setting Up Virtual Hosts</a> (ApacheToday)</li>
  +
  +      <li><a
  +      href="http://www.builder.com/Servers/Apache/ss02.html">Maximum
  +      Apache: Configure Apache</a> (CNET Builder.com)</li>
  +
  +      <li>Getting More Out of Apache <a
  +      href="http://www.devshed.com/Server_Side/Administration/MoreApache/">
  +      Part 1</a> - <a
  +      href="http://www.devshed.com/Server_Side/Administration/MoreApache2/">
  +      Part 2</a> (Developer Shed)</li>
  +    </ul>
  +
  +    <h2>Security</h2>
  +
  +    <ul>
  +      <li><a
  +      href="http://www.linuxplanet.com/linuxplanet/tutorials/1527/1/">
  +      Security and Apache: An Essential Primer</a>
  +      (LinuxPlanet)</li>
  +
  +      <li><a
  +      href="http://www.apacheweek.com/features/userauth">Using User
  +      Authentication</a> (Apacheweek)</li>
  +
  +      <li><a href="http://www.apacheweek.com/features/dbmauth">DBM
  +      User Authentication</a> (Apacheweek)</li>
  +
  +      <li><a
  +      href="http://linux.com/security/newsitem.phtml?sid=12&amp;aid=3549">
  +      An Introduction to Securing Apache</a> (Linux.com)</li>
  +
  +      <li><a
  +      href="http://linux.com/security/newsitem.phtml?sid=12&amp;aid=3667">
  +      Securing Apache - Access Control</a> (Linux.com)</li>
  +
  +      <li>Apache Authentication <a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-07-24-002-01-NW-LF-SW">
  +      Part 1</a> - <a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-07-31-001-01-NW-DP-LF">
  +      Part 2</a> - <a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-08-07-001-01-NW-LF-SW">
  +      Part 3</a> - <a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-08-14-001-01-NW-LF-SW">
  +      Part 4</a> (ApacheToday)</li>
  +
  +      <li><a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-11-13-003-01-SC-LF-SW">
  +      mod_access: Restricting Access by Host</a> (ApacheToday)</li>
  +    </ul>
  +
  +    <h2>Logging</h2>
  +
  +    <ul>
  +      <li><a
  +      href="http://www.onlamp.com/pub/a/apache/2000/03/10/log_rhythms.html">
  +      Log Rhythms</a> (O'Reilly Network Apache DevCenter)</li>
  +
  +      <li><a
  +      href="http://www.apacheweek.com/features/logfiles">Gathering
  +      Visitor Information: Customising Your Logfiles</a>
  +      (Apacheweek)</li>
  +
  +      <li>Apache Guide: Logging <a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-08-21-003-01-NW-LF-SW">
  +      Part 1</a> - <a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-08-28-001-01-NW-LF-SW">
  +      Part 2</a> - <a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-09-05-001-01-NW-LF-SW">
  +      Part 3</a> - <a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-09-18-003-01-NW-LF-SW">
  +      Part 4</a> - <a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-09-25-001-01-NW-LF-SW">
  +      Part 5</a> (ApacheToday)</li>
  +    </ul>
  +
  +    <h2>CGI and SSI</h2>
  +
  +    <ul>
  +      <li><a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-06-05-001-10-NW-LF-SW">
  +      Dynamic Content with CGI</a> (ApacheToday)</li>
  +
  +      <li><a
  +      href="http://www.perl.com/CPAN-local/doc/FAQs/cgi/idiots-guide.html">
  +      The Idiot's Guide to Solving Perl CGI Problems</a>
  +      (CPAN)</li>
  +
  +      <li><a
  +      href="http://www.linuxplanet.com/linuxplanet/tutorials/1445/1/">
  +      Executing CGI Scripts as Other Users</a> (LinuxPlanet)</li>
  +
  +      <li><a href="http://www.htmlhelp.org/faq/cgifaq.html">CGI
  +      Programming FAQ</a> (Web Design Group)</li>
  +
  +      <li>Introduction to Server Side Includes <a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-06-12-001-01-PS">
  +      Part 1</a> - <a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-06-19-002-01-NW-LF-SW">
  +      Part 2</a> (ApacheToday)</li>
  +
  +      <li><a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-06-26-001-01-NW-LF-SW">
  +      Advanced SSI Techniques</a> (ApacheToday)</li>
  +
  +      <li><a
  +      href="http://www.builder.com/Servers/ApacheFiles/082400/">Setting
  +      up CGI and SSI with Apache</a> (CNET Builder.com)</li>
  +    </ul>
  +
  +    <h2>Other Features</h2>
  +
  +    <ul>
  +      <li><a
  +      href="http://www.apacheweek.com/features/negotiation">Content
  +      Negotiation Explained</a> (Apacheweek)</li>
  +
  +      <li><a
  +      href="http://www.apacheweek.com/features/imagemaps">Using
  +      Apache Imagemaps</a> (Apacheweek)</li>
  +
  +      <li><a
  +      href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS">
  +      Keeping Your Images from Adorning Other Sites</a>
  +      (ApacheToday)</li>
  +
  +      <li><a
  +      href="http://ppewww.ph.gla.ac.uk/~flavell/www/lang-neg.html">Language
  +      Negotiation Notes</a> (Alan J. Flavell)</li>
  +    </ul>
  +
  +    <p>If you have a pointer to an accurate and well-written
  +    tutorial not included here, please let us know by submitting it
  +    to the <a href="http://bugs.apache.org/">Apache Bug
  +    Database</a>. <!--#include virtual="footer.html" -->
  +    </p>
  +  </body>
  +</html>
   
  -<P>The following documents give you step-by-step instructions on how
  -to accomplish common tasks with the Apache http server.  Many of these
  -documents are located at external sites and are not the work of the
  -Apache Software Foundation.  Copyright to documents on external sites
  -is owned by the authors or their assignees.  Please consult the <A
  -HREF="../">official Apache Server documentation</A> to verify what you
  -read on external sites.
  -
  -
  -<H2>Installation &amp; Getting Started</H2>
  -
  -<UL>
  -
  -<LI><A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-06-1-001-01-NW-DP-LF"
  ->Getting Started with Apache 1.3</A> (ApacheToday)
  -
  -<LI><A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-07-10-001-01-NW-LF-SW"
  ->Configuring Your Apache Server Installation</A> (ApacheToday)
  -
  -<LI><A
  -HREF="http://www.onlamp.com/pub/a/apache/2000/02/24/installing_apache.html"
  ->Getting, Installing, and Running Apache (on Unix)</A> (O'Reilly
  -Network Apache DevCenter)
  -
  -<LI><A HREF="http://www.builder.com/Servers/Apache/ss01.html">Maximum
  -Apache: Getting Started</A> (CNET Builder.com)
  -
  -<LI><A HREF="http://www.devshed.com/Server_Side/Administration/APACHE/"
  ->How to Build the Apache of Your Dreams</A> (Developer Shed)
  -
  -</UL>
  -
  -
  -<H2>Basic Configuration</H2>
  -
  -<UL>
  -
  -<LI><A
  -HREF="http://www.onlamp.com/pub/a/apache/2000/03/02/configuring_apache.html"
  ->An Amble Through Apache Configuration</A> (O'Reilly Network Apache
  -DevCenter)
  -
  -<LI><A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-07-19-002-01-NW-LF-SW"
  ->Using .htaccess Files with Apache</A> (ApacheToday)
  -
  -<LI><A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-07-17-001-01-PS"
  ->Setting Up Virtual Hosts</A> (ApacheToday)
  -
  -<LI><A HREF="http://www.builder.com/Servers/Apache/ss02.html">Maximum
  -Apache: Configure Apache</A> (CNET Builder.com)
  -
  -<LI>Getting More Out of Apache <A HREF="http://www.devshed.com/Server_Side/Administration/MoreApache/">Part 1</A> - <A HREF="http://www.devshed.com/Server_Side/Administration/MoreApache2/">Part 2</A> (Developer Shed)
  -
  -</UL>
  -
  -<H2>Security</H2>
  -
  -<UL>
  -
  -<LI><A
  -HREF="http://www.linuxplanet.com/linuxplanet/tutorials/1527/1/">Security
  -and Apache: An Essential Primer</A> (LinuxPlanet)
  -
  -<LI><A HREF="http://www.apacheweek.com/features/userauth">Using User
  -Authentication</A> (Apacheweek)
  -
  -<LI><A HREF="http://www.apacheweek.com/features/dbmauth">DBM User
  -Authentication</A> (Apacheweek)
  -
  -<LI><A
  -HREF="http://linux.com/security/newsitem.phtml?sid=12&aid=3549">An
  -Introduction to Securing Apache</A> (Linux.com)
  -
  -<LI><A
  -HREF="http://linux.com/security/newsitem.phtml?sid=12&aid=3667">Securing
  -Apache - Access Control</A> (Linux.com)
  -
  -<LI>Apache Authentication <A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-07-24-002-01-NW-LF-SW"
  ->Part 1</A> - <A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-07-31-001-01-NW-DP-LF"
  ->Part 2</A> - <A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-08-07-001-01-NW-LF-SW"
  ->Part 3</A> - <A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-08-14-001-01-NW-LF-SW"
  ->Part 4</A> (ApacheToday)
  -
  -<LI><a href="http://apachetoday.com/news_story.php3?ltsn=2000-11-13-003-01-SC-LF-SW"
  ->mod_access: Restricting Access by Host</a> (ApacheToday)
  -
  -</UL>
  -
  -<H2>Logging</H2>
  -
  -<UL>
  -
  -<LI><A
  -HREF="http://www.onlamp.com/pub/a/apache/2000/03/10/log_rhythms.html"
  ->Log Rhythms</A> (O'Reilly Network Apache DevCenter)
  -
  -<LI><A HREF="http://www.apacheweek.com/features/logfiles">Gathering
  -Visitor Information: Customising Your Logfiles</A> (Apacheweek)
  -
  -<LI>Apache Guide: Logging
  -<A HREF="http://apachetoday.com/news_story.php3?ltsn=2000-08-21-003-01-NW-LF-SW"
  ->Part 1</A> -
  -<A HREF="http://apachetoday.com/news_story.php3?ltsn=2000-08-28-001-01-NW-LF-SW"
  ->Part 2</A> - 
  -<A HREF="http://apachetoday.com/news_story.php3?ltsn=2000-09-05-001-01-NW-LF-SW"
  ->Part 3</A> -
  -<A HREF="http://apachetoday.com/news_story.php3?ltsn=2000-09-18-003-01-NW-LF-SW"
  ->Part 4</A> -
  -<A HREF="http://apachetoday.com/news_story.php3?ltsn=2000-09-25-001-01-NW-LF-SW"
  ->Part 5</A> (ApacheToday)
  -
  -</UL>
  -
  -<H2>CGI and SSI</H2>
  -
  -<UL>
  -
  -<LI><A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-06-05-001-10-NW-LF-SW"
  ->Dynamic Content with CGI</A> (ApacheToday)
  -
  -<LI><A
  -HREF="http://www.perl.com/CPAN-local/doc/FAQs/cgi/idiots-guide.html">The
  -Idiot's Guide to Solving Perl CGI Problems</A> (CPAN)
  -
  -<LI><A
  -HREF="http://www.linuxplanet.com/linuxplanet/tutorials/1445/1/">Executing
  -CGI Scripts as Other Users</A> (LinuxPlanet)
  -
  -<LI><A HREF="http://www.htmlhelp.org/faq/cgifaq.html">CGI Programming
  -FAQ</A> (Web Design Group)
  -
  -<LI>Introduction to Server Side Includes <A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-06-12-001-01-PS">Part
  -1</A> - <A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-06-19-002-01-NW-LF-SW"
  ->Part 2</A> (ApacheToday)
  -
  -<LI><A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-06-26-001-01-NW-LF-SW"
  ->Advanced SSI Techniques</A> (ApacheToday)
  -
  -<LI><A
  -HREF="http://www.builder.com/Servers/ApacheFiles/082400/">Setting up
  -CGI and SSI with Apache</A> (CNET Builder.com)
  -
  -</UL>
  -
  -<H2>Other Features</H2>
  -
  -<UL>
  -
  -<LI><A HREF="http://www.apacheweek.com/features/negotiation">Content
  -Negotiation Explained</A> (Apacheweek)
  -
  -<LI><A HREF="http://www.apacheweek.com/features/imagemaps">Using
  -Apache Imagemaps</A> (Apacheweek)
  -
  -<LI><A
  -HREF="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS"
  ->Keeping Your Images from Adorning Other Sites</A> (ApacheToday)
  -
  -<LI><A HREF="http://ppewww.ph.gla.ac.uk/~flavell/www/lang-neg.html"
  ->Language Negotiation Notes</A> (Alan J. Flavell)
  -
  -</UL>
  -
  -
  -<P>If you have a pointer to an accurate and well-written tutorial
  -not included here, please let us know by submitting it to the
  -<A HREF="http://bugs.apache.org/">Apache Bug Database</A>.
  -
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  
  
  
  1.12      +28 -29    httpd-docs-1.3/htdocs/manual/misc/vif-info.html
  
  Index: vif-info.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/vif-info.html,v
  retrieving revision 1.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- vif-info.html	2000/12/03 03:28:38	1.11
  +++ vif-info.html	2001/10/08 01:26:54	1.12
  @@ -1,19 +1,20 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML><HEAD>
  -<TITLE>Configuring Multiple IP Addresses</TITLE>
  -</HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Configuring Multiple IP Addresses</H1>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -<PRE>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>Configuring Multiple IP Addresses</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">Configuring Multiple IP Addresses</h1>
  +<pre>
   This material is originally from John Ioannidis (ji@polaris.ctr.columbia.edu)
   I have condensed it some and applied some corrections for SunOS 4.1.x
   courtesy of Chuck Smoko (csmoko@relay.nswc.navy.mil).
  @@ -295,7 +296,7 @@
                   *(mtod(m0, struct ifnet **)) = ifp;
                   s = splimp();
                   ifp-&gt;if_opackets++;
  -                ifq = &ipintrq;
  +                ifq = &amp;ipintrq;
                   if (IF_QFULL(ifq)) {
                           IF_DROP(ifq);
                           m_freem(m0);
  @@ -369,7 +370,7 @@
   kmem_alloc() the vif_softc structure at open time, and use the minor
   number of the device to tell it how many interfaces to create.
   
  -Now you can go ahead and ifconfig <EM>etc.</EM>
  +Now you can go ahead and ifconfig <em>etc.</em>
   
   I'll be happy to answer minor questions, and hear about success and
   failure stories, but I cannot help you if you don't already know how
  @@ -383,17 +384,15 @@
   E-Mail-To: ji@cs.columbia.edu
   V-Mail-To: +1 212 854 8120
   P-Mail-To: 450 Computer Science \n Columbia University \n New York, NY 10027
  -</PRE>
  -
  -<P>
  -
  -Note: there is also a <A
  -HREF="http://www.multihost.com/">commercial-product-turned-freeware
  -called "Col. Patch"</A> which does this as a loadable kernel module
  -for SunOS 4.1.3_U1.
  +</pre>
   
  -<P>
  +    <p>Note: there is also a <a
  +    href="http://www.multihost.com/">commercial-product-turned-freeware
  +    called "Col. Patch"</a> which does this as a loadable kernel
  +    module for SunOS 4.1.3_U1.</p>
  +
  +    <p><!--#include virtual="footer.html" -->
  +    </p>
  +  </body>
  +</html>
   
  -<!--#include virtual="footer.html" -->
  -</BODY>
  -</HTML>
  
  
  
  1.5       +23 -19    httpd-docs-1.3/htdocs/manual/misc/windoz_keepalive.html
  
  Index: windoz_keepalive.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/misc/windoz_keepalive.html,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- windoz_keepalive.html	1997/12/29 20:41:50	1.4
  +++ windoz_keepalive.html	2001/10/08 01:26:54	1.5
  @@ -1,20 +1,22 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>MS Windows Netscape 3.0b4 KeepAlive problem solved</TITLE>
  -</HEAD>
  -<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  -<!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">HTTP/1.1 KeepAlive problems with Netscape 3.0</H1>
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
  -<PRE>
  +<html xmlns="http://www.w3.org/1999/xhtml">
  +  <head>
  +    <meta name="generator" content="HTML Tidy, see www.w3.org" />
  +
  +    <title>MS Windows Netscape 3.0b4 KeepAlive problem
  +    solved</title>
  +  </head>
  +  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  +
  +  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  +  vlink="#000080" alink="#FF0000">
  +    <!--#include virtual="header.html" -->
  +
  +    <h1 align="CENTER">HTTP/1.1 KeepAlive problems with Netscape
  +    3.0</h1>
  +<pre>
   Date: Mon, 1 Jul 1996 16:03:06 -0700 (PDT)
   From: Alexei Kosut &lt;akosut@organic.com&gt;
   To: Apache Group
  @@ -45,6 +47,8 @@
   
   -- Alexei Kosut &lt;akosut@organic.com&gt;            The Apache HTTP Server
      http://www.nueva.pvt.k12.ca.us/~akosut/      http://www.apache.org/
  -</PRE>
  -<!--#include virtual="footer.html" -->
  -</BODY></HTML>
  +</pre>
  +    <!--#include virtual="footer.html" -->
  +  </body>
  +</html>
  +
  
  
  

Mime
View raw message