This commit was manufactured by cvs2svn to create tag 'APACHE_1_2_1'.
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/tags/1.2.1@78528 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/docs/docroot/apache_pb.gif b/docs/docroot/apache_pb.gif
deleted file mode 100644
index 3a1c139..0000000
--- a/docs/docroot/apache_pb.gif
+++ /dev/null
Binary files differ
diff --git a/docs/manual/bind.html.en b/docs/manual/bind.html.en
deleted file mode 100644
index 9253168..0000000
--- a/docs/manual/bind.html.en
+++ /dev/null
@@ -1,109 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html><head>
-<title>Setting which addresses and ports Apache uses</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">Setting which addresses and ports Apache uses</h1>
-
-<hr>
-
-When Apache starts, it connects to some port and address on the
-local machine and waits for incoming requests. By default, it
-listens to all addresses on the machine, and to the port
-as specified by the <tt>Port</tt> directive in the server configuration.
-However, it can be told to listen to more the one port, or to listen
-to only selected addresses, or a combination. This is often combined
-with the Virtual Host feature which determines how Apache
-responds to different IP addresses, hostnames and ports.<p>
-
-There are two directives used to restrict or specify which addresses
-and ports Apache listens to.
-
-<ul>
-<li><a href="#bindaddress">BindAddress</a> is used to restrict the server to listening to
- a single address, and can be used to permit multiple Apache servers
- on the same machine listening to different IP addresses.
-<li><a href="#listen">Listen</a> can be used to make a single Apache server listen
- to more than one address and/or port.
-</ul>
-
-<h3><a name="bindaddress">BindAddress</a></h3>
-<strong>Syntax:</strong> BindAddress <em>[ * | IP-address | hostname ]</em><br>
-<strong>Default:</strong> <code>BindAddress *</code><br>
-<strong>Context:</strong> server config<br>
-<strong>Status:</strong> Core<p>
-
-Makes the server listen to just the specified address. If the argument
-is *, the server listens to all addresses. The port listened to
-is set with the <tt>Port</tt> directive. Only one BindAddress
-should be used.
-
-<h3><a name="listen">Listen</a></h3>
-<strong>Syntax:</strong> Listen <em>[ port | IP-address:port ]</em><br>
-<strong>Default:</strong> <code>none</code><br>
-<strong>Context:</strong> server config<br>
-<strong>Status:</strong> Core<p>
-
-<tt>Listen</tt> can be used instead of <tt>BindAddress</tt> and
-<tt>Port</tt>. It tells the server to accept incoming requests on the
-specified port or address-and-port combination. If the first format is
-used, with a port number only, the server listens to the given port on
-all interfaces, instead of the port given by the <tt>Port</tt>
-directive. If an IP address is given as well as a port, the server
-will listen on the given port and interface. <p> Multiple Listen
-directives may be used to specify a number of addresses and ports to
-listen to. The server will respond to requests from any of the listed
-addresses and ports.<p>
-
-For example, to make the server accept connections on both port
-80 and port 8000, use:
-<pre>
- Listen 80
- Listen 8000
-</pre>
-
-To make the server accept connections on two specified
-interfaces and port numbers, use
-<pre>
- Listen 192.170.2.1:80
- Listen 192.170.2.5:8000
-</pre>
-
-<h2>How this works with Virtual Hosts</h2>
-
-BindAddress and Listen do not implement Virtual Hosts. They tell the
-main server what addresses and ports to listen to. If no
-<VirtualHost> directives are used, the server will behave the
-same for all accepted requests. However, <VirtualHost> can be
-used to specify a different behavior for one or more of the addresses
-and ports. To implement a VirtualHost, the server must first be told
-to listen to the address and port to be used. Then a
-<VirtualHost> section should be created for a specified address
-and port to set the behavior of this virtual host. Note that if the
-<VirtualHost> is set for an address and port that the server is
-not listening to, it cannot be accessed.
-
-<h2>See also</h2>
-
-See also the documentation on
-<a href="virtual-host.html">Virtual Hosts</a>,
-<a href="host.html">Non-IP virtual hosts</a>,
-<a href="mod/core.html#bindaddress">BindAddress directive</a>,
-<a href="mod/core.html#port">Port directive</a>,
-<a href="dns-caveats.html">DNS Issues</a>
-and
-<a href="mod/core.html#virtualhost"><VirtualHost> section</a>.
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
-
diff --git a/docs/manual/cgi_path.html.en b/docs/manual/cgi_path.html.en
deleted file mode 100644
index 8ac3bc0..0000000
--- a/docs/manual/cgi_path.html.en
+++ /dev/null
@@ -1,93 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html><head>
-<title>PATH_INFO Changes in the CGI Environment</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">PATH_INFO Changes in the CGI Environment</h1>
-
-<hr>
-
-<h2><a name="over">Overview</a></h2>
-
-<p>As implemented in Apache 1.1.1 and earlier versions, the method
-Apache used to create PATH_INFO in the CGI environment was
-counterintuitive, and could result in crashes in certain cases. In
-Apache 1.2 and beyond, this behavior has changed. Although this
-results in some compatibility problems with certain legacy CGI
-applications, the Apache 1.2 behavior is still compatible with the
-CGI/1.1 specification, and CGI scripts can be easily modified (<a
-href="#compat">see below</a>).
-
-<h2><a name="prob">The Problem</a></h2>
-
-<p>Apache 1.1.1 and earlier implemented the PATH_INFO and SCRIPT_NAME
-environment variables by looking at the filename, not the URL. While
-this resulted in the correct values in many cases, when the filesystem
-path was overloaded to contain path information, it could result in
-errant behavior. For example, if the following appeared in a config
-file:
-<pre>
- Alias /cgi-ralph /usr/local/httpd/cgi-bin/user.cgi/ralph
-</pre>
-<p>In this case, <code>user.cgi</code> is the CGI script, the "/ralph"
-is information to be passed onto the CGI. If this configuration was in
-place, and a request came for "<code>/cgi-ralph/script/</code>", the
-code would set PATH_INFO to "<code>/ralph/script</code>", and
-SCRIPT_NAME to "<code>/cgi-</code>". Obviously, the latter is
-incorrect. In certain cases, this could even cause the server to
-crash.</p>
-
-<h2><a name="solution">The Solution</a></h2>
-
-<p>Apache 1.2 and later now determine SCRIPT_NAME and PATH_INFO by
-looking directly at the URL, and determining how much of the URL is
-client-modifiable, and setting PATH_INFO to it. To use the above
-example, PATH_INFO would be set to "<code>/script</code>", and
-SCRIPT_NAME to "<code>/cgi-ralph</code>". This makes sense and results
-in no server behavior problems. It also permits the script to be
-guaranteed that
-"<code>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</code>"
-will always be an accessible URL that points to the current script,
-something which was not necessarily true with previous versions of
-Apache.
-
-<p>However, the "<code>/ralph</code>"
-information from the <code>Alias</code> directive is lost. This is
-unfortunate, but we feel that using the filesystem to pass along this
-sort of information is not a recommended method, and a script making
-use of it "deserves" not to work. Apache 1.2b3 and later, however, do
-provide <a href="#compat">a workaround.</a>
-
-<h2><a name="compat">Compatibility with Previous Servers</a></h2>
-
-<p>It may be necessary for a script that was designed for earlier
-versions of Apache or other servers to need the information that the
-old PATH_INFO variable provided. For this purpose, Apache 1.2 (1.2b3
-and later) sets an additional variable, FILEPATH_INFO. This
-environment variable contains the value that PATH_INFO would have had
-with Apache 1.1.1.</p>
-
-<p>A script that wishes to work with both Apache 1.2 and earlier
-versions can simply test for the existence of FILEPATH_INFO, and use
-it if available. Otherwise, it can use PATH_INFO. For example, in
-Perl, one might use:
-<pre>
- $path_info = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'};
-</pre>
-
-<p>By doing this, a script can work with all servers supporting the
-CGI/1.1 specification, including all versions of Apache.</p>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
-
diff --git a/docs/manual/content-negotiation.html.en b/docs/manual/content-negotiation.html.en
deleted file mode 100644
index 2aa06eb..0000000
--- a/docs/manual/content-negotiation.html.en
+++ /dev/null
@@ -1,426 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache Content Negotiation</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">Content Negotiation</h1>
-
-Apache's support for content negotiation has been updated to meet the
-HTTP/1.1 specification. It can choose the best representation of a
-resource based on the browser-supplied preferences for media type,
-languages, character set and encoding. It is also implements a
-couple of features to give more intelligent handling of requests from
-browsers which send incomplete negotiation information. <p>
-
-Content negotiation is provided by the
-<a href="mod/mod_negotiation.html">mod_negotiation</a> module,
-which is compiled in by default.
-
-<hr>
-
-<h2>About Content Negotiation</h2>
-
-A resource may be available in several different representations. For
-example, it might be available in different languages or different
-media types, or a combination. One way of selecting the most
-appropriate choice is to give the user an index page, and let them
-select. However it is often possible for the server to choose
-automatically. This works because browsers can send as part of each
-request information about what representations they prefer. For
-example, a browser could indicate that it would like to see
-information in French, if possible, else English will do. Browsers
-indicate their preferences by headers in the request. To request only
-French representations, the browser would send
-
-<pre>
- Accept-Language: fr
-</pre>
-
-Note that this preference will only be applied when there is a choice
-of representations and they vary by language.
-<p>
-
-As an example of a more complex request, this browser has been
-configured to accept French and English, but prefer French, and to
-accept various media types, preferring HTML over plain text or other
-text types, and preferring GIF or JPEG over other media types, but also
-allowing any other media type as a last resort:
-
-<pre>
- Accept-Language: fr; q=1.0, en; q=0.5
- Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
- image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
-</pre>
-
-Apache 1.2 supports 'server driven' content negotiation, as defined in
-the HTTP/1.1 specification. It fully supports the Accept,
-Accept-Language, Accept-Charset and Accept-Encoding request headers.
-<p>
-
-The terms used in content negotiation are: a <b>resource</b> is an
-item which can be requested of a server, which might be selected as
-the result of a content negotiation algorithm. If a resource is
-available in several formats, these are called <b>representations</b>
-or <b>variants</b>. The ways in which the variants for a particular
-resource vary are called the <b>dimensions</b> of negotiation.
-
-<h2>Negotiation in Apache</h2>
-
-In order to negotiate a resource, the server needs to be given
-information about each of the variants. This is done in one of two
-ways:
-
-<ul>
- <li> Using a type map (i.e., a <code>*.var</code> file) which
- names the files containing the variants explicitly
- <li> Or using a 'MultiViews' search, where the server does an implicit
- filename pattern match, and chooses from among the results.
-</ul>
-
-<h3>Using a type-map file</h3>
-
-A type map is a document which is associated with the handler
-named <code>type-map</code> (or, for backwards-compatibility with
-older Apache configurations, the mime type
-<code>application/x-type-map</code>). Note that to use this feature,
-you've got to have a <code>SetHandler</code> some place which defines a
-file suffix as <code>type-map</code>; this is best done with a
-<pre>
-
- AddHandler type-map var
-
-</pre>
-in <code>srm.conf</code>. See comments in the sample config files for
-details. <p>
-
-Type map files have an entry for each available variant; these entries
-consist of contiguous RFC822-format header lines. Entries for
-different variants are separated by blank lines. Blank lines are
-illegal within an entry. It is conventional to begin a map file with
-an entry for the combined entity as a whole (although this
-is not required, and if present will be ignored). An example
-map file is:
-<pre>
-
- URI: foo
-
- URI: foo.en.html
- Content-type: text/html
- Content-language: en
-
- URI: foo.fr.de.html
- Content-type: text/html; charset=iso-8859-2
- Content-language: fr, de
-</pre>
-
-If the variants have different source qualities, that may be indicated
-by the "qs" parameter to the media type, as in this picture (available
-as jpeg, gif, or ASCII-art):
-<pre>
- URI: foo
-
- URI: foo.jpeg
- Content-type: image/jpeg; qs=0.8
-
- URI: foo.gif
- Content-type: image/gif; qs=0.5
-
- URI: foo.txt
- Content-type: text/plain; qs=0.01
-
-</pre>
-<p>
-
-qs values can vary between 0.000 and 1.000. Note that any variant with
-a qs value of 0.000 will never be chosen. Variants with no 'qs'
-parameter value are given a qs factor of 1.0. <p>
-
-The full list of headers recognized is:
-
-<dl>
- <dt> <code>URI:</code>
- <dd> uri of the file containing the variant (of the given media
- type, encoded with the given content encoding). These are
- interpreted as URLs relative to the map file; they must be on
- the same server (!), and they must refer to files to which the
- client would be granted access if they were to be requested
- directly.
- <dt> <code>Content-type:</code>
- <dd> media type --- charset, level and "qs" parameters may be given. These
- are often referred to as MIME types; typical media types are
- <code>image/gif</code>, <code>text/plain</code>, or
- <code>text/html; level=3</code>.
- <dt> <code>Content-language:</code>
- <dd> The languages of the variant, specified as an Internet standard
- language code (e.g., <code>en</code> for English,
- <code>kr</code> for Korean, etc.).
- <dt> <code>Content-encoding:</code>
- <dd> If the file is compressed, or otherwise encoded, rather than
- containing the actual raw data, this says how that was done.
- For compressed files (the only case where this generally comes
- up), content encoding should be
- <code>x-compress</code>, or <code>x-gzip</code>, as appropriate.
- <dt> <code>Content-length:</code>
- <dd> The size of the file. Clients can ask to receive a given media
- type only if the variant isn't too big; specifying a content
- length in the map allows the server to compare against these
- thresholds without checking the actual file.
-</dl>
-
-<h3>Multiviews</h3>
-
-This is a per-directory option, meaning it can be set with an
-<code>Options</code> directive within a <code><Directory></code>,
-<code><Location></code> or <code><Files></code>
-section in <code>access.conf</code>, or (if <code>AllowOverride</code>
-is properly set) in <code>.htaccess</code> files. Note that
-<code>Options All</code> does not set <code>MultiViews</code>; you
-have to ask for it by name. (Fixing this is a one-line change to
-<code>http_core.h</code>).
-
-<p>
-
-The effect of <code>MultiViews</code> is as follows: if the server
-receives a request for <code>/some/dir/foo</code>, if
-<code>/some/dir</code> has <code>MultiViews</code> enabled, and
-<code>/some/dir/foo</code> does <em>not</em> exist, then the server reads the
-directory looking for files named foo.*, and effectively fakes up a
-type map which names all those files, assigning them the same media
-types and content-encodings it would have if the client had asked for
-one of them by name. It then chooses the best match to the client's
-requirements, and forwards them along.
-
-<p>
-
-This applies to searches for the file named by the
-<code>DirectoryIndex</code> directive, if the server is trying to
-index a directory; if the configuration files specify
-<pre>
-
- DirectoryIndex index
-
-</pre> then the server will arbitrate between <code>index.html</code>
-and <code>index.html3</code> if both are present. If neither are
-present, and <code>index.cgi</code> is there, the server will run it.
-
-<p>
-
-If one of the files found when reading the directive is a CGI script,
-it's not obvious what should happen. The code gives that case
-special treatment --- if the request was a POST, or a GET with
-QUERY_ARGS or PATH_INFO, the script is given an extremely high quality
-rating, and generally invoked; otherwise it is given an extremely low
-quality rating, which generally causes one of the other views (if any)
-to be retrieved.
-
-<h2>The Negotiation Algorithm</h2>
-
-After Apache has obtained a list of the variants for a given resource,
-either from a type-map file or from the filenames in the directory, it
-applies a algorithm to decide on the 'best' variant to return, if
-any. To do this it calculates a quality value for each variant in each
-of the dimensions of variance. It is not necessary to know any of the
-details of how negotiation actually takes place in order to use Apache's
-content negotiation features. However the rest of this document
-explains in detail the algorithm used for those interested. <p>
-
-In some circumstances, Apache can 'fiddle' the quality factor of a
-particular dimension to achieve a better result. The ways Apache can
-fiddle quality factors is explained in more detail below.
-
-<h3>Dimensions of Negotiation</h3>
-
-<table>
-<tr><th>Dimension
-<th>Notes
-<tr><td>Media Type
-<td>Browser indicates preferences on Accept: header. Each item
-can have an associated quality factor. Variant description can also
-have a quality factor.
-<tr><td>Language
-<td>Browser indicates preferences on Accept-Language: header. Each
-item
-can have a quality factor. Variants can be associated with none, one
-or more languages.
-<tr><td>Encoding
-<td>Browser indicates preference with Accept-Encoding: header.
-<tr><td>Charset
-<td>Browser indicates preference with Accept-Charset: header. Variants
-can indicate a charset as a parameter of the media type.
-</table>
-
-<h3>Apache Negotiation Algorithm</h3>
-
-Apache uses an algorithm to select the 'best' variant (if any) to
-return to the browser. This algorithm is not configurable. It operates
-like this:
-<p>
-
-<ol>
-<li>
-Firstly, for each dimension of the negotiation, the appropriate
-Accept header is checked and a quality assigned to this each
-variant. If the Accept header for any dimension means that this
-variant is not acceptable, eliminate it. If no variants remain, go
-to step 4.
-
-<li>Select the 'best' variant by a process of elimination. Each of
-the following tests is applied in order. Any variants not selected at
-each stage are eliminated. After each test, if only one variant
-remains, it is selected as the best match. If more than one variant
-remains, move onto the next test.
-
-<ol>
-<li>Multiply the quality factor from the Accept header with the
- quality-of-source factor for this variant's media type, and select
- the variants with the highest value
-
-<li>Select the variants with the highest language quality factor
-
-<li>Select the variants with the best language match, using either the
- order of languages on the <code>LanguagePriority</code> directive (if present),
- else the order of languages on the Accept-Language header.
-
-<li>Select the variants with the highest 'level' media parameter
- (used to give the version of text/html media types).
-
-<li>Select only unencoded variants, if there is a mix of encoded
- and non-encoded variants. If either all variants are encoded
- or all variants are not encoded, select all.
-
-<li>Select only variants with acceptable charset media parameters,
- as given on the Accept-Charset header line. Charset ISO-8859-1
- is always acceptable. Variants not associated with a particular
- charset are assumed to be in ISO-8859-1.
-
-<li>Select the variants with the smallest content length
-
-<li>Select the first variant of those remaining (this will be either the
-first listed in the type-map file, or the first read from the directory)
-and go to stage 3.
-
-</ol>
-
-<li>The algorithm has now selected one 'best' variant, so return
- it as the response. The HTTP response header Vary is set to indicate the
- dimensions of negotiation (browsers and caches can use this
- information when caching the resource). End.
-
-<li>To get here means no variant was selected (because non are acceptable
- to the browser). Return a 406 status (meaning "No acceptable representation")
- with a response body consisting of an HTML document listing the
- available variants. Also set the HTTP Vary header to indicate the
- dimensions of variance.
-
-</ol>
-<h2><a name="better">Fiddling with Quality Values</a></h2>
-
-Apache sometimes changes the quality values from what would be
-expected by a strict interpretation of the algorithm above. This is to
-get a better result from the algorithm for browsers which do not send
-full or accurate information. Some of the most popular browsers send
-Accept header information which would otherwise result in the
-selection of the wrong variant in many cases. If a browser
-sends full and correct information these fiddles will not
-be applied.
-<p>
-
-<h3>Media Types and Wildcards</h3>
-
-The Accept: request header indicates preferences for media types. It
-can also include 'wildcard' media types, such as "image/*" or "*/*"
-where the * matches any string. So a request including:
-<pre>
- Accept: image/*, */*
-</pre>
-
-would indicate that any type starting "image/" is acceptable,
-as is any other type (so the first "image/*" is redundant). Some
-browsers routinely send wildcards in addition to explicit types they
-can handle. For example:
-<pre>
- Accept: text/html, text/plain, image/gif, image/jpeg, */*
-</pre>
-
-The intention of this is to indicate that the explicitly
-listed types are preferred, but if a different representation is
-available, that is ok too. However under the basic algorithm, as given
-above, the */* wildcard has exactly equal preference to all the other
-types, so they are not being preferred. The browser should really have
-sent a request with a lower quality (preference) value for *.*, such
-as:
-<pre>
- Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
-</pre>
-
-The explicit types have no quality factor, so they default to a
-preference of 1.0 (the highest). The wildcard */* is given
-a low preference of 0.01, so other types will only be returned if
-no variant matches an explicitly listed type.
-<p>
-
-If the Accept: header contains <i>no</i> q factors at all, Apache sets
-the q value of "*/*", if present, to 0.01 to emulate the desired
-behavior. It also sets the q value of wildcards of the format
-"type/*" to 0.02 (so these are preferred over matches against
-"*/*". If any media type on the Accept: header contains a q factor,
-these special values are <i>not</i> applied, so requests from browsers
-which send the correct information to start with work as expected.
-
-<h3>Variants with no Language</h3>
-
-If some of the variants for a particular resource have a language
-attribute, and some do not, those variants with no language
-are given a very low language quality factor of 0.001.<p>
-
-The reason for setting this language quality factor for
-variant with no language to a very low value is to allow
-for a default variant which can be supplied if none of the
-other variants match the browser's language preferences.
-
-For example, consider the situation with three variants:
-
-<ul>
-<li>foo.en.html, language en
-<li>foo.fr.html, language en
-<li>foo.html, no language
-</ul>
-
-The meaning of a variant with no language is that it is
-always acceptable to the browser. If the request Accept-Language
-header includes either en or fr (or both) one of foo.en.html
-or foo.fr.html will be returned. If the browser does not list
-either en or fr as acceptable, foo.html will be returned instead.
-
-<h2>Note on Caching</h2>
-
-When a cache stores a document, it associates it with the request URL.
-The next time that URL is requested, the cache can use the stored
-document, provided it is still within date. But if the resource is
-subject to content negotiation at the server, this would result in
-only the first requested variant being cached, and subsequent cache
-hits could return the wrong response. To prevent this,
-Apache normally marks all responses that are returned after content negotiation
-as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1
-protocol features to allow caching of negotiated responses. <P>
-
-For requests which come from a HTTP/1.0 compliant client (either a
-browser or a cache), the directive <tt>CacheNegotiatedDocs</tt> can be
-used to allow caching of responses which were subject to negotiation.
-This directive can be given in the server config or virtual host, and
-takes no arguments. It has no effect on requests from HTTP/1.1
-clients.
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
diff --git a/docs/manual/custom-error.html b/docs/manual/custom-error.html
index 3f04af0..3165ec0 100644
--- a/docs/manual/custom-error.html
+++ b/docs/manual/custom-error.html
@@ -29,9 +29,9 @@
response, then this response can be replaced with either some
friendlier text or by a redirection to another URL (local or
external).
-
+
<P>
-
+
<DT>Old behavior
<DD>NCSA httpd 1.3 would return some boring old error/problem message
diff --git a/docs/manual/custom-error.html.en b/docs/manual/custom-error.html.en
deleted file mode 100644
index 3f04af0..0000000
--- a/docs/manual/custom-error.html.en
+++ /dev/null
@@ -1,153 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Custom error responses</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">Custom error responses</H1>
-
-<DL>
-
-<DT>Purpose
-
- <DD>Additional functionality. Allows webmasters to configure the response of
- Apache to some error or problem.
-
- <P>Customizable responses can be defined to be activated in the
- event of a server detected error or problem.
-
- <P>e.g. if a script crashes and produces a "500 Server Error"
- response, then this response can be replaced with either some
- friendlier text or by a redirection to another URL (local or
- external).
-
- <P>
-
-<DT>Old behavior
-
- <DD>NCSA httpd 1.3 would return some boring old error/problem message
- which would often be meaningless to the user, and would provide no
- means of logging the symptoms which caused it.<BR>
-
- <P>
-
-<DT>New behavior
-
- <DD>The server can be asked to;
- <OL>
- <LI>Display some other text, instead of the NCSA hard coded messages, or
- <LI>redirect to a local URL, or
- <LI>redirect to an external URL.
- </OL>
-
- <P>Redirecting to another URL can be useful, but only if some information
- can be passed which can then be used to explain and/or log the error/problem
- more clearly.
-
- <P>To achieve this, Apache will define new CGI-like environment
- variables, e.g.
-
- <blockquote><code>
-REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <br>
-REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <br>
-REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <br>
-REDIRECT_QUERY_STRING= <br>
-REDIRECT_REMOTE_ADDR=121.345.78.123 <br>
-REDIRECT_REMOTE_HOST=ooh.ahhh.com <br>
-REDIRECT_SERVER_NAME=crash.bang.edu <br>
-REDIRECT_SERVER_PORT=80 <br>
-REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <br>
-REDIRECT_URL=/cgi-bin/buggy.pl <br>
- </code></blockquote>
-
- <P>note the <code>REDIRECT_</code> prefix.
-
- <P>At least <code>REDIRECT_URL</code> and <code>REDIRECT_QUERY_STRING</code> will
- be passed to the new URL (assuming it's a cgi-script or a cgi-include). The
- other variables will exist only if they existed prior to the error/problem.
- <b>None</b> of these will be set if your ErrorDocument is an
- <i>external</i> redirect (i.e. anything starting with a protocol name
- like <code>http:</code>, even if it refers to the same host as the
- server).<p>
-
-<DT>Configuration
-
- <DD> Use of "ErrorDocument" is enabled for .htaccess files when the
- <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is allowed.
-
- <P>Here are some examples...
-
- <blockquote><code>
-ErrorDocument 500 /cgi-bin/crash-recover <br>
-ErrorDocument 500 "Sorry, our script crashed. Oh dear<br>
-ErrorDocument 500 http://xxx/ <br>
-ErrorDocument 404 /Lame_excuses/not_found.html <br>
-ErrorDocument 401 /Subscription/how_to_subscribe.html
- </code></blockquote>
-
- <P>The syntax is,
-
- <P><code><A HREF="mod/core.html#errordocument">ErrorDocument</A></code>
-<3-digit-code> action
-
- <P>where the action can be,
-
- <OL>
- <LI>Text to be displayed. Prefix the text with a quote ("). Whatever
- follows the quote is displayed. <em>Note: the (") prefix isn't
- displayed.</em>
-
- <LI>An external URL to redirect to.
-
- <LI>A local URL to redirect to.
-
- </OL>
-</DL>
-
-<P><HR><P>
-
-<h2>Custom error responses and redirects</H2>
-
-<DL>
-
-<DT>Purpose
-
- <DD>Apache's behavior to redirected URLs has been modified so that additional
- environment variables are available to a script/server-include.<p>
-
-<DT>Old behavior
-
- <DD>Standard CGI vars were made available to a script which has been
- redirected to. No indication of where the redirection came from was provided.
-
- <p>
-
-<DT>New behavior
- <DD>
-
-A new batch of environment variables will be initialized for use by a
-script which has been redirected to. Each new variable will have the
-prefix <code>REDIRECT_</code>. <code>REDIRECT_</code> environment
-variables are created from the CGI environment variables which existed
-prior to the redirect, they are renamed with a <code>REDIRECT_</code>
-prefix, i.e. <code>HTTP_USER_AGENT</code> becomes
-<code>REDIRECT_HTTP_USER_AGENT</code>. In addition to these new
-variables, Apache will define <code>REDIRECT_URL</code> and
-<code>REDIRECT_STATUS</code> to help the script trace its origin.
-Both the original URL and the URL being redirected to can be logged in
-the access log.
-
-</DL>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
diff --git a/docs/manual/developer/API.html b/docs/manual/developer/API.html
deleted file mode 100644
index ad539e2..0000000
--- a/docs/manual/developer/API.html
+++ /dev/null
@@ -1,1004 +0,0 @@
-<!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, etc. 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, etc.</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> (i.e., a
-wildcard MIME type specification). However, wildcard handlers are
-only invoked if the server has already tried and failed to find a more
-specific response handler for the MIME type of the requested object
-(either none existed, or they all declined).<p>
-
-The handlers themselves are functions of one argument (a
-<code>request_rec</code> structure. vide infra), which returns an
-integer, as above.<p>
-
-<h3><a name="moduletour">A brief tour of a module</a></h3>
-
-At this point, we need to explain the structure of a module. Our
-candidate will be one of the messier ones, the CGI module --- this
-handles both CGI scripts and the <code>ScriptAlias</code> config file
-command. It's actually a great deal more complicated than most
-modules, but if we're going to have only one example, it might as well
-be the one with its fingers in 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, etc., either to service a
-particular request, or to handle the process of configuring itself.
-That way, when the request is over (or, for the configuration pool,
-when the server is restarting), the memory can be freed, and the files
-closed, <i>en masse</i>, without anyone having to write explicit code to
-track them all down and dispose of them. Also, a
-<code>cmd_parms</code> structure contains various information about
-the config file being read, and other status information, which is
-sometimes of use to the function which processes a config-file command
-(such as <code>ScriptAlias</code>).
-
-With no further ado, the module itself:
-
-<pre>
-/* Declarations of handlers. */
-
-int translate_scriptalias (request_rec *);
-int type_scriptalias (request_rec *);
-int cgi_handler (request_rec *);
-
-/* Subsidiary dispatch table for response-phase handlers, by MIME type */
-
-handler_rec cgi_handlers[] = {
-{ "application/x-httpd-cgi", cgi_handler },
-{ NULL }
-};
-
-/* Declarations of routines to manipulate the module's configuration
- * info. Note that these are returned, and passed in, as void *'s;
- * the server core keeps track of them, but it doesn't, and can't,
- * know their internal structure.
- */
-
-void *make_cgi_server_config (pool *);
-void *merge_cgi_server_config (pool *, void *, void *);
-
-/* Declarations of routines to handle config-file commands */
-
-extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
- char *real);
-
-command_rec cgi_cmds[] = {
-{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,
- "a fakename and a realname"},
-{ NULL }
-};
-
-module cgi_module = {
- STANDARD_MODULE_STUFF,
- NULL, /* initializer */
- NULL, /* dir config creator */
- NULL, /* dir merger --- default is to override */
- make_cgi_server_config, /* server config */
- merge_cgi_server_config, /* merge server config */
- cgi_cmds, /* command table */
- cgi_handlers, /* handlers */
- translate_scriptalias, /* filename translation */
- NULL, /* check_user_id */
- NULL, /* check auth */
- NULL, /* check access */
- type_scriptalias, /* type_checker */
- NULL, /* fixups */
- NULL, /* logger */
- NULL /* header parser */
-};
-</pre>
-
-<h2><a name="handlers">How handlers work</a></h2>
-
-The sole argument to handlers is a <code>request_rec</code> structure.
-This structure describes a particular request which has been made to
-the server, on behalf of a client. In most cases, each connection to
-the client generates only one <code>request_rec</code> structure.<p>
-
-<h3><a name="req_tour">A brief tour of the <code>request_rec</code></a></h3>
-
-The <code>request_rec</code> contains pointers to a resource pool
-which will be cleared when the server is finished handling the
-request; to structures containing per-server and per-connection
-information, and most importantly, information on the request itself.<p>
-
-The most important such information is a small set of character
-strings describing attributes of the object being requested, including
-its URI, filename, content-type and content-encoding (these being filled
-in by the translation and type-check handlers which handle the
-request, respectively). <p>
-
-Other commonly used data items are tables giving the MIME headers on
-the client's original request, MIME headers to be sent back with the
-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>table_get</code> and <code>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>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>
-struct request_rec {
-
- pool *pool;
- conn_rec *connection;
- server_rec *server;
-
- /* What object is being requested */
-
- char *uri;
- char *filename;
- char *path_info;
- char *args; /* QUERY_ARGS, if any */
- struct stat finfo; /* Set by server core;
- * st_mode set to zero if no such file */
-
- char *content_type;
- char *content_encoding;
-
- /* MIME header environments, in and out. Also, an array containing
- * environment variables to be passed to subprocesses, so people can
- * write modules to add to that environment.
- *
- * The difference between headers_out and err_headers_out is that
- * the latter are printed even on error, and persist across internal
- * redirects (so the headers printed for ErrorDocument handlers will
- * have them).
- */
-
- table *headers_in;
- table *headers_out;
- table *err_headers_out;
- table *subprocess_env;
-
- /* Info about the request itself... */
-
- int header_only; /* HEAD request, as opposed to GET */
- char *protocol; /* Protocol, as given to us, or HTTP/0.9 */
- char *method; /* GET, HEAD, POST, etc. */
- int method_number; /* M_GET, M_POST, etc. */
-
- /* Info for logging */
-
- char *the_request;
- int bytes_sent;
-
- /* A flag which modules can set, to indicate that the data being
- * returned is volatile, and clients should be told not to cache it.
- */
-
- int no_cache;
-
- /* Various other config info which may change with .htaccess files
- * These are config vectors, with one void* pointer for each module
- * (the thing pointed to being the module's business).
- */
-
- void *per_dir_config; /* Options set in config files, etc. */
- void *request_config; /* Notes on *this* request */
-
-};
-
-</pre>
-
-<h3><a name="req_orig">Where request_rec structures come from</a></h3>
-
-Most <code>request_rec</code> structures are built by reading an HTTP
-request from a client, and filling in the fields. However, there are
-a few exceptions:
-
-<ul>
- <li> If the request is to an imagemap, a type map (i.e., a
- <code>*.var</code> file), or a CGI script which returned a
- local `Location:', then the resource which the user requested
- is going to be ultimately located by some URI other than what
- the client originally supplied. In this case, the server does
- an <em>internal redirect</em>, constructing a new
- <code>request_rec</code> for the new URI, and processing it
- almost exactly as if the client had requested the new URI
- directly. <p>
-
- <li> If some handler signaled an error, and an
- <code>ErrorDocument</code> is in scope, the same internal
- redirect machinery comes into play.<p>
-
- <li> Finally, a handler occasionally needs to investigate `what
- would happen if' some other request were run. For instance,
- the directory indexing module needs to know what MIME type
- would be assigned to a request for each directory entry, in
- order to figure out what icon to use.<p>
-
- Such handlers can construct a <em>sub-request</em>, using the
- functions <code>sub_req_lookup_file</code> and
- <code>sub_req_lookup_uri</code>; this constructs a new
- <code>request_rec</code> structure and processes it as you
- would expect, up to but not including the point of actually
- sending a response. (These functions skip over the access
- checks if the sub-request is for a file in the same directory
- as the original request).<p>
-
- (Server-side includes work by building sub-requests and then
- actually invoking the response handler for them, via the
- function <code>run_sub_request</code>).
-</ul>
-
-<h3><a name="req_return">Handling requests, declining, and returning error codes</a></h3>
-
-As discussed above, each handler, when invoked to handle a particular
-<code>request_rec</code>, has to return an <code>int</code> to
-indicate what happened. That can either be
-
-<ul>
- <li> OK --- the request was handled successfully. This may or may
- not terminate the phase.
- <li> DECLINED --- no erroneous condition exists, but the module
- declines to handle the phase; the server tries to find another.
- <li> an HTTP error code, which aborts handling of the request.
-</ul>
-
-Note that if the error code returned is <code>REDIRECT</code>, then
-the module should put a <code>Location</code> in the request's
-<code>headers_out</code>, to indicate where the client should be
-redirected <em>to</em>. <p>
-
-<h3><a name="resp_handlers">Special considerations for response handlers</a></h3>
-
-Handlers for most phases do their work by simply setting a few fields
-in the <code>request_rec</code> structure (or, in the case of access
-checkers, simply by returning the correct error code). However,
-response handlers have to actually send a request back to the client. <p>
-
-They should begin by sending an HTTP response header, using the
-function <code>send_http_header</code>. (You don't have to do
-anything special to skip sending the header for HTTP/0.9 requests; the
-function figures out on its own that it shouldn't do anything). If
-the request is marked <code>header_only</code>, that's all they should
-do; they should return after that, without attempting any further
-output. <p>
-
-Otherwise, they should produce a request body which responds to the
-client as appropriate. The primitives for this are <code>rputc</code>
-and <code>rprintf</code>, for internally generated output, and
-<code>send_fd</code>, to copy the contents of some <code>FILE *</code>
-straight to the client. <p>
-
-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>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>set_content_length</code>, but it returns an error code for
-symmetry.<p>
-
-<pre>
-int default_handler (request_rec *r)
-{
- int errstatus;
- FILE *f;
-
- if (r->method_number != M_GET) return DECLINED;
- if (r->finfo.st_mode == 0) return NOT_FOUND;
-
- if ((errstatus = set_content_length (r, r->finfo.st_size))
- || (errstatus = set_last_modified (r, r->finfo.st_mtime)))
- return errstatus;
-
- f = fopen (r->filename, "r");
-
- if (f == NULL) {
- log_reason("file permissions deny server access",
- r->filename, r);
- return FORBIDDEN;
- }
-
- register_timeout ("send", r);
- send_http_header (r);
-
- if (!r->header_only) send_fd (f, r);
- 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>internal_redirect</code>, which is how the internal redirection
-machinery discussed above is invoked. A response handler which has
-internally redirected should always return <code>OK</code>. <p>
-
-(Invoking <code>internal_redirect</code> from handlers which are
-<em>not</em> response handlers will lead to serious confusion).
-
-<h3><a name="auth_handlers">Special considerations for authentication handlers</a></h3>
-
-Stuff that should be discussed here in detail:
-
-<ul>
- <li> Authentication-phase handlers not invoked unless auth is
- configured for the directory.
- <li> Common auth configuration stored in the core per-dir
- configuration; it has accessors <code>auth_type</code>,
- <code>auth_name</code>, and <code>requires</code>.
- <li> Common routines, to handle the protocol end of things, at least
- for HTTP basic authentication (<code>get_basic_auth_pw</code>,
- which sets the <code>connection->user</code> structure field
- automatically, and <code>note_basic_auth_failure</code>, which
- arranges for the proper <code>WWW-Authenticate:</code> header
- to be sent back).
-</ul>
-
-<h3><a name="log_handlers">Special considerations for logging handlers</a></h3>
-
-When a request has internally redirected, there is the question of
-what to log. 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>
-
-One of the problems of writing and designing a server-pool server is
-that of preventing leakage, that is, allocating resources (memory,
-open files, etc.), without subsequently releasing them. The resource
-pool machinery is designed to 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>
-
-The way this works is as follows: the memory which is allocated, file
-opened, etc., 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>
-
-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>
-
-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>
-
-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">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>palloc</code> is generally faster than
-<code>malloc</code>.<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.
-
-<h3>Allocation of memory in pools</h3>
-
-Memory is allocated to pools by calling the function
-<code>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:
-
-<pre>
-int my_handler(request_rec *r)
-{
- struct my_structure *foo;
- ...
-
- foo = (foo *)palloc (r->pool, sizeof(my_structure));
-}
-</pre>
-
-Note that <em>there is no <code>pfree</code></em> ---
-<code>palloc</code>ed memory is freed only when the associated
-resource pool is cleared. This means that <code>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>
-
-(It also raises the possibility that heavy use of <code>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).
-
-<h3>Allocating initialized memory</h3>
-
-There are functions which allocate initialized memory, and are
-frequently useful. The function <code>pcalloc</code> has the same
-interface as <code>palloc</code>, but clears out the memory it
-allocates before it returns it. The function <code>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>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:
-
-<pre>
- pstrcat (r->pool, "foo", "/", "bar", NULL);
-</pre>
-
-returns a pointer to 8 bytes worth of memory, initialized to
-<code>"foo/bar"</code>.
-
-<h3><a name="pool-files">Tracking open files, etc.</a></h3>
-
-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>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>, e.g.,
-
-<pre>
- ...
- FILE *f = pfopen (r->pool, r->filename, "r");
-
- if (f == NULL) { ... } else { ... }
-</pre>
-
-There is also a <code>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>
-
-Unlike the case for memory, there <em>are</em> functions to close
-files allocated with <code>pfopen</code>, and <code>popenf</code>,
-namely <code>pfclose</code> and <code>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>pfopen</code> and
-<code>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>
-
-(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).
-
-<h3>Other sorts of resources --- cleanup functions</h3>
-
-More text goes here. Describe the the cleanup primitives in terms of
-which the file stuff is implemented; also, <code>spawn_process</code>.
-
-<h3>Fine control --- creating and dealing with sub-pools, with a note
-on sub-requests</h3>
-
-On rare occasions, too-free use of <code>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>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>clear_pool</code> and <code>destroy_pool</code>, respectively.
-(The difference is that <code>clear_pool</code> frees resources
-associated with the pool, while <code>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>sub_req_lookup_...</code> functions)
-is <code>destroy_sub_request</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>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>
-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>palloc</code>s the structure above, and a creates a couple of
-<code>table</code>s to fill it. That looks like this:
-
-<pre>
-void *create_mime_dir_config (pool *p, char *dummy)
-{
- mime_dir_config *new =
- (mime_dir_config *) palloc (p, sizeof(mime_dir_config));
-
- new->forced_types = make_table (p, 4);
- new->encoding_types = make_table (p, 4);
-
- return new;
-}
-</pre>
-
-Now, suppose we've just read in a <code>.htaccess</code> file. We
-already have the per-directory configuration structure for the next
-directory up in the hierarchy. If the <code>.htaccess</code> file we
-just read in didn't have any <code>AddType</code> or
-<code>AddEncoding</code> commands, its per-directory config structure
-for the MIME module is still valid, and we can just use it.
-Otherwise, we need to merge the two structures somehow. <p>
-
-To do that, the server invokes the module's per-directory config merge
-function, if one is present. That function takes three arguments:
-the two structures being merged, and a resource pool in which to
-allocate the result. For the MIME module, all that needs to be done
-is overlay the tables from the new per-directory config structure with
-those from the parent:
-
-<pre>
-void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
-{
- mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
- mime_dir_config *subdir = (mime_dir_config *)subdirv;
- mime_dir_config *new =
- (mime_dir_config *)palloc (p, sizeof(mime_dir_config));
-
- new->forced_types = overlay_tables (p, subdir->forced_types,
- parent_dir->forced_types);
- new->encoding_types = overlay_tables (p, subdir->encoding_types,
- parent_dir->encoding_types);
-
- return new;
-}
-</pre>
-
-As a note --- if there is no per-directory merge function present, the
-server will just use the subdirectory's configuration info, and ignore
-the parent's. For some modules, that works just fine (e.g., for the
-includes module, whose per-directory configuration information
-consists solely of the state of the <code>XBITHACK</code>), and for
-those modules, you can just not declare one, and leave the
-corresponding structure slot in the module itself <code>NULL</code>.<p>
-
-<h3><a name="commands">Command handling</a></h3>
-
-Now that we have these structures, we need to be able to figure out
-how to fill them. That involves processing the actual
-<code>AddType</code> and <code>AddEncoding</code> commands. To find
-commands, the server looks in the module's <code>command table</code>.
-That table contains information on how many arguments the commands
-take, and in what formats, where it is permitted, and so forth. That
-information is sufficient to allow the server to invoke most
-command-handling functions with 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;
- 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>
-command_rec mime_cmds[] = {
-{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2,
- "a mime type followed by a file extension" },
-{ "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,
- "an encoding (e.g., gzip), followed by a file extension" },
-{ NULL }
-};
-</pre>
-
-The entries in these tables are:
-
-<ul>
- <li> The name of the command
- <li> The function which handles it
- <li> a <code>(void *)</code> pointer, which is passed in the
- <code>cmd_parms</code> structure to the command handler ---
- this is useful in case many similar commands are handled by the
- same function.
- <li> A bit mask indicating where the command may appear. There are
- mask bits corresponding to each <code>AllowOverride</code>
- option, and an additional mask bit, <code>RSRC_CONF</code>,
- indicating that the command may appear in the server's own
- config files, but <em>not</em> in any <code>.htaccess</code>
- file.
- <li> A flag indicating how many arguments the command handler wants
- 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>get_module_config</code> function.
-
-<pre>
-int find_ct(request_rec *r)
-{
- int i;
- char *fn = pstrdup (r->pool, r->filename);
- mime_dir_config *conf = (mime_dir_config *)
- get_module_config(r->per_dir_config, &mime_module);
- char *type;
-
- if (S_ISDIR(r->finfo.st_mode)) {
- r->content_type = DIR_MAGIC_TYPE;
- return OK;
- }
-
- if((i=rind(fn,'.')) < 0) return DECLINED;
- ++i;
-
- if ((type = table_get (conf->encoding_types, &fn[i])))
- {
- r->content_encoding = type;
-
- /* go back to previous extension to try to use it as a type */
-
- fn[i-1] = '\0';
- if((i=rind(fn,'.')) < 0) return OK;
- ++i;
- }
-
- if ((type = table_get (conf->forced_types, &fn[i])))
- {
- r->content_type = type;
- }
-
- return OK;
-}
-
-</pre>
-
-<h3><a name="servconf">Side notes --- per-server configuration, virtual servers, etc.</a></h3>
-
-The basic ideas behind per-server module configuration are basically
-the same as those for per-directory configuration; there is a creation
-function and a merge function, the latter being invoked where a
-virtual server has partially 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>
-char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
-{
- server_rec *s = cmd->server;
- alias_server_conf *conf = (alias_server_conf *)
- get_module_config(s->module_config,&alias_module);
- alias_entry *new = push_array (conf->redirects);
-
- if (!is_url (url)) return "Redirect to non-URL";
-
- new->fake = f; new->real = url;
- return NULL;
-}
-</pre>
-<!--#include virtual="footer.html" -->
-</body></html>
diff --git a/docs/manual/handler.html.en b/docs/manual/handler.html.en
deleted file mode 100644
index 8059216..0000000
--- a/docs/manual/handler.html.en
+++ /dev/null
@@ -1,141 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache's Handler Use</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's Handler Use</h1>
-
-<h2>What is a Handler</h2>
-
-<p>A "handler" is an internal Apache representation of the action to be
-performed when a file is called. Generally, files have implicit
-handlers, based on the file type. Normally, all files are simply
-served by the server, but certain file typed are "handled"
-separately. For example, you may use a type of
-"application/x-httpd-cgi" to invoke CGI scripts.</p>
-
-<p>Apache 1.1 adds the additional ability to use handlers
-explicitly. Either based on filename extensions or on location, these
-handlers are unrelated to file type. This is advantageous both because
-it is a more elegant solution, but it also allows for both a type
-<strong>and</strong> a handler to be associated with a file.</p>
-
-<p>Handlers can either be built into the server or to a module, or
-they can be added with the <a
-href="mod/mod_actions.html#action">Action</a> directive. The built-in
-handlers in the standard distribution are as follows:</p>
-
-<ul>
-<li><strong>send-as-is</strong>:
- Send file with HTTP headers as is.
- (<a href="mod/mod_asis.html">mod_asis</a>)
-<li><strong>cgi-script</strong>:
- Treat the file as a CGI script.
- (<a href="mod/mod_cgi.html">mod_cgi</a>)
-<li><strong>imap-file</strong>:
- Imagemap rule file.
- (<a href="mod/mod_imap.html">mod_imap</a>)
-<li><strong>server-info</strong>:
- Get the server's configuration information
- (<a href="mod/mod_info.html">mod_info</a>)
-<li><strong>server-parsed</strong>:
- Parse for server-side includes
- (<a href="mod/mod_include.html">mod_include</a>)
-<li><strong>server-status</strong>:
- Get the server's status report
- (<a href="mod/mod_status.html">mod_status</a>)
-<li><strong>type-map</strong>:
- Parse as a type map file for content negotiation
- (<a href="mod/mod_negotiation.html">mod_negotiation</a>)
-</ul>
-
-<p>
-
-<h2>Directives</h2>
-<ul>
-<li><A HREF="#addhandler">AddHandler</A>
-<li><A HREF="#sethandler">SetHandler</A>
-</ul>
-
-<hr>
-
-<h2><a name="addhandler">AddHandler</a></h2>
-
-<strong>Syntax:</strong> <AddHandler <em>handler-name extension</em>><br>
-<strong>Context:</strong> server config, virtual host, directory, .htaccess<br>
-<strong>Status:</strong> Base<br>
-<strong>Module:</strong> mod_mime
-
-<p>AddHandler maps the filename extension <em>extension</em> to the
-handler <em>handler-name</em>. For example, to activate CGI scripts
-with the file extension "<code>.cgi</code>", you might use:
-<pre>
- AddHandler cgi-script cgi
-</pre>
-
-<p>Once that has been put into your srm.conf or httpd.conf file, any
-file ending with "<code>.cgi</code>" will be treated as a CGI
-program.</p>
-
-<hr>
-
-<h2><a name="sethandler">SetHandler</a></h2>
-
-<strong>Syntax:</strong> <SetHandler <em>handler-name</em>><br>
-<strong>Context:</strong> directory, .htaccess<br>
-<strong>Status:</strong> Base<br>
-<strong>Module:</strong> mod_mime
-
-<p>When placed into an <code>.htaccess</code> file or a
-<code><Directory></code> or <code><Location></code> section,
-this directive forces all matching files to be parsed through the
-handler given by <em>handler-name</em>. For example, if you had a
-directory you wanted to be parsed entirely as imagemap rule files,
-regardless of extension, you might put the following into an
-<code>.htaccess</code> file in that directory:
-<pre>
- SetHandler imap-file
-</pre>
-<p>Another example: if you wanted to have the server display a status
-report whenever a URL of <code>http://servername/status</code> was
-called, you might put the following into access.conf:
-<pre>
- <Location /status>
- SetHandler server-status
- </Location>
-</pre>
-
-<p><hr>
-
-<h2>Programmer's Note</h2>
-
-<p>In order to implement the handler features, an addition has been
-made to the <a href="misc/API.html">Apache API</a> that you may wish to
-make use of. Specifically, a new record has been added to the
-<code>request_rec</code> structure:</p>
-<pre>
- char *handler
-</pre>
-<p>If you wish to have your module engage a handler, you need only to
-set <code>r->handler</code> to the name of the handler at any time
-prior to the <code>invoke_handler</code> stage of the
-request. Handlers are implemented as they were before, albeit using
-the handler name instead of a content type. While it is not
-necessary, the naming convention for handlers is to use a
-dash-separated word, with no slashes, so as to not invade the media
-type name-space.</p>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
-
diff --git a/docs/manual/install.html.en b/docs/manual/install.html.en
deleted file mode 100644
index 52e84b0..0000000
--- a/docs/manual/install.html.en
+++ /dev/null
@@ -1,249 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Compiling and Installing 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">Compiling and Installing Apache 1.2</H1>
-
-<P>If you wish to download and install an earlier version of Apache please
-read <A HREF="install_1_1.html">Compiling and Installing Apache 1.1</A>.</P>
-
-UnixWare users will want to consult <A HREF="unixware.html">build notes</A>
-for various UnixWare versions before compiling.
-
-<H2>Downloading Apache</H2>
-
-Information on the latest version of Apache can be found on the Apache
-web server at <A
-HREF="http://www.apache.org/">http://www.apache.org/</A>. This will
-list the current release, any more recent beta-test release, together
-with details of mirror web and anonymous ftp sites.
-
-<P>
-
-If you downloaded a binary distribution, skip to <A
-HREF="#install">Installing Apache</A>. Otherwise read the next section
-for how to compile the server.
-
-<h2>Compiling Apache</h2>
-
-Compiling Apache consists of three steps: Firstly select which Apache
-<b>modules</b> you want to include into the server. Secondly create a
-configuration for your operating system. Thirdly compile the
-executable.
-<P>
-
-All configuration of Apache is performed in the <CODE>src</CODE>
-directory of the Apache distribution. Change into this directory.
-
-<OL>
- <LI>
- Select modules to compile into Apache in the
- <CODE>Configuration</CODE> file. Uncomment lines corresponding to
- those optional modules you wish to include (among the Module lines
- at the bottom of the file), or add new lines corresponding to
- additional modules you have downloaded or written. (See <A
- HREF="misc/API.html">API.html</A> for preliminary docs on how to
- write Apache modules). Advanced users can comment out some of the
- default modules if they are sure they will not need them (be careful
- though, since many of the default modules are vital for the correct
- operation and security of the server).
- <P>
-
- You should also read the instructions in the <CODE>Configuration</CODE>
- file to see if you need to set any of the <CODE>Rule</CODE> lines.
-
-
- <LI>
- Configure Apache for your operating system. Normally you can just
- type run the <CODE>Configure</CODE> script as given below. However
- if this fails or you have any special requirements (e.g. to include
- an additional library required by an optional module) you might need
- to edit one or more of the following options in the
- <CODE>Configuration</CODE> file:
- <CODE>EXTRA_CFLAGS, LIBS, LFLAGS, INCLUDES</CODE>.
- <P>
-
- Run the <CODE>Configure</CODE> script:
- <BLOCKQUOTE>
- <PRE>
- % Configure
- Using 'Configuration' as config file
- + configured for <whatever> platform
- + setting C compiler to <whatever> *
- + setting C compiler optimization-level to <whatever> *
- %
- </PRE>
- </BLOCKQUOTE>
-
- (*: Depending on Configuration and your system, Configure
- make not print these lines. That's OK).<P>
-
- This generates a Makefile for use in stage 3. It also creates a
- Makefile in the support directory, for compilation of the optional
- support programs.
- <P>
-
- (If you want to maintain multiple configurations, you can give a
- option to <CODE>Configure</CODE> to tell it to read an alternative
- Configuration file, such as <CODE>Configure -file
- Configuration.ai</CODE>).
- <P>
-
- <LI>
- Type <CODE>make</CODE>.
-</OL>
-
-The modules we place in the Apache distribution are the ones we have
-tested and are used regularly by various members of the Apache
-development group. Additional modules contributed by members or third
-parties with specific needs or functions are available at <A
-HREF="http://www.apache.org/dist/contrib/modules/"><URL:http://www.apache.org/dist/contrib/modules/></a>.
-There are instructions on that page for linking these modules into the
-core Apache code.
-
-<h2><A NAME="install">Installing Apache</A></h2>
-
-You will have a binary file called <CODE>httpd</CODE> in the
-<CODE>src</CODE> directory. A binary distribution of Apache will
-supply this file. <P>
-
-The next step is to install the program and configure it. Apache is
-designed to be configured and run from the same set of directories
-where it is compiled. If you want to run it from somewhere else, make
-a directory and copy the <CODE>conf</CODE>, <CODE>logs</CODE> and
-<CODE>icons</CODE> directories into it. <P>
-
-The next step is to edit the configuration files for the server. This
-consists of setting up various <B>directives</B> in up to three
-central configuration files. By default, these files are located in
-the <CODE>conf</CODE> directory and are called <CODE>srm.conf</CODE>,
-<CODE>access.conf</CODE> and <CODE>httpd.conf</CODE>. To help you get
-started there are same files in the <CODE>conf</CODE> directory of the
-distribution, called <CODE>srm.conf-dist</CODE>,
-<CODE>access.conf-dist</CODE> and <CODE>httpd.conf-dist</CODE>. Copy
-or rename these files to the names without the <CODE>-dist</CODE>.
-Then edit each of the files. Read the comments in each file carefully.
-Failure to setup these files correctly could lead to your server not
-working or being insecure. You should also have an additional file in
-the <CODE>conf</CODE> directory called <CODE>mime.types</CODE>. This
-file usually does not need editing.
-
-<P>
-
-First edit <CODE>httpd.conf</CODE>. This sets up general attributes
-about the server: the port number, the user it runs as, etc. Next
-edit the <CODE>srm.conf</CODE> file; this sets up the root of the
-document tree, special functions like server-parsed HTML or internal
-imagemap parsing, etc. Finally, edit the <CODE>access.conf</CODE>
-file to at least set the base cases of access.
-
-<P>
-
-In addition to these three files, the server behavior can be configured
-on a directory-by-directory basis by using <CODE>.htaccess</CODE>
-files in directories accessed by the server.
-
-<H3>Starting and Stopping the Server</H3>
-
-To start the server, simply run <CODE>httpd</CODE>. This will look for
-<CODE>httpd.conf</CODE> in the location compiled into the code (by
-default <CODE>/usr/locale/etc/httpd/conf/httpd.conf</CODE>). If
-this file is somewhere else, you can give the real
-location with the -f argument. For example:
-
-<PRE>
- /usr/local/etc/apache/src/httpd -f /usr/local/etc/apache/conf/httpd.conf
-</PRE>
-
-If all goes well this will return to the command prompt almost
-immediately. This indicates that the server is now up and running. If
-anything goes wrong during the initialization of the server you will
-see an error message on the screen.
-
-If the server started ok, you can now use your browser to
-connect to the server and read the documentation. If you are running
-the browser on the same machine as the server and using the default
-port of 80, a suitable URL to enter into your browser is
-
-<PRE>
- http://localhost/
-</PRE>
-
-<P>
-
-Note that when the server starts it will create a number of
-<i>child</i> processes to handle the requests. If you started Apache
-as the root user, the parent process will continue to run as root
-while the children will change to the user as given in the httpd.conf
-file.
-
-<P>
-
-If when you run <CODE>httpd</CODE> it complained about being unable to
-"bind" to an address, then either some other process is already using
-the port you have configured Apache to use, or you are running httpd
-as a normal user but trying to use port below 1024 (such as the
-default port 80).
-
-<P>
-
-If the server is not running, read the error message displayed
-when you run httpd. You should also check the server
-error_log for additional information (with the default configuration,
-this will be located in the file <CODE>error_log</CODE> in the
-<CODE>logs</CODE> directory).
-
-<P>
-
-If you want your server to continue running after a system reboot, you
-should add a call to <CODE>httpd</CODE> to your system startup files
-(typically <CODE>rc.local</CODE> or a file in an
-<CODE>rc.<I>N</I></CODE> directory). This will start Apache as root.
-Before doing this ensure that your server is properly configured
-for security and access restrictions.
-
-<P>
-
-To stop Apache send the parent process a TERM signal. The PID of this
-process is written to the file <CODE>httpd.pid</CODE> in the
-<CODE>logs</CODE> directory (unless configured otherwise). Do not
-attempt to kill the child processes because they will be renewed by
-the parent. A typical command to stop the server is:
-
-<PRE>
- kill -TERM `cat /usr/local/etc/apache/logs/httpd.pid`
-</PRE>
-
-<P>
-
-For more information about Apache command line options, configuration
-and log files, see <A HREF="invoking.html">Starting Apache</A>. For a
-reference guide to all Apache directives supported by the distributed
-modules, see the <A HREF="mod/directives.html">Apache directives</A>.
-
-<H2>Compiling Support Programs</H2>
-
-In addition to the main <CODE>httpd</CODE> server which is compiled
-and configured as above, Apache includes a number of support programs.
-These are not compiled by default. The support programs are in the
-<CODE>support</CODE> directory of the distribution. To compile
-the support programs, change into this directory and type
-<PRE>
- make
-</PRE>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
diff --git a/docs/manual/invoking.html.en b/docs/manual/invoking.html.en
deleted file mode 100644
index 62e6a41..0000000
--- a/docs/manual/invoking.html.en
+++ /dev/null
@@ -1,124 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Starting 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">Starting Apache</h1>
-
-<h2>Invoking Apache</h2>
-The <code>httpd</code> program is usually run as a daemon which executes
-continuously, handling requests. It is possible to invoke Apache by
-the Internet daemon <code>inetd</code> each time a connection to the HTTP
-service is made (use the
-<A HREF="mod/core.html#servertype">ServerType</A> directive)
-but this is not recommended.
-
-<h2>Command line options</h2>
-The following options are recognized on the httpd command line:
-<dl>
-<dt><code>-d</code> <em>serverroot</em>
-<dd>Set the initial value for the
-<A HREF="mod/core.html#serverroot">ServerRoot</A> variable to
-<em>serverroot</em>. This can be overridden by the ServerRoot command in the
-configuration file. The default is <code>/usr/local/etc/httpd</code>.
-
-<dt><code>-f</code> <em>config</em>
-<dd>Execute the commands in the file <em>config</em> on startup. If
-<em>config</em> does not begin with a <code>/</code>, then it is taken to be a
-path relative to the <A HREF="mod/core.html#serverroot">ServerRoot</A>. The
-default is <code>conf/httpd.conf</code>.
-
-<dt><code>-X</code>
-<dd>Run in single-process mode, for internal debugging purposes only; the
-daemon does not detach from the terminal or fork any children. Do <em>NOT</em>
-use this mode to provide ordinary web service.
-
-<dt><code>-v</code>
-<dd>Print the version of httpd, and then exit.
-
-<dt><a name="help"><code>-h</code></a>
-<dd>Give a list of directives together with expected arguments and
-places where the directive is valid. (New in Apache 1.2)
-
-<dt><code>-l</code>
-<dd>Give a list of all modules compiled into the server.
-
-<dt><code>-?</code>
-<dd>Print a list of the httpd options, and then exit.
-</dl>
-
-<h2>Configuration files</h2>
-The server will read three files for configuration directives. Any directive
-may appear in any of these files. The the names of these files are taken
-to be relative to the server root; this is set by the
-<A HREF="mod/core.html#serverroot">ServerRoot</A> directive, or the
-<code>-d</code> command line flag.
-
-Conventionally, the files are:
-<dl>
-<dt><code>conf/httpd.conf</code>
-<dd>Contains directives that control the operation of the server daemon.
-The filename may be overridden with the <code>-f</code> command line flag.
-
-<dt><code>conf/srm.conf</code>
-<dd>Contains directives that control the specification of documents that
-the server can provide to clients. The filename may be overridden with
-the <A HREF="mod/core.html#resourceconfig">ResourceConfig</A> directive.
-
-<dt><code>conf/access.conf</code>
-<dd>Contains directives that control access to documents.
-The filename may be overridden with the
-<A HREF="mod/core.html#accessconfig">AccessConfig</A> directive.
-</dl>
-However, these conventions need not be adhered to.
-<p>
-The server also reads a file containing mime document types; the filename
-is set by the <A HREF="mod/mod_mime.html#typesconfig">TypesConfig</A> directive,
-and is <code>conf/mime.types</code> by default.
-
-<h2>Log files</h2>
-<h3>security warning</h3>
-Anyone who can write to the directory where Apache is writing a
-log file can almost certainly gain access to the uid that the server is
-started as, which is normally root. Do <EM>NOT</EM> give people write
-access to the directory the logs are stored in without being aware of
-the consequences; see the <A HREF="misc/security_tips.html">security tips</A>
-document for details.
-<h3>pid file</h3>
-On daemon startup, it saves the process id of the parent httpd process to
-the file <code>logs/httpd.pid</code>. This filename can be changed with the
-<A HREF="mod/core.html#pidfile">PidFile</A> directive. The process-id is for
-use by the administrator in restarting and terminating the daemon;
-A HUP or USR1 signal causes the daemon to re-read its configuration files and
-a TERM signal causes it to die gracefully. For more information
-see the <a href="stopping.html">Stopping and Restarting</a> page.
-<p>
-If the process dies (or is killed) abnormally, then it will be necessary to
-kill the children httpd processes.
-
-<h3>Error log</h3>
-The server will log error messages to a log file, <code>logs/error_log</code>
-by default. The filename can be set using the
-<A HREF="mod/core.html#errorlog">ErrorLog</A> directive; different error logs can
-be set for different <A HREF="mod/core.html#virtualhost">virtual hosts</A>.
-
-<h3>Transfer log</h3>
-The server will typically log each request to a transfer file,
-<code>logs/access_log</code> by default. The filename can be set using a
-<A HREF="mod/mod_log_common.html#transferlog">TransferLog</A> directive; different
-transfer logs can be set for different <A HREF="mod/core.html#virtualhost">virtual
-hosts</A>.
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
diff --git a/docs/manual/misc/FAQ.html b/docs/manual/misc/FAQ.html
index 94d257d..ef0c292 100644
--- a/docs/manual/misc/FAQ.html
+++ b/docs/manual/misc/FAQ.html
@@ -15,7 +15,7 @@
<!--#include virtual="header.html" -->
<H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>
<P>
- $Revision: 1.63 $ ($Date: 1997/06/04 11:42:55 $)
+ $Revision: 1.63.2.8 $ ($Date: 1997/07/05 17:30:58 $)
</P>
<P>
The latest version of this FAQ is always available from the main
@@ -35,6 +35,11 @@
<!-- apache.org or apacheweek.com). -->
<!-- - 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>
@@ -51,8 +56,8 @@
<!-- - 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.? -->
+<!-- - 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? -->
@@ -61,17 +66,17 @@
<!-- HTTP/1.1 browsers? -->
<!-- - Is there an Apache for W95/WNT? -->
<!-- - Why does Apache die when a vhost can't be DNS-resolved? -->
-<!-- - How do I setup an access restriction so that people from -->
-<!-- this domain don't have to authenticate, and all others can -->
-<!-- do so via a username and password? -->
<!-- - 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 does http://host/~user not work but http://host/~user/ -->
-<!-- works properly? -->
+<!-- - 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. -->
<UL>
<LI><STRONG>Background</STRONG>
<OL START=1>
@@ -126,6 +131,8 @@
<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 FD_SETSIZE on FreeBSD?</A>
+ </LI>
<LI><A HREF="#limitGET">Why do I keep getting "access denied" for
form POST requests?</A>
</LI>
@@ -155,11 +162,14 @@
<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="#nph-scripts">How can I get my script's output without
Apache buffering it?</A>
</LI>
<LI><A HREF="#linuxiovec">Why do I get complaints about redefinition
- of `struct iovec' when compiling under Linux?</A>
+ of "<CODE>struct iovec</CODE>" when compiling under Linux?</A>
</LI>
<LI><A HREF="#wheres-the-dump">The errorlog says Apache dumped core,
but where's the dump file?</A>
@@ -181,6 +191,35 @@
<LI><A HREF="#addlog">How do I add browsers and referrers to my
logs?</A>
</LI>
+ <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="#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="#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="#no-info-directives">Why doesn't mod_info list any
+ directives?</A>
+ <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="#authauthoritative">Why does my authentification give
+ me a server error?</A>
+ <LI><A HREF="#auth-on-same-machine">Do I have to keep the (mSQL)
+ authentification information on the same machine?</A>
+ </LI>
+ <LI><A HREF="#msql-slow">Why is my mSQL authentification terribly slow?</A>
+ </LI>
</OL>
</LI>
</UL>
@@ -222,8 +261,8 @@
programmers that httpd didn't behave as they wanted it to behave.
Apache is an entirely volunteer effort, completely funded by its
members, not by commercial sales.
- <HR>
</P>
+ <HR>
</LI>
<LI><A NAME="relate">
<STRONG>How does The Apache Group's work relate to other
@@ -383,7 +422,7 @@
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
- <CODE>/usr/local/etc/httpd/logs/error_log</CODE>, but see the
+ <SAMP>/usr/local/etc/httpd/logs/error_log</SAMP>, but see the
<A
HREF="../mod/core.html#errorlog"
><SAMP>ErrorLog</SAMP></A>
@@ -446,16 +485,12 @@
dump, please include a backtrace (if possible). As an example,
</P>
<P>
- <CODE>
- <DL>
- <DD># cd <EM>ServerRoot</EM>
- </DD>
- <DD># dbx httpd core
- </DD>
- <DD>(dbx) where
- </DD>
- </DL>
- </CODE>
+ <DL>
+ <DD><CODE># cd <EM>ServerRoot</EM><BR>
+ # dbx httpd core<BR>
+ (dbx) where</CODE>
+ </DD>
+ </DL>
</P>
<P>
(Substitute the appropriate locations for your
@@ -524,15 +559,19 @@
</DD>
</DL>
</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.
+ <P>
+ </P>
</LI>
</OL>
<HR>
@@ -544,27 +583,48 @@
<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. The most common cause of this (aside from people not
- outputting the required headers at all) a result of an interaction
- with perl's output buffering. To make perl flush its buffers
- after each output statement, insert the following statements before your
- first <CODE>print</CODE> or <CODE>write</CODE> statement:
+ them.
</P>
<P>
- <CODE>
- <DL>
- <DD>$cfh = select (STDOUT);
- </DD>
- <DD>$| = 1;
- </DD>
- <DD>select ($cfh);
- </DD>
- </DL>
- </CODE>
+ 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.
+ </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>
This is generally only necessary when you are calling external
- programs from your script that send output to stdout.
+ 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 maximise 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
@@ -587,7 +647,13 @@
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 <EM>extremely</EM>
- resource-consumptive, and is not enabled by default.
+ resource-consumptive, 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
@@ -695,7 +761,11 @@
<STRONG>Does or will Apache act as a Proxy server?</STRONG>
</A>
<P>
- Apache version 1.1 and above comes with a proxy module. If compiled
+ 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>
@@ -761,8 +831,9 @@
HREF="../mod/core.html#listen"
><SAMP>Listen</SAMP></A>
directives. If there are no other servers running on the machine
- and all of them are running on the same port, you normally don't
- need any Listen directives at all.
+ 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
@@ -780,7 +851,8 @@
<A
HREF="perf.html"
>performance hints</A>
- page.
+ page. There is a specific note for
+ <a href="#freebsd-setsize">FreeBSD</a> below.
</LI>
<LI>"Don't do that" - try to run with fewer virtual hosts
</LI>
@@ -794,8 +866,32 @@
<P>
Since this is an operating-system limitation, there's not much else
available in the way of solutions.
+ <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 FreeBSD 2.2 and older <SAMP>FD_SETSIZE</SAMP>, which limits the
+ number of open
+ files on the system, is limited to 256. This can restrict the number of
+ virtual hosts you can use; especially if they all use different log
+ files. Increasing this limit (and recompiling Apache) is not enough,
+ as it is on some platforms (such as Solaris), as you also will have
+ to recompile <SAMP>libc</SAMP> with the changed setting.
+ </P>
+ <P>
+ On FreeBSD 3.0 the default is 1024, so the problem is lessened.
+ </P>
+ <HR>
+ </LI>
+
<LI><A NAME="limitGET">
<STRONG>Why do I keep getting "access denied" for form POST
requests?</STRONG>
@@ -807,17 +903,13 @@
would affect the location where the POST-handling script resides:
</P>
<P>
- <CODE>
- <DL>
- <DD><Limit GET>
- </DD>
- <DD> :
- </DD>
- </DL>
- </CODE>
+ <DL>
+ <DD><CODE><Limit GET><BR> :</CODE>
+ </DD>
+ </DL>
</P>
<P>
- Change that to <SAMP><Limit GET POST></SAMP> and the problem
+ Change that to <CODE><Limit GET POST></CODE> and the problem
will probably go away.
</P>
<HR>
@@ -875,12 +967,14 @@
warranty, though, and you'll lose all accumulated UNIX guru points.
</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 "/foo/bar" and not one
- with a method and hostname such as "http://host/foo/bar". See the
+ 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>
@@ -986,7 +1080,7 @@
</P>
<P>
<DL>
- <DD><CODE>BrowserMatch Java/1.0 force-response-1.0</CODE>
+ <DD><CODE>BrowserMatch Java1.0 force-response-1.0</CODE>
</DD>
</DL>
</P>
@@ -1014,7 +1108,7 @@
><CITE>Publishing Pages with PUT</CITE></A>.
</P>
<HR>
- </LI>
+ </LI>
<LI><A NAME="fastcgi">
<STRONG>Why isn't FastCGI included with Apache any more?</STRONG>
</A>
@@ -1045,6 +1139,20 @@
</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 cancelled 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="nph-scripts">
<STRONG>How can I get my script's output without Apache buffering
it?</STRONG>
@@ -1079,25 +1187,25 @@
<P>
As an example how you might handle the former (in a Perl script):
</P>
- <CODE>
- <DL>
- <DD>if ($0 =~ m:/*nph-:) {
- <BR>
-
- $HTTP_headers =
- "HTTP/1.1 200 OK\015\012";
- <BR>
-
- $HTTP_headers .=
- "Connection: close\015\012";
- <BR>
-
- printf ($HTTP_headers);
- <BR>
- };
- </DD>
- </DL>
- </CODE>
+ <P>
+ <DL>
+ <DD><CODE>if ($0 =~ m:^(.*/)*nph-[^/]*$:) {
+ <BR>
+
+ $HTTP_headers =
+ "HTTP/1.1 200 OK\015\012";
+ <BR>
+
+ $HTTP_headers .=
+ "Connection: close\015\012";
+ <BR>
+
+ print $HTTP_headers;
+ <BR>
+ }</CODE>
+ </DD>
+ </DL>
+ </P>
<P>
and then follow with your normal non-<SAMP>nph</SAMP> headers.
</P>
@@ -1105,13 +1213,15 @@
</LI>
<LI><A NAME="linuxiovec">
<STRONG>Why do I get complaints about redefinition
- of `struct iovec' when compiling under Linux?</STRONG>
+ 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>.
@@ -1122,6 +1232,7 @@
This hurts performance and should only be used as a last resort.
</LI>
</UL>
+ </P>
<HR>
</LI>
<LI><A NAME="wheres-the-dump">
@@ -1129,7 +1240,7 @@
file?</STRONG>
</A>
<P>
- In Apache version 1.2 (beginning with 1.2b8), the error log message
+ 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;
@@ -1183,10 +1294,12 @@
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>
This will cause Apache to be very paranoid about making sure a
particular host address is <EM>really</EM> assigned to the name it
@@ -1227,8 +1340,8 @@
><CITE>Apache and Secure Transactions</CITE></A>.
</P>
<HR>
- </LI>
- <LI><A NAME="HPUX-core">
+ </LI>
+ <LI><A NAME="HPUX-core">
<STRONG>Why do I get core dumps under HPUX using HP's ANSI
C compiler?</STRONG>
</A>
@@ -1259,10 +1372,12 @@
<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>
Note that this may break browsers that <EM>do</EM> recognize the
<SAMP>audio/midi</SAMP> MIME type unless they're prepared to also
@@ -1275,7 +1390,7 @@
<LI><A NAME="cantbuild">
<STRONG>Why won't Apache compile with my system's
<SAMP>cc</SAMP>?</STRONG>
- </A>
+ </A>
<P>
If the server won't compile on your system, it is probably due to one
of the following causes:
@@ -1368,29 +1483,280 @@
</P>
<HR>
</LI>
- <LI><A NAME="jdk1.x">
- <STRONG>Why do Java applets and applications not work
- with documents on my Apache server?</A></STRONG>
+ <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>
- The Java Development Kit (JDK) libraries versions 1.0.2 and 1.1 do not
- correctly interpret the "<SAMP>HTTP/1.1</SAMP>" response
- header that Apache 1.2 sends. Instead, if they don't see an exact
- match for "<SAMP>HTTP/1.0</SAMP>", they assume the headers
- are part of the document content.
+ 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>
- This is a known problem, and it has been reported to Sun's JavaSoft
- unit. In the meantime, Apache 1.2 servers can work around this by
- adding the following lines to their configuration files:
+ 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>BrowserMatch Java1.0 force-response-1.0</CODE>
+ <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>
<HR>
- <!-- Don't forget to add HR tags at the end of each list item.. -->
</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="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 explaination 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/etc/httpd/conf/htpasswd.users
+ <BR>
+ AuthName special directory
+ <BR>
+ require valid-user
+ <BR>
+ satisfy any</CODE>
+ </DD>
+ </DL>
+ </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="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 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="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.linuxhq.com/HOWTO/Kernel-HOWTO.html"
+ >Kernel HOWTO</A>,
+ or the documentation provided with your distribution, or a
+ <A HREF="http://www.linuxhq.com/HOWTO/META-FAQ.html"
+ >Linux newsgroup/mailing list</A>.
+ As a last-resort workaround, you can
+ comment out the <CODE>#define HAVE_SHMGET</CODE> definition in the
+ <SAMP>LINUX</SAMP> section of
+ <SAMP>src/conf.h</SAMP> and rebuild the server. This will produce
+ a server which is slower and less reliable.
+ </P>
+ <HR>
+ </LI>
+ <LI><A NAME="authauthoritative">
+ <STRONG>Why does my authentification 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 "authentification
+ 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 authentification 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) authentification information
+ on the same machine?</STRONG>
+ </A>
+ <P>
+ Some organizations feel very strongly about keeping the authentification
+ 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 authentification terribly slow?</STRONG>
+ </A>
+ <P>
+ You have probably configured the Host by specificing a FQHN,
+ and thus the libmsql 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>
+
+ <!-- Don't forget to add HR tags at the end of each list item.. -->
+
</OL>
<!--#include virtual="footer.html" -->
</BODY>
diff --git a/docs/manual/misc/compat_notes.html b/docs/manual/misc/compat_notes.html
index 56e20bb..23adf53 100644
--- a/docs/manual/misc/compat_notes.html
+++ b/docs/manual/misc/compat_notes.html
@@ -33,18 +33,7 @@
<LI>The basic mod_auth <CODE>AuthGroupFile</CODE>-specified group file
format allows commas between user names - Apache does not.<BR>
<I>- added 12/1/96</I>
-
-<LI><CODE>AddType</CODE> only accepts one file extension per line, without
-any dots (<code>.</code>) in the extension, and does not take full filenames.
-If you need multiple extensions per type, use multiple lines, e.g.
-<blockquote><code>
-AddType application/foo foo<br>
-AddType application/foo bar
-</code></blockquote>
-To map <code>.foo</code> and <code>.bar</code> to <code>application/foo</code>
-<p>
-
-
+ <p>
<LI><P>If you follow the NCSA guidelines for setting up access restrictions
based on client domain, you may well have added entries for,
@@ -111,6 +100,9 @@
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>.
</OL>
diff --git a/docs/manual/misc/descriptors.html b/docs/manual/misc/descriptors.html
new file mode 100644
index 0000000..e5c97f3
--- /dev/null
+++ b/docs/manual/misc/descriptors.html
@@ -0,0 +1,155 @@
+<!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 <i>descriptor</i>, also commonly called a <i>file handle</i> 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 (i.e. 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 <i>FD_SETSIZE</i>). Or you
+may be stuck with a (relatively) low amount. The second limit is called
+the <i>hard resource</i> 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 <i>soft
+resource</i> 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>To summarize:
+
+<center><pre>
+ #open files <= soft limit <= hard limit <= kernel limit
+</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>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> <b>BSDI 2.0</b>
+ <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> <b>FreeBSD 2.2, BSDI 2.1+</b>
+ <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> <b>Linux</b>
+ <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> <b>Solaris through 2.5.1</b>
+ <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> <b>AIX version ??</b>
+ <dd> AIX appears to have a hard limit of 128 descriptors. End of
+ story.
+ <p>
+
+ <dt> <b>Others</b>
+ <dd> If you have details on another operating system, please submit
+ it through our <a href="http://www.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 <i>low
+slack line</i>.
+
+<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://www.apache.org/bug_report.html">Bug
+Report Page</a> so that
+we can investigate.
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
diff --git a/docs/manual/misc/fin_wait_2.html b/docs/manual/misc/fin_wait_2.html
index 48e1087..4b9d60a 100644
--- a/docs/manual/misc/fin_wait_2.html
+++ b/docs/manual/misc/fin_wait_2.html
@@ -57,13 +57,13 @@
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
+ <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.
+ <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
@@ -77,16 +77,16 @@
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
+ <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)
+ <LI>Mozilla/3.01 (Win95; I)
</UL>
<P>
@@ -155,56 +155,56 @@
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.sco.com/">SCO TCP/IP Release 1.2.1</A>
- can be modified to have a timeout by following
- <A HREF="http://www.sco.com/cgi-bin/waisgate?WAISdocID=2242622956+0+0+0&WAISaction=retrieve"> SCO's instructions</A>.
- <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">Squent's ptx/TCP/IP for
- DYNIX/ptx</A> has had a FIN_WAIT_2 timeout since around
- release 4.1 in mid-1994.
+ <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.sco.com/">SCO TCP/IP Release 1.2.1</A>
+ can be modified to have a timeout by following
+ <A HREF="http://www.sco.com/cgi-bin/waisgate?WAISdocID=2242622956+0+0+0&WAISaction=retrieve"> SCO's instructions</A>.
+ <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">Squent'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.
+ <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
@@ -266,6 +266,12 @@
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
diff --git a/docs/manual/misc/index.html b/docs/manual/misc/index.html
index 127b1f2..2b44c66 100644
--- a/docs/manual/misc/index.html
+++ b/docs/manual/misc/index.html
@@ -21,92 +21,92 @@
</P>
<DL>
<DT><A
- HREF="API.html"
+ HREF="API.html"
>API</A>
</DT>
<DD>Description of Apache's Application Programming Interface.
</DD>
<DT><A
- HREF="FAQ.html"
+ HREF="FAQ.html"
>FAQ</A>
</DT>
<DD>Frequently-Asked Questions concerning the Apache project and server
</DD>
<DT><A
- HREF="client_block_api.html"
+ 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"
+ HREF="compat_notes.html"
>Compatibility with NCSA</A>
</DT>
<DD>Notes about Apache's compatibility with the NCSA server
</DD>
<DT><A
- HREF="fin_wait_2.html"
+ 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"
+ HREF="howto.html"
>"How-To"</A>
</DT>
<DD>Instructions about how to accomplish some commonly-desired server
functionality changes
</DD>
<DT><A
- HREF="known_bugs.html"
+ HREF="known_bugs.html"
>Known Bugs</A>
</DT>
<DD>Just what it says - a list of known bugs in each of the Apache releases
</DD>
<DT><A
- HREF="nopgp.html"
+ 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"
+ 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"
+ 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.html"
+ HREF="perf.html"
>Performance Notes (General)</A>
</DT>
<DD>Some generic notes about how to improve Apache performance
</DD>
<DT><A
- HREF="security_tips.html"
+ 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"
+ 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"
+ HREF="windoz_keepalive.html"
>Windows Bug with Web Keepalive</A>
</DT>
<DD>A brief description of a known problem with Microsoft Windows and
diff --git a/docs/manual/misc/security_tips.html b/docs/manual/misc/security_tips.html
index cba41ad..21b5177 100644
--- a/docs/manual/misc/security_tips.html
+++ b/docs/manual/misc/security_tips.html
@@ -170,7 +170,6 @@
>UserDir</A>
directive; setting it to something like <SAMP>"./"</SAMP>
would have the same effect, for root, as the first example above.
-</P>
<HR>
<P>Please send any other useful security tips to The Apache Group
diff --git a/docs/manual/mod/core.html b/docs/manual/mod/core.html
index fde6c35..186a315 100644
--- a/docs/manual/mod/core.html
+++ b/docs/manual/mod/core.html
@@ -44,6 +44,7 @@
<li><A HREF="#limit"><Limit></A>
<li><A HREF="#listen">Listen</A>
<li><A HREF="#location"><Location></A>
+<li><A HREF="#lockfile">LockFile</A>
<li><A HREF="#maxclients">MaxClients</A>
<li><A HREF="#maxkeepaliverequests">MaxKeepAliveRequests</a>
<li><A HREF="#maxrequestsperchild">MaxRequestsPerChild</A>
@@ -714,7 +715,7 @@
<Location ~ "/(extra|special)/data">
</pre>
-would match URLs that contained the substring "/extra/data" or
+<p>would match URLs that contained the substring "/extra/data" or
"/special/data".</p>
<p>The <code>Location</code> functionality is especially useful when
@@ -732,7 +733,23 @@
</pre>
<hr>
-<A name="maxclients"><h2>MaxClients directive</h2></A>
+<A NAME="lockfile"><H2>LockFile</H2></A>
+<strong>Syntax:</strong> LockFile <em>filename</em><BR>
+<strong>Default:</strong> <code>LockFile logs/accept.lock</code><BR>
+<strong>Context:</strong> server config<BR>
+<strong>Status:</strong> core<P>
+
+The LockFile directive sets the path to the lockfile used when
+Apache is compiled with either USE_FCNTL_SERIALIZED_ACCEPT or
+USE_FLOCK_SERIALIZED_ACCEPT. This directive should normally be
+left at its default value. The main reason for changing it is if
+the <code>logs</code> directory is NFS mounted, since the lockfile
+should be stored on a local disk if possible. The PID of the main
+server process is automatically appended to the filename.
+
+<P><HR>
+
+<A name="maxclients"><h2>MaxClients</h2></A>
<!--%plaintext <?INDEX {\tt MaxClients} directive> -->
<strong>Syntax:</strong> MaxClients <em>number</em><br>
<strong>Default:</strong> <code>MaxClients 256</code><br>
@@ -836,6 +853,9 @@
<dd>
<!--%plaintext <?INDEX {\tt FollowSymLinks} option> -->
The server will follow symbolic links in this directory.
+<b>Note</b>: even though the server follows the symlink it does <i>not</i>
+change the pathname used to match against <code><Directory></code>
+sections.
<dt>Includes
<dd>
<!--%plaintext <?INDEX {\tt Includes} option> -->
@@ -1031,7 +1051,7 @@
See also <A HREF="#accessconfig">AccessConfig</A>.<p><hr>
-<A name="rlimit">
+<A name="rlimit"> </A>
<A name="rlimitcpu"><h2>RLimitCPU directive</h2></A>
<!--%plaintext <?INDEX {\tt RLimitCPU} directive> -->
<strong>Syntax:</strong> RLimitCPU <em># or 'max'</em> <em>[# or 'max']</em><br>
@@ -1158,7 +1178,7 @@
<A name="sendbuffersize"><h2>SendBufferSize directive</h2></A>
<!--%plaintext <?INDEX {\tt SendBufferSize} directive> -->
<strong>Syntax:</strong> SendBufferSize <em>bytes</em><br>
-<strong>Context:</strong> server config, virtual host<br>
+<strong>Context:</strong> server config<br>
<strong>Status:</strong> core<p>
The server will set the TCP buffer size to the number of bytes
diff --git a/docs/manual/mod/directives.html b/docs/manual/mod/directives.html
index 2359909..b2645a4 100644
--- a/docs/manual/mod/directives.html
+++ b/docs/manual/mod/directives.html
@@ -106,6 +106,7 @@
<li><A HREF="mod_dld.html#loadfile">LoadFile</A>
<li><A HREF="mod_dld.html#loadmodule">LoadModule</A>
<li><A HREF="core.html#location"><Location></A>
+<li><A HREF="core.html#lockfile">LockFile</A>
<li><A HREF="mod_log_config.html#logformat">LogFormat</A>
<li><A HREF="core.html#maxclients">MaxClients</A>
<li><A HREF="core.html#maxkeepaliverequests">MaxKeepAliveRequests</A>
diff --git a/docs/manual/mod/mod_auth_anon.html b/docs/manual/mod/mod_auth_anon.html
index c880c34..c1b6933 100644
--- a/docs/manual/mod/mod_auth_anon.html
+++ b/docs/manual/mod/mod_auth_anon.html
@@ -61,23 +61,23 @@
<strong>Status:</strong> Extension<br>
<strong>Module:</strong> mod_auth_anon<p>
- A list of one or more 'magic' userIDs which are allowed access
- without password verification. The userIDs are space separated.
- It is possible to use the ' and " quotes to allow a space in
- a userID as well as the \ escape character.
- <p>
- Please note that the comparison is <b>case-IN-sensitive</b>.
- <br>
- I strongly suggest that the magic username '<code>anonymous</code>'
- is always one of the allowed userIDs.
- <p>
- Example:<br>
- <code>
- Anonymous: anonymous "Not Registered" 'I don\'t know'
- </code><p>
- This would allow the user to enter without password verification
- by using the userId's 'anonymous', 'AnonyMous','Not Registered' and
- 'I Don't Know'.
+ A list of one or more 'magic' userIDs which are allowed access
+ without password verification. The userIDs are space separated.
+ It is possible to use the ' and " quotes to allow a space in
+ a userID as well as the \ escape character.
+ <p>
+ Please note that the comparison is <b>case-IN-sensitive</b>.
+ <br>
+ I strongly suggest that the magic username '<code>anonymous</code>'
+ is always one of the allowed userIDs.
+ <p>
+ Example:<br>
+ <code>
+ Anonymous: anonymous "Not Registered" 'I don\'t know'
+ </code><p>
+ This would allow the user to enter without password verification
+ by using the userId's 'anonymous', 'AnonyMous','Not Registered' and
+ 'I Don't Know'.
<HR>
<A name="Authoritative"><h2>Anonymous_Authoritative</h2></A>
@@ -91,12 +91,12 @@
When set 'on', there is no
fall-through to other authorization methods. So if a
userID does not match the values specified in the
- <code>Anonymous</code> directive, access is denied.
- <p>
- Be sure you know what you are doing when you decide to switch
- it on. And remember that it is the linking order of the modules
- (in the Configuration / Make file) which details the order
- in which the Authorization modules are queried.
+ <code>Anonymous</code> directive, access is denied.
+ <p>
+ Be sure you know what you are doing when you decide to switch
+ it on. And remember that it is the linking order of the modules
+ (in the Configuration / Make file) which details the order
+ in which the Authorization modules are queried.
<hr>
<A name="LogEmail"><h2>Anonymous_LogEmail</h2></A>
@@ -107,8 +107,8 @@
<strong>Status:</strong> Extension<br>
<strong>Module:</strong> mod_auth_anon<p>
- When set 'on', the default, the 'password' entered (which hopefully
- contains a sensible email address) is logged in the httpd-log file.
+ When set 'on', the default, the 'password' entered (which hopefully
+ contains a sensible email address) is logged in the httpd-log file.
<hr>
<A name="MustGiveEmail"><h2>Anonymous_MustGiveEmail</h2></a>
@@ -120,8 +120,8 @@
<strong>Status:</strong> Extension<br>
<strong>Module:</strong> mod_auth_anon<p>
- Specifies whether the user must specify an email
- address as the password. This prohibits blank passwords.
+ Specifies whether the user must specify an email
+ address as the password. This prohibits blank passwords.
<HR>
<A name="NoUserID"><h2>Anonymous_NoUserID</h2></A>
@@ -132,11 +132,11 @@
<strong>Status:</strong> Extension<br>
<strong>Module:</strong> mod_auth_anon<p>
- When set 'on', users can leave
- the userID (and perhaps the password field) empty. This
- can be very convenient for MS-Explorer users who can
- just hit return or click directly on the OK button; which
- seems a natural reaction.
+ When set 'on', users can leave
+ the userID (and perhaps the password field) empty. This
+ can be very convenient for MS-Explorer users who can
+ just hit return or click directly on the OK button; which
+ seems a natural reaction.
<hr>
@@ -148,9 +148,9 @@
<strong>Status:</strong> Extension<br>
<strong>Module:</strong> mod_auth_anon<p>
- When set 'on' the 'password' entered is
- checked for at least one '@' and a '.' to encourage users to enter
- valid email addresses (see the above <code>Auth_LogEmail</code>).
+ When set 'on' the 'password' entered is
+ checked for at least one '@' and a '.' to encourage users to enter
+ valid email addresses (see the above <code>Auth_LogEmail</code>).
<hr><a name="Example"><h2>Example</h2></a>
@@ -180,10 +180,10 @@
<dl>
<dt><code>
Anonymous anonymous guest www test welcome<p>
-Anonymous_MustGiveEmail on<br>
+Anonymous_MustGiveEmail on<br>
Anonymous_VerifyEmail on<br>
-Anonymous_NoUserId off<br>
-Anonymous_LogEmail on<br>
+Anonymous_NoUserId off<br>
+Anonymous_LogEmail on<br>
<p>
AuthName Use 'anonymous' & Email address for guest entry<br>
AuthType basic<p>
@@ -217,8 +217,8 @@
</dd>
<dt>Version 0.5<br></dt>
<dd>Added 'VerifyEmail' and 'LogEmail' options. Multiple
- 'anonymous' tokens allowed. more docs. Added Authoritative
- functionality.
+ 'anonymous' tokens allowed. more docs. Added Authoritative
+ functionality.
</dd>
</dl>
diff --git a/docs/manual/mod/mod_include.html b/docs/manual/mod/mod_include.html
index 6f51130..f157647 100644
--- a/docs/manual/mod/mod_include.html
+++ b/docs/manual/mod/mod_include.html
@@ -309,15 +309,15 @@
Unix egrep command.
<DT>( <I>test_condition</I> )
- <DD>true if <I>test_condition</I> is true
+ <DD>true if <I>test_condition</I> is true
<DT>! <I>test_condition</I>
- <DD>true if <I>test_condition</I> is false
+ <DD>true if <I>test_condition</I> is false
<DT><I>test_condition1</I> && <I>test_condition2</I>
- <DD>true if both <I>test_condition1</I> and
- <I>test_condition2</I> are true
+ <DD>true if both <I>test_condition1</I> and
+ <I>test_condition2</I> are true
<DT><I>test_condition1</I> || <I>test_condition2</I>
- <DD>true if either <I>test_condition1</I> or
- <I>test_condition2</I> is true
+ <DD>true if either <I>test_condition1</I> or
+ <I>test_condition2</I> is true
</DL>
<P> "<I>=</I>" and "<I>!=</I>" bind more tightly than "<I>&&</I>" and
diff --git a/docs/manual/mod/mod_mime.html b/docs/manual/mod/mod_mime.html
index fa150c8..fd3e6b0 100644
--- a/docs/manual/mod/mod_mime.html
+++ b/docs/manual/mod/mod_mime.html
@@ -20,22 +20,44 @@
from the filename.
<h2>Summary</h2>
-This module is used to determine the mime types of documents. Some mime
-types indicate special processing to be performed by the server, otherwise
-the type is returned to the client so that the browser can deal with
-the document appropriately.<p>
-The filename of a document is treated as being composed of a basename followed
-by some extensions, in the following order:
-<blockquote><em>base.type.language.enc</em></blockquote>
-The <em>type</em> extension sets the type of the document; types are defined
-in the <A HREF="#typesconfig">TypesConfig</A> file and by the
-<A HREF="#addtype">AddType</A> directive. The <em>language</em> extension
-sets the language of the document, as defined by the
-<A HREF="#addlanguage">AddLanguage</A> directive. Finally, the
-<em>enc</em> directive sets the encoding of the document, as defined by
-the <A HREF="#addencoding">AddEncoding</A> directive.
+This module is used to determine various bits of "meta information"
+about documents. This information relates to the content of the
+document and is returned to the browser or used in content-negotiation
+within the server. In addition, a "handler" can be set for a document,
+which determines how the document will be processed within the server.
+<P>
+
+The directives <A HREF="#addencoding">AddEncoding</A>, <A
+HREF="#addhandler">AddHandler</A>, <A
+HREF="#addlanguage">AddLanguage</A> and <A HREF="#addtype">AddType</A>
+are all used to map file extensions onto the meta-information for that
+file. Respectively they set the content-encoding, handler,
+content-language and mime-type (content-type) of documents. The
+directive <A HREF="#typesconfig">TypesConfig</A> is used to specify a
+file which also maps extensions onto mime types. The directives <A
+HREF="#forcetype">ForceType</A> and <A
+HREF="#sethandler">SetHandler</A> are used to associated all the files
+in a given location (e.g. a particular directory) onto a particular
+mime type or handler.
+
+<P>
+
+Files can have more than one extension, and the order of the
+extensions is normally irrelevant. For example, if the file
+<CODE>welcome.html.fr</CODE> maps onto content type text/html and
+language French then the file <CODE>welcome.fr.html</CODE> will map
+onto exactly the same information. The only exception to this is if an
+extension is given which Apache does not know how to handle. In this
+case it will "forget" about any information it obtained from
+extensions to the left of the unknown extension. So, for example, if
+the extensions fr and html are mapped to the appropriate language and
+type but extension xxx is not assigned to anything, then the file
+<CODE>welcome.fr.xxx.html</CODE> will be associated with content-type
+text/html but <i>no</i> language.
+
+<P>
<h2> Directives</h2>
<ul>
@@ -72,14 +94,14 @@
<h2><a name="addhandler">AddHandler</a></h2>
-<strong>Syntax:</strong> <AddHandler <em>handler-name extension</em>><br>
+<strong>Syntax:</strong> AddHandler <em>handler-name extension extension...</em><br>
<strong>Context:</strong> server config, virtual host, directory, .htaccess<br>
<strong>Status:</strong> Base<br>
<strong>Module:</strong> mod_mime<br>
<strong>Compatibility:</strong> AddHandler is only available in Apache
1.1 and later<p>
-<p>AddHandler maps the filename extension <em>extension</em> to the
+<p>AddHandler maps the filename extensions <em>extension</em> to the
<a href="../handler.html">handler</a>
<em>handler-name</em>. For example, to activate CGI scripts
with the file extension "<code>.cgi</code>", you might use:
@@ -138,7 +160,7 @@
<h2><a name="forcetype">ForceType</a></h2>
-<strong>Syntax:</strong> <ForceType <em>media type</em>><br>
+<strong>Syntax:</strong> ForceType <em>media type</em><br>
<strong>Context:</strong> directory, .htaccess<br>
<strong>Status:</strong> Base<br>
<strong>Module:</strong> mod_mime<br>
@@ -159,7 +181,7 @@
<h2><a name="sethandler">SetHandler</a></h2>
-<strong>Syntax:</strong> <SetHandler <em>handler-name</em>><br>
+<strong>Syntax:</strong> SetHandler <em>handler-name</em><br>
<strong>Context:</strong> directory, .htaccess<br>
<strong>Status:</strong> Base<br>
<strong>Module:</strong> mod_mime<br>
diff --git a/docs/manual/mod/mod_proxy.html b/docs/manual/mod/mod_proxy.html
index e0aef68..30926d4 100644
--- a/docs/manual/mod/mod_proxy.html
+++ b/docs/manual/mod/mod_proxy.html
@@ -297,7 +297,7 @@
<li><a href="#shortname">Using Netscape hostname shortcuts</a>
<li><a href="#mimetypes">Why doesn't file type <i>xxx</i> download via FTP?</a>
<li><a href="#startup">Why does Apache start more slowly when using the
- proxy module?</a>
+ proxy module?</a>
<li><a href="#socks">Can I use the Apache proxy module with my SOCKS proxy?</a>
</ul>
@@ -337,7 +337,7 @@
</pre>
<h2><a name="startup">Why does Apache start more slowly when using the
- proxy module?</a></h2>
+ proxy module?</a></h2>
If you're using the <code>ProxyBlock</code> or <code>NoCache</code>
directives, hostnames' IP addresses are looked up and cached during
diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html
index 03eaa58..4cb6c83 100644
--- a/docs/manual/mod/mod_rewrite.html
+++ b/docs/manual/mod/mod_rewrite.html
@@ -44,7 +44,6 @@
It operates on the full URLs (including the PATH_INFO part) both in
per-server context (httpd.conf) and per-dir context (.htaccess) and even
can generate QUERY_STRING parts on result. The rewritten result can lead to internal sub-processing, external request redirection or to internal proxy throughput.
-</b>
<p>
The latest version can be found on<br>
@@ -147,7 +146,7 @@
config.
<p>
-<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
+<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
To disable the logging of rewriting actions it is not recommended
to set <em>Filename</em>
@@ -161,7 +160,7 @@
</table>
<p>
-<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
+<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
SECURITY: See the <a
href="../misc/security_tips.html">Apache Security
@@ -198,7 +197,7 @@
This disables all rewrite action logs.
<p>
-<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
+<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
<b>Notice:</b> Using a high value for <i>Level</i> will slow down your Apache
server dramatically! Use the rewriting logfile only for debugging or at least
@@ -289,7 +288,7 @@
<li><b>DBM Hashfile Format</b>
<p>
This is a binary NDBM format file containing the
- same contents as the <em>Plain Text Format</b> files. You can create
+ same contents as the <em>Plain Text Format</em> files. You can create
such a file with any NDBM tool or with the <tt>dbmmanage</tt> program
from the <tt>support</tt> directory of the Apache distribution.
<p>
@@ -346,7 +345,7 @@
context.
<p>
-<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
+<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
For plain text and DBM format files the looked-up keys are cached in-core
until the <tt>mtime</tt> of the mapfile changes or the server does a
@@ -384,7 +383,7 @@
directive to specify the correct URL-prefix.
<p>
-<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
+<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
So, if your webserver's URLs are <b>not</b> directly
related to physical file paths, you have to use <tt>RewriteBase</tt> in every
@@ -424,7 +423,7 @@
rewritten to the physical file <tt>/abc/def/newstuff.html</tt>.
<p>
-<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
+<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
<font size=-1>
<b>For the Apache hackers:</b><br>
@@ -437,10 +436,10 @@
/xyz/oldstuff.html
Internal Processing:
- /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias)
- /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule)
- /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase)
- /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias)
+ /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias)
+ /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule)
+ /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase)
+ /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias)
Result:
/abc/def/newstuff.html
@@ -471,7 +470,7 @@
<p>
The <tt>RewriteCond</tt> directive defines a rule condition. Precede a
-<tt>RewriteRule</tt> directive with one or more <t>RewriteCond</tt>
+<tt>RewriteRule</tt> directive with one or more <tt>RewriteCond</tt>
directives.
The following rewriting rule is only used if its pattern matches the current
@@ -562,7 +561,7 @@
<p>
-<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
+<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
These variables all correspond to the similar named HTTP MIME-headers, C
variables of the Apache server or <tt>struct tm</tt> fields of the Unix
@@ -770,7 +769,7 @@
last default rule.
<p>
-<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
+<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
<b>Notice!</b> When using the NOT character to negate a pattern you cannot
have grouped wildcard parts in the pattern. This is impossible because when
@@ -814,7 +813,7 @@
pattern to be applied before a substitution occurs.
<p>
-<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
+<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
<b>Notice</b>: There is a special feature. When you prefix a substitution
field with <tt>http://</tt><em>thishost</em>[<em>:thisport</em>] then
@@ -962,7 +961,7 @@
typical example is the use of <tt>mod_alias</tt> and
<tt>mod_rewrite</tt>..
<p>
-<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
+<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
<font size=-1>
<b>For the Apache hackers:</b><br>
@@ -988,14 +987,14 @@
which will be expanded. You can use this flag more than once to set more
than one variable. The variables can be later dereferenced at a lot of
situations, but the usual location will be from within XSSI (via
- <tt><!--#echo var="VAR"--></tt>) or CGI (e.g. <tt>$ENV{'VAR'}</tt>).
- But additionally you can also dereference it in a following RewriteCond
- pattern via <tt>%{ENV:VAR}</tt>. Use this to strip but remember
- information from URLs.
+ <tt><!--#echo var="VAR"--></tt>) or CGI (e.g. <tt>$ENV{'VAR'}</tt>).
+ But additionally you can also dereference it in a following RewriteCond
+ pattern via <tt>%{ENV:VAR}</tt>. Use this to strip but remember
+ information from URLs.
</ul>
<p>
-<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
+<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
Remember: Never forget that <em>Pattern</em> gets applied to a complete URL
in per-server configuration files. <b>But in per-directory configuration
@@ -1012,7 +1011,7 @@
</table>
<p>
-<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
+<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
Notice! To enable the rewriting engine for per-directory configuration files
you need to set ``<tt>RewriteEngine On</tt>'' in these files <b>and</b>
@@ -1120,10 +1119,6 @@
</table>
-</td>
-</tr>
-</table>
-
<p>
<b>Example:</b>
<p>
diff --git a/docs/manual/mod/mod_status.html b/docs/manual/mod/mod_status.html
index f5a55fa..f671ad7 100644
--- a/docs/manual/mod/mod_status.html
+++ b/docs/manual/mod/mod_status.html
@@ -90,7 +90,7 @@
Do this by adding the following to the AUX_CFLAGS line in the
"Configuration" file and then recompiling as usual.
<pre>
- AUX_CFLAGS= (something) -DSTATUS
+ AUX_CFLAGS= (something) -DSTATUS
</pre>
<BLOCKQUOTE>
diff --git a/docs/manual/mod/mod_userdir.html b/docs/manual/mod/mod_userdir.html
index cca87f5..790c752 100644
--- a/docs/manual/mod/mod_userdir.html
+++ b/docs/manual/mod/mod_userdir.html
@@ -42,15 +42,15 @@
patterns. If not disabled, then a request for
<code>http://www.foo.com/~bob/one/two.html</code> will be translated to:
<pre>
-UserDir public_html -> ~bob/public_html/one/two.html
-UserDir /usr/web -> /usr/web/bob/one/two.html
-UserDir /home/*/www -> /home/bob/www/one/two.html
+UserDir public_html -> ~bob/public_html/one/two.html
+UserDir /usr/web -> /usr/web/bob/one/two.html
+UserDir /home/*/www -> /home/bob/www/one/two.html
</pre>
The following directives will send redirects to the client:
<pre>
-UserDir http://www.foo.com/users -> http//www.foo.com/users/bob/one/two.html
-UserDir http://www.foo.com/*/usr -> http://www.foo.com/bob/usr/one/two.html
-UserDir http://www.foo.com/~*/ -> http://www.foo.com/~bob/one/two.html
+UserDir http://www.foo.com/users -> http//www.foo.com/users/bob/one/two.html
+UserDir http://www.foo.com/*/usr -> http://www.foo.com/bob/usr/one/two.html
+UserDir http://www.foo.com/~*/ -> http://www.foo.com/~bob/one/two.html
</pre>
<P>
diff --git a/docs/manual/platform/perf-bsd44.html b/docs/manual/platform/perf-bsd44.html
deleted file mode 100644
index 0a1661b..0000000
--- a/docs/manual/platform/perf-bsd44.html
+++ /dev/null
@@ -1,236 +0,0 @@
-<!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 <b>first limit hit</b>. 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>
- /*
- * 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">
-<b>Addendum for <i>very</i> heavily loaded BSD servers</b><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, etc.
-
-<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>
-maxusers 256
-</pre>
-
-Maxusers drives a <i>lot</i> of other kernel parameters:
-
-<ul>
-
-<li> Maximum # of processes
-
-<li> Maximum # of processes per user
-
-<li> System wide open files limit
-
-<li> Per-process open files limit
-
-<li> Maximum # of mbuf clusters
-
-<li> Proc/pgrp hash table size
-
-</ul>
-
-The actual formulae for these derived parameters are in
-<i>/usr/src/sys/conf/param.c</i>.
-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.
-options SOMAXCONN=256 # max pending connects
-options NMBCLUSTERS=4096 # mbuf clusters at 4096
-
-#
-# Misc. options
-#
-options CHILD_MAX=512 # maximum number of child processes
-options OPEN_MAX=512 # maximum fds (breaks RPC svcs)
-</pre>
-
-SOMAXCONN is not derived from maxusers, so you'll always need to increase
-that yourself. We used a value guaranteed to be larger than Apache's
-default for the listen() of 128, currently.
-
-<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>
-/*
- * Mbufs are of a single size, MSIZE (machine/machparam.h), which
- * includes overhead. An mbuf may add a single "mbuf cluster" of size
- * MCLBYTES (also in machine/machparam.h), which has no additional overhead
- * and is used instead of the internal data area; this is done when
- * at least MINCLSIZE of data must be stored.
- */
-</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>
-
-<b>Caveats</b>
-
-<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. <b>ALWAYS</b>
-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>
-
-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 <b>HARD_SERVER_LIMIT</b> in <i>httpd.h</i> 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, i.e., 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 <i>Tony Sanders</i> and <i>Chris Torek</i> 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-ponter -O2</code><BR>
-helped reduce the number of "unable" errors, because the CPU was
-often maxed out.</blockquote>
-<P>
-
-<HR>
-
-<H3>More welcome!</H3>
-
-If you have tips to contribute, send mail to <a
-href="mailto:brian@organic.com">brian@organic.com</a>
-
-<!--#include virtual="footer.html" -->
-</body></html>
-
diff --git a/docs/manual/platform/perf-dec.html b/docs/manual/platform/perf-dec.html
deleted file mode 100644
index 7cc8bb1..0000000
--- a/docs/manual/platform/perf-dec.html
+++ /dev/null
@@ -1,279 +0,0 @@
-<!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>
- 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>
-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>
-Message-ID <A HREF="news:4oirch$bc8@usenet.pa.dec.com"><4oirch$bc8@usenet.pa.dec.com></A>
-Subject Re: Web Site Performance
-References 1
-
-
-
-In article <skoogDs54BH.9pF@netcom.com> skoog@netcom.com (Jim Skoog) writes:
->Where are the performance bottlenecks for Alpha AXP running the
->Netscape Commerce Server 1.12 with high volume internet traffic?
->We are evaluating network performance for a variety of Alpha AXP
->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
-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.
-
-How much larger? Well, no larger than 32767 (decimal). And
-probably no less than about 2048, if you have a really high volume
-(millions of hits per day), like AltaVista does.
-
-This change allows the system to maintain more than 8 TCP
-connections in the SYN_RCVD state for the HTTP server. (You
-can use "netstat -An |grep SYN_RCVD" to see how many such
-connections exist at any given instant).
-
-If you don't make this change, you might find that as the load gets
-high, some connection attempts take a very long time. And if a lot
-of your clients disconnect from the Internet during the process of
-TCP connection establishment (this happens a lot with dialup
-users), these "embryonic" connections might tie up your somaxconn
-quota of SYN_RCVD-state connections. Until the kernel times out
-these embryonic connections, no other connections will be accepted,
-and it will appear as if the server has died.
-
-The default value for somaxconn in Digital UNIX V4.0 will be quite
-a bit larger than it has been in previous versions (we inherited
-this default from 4.3BSD).
-
-Digital UNIX V4.0 includes some other performance-related changes
-that significantly improve its maximum HTTP connection rate. However,
-we've been using V3.2C systems to front-end for altavista.digital.com
-with no obvious performance bottlenecks at the millions-of-hits-per-day
-level.
-
-We have some Webstone performance results available at
- <A HREF="http://www.digital.com/info/alphaserver/news/webff.html">http://www.digital.com/info/alphaserver/news/webff.html</A>
-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
-version of V4.0.
-
--Jeff
-
-<HR>
-
-----------------------------------------------------------------------------
-
-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>
-Message-ID <A HREF="news:4onmmd$mmd@usenet.pa.dec.com"><4onmmd$mmd@usenet.pa.dec.com></A>
-Subject Digital UNIX V3.2C Internet tuning patch info
-
-----------------------------------------------------------------------------
-
-Something that probably few people are aware of is that Digital
-has a patch kit available for Digital UNIX V3.2C that may improve
-Internet performance, especially for busy web servers.
-
-This patch kit is one way to increase the value of somaxconn,
-which I discussed in a message here a day or two ago.
-
-I've included in this message the revised README file for this
-patch kit below. Note that the original README file in the patch
-kit itself may be an earlier version; I'm told that the version
-below is the right one.
-
-Sorry, this patch kit is NOT available for other versions of Digital
-UNIX. Most (but not quite all) of these changes also made it into V4.0,
-so the description of the various tuning parameters in this README
-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>
-so I guess you'll have to call Digital's Customer Support to get it.
-
--Jeff
-
-DESCRIPTION: Digital UNIX Network tuning patch
-
- Patch ID: OSF350-146
-
- SUPERSEDED PATCHES: OSF350-151, OSF350-158
-
- This set of files improves the performance of the network
- subsystem on a system being used as a web server. There are
- additional tunable parameters included here, to be used
- cautiously by an informed system administrator.
-
-TUNING
-
- To tune the web server, the number of simultaneous socket
- connection requests are limited by:
-
- somaxconn Sets the maximum number of pending requests
- allowed to wait on a listening socket. The
- default value in Digital UNIX V3.2 is 8.
- This patch kit increases the default to 1024,
- which matches the value in Digital UNIX V4.0.
-
- sominconn Sets the minimum number of pending connections
- allowed on a listening socket. When a user
- process calls listen with a backlog less
- than sominconn, the backlog will be set to
- sominconn. sominconn overrides somaxconn.
- The default value is 1.
-
- The effectiveness of tuning these parameters can be monitored by
- the sobacklog variables available in the kernel:
-
- sobacklog_hiwat Tracks the maximum pending requests to any
- socket. The initial value is 0.
-
- sobacklog_drops Tracks the number of drops exceeding the
- socket set backlog limit. The initial
- value is 0.
-
- somaxconn_drops Tracks the number of drops exceeding the
- somaxconn limit. When sominconn is larger
- than somaxconn, tracks the number of drops
- exceeding sominconn. The initial value is 0.
-
- TCP timer parameters also affect performance. Tuning the following
- require some knowledge of the characteristics of the network.
-
- tcp_msl Sets the tcp maximum segment lifetime.
- This is the maximum lifetime in half
- seconds that a packet can be in transit
- on the network. This value, when doubled,
- is the length of time a connection remains
- in the TIME_WAIT state after a incoming
- close request is processed. The unit is
- specified in 1/2 seconds, the initial
- value is 60.
-
- tcp_rexmit_interval_min
- Sets the minimum TCP retransmit interval.
- For some WAN networks the default value may
- be too short, causing unnecessary duplicate
- packets to be sent. The unit is specified
- in 1/2 seconds, the initial value is 1.
-
- tcp_keepinit This is the amount of time a partially
- established connection will sit on the listen
- queue before timing out (e.g. 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
- fill with connections in SYN_RCVD state,
- tcp_keepinit can be decreased to make those
- partial connects time out sooner. This should
- be used with caution, since there might be
- legitimate clients that are taking a while
- to respond to SYN/ACK. The unit is specified
- in 1/2 seconds, the default value is 150
- (ie. 75 seconds).
-
- The hashlist size for the TCP inpcb lookup table is regulated by:
-
- tcbhashsize The number of hash buckets used for the
- TCP connection table used in the kernel.
- The initial value is 32. For best results,
- should be specified as a power of 2. For
- busy Web servers, set this to 2048 or more.
-
- The hashlist size for the interface alias table is regulated by:
-
- inifaddr_hsize The number of hash buckets used for the
- interface alias table used in the kernel.
- The initial value is 32. For best results,
- should be specified as a power of 2.
-
- ipport_userreserved The maximum number of concurrent non-reserved,
- dynamically allocated ports. Default range
- is 1025-5000. The maximum value is 65535.
- This limits the numer of times you can
- simultaneously telnet or ftp out to connect
- to other systems.
-
- tcpnodelack Don't delay acknowledging TCP data; this
- can sometimes improve performance of locally
- run CAD packages. Default is value is 0,
- the enabled value is 1.
-
- Digital UNIX version:
-
- V3.2C
-Feature V3.2C patch V4.0
- ======= ===== ===== ====
-somaxconn X X X
-sominconn - X X
-sobacklog_hiwat - X -
-sobacklog_drops - X -
-somaxconn_drops - X -
-tcpnodelack X X X
-tcp_keepidle X X X
-tcp_keepintvl X X X
-tcp_keepcnt - X X
-tcp_keepinit - X X
-TCP keepalive per-socket - - X
-tcp_msl - X -
-tcp_rexmit_interval_min - X -
-TCP inpcb hashing - X X
-tcbhashsize - X X
-interface alias hashing - X X
-inifaddr_hsize - X X
-ipport_userreserved - X -
-sysconfig -q inet - - X
-sysconfig -q socket - - X
-
-</PRE>
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
diff --git a/docs/manual/platform/perf.html b/docs/manual/platform/perf.html
deleted file mode 100644
index 96c48ea..0000000
--- a/docs/manual/platform/perf.html
+++ /dev/null
@@ -1,146 +0,0 @@
-<!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, etc.
-
-<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="#HP">Hewlett-Packard</A>
-<LI><A HREF="#Linux">Linux</A>
-<LI><A HREF="#SGI">SGI</A>
-<LI><A HREF="#Solaris">Solaris</A>
-<LI><A HREF="#SunOS">SunOS 4.x</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 <I>listen()</I> 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.
-
-<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="HP">
-Hewlett-Packard
-</A></H3>
-
-Some documentation on tuning HP machines can be found at <A
-HREF="http://www.software.hp.com/internet/perf/tuning.html">http://www.software.hp.com/internet/perf/tuning.html</A>.
-
-<P><HR>
-
-<H3><A NAME="Linux">
-Linux
-</A></H3>
-
-The most common problem on Linux shows up on heavily-loaded systems
-where the whole server will appear to freeze for a couple of minutes
-at a time, and then come back to life. This has been traced to a
-listen() queue overload - certain Linux implementations have a low
-value set for the incoming connection queue which can cause problems.
-Please see our <a
-href="http://www.qosina.com/~awm/apache/linux-tcp.html">Using Apache on
-Linux</a> page for more info on how to fix this.
-
-<P><HR>
-
-<H3><A NAME="SGI">
-SGI
-</A></H3>
-
-<UL>
-<LI><A HREF="http://www.sgi.com/Products/WebFORCE/Resources/res_TuningGuide.html">
-WebFORCE Web Server Tuning Guidelines for IRIX 5.3,
-<http://www.sgi.com/Products/WebFORCE/Resources/res_TuningGuide.html></A>
-</UL>
-
-<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.
-
-<UL>
-
-<LI><A href="http://www.sun.com/sun-on-net/Sun.Internet.Solutions/performance/">
-World Wide Web Server Performance,
-<http://www.sun.com/sun-on-net/Sun.Internet.Solutions/performance/></a>
-<LI><A HREF="http://www.sun.com/solaris/products/siss/">
-Solaris Internet Server Supplement for 2.5.1</A>
-</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>More welcome!</H3>
-
-If you have tips to contribute, send mail to <a
-href="mailto:brian@organic.com">brian@organic.com</a>
-
-<!--#include virtual="footer.html" -->
-</body></html>
-
diff --git a/docs/manual/platform/unixware.html b/docs/manual/platform/unixware.html
deleted file mode 100644
index eb8adbe..0000000
--- a/docs/manual/platform/unixware.html
+++ /dev/null
@@ -1,61 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Compiling Apache under UnixWare</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">Compiling Apache under UnixWare</H1>
-
-To compile a working copy of Apache under UnixWare, there are several other
-steps you may need to take. These prevent such problems as zombie processes,
-bind errors, and accept errors, to name a few.
-
-<H2>UnixWare 1.x</H2>
-
-Make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not
-defined by Apache autoconfiguration). If using the UnixWare <i>cc</i>
-compiler, and you still see accept() errors, don't use compiler optimization,
-or get <i>gcc</i>.
-
-<H2>UnixWare 2.0.x</H2>
-
-SCO patch <a href="ftp://ftp.sco.com/UW20/tf2163.txt">tf2163</a> is required
-in order for Apache to work correctly on UnixWare 2.0.x. See
-<a href="http://www.sco.com">http://www.sco.com</a>
-for UnixWare patch information.<p>
-
-In addition, make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not
-defined by Apache autoconfiguration). To reduce instances of connections
-in FIN_WAIT_2 state, you may also want to define NO_LINGCLOSE (Apache 1.2
-only).
-
-<H2>UnixWare 2.1.x</H2>
-
-SCO patch <a href="ftp://ftp.sco.com/UW21/ptf3123b.txt">ptf3123</a> is required
-in order for Apache to work correctly on UnixWare 2.1.x. See
-<a href="http://www.sco.com">http://www.sco.com</a>
-for UnixWare patch information.<p>
-
-<b>NOTE:</b> Unixware 2.1.2 and later already have patch ptf3123 included<p>
-
-In addition, make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not
-defined by Apache autoconfiguration). To reduce instances of connections
-in FIN_WAIT_2 state, you may also want to define NO_LINGCLOSE (Apache 1.2
-only).<p>
-
-Thanks to Joe Doupnik <JRD@cc.usu.edu> and Rich Vaughn
-<rvaughn@aad.com> for additional info for UnixWare builds.<p>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
diff --git a/docs/manual/process-model.html b/docs/manual/process-model.html
index c130dec..2c37337 100644
--- a/docs/manual/process-model.html
+++ b/docs/manual/process-model.html
@@ -39,9 +39,9 @@
The defaults for each variable are:
<PRE>
-MinSpareServers 5
-MaxSpareServers 10
-StartServers 5
+MinSpareServers 5
+MaxSpareServers 10
+StartServers 5
</PRE>
There is an absolute maximum number of simultaneous children defined
diff --git a/docs/manual/search/manual-index.cgi b/docs/manual/search/manual-index.cgi
deleted file mode 100644
index 8d06e8a..0000000
--- a/docs/manual/search/manual-index.cgi
+++ /dev/null
@@ -1,239 +0,0 @@
-#!/usr/local/bin/perl5 -w
-# ====================================================================
-# Copyright (c) 1995-1997 The Apache Group. All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions
-# are met:
-#
-# 1. Redistributions of source code must retain the above copyright
-# notice, this list of conditions and the following disclaimer.
-#
-# 2. Redistributions in binary form must reproduce the above copyright
-# notice, this list of conditions and the following disclaimer in
-# the documentation and/or other materials provided with the
-# distribution.
-#
-# 3. All advertising materials mentioning features or use of this
-# software must display the following acknowledgment:
-# "This product includes software developed by the Apache Group
-# for use in the Apache HTTP server project (http://www.apache.org/)."
-#
-# 4. The names "Apache Server" and "Apache Group" must not be used to
-# endorse or promote products derived from this software without
-# prior written permission.
-#
-# 5. Redistributions of any form whatsoever must retain the following
-# acknowledgment:
-# "This product includes software developed by the Apache Group
-# for use in the Apache HTTP server project (http://www.apache.org/)."
-#
-# 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
-# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE GROUP OR
-# ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-# 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.
-# ====================================================================
-#
-# manual-index.cgi script
-# originally written by Ken Coar <Coar@DECUS.Org> in May 1997
-#
-# This script either displays a form in order to find documents in which
-# a word appears, or displays the results of such a search. It is
-# called as a CGI script.
-#
-# [FILE]PATH_INFO is the prefix to add to to the files names found in
-# the index (URL prefix, not filesystem prefix), and QUERY_STRING is the
-# word to be found.
-#
-#***
-#***
-# You may need to tweak the following line to point to the correct
-# location of the index file on your system (it's in the
-# apache/htdocs/manual directory of the Apache distribution tree).
-#***
-#***
-$INDEX = "/export/pub/apache/manual-index.dat";
-
-#***
-#***
-# You shouldn't have to modify anything else.
-#***
-#***
-
-$HTML = "";
-
-#
-# If we have a FILEPATH_INFO or PATH_INFO, it's there to remap the
-# documents to the manual root directory. If this script is already in
-# that directory, this isn't needed.
-#
-$prefix = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'};
-$prefix .= "/" if ($prefix && ($prefix !~ m:/$:));
-
-#
-# QUERY_STRING, if present, contains the word for which we are to
-# search. We also use its [non]presence to determine wha we display.
-#
-$word = $ENV{'QUERY_STRING'};
-
-#
-# Make sure our HTTP header makes it to the server by causing Perl to do
-# a fflush() after every write to STDOUT.
-#
-select (STDOUT);
-$| = 1;
-printf ("Content-type: text/html\n\n");
-
-#
-# Fine, now buffering can go back to normal.
-#
-$| = 0;
-
-#
-# Set up the HTML page title
-$title = "Apache Documentation Search";
-$title .= ": Results for \"$word\"" if ($word);
-
-#
-# We'll re-use the HTML scalar several times; we use it with here
-# documents for multi-line static HTML code. Lets' do the standard page
-# header.
-#
-$HTML = <<EOHT;
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
- <HEAD>
- <TITLE>$title
- </TITLE>
- </HEAD>
- <BODY BGCOLOR="white" TEXT="black" LINK="blue" VLINK="navy" ALINK="red">
- <DIV ALIGN="CENTER">
- <IMG
- SRC="${prefix}images/sub.gif"
- ALT=""
- >
- </DIV>
- <H1 ALIGN="CENTER">
- Apache Documentation Search
- </H1>
- <P>
- This script performs a very simple search across the Apache
- documentation for any single case-insensitive word. No combinations,
- wildcards, regular expressions, word-stubbing, or other fancy options
- are supported; this is just to help you find topics quickly. Only
- those pages which include the <EM>exact</EM> word you type will be
- listed.
- </P>
- <P>
- Documents containing the search word are <EM>not</EM> listed in any
- sort of priority order.
- </P>
- <ISINDEX PROMPT="Enter word to find and press ENTER: ">
-EOHT
-
-printf ($HTML);
-
-#
-# Now set up the next section, which is only displayed if we've been
-# given a word to find.
-#
-$HTML = <<EOHT;
- <HR>
- <H2>
- Results of Search for <SAMP>$word</SAMP>
- </H2>
-EOHT
-
-#
-# We enblock the next section so problems can drop out to the common
-# closure code.
-#
-QUERY:
- {
- if ($word) {
- #
- # Try and open the index file; complain bitterly if we can't.
- #
- if (! open (INDEX, "<$INDEX")) {
- printf ("Can't find documentation index!");
- last QUERY;
- }
- #
- # Got it; display the search-results header.
- #
- printf ($HTML);
- #
- # Read the entire index in and turn it into an hash for the
- # lookup.
- #
- @index = <INDEX>;
- close (INDEX);
- chomp (@index);
- foreach (@index) {
- ($key, $files) = split (/:/, $_);
- $Index{$key} = $files;
- }
- #
- # The dictionary is all lowercase words. Smash our query value
- # and try to find it.
- #
- $word = lc ($word);
- if (! exists ($Index{$word})) {
- printf (" <P>\n <EM>Sorry, no matches found.</EM>\n </P>\n");
- last QUERY;
- }
- #
- # Found an entry, so turn the hash value (a comma-separated list
- # of relative file names) into an array for display.
- # Incidentally, tell the user how many there are.
- #
- @files = split (/,/, $Index{$word});
- printf (" <P>Total of %d match", scalar (@files));
- #
- # Be smart about plurals.
- #
- if (scalar (@files) != 1) {
- printf ("es") ;
- }
- printf (" found.\n </P>\n");
- #
- # Right. Now display the files as they're listed.
- #
- printf (" <OL>\n");
- foreach (@files) {
- printf (" <LI><A HREF=\"${prefix}$_\">");
- printf ("<SAMP>$_</SAMP></A>\n");
- printf (" </LI>\n");
- }
- printf (" </OL>\n");
- #
- # C'est tout!
- #
- }
- }
-
-#
-# Back to common code - the exit path. Display the page trailer.
-#
-$HTML = <<EOHT;
- <A
- HREF="/"
- ><IMG
- SRC="/images/apache_home.gif"
- ALT="Home"
- ></A>
- <HR>
- </BODY>
-</HTML>
-EOHT
-
-printf ($HTML);
-exit (0);
diff --git a/docs/manual/stopping.html.en b/docs/manual/stopping.html.en
deleted file mode 100644
index 373590a..0000000
--- a/docs/manual/stopping.html.en
+++ /dev/null
@@ -1,166 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Stopping and Restarting 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">Stopping and Restarting Apache</h1>
-
-<p>You will notice many <code>httpd</code> executables running on your system,
-but you should not send signals to any of them except the parent, whose
-pid is in the <a href="mod/core.html#pidfile">PidFile</a>. That is to
-say you shouldn't ever need to send signals to any process except the
-parent. There are three signals that you can send the parent:
-<code>TERM</code>, <code>HUP</code>, and <code>USR1</code>, which will
-be described in a moment.
-
-<p>To send a signal to the parent you should issue a command such as:
-<blockquote><pre>
- kill -TERM `cat /usr/local/etc/httpd/logs/httpd.pid`
-</pre></blockquote>
-
-You can read about its progress by issuing:
-
-<blockquote><pre>
- tail -f /usr/local/etc/httpd/logs/error_log
-</pre></blockquote>
-
-Modify those examples to match your
-<a href="mod/core.html#serverroot">ServerRoot</a> and
-<a href="mod/core.html#pidfile">PidFile</a> settings.
-
-<h3>TERM Signal: stop now</h3>
-
-<p>Sending the <code>TERM</code> signal to the parent causes it to
-immediately attempt to kill off all of its children. It may take it
-several seconds to complete killing off its children. Then the
-parent itself exits. Any requests in progress are terminated, and no
-further requests are served.
-
-<h3>HUP Signal: restart now</h3>
-
-<p>Sending the <code>HUP</code> signal to the parent causes it to kill off
-its children like in <code>TERM</code> but the parent doesn't exit. It
-re-reads its configuration files, and re-opens any log files.
-Then it spawns a new set of children and continues
-serving hits.
-
-<p>Users of the
-<a href="mod/mod_status.html">status module</a>
-will notice that the server statistics are
-set to zero when a <code>HUP</code> is sent.
-
-<p><b>Note:</b> If your configuration file has errors in it when you issue a
-restart then your parent will not restart, it will exit with an error.
-See below for a method of avoiding this.
-
-<h3>USR1 Signal: graceful restart</h3>
-
-<p><b>Note:</b> prior to release 1.2b9 this code is quite unstable and
-shouldn't be used at all.
-
-<p>The <code>USR1</code> signal causes the parent process to <i>advise</i>
-the children to exit after their current request (or to exit immediately
-if they're not serving anything). The parent re-reads its configuration
-files and re-opens its log files. As each child dies off the parent
-replaces it with a child from the new <i>generation</i> of the
-configuration, which begins serving new requests immediately.
-
-<p>This code is designed to always respect the
-<a href="mod/core.html#maxclients">MaxClients</a>,
-<a href="mod/core.html#minspareservers">MinSpareServers</a>,
-and <a href="mod/core.html#maxspareservers">MaxSpareServers</a> settings.
-Furthermore, it respects <a href="mod/core.html#startservers">StartServers</a>
-in the following manner: if after one second at least StartServers new
-children have not been created, then create enough to pick up the slack.
-This is to say that the code tries to maintain both the number of children
-appropriate for the current load on the server, and respect your wishes
-with the StartServers parameter.
-
-<p>Users of the
-<a href="mod/mod_status.html">status module</a>
-will notice that the server statistics
-are <b>not</b> set to zero when a <code>USR1</code> is sent. The code
-was written to both minimize the time in which the server is unable to serve
-new requests (they will be queued up by the operating system, so they're
-not lost in any event) and to respect your tuning parameters. In order
-to do this it has to keep the <i>scoreboard</i> used to keep track
-of all children across generations.
-
-<p>The status module will also use a <code>G</code> to indicate those
-children which are still serving requests started before the graceful
-restart was given.
-
-<p>At present there is no way for a log rotation script using
-<code>USR1</code> to know for certain that all children writing the
-pre-restart log have finished. We suggest that you use a suitable delay
-after sending the <code>USR1</code> signal before you do anything with the
-old log. For example if most of your hits take less than 10 minutes to
-complete for users on low bandwidth links then you could wait 15 minutes
-before doing anything with the old log.
-
-<p><b>Note:</b> If your configuration file has errors in it when you issue a
-restart then your parent will not restart, it will exit with an error.
-In the case of graceful
-restarts it will also leave children running when it exits. (These are
-the children which are "gracefully exiting" by handling their last request.)
-This will cause problems if you attempt to restart the server -- it will
-not be able to bind to its listening ports. At present the only work
-around is to check the syntax of your files before doing a restart. The
-easiest way is to just run httpd as a non-root user. If there are no
-errors it will attempt to open its sockets and logs and fail because it's
-not root (or because the currently running httpd already has those ports
-bound). If it fails for any other reason then it's probably a config file
-error and the error should be fixed before issuing the graceful restart.
-
-<h3>Appendix: signals and race conditions</h3>
-
-<p>Prior to Apache 1.2b9 there were several <i>race conditions</i>
-involving the restart and die signals (a simple description of race
-condition is: a time-sensitive problem, as in if something happens at just
-the wrong time it won't behave as expected). For those architectures that
-have the "right" feature set we have eliminated as many as we can.
-But it should be noted that there still do exist race conditions on
-certain architectures.
-
-<p>Architectures that use an on disk
-<a href="mod/core.html#scoreboardfile">ScoreBoardFile</a>
-have the potential to corrupt their scoreboards. This can result in
-the "bind: Address already in use" (after <code>HUP</code>) or
-"long lost child came home!" (after <code>USR1</code>). The former is
-a fatal error, while the latter just causes the server to lose a scoreboard
-slot. So it might be advisable to use graceful restarts, with
-an occasional hard restart. These problems are very difficult to work
-around, but fortunately most architectures do not require a scoreboard file.
-See the ScoreBoardFile documentation for a method to determine if your
-architecture uses it.
-
-<p><code>NEXT</code> and <code>MACHTEN</code> (68k only) have small race
-conditions
-which can cause a restart/die signal to be lost, but should not cause the
-server to do anything otherwise problematic.
-<!-- they don't have sigaction, or we're not using it -djg -->
-
-<p>All architectures have a small race condition in each child involving
-the second and subsequent requests on a persistent HTTP connection
-(KeepAlive). It may exit after reading the request line but before
-reading any of the request headers. There is a fix that was discovered
-too late to make 1.2. In theory this isn't an issue because the KeepAlive
-client has to expect these events because of network latencies and
-server timeouts. In practice it doesn't seem to affect anything either
--- in a test case the server was restarted twenty times per second and
-clients successfully browsed the site without getting broken images or
-empty documents.
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
diff --git a/docs/manual/suexec.html b/docs/manual/suexec.html
index 2b32aa9..0157cd0 100644
--- a/docs/manual/suexec.html
+++ b/docs/manual/suexec.html
@@ -1,8 +1,8 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html><head>
-<title>Apache SetUserID Support</title>
-</head>
-
+<HTML>
+<HEAD>
+<TITLE>Apache suEXEC Support</TITLE>
+</HEAD>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY
BGCOLOR="#FFFFFF"
@@ -12,150 +12,413 @@
ALINK="#FF0000"
>
<!--#include virtual="header.html" -->
-<h1 ALIGN="CENTER">Apache suEXEC Support</h1>
-<hr>
+<H1 ALIGN="CENTER">Apache suEXEC Support</H1>
-<h3>What is suEXEC?</h3>
-The <STRONG>suEXEC</STRONG> feature, introduced in Apache 1.2 provides
-the ability to run <STRONG>CGI</STRONG> programs under user IDs
-different from the user ID of the calling web-server. Used properly,
-this feature can reduce considerably the insecurity of allowing users to
-run CGI programs. At the same time, improperly configured, this facility
-can crash your computer, burn your house down and steal all the money
-from your retirement fund. <STRONG>:-)</STRONG> If you aren't familiar
-with managing setuid root programs and the security issues they
-present, we highly recommend that you not consider using this feature.<p>
+<P ALIGN="LEFT">
+<OL>
+ <LH><BIG><STRONG>CONTENTS</STRONG></BIG></LH>
+ <LI><A HREF="#what">What is suEXEC?</A></LI>
+ <LI><A HREF="#before">Before we begin.</A></LI>
+ <LI><A HREF="#model">suEXEC Security Model.</A></LI>
+ <LI><A HREF="#install">Configuring & Installing suEXEC</A></LI>
+ <LI><A HREF="#enable">Enabling & Disabling suEXEC</A></LI>
+ <LI><A HREF="#debug">Debugging suEXEC</A></LI>
+ <LI><A HREF="#jabberwock">Beware the Jabberwock: Warnings &
+ Examples</A></LI>
+</OL>
+</P>
-<hr>
+<H3><A NAME="what">What is suEXEC?</A></H3>
+<P ALIGN="LEFT">
+The <STRONG>suEXEC</STRONG> feature -- introduced in Apache 1.2 -- provides
+Apache users the ability to run <STRONG>CGI</STRONG> and <STRONG>SSI</STRONG>
+programs under user IDs different from the user ID of the calling web-server.
+Normally, when a CGI or SSI program executes, it runs as the same user who is
+running the web server.
+</P>
-<h3>Enabling suEXEC Support</h3>
-Having said all that, enabling this feature is purposefully difficult with
-the intent that it will only be installed by users determined to use it and
-is not part of the normal install/compile process.<p>
+<P ALIGN="LEFT">
+Used properly, this feature can reduce considerably the security risks involved
+with allowing users to develop and run private CGI or SSI programs. However,
+if suEXEC is improperly configured, it can cause any number of problems and
+possibly create new holes in your computer's security. If you aren't familiar
+with managing setuid root programs and the security issues they present, we
+highly recommend that you not consider using suEXEC.
+</P>
-<h3>Configuring the suEXEC wrapper</h3>
-From the top-level of the Apache source tree,
-type: <STRONG><code>cd support [ENTER]</code></STRONG><p>
+<P ALIGN="CENTER">
+<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
+</P>
+
+<H3><A NAME="before">Before we begin.</A></H3>
+<P ALIGN="LEFT">
+Before jumping head-first into this document, you should be aware of the
+assumptions made on the part of the Apache Group and this document.
+</P>
+
+<P ALIGN="LEFT">
+First, it is assumed that you are using a UNIX derivate operating system that
+is capable of <STRONG>setuid</STRONG> and <STRONG>setgid</STRONG> operations.
+All command examples are given in this regard. Other platforms, if they are
+capable of supporting suEXEC, may differ in their configuration.
+</P>
+
+<P ALIGN="LEFT">
+Second, it is assumed you are familiar with some basic concepts of your
+computer's security and its administration. This involves an understanding
+of <STRONG>setuid/setgid</STRONG> operations and the various effects they
+may have on your system and its level of security.
+</P>
+
+<P ALIGN="LEFT">
+Third, it is assumed that you are using an <STRONG>unmodified</STRONG>
+version of suEXEC code. All code for suEXEC has been carefully scrutinized and
+tested by the developers as well as numerous beta testers. Every precaution has
+been taken to ensure a simple yet solidly safe base of code. Altering this
+code can cause unexpected problems and new security risks. It is
+<STRONG>highly</STRONG> recommended you not alter the suEXEC code unless you
+are well versed in the particulars of security programming and are willing to
+share your work with the Apache Group for consideration.
+</P>
+
+<P ALIGN="LEFT">
+Fourth, and last, it has been the decision of the Apache Group to
+<STRONG>NOT</STRONG> make suEXEC part of the default installation of Apache.
+To this end, suEXEC configuration is a manual process requiring of the
+administrator careful attention to details. It is through this process
+that the Apache Group hopes to limit suEXEC installation only to those
+who are determined to use it.
+</P>
+
+<P ALIGN="LEFT">
+Still with us? Yes? Good. Let's move on!
+</P>
+
+<P ALIGN="CENTER">
+<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
+</P>
+
+<H3><A NAME="model">suEXEC Security Model</A></H3>
+<P ALIGN="LEFT">
+Before we begin configuring and installing suEXEC, we will first discuss
+the security model you are about to implement. By doing so, you may
+better understand what exactly is going on inside suEXEC and what precautions
+are taken to ensure your system's security.
+</P>
+
+<P ALIGN="LEFT">
+<STRONG>suEXEC</STRONG> is based on a setuid "wrapper" program that is
+called by the main Apache web server. This wrapper is called when an HTTP
+request is made for a CGI or SSI program that the administrator has designated
+to run as a userid other than that of the main server. When such a request
+is made, Apache provides the suEXEC wrapper with the program's name and the
+user and group IDs under which the program is to execute.
+</P>
+
+<P ALIGN="LEFT">
+The wrapper then employs the following process to determine success or
+failure -- if any one of these conditions fail, the program logs the failure
+and exits with an error, otherwise it will continue:
+ <OL>
+ <LI><STRONG>Was the wrapper called with the proper number of arguments?</STRONG>
+ <BLOCKQUOTE>
+ The wrapper will only execute if it is given the proper number of arguments.
+ The proper argument format is known to the Apache web server. If the wrapper
+ is not receiving the proper number of arguments, it is either being hacked, or
+ there is something wrong with the suEXEC portion of your Apache binary.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is the user executing this wrapper a valid user of this system?</STRONG>
+ <BLOCKQUOTE>
+ This is to ensure that the user executing the wrapper is truly a user of the system.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is this valid user allowed to run the wrapper?</STRONG>
+ <BLOCKQUOTE>
+ Is this user the user allowed to run this wrapper? Only one user (the Apache
+ user) is allowed to execute this program.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Does the target program have an unsafe hierarchical reference?</STRONG>
+ <BLOCKQUOTE>
+ Does the target program contain a leading '/' or have a '..' backreference? These
+ are not allowed; the target program must reside within the Apache webspace.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is the target user name valid?</STRONG>
+ <BLOCKQUOTE>
+ Does the target user exist?
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is the target group name valid?</STRONG>
+ <BLOCKQUOTE>
+ Does the target group exist?
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is the target user <EM>NOT</EM> superuser?</STRONG>
+ <BLOCKQUOTE>
+ Presently, suEXEC does not allow 'root' to execute CGI/SSI programs.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is the target userid <EM>ABOVE</EM> the minimum ID number?</STRONG>
+ <BLOCKQUOTE>
+ The minimum user ID number is specified during configuration. This allows you
+ to set the lowest possible userid that will be allowed to execute CGI/SSI programs.
+ This is useful to block out "system" accounts.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is the target group <EM>NOT</EM> the superuser group?</STRONG>
+ <BLOCKQUOTE>
+ Presently, suEXEC does not allow the 'root' group to execute CGI/SSI programs.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is the target groupid <EM>ABOVE</EM> the minimum ID number?</STRONG>
+ <BLOCKQUOTE>
+ The minimum group ID number is specified during configuration. This allows you
+ to set the lowest possible groupid that will be allowed to execute CGI/SSI programs.
+ This is useful to block out "system" groups.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Can the wrapper successfully become the target user and group?</STRONG>
+ <BLOCKQUOTE>
+ Here is where the program becomes the target user and group via setuid and setgid
+ calls. The group access list is also initialized with all of the groups of which
+ the user is a member.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Does the directory in which the program resides exist?</STRONG>
+ <BLOCKQUOTE>
+ If it doesn't exist, it can't very well contain files.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is the directory within the Apache webspace?</STRONG>
+ <BLOCKQUOTE>
+ If the request is for a regular portion of the server, is the requested directory
+ within the server's document root? If the request is for a UserDir, is the requested
+ directory within the user's document root?
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is the directory <EM>NOT</EM> writable by anyone else?</STRONG>
+ <BLOCKQUOTE>
+ We don't want to open up the directory to others; only the owner user may be able
+ to alter this directories contents.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Does the target program exist?</STRONG>
+ <BLOCKQUOTE>
+ If it doesn't exists, it can't very well be executed.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is the target program <EM>NOT</EM> writable by anyone else?</STRONG>
+ <BLOCKQUOTE>
+ We don't want to give anyone other than the owner the ability to change the program.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is the target program <EM>NOT</EM> setuid or setgid?</STRONG>
+ <BLOCKQUOTE>
+ We do not want to execute programs that will then change our UID/GID again.
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Is the target user/group the same as the program's user/group?</STRONG>
+ <BLOCKQUOTE>
+ Is the user the owner of the file?
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Can we successfully clean the process environment to ensure safe operations?</STRONG>
+ <BLOCKQUOTE>
+ suEXEC cleans the process' environment by establishing a safe execution PATH (defined
+ during configuration), as well as only passing through those variables whose names
+ are listed in the safe environment list (also created during configuration).
+ </BLOCKQUOTE>
+ </LI>
+ <LI><STRONG>Can we successfully become the target program and execute?</STRONG>
+ <BLOCKQUOTE>
+ Here is where suEXEC ends and the target program begins.
+ </BLOCKQUOTE>
+ </LI>
+ </OL>
+</P>
+
+<P ALIGN="LEFT">
+This is the standard operation of the the suEXEC wrapper's security model.
+It is somewhat stringent and can impose new limitations and guidelines for
+CGI/SSI design, but it was developed carefully step-by-step with security
+in mind.
+</P>
+
+<P ALIGN="LEFT">
+For more information as to how this security model can limit your possibilities
+in regards to server configuration, as well as what security risks can be avoided
+with a proper suEXEC setup, see the <A HREF="#beware">"Beware the Jabberwock"</A>
+section of this document.
+</P>
+
+<P ALIGN="CENTER">
+<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
+</P>
+
+<H3><A NAME="install">Configuring & Installing suEXEC</A></H3>
+<P ALIGN="LEFT">
+Here's where we begin the fun. The configuration and installation of suEXEC is
+a four step process: edit the suEXEC header file, compile suEXEC, place the
+suEXEC binary in its proper location, and configure Apache for use with suEXEC.
+</P>
+
+<P ALIGN="LEFT">
+<STRONG>EDITING THE SUEXEC HEADER FILE</STRONG><BR>
+- From the top-level of the Apache source tree, type:
+<STRONG><code>cd support [ENTER]</code></STRONG>
+</P>
+
+<P ALIGN="LEFT">
Edit the <code>suexec.h</code> file and change the following macros to
-match your local Apache installation.<p>
+match your local Apache installation.
+</P>
+
+<P ALIGN="LEFT">
<EM>From support/suexec.h</EM>
-<pre>
-/*
- * HTTPD_USER -- Define as the username under which Apache normally
- * runs. This is the only user allowed to execute
- * this program.
- */
-#define HTTPD_USER "www"
+<PRE>
+ /*
+ * HTTPD_USER -- Define as the username under which Apache normally
+ * runs. This is the only user allowed to execute
+ * this program.
+ */
+ #define HTTPD_USER "www"
-/*
- * LOG_EXEC -- Define this as a filename if you want all suEXEC
- * transactions and errors logged for auditing and
- * debugging purposes.
- */
-#define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log"
+ /*
+ * UID_MIN -- Define this as the lowest UID allowed to be a target user
+ * for suEXEC. For most systems, 500 or 100 is common.
+ */
+ #define UID_MIN 100
-/*
- * DOC_ROOT -- Define as the DocumentRoot set for Apache. This
- * will be the only hierarchy (aside from UserDirs)
- * that can be used for suEXEC behavior.
- */
-#define DOC_ROOT "/usr/local/etc/httpd/htdocs"
+ /*
+ * GID_MIN -- Define this as the lowest GID allowed to be a target group
+ * for suEXEC. For most systems, 100 is common.
+ */
+ #define GID_MIN 100
-/*
- * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables.
- *
- */
-#define SAFE_PATH "/usr/local/bin:/usr/bin:/bin"
-</pre>
+ /*
+ * USERDIR_SUFFIX -- Define to be the subdirectory under users'
+ * home directories where suEXEC access should
+ * be allowed. All executables under this directory
+ * will be executable by suEXEC as the user so
+ * they should be "safe" programs. If you are
+ * using a "simple" UserDir directive (ie. one
+ * without a "*" in it) this should be set to
+ * the same value. suEXEC will not work properly
+ * in cases where the UserDir directive points to
+ * a location that is not the same as the user's
+ * home directory as referenced in the passwd file.
+ *
+ * If you have VirtualHosts with a different
+ * UserDir for each, you will need to define them to
+ * all reside in one parent directory; then name that
+ * parent directory here. IF THIS IS NOT DEFINED
+ * PROPERLY, ~USERDIR CGI REQUESTS WILL NOT WORK!
+ * See the suEXEC documentation for more detailed
+ * information.
+ */
+ #define USERDIR_SUFFIX "public_html"
-<h3>Compiling the suEXEC wrapper</h3>
-At the shell command prompt, type: <STRONG><code>cc suexec.c
--o suexec [ENTER]</code></STRONG>.<p>
+ /*
+ * LOG_EXEC -- Define this as a filename if you want all suEXEC
+ * transactions and errors logged for auditing and
+ * debugging purposes.
+ */
+ #define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log" /* Need me? */
+
+ /*
+ * DOC_ROOT -- Define as the DocumentRoot set for Apache. This
+ * will be the only hierarchy (aside from UserDirs)
+ * that can be used for suEXEC behavior.
+ */
+ #define DOC_ROOT "/usr/local/etc/httpd/htdocs"
+
+ /*
+ * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables.
+ *
+ */
+ #define SAFE_PATH "/usr/local/bin:/usr/bin:/bin"
+</PRE>
+</P>
+
+<P ALIGN="LEFT">
+<STRONG>COMPILING THE SUEXEC WRAPPER</STRONG><BR>
+You now need to compile the suEXEC wrapper. At the shell command prompt,
+type: <STRONG><CODE>cc suexec.c -o suexec [ENTER]</CODE></STRONG>.
This should create the <STRONG><em>suexec</em></STRONG> wrapper executable.
+</P>
-<h3>Compiling Apache for suEXEC support</h3>
+<P ALIGN="LEFT">
+<STRONG>COMPILING APACHE FOR USE WITH SUEXEC</STRONG><BR>
By default, Apache is compiled to look for the suEXEC wrapper in the following
-location.<p>
+location.
+</P>
+
+<P ALIGN="LEFT">
<EM>From src/httpd.h</EM>
-<pre>
-/* The path to the suEXEC wrapper */
-#ifndef SUEXEC_BIN
-#define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec"
-#endif
-</pre>
-<p>
+<PRE>
+ /* The path to the suEXEC wrapper */
+ #define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec"
+</PRE>
+</P>
+
+<P ALIGN="LEFT">
If your installation requires location of the wrapper program in a different
directory, edit src/httpd.h and recompile your Apache server.
-See <a href="install.html">Compiling and Installing Apache</a> for more
-info on this process.<p>
+See <A HREF="install.html">Compiling and Installing Apache</A> for more
+info on this process.
+</P>
-<h3>Installing the suEXEC wrapper</h3>
+<P ALIGN="LEFT">
+<STRONG>COPYING THE SUEXEC BINARY TO ITS PROPER LOCATION</STRONG><BR>
Copy the <STRONG><em>suexec</em></STRONG> executable created in the
-exercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>.<p>
-In order for the wrapper to set the user ID for execution requests it
-must me installed as owner <STRONG><em>root</em></STRONG> and must have
-the setuserid execution bit set for file modes.
-If you are not running a <STRONG><em>root</em></STRONG> user shell, do
-so now and execute the following commands.<p>
+exercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>.
+</P>
-<STRONG><code>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</code></STRONG><p>
-<STRONG><code>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</code></STRONG><p>
+<P ALIGN="LEFT">
+<STRONG><CODE>cp suexec /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG>
+</P>
-<EM>Change the path to the suEXEC wrapper to match your system
-installation.</EM>
+<P ALIGN="LEFT">
+In order for the wrapper to set the user ID, it must me installed as owner
+<STRONG><em>root</em></STRONG> and must have the setuserid execution bit
+set for file modes. If you are not running a <STRONG><em>root</em></STRONG>
+user shell, do so now and execute the following commands.
+</P>
-<hr>
+<P ALIGN="LEFT">
+<STRONG><CODE>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG><BR>
+<STRONG><CODE>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG>
+</P>
-<h3><a name="model">Security Model of suEXEC</a></h3>
-The <STRONG>suEXEC</STRONG> wrapper supplied with Apache performs the
-following security checks before it will execute any program passed to
-it for execution.
-<ol>
-<li>User executing the wrapper <STRONG>must be a valid user on this
- system</STRONG>.
-<li>User executing the wrapper <STRONG>must be the compiled in
- HTTPD_USER</STRONG>.
-<li>The command that the request wishes to execute <STRONG>must not
- contain a leading / or ../, or the string "/../" anywhere</STRONG>.
-<li>The command being executed <STRONG>must reside under the compiled in
- DOC_ROOT</STRONG>.
-<li>The current working directory <STRONG>must be a directory</STRONG>.
-<li>The current working directory <STRONG>must not be writable by
- <em>group</em> or <em>other</em></STRONG>.
-<li>The command being executed <STRONG>cannot be a symbolic link</STRONG>.
-<li>The command being executed <STRONG>cannot be writable by
- <em>group</em> or <em>other</em></STRONG>.
-<li>The command being executed <STRONG>cannot be a <em>setuid</em> or
- <em>setgid</em> program</STRONG>.
-<li>The target UID and GID <STRONG>must be a valid user and group on
- this system</STRONG>.
-<li>The target UID and GID to execute as, <STRONG>must match the UID and
- GID of the directory</STRONG>.
-<li>The target execution UID and GID <STRONG>must not be the privileged
- ID 0</STRONG>.
-</ol>
-If any of these issues are too restrictive, or do not seem restrictive
-enough, you are welcome to install your own version of the wrapper.
-We've given you the rope, now go have fun with it. <STRONG>:-)</STRONG>
+<P ALIGN="CENTER">
+<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
+</P>
-<hr>
-
-<h3>Using suEXEC</h3>
+<H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3>
+<P ALIGN="LEFT">
After properly installing the <STRONG>suexec</STRONG> wrapper
-executable, you must kill and restart the Apache server. A simple
-<code><STRONG>kill -1 `cat httpd.pid`</STRONG></code> will not be enough.
+executable, you must kill and restart the Apache server. A simple
+<STRONG><CODE>kill -1 `cat httpd.pid`</CODE></STRONG> will not be enough.
Upon startup of the web-server, if Apache finds a properly configured
<STRONG>suexec</STRONG> wrapper, it will print the following message to
-the console:<p>
+the console:
+</P>
-<code>Configuring Apache for use with suexec wrapper.</code><p>
+<P ALIGN="LEFT">
+<CODE>Configuring Apache for use with suexec wrapper.</CODE>
+</P>
+<P ALIGN="LEFT">
If you don't see this message at server startup, the server is most
likely not finding the wrapper program where it expects it, or the
-executable is not installed <STRONG><em>setuid root</em></STRONG>. Check
-your installation and try again.<p>
+executable is not installed <STRONG><EM>setuid root</EM></STRONG>. Check
+your installation and try again.
+</P>
+<P ALIGN="LEFT">
One way to use <STRONG>suEXEC</STRONG> is through the
<a href="mod/core.html#user"><STRONG>User</STRONG></a> and
<a href="mod/core.html#group"><STRONG>Group</STRONG></a> directives in
@@ -176,15 +439,68 @@
execution to be enabled for the user and that the script must meet the
scrutiny of the <a href="#model">security checks</a> above.
-<hr>
+<P ALIGN="CENTER">
+<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
+</P>
-<h3>Debugging suEXEC</h3>
+<H3><A NAME="debug">Debugging suEXEC</A></H3>
+<P ALIGN="LEFT">
The suEXEC wrapper will write log information to the location defined in
the <code>suexec.h</code> as indicated above. If you feel you have
-configured and installed the wrapper properly,
-have a look at this log and the error_log for the server to see where
-you may have gone astray.
-<!--#include virtual="footer.html" -->
+configured and installed the wrapper properly, have a look at this log
+and the error_log for the server to see where you may have gone astray.
+</P>
+<P ALIGN="CENTER">
+<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
+</P>
+
+<H3><A NAME="jabberwock">Beware the Jabberwock: Warnings & Examples</A></H3>
+<P ALIGN="LEFT">
+<STRONG>NOTE!</STRONG> This section may not be complete. For the latest
+revision of this section of the documentation, see the Apache Group's
+<A HREF="http://www.apache.org/docs/suexec.html">Online Documentation</A>
+version.
+</P>
+
+<P ALIGN="LEFT">
+There are a few points of interest regarding the wrapper that can cause
+limitations on server setup. Please review these before submitting any
+"bugs" regarding suEXEC.
+<UL>
+ <LH><STRONG>suEXEC Points Of Interest</STRONG></LH>
+ <LI>Hierarchy limitations
+ <BLOCKQUOTE>
+ For security and efficiency reasons, all suexec requests must
+ remain within either a top-level document root for virtual
+ host requests, or one top-level personal document root for
+ userdir requests. For example, if you have four VirtualHosts
+ configured, you would need to structure all of your VHosts'
+ document roots off of one main Apache document hierarchy to
+ take advantage of suEXEC for VirtualHosts. (Example forthcoming.)
+ </BLOCKQUOTE>
+ </LI>
+ <LI>suEXEC's PATH environment variable
+ <BLOCKQUOTE>
+ This can be a dangerous thing to change. Make certain every
+ path you include in this define is a <STRONG>trusted</STRONG>
+ directory. You don't want to open people up to having someone
+ from across the world running a trojan horse on them.
+ </BLOCKQUOTE>
+ </LI>
+ <LI>Altering the suEXEC code
+ <BLOCKQUOTE>
+ Again, this can cause <STRONG>Big Trouble</STRONG> if you try
+ this without knowing what you are doing. Stay away from it
+ if at all possible.
+ </BLOCKQUOTE>
+ </LI>
+</UL>
+
+<P ALIGN="CENTER">
+<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
+</P>
+
+<!--#include virtual="footer.html" -->
</BODY>
</HTML>
diff --git a/docs/manual/suexec.html.en b/docs/manual/suexec.html.en
deleted file mode 100644
index 2b32aa9..0000000
--- a/docs/manual/suexec.html.en
+++ /dev/null
@@ -1,190 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html><head>
-<title>Apache SetUserID Support</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 suEXEC Support</h1>
-
-<hr>
-
-<h3>What is suEXEC?</h3>
-The <STRONG>suEXEC</STRONG> feature, introduced in Apache 1.2 provides
-the ability to run <STRONG>CGI</STRONG> programs under user IDs
-different from the user ID of the calling web-server. Used properly,
-this feature can reduce considerably the insecurity of allowing users to
-run CGI programs. At the same time, improperly configured, this facility
-can crash your computer, burn your house down and steal all the money
-from your retirement fund. <STRONG>:-)</STRONG> If you aren't familiar
-with managing setuid root programs and the security issues they
-present, we highly recommend that you not consider using this feature.<p>
-
-<hr>
-
-<h3>Enabling suEXEC Support</h3>
-Having said all that, enabling this feature is purposefully difficult with
-the intent that it will only be installed by users determined to use it and
-is not part of the normal install/compile process.<p>
-
-<h3>Configuring the suEXEC wrapper</h3>
-From the top-level of the Apache source tree,
-type: <STRONG><code>cd support [ENTER]</code></STRONG><p>
-Edit the <code>suexec.h</code> file and change the following macros to
-match your local Apache installation.<p>
-<EM>From support/suexec.h</EM>
-<pre>
-/*
- * HTTPD_USER -- Define as the username under which Apache normally
- * runs. This is the only user allowed to execute
- * this program.
- */
-#define HTTPD_USER "www"
-
-/*
- * LOG_EXEC -- Define this as a filename if you want all suEXEC
- * transactions and errors logged for auditing and
- * debugging purposes.
- */
-#define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log"
-
-/*
- * DOC_ROOT -- Define as the DocumentRoot set for Apache. This
- * will be the only hierarchy (aside from UserDirs)
- * that can be used for suEXEC behavior.
- */
-#define DOC_ROOT "/usr/local/etc/httpd/htdocs"
-
-/*
- * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables.
- *
- */
-#define SAFE_PATH "/usr/local/bin:/usr/bin:/bin"
-</pre>
-
-<h3>Compiling the suEXEC wrapper</h3>
-At the shell command prompt, type: <STRONG><code>cc suexec.c
--o suexec [ENTER]</code></STRONG>.<p>
-This should create the <STRONG><em>suexec</em></STRONG> wrapper executable.
-
-<h3>Compiling Apache for suEXEC support</h3>
-By default, Apache is compiled to look for the suEXEC wrapper in the following
-location.<p>
-<EM>From src/httpd.h</EM>
-<pre>
-/* The path to the suEXEC wrapper */
-#ifndef SUEXEC_BIN
-#define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec"
-#endif
-</pre>
-<p>
-If your installation requires location of the wrapper program in a different
-directory, edit src/httpd.h and recompile your Apache server.
-See <a href="install.html">Compiling and Installing Apache</a> for more
-info on this process.<p>
-
-<h3>Installing the suEXEC wrapper</h3>
-Copy the <STRONG><em>suexec</em></STRONG> executable created in the
-exercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>.<p>
-In order for the wrapper to set the user ID for execution requests it
-must me installed as owner <STRONG><em>root</em></STRONG> and must have
-the setuserid execution bit set for file modes.
-If you are not running a <STRONG><em>root</em></STRONG> user shell, do
-so now and execute the following commands.<p>
-
-<STRONG><code>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</code></STRONG><p>
-<STRONG><code>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</code></STRONG><p>
-
-<EM>Change the path to the suEXEC wrapper to match your system
-installation.</EM>
-
-<hr>
-
-<h3><a name="model">Security Model of suEXEC</a></h3>
-The <STRONG>suEXEC</STRONG> wrapper supplied with Apache performs the
-following security checks before it will execute any program passed to
-it for execution.
-<ol>
-<li>User executing the wrapper <STRONG>must be a valid user on this
- system</STRONG>.
-<li>User executing the wrapper <STRONG>must be the compiled in
- HTTPD_USER</STRONG>.
-<li>The command that the request wishes to execute <STRONG>must not
- contain a leading / or ../, or the string "/../" anywhere</STRONG>.
-<li>The command being executed <STRONG>must reside under the compiled in
- DOC_ROOT</STRONG>.
-<li>The current working directory <STRONG>must be a directory</STRONG>.
-<li>The current working directory <STRONG>must not be writable by
- <em>group</em> or <em>other</em></STRONG>.
-<li>The command being executed <STRONG>cannot be a symbolic link</STRONG>.
-<li>The command being executed <STRONG>cannot be writable by
- <em>group</em> or <em>other</em></STRONG>.
-<li>The command being executed <STRONG>cannot be a <em>setuid</em> or
- <em>setgid</em> program</STRONG>.
-<li>The target UID and GID <STRONG>must be a valid user and group on
- this system</STRONG>.
-<li>The target UID and GID to execute as, <STRONG>must match the UID and
- GID of the directory</STRONG>.
-<li>The target execution UID and GID <STRONG>must not be the privileged
- ID 0</STRONG>.
-</ol>
-If any of these issues are too restrictive, or do not seem restrictive
-enough, you are welcome to install your own version of the wrapper.
-We've given you the rope, now go have fun with it. <STRONG>:-)</STRONG>
-
-<hr>
-
-<h3>Using suEXEC</h3>
-After properly installing the <STRONG>suexec</STRONG> wrapper
-executable, you must kill and restart the Apache server. A simple
-<code><STRONG>kill -1 `cat httpd.pid`</STRONG></code> will not be enough.
-Upon startup of the web-server, if Apache finds a properly configured
-<STRONG>suexec</STRONG> wrapper, it will print the following message to
-the console:<p>
-
-<code>Configuring Apache for use with suexec wrapper.</code><p>
-
-If you don't see this message at server startup, the server is most
-likely not finding the wrapper program where it expects it, or the
-executable is not installed <STRONG><em>setuid root</em></STRONG>. Check
-your installation and try again.<p>
-
-One way to use <STRONG>suEXEC</STRONG> is through the
-<a href="mod/core.html#user"><STRONG>User</STRONG></a> and
-<a href="mod/core.html#group"><STRONG>Group</STRONG></a> directives in
-<a href="mod/core.html#virtualhost"><STRONG>VirtualHost</STRONG></a>
-definitions. By setting these directives to values different from the
-main server user ID, all requests for CGI resources will be executed as
-the <STRONG>User</STRONG> and <STRONG>Group</STRONG> defined for that
-<STRONG><VirtualHost></STRONG>. If only one or
-neither of these directives are specified for a
-<STRONG><VirtualHost></STRONG> then the main
-server userid is assumed.<p>
-
-<STRONG>suEXEC</STRONG> can also be used to to execute CGI programs as
-the user to which the request is being directed. This is accomplished by
-using the <STRONG>~</STRONG> character prefixing the user ID for whom
-execution is desired.
-The only requirement needed for this feature to work is for CGI
-execution to be enabled for the user and that the script must meet the
-scrutiny of the <a href="#model">security checks</a> above.
-
-<hr>
-
-<h3>Debugging suEXEC</h3>
-The suEXEC wrapper will write log information to the location defined in
-the <code>suexec.h</code> as indicated above. If you feel you have
-configured and installed the wrapper properly,
-have a look at this log and the error_log for the server to see where
-you may have gone astray.
-<!--#include virtual="footer.html" -->
-
-</BODY>
-</HTML>
