You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by rb...@apache.org on 2001/10/08 03:26:56 UTC
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
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 -> 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 -> 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->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><Directory></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><Directory></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->finfo.st_mode == 0) return NOT_FOUND;
if ((errstatus = ap_set_content_length (r, r->finfo.st_size))
- || (errstatus = ap_set_last_modified (r, r->finfo.st_mtime)))
+ || (errstatus = ap_set_last_modified (r, r->finfo.st_mtime)))
return errstatus;
f = fopen (r->filename, "r");
@@ -455,119 +510,125 @@
ap_pfclose (r->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->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->prev</CODE> and <CODE>r->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->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->prev</code> and <code>r->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->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->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->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->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->pool
- </LI>
- </UL>
- </DD>
- <DT>r->pool
- </DT>
- <DD>
- <UL>
- <LI>for the main request this is a subpool of connection->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->pool; <EM>i.e.</EM>,
- r->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->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->user to a value from r->pool -- in this case
-connection exists
-for the lifetime of ptrans, which is longer than r->pool (especially if
-r->pool is a subrequest!). So the correct thing to do is to allocate
-from connection->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->pool
-or r->main->pool. In this case the resource that they are registering
-for cleanup is a child process. If it were registered in r->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->main->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->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->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->pool</li>
+ </ul>
+ </dd>
+
+ <dt>r->pool</dt>
+
+ <dd>
+ <ul>
+ <li>for the main request this is a subpool of
+ connection->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->pool;
+ <em>i.e.</em>, r->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->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->user to a value from r->pool
+ -- in this case connection exists for the lifetime of ptrans,
+ which is longer than r->pool (especially if r->pool is a
+ subrequest!). So the correct thing to do is to allocate from
+ connection->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->pool or r->main->pool.
+ In this case the resource that they are registering for cleanup
+ is a child process. If it were registered in r->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->main->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->pool, r->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 -> 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><Directory></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><Directory /></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 -> 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><Directory></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><Directory /></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><Directory></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><Directory></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->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->server;
@@ -1148,6 +1231,8 @@
new->fake = f; new->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
- <<A
- HREF="http://httpd.apache.org/docs/misc/FAQ.html"
- REL="Help"
- ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>>.
- </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>
+<!--#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 "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 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 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 <<a
+ href="http://httpd.apache.org/docs/misc/FAQ.html"
+ rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>>.</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
- <<A
- HREF="http://httpd.apache.org/docs/misc/FAQ.html"
- REL="Help"
- ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>>.
- </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>
+<!--#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>"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
- & 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&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><<a href="http://www.apache.org/info/support.cgi"
- >http://www.apache.org/info/support.cgi</a>></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 <<a
+ href="http://httpd.apache.org/docs/misc/FAQ.html"
+ rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>>.</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 & 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&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><<a
+ href="http://www.apache.org/info/support.cgi">http://www.apache.org/info/support.cgi</a>></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 -c</CODE>' or '<CODE>diff -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><<A HREF="http://www.apache.org/LICENSE.txt"
- >http://www.apache.org/LICENSE.txt</A>></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
- (<URL:<a href="http://httpd.apache.org/dist/httpd/binaries/"
- >http://httpd.apache.org/dist/httpd/binaries/</a>>),
- 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 -c</code>' or
+ '<code>diff -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><<a
+ href="http://www.apache.org/LICENSE.txt">http://www.apache.org/LICENSE.txt</a>></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 (<URL:<a
+ href="http://httpd.apache.org/dist/httpd/binaries/">http://httpd.apache.org/dist/httpd/binaries/</a>>),
+ 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
- <<A
- HREF="http://httpd.apache.org/docs/misc/FAQ.html"
- REL="Help"
- ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>>.
- </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>
+<!--#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 <<a
+ href="http://httpd.apache.org/docs/misc/FAQ.html"
+ rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>>.</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 & 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
- "<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>
- <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
- & OS versions and exact error messages.
- </P>
- <HR>
- </LI>
-
- <LI><A 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>
- <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
- <<A
- HREF="http://httpd.apache.org/docs/misc/FAQ.html"
- REL="Help"
- ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>>.
- </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 </Directory>
- but saw </Directory></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>
+<!--#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 "<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 #-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 "<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 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 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 "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 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 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 "<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 NAME="aixccbug"><STRONG>Why am I getting "<SAMP>Expected
- </Directory> but saw </Directory></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 "<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>
+<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 <<a
+ href="http://httpd.apache.org/docs/misc/FAQ.html"
+ rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>>.</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
+ </Directory> but saw </Directory></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 #-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 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 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 </Directory> but saw
+ </Directory></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
- <<A
- HREF="http://httpd.apache.org/docs/misc/FAQ.html"
- REL="Help"
- ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>>.
- </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 <<EM>n</EM>>
- 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>, <SAMP>http://foo.domain.com/~user/</SAMP>) but
- not when I omit it
- (<EM>e.g.</EM>, <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><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>
- </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 <<a
+ href="http://httpd.apache.org/docs/misc/FAQ.html"
+ rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>>.</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
+ <<em>n</em>> 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>, <samp>http://foo.domain.com/~user/</samp>)
+ but not when I omit it
+ (<em>e.g.</em>, <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 <<em>n</em>> 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 <<em>n</em>> 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 logs/access_log "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{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>, <samp>http://foo.domain.com/~user/</samp>)
+ but not when I omit it
+ (<em>e.g.</em>, <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><VirtualHost></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><VirtualHost></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><VirtualHost></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><Files ~></code>. If you find it,
+ that's your problem -- that particular <Files>
+ container is malformed. Delete it or replace it with
+ <code><Files ~ "^\.ht"></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 <<EM>n</EM>>
- 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 <<EM>n</EM>> 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 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 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 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 "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>
- <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 logs/access_log "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{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 NAME="set-servername">
- <STRONG>Why does accessing directories only work when I include
- the trailing "/"
- (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user/</SAMP>)
- but not when I omit it
- (<EM>e.g.</EM>, <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 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 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><VirtualHost></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><VirtualHost></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><VirtualHost></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 "<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>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
- "<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><Files ~></code>. If you find it,
- that's your problem -- that particular <Files> container
- is malformed. Delete it or replace it with
- <code><Files ~ "^\.ht"></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
- <<A
- HREF="http://httpd.apache.org/docs/misc/FAQ.html"
- REL="Help"
- ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>>.
- </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>
+<!--#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 <<a
+ href="http://httpd.apache.org/docs/misc/FAQ.html"
+ rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>>.</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 />
+ local ($oldbar) = $|;<br />
+ $cfh = select (STDOUT);<br />
+ $| = 1;<br />
+ #<br />
+ # print your HTTP headers here<br />
+ #<br />
+ $| = $oldbar;<br />
+ 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 < <a
+ href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"><samp>
+ http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</samp></a>>.
+ 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 <<a
+ href="http://web.golux.com/coar/cgi/"><samp>http://web.golux.com/coar/cgi/</samp></a>>.</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><Directory
+ /home/*/public_html/cgi-bin><br />
+ Options ExecCGI<br />
+ SetHandler cgi-script<br />
+ </Directory></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
- "<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>
- <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 "<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></P>
- <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>
- <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
- "<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>
- <P>
- <DL>
- <DD><CODE>{<BR>
- local ($oldbar) = $|;<BR>
- $cfh = select (STDOUT);<BR>
- $| = 1;<BR>
- #<BR>
- # print your HTTP headers here<BR>
- #<BR>
- $| = $oldbar;<BR>
- 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 "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 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 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 "CGI specification"?</STRONG>
- </A>
- <P>
- The Common Gateway Interface (CGI) specification can be found at
- the original NCSA site
- <<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">
- <SAMP>http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</SAMP></A>>.
- 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
- <<A HREF="http://web.golux.com/coar/cgi/"
- ><SAMP>http://web.golux.com/coar/cgi/</SAMP></A>>.
- </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 "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:
- <P>
- <DL>
- <DD><CODE>AddHandler server-parsed .shtml</CODE>
- </DD>
- </DL>
- <P></P>
- <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 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 "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 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><Directory /home/*/public_html/cgi-bin><BR>
- Options ExecCGI<BR>
- SetHandler cgi-script<BR>
- </Directory></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
- <<A
- HREF="http://httpd.apache.org/docs/misc/FAQ.html"
- REL="Help"
- ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>>.
- </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>
+<!--#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 "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 /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 "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 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 <<a
+ href="http://httpd.apache.org/docs/misc/FAQ.html"
+ rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>>.</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 /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
- <<A
- HREF="http://httpd.apache.org/docs/misc/FAQ.html"
- REL="Help"
- ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>>.
- </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>
+<!--#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 <<a
+ href="http://httpd.apache.org/docs/misc/FAQ.html"
+ rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>>.</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 <<a
+ href="http://www.heise.de/ix/artikel/9612149/">http://www.heise.de/ix/artikel/9612149/</a>>,
+ the English (translated) version can be found at <<a
+ href="http://www.heise.de/ix/artikel/E/9612149/">http://www.heise.de/ix/artikel/E/9612149/</a>>.</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 "iX Multiuser Multitasking Magazin" issue #12/96. The
- german (original) version
- can be read online at
- <<A HREF="http://www.heise.de/ix/artikel/9612149/"
- >http://www.heise.de/ix/artikel/9612149/</A>>,
- the English (translated) version can be found at
- <<A HREF="http://www.heise.de/ix/artikel/E/9612149/"
- >http://www.heise.de/ix/artikel/E/9612149/</A>>.
- </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 "<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 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 "RewriteEngine on" 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
- <<A
- HREF="http://httpd.apache.org/docs/misc/FAQ.html"
- REL="Help"
- ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>>.
- </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>
+<!--#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 <<a
+ href="http://httpd.apache.org/docs/misc/FAQ.html"
+ rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>>.</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, <URL:<a
+ href="http://jakarta.apache.org">http://jakarta.apache.org/</a>>.</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 "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 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 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 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, <URL:<a href="http://jakarta.apache.org"
- >http://jakarta.apache.org/</a>>.
- </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
- <<A
- HREF="http://httpd.apache.org/docs/misc/FAQ.html"
- REL="Help"
- ><SAMP>http://httpd.apache.org/docs/misc/FAQ.html</SAMP></A>>.
- </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>
+<!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 <<a
+ href="http://httpd.apache.org/docs/misc/FAQ.html"
+ rel="Help"><samp>http://httpd.apache.org/docs/misc/FAQ.html</samp></a>>.</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><Limit></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 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 <Limit>.
-
-<P>
-<LI>Apache's <CODE><VirtualHost></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
-<Files> 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><Limit></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 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
+ <Limit>.</li>
+
+ <li>Apache's <code><VirtualHost></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 <Files> 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"><Directory></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 <Directory> and </Directory> 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"><Directory></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 <Directory> and </Directory>
+ directives -but not the contained directives- must be
+ omitted.)</small>
+<pre>
LanguagePriority en fr de
Alias /errordocs /usr/local/apache/errordocs
<Directory /usr/local/apache/errordocs>
@@ -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><!--#include virtual="head" --></CODE>
-and <CODE><!--#include virtual="foot" --></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>
-<!--#set var="title" value="<EM>error description title</EM>" -->
+</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><!--#include virtual="head" --></code>
+ and <code><!--#include virtual="foot" --></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>
+<!--#set var="title" value="<em>error description title</em>" -->
<!--#include virtual="head" -->
- <EM>explanatory error text</EM>
+ <em>explanatory error text</em>
<!--#include virtual="foot" -->
-</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>
<!--#if expr="$REDIRECT_ERROR_NOTES = ''" -->
<p>
The server encountered an unexpected condition
@@ -321,16 +367,18 @@
<!--#else -->
<!--#echo var="REDIRECT_ERROR_NOTES" -->
<!--#endif -->
-</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>
<!--#set var="title" value="Bad Request"
--><!--#include virtual="head" --><P>
Your browser sent a request that this server could not understand:
@@ -351,18 +399,21 @@
<!--#endif -->
</P>
<!--#include virtual="foot" -->
-</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>
<!--#if expr="$SERVER_NAME = /.*\.mycompany\.com/"
--><!--#set var="IMG_CorpLogo"
value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif"
@@ -394,10 +445,11 @@
</H1>
<HR><!-- ======================================================== -->
<DIV>
-</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>
</DIV>
<HR>
<DIV ALIGN="right"><SMALL><SUP>Local Server time:
@@ -419,15 +471,13 @@
</ADDRESS>
</UL></BODY>
</HTML>
-</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 <= soft limit <= hard limit <= 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"
- >"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>
+<!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 "<MAJOR>.<MINOR>" 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 "<MAJOR>.<MINOR>" 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 <agifford@InfoWest.COM>"
-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 <agifford@InfoWest.COM>" 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 <chuck@telebase.com>
-
-<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 <chuck@telebase.com></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" <mi@ALDAN.ziplink.net> 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
-"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>
-
-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>
-
-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>
-
-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 "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>
+</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" <mi@ALDAN.ziplink.net> 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 <mogul@pa.dec.com><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 <mogul@pa.dec.com><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 <4oirch$bc8@usenet.pa.dec.com>
Subject Re: Web Site Performance
References 1
@@ -63,10 +65,10 @@
>runing DEC UNIX 3.2C, which run DEC's seal firewall and behind
>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 <4onmmd$mmd@usenet.pa.dec.com>
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"> </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"> </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 <<a href="mailto:raj@cup.hp.com">raj@cup.hp.com</a>>
+From: Rick Jones <<a
+href="mailto:raj@cup.hp.com">raj@cup.hp.com</a>>
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 <BINARY>."
+ 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 <BINARY>." 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><Location /server-status></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><Location /server-status></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
<Files ~ "\.(html|cgi)$">
HostnameLookups on
</Files>
-</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
<Directory />
Options SymLinksIfOwnerMatch
</Directory>
-</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
<Directory />
Options FollowSymLinks
@@ -153,438 +181,485 @@
<Directory /www/htdocs>
Options -FollowSymLinks +SymLinksIfOwnerMatch
</Directory>
-</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
<Directory />
AllowOverride all
</Directory>
-</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 (&accept_fds);
- for (i = first_socket; i <= last_socket; ++i) {
- FD_SET (i, &accept_fds);
- }
- rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
- if (rc < 1) continue;
- new_connection = -1;
- for (i = first_socket; i <= last_socket; ++i) {
- if (FD_ISSET (i, &accept_fds)) {
- new_connection = accept (i, NULL, NULL);
- if (new_connection != -1) break;
- }
- }
- if (new_connection != -1) break;
- }
- process the new_connection;
+ FD_ZERO (&accept_fds);
+ for (i = first_socket; i <= last_socket; ++i) {
+ FD_SET (i, &accept_fds);
+ }
+ rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
+ if (rc < 1) continue;
+ new_connection = -1;
+ for (i = first_socket; i <= last_socket; ++i) {
+ if (FD_ISSET (i, &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 (&accept_fds);
- for (i = first_socket; i <= last_socket; ++i) {
- FD_SET (i, &accept_fds);
- }
- rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
- if (rc < 1) continue;
- new_connection = -1;
- for (i = first_socket; i <= last_socket; ++i) {
- if (FD_ISSET (i, &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 (&accept_fds);
+ for (i = first_socket; i <= last_socket; ++i) {
+ FD_SET (i, &accept_fds);
+ }
+ rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
+ if (rc < 1) continue;
+ new_connection = -1;
+ for (i = first_socket; i <= last_socket; ++i) {
+ if (FD_ISSET (i, &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)) <= 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)) <= 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>
<Directory />
AllowOverride none
Options FollowSymLinks
</Directory>
-</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,
-<http://www.sun.com/sun-on-net/performance.html></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
- (à 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,
+ <http://www.sun.com/sun-on-net/performance.html></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 (à
+ 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 (à 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 à 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 (à 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 à 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 <rse@apache.org><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 <rse@apache.org><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 "</html>\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 <STRING,
->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 <STRING, >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} >0700
RewriteCond %{TIME_HOUR}%{TIME_MIN} <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 >1024 --> Host www2.quux-corp.dom Port <STRONG>80</STRONG>
-<STRONG>DENY</STRONG> Host * Port * --> 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 >1024 --> Host www2.quux-corp.dom Port <strong>80</strong>
+<strong>DENY</strong> Host * Port * --> 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><VirtualHost></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><VirtualHost></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 >= 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 >= 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 <= 1.3b6:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>For Apache <= 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>
<VirtualHost *:8008>
...
RewriteEngine On
@@ -1815,84 +2245,110 @@
RewriteRule ^proxy: - [F]
...
</VirtualHost>
-</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 <--#include virtual="..." --> 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 <--#include virtual="..." --> 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 @@
</Directory><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>
- <Directory></samp></a> blocks to allow access only in
- those areas you wish. For example,</p>
+ appropriate <a
+ href="../mod/core.html#directory"><samp><Directory></samp></a>
+ blocks to allow access only in those areas you wish. For
+ example,</p>
<pre>
<Directory /usr/users/*/public_html>
Order Deny,Allow
@@ -261,12 +257,12 @@
</pre>
<p>Pay particular attention to the interactions of <a
- href="../mod/core.html#location"><samp>
- <Location></samp></a> and <a
- href="../mod/core.html#directory"><samp>
- <Directory></samp></a> directives; for instance, even if
- <samp><Directory /></samp> denies access, a <samp>
- <Location /></samp> directive might overturn it.</p>
+ href="../mod/core.html#location"><samp><Location></samp></a>
+ and <a
+ href="../mod/core.html#directory"><samp><Directory></samp></a>
+ directives; for instance, even if <samp><Directory
+ /></samp> denies access, a <samp><Location /></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 & 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&aid=3549">
+ An Introduction to Securing Apache</a> (Linux.com)</li>
+
+ <li><a
+ href="http://linux.com/security/newsitem.phtml?sid=12&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 & 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->if_opackets++;
- ifq = &ipintrq;
+ ifq = &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 <akosut@organic.com>
To: Apache Group
@@ -45,6 +47,8 @@
-- Alexei Kosut <akosut@organic.com> 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>
+