diff options
| author | (no author) <(no author)@unknown> | 1997-06-05 20:07:19 +0000 |
|---|---|---|
| committer | (no author) <(no author)@unknown> | 1997-06-05 20:07:19 +0000 |
| commit | c24d67e9d052e9fd47f5ec45d6f1213a44750060 (patch) | |
| tree | ced9d575e92d0a5619983d05d0042bb3fb6d3cf8 | |
| parent | 18089b56128835529e43aa2d76f38105a9260c40 (diff) | |
| download | httpd-c24d67e9d052e9fd47f5ec45d6f1213a44750060.tar.gz | |
This commit was manufactured by cvs2svn to create branch
'unlabeled-1.11.2'.
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/unlabeled-1.11.2@78247 13f79535-47bb-0310-9956-ffa450edef68
80 files changed, 0 insertions, 17076 deletions
diff --git a/docs/docroot/apache_pb.gif b/docs/docroot/apache_pb.gif Binary files differdeleted file mode 100644 index 3a1c139fc4..0000000000 --- a/docs/docroot/apache_pb.gif +++ /dev/null diff --git a/docs/manual/LICENSE b/docs/manual/LICENSE deleted file mode 100644 index ec09d302fe..0000000000 --- a/docs/manual/LICENSE +++ /dev/null @@ -1,54 +0,0 @@ -/* ==================================================================== - * 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. - * ==================================================================== - * - * This software consists of voluntary contributions made by many - * individuals on behalf of the Apache Group and was originally based - * on public domain software written at the National Center for - * Supercomputing Applications, University of Illinois, Urbana-Champaign. - * For more information on the Apache Group and the Apache HTTP server - * project, please see <http://www.apache.org/>. - * - */ - - - diff --git a/docs/manual/bind.html b/docs/manual/bind.html deleted file mode 100644 index 9253168138..0000000000 --- a/docs/manual/bind.html +++ /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/bind.html.en b/docs/manual/bind.html.en deleted file mode 100644 index 9253168138..0000000000 --- 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 b/docs/manual/cgi_path.html deleted file mode 100644 index 8ac3bc0dd1..0000000000 --- a/docs/manual/cgi_path.html +++ /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/cgi_path.html.en b/docs/manual/cgi_path.html.en deleted file mode 100644 index 8ac3bc0dd1..0000000000 --- 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 b/docs/manual/content-negotiation.html deleted file mode 100644 index 2aa06eb32f..0000000000 --- a/docs/manual/content-negotiation.html +++ /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/content-negotiation.html.en b/docs/manual/content-negotiation.html.en deleted file mode 100644 index 2aa06eb32f..0000000000 --- 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 deleted file mode 100644 index 3f04af058b..0000000000 --- a/docs/manual/custom-error.html +++ /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/custom-error.html.en b/docs/manual/custom-error.html.en deleted file mode 100644 index 3f04af058b..0000000000 --- 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 ad539e2abb..0000000000 --- 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/dns-caveats.html b/docs/manual/dns-caveats.html deleted file mode 100644 index 50a9bcfe8f..0000000000 --- a/docs/manual/dns-caveats.html +++ /dev/null @@ -1,201 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>Issues Regarding DNS 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">Issues Regarding DNS and Apache</h1> - -<p>This page could be summarized with the statement: <i>don't require -Apache to use DNS for any parsing of the configuration files</i>. -If Apache has to use DNS to parse the configuration files then your -server may be subject to reliability problems (it might not boot), or -denial and theft of service attacks (including users able to steal hits -from other users). - -<h3>A Simple Example</h3> - -Consider this configuration snippet: - -<blockquote><pre> - <VirtualHost www.abc.dom> - ServerAdmin webgirl@abc.dom - DocumentRoot /www/abc - </VirtualHost> -</pre></blockquote> - -<p>In order for Apache to function properly it absolutely needs -to have two pieces of information about each virtual host: the -<a href="mod/core.html#servername"><code>ServerName</code></a> -and at least one IP address that the server -responds to. This example does not include the IP address, so Apache -must use DNS to find the address of <code>www.abc.dom</code>. If for -some reason DNS is not available at the time your server is parsing its -config file, then this virtual host <b>will not be configured</b>. It -won't be able to respond to any hits to this virtual host (prior to -Apache version 1.2 the server would not even boot). - -<p>Suppose that <code>www.abc.dom</code> has address 10.0.0.1. Then -consider this configuration snippet: - -<blockquote><pre> - <VirtualHost 10.0.0.1> - ServerAdmin webgirl@abc.dom - DocumentRoot /www/abc - </VirtualHost> -</pre></blockquote> - -<p>Now Apache needs to use reverse DNS to find the <code>ServerName</code> -for this virtualhost. If that reverse lookup fails then it will partially -disable the virtualhost (prior to Apache version 1.2 the server would not -even boot). If the virtual host is name-based then it will effectively -be totally disabled, but if it is IP-based then it will mostly work. -However if Apache should ever have to generate a full URL for the server -which includes the server name then it will fail to generate a valid URL. - -<p>Here is a snippet that avoids both of these problems. - -<blockquote><pre> - <VirtualHost 10.0.0.1> - ServerName www.abc.dom - ServerAdmin webgirl@abc.dom - DocumentRoot /www/abc - </VirtualHost> -</pre></blockquote> - -<h3>Denial of Service</h3> - -<p>There are (at least) two forms that denial of service can come in. -If you are running a version of Apache prior to version 1.2 then your -server will not even boot if one of the two DNS lookups mentioned above -fails for any of your virtual hosts. In some cases this DNS lookup may -not even be under your control. For example, if <code>abc.dom</code> -is one of your customers and they control their own DNS then they -can force your (pre-1.2) server to fail while booting simply by deleting the -<code>www.abc.dom</code> record. - -<p>Another form is far more insidious. Consider this configuration -snippet: - -<blockquote><pre> - <VirtualHost www.abc.dom> - ServerAdmin webgirl@abc.dom - DocumentRoot /www/abc - </VirtualHost> -</pre></blockquote> - -<blockquote><pre> - <VirtualHost www.def.dom> - ServerAdmin webguy@def.dom - DocumentRoot /www/def - </VirtualHost> -</pre></blockquote> - -<p>Suppose that you've assigned 10.0.0.1 to <code>www.abc.dom</code> and -10.0.0.2 to <code>www.def.dom</code>. Furthermore, suppose that -<code>def.com</code> has control of their own DNS. With this config -you have put <code>def.com</code> into a position where they can steal -all traffic destined to <code>abc.com</code>. To do so, all they have to -do is set <code>www.def.dom</code> to 10.0.0.1. -Since they control their own DNS you can't stop them from pointing the -<code>www.def.com</code> record wherever they wish. - -<p>Requests coming in to 10.0.0.1 (including all those where users typed -in URLs of the form <code>http://www.abc.dom/whatever</code>) will all be -served by the <code>def.com</code> virtual host. To better understand why -this happens requires a more in-depth discussion of how Apache matches -up incoming requests with the virtual host that will serve it. A rough -document describing this <a href="vhosts-in-depth.html"> is available</a>. - -<h3>The "main server" Address</h3> - -<p>The addition of <a href="host.html">non-IP-based virtual host -support</a> in Apache 1.1 requires Apache to know the IP address(es) of -the host that httpd is running on. To get this address it uses either -the global <code>ServerName</code> (if present) or calls the C function -<code>gethostname</code> (which should return the same as typing -"hostname" at the command prompt). Then it performs a DNS lookup on -this address. At present there is no way to avoid this lookup. - -<p>If you fear that this lookup might fail because your DNS server is down -then you can insert the hostname in <code>/etc/hosts</code> (where you -probably already have it so that the machine can boot properly). Then -ensure that your machine is configured to use <code>/etc/hosts</code> -in the event that DNS fails. Depending on what OS you are using this -might be accomplished by editing <code>/etc/resolv.conf</code>, or maybe -<code>/etc/nsswitch.conf</code>. - -<p>If your server doesn't have to perform DNS for any other reason -then you might be able to get away with running Apache with the -<code>HOSTRESORDER</code> environment variable set to "local". This all -depends on what OS and resolver libraries you are using. It also affects -CGIs unless you use <a href="mod/mod_env.html"><code>mod_env</code></a> -to control the environment. It's best to consult the man pages or FAQs -for your OS. - -<h3>The _default_ Address</h3> - -<p>Any address that happens to go to your webserver which doesn't match -the IP address of any of the webservers will be served from the "main" or -"default" server configurations. The "main" server configuration consists -of all those definitions appearing outside of any VirtualHost section. -You may want instead to define a <code><VirtualHost _default_:*></code> -which returns 403 or 404 for all hits. (The trailing <code>:*</code> -makes it apply to all ports, which is just a safety measure should you -begin using multiple <code><a href="mod/core.html#listen">Listen</a></code> -directives.) - -<h3><a name="tips">Tips to Avoid these problems</a></h3> - -<ul> -<li> use IP addresses in <code><VirtualHost></code> -<li> use IP addresses in <code>Listen</code> -<li> use IP addresses in <code>BindAddress</code> -<li> ensure all virtual hosts have an explicit <code>ServerName</code> -<li> create a <code><VirtualHost _default_:*></code> server that - has no pages to serve -</ul> - -<h3>Appendix: Future Directions</h3> - -<p>The situation regarding DNS is highly undesirable. For Apache -1.2 we've attempted to make the server at least continue booting -in the event of failed DNS, but it might not be the best we -can do. In any event requiring the use of explicit IP addresses in -configuration files is highly undesirable in today's Internet where <a -href="http://www.ietf.org/html.charters/pier-charter.html">renumbering -</a> is a necessity. - -<p>A possible work around to the theft of service attack described above -would be to perform a reverse DNS lookup on the ip address returned by -the forward lookup and compare the two names. In the event of a mismatch -the virtualhost would be disabled. This would require reverse DNS to be -configured properly (which is something that most admins are familiar with -because of the common use of "double-reverse" DNS lookups by FTP servers -and TCP wrappers). - -<p>In any event it doesn't seem possible to reliably boot a virtual-hosted -web server when DNS has failed unless IP addresses are used. Partial -solutions such as disabling portions of the configuration might be worse -than not booting at all depending on what the webserver is supposed -to accomplish. - -<p>As HTTP/1.1 is deployed and browsers and proxies start issuing the -<code>Host</code> header it will become possible to avoid the use of -IP-based virtual hosts entirely. In this event a webserver has no requirement -to do DNS lookups during configuration. But as of March 1997 these -features have not been deployed widely enough to be put into use on -critical webservers. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/env.html b/docs/manual/env.html deleted file mode 100644 index 9ef4f28ff0..0000000000 --- a/docs/manual/env.html +++ /dev/null @@ -1,41 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Special Purpose Environment Variables</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">Special Purpose Environment Variables</h1> -<P>Interoperability problems have led to the introduction of -mechanisms to modify the way Apache behaves when talking to particular -clients. To make these mechanisms as flexible as possible, they -are invoked by defining environment variables, typically with -<A HREF="mod/mod_browser.html#browsermatch">BrowserMatch</A>, though -<A HREF="mod/mod_env.html#setenv">SetEnv</A> and -<A HREF="mod/mod_env.html#passenv">PassEnv</A> could also be used, for -example.</P> - -<H2>nokeepalive</H2> -This disables <A HREF="mod/core.html#keepalive">KeepAlive</A> when set. Because -of problems with Netscape 2.x and KeepAlive, we recommend the following -directive be used: -<BLOCKQUOTE><CODE> -BrowserMatch Mozilla/2 nokeepalive -</CODE></BLOCKQUOTE> -<H2>force-response-1.0</H2> -This forces an HTTP/1.0 response when set. It was originally implemented as a -result of a problem with AOL's proxies. Some clients may not behave correctly -when given an HTTP/1.1 response, and this can be used to interoperate with -them. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/env.html.en b/docs/manual/env.html.en deleted file mode 100644 index 9ef4f28ff0..0000000000 --- a/docs/manual/env.html.en +++ /dev/null @@ -1,41 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Special Purpose Environment Variables</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">Special Purpose Environment Variables</h1> -<P>Interoperability problems have led to the introduction of -mechanisms to modify the way Apache behaves when talking to particular -clients. To make these mechanisms as flexible as possible, they -are invoked by defining environment variables, typically with -<A HREF="mod/mod_browser.html#browsermatch">BrowserMatch</A>, though -<A HREF="mod/mod_env.html#setenv">SetEnv</A> and -<A HREF="mod/mod_env.html#passenv">PassEnv</A> could also be used, for -example.</P> - -<H2>nokeepalive</H2> -This disables <A HREF="mod/core.html#keepalive">KeepAlive</A> when set. Because -of problems with Netscape 2.x and KeepAlive, we recommend the following -directive be used: -<BLOCKQUOTE><CODE> -BrowserMatch Mozilla/2 nokeepalive -</CODE></BLOCKQUOTE> -<H2>force-response-1.0</H2> -This forces an HTTP/1.0 response when set. It was originally implemented as a -result of a problem with AOL's proxies. Some clients may not behave correctly -when given an HTTP/1.1 response, and this can be used to interoperate with -them. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/expand.pl b/docs/manual/expand.pl deleted file mode 100644 index 37483ad0bd..0000000000 --- a/docs/manual/expand.pl +++ /dev/null @@ -1,100 +0,0 @@ -#!/usr/local/bin/perl5 - -# This is a very simple Perl script to expand server-side includes -# in the directory it is run, and direct subdirectories. It will -# work only on SSI directives of the form -# -# <!--#include virtual="filename" --> -# -# Filename must be relative to the directory the file appears in. -# -# Nov 30, 1996 - Alexei Kosut <akosut@apache.org> - -# ==================================================================== -# Copyright (c) 1996,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. -# ==================================================================== -# -# This software consists of voluntary contributions made by many -# individuals on behalf of the Apache Group and was originally based -# on public domain software written at the National Center for -# Supercomputing Applications, University of Illinois, Urbana-Champaign. -# For more information on the Apache Group and the Apache HTTP server -# project, please see <http://www.apache.org/>. - -# Put a list of dirs (except ..) into @dirs - -opendir DIR, "." or die "Could not open directory: $!"; -@dirs = grep !/^\.\.$/, (grep -d, readdir DIR); -closedir DIR; - -foreach $dir (@dirs) { - print "Entering directory $dir\n"; - opendir SUBDIR, "$dir" or die "Could not open subdir $dir: $!"; - foreach $file (grep /\.html$/, readdir SUBDIR) { - print "Expanding file $dir/$file\n"; - rename "$dir/$file", "$dir/${file}.old"; - open READ, "$dir/${file}.old" or die "Couldn't read $dir/$file: $!"; - open WRITE, ">$dir/$file" or die "Couldn't write $dir/$file: $!"; - while ($r = <READ>) { - if ($r =~ /<!--#include virtual="(.*)" -->/) { - ($pre, $include, $post) = ($`, $1, $'); - print WRITE $pre; - - open INC, "$dir/$include" or - print "Could not include file $dir/$include: $!"; - print WRITE while (<INC>); - close INC; - - print WRITE $post; - } - else { - print WRITE $r; - } - } - close READ; - close WRITE; - unlink "$dir/$file.old"; - } - closedir SUBDIR; -} - - diff --git a/docs/manual/footer.html b/docs/manual/footer.html deleted file mode 100644 index d1f330db4b..0000000000 --- a/docs/manual/footer.html +++ /dev/null @@ -1,3 +0,0 @@ -<HR> - -<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> diff --git a/docs/manual/handler.html b/docs/manual/handler.html deleted file mode 100644 index 8059216112..0000000000 --- a/docs/manual/handler.html +++ /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/handler.html.en b/docs/manual/handler.html.en deleted file mode 100644 index 8059216112..0000000000 --- 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/header.html b/docs/manual/header.html deleted file mode 100644 index a6e66f69a1..0000000000 --- a/docs/manual/header.html +++ /dev/null @@ -1,3 +0,0 @@ -<DIV ALIGN="CENTER"> - <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> -</DIV> diff --git a/docs/manual/images/home.gif b/docs/manual/images/home.gif Binary files differdeleted file mode 100644 index 11299c1cb7..0000000000 --- a/docs/manual/images/home.gif +++ /dev/null diff --git a/docs/manual/images/index.gif b/docs/manual/images/index.gif Binary files differdeleted file mode 100644 index 741c8939d7..0000000000 --- a/docs/manual/images/index.gif +++ /dev/null diff --git a/docs/manual/images/sub.gif b/docs/manual/images/sub.gif Binary files differdeleted file mode 100644 index 93061c5ad7..0000000000 --- a/docs/manual/images/sub.gif +++ /dev/null diff --git a/docs/manual/install.html b/docs/manual/install.html deleted file mode 100644 index 52e84b0c54..0000000000 --- a/docs/manual/install.html +++ /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/install.html.en b/docs/manual/install.html.en deleted file mode 100644 index 52e84b0c54..0000000000 --- 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 b/docs/manual/invoking.html deleted file mode 100644 index 62e6a41af9..0000000000 --- a/docs/manual/invoking.html +++ /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/invoking.html.en b/docs/manual/invoking.html.en deleted file mode 100644 index 62e6a41af9..0000000000 --- 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/location.html b/docs/manual/location.html deleted file mode 100644 index 96ab3a8544..0000000000 --- a/docs/manual/location.html +++ /dev/null @@ -1,59 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Access Control by URL</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">Access Control by URL</H1> - -<h2><a name="location">The <code><Location></code> Directive</a></h2> - -<strong>Syntax:</strong> <Location <em>URL prefix</em>><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<br> - -<p>The <Location> directive provides for access control by -URL. It is comparable to the <a -href="mod/core.html#directory"><Directory></a> directive, and -should be matched with a </Location> directive. Directives that -apply to the URL given should be listen -within. <code><Location></code> sections are processed in the -order they appear in the configuration file, after the -<Directory> sections and <code>.htaccess</code> files are -read.</p> - -<p>Note that, due to the way HTTP functions, <em>URL prefix</em> -should, save for proxy requests, be of the form <code>/path/</code>, -and should not include the <code>http://servername</code>. It doesn't -necessarily have to protect a directory (it can be an individual -file, or a number of files), and can include wild-cards. In a wild-card -string, `?' matches any single character, and `*' matches any -sequences of characters. - -<p>This functionality is especially useful when combined with the -<code><a href="mod/mod_mime.html#sethandler">SetHandler</a></code> -directive. For example, to enable status requests, but allow them only -from browsers at foo.com, you might use: - -<pre> - <Location /status> - SetHandler server-status - order deny,allow - deny from all - allow from .foo.com - </Location> -</pre> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/misc/API.html b/docs/manual/misc/API.html deleted file mode 100644 index ad539e2abb..0000000000 --- a/docs/manual/misc/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/misc/FAQ.html b/docs/manual/misc/FAQ.html deleted file mode 100644 index 94d257d661..0000000000 --- a/docs/manual/misc/FAQ.html +++ /dev/null @@ -1,1397 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Server Frequently Asked Questions</TITLE> - </HEAD> - - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> - <P> - $Revision: 1.63 $ ($Date: 1997/06/04 11:42:55 $) - </P> - <P> - The latest version of this FAQ is always available from the main - Apache web site, at - <<A - HREF="http://www.apache.org/docs/misc/FAQ" - REL="Help" - ><SAMP>http://www.apache.org/docs/misc/FAQ</SAMP></A>>. - </P> -<!-- Notes about changes: --> -<!-- - If adding a relative link to another part of the --> -<!-- documentation, *do* include the ".html" portion. There's a --> -<!-- good chance that the user will be reading the documentation --> -<!-- on his own system, which may not be configured for --> -<!-- multiviews. Leave off the ".html" extension for absolute --> -<!-- links to sites which are known to run multiviews (e.g., --> -<!-- 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 forget to include an HR tag after the last /P tag --> -<!-- but before the /LI in an item. --> - <P> - If you are reading a text-only version of this FAQ, you may find numbers - enclosed in brackets (such as "[12]"). These refer to the list of - reference URLs to be found at the end of the document. These references - do not appear, and are not needed, for the hypertext version. - </P> - <H2>The Questions</H2> -<!-- Stuff to Add: --> -<!-- - can't bind to port 80 --> -<!-- - permission denied --> -<!-- - address already in use --> -<!-- - mod_auth & passwd lines "user:pw:.*" - ++1st colon onward is --> -<!-- treated as pw, not just ++1st to --2nd. --> -<!-- - SSL: --> -<!-- Can I use Apache-SSL for free in Canada? --> -<!-- Why can't I use Apache-SSL in the U.S.? --> -<!-- - How can I found out how many visitors my site gets? --> -<!-- - How do I add a counter? --> -<!-- - How do I configure Apache as a proxy? --> -<!-- - What browsers support HTTP/1.1? --> -<!-- - What's the point of vhosts-by-name is there aren't any --> -<!-- HTTP/1.1 browsers? --> -<!-- - Is there an Apache for W95/WNT? --> -<!-- - Why does Apache die when a vhost can't be DNS-resolved? --> -<!-- - 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? --> -<!-- - How do I add a footer to all pages offered by my server? --> -<UL> - <LI><STRONG>Background</STRONG> - <OL START=1> - <LI><A HREF="#what">What is Apache?</A> - </LI> - <LI><A HREF="#why">Why was Apache created?</A> - </LI> - <LI><A HREF="#relate">How does The Apache Group's work relate to - other servers?</A> - </LI> - <LI><A HREF="#name">Why the name "Apache"?</A> - </LI> - <LI><A HREF="#compare">OK, so how does Apache compare to other servers?</A> - </LI> - <LI><A HREF="#tested">How thoroughly tested is Apache?</A> - </LI> - <LI><A HREF="#future">What are the future plans for Apache?</A> - </LI> - <LI><A HREF="#support">Whom do I contact for support?</A> - </LI> - <LI><A HREF="#more">Is there any more information on Apache?</A> - </LI> - <LI><A HREF="#where">Where can I get Apache?</A> - </LI> - </OL> - </LI> - <LI><STRONG>Technical Questions</STRONG> - <OL START=11> - <LI><A HREF="#what2do">"Why can't I ...? Why won't ... - work?" What to do in case of problems</A> - </LI> - <LI><A HREF="#compatible">How compatible is Apache with my existing - NCSA 1.3 setup?</A> - </LI> - <LI><A HREF="#CGIoutsideScriptAlias">How do I enable CGI execution - in directories other than the ScriptAlias?</A> - </LI> - <LI><A HREF="#premature-script-headers">What does it mean when my - CGIs fail with "<SAMP>Premature end of script - headers</SAMP>"?</A> - </LI> - <LI><A HREF="#ssi-part-i">How do I enable SSI (parsed HTML)?</A> - </LI> - <LI><A HREF="#ssi-part-ii">Why don't my parsed files get cached?</A> - </LI> - <LI><A HREF="#ssi-part-iii">How can I have my script output parsed?</A> - </LI> - <LI><A HREF="#proxy">Does or will Apache act as a Proxy server?</A> - </LI> - <LI><A HREF="#multiviews">What are "multiviews"?</A> - </LI> - <LI><A HREF="#fdlim">Why can't I run more than <<EM>n</EM>> - virtual hosts?</A> - </LI> - <LI><A HREF="#limitGET">Why do I keep getting "access denied" for - form POST requests?</A> - </LI> - <LI><A HREF="#passwdauth">Can I use my <SAMP>/etc/passwd</SAMP> file - for Web page authentication?</A> - </LI> - <LI><A HREF="#errordoc401">Why doesn't my <CODE>ErrorDocument - 401</CODE> work?</A> - </LI> - <LI><A HREF="#setgid">Why do I get "<SAMP>setgid: Invalid - argument</SAMP>" at startup?</A> - </LI> - <LI><A HREF="#cookies1">Why does Apache send a cookie on every response?</A> - </LI> - <LI><A HREF="#cookies2">Why don't my cookies work, I even compiled in - <SAMP>mod_cookies</SAMP>?</A> - </LI> - <LI><A HREF="#jdk1-and-http1.1">Why do my Java app[let]s give me plain text - when I request an URL from an Apache server?</A> - </LI> - <LI><A HREF="#putsupport">Why can't I publish to my Apache server - using PUT on Netscape Gold and other programs?</A> - </LI> - <LI><A HREF="#fastcgi">Why isn't FastCGI included with Apache any - more?</A> - </LI> - <LI><A HREF="#nodelay">Why am I getting "<SAMP>httpd: could not - set socket option TCP_NODELAY</SAMP>" in my error log?</A> - </LI> - <LI><A HREF="#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> - </LI> - <LI><A HREF="#wheres-the-dump">The errorlog says Apache dumped core, - but where's the dump file?</A> - </LI> - <LI><A HREF="#dnsauth">Why isn't restricting access by host or domain name - working correctly?</A> - </LI> - <LI><A HREF="#SSL-i">Why doesn't Apache include SSL?</A> - </LI> - <LI><A HREF="#HPUX-core">Why do I get core dumps under HPUX using - HP's ANSI C compiler?</A> - </LI> - <LI><A HREF="#midi">How do I get Apache to send a MIDI file so the - browser can play it?</A> - </LI> - <LI><A HREF="#cantbuild">Why won't Apache compile with my - system's <SAMP>cc</SAMP>?</A> - </LI> - <LI><A HREF="#addlog">How do I add browsers and referrers to my - logs?</A> - </LI> - </OL> - </LI> -</UL> - -<HR> - - <H2>The Answers</H2> - <P> - </P> - <H3> - Background - </H3> -<OL START=1> - <LI><A NAME="what"> - <STRONG>What is Apache?</STRONG> - </A> - <P> - Apache was originally based on code and ideas found in the most - popular HTTP server of the time.. NCSA httpd 1.3 (early 1995). It has - since evolved into a far superior system which can rival (and probably - surpass) almost any other UNIX based HTTP server in terms of functionality, - efficiency and speed. - </P> - <P> - Since it began, it has been completely rewritten, and includes many new - features. Apache is, as of January 1997, the most popular WWW server on - the Internet, according to the - <A - HREF="http://www.netcraft.com/Survey/" - >Netcraft Survey</A>. - </P> - <HR> - </LI> - <LI><A NAME="why"> - <STRONG>Why was Apache created?</STRONG> - </A> - <P> - To address the concerns of a group of WWW providers and part-time httpd - 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> - </LI> - <LI><A NAME="relate"> - <STRONG>How does The Apache Group's work relate to other - server efforts, such as NCSA's?</STRONG> - </A> - <P> - We, of course, owe a great debt to NCSA and their programmers for - making the server Apache was based on. We now, however, have our own - server, and our project is mostly our own. The Apache Project is an - entirely independent venture. - </P> - <HR> - </LI> - <LI><A NAME="name"> - <STRONG>Why the name "Apache"?</STRONG> - </A> - <P> - A cute name which stuck. Apache is "<STRONG>A - PA</STRONG>t<STRONG>CH</STRONG>y server". It was - based on some existing code and a series of "patch files". - </P> - <HR> - </LI> - <LI><A NAME="compare"> - <STRONG>OK, so how does Apache compare to other servers?</STRONG> - </A> - <P> - For an independent assessment, see - <A - HREF="http://webcompare.iworld.com/compare/chart.html" - >Web Compare</A>'s - comparison chart. - </P> - <P> - Apache has been shown to be substantially faster than many other - free servers. Although certain commercial servers have claimed to - surpass Apache's speed (it has not been demonstrated that any of these - "benchmarks" are a good way of measuring WWW server speed at any - rate), we feel that it is better to have a mostly-fast free server - than an extremely-fast server that costs thousands of dollars. Apache - is run on sites that get millions of hits per day, and they have - experienced no performance difficulties. - </P> - <HR> - </LI> - <LI><A NAME="tested"> - <STRONG>How thoroughly tested is Apache?</STRONG> - </A> - <P> - Apache is run on over 400,000 Internet servers (as of April 1997). It has - been tested thoroughly by both developers and users. The Apache Group - maintains rigorous standards before releasing new versions of their - server, and our server runs without a hitch on over one third of all - WWW servers available on the Internet. When bugs do show up, we - release patches and new versions as soon as they are available. - </P> - <P> - The Apache project's web site includes a page with a partial list of - <A - HREF="http://www.apache.org/info/apache_users" - >sites running Apache</A>. - </P> - <HR> - </LI> - <LI><A NAME="future"> - <STRONG>What are the future plans for Apache?</STRONG> - </A> - <P> - <UL> - <LI>to continue as a public domain HTTP server, - </LI> - <LI>to keep up with advances in HTTP protocol and web developments in - general, - </LI> - <LI>to collect suggestions for fixes/improvements from its users, - </LI> - <LI>to respond to needs of large volume providers as well as - occasional users. - </LI> - </UL> - </P> - <HR> - </LI> - <LI><A NAME="support"> - <STRONG>Whom do I contact for support?</STRONG> - </A> - <P> - There is no official support for Apache. None of the developers want to - be swamped by a flood of trivial questions that can be resolved elsewhere. - Bug reports and suggestions should be sent <EM>via</EM> - <A - HREF="http://www.apache.org/bug_report" - >the bug report page</A>. - Other questions should be directed to the - <A - HREF="news:comp.infosystems.www.servers.unix" - ><SAMP>comp.infosystems.www.servers.unix</SAMP></A> - newsgroup, where some of the Apache team lurk, - in the company of many other httpd gurus who should be able - to help. - </P> - <P> - Commercial support for Apache is, however, available from a number - of third parties. - </P> - <HR> - </LI> - <LI><A NAME="more"> - <STRONG>Is there any more information available on - Apache?</STRONG> - </A> - <P> - Indeed there is. See the main - <A - HREF="http://www.apache.org/" - >Apache web site</A>. - There is also a regular electronic publication called - <A - HREF="http://www.apacheweek.com/" - REL="Help" - ><CITE>Apache Week</CITE></A> - available. Links to relevant <CITE>Apache Week</CITE> articles are - included below where appropriate. - </P> - <HR> - </LI> - <LI><A NAME="where"> - <STRONG>Where can I get Apache?</STRONG> - </A> - <P> - You can find out how to download the source for Apache at the - project's - <A - HREF="http://www.apache.org/" - >main web page</A>. - </P> - <HR> - </LI> -</OL> - <H3> - Technical Questions - </H3> -<OL START=11> - <LI><A NAME="what2do"> - <STRONG>"Why can't I ...? Why won't ... work?" What to - do in case of problems</STRONG> - </A> - <P> - If you are having trouble with your Apache server software, you should - take the following steps: - </P> - <OL> - <LI><STRONG>Check the errorlog!</STRONG> - <P> - Apache tries to be helpful when it encounters a problem. In many - cases, it will provide some details by writing one or messages to - the server error log. Sometimes this is enough for you to diagnose - & fix the problem yourself (such as file permissions or the like). - The default location of the error log is - <CODE>/usr/local/etc/httpd/logs/error_log</CODE>, but see the - <A - HREF="../mod/core.html#errorlog" - ><SAMP>ErrorLog</SAMP></A> - directive in your config files for the location on your server. - </P> - </LI> - <LI><STRONG>Check the - <A - HREF="http://www.apache.org/docs/misc/FAQ.html" - >FAQ</A>!</STRONG> - <P> - The latest version of the Apache Frequently-Asked Questions list can - always be found at the main Apache web site. - </P> - </LI> - <LI><STRONG>Check the Apache bug database</STRONG> - <P> - Most problems that get reported to The Apache Group are recorded in - the - <A - HREF="http://www.apache.org/bugdb.cgi" - >bug database</A>. - <EM><STRONG>Please</STRONG> check the existing reports, open - <STRONG>and</STRONG> closed, before adding one.</EM> If you find - that your issue has already been reported, please <EM>don't</EM> add - a "me, too" report. If the original report isn't closed - yet, we suggest that you check it periodically. You might also - consider contacting the original submitter, because there may be an - email exchange going on about the issue that isn't getting recorded - in the database. - </P> - </LI> - <LI><STRONG>Ask in the <SAMP>comp.infosystems.www.servers.unix</SAMP> - USENET newsgroup</STRONG> - <P> - A lot of common problems never make it to the bug database because - there's already high Q&A traffic about them in the - <A - HREF="news:comp.infosystems.www.servers.unix" - ><SAMP>comp.infosystems.www.servers.unix</SAMP></A> - newsgroup. Many Apache users, and some of the developers, can be - found roaming its virtual halls, so it is suggested that you seek - wisdom there. The chances are good that you'll get a faster answer - there than from the bug database, even if you <EM>don't</EM> see - your question already posted. - </P> - </LI> - <LI><STRONG>If all else fails, report the problem in the bug - database</STRONG> - <P> - If you've gone through those steps above that are appropriate and - have obtained no relief, then please <EM>do</EM> let The Apache - Group know about the problem by - <A - HREF="http://www.apache.org/bugdb.cgi" - >logging a bug report</A>. - </P> - <P> - If your problem involves the server crashing and generating a core - dump, please include a backtrace (if possible). As an example, - </P> - <P> - <CODE> - <DL> - <DD># cd <EM>ServerRoot</EM> - </DD> - <DD># dbx httpd core - </DD> - <DD>(dbx) where - </DD> - </DL> - </CODE> - </P> - <P> - (Substitute the appropriate locations for your - <SAMP>ServerRoot</SAMP> and your <SAMP>httpd</SAMP> and - <SAMP>core</SAMP> files. You may have to use <CODE>gdb</CODE> - instead of <CODE>dbx</CODE>.) - </P> - </LI> - </OL> - <HR> - </LI> - <LI><A NAME="compatible"> - <STRONG>How compatible is Apache with my existing NCSA 1.3 - setup?</STRONG> - </A> - <P> - Apache attempts to offer all the features and configuration options - of NCSA httpd 1.3, as well as many of the additional features found in - NCSA httpd 1.4 and NCSA httpd 1.5. - </P> - <P> - NCSA httpd appears to be moving toward adding experimental features - which are not generally required at the moment. Some of the experiments - will succeed while others will inevitably be dropped. The Apache - philosophy is to add what's needed as and when it is needed. - </P> - <P> - Friendly interaction between Apache and NCSA developers should ensure - that fundamental feature enhancements stay consistent between the two - servers for the foreseeable future. - </P> - <HR> - </LI> - <LI><A NAME="CGIoutsideScriptAlias"> - <STRONG>How do I enable CGI execution in directories other than - the ScriptAlias?</STRONG> - </A> - <P> - Apache recognizes all files in a directory named as a - <A - HREF="../mod/mod_alias.html#scriptalias" - ><SAMP>ScriptAlias</SAMP></A> - as being eligible for execution rather than processing as normal - documents. This applies regardless of the file name, so scripts in a - ScriptAlias directory don't need to be named - "<SAMP>*.cgi</SAMP>" or "<SAMP>*.pl</SAMP>" or - whatever. In other words, <EM>all</EM> files in a ScriptAlias - directory are scripts, as far as Apache is concerned. - </P> - <P> - To persuade Apache to execute scripts in other locations, such as in - directories where normal documents may also live, you must tell it how - to recognize them - and also that it's okay to execute them. For - this, you need to use something like the - <A - HREF="../mod/mod_mime.html#addhandler" - ><SAMP>AddHandler</SAMP></A> - directive. - </P> - <OL> - <LI>In an appropriate section of your server configuration files, add - a line such as - <P> - <DL> - <DD><CODE>AddHandler cgi-script .cgi</CODE> - </DD> - </DL> - </P> - The server will then recognize that all files in that location (and - its logical descendants) that end in "<SAMP>.cgi</SAMP>" - are script files, not documents. - </LI> - <LI>Make sure that the directory location is covered by an - <A - HREF="../mod/core.html#options" - ><SAMP>Options</SAMP></A> - declaration that includes the <SAMP>ExecCGI</SAMP> option. - </LI> - </OL> - <HR> - </LI> - <LI><A NAME="premature-script-headers"> - <STRONG>What does it mean when my CGIs fail with - "<SAMP>Premature end of script headers</SAMP>"?</STRONG> - </A> - <P> - It means just what it says: the server was expecting a complete set of - HTTP headers (one or more followed by a blank line), and didn't get - them. 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: - </P> - <P> - <CODE> - <DL> - <DD>$cfh = select (STDOUT); - </DD> - <DD>$| = 1; - </DD> - <DD>select ($cfh); - </DD> - </DL> - </CODE> - </P> - <P> - This is generally only necessary when you are calling external - programs from your script that send output to stdout. - <P> - If your script isn't written in Perl, do the equivalent thing for - whatever language you <EM>are</EM> using (<EM>e.g.</EM>, for C, call - <CODE>fflush()</CODE> after writing the headers). - </P> - <HR> - </LI> - <LI><A NAME="ssi-part-i"> - <STRONG>How do I enable SSI (parsed HTML)?</STRONG> - </A> - <P> - SSI (an acronym for Server-Side Include) directives allow static HTML - documents to be enhanced at run-time (<EM>e.g.</EM>, when delivered to - a client by Apache). The format of SSI directives is covered - in the <A HREF="../mod/mod_include.html">mod_include manual</A>; - suffice it to say that Apache supports not only SSI but - xSSI (eXtended SSI) directives. - </P> - <P> - Processing a document at run-time is called <EM>parsing</EM> it; hence - the term "parsed HTML" sometimes used for documents that - contain SSI instructions. Parsing tends to be <EM>extremely</EM> - resource-consumptive, and is not enabled by default. - </P> - <P> - To enable SSI processing, you need to - </P> - <UL> - <LI>Build your server with the - <A - HREF="../mod/mod_include.html" - ><SAMP>mod_include</SAMP></A> - module. This is normally compiled in by default. - </LI> - <LI>Make sure your server configuration files have an - <A - HREF="../mod/core.html#options" - ><SAMP>Options</SAMP></A> - directive which permits <SAMP>Includes</SAMP>. - </LI> - <LI>Make sure that the directory where you want the SSI documents to - live is covered by the "server-parsed" content handler, - either explicitly or in some ancestral location. That can be done - with the following - <A - HREF="../mod/mod_mime.html#addhandler" - ><SAMP>AddHandler</SAMP></A> - directive: - <P> - <DL> - <DD><CODE>AddHandler server-parsed .shtml</CODE> - </DD> - </DL> - </P> - This indicates that all files ending in ".shtml" in that - location (or its descendants) should be parsed. Note that using - ".html" will cause all normal HTML files to be parsed, - which may put an inordinate load on your server. - </LI> - </UL> - <P> - For additional information, see the <CITE>Apache Week</CITE> article - on - <A - HREF="http://www.apacheweek.com/features/ssi" - REL="Help" - ><CITE>Using Server Side Includes</CITE></A>. - </P> - <HR> - </LI> - <LI><A NAME="ssi-part-ii"> - <STRONG>Why don't my parsed files get cached?</STRONG> - </A> - <P> - Since the server is performing run-time processing of your SSI - directives, which may change the content shipped to the client, it - can't know at the time it starts parsing what the final size of the - result will be, or whether the parsed result will always be the same. - This means that it can't generate <SAMP>Content-Length</SAMP> or - <SAMP>Last-Modified</SAMP> headers. Caches commonly work by comparing - the <SAMP>Last-Modified</SAMP> of what's in the cache with that being - delivered by the server. Since the server isn't sending that header - for a parsed document, whatever's doing the caching can't tell whether - the document has changed or not - and so fetches it again to be on the - safe side. - </P> - <P> - You can work around this in some cases by causing an - <SAMP>Expires</SAMP> header to be generated. (See the - <A - HREF="../mod/mod_expires.html" - REL="Help" - ><SAMP>mod_expires</SAMP></A> - documentation for more details.) Another possibility is to use the - <A - HREF="../mod/mod_include.html#xbithack" - REL="Help" - ><SAMP>XBitHack Full</SAMP></A> - mechanism, which tells Apache to send (under certain circumstances - detailed in the XBitHack directive description) a - <SAMP>Last-Modified</SAMP> header based upon the last modification - time of the file being parsed. Note that this may actually be lying - to the client if the parsed file doesn't change but the SSI-inserted - content does; if the included content changes often, this can result - in stale copies being cached. - </P> - <HR> - </LI> - <LI><A NAME="ssi-part-iii"> - <STRONG>How can I have my script output parsed?</STRONG> - </A> - <P> - So you want to include SSI directives in the output from your CGI - script, but can't figure out how to do it? - The short answer is "you can't." This is potentially - a security liability and, more importantly, it can not be cleanly - implemented under the current server API. The best workaround - is for your script itself to do what the SSIs would be doing. - After all, it's generating the rest of the content. - </P> - <P> - This is a feature The Apache Group hopes to add in the next major - release after 1.2. - </P> - <HR> - </LI> - <LI><A NAME="proxy"> - <STRONG>Does or will Apache act as a Proxy server?</STRONG> - </A> - <P> - Apache version 1.1 and above comes with a proxy module. If compiled - in, this will make Apache act as a caching-proxy server. - </P> - <HR> - </LI> - <LI><A NAME="multiviews"> - <STRONG>What are "multiviews"?</STRONG> - </A> - <P> - "Multiviews" is the general name given to the Apache - server's ability to provide language-specific document variants in - response to a request. This is documented quite thoroughly in the - <A - HREF="../content-negotiation.html" - REL="Help" - >content negotiation</A> - description page. In addition, <CITE>Apache Week</CITE> carried an - article on this subject entitled - "<A - HREF="http://www.apacheweek.com/features/negotiation" - REL="Help" - ><CITE>Content Negotiation Explained</CITE></A>". - </P> - <HR> - </LI> - <LI><A NAME="fdlim"> - <STRONG>Why can't I run more than <<EM>n</EM>> - virtual hosts?</STRONG> - </A> - <P> - You are probably running into resource limitations in your - operating system. The most common limitation is the - <EM>per</EM>-process limit on <STRONG>file descriptors</STRONG>, - which is almost always the cause of problems seen when adding - virtual hosts. Apache often does not give an intuitive error - message because it is normally some library routine (such as - <CODE>gethostbyname()</CODE>) which needs file descriptors and - doesn't complain intelligibly when it can't get them. - </P> - <P> - Each log file requires a file descriptor, which means that if you are - using separate access and error logs for each virtual host, each - virtual host needs two file descriptors. Each - <A - HREF="../mod/core.html#listen" - ><SAMP>Listen</SAMP></A> - directive also needs a file descriptor. - </P> - <P> - Typical values for <<EM>n</EM>> that we've seen are in - the neighborhood of 128 or 250. When the server bumps into the file - descriptor limit, it may dump core with a SIGSEGV, it might just - hang, or it may limp along and you'll see (possibly meaningful) errors - in the error log. One common problem that occurs when you run into - a file descriptor limit is that CGI scripts stop being executed - properly. - </P> - <P> - As to what you can do about this: - </P> - <OL> - <LI>Reduce the number of - <A - HREF="../mod/core.html#listen" - ><SAMP>Listen</SAMP></A> - directives. If there are no other servers running on the machine - and all of them are running on the same port, you normally don't - need any Listen directives at all. - </LI> - <LI>Reduce the number of log files. You can use - <A - HREF="../mod/mod_log_config.html" - ><SAMP>mod_log_config</SAMP></A> - to log all requests to a single log file while including the name - of the virtual host in the log file. You can then write a - script to split the logfile into separate files later if - necessary. - </LI> - <LI>Increase the number of file descriptors available to the server - (see your system's documentation on the <CODE>limit</CODE> or - <CODE>ulimit</CODE> commands). For some systems, information on - how to do this is available in the - <A - HREF="perf.html" - >performance hints</A> - page. - </LI> - <LI>"Don't do that" - try to run with fewer virtual hosts - </LI> - <LI>Spread your operation across multiple server processes (using - <A - HREF="../mod/core.html#listen" - ><SAMP>Listen</SAMP></A> - for example, but see the first point) and/or ports. - </LI> - </OL> - <P> - Since this is an operating-system limitation, there's not much else - available in the way of solutions. - </P> - <HR> - <LI><A NAME="limitGET"> - <STRONG>Why do I keep getting "access denied" for form POST - requests?</STRONG> - </A> - <P> - The most common cause of this is a <SAMP><Limit></SAMP> section - that only names the <SAMP>GET</SAMP> method. Look in your - configuration files for something that resembles the following and - would affect the location where the POST-handling script resides: - </P> - <P> - <CODE> - <DL> - <DD><Limit GET> - </DD> - <DD> : - </DD> - </DL> - </CODE> - </P> - <P> - Change that to <SAMP><Limit GET POST></SAMP> and the problem - will probably go away. - </P> - <HR> - </LI> - <LI><A NAME="passwdauth"> - <STRONG>Can I use my <SAMP>/etc/passwd</SAMP> file - for Web page authentication?</STRONG> - </A> - <P> - Yes, you can - but it's a <STRONG>very bad idea</STRONG>. Here are - some of the reasons: - </P> - <UL> - <LI>The Web technology provides no governors on how often or how - rapidly password (authentication failure) retries can be made. That - means that someone can hammer away at your system's - <SAMP>root</SAMP> password using the Web, using a dictionary or - similar mass attack, just as fast as the wire and your server can - handle the requests. Most operating systems these days include - attack detection (such as <EM>n</EM> failed passwords for the same - account within <EM>m</EM> seconds) and evasion (breaking the - connection, disabling the account under attack, disabling - <EM>all</EM> logins from that source, <EM>et cetera</EM>), but the - Web does not. - </LI> - <LI>An account under attack isn't notified (unless the server is - heavily modified); there's no "You have 19483 login - failures" message when the legitimate owner logs in. - </LI> - <LI>Without an exhaustive and error-prone examination of the server - logs, you can't tell whether an account has been compromised. - Detecting that an attack has occurred, or is in progress, is fairly - obvious, though - <EM>if</EM> you look at the logs. - </LI> - <LI>Web authentication passwords (at least for Basic authentication) - generally fly across the wire, and through intermediate proxy - systems, in what amounts to plaintext. "O'er the net we - go/Caching all the way;/O what fun it is to surf/Giving my password - away!" - </LI> - <LI>Since HTTP is stateless, information about the authentication is - transmitted <EM>each and every time</EM> a request is made to the - server. Essentially, the client caches it after the first - successful access, and transmits it without asking for all - subsequent requests to the same server. - </LI> - <LI>It's relatively trivial for someone on your system to put up a - page that will steal the cached password from a client's cache - without them knowing. Can you say "password grabber"? - </LI> - </UL> - <P> - If you still want to do this in light of the above disadvantages, the - method is left as an exercise for the reader. It'll void your Apache - warranty, though, and you'll lose all accumulated UNIX guru points. - </P> - <HR> - <LI><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 - <A - HREF="../mod/core.html#errordocument" - ><SAMP>ErrorDocument</SAMP></A> - documentation for details. This was incorrectly documented in the past. - </P> - <HR> - </LI> - <LI><A NAME="setgid"> - <STRONG>Why do I get "<SAMP>setgid: Invalid - argument</SAMP>" at startup?</STRONG> - </A> - <P> - Your - <A - HREF="../mod/core.html#group" - ><SAMP>Group</SAMP></A> - directive (probably in <SAMP>conf/httpd.conf</SAMP>) needs to name a - group that actually exists in the <SAMP>/etc/group</SAMP> file (or - your system's equivalent). - </P> - <HR> - </LI> - <LI><A NAME="cookies1"> - <STRONG>Why does Apache send a cookie on every response?</STRONG> - </A> - <P> - Apache does <EM>not</EM> send automatically send a cookie on every - response, unless you have re-compiled it with the - <A - HREF="../mod/mod_cookies.html" - ><SAMP>mod_cookies</SAMP></A> - module. - This module was distributed with Apache prior to 1.2. - This module may help track users, and uses cookies to do this. If - you are not using the data generated by <SAMP>mod_cookies</SAMP>, do - not compile it into Apache. Note that in 1.2 this module was renamed - to the more correct name - <A - HREF="../mod/mod_usertrack.html" - ><SAMP>mod_usertrack</SAMP></A>, - and cookies - have to be specifically enabled with the - <A - HREF="../mod/mod_usertrack.html#cookietracking" - ><SAMP>CookieTracking</SAMP></A> - directive. - </P> - <HR> - </LI> - <LI><A NAME="cookies2"> - <STRONG>Why don't my cookies work, I even compiled in - <SAMP>mod_cookies</SAMP>? - </STRONG> - </A> - <P> - Firstly, you do <EM>not</EM> need to compile in - <SAMP>mod_cookies</SAMP> in order for your scripts to work (see the - <A - HREF="#cookies1" - >previous question</A> - for more about <SAMP>mod_cookies</SAMP>). Apache passes on your - <SAMP>Set-Cookie</SAMP> header fine, with or without this module. If - cookies do not work it will be because your script does not work - properly or your browser does not use cookies or is not set-up to - accept them. - </P> - <HR> - </LI> - <LI><A NAME="jdk1-and-http1.1"> - <STRONG>Why do my Java app[let]s give me plain text when I request - an URL from an Apache server?</STRONG> - </A> - <P> - As of version 1.2, Apache is an HTTP/1.1 (HyperText Transfer Protocol - version 1.1) server. This fact is reflected in the protocol version - that's included in the response headers sent to a client when - processing a request. Unfortunately, low-level Web access classes - included in the Java Development Kit (JDK) version 1.0.2 expect to see - the version string "HTTP/1.0" and do not correctly interpret - the "HTTP/1.1" value Apache is sending (this part of the - response is a declaration of what the server can do rather than a - declaration of the dialect of the response). The result - is that the JDK methods do not correctly parse the headers, and - include them with the document content by mistake. - </P> - <P> - This is definitely a bug in the JDK 1.0.2 foundation classes from Sun, - and it has been fixed in version 1.1. However, the classes in - question are part of the virtual machine environment, which means - they're part of the Web browser (if Java-enabled) or the Java - environment on the client system - so even if you develop - <EM>your</EM> classes with a recent JDK, the eventual users might - encounter the problem. - The classes involved are replaceable by vendors implementing the - Java virtual machine environment, and so even those that are based - upon the 1.0.2 version may not have this problem. - </P> - <P> - In the meantime, a workaround is to tell - Apache to "fake" an HTTP/1.0 response to requests that come - from the JDK methods; this can be done by including a line such as the - following in your server configuration files: - </P> - <P> - <DL> - <DD><CODE>BrowserMatch Java/1.0 force-response-1.0</CODE> - </DD> - </DL> - </P> - <P> - More information about this issue can be found in the - <A - HREF="http://www.apache.org/info/jdk-102" - ><CITE>Java and HTTP/1.1</CITE></A> - page at the Apache web site. - </P> - <HR> - </LI> - <LI><A NAME="putsupport"> - <STRONG>Why can't I publish to my Apache server using PUT on - Netscape Gold and other programs?</STRONG> - </A> - <P> - Because you need to install and configure a script to handle - the uploaded files. This script is often called a "PUT" handler. - There are several available, but they may have security problems. - Using FTP uploads may be easier and more secure, at least for now. - For more information, see the <CITE>Apache Week</CITE> article - <A - HREF="http://www.apacheweek.com/features/put" - ><CITE>Publishing Pages with PUT</CITE></A>. - </P> - <HR> - </LI> - <LI><A NAME="fastcgi"> - <STRONG>Why isn't FastCGI included with Apache any more?</STRONG> - </A> - <P> - The simple answer is that it was becoming too difficult to keep the - version being included with Apache synchronized with the master copy - at the - <A - HREF="http://www.fastcgi.com/servers/apache/" - >FastCGI web site</A>. When a new version of Apache was released, the - version of the FastCGI module included with it would soon be out of date. - </P> - <P> - You can still obtain the FastCGI module for Apache from the master - FastCGI web site. - </P> - <HR> - </LI> - <LI><A NAME="nodelay"> - <STRONG>Why am I getting "<SAMP>httpd: could not set socket - option TCP_NODELAY</SAMP>" in my error log?</STRONG> - </A> - <P> - This message almost always indicates that the client disconnected - before Apache reached the point of calling <CODE>setsockopt()</CODE> - for the connection. It shouldn't occur for more than about 1% of the - requests your server handles, and it's advisory only in any case. - </P> - <HR> - </LI> - <LI><A NAME="nph-scripts"> - <STRONG>How can I get my script's output without Apache buffering - it?</STRONG> - </A> - <P> - In order to improve network performance, Apache buffers script output - into relatively large chunks. If you have a script that sends - information in bursts (such as partial-done messages in a multi-commit - database transaction, perhaps), the client will not necessarily get - the output as the script is generating it. - </P> - <P> - To avoid this, Apache recognizes scripts whose names begin with - "<SAMP>nph-</SAMP>" as <EM>non-parsed-header</EM> scripts. - That is, Apache won't buffer their output, but connect it directly to - the socket going back to the client. - </P> - <P> - While this will probably do what you want, there <EM>are</EM> some - disadvantages to it: - </P> - <UL> - <LI><STRONG>YOU</STRONG> (the script) are responsible for generating - <STRONG>ALL</STRONG> of the HTTP headers, and no longer - <EM>just</EM> the "<SAMP>Content-type</SAMP>" or - "<SAMP>Location</SAMP>" headers - </LI> - <LI>Unless your script generates its output carefully, you will see a - performance penalty as excessive numbers of packets go back and forth - </LI> - </UL> - <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> - and then follow with your normal non-<SAMP>nph</SAMP> headers. - </P> - <HR> - </LI> - <LI><A NAME="linuxiovec"> - <STRONG>Why do I get complaints about redefinition - of `struct iovec' when compiling under Linux?</STRONG> - </A> - <P> - This is a conflict between your C library includes and your kernel - includes. You need to make sure that the versions of both are matched - properly. There are two workarounds, either one will solve the problem: - </P> - <UL> - <LI>Remove the definition of <CODE>struct iovec</CODE> from your C - library includes. It is located in <CODE>/usr/include/sys/uio.h</CODE>. - <STRONG>Or,</STRONG> - </LI> - <LI>Add <CODE>-DNO_WRITEV</CODE> to the <CODE>EXTRA_CFLAGS</CODE> - line in your <SAMP>Configuration</SAMP> and reconfigure/rebuild. - This hurts performance and should only be used as a last resort. - </LI> - </UL> - <HR> - </LI> - <LI><A NAME="wheres-the-dump"> - <STRONG>The errorlog says Apache dumped core, but where's the dump - file?</STRONG> - </A> - <P> - In Apache version 1.2 (beginning with 1.2b8), the error log message - about dumped core includes the directory where the dump file should be - located. However, many Unixes do not allow a process that has - called <CODE>setuid()</CODE> to dump core for security reasons; - the typical Apache setup has the server started as root to bind to - port 80, after which it changes UIDs to a non-privileged user to - serve requests. - </P> - <P> - Dealing with this is extremely operating system-specific, and may - require rebuilding your system kernel. Consult your operating system - documentation or vendor for more information about whether your system - does this and how to bypass it. If there <EM>is</EM> a documented way - of bypassing it, it is recommended that you bypass it only for the - <SAMP>httpd</SAMP> server process if possible. - </P> - <P> - The canonical location for Apache's core-dump files is the - <A - HREF="../mod/core.html#serverroot" - >ServerRoot</A> - directory. - </P> - <HR> - </LI> - <LI><A NAME="dnsauth"> - <STRONG>Why isn't restricting access by host or domain name - working correctly?</STRONG> - </A> - <P> - Two of the most common causes of this are: - </P> - <OL> - <LI><STRONG>An error, inconsistency, or unexpected mapping in the DNS - registration</STRONG> - <BR> - This happens frequently: your configuration restricts access to - <SAMP>Host.FooBar.Com</SAMP>, but you can't get in from that host. - The usual reason for this is that <SAMP>Host.FooBar.Com</SAMP> is - actually an alias for another name, and when Apache performs the - address-to-name lookup it's getting the <EM>real</EM> name, not - <SAMP>Host.FooBar.Com</SAMP>. You can verify this by checking the - reverse lookup yourself. The easiest way to work around it is to - specify the correct host name in your configuration. - </LI> - <LI><STRONG>Inadequate checking and verification in your - configuration of Apache</STRONG> - <BR> - If you intend to perform access checking and restriction based upon - the client's host or domain name, you really need to configure - Apache to double-check the origin information it's supplied. You do - this by adding the <SAMP>-DMAXIMUM_DNS</SAMP> clause to the - <SAMP>EXTRA_CFLAGS</SAMP> definition in your - <SAMP>Configuration</SAMP> file. For example: - <DL> - <DD><CODE>EXTRA_CFLAGS=-DMAXIMUM_DNS</CODE> - </DD> - </DL> - <P> - This will cause Apache to be very paranoid about making sure a - particular host address is <EM>really</EM> assigned to the name it - claims to be. Note that this <EM>can</EM> incur a significant - performance penalty, however, because of all the name resolution - requests being sent to a nameserver. - </P> - </LI> - </OL> - <HR> - </LI> - <LI><A NAME="SSL-i"> - <STRONG>Why doesn't Apache include SSL?</STRONG> - </A> - <P> - SSL (Secure Socket Layer) data transport requires encryption, and many - governments have restrictions upon the import, export, and use of - encryption technology. If Apache included SSL in the base package, - its distribution would involve all sorts of legal and bureaucratic - issues, and it would no longer be freely available. Also, some of - the technology required to talk to current clients using SSL is - patented by <A HREF="http://www.rsa.com/">RSA Data Security</A>, - who restricts its use without a license. - </P> - <P> - Some SSL implementations of Apache are available, however; see the - "<A - HREF="http://www.apache.org/related_projects" - >related projects</A>" - page at the main Apache web site. - </P> - <P> - You can find out more about this topic in the <CITE>Apache Week</CITE> - article about - <A - HREF="http://www.apacheweek.com/features/ssl" - REL="Help" - ><CITE>Apache and Secure Transactions</CITE></A>. - </P> - <HR> - </LI> - <LI><A NAME="HPUX-core"> - <STRONG>Why do I get core dumps under HPUX using HP's ANSI - C compiler?</STRONG> - </A> - <P> - We have had numerous reports of Apache dumping core when compiled - with HP's ANSI C compiler using optimization. Disabling the compiler - optimization has fixed these problems. - </P> - <HR> - </LI> - <LI><A NAME="midi"> - <STRONG>How do I get Apache to send a MIDI file so the browser can - play it?</STRONG> - </A> - <P> - Even though the registered MIME type for MIDI files is - <SAMP>audio/midi</SAMP>, some browsers are not set up to recognize it - as such; instead, they look for <SAMP>audio/x-midi</SAMP>. There are - two things you can do to address this: - </P> - <OL> - <LI>Configure your browser to treat documents of type - <SAMP>audio/midi</SAMP> correctly. This is the type that Apache - sends by default. This may not be workable, however, if you have - many client installations to change, or if some or many of the - clients are not under your control. - </LI> - <LI>Instruct Apache to send a different <SAMP>Content-type</SAMP> - header for these files by adding the following line to your server's - configuration files: - <DL> - <DD><CODE>AddType audio/x-midi .mid .midi .kar</CODE> - </DD> - </DL> - <P> - Note that this may break browsers that <EM>do</EM> recognize the - <SAMP>audio/midi</SAMP> MIME type unless they're prepared to also - handle <SAMP>audio/x-midi</SAMP> the same way. - </P> - </LI> - </OL> - <HR> - </LI> - <LI><A NAME="cantbuild"> - <STRONG>Why won't Apache compile with my system's - <SAMP>cc</SAMP>?</STRONG> - </A> - <P> - If the server won't compile on your system, it is probably due to one - of the following causes: - </P> - <UL> - <LI><STRONG>The <SAMP>Configure</SAMP> script doesn't recognize your system - environment.</STRONG> - <BR> - This might be either because it's completely unknown or because - the specific environment (include files, OS version, <EM>et - cetera</EM>) isn't explicitly handled. If this happens, you may - need to port the server to your OS yourself. - </LI> - <LI><STRONG>Your system's C compiler is garbage.</STRONG> - <BR> - Some operating systems include a default C compiler that is either - not ANSI C-compliant or suffers from other deficiencies. The usual - recommendation in cases like this is to acquire, install, and use - <SAMP>gcc</SAMP>. - </LI> - <LI><STRONG>Your <SAMP>include</SAMP> files may be confused.</STRONG> - <BR> - In some cases, we have found that a compiler installation or system - upgrade has left the C header files in an inconsistent state. Make - sure that your include directory tree is in sync with the compiler and - the operating system. - </LI> - <LI><STRONG>Your operating system or compiler may be out of - revision.</STRONG> - <BR> - Software vendors (including those that develop operating systems) - issue new releases for a reason; sometimes to add functionality, but - more often to fix bugs that have been discovered. Try upgrading - your compiler and/or your operating system. - </LI> - </UL> - <P> - The Apache Group tests the ability to build the server on many - different platforms. Unfortunately, we can't test all of the OS - platforms there are. If you have verified that none of the above - issues is the cause of your problem, and it hasn't been reported - before, please submit a - <A - HREF="http://www.apache.org/bugdb.cgi" - >problem report</A>. - Be sure to include <EM>complete</EM> details, such as the compiler - & OS versions and exact error messages. - </P> - <HR> - </LI> - <LI><A NAME="addlog"> - <STRONG>How do I add browsers and referrers to my logs?</STRONG> - </A> - <P> - Apache provides a couple of different ways of doing this. The - recommended method is to compile the - <A - HREF="../mod/mod_log_config.html" - ><SAMP>mod_log_config</SAMP></A> - module into your configuration and use the - <A - HREF="../mod/mod_log_config.html#customlog" - ><SAMP>CustomLog</SAMP></A> - directive. - </P> - <P> - You can either log the additional information in files other than your - normal transfer log, or you can add them to the records already being - written. For example: - </P> - <P> - <CODE> - CustomLog logs/access_log "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"" - </CODE> - </P> - <P> - This will add the values of the <SAMP>User-agent:</SAMP> and - <SAMP>Referer:</SAMP> headers, which indicate the client and the - referring page, respectively, to the end of each line in the access - log. - </P> - <P> - You may want to check out the <CITE>Apache Week</CITE> article - entitled: - "<A - HREF="http://www.apacheweek.com/features/logfiles" - REL="Help" - ><CITE>Gathering Visitor Information: Customising Your - Logfiles</CITE></A>". - </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> - </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. - </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: - </P> - <DL> - <DD>BrowserMatch Java1.0 force-response-1.0</CODE> - </DD> - </DL> - <HR> - <!-- Don't forget to add HR tags at the end of each list item.. --> - </LI> -</OL> - <!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/misc/client_block_api.html b/docs/manual/misc/client_block_api.html deleted file mode 100644 index 2458e0ec7f..0000000000 --- a/docs/manual/misc/client_block_api.html +++ /dev/null @@ -1,86 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Reading Client Input in Apache 1.2</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Reading Client Input in Apache 1.2</h1> - -<hr> - -<p>Apache 1.1 and earlier let modules handle POST and PUT requests by -themselves. The module would, on its own, determine whether the -request had an entity, how many bytes it was, and then called a -function (<code>read_client_block</code>) to get the data. - -<p>However, HTTP/1.1 requires several things of POST and PUT request -handlers that did not fit into this module, and all existing modules -have to be rewritten. The API calls for handling this have been -further abstracted, so that future HTTP protocol changes can be -accomplished while remaining backwards-compatible.</p> - -<hr> - -<h3>The New API Functions</h3> - -<pre> - int setup_client_block (request_rec *, int read_policy); - int should_client_block (request_rec *); - long get_client_block (request_rec *, char *buffer, int buffer_size); -</pre> - -<ol> -<li>Call <code>setup_client_block()</code> near the beginning of the request - handler. This will set up all the necessary properties, and - will return either OK, or an error code. If the latter, - the module should return that error code. The second parameter - selects the policy to apply if the request message indicates a - body, and how a chunked - transfer-coding should be interpreted. Choose one of -<pre> - REQUEST_NO_BODY Send 413 error if message has any body - REQUEST_CHUNKED_ERROR Send 411 error if body without Content-Length - REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks for me. - REQUEST_CHUNKED_PASS Pass the chunks to me without removal. -</pre> - In order to use the last two options, the caller MUST provide a buffer - large enough to hold a chunk-size line, including any extensions. - - - -<li>When you are ready to possibly accept input, call - <code>should_client_block()</code>. - This will tell the module whether or not to read input. If it is 0, - the module should assume that the input is of a non-entity type - (e.g. a GET request). A nonzero response indicates that the module - should proceed (to step 3). - This step also sends a 100 Continue response - to HTTP/1.1 clients, so should not be called until the module - is <strong>*definitely*</strong> ready to read content. (otherwise, the point of the - 100 response is defeated). Never call this function more than once. - -<li>Finally, call <code>get_client_block</code> in a loop. Pass it a - buffer and its - size. It will put data into the buffer (not necessarily the full - buffer, in the case of chunked inputs), and return the length of - the input block. When it is done reading, it will - return 0 if EOF, or -1 if there was an error. - -</ol> - -<p>As an example, please look at the code in -<code>mod_cgi.c</code>. This is properly written to the new API -guidelines.</p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/misc/compat_notes.html b/docs/manual/misc/compat_notes.html deleted file mode 100644 index 56e20bb080..0000000000 --- a/docs/manual/misc/compat_notes.html +++ /dev/null @@ -1,121 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Apache HTTP Server: Compatibility Notes with NCSA's Server</TITLE> -</HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Compatibility Notes with NCSA's Server</H1> - -<HR> - -While Apache 0.8.x and beyond are for the most part a drop-in -replacement for NCSA's httpd and earlier versions of Apache, there are -a couple gotcha's to watch out for. These are mostly due to the fact -that the parser for config and access control files was rewritten from -scratch, so certain liberties the earlier servers took may not be -available here. These are all easily fixable. If you know of other -non-fatal problems that belong here, <a -href="http://www.apache.org/bugdb.cgi">let us know.</a> - -<P>Please also check the <A HREF="known_bugs.html">known bugs</A> page. - - - -<OL> - -<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> - - - - <LI><P>If you follow the NCSA guidelines for setting up access restrictions - based on client domain, you may well have added entries for, - <CODE>AuthType, AuthName, AuthUserFile</CODE> or <CODE>AuthGroupFile</CODE>. - <B>None</B> of these are needed (or appropriate) for restricting access - based on client domain. - - <P>When Apache sees <CODE>AuthType</CODE> it (reasonably) assumes you - are using some authorization type based on username and password. - - <P>Please remove <CODE>AuthType</CODE>, it's unnecessary even for NCSA. - - <P> - - <LI><CODE>AuthUserFile</CODE> requires a full pathname. In earlier - versions of NCSA httpd and Apache, you could use a filename - relative to the .htaccess file. This could be a major security hole, - as it made it trivially easy to make a ".htpass" file in the a - directory easily accessible by the world. We recommend you store - your passwords outside your document tree. - - <P> - - <LI><CODE>OldScriptAlias</CODE> is no longer supported. - - <P> - - <LI><CODE>exec cgi=""</CODE> produces reasonable <B>malformed header</B> - responses when used to invoke non-CGI scripts.<BR> - The NCSA code ignores the missing header. (bad idea)<BR> - Solution: write CGI to the CGI spec or use <CODE>exec cmd=""</CODE> instead. - <P>We might add <CODE>virtual</CODE> support to <CODE>exec cmd</CODE> to - make up for this difference. - - <P> - - <LI><Limit> silliness - in the old Apache 0.6.5, a - directive of <Limit GET> would also restrict POST methods - Apache 0.8.8's new - core is correct in not presuming a limit on a GET is the same limit on a POST, - so if you are relying on that behavior you need to change your access configurations - to reflect that. - - <P> - - <LI>Icons for FancyIndexing broken - well, no, they're not broken, we've just upgraded the - icons from flat .xbm files to pretty and much smaller .gif files, courtesy of -<a href="mailto:kevinh@eit.com">Kevin Hughes</a> at -<a href="http://www.eit.com">EIT</a>. - If you are using the same srm.conf from an old distribution, make sure you add the new - AddIcon, AddIconByType, and DefaultIcon commands. - - <P> - - <LI>Under IRIX, the "Group" directive in httpd.conf needs to be a valid group name - (i.e. "nogroup") not the numeric group ID. The distribution httpd.conf, and earlier - ones, had the default Group be "#-1", which was causing silent exits at startup.<p> - -<li><code>.asis</code> files: Apache 0.6.5 did not require a Status header; -it added one automatically if the .asis file contained a Location header. -0.8.14 requires a Status header. <p> - - <P> - <LI>Apache versions before 1.2b1 will ignore the last line of configuration - files if the last line does not have a trailing newline. This affects - configuration files (httpd.conf, access.conf and srm.conf), and - htpasswd and htgroup files. - -</OL> - -More to come when we notice them.... - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/misc/fin_wait_2.html b/docs/manual/misc/fin_wait_2.html deleted file mode 100644 index 48e10874af..0000000000 --- a/docs/manual/misc/fin_wait_2.html +++ /dev/null @@ -1,321 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Connections in FIN_WAIT_2 and Apache</TITLE> -<LINK REV="made" HREF="mailto:marc@apache.org"> - -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Connections in the FIN_WAIT_2 state and Apache</H1> -<OL> -<LI><H2>What is the FIN_WAIT_2 state?</H2> -Starting with the Apache 1.2 betas, people are reporting many more -connections in the FIN_WAIT_2 state (as reported by -<code>netstat</code>) than they saw using older versions. When the -server closes a TCP connection, it sends a packet with the FIN bit -sent to the client, which then responds with a packet with the ACK bit -set. The client then sends a packet with the FIN bit set to the -server, which responds with an ACK and the connection is closed. The -state that the connection is in during the period between when the -server gets the ACK from the client and the server gets the FIN from -the client is known as FIN_WAIT_2. See the <A -HREF="ftp://ds.internic.net/rfc/rfc793.txt">TCP RFC</A> for the -technical details of the state transitions.<P> - -The FIN_WAIT_2 state is somewhat unusual in that there is no timeout -defined in the standard for it. This means that on many operating -systems, a connection in the FIN_WAIT_2 state will stay around until -the system is rebooted. If the system does not have a timeout and -too many FIN_WAIT_2 connections build up, it can fill up the space -allocated for storing information about the connections and crash -the kernel. The connections in FIN_WAIT_2 do not tie up an httpd -process.<P> - -<LI><H2>But why does it happen?</H2> - -There are several reasons for it happening, and not all of them are -fully understood by the Apache team yet. What is known follows.<P> - -<H3>Buggy clients and persistent connections</H3> - -Several clients have a bug which pops up when dealing with -<A HREF="../keepalive.html">persistent connections</A> (aka keepalives). -When the connection is idle and the server closes the connection -(based on the <A HREF="../mod/core.html#keepalivetimeout"> -KeepAliveTimeout</A>), the client is programmed so that the client does -not send back a FIN and ACK to the server. This means that the -connection stays in the FIN_WAIT_2 state until one of the following -happens:<P> -<UL> - <LI>The client opens a new connection to the same or a different - site, which causes it to fully close the older connection on - that socket. - <LI>The user exits the client, which on some (most?) clients - causes the OS to fully shutdown the connection. - <LI>The FIN_WAIT_2 times out, on servers that have a timeout - for this state. -</UL><P> -If you are lucky, this means that the buggy client will fully close the -connection and release the resources on your server. However, there -are some cases where the socket is never fully closed, such as a dialup -client disconnecting from their provider before closing the client. -In addition, a client might sit idle for days without making another -connection, and thus may hold its end of the socket open for days -even though it has no further use for it. -<STRONG>This is a bug in the browser or in its operating system's -TCP implementation.</STRONG> <P> - -The clients on which this problem has been verified to exist:<P> -<UL> - <LI>Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE i386) - <LI>Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE i386) - <LI>Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m) - <LI>MSIE 3.01 on the Macintosh - <LI>MSIE 3.01 on Windows 95 -</UL><P> - -This does not appear to be a problem on: -<UL> - <LI>Mozilla/3.01 (Win95; I) -</UL> -<P> - -It is expected that many other clients have the same problem. What a -client <STRONG>should do</STRONG> is periodically check its open -socket(s) to see if they have been closed by the server, and close their -side of the connection if the server has closed. This check need only -occur once every few seconds, and may even be detected by a OS signal -on some systems (e.g., Win95 and NT clients have this capability, but -they seem to be ignoring it).<P> - -Apache <STRONG>cannot</STRONG> avoid these FIN_WAIT_2 states unless it -disables persistent connections for the buggy clients, just -like we recommend doing for Navigator 2.x clients due to other bugs. -However, non-persistent connections increase the total number of -connections needed per client and slow retrieval of an image-laden -web page. Since non-persistent connections have their own resource -consumptions and a short waiting period after each closure, a busy server -may need persistence in order to best serve its clients.<P> - -As far as we know, the client-caused FIN_WAIT_2 problem is present for -all servers that support persistent connections, including Apache 1.1.x -and 1.2.<P> - -<H3>Something in Apache may be broken</H3> - -While the above bug is a problem, it is not the whole problem. -Some users have observed no FIN_WAIT_2 problems with Apache 1.1.x, -but with 1.2b enough connections build up in the FIN_WAIT_2 state to -crash their server. We have not yet identified why this would occur -and welcome additional test input.<P> - -One possible (and most likely) source for additional FIN_WAIT_2 states -is a function called <CODE>lingering_close()</CODE> which was added -between 1.1 and 1.2. This function is necessary for the proper -handling of persistent connections and any request which includes -content in the message body (e.g., PUTs and POSTs). -What it does is read any data sent by the client for -a certain time after the server closes the connection. The exact -reasons for doing this are somewhat complicated, but involve what -happens if the client is making a request at the same time the -server sends a response and closes the connection. Without lingering, -the client might be forced to reset its TCP input buffer before it -has a chance to read the server's response, and thus understand why -the connection has closed. -See the <A HREF="#appendix">appendix</A> for more details.<P> - -We have not yet tracked down the exact reason why -<CODE>lingering_close()</CODE> causes problems. Its code has been -thoroughly reviewed and extensively updated in 1.2b6. It is possible -that there is some problem in the BSD TCP stack which is causing the -observed problems. It is also possible that we fixed it in 1.2b6. -Unfortunately, we have not been able to replicate the problem on our -test servers.<P> - -<H2><LI>What can I do about it?</H2> - -There are several possible workarounds to the problem, some of -which work better than others.<P> - -<H3>Add a timeout for FIN_WAIT_2</H3> - -The obvious workaround is to simply have a timeout for the FIN_WAIT_2 state. -This is not specified by the RFC, and could be claimed to be a -violation of the RFC, but it is widely recognized as being necessary. -The following systems are known to have a timeout: -<P> -<UL> - <LI><A HREF="http://www.freebsd.org/">FreeBSD</A> versions starting at 2.0 or possibly earlier. - <LI><A HREF="http://www.netbsd.org/">NetBSD</A> version 1.2(?) - <LI><A HREF="http://www.openbsd.org/">OpenBSD</A> all versions(?) - <LI><A HREF="http://www.bsdi.com/">BSD/OS</A> 2.1, with the - <A HREF="ftp://ftp.bsdi.com/bsdi/patches/patches-2.1/K210-027"> - K210-027</A> patch installed. - <LI><A HREF="http://www.sun.com/">Solaris</A> as of around version - 2.2. The timeout can be tuned by using <CODE>ndd</CODE> to - modify <CODE>tcp_fin_wait_2_flush_interval</CODE>, but the - default should be appropriate for most servers and improper - tuning can have negative impacts. - <LI><A HREF="http://www.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. -</UL> -<P> -There is a -<A HREF="http://www.apache.org/dist/contrib/patches/1.2/fin_wait_2.patch"> -patch available</A> for adding a timeout to the FIN_WAIT_2 state; it -was originally intended for BSD/OS, but should be adaptable to most -systems using BSD networking code. You need kernel source code to be -able to use it. If you do adapt it to work for any other systems, -please drop me a note at <A HREF="mailto:marc@apache.org">marc@apache.org</A>. -<P> -<H3>Compile without using <CODE>lingering_close()</CODE></H3> - -It is possible to compile Apache 1.2 without using the -<CODE>lingering_close()</CODE> function. This will result in that -section of code being similar to that which was in 1.1. If you do -this, be aware that it can cause problems with PUTs, POSTs and -persistent connections, especially if the client uses pipelining. -That said, it is no worse than on 1.1, and we understand that keeping your -server running is quite important.<P> - -To compile without the <CODE>lingering_close()</CODE> function, add -<CODE>-DNO_LINGCLOSE</CODE> to the end of the -<CODE>EXTRA_CFLAGS</CODE> line in your <CODE>Configuration</CODE> file, -rerun <CODE>Configure</CODE> and rebuild the server. -<P> -<H3>Use <CODE>SO_LINGER</CODE> as an alternative to -<CODE>lingering_close()</CODE></H3> - -On most systems, there is an option called <CODE>SO_LINGER</CODE> that -can be set with <CODE>setsockopt(2)</CODE>. It does something very -similar to <CODE>lingering_close()</CODE>, except that it is broken -on many systems so that it causes far more problems than -<CODE>lingering_close</CODE>. On some systems, it could possibly work -better so it may be worth a try if you have no other alternatives. <P> - -To try it, add <CODE>-DUSE_SO_LINGER -DNO_LINGCLOSE</CODE> to the end of the -<CODE>EXTRA_CFLAGS</CODE> line in your <CODE>Configuration</CODE> -file, rerun <CODE>Configure</CODE> and rebuild the server. <P> - -<STRONG>NOTE:</STRONG> Attempting to use <CODE>SO_LINGER</CODE> and -<CODE>lingering_close()</CODE> at the same time is very likely to do -very bad things, so don't.<P> - -<H3>Increase the amount of memory used for storing connection state</H3> -<DL> -<DT>BSD based networking code: -<DD>BSD stores network data, such as connection states, -in something called an mbuf. When you get so many connections -that the kernel does not have enough mbufs to put them all in, your -kernel will likely crash. You can reduce the effects of the problem -by increasing the number of mbufs that are available; this will not -prevent the problem, it will just make the server go longer before -crashing.<P> - -The exact way to increase them may depend on your OS; look -for some reference to the number of "mbufs" or "mbuf clusters". On -many systems, this can be done by adding the line -<CODE>NMBCLUSTERS="n"</CODE>, where <CODE>n</CODE> is the number of -mbuf clusters you want to your kernel config file and rebuilding your -kernel.<P> -</DL> -<H2><LI>Feedback</H2> - -If you have any information to add to this page, please contact me at -<A HREF="mailto:marc@apache.org">marc@apache.org</A>.<P> - -<H2><A NAME="appendix"><LI>Appendix</A></H2> -<P> -Below is a message from Roy Fielding, one of the authors of HTTP/1.1. - -<H3>Why the lingering close functionality is necessary with HTTP</H3> - -The need for a server to linger on a socket after a close is noted a couple -times in the HTTP specs, but not explained. This explanation is based on -discussions between myself, Henrik Frystyk, Robert S. Thau, Dave Raggett, -and John C. Mallery in the hallways of MIT while I was at W3C.<P> - -If a server closes the input side of the connection while the client -is sending data (or is planning to send data), then the server's TCP -stack will signal an RST (reset) back to the client. Upon -receipt of the RST, the client will flush its own incoming TCP buffer -back to the un-ACKed packet indicated by the RST packet argument. -If the server has sent a message, usually an error response, to the -client just before the close, and the client receives the RST packet -before its application code has read the error message from its incoming -TCP buffer and before the server has received the ACK sent by the client -upon receipt of that buffer, then the RST will flush the error message -before the client application has a chance to see it. The result is -that the client is left thinking that the connection failed for no -apparent reason.<P> - -There are two conditions under which this is likely to occur: -<OL> -<LI>sending POST or PUT data without proper authorization -<LI>sending multiple requests before each response (pipelining) - and one of the middle requests resulting in an error or - other break-the-connection result. -</OL> -<P> -The solution in all cases is to send the response, close only the -write half of the connection (what shutdown is supposed to do), and -continue reading on the socket until it is either closed by the -client (signifying it has finally read the response) or a timeout occurs. -That is what the kernel is supposed to do if SO_LINGER is set. -Unfortunately, SO_LINGER has no effect on some systems; on some other -systems, it does not have its own timeout and thus the TCP memory -segments just pile-up until the next reboot (planned or not).<P> - -Please note that simply removing the linger code will not solve the -problem -- it only moves it to a different and much harder one to detect. -</OL> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/misc/footer.html b/docs/manual/misc/footer.html deleted file mode 100644 index 2c2b410378..0000000000 --- a/docs/manual/misc/footer.html +++ /dev/null @@ -1,4 +0,0 @@ -<HR> - -<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> -<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> diff --git a/docs/manual/misc/header.html b/docs/manual/misc/header.html deleted file mode 100644 index 8b23a1ccba..0000000000 --- a/docs/manual/misc/header.html +++ /dev/null @@ -1,3 +0,0 @@ -<DIV ALIGN="CENTER"> - <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> -</DIV> diff --git a/docs/manual/misc/howto.html b/docs/manual/misc/howto.html deleted file mode 100644 index 98a1843e83..0000000000 --- a/docs/manual/misc/howto.html +++ /dev/null @@ -1,147 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<META NAME="description" CONTENT="Some 'how to' tips for the Apache httpd server"> -<META NAME="keywords" CONTENT="apache,redirect,robots,rotate,logfiles"> -<TITLE>Apache HOWTO documentation</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache HOWTO documentation</H1> - -How to: -<ul> -<li><A HREF="#redirect">redirect an entire server or directory to a single URL</A> -<li><A HREF="#logreset">reset your log files</A> -<li><A HREF="#stoprob">stop/restrict robots</A> -</ul> - -<HR> -<H2><A name="redirect">How to redirect an entire server or directory to a single URL</A></H2> - -<P>There are two chief ways to redirect all requests for an entire -server to a single location: one which requires the use of -<code>mod_rewrite</code>, and another which uses a CGI script. - -<P>First: if all you need to do is migrate a server from one name to -another, simply use the <code>Redirect</code> directive, as supplied -by <code>mod_alias</code>: - -<blockquote><pre> - Redirect / http://www.apache.org/ -</pre></blockquote> - -<P>Since <code>Redirect</code> will forward along the complete path, -however, it may not be appropriate - for example, when the directory -structure has changed after the move, and you simply want to direct people -to the home page. - -<P>The best option is to use the standard Apache module <code>mod_rewrite</code>. -If that module is compiled in, the following lines: - -<blockquote><pre>RewriteEngine On -RewriteRule /.* http://www.apache.org/ [R] -</pre></blockquote> - -This will send an HTTP 302 Redirect back to the client, and no matter -what they gave in the original URL, they'll be sent to -"http://www.apache.org". - -The second option is to set up a <CODE>ScriptAlias</Code> pointing to -a <B>cgi script</B> which outputs a 301 or 302 status and the location -of the other server.</P> - -<P>By using a <B>cgi-script</B> you can intercept various requests and -treat them specially, e.g. you might want to intercept <B>POST</B> -requests, so that the client isn't redirected to a script on the other -server which expects POST information (a redirect will lose the POST -information.) You might also want to use a CGI script if you don't -want to compile mod_rewrite into your server. - -<P>Here's how to redirect all requests to a script... In the server -configuration file, -<blockquote><pre>ScriptAlias / /usr/local/httpd/cgi-bin/redirect_script</pre></blockquote> - -and here's a simple perl script to redirect requests: - -<blockquote><pre> -#!/usr/local/bin/perl - -print "Status: 302 Moved Temporarily\r -Location: http://www.some.where.else.com/\r\n\r\n"; - -</pre></blockquote></P> - -<HR> - -<H2><A name="logreset">How to reset your log files</A></H2> - -<P>Sooner or later, you'll want to reset your log files (access_log and -error_log) because they are too big, or full of old information you don't -need.</P> - -<P><CODE>access.log</CODE> typically grows by 1Mb for each 10,000 requests.</P> - -<P>Most people's first attempt at replacing the logfile is to just move the -logfile or remove the logfile. This doesn't work.</P> - -<P>Apache will continue writing to the logfile at the same offset as before the -logfile moved. This results in a new logfile being created which is just -as big as the old one, but it now contains thousands (or millions) of null -characters.</P> - -<P>The correct procedure is to move the logfile, then signal Apache to tell it to reopen the logfiles.</P> - -<P>Apache is signaled using the <B>SIGHUP</B> (-1) signal. e.g. -<blockquote><code> -mv access_log access_log.old<BR> -kill -1 `cat httpd.pid` -</code></blockquote> -</P> - -<P>Note: <code>httpd.pid</code> is a file containing the <B>p</B>rocess <B>id</B> -of the Apache httpd daemon, Apache saves this in the same directory as the log -files.</P> - -<P>Many people use this method to replace (and backup) their logfiles on a -nightly or weekly basis.</P> -<HR> - -<H2><A name="stoprob">How to stop or restrict robots</A></H2> - -<P>Ever wondered why so many clients are interested in a file called -<code>robots.txt</code> which you don't have, and never did have?</P> - -<P>These clients are called <B>robots</B> (also known as crawlers, -spiders and other cute name) - special automated clients which -wander around the web looking for interesting resources.</P> - -<P>Most robots are used to generate some kind of <em>web index</em> which -is then used by a <em>search engine</em> to help locate information.</P> - -<P><code>robots.txt</code> provides a means to request that robots limit their -activities at the site, or more often than not, to leave the site alone.</P> - -<P>When the first robots were developed, they had a bad reputation for sending hundreds/thousands of requests to each site, often resulting in the site being overloaded. Things have improved dramatically since then, thanks to <A HREF="http://info.webcrawler.com/mak/projects/robots/guidelines.html"> Guidelines for Robot Writers</A>, but even so, some robots may <A HREF="http://www.zyzzyva.com/robots/alert/">exhibit unfriendly behavior</A> which the webmaster isn't willing to tolerate, and will want to stop.</P> - -<P>Another reason some webmasters want to block access to robots, is to -stop them indexing dynamic information. Many search engines will use the -data collected from your pages for months to come - not much use if your -serving stock quotes, news, weather reports or anything else that will be -stale by the time people find it in a search engine.</P> - -<P>If you decide to exclude robots completely, or just limit the areas -in which they can roam, create a <CODE>robots.txt</CODE> file; refer -to the <A HREF="http://info.webcrawler.com/mak/projects/robots/robots.html">robot information pages</A> provided by Martijn Koster for the syntax.</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/misc/index.html b/docs/manual/misc/index.html deleted file mode 100644 index 127b1f2f0d..0000000000 --- a/docs/manual/misc/index.html +++ /dev/null @@ -1,119 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Miscellaneous Documentation</TITLE> - </HEAD> - - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Miscellaneous Documentation</h1> - - <P> - Below is a list of additional documentation pages that apply to the - Apache web server development project. - </P> - <DL> - <DT><A - HREF="API.html" - >API</A> - </DT> - <DD>Description of Apache's Application Programming Interface. - </DD> - <DT><A - HREF="FAQ.html" - >FAQ</A> - </DT> - <DD>Frequently-Asked Questions concerning the Apache project and server - </DD> - <DT><A - HREF="client_block_api.html" - >Reading Client Input in Apache 1.2</A> - </DT> - <DD>Describes differences between Apache 1.1 and 1.2 in how modules - read information from the client - </DD> - <DT><A - HREF="compat_notes.html" - >Compatibility with NCSA</A> - </DT> - <DD>Notes about Apache's compatibility with the NCSA server - </DD> - <DT><A - HREF="fin_wait_2.html" - ><SAMP>FIN_WAIT_2</SAMP></A> - </DT> - <DD>A description of the causes of Apache processes going into the - <SAMP>FIN_WAIT_2</SAMP> state, and what you can do about it - </DD> - <DT><A - HREF="howto.html" - >"How-To"</A> - </DT> - <DD>Instructions about how to accomplish some commonly-desired server - functionality changes - </DD> - <DT><A - HREF="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" - >No PGP</A> - </DT> - <DD>Why we took PEM and PGP support out of the base Apache distribution - </DD> - <DT><A - HREF="perf-bsd44.html" - >Performance Notes (BSD 4.4)</A> - </DT> - <DD>Some notes about ways to improve/optimize Apache performance on - BSD 4.4 systems - </DD> - <DT><A - HREF="perf-dec.html" - >Performance Notes (Digital UNIX)</A> - </DT> - <DD>Extracts of USENET postings describing how to optimize Apache - performance on Digital UNIX systems - </DD> - <DT><A - HREF="perf.html" - >Performance Notes (General)</A> - </DT> - <DD>Some generic notes about how to improve Apache performance - </DD> - <DT><A - HREF="security_tips.html" - >Security Tips</A> - </DT> - <DD>Some "do"s - and "don't"s - for keeping your - Apache web site secure - </DD> - <DT><A - HREF="vif-info.html" - >Virtual Hosts (IP-based)</A> - </DT> - <DD>Excerpts and notes about configuring and using Apache IP-based virtual - hosts - </DD> - <DT><A - HREF="windoz_keepalive.html" - >Windows Bug with Web Keepalive</A> - </DT> - <DD>A brief description of a known problem with Microsoft Windows and - web sites accessed using keepalive connections - </DD> - </DL> - - <!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/misc/security_tips.html b/docs/manual/misc/security_tips.html deleted file mode 100644 index cba41ada90..0000000000 --- a/docs/manual/misc/security_tips.html +++ /dev/null @@ -1,186 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache HTTP Server: Security Tips</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">Security Tips for Server Configuration</H1> - -<hr> - -<P>Some hints and tips on security issues in setting up a web server. Some of -the suggestions will be general, others specific to Apache. - -<HR> - -<H2>Permissions on Log File Directories</H2> -<P>When Apache starts, it opens the log files as the user who started the -server before switching to the user defined in the -<a href="../mod/core.html#user"><b>User</b></a> directive. Anyone who -has write permission for the directory where any log files are -being written to can append pseudo-arbitrary data to any file on the -system which is writable by the user who starts Apache. Since the -server is normally started by root, you should <EM>NOT</EM> give anyone -write permission to the directory where logs are stored unless you -want them to have root access. -<P> -<HR> -<H2>Server Side Includes</H2> -<P>Server side includes (SSI) can be configured so that users can execute -arbitrary programs on the server. That thought alone should send a shiver -down the spine of any sys-admin.<p> - -One solution is to disable that part of SSI. To do that you use the -IncludesNOEXEC option to the <A HREF="../mod/core.html#options">Options</A> -directive.<p> - -<HR> - -<H2>Non Script Aliased CGI</H2> -<P>Allowing users to execute <B>CGI</B> scripts in any directory should only -be considered if; -<OL> - <LI>You trust your users not to write scripts which will deliberately or -accidentally expose your system to an attack. - <LI>You consider security at your site to be so feeble in other areas, as to -make one more potential hole irrelevant. - <LI>You have no users, and nobody ever visits your server. -</OL><p> -<HR> - -<H2>Script Alias'ed CGI</H2> -<P>Limiting <B>CGI</B> to special directories gives the admin control over -what goes into those directories. This is inevitably more secure than -non script aliased CGI, but <strong>only if users with write access to the -directories are trusted</strong> or the admin is willing to test each new CGI -script/program for potential security holes.<P> - -Most sites choose this option over the non script aliased CGI approach.<p> - -<HR> -<H2>CGI in general</H2> -<P>Always remember that you must trust the writers of the CGI script/programs -or your ability to spot potential security holes in CGI, whether they were -deliberate or accidental.<p> - -All the CGI scripts will run as the same user, so they have potential to -conflict (accidentally or deliberately) with other scripts e.g. -User A hates User B, so he writes a script to trash User B's CGI -database. One program which can be used to allow scripts to run -as different users is <A HREF="../suexec.html">suEXEC</A> which is -included with Apache as of 1.2 and is called from special hooks in -the Apache server code. Another popular way of doing this is with -<A HREF="http://wwwcgi.umr.edu/~cgiwrap/">CGIWrap</A>. <P> - -<HR> - - -<H2>Stopping users overriding system wide settings...</H2> -<P>To run a really tight ship, you'll want to stop users from setting -up <CODE>.htaccess</CODE> files which can override security features -you've configured. Here's one way to do it...<p> - -In the server configuration file, put -<blockquote><code> -<Directory /> <br> -AllowOverride None <br> -Options None <br> -allow from all <br> -</Directory> <br> -</code></blockquote> - -Then setup for specific directories<P> - -This stops all overrides, Includes and accesses in all directories apart -from those named.<p> -<HR> -<H2> - Protect server files by default -</H2> -<P> -One aspect of Apache which is occasionally misunderstood is the feature -of default access. That is, unless you take steps to change it, if the -server can find its way to a file through normal URL mapping rules, it -can serve it to clients. -</P> -<P> -For instance, consider the following example: -</P> -<OL> - <LI><SAMP># cd /; ln -s / public_html</SAMP> - </LI> - <LI>Accessing <SAMP>http://localhost/~root/</SAMP> - </LI> -</OL> -<P> -This would allow clients to walk through the entire filesystem. To work -around this, add the following block to your server's configuration: -</P> -<PRE> - <Directory /> - Order deny,allow - Deny from all - </Directory> -</PRE> -<P> -This will forbid default access to filesystem locations. Add -appropriate -<A - HREF="../mod/core.html#directory" -><SAMP><Directory></SAMP></A> -blocks to allow access only -in those areas you wish. For example, -</P> -<PRE> - <Directory /usr/users/*/public_html> - Order deny,allow - Allow from all - </Directory> - <Directory /usr/local/httpd> - Order deny,allow - Allow from all - </Directory> -</PRE> -<P> -Pay particular attention to the interactions of -<A - HREF="../mod/core.html#location" -><SAMP><Location></SAMP></A> -and -<A - HREF="../mod/core.html#directory" -><SAMP><Directory></SAMP></A> -directives; for instance, even if <SAMP><Directory /></SAMP> -denies access, a <SAMP><Location /></SAMP> directive might -overturn it. -</P> -<P> -Also be wary of playing games with the -<A - HREF="../mod/mod_userdir.html#userdir" ->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 -by filling out a -<A HREF="http://www.apache.org/bugdb.cgi">problem report</A>, or by -sending mail to -<A HREF="mailto:apache-bugs@mail.apache.org">apache-bugs@mail.apache.org</A> -<p> -<HR> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/core.html b/docs/manual/mod/core.html deleted file mode 100644 index fde6c351a2..0000000000 --- a/docs/manual/mod/core.html +++ /dev/null @@ -1,1429 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache Core Features</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 Core Features</h1> - -These configuration parameters control the core Apache features, and are -always available. - - -<ul> -<li><A HREF="#accessconfig">AccessConfig</A> -<li><A HREF="#accessfilename">AccessFileName</A> -<li><A HREF="#addmodule">AddModule</A> -<li><A HREF="#allowoverride">AllowOverride</A> -<li><A HREF="#authname">AuthName</A> -<li><A HREF="#authtype">AuthType</A> -<li><A HREF="#bindaddress">BindAddress</A> -<li><A HREF="#clearmodulelist">ClearModuleList</A> -<li><A HREF="#defaulttype">DefaultType</A> -<li><A HREF="#directory"><Directory></A> -<li><A HREF="#documentroot">DocumentRoot</A> -<li><A HREF="#errordocument">ErrorDocument</A> -<li><A HREF="#errorlog">ErrorLog</A> -<li><A HREF="#files"><Files></A> -<li><A HREF="#group">Group</A> -<li><A HREF="#hostnamelookups">HostNameLookups</A> -<li><A HREF="#identitycheck">IdentityCheck</A> -<li><A HREF="#ifmodule"><IfModule></A> -<li><A HREF="#keepalive">KeepAlive</A> -<li><A HREF="#keepalivetimeout">KeepAliveTimeout</A> -<li><A HREF="#limit"><Limit></A> -<li><A HREF="#listen">Listen</A> -<li><A HREF="#location"><Location></A> -<li><A HREF="#maxclients">MaxClients</A> -<li><A HREF="#maxkeepaliverequests">MaxKeepAliveRequests</a> -<li><A HREF="#maxrequestsperchild">MaxRequestsPerChild</A> -<li><A HREF="#maxspareservers">MaxSpareServers</A> -<li><A HREF="#minspareservers">MinSpareServers</A> -<li><A HREF="#options">Options</A> -<li><A HREF="#pidfile">PidFile</A> -<li><A HREF="#port">Port</A> -<li><A HREF="#require">require</A> -<li><A HREF="#resourceconfig">ResourceConfig</A> -<li><A HREF="#rlimitcpu">RLimitCPU</A> -<li><A HREF="#rlimitmem">RLimitMEM</A> -<li><A HREF="#rlimitnproc">RLimitNPROC</A> -<li><A HREF="#satisfy">Satisfy</A> -<li><A HREF="#scoreboardfile">ScoreBoardFile</A> -<li><A HREF="#sendbuffersize">SendBufferSize</A> -<li><A HREF="#serveradmin">ServerAdmin</A> -<li><A HREF="#serveralias">ServerAlias</A> -<li><A HREF="#servername">ServerName</A> -<li><A HREF="#serverpath">ServerPath</A> -<li><A HREF="#serverroot">ServerRoot</A> -<li><A HREF="#servertype">ServerType</A> -<li><A HREF="#startservers">StartServers</A> -<li><A HREF="#timeout">TimeOut</A> -<li><A HREF="#user">User</A> -<li><A HREF="#virtualhost"><VirtualHost></A> -</ul> -<hr> - -<A name="accessconfig"><h2>AccessConfig directive</h2></A> -<!--%plaintext <?INDEX {\tt AccessConfig} directive> --> -<strong>Syntax:</strong> AccessConfig <em>filename</em><br> -<strong>Default:</strong> <code>AccessConfig conf/access.conf</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -The server will read this file for more directives after reading the -<A HREF="#resourceconfig">ResourceConfig</A> file. <em>Filename</em> is -relative to the <A HREF="#serverroot">ServerRoot</A>. -This feature can be disabled using: -<blockquote><code>AccessConfig /dev/null</code></blockquote> -Historically, this file only contained -<A HREF="#directory"><Directory></A> sections; in fact it can now -contain any server directive allowed in the <em>server config</em> context. -<p><hr> - -<A name="accessfilename"><h2>AccessFileName directive</h2></A> -<!--%plaintext <?INDEX {\tt AccessFileName} directive> --> -<strong>Syntax:</strong> AccessFileName <em>filename</em><br> -<strong>Default:</strong> <code>AccessFileName .htaccess</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -When returning a document to the client the server looks for an -access control file with this name in every directory of the path to -the document, if access control files are enabled for that directory. - -For example: -<blockquote><code>AccessFileName .acl</code></blockquote> -before returning the document /usr/local/web/index.html, the -server will read /.acl, /usr/.acl, /usr/local/.acl and /usr/local/web/.acl -for directives, unless they have been disabled with -<blockquote><code> -<Directory /><br> -AllowOverride None<br> -</Directory></code></blockquote><p><hr> - -<A name="addmodule"><h2>AddModule directive</h2></A> -<!--%plaintext <?INDEX {\tt AddModule} directive> --> -<strong>Syntax:</strong> AddModule <em>module module ...</em><br> -<strong>Context:</strong> server config <br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> AddModule is only available in Apache 1.2 and later<p> - -The server can have modules compiled in which are not actively in use. -This directive can be used to enable the use of those modules. The -server comes with a pre-loaded list of active modules; this list can -be cleared with the <A HREF="#clearmodulelist">ClearModuleList</A> -directive.<p><hr> - -<A name="allowoverride"><h2>AllowOverride directive</h2></A> -<!--%plaintext <?INDEX {\tt AllowOverride} directive> --> -<strong>Syntax:</strong> AllowOverride <em>override override ...</em><br> -<strong>Default:</strong> <code>AllowOverride All</code><br> -<strong>Context:</strong> directory<br> -<strong>Status:</strong> core<p> - -When the server finds an .htaccess file (as specified by -<A HREF="#accessfilename">AccessFileName</A>) it needs to know which -directives declared in that file can override earlier access information.<p> - -<em>Override</em> can be set to <code>None</code>, in which case the server -will not read the file, <code>All</code> in which case the server will -allow all the directives, or one or more of the following: -<dl> -<dt>AuthConfig -<dd> -<!--%plaintext <?INDEX {\tt AuthConfig} override> --> -Allow use of the authorization directives -(<A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A>, -<A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A>, -<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A>, -<A HREF="#authname">AuthName</A>, <A HREF="#authtype">AuthType</A>, -<A HREF="mod_auth.html#authuserfile">AuthUserFile</A>, -<A HREF="#require">require</A>, etc.). -<dt>FileInfo -<dd> -<!--%plaintext <?INDEX {\tt FileInfo} override> --> -Allow use of the directives controlling document types -(<A HREF="mod_mime.html#addencoding">AddEncoding</A>, -<A HREF="mod_mime.html#addlanguage">AddLanguage</A>, -<A HREF="mod_mime.html#addtype">AddType</A>, -<A HREF="#defaulttype">DefaultType</A>, -<A HREF="#errordocument">ErrorDocument</A>, -<A HREF="mod_negotiation.html#languagepriority">LanguagePriority</A>, etc.). -<dt>Indexes -<dd> -<!--%plaintext <?INDEX {\tt Indexes} override> --> -Allow use of the directives controlling directory indexing -(<A HREF="mod_dir.html#adddescription">AddDescription</A>, -<A HREF="mod_dir.html#addicon">AddIcon</A>, -<A HREF="mod_dir.html#addiconbyencoding">AddIconByEncoding</A>, -<A HREF="mod_dir.html#addiconbytype">AddIconByType</A>, -<A HREF="mod_dir.html#defaulticon">DefaultIcon</A>, -<A HREF="mod_dir.html#directoryindex">DirectoryIndex</A>, -<A HREF="mod_dir.html#fancyindexing">FancyIndexing</A>, -<A HREF="mod_dir.html#headername">HeaderName</A>, -<A HREF="mod_dir.html#indexignore">IndexIgnore</A>, -<A HREF="mod_dir.html#indexoptions">IndexOptions</A>, -<A HREF="mod_dir.html#readmename">ReadmeName</A>, etc.). -<dt>Limit -<dd> -<!--%plaintext <?INDEX {\tt Limit} override> --> -Allow use of the directives controlling host access (allow, deny and order). -<dt>Options -<dd> -<!--%plaintext <?INDEX {\tt Options} override> --> -Allow use of the directives controlling specific directory features -(<A HREF="#options">Options</A> and -<A HREF="mod_include.html#xbithack">XBitHack</A>). -</dl><p><hr> - -<A name="authname"><h2>AuthName directive</h2></A> -<!--%plaintext <?INDEX {\tt AuthName} directive> --> -<strong>Syntax:</strong> AuthName <em>auth-domain</em><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> core<p> - -This directive sets the name of the authorization realm for a directory. -This realm is given to the client so that the user knows which username and -password to send. -It must be accompanied by <A HREF="#authtype">AuthType</A> and -<A HREF="#require">require</A> directives, and directives such as -<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and -<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> to work.<p><hr> - -<A name="authtype"><h2>AuthType directive</h2></A> -<!--%plaintext <?INDEX {\tt AuthType} directive> --> -<strong>Syntax:</strong> AuthType <em>type</em><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> core<p> - -This directive selects the type of user authentication for a directory. -Only <code>Basic</code> is currently implemented. -<!--%plaintext <?INDEX {\tt Basic} authentication scheme> --> -It must be accompanied by <A HREF="#authname">AuthName</A> and -<A HREF="#require">require</A> directives, and directives such as -<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and -<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> to work.<p><hr> - -<A name="bindaddress"><h2>BindAddress directive</h2></A> -<!--%plaintext <?INDEX {\tt BindAddress} directive> --> -<strong>Syntax:</strong> BindAddress <em>saddr</em><br> -<strong>Default:</strong> <code>BindAddress *</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -A Unix® http server can either listen for connections to every -IP address of the server machine, or just one IP address of the server -machine. <em>Saddr</em> can be - -<menu> -<li>* -<li>An IP address -<li>A fully-qualified Internet domain name -</menu> -If the value is *, then the server will listen for connections on -every IP address, otherwise it will only listen on the IP address -specified. <p> - -This option can be used as an alternative method for supporting -<A HREF="../virtual-host.html">virtual hosts</A> instead of using -<A HREF="#virtualhost"><VirtualHost></A> sections. - -<p><strong>See Also:</strong> -<a href="../dns-caveats.html">DNS Issues</a><br> -<strong>See Also:</strong> -<a href="../bind.html">Setting which addresses and ports Apache uses</a></p> - -<hr> - -<A name="clearmodulelist"><h2>ClearModuleList directive</h2></A> -<!--%plaintext <?INDEX {\tt ClearModuleList} directive> --> -<strong>Syntax:</strong> ClearModuleList<br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> ClearModuleList is only available in Apache 1.2 and later<p> - -The server comes with a built-in list of active modules. This -directive clears the list. It is assumed that the list will then be -re-populated using the <A HREF="#addmodule">AddModule</A> directive.<p><hr> - -<A name="defaulttype"><h2>DefaultType directive</h2></A> -<!--%plaintext <?INDEX {\tt DefaultType} directive> --> -<strong>Syntax:</strong> DefaultType <em>mime-type</em><br> -<strong>Default:</strong> <code>DefaultType text/html</code><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> core<p> - -There will be times when the server is asked to provide a document -whose type cannot be determined by its MIME types mappings.<p> - -The server must inform the client of the content-type of the document, so in -the event of an unknown type it uses the <CODE>DefaultType</CODE>. For -example: -<blockquote><code>DefaultType image/gif</code></blockquote> -would be appropriate for a directory which contained many gif images -with filenames missing the .gif extension.<p><hr> - -<A name="directory"><h2><Directory> directive</h2></A> -<!--%plaintext <?INDEX {\tt Directory} section directive> --> -<strong>Syntax:</strong> <Directory <em>directory</em>> ... </Directory> <br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Core. <p> - -<Directory> and </Directory> are used to enclose a group of -directives which will apply only to the named directory and sub-directories -of that directory. Any directive which is allowed in a directory -context may be used. <em>Directory</em> is either the full path to a directory, -or a wild-card string. In a wild-card string, `?' matches any single character, -and `*' matches any sequences of characters. Example: -<pre> - <Directory /usr/local/httpd/htdocs> - Options Indexes FollowSymLinks - </Directory> -</pre> - -<p><strong>Apache 1.2 and above:</strong> -Extended regular expressions can also be used, with the addition of the -<code>~</code> character. For example:</p> - -<pre> - <Directory ~ "^/www/.*/[0-9]{3}"> -</pre> - -would match directories in /www/ that consisted of three numbers.<p> - -<p>If multiple directory sections match the directory (or its parents) containing -a document, then the directives are applied in the order of shortest match -first, interspersed with the directives from the -<A HREF="#accessfilename">.htaccess</A> files. For example, with -<blockquote><code> -<Directory /><br> -AllowOverride None<br> -</Directory><br><br> -<Directory /home/*><br> -AllowOverride FileInfo<br> -</Directory></code></blockquote> -for access to the document <code>/home/web/dir/doc.html</code> the -steps are: -<menu> -<li>Apply directive <code>AllowOverride None</code> (disabling -<code>.htaccess</code> files). -<li>Apply directive <code>AllowOverride FileInfo</code> (for directory -<code>/home/web</code>). -<li>Apply any FileInfo directives in <code>/home/web/.htaccess</code> -</menu> - -<P> -<STRONG> -Note that the default Apache access for <Directory /> is -<SAMP>Allow from All</SAMP>. This means that Apache will serve any file -mapped from an URL. It is recommended that you change this with a block -such as -</STRONG> -<PRE> - <Directory /> - Order Deny,Allow - Deny from All - </Directory> -</PRE> -<P> -<STRONG> -and then override this for directories you <EM>want</EM> accessible. -See the -<A - HREF="../misc/security_tips.html" ->Security Tips</A> -page for more details. -</STRONG> -</P> - -The directory sections typically occur in the access.conf file, but they -may appear in any configuration file. <Directory> directives cannot -nest, and cannot appear in a <A HREF="#limit"><Limit></A> section. -<p><hr> - -<A NAME="documentroot"><h2>DocumentRoot directive</h2></A> -<!--%plaintext <?INDEX {\tt DocumentRoot} directive> --> -<strong>Syntax:</strong> DocumentRoot <em>directory-filename</em><br> -<strong>Default:</strong> <code>DocumentRoot -/usr/local/etc/httpd/htdocs</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -This directive sets the directory from which httpd will serve files. -Unless matched by a directive like Alias, the server appends the path -from the requested URL to the document root to make the path to the -document. Example: -<blockquote><code>DocumentRoot /usr/web</code></blockquote> -then an access to <code>http://www.my.host.com/index.html</code> refers -to <code>/usr/web/index.html</code>. - -<P>There appears to be a bug in mod_dir which causes problems when the -DocumentRoot has a trailing slash (i.e. "DocumentRoot /usr/web/") so -please avoid that. - -<p><hr> - -<A name="errordocument"><h2>ErrorDocument directive</h2></A> -<!--%plaintext <?INDEX {\tt ErrorDocument} directive> --> -<strong>Syntax:</strong> ErrorDocument <em>error-code document</em><br> -<strong>Context</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> core<br> -<strong>Override:</strong> FileInfo<br> -<strong>Compatibility:</strong> The directory and .htaccess contexts -are only available in Apache 1.1 and later.<p> - -In the event of a problem or error, Apache can be configured to do -one of four things, - -<OL> -<LI>output a simple hardcoded error message -<LI>output a customized message -<LI>redirect to a local URL to handle the problem/error -<LI>redirect to an external URL to handle the problem/error -</OL> - -<P>The first option is the default, while options 2-4 are configured -using the <CODE>ErrorDocument</CODE> directive, which is followed by -the HTTP response code and a message or URL. - -<P><em>Messages</em> in this context begin with a single quote -(<code>"</code>), which does not form part of the message itself. -Apache will sometimes offer additional information regarding the -problem/error. - -<P>URLs can begin with a slash (/) for local URLs, or be a full -URL which the client can resolve. Examples: -<blockquote><code> -ErrorDocument 500 http://foo.example.com/cgi-bin/tester<br> -ErrorDocument 404 /cgi-bin/bad_urls.pl<br> -ErrorDocument 401 /subscription_info.html<br> -ErrorDocument 403 "Sorry can't allow you access today -</code></blockquote> - -<P>Note that when you specify an <CODE>ErrorDocument</CODE> that -points to a remote URL (ie. anything with a method such as "http" in -front of it) Apache will send a redirect to the client to tell it -where to find the document, even if the document ends up being -on the same server.. This has several implications, the -most important being that <STRONG>if you use an "ErrorDocument 401" -directive then it must refer to a local document.</STRONG> This results -from the nature of the HTTP basic authentication scheme. - -<P>See Also: <A HREF="../custom-error.html">documentation of customizable -responses.</A><p><hr> - -<A name="errorlog"><h2>ErrorLog directive</h2></A> -<!--%plaintext <?INDEX {\tt ErrorLog} directive> --> -<strong>Syntax:</strong> ErrorLog <em>filename</em><br> -<strong>Default:</strong> <code>ErrorLog logs/error_log</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -The error log directive sets the name of the file to which the server will log -any errors it encounters. If the filename does not begin with a slash (/) -then it is assumed to be relative to the <A HREF="#serverroot">ServerRoot</A>. -Example: -<blockquote><code>ErrorLog /dev/null</code></blockquote> -This effectively turns off error logging.<p> - -SECURITY: See the <A HREF="../misc/security_tips.html">security tips</A> -document for details on why your security could be compromised if -the directory where logfiles are stored is writable by anyone other -than the user that starts the server. - -<p><hr> - -<A name="files"><h2><Files></h2></A> -<strong>Syntax:</strong> <Files <em>filename</em>> -... </Files><br> -<strong>Context:</strong> server config, virtual host, htaccess<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> only available in Apache -1.2 and above.<p> - -<p>The <Files> directive provides for access control by -filename. It is comparable to the <a -href="#directory"><Directory></a> directive and -<a href="#location"><Location></a> directives. It -should be matched with a </Files> directive. Directives that -apply to the filename given should be listed -within. <code><Files></code> sections are processed in the -order they appear in the configuration file, after the -<Directory> sections and <code>.htaccess</code> files are -read, but before <Location> sections.</p> - -<p>The <em>filename</em> argument should include a filename, or a -wild-card string, where `?' matches any single character, and `*' matches any -sequences of characters. Extended regular expressions can also be used, with the addition of -the <code>~</code> character. For example:</p> - -<pre> - <Files ~ "\.(gif|jpe?g|png)$"> -</pre> - -would match most common Internet graphics formats. - -<p>Note that unlike <a -href="#directory"><code><Directory></code></a> and <a -href="#location"><code><Location></code></a> sections, -<code><Files></code> sections can be used inside .htaccess -files. This allows users to control access to their own files, at a -file-by-file level. When used in an .htaccess file, if the -<em>filename</em> does not begin with a <code>/</code> character, -the directory being applied will be prefixed automatically. - -<p> <hr> - -<A name="group"><h2>Group directive</h2></A> -<!--%plaintext <?INDEX {\tt Group} directive> --> -<strong>Syntax:</strong> Group <em>unix-group</em><br> -<strong>Default:</strong> <code>Group #-1</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -The Group directive sets the group under which the server will answer requests. -In order to use this directive, the stand-alone server must be run initially -as root. <em>Unix-group</em> is one of: -<dl> -<dt>A group name -<dd>Refers to the given group by name. -<dt># followed by a group number. -<dd>Refers to a group by its number. -</dl> - -It is recommended that you set up a new group specifically for running the -server. Some admins use user <code>nobody</code>, but this is not always -possible or desirable.<p> - -Note: if you start the server as a non-root user, it will fail to change -to the specified group, and will instead continue to run as the group of the -original user. <p> - -Special note: Use of this directive in <VirtualHost> requires a -properly configured <A HREF="../suexec.html">suEXEC wrapper</A>. -When used inside a <VirtualHost> in this manner, only the group -that CGIs are run as is affected. Non-CGI requests are still processed -as the group specified in the main Group directive.<p> - -SECURITY: See <A HREF="#user">User</A> for a discussion of the security -considerations.<p><hr> - -<A name="hostnamelookups"><h2>HostNameLookups directive</h2></A> -<!--%plaintext <?INDEX {\tt HostNameLookups} directive> --> -<strong>Syntax:</strong> HostNameLookups <em>boolean</em><br> -<strong>Default:</strong> <code>HostNameLookups on</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -This directive enables DNS lookups so that host names can be logged. -Having this directive set <code>on</code> also enables the use of names -in <Limit> blocks for access control.<p> - -Heavily loaded sites should set this directive <code>off</code>, since DNS -lookups can take considerable amounts of time. The utility <i>logresolve</i>, -provided in the <i>/support</i> directory, can be used to look up host names -from logged IP addresses offline.<p><hr> - -<A name="identitycheck"><h2>IdentityCheck directive</h2></A> -<!--%plaintext <?INDEX {\tt IdentityCheck} directive> --> -<strong>Syntax:</strong> IdentityCheck <em>boolean</em><br> -<strong>Default:</strong> <code>IdentityCheck off</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -This directive enables RFC1413-compliant logging of the remote user name -for each connection, where the client machine runs identd or something similar. -This information is logged in the access log. <em>Boolean</em> is either -<code>on</code> or <code>off</code>.<p> - -The information should not be trusted in any way except for rudimentary usage -tracking.<p> - -Note that this can cause serious latency problems accessing your server -since every request requires one of these lookups to be performed. When -firewalls are involved each lookup might possibly fail and add 30 seconds -of latency to each hit. So in general this is not very useful on public -servers accessible from the Internet. -<p><hr> - -<A NAME="ifmodule"><H2><IfModule></H2></A> -<b>Syntax:</b> <IfModule [!]<i>module-name</i>> <i>...</i> -</IfModule><br> -<b>Default:</b> None<br> -<b>Context:</b> all<br> -<b>Status:</b> Core -<strong>Compatibility:</strong> ScriptLog is only available in 1.2 and -later.<P> - -<p> - -The <IfModule <i>test</i>>...</IfModule> -section is used to mark directives that are conditional. The -directives within an IfModule section are only -processed if the <i>test</i> is true. If <i>test</i> -is false, everything between the start and end markers -is ignored.<p> - -The <i>test</i> in the <IfModule> section directive -can be one of two forms: - -<ul> -<li><i>module name</i> -<li>!<i>module name</i> -</ul> - -<p>In the former case, the directives between the start and end markers -are only processed if the module named <i>module name</i> is compiled -in to Apache. The second format reverses the test, and only processes -the directives if <i>module name</i> is <b>not</b> compiled in. - -<p>The <i>module name</i> argument is a module name as given as the file -name of the module, at the time it was compiled. For example, -<code>mod_rewrite.c</code>. - -<p><IfModule> sections are nest-able, which can be used to implement -simple multiple-module tests. - -<P> <hr> - -<h2><a name="keepalive">KeepAlive</a></h2> -<strong>Syntax: (Apache 1.1)</strong> KeepAlive <em>max-requests</em><br> -<strong>Default: (Apache 1.1)</strong> <code>KeepAlive 5</code><br> -<strong>Syntax: (Apache 1.2)</strong> KeepAlive <em>on/off</em><br> -<strong>Default: (Apache 1.2)</strong> <code>KeepAlive On</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Core<br> -<strong>Compatibility:</strong> KeepAlive is only available in Apache -1.1 and later.<p> - -This directive enables -<a href="../keepalive.html">Keep-Alive</a> -support. - -<p><strong>Apache 1.1</strong>: Set <em>max-requests</em> -to the maximum number of requests you want Apache to entertain per -request. A limit is imposed to prevent a client from hogging your -server resources. Set this to <code>0</code> to disable support. - -<p><strong>Apache 1.2 and later</strong>: Set to "On" to enable -persistent connections, "Off" to disable. See also the <a -href="#maxkeepaliverequests">MaxKeepAliveRequests</a> directive.</p> - -<h2><a name="keepalivetimeout">KeepAliveTimeout</a></h2> -<strong>Syntax:</strong> KeepAliveTimeout <em>seconds</em><br> -<strong>Default:</strong> <code>KeepAliveTimeout 15</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Core<br> -<strong>Compatibility:</strong> KeepAliveTimeout is only available in Apache -1.1 and later.<p> - -The number of seconds Apache will wait for a subsequent request before -closing the connection. Once a request has been received, the timeout -value specified by the <a -href="#timeout"><code>Timeout</code></a> directive -applies. -<hr> - -<A name="listen"><h2>Listen</h2></A> -<strong>Syntax:</strong> -Listen [<em>IP address</em>:]<em>port number</em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> Listen is only available in Apache -1.1 and later.<p> - -<p>The Listen directive instructs Apache to listen to more than one IP -address or port; by default it responds to requests on all IP -interfaces, but only on the port given by the <a href="#port">Port</a> -directive.</p> - -<p><strong>See Also:</strong> -<a href="../dns-caveats.html">DNS Issues</a><br> -<strong>See Also:</strong> -<a href="../bind.html">Setting which addresses and ports Apache uses</a><br> -<strong>See Also:</strong> -<a href="../misc/known_bugs.html#listenbug">Known Bugs</a></p> -<hr> - -<A name="limit"><h2><Limit> directive</h2></A> -<!--%plaintext <?INDEX {\tt Limit} section directive> --> -<strong>Syntax:</strong> - <Limit <em>method method</em> ... > ... </Limit><br> -<strong>Context:</strong> any<br> -<strong>Status:</strong> core<p> - -<Limit> and </Limit> are used to enclose a group of -access control directives which will then apply only to the specified -access methods, where <em>method</em> is any valid HTTP method. -Any directive except another <Limit> or -<A HREF="#directory"><Directory></A> may be used; the majority will be -unaffected by the <Limit>. Example: -<blockquote><code> -<Limit GET POST><br> -require valid-user<br> -</Limit></code></blockquote> -If an access control directive appears outside a <Limit> directive, -then it applies to all access methods.<p><hr> - -<h2><a name="location"><Location></a></h2> - -<strong>Syntax:</strong> <Location <em>URL</em>> -... </Location><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> Location is only available in Apache -1.1 and later.<p> - -<p>The <Location> directive provides for access control by -URL. It is comparable to the <a -href="#directory"><Directory></a> directive, and -should be matched with a </Location> directive. Directives that -apply to the URL given should be listed -within. <code><Location></code> sections are processed in the -order they appear in the configuration file, after the -<Directory> sections and <code>.htaccess</code> files are -read.</p> - -<p>Note that, due to the way HTTP functions, <em>URL prefix</em> -should, save for proxy requests, be of the form <code>/path/</code>, -and should not include the <code>http://servername</code>. It doesn't -necessarily have to protect a directory (it can be an individual -file, or a number of files), and can include wild-cards. In a wild-card -string, `?' matches any single character, and `*' matches any -sequences of characters. - -<p><strong>Apache 1.2 and above:</strong> -Extended regular expressions can also be used, with the addition of -the -<code>~</code> character. For example:</p> - -<pre> - <Location ~ "/(extra|special)/data"> -</pre> - -would match URLs that contained the substring "/extra/data" or -"/special/data".</p> - -<p>The <code>Location</code> functionality is especially useful when -combined with the <code><a -href="mod_mime.html#sethandler">SetHandler</a></code> directive. For example, to enable status requests, but allow them only -from browsers at foo.com, you might use: - -<pre> - <Location /status> - SetHandler server-status - order deny,allow - deny from all - allow from .foo.com - </Location> -</pre> -<hr> - -<A name="maxclients"><h2>MaxClients directive</h2></A> -<!--%plaintext <?INDEX {\tt MaxClients} directive> --> -<strong>Syntax:</strong> MaxClients <em>number</em><br> -<strong>Default:</strong> <code>MaxClients 256</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The MaxClients directive sets the limit on the number of simultaneous -requests that can be supported; not more than this number of child server -processes will be created.<p><hr> - -<A name="maxkeepaliverequests"><h2>MaxKeepAliveRequests</h2></A> -<strong>Syntax:</strong> MaxKeepAliveRequests <em>number</em><br> -<strong>Default:</strong> <code>MaxKeepAliveRequests 100</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> Only available in Apache -1.2 and later. - -<p>The MaxKeepAliveRequests directive limits the number of requests -allowed per connection when <a href="#keepalive">KeepAlive</a> is -on. If it is set to "<code>0</code>", unlimited requests will be -allowed. We recommend that this setting be kept to a high value for -maximum server performance. - -<A name="maxrequestsperchild"><h2>MaxRequestsPerChild directive</h2></A> -<!--%plaintext <?INDEX {\tt MaxRequestsPerChild} directive> --> -<strong>Syntax:</strong> MaxRequestsPerChild <em>number</em><br> -<strong>Default:</strong> <code>MaxRequestsPerChild 0</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The MaxRequestsPerChild directive sets the limit on the number of requests -that an individual child server process will handle. After MaxRequestsPerChild -requests, the child process will die. If MaxRequestsPerChild is 0, then -the process will never expire.<p> - -Setting MaxRequestsPerChild to a non-zero limit has two beneficial effects: -<ul> -<li>it limits the amount of memory that process can consume by (accidental) -memory leakage; -<li> by giving processes a finite lifetime, it helps reduce the -number of processes when the server load reduces. -</ul><p><hr> - -<A name="maxspareservers"><h2>MaxSpareServers directive</h2></A> -<!--%plaintext <?INDEX {\tt MaxSpareServers} directive> --> -<strong>Syntax:</strong> MaxSpareServers <em>number</em><br> -<strong>Default:</strong> <code>MaxSpareServers 10</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The MaxSpareServers directive sets the desired maximum number of <em>idle</em> -child server processes. An idle process is one which is not handling -a request. If there are more than MaxSpareServers idle, then the parent -process will kill off the excess processes.<p> - -Tuning of this parameter should only be necessary on very busy sites. -Setting this parameter to a large number is almost always a bad idea.<p> - -See also <A HREF="#minspareservers">MinSpareServers</A> and -<A HREF="#startservers">StartServers</A>.<p><hr> - -<A name="minspareservers"><h2>MinSpareServers directive</h2></A> -<!--%plaintext <?INDEX {\tt MinSpareServers} directive> --> -<strong>Syntax:</strong> MinSpareServers <em>number</em><br> -<strong>Default:</strong> <code>MinSpareServers 5</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The MinSpareServers directive sets the desired minimum number of <em>idle</em> -child server processes. An idle process is one which is not handling -a request. If there are fewer than MinSpareServers idle, then the parent -process creates new children at a maximum rate of 1 per second.<p> - -Tuning of this parameter should only be necessary on very busy sites. -Setting this parameter to a large number is almost always a bad idea.<p> - -See also <A HREF="#maxspareservers">MaxSpareServers</A> and -<A HREF="#startservers">StartServers</A>.<p><hr> - -<A name="options"><h2>Options directive</h2></A> -<!--%plaintext <?INDEX {\tt Options} directive> --> -<strong>Syntax:</strong> Options <em>[+|-]option [+|-]option ...</em><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Override:</strong> Options<br> -<strong>Status:</strong> core<p> - -The Options directive controls which server features are available in -a particular directory. -<p> -<em>option</em> can be set to <code>None</code>, in which case none of -the extra features are enabled, or one or more of the following: -<dl> -<dt>All -<dd>All options except for MultiViews. -<dt>ExecCGI -<dd> -<!--%plaintext <?INDEX {\tt ExecCGI} option> --> -Execution of CGI scripts is permitted. -<dt>FollowSymLinks -<dd> -<!--%plaintext <?INDEX {\tt FollowSymLinks} option> --> -The server will follow symbolic links in this directory. -<dt>Includes -<dd> -<!--%plaintext <?INDEX {\tt Includes} option> --> -Server-side includes are permitted. -<dt>IncludesNOEXEC -<dd> -<!--%plaintext <?INDEX {\tt IncludesNOEXEC} option> --> -Server-side includes are permitted, but the #exec command and -#include of CGI scripts are disabled. -<dt>Indexes -<dd> -<!--%plaintext <?INDEX {\tt Indexes} option> --> -If a URL which maps to a directory is requested, and the there is no -DirectoryIndex (e.g. index.html) in that directory, then the server will -return a formatted listing of the directory. -<dt>MultiViews -<dd> -<!--%plaintext <?INDEX {\tt MultiViews} option> --> -<A HREF="../content-negotiation.html">Content negotiated</A> MultiViews are -allowed. -<dt>SymLinksIfOwnerMatch -<dd> -<!--%plaintext <?INDEX {\tt SymLinksIfOwnerMatch} option> --> -The server will only follow symbolic links for which the target -file or directory is owned by the same user id as the link. -</dl> - -Normally, if multiple <code>Options</code> could apply to a directory, -then the most specific one is taken complete; the options are not -merged. However if <i>all</i> the options on the <code>Options</code> -directive are preceded by a + or - symbol, the options are -merged. Any options preceded by a + are added to the options -currently in force, and any options preceded by a - are removed from -the options currently in force. <P> - -For example, without any + and - symbols: - -<blockquote><code> -<Directory /web/docs> <br> -Options Indexes FollowSymLinks<br> -</Directory><br> -<Directory /web/docs/spec> <br> -Options Includes<br> -</Directory> -</code></blockquote> -then only <code>Includes</code> will be set for the /web/docs/spec -directory. However if the second <code>Options</code> directive uses the + -and - symbols:<p> - -<blockquote><code> -<Directory /web/docs> <br> -Options Indexes FollowSymLinks<br> -</Directory><br> -<Directory /web/docs/spec> <br> -Options +Includes -Indexes<br> -</Directory> -</code></blockquote> -then the options <code>FollowSymLinks</code> and <code>Includes</code> -are set for the /web/docs/spec directory. -<hr> - -<A name="pidfile"><h2>PidFile directive</h2></A> -<!--%plaintext <?INDEX {\tt PidFile} directive> --> -<strong>Syntax:</strong> PidFile <em>filename</em><br> -<strong>Default:</strong> <code>PidFile logs/httpd.pid</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The PidFile directive sets the file to which the server records the -process id of the daemon. If the filename does not begin with a slash (/) -then it is assumed to be relative to the <A HREF="#serverroot">ServerRoot</A>. -The PidFile is only used in <A HREF="#servertype">standalone</A> mode.<p> - -It is often useful to be able to send the server a signal, so that it closes -and then reopens its <A HREF="#errorlog">ErrorLog</A> and TransferLog, and -re-reads its configuration files. This is done by sending a SIGHUP (kill -1) -signal to the process id listed in the PidFile.<p> - -The PidFile is subject to the same warnings about log file placement and -<a href="../misc/security_tips.html">security</a>. - -<p><hr> - -<A name="port"><h2>Port directive</h2></A> -<!--%plaintext <?INDEX {\tt Port} directive> --> -<strong>Syntax:</strong> Port <em>number</em><br> -<strong>Default:</strong> <code>Port 80</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -<em>Number</em> is a number from 0 to 65535; some port numbers (especially below -1024) are reserved for particular protocols. See <code>/etc/services</code> -for a list of some defined ports; the standard port for the http protocol -is 80.<p> - -The Port directive has two behaviors, the first of which is necessary for -NCSA backwards compatibility (and which is confusing in the context of -Apache).<p> - -<ul> -<li> -In the absence of any <a href="#listen">Listen</a> or -<a href="#bindaddress">BindAddress</a> directives specifying a port number, -the Port directive sets the network port on which the server listens. -If there are any Listen or BindAddress directives specifying -<code>:number</code> then Port has no effect on what address the server -listens at. - -<li>The Port directive -sets the <code>SERVER_PORT</code> environment variable (for -<a href="mod_cgi.html">CGI</a> and <a href="mod_include.html">SSI</a>), -and is used when the server must generate a URL that refers to itself -(for example when creating an external redirect to itself). -</ul> - -In no event does a Port setting affect -what ports a <a href="#virtualhost">VirtualHost</a> responds on, the -VirtualHost directive itself is used for that.<p> - -The primary behaviour of Port should be considered to be similar to that of -the <a href="#servername">ServerName</a> directive. The ServerName -and Port together specify what you consider to be the <i>canonical</i> -address of the server.<p> - -Port 80 is one of Unix's special ports. All ports numbered -below 1024 are reserved for system use, i.e. regular (non-root) users cannot -make use of them; instead they can only use higher port numbers. -To use port 80, you must start the server from the root account. -After binding to the port and before accepting requests, Apache will change -to a low privileged user as set by the <A HREF="#user">User directive</A>.<p> - -If you cannot use port 80, choose any other unused port. Non-root users -will have to choose a port number higher than 1023, such as 8000.<p> - -SECURITY: if you do start the server as root, be sure -not to set <A HREF="#user">User</A> to root. If you run the server as -root whilst handling connections, your site may be open to a major security -attack.<p><hr> - -<A name="require"><h2>require directive</h2></A> -<!--%plaintext <?INDEX {\tt require} directive> --> -<strong>Syntax:</strong> require <em>entity-name entity entity...</em><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> core<p> - -This directive selects which authenticated users can access a directory. -The allowed syntaxes are: -<ul> -<li>require user <em>userid userid ...</em><p> -Only the named users can access the directory.<p> -<li>require group <em>group-name group-name ...</em><p> -Only users in the named groups can access the directory.<p> -<li>require valid-user<p> -All valid users can access the directory. -</ul> -<p> -If <code>require</code> appears in a <A HREF="#limit"><Limit></A> -section, then it restricts access to the named methods, otherwise -it restricts access for all methods. Example: -<blockquote><code> -AuthType Basic<br> -AuthName somedomain<br> -AuthUserFile /web/users<br> -AuthGroupFile /web/groups<br> -<Limit GET POST><br> -require group admin<br> -</Limit> -</code></blockquote> - -Require must be accompanied by <A HREF="#authname">AuthName</A> and -<A HREF="#authtype">AuthType</A> directives, and directives such as -<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and -<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> (to define users and -groups) in order to work correctly.<p><hr> - -<A name="resourceconfig"><h2>ResourceConfig directive</h2></A> -<!--%plaintext <?INDEX {\tt ResourceConfig} directive> --> -<strong>Syntax:</strong> ResourceConfig <em>filename</em><br> -<strong>Default:</strong> <code>ResourceConfig conf/srm.conf</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -The server will read this file for more directives after reading the -httpd.conf file. <em>Filename</em> is relative to the -<A HREF="#serverroot">ServerRoot</A>. -This feature can be disabled using: -<blockquote><code>ResourceConfig /dev/null</code></blockquote> -Historically, this file contained most directives except for server -configuration directives and <A HREF="#directory"><Directory></A> -sections; in fact it can now contain any server directive allowed in the -<em>server config</em> context.<p> - -See also <A HREF="#accessconfig">AccessConfig</A>.<p><hr> - -<A name="rlimit"> -<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> -<strong>Default:</strong> <code>Unset uses operating system defaults</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> RLimitCPU is only available in Apache 1.2 and later<p> - -Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all -processes and the second parameter sets the maximum resource limit. Either parameter -can be a number, or <em>max</em> to indicate to the server that the limit should -be set to the maximum allowed by the operating system configuration. Raising the -maximum resource limit requires that the server is running as root, or in the initial -startup phase.<p> - -CPU resource limits are expressed in seconds per process.<p> - -See also <A HREF="#rlimitmem">RLimitMEM</A> or <A HREF="#rlimitnproc">RLimitNPROC</A>.<p><hr> - -<A name="rlimitmem"><h2>RLimitMEM directive</h2></A> -<!--%plaintext <?INDEX {\tt RLimitMEM} directive> --> -<strong>Syntax:</strong> RLimitMEM <em># or 'max'</em> <em>[# or 'max']</em><br> -<strong>Default:</strong> <code>Unset uses operating system defaults</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> RLimitMEM is only available in Apache 1.2 and later<p> - -Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all -processes and the second parameter sets the maximum resource limit. Either parameter -can be a number, or <em>max</em> to indicate to the server that the limit should -be set to the maximum allowed by the operating system configuration. Raising the -maximum resource limit requires that the server is running as root, or in the initial -startup phase.<p> - -Memory resource limits are expressed in bytes per process.<p> - -See also <A HREF="#rlimitcpu">RLimitCPU</A> or <A HREF="#rlimitnproc">RLimitNPROC</A>.<p><hr> - -<A name="rlimitnproc"><h2>RLimitNPROC directive</h2></A> -<!--%plaintext <?INDEX {\tt RLimitNPROC} directive> --> -<strong>Syntax:</strong> RLimitNPROC <em># or 'max'</em> <em>[# or 'max']</em><br> -<strong>Default:</strong> <code>Unset uses operating system defaults</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> RLimitNPROC is only available in Apache 1.2 and later<p> - -Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all -processes and the second parameter sets the maximum resource limit. Either parameter -can be a number, or <em>max</em> to indicate to the server that the limit should -be set to the maximum allowed by the operating system configuration. Raising the -maximum resource limit requires that the server is running as root, or in the initial -startup phase.<p> - -Process limits control the number of processes per user.<p> - -Note: If CGI processes are <b>not</b> running under userids other than the -web server userid, this directive will limit the number of processes that the -server itself can create. Evidence of this situation will be indicated by -<b><em>cannot fork</em></b> messages in the error_log.<p> - -See also <A HREF="#rlimitmem">RLimitMEM</A> or <A HREF="#rlimitcpu">RLimitCPU</A>. - -<p><hr> - -<A name="satisfy"><h2>Satisfy</h2></A> -<!--%plaintext <?INDEX {\tt Satisfy} directive> --> -<strong>Syntax:</strong> Satisfy <em>'any' or 'all'</em><br> -<strong>Default:</strong> Satisfy all<br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> Satisfy is only available in Apache 1.2 and later<p> - -Access policy if both allow and require used. The parameter can be -either <em>'all'</em> or <em>'any'</em>. This directive is only useful -if access to a particular area is being restricted by both -username/password <i>and</i> client host address. In this case the -default behavior ("all") is to require that the client passes the -address access restriction <i>and</i> enters a valid username and -password. With the "any" option the client will be granted access if -they either pass the host restriction or enter a valid username and -password. This can be used to password restrict an area, but to let -clients from particular addresses in without prompting for a password. - - -<p><hr> - -<A name="scoreboardfile"><h2>ScoreBoardFile directive</h2></A> -<!--%plaintext <?INDEX {\tt ScoreBoardFile} directive> --> -<strong>Syntax:</strong> ScoreBoardFile <em>filename</em><br> -<strong>Default:</strong> <code>ScoreBoardFile logs/apache_status</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The ScoreBoardFile directive is required on some architectures to place -a file that the server will use to communicate between its children and -the parent. The easiest way to find out if your architecture requires -a scoreboard file is to run Apache and see if it creates the file named -by the directive. If your architecture requires it then you must ensure -that this file is not used at the same time by more than one invocation -of Apache.<p> - -If you have to use a ScoreBoardFile then you may see improved speed by -placing it on a RAM disk. But be careful that you heed the same warnings -about log file placement and -<a href="../misc/security_tips.html">security</a>.<p> - -Apache 1.2 and above:<p> - -Linux 1.x users might be able to add <code>-DHAVE_SHMGET</code> to -the <code>EXTRA_CFLAGS</code> in your <code>Configuration</code>. This -might work with some 1.x installations, but won't work with all of -them.<p> - -SVR4 users should consider adding <code>-DHAVE_SHMGET</code> to the -<code>EXTRA_CFLAGS</code> in your <code>Configuration</code>. This -is believed to work, but we were unable to test it in time for 1.2 -release.<p> - -<strong>See Also</strong>: -<a href="../stopping.html">Stopping and Restarting Apache</a></p> - -<p><hr> - -<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>Status:</strong> core<p> - -The server will set the TCP buffer size to the number of bytes -specified. Very useful to increase past standard OS defaults on high -speed high latency (i.e. 100ms or so, such as transcontinental -fast pipes) -<p><hr> - -<A name="serveradmin"><h2>ServerAdmin directive</h2></A> -<!--%plaintext <?INDEX {\tt ServerAdmin} directive> --> -<strong>Syntax:</strong> ServerAdmin <em>email-address</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -The ServerAdmin sets the e-mail address that the server includes in any -error messages it returns to the client.<p> - -It may be worth setting up a dedicated address for this, e.g. -<blockquote><code>ServerAdmin www-admin@foo.bar.com</code></blockquote> -as users do not always mention that they are talking about the server!<p><hr> - -<A name="serveralias"><h2>ServerAlias directive</h2></A> - -<strong>Syntax:</strong> ServerAlias <em>host1 host2 ...</em><br> -<strong>Context:</strong> virtual host<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> ServerAlias is only available in Apache -1.1 and later.<p> - -The ServerAlias directive sets the alternate names for a host, for use -with -<a href="../host.html">Host-header based virtual hosts</a>. -<p><strong>See Also</strong>: -<a href="../vhosts-in-depth.html">In-depth description of Virtual Host matching</a></p> - -<hr> - -<A name="servername"><h2>ServerName directive</h2></A> -<!--%plaintext <?INDEX {\tt ServerName} directive> --> -<strong>Syntax:</strong> ServerName <em>fully-qualified domain name</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -The ServerName directive sets the hostname of the server; this is only -used when creating redirection URLs. If it is not specified, then the -server attempts to deduce it from its own IP address; however this may -not work reliably, or may not return the preferred hostname. For example: -<blockquote><code>ServerName www.wibble.com</code></blockquote> -would be used if the canonical (main) name of the actual machine -were <code>monster.wibble.com</code>.<p> -<p><strong>See Also</strong>: -<a href="../dns-caveats.html">DNS Issues</a></p> -<hr> - -<A name="serverpath"><h2>ServerPath directive</h2></A> - -<strong>Syntax:</strong> ServerPath <em>pathname</em><br> -<strong>Context:</strong> virtual host<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> ServerPath is only available in Apache -1.1 and later.<p> - -The ServerPath directive sets the legacy URL pathname for a host, for -use with <a href="../host.html">Host-header based virtual hosts</a>. -<p><strong>See Also</strong>: -<a href="../vhosts-in-depth.html">In-depth description of Virtual Host matching</a></p> -<hr> - -<A name="serverroot"><h2>ServerRoot directive</h2></A> -<!--%plaintext <?INDEX {\tt ServerRoot} directive> --> -<strong>Syntax:</strong> ServerRoot <em>directory-filename</em><br> -<strong>Default:</strong> <code>ServerRoot /usr/local/etc/httpd</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The ServerRoot directive sets the directory in which the server lives. -Typically it will contain the subdirectories <code>conf/</code> and -<code>logs/</code>. Relative paths for other configuration files are taken -as relative to this directory.<br> -See also <a href="../invoking.html">the <code>-d</code> option to httpd</a>.<p><hr> - -<A name="servertype"><h2>ServerType directive</h2></A> -<!--%plaintext <?INDEX {\tt ServerType} directive> --> -<strong>Syntax:</strong> ServerType <em>type</em><br> -<strong>Default:</strong> <code>ServerType standalone</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The ServerType directive sets how the server is executed by the system. -<em>Type</em> is one of -<dl> -<dt>inetd -<dd>The server will be run from the system process inetd; the command to start -the server is added to <code>/etc/inetd.conf</code> -<dt>standalone -<dd>The server will run as a daemon process; the command to start the server -is added to the system startup scripts. (<code>/etc/rc.local</code> or -<code>/etc/rc3.d/...</code>.) -</dl> - -Inetd is the lesser used of the two options. For each http -connection received, a new copy of the server is started from scratch; -after the connection is complete, this program exits. There is a high price to -pay per connection, but for security reasons, some admins prefer this option. -<p> - -Standalone is the most common setting for ServerType since -it is far more efficient. The server is started once, and services all -subsequent connections. If you intend running Apache to serve a busy site, -standalone will probably be your only option.<p> - -SECURITY: if you are paranoid about security, run in inetd mode. Security -cannot be guaranteed in either, but whilst most people are happy to use -standalone, inetd is probably least prone to attack.<p><hr> - -<A name="startservers"><h2>StartServers directive</h2></A> -<!--%plaintext <?INDEX {\tt StartServers} directive> --> -<strong>Syntax:</strong> StartServers <em>number</em><br> -<strong>Default:</strong> <code>StartServers 5</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The StartServers directive sets the number of child server processes created -on startup. As the number of processes is dynamically controlled depending -on the load, there is usually little reason to adjust this parameter.<p> - -See also <A HREF="#minspareservers">MinSpareServers</A> and -<A HREF="#maxspareservers">MaxSpareServers</A>.<p><hr> - -<A name="timeout"><h2>TimeOut directive</h2></A> -<!--%plaintext <?INDEX {\tt TimeOut} directive> --> -<strong>Syntax:</strong> TimeOut <em>number</em><br> -<strong>Default:</strong> <code>TimeOut 300</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The TimeOut directive currently defines the amount of time Apache will -wait for three things: - -<OL> - <LI>The total amount of time it takes to receive a GET request. - <LI>The amount of time between receipt of TCP packets on a POST or - PUT request. - <LI>The amount of time between ACKs on transmissions of TCP packets - in responses. -</OL> - -We plan on making these separately configurable at some point down the -road. The timer used to default to 1200 before 1.2, but has been -lowered to 300 which is still far more than necessary in most -situations. It is not set any lower by default because there may -still be odd places in the code where the timer is not reset when -a packet is sent. - -<p><hr> - -<A name="user"><h2>User directive</h2></A> -<!--%plaintext <?INDEX {\tt User} directive> --> -<strong>Syntax:</strong> User <em>unix-userid</em><br> -<strong>Default:</strong> <code>User #-1</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -The User directive sets the userid as which the server will answer requests. -In order to use this directive, the standalone server must be run initially -as root. <em>Unix-userid</em> is one of: -<dl> -<dt>A username -<dd>Refers to the given user by name. -<dt># followed by a user number. -<dd>Refers to a user by their number. -</dl> - -The user should have no privileges which result in it being able to access -files which are not intended to be visible to the outside world, and -similarly, the user should not be able to execute code which is not -meant for httpd requests. It is recommended that you set up a new user and -group specifically for running the server. Some admins use user -<code>nobody</code>, but this is not always possible or desirable.<p> - -Notes: If you start the server as a non-root user, it will fail to change -to the lesser privileged user, and will instead continue to run as -that original user. If you do start the server as root, then it is normal -for the parent process to remain running as root.<p> - -Special note: Use of this directive in <VirtualHost> requires a -properly configured <A HREF="../suexec.html">suEXEC wrapper</A>. -When used inside a <VirtualHost> in this manner, only the user -that CGIs are run as is affected. Non-CGI requests are still processed -with the user specified in the main User directive.<p> - -SECURITY: Don't set User (or <A HREF="#group">Group</A>) to -<code>root</code> unless you know exactly what you are doing, and what the -dangers are.<p><hr> - -<A name="virtualhost"><h2><VirtualHost> directive</h2></A> -<!--%plaintext <?INDEX {\tt VirtualHost} section directive> --> -<strong>Syntax:</strong> <VirtualHost <em>addr</em>[:<em>port</em>] ...> ... -</VirtualHost> <br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Core.<br> -<strong>Compatibility:</strong> Non-IP address-based Virtual Hosting only -available in Apache 1.1 and later.<br> -<strong>Compatibility:</strong> Multiple address support only available in -Apache 1.2 and later.<p> - -<VirtualHost> and </VirtualHost> are used to enclose a group of -directives which will apply only to a particular virtual host. -Any directive which is allowed in a virtual host context may be used. -When the server receives a request for a document on a particular virtual -host, it uses the configuration directives enclosed in the <VirtualHost> -section. <em>Addr</em> can be -<menu> -<li>The IP address of the virtual host -<li>A fully qualified domain name for the IP address of the virtual host. -</menu> Example: -<blockquote> -<code> -<VirtualHost 10.1.2.3> <br> -ServerAdmin webmaster@host.foo.com <br> -DocumentRoot /www/docs/host.foo.com <br> -ServerName host.foo.com <br> -ErrorLog logs/host.foo.com-error_log <br> -TransferLog logs/host.foo.com-access_log <br> -</VirtualHost> -</code></blockquote> - -Each VirtualHost must correspond to a different IP address or a -different host name for the server, in the latter case the server -machine must be configured to accept IP packets for multiple -addresses. (If the machine does not have multiple network interfaces, -then this can be accomplished with the <code>ifconfig alias</code> -command (if your OS supports it), or with kernel patches like <A -HREF="../misc/vif-info.html">VIF</A> (for SunOS(TM) 4.1.x)).<p> - -The special name <code>_default_</code> can be specified in which case -this virtual host will match any IP address that is not explicitly listed -in another virtual host. In the absence of any _default_ virtual host -the "main" server config, consisting of all those definitions outside -any VirtualHost section, is used when no match occurs.<p> - -You can specify a <code>:port</code> to change the port that is matched. -If unspecified then it defaults to the same port as the most recent -<code><a href="#port">Port</a></code> statement of the main server. You -may also specify <code>:*</code> to match all ports on that address. -(This is recommended when used with <code>_default_</code>.)<p> - -<strong>SECURITY</strong>: See the -<A HREF="../misc/security_tips.html">security tips</A> -document for details on why your security could be compromised if -the directory where logfiles are stored is writable by anyone other -than the user that starts the server. - -<p><strong>See also:</strong> -<A HREF="../dns-caveats.html">Warnings about DNS and Apache</a><br> -<strong>See also:</strong> -<A HREF="../virtual-host.html">Information on Virtual Hosts. -(multihome)</A><br> -<strong>See also:</strong> -<a href="../host.html">Non-IP address-based Virtual Hosts</a><br> -<strong>See also:</strong> -<a href="../vhosts-in-depth.html">In-depth description of Virtual Host matching</a> -</p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/directives.html b/docs/manual/mod/directives.html deleted file mode 100644 index 23599099c2..0000000000 --- a/docs/manual/mod/directives.html +++ /dev/null @@ -1,176 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache directives</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 directives</H1> - -<ul> -<li><A HREF="core.html#accessconfig">AccessConfig</A> -<li><A HREF="core.html#accessfilename">AccessFileName</A> -<li><A HREF="mod_actions.html#action">Action</A> -<li><A HREF="mod_dir.html#addalt">AddAlt</A> -<li><A HREF="mod_dir.html#addaltbyencoding">AddAltByEncoding</A> -<li><A HREF="mod_dir.html#addaltbytype">AddAltByType</A> -<li><A HREF="mod_dir.html#adddescription">AddDescription</A> -<li><A HREF="mod_mime.html#addencoding">AddEncoding</A> -<li><A HREF="mod_mime.html#addhandler">AddHandler</A> -<li><A HREF="mod_dir.html#addicon">AddIcon</A> -<li><A HREF="mod_dir.html#addiconbyencoding">AddIconByEncoding</A> -<li><A HREF="mod_dir.html#addiconbytype">AddIconByType</A> -<li><A HREF="mod_mime.html#addlanguage">AddLanguage</A> -<li><A HREF="core.html#addmodule">AddModule</A> -<li><A HREF="mod_mime.html#addtype">AddType</A> -<li><A HREF="mod_log_agent.html#agentlog">AgentLog</A> -<li><A HREF="mod_alias.html#alias">Alias</A> -<li><A HREF="mod_access.html#allow">allow</A> -<li><A HREF="core.html#allowoverride">AllowOverride</A> -<li><A HREF="mod_auth_anon.html#anonymous">Anonymous</A> -<li><A HREF="mod_auth_anon.html#Authoritative">Anonymous_Authoritative</A> -<li><A HREF="mod_auth_anon.html#LogEmail">Anonymous_LogEmail</A> -<li><A HREF="mod_auth_anon.html#MustGiveEmail">Anonymous_MustGiveEmail</A> -<li><A HREF="mod_auth_anon.html#NoUserID">Anonymous_NoUserID</A> -<li><A HREF="mod_auth_anon.html#VerifyEmail">Anonymous_VerifyEmail</A> -<li><A HREF="mod_auth.html#authauthoritative">AuthAuthoritative</A> -<li><A HREF="mod_auth_db.html#authdbauthoritative">AuthDBAuthoritative</A> -<li><A HREF="mod_auth_db.html#authdbgroupfile">AuthDBGroupFile</A> -<li><A HREF="mod_auth_dbm.html#authdbmauthoritative">AuthDBMAuthoritative</A> -<li><A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> -<li><A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> -<li><A HREF="mod_auth_db.html#authdbuserfile">AuthDBUserFile</A> -<li><A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A> -<li><A HREF="mod_digest.html#authdigestfile">AuthDigestFile</A> -<li><A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> -<li><A HREF="core.html#authname">AuthName</A> -<li><A HREF="core.html#authtype">AuthType</A> -<li><A HREF="mod_auth.html#authuserfile">AuthUserFile</A> -<li><A HREF="core.html#bindaddress">BindAddress</A> -<li><A HREF="mod_browser.html#browsermatch">BrowserMatch</A> -<li><A HREF="mod_browser.html#browsermatchnocase">BrowserMatchNoCase</A> -<li><A HREF="mod_proxy.html#cachedefaultexpire">CacheDefaultExpire</A> -<li><A HREF="mod_proxy.html#cachedirlength">CacheDirLength</A> -<li><A HREF="mod_proxy.html#cachedirlevels">CacheDirLevels</A> -<li><A HREF="mod_proxy.html#cachegcinterval">CacheGcInterval</A> -<li><A HREF="mod_proxy.html#cachelastmodifiedfactor">CacheLastModifiedFactor</A> -<li><A HREF="mod_proxy.html#cachemaxexpire">CacheMaxExpire</A> -<li><A HREF="mod_negotiation.html#cachenegotiateddocs">CacheNegotiatedDocs</A> -<li><A HREF="mod_proxy.html#cacheroot">CacheRoot</A> -<li><A HREF="mod_proxy.html#cachesize">CacheSize</A> -<li><A HREF="core.html#clearmodulelist">ClearModuleList</A> -<li><A HREF="mod_usertrack.html#cookieexpires">CookieExpires</A> -<li><A HREF="mod_cookies.html#cookielog">CookieLog</A> (mod_cookies) -<li><A HREF="mod_log_config.html#cookielog">CookieLog</A> (mod_log_config) -<li><A HREF="mod_usertrack.html#cookietracking">CookieTracking</A> -<li><A HREF="mod_log_config.html#customlog">CustomLog</A> -<li><A HREF="mod_dir.html#defaulticon">DefaultIcon</A> -<li><A HREF="core.html#defaulttype">DefaultType</A> -<li><A HREF="mod_access.html#deny">deny</A> -<li><A HREF="core.html#directory"><Directory></A> -<li><A HREF="mod_dir.html#directoryindex">DirectoryIndex</A> -<li><A HREF="core.html#documentroot">DocumentRoot</A> -<li><A HREF="core.html#errordocument">ErrorDocument</A> -<li><A HREF="core.html#errorlog">ErrorLog</A> -<li><A HREF="mod_example.html#example">Example</A> -<li><A HREF="mod_expires.html#expiresactive">ExpiresActive</A> -<li><A HREF="mod_expires.html#expiresbytype">ExpiresByType</A> -<li><A HREF="mod_expires.html#expiresdefault">ExpiresDefault</A> -<li><A HREF="mod_dir.html#fancyindexing">FancyIndexing</A> -<li><A HREF="core.html#files"><Files></A> -<li><A HREF="mod_mime.html#forcetype">ForceType</A> -<li><A HREF="core.html#group">Group</A> -<li><A HREF="mod_headers.html#header">Header</A> -<li><A HREF="mod_dir.html#headername">HeaderName</A> -<li><A HREF="core.html#hostnamelookups">HostNameLookups</A> -<li><A HREF="core.html#identitycheck">IdentityCheck</A> -<li><A HREF="core.html#ifmodule"><IfModule></A> -<li><A HREF="mod_imap.html#imapbase">ImapBase</A> -<li><A HREF="mod_imap.html#imapdefault">ImapDefault</A> -<li><A HREF="mod_imap.html#imapmenu">ImapMenu</A> -<li><A HREF="mod_dir.html#indexignore">IndexIgnore</A> -<li><A HREF="mod_dir.html#indexoptions">IndexOptions</A> -<li><A HREF="core.html#keepalive">KeepAlive</A> -<li><A HREF="core.html#keepalivetimeout">KeepAliveTimeout</A> -<li><A HREF="mod_negotiation.html#languagepriority">LanguagePriority</A> -<li><A HREF="core.html#limit"><Limit></A> -<li><A HREF="core.html#listen">Listen</A> -<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="mod_log_config.html#logformat">LogFormat</A> -<li><A HREF="core.html#maxclients">MaxClients</A> -<li><A HREF="core.html#maxkeepaliverequests">MaxKeepAliveRequests</A> -<li><A HREF="core.html#maxrequestsperchild">MaxRequestsPerChild</A> -<li><A HREF="core.html#maxspareservers">MaxSpareServers</A> -<li><A HREF="mod_cern_meta.html#metadir">MetaDir</A> -<li><A HREF="mod_cern_meta.html#metasuffix">MetaSuffix</A> -<li><A HREF="core.html#minspareservers">MinSpareServers</A> -<li><A HREF="mod_proxy.html#nocache">NoCache</A> -<li><A HREF="core.html#options">Options</A> -<li><A HREF="mod_access.html#order">order</A> -<li><A HREF="mod_env.html#passenv">PassEnv</A> -<li><A HREF="core.html#pidfile">PidFile</A> -<li><A HREF="core.html#port">Port</A> -<li><A HREF="mod_proxy.html#proxyblock">ProxyBlock</A> -<li><A HREF="mod_proxy.html#proxypass">ProxyPass</A> -<li><A HREF="mod_proxy.html#proxyremote">ProxyRemote</A> -<li><A HREF="mod_proxy.html#proxyrequests">ProxyRequests</A> -<li><A HREF="mod_dir.html#readmename">ReadmeName</A> -<li><A HREF="mod_alias.html#redirect">Redirect</A> -<li><A HREF="mod_alias.html#redirectperm">RedirectPermanent</A> -<li><A HREF="mod_alias.html#redirecttemp">RedirectTemp</A> -<li><A HREF="mod_log_referer.html#refererignore">RefererIgnore</A> -<li><A HREF="mod_log_referer.html#refererlog">RefererLog</A> -<li><A HREF="core.html#require">require</A> -<li><A HREF="core.html#resourceconfig">ResourceConfig</A> -<li><A HREF="mod_rewrite.html#RewriteBase">RewriteBase</A> -<li><A HREF="mod_rewrite.html#RewriteCond">RewriteCond</A> -<li><A HREF="mod_rewrite.html#RewriteEngine">RewriteEngine</A> -<li><A HREF="mod_rewrite.html#RewriteLog">RewriteLog</A> -<li><A HREF="mod_rewrite.html#RewriteLogLevel">RewriteLogLevel</A> -<li><A HREF="mod_rewrite.html#RewriteMap">RewriteMap</A> -<li><A HREF="mod_rewrite.html#RewriteOptions">RewriteOptions</A> -<li><A HREF="mod_rewrite.html#RewriteRule">RewriteRule</A> -<li><A HREF="core.html#rlimitcpu">RLimitCPU</A> -<li><A HREF="core.html#rlimitmem">RLimitMEM</A> -<li><A HREF="core.html#rlimitnproc">RLimitNPROC</A> -<li><A HREF="core.html#satisfy">Satisfy</A> -<li><A HREF="core.html#scoreboardfile">ScoreBoardFile</A> -<li><A HREF="mod_actions.html#script">Script</A> -<li><A HREF="mod_alias.html#scriptalias">ScriptAlias</A> -<li><A HREF="mod_cgi.html#scriptlog">ScriptLog</A> -<li><A HREF="mod_cgi.html#scriptlogbuffer">ScriptLogBuffer</A> -<li><A HREF="mod_cgi.html#scriptloglength">ScriptLogLength</A> -<li><A HREF="core.html#sendbuffersize">SendBufferSize</A> -<li><A HREF="core.html#serveradmin">ServerAdmin</A> -<li><A HREF="core.html#serveralias">ServerAlias</A> -<li><A HREF="core.html#servername">ServerName</A> -<li><A HREF="core.html#serverpath">ServerPath</A> -<li><A HREF="core.html#serverroot">ServerRoot</A> -<li><A HREF="core.html#servertype">ServerType</A> -<li><A HREF="mod_env.html#setenv">SetEnv</A> -<li><A HREF="mod_mime.html#sethandler">SetHandler</A> -<li><A HREF="core.html#startservers">StartServers</A> -<li><A HREF="core.html#timeout">TimeOut</A> -<li><A HREF="mod_log_common.html#transferlog">TransferLog</A> (mod_log_common) -<li><A HREF="mod_log_config.html#transferlog">TransferLog</A> (mod_log_config) -<li><A HREF="mod_mime.html#typesconfig">TypesConfig</A> -<li><A HREF="mod_env.html#unsetenv">UnsetEnv</A> -<li><A HREF="core.html#user">User</A> -<li><A HREF="mod_userdir.html#userdir">UserDir</A> -<li><A HREF="core.html#virtualhost"><VirtualHost></A> -<li><A HREF="mod_include.html#xbithack">XBitHack</A> -</ul> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/footer.html b/docs/manual/mod/footer.html deleted file mode 100644 index 2c2b410378..0000000000 --- a/docs/manual/mod/footer.html +++ /dev/null @@ -1,4 +0,0 @@ -<HR> - -<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> -<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> diff --git a/docs/manual/mod/header.html b/docs/manual/mod/header.html deleted file mode 100644 index 8b23a1ccba..0000000000 --- a/docs/manual/mod/header.html +++ /dev/null @@ -1,3 +0,0 @@ -<DIV ALIGN="CENTER"> - <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> -</DIV> diff --git a/docs/manual/mod/index.html b/docs/manual/mod/index.html deleted file mode 100644 index 347393f474..0000000000 --- a/docs/manual/mod/index.html +++ /dev/null @@ -1,103 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache modules</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 modules</h1> - -<P> -Below is a list of all of the modules that come as part of the -Apache distribution. See also the complete alphabetical list of -<A - HREF="directives.html" ->all Apache directives</A>. -</P> - -<dl> -<dt><A HREF="core.html">Core</A> -<dd>Core Apache features. -<dt><A HREF="mod_access.html">mod_access</A> -<dd>Host based access control. -<dt><A HREF="mod_actions.html">mod_actions</A> Apache 1.1 and later. -<dd>Filetype/method-based script execution -<dt><A HREF="mod_alias.html">mod_alias</A> -<dd>Aliases and redirects. -<dt><A HREF="mod_asis.html">mod_asis</A> -<dd>The .asis file handler. -<dt><A HREF="mod_auth.html">mod_auth</A> -<dd>User authentication using text files. -<dt><A HREF="mod_auth_anon.html">mod_auth_anon</A> -<dd>Anonymous user authentication, FTP-style. -<dt><A HREF="mod_auth_db.html">mod_auth_db</A> -<dd>User authentication using Berkeley DB files. -<dt><A HREF="mod_auth_dbm.html">mod_auth_dbm</A> -<dd>User authentication using DBM files. -<dt><A HREF="mod_auth_msql.html">mod_auth_msql</A> -<dd>User authentication using mSQL files. -<dt><A HREF="mod_browser.html">mod_browser</A> Apache 1.2 and up -<dd>Set environment variables based on User-Agent strings -<dt><A HREF="mod_cern_meta.html">mod_cern_meta</a> -<dd>Support for HTTP header metafiles. -<dt><A HREF="mod_cgi.html">mod_cgi</A> -<dd>Invoking CGI scripts. -<dt><A HREF="mod_cookies.html">mod_cookies</A> up to Apache 1.1.1 -<dd>Support for Netscape-like cookies. Replaced in Apache 1.2 by -mod_usertrack -<dt><A HREF="mod_digest.html">mod_digest</A> -<dd>MD5 authentication -<dt><A HREF="mod_dir.html">mod_dir</A> -<dd>Automatic directory listings. -<dt><A HREF="mod_dld.html">mod_dld</A> -<dd>Start-time linking with the GNU libdld. -<dt><A HREF="mod_env.html">mod_env</A> -<dd>Passing of environments to CGI scripts -<dt><A HREF="mod_example.html">mod_example</A> Apache 1.2 and up -<dd>Demonstrates Apache API -<dt><A HREF="mod_expires.html">mod_expires</A> Apache 1.2 and up -<dd>Apply Expires: headers to resources -<dt><A HREF="mod_headers.html">mod_headers</A> Apache 1.2 and up -<dd>Add arbitrary HTTP headers to resources -<dt><A HREF="mod_imap.html">mod_imap</A> -<dd>The imagemap file handler. -<dt><A HREF="mod_include.html">mod_include</A> -<dd>Server-parsed documents. -<dt><A HREF="mod_info.html">mod_info</a> -<dd>Server configuration information -<dt><A HREF="mod_log_agent.html">mod_log_agent</A> -<dd>Logging of User Agents. -<dt><A HREF="mod_log_common.html">mod_log_common</A> up to Apache 1.1.1 -<dd>Standard logging in the Common Logfile Format. Replaced by the -mod_log_config module in Apache 1.2 and up -<dt><A HREF="mod_log_config.html">mod_log_config</A> -<dd>User-configurable logging replacement for mod_log_common. -<dt><A HREF="mod_log_referer.html">mod_log_referer</A> -<dd>Logging of document references. -<dt><A HREF="mod_mime.html">mod_mime</A> -<dd>Determining document types. -<dt><A HREF="mod_negotiation.html">mod_negotiation</A> -<dd>Content negotiation. -<dt><A HREF="mod_rewrite.html">mod_rewrite</a> Apache 1.2 and up -<dd>Powerful URI-to-filename mapping using regular expressions -<dt><A HREF="mod_proxy.html">mod_proxy</A> -<dd>Caching proxy abilities -<dt><A HREF="mod_status.html">mod_status</a> -<dd>Server status display -<dt><A HREF="mod_userdir.html">mod_userdir</A> -<dd>User home directories. -<dt><A HREF="mod_usertrack.html">mod_usertrack</A> Apache 1.2 and up -<dd>User tracking using Cookies (replacement for mod_cookies.c) -</dl> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_access.html b/docs/manual/mod/mod_access.html deleted file mode 100644 index 80c9983105..0000000000 --- a/docs/manual/mod/mod_access.html +++ /dev/null @@ -1,176 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_access</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">Module mod_access</h1> - -This module is contained in the <code>mod_access.c</code> file, and -is compiled in by default. It provides access control based on client -hostname or IP address. - - -<menu> -<li><A HREF="#allow">allow</A> -<li><A HREF="#allowfromenv">allow from env=</A> -<li><A HREF="#deny">deny</A> -<li><A HREF="#denyfromenv">deny from env=</A> -<li><A HREF="#order">order</A> -</menu> -<hr> - - -<A name="allow"><h2>allow</h2></A> -<!--%plaintext <?INDEX {\tt allow} directive> --> -<strong>Syntax:</strong> allow from <em>host host ...</em><br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> Limit<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_access<p> - -The allow directive affects which hosts can access a given directory. -<em>Host</em> is one of the following: -<dl> -<dt><code>all</code> -<dd>all hosts are allowed access -<dt>A (partial) domain-name -<dd>host whose name is, or ends in, this string are allowed access. -<dt>A full IP address -<dd>An IP address of a host allowed access -<dt>A partial IP address -<dd>The first 1 to 3 bytes of an IP address, for subnet restriction. -</dl> - -Example:<blockquote><code>allow from .ncsa.uiuc.edu</code></blockquote> -All hosts in the specified domain are allowed access.<p> - -Note that this compares whole components; <code>bar.edu</code> -would not match <code>foobar.edu</code>.<p> - -See also <A HREF="#deny">deny</A>, <A HREF="#order">order</A>, and -<a href="mod_browser.html#browsermatch">BrowserMatch</a>.<p> - -<a name="allowfromenv"><strong>Syntax:</strong> allow from env=<em>variablename</em></a><br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> Limit<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_access<br> -<strong>Compatibility:</strong> Apache 1.2 and above<p> - -The allow from env directive controls access to a directory by the -existence (or non-existence) of an environment variable. - -Example:<blockquote><pre> -BrowserMatch ^KnockKnock/2.0 let_me_in -<Directory /docroot> -order allow,deny -allow from env=let_me_in -deny from all -</Directory> -</pre></blockquote> - -See also <A HREF="#denyfromenv">deny from env</A> -and <A HREF="#order">order</A>.<p><hr> - -<A name="deny"><h2>deny</h2></A> -<!--%plaintext <?INDEX {\tt deny} directive> --> -<strong>Syntax:</strong> deny from <em>host host ...</em><br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> Limit<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_access<p> - -The deny directive affects which hosts can access a given directory. -<em>Host</em> is one of the following: -<dl> -<dt><code>all</code> -<dd>all hosts are denied access -<dt>A (partial) domain-name -<dd>host whose name is, or ends in, this string are denied access. -<dt>A full IP address -<dd>An IP address of a host denied access -<dt>A partial IP address -<dd>The first 1 to 3 bytes of an IP address, for subnet restriction. -</dl> - -Example:<blockquote><code>deny from 16</code></blockquote> -All hosts in the specified network are denied access.<p> - -Note that this compares whole components; <code>bar.edu</code> -would not match <code>foobar.edu</code>.<p> - -See also <A HREF="#allow">allow</A> and <A HREF="#order">order</A>.<p> - -<a name="denyfromenv"><strong>Syntax:</strong> deny from env=<em>variablename</em></a><br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> Limit<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_access<br> -<strong>Compatibility:</strong> Apache 1.2 and above<p> - -The deny from env directive controls access to a directory by the -existence (or non-existence) of an environment variable. - -Example:<blockquote><pre> -BrowserMatch ^BadRobot/0.9 go_away -<Directory /docroot> -order deny,allow -deny from env=go_away -allow from all -</Directory> -</pre></blockquote> - -See also <A HREF="#allowfromenv">allow from env</A> -and <A HREF="#order">order</A>.<p><hr> - -<A name="order"><h2>order</h2></A> -<!--%plaintext <?INDEX {\tt order} directive> --> -<strong>Syntax:</strong> order <em>ordering</em><br> -<strong>Default:</strong> <code>order deny,allow</code><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> Limit<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_access<p> - -The order directive controls the order in which <A HREF="#allow">allow</A> and -<A HREF="#deny">deny</A> directives are evaluated. <em>Ordering</em> is one -of -<dl> -<dt>deny,allow -<dd>the deny directives are evaluated before the allow directives. (The -initial state is OK.) -<dt>allow,deny -<dd>the allow directives are evaluated before the deny directives. (The -initial state is FORBIDDEN.) -<dt>mutual-failure -<dd>Only those hosts which appear on the allow list and do not appear -on the deny list are granted access. (The initial state is irrelevant.) -</dl> - -Note that in all cases every <code>allow</code> and <code>deny</code> -statement is evaluated, there is no "short-circuiting". - -<p>Example: -<blockquote><code> -order deny,allow<br> -deny from all<br> -allow from .ncsa.uiuc.edu<br> -</code></blockquote> -Hosts in the ncsa.uiuc.edu domain are allowed access; all other hosts are -denied access. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_actions.html b/docs/manual/mod/mod_actions.html deleted file mode 100644 index 03709d5a90..0000000000 --- a/docs/manual/mod/mod_actions.html +++ /dev/null @@ -1,85 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Module mod_actions</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">Module mod_actions</h1> - -This module is contained in the <code>mod_actions.c</code> file, and -is compiled in by default. It provides for -executing CGI scripts based on media type or request method. It is not -present in versions prior to Apache 1.1. - -<h2>Summary</h2> - -This module lets you run CGI scripts whenever a file of a certain type -is requested. This makes it much easier to execute scripts that -process files. - -<h2>Directives</h2> -<ul> -<li><A HREF="#action">Action</A> -<li><A HREF="#script">Script</A> -</ul> - -<hr> - -<A name="action"><h2>Action</h2></A> -<strong>Syntax:</strong> Action <em>mime-type cgi-script</em><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_actions<br> -<strong>Compatibility:</strong> Action is only available in Apache 1.1 -and later<p> - -This directive adds an action, which will activate <em>cgi-script</em> when -a file of content type <em>mime-type</em> is requested. It sends the -URL and file path of the requested document using the standard -CGI PATH_INFO and PATH_TRANSLATED environment variables. - -<hr> - -<A name="script"><h2>Script</h2></A> -<strong>Syntax:</strong> Script <em>method cgi-script</em><br> -<strong>Context:</strong> server config, virtual host, directory<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_actions<br> -<strong>Compatibility:</strong> Script is only available in Apache 1.1 -and later<p> - -<p>This directive adds an action, which will activate <em>cgi-script</em> when -a file is requested using the method of <em>method</em>, which can be -one of <code>GET</code>, <code>POST</code>, <code>PUT</code> or -<code>DELETE</code>. It sends the -URL and file path of the requested document using the standard -CGI PATH_INFO and PATH_TRANSLATED environment variables. - -<p>Note that the Script command defines default actions only. If a CGI -script is called, or some other resource that is capable of handling -the requested method internally, it will do so. Also note that script -with a method of <code>GET</code> will only be called if there are -query arguments present (e.g. foo.html?hi). Otherwise, the request -will proceed normally. - -<p>Examples: -<pre> - Script GET /cgi-bin/search #e.g. for <ISINDEX>-style searching - Script PUT /~bob/put.cgi - -</pre> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_alias.html b/docs/manual/mod/mod_alias.html deleted file mode 100644 index c5c89250e3..0000000000 --- a/docs/manual/mod/mod_alias.html +++ /dev/null @@ -1,146 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_alias</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">Module mod_alias</h1> - -This module is contained in the <code>mod_alias.c</code> file, and -is compiled in by default. It provides for mapping different parts of the -host filesystem in the the document tree, and for URL redirection. - - -<menu> -<li><A HREF="#alias">Alias</A> -<li><A HREF="#redirect">Redirect</A> -<li><A HREF="#redirecttemp">RedirectTemp</A> -<li><A HREF="#redirectperm">RedirectPermanent</A> -<li><A HREF="#scriptalias">ScriptAlias</A> -</menu> -<hr> - - -<A name="alias"><h2>Alias</h2></A> -<!--%plaintext <?INDEX {\tt Alias} directive> --> -<strong>Syntax:</strong> Alias <em>url-path directory-filename</em><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> - -The Alias directive allows documents to be stored in the local filesystem -other than under the <A HREF="core.html#documentroot">DocumentRoot</A>. -URLs with a (%-decoded) path beginning with <em>url-path</em> will be -mapped to local files beginning with <em>directory-filename</em>. -Example: -<blockquote><code>Alias /image /ftp/pub/image</code></blockquote> -A request for http://myserver/image/foo.gif would cause the server to -return the file /ftp/pub/image/foo.gif.<p> - -Note that if you include a trailing / on the <em>url-path</em> then the -server will require a trailing / in order to expand the alias. That is, -if you use <code>Alias /icons/ /usr/local/etc/httpd/icons/</code> then -the url <code>/icons</code> will not be aliased.<p> - -See also <A HREF="#scriptalias">ScriptAlias</A>.<p><hr> - -<A name="redirect"><h2>Redirect</h2></A> -<!--%plaintext <?INDEX {\tt Redirect} directive> --> -<strong>Syntax:</strong> Redirect [ <em>status</em> ] <em>url-path url</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> -<strong>Compatibility:</strong> The directory and .htaccess context's -are only available in versions 1.1 and later. The <em>status</em> argument is only available in Apache 1.2 or later.<p> - -The Redirect directive maps an old URL into a new one. The new URL is returned -to the client which attempts to fetch it again with the new address. -<em>Url-path</em> a (%-decoded) path; any requests for documents beginning with -this path will be returned a redirect error to a new (%-encoded) url -beginning with <em>url</em>. Example: -<blockquote><code>Redirect /service -http://foo2.bar.com/service</code></blockquote> -If the client requests http://myserver/service/foo.txt, it will be told to -access http://foo2.bar.com/service/foo.txt instead.<p> - -Note: Redirect directives take precedence over Alias and ScriptAlias -directives, irrespective of their ordering in the configuration file. Also, -<em>Url-path</em> must be an absolute path, not a relative path, even when used with -.htaccess files or inside of <Directory> sections.<p> - -If no <em>status</em> argument is given, the redirect will be -"temporary" (HTTP status 302). This indicates to the client that the -resources is has moved temporarily. The <em>status</em> -argument can be used to return other HTTP status codes: -<dl> -<dt>permanent<dd>Returns a permanent redirect status (301) indicating that -the resource has moved permanently. -<dt>temp<dd>Returns a temporary redirect status (302). This is the -default. -<dt>seeother<dd>Returns a "See Other" status (303) indicating that -the resource has been replaced. -<dt>gone<dd>Returns a "Gone" status (410) indicating that the resource -has been permanently removed. When this status is used the <em>url</em> -argument should be omitted. -</dl> - -Other status codes can be returned by giving the numeric status code -as the value of <em>status</em>. If the status is between 300 and 399, -the <em>url</em> argument must be present, otherwise it must be -omitted. Note that the status must be known to the Apache code (see -the function <code>send_error_response</code> in http_protocol.c). - -<A name="redirecttemp"><h2>RedirectTemp</h2></A> -<!--%plaintext <?INDEX {\tt Redirect} directive> --> -<strong>Syntax:</strong> RedirectTemp <em>url-path url</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> -<strong>Compatibility:</strong> This directive is only available in 1.2<P> - -This directive makes the client know that the Redirect is only -temporary. (Status 302). Exactly equivalent to <code>Redirect temporary </code><P> - -<A name="redirectperm"><h2>RedirectPermanent</h2></A> -<!--%plaintext <?INDEX {\tt Redirect} directive> --> -<strong>Syntax:</strong> RedirectPermanent <em>url-path url</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> -<strong>Compatibility:</strong> This directive is only available in 1.2<P> - -This directive makes the client know that the Redirect is permanent. -(Status 301). Exactly equivalent to <code>Redirect permanent</code><P> - -<hr> -<A name="scriptalias"><h2>ScriptAlias</h2></A> -<!--%plaintext <?INDEX {\tt ScriptAlias} directive> --> -<strong>Syntax:</strong> ScriptAlias <em>url-path directory-filename</em><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> - -The ScriptAlias directive has the same behavior as the -<A HREF="#alias">Alias</A> directive, except that in addition it -marks the target directory as containing CGI scripts. -URLs with a (%-decoded) path beginning with <em>url-path</em> will be -mapped to scripts beginning with <em>directory-filename</em>. -Example: -<blockquote><code>ScriptAlias /cgi-bin/ /web/cgi-bin/</code></blockquote> -A request for http://myserver/cgi-bin/foo would cause the server to -run the script /web/cgi-bin/foo.<p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_asis.html b/docs/manual/mod/mod_asis.html deleted file mode 100644 index 85e628115e..0000000000 --- a/docs/manual/mod/mod_asis.html +++ /dev/null @@ -1,68 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_asis</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">Module mod_asis</h1> - -This module is contained in the <code>mod_asis.c</code> file, and -is compiled in by default. It provides for <code>.asis</code> files. Any -document with mime type <code>httpd/send-as-is</code> will be processed by -this module. -<!--%plaintext <?INDEX {\tt httpd/send-as-is} mime type> --> - -<h2>Purpose</h2> -To allow file types to be defined such that Apache sends them without -adding HTTP headers.<P> - -This can be used to send any kind of data from the server, including redirects -and other special HTTP responses, without requiring a cgi-script or an nph -script. -<h2>Usage</h2> -In the server configuration file, define a new mime type called -<code>httpd/send-as-is</code> e.g. -<blockquote><code>AddType httpd/send-as-is asis</code></blockquote> -this defines the <code>.asis</code> file extension as being of the new -<code>httpd/send-as-is</code> mime type. The contents of any file with a -<code>.asis</code> extension will then be sent by Apache to the client with -almost no changes. Clients will need HTTP headers to be attached, so do not -forget them. A Status: header is also required; the data should be the -3-digit HTTP response code, followed by a textual message.<p> - -Here's an example of a file whose contents are sent <em>as is</em> so as to -tell the client that a file has redirected. -<blockquote><code> -Status: 302 Now where did I leave that URL <br> -Location: http://xyz.abc.com/foo/bar.html <br> -Content-type: text/html <br> -<br> -<HTML> <br> -<HEAD> <br> -<TITLE>Lame excuses'R'us</TITLE> <br> -</HEAD> <br> -<BODY> <br> -<H1>Fred's exceptionally wonderful page has moved to <br> -<A HREF="http://xyz.abc.com/foo/bar.html">Joe's</A> site. <br> -</H1> <br> -</BODY> <br> -</HTML> -</code></blockquote> -Notes: the server always adds a Date: and Server: header to the data returned -to the client, so these should not be included in the file. -The server does <em>not</em> add a Last-Modified header; it probably should. -<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_auth.html b/docs/manual/mod/mod_auth.html deleted file mode 100644 index bfb47a795a..0000000000 --- a/docs/manual/mod/mod_auth.html +++ /dev/null @@ -1,145 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_auth</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">Module mod_auth</h1> - -This module is contained in the <code>mod_auth.c</code> file, and -is compiled in by default. It provides for user authentication using -textual files. - - -<menu> -<li><A HREF="#authgroupfile">AuthGroupFile</A> -<li><A HREF="#authuserfile">AuthUserFile</A> -<li><A HREF="#authauthoritative">AuthAuthoritative</A> -</menu> -<hr> - - -<A name="authgroupfile"><h2>AuthGroupFile</h2></A> -<!--%plaintext <?INDEX {\tt AuthGroupFile} directive> --> -<strong>Syntax:</strong> AuthGroupFile <em>filename</em><br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_auth<p> - -The AuthGroupFile directive sets the name of a textual file containing the list -of user groups for user authentication. <em>Filename</em> is the absolute path -to the group file.<p> -Each line of the group file contains a groupname followed by a colon, followed -by the member usernames separated by spaces. Example: -<blockquote><code>mygroup: bob joe anne</code></blockquote> -Note that searching large groups files is <em>very</em> inefficient; -<A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> should -be used instead.<p> - -Security: make sure that the AuthGroupFile is stored outside the -document tree of the web-server; do <em>not</em> put it in the directory that -it protects. Otherwise, clients will be able to download the AuthGroupFile.<p> - -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authuserfile">AuthUserFile</A>.<p><hr> - -<A name="authuserfile"><h2>AuthUserFile</h2></A> -<!--%plaintext <?INDEX {\tt AuthUserFile} directive> --> -<strong>Syntax:</strong> AuthUserFile <em>filename</em><br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_auth<p> - -The AuthUserFile directive sets the name of a textual file containing -the list of users and passwords for user -authentication. <em>Filename</em> is the absolute path to the user -file.<p> Each line of the user file file contains a username followed -by a colon, followed by the crypt() encrypted password. The behavior -of multiple occurrences of the same user is undefined.<p> Note that -searching user groups files is inefficient; <A -HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A> should be -used instead.<p> - -Security: make sure that the AuthUserFile is stored outside the -document tree of the web-server; do <em>not</em> put it in the directory that -it protects. Otherwise, clients will be able to download the AuthUserFile.<p> - -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authgroupfile">AuthGroupFile</A>.<p> -<hr> -<A name="authauthoritative"><h2>AuthAuthoritative</h2></A> -<!--%plaintext <?INDEX {\tt AuthAuthoritative} directive> --> -<strong>Syntax:</strong> AuthAuthoritative < <strong> on</strong>(default) | off > <br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_auth<p> - -Setting the AuthAuthoritative directive explicitly to <b>'off'</b> -allows for both authentication and authorization to be passed on to -lower level modules (as defined in the <code>Configuration</code> and -<code>modules.c</code> files) if there is <b>no userID</b> or -<b>rule</b> matching the supplied userID. If there is a userID and/or -rule specified; the usual password and access checks will be applied -and a failure will give an Authorization Required reply. - -<p> - -So if a userID appears in the database of more than one module; or if -a valid require directive applies to more than one module; then the -first module will verify the credentials; and no access is passed on; -regardless of the AuthAuthoritative setting. - -<p> - -A common use for this is in conjunction with one of the database -modules; such as <a -href="mod_auth_db.html"><code>mod_auth_db.c</code></a>, <a -href="mod_auth_dbm.html"><code>mod_auth_dbm.c</code></a>, <a -href="mod_auth_msql.html"><code>mod_auth_msql.c</code></a> and <a -href="mod_auth_anon.html"><code>mod_auth_anon.c</code></a>. These modules -supply the bulk of the user credential checking; but a few -(administrator) related accesses fall through to a lower level with a -well protected AuthUserFile. - -<p> - -<b>Default:</b> By default; control is not passed on; and an unknown -userID or rule will result in an Authorization Required reply. Not -setting it thus keeps the system secure; and forces an NSCA compliant -behaviour. - -<p> - -Security: Do consider the implications of allowing a user to allow -fall-through in his .htaccess file; and verify that this is really -what you want; Generally it is easier to just secure a single -.htpasswd file, than it is to secure a database such as mSQL. Make -sure that the AuthUserFile is stored outside the document tree of the -web-server; do <em>not</em> put it in the directory that it -protects. Otherwise, clients will be able to download the -AuthUserFile. - -<p> -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authgroupfile">AuthGroupFile</A>.<p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_auth_anon.html b/docs/manual/mod/mod_auth_anon.html deleted file mode 100644 index c880c34ee1..0000000000 --- a/docs/manual/mod/mod_auth_anon.html +++ /dev/null @@ -1,249 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_auth_anon.c</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">Module mod_auth_anon</H1> - -This module is contained in the <code>mod_auth_anon.c</code> file and -is not compiled in by default. It is only available in Apache 1.1 and -later. It allows "anonymous" user access to authenticated areas. - -<h2>Summary</h2> - -It does access control in a manner similar to anonymous-ftp sites; i.e. -have a 'magic' user id 'anonymous' and the email address as a password. -These email addresses can be logged. -<p> -Combined with other (database) access control methods, this allows for -effective user tracking and customization according to a user profile -while still keeping the site open for 'unregistered' users. One advantage -of using Auth-based user tracking is that, unlike magic-cookies and -funny URL pre/postfixes, it is completely browser independent and it -allows users to share URLs. -<p> - -<a href="#Directives">Directives</a> / -<a href="#Example">Example</a> / -<a href="#CompileTimeOptions">Compile time options</a> / -<a href="#RevisionHistory">RevisionHistory</a> / -<a href="#Person">Person to blame</a> / -<a href="#Sourcecode">Sourcecode</a> -<p> - -<h2><a name="Directives">Directives</a></h2> -<ul> -<li><A HREF="#anonymous">Anonymous</A> -<li><A HREF="#Authoritative">Anonymous_Authoritative</A> -<li><A HREF="#LogEmail">Anonymous_LogEmail</A> -<li><A HREF="#MustGiveEmail">Anonymous_MustGiveEmail</A> -<li><A HREF="#NoUserID">Anonymous_NoUserID</A> -<li><A HREF="#VerifyEmail">Anonymous_VerifyEmail</A> -</ul> - -<hr> - -<A name="anonymous"><h2>Anonymous</h2></a> -<!--%plaintext <?INDEX {\tt Anonymous} directive> --> -<strong>Syntax:</strong> Anonymous <em>user user ...</em><br> -<strong>Default:</strong> none<br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> AuthConfig<br> -<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'. -<HR> - -<A name="Authoritative"><h2>Anonymous_Authoritative</h2></A> -<strong>Syntax:</strong> Anonymous_Authoritative <em>on | off</em><br> -<strong>Default:</strong> <code>Anonymous_Authoritative off</code><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> Extension<br> -<strong>Module:</strong> mod_auth_anon<p> - - 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. -<hr> - -<A name="LogEmail"><h2>Anonymous_LogEmail</h2></A> -<strong>Syntax:</strong> Anonymous_LogEmail <em>on | off</em><br> -<strong>Default:</strong> <code>off</code><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> AuthConfig<br> -<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. -<hr> - -<A name="MustGiveEmail"><h2>Anonymous_MustGiveEmail</h2></a> -<!--%plaintext <?INDEX {\tt Anonymous_MustGiveEmail} directive> --> -<strong>Syntax:</strong> Anonymous_MustGiveEmail <em>on</em> | <em>off</em><br> -<strong>Default:</strong> off<br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> AuthConfig<br> -<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. -<HR> - -<A name="NoUserID"><h2>Anonymous_NoUserID</h2></A> -<strong>Syntax:</strong> Anonymous_NoUserID <em>on | off</em><br> -<strong>Default:</strong> <code>Anonymous_NoUserID off</code><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> AuthConfig<br> -<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. - -<hr> - -<A name="VerifyEmail"><h2>Anonymous_VerifyEmail</h2></A> -<strong>Syntax:</strong> Anonymous <em>on | off</em><br> -<strong>Default:</strong> <code>Anonymous_VerifyEmail off</code><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> AuthConfig<br> -<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>). - -<hr><a name="Example"><h2>Example</h2></a> - -The example below (when combined with the Auth directives -of a htpasswd-file based (or GDM, mSQL etc) base access -control system allows users in as 'guests' with the -following properties: -<ul> -<li> -It insists that the user enters a userId. (<code>Anonymous_NoUserId</code>) -<li> -It insists that the user enters a password. (<code>Anonymous_MustGiveEmail</code>) -<li> -The password entered must be a valid email address, ie. contain at least one '@' and a '.'. -(<code>Anonymous_VerifyEmail</code>) -<li> -The userID must be one of <code>anonymous guest www test welcome</code> -and comparison is <b>not</b> case sensitive. -<code><directory /web/docs/public></code> -<li> -And the Email addresses entered in the passswd field are logged to -the httpd-log file -(<code>Anonymous_LogEmail</code>) -</ul> -<p> -Excerpt of access.conf: -<dl> -<dt><code> -Anonymous anonymous guest www test welcome<p> -Anonymous_MustGiveEmail on<br> -Anonymous_VerifyEmail on<br> -Anonymous_NoUserId off<br> -Anonymous_LogEmail on<br> -<p> -AuthName Use 'anonymous' & Email address for guest entry<br> -AuthType basic<p> - -</code></dt> -<dd> - Normal Apache/NCSA tokens for access control - <p> - <code><limit get post head></code><br> - <code>order deny,allow </code><br> - <code>allow from all </code><br> - <p> - <code>require valid-user </code><br> - <code><limit> </code><br> -</dd> -</dl> - - -<hr><h2><a name="CompileTimeOptions">Compile Time Options</a></h2> - -Currently there are no Compile options. - -<hr><h2><a name="RevisionHistory">Revision History</a></h2> - -This version: 23 Nov 1995, 24 Feb 1996, 16 May 1996. - -<dl> - -<dt>Version 0.4<br></dt> - <dd>First release - </dd> -<dt>Version 0.5<br></dt> - <dd>Added 'VerifyEmail' and 'LogEmail' options. Multiple - 'anonymous' tokens allowed. more docs. Added Authoritative - functionality. - </dd> -</dl> - - -<hr><h2><a name="Person">Contact/person to blame</a></h2> - -This module was written for the -<a href="http://ewse.ceo.org">European Wide Service Exchange</a> by -<<a href="mailto:Dirk.vanGulik@jrc.it"><code>Dirk.vanGulik@jrc.it</code></a>>. -Feel free to contact me if you have any problems, ice-creams or bugs. This -documentation, courtesy of Nick Himba, <a href="mailto:himba@cs.utwente.nl"> -<code><himba@cs.utwente.nl></code></a>. -<p> - - -<hr><h2><a NAME="Sourcecode">Sourcecode</a></h2> - -The source code can be found at <a href="http://www.apache.org"><code> -http://www.apache.org</code></a>. A snapshot of a development version -usually resides at <a href="http://me-www.jrc.it/~dirkx/mod_auth_anon.c"><code> -http://me-www.jrc.it/~dirkx/mod_auth_anon.c</code></a>. Please make sure -that you always quote the version you use when filing a bug report. -<p> - -<!--#include virtual="footer.html" --> -</body> -</html> - diff --git a/docs/manual/mod/mod_auth_db.html b/docs/manual/mod/mod_auth_db.html deleted file mode 100644 index d97035bf0f..0000000000 --- a/docs/manual/mod/mod_auth_db.html +++ /dev/null @@ -1,160 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_auth_db</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">Module mod_auth_db</h1> - -This module is contained in the <code>mod_auth_db.c</code> file, and -is not compiled in by default. It provides for user authentication using -Berkeley DB files. It is an alternative to <A HREF="mod_auth_dbm.html">DBM</A> -files for those systems which support DB and not DBM. It is only -available in Apache 1.1 and later. - - -<menu> -<li><A HREF="#authdbgroupfile">AuthDBGroupFile</A> -<li><A HREF="#authdbuserfile">AuthDBUserFile</A> -<li><A HREF="#authdbauthoritative">AuthDBAuthoritative</A> -</menu> -<hr> - - -<A name="authdbgroupfile"><h2>AuthDBGroupFile</h2></A> -<!--%plaintext <?INDEX {\tt AuthDBGroupFile} directive> --> -<strong>Syntax:</strong> AuthDBGroupFile <em>filename</em><br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> Extension<br> -<strong>Module:</strong> mod_auth_db<p> - -The AuthDBGroupFile directive sets the name of a DB file containing the list -of user groups for user authentication. <em>Filename</em> is the absolute path -to the group file.<p> - -The group file is keyed on the username. The value for a user is a -comma-separated list of the groups to which the users belongs. There must -be no whitespace within the value, and it must never contain any colons.<p> - -Security: make sure that the AuthDBGroupFile is stored outside the -document tree of the web-server; do <em>not</em> put it in the directory that -it protects. Otherwise, clients will be able to download the -AuthDBGroupFile unless otherwise protected.<p> - -Combining Group and Password DB files: In some cases it is easier to -manage a single database which contains both the password and group -details for each user. This simplifies any support programs that need -to be written: they now only have to deal with writing to and locking -a single DBM file. This can be accomplished by first setting the group -and password files to point to the same DB file:<p> - -<blockquote><code> -AuthDBGroupFile /www/userbase<br> -AuthDBUserFile /www/userbase -</code></blockquote> - -The key for the single DB record is the username. The value consists of <p> - -<blockquote><code> -Unix Crypt-ed Password : List of Groups [ : (ignored) ] -</code></blockquote> - -The password section contains the Unix crypt() password as before. This is -followed by a colon and the comma separated list of groups. Other data may -optionally be left in the DB file after another colon; it is ignored by the -authentication module. <p> - -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authdbuserfile">AuthDBUserFile</A>.<p><hr> - -<A name="authdbuserfile"><h2>AuthDBUserFile</h2></A> -<!--%plaintext <?INDEX {\tt AuthDBUserFile} directive> --> -<strong>Syntax:</strong> AuthDBUserFile <em>filename</em><br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> Extension<br> -<strong>Module:</strong> mod_auth_db<p> - -The AuthDBUserFile directive sets the name of a DB file containing the list -of users and passwords for user authentication. <em>Filename</em> is the -absolute path to the user file.<p> - -The user file is keyed on the username. The value for a user is the -crypt() encrypted password, optionally followed by a colon and -arbitrary data. The colon and the data following it will be ignored -by the server.<p> - -Security: make sure that the AuthDBUserFile is stored outside the -document tree of the web-server; do <em>not</em> put it in the directory that -it protects. Otherwise, clients will be able to download the -AuthDBUserFile.<p> - -Important compatibility note: The implementation of "dbmopen" in the -apache modules reads the string length of the hashed values from the -DB data structures, rather than relying upon the string being -NULL-appended. Some applications, such as the Netscape web server, -rely upon the string being NULL-appended, so if you are having trouble -using DB files interchangeably between applications this may be a -part of the problem. <p> - -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authdbgroupfile">AuthDBGroupFile</A>.<p> -<hr> -<A name="authdbauthoritative"><h2>AuthDBAuthoritative</h2></A> -<!--%plaintext <?INDEX {\tt AuthDBAuthoritative} directive> --> -<strong>Syntax:</strong> AuthDBAuthoritative < <strong> on</strong>(default) | off > <br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_auth<p> - -Setting the AuthDBAuthoritative directive explicitly to <b>'off'</b> -allows for both authentication and authorization to be passed on -to lower level modules (as defined in the <code>Configuration</code> -and <code>modules.c</code> file if there is <b>no userID</b> or -<b>rule</b> matching the supplied userID. If there is a userID -and/or rule specified; the usual password and access checks will -be applied and a failure will give an Authorization Required reply. -<p> -So if a userID appears in the database of more than one module; or -if a valid require directive applies to more than one module; then -the first module will verify the credentials; and no access is -passed on; regardless of the AuthAuthoritative setting. <p> - -A common use for this is in conjunction with one of the basic auth -modules; such as <a href="mod_auth.html"><code>mod_auth.c</code></a>. -Whereas this DB module supplies the bulk of the user credential -checking; a few (administrator) related accesses fall through to -a lower level with a well protected .htpasswd file. <p> - -<b>Default:</b> By default; control is not passed on; and an unknown -userID or rule will result in an Authorization Required reply. Not -setting it thus keeps the system secure; and forces an NSCA compliant -behaviour. <p> -Security: Do consider the implications of allowing a user to allow -fall-through in his .htaccess file; and verify that this is really -what you want; Generally it is easier to just secure a single -.htpasswd file, than it is to secure a database which might have -more access interfaces. - -<p> -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authdbgroupfile">AuthDBGroupFile</A>.<p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_auth_dbm.html b/docs/manual/mod/mod_auth_dbm.html deleted file mode 100644 index 42e0b64985..0000000000 --- a/docs/manual/mod/mod_auth_dbm.html +++ /dev/null @@ -1,162 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_auth_dbm</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">Module mod_auth_dbm</h1> - -This module is contained in the <code>mod_auth_dbm.c</code> file, and -is not compiled in by default. It provides for user authentication using -DBM files. - - -<menu> -<li><A HREF="#authdbmgroupfile">AuthDBMGroupFile</A> -<li><A HREF="#authdbmuserfile">AuthDBMUserFile</A> -<li><A HREF="#authdbmauthoritative">AuthDBMAuthoritative</A> -</menu> -<hr> - - -<A name="authdbmgroupfile"><h2>AuthDbmGroupFile</h2></A> -<!--%plaintext <?INDEX {\tt AuthDbmGroupFile} directive> --> -<strong>Syntax:</strong> AuthDBMGroupFile <em>filename</em><br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> Extension<br> -<strong>Module:</strong> mod_auth_dbm<p> - -The AuthDBMGroupFile directive sets the name of a DBM file containing the list -of user groups for user authentication. <em>Filename</em> is the absolute path -to the group file.<p> - -The group file is keyed on the username. The value for a user is a -comma-separated list of the groups to which the users belongs. There must -be no whitespace within the value, and it must never contain any colons.<p> - -Security: make sure that the AuthDBMGroupFile is stored outside the -document tree of the web-server; do <em>not</em> put it in the directory that -it protects. Otherwise, clients will be able to download the -AuthDBMGroupFile unless otherwise protected.<p> - -Combining Group and Password DBM files: In some cases it is easier to -manage a single database which contains both the password and group -details for each user. This simplifies any support programs that need -to be written: they now only have to deal with writing to and locking -a single DBM file. This can be accomplished by first setting the group -and password files to point to the same DBM:<p> - -<blockquote><code> -AuthDBMGroupFile /www/userbase<br> -AuthDBMUserFile /www/userbase -</code></blockquote> - -The key for the single DBM is the username. The value consists of <p> - -<blockquote><code> -Unix Crypt-ed Password : List of Groups [ : (ignored) ] -</code></blockquote> - -The password section contains the Unix crypt() password as before. This is -followed by a colon and the comma separated list of groups. Other data may -optionally be left in the DBM file after another colon; it is ignored by the -authentication module. This is what www.telescope.org uses for its combined -password and group database. <p> - -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authdbmuserfile">AuthDBMUserFile</A>.<p><hr> - -<A name="authdbmuserfile"><h2>AuthDBMUserFile</h2></A> -<!--%plaintext <?INDEX {\tt AuthDBMUserFile} directive> --> -<strong>Syntax:</strong> AuthDBMUserFile <em>filename</em><br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> Extension<br> -<strong>Module:</strong> mod_auth_dbm<p> - -The AuthDBMUserFile directive sets the name of a DBM file containing the list -of users and passwords for user authentication. <em>Filename</em> is the -absolute path to the user file.<p> - -The user file is keyed on the username. The value for a user is the -crypt() encrypted password, optionally followed by a colon and -arbitrary data. The colon and the data following it will be ignored -by the server.<p> - -Security: make sure that the AuthDBMUserFile is stored outside the -document tree of the web-server; do <em>not</em> put it in the directory that -it protects. Otherwise, clients will be able to download the -AuthDBMUserFile.<p> - -Important compatibility note: The implementation of "dbmopen" in the -apache modules reads the string length of the hashed values from the -DBM data structures, rather than relying upon the string being -NULL-appended. Some applications, such as the Netscape web server, -rely upon the string being NULL-appended, so if you are having trouble -using DBM files interchangeably between applications this may be a -part of the problem. <p> - -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authdbmgroupfile">AuthDBMGroupFile</A>.<p> - -<hr> -<A name="authdbmauthoritative"><h2>AuthDBMAuthoritative</h2></A> -<!--%plaintext <?INDEX {\tt AuthDBMAuthoritative} directive> --> -<strong>Syntax:</strong> AuthDBMAuthoritative < <strong> on</strong>(default) | off > <br> -<Strong>Context:</strong> directory, .htaccess<br> -<Strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_auth<p> - -Setting the AuthDBMAuthoritative directive explicitly to <b>'off'</b> -allows for both authentication and authorization to be passed on -to lower level modules (as defined in the <code>Configuration</code> -and <code>modules.c</code> file if there is <b>no userID</b> or -<b>rule</b> matching the supplied userID. If there is a userID -and/or rule specified; the usual password and access checks will -be applied and a failure will give an Authorization Required reply. -<p> -So if a userID appears in the database of more than one module; or -if a valid require directive applies to more than one module; then -the first module will verify the credentials; and no access is -passed on; regardless of the AuthAuthoritative setting. <p> - -A common use for this is in conjunction with one of the basic auth -modules; such as <a href="mod_auth.html"><code>mod_auth.c</code></a>. -Whereas this DBM module supplies the bulk of the user credential -checking; a few (administrator) related accesses fall through to -a lower level with a well protected .htpasswd file. <p> - -<b>Default:</b> By default; control is not passed on; and an unknown -userID or rule will result in an Authorization Required reply. Not -setting it thus keeps the system secure; and forces an NSCA compliant -behaviour. <p> - -Security: Do consider the implications of allowing a user to allow -fall-through in his .htaccess file; and verify that this is really -what you want; Generally it is easier to just secure a single -.htpasswd file, than it is to secure a database which might have -more access interfaces. - -<p> -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authdbmgroupfile">AuthDBMGroupFile</A>.<p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_autoindex.html b/docs/manual/mod/mod_autoindex.html deleted file mode 100644 index aebd31a5bb..0000000000 --- a/docs/manual/mod/mod_autoindex.html +++ /dev/null @@ -1,367 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_dir</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">Module mod_dir</H1> - -This module is contained in the <code>mod_dir.c</code> file, and -is compiled in by default. It provides for directory indexing. - -<h2>Summary</h2> -This module controls the directory indexing. The index of a directory -can come from one of two sources: -<ul> -<li>A file written by the user, typically called <code>index.html</code>. -The <A HREF="#directoryindex">DirectoryIndex</A> directive sets the name -of this file. -<li>Otherwise, a listing generated by the server. The other directives -control the format of this listing. The <A HREF="#addicon">AddIcon</A>, -<A HREF="#addiconbyencoding">AddIconByEncoding</A> and -<A HREF="#addiconbytype">AddIconByType</A> are used to set a list of -icons to display for various file types; for each file listed, the -first icon listed that matches the file is displayed. -</ul> - - -<h2>Directives</h2> - -<menu> -<li><A HREF="#addalt">AddAlt</A> -<li><A HREF="#addaltbyencoding">AddAltByEncoding</A> -<li><A HREF="#addaltbytype">AddAltByType</A> -<li><A HREF="#adddescription">AddDescription</A> -<li><A HREF="#addicon">AddIcon</A> -<li><A HREF="#addiconbyencoding">AddIconByEncoding</A> -<li><A HREF="#addiconbytype">AddIconByType</A> -<li><A HREF="#defaulticon">DefaultIcon</A> -<li><A HREF="#directoryindex">DirectoryIndex</A> -<li><A HREF="#fancyindexing">FancyIndexing</A> -<li><A HREF="#headername">HeaderName</A> -<li><A HREF="#indexignore">IndexIgnore</A> -<li><A HREF="#indexoptions">IndexOptions</A> -<li><A HREF="#readmename">ReadmeName</A> -</menu> -<hr> - -<A name="addalt"><h2>AddAlt</h2></A> -<!--%plaintext <?INDEX {\tt AddAlt} directive> --> -<strong>Syntax:</strong> AddAlt <em>string file file...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the alternate text to display for a file, instead of an icon, for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>File</em> is a file -extension, partial filename, wild-card expression or full filename for files -to describe. <em>String</em> is enclosed in double quotes -(<code>"</code>). This alternate text is displayed if the client is -image-incapable or has image loading disabled. - -<HR> -<A name="addaltbyencoding"><h2>AddAltByEncoding</h2></A> -<!--%plaintext <?INDEX {\tt AddAltByEncoding} directive> --> -<strong>Syntax:</strong> AddAltByEncoding <em>string MIME-encoding - MIME-encoding...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the alternate text to display for a file, instead of an icon, for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>MIME-encoding</em> is a -valid content-encoding, such as <SAMP>x-compress</SAMP>. -<em>String</em> is enclosed in double quotes -(<code>"</code>). This alternate text is displayed if the client is -image-incapable or has image loading disabled. - -<HR> -<A name="addaltbytype"><h2>AddAltByType</h2></A> -<!--%plaintext <?INDEX {\tt AddAltByType} directive> --> -<strong>Syntax:</strong> AddAltByType <em>string MIME-type MIME-type...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the alternate text to display for a file, instead of an icon, for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>MIME-type</em> is a -valid content-type, such as <SAMP>text/html</SAMP>. -<em>String</em> is enclosed in double quotes -(<code>"</code>). This alternate text is displayed if the client is -image-incapable or has image loading disabled. - -<HR> - -<A name="adddescription"><h2>AddDescription</h2></A> -<!--%plaintext <?INDEX {\tt AddDescription} directive> --> -<strong>Syntax:</strong> AddDescription <em>string file file...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the description to display for a file, for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>File</em> is a file -extension, partial filename, wild-card expression or full filename for files -to describe. <em>String</em> is enclosed in double quotes -(<code>"</code>). Example: -<blockquote><code>AddDescription "The planet Mars" /web/pics/mars.gif -</code></blockquote><p><hr> - -<A name="addicon"><h2>AddIcon</h2></A> -<!--%plaintext <?INDEX {\tt AddIcon} directive> --> -<strong>Syntax:</strong> AddIcon <em>icon name name ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the icon to display next to a file ending in <em>name</em> for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>Icon</em> is either a -(%-escaped) relative URL to the icon, or of the format -(<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag given -for an icon for non-graphical browsers.<p> - -<em>Name</em> is either ^^DIRECTORY^^ for directories, ^^BLANKICON^^ for -blank lines (to format the list correctly), a file extension, a wildcard -expression, a partial filename or a complete filename. Examples: -<blockquote><code> -AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm <br> -AddIcon /icons/dir.xbm ^^DIRECTORY^^ <br> -AddIcon /icons/backup.xbm *~ -</code></blockquote> -<A HREF="#addiconbytype">AddIconByType</A> should be used in preference to -AddIcon, when possible.<p><hr> - -<A name="addiconbyencoding"><h2>AddIconByEncoding</h2></A> -<!--%plaintext <?INDEX {\tt AddIconByEncoding} directive> --> -<strong>Syntax:</strong> AddIconByEncoding <em>icon mime-encoding mime-encoding -...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the icon to display next to files with -<em>mime-encoding</em> for <A HREF="#fancyindexing">FancyIndexing</A>. -<em>Icon</em> is either a (%-escaped) relative URL to the icon, or of the -format (<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag -given for an icon for non-graphical browsers.<p> - -<em>Mime-encoding</em> is a wildcard expression matching required the -content-encoding. Examples: -<blockquote><code> -AddIconByEncoding /icons/compress.xbm x-compress -</code></blockquote><p><hr> - -<A name="addiconbytype"><h2>AddIconByType</h2></A> -<!--%plaintext <?INDEX {\tt AddIconByType} directive> --> -<strong>Syntax:</strong> AddIconByType <em>icon mime-type mime-type ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the icon to display next to files of type <em>mime-type</em> for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>Icon</em> is either a -(%-escaped) relative URL to the icon, or of the format -(<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag given -for an icon for non-graphical browsers.<p> -<em>Mime-type</em> is a wildcard expression matching required the mime types. -Examples: -<blockquote><code> -AddIconByType (IMG,/icons/image.xbm) image/* -</code></blockquote><p><hr> - -<A name="defaulticon"><h2>DefaultIcon</h2></A> -<!--%plaintext <?INDEX {\tt DefaultIcon} directive> --> -<strong>Syntax:</strong> DefaultIcon <em>url</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The DefaultIcon directive sets the icon to display for files when no -specific icon is known, for <A HREF="#fancyindexing">FancyIndexing</A>. -<em>Url</em> is a (%-escaped) relative URL to the icon. Examples: -<blockquote><code> -DefaultIcon /icon/unknown.xbm -</code></blockquote><p><hr> - -<A name="directoryindex"><h2>DirectoryIndex</h2></A> -<!--%plaintext <?INDEX {\tt DirectoryIndex} directive> --> -<strong>Syntax:</strong> DirectoryIndex <em>local-url local-url ...</em><br> -<strong>Default:</strong> <code>DirectoryIndex index.html</code><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The DirectoryIndex directive sets the list of resources to look for, -when the client requests an index of the directory by specifying a / -at the end of the a directory name. <em>Local-url</em> is the -(%-encoded) URL of a document on the server relative to the requested -directory; it is usually the name of a file in the directory. Several -URLs may be given, in which case the server will return the first one -that it finds. If none of the resources exist and the -<CODE>Indexes</CODE> option is set, the server will generate its own -listing of the directory. -<P> - -Example: -<blockquote><code> -DirectoryIndex index.html -</code></blockquote> -then a request for <code>http://myserver/docs/</code> would return -<code>http://myserver/docs/index.html</code> if it exists, or would list -the directory if it did not. <p> - -Note that the documents do not need to be relative to the directory; -<blockquote><code> -DirectoryIndex index.html index.txt /cgi-bin/index.pl</code></blockquote> -would cause the CGI script <code>/cgi-bin/index.pl</code> to be executed -if neither <code>index.html</code> or <code>index.txt</code> existed in -a directory.<p><hr> - -<A name="fancyindexing"><h2>FancyIndexing</h2></A> -<!--%plaintext <?INDEX {\tt FancyIndexing} directive> --> -<strong>Syntax:</strong> FancyIndexing <em>boolean</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The FancyIndexing directive sets the FancyIndexing option for a directory. -<em>Boolean</em> can be <code>on</code> or <code>off</code>. The -<A HREF="#indexoptions">IndexOptions</A> directive should be used in -preference.<p><hr> - -<A name="headername"><h2>HeaderName</h2></A> -<!--%plaintext <?INDEX {\tt HeaderName} directive> --> -<strong>Syntax:</strong> HeaderName <em>filename</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The HeaderName directive sets the name of the file that will be inserted -at the top of the index listing. <em>Filename</em> is the name of the file -to include, and is taken to be relative to the directory being indexed. -The server first attempts to include <em>filename</em><code>.html</code> -as an HTML document, otherwise it will include <em>filename</em> as plain -text. Example: -<blockquote><code>HeaderName HEADER</code></blockquote> -when indexing the directory <code>/web</code>, the server will first look for -the HTML file <code>/web/HEADER.html</code> and include it if found, otherwise -it will include the plain text file <code>/web/HEADER</code>, if it exists. - -<p>See also <A HREF="#readmename">ReadmeName</A>.<p><hr> - -<A name="indexignore"><h2>IndexIgnore</h2></A> -<!--%plaintext <?INDEX {\tt IndexIgnore} directive> --> -<strong>Syntax:</strong> IndexIgnore <em>file file ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The IndexIgnore directive adds to the list of files to hide when listing -a directory. <em>File</em> is a file extension, partial filename, -wildcard expression or full filename for files to ignore. Multiple -IndexIgnore directives add to the list, rather than the replacing the list -of ignored files. By default, the list contains `<code>.</code>'. Example: -<blockquote><code> -IndexIgnore README .htaccess *~ -</code></blockquote><p><hr> - -<A name="indexoptions"><h2>IndexOptions</h2></A> -<!--%plaintext <?INDEX {\tt IndexOptions} directive> --> -<strong>Syntax:</strong> IndexOptions <em>option option ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The IndexOptions directive specifies the behavior of the directory indexing. -<em>Option</em> can be one of -<dl> -<dt>FancyIndexing -<dd><!--%plaintext <?INDEX {\tt FancyIndexing} index option> --> -This turns on fancy indexing of directories. -<dt>IconsAreLinks -<dd> -<!--%plaintext <?INDEX {\tt IconsAreLinks} index option> --> -This makes the icons part of the anchor for the filename, for -fancy indexing. -<dt>ScanHTMLTitles -<dd><!--%plaintext <?INDEX {\tt ScanHTMLTitles} index option> --> -This enables the extraction of the title from HTML documents for fancy -indexing. If the file does not have a description given by -<A HREF="#adddescription">AddDescription</A> then httpd will read the -document for the value of the TITLE tag. This is CPU and disk intensive. -<dt>SuppressLastModified -<dd> -<!--%plaintext <?INDEX {\tt SuppressLastModified} index option> --> -This will suppress the display of the last modification date, in fancy -indexing listings. -<dt>SuppressSize -<dd> -<!--%plaintext <?INDEX {\tt SuppressSize} index option> --> -This will suppress the file size in fancy indexing listings. -<dt>SuppressDescription -<dd> -<!--%plaintext <?INDEX {\tt SuppressDescription} index option> --> -This will suppress the file description in fancy indexing listings. -</dl> -This default is that no options are enabled. If multiple IndexOptions -could apply to a directory, then the most specific one is taken complete; -the options are not merged. For example: -<blockquote><code> -<Directory /web/docs> <br> -IndexOptions FancyIndexing <br> -</Directory><br> -<Directory /web/docs/spec> <br> -IndexOptions ScanHTMLTitles <br> -</Directory> -</code></blockquote> -then only <code>ScanHTMLTitles</code> will be set for the /web/docs/spec -directory.<p><hr> - -<A name="readmename"><h2>ReadmeName</h2></A> -<!--%plaintext <?INDEX {\tt ReadmeName} directive> --> -<strong>Syntax:</strong> ReadmeName <em>filename</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The ReadmeName directive sets the name of the file that will be appended -to the end of the index listing. <em>Filename</em> is the name of the file -to include, and is taken to be relative to the directory being indexed. -The server first attempts to include <em>filename</em><code>.html</code> -as an HTML document, otherwise it will include <em>filename</em> as plain -text. Example: -<blockquote><code>ReadmeName README</code></blockquote> -when indexing the directory <code>/web</code>, the server will first look for -the HTML file <code>/web/README.html</code> and include it if found, otherwise -it will include the plain text file <code>/web/README</code>, if it exists. - -<p>See also <A HREF="#headername">HeaderName</A>.<p> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_cern_meta.html b/docs/manual/mod/mod_cern_meta.html deleted file mode 100644 index 98a7410f40..0000000000 --- a/docs/manual/mod/mod_cern_meta.html +++ /dev/null @@ -1,81 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Module mod_cern_meta</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 module mod_cern_meta</h1> - -This module is contained in the <code>mod_cern_meta.c</code> file, and -is not compiled in by default. It provides for CERN httpd metafile -semantics. It is only available in Apache 1.1 and later. - -<h2>Summary</h2> - -Emulate the CERN HTTPD Meta file semantics. Meta files are HTTP -headers that can be output in addition to the normal range of headers -for each file accessed. They appear rather like the Apache -.asis files, and are able to provide a crude way of influencing -the Expires: header, as well as providing other curiosities. -There are many ways to manage meta information, this one was -chosen because there is already a large number of CERN users -who can exploit this module. - -<p>More information on the -<a href="http://www.w3.org/pub/WWW/Daemon/User/Config/General.html#MetaDir -">CERN metafile semantics</a> is available. - -<h2>Directives</h2> -<ul> -<li><A HREF="#metadir">MetaDir</A> -<li><A HREF="#metasuffix">MetaSuffix</A> -</ul> - -<hr> - -<h2><A name="metadir">MetaDir</A></h2> -<strong>Syntax:</strong> MetaDir <em>directory name</em><br> -<strong>Default:</strong> <code>MetaDir .web</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_cern_meta<br> -<strong>Compatibility:</strong> MetaDir is only available in Apache 1.1 -and later.<p> - -Specifies the name of the directory in which Apache can find -meta information files. The directory is usually a 'hidden' -subdirectory of the directory that contains the file being -accessed. Set to "<code>.</code>" to look in the same directory as the -file. - -<h2><A name="metasuffix">MetaSuffix</A></h2> -<strong>Syntax:</strong> MetaSuffix <em>suffix</em><br> -<strong>Default:</strong> <code>MetaSuffix .meta</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_cern_meta<br> -<strong>Compatibility:</strong> MetaSuffix is only available in Apache 1.1 -and later.<p> - -Specifies the file name suffix for the file containing the -meta information. For example, the default values for the two -directives will cause a request to <code> -DOCUMENT_ROOT/somedir/index.html</code> to look in -<code>DOCUMENT_ROOT/somedir/.web/index.html.meta</code> and will use -its contents to generate additional MIME header information. - -<p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_cgi.html b/docs/manual/mod/mod_cgi.html deleted file mode 100644 index fc06cf5c27..0000000000 --- a/docs/manual/mod/mod_cgi.html +++ /dev/null @@ -1,174 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> -<head> -<title>Apache module mod_cgi</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">Module mod_cgi</h1> - -This module is contained in the <code>mod_cgi.c</code> file, and -is compiled in by default. It provides for execution of CGI scripts. -Any file with mime type <code>application/x-httpd-cgi</code> will be -processed by this module. -<!--%plaintext <?INDEX {\tt application/x-httpd-cgi} mime type> --> -<!--%plaintext <?INDEX CGI scripts> --> - -<h2>Summary</h2> -Any file that has the mime type <code>application/x-httpd-cgi</code> -or handler <code>cgi-script</code> (Apache 1.1 or later) -will be treated as a CGI script, and run by the server, with its output -being returned to the client. Files acquire this type either by -having a name ending in an extension defined by the -<A HREF="mod_mime.html#addtype">AddType</A> directive, or by being in -a <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> directory. <p> - -When the server invokes a CGI script, it will add a variable called -<code>DOCUMENT_ROOT</code> to the environment. This variable will contain the -value of the <A HREF="core.html#documentroot">DocumentRoot</A> -configuration variable. - -<h2>CGI Environment variables</h2> -The server will set the CGI environment variables as described in the CGI -specification, with the following provisions: -<dl> -<dt>REMOTE_HOST -<dd>This will only be set if the server has not been compiled with -<code>MINIMAL_DNS</code>. -<dt>REMOTE_IDENT -<dd>This will only be set if -<A HREF="core.html#identitycheck">IdentityCheck</A> is set to <code>on</code>. -<dt>REMOTE_USER -<dd>This will only be set if the CGI script is subject to authentication. -</dl> -<P> - -<hr> - -<h2><a name="cgi_debug">CGI Debugging</a></h2> - -Debugging CGI scripts has traditionally been difficult, mainly because -it has -not -been possible to study the output (standard output and error) for -scripts -which are failing to run properly. These directives, included in -Apache 1.2 and later, provide -more detailed logging of errors when they occur. - -<hr> - -<h2>CGI Logfile Format</h2> - -When configured, the CGI error log logs any CGI which does not execute -properly. Each CGI script which fails to operate causes several lines -of information to be logged. The first two lines are always of the -format: - -<pre> - %% [<i>time</i>] <i>request-line</i> - %% <i>HTTP-status</i> <i>CGI-script-filename</i> -</pre> - -If the error is that CGI script cannot be run, the log file will -contain -an extra two lines: - -<pre> - %%error - <i>error-message</i> -</pre> - -Alternatively, if the error is the result of the script returning -incorrect header information (often due to a bug in the script), the -following information is logged: - -<pre> - %request - <i>All HTTP request headers received</i> - <i>POST or PUT entity (if any)</i> - %response - <i>All headers output by the CGI script</i> - %stdout - <i>CGI standard output</i> - %stderr - <i>CGI standard error</i> -</pre> - -(The %stdout and %stderr parts may be missing if the script did not -output -anything on standard output or standard error). - -<hr> - -<h2>Directives</h2> - -<h3><a name="scriptlog">ScriptLog</a></h3> - -<b>Syntax:</b> ScriptLog <i>filename</i><br> -<b>Default:</b> none<br> -<b>Context:</b> resource config<br> -<b>Status:</b> mod_cgi -<p> - -The <tt>ScriptLog</tt> directive sets the CGI script error logfile. -If no ScriptLog is given, no error log is created. If given, any -CGI errors are logged into the filename given as argument. If this -is a relative file or path it is taken relative to the server root. - -<P>This log will be opened as the user the child processes run as, -ie. the user specified in the main <A HREF="core.html#User">User</A> -directive. This means that either the directory the script log is -in needs to be writable by that user or the file needs to be manually -created and set to be writable by that user. If you place the -script log in your main logs directory, do <STRONG>NOT</STRONG> -change the directory permissions to make it writable by the user -the child processes run as.</P> - -<p>Note that script logging is meant to be a debugging feature when -writing CGI scripts, and is not meant to be activated continuously on -running servers. It is not optimized for speed or efficiency, and may -have security problems if used in a manner other than that for which -it was designed.</p> - -<h3><a name="scriptloglength">ScriptLogLength</a></h3> - -<b>Syntax:</b> ScriptLogLength <i>size</i><br> -<b>Default:</b> 10385760<br> -<b>Context:</b> resource config<br> -<b>Status:</b> mod_cgi -<p> - -<tt>ScriptLogLength</tt> can be used to limit the size of the CGI -script logfile. Since the logfile logs a lot of information per CGI -error (all request headers, all script output) it can grow to be a big -file. To prevent problems due to unbounded growth, this directive can -be used to set an maximum file-size for the CGI logfile. If the file -exceeds this size, no more information will be written to it. - -<h3><a name="scriptlogbuffer">ScriptLogBuffer</a></h3> - -<b>Syntax:</b> ScriptLogBuffer <i>size</i><br> -<b>Default:</b> 1024<br> -<b>Context:</b> resource config<br> -<b>Status:</b> mod_cgi -<p> - -The size of any PUT or POST entity body that is logged to the file is -limited, to prevent the log file growing too big too quickly if large -bodies are being received. By default, up to 1024 bytes are logged, -but this can be changed with this directive. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_dir.html b/docs/manual/mod/mod_dir.html deleted file mode 100644 index aebd31a5bb..0000000000 --- a/docs/manual/mod/mod_dir.html +++ /dev/null @@ -1,367 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_dir</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">Module mod_dir</H1> - -This module is contained in the <code>mod_dir.c</code> file, and -is compiled in by default. It provides for directory indexing. - -<h2>Summary</h2> -This module controls the directory indexing. The index of a directory -can come from one of two sources: -<ul> -<li>A file written by the user, typically called <code>index.html</code>. -The <A HREF="#directoryindex">DirectoryIndex</A> directive sets the name -of this file. -<li>Otherwise, a listing generated by the server. The other directives -control the format of this listing. The <A HREF="#addicon">AddIcon</A>, -<A HREF="#addiconbyencoding">AddIconByEncoding</A> and -<A HREF="#addiconbytype">AddIconByType</A> are used to set a list of -icons to display for various file types; for each file listed, the -first icon listed that matches the file is displayed. -</ul> - - -<h2>Directives</h2> - -<menu> -<li><A HREF="#addalt">AddAlt</A> -<li><A HREF="#addaltbyencoding">AddAltByEncoding</A> -<li><A HREF="#addaltbytype">AddAltByType</A> -<li><A HREF="#adddescription">AddDescription</A> -<li><A HREF="#addicon">AddIcon</A> -<li><A HREF="#addiconbyencoding">AddIconByEncoding</A> -<li><A HREF="#addiconbytype">AddIconByType</A> -<li><A HREF="#defaulticon">DefaultIcon</A> -<li><A HREF="#directoryindex">DirectoryIndex</A> -<li><A HREF="#fancyindexing">FancyIndexing</A> -<li><A HREF="#headername">HeaderName</A> -<li><A HREF="#indexignore">IndexIgnore</A> -<li><A HREF="#indexoptions">IndexOptions</A> -<li><A HREF="#readmename">ReadmeName</A> -</menu> -<hr> - -<A name="addalt"><h2>AddAlt</h2></A> -<!--%plaintext <?INDEX {\tt AddAlt} directive> --> -<strong>Syntax:</strong> AddAlt <em>string file file...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the alternate text to display for a file, instead of an icon, for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>File</em> is a file -extension, partial filename, wild-card expression or full filename for files -to describe. <em>String</em> is enclosed in double quotes -(<code>"</code>). This alternate text is displayed if the client is -image-incapable or has image loading disabled. - -<HR> -<A name="addaltbyencoding"><h2>AddAltByEncoding</h2></A> -<!--%plaintext <?INDEX {\tt AddAltByEncoding} directive> --> -<strong>Syntax:</strong> AddAltByEncoding <em>string MIME-encoding - MIME-encoding...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the alternate text to display for a file, instead of an icon, for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>MIME-encoding</em> is a -valid content-encoding, such as <SAMP>x-compress</SAMP>. -<em>String</em> is enclosed in double quotes -(<code>"</code>). This alternate text is displayed if the client is -image-incapable or has image loading disabled. - -<HR> -<A name="addaltbytype"><h2>AddAltByType</h2></A> -<!--%plaintext <?INDEX {\tt AddAltByType} directive> --> -<strong>Syntax:</strong> AddAltByType <em>string MIME-type MIME-type...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the alternate text to display for a file, instead of an icon, for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>MIME-type</em> is a -valid content-type, such as <SAMP>text/html</SAMP>. -<em>String</em> is enclosed in double quotes -(<code>"</code>). This alternate text is displayed if the client is -image-incapable or has image loading disabled. - -<HR> - -<A name="adddescription"><h2>AddDescription</h2></A> -<!--%plaintext <?INDEX {\tt AddDescription} directive> --> -<strong>Syntax:</strong> AddDescription <em>string file file...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the description to display for a file, for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>File</em> is a file -extension, partial filename, wild-card expression or full filename for files -to describe. <em>String</em> is enclosed in double quotes -(<code>"</code>). Example: -<blockquote><code>AddDescription "The planet Mars" /web/pics/mars.gif -</code></blockquote><p><hr> - -<A name="addicon"><h2>AddIcon</h2></A> -<!--%plaintext <?INDEX {\tt AddIcon} directive> --> -<strong>Syntax:</strong> AddIcon <em>icon name name ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the icon to display next to a file ending in <em>name</em> for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>Icon</em> is either a -(%-escaped) relative URL to the icon, or of the format -(<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag given -for an icon for non-graphical browsers.<p> - -<em>Name</em> is either ^^DIRECTORY^^ for directories, ^^BLANKICON^^ for -blank lines (to format the list correctly), a file extension, a wildcard -expression, a partial filename or a complete filename. Examples: -<blockquote><code> -AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm <br> -AddIcon /icons/dir.xbm ^^DIRECTORY^^ <br> -AddIcon /icons/backup.xbm *~ -</code></blockquote> -<A HREF="#addiconbytype">AddIconByType</A> should be used in preference to -AddIcon, when possible.<p><hr> - -<A name="addiconbyencoding"><h2>AddIconByEncoding</h2></A> -<!--%plaintext <?INDEX {\tt AddIconByEncoding} directive> --> -<strong>Syntax:</strong> AddIconByEncoding <em>icon mime-encoding mime-encoding -...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the icon to display next to files with -<em>mime-encoding</em> for <A HREF="#fancyindexing">FancyIndexing</A>. -<em>Icon</em> is either a (%-escaped) relative URL to the icon, or of the -format (<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag -given for an icon for non-graphical browsers.<p> - -<em>Mime-encoding</em> is a wildcard expression matching required the -content-encoding. Examples: -<blockquote><code> -AddIconByEncoding /icons/compress.xbm x-compress -</code></blockquote><p><hr> - -<A name="addiconbytype"><h2>AddIconByType</h2></A> -<!--%plaintext <?INDEX {\tt AddIconByType} directive> --> -<strong>Syntax:</strong> AddIconByType <em>icon mime-type mime-type ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the icon to display next to files of type <em>mime-type</em> for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>Icon</em> is either a -(%-escaped) relative URL to the icon, or of the format -(<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag given -for an icon for non-graphical browsers.<p> -<em>Mime-type</em> is a wildcard expression matching required the mime types. -Examples: -<blockquote><code> -AddIconByType (IMG,/icons/image.xbm) image/* -</code></blockquote><p><hr> - -<A name="defaulticon"><h2>DefaultIcon</h2></A> -<!--%plaintext <?INDEX {\tt DefaultIcon} directive> --> -<strong>Syntax:</strong> DefaultIcon <em>url</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The DefaultIcon directive sets the icon to display for files when no -specific icon is known, for <A HREF="#fancyindexing">FancyIndexing</A>. -<em>Url</em> is a (%-escaped) relative URL to the icon. Examples: -<blockquote><code> -DefaultIcon /icon/unknown.xbm -</code></blockquote><p><hr> - -<A name="directoryindex"><h2>DirectoryIndex</h2></A> -<!--%plaintext <?INDEX {\tt DirectoryIndex} directive> --> -<strong>Syntax:</strong> DirectoryIndex <em>local-url local-url ...</em><br> -<strong>Default:</strong> <code>DirectoryIndex index.html</code><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The DirectoryIndex directive sets the list of resources to look for, -when the client requests an index of the directory by specifying a / -at the end of the a directory name. <em>Local-url</em> is the -(%-encoded) URL of a document on the server relative to the requested -directory; it is usually the name of a file in the directory. Several -URLs may be given, in which case the server will return the first one -that it finds. If none of the resources exist and the -<CODE>Indexes</CODE> option is set, the server will generate its own -listing of the directory. -<P> - -Example: -<blockquote><code> -DirectoryIndex index.html -</code></blockquote> -then a request for <code>http://myserver/docs/</code> would return -<code>http://myserver/docs/index.html</code> if it exists, or would list -the directory if it did not. <p> - -Note that the documents do not need to be relative to the directory; -<blockquote><code> -DirectoryIndex index.html index.txt /cgi-bin/index.pl</code></blockquote> -would cause the CGI script <code>/cgi-bin/index.pl</code> to be executed -if neither <code>index.html</code> or <code>index.txt</code> existed in -a directory.<p><hr> - -<A name="fancyindexing"><h2>FancyIndexing</h2></A> -<!--%plaintext <?INDEX {\tt FancyIndexing} directive> --> -<strong>Syntax:</strong> FancyIndexing <em>boolean</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The FancyIndexing directive sets the FancyIndexing option for a directory. -<em>Boolean</em> can be <code>on</code> or <code>off</code>. The -<A HREF="#indexoptions">IndexOptions</A> directive should be used in -preference.<p><hr> - -<A name="headername"><h2>HeaderName</h2></A> -<!--%plaintext <?INDEX {\tt HeaderName} directive> --> -<strong>Syntax:</strong> HeaderName <em>filename</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The HeaderName directive sets the name of the file that will be inserted -at the top of the index listing. <em>Filename</em> is the name of the file -to include, and is taken to be relative to the directory being indexed. -The server first attempts to include <em>filename</em><code>.html</code> -as an HTML document, otherwise it will include <em>filename</em> as plain -text. Example: -<blockquote><code>HeaderName HEADER</code></blockquote> -when indexing the directory <code>/web</code>, the server will first look for -the HTML file <code>/web/HEADER.html</code> and include it if found, otherwise -it will include the plain text file <code>/web/HEADER</code>, if it exists. - -<p>See also <A HREF="#readmename">ReadmeName</A>.<p><hr> - -<A name="indexignore"><h2>IndexIgnore</h2></A> -<!--%plaintext <?INDEX {\tt IndexIgnore} directive> --> -<strong>Syntax:</strong> IndexIgnore <em>file file ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The IndexIgnore directive adds to the list of files to hide when listing -a directory. <em>File</em> is a file extension, partial filename, -wildcard expression or full filename for files to ignore. Multiple -IndexIgnore directives add to the list, rather than the replacing the list -of ignored files. By default, the list contains `<code>.</code>'. Example: -<blockquote><code> -IndexIgnore README .htaccess *~ -</code></blockquote><p><hr> - -<A name="indexoptions"><h2>IndexOptions</h2></A> -<!--%plaintext <?INDEX {\tt IndexOptions} directive> --> -<strong>Syntax:</strong> IndexOptions <em>option option ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The IndexOptions directive specifies the behavior of the directory indexing. -<em>Option</em> can be one of -<dl> -<dt>FancyIndexing -<dd><!--%plaintext <?INDEX {\tt FancyIndexing} index option> --> -This turns on fancy indexing of directories. -<dt>IconsAreLinks -<dd> -<!--%plaintext <?INDEX {\tt IconsAreLinks} index option> --> -This makes the icons part of the anchor for the filename, for -fancy indexing. -<dt>ScanHTMLTitles -<dd><!--%plaintext <?INDEX {\tt ScanHTMLTitles} index option> --> -This enables the extraction of the title from HTML documents for fancy -indexing. If the file does not have a description given by -<A HREF="#adddescription">AddDescription</A> then httpd will read the -document for the value of the TITLE tag. This is CPU and disk intensive. -<dt>SuppressLastModified -<dd> -<!--%plaintext <?INDEX {\tt SuppressLastModified} index option> --> -This will suppress the display of the last modification date, in fancy -indexing listings. -<dt>SuppressSize -<dd> -<!--%plaintext <?INDEX {\tt SuppressSize} index option> --> -This will suppress the file size in fancy indexing listings. -<dt>SuppressDescription -<dd> -<!--%plaintext <?INDEX {\tt SuppressDescription} index option> --> -This will suppress the file description in fancy indexing listings. -</dl> -This default is that no options are enabled. If multiple IndexOptions -could apply to a directory, then the most specific one is taken complete; -the options are not merged. For example: -<blockquote><code> -<Directory /web/docs> <br> -IndexOptions FancyIndexing <br> -</Directory><br> -<Directory /web/docs/spec> <br> -IndexOptions ScanHTMLTitles <br> -</Directory> -</code></blockquote> -then only <code>ScanHTMLTitles</code> will be set for the /web/docs/spec -directory.<p><hr> - -<A name="readmename"><h2>ReadmeName</h2></A> -<!--%plaintext <?INDEX {\tt ReadmeName} directive> --> -<strong>Syntax:</strong> ReadmeName <em>filename</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The ReadmeName directive sets the name of the file that will be appended -to the end of the index listing. <em>Filename</em> is the name of the file -to include, and is taken to be relative to the directory being indexed. -The server first attempts to include <em>filename</em><code>.html</code> -as an HTML document, otherwise it will include <em>filename</em> as plain -text. Example: -<blockquote><code>ReadmeName README</code></blockquote> -when indexing the directory <code>/web</code>, the server will first look for -the HTML file <code>/web/README.html</code> and include it if found, otherwise -it will include the plain text file <code>/web/README</code>, if it exists. - -<p>See also <A HREF="#headername">HeaderName</A>.<p> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_env.html b/docs/manual/mod/mod_env.html deleted file mode 100644 index 0ee71931b3..0000000000 --- a/docs/manual/mod/mod_env.html +++ /dev/null @@ -1,92 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_env</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 module mod_env</h1> - -This module is contained in the <code>mod_env.c</code> file, and -is not compiled in by default. It provides for -passing environment variables to CGI/SSI scripts. Is is only available -in Apache 1.1 and later. - -<h2>Summary</h2> - -This module allows Apache's CGI and SSI environment to inherit -environment variables from the shell which invoked the httpd process. -CERN web-servers are able to do this, so this module is especially -useful to web-admins who wish to migrate from CERN to Apache without -rewriting all their scripts - -<h2>Directives</h2> -<ul> -<li><A HREF="#passenv">PassEnv</A> -<li><A HREF="#setenv">SetEnv</A> -<li><A HREF="#unsetenv">UnsetEnv</A> -</ul> - -<hr> - -<h2><A name="passenv">PassEnv</A></h2> -<strong>Syntax:</strong> PassEnv <em>variable variable ...</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_env<br> -<strong>Compatibility:</strong> PassEnv is only available in -Apache 1.1 and later.<p> - -Specifies one or more environment variables to pass to CGI scripts -from the server's own environment. Example: -<pre> - PassEnv LD_LIBRARY_PATH -</pre> - -<HR> - -<h2><A name="setenv">SetEnv</A></h2> -<strong>Syntax:</strong> SetEnv <em>variable value</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_env<br> -<strong>Compatibility:</strong> SetEnv is only available in -Apache 1.1 and later.<p> - -Sets an environment variable, which is then passed on to CGI -scripts. Example: -<pre> - SetEnv SPECIAL_PATH /foo/bin -</pre> - -<hr> - -<h2><A name="unsetenv">UnsetEnv</A></h2> -<strong>Syntax:</strong> UnsetEnv <em>variable variable ...</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_env<br> -<strong>Compatibility:</strong> UnsetEnv is only available in -Apache 1.1 and later.<p> - -Removes one or more environment variables from those passed on to -CGI scripts. Example: -<pre> - UnsetEnv LD_LIBRARY_PATH -</pre> - - - -<p> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_example.html b/docs/manual/mod/mod_example.html deleted file mode 100644 index 5ac54af327..0000000000 --- a/docs/manual/mod/mod_example.html +++ /dev/null @@ -1,140 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_example</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">Module mod_example</h1> - <P> - This module is contained in the <CODE>modules/mod_example.c</CODE> file, and - <STRONG>is not</STRONG> compiled in by default. It illustrates many of - the aspects of the - <A - HREF="../misc/API.html" - REL="Help" - >Apache 1.2 API</A> - and, when used, demonstrates the manner in which module callbacks are - triggered by the server. - </P> - <H2>Summary</H2> - <P> - The files in the <CODE>src/modules/example directory</CODE> under the - Apache distribution directory tree are provided as an example to those - that wish to write modules that use the Apache API. - </P> - <P> - The main file is <CODE>mod_example.c</CODE>, which illustrates all - the different callback mechanisms and call syntaces. By no means does - an add-on module need to include routines for all of the callbacks - - quite the contrary! - </P> - <P> - The example module is an actual working module. If you link it into - your server, enable the "example-handler" handler for a location, and - then browse to that location, you will see a display of - some of the tracing the example module did as the various callbacks - were made. - </P> - <P> - To include the example module in your server, follow the steps below: - </P> - <OL> - <LI>Uncomment the "Module example_module" line near the bottom of - the <CODE>src/Configuration</CODE> file. If there isn't one, add - it; it should look like this: - <PRE> - Module example_module modules/example/mod_example.o - </PRE> - </LI> - <LI>Run the <CODE>src/Configure</CODE> script - ("<SAMP>cd src; ./Configure</SAMP>"). This will - build the Makefile for the server itself, and update the - <CODE>src/modules/Makefile</CODE> for any additional modules you - have requested from beneath that subdirectory. - </LI> - <LI>Make the server (run "<SAMP>make</SAMP>" in the <CODE>src</CODE> - directory). - </LI> - </OL> - <P> - To add another module of your own: - </P> - <OL TYPE="A"> - <LI><SAMP>mkdir src/modules/<EM>mymodule</EM></SAMP> - </LI> - <LI><SAMP>cp src/modules/example/* src/modules/<EM>mymodule</EM></SAMP> - </LI> - <LI>Modify the files in the new directory. - </LI> - <LI>Follow steps [1] through [3] above, with appropriate changes. - </LI> - </OL> - <H3> - Using the <SAMP>mod_example</SAMP> Module - </H3> - <P> - To activate the example module, include a block similar to the - following in your <SAMP>srm.conf</SAMP> file: - </P> - <PRE> - <Location /example-info> - SetHandler example-handler - </Location> - </PRE> - <P> - As an alternative, you can put the following into a - <A - HREF="core.html#accessfilename" - ><SAMP>.htaccess</SAMP></A> - file and then request the file "test.example" from that - location: - </P> - <PRE> - AddHandler example-handler .example - </PRE> - <P> - After reloading/restarting your server, you should be able to browse - to this location and see the brief display mentioned earlier. - </P> - <H2>Directives</H2> - <P> - <UL> - <LI><A HREF="#example">Example</A> - </LI> - </UL> - </P> - <HR> - <H2><A NAME="example"> - Example - </A></H2> - <P> - <STRONG>Syntax:</STRONG> Example - <BR> - <STRONG>Default:</STRONG> None - <BR> - <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess - <BR> - <STRONG>Override:</STRONG> Options - <BR> - <STRONG>Status:</STRONG> Extension - <BR> - <STRONG>Module:</STRONG> mod_example - </P> - <P> - The Example directive activates the example module's content handler - for a particular location or file type. It takes no arguments. If - you browse to an URL to which the example content-handler applies, you - will get a display of the routines within the module and how and in - what order they were called to service the document request. - </P> - <!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/mod_expires.html b/docs/manual/mod/mod_expires.html deleted file mode 100644 index 3ec53d1156..0000000000 --- a/docs/manual/mod/mod_expires.html +++ /dev/null @@ -1,185 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_expires</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">Module mod_expires</H1> - <P> - This module is contained in the <CODE>mod_expires.c</CODE> file, and - is <STRONG>not</STRONG> compiled in by default. It provides for the - generation of <CODE>Expires</CODE> headers according to user-specified - criteria. - </P> - <H2>Summary</H2> - <P> - This module controls the setting of the <CODE>Expires</CODE> HTTP - header in server responses. The expiration date can set to be - relative to either the time the source file was last modified, or to - the time of the client access. - </P> - <P> - The <CODE>Expires</CODE> HTTP header is an instruction to the client - about the document's validity and persistence. If cached, the document - may be fetched from the cache rather than from the source until this - time has passed. After that, the cache copy is considered - "expired" and invalid, and a new copy must be obtained from - the source. - </P> - <H2>Directives</H2> - <P> - <MENU> - <LI><A - HREF="#expiresactive" - >ExpiresActive</A> - </LI> - <LI><A - HREF="#expiresbytype" - >ExpiresByType</A> - </LI> - <LI><A - HREF="#expiresdefault" - >ExpiresDefault</A> - </LI> - </MENU> - <HR> - <H2><A NAME="expiresactive"> - ExpiresActive directive - </A></H2> - <!--%plaintext <?INDEX {\tt ExpiresActive} directive> --> - <P> - <STRONG>Syntax:</STRONG> ExpiresActive <EM>boolean</EM> - <BR> - <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess - <br> - <STRONG>Override:</STRONG> Indexes - <br> - <STRONG>Status:</STRONG> Extension - <br> - <STRONG>Module:</STRONG> mod_expires - </P> - <P> - This directive enables or disables the generation of the - <CODE>Expires</CODE> header for the document realm in question. (That - is, if found in an <CODE>.htaccess</CODE> file, for instance, it - applies only to documents generated from that directory.) If set to - <EM><CODE>Off</CODE></EM>, no <CODE>Expires</CODE> header will be - generated for any document in the realm (unless overridden at a lower - level, such as an <CODE>.htaccess</CODE> file overriding a server - config file). If set to <EM><CODE>On</CODE></EM>, the header will be - added to served documents according to the criteria defined by the - <A - HREF="#expiresbytype" - >ExpiresByType</A> - and - <A - HREF="#expiresdefault" - >ExpiresDefault</A> - directives (<EM>q.v.</EM>). - </P> - <P> - Note that this directive does not guarantee that an - <CODE>Expires</CODE> header will be generated. If the criteria aren't - met, no header will be sent, and the effect will be as though this - directive wasn't even specified. - </P> - <HR> - <H2><A NAME="expiresbytype"> - ExpiresByType directive - </A></H2> - <!--%plaintext <?INDEX {\tt ExpiresByType} directive> --> - <P> - <STRONG>Syntax:</STRONG> ExpiresByType <EM>mime-type <code>seconds</EM> - <BR> - <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess - <br> - <STRONG>Override:</STRONG> Indexes - <br> - <STRONG>Status:</STRONG> Extension - <br> - <STRONG>Module:</STRONG> mod_expires - </P> - <P> - This directive defines the value of the <CODE>Expires</CODE> header - generated for documents of the specified type (<EM>e.g.</EM>, - <CODE>text/html</CODE>). The second argument sets the number of - seconds that will be added to a base time to construct the expiration - date. - </P> - <P> - The base time is either the last modification time of the file, or the - time of the client's access to the document. Which should be used is - specified by the <CODE><EM><code></EM></CODE> field; - <STRONG>M</STRONG> means that the file's last modification time should - be used as the base time, and <STRONG>A</STRONG> means the client's - access time should be used. - </P> - <P> - The difference in effect is subtle. If <EM>M</EM> is used, all current - copies of the document in all caches will expire at the same time, - which can be good for something like a weekly notice that's always - found at the same URL. If <EM>A</EM> is used, the date of expiration - is different for each client; this can be good for image files that - don't change very often, particularly for a set of related documents - that all refer to the same images (<EM>i.e.</EM>, the images will be - accessed repeatedly within a relatively short timespan). - </P> - <P> - <STRONG>Example:</STRONG> - </P> - <P> - <PRE> - ExpiresActive On # enable expirations - ExpiresByType image/gif A2592000 # expire GIF images after a month - # in the client's cache - ExpiresByType text/html M604800 # HTML documents are good for a - # week from the time they were - # changed, period - </PRE> - </P> - <P> - Note that this directive only has effect if <CODE>ExpiresActive - On</CODE> has been specified. It overrides, for the specified MIME - type <EM>only</EM>, any expiration date set by the - <A - HREF="#expiresdefault" - >ExpiresDefault</A> - directive. - </P> - <HR> - <H2><A NAME="expiresdefault"> - ExpiresDefault directive - </A></H2> - <!--%plaintext <?INDEX {\tt ExpiresDefault} directive> --> - <P> - <STRONG>Syntax:</STRONG> ExpiresDefault <EM><code>seconds</EM> - <BR> - <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess - <br> - <STRONG>Override:</STRONG> Indexes - <br> - <STRONG>Status:</STRONG> Extension - <br> - <STRONG>Module:</STRONG> mod_expires - </P> - <P> - This directive sets the default algorithm for calculating the - expiration time for all documents in the affected realm. It can be - overridden on a type-by-type basis by the - <A - HREF="#expiresbytype" - >ExpiresByType</A> - directive. See the description of that directive for details about - the syntax of the argument. - </P> - <!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/mod_headers.html b/docs/manual/mod/mod_headers.html deleted file mode 100644 index aed34f04db..0000000000 --- a/docs/manual/mod/mod_headers.html +++ /dev/null @@ -1,104 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_headers</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">Headers Module</h1> - -The optional headers module allows for the customization of HTTP -response headers. Headers can be merged, replaced or removed. The -directives described in this document are only available if Apache is -compiled with <b>mod_headers.c</b>. - -<hr> - -<h2>Directive</h2> -<ul> -<li><A HREF="#header">Header</A> -</ul> - -<hr> - -<h2><A name="header">Header</A></h2> -<strong>Syntax:</strong> Header [ set | append | add ] <em>header</em> <em>value</em><br> -<strong>Syntax:</strong> Header unset <em>header</em><br> -<strong>Context:</strong> server config, virtual host, access.conf, .htaccess<br> -<strong>Status:</strong> optional<br> -<strong>Module:</strong> mod_header<p> - -This directive can replace, merge or remove HTTP response headers. The -action it performs is determined by the first argument. This can be one -of the following values: - -<ul> -<li><b>set</b><br> - The response header is set, replacing any previous header with this name - -<li><b>append</b><br> - The response header is appended to any existing header of the same - name. When a new value is merged onto an existing header it is - separated from the existing header with a comma. This is the HTTP standard - way of giving a header multiple values. - -<li><b>add</b><br> - The response header is added to the existing set of headers, even if - this header already exists. This can result in two (or more) headers - having the same name. This can lead to unforeseen consequences, and in - general "append" should be used instead. - -<li><b>unset</b><br> - The response header of this name is removed, if it exists. If there are - multiple headers of the same name, only the first one set will be removed. -</ul> - -This argument is followed by a header name, which can include the -final colon, but it is not required. Case is ignored. For -add, append and set a value is given as the third argument. If this -value contains spaces, it should be surrounded by double quotes. -For unset, no value should be given. - -<h3>Order of Processing</h3> - -The Header directive can occur almost anywhere within the server -configuration. It is valid in the main server config and virtual host -sections, inside <Directory>, <Location> and <Files> -sections, and within .htaccess files. -<p> -The Header directives are processed in the following order: -<ol> -<li>main server -<li>virtual host -<li><Directory> sections and .htaccess -<li><Location> -<li><Files> -</ol> - -Order is important. These two headers have a different effect if reversed: -<pre> -Header append Author "John P. Doe" -Header unset Author -</pre> - -This way round, the Author header is not set. If reversed, the Author -header is set to "John P. Doe". -<p> - -The Header directives are processed just before the response is sent -by its handler. These means that some headers that are added just -before the response is sent cannot be unset or overridden. This -includes headers such as "Date" and "Server". -<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_imap.html b/docs/manual/mod/mod_imap.html deleted file mode 100644 index 718f3fb683..0000000000 --- a/docs/manual/mod/mod_imap.html +++ /dev/null @@ -1,284 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> -<head> -<title>Apache module mod_imap</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">Module mod_imap</h1> - -This module is contained in the <code>mod_imap.c</code> file, and is -compiled in by default. It provides for <code>.map</code> files, -replacing the functionality of the <code>imagemap</code> CGI -program. Any directory or document type configured to use the handler -<code>imap-file</code> (using either <code><A -HREF="mod_mime.html#addhandler">AddHandler</A> </code> or <code><A -HREF="mod_mime.html#sethandler">SetHandler</A></code>) will be -processed by this module. - -<h2>Summary</h2> - -This module is in the default Apache distribution. The following directive will -activate files ending with <code>.map</code> as imagemap files: - -<blockquote><code>AddHandler imap-file map</code></blockquote> - -Note that the following is still supported: - - <blockquote><code>AddType application/x-httpd-imap map</code></blockquote> - -However, we are trying to phase out "magic MIME types" so we are deprecating -this method. - -<H2>New Features</H2> -The imagemap module adds some new features that were not -possible with previously distributed imagemap programs.<P> - -<ul> -<LI>URL references relative to the Referer: information. -<LI>Default <BASE> assignment through a new map directive -<code>base</code>. -<LI>No need for <code>imagemap.conf</code> file. -<LI>Point references. -<LI>Configurable generation of imagemap menus. -</ul> -<P> - -<h2>Configuration Directives</h2> -<ul> -<li><A HREF="#imapmenu">ImapMenu</A> -<li><A HREF="#imapdefault">ImapDefault</A> -<li><A HREF="#imapbase">ImapBase</A> -</ul> - - -<p> - -<h3><A name="imapmenu">ImapMenu</A></h3> -<strong>Syntax:</strong> ImapMenu <code>{none, formatted, semi-formatted, - unformatted}</code><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Module:</strong> mod_imap.c<br> -<strong>Compatibility:</strong> ImapMenu is only available in Apache -1.1 and later.<p> - -The ImapMenu directive determines the action taken if an imagemap file -is called without valid coordinates. -<dl> - <dt><code>none</code> - <dd>If ImapMenu is - <code>none</code>, no menu is generated, and the <code>default</code> - action is performed. - <dt><code>formatted</code> - <dd>A <code>formatted</code> menu is the simplest menu. Comments - in the imagemap file are ignored. A level one header is - printed, then an hrule, then the links each on a separate line. - The menu has a consistent, plain look close to that of - a directory listing. - <dt><code>semiformatted</code> - <dd>In the <code>semiformatted</code> menu, comments are printed - where they occur in the imagemap file. Blank lines are turned - into HTML breaks. No header or hrule is printed, but otherwise - the menu is the same as a <code>formatted</code> menu. - <dt><code>unformatted</code> - <dd>Comments are printed, blank lines are ignored. Nothing is - printed that does not appear in the imagemap file. All breaks - and headers must be included as comments in the imagemap file. - This gives you the most flexibility over the appearance of your - menus, but requires you to treat your map files as HTML instead - of plaintext. -</dl> - -<p> - -<h3><A name="imapdefault">ImapDefault</A></h3> -<strong>Syntax:</strong> ImapDefault <code>{error, nocontent, - map, referer, URL}</code><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Module:</strong> mod_imap.c<br> -<strong>Compatibility:</strong> ImapDefault is only available in Apache -1.1 and later.<p> - - -The ImapDefault directive sets the default <code>default</code> used in -the imagemap files. It's value is overridden by a <code>default</code> -directive within the imagemap file. If not present, the -<code>default</code> action is <code>nocontent</code>, which means -that a <code>204 No Content</code> is sent to the client. In this -case, the client should continue to display the original page. - -<p> - -<h3><A name="imapbase">ImapBase</A></h3> -<strong>Syntax:</strong> ImapBase <code>{map, referer, URL}</code><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Module:</strong> mod_imap.c<br> -<strong>Compatibility:</strong> ImapBase is only available in Apache -1.1 and later.<p> - -The ImapBase directive sets the default <code>base</code> used in -the imagemap files. It's value is overridden by a <code>base</code> -directive within the imagemap file. If not present, the -<code>base</code> defaults to <code>http://servername/</code>. - -<hr> -<p> - -<h2>Imagemap File</h2> -The lines in the imagemap files can have one of several formats: -<blockquote> -<code>directive value [x,y ...]</code><br> -<code>directive value "Menu text" [x,y ...]</code><br> -<code>directive value x,y ... "Menu text"</code><br> -</blockquote> -The directive is one of <code>base</code>, <code>default</code>, -<code>poly</code>, <code>circle</code>, <code>rect</code>, or -<code>point</code>. The value is an absolute or relative URL, or one -of the special values listed below. The coordinates are -<code>x,y</code> pairs separated by whitespace. The quoted text is -used as the text of the link if a imagemap menu is generated. Lines -beginning with '#' are comments. - -<h3>Imagemap File Directives</h3> -There are six directives allowed in the imagemap file. The directives -can come in any order, but are processed in the order they are found -in the imagemap file. -<dl> -<dt><code>base</code> Directive -<dd>Has the effect of <code><BASE href="value"></code>. The - non-absolute URLs of the map-file are taken relative to this value. - The <code>base</code> directive overrides ImapBase as set in a - .htaccess file or in the server configuration files. In the absence - of an ImapBase configuration directive, <code>base</code> defaults to - <code>http://server_name/</code>. <br> - <code>base_uri</code> is synonymous with <code>base</code>. Note that - a trailing slash on the URL is significant. -<p> -<dt><code>default</code> Directive -<dd>The action taken if the coordinates given do not fit any of the - <code>poly</code>, <code>circle</code> or <code>rect</code> - directives, and there are no <code>point</code> directives. Defaults - to <code>nocontent</code> in the absence of an ImapDefault - configuration setting, causing a status code of <code>204 No - Content</code> to be returned. The client should keep the same - page displayed. -<p> -<dt><code>poly</code> Directive -<dd>Takes three to one-hundred points, and is obeyed if the user selected - coordinates fall within the polygon defined by these points. -<p> -<dt><code>circle</code> -<dd>Takes the center coordinates of a circle and a point on the circle. Is - obeyed if the user selected point is with the circle. -<p> -<dt><code>rect</code> Directive -<dd>Takes the coordinates of two opposing corners of a rectangle. Obeyed - if the point selected is within this rectangle. -<p> -<dt><code>point</code> Directive -<dd>Takes a single point. The point directive closest to the user - selected point is obeyed if no other directives are satisfied. - Note that <code>default</code> will not be followed if a - <code>point</code> directive is present and valid coordinates are - given. -</dl> - - - -<h3>Values</h3> -The values for each of the directives can any of the following: -<dl> - <dt>a URL - <dd>The URL can be relative or absolute URL. Relative URLs can - contain '..' syntax and will be resolved relative to the - <code>base</code> value. <br> - <code>base</code> itself will not resolved according to the current - value. A statement <code>base mailto:</code> will work properly, though. -<p> - <dt><code>map</code> - <dd>Equivalent to the URL of the imagemap file itself. No - coordinates are sent with this, so a menu will be generated - unless ImapMenu is set to 'none'. -<p> - <dt><code>menu</code> - <dd>Synonymous with <code>map</code>. -<p> - <dt><code>referer</code> - <dd>Equivalent to the URL of the referring document. - Defaults to <code>http://servername/</code> if no Referer: - header was present. -<p> - <dt><code>nocontent</code> - <dd>Sends a status code of <code>204 No Content</code>, - telling the client to keep the same page displayed. Valid for - all but <code>base</code>. -<p> - <dt><code>error</code> - <dd>Fails with a <code>500 Server Error</code>. Valid for all but - <code>base</code>, but sort of silly for anything but - <code>default</code>. -</dl> - -<h3>Coordinates</h3> -<dl> - <dt><code>0,0 200,200</code> - <dd>A coordinate consists of an <tt>x</tt> and a <tt>y</tt> value - separated by a comma. The coordinates are separated from each other - by whitespace. To accommodate the way Lynx handles imagemaps, should a - user select the coordinate <code>0,0</code>, it is as if - no coordinate had been selected. -</dl> - -<h3>Quoted Text</h3> -<dl> - <dt><code>"Menu Text"</code> - <dd>After the value or after the coordinates, the line optionally may - contain text within double quotes. This string is used as the - text for the link if a menu is generated:<br> - <code><a href="http://foo.com/">Menu text</a></code><br> - If no quoted text is present, the name of the link will be used - as the text:<br> - <code><a href="http://foo.com/">http://foo.com</a></code><br> - It is impossible to escape double quotes within this text. -</dl> - -<hr> - -<h2>Example Mapfile</h2> -<blockquote><code> -#Comments are printed in a 'formatted' or 'semiformatted' menu. <br> -#And can contain html tags. <hr> <br> -base referer <br> -poly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0 <br> -rect .. 0,0 77,27 "the directory of the referer"<br> -circle http://www.inetnebr.com/lincoln/feedback/ 195,0 305,27 <br> -rect another_file "in same directory as referer" 306,0 419,27 <br> -point http://www.zyzzyva.com/ 100,100 <br> -point http://www.tripod.com/ 200,200 <br> -rect mailto:nate@tripod.com 100,150 200,0 "Bugs?" <br> -</code></blockquote> -<P> - -<h2>Referencing your mapfile</h2> -<blockquote><code> -<A HREF="/maps/imagmap1.map"> <br> -<IMG ISMAP SRC="/images/imagemap1.gif"> <br> -</A> -</code></blockquote><p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - - diff --git a/docs/manual/mod/mod_include.html b/docs/manual/mod/mod_include.html deleted file mode 100644 index 6f51130998..0000000000 --- a/docs/manual/mod/mod_include.html +++ /dev/null @@ -1,385 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_include</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">Module mod_include</H1> - -This module is contained in the <code>mod_include.c</code> file, and -is compiled in by default. It provides for server-parsed html -documents. Several directives beyond the original NCSA definition have been -included in Apache 1.2 - these are flagged below with the phrase -"Apache 1.2 and above". Of particular significance are the new flow -control directives documented at the bottom. - -<H2>Enabling Server-Side Includes</H2> - -Any document with handler of "server-parsed" will be parsed by this -module, if the <CODE>Includes</CODE> option is set. If documents -containing server-side include directives are given the extension -.shtml, the following directives will make Apache parse them and -assign the resulting document the mime type of <CODE>text/html</CODE>: - -<PRE> -AddType text/html .shtml -AddHandler server-parsed .shtml -</PRE> - -The following directive must be given for the directories containing -the shtml files (typically in a <CODE><Directory></CODE> section, -but this directive is also valid .htaccess files if <CODE>AllowOverride -Options</CODE> is set): - -<PRE> -Options +Includes -</PRE> - -Alternatively the <A HREF="#xbithack"><CODE>XBitHack</CODE></A> -directive can be used to parse normal (<CODE>text/html</CODE>) files, -based on file permissions. <P> - -For backwards compatibility, documents with mime type -<code>text/x-server-parsed-html</code> or -<code>text/x-server-parsed-html3</code> will also be parsed -(and the resulting output given the mime type <code>text/html</code>). - -<h2>Basic Elements</h2> - -The document is parsed as an HTML document, with special commands embedded -as SGML comments. A command has the syntax: - -<blockquote><code> -<!--#</code><em>element attribute=value attribute=value ...</em> -<code> --> -</code></blockquote> - -The value will often be enclosed in double quotes; many commands only allow -a single attribute-value pair. Note that the comment terminator -(<SAMP>--></SAMP>) should be preceded by whitespace to ensure that it -isn't considered part of an SSI token. -<p> -The allowed elements are:<p> - -<dl> - -<dt><strong>config</strong> -<dd> -This command controls various aspects of the parsing. The valid attributes -are: -<dl> -<dt>errmsg -<dd>The value is a message that is sent back to the client if an error occurs -whilst parsing the document. -<dt>sizefmt -<dd>The value sets the format to be used which displaying the size of a file. -Valid values are <code>bytes</code> for a count in bytes, or -<code>abbrev</code> for a count in Kb or Mb as appropriate. -<dt>timefmt -<dd>The value is a string to be used by the <code>strftime(3)</code> library -routine when printing dates. -</dl> - -<dt><strong>echo</strong> -<dd> -This command prints one of the include variables, defined below. -If the variable is unset, it is printed as <code>(none)</code>. -Any dates printed are subject to the currently configured <code>timefmt</code>. -Attributes: -<dl> -<dt>var -<dd>The value is the name of the variable to print. -</dl> - -<dt><strong>exec</strong> -<dd> -The exec command executes a given shell command or CGI script. -The IncludesNOEXEC <A HREF="core.html#options">Option</A> disables this command -completely. The valid attributes are: -<dl> -<dt>cgi -<dd> -The value specifies a (%-encoded) URL relative path to the CGI script. -If the path does not begin with a (/), then it is taken to be relative to -the current document. The document referenced by this path is invoked -as a CGI script, even if the server would not normally recognize it as -such. However, the directory containing the script must be enabled for -CGI scripts (with <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> -or the ExecCGI <A HREF="core.html#options">Option</A>).<p> -The CGI script is given the PATH_INFO and query string (QUERY_STRING) of the -original request from the client; these cannot be specified in the URL path. -The include variables will be available to the script in addition to the -standard <A HREF="mod_cgi.html">CGI</A> environment.<p> -If the script returns a Location: header instead of output, then this -will be translated into an HTML anchor.<p> -The <code>include virtual</code> element should be used in preference to -<code>exec cgi</code>. -<dt>cmd -<dd>The server will execute the given string using <code>/bin/sh</code>. -The include variables are available to the command. -</dl> - -<dt><strong>fsize</strong> -<dd> -This command prints the size of the specified file, subject to the -<code>sizefmt</code> format specification. Attributes: -<dl> -<dt>file -<dd>The value is a path relative to the directory containing the current -document being parsed. -<dt>virtual -<dd>The value is a (%-encoded) URL-path relative to the current document being -parsed. If it does not begin with a slash (/) then it is taken to be relative -to the current document. -</dl> - -<dt><strong>flastmod</strong> -<dd> -This command prints the last modification date of the specified file, -subject to the <code>timefmt</code> format specification. The attributes are -the same as for the <code>fsize</code> command. - -<dt><strong>include</strong> -<dd> -This command inserts the text of another document or file into the parsed -file. Any included file is subject to the usual access control. If the -directory containing the parsed file has the -<A HREF="core.html#options">Option</A> -IncludesNOEXEC set, and the including the document would cause a program -to be executed, then it will not be included; this prevents the execution of -CGI scripts. Otherwise CGI scripts are invoked as normal using the complete -URL given in the command, including any query string. -<!--%plaintext <?INDEX CGI scripts, {\tt include} element and> --> -<p> - -An attribute defines the location of the document; the inclusion is done for -each attribute given to the include command. The valid attributes are: -<dl> -<dt>file -<dd>The value is a path relative to the directory containing the current -document being parsed. It cannot contain <code>../</code>, nor can it be an -absolute path. The <code>virtual</code> attribute should always be used -in preference to this one. -<dt>virtual -<dd>The value is a (%-encoded) URL relative to the current document being -parsed. The URL cannot contain a scheme or hostname, only a path and -an optional query string. If it does not begin with a slash (/) then it -is taken to be relative to the current document. -</dl> -A URL is constructed from the attribute, and the output the server -would return if the URL were accessed by the client is included in the parsed -output. Thus included files can be nested. - -<dt><strong>printenv</strong> -<dd>This prints out a listing of all existing variables and their values. - No attributes. -<dd>For example: <code><!--#printenv --></code> -<dd>Apache 1.2 and above. - -<dt><strong>set</strong> -<dd>This sets the value of a variable. Attributes: -<dl> -<dt>var -<dd>The name of the variable to set. -<dt>value -<dd>The value to give a variable. -</dl> -For example: - <CODE><!--#set var="category" value="help" --></CODE> -<dd>Apache 1.2 and above. - -</dl> - -<h2>Include Variables</h2> - -In addition to the variables in the standard CGI environment, these are -available for the <code>echo</code> command, for <code>if</code> and -<code>elif</code>, and to any program invoked by the document. - -<dl> -<dt>DATE_GMT -<dd>The current date in Greenwich Mean Time. -<dt>DATE_LOCAL -<dd>The current date in the local time zone. -<dt>DOCUMENT_NAME -<dd>The filename (excluding directories) of the document requested by the -user. -<dt>DOCUMENT_URI -<dd>The (%-decoded) URL path of the document requested by the user. Note that -in the case of nested include files, this is <em>not</em> then URL for the -current document. -<dt>LAST_MODIFIED -<dd>The last modification date of the document requested by the user. -</dl> -<p> - -<H2>Variable Substitution</H2> -<P> Variable substitution is done within quoted strings in most cases - where they may reasonably occur as an argument to an SSI directive. - This includes the - <SAMP>config</SAMP>, - <SAMP>exec</SAMP>, - <SAMP>flastmod</SAMP>, - <SAMP>fsize</SAMP>, - <SAMP>include</SAMP>, and - <SAMP>set</SAMP> - directives, as well as the arguments to conditional operators. - You can insert a literal dollar sign into the string using backslash - quoting: - -<PRE> - <!--#if expr="$a = \$test" --> -</PRE> - -<P> If a variable reference needs to be substituted in the middle of a - character sequence that might otherwise be considered a valid - identifier in its own right, it can be disambiguated by enclosing - the reference in braces, <EM>à la</EM> shell substitution: - -<PRE> - <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --> -</PRE> - -<P> This will result in the <SAMP>Zed</SAMP> variable being set to - "<SAMP>X_Y</SAMP>" if <SAMP>REMOTE_HOST</SAMP> is - "<SAMP>X</SAMP>" and <SAMP>REQUEST_METHOD</SAMP> is - "<SAMP>Y</SAMP>". - -<P> EXAMPLE: the below example will print "in foo" if the DOCUMENT_URI is -/foo/file.html, "in bar" if it is /bar/file.html and "in neither" -otherwise: -<PRE> - <!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" --> - in foo - <!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" --> - in bar - <!--#else --> - in neither - <!--#endif --> -</PRE> - -<H2>Flow Control Elements</H2> - -These are available in Apache 1.2 and above. The basic flow control -elements are: - -<PRE> - <!--#if expr="<I>test_condition</I>" --> - <!--#elif expr="<I>test_condition</I>" --> - <!--#else --> - <!--#endif --> -</PRE> - -<P> The <B><CODE>if</CODE></B> element works like an - if statement in a programming language. The test condition - is evaluated and if the result is true, then the text until - the next <B><CODE>elif</CODE></B>, <B><CODE>else</CODE></B>. - or <B><CODE>endif</CODE></B> element is included in the - output stream. - -<P> The <B><CODE>elif</CODE></B> or <B><CODE>else</CODE></B> - statements are be used the put text into the output stream - if the original test_condition was false. These elements - are optional. - -<P> The <B><CODE>endif</CODE></B> element ends the - <B><CODE>if</CODE></B> element and is required. - -<P> <I>test_condition</I> is one of the following: - -<DL> - -<DT><I>string</I><DD>true if <I>string</I> is not empty - -<DT><I>string1</I> = <I>string2</I><BR> - <I>string1</I> != <I>string2</I> - -<DD>Compare string1 with string 2. If string2 has the form <I>/string/</I> - than it is compared as a regular expression. - Regular expressions have the same syntax as those found in the - Unix egrep command. - -<DT>( <I>test_condition</I> ) - <DD>true if <I>test_condition</I> is true -<DT>! <I>test_condition</I> - <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 -<DT><I>test_condition1</I> || <I>test_condition2</I> - <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 - "<I>||</I>". - "<I>!</I>" binds most tightly. Thus, the following are equivalent: - -<PRE> - <!--#if expr="$a = test1 && $b = test2" --> - <!--#if expr="($a = test1) && ($b = test2)" --> -</PRE> - -<P> Anything that's not recognized as a variable or an operator is - treated as a string. Strings can also be quoted: <I>'string'</I>. - Unquoted strings can't contain whitespace (blanks and tabs) - because it is used to separate tokens such as variables. If - multiple strings are found in a row, they are concatenated using - blanks. So, - -<PRE> - <I>string1 string2</I> results in <I>string1 string2</I> - <I>'string1 string2'</I> results in <I>string1 string2</I> -</PRE> - -<hr> -<h2>Directives</h2> -<ul> -<li><A HREF="#xbithack">XBitHack</A> -</ul> -<hr> - - -<h2><A name="xbithack">XBitHack</A></h2> -<!--%plaintext <?INDEX {\tt XBitHack} directive> --> -<strong>Syntax:</strong> XBitHack <em>status</em><br> -<strong>Default:</strong> <code>XBitHack off</code><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Options<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_include<p> - -The XBitHack directives controls the parsing of ordinary html documents. -This directive only affects files associated with the MIME type -<CODE>text/html</CODE>. -<em>Status</em> can have the following values: -<dl> -<dt>off -<dd>No special treatment of executable files. -<dt>on -<dd>Any file that has the user-execute bit set will be treated as a -server-parsed html document. -<dt>full -<dd>As for <code>on</code> but also test the group-execute bit. If it -is set, then set the Last-modified date of the returned file to be the -last modified time of the file. If it is not set, then no last-modified date -is sent. Setting this bit allows clients and proxies to cache the result of -the request. -<p><b>Note:</b> you would not want to use this, for example, when you -<code>#include</code> a CGI that produces different output on each hit -(or potentially depends on the hit). -</dl> -<p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_info.html b/docs/manual/mod/mod_info.html deleted file mode 100644 index dd75349990..0000000000 --- a/docs/manual/mod/mod_info.html +++ /dev/null @@ -1,73 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> -<head> -<title>Apache module mod_info</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">Module mod_info</h1> - -This module is contained in the <code>mod_info.c</code> file. It -provides a comprehensive overview of the server configuration -including all installed modules and directives in the configuration -files. This module is not compiled into the -server by default. It is only available in Apache 1.1 and later. To -enable it, add the following line to the server build Configuration -file, and rebuild the server: - -<PRE> -Module info_module mod_info.o -</PRE> - -<HR> -<P> -To configure it, add the following to your <code>access.conf</code> file. - -<PRE> -<Location /server-info> -SetHandler server-info -</Location> -</PRE> - -You may wish to add a -<A - HREF="core.html#limit" -><Limit></A> -clause inside the -<A - HREF="core.html#location" ->location</A> -directive to limit access to your server configuration information.<p> -Once configured, the server information is obtained by accessing -<tt>http://your.host.dom/server-info</tt><p> -<BLOCKQUOTE> - <STRONG> - Note that the configuration files are read by the module at run-time, - and therefore the display may <EM>not</EM> reflect the running - server's active configuration if the files have been changed since the - server was last reloaded. Also, the configuration files must be - readable by the user as which the server is running (see the - <A - HREF="core.html#user" - ><SAMP>User</SAMP></A> - directive), or else the directive settings will not be listed. - <P> - It should also be noted that if <SAMP>mod_info</SAMP> is compiled into - the server, its handler capability is available in <EM>all</EM> - configuration files, including <EM>per</EM>-directory files - (<EM>e.g.</EM>, <SAMP>.htaccess</SAMP>). This may have - security-related ramifications for your site. - </P> - </STRONG> -</BLOCKQUOTE> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_log_agent.html b/docs/manual/mod/mod_log_agent.html deleted file mode 100644 index 9e8fa50855..0000000000 --- a/docs/manual/mod/mod_log_agent.html +++ /dev/null @@ -1,61 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Module mod_log_agent</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">Module mod_log_agent</h1> - -This module is contained in the <code>mod_log_agent.c</code> file, and is not -compiled in by default. It provides for logging of the client user agents. - - -<ul> -<li><A HREF="#agentlog">AgentLog</A> -</ul> -<hr> - - -<h2><A name="agentlog">AgentLog</A></h2> -<!--%plaintext <?INDEX {\tt AgentLog} directive> --> -<strong>Syntax:</strong> AgentLog <em>file-pipe</em><br> -<strong>Default:</strong> <code>AgentLog logs/agent_log</code><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Extension<br> -<strong>Module:</strong> mod_log_agent<p> - -The AgentLog directive sets the name of the file to which the server will -log the UserAgent header of incoming requests. <em>File-pipe</em> is one -of -<dl><dt>A filename -<dd>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>. -<dt> `|' followed by a command -<dd>A program to receive the agent log information on its standard input. -Note the a new program will not be started for a VirtualHost if it inherits -the AgentLog from the main server. -</dl> -<strong>Security:</strong> if a program is used, then it will be -run under the user who started httpd. This will be root if the server -was started by root; be sure that the program is secure.<p> - -<strong>Security:</strong> See the <A -HREF="../misc/security_tips.html">security tips</A> document for -details on why your security could be compromised if the directory -where logfiles are stored is writable by anyone other than the user -that starts the server.<P> - -This directive is provided for compatibility with NCSA 1.4.<p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_log_config.html b/docs/manual/mod/mod_log_config.html deleted file mode 100644 index 8ffc86c5cb..0000000000 --- a/docs/manual/mod/mod_log_config.html +++ /dev/null @@ -1,263 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_log_config</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">Module mod_log_config</h1> - -This module is contained in the <code>mod_log_config.c</code> file, -and is compiled in by default in Apache 1.2. mod_log_config replaces -mod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was -an optional module. It provides for logging of the requests made to -the server, using the Common Log Format or a user-specified format. - -<h2>Summary</h2> - -Three directives are provided by this module: <code>TransferLog</code> -to create a log file, <code>LogFormat</code> to set a custom format, -and <code>CustomLog</code> to define a log file and format in one go. -The <code>TransferLog</code> and <code>CustomLog</code> directives can -be used multiple times in each server to cause each request to be -logged to multiple files. -<P> - -<h3>Compatibility notes</h3> - -<ul> -<li>This module is based on mod_log_config distributed with -previous Apache releases, now updated to handle multiple logs. -There is now no need to re-configure Apache to use configuration log -formats. - -<li>The module also implements the <code>CookieLog</code> directive, -used to log user-tracking information created by <a -href="mod_usertrack.html">mod_usertrack</a>. The use of -<code>CookieLog</code> is deprecated, and a <code>CustomLog</code> -should be defined to log user-tracking information instead. - -</ul> - -<h2>Log File Formats</h2> - -Unless told otherwise with <tt>LogFormat</tt> the log files created by -<tt>TransferLog</tt> will be in standard "Common Log Format" -(CLF). The contents of each line in a CLF file are explained -below. Alternatively, the log file can be customized (and if multiple -log files are used, each can have a different format). Custom formats -are set with <code>LogFormat</code> and <code>CustomLog</code>. - -<h3>Common Log Format</h3> - -The Common Log Format (CLF) file contains a separate line for each -request. A line is composed of several tokens separated by spaces: - -<blockquote> -host ident authuser date request status bytes -</blockquote> -If a token does not have a value then it is represented by a hyphen (-). -The meanings and values of these tokens are as follows: -<dl> -<dt>host -<dd>The fully-qualified domain name of the client, or its IP number if the -name is not available. -<dt>ident -<dd>If <A HREF="core.html#identitycheck">IdentityCheck</A> is enabled and the -client machine runs identd, then this is the identity information reported -by the client. -<dt>authuser -<dd>If the request was for an password protected document, then this is -the userid used in the request. -<dt>date -<dd>The date and time of the request, in the following format: -<dl><dd><blockquote><code> date = [day/month/year:hour:minute:second zone] <br> -day = 2*digit<br> -month = 3*letter<br> -year = 4*digit<br> -hour = 2*digit<br> -minute = 2*digit<br> -second = 2*digit<br> -zone = (`+' | `-') 4*digit</code></blockquote></dl> -<dt>request -<dd>The request line from the client, enclosed in double quotes -(<code>"</code>). -<dt>status -<dd>The three digit status code returned to the client. -<dt>bytes -<dd>The number of bytes in the object returned to the client, not including -any headers. -</dl> - -<h3><A NAME="formats">Custom Log Formats</A></h3> - -The format argument to the <code>LogFormat</code> and -<code>CustomLog</code> is a string. This string is logged to the log -file for each request. It can contain literal characters copied into -the log files, and `%' directives which are replaced in the log file -by the values as follows: - -<PRE> -%...b: Bytes sent, excluding HTTP headers. -%...f: Filename -%...{FOOBAR}e: The contents of the environment variable FOOBAR -%...h: Remote host -%...{Foobar}i: The contents of Foobar: header line(s) in the request - sent to the server. -%...l: Remote logname (from identd, if supplied) -%...{Foobar}n: The contents of note "Foobar" from another module. -%...{Foobar}o: The contents of Foobar: header line(s) in the reply. -%...p: The port the request was served to -%...P: The process ID of the child that serviced the request. -%...r: First line of request -%...s: Status. For requests that got internally redirected, this - is status of the *original* request --- %...>s for the last. -%...t: Time, in common log format time format -%...{format}t: The time, in the form given by format, which should - be in strftime(3) format. -%...T: The time taken to serve the request, in seconds. -%...u: Remote user (from auth; may be bogus if return status (%s) is 401) -%...U: The URL path requested. -%...v: The name of the server (i.e. which virtual host?) -</PRE> - -The `...' can be nothing at all (e.g. <code>"%h %u %r %s %b"</code>), or it can -indicate conditions for inclusion of the item (which will cause it -to be replaced with `-' if the condition is not met). Note that -there is no escaping performed on the strings from %r, %...i and -%...o; some with long memories may remember that I thought this was -a bad idea, once upon a time, and I'm still not comfortable with -it, but it is difficult to see how to `do the right thing' with all -of `%..i', unless we URL-escape everything and break with CLF. - -<P> - -The forms of condition are a list of HTTP status codes, which may -or may not be preceded by `!'. Thus, `%400,501{User-agent}i' logs -User-agent: on 400 errors and 501 errors (Bad Request, Not -Implemented) only; `%!200,304,302{Referer}i' logs Referer: on all -requests which did <b>not</b> return some sort of normal status. - -<P> - -Note that the common log format is defined by the string <code>"%h %l -%u %t \"%r\" %s %b"</code>, which can be used as the basis for -extending for format if desired (e.g. to add extra fields at the end). -NCSA's extended/combined log format would be <code>"%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\""</code>. - -<h2>Using Multiple Log Files</h2> - -The <code>TransferLog</code> and <code>CustomLog</code> directives can -be given more than once to log requests to multiple log files. Each -request will be logged to all the log files defined by either of these -directives. - -<h3>Use with Virtual Hosts</h3> - -If a <VirtualHost> section does not contain any -<tt>TransferLog</tt> or <tt>CustomLog</tt> directives, the -logs defined for the main server will be used. If it does -contain one or more of these directives, requests serviced by -this virtual host will only be logged in the log files defined -within its definition, not in any of the main server's log files. -See the examples below. -<p> - -<h2>Security Considerations</h2> - -See the <A HREF="../misc/security_tips.html">security tips</A> document -for details on why your security could be compromised if the directory -where logfiles are stored is writable by anyone other than the user -that starts the server. -<p> -<h2>Directives</h2> - -<ul> -<li><A HREF="#cookielog">CookieLog</A> -<LI><A HREF="#customlog">CustomLog</A> -<li><A HREF="#logformat">LogFormat</A> -<li><A HREF="#transferlog">TransferLog</A> -</ul> -<hr> - - -<h2><A name="cookielog">CookieLog</A></h2> -<!--%plaintext <?INDEX {\tt CookieLog} directive> --> -<strong>Syntax:</strong> CookieLog <em>filename</em><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Module:</strong> mod_cookies<br> -<strong>Compatibility:</strong> Only available in Apache 1.2 and above<p> - -The CookieLog directive sets the filename for logging of cookies. -The filename is relative to the <A -HREF="core.html#serverroot">ServerRoot</A>. This directive is included -only for compatibility with <a -href="mod_cookies.html">mod_cookies</a>, and is deprecated. -<p> - -<H2><A NAME="customlog">CustomLog</A></H2> -<STRONG>Syntax:</STRONG> CustomLog <em>file-pipe</em> <em>format</em><BR> -<STRONG>Context:</STRONG> server config, virtual host<BR> -<STRONG>Status:</STRONG> Base<BR> -<STRONG>Module:</STRONG> mod_log_config<P> - -The first argument is the filename to log to. This is used -exactly like the argument to <tt>TransferLog</tt>, that is, -it is either a full path, or relative to the current -server root. <p> - -The format argument specifies a format for each line of the log file. -The options available for the format are exactly the same as for -the argument of the <tt>LogFormat</tt> directive. If the format -includes any spaces (which it will do in almost all cases) it -should be enclosed in double quotes. - -<h2><A name="logformat">LogFormat</A></h2> -<!--%plaintext <?INDEX {\tt LogFormat} directive> --> -<strong>Syntax:</strong> LogFormat <em>string</em><br> -<strong>Default:</strong> <code>LogFormat "%h %l %u %t \"%r\" -%s %b"</code><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_log_config<p> - -This sets the format of the logfile. See <A HREF="#formats"> -Custom Log Formats</A> for details on the format arguments.<p><hr> - - -<h2><A name="transferlog">TransferLog</A></h2> -<!--%plaintext <?INDEX {\tt TransferLog} directive> --> -<strong>Syntax:</strong> TransferLog <em>file-pipe</em><br> -<strong>Default:</strong> none<br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_log_config<p> - -The TransferLog directive adds a log file in Common Log Format. -<em>File-pipe</em> is one -of -<dl><dt>A filename -<dd>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>. -<dt> `|' followed by a command -<dd>A program to receive the agent log information on its standard input. -Note the a new program will not be started for a VirtualHost if it inherits -the TransferLog from the main server. -</dl> -<strong>Security:</strong> if a program is used, then it will be -run under the user who started httpd. This will be root if the server -was started by root; be sure that the program is secure.<p> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - - diff --git a/docs/manual/mod/mod_log_referer.html b/docs/manual/mod/mod_log_referer.html deleted file mode 100644 index 8a5146491a..0000000000 --- a/docs/manual/mod/mod_log_referer.html +++ /dev/null @@ -1,88 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_log_referer</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">Module mod_log_referer</h1> - -This module is contained in the <code>mod_log_referer.c</code> file, and is not -compiled in by default. It provides for logging of the documents which -reference documents on the server. - -<h2>Log file format</h2> -The log file contains a separate line for each refer. Each line has the -format -<blockquote><em>uri</em> <code>-></code> <em>document</em></blockquote> -where <em>uri</em> is the (%-escaped) URI for the document that references -the one requested by the client, and <em>document</em> is the (%-decoded) -local URL to the document being referred to. - - -<h2>Directives</h2> -<ul> -<li><A HREF="#refererignore">RefererIgnore</A> -<li><A HREF="#refererlog">RefererLog</A> -</ul> -<hr> - - -<h2><A name="refererignore">RefererIgnore</A></h2> -<!--%plaintext <?INDEX {\tt RefererIgnore} directive> --> -<strong>Syntax:</strong> RefererIgnore <em>string string ...</em><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Extension<br> -<strong>Module:</strong> mod_log_referer<p> - -The RefererIgnore directive adds to the list of strings to ignore in -Referer headers. If any of the strings in the list is contained in -the Referer header, then no referrer information will be logged for the -request. Example: -<blockquote><code>RefererIgnore www.ncsa.uiuc.edu</code></blockquote> -This avoids logging references from www.ncsa.uiuc.edu. -<p><hr> - - -<h2><A name="refererlog">RefererLog</A></h2> -<!--%plaintext <?INDEX {\tt RefererLog} directive> --> -<strong>Syntax:</strong> RefererLog <em>file-pipe</em><br> -<strong>Default:</strong> <code>RefererLog logs/referer_log</code><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Extension<br> -<strong>Module:</strong> mod_log_referer<p> - -The RefererLog directive sets the name of the file to which the server will -log the Referer header of incoming requests. <em>File-pipe</em> is one -of -<dl><dt>A filename -<dd>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>. -<dt> `|' followed by a command -<dd>A program to receive the referrer log information on its standard input. -Note the a new program will not be started for a VirtualHost if it inherits -the RefererLog from the main server. -</dl> -<strong>Security:</strong> if a program is used, then it will be -run under the user who started httpd. This will be root if the server -was started by root; be sure that the program is secure.<p> - -<strong>Security:</strong> See the <A -HREF="../misc/security_tips.html">security tips</A> document for -details on why your security could be compromised if the directory -where logfiles are stored is writable by anyone other than the user -that starts the server.<P> - -This directive is provided for compatibility with NCSA 1.4.<p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_mime.html b/docs/manual/mod/mod_mime.html deleted file mode 100644 index fa150c88e0..0000000000 --- a/docs/manual/mod/mod_mime.html +++ /dev/null @@ -1,212 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_mime</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">Module mod_mime</h1> - -This module is contained in the <code>mod_mime.c</code> file, and is -compiled in by default. It provides for determining the types of files -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. - - -<h2> Directives</h2> -<ul> -<li><A HREF="#addencoding">AddEncoding</A> -<li><A HREF="#addhandler">AddHandler</A> -<li><A HREF="#addlanguage">AddLanguage</A> -<li><A HREF="#addtype">AddType</A> -<li><A HREF="#forcetype">ForceType</A> -<li><A HREF="#sethandler">SetHandler</A> -<li><A HREF="#typesconfig">TypesConfig</A> -</ul> -<hr> - - -<h2><A name="addencoding">AddEncoding</A></h2> -<!--%plaintext <?INDEX {\tt AddEncoding} directive> --> -<strong>Syntax:</strong> AddEncoding <em>mime-enc extension extension...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<p> - -The AddEncoding directive adds to the list of filename extensions which -filenames may end in for the specified encoding type. <em>Mime-enc</em> -is the mime encoding to use for documents ending in <em>extension</em>. -Example: -<blockquote><code> -AddEncoding x-gzip gz<br> -AddEncoding x-compress Z -</code></blockquote> - -This will cause files ending in .gz to be marked as encoded using the x-gzip -encoding, and .Z files to be marked as encoded with x-compress.<p><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<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 -<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: -<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="addlanguage">AddLanguage</A></h2> -<!--%plaintext <?INDEX {\tt AddLanguage} directive> --> -<strong>Syntax:</strong> AddLanguage <em>mime-lang extension extension...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<p> - -The AddLanguage directive adds to the list of filename extensions which -filenames may end in for the specified content language. <em>Mime-lang</em> -is the mime language of files with names ending <em>extension</em>, -after any content encoding extensions have been removed. Example: -<blockquote><code> -AddEncoding x-compress Z<br> -AddLanguage en .en<br> -AddLanguage fr .fr<br> -</code></blockquote> - -Then the document <code>xxxx.en.Z</code> will be treated as being a compressed -English document. Although the content language is reported to the client, -the browser is unlikely to use this information. The AddLanguage directive -is more useful for content negotiation, where the server returns one -from several documents based on the client's language preference.<p><hr> - -<h2><A name="addtype">AddType</A></h2> -<!--%plaintext <?INDEX {\tt AddType} directive> --> -<strong>Syntax:</strong> AddType <em>mime-type extension extension...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<p> - -The AddType directive adds to the list of filename extensions which -filenames may end in for the specified content type. <em>Mime-enc</em> -is the mime type to use for documents ending in <em>extension</em>. -after content-encoding and language extensions have been removed. Example: -<blockquote><code> -AddType image/gif GIF -</code></blockquote> -It is recommended that new mime types be added using the AddType directive -rather than changing the <A HREF="#typesconfig">TypesConfig</A> file.<p> -Note that, unlike the NCSA httpd, this directive cannot be used to set the -type of particular files.<p><hr> - -<h2><a name="forcetype">ForceType</a></h2> - -<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> -<strong>Compatibility:</strong> ForceType is only available in Apache -1.1 and later.<p> - -<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 served -as the content type given by <em>media type</em>. For example, if you -had a directory full of GIF files, but did not want to label them all with -".gif", you might want to use: -<pre> - ForceType image/gif -</pre> -<p>Note that this will override any filename extensions that might -media type.</p> - -<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<br> -<strong>Compatibility:</strong> SetHandler is only available in Apache -1.1 and later.<p> - -<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 -<a href="../handler.html">handler</a> -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> -<HR> - -<h2><A name="typesconfig">TypesConfig</A></h2> -<!--%plaintext <?INDEX {\tt TypesConfig} directive> --> -<strong>Syntax:</strong> TypesConfig <em>filename</em><br> -<strong>Default:</strong> <code>TypesConfig conf/mime.types</code><br> -<Strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<p> - -The TypesConfig directive sets the location of the mime types configuration -file. <em>Filename</em> is relative to the -<A HREF="core.html#serverroot">ServerRoot</A>. This file sets the default list of -mappings from filename extensions to content types; changing this file is not -recommended. Use the <A HREF="#addtype">AddType</A> directive instead. The -file contains lines in the format of the arguments to an AddType command: -<blockquote><em>mime-type extension extension ...</em></blockquote> -The extensions are lower-cased. Blank lines, and lines beginning with a hash -character (`#') are ignored.<p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_negotiation.html b/docs/manual/mod/mod_negotiation.html deleted file mode 100644 index 141b74bfe6..0000000000 --- a/docs/manual/mod/mod_negotiation.html +++ /dev/null @@ -1,147 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_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">Module mod_negotiation</h1> - -This module is contained in the <code>mod_negotiation.c</code> file, -and is compiled in by default. It provides for <A -HREF="../content-negotiation.html">content negotiation</A>. - -<h2>Summary</h2> -Content negotiation, or more accurately content selection, is the -selection of the document that best matches the clients -capabilities, from one of several available documents. -There are two implementations of this. -<ul> -<li> A type map (a file with the handler <code>type-map</code>) -which explicitly lists the files containing the variants. -<li> A MultiViews search (enabled by the MultiViews -<A HREF="core.html#options">Option</A>, where the server does an implicit -filename pattern match, and choose from amongst the results. -</ul> - -<h3>Type maps</h3> -A type map has the same format as RFC822 mail headers. It contains document -descriptions separated by blank lines, with lines beginning with a hash -character ('#') treated as comments. A document description consists of -several header records; records may be continued on multiple lines if the -continuation lines start with spaces. The leading space will be deleted -and the lines concatenated. A header record consists of a keyword -name, which always ends in a colon, followed by a value. Whitespace is allowed -between the header name and value, and between the tokens of value. - -The headers allowed are: - -<dl> -<dt>Content-Encoding: -<dd>The encoding of the file. Currently only two encodings are recognized -by http; <code>x-compress</code> for compressed files, and <code>x-gzip</code> -for gzipped files. -<dt>Content-Language: -<dd>The language of the variant, as an Internet standard language code, such -as <code>en</code>. -<dt>Content-Length: -<dd>The length of the file, in bytes. If this header is not present, then -the actual length of the file is used. -<dt>Content-Type: -<dd>The MIME media type of the document, with optional parameters. -parameters are separated from the media type and from one another by -semi-colons. Parameter syntax is name=value; allowed parameters are: -<dl> -<dt>level -<dd>the value is an integer, which specifies the version of the media type. -For <code>text/html</code> this defaults to 2, otherwise 0. -<dt>qs -<dd>the value is a floating-point number with value between 0. and 1. -It indications the 'quality' of this variant. -</dl> -Example: -<blockquote><code>Content-Type: image/jpeg; qs=0.8</code></blockquote> -<dt>URI: -<dd>The path to the file containing this variant, relative to the map file. -</dl> - -<h3>MultiViews</h3> -A MultiViews search is enabled by the MultiViews -<A HREF="core.html#options">Option</A>. -If the server receives a request for <code>/some/dir/foo</code> and -<code>/some/dir/foo</code> does <em>not</em> exist, then the server reads the -directory looking for all files named <code>foo.*</code>, 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 returns that document.<p> - - - -<h2>Directives</h2> -<ul> -<li><A href="#cachenegotiateddocs">CacheNegotiatedDocs</a> -<li><A HREF="#languagepriority">LanguagePriority</A> -</ul> -<hr> - - -<h2><A name="cachenegotiateddocs">CacheNegotiatedDocs</A></h2> -<strong>Syntax:</strong> CacheNegotiatedDocs<br> -<Strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_negotiation<br> -<strong>Compatibility:</strong> CacheNegotiatedDocs is only available -in Apache 1.1 and later.<p> - -<p>If set, this directive allows content-negotiated documents to be -cached by proxy servers. This could mean that clients behind those -proxys could retrieve versions of the documents that are not the best -match for their abilities, but it will make caching more -efficient. -<p> - -This directive only applies to requests which come from HTTP/1.0 browsers. -HTTP/1.1 provides much better control over the caching of negotiated -documents, and this directive has no effect in responses to -HTTP/1.1 requests. - - - -<h2><A name="languagepriority">LanguagePriority</A></h2> -<!--%plaintext <?INDEX {\tt LanguagePriority} directive> --> -<strong>Syntax:</strong> LanguagePriority <em>mime-lang mime-lang...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_negotiation<p> - -The LanguagePriority sets the precedence of language variants for the case -where the client does not express a preference, when handling a -MultiViews request. The list of <em>mime-lang</em> are in order of decreasing -preference. Example: - -<blockquote><code>LanguagePriority en fr de</code></blockquote> - -For a request for <code>foo.html</code>, where <code>foo.html.fr</code> -and <code>foo.html.de</code> both existed, but the browser did not express -a language preference, then <code>foo.html.fr</code> would be returned.<p> - -<P> - -Note that this directive only has an effect if a 'best' language -cannot be determined by other any other means. Correctly implemented -HTTP/1.1 requests will mean this directive has no effect. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_proxy.html b/docs/manual/mod/mod_proxy.html deleted file mode 100644 index e0aef68846..0000000000 --- a/docs/manual/mod/mod_proxy.html +++ /dev/null @@ -1,366 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_proxy</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 module mod_proxy</h1> - -This module is contained in the <code>mod_proxy.c</code> file for Apache 1.1.x, -or the <code>modules/proxy</code> subdirectory for Apache 1.2, and -is not compiled in by default. It provides for an <b>HTTP 1.0</b> caching proxy -server. It is only available in Apache 1.1 and later. Common configuration -questions are addressed <a href="#configs">here</a>. - -<h3>Note:</h3> -<p>This module was experimental in Apache 1.1.x. As of Apache 1.2, mod_proxy -stability is <i>greatly</i> improved.<p> - -<h2>Summary</h2> - -This module implements a proxy/cache for Apache. It implements -proxying capability for -<code>FTP</code>, -<code>CONNECT</code> (for SSL), -<code>HTTP/0.9</code>, and -<code>HTTP/1.0</code>. -The module can be configured to connect to other proxy modules for these -and other protocols. - -<h2>Directives</h2> -<ul> -<li><a href="#proxyrequests">ProxyRequests</a> -<li><a href="#proxyremote">ProxyRemote</a> -<li><a href="#proxypass">ProxyPass</a> -<li><a href="#proxyblock">ProxyBlock</a> -<li><a href="#cacheroot">CacheRoot</a> -<li><a href="#cachesize">CacheSize</a> -<li><a href="#cachemaxexpire">CacheMaxExpire</a> -<li><a href="#cachedefaultexpire">CacheDefaultExpire</a> -<li><a href="#cachelastmodifiedfactor">CacheLastModifiedFactor</a> -<li><a href="#cachegcinterval">CacheGcInterval</a> -<li><a href="#cachedirlevels">CacheDirLevels</a> -<li><a href="#cachedirlength">CacheDirLength</a> -<li><a href="#nocache">NoCache</a> -</ul> - -<hr> - -<A name="proxyrequests"><h2>ProxyRequests</h2></A> -<strong>Syntax:</strong> ProxyRequests <em>on/off</em><br> -<strong>Default:</strong> <code>ProxyRequests Off</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> ProxyRequest is only available in -Apache 1.1 and later.<p> - -This allows or prevents Apache from functioning as a proxy -server. Setting ProxyRequests to 'off' does not disable use of the <a -href="#proxypass">ProxyPass</a> directive. - -<A name="proxyremote"><h2>ProxyRemote</h2></A> -<strong>Syntax:</strong> ProxyRemote <em><match> <remote-server></em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> ProxyRemote is only available in -Apache 1.1 and later.<p> - -This defines remote proxies to this proxy. <match> is either the -name of a URL-scheme that the remote server supports, or a partial URL -for which the remote server should be used, or '*' to indicate the -server should be contacted for all requests. <remote-server> is a -partial URL for the remote server. Syntax: - -<pre> - <remote-server> = <protocol>://<hostname>[:port] -</pre> - -<protocol> is the protocol that should be used to communicate -with the remote server; only "http" is supported by this module. - -Example: -<pre> - ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000 - ProxyRemote * http://cleversite.com - ProxyRemote ftp http://ftpproxy.mydomain.com:8080 -</pre> - -In the last example, the proxy will forward FTP requests, encapsulated -as yet another HTTP proxy request, to another proxy which can handle -them. - -<A name="proxypass"><h2>ProxyPass</h2></A> -<strong>Syntax:</strong> ProxyPass <em><path> <url></em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> ProxyPass is only available in -Apache 1.1 and later.<p> - -This directive allows remote servers to be mapped into the space of the local -server; the local server does not act as a proxy in the conventional sense, -but appears to be a mirror of the remote server. <path> is the name of -a local virtual path; <url> is a partial URL for the remote server. - -Suppose the local server has address http://wibble.org; then -<pre> - ProxyPass /mirror/foo http://foo.com -</pre> -Will cause a local request for the http://wibble.org/mirror/foo/bar to be -internally converted into a proxy request to http://foo.com/bar - -<A name="proxyblock"><h2>ProxyBlock</h2></A> -<strong>Syntax:</strong> ProxyBlock <em><word/host/domain list></em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> ProxyBlock is only available in -Apache 1.2 and later.<p> - -The ProxyBlock directive specifies a list of words, hosts and/or domains, -separated by spaces. HTTP, HTTPS, and FTP document requests to matched words, -hosts or domains are <em>blocked</em> by the proxy server. The proxy module -will also attempt to determine IP addresses of list items which may be -hostnames during startup, and cache them for match test as well. Example: - -<pre> - ProxyBlock joes_garage.com some_host.co.uk rocky.wotsamattau.edu -</pre> - -'rocky.wotsamattau.edu' would also be matched if referenced by IP address.<p> - -Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.<p> - -Note also that - -<pre> -ProxyBlock * -</pre> - -blocks connections to all sites. - -<A name="cacheroot"><h2>CacheRoot</h2></A> -<strong>Syntax:</strong> CacheRoot <em><directory></em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheRoot is only available in -Apache 1.1 and later.<p> - -Sets the name of the directory to contain cache files; this must be -writable -by the httpd server. - -<A name="cachesize"><h2>CacheSize</h2></A> -<strong>Syntax:</strong> CacheSize <em><size></em><br> -<strong>Default:</strong> <code>CacheSize 5</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheSize is only available in -Apache 1.1 and later.<p> - -Sets the desired space usage of the cache, in Kb (1024 byte units). Although -usage may grow above this setting, the garbage collection will delete files -until the usage is at or below this setting. - -<A name="cachegcinterval"><h2>CacheGcInterval</h2></A> -<strong>Syntax:</strong> CacheGcInterval <em><time></em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheGcinterval is only available in -Apache 1.1 and later.<p> - -Check the cache every <time> hours, and delete files if the space -usage is greater than that set by CacheSize. - -<A name="cachemaxexpire"><h2>CacheMaxExpire</h2></A> -<strong>Syntax:</strong> CacheMaxExpire <em><time></em><br> -<strong>Default:</strong> <code>CacheMaxExpire 24</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheMaxExpire is only available in -Apache 1.1 and later.<p> - -Cachable HTTP documents will be retained for at most <time> hours without -checking the origin server. Thus documents can be at most <time> -hours out of date. This restriction is enforced even if an expiry date -was supplied with the document. - -<A name="cachelastmodifiedfactor"><h2>CacheLastModifiedFactor</h2></A> -<strong>Syntax:</strong> CacheLastModifiedFactor <em><factor></em><br> -<strong>Default:</strong> <code>CacheLastModifiedFactor 0.1</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheLastModifiedFactor is only available in -Apache 1.1 and later.<p> - -If the origin HTTP server did not supply an expiry date for the -document, then estimate one using the formula -<pre> - expiry-period = time-since-last-modification * <factor> -</pre> -For example, if the document was last modified 10 hours ago, and -<factor> is 0.1, then the expiry period will be set to 10*0.1 = 1 hour. - -<p>If the expiry-period would be longer than that set by CacheMaxExpire, -then the latter takes precedence. - -<A name="cachedirlevels"><h2>CacheDirLevels</h2></A> -<strong>Syntax:</strong> CacheDirLevels <em><levels></em><br> -<strong>Default:</strong> <code>CacheDirLevels 3</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheDirLevels is only available in -Apache 1.1 and later.<p> - -CacheDirLevels sets the number of levels of subdirectories in the cache. -Cached data will be saved this many directory levels below CacheRoot. - -<A name="cachedirlength"><h2>CacheDirLength</h2></A> -<strong>Syntax:</strong> CacheDirLength <em><length></em><br> -<strong>Default:</strong> <code>CacheDirLength 1</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheDirLength is only available in -Apache 1.1 and later.<p> - -CacheDirLength sets the number of characters in proxy cache subdirectory names. - -<A name="cachedefaultexpire"><h2>CacheDefaultExpire</h2></A> -<strong>Syntax:</strong> CacheDefaultExpire <em><time></em><br> -<strong>Default:</strong> <code>CacheDefaultExpire 1</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheDefaultExpire is only available in -Apache 1.1 and later.<p> - -If the document is fetched via a protocol that does not support expiry times, -then use <time> hours as the expiry time. -<a href="#cachemaxexpire">CacheMaxExpire</a> does <strong>not</strong> -override. - -<A name="nocache"><h2>NoCache</h2></A> -<strong>Syntax:</strong> NoCache <em><word/host/domain list></em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> NoCache is only available in -Apache 1.1 and later.<p> - -The NoCache directive specifies a list of words, hosts and/or domains, separated -by spaces. HTTP and non-passworded FTP documents from matched words, hosts or -domains are <em>not</em> cached by the proxy server. The proxy module will -also attempt to determine IP addresses of list items which may be hostnames -during startup, and cache them for match test as well. Example: - -<pre> - NoCache joes_garage.com some_host.co.uk bullwinkle.wotsamattau.edu -</pre> - -'bullwinkle.wotsamattau.edu' would also be matched if referenced by IP -address.<p> - -Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.<p> - -Note also that - -<pre> -NoCache * -</pre> - -disables caching completely.<p> - -<hr> - -<a name="configs"><h2>Common configuration topics</h2></a> - -<ul> -<li><a href="#access">Controlling access to your proxy</a> -<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> -<li><a href="#socks">Can I use the Apache proxy module with my SOCKS proxy?</a> -</ul> - -<h2><a name="access">Controlling access to your proxy</a></h2> - -You can control who can access your proxy via the normal <Directory> -control block using the following example:<p> - -<pre> -<Directory proxy:*> -<Limit GET PUT POST DELETE CONNECT OPTIONS> -order deny,allow -deny from [machines you'd like *not* to allow by IP address or name] -allow from [machines you'd like to allow by IP address or name] -</Limit> -</Directory> -</pre><p> - -A <Files> block will also work, and is the only method known to work -for all possible URLs in Apache versions earlier than 1.2b10.<p> - -<h2><a name="shortname">Using Netscape hostname shortcuts</a></h2> - -There is an optional patch to the proxy module to allow Netscape-like -hostname shortcuts to be used. It's available -<a href="http://www.apache.org/dist/contrib/patches/1.2/netscapehost.patch"> -here</a>.<p> - -<h2><a name="mimetypes">Why doesn't file type <i>xxx</i> download via FTP?</a></h2> - -You probably don't have that particular file type defined as -<i>application/octet-stream</i> in your proxy's mime.types configuration -file. A useful line can be<p> - -<pre> -application/octet-stream bin dms lha lzh exe class tgz taz -</pre> - -<h2><a name="startup">Why does Apache start more slowly when using the - 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 -startup for later match test. This may take a few seconds (or more) -depending on the speed with which the hostname lookups occur.<p> - -<h2><a name="socks">Can I use the Apache proxy module with my SOCKS proxy?</a></h2> - -Yes. Just build Apache with the rule <code>SOCKS4=yes</code> in your -<i>Configuration</i> file, and follow the instructions there. SOCKS5 -capability can be added in a similar way (there's no <code>SOCKS5</code> -rule yet), so use the <code>EXTRA_LFLAGS</code> definition, or build Apache -normally and run it with the <i>runsocks</i> wrapper provided with SOCKS5, -if your OS supports dynamically linked libraries.<p> - -Some users have reported problems when using SOCKS version 4.2 on Solaris. -The problem was solved by upgrading to SOCKS 4.3.<p> - -Remember that you'll also have to grant access to your Apache proxy machine by -permitting connections on the appropriate ports in your SOCKS daemon's -configuration.<p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html deleted file mode 100644 index 03eaa5801f..0000000000 --- a/docs/manual/mod/mod_rewrite.html +++ /dev/null @@ -1,1161 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<!--%hypertext --> -<!-- mod_rewrite.html --> -<!-- Documentation for the mod_rewrite Apache module --> -<html> -<head> -<title>Apache module mod_rewrite</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">Module mod_rewrite (Version 3.0)</h1> - -This module is contained in the <code>mod_rewrite.c</code> file, with Apache -1.2 and later. It provides a rule-based rewriting engine to rewrite requested -URLs on the fly. <code>mod_rewrite</code> is not compiled into the server by -default. To use <code>mod_rewrite</code> you have to enable the following line -in the server build Configuration file: -<pre> - Module rewrite_module mod_rewrite.o -</pre> - -<h2>Summary</h2> - -This module uses a rule-based rewriting engine (based on a -regular-expression parser) to rewrite requested URLs on the fly. - -<p> -It supports an unlimited number of additional rule conditions (which can -operate on a lot of variables, including HTTP headers) for granular -matching and external database lookups (either via plain text -tables, DBM hash files or external processes) for advanced URL -substitution. - -<p> -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> -<a href="http://www.engelschall.com/sw/mod_rewrite/"> -<code><b>http://www.engelschall.com/sw/mod_rewrite/</b></code></a> - -<p> -Copyright © 1996,1997 <b>The Apache Group</b>, All rights reserved.<br> -Copyright © 1996,1997 <i>Ralf S. Engelschall</i>, All rights reserved. -<p> -Written for <b>The Apache Group</b> by -<blockquote> - <i>Ralf S. Engelschall</i><br> - <a href="mailto:rse@engelschall.com"><tt>rse@engelschall.com</tt></a><br> - <a href="http://www.engelschall.com/"><tt>www.engelschall.com</tt></a> -</blockquote> - -<!--%hypertext --> -<HR> -<!--/%hypertext --> - -<p> -<h2>Directives</h2> - -<ul> - <li><a href="#RewriteEngine">RewriteEngine</a> - <li><a href="#RewriteOptions">RewriteOptions</a> - <li><a href="#RewriteLog">RewriteLog</a> - <li><a href="#RewriteLogLevel">RewriteLogLevel</a> - <li><a href="#RewriteMap">RewriteMap</a> - <li><a href="#RewriteBase">RewriteBase</a> - <li><a href="#RewriteCond">RewriteCond</a> - <li><a href="#RewriteRule">RewriteRule</a> -</ul> - -<!--%hypertext --> -<hr> -<!--/%hypertext --> - - -<center> -<a name="Configuration"> -<h1>Configuration Directives</h1> -</a> -</center> - -<a name="RewriteEngine"><h3>RewriteEngine</h3></a> -<strong>Syntax:</strong> <code>RewriteEngine</code> {<code>on,off</code>}<br> -<strong>Default:</strong> <strong><code>RewriteEngine off</code></strong><br> -<strong>Context:</strong> server config, virtual host, per-directory config<br> -<p> - -The <tt>RewriteEngine</tt> directive enables or disables the -runtime rewriting engine. If it is set to <code>off</code> this module does -no runtime processing at all. It does not even update the <tt>SCRIPT_URx</tt> -environment variables. - -<p> -Use this directive to disable the module instead of commenting out -all <tt>RewriteRule</tt> directives! - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteOptions"><h3>RewriteOptions</h3></a> -<strong>Syntax:</strong> <code>RewriteOptions</code> <em>Option</em> ...<br> -<strong>Default:</strong> -<em>None</em>-<br> -<strong>Context:</strong> server config, virtual host, per-directory config<br> -<p> - -The <tt>RewriteOption</tt> directive sets some special options for the -current per-server or per-directory configuration. The <em>Option</em> -strings can be one of the following: - -<ul> -<li>'<strong><code>inherit</code></strong>'<br> - This forces the current configuration to inherit the configuration of the - parent. In per-virtual-server context this means that the maps, - conditions and rules of the main server gets inherited. In per-directory - context this means that conditions and rules of the parent directory's - <tt>.htaccess</tt> configuration gets inherited. -<p> -</ul> - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteLog"><h3>RewriteLog</h3></a> -<strong>Syntax:</strong> <code>RewriteLog</code> <em>Filename</em><br> -<strong>Default:</strong> -<em>None</em>-<br> -<strong>Context:</strong> server config, virtual host<br> -<p> - -The <tt>RewriteLog</tt> directive sets the name of the file to which the -server logs any rewriting actions it performs. If the name does not begin -with a slash ('<tt>/</tt>') then it is assumed to be relative to the -<em>Server Root</em>. The directive should occur only once per server -config. - -<p> -<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> -to <code>/dev/null</code>, because although the rewriting engine does -not create output to a logfile it still creates the logfile -output internally. <b>This will slow down the server with no advantage to the -administrator!</b> -To disable logging either remove or comment out the -<tt>RewriteLog</tt> directive or use <tt>RewriteLogLevel 0</tt>! -</td></tr> -</table> - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -SECURITY: See the <a -href="../misc/security_tips.html">Apache Security -Tips</a> document for details on why your security could be compromised if the -directory where logfiles are stored is writable by anyone other than the user -that starts the server. -</td></tr> -</table> - -<p> -<b>Example:</b> -<blockquote> -<pre> -RewriteLog "/usr/local/var/apache/logs/rewrite.log" -</pre> -</blockquote> - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteLogLevel"><h3>RewriteLogLevel</h3></a> -<strong>Syntax:</strong> <code>RewriteLogLevel</code> <em>Level</em><br> -<strong>Default:</strong> <strong><code>RewriteLogLevel 0</code></strong><br> -<strong>Context:</strong> server config, virtual host<br> -<p> - -The <tt>RewriteLogLevel</tt> directive set the verbosity level of the rewriting -logfile. The default level 0 means no logging, while 9 or more means -that practically all actions are logged. - -<p> -To disable the logging of rewriting actions simply set <em>Level</em> to 0. -This disables all rewrite action logs. - -<p> -<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 -at <em>Level</em> not greater than 2! -</td></tr> -</table> - - -<p> -<b>Example:</b> -<blockquote> -<pre> -RewriteLogLevel 3 -</pre> -</blockquote> - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteMap"><h3>RewriteMap</h3></a> -<strong>Syntax:</strong> <code>RewriteMap</code> <em>Mapname</em> <code>{txt,dbm,prg}:</code><em>Filename</em><br> -<strong>Default:</strong> not used per default<br> -<strong>Context:</strong> server config, virtual host<br> -<p> - -The <tt>RewriteMap</tt> directive defines an external <em>Rewriting Map</em> -which can be used inside rule substitution strings by the mapping-functions -to insert/substitute fields through a key lookup. -<p> - -The <a name="mapfunc"><em>Mapname</em></a> is the name of the map and will -be used to specify a mapping-function for the substitution strings of a -rewriting rule via - -<blockquote><strong> -<code>${</code> <em>Mapname</em> <code>:</code> <em>LookupKey</em> -<code>|</code> <em>DefaultValue</em> <code>}</code> -</strong></blockquote> - -When such a directive occurs the map <em>Mapname</em> -is consulted and the key <em>LookupKey</em> is looked-up. If the key is -found, the map-function directive is substituted by <em>SubstValue</em>. If -the key is not found then it is substituted by <em>DefaultValue</em>. - -<p> -The <em>Filename</em> must be a valid Unix filepath, containing one -of the following formats: - -<ol> -<li><b>Plain Text Format</b> - <p> - This is a ASCII file which contains either blank lines, comment lines - (starting with a '#' character) or - - <blockquote><strong> - <em>MatchingKey</em> <em>SubstValue</em> - </strong></blockquote> - - pairs - one per line. You can create such files either manually, - using your favorite editor, or by using the programs - <tt>mapcollect</tt> and <tt>mapmerge</tt> from the <tt>support</tt> - directory of the <b>mod_rewrite</b> distribution. - <p> - To declare such a map prefix, <em>Filename</em> with a <code>txt:</code> - string as in the following example: - -<p> -<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0"> -<tr><td><pre> -# -# map.real-to-user -- maps realnames to usernames -# - -Ralf.S.Engelschall rse # Bastard Operator From Hell -Dr.Fred.Klabuster fred # Mr. DAU -</pre></td></tr> -</table> - -<p> -<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0"> -<tr><td><pre> -RewriteMap real-to-host txt:/path/to/file/map.real-to-user -</pre></td></tr> -</table> - -<p> -<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 - 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> - To declare such a map prefix <em>Filename</em> with a <code>dbm:</code> - string. -<p> -<li><b>Program Format</b> - <p> - This is a Unix executable, not a lookup file. To create it you can use - the language of your choice, but the result has to be a run-able Unix - binary (i.e. either object-code or a script with the - magic cookie trick '<tt>#!/path/to/interpreter</tt>' as the first line). - <p> - This program gets started once at startup of the Apache servers and then - communicates with the rewriting engine over its <tt>stdin</tt> and - <tt>stdout</tt> file-handles. For each map-function lookup it will - receive the key to lookup as a newline-terminated string on - <tt>stdin</tt>. It then has to give back the looked-up value as a - newline-terminated string on <tt>stdout</tt> or the four-character string - ``<tt>NULL</tt>'' if it fails (i.e. there is no corresponding value - for the given key). A trivial program which will implement a 1:1 map - (i.e. key == value) could be: - <p> -<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0"> -<tr><td><pre> -#!/usr/bin/perl -$| = 1; -while (<STDIN>) { - # ...here any transformations - # or lookups should occur... - print $_; -} -</pre></td></tr> -</table> - <p> - <b>But be very careful:</b><br> - <ol> - <li>``<i>Keep the program simple, stupid</i>'' (KISS), because - if this program hangs it will lead to a hang of the Apache server - when the rule occurs. - <li>Avoid one common mistake: never do buffered I/O on <tt>stdout</tt>! - This will cause a deadloop! Hence the ``<tt>$|=1</tt>'' in the above - example... - </ol> - <p> - To declare such a map prefix <em>Filename</em> with a <code>prg:</code> - string. -</ol> - -The <tt>RewriteMap</tt> directive can occur more than once. For each -mapping-function use one <tt>RewriteMap</tt> directive to declare its -rewriting mapfile. While you cannot <b>declare</b> a map in per-directory -context it is of course possible to <b>use</b> this map in per-directory -context. - -<p> -<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 -restart. This way you can have map-functions in rules which are used -for <b>every</b> request. This is no problem, because the external lookup -only happens once! -</td></tr> -</table> - - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteBase"><h3>RewriteBase</h3></a> -<strong>Syntax:</strong> <code>RewriteBase</code> <em>BaseURL</em><br> -<strong>Default:</strong> <em>default is the physical directory path</em><br> -<strong>Context:</strong> per-directory config<br> -<p> - -The <tt>RewriteBase</tt> directive explicitly sets the base URL for -per-directory rewrites. As you will see below, <tt>RewriteRule</tt> can be -used in per-directory config files (<tt>.htaccess</tt>). There it will act -locally, i.e. the local directory prefix is stripped at this stage of -processing and your rewriting rules act only on the remainder. At the end -it is automatically added. - -<p> -When a substitution occurs for a new URL, this module has to -re-inject the URL into the server processing. To be able to do this it needs -to know what the corresponding URL-prefix or URL-base is. By default this -prefix is the corresponding filepath itself. <b>But at most websites URLs are -<b>NOT</b> directly related to physical filename paths, so this assumption -will be usually be wrong!</b> There you have to use the <tt>RewriteBase</tt> -directive to specify the correct URL-prefix. - -<p> -<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 -<tt>.htaccess</tt> files where you want to use <tt>RewriteRule</tt> -directives. -</td></tr> -</table> - -<p> -<b>Example:</b> - -<blockquote> - Assume the following per-directory config file: - -<p> -<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0"> -<tr><td><pre> -# -# /abc/def/.htaccess -- per-dir config file for directory /abc/def -# Remember: /abc/def is the physical path of /xyz, i.e. the server -# has a 'Alias /xyz /abc/def' directive e.g. -# - -RewriteEngine On - -# let the server know that we are reached via /xyz and not -# via the physical path prefix /abc/def -RewriteBase /xyz - -# now the rewriting rules -RewriteRule ^oldstuff\.html$ newstuff.html -</pre></td></tr> -</table> - -<p> -In the above example, a request to <tt>/xyz/oldstuff.html</tt> gets correctly -rewritten to the physical file <tt>/abc/def/newstuff.html</tt>. - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -<font size=-1> -<b>For the Apache hackers:</b><br> -The following list gives detailed information about the internal -processing steps: - -<p> -<pre> -Request: - /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) - -Result: - /abc/def/newstuff.html -</pre> - -This seems very complicated but is the correct Apache internal processing, -because the per-directory rewriting comes too late in the process. So, -when it occurs the (rewritten) request has to be re-injected into the Apache -kernel! BUT: While this seems like a serious overhead, it really isn't, because -this re-injection happens fully internal to the Apache server and the same -procedure is used by many other operations inside Apache. So, you can be -sure the design and implementation is correct. -</font> -</td></tr> -</table> - -</blockquote> - - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteCond"><h3>RewriteCond</h3></a> -<strong>Syntax:</strong> <code>RewriteCond</code> <em>TestString</em> <em>CondPattern</em><br> -<strong>Default:</strong> -<em>None</em>-<br> -<strong>Context:</strong> server config, virtual host, per-directory config<br> -<p> - -The <tt>RewriteCond</tt> directive defines a rule condition. Precede a -<tt>RewriteRule</tt> directive with one or more <t>RewriteCond</tt> -directives. - -The following rewriting rule is only used if its pattern matches the current -state of the URI <b>AND</b> if these additional conditions apply, too. - -<p> -<em>TestString</em> is a string which contains server-variables of the form - -<blockquote><strong> -<tt>%{</tt> <em>NAME_OF_VARIABLE</em> <tt>}</tt> -</strong></blockquote> - -where <em>NAME_OF_VARIABLE</em> can be a string -of the following list: - -<p> -<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5> -<tr> -<td valign=top> -<b>HTTP headers:</b><p> -<font size=-1> -HTTP_USER_AGENT<br> -HTTP_REFERER<br> -HTTP_COOKIE<br> -HTTP_FORWARDED<br> -HTTP_HOST<br> -HTTP_PROXY_CONNECTION<br> -HTTP_ACCEPT<br> -</font> -</td> - -<td valign=top> -<b>connection & request:</b><p> -<font size=-1> -REMOTE_ADDR<br> -REMOTE_HOST<br> -REMOTE_USER<br> -REMOTE_IDENT<br> -REQUEST_METHOD<br> -SCRIPT_FILENAME<br> -PATH_INFO<br> -QUERY_STRING<br> -AUTH_TYPE<br> -</font> -</td> - -</tr> -<tr> - -<td valign=top> -<b>server internals:</b><p> -<font size=-1> -DOCUMENT_ROOT<br> -SERVER_ADMIN<br> -SERVER_NAME<br> -SERVER_PORT<br> -SERVER_PROTOCOL<br> -SERVER_SOFTWARE<br> -SERVER_VERSION<br> -</font> -</td> - -<td valign=top> -<b>system stuff:</b><p> -<font size=-1> -TIME_YEAR<br> -TIME_MON<br> -TIME_DAY<br> -TIME_HOUR<br> -TIME_MIN<br> -TIME_SEC<br> -TIME_WDAY<br> -</font> -</td> - -<td valign=top> -<b>specials:</b><p> -<font size=-1> -API_VERSION<br> -THE_REQUEST<br> -REQUEST_URI<br> -REQUEST_FILENAME<br> -IS_SUBREQ<br> -</font> -</td> -</tr> -</table> - - -<p> -<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 -system. -</td></tr> -</table> - -<p> -Special Notes: -<ol> -<li>The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same -value, i.e. the value of the <tt>filename</tt> field of the internal -<tt>request_rec</tt> structure of the Apache server. The first name is just the -commonly known CGI variable name while the second is the consistent -counterpart to REQUEST_URI (which contains the value of the <tt>uri</tt> -field of <tt>request_rec</tt>). - -<p> -<li>There is the special format: <tt>%{ENV:variable}</tt> where -<i>variable</i> can be any environment variable. This is looked-up via -internal Apache structures and (if not found there) via <tt>getenv()</tt> from -the Apache server process. - -<p> -<li>There is the special format: <tt>%{HTTP:header}</tt> where -<i>header</i> can be any HTTP MIME-header name. This is looked-up -from the HTTP request. Example: <tt>%{HTTP:Proxy-Connection}</tt> -is the value of the HTTP header ``<tt>Proxy-Connection:</tt>''. - -<p> -<li>There is the special format: <tt>%{LA-U:url}</tt> -for look-aheads like <tt>-U</tt>. This performs a internal sub-request to -look-ahead for the final value of <i>url</i>. - -<p> -<li>There is the special format: <tt>%{LA-F:file}</tt> -for look-aheads like <tt>-F</tt>. This performs a internal sub-request to -look-ahead for the final value of <i>file</i>. -</ol> - -<p> -<em>CondPattern</em> is the condition pattern, i.e. a regular expression -which gets applied to the current instance of the <em>TestString</em>, i.e. -<em>TestString</em> gets evaluated and then matched against -<em>CondPattern</em>. - -<p> -<b>Remember:</b> <em>CondPattern</em> is a standard -<em>Extended Regular Expression</em> with some additions: - -<ol> -<li>You can precede the pattern string with a '<tt>!</tt>' character -(exclamation mark) to specify a <b>non</b>-matching pattern. - -<p> -<li> -There are some special variants of <em>CondPatterns</em>. Instead of real -regular expression strings you can also use one of the following: -<p> -<ul> -<li>'<b>-d</b>' (is <b>d</b>irectory)<br> -Treats the <i>TestString</i> as a pathname and -tests if it exists and is a directory. -<p> -<li>'<b>-f</b>' (is regular <b>f</b>ile)<br> -Treats the <i>TestString</i> as a pathname and -tests if it exists and is a regular file. -<p> -<li>'<b>-s</b>' (is regular file with <b>s</b>ize)<br> -Treats the <i>TestString</i> as a pathname and -tests if it exists and is a regular file with size greater then zero. -<p> -<li>'<b>-l</b>' (is symbolic <b>l</b>ink)<br> -Treats the <i>TestString</i> as a pathname and -tests if it exists and is a symbolic link. -<p> -<li>'<b>-F</b>' (is existing file via subrequest)<br> -Checks if <i>TestString</i> is a valid file and accessible via all the -server's currently-configured access controls for that path. This uses an -internal subrequest to determine the check, so use it with care because it -decreases your servers performance! -<p> -<li>'<b>-U</b>' (is existing URL via subrequest)<br> -Checks if <i>TestString</i> is a valid URL and accessible via all the server's -currently-configured access controls for that path. This uses an internal -subrequest to determine the check, so use it with care because it decreases -your servers performance! -</ul> -<p> -Notice: All of these tests can also be prefixed by a not ('!') character -to negate their meaning. -</ol> - -<p> -Additionally you can set special flags for <em>CondPattern</em> by appending - -<blockquote><strong> -<code>[</code><em>flags</em><code>]</code> -</strong></blockquote> - -as the third argument to the <tt>RewriteCond</tt> directive. <em>Flags</em> -is a comma-separated list of the following flags: - -<ul> -<li>'<strong><code>nocase|NC</code></strong>' (<b>n</b>o <b>c</b>ase)<br> - This makes the condition test case-insensitive, i.e. there is - no difference between 'A-Z' and 'a-z' both in the expanded - <em>TestString</em> and the <em>CondPattern</em>. -<p> -<li>'<strong><code>ornext|OR</code></strong>' (<b>or</b> next condition)<br> - Use this to combine rule conditions with a local OR instead of the - implicit AND. Typical example: - <p> -<blockquote><pre> -RewriteCond %{REMOTE_HOST} ^host1.* [OR] -RewriteCond %{REMOTE_HOST} ^host2.* [OR] -RewriteCond %{REMOTE_HOST} ^host3.* -RewriteRule ...some special stuff for any of these hosts... -</pre></blockquote> - Without this flag you had to write down the cond/rule three times. -<p> -</ul> - -<p> -<b>Example:</b> -<blockquote> - -To rewrite the Homepage of a site according to the ``<tt>User-Agent:</tt>'' -header of the request, you can use the following: - -<blockquote><pre> -RewriteCond %{HTTP_USER_AGENT} ^Mozilla.* -RewriteRule ^/$ /homepage.max.html [L] - -RewriteCond %{HTTP_USER_AGENT} ^Lynx.* -RewriteRule ^/$ /homepage.min.html [L] - -RewriteRule ^/$ /homepage.std.html [L] -</pre></blockquote> - -Interpretation: If you use Netscape Navigator as your browser (which identifies -itself as 'Mozilla'), then you get the max homepage, which includes -Frames, etc. If you use the Lynx browser (which is Terminal-based), then you -get the min homepage, which contains no images, no tables, etc. If you -use any other browser you get the standard homepage. -</blockquote> -<p> - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteRule"><h3>RewriteRule</h3></a> -<strong>Syntax:</strong> <code>RewriteRule</code> <em>Pattern</em> <em>Substitution</em><br> -<strong>Default:</strong> -<em>None</em>-<br> -<strong>Context:</strong> server config, virtual host, per-directory config<br> - -<p> -The <tt>RewriteRule</tt> directive is the real rewriting workhorse. The -directive can occur more than once. Each directive then defines one single -rewriting rule. The <b>definition order</b> of these rules is -<b>important</b>, because this order is used when applying the rules at -run-time. - -<p> -<a name="patterns"><em>Pattern</em></a> can be (for Apache 1.1.x a System -V8 and for Apache 1.2.x a POSIX) <a name="regexp">regular expression</a> -which gets applied to the current URL. Here ``current'' means the value of the -URL when this rule gets applied. This may not be the original requested -URL, because there could be any number of rules before which already matched -and made alterations to it. - -<p> -Some hints about the syntax of regular expressions: - -<p> -<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5> -<tr> -<td valign=top> -<pre> -<strong><code>^</code></strong> Start of line -<strong><code>$</code></strong> End of line -<strong><code>.</code></strong> Any single character -<strong><code>[</code></strong>chars<strong><code>]</code></strong> One of chars -<strong><code>[^</code></strong>chars<strong><code>]</code></strong> None of chars - -<strong><code>?</code></strong> 0 or 1 of the preceding char -<strong><code>*</code></strong> 0 or N of the preceding char -<strong><code>+</code></strong> 1 or N of the preceding char - -<strong><code>\</code></strong>char escape that specific char - (e.g. for specifying the chars "<code>.[]()</code>" etc.) - -<strong><code>(</code></strong>string<strong><code>)</code></strong> Grouping of chars (the <b>N</b>th group can be used on the RHS with <code>$</code><b>N</b>) -</pre> -</td> -</tr> -</table> - -<p> -Additionally the NOT character ('<tt>!</tt>') is a possible pattern -prefix. This gives you the ability to negate a pattern; to say, for instance: ``<i>if -the current URL does <b>NOT</b> match to this pattern</i>''. This can be used -for special cases where it is better to match the negative pattern or as a -last default rule. - -<p> -<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 -the pattern does NOT match, there are no contents for the groups. In -consequence, if negated patterns are used, you cannot use <tt>$N</tt> in the -substitution string! -</td></tr> -</table> - -<p> -<a name="rhs"><em>Substitution</em></a> of a rewriting rule is the string -which is substituted for (or replaces) the original URL for which -<em>Pattern</em> matched. Beside plain text you can use - -<ol> -<li>pattern-group back-references (<code>$N</code>) -<li>server-variables as in rule condition test-strings (<code>%{VARNAME}</code>) -<li><a href="#mapfunc">mapping-function</a> calls (<code>${mapname:key|default}</code>) -</ol> - -Back-references are <code>$</code><b>N</b> (<b>N</b>=1..9) identifiers which -will be replaced by the contents of the <b>N</b>th group of the matched -<em>Pattern</em>. The server-variables are the same as for the -<em>TestString</em> of a <tt>RewriteCond</tt> directive. The -mapping-functions come from the <tt>RewriteMap</tt> directive and are -explained there. These three types of variables are expanded in the order of -the above list. - -<p> -As already mentioned above, all the rewriting rules are applied to the -<em>Substitution</em> (in the order of definition in the config file). The -URL is <b>completely replaced</b> by the <em>Substitution</em> and the -rewriting process goes on until there are no more rules (unless explicitly -terminated by a <code><b>L</b></code> flag - see below). - -<p> -There is a special substitution string named '<tt>-</tt>' which means: -<b>NO substitution</b>! Sounds silly? No, it is useful to provide rewriting -rules which <b>only</b> match some URLs but do no substitution, e.g. in -conjunction with the <b>C</b> (chain) flag to be able to have more than one -pattern to be applied before a substitution occurs. - -<p> -<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 -<b>mod_rewrite</b> automatically strips it out. This auto-reduction on -implicit external redirect URLs is a useful and important feature when -used in combination with a mapping-function which generates the hostname -part. Have a look at the first example in the example section below to -understand this. -<p> -<b>Remember:</b> An unconditional external redirect to your own server will -not work with the prefix <tt>http://thishost</tt> because of this feature. -To achieve such a self-redirect, you have to use the <b>R</b>-flag (see -below). -</td></tr> -</table> - -<p> -Additionally you can set special flags for <em>Substitution</em> by appending - -<blockquote><strong> -<code>[</code><em>flags</em><code>]</code> -</strong></blockquote> - -as the third argument to the <tt>RewriteRule</tt> directive. <em>Flags</em> is a -comma-separated list of the following flags: - -<ul> -<li>'<strong><code>redirect|R</code>[=<i>code</i>]</strong>' (force <a name="redirect"><b>r</b>edirect</a>)<br> - Prefix <em>Substitution</em> - with <code>http://thishost[:thisport]/</code> (which makes the new URL a URI) to - force a external redirection. If no <i>code</i> is given a HTTP response - of 302 (MOVED TEMPORARILY) is used. If you want to use other response - codes in the range 300-400 just specify them as a number or use - one of the following symbolic names: <tt>temp</tt> (default), <tt>permanent</tt>, - <tt>seeother</tt>. - Use it for rules which should - canonicalize the URL and gives it back to the client, e.g. translate - ``<code>/~</code>'' into ``<code>/u/</code>'' or always append a slash to - <code>/u/</code><em>user</em>, etc.<br> - <p> - <b>Notice:</b> When you use this flag, make sure that the - substitution field is a valid URL! If not, you are redirecting to an - invalid location! And remember that this flag itself only prefixes the - URL with <code>http://thishost[:thisport]/</code>, but rewriting goes on. - Usually you also want to stop and do the redirection immediately. To stop - the rewriting you also have to provide the 'L' flag. -<p> -<li>'<strong><code>forbidden|F</code></strong>' (force URL to be <b>f</b>orbidden)<br> - This forces the current URL to be forbidden, i.e. it immediately sends - back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with - appropriate RewriteConds to conditionally block some URLs. -<p> -<li>'<strong><code>gone|G</code></strong>' (force URL to be <b>g</b>one)<br> - This forces the current URL to be gone, i.e. it immediately sends back a - HTTP response of 410 (GONE). Use this flag to mark no longer existing - pages as gone. -<p> -<li>'<strong><code>proxy|P</code></strong>' (force <b>p</b>roxy)<br> - This flag forces the substitution part to be internally forced as a proxy - request and immediately (i.e. rewriting rule processing stops here) put - through the proxy module. You have to make sure that the substitution - string is a valid URI (e.g. typically <tt>http://</tt>) which can - be handled by the Apache proxy module. If not you get an error from - the proxy module. Use this flag to achieve a more powerful implementation - of the <tt>mod_proxy</tt> directive <tt>ProxyPass</tt>, to map - some remote stuff into the namespace of the local server. - <p> - Notice: <b>You really have to put <tt>ProxyRequests On</tt> into your - server configuration to prevent proxy requests from leading to core-dumps - inside the Apache kernel. If you have not compiled in the proxy module, - then there is no core-dump problem, because mod_rewrite checks for - existence of the proxy module and if lost forbids proxy URLs. </b> -<p> -<li>'<strong><code>last|L</code></strong>' (<b>l</b>ast rule)<br> - Stop the rewriting process here and - don't apply any more rewriting rules. This corresponds to the Perl - <code>last</code> command or the <code>break</code> command from the C - language. Use this flag to prevent the currently rewritten URL from being - rewritten further by following rules which may be wrong. For - example, use it to rewrite the root-path URL ('<code>/</code>') to a real - one, e.g. '<code>/e/www/</code>'. -<p> -<li>'<strong><code>next|N</code></strong>' (<b>n</b>ext round)<br> - Re-run the rewriting process (starting again with the first rewriting - rule). Here the URL to match is again not the original URL but the URL - from the last rewriting rule. This corresponds to the Perl - <code>next</code> command or the <code>continue</code> command from the C - language. Use this flag to restart the rewriting process, i.e. to - immediately go to the top of the loop. <br> - <b>But be careful not to create a deadloop!</b> -<p> -<li>'<strong><code>chain|C</code></strong>' (<b>c</b>hained with next rule)<br> - This flag chains the current rule with the next rule (which itself can - also be chained with its following rule, etc.). This has the following - effect: if a rule matches, then processing continues as usual, i.e. the - flag has no effect. If the rule does <b>not</b> match, then all following - chained rules are skipped. For instance, use it to remove the - ``<tt>.www</tt>'' part inside a per-directory rule set when you let an - external redirect happen (where the ``<tt>.www</tt>'' part should not to - occur!). -<p> -<li>'<strong><code>type|T</code></strong>=<em>mime-type</em>' (force MIME <b>t</b>ype)<br> - Force the MIME-type of the target file to be <em>mime-type</em>. For - instance, this can be used to simulate the old <tt>mod_alias</tt> - directive <tt>ScriptAlias</tt> which internally forces all files inside - the mapped directory to have a MIME type of - ``<tt>application/x-httpd-cgi</tt>''. -<p> -<li>'<strong><code>nosubreq|NS</code></strong>' (used only if <b>n</b>o internal <b>s</b>ub-request)<br> - This flag forces the rewriting engine to skip a rewriting rule if the - current request is an internal sub-request. For instance, sub-requests - occur internally in Apache when <tt>mod_include</tt> tries to find out - information about possible directory default files (<tt>index.xxx</tt>). - On sub-requests it is not always useful and even sometimes causes a failure to - if the complete set of rules are applied. Use this flag to exclude some rules.<br> - <p> - Use the following rule for your decision: whenever you prefix some URLs - with CGI-scripts to force them to be processed by the CGI-script, the - chance is high that you will run into problems (or even overhead) on sub-requests. - In these cases, use this flag. -<p> -<li>'<strong><code>passthrough|PT</code></strong>' (<b>p</b>ass <b>t</b>hrough to next handler)<br> - This flag forces the rewriting engine to set the <code>uri</code> field - of the internal <code>request_rec</code> structure to the value - of the <code>filename</code> field. This flag is just a hack to be able - to post-process the output of <tt>RewriteRule</tt> directives by - <tt>Alias</tt>, <tt>ScriptAlias</tt>, <tt>Redirect</tt>, etc. directives - from other URI-to-filename translators. A trivial example to show the - semantics: - If you want to rewrite <tt>/abc</tt> to <tt>/def</tt> via the rewriting - engine of <tt>mod_rewrite</tt> and then <tt>/def</tt> to <tt>/ghi</tt> - with <tt>mod_alias</tt>: - <pre> - RewriteRule ^/abc(.*) /def$1 [PT] - Alias /def /ghi - </pre> - If you omit the <tt>PT</tt> flag then <tt>mod_rewrite</tt> - will do its job fine, i.e. it rewrites <tt>uri=/abc/...</tt> to - <tt>filename=/def/...</tt> as a full API-compliant URI-to-filename - translator should do. Then <tt>mod_alias</tt> comes and tries to do a - URI-to-filename transition which will not work. - <p> - Notice: <b>You have to use this flag if you want to intermix directives - of different modules which contain URL-to-filename translators</b>. The - 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> -<tr><td> -<font size=-1> - <b>For the Apache hackers:</b><br> - If the current Apache API had a - filename-to-filename hook additionally to the URI-to-filename hook then - we wouldn't need this flag! But without such a hook this flag is the - only solution. The Apache Group has discussed this problem and will - add such hooks into Apache version 2.0. -</font> -</td></tr> -</table> -<p> -<li>'<strong><code>skip|S</code></strong>=<em>num</em>' (<b>s</b>kip next rule(s))<br> - This flag forces the rewriting engine to skip the next <em>num</em> rules - in sequence when the current rule matches. Use this to make pseudo - if-then-else constructs: The last rule of the then-clause becomes - a <tt>skip=N</tt> where N is the number of rules in the else-clause. - (This is <b>not</b> the same as the 'chain|C' flag!) -<p> -<li>'<strong><code>env|E=</code></strong><i>VAR</i>:<i>VAL</i>' (set <b>e</b>nvironment variable)<br> - This forces an environment variable named <i>VAR</i> to be set to the value - <i>VAL</i>, where <i>VAL</i> can contain regexp backreferences <tt>$N</tt> - 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. -</ul> - -<p> -<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 -files, the per-directory prefix (which always is the same for a specific -directory!) gets automatically <em>removed</em> for the pattern matching and -automatically <em>added</em> after the substitution has been done.</b> This feature is -essential for many sorts of rewriting, because without this prefix stripping -you have to match the parent directory which is not always possible. -<p> -There is one exception: If a substitution string starts with -``<tt>http://</tt>'' then the directory prefix will be <b>not</b> added and a -external redirect or proxy throughput (if flag <b>P</b> is used!) is forced! -</td></tr> -</table> - -<p> -<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> -``<tt>Option FollowSymLinks</tt>'' enabled. If your administrator has -disabled override of <tt>FollowSymLinks</tt> for a user's directory, then -you cannot use the rewriting engine. This restriction is needed for -security reasons. -</td></tr> -</table> - -<p> -Here are all possible substitution combinations and their meanings: - -<p> -<b>Inside per-server configuration (<tt>httpd.conf</tt>)<br> -for request ``<tt>GET /somepath/pathinfo</tt>'':</b><br> - -<p> -<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5> -<tr> -<td> -<pre> -<b>Given Rule</b> <b>Resulting Substitution</b> ----------------------------------------------- ---------------------------------- -^/somepath(.*) otherpath$1 not supported, because invalid! - -^/somepath(.*) otherpath$1 [R] not supported, because invalid! - -^/somepath(.*) otherpath$1 [P] not supported, because invalid! ----------------------------------------------- ---------------------------------- -^/somepath(.*) /otherpath$1 /otherpath/pathinfo - -^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo - via external redirection - -^/somepath(.*) /otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo - -^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo - via external redirection - -^/somepath(.*) http://thishost/otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo - via external redirection - -^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo - via external redirection - (the [R] flag is redundant) - -^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo - via internal proxy -</pre> -</td> -</tr> -</table> - -<p> -<b>Inside per-directory configuration for <tt>/somepath</tt><br> -(i.e. file <tt>.htaccess</tt> in dir <tt>/physical/path/to/somepath</tt> containing -<tt>RewriteBase /somepath</tt>)<br> for -request ``<tt>GET /somepath/localpath/pathinfo</tt>'':</b><br> - -<p> -<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5> -<tr> -<td> -<pre> -<b>Given Rule</b> <b>Resulting Substitution</b> ----------------------------------------------- ---------------------------------- -^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo - -^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo - via external redirection - -^localpath(.*) otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^localpath(.*) /otherpath$1 /otherpath/pathinfo - -^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo - via external redirection - -^localpath(.*) /otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo - -^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo - via external redirection - -^localpath(.*) http://thishost/otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo - via external redirection - -^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo - via external redirection - (the [R] flag is redundant) - -^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo - via internal proxy -</pre> -</td> -</tr> -</table> - - -</td> -</tr> -</table> - -<p> -<b>Example:</b> -<p> -<blockquote> -We want to rewrite URLs of the form -<blockquote> -<code>/</code> <em>Language</em> -<code>/~</code> <em>Realname</em> -<code>/.../</code> <em>File</em> -</blockquote> -into -<blockquote> -<code>/u/</code> <em>Username</em> -<code>/.../</code> <em>File</em> -<code>.</code> <em>Language</em> -</blockquote> -<p> -We take the rewrite mapfile from above and save it under -<code>/anywhere/map.real-to-user</code>. Then we only have to add the -following lines to the Apache server configuration file: - -<blockquote> -<pre> -RewriteLog /anywhere/rewrite.log -RewriteMap real-to-user txt:/anywhere/map.real-to-host -RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1 -</pre> -</blockquote> -</blockquote> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_status.html b/docs/manual/mod/mod_status.html deleted file mode 100644 index f5a55fa397..0000000000 --- a/docs/manual/mod/mod_status.html +++ /dev/null @@ -1,107 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>Apache module mod_status</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">Module mod_status</h1> - -The Status Module is only available in Apache 1.1 and later.<p> - -<h2>Function</h2> - -The Status module allows a server administrator to find out how well -their server is performing. A HTML page is presented that gives -the current server statistics in an easily readable form. If required -this page can be made to automatically refresh (given a compatible -browser). Another page gives a simple machine-readable list of the current -server state. -<p> -The details given are: -<ul> -<li>The number of children serving requests -<li>The number of idle children -<li>The status of each child, the number of requests that child has -performed and the total number of bytes served by the child (*) -<li>A total number of accesses and byte count served (*) -<li>The time the server was started/restarted and the -time it has been running for -<li>Averages giving the number of requests per second, -the number of bytes served per second and the average number -of bytes per request (*) -<li>The current percentage CPU used by each child and in total by -Apache (*) -<li>The current hosts and requests being processed (*) -</ul> - -A compile-time option must be used to display the details marked "(*)" as -the instrumentation required for obtaining these statistics does not -exist within standard Apache. - -<h2>Enabling Status Support</h2> - -To enable status reports only for browsers from the foo.com -domain add this code to your <code>access.conf</code> configuration file -<pre> - <Location /server-status> - SetHandler server-status - - order deny,allow - deny from all - allow from .foo.com - </Location> -</pre> -<p> -You can now access server statistics by using a Web browser to access the -page <code>http://your.server.name/server-status</code> -<p> -Note that mod_status will only work when you are running Apache in -<A HREF="core.html#servertype">standalone</A> mode and not -<A HREF="core.html#servertype">inetd</A> mode. - -<h3>Automatic Updates</h3> -You can get the status page to update itself automatically if you have -a browser that supports "refresh". Access the page -<code>http://your.server.name/server-status?refresh=N</code> to refresh the page -every N seconds. -<h3>Machine Readable Status File</h3> -A machine-readable version of the status file is available by accessing the -page <code>http://your.server.name/server-status?auto</code>. This is useful -when automatically run, see the Perl program in the <code>/support</code> -directory of Apache, <code>log_server_status</code>. - -<h2>Full Instrumentation</h2> - -To obtain full statistics you must compile Apache with a special -directive. On some machines there may be a small performance loss -if you do this. Try full statistics and see if you notice any -difference. If you do please contact <a href="mailto:mark@ukweb.com"> -mark@ukweb.com</a> and tell me your configuration. - -<p> - -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 -</pre> - -<BLOCKQUOTE> - <STRONG> - It should be noted that if <SAMP>mod_status</SAMP> is compiled into - the server, its handler capability is available in <EM>all</EM> - configuration files, including <EM>per</EM>-directory files - (<EM>e.g.</EM>, <SAMP>.htaccess</SAMP>). This may have - security-related ramifications for your site. - </STRONG> -</BLOCKQUOTE> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_userdir.html b/docs/manual/mod/mod_userdir.html deleted file mode 100644 index cca87f5020..0000000000 --- a/docs/manual/mod/mod_userdir.html +++ /dev/null @@ -1,76 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_userdir</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">Module mod_userdir</h1> - -This module is contained in the <code>mod_userdir.c</code> file, and -is compiled in by default. It provides for user-specific directories. - - -<ul> -<li><A HREF="#userdir">UserDir</A> -</ul> -<hr> - - -<h2><A name="userdir">UserDir</A></h2> -<!--%plaintext <?INDEX {\tt UserDir} directive> --> -<strong>Syntax:</strong> UserDir <em>directory/filename</em><br> -<strong>Default:</strong> <code>UserDir public_html</code><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_userdir<br> -<strong>Compatibility:</strong> All forms except the <code>UserDir -public_html</code> form are only available in Apache 1.1 or above.<p> - -The UserDir directive sets the real directory in a user's home directory -to use when a request for a document for a user is received. -<em>Directory</em> is either <code>disabled</code>, to disable this feature, - or the name of a directory, following one of the following -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 -</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 -</pre> - -<P> -<STRONG> -Be careful when using this directive; for instance, <SAMP>"UserDir -./"</SAMP> would map <SAMP>"/~root"</SAMP> to -<SAMP>"/"</SAMP> - which is probably undesirable. See also -the -<A - HREF="core.html#directory" -><Directory></A> -directive and the -<A - HREF="../misc/security_tips.html" ->Security Tips</A> -page for more information. -</STRONG> -</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_usertrack.html b/docs/manual/mod/mod_usertrack.html deleted file mode 100644 index 585e45d64d..0000000000 --- a/docs/manual/mod/mod_usertrack.html +++ /dev/null @@ -1,87 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_usertrack</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">Module mod_usertrack</h1> - -Previous releases of Apache have included a module which generates a -'clickstream' log of user activity on a site using cookies. This was -called the "cookies" module, mod_cookies. In Apache 1.2 and later this -module has been renamed the "user tracking" module, -mod_usertrack. This module has been simplified and new directives -added. - -<hr> - -<h2>Logging</h2> - -Previously, the cookies module (now the user tracking module) did its -own logging, using the <tt>CookieLog</tt> directive. In this release, -this module does no logging at all. Instead, a configurable log -format file should be used to log user click-streams. This is possible -because the logging module now allows <a -href="../multilogs.html">multiple log files</a>. The cookie itself is -logged by using the text <tt>%{cookie}n </tt> - -in the log file format. For example: -<pre> -CustomLog logs/clickstream "%{cookie}n %r %t" -</pre> - -For backward compatibility the configurable log module implements the -old <tt>CookieLog</tt> directive, but this should be upgraded to the -above <tt>CustomLog</tt> directive. - -<h2>Directives</h2> - -<ul> -<li><a href="#cookieexpires">CookieExpires</a> -<li><a href="#cookietracking">CookieTracking</a> -</ul> - -<hr> - -<h2><a name="cookieexpires">CookieExpires</A></h2> -<strong>Syntax:</strong> CookieExpires <em>expiry-period</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> optional<br> -<strong>Module:</strong> mod_usertrack<p> - -When used, this directive sets an expiry time on the cookie generated -by the usertrack module. The <i>expiry-period</i> can be given either -as a number of seconds, or in the format such as "2 weeks 3 days 7 -hours". Valid denominations are: years, months, weeks, hours, minutes -and seconds. - -<p>If this directive is not used, cookies last only for the current -browser session.</p> - -<h2><a name="cookietracking">CookieTracking</A></h2> -<strong>Syntax:</strong> CookieTracking <em>on | off</em><br> -<strong>Context:</strong> server config, virtual host, directory, -.htaccess<br> -<strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> optional<br> -<strong>Module:</strong> mod_usertrack<p> - -When the user track module is compiled in, and "CookieTracking on" is -set, Apache will start sending a user-tracking cookie for all new -requests. This directive can be used to turn this behavior on or off -on a per-server or per-directory basis. By default, compiling -mod_usertrack will not activate cookies. - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/platform/perf-bsd44.html b/docs/manual/platform/perf-bsd44.html deleted file mode 100644 index 0a1661b7ca..0000000000 --- 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 7cc8bb1308..0000000000 --- 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 96c48ea199..0000000000 --- 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 eb8adbe2fe..0000000000 --- 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 deleted file mode 100644 index c130decffa..0000000000 --- a/docs/manual/process-model.html +++ /dev/null @@ -1,68 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Server Pool Management</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">Server Pool Management</H1> - -<HR> -<P> -We found that many people were using values for "MaxServers" either -too high or too low, and were hanging themselves on it. The model we -adopted is still based on long-lived minimal-forking processes, but -instead of specifying one number of persistent processes, the -web-master specifies a maximum and minimum number of processes to be -"spare" - every couple of seconds the parent checks the actual number -of spare servers and adjusts accordingly. This should keep the number -of servers concurrently running relatively low while still ensuring -minimal forking. - -<P> - -We renamed the current StartServers to MinSpareServers, created -separate StartServers parameter which means what it says, and renamed -MaxServers to MaxSpareServers (though the old name still works, for -NCSA 1.4 back-compatibility). The old names were generally regarded -as too confusing. - -<P> - -The defaults for each variable are: - -<PRE> -MinSpareServers 5 -MaxSpareServers 10 -StartServers 5 -</PRE> - -There is an absolute maximum number of simultaneous children defined -by a compile-time limit which defaults to 256 and a "MaxClients" -directive which specifies the number of simultaneous children that -will be allowed. MaxClients can be adjusted up to the compile-time -limit (HARD_SERVER_LIMIT, defined in httpd.h). If you need more -than 256 simultaneous children, you need to modify both HARD_SERVER_LIMIT -and MaxClients.<P> - -In versions before 1.2, HARD_SERVER_LIMIT defaulted to 150.<P> - -We do not recommend changing either of these values unless: - -<OL> -<LI>You know you have the server resources to handle more -<LI>You use the machine for other purposes and must limit the amount of memory -Apache uses -</OL> - -<!--#include virtual="footer.html" --> -</body></html> - - diff --git a/docs/manual/search/manual-index.cgi b/docs/manual/search/manual-index.cgi deleted file mode 100644 index 8d06e8a115..0000000000 --- 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 b/docs/manual/stopping.html deleted file mode 100644 index 373590a311..0000000000 --- a/docs/manual/stopping.html +++ /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/stopping.html.en b/docs/manual/stopping.html.en deleted file mode 100644 index 373590a311..0000000000 --- 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 deleted file mode 100644 index 7806bc8f55..0000000000 --- a/docs/manual/suexec.html +++ /dev/null @@ -1,505 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache suEXEC 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> - -<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> - -<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> - -<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> - -<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> - -<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" - - /* - * 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 - - /* - * 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 - - /* - * 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" - - /* - * 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> - -<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> - -<P ALIGN="LEFT"> -<EM>From src/httpd.h</EM> -<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> - -<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> - -<P ALIGN="LEFT"> -<STRONG><CODE>cp suexec /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG> -</P> - -<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> - -<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> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<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 -<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> - -<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> - -<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 -<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. - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<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. -</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> |
