--- /dev/null
+#!/bin/sh
+#
+# binbuild.sh - Builds an Apache binary distribution.
+# Initially written by Lars Eilebrecht <lars@apache.org>.
+#
+# This script falls under the Apache License.
+# See http://www.apache.org/docs/LICENSE
+
+
+APDIR=$(basename $(pwd))
+VER=$(echo $APDIR |sed s/apache-//)
+OS=$(src/helpers/GuessOS)
+USER="$(src/helpers/buildinfo.sh -n %u@%h%d)"
+TAR="$(src/helpers/findprg.sh tar)"
+GTAR="$(src/helpers/findprg.sh gtar)"
+GZIP="$(src/helpers/findprg.sh gzip)"
+CONFIGPARAM="--with-layout=BinaryDistribution --enable-module=most --enable-shared=max"
+
+if [ ! -f ./ABOUT_APACHE ]
+then
+ echo "ERROR: The current directory contains no valid Apache distribution."
+ echo "Please change the directory to the top level directory of a freshly"
+ echo "unpacked Apache 1.3 source distribution and re-execute the script"
+ echo "'./src/helpers/bindbuild.sh'."
+ exit 1;
+fi
+
+if [ -d ./CVS ]
+then
+ echo "ERROR: The current directory is a CVS checkout of Apache."
+ echo "Only a standard Apache 1.3 source distribution should be used to"
+ echo "create a binary distribution."
+ exit 1;
+fi
+
+echo "Building Apache $VER binary distribution..."
+echo "Platform is \"$OS\"..."
+
+( echo "Build log for Apache binary distribution" && \
+ echo "----------------------------------------------------------------------" && \
+ ./configure $CONFIGPARAM && \
+ echo "----------------------------------------------------------------------" && \
+ make clean && \
+ rm -rf bindist install-bindist.sh *.bindist
+ echo "----------------------------------------------------------------------" && \
+ make && \
+ echo "----------------------------------------------------------------------" && \
+ make install-quiet root="bindist/" && \
+ echo "----------------------------------------------------------------------" && \
+ make clean && \
+ echo "----------------------------------------------------------------------" && \
+ echo "[EOF]" \
+) > build.log 2>&1
+
+if [ ! -f ./bindist/bin/httpd ]
+then
+ echo "ERROR: Failed to build Apache. See \"build.log\" for details."
+ exit 1;
+fi
+
+echo "Binary images successfully created..."
+echo "Creating supplementary files..."
+
+( echo " " && \
+ echo "Apache $VER binary distribution" && \
+ echo "================================" && \
+ echo " " && \
+ echo "This binary distribution is usable on a \"$OS\"" && \
+ echo "system and was built by \"$USER\"." && \
+ echo "" && \
+ echo "The distribution contains all standard Apache modules as shared" && \
+ echo "objects. This allows you to enable or disable particular modules" && \
+ echo "with the LoadModule/AddModule directives in the configuration file" && \
+ echo "without the need to re-compile Apache." && \
+ echo "" && \
+ echo "See \"INSTALL.bindist\" on how to install the distribution." && \
+ echo " " && \
+ echo "NOTE: Please do not send support-related mails to the address mentioned" && \
+ echo " above or to any member of the Apache Group! Support questions" && \
+ echo " should be directed to the \"comp.infosystems.www.servers.unix\"" && \
+ echo " or \"comp.infosystems.www.servers.ms-windows\" newsgroup" && \
+ echo " (as appropriate for the platform you use), where some of the" && \
+ echo " Apache team lurk, in the company of many other Apache gurus" && \
+ echo " who should be able to help." && \
+ echo " If you think you found a bug in Apache or have a suggestion please" && \
+ echo " visit the bug report page at http://www.apache.org/bug_report.html" && \
+ echo " " && \
+ echo "----------------------------------------------------------------------" && \
+ ./bindist/bin/httpd -V && \
+ echo "----------------------------------------------------------------------" \
+) > README.bindist
+cp README.bindist ../apache-$VER-$OS.README
+
+( echo " " && \
+ echo "Apache $VER binary installation" && \
+ echo "================================" && \
+ echo " " && \
+ echo "To install this binary distribution you have to execute the installation" && \
+ echo "script \"install-bindist.sh\" in the top-level directory of the distribution." && \
+ echo " " && \
+ echo "The script takes the ServerRoot directory into which you want to install" && \
+ echo "Apache as an option. If you ommit the option the default path" && \
+ echo "\"/usr/local/apache\" is used." && \
+ echo "Make sure you have write permissions in the target directory, e.g. switch" && \
+ echo "to user \"root\" before you execute the script." && \
+ echo " " && \
+ echo "See \"README.bindist\" for further details about this distribution." && \
+ echo " " && \
+ echo "Please note that this distribution includes the complete Apache source code." && \
+ echo "Therefore you may compile Apache yourself at any time if you have a compiler" && \
+ echo "installation on your system." && \
+ echo "See \"INSTALL\" for details on how to accomplish this." && \
+ echo " " \
+) > INSTALL.bindist
+
+( echo "#!/bin/sh" && \
+ echo "#" && \
+ echo "# Usage: install-bindist.sh [ServerRoot]" && \
+ echo "# This script installs the Apache binary distribution and" && \
+ echo "# was automatically created by binbuild.sh." && \
+ echo " " && \
+ echo "if [ .\$1 = . ]" && \
+ echo "then" && \
+ echo " SR=/usr/local/apache" && \
+ echo "else" && \
+ echo " SR=\$1" && \
+ echo "fi" && \
+ echo "echo \"Installing binary distribution for platform $OS\"" && \
+ echo "echo \"into directory \$SR ...\"" && \
+ echo "./src/helpers/mkdir.sh \$SR" && \
+ echo "cp -r bindist/proxy \$SR/proxy" && \
+ echo "cp -r bindist/man \$SR/man" && \
+ echo "cp -r bindist/logs \$SR/logs" && \
+ echo "cp -r bindist/libexec \$SR/libexec" && \
+ echo "cp -r bindist/include \$SR/include" && \
+ echo "cp -r bindist/icons \$SR/icons" && \
+ echo "cp -r bindist/cgi-bin \$SR/cgi-bin" && \
+ echo "cp -r bindist/bin \$SR/bin" && \
+ echo "if [ -d \$SR/conf ]" && \
+ echo "then" && \
+ echo " echo \"[Preserving existing configuration files.]\"" && \
+ echo " cp -r bindist/conf/*.default \$SR/conf/" && \
+ echo "else" && \
+ echo " cp -r bindist/conf \$SR/conf" && \
+ echo "fi" && \
+ echo "if [ -d \$SR/htdocs ]" && \
+ echo "then" && \
+ echo " echo \"[Preserving existing htdocs directory.]\"" && \
+ echo "else" && \
+ echo " cp -r bindist/htdocs \$SR/htdocs" && \
+ echo "fi" && \
+ echo "sed -e s%/usr/local/apache%\$SR/% \$SR/conf/httpd.conf.default > \$SR/conf/httpd.conf" && \
+ echo "sed -e s%PIDFILE=%PIDFILE=\$SR/% -e s%HTTPD=%HTTPD=\\\"\$SR/% -e \"s%/httpd$%/httpd -d \$SR\\\"%\" bindist/bin/apachectl > \$SR/bin/apachectl" && \
+ echo " " && \
+ echo "echo \"Ready.\"" && \
+ echo "echo \" +--------------------------------------------------------+\"" && \
+ echo "echo \" | You now have successfully installed the Apache $VER |\"" && \
+ echo "echo \" | HTTP server. To verify that Apache actually works |\"" && \
+ echo "echo \" | correctly you now should first check the (initially |\"" && \
+ echo "echo \" | created or preserved) configuration files |\"" && \
+ echo "echo \" | |\"" && \
+ echo "echo \" | \$SR/conf/httpd.conf\"" && \
+ echo "echo \" | |\"" && \
+ echo "echo \" | and then you should be able to immediately fire up |\"" && \
+ echo "echo \" | Apache the first time by running: |\"" && \
+ echo "echo \" | |\"" && \
+ echo "echo \" | \$SR/bin/apachectl start \"" &&\
+ echo "echo \" | |\"" && \
+ echo "echo \" | Thanks for using Apache. The Apache Group |\"" && \
+ echo "echo \" | http://www.apache.org/ |\"" && \
+ echo "echo \" +--------------------------------------------------------+\"" && \
+ echo "echo \" \"" \
+) > install-bindist.sh
+chmod 755 install-bindist.sh
+
+sed -e "s%\"/htdocs%\"/usr/local/apache/htdocs%" \
+ -e "s%\"/icons%\"/usr/local/apache/icons%" \
+ -e "s%\"/cgi-bin%\"/usr/local/apache/cgi-bin%" \
+ -e "s%^ServerAdmin.*%ServerAdmin you@your.address%" \
+ -e "s%#ServerName.*%#ServerName localhost%" \
+ -e "s%Port 8080%Port 80%" \
+ bindist/conf/httpd.conf.default > bindist/conf/httpd.conf
+cp bindist/conf/httpd.conf bindist/conf/httpd.conf.default
+
+echo "Creating distribution archive and readme file..."
+
+if [ ".`grep -i error build.log > /dev/null`" != . ]
+then
+ echo "ERROR: Failed to build Apache. See \"build.log\" for details."
+ exit 1;
+else
+ if [ ".$GTAR" != . ]
+ then
+ $GTAR -zcf ../apache-$VER-$OS.tar.gz -C .. --owner=root --group=root apache-$VER
+ else
+ if [ ".$TAR" != . ]
+ then
+ $TAR -cf ../apache-$VER-$OS.tar -C .. apache-$VER
+ if [ ".$GZIP" != . ]
+ then
+ $GZIP ../apache-$VER-$OS.tar
+ fi
+ else
+ echo "ERROR: Could not find a 'tar' program!"
+ echo " Please execute the following commands manually:"
+ echo " tar -cf ../apache-$VER-$OS.tar ."
+ echo " gzip ../apache-$VER-$OS.tar"
+ fi
+ fi
+
+ if [ -f ../apache-$VER-$OS.tar.gz ] && [ -f ../apache-$VER-$OS.README ]
+ then
+ echo "Ready."
+ echo "You can find the binary archive (apache-$VER-$OS.tar.gz)"
+ echo "and the readme file (apache-$VER-$OS.README) in the"
+ echo "parent directory."
+ exit 0;
+ else
+ exit 1;
+ fi
+fi
--- /dev/null
+<html><head>
+<title>PATH_INFO Changes in the CGI Environment</title>
+</head><body>
+
+<!--#include virtual="header.html" -->
+<h1>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
+counterintiutive, 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
+gauranteed that
+"<code>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</code>"
+will always be an accessable URL that points to the current script,
+something which was not neccessarily 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 neccessary 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 existance 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>
+
--- /dev/null
+<html><head>
+<title>PATH_INFO Changes in the CGI Environment</title>
+</head><body>
+
+<!--#include virtual="header.html" -->
+<h1>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
+counterintiutive, 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
+gauranteed that
+"<code>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</code>"
+will always be an accessable URL that points to the current script,
+something which was not neccessarily 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 neccessary 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 existance 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>
+
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<html><head>
+<title>Issues Regarding DNS and Apache</title>
+</head><body>
+
+<!--#include virtual="header.html" -->
+<h1>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.
+
+<a name="tips"><h3>Tips to Avoid these problems</h3></a>
+
+<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>
+
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML><HEAD>
+<TITLE>Apache 1.3 Dynamic Shared Object (DSO) 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>Apache 1.3 Dynamic Shared Object (DSO) support</H1>
+
+<P><HR><P>
+
+<address>Originally written by Ralf S. Engelschall, April 1998</address>
+
+<H3>Background</H3>
+
+<P>On modern Unix derivatives there exists a nifty mechanism usually
+ called dynamic linking/loading of Dynamic Shared Objects (DSO) which
+ provides a way to build a piece of program code in a special format
+ for loading it at run-time into the address space of an executable
+ program.
+
+<P>This loading can usually be done in two ways: Automatically by a
+ system program called <CODE>ld.so</CODE> when an executable program
+ is started or manually from within the executing program via a
+ programmatic system interface to the Unix loader through the system
+ calls <CODE>dlopen()/dlsym()</CODE>.
+
+<P>In the first way the DSO's are usually called "shared libraries" or
+ "DSO libraries" and named <CODE>libfoo.so</CODE> or
+ <CODE>libfoo.so.1.2</CODE>. They reside in a system directory
+ (usually <CODE>/usr/lib</CODE>) and the link to the executable
+ program is established at link-time by specifying <CODE>-lfoo</CODE>
+ to the linker command. This hardcodes library references into the
+ executable program file so that at start-time the Unix loader is able
+ to locate <CODE>libfoo.so</CODE> in <CODE>/usr/lib</CODE> or in paths
+ configured via the environment variable
+ <CODE>LD_LIBRARY_PATH</CODE>. It then resolves any (yet unresolved)
+ symbols in the executable program which are available in the DSO.
+
+<P>Symbols in the executable program are usually not referenced by the
+ DSO (because it's a reuseable library of general code) and hence no
+ further resolving has to be done. The executable program has no need
+ to do anything on its own to use the symbols from the DSO because the
+ complete resolving is done by the Unix loader. (In fact, the code to
+ invoke <CODE>ld.so</CODE> is part of the run-time startup code which
+ is linked into every executable program which has been bound
+ non-static). The advantage of dynamic loading of common library code
+ is obvious: the library code needs to be stored only once, in a
+ system library like <CODE>libc.so</CODE>, saving disk space for every
+ program.
+
+<P>In the second way the DSO's are usually called "shared objects" or
+ "DSO files" and can be named with an arbitrary extension (although
+ the canonical name is <CODE>foo.so</CODE>). These files usually stay
+ inside a program-specific directory and there is no automatically
+ established link to the executable program where they are
+ used. Instead the executable program manually loads the DSO at
+ run-time into its address space via <CODE>dlopen()</CODE>. At this
+ time no resolving of symbols from the DSO for the executable program
+ is done. But instead the Unix loader automatically resolves any (yet
+ unresolved) symbols in the DSO from the set of symbols exported by
+ the executable program and its already loaded DSO libraries
+ (especially all symbols from the ubiquitous <CODE>libc.so</CODE>).
+ This way the DSO gets knowledge of the executable program's symbol
+ set as if it had been statically linked with it in the first place.
+
+<P>Finally, to take advantage of the DSO's API the executable program
+ has to resolve particular symbols from the DSO via
+ <CODE>dlsym()</CODE> for later use inside dispatch tables etc. In
+ other words: The executable program has to manually resolve every
+ symbol it needs to be able to use it. The advantage of such a
+ mechanism is that optional program parts need not be loaded (and thus
+ do not spend memory) until they are needed by the program in
+ question. When required, these program parts can be loaded
+ dynamically to extend the base program's functionality.
+
+<P>Although this DSO mechanism sounds straightforward there is at least one
+ difficult step here: The resolving of symbols from the executable program for
+ the DSO when using a DSO to extend a program (the second way). Why? Because
+ `reverse resolving' DSO symbols from the executable program's symbol set is
+ against the library design (where the library has no knowledge about the
+ programs it is used by) and is neither available under all platforms nor
+ standardized. In practice the executable program's global symbols are often
+ not re-exported and thus not available for use in a DSO. Finding a way to
+ force the linker to export all global symbols is the main problem one has to
+ solve when using DSO for extending a program at run-time.
+
+<H3>Practical Usage</H3>
+
+<P>The shared library approach is the typical one, because it is what the DSO
+ mechanism was designed for, hence it is used for nearly all types of
+ libraries the operating system provides. On the other hand using shared
+ objects for extending a program is not used by a lot of programs.
+
+<P>As of 1998 there are only a few software packages available which use the DSO
+ mechanism to actually extend their functionality at run-time: Perl 5 (via its
+ XS mechanism and the DynaLoader module), GIMP, Netscape Server, etc.
+ Starting with version 1.3, Apache joined the crew, because Apache already
+ uses a module concept to extend its functionality and internally uses a
+ dispatch-list-based approach to link external modules into the Apache core
+ functionality. So, Apache is really predestined for using DSO to load its
+ modules at run-time.
+
+<P>As of Apache 1.3, the configuration system supports two optional features for
+ taking advantage of the modular DSO approach: compilation of the Apache core
+ program into a DSO library for shared usage and compilation of the Apache
+ modules into DSO files for explicit loading at run-time.
+
+<H3>Implementation</H3>
+
+<P> The DSO support for loading individual Apache modules is based on a module
+ named mod_so.c which has to be statically compiled into the Apache core. It
+ is the only module besides http_core.c which cannot be put into a DSO itself
+ (bootstrapping!). Practically all other distributed Apache modules then can
+ then be placed into a DSO by individually enabling the DSO build for them via
+ configure's --enable-shared option (see ../INSTALL file) or by changing the
+ `AddModule' command in src/Configuration.tmpl into a `SharedModule' command
+ (see ./INSTALL file). After a module is compiled into a DSO named mod_foo.so
+ you can use mod_so's `LoadModule' command in your httpd.conf file to load
+ this module at server startup or restart.
+
+<P>To simplify this creation of DSO files for Apache modules (especially for
+ third-party modules) a new support program named `apxs' is available. It can
+ be used to build DSO based modules _outside of_ the Apache source tree. The
+ idea is simple: When installing Apache the configure's "make install"
+ procedure installs the Apache C header files and puts the platform-dependend
+ compiler and linker flags for building DSO files into the `apxs' program.
+ This way the user can use `apxs' to compile his Apache module sources without
+ the Apache distribution source tree and without having to fiddle with the
+ platform-dependend compiler and linker flags for DSO support.
+
+<P>To place the complete Apache core program into a DSO library (only required
+ on some of the supported platforms to force the linker to export the apache
+ core symbols -- a prerequisite for the DSO modularization) the rule
+ SHARED_CORE has to be enabled via configure's --enable-rule=SHARED_CORE
+ option (see ../INSTALL file) or by changing the Rule command in
+ Configuration.tmpl to "Rule SHARED_CORE=yes" (see ./INSTALL file). The Apache
+ core code is then placed into a DSO library named libhttpd.so. Because one
+ cannot link a DSO against static libraries, an additional executable program
+ named libhttpd.ep is created which both binds this static code and provides a
+ stub for the main() function. Finally the httpd executable program itself is
+ replaced by a bootstrapping code which automatically makes sure the Unix
+ loader is able to load and start libhttpd.ep by providing the LD_LIBRARY_PATH
+ to libhttpd.so.
+
+<H3>Supported Platforms</H3>
+
+<P>Apache's src/Configure script currently has only limited built-in knowledge
+ on how to compile DSO files because (as already mentioned) this is heavily
+ platform-dependent. Nevertheless all major Unix platforms are supported. The
+ definitive current state (May 1998) is this:
+
+<PRE>
+ Out-of-the-box supported platforms:
+ (actually tested versions in parenthesis)
+
+ o FreeBSD (2.1.5, 2.2.5, 2.2.6)
+ o OpenBSD (2.x)
+ o NetBSD (1.3.1)
+ o Linux (Debian/1.3.1, RedHat/4.2)
+ o Solaris (2.4, 2.5.1, 2.6)
+ o SunOS (4.1.3)
+ o OSF1 (4.0)
+ o IRIX (6.2)
+ o HP/UX (10.20)
+ o UnixWare (2.01, 2.1.2)
+ o AIX (3.2, 4.1.5, 4.2, 4.3)
+ o ReliantUNIX/SINIX (5.43)
+ o SVR4 (-)
+
+ Explicitly unsupported platforms:
+
+ o Ultrix: There is no dlopen-style interface under this platform.
+</PRE>
+
+
+<H3>Usage Summary</H3>
+
+<P>To give you an overview of the DSO features of Apache 1.3, here is
+ a short and concise summary:
+
+<OL>
+
+<LI>Placing the Apache core code (all the stuff which usually forms
+ the httpd binary) into a DSO libhttpd.so, an executable program
+ libhttpd.ep and a bootstrapping executable program httpd (Notice:
+ this is only required on some of the supported platforms to force
+ the linker to export the Apache core symbols, which in turn is a
+ prerequisite for the DSO modularization):
+
+<PRE>
+ o Build and install via configure (preferred):
+ $ ./configure --prefix=/path/to/install
+ --enable-rule=SHARED_CORE ...
+ $ make install
+
+ o Build and install manually:
+ - Edit src/Configuration:
+ << "Rule SHARED_CORE=default"
+ >> "Rule SHARED_CORE=yes"
+ << "EXTRA_CFLAGS= "
+ >> "EXTRA_CFLAGS= -DSHARED_CORE_DIR=\"/path/to/install/libexec\"
+ $ make
+ $ cp src/libhttpd.so* /path/to/install/libexec/
+ $ cp src/libhttpd.ep /path/to/install/libexec/
+ $ cp src/httpd /path/to/install/bin/
+</PRE>
+
+<LI>Build and install a distributed Apache module, say mod_foo.c,
+ into its own DSO mod_foo.so:
+
+<PRE>
+ o Build and install via configure (preferred):
+ $ ./configure --prefix=/path/to/install
+ --enable-shared=foo
+ $ make install
+
+ o Build and install manually:
+ - Edit src/Configuration:
+ << "AddModule modules/xxxx/mod_foo.o"
+ >> "SharedModule modules/xxxx/mod_foo.so"
+ $ make
+ $ cp src/xxxx/mod_foo.so /path/to/install/libexec
+ - Edit /path/to/install/etc/httpd.conf
+ >> "LoadModule foo_module /path/to/install/libexec/mod_foo.so"
+</PRE>
+
+<LI>Build and install a third-party Apache module, say mod_foo.c,
+ into its own DSO mod_foo.so
+
+<PRE>
+ o Build and install via configure (preferred):
+ $ ./configure --add-module=/path/to/3rdparty/mod_foo.c
+ --enable-shared=foo
+ $ make install
+
+ o Build and install manually:
+ $ cp /path/to/3rdparty/mod_foo.c /path/to/apache-1.3/src/modules/extra/
+ - Edit src/Configuration:
+ >> "SharedModule modules/extra/mod_foo.so"
+ $ make
+ $ cp src/xxxx/mod_foo.so /path/to/install/libexec
+ - Edit /path/to/install/etc/httpd.conf
+ >> "LoadModule foo_module /path/to/install/libexec/mod_foo.so"
+</PRE>
+
+<LI>Build and install a third-party Apache module, say mod_foo.c,
+ into its own DSO mod_foo.so _outside of_ the Apache source tree:
+
+<PRE>
+ o Build and install via APXS:
+ $ cd /path/to/3rdparty
+ $ apxs -c mod_foo.c
+ $ apxs -i -a -n foo mod_foo.so
+</PRE>
+
+</UL>
+
+<H3>Advantages & Disadvantages</H3>
+
+<P>The above DSO based features of Apache 1.3 have the following advantages:
+
+<UL>
+<LI> The server package is more flexible at run-time because the actual server
+ process can be assembled at run-time via LoadModule httpd.conf
+ configuration commands instead of Configuration AddModule commands at
+ build-time. For instance this way one is able to run different server
+ instances (standard & SSL version, minimalistic & powered up version
+ [mod_perl, PHP3], etc.) with only one Apache installation.
+
+<LI> The server package can be easily extended with third-party modules even
+ after installation. This is at least a great benefit for vendor package
+ maintainers who can create a Apache core package and additional packages
+ containing extensions like PHP3, mod_perl, mod_fastcgi, etc.
+
+<LI> Easier Apache module prototyping because with the DSO/APXS pair you can
+ both work outside the Apache source tree and only need an `apxs -i'
+ command followed by a `apachectl restart' to bring a new version of your
+ currently developed module into the running Apache server.
+</UL>
+
+<P>DSO has the following disadvantages:
+
+<UL>
+<LI> The DSO mechanism cannot be used on every platform because not all
+ operating systems support dynamic loading.
+
+<LI> The server is approximately 20% slower at startup time because of the
+ symbol resolving overhead the Unix loader now has to do.
+
+<LI> The server is approximately 5% slower at execution time under some
+ platforms because position independed code (PIC) sometimes needs
+ complicated assembler tricks for relative addressing which are not
+ necessarily as fast as absolute addressing.
+
+<LI> Because DSO modules cannot be linked against other DSO-based libraries
+ (ld -lfoo) on all platforms (for instance a.out-based platforms usually
+ don't provide this functionality while ELF-based platforms do) you cannot
+ use the DSO mechanism for all types of modules. Or in other words,
+ modules compiled as DSO files are restricted to only use symbols from the
+ Apache core, from the C library (libc) and all other dynamic or static
+ libraries used by the Apache core, or from static library archives
+ (libfoo.a) containing position independend code. The only chance to use
+ other code is to either make sure the Apache core itself already contains
+ a reference to it or loading the code yourself via dlopen().
+
+<LI> Under some platforms (many SVR4 systems) there is no way to force the
+ linker to export all global symbols for use in DSO's when linking the
+ Apache httpd executable program. But without the visibility of the Apache
+ core symbols no standard Apache module could be used as a DSO. The only
+ chance here is to use the SHARED_CORE feature because this way the global
+ symbols are forced to be exported. As a consequence the Apache
+ src/Configure script automatically enforces SHARED_CORE on these
+ platforms when DSO features are used in the Configuration file or on the
+ configure command line.
+</UL>
+
+<PRE>
+ Ralf S. Engelschall
+ rse@engelschall.com
+ www.engelschall.com
+</PRE>
+
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
+
+
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML><HEAD>
+<TITLE>Apache 1.3 Dynamic Shared Object (DSO) 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>Apache 1.3 Dynamic Shared Object (DSO) support</H1>
+
+<P><HR><P>
+
+<address>Originally written by Ralf S. Engelschall, April 1998</address>
+
+<H3>Background</H3>
+
+<P>On modern Unix derivatives there exists a nifty mechanism usually
+ called dynamic linking/loading of Dynamic Shared Objects (DSO) which
+ provides a way to build a piece of program code in a special format
+ for loading it at run-time into the address space of an executable
+ program.
+
+<P>This loading can usually be done in two ways: Automatically by a
+ system program called <CODE>ld.so</CODE> when an executable program
+ is started or manually from within the executing program via a
+ programmatic system interface to the Unix loader through the system
+ calls <CODE>dlopen()/dlsym()</CODE>.
+
+<P>In the first way the DSO's are usually called "shared libraries" or
+ "DSO libraries" and named <CODE>libfoo.so</CODE> or
+ <CODE>libfoo.so.1.2</CODE>. They reside in a system directory
+ (usually <CODE>/usr/lib</CODE>) and the link to the executable
+ program is established at link-time by specifying <CODE>-lfoo</CODE>
+ to the linker command. This hardcodes library references into the
+ executable program file so that at start-time the Unix loader is able
+ to locate <CODE>libfoo.so</CODE> in <CODE>/usr/lib</CODE> or in paths
+ configured via the environment variable
+ <CODE>LD_LIBRARY_PATH</CODE>. It then resolves any (yet unresolved)
+ symbols in the executable program which are available in the DSO.
+
+<P>Symbols in the executable program are usually not referenced by the
+ DSO (because it's a reuseable library of general code) and hence no
+ further resolving has to be done. The executable program has no need
+ to do anything on its own to use the symbols from the DSO because the
+ complete resolving is done by the Unix loader. (In fact, the code to
+ invoke <CODE>ld.so</CODE> is part of the run-time startup code which
+ is linked into every executable program which has been bound
+ non-static). The advantage of dynamic loading of common library code
+ is obvious: the library code needs to be stored only once, in a
+ system library like <CODE>libc.so</CODE>, saving disk space for every
+ program.
+
+<P>In the second way the DSO's are usually called "shared objects" or
+ "DSO files" and can be named with an arbitrary extension (although
+ the canonical name is <CODE>foo.so</CODE>). These files usually stay
+ inside a program-specific directory and there is no automatically
+ established link to the executable program where they are
+ used. Instead the executable program manually loads the DSO at
+ run-time into its address space via <CODE>dlopen()</CODE>. At this
+ time no resolving of symbols from the DSO for the executable program
+ is done. But instead the Unix loader automatically resolves any (yet
+ unresolved) symbols in the DSO from the set of symbols exported by
+ the executable program and its already loaded DSO libraries
+ (especially all symbols from the ubiquitous <CODE>libc.so</CODE>).
+ This way the DSO gets knowledge of the executable program's symbol
+ set as if it had been statically linked with it in the first place.
+
+<P>Finally, to take advantage of the DSO's API the executable program
+ has to resolve particular symbols from the DSO via
+ <CODE>dlsym()</CODE> for later use inside dispatch tables etc. In
+ other words: The executable program has to manually resolve every
+ symbol it needs to be able to use it. The advantage of such a
+ mechanism is that optional program parts need not be loaded (and thus
+ do not spend memory) until they are needed by the program in
+ question. When required, these program parts can be loaded
+ dynamically to extend the base program's functionality.
+
+<P>Although this DSO mechanism sounds straightforward there is at least one
+ difficult step here: The resolving of symbols from the executable program for
+ the DSO when using a DSO to extend a program (the second way). Why? Because
+ `reverse resolving' DSO symbols from the executable program's symbol set is
+ against the library design (where the library has no knowledge about the
+ programs it is used by) and is neither available under all platforms nor
+ standardized. In practice the executable program's global symbols are often
+ not re-exported and thus not available for use in a DSO. Finding a way to
+ force the linker to export all global symbols is the main problem one has to
+ solve when using DSO for extending a program at run-time.
+
+<H3>Practical Usage</H3>
+
+<P>The shared library approach is the typical one, because it is what the DSO
+ mechanism was designed for, hence it is used for nearly all types of
+ libraries the operating system provides. On the other hand using shared
+ objects for extending a program is not used by a lot of programs.
+
+<P>As of 1998 there are only a few software packages available which use the DSO
+ mechanism to actually extend their functionality at run-time: Perl 5 (via its
+ XS mechanism and the DynaLoader module), GIMP, Netscape Server, etc.
+ Starting with version 1.3, Apache joined the crew, because Apache already
+ uses a module concept to extend its functionality and internally uses a
+ dispatch-list-based approach to link external modules into the Apache core
+ functionality. So, Apache is really predestined for using DSO to load its
+ modules at run-time.
+
+<P>As of Apache 1.3, the configuration system supports two optional features for
+ taking advantage of the modular DSO approach: compilation of the Apache core
+ program into a DSO library for shared usage and compilation of the Apache
+ modules into DSO files for explicit loading at run-time.
+
+<H3>Implementation</H3>
+
+<P> The DSO support for loading individual Apache modules is based on a module
+ named mod_so.c which has to be statically compiled into the Apache core. It
+ is the only module besides http_core.c which cannot be put into a DSO itself
+ (bootstrapping!). Practically all other distributed Apache modules then can
+ then be placed into a DSO by individually enabling the DSO build for them via
+ configure's --enable-shared option (see ../INSTALL file) or by changing the
+ `AddModule' command in src/Configuration.tmpl into a `SharedModule' command
+ (see ./INSTALL file). After a module is compiled into a DSO named mod_foo.so
+ you can use mod_so's `LoadModule' command in your httpd.conf file to load
+ this module at server startup or restart.
+
+<P>To simplify this creation of DSO files for Apache modules (especially for
+ third-party modules) a new support program named `apxs' is available. It can
+ be used to build DSO based modules _outside of_ the Apache source tree. The
+ idea is simple: When installing Apache the configure's "make install"
+ procedure installs the Apache C header files and puts the platform-dependend
+ compiler and linker flags for building DSO files into the `apxs' program.
+ This way the user can use `apxs' to compile his Apache module sources without
+ the Apache distribution source tree and without having to fiddle with the
+ platform-dependend compiler and linker flags for DSO support.
+
+<P>To place the complete Apache core program into a DSO library (only required
+ on some of the supported platforms to force the linker to export the apache
+ core symbols -- a prerequisite for the DSO modularization) the rule
+ SHARED_CORE has to be enabled via configure's --enable-rule=SHARED_CORE
+ option (see ../INSTALL file) or by changing the Rule command in
+ Configuration.tmpl to "Rule SHARED_CORE=yes" (see ./INSTALL file). The Apache
+ core code is then placed into a DSO library named libhttpd.so. Because one
+ cannot link a DSO against static libraries, an additional executable program
+ named libhttpd.ep is created which both binds this static code and provides a
+ stub for the main() function. Finally the httpd executable program itself is
+ replaced by a bootstrapping code which automatically makes sure the Unix
+ loader is able to load and start libhttpd.ep by providing the LD_LIBRARY_PATH
+ to libhttpd.so.
+
+<H3>Supported Platforms</H3>
+
+<P>Apache's src/Configure script currently has only limited built-in knowledge
+ on how to compile DSO files because (as already mentioned) this is heavily
+ platform-dependent. Nevertheless all major Unix platforms are supported. The
+ definitive current state (May 1998) is this:
+
+<PRE>
+ Out-of-the-box supported platforms:
+ (actually tested versions in parenthesis)
+
+ o FreeBSD (2.1.5, 2.2.5, 2.2.6)
+ o OpenBSD (2.x)
+ o NetBSD (1.3.1)
+ o Linux (Debian/1.3.1, RedHat/4.2)
+ o Solaris (2.4, 2.5.1, 2.6)
+ o SunOS (4.1.3)
+ o OSF1 (4.0)
+ o IRIX (6.2)
+ o HP/UX (10.20)
+ o UnixWare (2.01, 2.1.2)
+ o AIX (3.2, 4.1.5, 4.2, 4.3)
+ o ReliantUNIX/SINIX (5.43)
+ o SVR4 (-)
+
+ Explicitly unsupported platforms:
+
+ o Ultrix: There is no dlopen-style interface under this platform.
+</PRE>
+
+
+<H3>Usage Summary</H3>
+
+<P>To give you an overview of the DSO features of Apache 1.3, here is
+ a short and concise summary:
+
+<OL>
+
+<LI>Placing the Apache core code (all the stuff which usually forms
+ the httpd binary) into a DSO libhttpd.so, an executable program
+ libhttpd.ep and a bootstrapping executable program httpd (Notice:
+ this is only required on some of the supported platforms to force
+ the linker to export the Apache core symbols, which in turn is a
+ prerequisite for the DSO modularization):
+
+<PRE>
+ o Build and install via configure (preferred):
+ $ ./configure --prefix=/path/to/install
+ --enable-rule=SHARED_CORE ...
+ $ make install
+
+ o Build and install manually:
+ - Edit src/Configuration:
+ << "Rule SHARED_CORE=default"
+ >> "Rule SHARED_CORE=yes"
+ << "EXTRA_CFLAGS= "
+ >> "EXTRA_CFLAGS= -DSHARED_CORE_DIR=\"/path/to/install/libexec\"
+ $ make
+ $ cp src/libhttpd.so* /path/to/install/libexec/
+ $ cp src/libhttpd.ep /path/to/install/libexec/
+ $ cp src/httpd /path/to/install/bin/
+</PRE>
+
+<LI>Build and install a distributed Apache module, say mod_foo.c,
+ into its own DSO mod_foo.so:
+
+<PRE>
+ o Build and install via configure (preferred):
+ $ ./configure --prefix=/path/to/install
+ --enable-shared=foo
+ $ make install
+
+ o Build and install manually:
+ - Edit src/Configuration:
+ << "AddModule modules/xxxx/mod_foo.o"
+ >> "SharedModule modules/xxxx/mod_foo.so"
+ $ make
+ $ cp src/xxxx/mod_foo.so /path/to/install/libexec
+ - Edit /path/to/install/etc/httpd.conf
+ >> "LoadModule foo_module /path/to/install/libexec/mod_foo.so"
+</PRE>
+
+<LI>Build and install a third-party Apache module, say mod_foo.c,
+ into its own DSO mod_foo.so
+
+<PRE>
+ o Build and install via configure (preferred):
+ $ ./configure --add-module=/path/to/3rdparty/mod_foo.c
+ --enable-shared=foo
+ $ make install
+
+ o Build and install manually:
+ $ cp /path/to/3rdparty/mod_foo.c /path/to/apache-1.3/src/modules/extra/
+ - Edit src/Configuration:
+ >> "SharedModule modules/extra/mod_foo.so"
+ $ make
+ $ cp src/xxxx/mod_foo.so /path/to/install/libexec
+ - Edit /path/to/install/etc/httpd.conf
+ >> "LoadModule foo_module /path/to/install/libexec/mod_foo.so"
+</PRE>
+
+<LI>Build and install a third-party Apache module, say mod_foo.c,
+ into its own DSO mod_foo.so _outside of_ the Apache source tree:
+
+<PRE>
+ o Build and install via APXS:
+ $ cd /path/to/3rdparty
+ $ apxs -c mod_foo.c
+ $ apxs -i -a -n foo mod_foo.so
+</PRE>
+
+</UL>
+
+<H3>Advantages & Disadvantages</H3>
+
+<P>The above DSO based features of Apache 1.3 have the following advantages:
+
+<UL>
+<LI> The server package is more flexible at run-time because the actual server
+ process can be assembled at run-time via LoadModule httpd.conf
+ configuration commands instead of Configuration AddModule commands at
+ build-time. For instance this way one is able to run different server
+ instances (standard & SSL version, minimalistic & powered up version
+ [mod_perl, PHP3], etc.) with only one Apache installation.
+
+<LI> The server package can be easily extended with third-party modules even
+ after installation. This is at least a great benefit for vendor package
+ maintainers who can create a Apache core package and additional packages
+ containing extensions like PHP3, mod_perl, mod_fastcgi, etc.
+
+<LI> Easier Apache module prototyping because with the DSO/APXS pair you can
+ both work outside the Apache source tree and only need an `apxs -i'
+ command followed by a `apachectl restart' to bring a new version of your
+ currently developed module into the running Apache server.
+</UL>
+
+<P>DSO has the following disadvantages:
+
+<UL>
+<LI> The DSO mechanism cannot be used on every platform because not all
+ operating systems support dynamic loading.
+
+<LI> The server is approximately 20% slower at startup time because of the
+ symbol resolving overhead the Unix loader now has to do.
+
+<LI> The server is approximately 5% slower at execution time under some
+ platforms because position independed code (PIC) sometimes needs
+ complicated assembler tricks for relative addressing which are not
+ necessarily as fast as absolute addressing.
+
+<LI> Because DSO modules cannot be linked against other DSO-based libraries
+ (ld -lfoo) on all platforms (for instance a.out-based platforms usually
+ don't provide this functionality while ELF-based platforms do) you cannot
+ use the DSO mechanism for all types of modules. Or in other words,
+ modules compiled as DSO files are restricted to only use symbols from the
+ Apache core, from the C library (libc) and all other dynamic or static
+ libraries used by the Apache core, or from static library archives
+ (libfoo.a) containing position independend code. The only chance to use
+ other code is to either make sure the Apache core itself already contains
+ a reference to it or loading the code yourself via dlopen().
+
+<LI> Under some platforms (many SVR4 systems) there is no way to force the
+ linker to export all global symbols for use in DSO's when linking the
+ Apache httpd executable program. But without the visibility of the Apache
+ core symbols no standard Apache module could be used as a DSO. The only
+ chance here is to use the SHARED_CORE feature because this way the global
+ symbols are forced to be exported. As a consequence the Apache
+ src/Configure script automatically enforces SHARED_CORE on these
+ platforms when DSO features are used in the Configuration file or on the
+ configure command line.
+</UL>
+
+<PRE>
+ Ralf S. Engelschall
+ rse@engelschall.com
+ www.engelschall.com
+</PRE>
+
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
+
+
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<HTML>
+<HEAD>
+<TITLE>Special Purpose Environment Variables</TITLE>
+</HEAD>
+
+<BODY>
+<!--#include virtual="header.html" -->
+<h1>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>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<HTML>
+<HEAD>
+<TITLE>Special Purpose Environment Variables</TITLE>
+</HEAD>
+
+<BODY>
+<!--#include virtual="header.html" -->
+<h1>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>
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<HTML>
-<HEAD>
-<TITLE>Access Control by URL</TITLE>
-</HEAD>
-
-<BODY>
-<IMG SRC="../../images/apache_sub.gif" ALT="">
-<H1>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 comprable to the <a
-href="../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
-neccessarily have to protect a directory (it can be an individual
-file, or a number of files), and can include wildcards. In a wildcard
-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_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
- <Limit GET>
- order deny,allow
- deny from all
- allow from .foo.com
- </Limit>
- </Location>
-</pre>
-
-<p><hr>
-
-<A HREF="../../"><IMG SRC="../../images/apache_home.gif" ALT="Home"></A>
-<A HREF="./"><IMG SRC="../../images/apache_index.gif" ALT="Index"></A>
-
-</BODY>
-</HTML>
-
+++ /dev/null
-<!--%hypertext -->
-<html><head>
-<title>Apache API notes</title>
-</head>
-<body>
-<!--/%hypertext -->
-<h1>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 recognise <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 */
-};
-</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>
-
-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>Tracking open files, etc.</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>
-<!--%hypertext -->
-</body></html>
-<!--/%hypertext -->
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache server Frequently Asked Questions</TITLE>
-</HEAD>
-
-<BODY>
-<IMG SRC="../images/apache_sub.gif" ALT="">
-<H1>Apache server Frequently Asked Questions</H1>
-
-<H2>The Questions</H2>
-<OL>
-<LI><A HREF="#what">What is Apache ?</A>
-<LI><A HREF="#why">Why was Apache created ?</A>
-<LI><A HREF="#relate">How does the Apache group relate to other servers ?</A>
-<LI><A HREF="#name">Why the name "Apache" ?</A>
-<LI><A HREF="#compatible">How compatible is Apache with my existing NCSA 1.3 setup ?</A>
-<LI><A HREF="#compare">OK, so how does Apache compare to other servers ?</A>
-<LI><A HREF="#tested">How thoroughly tested is Apache?</A>
-<LI><A HREF="#proxy">Does or will Apache act as a Proxy server?</A>
-<LI><A HREF="#future">What are the future plans for Apache ?</A>
-<LI><A HREF="#support">Who do I contact for support ?</A>
-<LI><A HREF="#more">Is there any more information on Apache ?</A>
-<LI><A HREF="#where">Where can get Apache ?</A>
-</OL>
-
-<HR>
-
-<H2>The Answers</H2>
-<OL>
-<LI><A name="what">What is Apache ?</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>Since it began, it has been completely rewritten, and includes many new
-features. Apache is, as of June 1996, the most popular WWW server on
-the Internet, according to the <a
-href="http://www.netcraft.com/Survey/">Netcraft Survey</a>.
-
-</P>
-<HR>
-<LI><A name="relate">How does the Apache group relate to other
-server efforts, such as NCSA's?</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
-entitely independent venture.
-</P>
-<HR>
-
-<LI><A name="why">Why was Apache created ?</A>
-<P>to address concerns of a group of www providers and part time httpd
-programmers, that httpd didn't behave as they wanted it
-to. Apache is an entirely volunteer effort, completely funded by its
-members, not by commercial sales.
-</P>
-
-<HR>
-
-<LI><A name="name">Why the name "Apache" ?</A>
-<P>A cute name which stuck. Apache is "<B>A PA</B>t<B>CH</B>y server". It was
- based on some existing code and a series of "patch files".
-</P>
-<HR>
-
-
-<LI><A name="compatible">How compatible is Apache with my existing NCSA 1.3
-setup ?</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>
-
-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>
-
-Friendly interaction between Apache and NCSA developers should ensure
-that fundamental feature enhancments stay consistent between the two
-servers for the foreseeable future.<p>
-
-<HR>
-
-<LI><A name="compare">OK, so how does Apache compare to other servers ?</A>
-<P>
-For an independent assessment, see <A HREF="http://www.webcompare.com/server-main.html">http://www.webcompare.com/server-main.html</A>
-</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><A name="tested">How thoroughly tested is Apache?</A>
-
-<p>Apache is run on over 100,000 Internet servers (as of July 1996). 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. When bugs do show up, we release patches and new
-versions, as soon as they are available.</a>
-
-<P>See <A HREF="../info/apache_users.html">http://www.apache.org/info/apache_users.html</A> for an incomplete list of sites running Apache.</P>
-
-<hr>
-
-<LI><A name="proxy">Does or will Apache act as a Proxy server?
-<p>Apache version 1.1
-and above will come with a proxy module. If compiled in, this will make
-Apache act as a caching-proxy server
-<p>
-<HR>
-
-<LI><A name="future">What are the future plans for Apache ?</A>
-<P><UL>
-<LI>to continue as a public domain HTTP server,
-<LI>to keep up with advances in HTTP protocol and web developments in general
-<LI>to collect suggestions for fixes/improvements from its users,
-<LI>to respond to needs of large volume providers as well as occasional users.
-</UL>
-</P><HR>
-
-<LI><A name="support">Who do I contact for support ?</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 via <A HREF="http://www.apache.org/bug_report.html">the bug report page.</A>
-Other questions should be directed to
-<A HREF="news:comp.infosystems.www.servers.unix">comp.infosystems.www.servers.unix</A>, where some of the Apache team lurk,
-in the company of many other httpd gurus who should be able
-to help.
-<p>
-Commercial support for Apache is, however, available from a number
-third parties.
-</p>
-<HR>
-
-<LI><A name="more">Is there any more information on Apache ?</A>
-<P>Indeed there is. See <A HREF="http://www.apache.org/">http://www.apache.org/</A>.
-</P>
-<HR>
-
-<LI><A name="where">Where can get Apache ?</A>
-<P>
-You can find the source for Apache at <A HREF="http://www.apache.org/">http://www.apache.org/</A>.
-</P>
-<HR>
-</OL>
-
-<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
-<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
-</BODY>
-</HTML>
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<HTML>
-<HEAD>
-<TITLE>Reading Client Input in Apache 1.2</TITLE>
-</HEAD>
-
-<BODY>
-<IMG SRC="../images/apache_sub.gif" ALT="">
-<H1>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
-furthur 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 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 neccessary properties, and
- will return either OK, or an error code. If the latter,
- the module should return that error code.
-
-<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 *defenitely* 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 neccessarily 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, and
- the module should proceed.
-
-</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>
-
-<hr>
-
-<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
-<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
-
-</BODY>
-</HTML>
+++ /dev/null
-<HTML><HEAD>
-<TITLE>Apache HTTP Server: Compatibility Notes with NCSA's Server</TITLE>
-</HEAD>
-<BODY>
-<IMG SRC="../images/apache_sub.gif" ALT="">
-<H3>Compatibility Notes with NCSA's Server</H3>
-
-<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="mailto:apache-bugs@apache.org">let us know.</a>
-
-<P>Please also check the <A HREF="known_bugs.html">known bugs</A> page.
-
-
-
-<OL>
-
-<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 accessable 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> sillyness - 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>
-
-</OL>
-
-More to come when we notice them....
-
-
-<hr>
-
-<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
-<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
-
-</BODY>
-</HTML>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<HTML>
+ <HEAD>
+ <TITLE>Apache Miscellaneous Documentation</TITLE>
+ </HEAD>
+
+ <BODY>
+ <!--#include virtual="header.html" -->
+ <H1>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/optimise 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 optimise Apache
+ performance on Digital UNIX systems
+ </DD>
+ <DT><A
+ HREF="perf.html"
+ >Performance Notes (General)</A>
+ </DT>
+ <DD>Some generic note 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>
--- /dev/null
+<html>
+<head>
+<title>Apache Performance Notes</title>
+</head>
+<body bgcolor="#ffffff" text="#000000" link="#0000ff" vlink="#000080" alink="#ff0000">
+
+<h1>Apache Performance Notes</h1>
+
+<p>Author: Dean Gaudet
+
+<h3>Introduction</h3>
+<p>Apache is a general webserver, which is designed to be correct first, and
+fast second. Even so, it's performance is quite satisfactory. Most
+sites have less than 10Mbits of outgoing bandwidth, which Apache can
+fill using only a low end Pentium-based webserver. In practice sites
+with more bandwidth require more than one machine to fill the bandwidth
+due to other constraints (such as CGI or database transaction overhead).
+For these reasons the development focus has been mostly on correctness
+and configurability.
+
+<p>Unfortunately many folks overlook these facts and cite raw performance
+numbers as if they are some indication of the quality of a web server
+product. There is a bare minimum performance that is acceptable, beyond
+that extra speed only caters to a much smaller segment of the market.
+But in order to avoid this hurdle to the acceptance of Apache in some
+markets, effort was put into Apache 1.3 to bring performance up to a
+point where the difference with other high-end webservers is minimal.
+
+<p>Finally there are the folks who just plain want to see how fast something
+can go. The author falls into this category. The rest of this document
+is dedicated to these folks who want to squeeze every last bit of
+performance out of Apache's current model, and want to understand why
+it does some things which slow it down.
+
+<p>Note that this is tailored towards Apache 1.3 on Unix. Some of it applies
+to Apache on NT. Apache on NT has not been tuned for performance yet,
+in fact it probably performs very poorly because NT performance requires
+a different programming model.
+
+<h3>Hardware and Operating System Issues</h3>
+
+<p>The single biggest hardware issue affecting webserver performance
+is RAM. A webserver should never ever have to swap, swapping increases
+the latency of each request beyond a point that users consider "fast
+enough". This causes users to hit stop and reload, further increasing
+the load. You can, and should, control the <code>MaxClients</code>
+setting so that your server does not spawn so many children it starts
+swapping.
+
+<p>Beyond that the rest is mundane: get a fast enough CPU, a fast enough
+network card, and fast enough disks, where "fast enough" is something
+that needs to be determined by experimentation.
+
+<p>Operating system choice is largely a matter of local concerns. But
+a general guideline is to always apply the latest vendor TCP/IP patches.
+HTTP serving completely breaks many of the assumptions built into Unix
+kernels up through 1994 and even 1995. Good choices include
+recent FreeBSD, and Linux.
+
+<h3>Run-Time Configuration Issues</h3>
+
+<h4>HostnameLookups</h4>
+<p>Prior to Apache 1.3, <code>HostnameLookups</code> defaulted to On.
+This adds latency
+to every request because it requires a DNS lookup to complete before
+the request is finished. In Apache 1.3 this setting defaults to Off.
+However (1.3 or later), if you use any <code>allow from domain</code> or
+<code>deny from domain</code> directives then you will pay for a
+double reverse DNS lookup (a reverse, followed by a forward to make sure
+that the reverse is not being spoofed). So for the highest performance
+avoid using these directives (it's fine to use IP addresses rather than
+domain names).
+
+<p>Note that it's possible to scope the directives, such as within
+a <code><Location /server-status></code> section. In this
+case the DNS lookups are only performed on requests matching the
+criteria. Here's an example which disables
+lookups except for .html and .cgi files:
+
+<blockquote><pre>
+HostnameLookups off
+<Files ~ "\.(html|cgi)$>
+ HostnameLookups on
+</Files>
+</pre></blockquote>
+
+But even still, if you just need DNS names
+in some CGIs you could consider doing the
+<code>gethostbyname</code> call in the specific CGIs that need it.
+
+<h4>FollowSymLinks and SymLinksIfOwnerMatch</h4>
+<p>Wherever in your URL-space you do not have an
+<code>Options FollowSymLinks</code>, or you do have an
+<code>Options SymLinksIfOwnerMatch</code> Apache will have to
+issue extra system calls to check up on symlinks. One extra call per
+filename component. For example, if you had:
+
+<blockquote><pre>
+DocumentRoot /www/htdocs
+<Directory />
+ Options SymLinksIfOwnerMatch
+</Directory>
+</pre></blockquote>
+
+and a request is made for the URI <code>/index.html</code>.
+Then Apache will perform <code>lstat(2)</code> on <code>/www</code>,
+<code>/www/htdocs</code>, and <code>/www/htdocs/index.html</code>. The
+results of these <code>lstats</code> are never cached,
+so they will occur on every single request. If you really desire the
+symlinks security checking you can do something like this:
+
+<blockquote><pre>
+DocumentRoot /www/htdocs
+<Directory />
+ Options FollowSymLinks
+</Directory>
+<Directory /www/htdocs>
+ Options -FollowSymLinks +SymLinksIfOwnerMatch
+</Directory>
+</pre></blockquote>
+
+This at least avoids the extra checks for the <code>DocumentRoot</code>
+path. Note that you'll need to add similar sections if you have any
+<code>Alias</code> or <code>RewriteRule</code> paths outside of your
+document root. For highest performance, and no symlink protection,
+set <code>FollowSymLinks</code> everywhere, and never set
+<code>SymLinksIfOwnerMatch</code>.
+
+<h4>AllowOverride</h4>
+
+<p>Wherever in your URL-space you allow overrides (typically
+<code>.htaccess</code> files) Apache will attempt to open
+<code>.htaccess</code> for each filename component. For example,
+
+<blockquote><pre>
+DocumentRoot /www/htdocs
+<Directory />
+ AllowOverride all
+</Directory>
+</pre></blockquote>
+
+and a request is made for the URI <code>/index.html</code>. Then
+Apache will attempt to open <code>/.htaccess</code>,
+<code>/www/.htaccess</code>, and <code>/www/htdocs/.htaccess</code>.
+The solutions are similar to the previous case of <code>Options
+FollowSymLinks</code>. For highest performance use
+<code>AllowOverride None</code> everywhere in your filesystem.
+
+<h4>Negotiation</h4>
+
+<p>If at all possible, avoid content-negotiation if you're really
+interested in every last ounce of performance. In practice the
+benefits of negotiation outweigh the performance penalties. There's
+one case where you can speed up the server. Instead of using
+a wildcard such as:
+
+<blockquote><pre>
+DirectoryIndex index
+</pre></blockquote>
+
+Use a complete list of options:
+
+<blockquote><pre>
+DirectoryIndex index.cgi index.pl index.shtml index.html
+</pre></blockquote>
+
+where you list the most common choice first.
+
+<h4>Process Creation</h4>
+
+<p>Prior to Apache 1.3 the <code>MinSpareServers</code>,
+<code>MaxSpareServers</code>, and <code>StartServers</code> settings
+all had drastic effects on benchmark results. In particular, Apache
+required a "ramp-up" period in order to reach a number of children
+sufficient to serve the load being applied. After the initial
+spawning of <code>StartServers</code> children, only one child per
+second would be created to satisfy the <code>MinSpareServers</code>
+setting. So a server being accessed by 100 simultaneous clients,
+using the default <code>StartServers</code> of 5 would take on
+the order 95 seconds to spawn enough children to handle the load. This
+works fine in practice on real-life servers, because they aren't restarted
+frequently. But does really poorly on benchmarks which might only run
+for ten minutes.
+
+<p>The one-per-second rule was implemented in an effort to avoid
+swamping the machine with the startup of new children. If the machine
+is busy spawning children it can't service requests. But it has such
+a drastic effect on the perceived performance of Apache that it had
+to be replaced. As of Apache 1.3,
+the code will relax the one-per-second rule. It
+will spawn one, wait a second, then spawn two, wait a second, then spawn
+four, and it will continue exponentially until it is spawning 32 children
+per second. It will stop whenever it satisfies the
+<code>MinSpareServers</code> setting.
+
+<p>This appears to be responsive enough that it's
+almost unnecessary to twiddle the <code>MinSpareServers</code>,
+<code>MaxSpareServers</code> and <code>StartServers</code> knobs. When
+more than 4 children are spawned per second, a message will be emitted
+to the <code>ErrorLog</code>. If you see a lot of these errors then
+consider tuning these settings. Use the <code>mod_status</code> output
+as a guide.
+
+<p>Related to process creation is process death induced by the
+<code>MaxRequestsPerChild</code> setting. By default this is 30, which
+is probably far too low unless your server is using a module such as
+<code>mod_perl</code> which causes children to have bloated memory
+images. If your server is serving mostly static pages then consider
+raising this value to something like 10000. The code is robust enough
+that this shouldn't be a problem.
+
+<p>When keep-alives are in use, children will be kept busy
+doing nothing waiting for more requests on the already open
+connection. The default <code>KeepAliveTimeout</code> of
+15 seconds attempts to minimize this effect. The tradeoff
+here is between network bandwidth and server resources.
+In no event should you raise this above about 60 seconds, as
+<a href="http://www.research.digital.com/wrl/techreports/abstracts/95.4.html">
+most of the benefits are lost</a>.
+
+<h3>Compile-Time Configuration Issues</h3>
+
+<h4>mod_status and Rule STATUS=yes</h4>
+
+<p>If you include <code>mod_status</code>
+and you also set <code>Rule STATUS=yes</code> when building
+Apache, then on every request Apache will perform two calls to
+<code>gettimeofday(2)</code> (or <code>times(2)</code> depending
+on your operating system), and (pre-1.3) several extra calls to
+<code>time(2)</code>. This is all done so that the status report
+contains timing indications. For highest performance, set <code>Rule
+STATUS=no</code>.
+
+<h4>accept Serialization - multiple sockets</h4>
+
+<p>This discusses a shortcoming in the Unix socket API.
+Suppose your
+web server uses multiple <code>Listen</code> statements to listen on
+either multiple ports or multiple addresses. In order to test each
+socket to see if a connection is ready Apache uses <code>select(2)</code>.
+<code>select(2)</code> indicates that a socket has <i>none</i> or
+<i>at least one</i> connection waiting on it. Apache's model includes
+multiple children, and all the idle ones test for new connections at the
+same time. A naive implementation looks something like this
+(these examples do not match the code, they're contrived for
+pedagogical purposes):
+
+<blockquote><pre>
+ for (;;) {
+ for (;;) {
+ fd_set accept_fds;
+
+ FD_ZERO (&accept_fds);
+ for (i = first_socket; i <= last_socket; ++i) {
+ FD_SET (i, &accept_fds);
+ }
+ rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
+ if (rc < 1) continue;
+ new_connection = -1;
+ for (i = first_socket; i <= last_socket; ++i) {
+ if (FD_ISSET (i, &accept_fds)) {
+ new_connection = accept (i, NULL, NULL);
+ if (new_connection != -1) break;
+ }
+ }
+ if (new_connection != -1) break;
+ }
+ process the new_connection;
+ }
+</pre></blockquote>
+
+But this naive implementation has a serious starvation problem. Recall
+that multiple children execute this loop at the same time, and so multiple
+children will block at <code>select</code> when they are in between
+requests. All those blocked children will awaken and return from
+<code>select</code> when a single request appears on any socket
+(the number of children which awaken varies depending on the operating
+system and timing issues).
+They will all then fall down into the loop and try to <code>accept</code>
+the connection. But only one will succeed (assuming there's still only
+one connection ready), the rest will be <i>blocked</i> in <code>accept</code>.
+This effectively locks those children into serving requests from that
+one socket and no other sockets, and they'll be stuck there until enough
+new requests appear on that socket to wake them all up.
+This starvation problem was first documented in
+<a href="http://bugs.apache.org/index/full/467">PR#467</a>. There
+are at least two solutions.
+
+<p>One solution is to make the sockets non-blocking. In this case the
+<code>accept</code> won't block the children, and they will be allowed
+to continue immediately. But this wastes CPU time. Suppose you have
+ten idle children in <code>select</code>, and one connection arrives.
+Then nine of those children will wake up, try to <code>accept</code> the
+connection, fail, and loop back into <code>select</code>, accomplishing
+nothing. Meanwhile none of those children are servicing requests that
+occurred on other sockets until they get back up to the <code>select</code>
+again. Overall this solution does not seem very fruitful unless you
+have as many idle CPUs (in a multiprocessor box) as you have idle children,
+not a very likely situation.
+
+<p>Another solution, the one used by Apache, is to serialize entry into
+the inner loop. The loop looks like this (differences highlighted):
+
+<blockquote><pre>
+ for (;;) {
+ <b>accept_mutex_on ();</b>
+ for (;;) {
+ fd_set accept_fds;
+
+ FD_ZERO (&accept_fds);
+ for (i = first_socket; i <= last_socket; ++i) {
+ FD_SET (i, &accept_fds);
+ }
+ rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
+ if (rc < 1) continue;
+ new_connection = -1;
+ for (i = first_socket; i <= last_socket; ++i) {
+ if (FD_ISSET (i, &accept_fds)) {
+ new_connection = accept (i, NULL, NULL);
+ if (new_connection != -1) break;
+ }
+ }
+ if (new_connection != -1) break;
+ }
+ <b>accept_mutex_off ();</b>
+ process the new_connection;
+ }
+</pre></blockquote>
+
+<a name="serialize"></a>
+The functions <code>accept_mutex_on</code> and <code>accept_mutex_off</code>
+implement a mutual exclusion semaphore. Only one child can have the
+mutex at any time. There are several choices for implementing these
+mutexes. The choice is defined in <code>src/conf.h</code> (pre-1.3) or
+<code>src/main/conf.h</code> (1.3 or later). Some architectures
+do not have any locking choice made, on these architectures it is unsafe
+to use multiple <code>Listen</code> directives.
+
+<dl>
+<dt><code>USE_FLOCK_SERIALIZED_ACCEPT</code>
+<dd>This method uses the <code>flock(2)</code> system call to lock a
+lock file (located by the <code>LockFile</code> directive).
+
+<dt><code>USE_FCNTL_SERIALIZED_ACCEPT</code>
+<dd>This method uses the <code>fcntl(2)</code> system call to lock a
+lock file (located by the <code>LockFile</code> directive).
+
+<dt><code>USE_SYSVSEM_SERIALIZED_ACCEPT</code>
+<dd>(1.3 or later) This method uses SysV-style semaphores to implement the
+mutex. Unfortunately SysV-style semaphores have some bad side-effects.
+One is that it's possible Apache will die without cleaning up the semaphore
+(see the <code>ipcs(8)</code> man page). The other is that the semaphore
+API allows for a denial of service attack by any CGIs running under the
+same uid as the webserver (i.e. all CGIs unless you use something
+like suexec or cgiwrapper). For these reasons this method is not used
+on any architecture except IRIX (where the previous two are prohibitively
+expensive on most IRIX boxes).
+
+<dt><code>USE_USLOCK_SERIALIZED_ACCEPT</code>
+<dd>(1.3 or later) This method is only available on IRIX, and uses
+<code>usconfig(2)</code> to create a mutex. While this method avoids
+the hassles of SysV-style semaphores, it is not the default for IRIX.
+This is because on single processor IRIX boxes (5.3 or 6.2) the
+uslock code is two orders of magnitude slower than the SysV-semaphore
+code. On multi-processor IRIX boxes the uslock code is an order of magnitude
+faster than the SysV-semaphore code. Kind of a messed up situation.
+So if you're using a multiprocessor IRIX box then you should rebuild your
+webserver with <code>-DUSE_USLOCK_SERIALIZED_ACCEPT</code> on the
+<code>EXTRA_CFLAGS</code>.
+
+<dt><code>USE_PTHREADS_SERIALIZED_ACCEPT</code>
+<dd>(1.3 or later) This method uses POSIX mutexes and should work on
+any architecture implementing the full POSIX threads specification,
+however appears to only work on Solaris (2.5 or later). This is the
+default for Solaris 2.5 or later.
+</dl>
+
+<p>If your system has another method of serialization which isn't in the
+above list then it may be worthwhile adding code for it (and submitting
+a patch back to Apache).
+
+<p>Another solution that has been considered but never implemented is
+to partially serialize the loop -- that is, let in a certain number
+of processes. This would only be of interest on multiprocessor boxes
+where it's possible multiple children could run simultaneously, and the
+serialization actually doesn't take advantage of the full bandwidth.
+This is a possible area of future investigation, but priority remains
+low because highly parallel web servers are not the norm.
+
+<p>Ideally you should run servers without multiple <code>Listen</code>
+statements if you want the highest performance. But read on.
+
+<h4>accept Serialization - single socket</h4>
+
+<p>The above is fine and dandy for multiple socket servers, but what
+about single socket servers? In theory they shouldn't experience
+any of these same problems because all children can just block in
+<code>accept(2)</code> until a connection arrives, and no starvation
+results. In practice this hides almost the same "spinning" behaviour
+discussed above in the non-blocking solution. The way that most TCP
+stacks are implemented, the kernel actually wakes up all processes blocked
+in <code>accept</code> when a single connection arrives. One of those
+processes gets the connection and returns to user-space, the rest spin in
+the kernel and go back to sleep when they discover there's no connection
+for them. This spinning is hidden from the user-land code, but it's
+there nonetheless. This can result in the same load-spiking wasteful
+behaviour that a non-blocking solution to the multiple sockets case can.
+
+<p>For this reason we have found that many architectures behave more
+"nicely" if we serialize even the single socket case. So this is
+actually the default in almost all cases. Crude experiments under
+Linux (2.0.30 on a dual Pentium pro 166 w/128Mb RAM) have shown that
+the serialization of the single socket case causes less than a 3%
+decrease in requests per second over unserialized single-socket.
+But unserialized single-socket showed an extra 100ms latency on
+each request. This latency is probably a wash on long haul lines,
+and only an issue on LANs. If you want to override the single socket
+serialization you can define <code>SAFE_UNSERIALIZED_ACCEPT</code>
+and then single-socket servers will not serialize at all.
+
+<h4>Lingering Close</h4>
+
+<p>As discussed in
+<a href="ftp://ds.internic.net/internet-drafts/draft-ietf-http-connection-00.txt">draft-ietf-http-connection-00.txt</a> section 8,
+in order for an HTTP server to <b>reliably</b> implement the protocol
+it needs to shutdown each direction of the communication independently
+(recall that a TCP connection is bi-directional, each half is independent
+of the other). This fact is often overlooked by other servers, but
+is correctly implemented in Apache as of 1.2.
+
+<p>When this feature was added to Apache it caused a flurry of
+problems on various versions of Unix because of a shortsightedness.
+The TCP specification does not state that the FIN_WAIT_2 state has a
+timeout, but it doesn't prohibit it. On systems without the timeout,
+Apache 1.2 induces many sockets stuck forever in the FIN_WAIT_2 state.
+In many cases this can be avoided by simply upgrading to the latest
+TCP/IP patches supplied by the vendor, in cases where the vendor has
+never released patches (i.e. SunOS4 -- although folks with a source
+license can patch it themselves) we have decided to disable this feature.
+
+<p>There are two ways of accomplishing this. One is the
+socket option <code>SO_LINGER</code>. But as fate would have it,
+this has never been implemented properly in most TCP/IP stacks. Even
+on those stacks with a proper implementation (i.e. Linux 2.0.31) this
+method proves to be more expensive (cputime) than the next solution.
+
+<p>For the most part, Apache implements this in a function called
+<code>lingering_close</code> (in <code>http_main.c</code>). The
+function looks roughly like this:
+
+<blockquote><pre>
+ void lingering_close (int s)
+ {
+ char junk_buffer[2048];
+
+ /* shutdown the sending side */
+ shutdown (s, 1);
+
+ signal (SIGALRM, lingering_death);
+ alarm (30);
+
+ for (;;) {
+ select (s for reading, 2 second timeout);
+ if (error) break;
+ if (s is ready for reading) {
+ read (s, junk_buffer, sizeof (junk_buffer));
+ /* just toss away whatever is here */
+ }
+ }
+
+ close (s);
+ }
+</pre></blockquote>
+
+This naturally adds some expense at the end of a connection, but it
+is required for a reliable implementation. As HTTP/1.1 becomes more
+prevalent, and all connections are persistent, this expense will be
+amortized over more requests. If you want to play with fire and
+disable this feature you can define <code>NO_LINGCLOSE</code>, but
+this is not recommended at all. In particular, as HTTP/1.1 pipelined
+persistent connections come into use <code>lingering_close</code>
+is an absolute necessity (and
+<a href="http://www.w3.org/Protocols/HTTP/Performance/Pipeline.html">
+pipelined connections are faster</a>, so you
+want to support them).
+
+<h4>Scoreboard File</h4>
+
+<p>Apache's parent and children communicate with each other through
+something called the scoreboard. Ideally this should be implemented
+in shared memory. For those operating systems that we either have
+access to, or have been given detailed ports for, it typically is
+implemented using shared memory. The rest default to using an
+on-disk file. The on-disk file is not only slow, but it is unreliable
+(and less featured). Peruse the <code>src/main/conf.h</code> file
+for your architecture and look for either <code>HAVE_MMAP</code> or
+<code>HAVE_SHMGET</code>. Defining one of those two enables the
+supplied shared memory code. If your system has another type of
+shared memory then edit the file <code>src/main/http_main.c</code> and
+add the hooks necessary to use it in Apache. (Send us back a patch
+too please.)
+
+<p>Historical note: The Linux port of Apache didn't start to use
+shared memory until version 1.2 of Apache. This oversight resulted
+in really poor and unreliable behaviour of earlier versions of Apache
+on Linux.
+
+<h4><code>DYNAMIC_MODULE_LIMIT</code></h4>
+
+<p>If you have no intention of using dynamically loaded modules
+(you probably don't if you're reading this and tuning your
+server for every last ounce of performance) then you should add
+<code>-DDYNAMIC_MODULE_LIMIT=0</code> when building your server.
+This will save RAM that's allocated only for supporting dynamically
+loaded modules.
+
+<h3>Appendix: Detailed Analysis of a Trace</h3>
+
+Here is a system call trace of Apache 1.3 running on Linux. The run-time
+configuration file is essentially the default plus:
+
+<blockquote><pre>
+<Directory />
+ AllowOverride none
+ Options FollowSymLinks
+</Directory>
+</pre></blockquote>
+
+The file being requested is a static 6K file of no particular content.
+Traces of non-static requests or requests with content negotiation
+look wildly different (and quite ugly in some cases). First the
+entire trace, then we'll examine details. (This was generated by
+the <code>strace</code> program, other similar programs include
+<code>truss</code>, <code>ktrace</code>, and <code>par</code>.)
+
+<blockquote><pre>
+accept(15, {sin_family=AF_INET, sin_port=htons(22283), sin_addr=inet_addr("127.0.0.1")}, [16]) = 3
+flock(18, LOCK_UN) = 0
+sigaction(SIGUSR1, {SIG_IGN}, {0x8059954, [], SA_INTERRUPT}) = 0
+getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0
+setsockopt(3, IPPROTO_TCP1, [1], 4) = 0
+read(3, "GET /6k HTTP/1.0\r\nUser-Agent: "..., 4096) = 60
+sigaction(SIGUSR1, {SIG_IGN}, {SIG_IGN}) = 0
+time(NULL) = 873959960
+gettimeofday({873959960, 404935}, NULL) = 0
+stat("/home/dgaudet/ap/apachen/htdocs/6k", {st_mode=S_IFREG|0644, st_size=6144, ...}) = 0
+open("/home/dgaudet/ap/apachen/htdocs/6k", O_RDONLY) = 4
+mmap(0, 6144, PROT_READ, MAP_PRIVATE, 4, 0) = 0x400ee000
+writev(3, [{"HTTP/1.1 200 OK\r\nDate: Thu, 11"..., 245}, {"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 6144}], 2) = 6389
+close(4) = 0
+time(NULL) = 873959960
+write(17, "127.0.0.1 - - [10/Sep/1997:23:39"..., 71) = 71
+gettimeofday({873959960, 417742}, NULL) = 0
+times({tms_utime=5, tms_stime=0, tms_cutime=0, tms_cstime=0}) = 446747
+shutdown(3, 1 /* send */) = 0
+oldselect(4, [3], NULL, [3], {2, 0}) = 1 (in [3], left {2, 0})
+read(3, "", 2048) = 0
+close(3) = 0
+sigaction(SIGUSR1, {0x8059954, [], SA_INTERRUPT}, {SIG_IGN}) = 0
+munmap(0x400ee000, 6144) = 0
+flock(18, LOCK_EX) = 0
+</pre></blockquote>
+
+<p>Notice the accept serialization:
+
+<blockquote><pre>
+flock(18, LOCK_UN) = 0
+...
+flock(18, LOCK_EX) = 0
+</pre></blockquote>
+
+These two calls can be removed by defining
+<code>SAFE_UNSERIALIZED_ACCEPT</code> as described earlier.
+
+<p>Notice the <code>SIGUSR1</code> manipulation:
+
+<blockquote><pre>
+sigaction(SIGUSR1, {SIG_IGN}, {0x8059954, [], SA_INTERRUPT}) = 0
+...
+sigaction(SIGUSR1, {SIG_IGN}, {SIG_IGN}) = 0
+...
+sigaction(SIGUSR1, {0x8059954, [], SA_INTERRUPT}, {SIG_IGN}) = 0
+</pre></blockquote>
+
+This is caused by the implementation of graceful restarts. When the
+parent receives a <code>SIGUSR1</code> it sends a <code>SIGUSR1</code>
+to all of its children (and it also increments a "generation counter"
+in shared memory). Any children that are idle (between connections)
+will immediately die
+off when they receive the signal. Any children that are in keep-alive
+connections, but are in between requests will die off immediately. But
+any children that have a connection and are still waiting for the first
+request will not die off immediately.
+
+<p>To see why this is necessary, consider how a browser reacts to a closed
+connection. If the connection was a keep-alive connection and the request
+being serviced was not the first request then the browser will quietly
+reissue the request on a new connection. It has to do this because the
+server is always free to close a keep-alive connection in between requests
+(i.e. due to a timeout or because of a maximum number of requests).
+But, if the connection is closed before the first response has been
+received the typical browser will display a "document contains no data"
+dialogue (or a broken image icon). This is done on the assumption that
+the server is broken in some way (or maybe too overloaded to respond
+at all). So Apache tries to avoid ever deliberately closing the connection
+before it has sent a single response. This is the cause of those
+<code>SIGUSR1</code> manipulations.
+
+<p>Note that it is theoretically possible to eliminate all three of
+these calls. But in rough tests the gain proved to be almost unnoticeable.
+
+<p>In order to implement virtual hosts, Apache needs to know the
+local socket address used to accept the connection:
+
+<blockquote><pre>
+getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0
+</pre></blockquote>
+
+It is possible to eliminate this call in many situations (such as when
+there are no virtual hosts, or when <code>Listen</code> directives are
+used which do not have wildcard addresses). But no effort has yet been
+made to do these optimizations.
+
+<p>Apache turns off the Nagle algorithm:
+
+<blockquote><pre>
+setsockopt(3, IPPROTO_TCP1, [1], 4) = 0
+</pre></blockquote>
+
+because of problems described in
+<a href="http://www.isi.edu/~johnh/PAPERS/Heidemann97a.html">a
+paper by John Heidemann</a>.
+
+<p>Notice the two <code>time</code> calls:
+
+<blockquote><pre>
+time(NULL) = 873959960
+...
+time(NULL) = 873959960
+</pre></blockquote>
+
+One of these occurs at the beginning of the request, and the other occurs
+as a result of writing the log. At least one of these is required to
+properly implement the HTTP protocol. The second occurs because the
+Common Log Format dictates that the log record include a timestamp of the
+end of the request. A custom logging module could eliminate one of the
+calls.
+
+<p>As described earlier, <code>Rule STATUS=yes</code> causes two
+<code>gettimeofday</code> calls and a call to <code>times</code>:
+
+<blockquote><pre>
+gettimeofday({873959960, 404935}, NULL) = 0
+...
+gettimeofday({873959960, 417742}, NULL) = 0
+times({tms_utime=5, tms_stime=0, tms_cutime=0, tms_cstime=0}) = 446747
+</pre></blockquote>
+
+These can be removed by either removing <code>mod_status</code> or
+setting <code>Rule STATUS=no</code>.
+
+<p>It might seem odd to call <code>stat</code>:
+
+<blockquote><pre>
+stat("/home/dgaudet/ap/apachen/htdocs/6k", {st_mode=S_IFREG|0644, st_size=6144, ...}) = 0
+</pre></blockquote>
+
+This is part of the algorithm which calculates the
+<code>PATH_INFO</code> for use by CGIs. In fact if the request had been
+for the URI <code>/cgi-bin/printenv/foobar</code> then there would be
+two calls to <code>stat</code>. The first for
+<code>/home/dgaudet/ap/apachen/cgi-bin/printenv/foobar</code>
+which does not exist, and the second for
+<code>/home/dgaudet/ap/apachen/cgi-bin/printenv</code>, which does exist.
+Regardless, at least one <code>stat</code> call is necessary when
+serving static files because the file size and modification times are
+used to generate HTTP headers (such as <code>Content-Length</code>,
+<code>Last-Modified</code>) and implement protocol features (such
+as <code>If-Modified-Since</code>). A somewhat more clever server
+could avoid the <code>stat</code> when serving non-static files,
+however doing so in Apache is very difficult given the modular structure.
+
+<p>All static files are served using <code>mmap</code>:
+
+<blockquote><pre>
+mmap(0, 6144, PROT_READ, MAP_PRIVATE, 4, 0) = 0x400ee000
+...
+munmap(0x400ee000, 6144) = 0
+</pre></blockquote>
+
+On some architectures it's slower to <code>mmap</code> small
+files than it is to simply <code>read</code> them. The define
+<code>MMAP_THRESHOLD</code> can be set to the minimum size required before
+using <code>mmap</code>. By default it's set to 0 (except on SunOS4
+where experimentation has shown 8192 to be a better value). Using a
+tool such as
+<a href="http://reality.sgi.com/lm_engr/lmbench/lmbench.html">lmbench</a>
+you can determine the optimal setting for your
+environment. It may even be the case that <code>mmap</code> isn't used
+on your architecture, if so then defining <code>USE_MMAP_FILES</code>
+might work (if it works then report back to us).
+
+
+<p>Apache does its best to avoid copying bytes around in memory. The
+first write of any request typically is turned into a <code>writev</code>
+which combines both the headers and the first hunk of data:
+
+<blockquote><pre>
+writev(3, [{"HTTP/1.1 200 OK\r\nDate: Thu, 11"..., 245}, {"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 6144}], 2) = 6389
+</pre></blockquote>
+
+When doing HTTP/1.1 chunked encoding Apache will generate up to four
+element <code>writev</code>s. The goal is to push the byte copying
+into the kernel, where it typically has to happen anyhow (to assemble
+network packets). On testing, various Unixes (BSDI 2.x, Solaris 2.5,
+Linux 2.0.31+) properly combine the elements into network packets.
+Pre-2.0.31 Linux will not combine, and will create a packet for
+each element, so upgrading is a good idea. Defining <code>NO_WRITEV</code>
+will disable this combining, but result in very poor chunked encoding
+performance.
+
+<p>The log write:
+
+<blockquote><pre>
+write(17, "127.0.0.1 - - [10/Sep/1997:23:39"..., 71) = 71
+</pre></blockquote>
+
+can be deferred by defining <code>BUFFERED_LOGS</code>. In this case
+up to <code>PIPE_BUF</code> bytes (a POSIX defined constant) of log entries
+are buffered before writing. At no time does it split a log entry
+across a <code>PIPE_BUF</code> boundary because those writes may not
+be atomic. (i.e. entries from multiple children could become mixed together).
+The code does it best to flush this buffer when a child dies.
+
+<p>The lingering close code causes four system calls:
+
+<blockquote><pre>
+shutdown(3, 1 /* send */) = 0
+oldselect(4, [3], NULL, [3], {2, 0}) = 1 (in [3], left {2, 0})
+read(3, "", 2048) = 0
+close(3) = 0
+</pre></blockquote>
+
+which were described earlier.
+
+<p>Let's apply some of these optimizations:
+<code>-DSAFE_UNSERIALIZED_ACCEPT -DBUFFERED_LOGS</code> and
+<code>Rule STATUS=no</code>. Here's the final trace:
+
+<blockquote><pre>
+accept(15, {sin_family=AF_INET, sin_port=htons(22286), sin_addr=inet_addr("127.0.0.1")}, [16]) = 3
+sigaction(SIGUSR1, {SIG_IGN}, {0x8058c98, [], SA_INTERRUPT}) = 0
+getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0
+setsockopt(3, IPPROTO_TCP1, [1], 4) = 0
+read(3, "GET /6k HTTP/1.0\r\nUser-Agent: "..., 4096) = 60
+sigaction(SIGUSR1, {SIG_IGN}, {SIG_IGN}) = 0
+time(NULL) = 873961916
+stat("/home/dgaudet/ap/apachen/htdocs/6k", {st_mode=S_IFREG|0644, st_size=6144, ...}) = 0
+open("/home/dgaudet/ap/apachen/htdocs/6k", O_RDONLY) = 4
+mmap(0, 6144, PROT_READ, MAP_PRIVATE, 4, 0) = 0x400e3000
+writev(3, [{"HTTP/1.1 200 OK\r\nDate: Thu, 11"..., 245}, {"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 6144}], 2) = 6389
+close(4) = 0
+time(NULL) = 873961916
+shutdown(3, 1 /* send */) = 0
+oldselect(4, [3], NULL, [3], {2, 0}) = 1 (in [3], left {2, 0})
+read(3, "", 2048) = 0
+close(3) = 0
+sigaction(SIGUSR1, {0x8058c98, [], SA_INTERRUPT}, {SIG_IGN}) = 0
+munmap(0x400e3000, 6144) = 0
+</pre></blockquote>
+
+That's 19 system calls, of which 4 remain relatively easy to remove,
+but don't seem worth the effort.
+
+<h3>Appendix: The Pre-Forking Model</h3>
+
+<p>Apache (on Unix) is a <i>pre-forking</i> model server. The
+<i>parent</i> process is responsible only for forking <i>child</i>
+processes, it does not serve any requests or service any network
+sockets. The child processes actually process connections, they serve
+multiple connections (one at a time) before dying.
+The parent spawns new or kills off old
+children in response to changes in the load on the server (it does so
+by monitoring a scoreboard which the children keep up to date).
+
+<p>This model for servers offers a robustness that other models do
+not. In particular, the parent code is very simple, and with a high
+degree of confidence the parent will continue to do its job without
+error. The children are complex, and when you add in third party
+code via modules, you risk segmentation faults and other forms of
+corruption. Even should such a thing happen, it only affects one
+connection and the server continues serving requests. The parent
+quickly replaces the dead child.
+
+<p>Pre-forking is also very portable across dialects of Unix.
+Historically this has been an important goal for Apache, and it continues
+to remain so.
+
+<p>The pre-forking model comes under criticism for various
+performance aspects. Of particular concern are the overhead
+of forking a process, the overhead of context switches between
+processes, and the memory overhead of having multiple processes.
+Furthermore it does not offer as many opportunities for data-caching
+between requests (such as a pool of <code>mmapped</code> files).
+Various other models exist and extensive analysis can be found in the
+<a href="http://www.cs.wustl.edu/~jxh/research/research.html"> papers
+of the JAWS project</a>. In practice all of these costs vary drastically
+depending on the operating system.
+
+<p>Apache's core code is already multithread aware, and Apache version
+1.3 is multithreaded on NT. There have been at least two other experimental
+implementations of threaded Apache (one using the 1.3 code base on DCE,
+and one using a custom user-level threads package and the 1.0 code base,
+neither are available publically). Part of our redesign for version 2.0
+of Apache will include abstractions of the server model so that we
+can continue to support the pre-forking model, and also support various
+threaded models.
+
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+ <HEAD>
+ <TITLE>Definitions of terms used to describe 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">Terms Used to Describe Apache Directives</H1>
+
+ <P>
+ Each Apache configuration directive is described using a common format
+ that looks like this:
+ </P>
+ <DL>
+ <DD><A
+ HREF="#Syntax"
+ REL="Help"
+ ><STRONG>Syntax:</STRONG></A> <EM>directive-name</EM> <EM>some args</EM>
+ <BR>
+ <A
+ HREF="#Default"
+ REL="Help"
+ ><STRONG>Default:</STRONG></A>
+ <SAMP><EM>directive-name default-value</EM></SAMP>
+ <BR>
+ <A
+ HREF="#Context"
+ REL="Help"
+ ><STRONG>Context:</STRONG></A> <EM>context-list</EM>
+ <BR>
+ <A
+ HREF="#Override"
+ REL="Help"
+ ><STRONG>Override:</STRONG></A> <EM>override</EM>
+ <BR>
+ <A
+ HREF="#Status"
+ REL="Help"
+ ><STRONG>Status:</STRONG></A> <EM>status</EM>
+ <BR>
+ <A
+ HREF="#Module"
+ REL="Help"
+ ><STRONG>Module:</STRONG></A> <EM>module-name</EM>
+ <BR>
+ <A
+ HREF="#Compatibility"
+ REL="Help"
+ ><STRONG>Compatibility:</STRONG></A> <EM>compatibility notes</EM>
+ </DD>
+ </DL>
+ <P>
+ Each of the directive's attributes, complete with possible values
+ where possible, are described in this document.
+ </P>
+
+ <H2>Directive Terms</H2>
+ <UL>
+ <LI><A HREF="#Syntax">Syntax</A>
+ </LI>
+ <LI><A HREF="#Default">Default</A>
+ </LI>
+ <LI><A HREF="#Context">Context</A>
+ </LI>
+ <LI><A HREF="#Override">Override</A>
+ </LI>
+ <LI><A HREF="#Status">Status</A>
+ </LI>
+ <LI><A HREF="#Module">Module</A>
+ </LI>
+ <LI><A HREF="#Compatibility">Compatibility</A>
+ </LI>
+ </UL>
+
+ <HR>
+ <H2><A NAME="Syntax">Syntax</A></H2>
+ <P>
+ This indicates the format of the directive as it would appear in a
+ configuration file. This syntax is extremely directive-specific, so
+ refer to the text of the directive's description for details.
+ </P>
+
+ <HR>
+ <H2><A NAME="Default">Default</A></H2>
+ <P>
+ If the directive has a default value (<EM>i.e.</EM>, if you omit it
+ from your configuration entirely, the Apache Web server will behave as
+ though you set it to a particular value), it is described here. If
+ there is no default value, this section should say
+ "<EM>None</EM>".
+ </P>
+
+ <HR>
+ <H2><A NAME="Context">Context</A></H2>
+ <P>
+ This indicates where in the server's configuration files the directive
+ is legal. It's a comma-separated list of one or more of the following
+ values:
+ </P>
+ <DL>
+ <DT><STRONG>server config</STRONG>
+ </DT>
+ <DD>This means that the directive may be used in the server
+ configuration files (<EM>e.g.</EM>, <SAMP>httpd.conf</SAMP>,
+ <SAMP>srm.conf</SAMP>, and <SAMP>access.conf</SAMP>), but
+ <STRONG>not</STRONG> within any <SAMP><VirtualHost></SAMP> or
+ <Directory> containers. It is not allowed in
+ <SAMP>.htaccess</SAMP> files at all.
+ <P>
+ </P>
+ </DD>
+ <DT><STRONG>virtual host</STRONG>
+ </DT>
+ <DD>This context means that the directive may appear inside
+ <SAMP><VirtualHost></SAMP> containers in the server
+ configuration files.
+ <P>
+ </P>
+ </DD>
+ <DT><STRONG>directory</STRONG>
+ </DT>
+ <DD>A directive marked as being valid in this context may be used
+ inside <SAMP><Directory></SAMP> containers in the server
+ configuration files.
+ <P>
+ </P>
+ </DD>
+ <DT><STRONG>.htaccess</STRONG>
+ </DT>
+ <DD>If a directive is valid in this context, it means that it can
+ appear inside <EM>per</EM>-directory <SAMP>.htaccess</SAMP> files.
+ It may not be processed, though depending upon the
+ <A
+ HREF="#Override"
+ REL="Help"
+ >overrides</A>
+ currently active.
+ <P>
+ </P>
+ </DD>
+ </DL>
+ <P>
+ The directive is <EM>only</EM> allowed within the designated context;
+ if you try to use it elsewhere, you'll get a configuration error that
+ will either prevent the server from handling requests in that context
+ correctly, or will keep the server from operating at all --
+ <EM>i.e.</EM>, the server won't even start.
+ </P>
+ <P>
+ The valid locations for the directive are actually the result of a
+ Boolean OR of all of the listed contexts. In other words, a directive
+ that is marked as being valid in "<SAMP>server config,
+ .htaccess</SAMP>" can be used in the <SAMP>httpd.conf</SAMP> file
+ and in <SAMP>.htaccess</SAMP> files, but not within any
+ <Directory> or <VirtualHost> containers.
+ </P>
+
+ <HR>
+ <H2><A NAME="Override">Override</A></H2>
+ <P>
+ This directive attribute indicates which configuration override must
+ be active in order for the directive to be processed when it appears
+ in a <SAMP>.htaccess</SAMP> file. If the directive's
+ <A
+ HREF="#Context"
+ REL="Help"
+ >context</A>
+ doesn't permit it to appear in <SAMP>.htaccess</SAMP> files, this
+ attribute should say "<EM>Not applicable</EM>".
+ </P>
+ <P>
+ Overrides are activated by the
+ <A
+ HREF="core.html#allowoverrides"
+ REL="Help"
+ ><SAMP>AllowOverrides</SAMP></A>
+ directive, and apply to a particular scope (such as a directory) and
+ all descendants, unless further modified by other
+ <SAMP>AllowOverrides</SAMP> directives at lower levels. The
+ documentation for that directive also lists the possible override
+ names available.
+ </P>
+
+ <HR>
+ <H2><A NAME="Status">Status</A></H2>
+ <P>
+ This indicates how tightly bound into the Apache Web server the
+ directive is; in other words, you may need to recompile the server
+ with an enhanced set of modules in order to gain access to the
+ directive and its functionality. Possible values for this attribute
+ are:
+ </P>
+ <DL>
+ <DT><STRONG>Core</STRONG>
+ </DT>
+ <DD>If a directive is listed as having "Core" status, that
+ means it is part of the innermost portions of the Apache Web server,
+ and is always available.
+ <P>
+ </P>
+ </DD>
+ <DT><STRONG>Base</STRONG>
+ </DT>
+ <DD>A directive labeled as having "Base" status is
+ supported by one of the standard Apache modules which is compiled
+ into the server by default, and is therefore normally available
+ unless you've taken steps to remove the module from your configuration.
+ <P>
+ </P>
+ </DD>
+ <DT><STRONG>Extension</STRONG>
+ </DT>
+ <DD>A directive with "Extension" status is provided by one
+ of the modules included with the Apache server kit, but the module
+ isn't normally compiled into the server. To enable the directive
+ and its functionality, you will need to change the server build
+ configuration files and re-compile Apache.
+ <P>
+ </P>
+ </DD>
+ <DT><STRONG>Experimental</STRONG>
+ </DT>
+ <DD>"Experimental" status indicates that the directive is
+ available as part of the Apache kit, but you're on your own if you
+ try to use it. The directive is being documented for completeness,
+ and is not necessarily supported. The module which provides the
+ directive may or may not be compiled in by default; check the top of
+ the page which describes the directive and its module to see if it
+ remarks on the availability.
+ <P>
+ </P>
+ </DD>
+ </DL>
+
+ <HR>
+ <H2><A NAME="Module">Module</A></H2>
+ <P>
+ This quite simply lists the name of the source module which defines
+ the directive.
+ </P>
+
+ <HR>
+ <H2><A NAME="Compatibility">Compatibility</A></H2>
+ <P>
+ If the directive wasn't part of the original Apache version 1
+ distribution, the version in which it was introduced should be listed
+ here. If the directive has the same name as one from the NCSA HTTPd
+ server, any inconsistencies in behaviour between the two should also
+ be mentioned. Otherwise, this attribute should say "<EM>No
+ compatibility issues.</EM>"
+ </P>
+<!--#include virtual="footer.html" -->
+ </BODY>
+</HTML>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+ <HEAD>
+ <TITLE>Definitions of terms used to describe 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">Terms Used to Describe Apache Directives</H1>
+
+ <P>
+ Each Apache configuration directive is described using a common format
+ that looks like this:
+ </P>
+ <DL>
+ <DD><A
+ HREF="#Syntax"
+ REL="Help"
+ ><STRONG>Syntax:</STRONG></A> <EM>directive-name</EM> <EM>some args</EM>
+ <BR>
+ <A
+ HREF="#Default"
+ REL="Help"
+ ><STRONG>Default:</STRONG></A>
+ <SAMP><EM>directive-name default-value</EM></SAMP>
+ <BR>
+ <A
+ HREF="#Context"
+ REL="Help"
+ ><STRONG>Context:</STRONG></A> <EM>context-list</EM>
+ <BR>
+ <A
+ HREF="#Override"
+ REL="Help"
+ ><STRONG>Override:</STRONG></A> <EM>override</EM>
+ <BR>
+ <A
+ HREF="#Status"
+ REL="Help"
+ ><STRONG>Status:</STRONG></A> <EM>status</EM>
+ <BR>
+ <A
+ HREF="#Module"
+ REL="Help"
+ ><STRONG>Module:</STRONG></A> <EM>module-name</EM>
+ <BR>
+ <A
+ HREF="#Compatibility"
+ REL="Help"
+ ><STRONG>Compatibility:</STRONG></A> <EM>compatibility notes</EM>
+ </DD>
+ </DL>
+ <P>
+ Each of the directive's attributes, complete with possible values
+ where possible, are described in this document.
+ </P>
+
+ <H2>Directive Terms</H2>
+ <UL>
+ <LI><A HREF="#Syntax">Syntax</A>
+ </LI>
+ <LI><A HREF="#Default">Default</A>
+ </LI>
+ <LI><A HREF="#Context">Context</A>
+ </LI>
+ <LI><A HREF="#Override">Override</A>
+ </LI>
+ <LI><A HREF="#Status">Status</A>
+ </LI>
+ <LI><A HREF="#Module">Module</A>
+ </LI>
+ <LI><A HREF="#Compatibility">Compatibility</A>
+ </LI>
+ </UL>
+
+ <HR>
+ <H2><A NAME="Syntax">Syntax</A></H2>
+ <P>
+ This indicates the format of the directive as it would appear in a
+ configuration file. This syntax is extremely directive-specific, so
+ refer to the text of the directive's description for details.
+ </P>
+
+ <HR>
+ <H2><A NAME="Default">Default</A></H2>
+ <P>
+ If the directive has a default value (<EM>i.e.</EM>, if you omit it
+ from your configuration entirely, the Apache Web server will behave as
+ though you set it to a particular value), it is described here. If
+ there is no default value, this section should say
+ "<EM>None</EM>".
+ </P>
+
+ <HR>
+ <H2><A NAME="Context">Context</A></H2>
+ <P>
+ This indicates where in the server's configuration files the directive
+ is legal. It's a comma-separated list of one or more of the following
+ values:
+ </P>
+ <DL>
+ <DT><STRONG>server config</STRONG>
+ </DT>
+ <DD>This means that the directive may be used in the server
+ configuration files (<EM>e.g.</EM>, <SAMP>httpd.conf</SAMP>,
+ <SAMP>srm.conf</SAMP>, and <SAMP>access.conf</SAMP>), but
+ <STRONG>not</STRONG> within any <SAMP><VirtualHost></SAMP> or
+ <Directory> containers. It is not allowed in
+ <SAMP>.htaccess</SAMP> files at all.
+ <P>
+ </P>
+ </DD>
+ <DT><STRONG>virtual host</STRONG>
+ </DT>
+ <DD>This context means that the directive may appear inside
+ <SAMP><VirtualHost></SAMP> containers in the server
+ configuration files.
+ <P>
+ </P>
+ </DD>
+ <DT><STRONG>directory</STRONG>
+ </DT>
+ <DD>A directive marked as being valid in this context may be used
+ inside <SAMP><Directory></SAMP> containers in the server
+ configuration files.
+ <P>
+ </P>
+ </DD>
+ <DT><STRONG>.htaccess</STRONG>
+ </DT>
+ <DD>If a directive is valid in this context, it means that it can
+ appear inside <EM>per</EM>-directory <SAMP>.htaccess</SAMP> files.
+ It may not be processed, though depending upon the
+ <A
+ HREF="#Override"
+ REL="Help"
+ >overrides</A>
+ currently active.
+ <P>
+ </P>
+ </DD>
+ </DL>
+ <P>
+ The directive is <EM>only</EM> allowed within the designated context;
+ if you try to use it elsewhere, you'll get a configuration error that
+ will either prevent the server from handling requests in that context
+ correctly, or will keep the server from operating at all --
+ <EM>i.e.</EM>, the server won't even start.
+ </P>
+ <P>
+ The valid locations for the directive are actually the result of a
+ Boolean OR of all of the listed contexts. In other words, a directive
+ that is marked as being valid in "<SAMP>server config,
+ .htaccess</SAMP>" can be used in the <SAMP>httpd.conf</SAMP> file
+ and in <SAMP>.htaccess</SAMP> files, but not within any
+ <Directory> or <VirtualHost> containers.
+ </P>
+
+ <HR>
+ <H2><A NAME="Override">Override</A></H2>
+ <P>
+ This directive attribute indicates which configuration override must
+ be active in order for the directive to be processed when it appears
+ in a <SAMP>.htaccess</SAMP> file. If the directive's
+ <A
+ HREF="#Context"
+ REL="Help"
+ >context</A>
+ doesn't permit it to appear in <SAMP>.htaccess</SAMP> files, this
+ attribute should say "<EM>Not applicable</EM>".
+ </P>
+ <P>
+ Overrides are activated by the
+ <A
+ HREF="core.html#allowoverrides"
+ REL="Help"
+ ><SAMP>AllowOverrides</SAMP></A>
+ directive, and apply to a particular scope (such as a directory) and
+ all descendants, unless further modified by other
+ <SAMP>AllowOverrides</SAMP> directives at lower levels. The
+ documentation for that directive also lists the possible override
+ names available.
+ </P>
+
+ <HR>
+ <H2><A NAME="Status">Status</A></H2>
+ <P>
+ This indicates how tightly bound into the Apache Web server the
+ directive is; in other words, you may need to recompile the server
+ with an enhanced set of modules in order to gain access to the
+ directive and its functionality. Possible values for this attribute
+ are:
+ </P>
+ <DL>
+ <DT><STRONG>Core</STRONG>
+ </DT>
+ <DD>If a directive is listed as having "Core" status, that
+ means it is part of the innermost portions of the Apache Web server,
+ and is always available.
+ <P>
+ </P>
+ </DD>
+ <DT><STRONG>Base</STRONG>
+ </DT>
+ <DD>A directive labeled as having "Base" status is
+ supported by one of the standard Apache modules which is compiled
+ into the server by default, and is therefore normally available
+ unless you've taken steps to remove the module from your configuration.
+ <P>
+ </P>
+ </DD>
+ <DT><STRONG>Extension</STRONG>
+ </DT>
+ <DD>A directive with "Extension" status is provided by one
+ of the modules included with the Apache server kit, but the module
+ isn't normally compiled into the server. To enable the directive
+ and its functionality, you will need to change the server build
+ configuration files and re-compile Apache.
+ <P>
+ </P>
+ </DD>
+ <DT><STRONG>Experimental</STRONG>
+ </DT>
+ <DD>"Experimental" status indicates that the directive is
+ available as part of the Apache kit, but you're on your own if you
+ try to use it. The directive is being documented for completeness,
+ and is not necessarily supported. The module which provides the
+ directive may or may not be compiled in by default; check the top of
+ the page which describes the directive and its module to see if it
+ remarks on the availability.
+ <P>
+ </P>
+ </DD>
+ </DL>
+
+ <HR>
+ <H2><A NAME="Module">Module</A></H2>
+ <P>
+ This quite simply lists the name of the source module which defines
+ the directive.
+ </P>
+
+ <HR>
+ <H2><A NAME="Compatibility">Compatibility</A></H2>
+ <P>
+ If the directive wasn't part of the original Apache version 1
+ distribution, the version in which it was introduced should be listed
+ here. If the directive has the same name as one from the NCSA HTTPd
+ server, any inconsistencies in behaviour between the two should also
+ be mentioned. Otherwise, this attribute should say "<EM>No
+ compatibility issues.</EM>"
+ </P>
+<!--#include virtual="footer.html" -->
+ </BODY>
+</HTML>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<HTML>
+<HEAD>
+<TITLE>Apache directives</TITLE>
+</HEAD>
+
+<BODY>
+<!--#include virtual="header.html" -->
+<H1>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#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="mod_mime.html#addtype">AddType</A>
+<li><A HREF="mod_alias.html#alias">Alias</A>
+<li><A HREF="mod_log_agent.html#agentlog">AgentLog</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#LogEmail">Anonymous_LogEmail</A>
+<li><A HREF="mod_auth_anon.html#VerifyEmail">Anonymous_VerifyEmail</A>
+<li><A HREF="mod_auth_anon.html#NoUser">Anonymous_NoUser</A>
+<li><A HREF="mod_auth_anon.html#Authorative">Anonymous_Authorative</A>
+<li><A HREF="mod_digest.html#authdigestfile">AuthDigestFile</A>
+<li><A HREF="mod_auth_dbm.html#authdbgroupfile">AuthDBGroupFile</A>
+<li><A HREF="mod_auth_dbm.html#authdbuserfile">AuthDBUserFile</A>
+<li><A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A>
+<li><A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A>
+<li><A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A>
+<li><A HREF="mod_auth.html#authuserfile">AuthUserFile</A>
+<li><A HREF="core.html#authname">AuthName</A>
+<li><A HREF="core.html#authtype">AuthType</A>
+<li><A HREF="core.html#bindaddress">BindAdress</A>
+<li><A HREF="mod_proxy.html#cachedefaultexpire">CacheDefaultExpire</A>
+<li><A HREF="mod_proxy.html#cachegcinterval">CacheGcInterval</A>
+<li><A HREF="mod_proxy.html#cachelastmodfied">CacheLastModified</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="mod_cookies.html#cookielog">CookieLog</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_dir.html#fancyindexing">FancyIndexing</A>
+<li><A HREF="mod_mime.html#forcetype">ForceType</A>
+<li><A HREF="core.html#group">Group</A>
+<li><A HREF="mod_dir.html#headername">HeaderName</A>
+<li><A HREF="core.html#identitycheck">IdentityCheck</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#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#proxyrequests">ProxyRequests</A>
+<li><A HREF="mod_proxy.html#proxyremote">ProxyRemote</A>
+<li><A HREF="mod_proxy.html#proxypass">ProxyPass</A>
+<li><A HREF="mod_dir.html#readmename">ReadmeName</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="mod_alias.html#redirect">Redirect</A>
+<li><A HREF="core.html#resourceconfig">ResourceConfig</A>
+<li><A HREF="mod_actions.html#script">Script</A>
+<li><A HREF="mod_alias.html#scriptalias">ScriptAlias</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="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>
+++ /dev/null
-<!--%hypertext -->
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache module mod_access</TITLE>
-</HEAD>
-
-<BODY>
-<IMG SRC="../images/apache_sub.gif" ALT="">
-<!--/%hypertext -->
-<H1>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.
-
-<!--%hypertext -->
-<menu>
-<li><A HREF="#allow">allow</A>
-<li><A HREF="#deny">deny</A>
-<li><A HREF="#order">order</A>
-</menu>
-<hr>
-<!--/%hypertext -->
-
-<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; it is
-typically used within a <A HREF="core.html#limit"><Limit></A> section.
-<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> 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; it is
-typically used within a <A HREF="core.html#limit"><Limit></A> section.
-<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><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.
-<dt>allow,deny
-<dd>the allow directives are evaluated before the deny directives.
-<dt>mutual-failure
-<dd>Only those hosts which appear on the allow list and do not appear
-on the deny list are granted access.
-</dl>
-
-Example:
-<blockquote><code>
-order deny,allow
-deny from all
-allow from .ncsa.uiuc.edu
-</code></blockquote>
-Hosts in the ncsa.uiuc.edu domain are allowed access; all other hosts are
-denied access.
-
-<!--%hypertext -->
-<hr>
-
-<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
-<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
-
-</BODY>
-</HTML>
-<!--/%hypertext -->
+++ /dev/null
-<!--%hypertext -->
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache module mod_auth</TITLE>
-</HEAD>
-
-<BODY>
-<IMG SRC="../images/apache_sub.gif" ALT="">
-<!--/%hypertext -->
-<H1>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.
-
-<!--%hypertext -->
-<menu>
-<li><A HREF="#authgroupfile">AuthGroupFile</A>
-<li><A HREF="#authuserfile">AuthUserFile</A>
-</menu>
-<hr>
-<!--/%hypertext -->
-
-<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 webserver; 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 behaviour 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 webserver; 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>
-
-<!--%hypertext -->
-<hr>
-<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
-<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
-
-</BODY>
-</HTML>
-<!--/%hypertext -->
+++ /dev/null
-<html>
-<head>
-<title>4.1a Module mod_auth_anon.c</title>
-</head>
-<body>
-<h1>4.1a Module mod_auth_anon.</h1>
-
-This module is contained in the <code>mod_auth_anon.c</code> file and
-is compiled in by default. It is only available in Apache 1.1 and
-later.
-<p>
-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="#FullDescription">Full description</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>
-
-<hr><h2><a name="FullDescription">Full description of all tokens</a></h2>
-<dl>
-
-<code><dt>
-Anonymous < Space separated list >
-</code></dt><dd>
- 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'.
-</dd>
-
-<code><dt>
-Anonymous_LogEmail < on | off >
-</code></dt><dd>
- When set 'on', the default, the 'password' entered (which hopefully
- contains a sensible email address) is logged in the httpd-log file.
-</dd>
-
-<code><dt>
-Anonymous_VerifyEmail < on | off >
-</code></dt><dd>
- When set 'on', the default is 'off', the 'password' entered is
- checked for at least one '@' and a '.' to encourage users to enter
- valid email addressses (see the above <code>Auth_LogEmail</code>.
-</dd>
-
-<code><dt>
-Anonymous_NoUserID < on | off >
-</code></dt><dd>
- When set 'on', the default is 'off', 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.
-</dd>
-
-<code><dt>
-<a name="Authorative">Anonymous_Authorative < on | off ></a>
-</code></dt><dd>
- Default is 'off'. 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.
-</dd>
-
-</dl>
-
-
-<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>
-Excerp 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' tokes allowed. more docs. Added Authorative
- 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, icecreams 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>
-
-</body>
-</html>
-
+++ /dev/null
-<!--%hypertext -->
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache module mod_auth_db</TITLE>
-</HEAD>
-
-<BODY>
-<IMG SRC="../../images/apache_sub.gif" ALT="">
-<!--/%hypertext -->
-<H1>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.
-
-<!--%hypertext -->
-<menu>
-<li><A HREF="#authdbgroupfile">AuthDBGroupFile</A>
-<li><A HREF="#authdbuserfile">AuthDBUserFile</A>
-</menu>
-<hr>
-<!--/%hypertext -->
-
-<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 webserver; 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 Crypted 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 webserver; 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>
-
-<!--%hypertext -->
-<hr>
-<A HREF="../../"><IMG SRC="../../images/apache_home.gif" ALT="Home"></A>
-<A HREF="./"><IMG SRC="../../images/apache_index.gif" ALT="Index"></A>
-
-</BODY>
-</HTML>
-<!--/%hypertext -->
+++ /dev/null
-<!--%hypertext -->
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache module mod_auth_dbm</TITLE>
-</HEAD>
-
-<BODY>
-<IMG SRC="../images/apache_sub.gif" ALT="">
-<!--/%hypertext -->
-<H1>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. See the <A HREF="auth_dbm.html">DBM user documentation</a>.
-
-<!--%hypertext -->
-<menu>
-<li><A HREF="#authdbmgroupfile">AuthDBMGroupFile</A>
-<li><A HREF="#authdbmuserfile">AuthDBMUserFile</A>
-</menu>
-<hr>
-<!--/%hypertext -->
-
-<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 webserver; 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 Crypted 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 webserver; 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>
-
-<!--%hypertext -->
-<hr>
-<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
-<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
-
-</BODY>
-</HTML>
-<!--/%hypertext -->
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<HTML>
+ <HEAD>
+ <TITLE>Apache module mod_example</TITLE>
+ </HEAD>
+ <BODY>
+ <!--#include virtual="header.html" -->
+ <H1>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>
+ <A NAME="example">
+ <H2>Example</H2>
+ </A>
+ <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>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<HTML>
+ <HEAD>
+ <TITLE>Apache module mod_expires</TITLE>
+ </HEAD>
+ <BODY>
+ <!--#include virtual="header.html" -->
+ <H1>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>
+ <A NAME="expiresactive">
+ <H2>ExpiresActive directive</H2>
+ </A>
+ <!--%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>
+ <A NAME="expiresbytype">
+ <H2>ExpiresByType directive</H2>
+ </A>
+ <!--%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>
+ <A NAME="expiresdefault">
+ <H2>ExpiresDefault directive</H2>
+ </A>
+ <!--%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>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<HTML>
+<HEAD>
+<TITLE>Apache module mod_headers</TITLE>
+</HEAD>
+
+<BODY>
+<!--#include virtual="header.html" -->
+<h1>Headers Module</h1>
+
+The optional headers module allows for the customisation 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>
+
+<A name="header"><h2>Header</h2></A>
+<strong>Sytnax:</strong> Header [ set | append | add ] <em>header</em> <em>value</em><br>
+<strong>Sytnax:</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 unforseen 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>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+<TITLE>Apache module mod_isapi</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_isapi</h1>
+
+<p>This module is contained in the <code>mod_isapi.c</code> file, and is
+ compiled in by default. It provides support for ISAPI Extensions when
+ running under Microsoft Windows. Any document with a handler of
+ <code>isapi-isa</code> will be processed by this module.
+
+<h2>Purpose</h2>
+
+<p>This module implements the <a
+ href="http://www.microsoft.com/win32dev/apiext/isapimrg.htm">ISAPI
+ Extension</a> API. It allows Internet Server Applications (i.e., ISAPI
+ Extensions) to be used with Apache for Windows.
+
+<h2>Usage</h2>
+
+<p>In the server configuration file, add a handler called
+ <code>isapi-isa</code>, and map it to files with a <code>.DLL</code>
+ extension. In other words:</p>
+<pre>
+ AddHandler isapi-isa dll
+</pre>
+<p>Now simply place the ISA DLLs into your document root, and they will
+ be loaded when their URLs are accessed.</p>
+
+<p>ISAPI Extensions are governed by the same restrictions as CGI
+ scripts. That is, <code>Options ExecCGI</code> must be active in the
+ directory that contains the ISA.</p>
+
+<h2>Notes</h2>
+
+<p>Apache's ISAPI implementation conforms to all of the ISAPI 2.0
+ specification, except for the "Microsoft-specific" extensions dealing
+ with ascynchronous I/O. Apache's I/O model does not allow asynchronous
+ reading and writing in a manner that the ISAPI could access. If an ISA
+ tries to access async I/O, a message will be place in the error log,
+ to help with debugging.
+
+<p>Some servers, like Microsoft IIS, load the ISA into the server, and
+ keep it loaded until memory usage is too high, and it is
+ unloaded. Apache currently loads and unloads the ISA for each
+ request. This is inefficient, but Apache's request model makes this
+ method the only method that currently works. A future release may use
+ a more effective loading method.
+
+<p>Apache 1.3a1 currently limits POST and PUT input to 48k per
+ request. This is to work around a problem with the ISAPI implementation
+ that could result in a denial of service attack. It is expected that
+ support for larger uploads will be added soon.
+
+<p>Also, remember that while Apache supports ISAPI Extensions, it does
+ not support ISAPI Filters. Support for filters may be added at a later
+ date, but no support is planned at this time.</p>
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
+++ /dev/null
-<!--%hypertext -->
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache module mod_log_agent</TITLE>
-</HEAD>
-
-<BODY>
-<IMG SRC="../images/apache_sub.gif" ALT="">
-<!--/%hypertext -->
-<H1>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.
-
-<!--%hypertext -->
-<ul>
-<li><A HREF="#agentlog">AgentLog</A>
-</ul>
-<hr>
-<!--/%hypertext -->
-
-<A name="agentlog"><h2>AgentLog</h2></A>
-<!--%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>
-
-This directive is provided for compatibility with NCSA 1.4.<p>
-<!--%hypertext -->
-<hr>
-
-<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
-<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
-
-</BODY>
-</HTML>
-<!--/%hypertext -->
+++ /dev/null
-<!--%hypertext -->
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache module mod_log_referer</TITLE>
-</HEAD>
-
-<BODY>
-<IMG SRC="../images/apache_sub.gif" ALT="">
-<!--/%hypertext -->
-<H1>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.
-
-<!--%hypertext -->
-<h2>Directives</h2>
-<ul>
-<li><A HREF="#refererignore">RefererIgnore</A>
-<li><A HREF="#refererlog">RefererLog</A>
-</ul>
-<hr>
-<!--/%hypertext -->
-
-<A name="refererignore"><h2>RefererIgnore</h2></A>
-<!--%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>
-
-
-<A name="refererlog"><h2>RefererLog</h2></A>
-<!--%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>
-
-This directive is provided for compatibility with NCSA 1.4.<p>
-<!--%hypertext -->
-<hr>
-<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
-<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
-
-</BODY>
-</HTML>
-<!--/%hypertext -->
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+ <HEAD>
+ <TITLE>Apache module mod_mime_magic</TITLE>
+ </HEAD>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+ <BODY
+ BGCOLOR="#FFFFFF"
+ TEXT="#000000"
+ LINK="#0000FF"
+ VLINK="#000080"
+ ALINK="#FF0000"
+ >
+ <h1 align="CENTER">Module mod_mime_magic</h1>
+
+ This module is an optional extension to the Apache HTTPD server.
+ The current version can be obtained from
+ <a href="http://www.employees.org/~ikluft/apache/mod_mime_magic/">
+ http://www.employees.org/~ikluft/apache/mod_mime_magic/</a>.
+
+ <h2>Summary</h2>
+
+ This module is derived from a free version of the <code>file(1)</code>
+ command for Unix,
+ which uses "magic numbers" and other hints from a file's contents to
+ figure out what the contents are.
+ In the case of this module,
+ it tries to figure out the MIME type of the file.
+ <p>
+ This module is only active if the magic file exists and
+ was successfully opened at server-configuration time.
+ The magic file can be named by the
+ <A HREF="#mimemagicfile"><code>MimeMagicFile</code></a>
+ directive or defaults to conf/magic.
+ <p>
+ The contents of the file are plain ASCII text in 4-5 columns.
+ Blank lines are allowed but ignored.
+ Commented lines use a hash mark "#".
+ The remaining lines are parsed for the following columns:
+ <table border=1>
+ <tr valign=top>
+ <th>Column</th>
+ <th>Description</th>
+ </tr>
+ <tr valign=top>
+ <td>1</td>
+ <td>byte number to begin checking from
+ <br>
+ ">" indicates a dependency upon the previous non-">" line</td>
+ </tr><tr valign=top>
+ <td>2</td>
+ <td>type of data to match
+ <table border=1>
+ <tr><td>byte</td><td>single character</td></tr>
+ <tr><td>short</td><td>machine-order 16-bit integer</td></tr>
+ <tr><td>long</td><td>machine-order 32-bit integer</td></tr>
+ <tr><td>string</td><td>arbitrary-length string</td></tr>
+ <tr><td>date</td><td>long integer date
+ (seconds since Unix epoch/1970)</td></tr>
+ <tr><td>beshort</td><td>big-endian 16-bit integer</td></tr>
+ <tr><td>belong</td><td>big-endian 32-bit integer</td></tr>
+ <tr><td>bedate</td><td>big-endian 32-bit integer date</td></tr>
+ <tr><td>leshort</td><td>little-endian 16-bit integer</td></tr>
+ <tr><td>lelong</td><td>little-endian 32-bit integer</td></tr>
+ <tr><td>ledate</td><td>little-endian 32-bit integer date</td></tr>
+ </table>
+ </td>
+ </tr><tr valign=top>
+ <td>3</td>
+ <td>contents of data to match</td>
+ </tr><tr valign=top>
+ <td>4</td>
+ <td>MIME type if matched</td>
+ </tr><tr valign=top>
+ <td>5</td>
+ <td>MIME encoding if matched (optional)</td>
+ </tr>
+ </table>
+
+ <p>
+ For example, the following magic file lines
+ would recognize some audio formats.
+
+<pre>
+# Sun/NeXT audio data
+0 string .snd
+>12 belong 1 audio/basic
+>12 belong 2 audio/basic
+>12 belong 3 audio/basic
+>12 belong 4 audio/basic
+>12 belong 5 audio/basic
+>12 belong 6 audio/basic
+>12 belong 7 audio/basic
+>12 belong 23 audio/x-adpcm
+</pre>
+
+ Or these would recognize the difference between "*.doc" files containing
+ Microsoft Word or FrameMaker documents. (These are incompatible file
+ formats which use the same file suffix.)
+
+<pre>
+# Frame
+0 string \<MakerFile application/x-frame
+0 string \<MIFFile application/x-frame
+0 string \<MakerDictionary application/x-frame
+0 string \<MakerScreenFon application/x-frame
+0 string \<MML application/x-frame
+0 string \<Book application/x-frame
+0 string \<Maker application/x-frame
+
+# MS-Word
+0 string \376\067\0\043 application/msword
+0 string \320\317\021\340\241\261 application/msword
+0 string \333\245-\0\0\0 application/msword
+</pre>
+
+ An optional MIME encoding can be included as a fifth column.
+ For example, this can recognize gzipped files and set the encoding
+ for them.
+
+<pre>
+# gzip (GNU zip, not to be confused with [Info-ZIP/PKWARE] zip archiver)
+0 string \037\213 application/octet-stream x-gzip
+</pre>
+
+ <h3>Performance Issues</h3>
+
+ This module is not for every system. If your system is barely keeping
+ up with its load or if you're performing a web server benchmark,
+ you may not want to enable this because the processing is not free.
+ <p>
+ However, an effort was made to improve the performance of the original
+ file(1) code to make it fit in a busy web server.
+ It was designed for a server where there are thousands of users who
+ publish their own documents.
+ This is probably very common on intranets.
+ Many times, it's helpful
+ if the server can make more intelligent decisions about a file's
+ contents than the file name allows
+ ...even if just to reduce the "why doesn't my page work" calls
+ when users improperly name their own files.
+ You have to decide if the extra work suits your environment.
+ <p>
+ When compiling an Apache server, this module should be at or near the
+ top of the list of modules in the Configuration file. The modules are
+ listed in increasing priority so that will mean this one is used only
+ as a last resort, just like it was designed to.
+
+ <h2>Directives</h2>
+ <p>
+ <UL>
+ <LI><A HREF="#mimemagicfile">MimeMagicFile</A>
+ </LI>
+ </UL>
+ </P>
+ <HR>
+ <H2><A NAME="mimemagicfile">
+ MimeMagicFile
+ </A></H2>
+ <P>
+ <STRONG>Syntax:</STRONG> MimeMagicFile <em>magic-file-name</em>
+ <BR>
+ <STRONG>Default:</STRONG> conf/magic
+ <BR>
+ <STRONG>Context:</STRONG> server config, virtual host
+ <BR>
+ <STRONG>Status:</STRONG> Extension
+ <BR>
+ <STRONG>Module:</STRONG> mod_mime_magic
+ <p>
+
+ The MimeMagicFile directive can be used to change the location of the
+ magic file from its default location at <code>conf/magic</code>.
+ Non-rooted paths are relative to the ServerRoot.
+ <p>
+ <HR>
+
+ <h2><a name="notes">Notes</a></h2>
+
+ Patches and suggestions for mod_mime_magic should be sent to
+ Ian Kluft <ikluft<!--- comment inserted to discourage spam --->@cisco.com>.
+ Note that enhancements are done on a volunteer basis so no timetable can
+ be committed for any particular request.
+ Obviously, patches are given much higher priority over plain requests.
+ <p>
+ The following notes apply to the mod_mime_magic module and are
+ included here for compliance with contributors' copyright restrictions
+ that require their acknowledgement.
+
+<pre>
+/*
+ * mod_mime_magic: MIME type lookup via file magic numbers
+ * Copyright (c) 1996-1997 Cisco Systems, Inc.
+ *
+ * This software was submitted by Cisco Systems to the Apache Group in July
+ * 1997. Future revisions and derivatives of this source code must
+ * acknowledge Cisco Systems as the original contributor of this module.
+ * All other licensing and usage conditions are those of the Apache Group.
+ *
+ * Some of this code is derived from the free version of the file command
+ * originally posted to comp.sources.unix. Copyright info for that program
+ * is included below as required.
+ * ---------------------------------------------------------------------------
+ * - Copyright (c) Ian F. Darwin, 1987. Written by Ian F. Darwin.
+ *
+ * This software is not subject to any license of the American Telephone and
+ * Telegraph Company or of the Regents of the University of California.
+ *
+ * Permission is granted to anyone to use this software for any purpose on any
+ * computer system, and to alter it and redistribute it freely, subject to
+ * the following restrictions:
+ *
+ * 1. The author is not responsible for the consequences of use of this
+ * software, no matter how awful, even if they arise from flaws in it.
+ *
+ * 2. The origin of this software must not be misrepresented, either by
+ * explicit claim or by omission. Since few users ever read sources, credits
+ * must appear in the documentation.
+ *
+ * 3. Altered versions must be plainly marked as such, and must not be
+ * misrepresented as being the original software. Since few users ever read
+ * sources, credits must appear in the documentation.
+ *
+ * 4. This notice may not be removed or altered.
+ * -------------------------------------------------------------------------
+ *
+ * For complicance with Mr Darwin's terms: this has been very significantly
+ * modified from the free "file" command.
+ * - all-in-one file for compilation convenience when moving from one
+ * version of Apache to the next.
+ * - Memory allocation is done through the Apache API's pool structure.
+ * - All functions have had necessary Apache API request or server
+ * structures passed to them where necessary to call other Apache API
+ * routines. (i.e. usually for logging, files, or memory allocation in
+ * itself or a called function.)
+ * - struct magic has been converted from an array to a single-ended linked
+ * list because it only grows one record at a time, it's only accessed
+ * sequentially, and the Apache API has no equivalent of realloc().
+ * - Functions have been changed to get their parameters from the server
+ * configuration instead of globals. (It should be reentrant now but has
+ * not been tested in a threaded environment.)
+ * - Places where it used to print results to stdout now saves them in a
+ * list where they're used to set the MIME type in the Apache request
+ * record.
+ * - Command-line flags have been removed since they will never be used here.
+ *
+ */
+</pre>
+
+ </BODY>
+</HTML>
--- /dev/null
+<!--%hypertext -->
+<!-- mod_rewrite.html -->
+<!-- Documentation for the mod_rewrite Apache module -->
+<html>
+<head>
+<title>Apache module mod_rewrite</title>
+</head>
+
+<body>
+<!--#include virtual="header.html" -->
+<h1>Module mod_rewrite (Version 2.3)</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 rewrittten 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 <b>The Apache Group</b>, All rights reserved.<br>
+Copyright © 1996 <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/~rse"><tt>http://www.engelschall.com/~rse</i></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>
+<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 runable 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> filehandles. 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 ore 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>
+</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 an additional format: <tt>%{ENV:variable}</tt> where
+<i>variable</i> can be any Unix environment variable. This is looked-up
+via <tt>getenv()</tt> from the Apache server process.
+
+<p>
+<li>There is one more additional 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>''.
+</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.
+</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></strong>' (force <a name="redirect"><b>r</b>edirect</a>)<br>
+ Prefix <em>Substitution</em>
+ with <code>http://thishost/</code> (which makes the new URL a URI) to
+ force a external redirection. 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>
+ <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!</b>
+<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>
+<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>
+</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>
\ No newline at end of file
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+ <HEAD>
+ <TITLE>Apache module mod_setenvif</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_setenvif</H1>
+ <P>
+ This module is contained in the <SAMP>mod_setenvif.c</SAMP> file, and
+ <STRONG>is</STRONG> compiled in by default. It provides for
+ the ability to set environment variables based upon attributes of the
+ request.
+ </P>
+ <H2>Summary</H2>
+ <P>
+ The <SAMP>mod_setenvif</SAMP> module allows you to set environment
+ variables according to whether different aspects of the request match
+ regular expressions you specify. These envariables can be used by
+ other parts of the server to make decisions about actions to be taken.
+ </P>
+ <H2>Directives</H2>
+ <UL>
+ <LI><A HREF="#BrowserMatch">BrowserMatch</A>
+ </LI>
+ <LI><A HREF="#BrowserMatchNoCase">BrowserMatchNoCase</A>
+ </LI>
+ <LI><A HREF="#SetEnvIf">SetEnvIf</A>
+ </LI>
+ <LI><A HREF="#SetEnvIfNoCase">SetEnvIfNoCase</A>
+ </LI>
+ </UL>
+
+ <HR> <!-- the HR is part of the directive description -->
+ <H2><A NAME="BrowserMatch">The <SAMP>BrowserMatch</SAMP> Directive</A></H2>
+ <P>
+ <STRONG>Syntax:</STRONG> BrowserMatch <EM>regex envar[=value] [...]</EM>
+ <BR>
+ <STRONG>Default:</STRONG> <EM>none</EM>
+ <BR>
+ <STRONG>Context:</STRONG> server config
+ <BR>
+ <STRONG>Override:</STRONG> <EM>none</EM>
+ <BR>
+ <STRONG>Status:</STRONG> Base
+ <BR>
+ <STRONG>Module:</STRONG> mod_setenvif
+ <BR>
+ <STRONG>Compatibility:</STRONG> Apache 1.2 and above
+ </P>
+ <P>
+ The BrowserMatch directive defines environment variables based on the
+ <SAMP>User-Agent</SAMP> HTTP request header field. The first argument
+ should be a POSIX.2 extended regular expression (similar to an
+ <SAMP>egrep</SAMP>-style regex). The rest of the arguments give the
+ names of variables to set, and optionally values to which they should
+ be set. These take the form of
+ </P>
+ <OL>
+ <LI><SAMP><EM>varname</EM></SAMP>, or
+ </LI>
+ <LI><SAMP>!<EM>varname</EM></SAMP>, or
+ </LI>
+ <LI><SAMP><EM>varname</EM>=<EM>value</EM></SAMP>
+ </LI>
+ </OL>
+ <P>
+ In the first form, the value will be set to "1". The second
+ will remove the given variable if already defined, and the third will
+ set the variable to the value given by <SAMP><EM>value</EM></SAMP>. If a
+ <SAMP>User-Agent</SAMP> string matches more than one entry, they will
+ be merged. Entries are processed in the order in which they appear,
+ and later entries can override earlier ones.
+ </P>
+ <P>
+ For example:
+ </P>
+ <PRE>
+ BrowserMatch ^Mozilla forms jpeg=yes browser=netscape
+ BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
+ BrowserMatch MSIE !javascript
+ </PRE>
+ <P>
+ Note that the regular expression string is
+ <STRONG>case-sensitive</STRONG>. For cane-INsensitive matching, see
+ the
+ <A
+ HREF="#BrowserMatchNoCase"
+ ><SAMP>BrowserMatchNoCase</SAMP></A>
+ directive.
+ </P>
+ <P>
+ The <SAMP>BrowserMatch</SAMP> and <SAMP>BrowserMatchNoCase</SAMP>
+ directives are special cases of the
+ <A
+ HREF="#SetEnvIf"
+ ><SAMP>SetEnvIf</SAMP></A>
+ and
+ <A
+ HREF="#SetEnvIfNoCase"
+ ><SAMP>SetEnvIfNoCase</SAMP></A>
+ directives. The following two lines have the same effect:
+ </P>
+ <PRE>
+ BrowserMatchNoCase Robot is_a_robot
+ SetEnvIfNoCase User-Agent Robot is_a_robot
+ </PRE>
+
+ <HR> <!-- the HR is part of the directive description -->
+ <H2>
+ <A NAME="BrowserMatchNoCase">
+ The <SAMP>BrowserMatchNoCase</SAMP> Directive
+ </A>
+ </H2>
+ <P>
+ <STRONG>Syntax:</STRONG> BrowserMatchNoCase <EM>regex envar[=value] [...]</EM>
+ <BR>
+ <STRONG>Default:</STRONG> <EM>none</EM>
+ <BR>
+ <STRONG>Context:</STRONG> server config
+ <BR>
+ <STRONG>Override:</STRONG> <EM>none</EM>
+ <BR>
+ <STRONG>Status:</STRONG> Base
+ <BR>
+ <STRONG>Module:</STRONG> mod_setenvif
+ <BR>
+ <STRONG>Compatibility:</STRONG> Apache 1.2 and above
+ </P>
+ <P>
+ The <SAMP>BrowserMatchNoCase</SAMP> directive is semantically identical to
+ the
+ <A
+ HREF="#BrowserMatch"
+ ><SAMP>BrowserMatch</SAMP></A>
+ directive. However, it provides for case-insensitive matching. For
+ example:
+ </P>
+ <PRE>
+ BrowserMatchNoCase mac platform=macintosh
+ BrowserMatchNoCase win platform=windows
+ </PRE>
+ <P>
+ The <SAMP>BrowserMatch</SAMP> and <SAMP>BrowserMatchNoCase</SAMP>
+ directives are special cases of the
+ <A
+ HREF="#SetEnvIf"
+ ><SAMP>SetEnvIf</SAMP></A>
+ and
+ <A
+ HREF="#SetEnvIfNoCase"
+ ><SAMP>SetEnvIfNoCase</SAMP></A>
+ directives. The following two lines have the same effect:
+ </P>
+ <PRE>
+ BrowserMatchNoCase Robot is_a_robot
+ SetEnvIfNoCase User-Agent Robot is_a_robot
+ </PRE>
+
+ <HR> <!-- the HR is part of the directive description -->
+ <H2>
+ <A NAME="SetEnvIf">
+ The <SAMP>SetEnvIf</SAMP> Directive
+ </A>
+ </H2>
+ <P>
+ <STRONG>Syntax:</STRONG> SetEnvIf <EM> attribute regex envar[=value] [...]</EM>
+ <BR>
+ <STRONG>Default:</STRONG> <EM>none</EM>
+ <BR>
+ <STRONG>Context:</STRONG> server config
+ <BR>
+ <STRONG>Override:</STRONG> <EM>none</EM>
+ <BR>
+ <STRONG>Status:</STRONG> Base
+ <BR>
+ <STRONG>Module:</STRONG> mod_setenvif
+ <BR>
+ <STRONG>Compatibility:</STRONG> Apache 1.3 and above
+ </P>
+ <P>
+ The <SAMP>SetEnvIf</SAMP> directive defines environment variables
+ based on attributes of the request. These attributes can be the
+ values of various HTTP request header fields (see
+ <A
+ HREF="http://ds.internic.net/rfc/rfc2068.txt"
+ >RFC2068</A>
+ for more information about these), or of other aspects of the request,
+ including the following:
+ </P>
+ <UL>
+ <LI><SAMP>Remote_Host</SAMP> - the hostname (if available) of the
+ client making the request
+ </LI>
+ <LI><SAMP>Remote_Addr</SAMP> - the IP address of the client making
+ the request
+ </LI>
+ <LI><SAMP>Remote_User</SAMP> - the authenticated username (if
+ available)
+ </LI>
+ <LI><SAMP>Request_Method</SAMP> - the name of the method being used
+ (<SAMP>GET</SAMP>, <SAMP>POST</SAMP>, <EM>et cetera</EM>)
+ </LI>
+ <LI><SAMP>Request_URI</SAMP> - the portion of the URL following the
+ scheme and host portion
+ </LI>
+ </UL>
+ <P>
+ Some of the more commonly used request header field names include
+ <SAMP>Host</SAMP>, <SAMP>User-Agent</SAMP>, and <SAMP>Referer</SAMP>.
+ </P>
+ <P>
+ Example:
+ </P>
+ <PRE>
+ SetEnvIf Request_URI "\.(gif)|(jpg)|(xbm)$" object_is_image
+ SetEnvIf Referer www\.mydomain\.com intra_site_referral
+ </PRE>
+ <P>
+ The first will set the envariable <SAMP>object_is_image</SAMP> if the
+ request was for an image file, and the second sets
+ <SAMP>intra_site_referral</SAMP> if the referring page was somewhere
+ on the <SAMP>www.mydomain.com</SAMP> Web site.
+ </P>
+
+ <HR> <!-- the HR is part of the directive description -->
+ <H2>
+ <A NAME="SetEnvIfNoCase">
+ The <SAMP>SetEnvIfNoCase</SAMP> Directive
+ </A>
+ </H2>
+ <P>
+ <STRONG>Syntax:</STRONG> SetEnvIfNoCase
+ <EM> attribute regex envar[=value] [...]</EM>
+ <BR>
+ <STRONG>Default:</STRONG> <EM>none</EM>
+ <BR>
+ <STRONG>Context:</STRONG> server config
+ <BR>
+ <STRONG>Override:</STRONG> <EM>none</EM>
+ <BR>
+ <STRONG>Status:</STRONG> Base
+ <BR>
+ <STRONG>Module:</STRONG> mod_setenvif
+ <BR>
+ <STRONG>Compatibility:</STRONG> Apache 1.3 and above
+ </P>
+ <P>
+ The <SAMP>SetEnvIfNoCase</SAMP> is semantically identical to the
+ <A
+ HREF="#SetEnvIf"
+ ><SAMP>SetEnvIf</SAMP></A>
+ directive, and differs only in that the regular expression matching is
+ performed in a case-insensitive manner. For example:
+ </P>
+ <PRE>
+ SetEnvIfNoCase Host Apache\.Org site=apache
+ </PRE>
+ <P>
+ This will cause the <SAMP>site</SAMP> envariable to be set to
+ "<SAMP>apache</SAMP>" if the HTTP request header field
+ <SAMP>Host:</SAMP> was included and contained <SAMP>Apache.Org</SAMP>,
+ <SAMP>apache.org</SAMP>, or any other combination.
+ </P>
+
+<!--#include virtual="footer.html" -->
+ </BODY>
+</HTML>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+<TITLE>Apache module mod_so</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_so</H1>
+
+This module is contained in the <CODE>mod_so.c</CODE> file, and is not
+compiled in by default. It provides for loading of executable code and
+modules into the server at start-up time, on Unix systems. Win32
+systems use <A HREF="mod_dll.html">mod_dll</A> instead. This module is
+only available in Apache 1.3 and up.
+
+<h2>Summary</h2>
+
+This is an experimental module. On selected operating systems it can
+be used to load modules into Apache at runtime, rather than requiring
+a recompilation.
+
+
+<h2>Directives</h2>
+<UL>
+<LI><A HREF="#loadfile">LoadFile</A>
+<LI><A HREF="#loadmodule">LoadModule</A>
+</UL>
+<HR>
+
+
+<h2><A name="loadfile">LoadFile</A></h2>
+<!--%plaintext <?INDEX {\tt LoadFile} directive> -->
+<A
+ HREF="directive-dict.html#Syntax"
+ REL="Help"
+><STRONG>Syntax:</STRONG></A> LoadFile <EM>filename filename ...</EM><BR>
+<A
+ HREF="directive-dict.html#Context"
+ REL="Help"
+><STRONG>Context:</STRONG></A> server config<BR>
+<A
+ HREF="directive-dict.html#Status"
+ REL="Help"
+><STRONG>Status:</STRONG></A> Experimental<BR>
+<A
+ HREF="directive-dict.html#Module"
+ REL="Help"
+><STRONG>Module:</STRONG></A> mod_so<P>
+
+The LoadFile directive links in the named object files or libraries when
+the server is started; this is used to load additional code which
+may be required for some module to work. <EM>Filename</EM> is relative
+to <A HREF="core.html#serverroot">ServerRoot</A>.<P><HR>
+
+<h2><A name="loadmodule">LoadModule</A></h2>
+<!--%plaintext <?INDEX {\tt LoadModule} directive> -->
+<A
+ HREF="directive-dict.html#Syntax"
+ REL="Help"
+><STRONG>Syntax:</STRONG></A> LoadModule <EM>module filename</EM><BR>
+<A
+ HREF="directive-dict.html#Context"
+ REL="Help"
+><STRONG>Context:</STRONG></A> server config<BR>
+<A
+ HREF="directive-dict.html#Status"
+ REL="Help"
+><STRONG>Status:</STRONG></A> Experimental<BR>
+<A
+ HREF="directive-dict.html#Module"
+ REL="Help"
+><STRONG>Module:</STRONG></A> mod_so<P>
+
+The LoadModule directive links in the object file or library <EM>filename</EM>
+and adds the module structure named <EM>module</EM> to the list of active
+modules. <EM>Module</EM> is the name of the external variable of type
+<CODE>module</CODE> in the file. Example:
+<BLOCKQUOTE><CODE>
+LoadModule status_module modules/mod_status.so
+</CODE></BLOCKQUOTE>
+loads the module in the modules subdirectory of the ServerRoot.<P>
+
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
+
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+ <HEAD>
+ <TITLE>Apache module mod_speling</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_speling</H1>
+ <P>
+ This module is contained in the <code>mod_speling.c</code> file,
+ and is <strong>not</strong> compiled in by default.
+ It attemps to correct mispellings of
+ URLs that users might have entered, by ignoring capitalization
+ and by allowing up to one misspelling.<br>
+ This catches the majority of misspelled requests. An automatic
+ "spelling corrected" redirection is returned if only one matching
+ document was found, and a list of matches is returned if more than
+ one document with a sufficiently similar name is found.
+ </P>
+
+ <h2>Summary</h2>
+ <p>
+ Requests to documents sometimes cannot be served by the core apache
+ server because the request was misspelled or miscapitalized. This
+ module addresses this problem by trying to find a matching document,
+ even after all other modules gave up. It does its work by comparing
+ each document name in the requested directory against the requested
+ document name <STRONG>without regard to case</STRONG>, and allowing
+ <STRONG>up to one misspelling</STRONG> (character insertion / omission
+ / transposition or wrong character). A list is built with all document
+ names which were matched using this strategy.
+ </p>
+ <p>
+ If, after scanning the directory,
+ <ul>
+ <li>no matching document was found, Apache will proceed as usual
+ and return a "document not found" error.
+ <li>only one document is found that "almost" matches the request,
+ then it is returned in the form of a redirection response.
+ <li>more than one document with a close match was found, then
+ the list of the matches is returned to the client, and the client
+ can select the correct candidate.
+ </ul>
+ </p>
+
+ <h2>Directives</h2>
+
+ <menu>
+ <li><A HREF="#checkspelling">CheckSpelling</A>
+ </menu>
+
+ <HR> <!-- the HR is part of the directive description -->
+ <A name="checkspelling"><h2>CheckSpelling</h2></A>
+ <!--%plaintext <?INDEX {\tt CheckSpelling} directive> -->
+ <strong>Syntax:</strong> CheckSpelling <em>on/off</em><br>
+ <strong>Default:</strong> <code>CheckSpelling Off</code><br>
+ <Strong>Context:</strong> server config, virtual host<br>
+ <strong>Status:</strong> Base<br>
+ <strong>Module:</strong> mod_speling<br>
+ <strong>Compatibility:</strong> CheckSpelling was available as a separately
+ available module for Apache 1.1, but was limited to miscapitalizations.
+ As of Apache 1.3, it is part of the apache distribution<!-- or:
+ available as a separate module-->.<p>
+
+ This directive enables or disables the spelling module. When enabled,
+ keep in mind that
+ <UL>
+ <LI>the directory scan which is necessary for the spelling
+ correction will have an impact on the server's performance
+ when many spelling corrections have to be performed at the same time.
+ <LI>the document trees should not contain sensitive files which could
+ be matched inadvertedly, by a spelling "correction".
+ <LI>the module is unable to correct misspelled user names
+ (as in <code>http://my.host/~apahce/</code>), just file names or
+ directory names.
+ </UL>
+
+<!--#include virtual="footer.html" -->
+ </BODY>
+</HTML>
+
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+<TITLE>Apache module mod_unique_id</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_unique_id</h1>
+
+This module provides a magic token for each request which is guaranteed
+to be unique across "all" requests under very specific conditions.
+The unique identifier is even unique across multiple machines in a
+properly configured cluster of machines. The environment variable
+<code>UNIQUE_ID</code> is set to the identifier for each request.
+Unique identifiers are useful for various reasons which are beyond the
+scope of this document.
+
+<h2>Theory</h2>
+
+<p>
+First a brief recap of how the Apache server works on Unix machines.
+This feature currently isn't supported on Windows NT. On Unix machines,
+Apache creates several children, the children process requests one at
+a time. Each child can serve multiple requests in its lifetime. For the
+purpose of this discussion, the children don't share any data
+with each other. We'll refer to the children as httpd processes.
+
+<p>
+Your website has one or more machines under your administrative control,
+together we'll call them a cluster of machines. Each machine can
+possibly run multiple instances of Apache. All of these collectively
+are considered "the universe", and with certain assumptions we'll
+show that in this universe we can generate unique identifiers for each
+request, without extensive communication between machines in the cluster.
+
+<p>
+The machines in your cluster should satisfy these requirements.
+(Even if you have only one machine you should synchronize its clock
+with NTP.)
+
+<ul>
+<li>The machines' times are synchronized via NTP or other network time
+ protocol.
+
+<li>The machines' hostnames all differ, such that the module can do a
+ hostname lookup on the hostname and receive a different IP address
+ for each machine in the cluster.
+</ul>
+
+<p>
+As far as operating system assumptions go, we assume that pids (process
+ids) fit in 32-bits. If the operating system uses more than 32-bits
+for a pid, the fix is trivial but must be performed in the code.
+
+<p>
+Given those assumptions, at a single point in time we can identify
+any httpd process on any machine in the cluster from all other httpd
+processes. The machine's IP address and the pid of the httpd process
+are sufficient to do this. So in order to generate unique identifiers
+for requests we need only distinguish between different points in time.
+
+<p>
+To distinguish time we will use a Unix timestamp (seconds since January
+1, 1970 UTC), and a 16-bit counter. The timestamp has only one second
+granularity, so the counter is used to represent up to 65536 values
+during a single second. The quadruple <i>( ip_addr, pid, time_stamp,
+counter )</i> is sufficient to enumerate 65536 requests per second per
+httpd process. There are issues however with pid reuse over
+time, and the counter is used to alleviate this issue.
+
+<p>
+When an httpd child is created, the counter is initialized with (
+current microseconds divided by 10 ) modulo 65536 (this formula was
+chosen to eliminate some variance problems with the low order bits of
+the microsecond timers on some systems). When a unique identifier is
+generated, the time stamp used is the time the request arrived at the
+web server. The counter is incremented every time an identifier is
+generated (and allowed to roll over).
+
+<p>
+The kernel generates a pid for each process as it forks the process, and
+pids are allowed to roll over (they're 16-bits on many Unixes, but newer
+systems have expanded to 32-bits). So over time the same pid will be
+reused. However unless it is reused within the same second, it does not
+destroy the uniqueness of our quadruple. That is, we assume the system
+does not spawn 65536 processes in a one second interval (it may even be
+32768 processes on some Unixes, but even this isn't likely to happen).
+
+<p>
+Suppose that time repeats itself for some reason. That is, suppose that
+the system's clock is screwed up and it revisits a past time (or it is
+too far forward, is reset correctly, and then revisits the future time).
+In this case we can easily show that we can get pid and time stamp reuse.
+The choice of initializer for the counter is intended to help defeat this.
+Note that we really want a random number to initialize the counter,
+but there aren't any readily available numbers on most systems (i.e. you
+can't use rand() because you need to seed the generator, and can't seed
+it with the time because time, at least at one second resolution, has
+repeated itself). This is not a perfect defense.
+
+<p>
+How good a defense is it? Well suppose that one of your machines serves
+at most 500 requests per second (which is a very reasonable upper bound
+at this writing, because systems generally do more than just shovel out
+static files). To do that it will require a number of children which
+depends on how many concurrent clients you have. But we'll be pessimistic
+and suppose that a single child is able to serve 500 requests per second.
+There are 1000 possible starting counter values such that two sequences
+of 500 requests overlap. So there is a 1.5% chance that if time (at one
+second resolution) repeats itself this child will repeat a counter value,
+and uniqueness will be broken. This was a very pessimistic example,
+and with real world values it's even less likely to occur. If your
+system is such that it's still likely to occur, then perhaps you should
+make the counter 32 bits (by editing the code).
+
+<p>
+You may be concerned about the clock being "set back" during summer
+daylight savings. However this isn't an issue because the times used here
+are UTC, which "always" go forward. Note that x86 based Unixes may need
+proper configuration for this to be true -- they should be configured to
+assume that the motherboard clock is on UTC and compensate appropriately.
+But even still, if you're running NTP then your UTC time will be correct
+very shortly after reboot.
+
+<p>
+The <code>UNIQUE_ID</code> environment variable is constructed by
+encoding the 112-bit (32-bit IP address, 32 bit pid, 32 bit time stamp,
+16 bit counter) quadruple using the alphabet <code>[A-Za-z0-9@-]</code>
+in a manner similar to MIME base64 encoding, producing 19 characters.
+The MIME base64 alphabet is actually <code>[A-Za-z0-9+/]</code> however
+<code>+</code> and <code>/</code> need to be specially encoded in URLs,
+which makes them less desirable. All values are encoded in network
+byte ordering so that the encoding is comparable across architectures of
+different byte ordering. The actual ordering of the encoding is: time
+stamp, IP address, pid, counter. This ordering has a purpose, but it
+should be emphasized that applications should not dissect the encoding.
+Applications should treat the entire encoded <code>UNIQUE_ID</code> as an
+opaque token, which can be compared against other <code>UNIQUE_ID</code>s
+for equality only.
+
+<p>
+The ordering was chosen such that it's possible to change the encoding
+in the future without worrying about collision with an existing database
+of <code>UNIQUE_ID</code>s. The new encodings should also keep the time
+stamp as the first element, and can otherwise use the same alphabet and
+bit length. Since the time stamps are essentially an increasing sequence,
+it's sufficient to have a <i>flag second</i> in which all machines in the
+cluster stop serving and request, and stop using the old encoding format.
+Afterwards they can resume requests and begin issuing the new encodings.
+
+<p>
+This we believe is a relatively portable solution to this problem. It can
+be extended to multithreaded systems like Windows NT, and can grow with
+future needs. The identifiers generated have essentially an infinite
+life-time because future identifiers can be made longer as required.
+Essentially no communication is required between machines in the cluster
+(only NTP synchronization is required, which is low overhead), and no
+communication between httpd processes is required (the communication is
+implicit in the pid value assigned by the kernel). In very specific
+situations the identifier can be shortened, but more information needs
+to be assumed (for example the 32-bit IP address is overkill for any
+site, but there is no portable shorter replacement for it).
+
+<hr>
+
+<h2>Directives</h2>
+
+<code>mod_unique_id</code> has no directives.
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
+++ /dev/null
-<html>
-<head>
-<title>Running a High-Performance Web Server for BSD</title>
-</head>
-
-<body>
-<A NAME="initial">
-<IMG SRC="../images/apache_sub.gif" ALT="">
-</A>
-<H2>Running a High-Performance Web Server for BSD</H2>
-
-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.
-
-<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><HR>
-
-<H3>More welcome!</H3>
-
-If you have tips to contribute, send mail to <a
-href="mailto:brian@organic.com">brian@organic.com</a>
-
-<P><HR><P>
-<A HREF="/"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
-<A HREF="."><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
-</body></html>
-
+++ /dev/null
-<HEAD>
-<TITLE>Performance Tuning Tips for Digital Unix</TITLE>
-</HEAD>
-<BODY>
-<H1>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.
-</UL>
-
-<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>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<title>Running a High-Performance Web Server on HPUX</title>
+</head>
+
+<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+<BODY
+ BGCOLOR="#FFFFFF"
+ TEXT="#000000"
+ LINK="#0000FF"
+ VLINK="#000080"
+ ALINK="#FF0000"
+>
+<A NAME="initial">
+<DIV ALIGN="CENTER">
+ <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]">
+ <H3>
+ Apache HTTP Server Version 1.3
+ </H3>
+</DIV>
+
+</A>
+<H1 ALIGN="CENTER">Running a High-Performance Web Server for HPUX</H1>
+
+<PRE>
+Date: Wed, 05 Nov 1997 16:59:34 -0800
+From: Rick Jones <<A HREF="mailto:raj@cup.hp.com">raj@cup.hp.com</A>>
+Reply-To: raj@cup.hp.com
+Organization: Network Performance
+Subject: HP-UX tuning tips
+</PRE>
+
+Here are some tuning tips for HP-UX to add to the tuning page.
+
+<P>
+
+For HP-UX 9.X: Upgrade to 10.20<BR>
+For HP-UX 10.[00|01|10]: Upgrade to 10.20
+
+<P>
+
+For HP-UX 10.20:
+
+<P>
+
+Install the latest cumulative ARPA Transport Patch. This will allow you
+to configure the size of the TCP connection lookup hash table. The
+default is 256 buckets and must be set to a power of two. This is
+accomplished with adb against the *disc* image of the kernel. The
+variable name is tcp_hash_size.
+
+<P>
+
+How to pick the value? Examine the output of
+<A HREF="ftp://ftp.cup.hp.com/dist/networking/tools/connhist">
+ftp://ftp.cup.hp.com/dist/networking/tools/connhist</A> and see how many
+total TCP connections exist on the system. You probably want that number
+divided by the hash table size to be reasonably small, say less than 10.
+Folks can look at HP's SPECweb96 disclosures for some common settings.
+These can be found at <A HREF="http://www.specbench.org/">
+http://www.specbench.org/</A>. If an HP-UX system was
+performing at 1000 SPECweb96 connections per second, the TIME_WAIT time
+of 60 seconds would mean 60,000 TCP "connections" being tracked.
+
+<P>
+
+Folks can check their listen queue depths with
+<A HREF="ftp://ftp.cup.hp.com/dist/networking/misc/listenq">
+ftp://ftp.cup.hp.com/dist/networking/misc/listenq</A>.
+
+<P>
+
+If folks are running Apache on a PA-8000 based system, they should
+consider "chatr'ing" the Apache executable to have a large page size.
+This would be "chatr +pi L <binary>." The GID of the running executable
+must have MLOCK priviledges. Setprivgrp(1m) should be consulted for
+assigning MLOCK. The change can be validated by running Glance and
+examining the memory regions of the server(s) to make sure that they
+show a non-trivial fraction of the text segment being locked.
+
+<P>
+
+If folks are running Apache on MP systems, they might consider writing a
+small program that uses mpctl() to bind processes to processors. A
+simple pid % numcpu algorithm is probably sufficient. This might even go
+into the source code.
+
+<P>
+
+If folks are concerned about the number of FIN_WAIT_2 connections, they
+can use nettune to shrink the value of tcp_keepstart. However, they
+should be careful there - certainly do not make it less than oh two to
+four minutes. If tcp_hash_size has been set well, it is probably OK to
+let the FIN_WAIT_2's take longer to timeout (perhaps even the default
+two hours) - they will not on average have a big impact on performance.
+
+<P>
+
+There are other things that could go into the code base, but that might
+be left for another email. Feel free to drop me a message if you or
+others are interested.
+
+<P>
+
+sincerely,
+
+<P>
+
+rick jones<BR>
+<A HREF="http://www.cup.hp.com/netperf/NetperfPage.html">
+http://www.cup.hp.com/netperf/NetperfPage.html</A>
+
+<HR>
+
+<H3 ALIGN="CENTER">
+ Apache HTTP Server Version 1.3
+</H3>
+
+<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A>
+<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A>
+
+</body></html>
+
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<html>
-<head>
-<title>Hints on Running a High-Performance Web Server</title>
-</head>
-
-<body>
-<IMG SRC="../images/apache_sub.gif" ALT="">
-<h2>Hints on Running a High-Performance Web Server</H2>
-
-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>
-
-<A NAME="AUX">
-<H3>A/UX (Apple's UNIX)</H3>
-</A>
-
-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>
-
-<A NAME="BSD">
-<H3>BSD-based (BSDI, FreeBSD, etc)</H3>
-</A>
-
-<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>
-
-<A NAME="DEC">
-<H3>Digital UNIX</H3>
-</A>
-
-We have some <A HREF="perf-dec.html">newsgroup postings</A> on how to
-tune Digital UNIX 3.2 and 4.0.
-
-<P><HR>
-
-<A NAME="HP">
-<H3>Hewlett-Packard</H3>
-</A>
-
-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>
-
-<A NAME="Linux">
-<H3>Linux</H3>
-</A>
-
-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>
-
-<A NAME="SGI">
-<H3>SGI</H3>
-
-<UL>
-<LI><A HREF="http://www.sgi.com/Products/WebFORCE/TuningGuide.html">
-WebFORCE Web Server Tuning Guidelines for IRIX 5.3,
-<http://www.sgi.com/Products/WebFORCE/TuningGuide.html></A>
-</UL>
-
-<P><HR>
-
-<A NAME="Solaris">
-<H3>Solaris 2.4</H3>
-</A>
-
-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/cgi-bin/show?sun-on-net/Sun.Internet.Solutions/performance/">
-World Wide Web Server Performance,
-<http://www.sun.com/cgi-bin/show?sun-on-net/Sun.Internet.Solutions/performance/></a>
-</UL>
-
-<P><HR>
-
-<A NAME="SunOS">
-<H3>SunOS 4.x</H3>
-</A>
-
-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>
-
-<P><HR><P>
-<A HREF="/"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
-<A HREF="."><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
-</body></html>
-
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+<TITLE>Using Apache with Microsoft Windows</TITLE>
+</HEAD>
+
+<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+<BODY
+ BGCOLOR="#FFFFFF"
+ TEXT="#000000"
+ LINK="#0000FF"
+ VLINK="#000080"
+ ALINK="#FF0000"
+>
+<!--#include virtual="header.html" -->
+
+<H1 ALIGN="CENTER">Using Apache With Microsoft Windows</H1>
+
+<p>This document explains how to compile, install, configure and run
+ Apache 1.3a1 (or later) under Microsoft Windows. Please note that at
+ this time, Windows support is entirely experimental, and is
+ recommended only for experienced users. The Apache Group does not
+ guarantee that this software will work as documented, or even at
+ all. If you find any bugs, or wish to contribute in other ways, please
+ use our <a href="http://www.apache.org/bug_report.html">bug reporting
+ page.</a></p>
+
+<hr>
+
+<ul>
+ <li><a href="#req">Requirements</a>
+ <li><a href="#down">Downloading Apache for Windows</a>
+ <li><a href="#comp">Compiling Apache for Windows</a>
+ <li><a href="#inst">Installing Apache for Windows</a>
+ <li><a href="#use">Using Apache for Windows</a>
+</ul>
+
+<hr>
+
+<h2><a name="req">Requirements</a></h2>
+
+<p>Apache 1.3a1 requires the following:</p>
+
+<ul>
+ <li>Microsoft Windows NT 4.0<a href="#351">*</a>, or Windows 95.
+ <li>An Intel-based PC-compatible capable of running above OS (exact
+ requirements unknown) with a connection to a TCP/IP network.
+ <li>Microsoft Visual C++ 5.0 or later.
+</ul>
+
+<p><small><a name="351">*</a> Apache may run with Windows NT 3.5.1, but
+ has not been tested.</small></p>
+
+<p>Apache 1.3a1 is available only in source form. Future releases will
+ contain prebuilt binaries for use by those without compilers (which we
+ understand are the vast majority of Windows users), however the
+ current release requires Microsoft Visual C++ 5.0 or later. The Apache
+ Group is releasing 1.3a1 only as source to limit the alpha release to
+ those who have the tools and knowledge to assist with the development
+ processes.</p>
+
+<p>This documentation assumes good working knowledge of Microsoft
+ Windows, Microsoft Visual C++, and the Apache web server (for
+ Unix).</p>
+
+<H2><a name="down">Downloading Apache for Windows</a></H2>
+
+<p>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 alpha or beta-test release,
+together with details of mirror web and anonymous ftp sites.</p>
+
+<p>You will be able to download Apache 1.3a1 or a later release in
+ several forms, including a WinZip (<code>.zip</code>)
+ archive. Although this contains the same files as the others (likely
+ <code>.tar.gz</code> and <code>.tar.Z</code>), it is recommended for
+ Windows use, as all the files contained therein will contain Windows
+ line breaks. The other archives may contain files with Unix line
+ breaks, which will not function on Windows (although they may).</p>
+
+<h2><a name="comp">Compiling Apache for Windows</a></h2>
+
+<p>Compiling Apache requires Microsoft Visual C++ 5.0 to be properly
+ installed. It is easiest to compile with the command-line tools
+ (nmake, etc...). Consult the VC++ manual to determine how to install
+ them.</p>
+
+<p>First, unpack the Apache distribution into an appropriate
+ directory. Open a command-line prompt, and change to the
+ <code>src</code> subdirectory of the Apache distribution.</p>
+
+<p>The master Apache makefile instructions are contained in the
+ <code>Makefile.nt</code> file. To compile Apache, simply use one of
+ the following commands:
+<ul>
+<li><code>nmake /f Makefile.nt release</code>
+<li><code>nmake /f Makefile.nt debug</code>
+</ul>
+
+<p>These will both compile Apache. The latter will include debugging
+ information in the resulting files, making it easier to find bugs and
+ track down problems.</p>
+
+<p>Apache can also be compiled using VC++'s Visual Studio development
+ environment. Although compiling Apache in this manner is not as simple,
+ it makes it possible to easily modify the Apache source, or to compile
+ Apache if the command-line tools are not installed.</p>
+
+<p>Project files (<code>.DSP</code>) are included for each of the
+ portions of Apache. The two projects that are necessary for Apache to
+ run are <code>Apache.dsp</code> and <code>ApacheCore.dsp</code>. The
+ <code>src\nt</code> subdirectory also contains project files for the
+ optional modules (see below).</p>
+
+<h2><a name="inst">Installing Apache for Windows</a></h2>
+
+<p>Once Apache has been compiled, it needs to be installed in its server
+ root directory. The hard-coded default is the <code>\Apache</code>
+ directory, on the current hard drive. Another directory may be used,
+ but the files will need to be installed manually.</p>
+
+<p>To install the files into the </code>\Apache</code> directory
+ automatically, use one the following nmake commands (see above):</p>
+<ul>
+<li><code>nmake /f Makefile.nt installr</code> (for release build)
+<li><code>nmake /f Makefile.nt installd</code> (for debug build)
+</ul>
+
+<p>This will install the following:</p>
+
+<ul>
+ <li><code>\Apache\Apache.exe</code> - Apache executable
+ <li><code>\Apache\ApacheCore.dll</code> - Main Apache shared library
+ <li><code>\Apache\modules\ApacheModule*.dll</code> - Optional Apache
+ modules (7 files)
+ <li><code>\Apache\conf</code> - Empty configuration directory
+ <li><code>\Apache\logs</code> - Empty logging directory
+</ul>
+
+<p>If you do not have nmake, or wish to install in a different directory,
+ be sure to use a similar naming scheme.</p>
+
+<h2><a name="use">Using Apache for Windows</a></h2>
+
+<p>The first step is to set up Apache's configuration files. Default
+ configuration files for Windows are located in the <code>conf</code>
+ subdirectory in the Apache distribution, and are named
+ <code>httpd.conf-dist-win</code>, <code>access.conf-dist-win</code>
+ and <code>srm.conf-dist-win</code>. Move these into
+ <code>\Apache\conf</code>, and rename them <code>httpd.conf</code>,
+ <code>access.conf</code> and <code>srm.conf</code>, respectively.</p>
+
+<p>Configuring Apache is nearly identical to the Unix version of Apache,
+ so most of the standard <a href="./">Apache documentation</a> is
+ applicable. A few things are, however, different:</p>
+
+<ul>
+ <li><p>Because Apache for Windows is multithreaded, it does not use a
+ separate process for each request, as Apache does with
+ Unix. Therefore, the "process"-management directives are different:
+ <p><a href="mod/core.html#startservers">StartServers</a> - This
+ tells the server how many processes to use. Unlike Unix, there
+ will never be more than this number, and only one will be used
+ at a time (the others will be held in reserve in case the main
+ processes crashes or otherwise dies). The recommended default is
+ <code>StartServers 3</code>.
+ <p><a
+ href="mod/core.html#maxrequestsperchild">MaxRequestsPerChild</a>
+ - Like the Unix directive, this controls how many requests a
+ process will serve before exiting. However, unlike Unix, a
+ process serves all the requests at once, not just one, so if
+ this is set, it is recommended that a very high number is
+ used. The recommended default, <code>MaxRequestsPerChild
+ 0</code>, does not cause the process to ever exit.
+ <p><a href="mode/core.html#threadsperchild">ThreadsPerChild</a> -
+ This directive is new, and tells the server how many threads it
+ should use. This is the maximum number of connections the server
+ can handle at once; be sure and set this number high enough for
+ your site if you get a lot of hits. The recommended default is
+ <code>ThreadsPerChild 20</code>.</p>
+ <li><p>The directives that accept filenames as arguments now must use
+ Windows filenames instead of Unix ones. However, because Apache
+ uses Unix-style names internally, you must use forward slashes, not
+ backslashes. Drive letters can be used; if omitted, the drive with
+ the Apache executable will be assumed.</p>
+ <li><p>Apache for Windows contains the ability to load modules at runtime,
+ without recompiling the server. If Apache is compiled normally, it
+ will install a number of optional modules in the
+ <code>\Apache\modules</code> directory. To activate these, or other
+ modules, the new <a href="mod/mod_dll.html#loadmodule">LoadModule</a>
+ directive must be used. For example, to active the status module,
+ use the following (in addition to the status-activating directives
+ in <code>access.conf</code>):</p>
+<pre>
+ LoadModule status_module modules/ApacheModuleStatus.dll
+</pre>
+ <p>Information on <a href="mod/mod_dll.html#creating">creating module
+ DLLs</a> is also available.</p>
+</ul>
+
+<p>Once Apache is configured correctly, it is nearly ready to be
+run. However, we recommend you copy the <code>icons</code> and
+<code>htdocs</code> subdirectories from the Apache distribution to
+<code>\Apache</code>. The latter is especially important, as it contains
+the document root (what the server actually serves).
+
+<p>Apache can be executed in one of two ways, directly from the command
+ line, or as a Windows NT service. To run it from the command line, use
+ the following command:
+<pre>
+ C:\Apache> <b>apache -s</b>
+</pre>
+
+<p>Apache will then execute, and will remain running until it is
+ exited. To use Apache as a Windows NT service, use the following:</p>
+<pre>
+ C:\Apache> <b>apache -i</b>
+</pre>
+<p>Then open the Services control panel, and start the Apache service.</p>
+
+<p>If you installed Apache in a server root other than
+ <code>\Apache</code>, you must use the <code>-f</code> command-line
+ option to specify the httpd.conf file, or the <code>-d</code> option
+ to specify the server root.</p>
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
+++ /dev/null
-<HTML><HEAD>
-<TITLE>Server Pool Management with MinSpareServers and MaxSpareServers</TITLE>
-</HEAD><BODY>
-
-<IMG SRC="../images/apache_sub.gif" ALT="">
-<H3>Server Pool Management with MinSpareServers and MaxSpareServers</H3>
-
-<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 persistant processes, the
-webmaster 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-combatibility). The old names were generally regarded
-as too confusing.
-
-<P>
-
-The defaults for each variable are:
-
-<PRE>
-MinSpareServers 5
-MaxSpareServers 10
-StartServers 10
-</PRE>
-
-There is a compile-time limit of 150 absolute maximum number of
-simultaneous children that will be allowed, which can be overruled by
-"MaxClients", though we don't recommend changing that number 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>
-
-</body></html>
-
-
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html><head>
+<title>How Directory, Location and Files sections work</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">How Directory, Location and Files sections work</h1>
+
+The sections <a
+href="mod/core.html#directory"><code><Directory></code></a>, <a
+href="mod/core.html#location"><code><Location></code></a> and <a
+href="mode/core.html#files"><code><Files></code></a> can contain
+directives which only apply to specified directories, URLs or files
+respectively. Also htaccess files can be used inside a directory to
+apply directives to that directory. This document explains how these
+different sections differ and how they relate to each other when
+Apache decides which directives apply for a particular directory or
+request URL.
+
+<h2>Directives allowed in the sections</h2>
+
+Everything that is syntactically allowed in
+<code><Directory></code> is also allowed in
+<code><Location></code> (except a sub-<code><Files></code>
+section, but the code doesn't test for that, Lars has an open bug
+report on that). Semantically however some things, and the most
+notable is AllowOverrides, make no sense in
+<code><Location></code>. The same for
+<code><Files></code> -- syntactically everything is fine, but
+semantically some things are different.
+
+<h2>How the sections are merged</h2>
+
+The order of merging is:
+
+<ol>
+
+<li>
+
+ <code><Directory></code> (except regular expressions) and
+ .htaccess done simultaneously (with .htaccess overriding
+ <code><Directory></code>)
+
+</li>
+
+<li>
+ <code><DirectoryMatch></code>, and
+ <code><Directory></code> with regular expressions
+
+</li>
+
+ <li><code><Files></code> and <code><FilesMatch></code> done simultaneously
+ </li>
+
+ <li><code><Location></code> and <code><LocationMatch></code> done simultaneously
+ </li>
+
+</ol>
+
+Apart from <code><Directory></code>, each group is processed in
+the order that they appear in the configuration
+files. <code><Directory></code> (group 1 above) is processed in
+the order shortest directory component to longest. If multiple
+<code><Directory></code> sections apply to the same directory
+they they are processed in the configuration file order. The
+configuration files are read in the order httpd.conf, srm.conf and
+access.conf. Configurations included via the <code>Include</code>
+directive will be treated as if they where inside the including file
+at the location of the <code>Include</code> directive.
+
+<p>
+
+Sections inside <code><VirtualHost></code> sections are applied
+<i>after</i> the corresponding sections outside the virtual host
+definition. This allows virtual hosts to override the main server
+configuration. (Note: this only works correctly from 1.2.2 and 1.3a2
+onwards. Before those releases sections inside virtual hosts were
+applied <i>before</i> the main server).
+
+<h2>Notes about using sections</h2>
+
+The general guidelines are:
+
+<p>
+
+<ul>
+<li>
+ If you are attempting to match objects at the filesystem level
+ then you must use <code><Directory></code> and/or
+ <code><Files></code>.
+</li>
+
+<li>
+ If you are attempting to match objects at the URL level then you
+ must use <code><Location></code>
+</li>
+</ul>
+
+But a notable exception is:
+
+<ul>
+<li>
+ proxy control is done via <code><Directory></code>. This is
+ a legacy mistake because the proxy existed prior to
+ <code><Location></code>. A future version of the config
+ language should probably switch this to
+ <code><Location></code>.
+</li>
+</ul>
+
+Note also that modifying .htaccess parsing during Location doesn't do
+anything because .htaccess parsing has already occured.
+
+<p>
+
+Another note:
+<p>
+
+<ul>
+<li>
+ There is actually a
+ <code><Location></code>/<code><LocationMatch></code>
+ sequence performed just before the name translation phase (where
+ <code>Aliases</code> and <code>DocumentRoots</code> are used to
+ map URLs to filenames). The results of this sequence are
+ completely thrown away after the translation has completed.
+</li>
+</ul>
+
+<!--#include virtual="footer.html" -->
+</body></html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html><head>
+<title>How Directory, Location and Files sections work</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">How Directory, Location and Files sections work</h1>
+
+The sections <a
+href="mod/core.html#directory"><code><Directory></code></a>, <a
+href="mod/core.html#location"><code><Location></code></a> and <a
+href="mode/core.html#files"><code><Files></code></a> can contain
+directives which only apply to specified directories, URLs or files
+respectively. Also htaccess files can be used inside a directory to
+apply directives to that directory. This document explains how these
+different sections differ and how they relate to each other when
+Apache decides which directives apply for a particular directory or
+request URL.
+
+<h2>Directives allowed in the sections</h2>
+
+Everything that is syntactically allowed in
+<code><Directory></code> is also allowed in
+<code><Location></code> (except a sub-<code><Files></code>
+section, but the code doesn't test for that, Lars has an open bug
+report on that). Semantically however some things, and the most
+notable is AllowOverrides, make no sense in
+<code><Location></code>. The same for
+<code><Files></code> -- syntactically everything is fine, but
+semantically some things are different.
+
+<h2>How the sections are merged</h2>
+
+The order of merging is:
+
+<ol>
+
+<li>
+
+ <code><Directory></code> (except regular expressions) and
+ .htaccess done simultaneously (with .htaccess overriding
+ <code><Directory></code>)
+
+</li>
+
+<li>
+ <code><DirectoryMatch></code>, and
+ <code><Directory></code> with regular expressions
+
+</li>
+
+ <li><code><Files></code> and <code><FilesMatch></code> done simultaneously
+ </li>
+
+ <li><code><Location></code> and <code><LocationMatch></code> done simultaneously
+ </li>
+
+</ol>
+
+Apart from <code><Directory></code>, each group is processed in
+the order that they appear in the configuration
+files. <code><Directory></code> (group 1 above) is processed in
+the order shortest directory component to longest. If multiple
+<code><Directory></code> sections apply to the same directory
+they they are processed in the configuration file order. The
+configuration files are read in the order httpd.conf, srm.conf and
+access.conf. Configurations included via the <code>Include</code>
+directive will be treated as if they where inside the including file
+at the location of the <code>Include</code> directive.
+
+<p>
+
+Sections inside <code><VirtualHost></code> sections are applied
+<i>after</i> the corresponding sections outside the virtual host
+definition. This allows virtual hosts to override the main server
+configuration. (Note: this only works correctly from 1.2.2 and 1.3a2
+onwards. Before those releases sections inside virtual hosts were
+applied <i>before</i> the main server).
+
+<h2>Notes about using sections</h2>
+
+The general guidelines are:
+
+<p>
+
+<ul>
+<li>
+ If you are attempting to match objects at the filesystem level
+ then you must use <code><Directory></code> and/or
+ <code><Files></code>.
+</li>
+
+<li>
+ If you are attempting to match objects at the URL level then you
+ must use <code><Location></code>
+</li>
+</ul>
+
+But a notable exception is:
+
+<ul>
+<li>
+ proxy control is done via <code><Directory></code>. This is
+ a legacy mistake because the proxy existed prior to
+ <code><Location></code>. A future version of the config
+ language should probably switch this to
+ <code><Location></code>.
+</li>
+</ul>
+
+Note also that modifying .htaccess parsing during Location doesn't do
+anything because .htaccess parsing has already occured.
+
+<p>
+
+Another note:
+<p>
+
+<ul>
+<li>
+ There is actually a
+ <code><Location></code>/<code><LocationMatch></code>
+ sequence performed just before the name translation phase (where
+ <code>Aliases</code> and <code>DocumentRoots</code> are used to
+ map URLs to filenames). The results of this sequence are
+ completely thrown away after the translation has completed.
+</li>
+</ul>
+
+<!--#include virtual="footer.html" -->
+</body></html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<HTML>
+<HEAD>
+<TITLE>Stopping and Restarting Apache</TITLE>
+</HEAD>
+
+<BODY>
+<!--#include virtual="header.html" -->
+<h1>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.
+
+<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.
+
+<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 lose track of a child during graceful restart (you'll see an <a
+href="mod/core.html#errorlog">ErrorLog</a> message saying something about
+a <i>long lost child</i>). The ScoreBoardFile directive explains how
+to figure out if your server uses a file, and possibly how to avoid it.
+There is also the potential that the scoreboard will be corrupted during
+any signalling, but this only has bad effects on graceful restart.
+
+<p><code>NEXT</code> and <code>MACHTEN</code> 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>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<HTML>
+<HEAD>
+<TITLE>Stopping and Restarting Apache</TITLE>
+</HEAD>
+
+<BODY>
+<!--#include virtual="header.html" -->
+<h1>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.
+
+<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.
+
+<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 lose track of a child during graceful restart (you'll see an <a
+href="mod/core.html#errorlog">ErrorLog</a> message saying something about
+a <i>long lost child</i>). The ScoreBoardFile directive explains how
+to figure out if your server uses a file, and possibly how to avoid it.
+There is also the potential that the scoreboard will be corrupted during
+any signalling, but this only has bad effects on graceful restart.
+
+<p><code>NEXT</code> and <code>MACHTEN</code> 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>
--- /dev/null
+<html><head>
+<title>Apache SetUserID Support</title>
+</head><body>
+
+<!--#include virtual="header.html" -->
+<h1>Apache SetUserID Support</h1>
+
+<hr>
+
+<h2>What is SUExec?</h2>
+
+<h2>Enabling SUExec Support</h2>
+
+<h2>When SUExec Is Used</h2>
+
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
+
--- /dev/null
+<html><head>
+<title>Apache SetUserID Support</title>
+</head><body>
+
+<!--#include virtual="header.html" -->
+<h1>Apache SetUserID Support</h1>
+
+<hr>
+
+<h2>What is SUExec?</h2>
+
+<h2>Enabling SUExec Support</h2>
+
+<h2>When SUExec Is Used</h2>
+
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
+
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html><head>
+<title>An In-Depth Discussion of Virtual Host Matching</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">An In-Depth Discussion of Virtual Host Matching</h1>
+
+<p>The virtual host code was completely rewritten in <B>Apache 1.3</B>.
+This document attempts to explain exactly what Apache does when
+deciding what virtual host to serve a hit from. With the help of the
+new <A HREF="../mod/core.html#namevirtualhost"><SAMP>NameVirtualHost</SAMP></A>
+directive virtual host configuration should be a lot easier and safer
+than with versions prior to 1.3.
+
+<p>If you just want to <cite>make it work</cite> without understanding
+how, here are <a href="examples.html">some examples</a>.
+
+<h3>Config File Parsing</h3>
+
+<p>There is a <EM>main_server</EM> which consists of all
+the definitions appearing outside of <CODE><VirtualHost></CODE> sections.
+There are virtual servers, called <EM>vhosts</EM>, which are defined by
+<A HREF="../mod/core.html#virtualhost"><SAMP><VirtualHost></SAMP></A>
+sections.
+
+<p>The directives
+<A HREF="../mod/core.html#port"><SAMP>Port</SAMP></A>,
+<A HREF="../mod/core.html#servername"><SAMP>ServerName</SAMP></A>,
+<A HREF="../mod/core.html#serverpath"><SAMP>ServerPath</SAMP></A>,
+and
+<A HREF="../mod/core.html#serveralias"><SAMP>ServerAlias</SAMP></A>
+can appear anywhere within the definition of
+a server. However, each appearance overrides the previous appearance
+(within that server).
+
+<p>The default value of the <code>Port</code> field for main_server
+is 80. The main_server has no default <code>ServerPath</code>, or
+<code>ServerAlias</code>. The default <code>ServerName</code> is
+deduced from the servers IP address.
+
+<p>The main_server Port directive has two functions due to legacy
+compatibility with NCSA configuration files. One function is
+to determine the default network port Apache will bind to. This
+default is overridden by the existence of any
+<A HREF="../mod/core.html#listen"><code>Listen</code></A> directives.
+The second function is to specify the port number which is used
+in absolute URIs during redirects.
+
+<p>Unlike the main_server, vhost ports <em>do not</em> affect what
+ports Apache listens for connections on.
+
+<p>Each address appearing in the <code>VirtualHost</code> directive
+can have an optional port. If the port is unspecified it defaults to
+the value of the main_server's most recent <code>Port</code> statement.
+The special port <SAMP>*</SAMP> indicates a wildcard that matches any port.
+Collectively the entire set of addresses (including multiple
+<SAMP>A</SAMP> record
+results from DNS lookups) are called the vhost's <EM>address set</EM>.
+
+<P>Unless a <A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A>
+directive is used for a specific IP address the first vhost with
+that address is treated as an IP-based vhost.
+
+<P>If name-based vhosts should be used a <code>NameVirtualHost</code>
+directive <em>must</em> appear with the IP address set to be used for the
+name-based vhosts. In other words, you must specify the IP address that
+holds the hostname aliases (CNAMEs) for your name-based vhosts via a
+<code>NameVirtualHost</code> directive in your configuration file.
+
+<P>Multiple <code>NameVirtualHost</code> directives can be used each
+with a set of <code>VirtualHost</code> directives.
+
+<P>The ordering of <code>NameVirtualHost</code> and
+<code>VirtualHost</code> directives is not important which makes the
+following two examples identical (only the order of the
+<code>VirtualHost</code> directives for <em>one</em> address set
+is important, see below):
+
+<pre>
+ |
+ NameVirtualHost 111.22.33.44 | <VirtualHost 111.22.33.44>
+ <VirtualHost 111.22.33.44> | # server A
+ # server A | </VirtualHost>
+ ... | <VirtualHost 111.22.33.55>
+ </VirtualHost> | # server C
+ <VirtualHost 111.22.33.44> | ...
+ # server B | </VirtualHost>
+ ... | <VirtualHost 111.22.33.44>
+ </VirtualHost> | # server B
+ | ...
+ NameVirtualHost 111.22.33.55 | </VirtualHost>
+ <VirtualHost 111.22.33.55> | <VirtualHost 111.22.33.55>
+ # server C | # server D
+ ... | ...
+ </VirtualHost> | </VirtualHost>
+ <VirtualHost 111.22.33.55> |
+ # server D | NameVirtualHost 111.22.33.44
+ ... | NameVirtualHost 111.22.33.55
+ </VirtualHost> |
+ |
+</pre>
+
+<p>(To aid the readability of your configuration you should prefer the
+left variant.)
+
+<p> After parsing the <code>VirtualHost</code> directive, the vhost server
+is given a default <code>Port</code> equal to the port assigned to the
+first name in its <code>VirtualHost</code> directive.
+
+<p>The complete list of names in the <code>VirtualHost</code> directive
+are treated just like a <code>ServerAlias</code> (but are not overridden by any
+<code>ServerAlias</code> statement) if all names resolve to the same address set.
+Note that subsequent <code>Port</code> statements for this vhost will not affect
+the ports assigned in the address set.
+
+<p>During initialization a list for each IP address
+is generated an inserted into an hash table. If the IP address is
+used in a <code>NameVirtualHost</code> directive the list contains
+all name-based vhosts for the given IP address. If there are no
+vhosts defined for that address the <code>NameVirtualHost</code> directive
+is ignored and an error is logged. For an IP-based vhost the list in the
+hash table is empty.
+
+<p>Due to a fast hashing function the overhead of hashing an IP address
+during a request is minimal and almost not existent. Additionally
+the table is optimized for IP addresses which vary in the last octet.
+
+<p>For every vhost various default values are set. In particular:
+
+<ol>
+<li>If a vhost has no
+ <A HREF="../mod/core.html#serveradmin"><code>ServerAdmin</code></A>,
+ <A HREF="../mod/core.html#resourceconfig"><code>ResourceConfig</code></A>,
+ <A HREF="../mod/core.html#accessconfig"><code>AccessConfig</code></A>,
+ <A HREF="../mod/core.html#timeout"><code>Timeout</code></A>,
+ <A HREF="../mod/core.html#keepalivetimeout"><code>KeepAliveTimeout</code></A>,
+ <A HREF="../mod/core.html#keepalive"><code>KeepAlive</code></A>,
+ <A HREF="../mod/core.html#maxkeepaliverequests"><code>MaxKeepAliveRequests</code></A>,
+ or
+ <A HREF="../mod/core.html#sendbuffersize"><code>SendBufferSize</code></A>
+ directive then the respective value is
+ inherited from the main_server. (That is, inherited from whatever
+ the final setting of that value is in the main_server.)
+
+<li>The "lookup defaults" that define the default directory
+ permissions
+ for a vhost are merged with those of the main_server. This includes
+ any per-directory configuration information for any module.
+
+<li>The per-server configs for each module from the main_server are
+ merged into the vhost server.
+</ol>
+
+Essentially, the main_server is treated as "defaults" or a
+"base" on which to build each vhost.
+But the positioning of these main_server
+definitions in the config file is largely irrelevant -- the entire
+config of the main_server has been parsed when this final merging occurs.
+So even if a main_server definition appears after a vhost definition
+it might affect the vhost definition.
+
+<p> If the main_server has no <code>ServerName</code> at this point,
+then the hostname of the machine that httpd is running on is used
+instead. We will call the <EM>main_server address set</EM> those IP
+addresses returned by a DNS lookup on the <code>ServerName</code> of
+the main_server.
+
+<p> For any undefined <code>ServerName</code> fields, a name-based vhost
+defaults to the address given first in the <code>VirtualHost</code>
+statement defining the vhost.
+
+<P>Any vhost that includes the magic <SAMP>_default_</SAMP> wildcard
+is given the same <code>ServerName</code> as the main_server.
+
+
+<h3>Virtual Host Matching</h3>
+
+<p>The server determines which vhost to use for a request as follows:
+
+<h4>Hash table lookup</h4>
+
+<p>When the connection is first made by a client, the IP address to
+which the client connected is looked up in the internal IP hash table.
+
+<P>If the lookup fails (the IP address wasn't found) the request is
+served from the <samp>_default_</samp> vhost if there is such a vhost
+for the port to which the client sent the request. If there is no
+matching <samp>_default_</samp> vhost the request is served from the
+main_server.
+
+<P>If the lookup succeeded (a corresponding list for the IP address was
+found) the next step is to decide if we have to deal with an IP-based
+or a name-base vhost.
+
+<h4>IP-based vhost</h4>
+
+<P>If the entry we found has an empty name list then we have found an
+IP-based vhost, no further actions are performed and the request is
+served from that vhost.
+
+<h4>Name-based vhost</h4>
+
+<p>If the entry corresponds to a name-based vhost the name list contains
+one or more vhost structures. This list contains the vhosts in the same
+order as the <code>VirtualHost</code> directives appear in the config
+file.
+
+<p>The first vhost on this list (the first vhost that appears after the
+corresponding <code>NameVirtualHost</code> directive in the config file)
+has the highest priority and catches any request to an unknown
+server name or a request without a <code>Host:</code> header.
+
+<p>If the client provided a <code>Host:</code> header the list is
+searched for a matching vhost and the first hit on a <code>ServerName</code>
+or <code>ServerAlias</code> is taken and the request is served from
+that vhost. A <code>Host:</code> header can contain a port number, but
+Apache always matches against the real port to which the client sent
+the request.
+
+<p>If the client submitted a HTTP/1.0 request without <code>Host:</code>
+header we don't know to what server the client tried to connect and
+any existing <code>ServerPath</code> is matched against the URI
+from the request. The first matching path on the list is used and the
+request is served from that vhost.
+
+<p>If no matching vhost could be found the request is served from the
+first vhost with a matching port number that is on the list for the IP
+to which the client connected (as already mentioned before).
+
+<h4>Persistent connections</h4>
+The IP lookup described above is only done <em>once</em> for a particular
+TCP/IP session while the name lookup is done on <em>every</em> request
+during a KeepAlive/persistent connection. In other words a client may
+request pages from different name-based vhosts during a single
+persistent connection.
+
+
+<h4>Absolute URI</h4>
+
+<p>If the URI from the request is an absolute URI, and its hostname and
+port match the main server or one of the configured virtual hosts
+<em>and</em> match the address and port to which the client sent the request,
+then the scheme/hostname/port prefix is stripped off and the remaining
+relative URI is served by the corresponding main server or virtual host.
+If it does not match, then the URI remains untouched and the request is
+taken to be a proxy request.
+
+
+<h3>Observations</h3>
+
+<ul>
+
+<li>A name-based vhost can never interfere with an IP-base vhost and
+ vice versa. IP-based vhosts can only be reached through an IP address
+ of its own address set and never through any other address.
+ The same applies to name-based vhosts, they can only be reached
+ through an IP address of the corresponding address set which must
+ be defined with a <code>NameVirtualHost</code> directive.
+ <p>
+
+<li><code>ServerAlias</code> and <code>ServerPath</code> checks are never
+ performed for an IP-based vhost.
+ <p>
+
+<li>The order of name-/IP-based, the <samp>_default_</samp>
+ vhost and the <code>NameVirtualHost</code> directive within the config
+ file is not important. Only the ordering
+ of name-based vhosts for a specific address set is significant. The one
+ name-based vhosts that comes first in the configuration file has
+ the highest priority for its corresponding address set.
+ <p>
+
+<li>For security reasons the port number given in a <code>Host:</code>
+ header is never used during the matching process. Apache always
+ uses the real port to which the client sent the request.
+ <p>
+
+<li>If a <code>ServerPath</code> directive exists which is a prefix of
+ another <code>ServerPath</code> directive that appears later in
+ the configuration file, then the former will always be matched
+ and the latter will never be matched. (That is assuming that no
+ Host header was available to disambiguate the two.)
+ <p>
+
+<li>If two IP-based vhosts have an address in common, the vhost appearing
+ first in the config file is always matched. Such a thing might happen
+ inadvertently. The server will give a warning in the error
+ logfile when it detects this.
+ <p>
+
+<li>A <code>_default_</code> vhost catches a request only if there is no
+ other vhost with a matching IP address <em>and</em> a matching port
+ number for the request. The request is only catched if the port number
+ to which the client sent the request matches the port number of your
+ <code>_default_</code> vhost which is your standard <code>Port</code>
+ by default. A wildcard port can be specified (i.e.
+ <code>_default_:*</code>) to catch requests to any available port.
+ <p>
+
+<li>The main_server is only used to serve a request if the IP address
+ and port number to which the client connected is unspecified
+ and does not match any other vhost (including a <code>_default_</code>
+ vhost). In other words the main_server only catches a request for an
+ unspecified address/port combination (unless there is a <code>_default_</code>
+ vhost which matches that port).
+ <p>
+
+<li>A <code>_default_</code> vhost or the main_server is <em>never</em>
+ matched for a request with an unknown or missing <code>Host:</code> header
+ if the client connected to an address (and port) which is used
+ for name-based vhosts, e.g. in a <code>NameVirtualHost</code> directive.
+ <p>
+
+<li>You should never specify DNS names in <code>VirtualHost</code>
+ directives because it will force your server to rely on DNS to boot.
+ Furthermore it poses a security threat if you do not control the
+ DNS for all the domains listed.
+ There's <a href="../dns-caveats.html">more information</a>
+ available on this and the next two topics.
+ <p>
+
+<li><code>ServerName</code> should always be set for each vhost. Otherwise
+ A DNS lookup is required for each vhost.
+ <p>
+
+</ul>
+
+<h3>Tips</h3>
+
+<p>In addition to the tips on the <a href="../dns-caveats.html#tips">DNS
+Issues</a> page, here are some further tips:
+
+<ul>
+
+<li>Place all main_server definitions before any <code>VirtualHost</code>
+ definitions. (This is to aid the readability of the configuration --
+ the post-config merging process makes it non-obvious that definitions
+ mixed in around virtual hosts might affect all virtual hosts.)
+ <p>
+
+<li>Group corresponding <code>NameVirtualHost</code> and
+ <code>VirtualHost</code> definitions in your configuration to ensure
+ better readability.
+ <p>
+
+<li>Avoid <code>ServerPaths</code> which are prefixes of other
+ <code>ServerPaths</code>. If you cannot avoid this then you have to
+ ensure that the longer (more specific) prefix vhost appears earlier in
+ the configuration file than the shorter (less specific) prefix
+ (<EM>i.e.</EM>, "ServerPath /abc" should appear after
+ "ServerPath /abc/def").
+ <p>
+
+</ul>
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html><head>
+<title>VirtualHost Examples</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">Virtual Host examples for common setups</h1>
+
+
+<h2>Base configuration</h2>
+
+<ul>
+<li><A HREF="#ip">IP-based vhosts only</A>
+<li><A HREF="#name">Name-based vhosts only</A>
+<li><A HREF="#mixed">Mixed name-/IP-based vhosts</A>
+<li><A HREF="#port">Port-based vhosts</A>
+</ul>
+
+<h2>Additional features</h2>
+
+<ul>
+<li><A HREF="#default">Using <code>_default_</code> vhosts</A>
+<li><A HREF="#migrate">Migrating a named-based vhost to an IP-based vhost</A>
+<li><A HREF="#serverpath">Using the <code>ServerPath</code> directive</A>
+</ul>
+
+<HR>
+
+<h3><A NAME="ip">IP-based vhosts only</A></h3>
+
+<ul>
+
+<li><b>Setup 1:</b>
+ The server machine has two IP addresses (<samp>111.22.33.44</samp>
+ and <samp>111.22.33.55</samp>)
+ which resolve to the names <samp>server.domain.tld</samp> and
+ <samp>www.otherdomain.tld</samp> respectively.
+ The hostname <samp>www.domain.tld</samp> is an alias (CNAME)
+ for <samp>server.domain.tld</samp> and will represent the
+ main server.
+ <p>
+ <b>Server configuration:</b>
+
+
+ <blockquote><pre>
+ ...
+ Port 80
+ DocumentRoot /www/domain
+ ServerName www.domain.tld
+
+ <VirtualHost 111.22.33.55>
+ DocumentRoot /www/otherdomain
+ ServerName www.otherdomain.tld
+ ...
+ </VirtualHost>
+ </pre>
+ <samp>www.otherdomain.tld</samp> can only be reached through the
+ address <samp>111.22.33.55</samp>, while <samp>www.domain.tld</samp>
+ can only be reached through <samp>111.22.33.44</samp>
+ (which represents our main server).
+ </blockquote>
+ <p>
+
+<li><b>Setup 2:</b>
+ Same as setup 1, but we don't want to have a dedicated main server.
+ <p>
+ <b>Server configuration:</b>
+
+ <blockquote><pre>
+ ...
+ Port 80
+ ServerName server.domain.tld
+
+ <VirtualHost 111.22.33.44>
+ DocumentRoot /www/domain
+ ServerName www.domain.tld
+ ...
+ </VirtualHost>
+
+ <VirtualHost 111.22.33.55>
+ DocumentRoot /www/otherdomain
+ ServerName www.otherdomain.tld
+ ...
+ </VirtualHost>
+ </pre>
+ The main server can never catch a request, because all IP address
+ of our machine are in use for IP-based virtual hosts
+ (only <samp>localhost</samp> requests can hit the main server).
+ </blockquote>
+ <p>
+
+<li><b>Setup 3:</b>
+ The server machine has two IP addresses (<samp>111.22.33.44</samp>
+ and <samp>111.22.33.55</samp>)
+ which resolve to the names <samp>server.domain.tld</samp> and
+ <samp>www-cache.domain.tld</samp> respectively.
+ The hostname <samp>www.domain.tld</samp> is an alias (CNAME)
+ for <samp>server.domain.tld</samp> and will represent the
+ main server.
+ <samp>www-cache.domain.tld</samp> will become our proxy-cache
+ listening on port 8080, while the web server itself uses the default
+ port 80.
+ <p>
+ <b>Server configuration:</b>
+
+ <blockquote><pre>
+ ...
+ Port 80
+ Listen 111.22.33.44:80
+ Listen 111.22.33.55:8080
+ ServerName server.domain.tld
+
+ <VirtualHost 111.22.33.44:80>
+ DocumentRoot /www/domain
+ ServerName www.domain.tld
+ ...
+ </VirtualHost>
+
+ <VirtualHost 111.22.33.55:8080>
+ ServerName www-cache.domain.tld
+ ...
+ <Directory proxy:>
+ order deny,allow
+ deny from all
+ allow from 111.22.33
+ </Directory>
+ </VirtualHost>
+ </pre>
+ The main server can never catch a request, because all IP addresss
+ (apart from <samp>localhost</samp>) of our machine are in use for IP-based
+ virtual hosts. The web server can only be reached on the first address
+ through port 80 and the proxy only on the second address through port 8080.
+ </blockquote>
+</ul>
+<HR>
+
+<h3><A NAME="name">Name-based vhosts only</A></h3>
+
+<ul>
+
+<li><b>Setup 1:</b>
+ The server machine has one IP address (<samp>111.22.33.44</samp>)
+ which resolves to the name <samp>server.domain.tld</samp>.
+ There are two aliases (CNAMEs) <samp>www.domain.tld</samp> and
+ <samp>www.sub.domain.tld</samp> for the address <samp>111.22.33.44</samp>.
+ <p>
+ <b>Server configuration:</b>
+
+ <blockquote><pre>
+ ...
+ Port 80
+ ServerName server.domain.tld
+
+ NameVirtualHost 111.22.33.44
+
+ <VirtualHost 111.22.33.44>
+ DocumentRoot /www/domain
+ ServerName www.domain.tld
+ ...
+ </VirtualHost>
+
+ <VirtualHost 111.22.33.44>
+ DocumentRoot /www/subdomain
+ ServerName www.sub.domain.tld
+ ...
+ </VirtualHost>
+ </pre>
+ Apart from <samp>localhost</samp> there are no unspecified
+ addresses/ports, therefore the main server only serves
+ <samp>localhost</samp> requests. Due to the fact
+ that <samp>www.domain.tld</samp> has the highest priority
+ it can be seen as the <cite>default</cite> or
+ <cite>primary</cite> server.
+ </blockquote>
+ <p>
+
+<li><b>Setup 2:</b>
+ The server machine has two IP addresses (<samp>111.22.33.44</samp>
+ and <samp>111.22.33.55</samp>)
+ which resolve to the names <samp>server1.domain.tld</samp> and
+ <samp>server2.domain.tld</samp> respectively.
+ The alias <samp>www.domain.tld</samp> should be used for the
+ main server which should also catch any unspecified addresses.
+ We want to use a virtual host for the alias
+ <samp>www.otherdomain.tld</samp> and one virtual host should
+ catch any request to hostnames of the form
+ <samp>*.sub.domain.tld</samp> with <samp>www.sub.domain.tld</samp>
+ as its server name. The address <samp>111.22.33.55</samp> should be
+ used for the virtual hosts.
+ <p>
+ <b>Server configuration:</b>
+
+ <blockquote><pre>
+ ...
+ Port 80
+ ServerName www.domain.tld
+ DocumentRoot /www/domain
+
+ NameVirtualHost 111.22.33.55
+
+ <VirtualHost 111.22.33.55>
+ DocumentRoot /www/otherdomain
+ ServerName www.otherdomain.tld
+ ...
+ </VirtualHost>
+
+ <VirtualHost 111.22.33.55>
+ DocumentRoot /www/subdomain
+ ServerName www.sub.domain.tld
+ ServerAlias *.sub.domain.tld
+ ...
+ </VirtualHost>
+ </pre>
+ Any request to an address other than <samp>111.22.33.55</samp>
+ will be served from the main server. A request to
+ <samp>111.22.33.55</samp> with an unknown or no <code>Host:</code>
+ header will be served from <samp>www.otherdomain.tld</samp>.
+ </blockquote>
+</ul>
+
+<HR>
+
+<h3><A NAME="mixed">Mixed name-/IP-based vhosts</A></h3>
+
+<Ul>
+
+<li><b>Setup:</b>
+ The server machine has three IP addresses (<samp>111.22.33.44</samp>,
+ <samp>111.22.33.55</samp> and <samp>111.22.33.66</samp>)
+ which resolve to the names <samp>server.domain.tld</samp>,
+ <samp>www.otherdomain1.tld</samp> and <samp>www.otherdomain2.tld</samp>
+ respectively.
+ The address <samp>111.22.33.44</samp> should we used for a couple
+ of name-based vhosts and the other addresses for IP-based vhosts.
+ <p>
+ <b>Server configuration:</b>
+
+ <blockquote><pre>
+ ...
+ Port 80
+ ServerName server.domain.tld
+
+ NameVirtualHost 111.22.33.44
+
+ <VirtualHost 111.22.33.44>
+ DocumentRoot /www/domain
+ ServerName www.domain.tld
+ ...
+ </VirtualHost>
+
+ <VirtualHost 111.22.33.44>
+ DocumentRoot /www/subdomain1
+ ServerName www.sub1.domain.tld
+ ...
+ </VirtualHost>
+
+ <VirtualHost 111.22.33.44>
+ DocumentRoot /www/subdomain2
+ ServerName www.sub2.domain.tld
+ ...
+ </VirtualHost>
+
+ <VirtualHost 111.22.33.55>
+ DocumentRoot /www/otherdomain1
+ ServerName www.otherdomain1.tld
+ ...
+ </VirtualHost>
+
+ <VirtualHost 111.22.33.66>
+ DocumentRoot /www/otherdomain2
+ ServerName www.otherdomain2.tld
+ ...
+ </VirtualHost>
+ </pre></blockquote>
+
+</ul>
+
+<HR>
+
+<h3><A NAME="port">Port-based vhosts</A></h3>
+
+<ul>
+
+<li><b>Setup:</b>
+ The server machine has one IP address (<samp>111.22.33.44</samp>)
+ which resolves to the name <samp>www.domain.tld</samp>.
+ If we don't have the option to get another address or alias
+ for our server we can use port-based vhosts if we need
+ a virtual host with a different configuration.
+ <p>
+ <b>Server configuration:</b>
+
+ <blockquote><pre>
+ ...
+ Listen 80
+ Listen 8080
+ ServerName www.domain.tld
+ DocumentRoot /www/domain
+
+ <VirtualHost 111.22.33.44:8080>
+ DocumentRoot /www/domain2
+ ...
+ </VirtualHost>
+ </pre>
+ A request to <samp>www.domain.tld</samp> on port 80 is served
+ from the main server and a request to port 8080 is served from
+ the virtual host.
+ </blockquote>
+</ul>
+
+<HR>
+
+<h3><A NAME="default">Using <code>_default_</code> vhosts</A></h3>
+
+<ul>
+
+<li><b>Setup 1:</b>
+ Catching <em>every</em> request to any unspecified IP address and port,
+ i.e. an address/port combination that is not used for any other
+ virtual host.
+ <p>
+ <b>Server configuration:</b>
+
+ <blockquote><pre>
+ ...
+ <VirtualHost _default_:*>
+ DocumentRoot /www/default
+ ...
+ </VirtualHost>
+ </pre>
+ Using such a default vhost with a wildcard port effectively
+ prevents any request going to the main server.<br>
+ A default vhost never serves a request that was sent to an
+ address/port that is used for name-based vhosts. If the request
+ contained an unknown or no <code>Host:</code> header it is
+ always served from the primary name-based vhost (the
+ vhost for that address/port appearing first in the configuration
+ file).<br>
+ You can use
+ <A HREF="../mod/mod_alias.html#aliasmatch"><code>AliasMatch</code></A>
+ or
+ <A HREF="../mod/mod_rewrite.html#RewriteRule"><code>RewriteRule</code></A>
+ to rewrite any request to a single information page (or script).
+ </blockquote>
+ <p>
+
+<li><b>Setup 2:</b>
+ Same as setup 1, but the server listens on several ports and
+ we want to use a second <code>_default_</code> vhost for port 80.
+ <p>
+ <b>Server configuration:</b>
+
+ <blockquote><pre>
+ ...
+ <VirtualHost _default_:80>
+ DocumentRoot /www/default80
+ ...
+ </VirtualHost>
+
+ <VirtualHost _default_:*>
+ DocumentRoot /www/default
+ ...
+ </VirtualHost>
+ </pre>
+ The default vhost for port 80 (which <em>must</em> appear before
+ any default vhost with a wildcard port) catches all requests that
+ were sent to an unspecified IP address. The main server is
+ never used to serve a request.
+ </blockquote>
+ <p>
+
+<li><b>Setup 3:</b>
+ We want to have a default vhost for port 80, but no other default vhosts.
+ <p>
+ <b>Server configuration:</b>
+
+ <blockquote><pre>
+ ...
+ <VirtualHost _default_:80>
+ DocumentRoot /www/default
+ ...
+ </VirtualHost>
+ </pre>
+ A request to an unspecified address on port 80 is served from the
+ default vhost any other request to an unspecified address and port
+ is served from the main server.
+ </blockquote>
+
+</ul>
+
+<HR>
+
+<h3><A NAME="migrate">Migrating a name-based vhost to an IP-based vhost</A></h3>
+
+<ul>
+
+<li><b>Setup:</b>
+ The name-based vhost with the hostname
+ <samp>www.otherdomain.tld</samp> (from our <a href="#name">name-based</A>
+ example, setup 2) should get its own IP address.
+ To avoid problems with name servers or proxies who cached the old
+ IP address for the name-based vhost we want to provide both variants
+ during a migration phase.<br>
+ The solution is easy, because we can simply add the new IP address
+ (<samp>111.22.33.66</samp>) to the <code>VirtualHost</code> directive.
+ <p>
+ <b>Server configuration:</b>
+
+ <blockquote><pre>
+ ...
+ Port 80
+ ServerName www.domain.tld
+ DocumentRoot /www/domain
+
+ NameVirtualHost 111.22.33.55
+
+ <VirtualHost 111.22.33.55 111.22.33.66>
+ DocumentRoot /www/otherdomain
+ ServerName www.otherdomain.tld
+ ...
+ </VirtualHost>
+
+ <VirtualHost 111.22.33.55>
+ DocumentRoot /www/subdomain
+ ServerName www.sub.domain.tld
+ ServerAlias *.sub.domain.tld
+ ...
+ </VirtualHost>
+ </pre>
+ The vhost can now be accessed through the new address (as an IP-based
+ vhost) and through the old address (as a name-based vhost).
+ </blockquote>
+
+</ul>
+
+<HR>
+
+<h3><A NAME="serverpath">Using the <code>ServerPath</code> directive</A></h3>
+
+<ul>
+
+<li><b>Setup:</b>
+ We have a server with two name-based vhosts. In order to match the correct
+ virtual host a client must send the correct <code>Host:</code> header.
+ Old HTTP/1.0 clients do not send such a header and Apache has no clue
+ what vhost the client tried to reach (and serves the request from
+ the primary vhost). To provide as much backward compatibility
+ as possible we create a primary vhost which returns a single page
+ containing links with an URL prefix to the name-based virtual hosts.
+ <p>
+ <b>Server configuration:</b>
+
+ <blockquote><pre>
+ ...
+ NameVirtualHost 111.22.33.44
+
+ <VirtualHost 111.22.33.44>
+ # primary vhost
+ DocumentRoot /www/subdomain
+ RewriteEngine On
+ RewriteRule ^/.* /www/subdomain/index.html
+ ...
+ </VirtualHost>
+
+ <VirtualHost 111.22.33.44>
+ DocumentRoot /www/subdomain/sub1
+ ServerName www.sub1.domain.tld
+ ServerPath /sub1/
+ RewriteEngine On
+ RewriteRule ^(/sub1/.*) /www/subdomain$1
+ ...
+ </VirtualHost>
+
+ <VirtualHost 111.22.33.44>
+ DocumentRoot /www/subdomain/sub2
+ ServerName www.sub2.domain.tld
+ ServerPath /sub2/
+ RewriteEngine On
+ RewriteRule ^(/sub2/.*) /www/subdomain$1
+ ...
+ </VirtualHost>
+ </pre>
+ Due to the <A HREF="../mod/core.html#serverpath"><code>ServerPath</code></A>
+ directive a request to the
+ URL <samp>http://www.sub1.domain.tld/sub1/</samp> is <em>always</em>
+ served from the sub1-vhost. <br>
+ A request to the URL <samp>http://www.sub1.domain.tld/</samp>
+ is only served from the sub1-vhost if the client sent a correct
+ <code>Host:</code> header.
+ If no <code>Host:</code> header is sent the client gets the
+ information page from the primary host.<br>
+ Please note that there is one oddity: A request to
+ <samp>http://www.sub2.domain.tld/sub1/</samp> is also served from
+ the sub1-vhost if the client sent no <code>Host:</code> header. <br>
+ The <code>RewriteRule</code> directives are used to make sure that
+ a client which sent a correct <code>Host:</code> header can use
+ both URL variants, i.e. with or without URL prefix.
+ </blockquote>
+
+</ul>
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<title>Apache Server Virtual Host 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">File Descriptor Limits</h1>
+
+<P>
+When using a large number of Virtual Hosts, Apache may run out of available
+file descriptors (sometimes called <cite>file handles</cite> if each Virtual
+Host specifies different log files.
+The total number of file descriptors used by Apache is one for each distinct
+error log file, one for every other log file directive, plus 10-20 for
+internal use. Unix operating systems limit the number of file descriptors that
+may be used by a process; the limit is typically 64, and may usually be
+increased up to a large hard-limit.
+<p>
+Although Apache attempts to increase the limit as required, this
+may not work if:
+<ol>
+<li>Your system does not provide the setrlimit() system call.
+<li>The setrlimit(RLIMIT_NOFILE) call does not function on your system
+ (such as Solaris 2.3)
+<li>The number of file descriptors required exceeds the hard limit.
+<li>Your system imposes other limits on file descriptors, such as a limit
+on stdio streams only using file descriptors below 256. (Solaris 2)
+</ol>
+
+In the event of problems you can:
+<ul>
+<li>Reduce the number of log files; don't specify log files in the VirtualHost
+sections, but only log to the main log files.
+<li>If you system falls into 1 or 2 (above), then increase the file descriptor
+limit before starting Apache, using a script like
+<blockquote><code>
+#!/bin/sh <br>
+ulimit -S -n 100 <br>
+exec httpd</code></blockquote>
+</ul>
+<P>
+Please see the
+<A HREF="../misc/descriptors.html">Descriptors and Apache</A>
+document containing further details about file descriptor problems and how
+they can be solved on your operating system.
+</P>
+
+<!--#include virtual="footer.html" -->
+</body></html>
+
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<title>Apache Server Virtual Host 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">File Descriptor Limits</h1>
+
+<P>
+When using a large number of Virtual Hosts, Apache may run out of available
+file descriptors (sometimes called <cite>file handles</cite> if each Virtual
+Host specifies different log files.
+The total number of file descriptors used by Apache is one for each distinct
+error log file, one for every other log file directive, plus 10-20 for
+internal use. Unix operating systems limit the number of file descriptors that
+may be used by a process; the limit is typically 64, and may usually be
+increased up to a large hard-limit.
+<p>
+Although Apache attempts to increase the limit as required, this
+may not work if:
+<ol>
+<li>Your system does not provide the setrlimit() system call.
+<li>The setrlimit(RLIMIT_NOFILE) call does not function on your system
+ (such as Solaris 2.3)
+<li>The number of file descriptors required exceeds the hard limit.
+<li>Your system imposes other limits on file descriptors, such as a limit
+on stdio streams only using file descriptors below 256. (Solaris 2)
+</ol>
+
+In the event of problems you can:
+<ul>
+<li>Reduce the number of log files; don't specify log files in the VirtualHost
+sections, but only log to the main log files.
+<li>If you system falls into 1 or 2 (above), then increase the file descriptor
+limit before starting Apache, using a script like
+<blockquote><code>
+#!/bin/sh <br>
+ulimit -S -n 100 <br>
+exec httpd</code></blockquote>
+</ul>
+<P>
+Please see the
+<A HREF="../misc/descriptors.html">Descriptors and Apache</A>
+document containing further details about file descriptor problems and how
+they can be solved on your operating system.
+</P>
+
+<!--#include virtual="footer.html" -->
+</body></html>
+
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+<TITLE>Apache Virtual Host 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 Virtual Host documentation</h1>
+
+<p>The term <cite>Virtual Host</cite> refers to the practice of maintaining
+more than one server on one machine, as differentiated by their apparent
+hostname. For example, it is often desirable for companies sharing a
+web server to have their own domains, with web servers accessible as
+<samp>www.company1.com</samp> and <samp>www.company2.com</samp>,
+without requiring the user to know any extra path information.</p>
+
+<p>Apache was one of the first servers to support IP-based
+virtual hosts right out of the box. Versions 1.1 and later of
+Apache support both, IP-based and name-based virtual hosts (vhosts).
+The latter variant of virtual hosts is sometimes also called host-based or
+non-IP virtual hosts.</P>
+
+<P>Below is a list of documentation pages which explain all details
+of virtual host support in Apache version 1.3 and later.</P>
+
+<HR>
+
+<H2>Virtual Host Support</H2>
+
+<UL>
+<LI><A HREF="ip-based.html">IP-based Virtual Hosts</A>
+<LI><A HREF="name-based.html">Name-based Virtual Hosts</A>
+<LI><A HREF="examples.html">Virtual Host examples for common setups</A>
+<LI><A HREF="details.html">In-Depth Discussion of Virtual Host Matching</A>
+<LI><A HREF="fd-limits.html">File Descriptor Limits</A>
+</UL>
+
+<H2>Configuration directives</H2>
+
+<UL>
+<LI><A HREF="../mod/core.html#virtualhost"><VirtualHost></A>
+<LI><A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A>
+<LI><A HREF="../mod/core.html#servername">ServerName</A>
+<LI><A HREF="../mod/core.html#serveralias">ServerAlias</A>
+<LI><A HREF="../mod/core.html#serverpath">ServerPath</A>
+</UL>
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+<TITLE>Apache Virtual Host 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 Virtual Host documentation</h1>
+
+<p>The term <cite>Virtual Host</cite> refers to the practice of maintaining
+more than one server on one machine, as differentiated by their apparent
+hostname. For example, it is often desirable for companies sharing a
+web server to have their own domains, with web servers accessible as
+<samp>www.company1.com</samp> and <samp>www.company2.com</samp>,
+without requiring the user to know any extra path information.</p>
+
+<p>Apache was one of the first servers to support IP-based
+virtual hosts right out of the box. Versions 1.1 and later of
+Apache support both, IP-based and name-based virtual hosts (vhosts).
+The latter variant of virtual hosts is sometimes also called host-based or
+non-IP virtual hosts.</P>
+
+<P>Below is a list of documentation pages which explain all details
+of virtual host support in Apache version 1.3 and later.</P>
+
+<HR>
+
+<H2>Virtual Host Support</H2>
+
+<UL>
+<LI><A HREF="ip-based.html">IP-based Virtual Hosts</A>
+<LI><A HREF="name-based.html">Name-based Virtual Hosts</A>
+<LI><A HREF="examples.html">Virtual Host examples for common setups</A>
+<LI><A HREF="details.html">In-Depth Discussion of Virtual Host Matching</A>
+<LI><A HREF="fd-limits.html">File Descriptor Limits</A>
+</UL>
+
+<H2>Configuration directives</H2>
+
+<UL>
+<LI><A HREF="../mod/core.html#virtualhost"><VirtualHost></A>
+<LI><A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A>
+<LI><A HREF="../mod/core.html#servername">ServerName</A>
+<LI><A HREF="../mod/core.html#serveralias">ServerAlias</A>
+<LI><A HREF="../mod/core.html#serverpath">ServerPath</A>
+</UL>
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<title>Apache IP-based Virtual Host 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 IP-based Virtual Host Support</h1>
+
+<strong>See also:</strong>
+<a href="name-based.html">Name-based Virtual Hosts Support</a>
+
+<HR>
+
+<h2>System requirements</h2>
+As the term <cite>IP-based</cite> indicates, the server <strong>must have a
+different IP address for each IP-based virtual host</strong>.
+This can be achieved by the machine having several physical network connections,
+or by use of virtual interfaces which are supported by most modern
+operating systems (see system documentation for details).
+
+<h2>How to set up Apache</h2>
+There are two ways of configuring apache to support multiple hosts.
+Either by running a separate httpd daemon for each hostname, or by running a
+single daemon which supports all the virtual hosts.
+<p>
+Use multiple daemons when:
+<ul>
+<li>The different virtual hosts need very different httpd configurations, such
+ as different values for: <A HREF="../mod/core.html#servertype">ServerType</A>,
+ <A HREF="../mod/core.html#user">User</A>,
+ <A HREF="../mod/core.html#group">Group</A>,
+ <A HREF="../mod/mod_mime.html#typesconfig">TypesConfig</A> or
+ <A HREF="../mod/core.html#serverroot">ServerRoot</A>.
+<li>The machine does not process a very high request rate.
+</ul>
+Use a single daemon when:
+<ul>
+<li>Sharing of the httpd configuration between virtual hosts is acceptable.
+<li>The machine services a large number of requests, and so the performance
+ loss in running separate daemons may be significant.
+</ul>
+
+<h2>Setting up multiple daemons</h2>
+Create a separate httpd installation for each virtual host.
+For each installation, use the
+<A HREF="../mod/core.html#listen">Listen</A> directive in the configuration
+file to select which IP address (or virtual host) that daemon services.
+e.g.
+<pre>
+ Listen www.smallco.com:80
+</pre>
+It is recommended that you use an IP address instead of a hostname
+(see <A HREF="../dns-caveats.html">DNS page</A>).
+
+<h2>Setting up a single daemon with virtual hosts</h2>
+For this case, a single httpd will service requests for the main server
+and all the virtual hosts.
+The <A HREF="../mod/core.html#virtualhost">VirtualHost</A> directive in the
+ configuration file is used to set the values of
+<A HREF="../mod/core.html#serveradmin">ServerAdmin</A>,
+<A HREF="../mod/core.html#servername">ServerName</A>,
+<A HREF="../mod/core.html#documentroot">DocumentRoot</A>,
+<A HREF="../mod/core.html#errorlog">ErrorLog</A> and
+<A HREF="../mod/mod_log_config.html#transferlog">TransferLog</A> or
+<A HREF="../mod/mod_log_config.html#customlog">CustomLog</A>
+configuration directives to different values for each virtual host.
+e.g.
+<pre>
+ <VirtualHost www.smallco.com>
+ ServerAdmin webmaster@mail.smallco.com
+ DocumentRoot /groups/smallco/www
+ ServerName www.smallco.com
+ ErrorLog /groups/smallco/logs/error_log
+ TransferLog /groups/smallco/logs/access_log
+ </VirtualHost>
+
+ <VirtualHost www.baygroup.org>
+ ServerAdmin webmaster@mail.baygroup.org
+ DocumentRoot /groups/baygroup/www
+ ServerName www.baygroup.org
+ ErrorLog /groups/baygroup/logs/error_log
+ TransferLog /groups/baygroup/logs/access_log
+ </VirtualHost>
+</pre>
+
+It is recommended that you use an IP address instead of a hostname
+(see <A HREF="../dns-caveats.html">DNS page</A>).
+
+<P>
+
+Almost <strong>any</strong> configuration directive can be put
+in the VirtualHost directive, with the exception of
+<A HREF="../mod/core.html#servertype">ServerType</A>,
+<A HREF="../mod/core.html#startservers">StartServers</A>,
+<A HREF="../mod/core.html#maxspareservers">MaxSpareServers</A>,
+<A HREF="../mod/core.html#minspareservers">MinSpareServers</A>,
+<A HREF="../mod/core.html#maxrequestsperchild">MaxRequestsPerChild</A>,
+<A HREF="../mod/core.html#bindaddress">BindAddress</A>,
+<A HREF="../mod/core.html#listen">Listen</A>,
+<A HREF="../mod/core.html#pidfile">PidFile</A>,
+<A HREF="../mod/mod_mime.html#typesconfig">TypesConfig</A>,
+<A HREF="../mod/core.html#serverroot">ServerRoot</A> and
+<A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A>.
+<P>
+<A HREF="../mod/core.html#user">User</A> and
+<A HREF="../mod/core.html#group">Group</A> maybe used inside a VirtualHost
+directive if the <A HREF="../suexec.html">suEXEC wrapper</A> is used.
+<P>
+
+<EM>SECURITY:</EM> When specifying where to write log files, be aware
+of some security risks which are present if anyone other than the
+user that starts Apache has write access to the directory where they
+are written. See the <A HREF="../misc/security_tips.html">security
+tips</A> document for details.
+</P>
+
+<!--#include virtual="footer.html" -->
+</body>
+</html>
+
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML><HEAD>
+<TITLE>Dynamically configured mass virtual hosting</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">Dynamically configured mass virtual hosting</H1>
+
+<P>This document describes how to efficiently serve an arbitrary number
+of virtual hosts with Apache 1.3. Some familiarity with
+<A HREF="../mod/mod_rewrite.html"><CODE>mod_rewrite</CODE></A> is
+useful.</P>
+
+<!--
+
+Written by Tony Finch (fanf@demon.net) (dot@dotat.at).
+
+Some examples were derived from Ralf S. Engleschall's document
+ http://www.engelschall.com/pw/apache/rewriteguide/
+
+Some suggestions were made by Brian Behlendorf.
+
+-->
+
+<H2><A NAME="contents">Contents:</A></H2>
+
+<UL>
+<LI><A HREF="#motivation">Motivation</A>
+<LI><A HREF="#overview">Overview of the technique</A>
+<LI><A HREF="#simple">Simple name-based dynamic virtual hosts</A>
+<LI><A HREF="#homepages">A virtually hosted homepages system</A>
+<LI><A HREF="#xtra-conf">Using a separate virtual host configuration file</A>
+<LI><A HREF="#combinations">Using more than one virtual hosting system on the same server</A>
+</UL>
+
+<HR><H2><A NAME="motivation">Motivation</A></H2>
+
+<P>The techniques described here are of interest if your
+<CODE>httpd.conf</CODE> contains hundreds of
+<CODE><VirtualHost></CODE> sections that are substantially the
+same, for example:
+<PRE>
+NameVirtualHost 111.22.33.44
+<VirtualHost 111.22.33.44>
+ ServerName www.customer-1.com
+ DocumentRoot /www/hosts/www.customer-1.com/docs
+ ScriptAlias /cgi-bin/ /www/hosts/www.customer-1.com/cgi-bin
+</VirtualHost>
+<VirtualHost 111.22.33.44>
+ ServerName www.customer-2.com
+ DocumentRoot /www/hosts/www.customer-2.com/docs
+ ScriptAlias /cgi-bin/ /www/hosts/www.customer-2.com/cgi-bin
+</VirtualHost>
+# blah blah blah
+<VirtualHost 111.22.33.44>
+ ServerName www.customer-N.com
+ DocumentRoot /www/hosts/www.customer-N.com/docs
+ ScriptAlias /cgi-bin/ /www/hosts/www.customer-N.com/cgi-bin
+</VirtualHost>
+</PRE>
+</P>
+
+<P>The basic idea is to replace all of the static
+<CODE><VirtualHost></CODE> configuration with a mechanism that
+works it out dynamically. This has a number of advantages:
+<OL>
+ <LI>Your configuration file is smaller so Apache starts faster and
+ uses less memory.
+ <LI>Adding virtual hosts is simply a matter of creating the
+ appropriate directories in the filesystem and entries in the DNS -
+ you don't need to reconfigure or restart Apache.
+</OL>
+</P>
+
+<P>The main disadvantage is that you cannot have a different log file
+for each server; however if you have very many virtual hosts then
+doing this is dubious anyway because it eats file descriptors. It's
+better to log to a pipe or a fifo and arrange for the process at the
+other end to distribute the logs (and perhaps accumulate statistics,
+etc.). A <CODE>LogFormat</CODE> directive that includes
+<CODE>%v</CODE> for the virtual host makes it easy to do this.</P>
+
+
+<HR><H2><A NAME="overview">Overview of the technique</A></H2>
+
+<P>All of the dynamic virtual hosts will either be configured as part
+of the main server configuration, or within a
+<CODE><VirtualHost></CODE> section. For a simple (very uniform)
+setup, <CODE><VirtualHost></CODE> sections aren't needed at all.</P>
+
+<P>A couple of things need to be `faked' to make the dynamic virtual
+host look like a normal one. The most important is the server name
+(configured with <CODE>ServerName</CODE> and available to CGIs via the
+<CODE>SERVER_NAME</CODE> environment variable). The way it is
+determined is controlled by the <CODE>UseCanonicalName</CODE>
+directive: with <CODE>UseCanonicalName off</CODE> the server name
+comes from the contents of the <CODE>Host:</CODE> header in the
+request. If there is no <CODE>Host:</CODE> header then the value
+configured with <CODE>ServerName</CODE> is used instead.</P>
+
+<P>The other one is the document root (configured with
+<CODE>DocumentRoot</CODE> and available to CGIs via the
+<CODE>DOCUMENT_ROOT</CODE> environment variable). This is used by the
+core module when mapping URIs to filenames, but in the context of
+dynamic virtual hosting its value only matters if any CGIs or SSI
+documents make use of the <CODE>DOCUMENT_ROOT</CODE> environment
+variable. This is an Apache extension to the CGI specification and as
+such shouldn't really be relied upon, especially because this
+technique breaks it: there isn't currently a way of setting
+<CODE>DOCUMENT_ROOT</CODE> dynamically.</P>
+
+<P>The meat of the mechanism works via Apache's URI-to-filename
+translation API phase. This is used by a number of modules:
+<A HREF="../mod/mod_rewrite.html"><CODE>mod_rewrite</CODE></A>,
+<A HREF="../mod/mod_alias.html"><CODE>mod_alias</CODE></A>,
+<A HREF="../mod/mod_userdir.html"><CODE>mod_userdir</CODE></A>,
+and <A HREF="../mod/core.html">the core module</A>.
+In the default configuration these modules are called in that order
+and given a chance to say that they know what the filename is. Most of
+these modules do it in a fairly simple fashion (e.g. the core module
+concatenates the document root and the URI) except for
+<CODE>mod_rewrite</CODE>, which provides enough functionality to do
+all sorts of sick and twisted things (like dynamic virtual hosting).
+Note that because of the order in which the modules are called, using
+a <CODE>mod_rewrite</CODE> configuration that matches any URI means
+that the other modules (particularly <CODE>mod_alias</CODE>) will
+cease to function. The examples below show how to deal with this.</P>
+
+<P><STRONG>The dynamic virtual hosting idea is very simple: use the
+server name as well as the URI to determine the corresponding
+filename.</STRONG></P>
+
+
+<HR><H2><A NAME="simple">Simple name-based dynamic virtual hosts</A></H2>
+
+<P>This extract from <CODE>httpd.conf</CODE> implements the virtual
+host arrangement outlined in the <A HREF="#motivation">Motivation</A>
+section above, but in a generic fashion.</P>
+
+<P>The first half shows some other configuration options that are
+needed to make the <CODE>mod_rewrite</CODE> part work as expected; the
+second half uses <CODE>mod_rewrite</CODE> to do the actual work. Some
+care is taken to do a per-dynamic-virtual-host equivalent of
+<CODE>ScriptAlias</CODE>.</P>
+
+<PRE>
+# dynamic ServerName
+UseCanonicalName Off
+
+# splittable logs
+LogFormat "%v %h %l %u %t \"%r\" %s %b" vcommon
+CustomLog logs/access_log vcommon
+
+<Directory /www/hosts>
+ # ExecCGI is needed here because we can't force
+ # CGI execution in the way that ScriptAlias does
+ Options FollowSymLinks ExecCGI
+</Directory>
+
+# now for the hard bit
+
+RewriteEngine On
+
+# a ServerName derived from a Host: header may be any case at all
+RewriteMap lowercase int:tolower
+
+## deal with normal documents first:
+# allow Alias /icons/ to work - repeat for other aliases
+RewriteCond %{REQUEST_URI} !^/icons/
+# allow CGIs to work
+RewriteCond %{REQUEST_URI} !^/cgi-bin/
+# do the magic
+RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1
+
+## and now deal with CGIs - we have to force a MIME type
+RewriteCond %{REQUEST_URI} ^/cgi-bin/
+RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi]
+
+# that's it!
+</PRE>
+
+
+<HR><H2><A NAME="homepages">A virtually hosted homepages system</A></H2>
+
+<P>This is an adjustment of the above system tailored for an ISP's
+homepages server. Using slightly more complicated rewriting rules we
+can select substrings of the server name to use in the filename so
+that e.g. the documents for <SAMP>www.user.isp.com</SAMP> are found in
+<CODE>/home/user/</CODE>. It uses a single <CODE>cgi-bin</CODE>
+directory instead of one per virtual host.</P>
+
+<PRE>
+RewriteEngine on
+
+RewriteMap lowercase int:tolower
+
+# allow CGIs to work
+RewriteCond %{REQUEST_URI} !^/cgi-bin/
+
+# check the hostname is right so that the RewriteRule works
+RewriteCond ${lowercase:%{HTTP_HOST}} ^www\.[a-z-]+\.isp\.com$
+
+# concatenate the virtual host name onto the start of the URI
+# the [C] means do the next rewrite on the result of this one
+RewriteRule ^(.+) ${lowercase:%{HTTP_HOST}}$1 [C]
+
+# now create the real file name
+RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /home/$1/$2
+
+# define the global CGI directory
+ScriptAlias /cgi-bin/ /www/std-cgi/
+</PRE>
+
+
+<HR><H2><A NAME="xtra-conf">Using a separate virtual host configuration file</A></H2>
+
+<P>This arrangement uses a separate configuration file to specify the
+translation from virtual host to document root. This provides more
+flexibility but requires more configuration.</P>
+
+<P>The <CODE>vhost.map</CODE> file contains something like this:
+<PRE>
+www.customer-1.com /www/customers/1
+www.customer-2.com /www/customers/2
+# ...
+www.customer-N.com /www/customers/N
+</PRE>
+</P>
+
+<P>The <CODE>http.conf</CODE> contains this:
+<PRE>
+RewriteEngine on
+
+RewriteMap lowercase int:tolower
+
+# define the map file
+RewriteMap vhost txt:/www/conf/vhost.map
+
+# deal with aliases as above
+RewriteCond %{REQUEST_URI} !^/icons/
+RewriteCond %{REQUEST_URI} !^/cgi-bin/
+RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$
+# this does the file-based remap
+RewriteCond ${vhost:%1} ^(/.*)$
+RewriteRule ^/(.*)$ %1/docs/$1
+
+RewriteCond %{REQUEST_URI} ^/cgi-bin/
+RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$
+RewriteCond ${vhost:%1} ^(/.*)$
+RewriteRule ^/(.*)$ %1/cgi-bin/$1
+</PRE>
+</P>
+
+
+<HR><H2><A NAME="combinations">Using more than one virtual hosting system on the same server</A></H2>
+
+<P>With more complicated setups, you can use Apache's normal
+<CODE><VirtualHost></CODE> directives to control the scope of
+the various rewrite configurations. For example, you could have one IP
+address for homepages customers and another for commercial customers
+with the following setup. This can of course be combined with
+convential <CODE><VirtualHost></CODE> configuration
+sections.</P>
+
+<PRE>
+UseCanonicalName Off
+
+LogFormat "%v %h %l %u %t \"%r\" %s %b" vcommon
+CustomLog logs/access_log vcommon
+
+<Directory /www/commercial>
+ Options FollowSymLinks ExecCGI
+ AllowOverride All
+</Directory>
+
+<Directory /www/homepages>
+ Options FollowSymLinks
+ AllowOverride None
+</Directory>
+
+<VirtualHost 111.22.33.44>
+ ServerName www.commercial.isp.com
+
+ RewriteEngine On
+ RewriteMap lowercase int:tolower
+
+ RewriteCond %{REQUEST_URI} !^/icons/
+ RewriteCond %{REQUEST_URI} !^/cgi-bin/
+ RewriteRule ^/(.*)$ /www/commercial/${lowercase:%{SERVER_NAME}}/docs/$1
+
+ RewriteCond %{REQUEST_URI} ^/cgi-bin/
+ RewriteRule ^/(.*)$ /www/commercial/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi]
+</VirtualHost>
+
+<VirtualHost 111.22.33.45>
+ ServerName www.homepages.isp.com
+
+ RewriteEngine on
+ RewriteMap lowercase int:tolower
+
+ RewriteCond %{REQUEST_URI} !^/cgi-bin/
+
+ RewriteCond ${lowercase:%{HTTP_HOST}} ^www\.[a-z-]+\.isp\.com$
+ RewriteRule ^(.+) ${lowercase:%{HTTP_HOST}}$1 [C]
+ RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /www/homepages/$1/$2
+
+ ScriptAlias /cgi-bin/ /www/std-cgi/
+</VirtualHost>
+</PRE>
+
+
+<HR>
+
+<H3 ALIGN="CENTER">
+ Apache HTTP Server Version 1.3
+</H3>
+
+<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A>
+<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A>
+
+</BODY>
+</HTML>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html><head>
+<title>Apache name-based Virtual Hosts</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 name-based Virtual Host Support</h1>
+
+<strong>See Also:</strong>
+<a href="ip-based.html">IP-based Virtual Host Support</a>
+
+<hr>
+
+<h2>Name-based vs. IP-based virtual hosts</h2>
+
+<p>While the approach with IP-based virtual hosts works still very well,
+it is not the most elegant solution, because a dedicated IP address
+is needed for every virtual host and it is hard to implement on some
+machines. The <code>HTTP/1.1</code> protocol contains a method for the
+server to identify what name it is being addressed as. Apache 1.1 and
+later support this approach as well as the traditional
+IP-address-per-hostname method.</p>
+
+<p>The benefits of using the new name-based virtual host support is a
+practically unlimited number of servers, ease of configuration and use, and
+requires no additional hardware or software.
+The main disadvantage is that the client must support this part of the
+protocol. The latest versions of most browsers do, but there are still
+old browsers in use who do not. This can cause problems, although a possible
+solution is addressed below.</p>
+
+<h2>Using non-IP Virtual Hosts</h2>
+
+<p>Using the new virtual hosts is quite easy, and superficially looks
+like the old method. You simply add to one of the Apache configuration
+files (most likely <code>httpd.conf</code> or <code>srm.conf</code>)
+code similar to the following:</p>
+<pre>
+ NameVirtualHost 111.22.33.44
+
+ <VirtualHost 111.22.33.44>
+ ServerName www.domain.tld
+ DocumentRoot /web/domain
+ </VirtualHost>
+</pre>
+
+<p>The notable difference between IP-based and name-based virtual host
+configuration is the
+<A HREF="../mod/core.html#namevirtualhost"><code>NameVirtualHost</code></A>
+directive which specifies any IP address that should be used as a target for
+name-based virtual hosts.
+
+<p>Of course, any additional directives can (and should) be placed
+into the <code><VirtualHost></code> section. To make this work,
+all that is needed is to make sure that the name
+<samp>www.domain.tld</samp> is an alias (CNAME) pointing to the IP address
+<samp>111.22.33.44</samp></p>
+
+<p>Additionally, many servers may wish to be accessible by more than
+one name. For example, the example server might want to be accessible
+as <code>domain.tld</code>, or <code>www2.domain.tld</code>, assuming
+the IP addresses pointed to the same server. In fact, one might want it
+so that all addresses at <code>domain.tld</code> were picked up by the
+server. This is possible with the
+<A HREF="../mod/core.html#serveralias"><code>ServerAlias</code></A>
+directive, placed inside the <VirtualHost> section. For
+example:</p>
+
+<pre>
+ ServerAlias domain.tld *.domain.tld
+</pre>
+
+<p>Note that you can use <code>*</code> and <code>?</code> as wild-card
+characters.</p>
+
+<p>You also might need <code>ServerAlias</code> if you are
+serving local users who do not always include the domain name.
+For example, if local users are
+familiar with typing "www" or "www.foobar" then you will need to add
+<code>ServerAlias www www.foobar</code>. It isn't possible for the
+server to know what domain the client uses for their name resolution
+because the client doesn't provide that information in the request.</p>
+
+<h2>Compatibility with Older Browsers</h2>
+
+<p>As mentioned earlier, there are still some clients in use who
+do not send the required data for the name-based virtual hosts to work
+properly. These clients will always be sent the pages from the
+<cite>primary</cite> name-based virtual host (the first virtual host
+appearing in the configuration file for a specific IP address).</p>
+
+<p>There is a possible workaround with the
+<A HREF="../mod/core.html#serverpath"><code>ServerPath</code></A>
+directive, albeit a slightly cumbersome one:</p>
+
+<p>Example configuration:
+
+<pre>
+ NameVirtualHost 111.22.33.44
+
+ <VirtualHost 111.22.33.44>
+ ServerName www.domain.tld
+ ServerPath /domain
+ DocumentRoot /web/domain
+ </VirtualHost>
+</pre>
+
+<p>What does this mean? It means that a request for any URI beginning
+with "<samp>/domain</samp>" will be served from the virtual host
+<samp>www.domain.tld</samp> This means that the pages can be accessed as
+<code>http://www.domain.tld/domain/</code> for all clients, although
+clients sending a <samp>Host:</samp> header can also access it as
+<code>http://www.domain.tld/</code>.</p>
+
+<p>In order to make this work, put a link on your primary virtual host's page
+to <samp>http://www.domain.tld/domain/</samp>
+Then, in the virtual host's pages, be sure to use either purely
+relative links (e.g. "<samp>file.html</samp>" or
+"<samp>../icons/image.gif</samp>" or links containing the prefacing
+<samp>/domain/</samp>
+(e.g. "<samp>http://www.domain.tld/domain/misc/file.html</samp>" or
+"<samp>/domain/misc/file.html</samp>").</p>
+
+<p>This requires a bit of
+discipline, but adherence to these guidelines will, for the most part,
+ensure that your pages will work with all browsers, new and old.</p>
+
+<p>See also: <A HREF="examples.html#serverpath">ServerPath configuration
+example</A></p>
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html><head>
+<title>Apache name-based Virtual Hosts</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 name-based Virtual Host Support</h1>
+
+<strong>See Also:</strong>
+<a href="ip-based.html">IP-based Virtual Host Support</a>
+
+<hr>
+
+<h2>Name-based vs. IP-based virtual hosts</h2>
+
+<p>While the approach with IP-based virtual hosts works still very well,
+it is not the most elegant solution, because a dedicated IP address
+is needed for every virtual host and it is hard to implement on some
+machines. The <code>HTTP/1.1</code> protocol contains a method for the
+server to identify what name it is being addressed as. Apache 1.1 and
+later support this approach as well as the traditional
+IP-address-per-hostname method.</p>
+
+<p>The benefits of using the new name-based virtual host support is a
+practically unlimited number of servers, ease of configuration and use, and
+requires no additional hardware or software.
+The main disadvantage is that the client must support this part of the
+protocol. The latest versions of most browsers do, but there are still
+old browsers in use who do not. This can cause problems, although a possible
+solution is addressed below.</p>
+
+<h2>Using non-IP Virtual Hosts</h2>
+
+<p>Using the new virtual hosts is quite easy, and superficially looks
+like the old method. You simply add to one of the Apache configuration
+files (most likely <code>httpd.conf</code> or <code>srm.conf</code>)
+code similar to the following:</p>
+<pre>
+ NameVirtualHost 111.22.33.44
+
+ <VirtualHost 111.22.33.44>
+ ServerName www.domain.tld
+ DocumentRoot /web/domain
+ </VirtualHost>
+</pre>
+
+<p>The notable difference between IP-based and name-based virtual host
+configuration is the
+<A HREF="../mod/core.html#namevirtualhost"><code>NameVirtualHost</code></A>
+directive which specifies any IP address that should be used as a target for
+name-based virtual hosts.
+
+<p>Of course, any additional directives can (and should) be placed
+into the <code><VirtualHost></code> section. To make this work,
+all that is needed is to make sure that the name
+<samp>www.domain.tld</samp> is an alias (CNAME) pointing to the IP address
+<samp>111.22.33.44</samp></p>
+
+<p>Additionally, many servers may wish to be accessible by more than
+one name. For example, the example server might want to be accessible
+as <code>domain.tld</code>, or <code>www2.domain.tld</code>, assuming
+the IP addresses pointed to the same server. In fact, one might want it
+so that all addresses at <code>domain.tld</code> were picked up by the
+server. This is possible with the
+<A HREF="../mod/core.html#serveralias"><code>ServerAlias</code></A>
+directive, placed inside the <VirtualHost> section. For
+example:</p>
+
+<pre>
+ ServerAlias domain.tld *.domain.tld
+</pre>
+
+<p>Note that you can use <code>*</code> and <code>?</code> as wild-card
+characters.</p>
+
+<p>You also might need <code>ServerAlias</code> if you are
+serving local users who do not always include the domain name.
+For example, if local users are
+familiar with typing "www" or "www.foobar" then you will need to add
+<code>ServerAlias www www.foobar</code>. It isn't possible for the
+server to know what domain the client uses for their name resolution
+because the client doesn't provide that information in the request.</p>
+
+<h2>Compatibility with Older Browsers</h2>
+
+<p>As mentioned earlier, there are still some clients in use who
+do not send the required data for the name-based virtual hosts to work
+properly. These clients will always be sent the pages from the
+<cite>primary</cite> name-based virtual host (the first virtual host
+appearing in the configuration file for a specific IP address).</p>
+
+<p>There is a possible workaround with the
+<A HREF="../mod/core.html#serverpath"><code>ServerPath</code></A>
+directive, albeit a slightly cumbersome one:</p>
+
+<p>Example configuration:
+
+<pre>
+ NameVirtualHost 111.22.33.44
+
+ <VirtualHost 111.22.33.44>
+ ServerName www.domain.tld
+ ServerPath /domain
+ DocumentRoot /web/domain
+ </VirtualHost>
+</pre>
+
+<p>What does this mean? It means that a request for any URI beginning
+with "<samp>/domain</samp>" will be served from the virtual host
+<samp>www.domain.tld</samp> This means that the pages can be accessed as
+<code>http://www.domain.tld/domain/</code> for all clients, although
+clients sending a <samp>Host:</samp> header can also access it as
+<code>http://www.domain.tld/</code>.</p>
+
+<p>In order to make this work, put a link on your primary virtual host's page
+to <samp>http://www.domain.tld/domain/</samp>
+Then, in the virtual host's pages, be sure to use either purely
+relative links (e.g. "<samp>file.html</samp>" or
+"<samp>../icons/image.gif</samp>" or links containing the prefacing
+<samp>/domain/</samp>
+(e.g. "<samp>http://www.domain.tld/domain/misc/file.html</samp>" or
+"<samp>/domain/misc/file.html</samp>").</p>
+
+<p>This requires a bit of
+discipline, but adherence to these guidelines will, for the most part,
+ensure that your pages will work with all browsers, new and old.</p>
+
+<p>See also: <A HREF="examples.html#serverpath">ServerPath configuration
+example</A></p>
+
+<!--#include virtual="footer.html" -->
+</BODY>
+</HTML>
--- /dev/null
+/* ====================================================================
+ * Copyright (c) 1995-1999 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. For written permission, please contact
+ * apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ * nor may "Apache" appear in their names without prior written
+ * permission of the Apache Group.
+ *
+ * 6. 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/>.
+ *
+ */
+
+#ifndef AP_MMN_H
+#define AP_MMN_H
+
+/* run until a restart/shutdown is indicated, return 1 for shutdown
+ 0 otherwise */
+API_EXPORT(int) ap_mpm_run(pool *pconf, pool *plog, server_rec *server_conf);
+
+/* predicate indicating if a graceful stop has been requested ...
+ used by the connection loop */
+API_EXPORT(int) ap_mpm_graceful_stop(void);
+
+#ifdef HAS_OTHER_CHILD
+/*
+ * register an other_child -- a child which the main loop keeps track of
+ * and knows it is different than the rest of the scoreboard.
+ *
+ * pid is the pid of the child.
+ *
+ * maintenance is a function that is invoked with a reason, the data
+ * pointer passed here, and when appropriate a status result from waitpid().
+ *
+ * write_fd is an fd that is probed for writing by select() if it is ever
+ * unwritable, then maintenance is invoked with reason OC_REASON_UNWRITABLE.
+ * This is useful for log pipe children, to know when they've blocked. To
+ * disable this feature, use -1 for write_fd.
+ */
+API_EXPORT(void) ap_register_other_child(int pid,
+ void (*maintenance) (int reason, void *data, ap_wait_t status), void *data,
+ int write_fd);
+#define OC_REASON_DEATH 0 /* child has died, caller must call
+ * unregister still */
+#define OC_REASON_UNWRITABLE 1 /* write_fd is unwritable */
+#define OC_REASON_RESTART 2 /* a restart is occuring, perform
+ * any necessary cleanup (including
+ * sending a special signal to child)
+ */
+#define OC_REASON_UNREGISTER 3 /* unregister has been called, do
+ * whatever is necessary (including
+ * kill the child) */
+#define OC_REASON_LOST 4 /* somehow the child exited without
+ * us knowing ... buggy os? */
+
+/*
+ * unregister an other_child. Note that the data pointer is used here, and
+ * is assumed to be unique per other_child. This is because the pid and
+ * write_fd are possibly killed off separately.
+ */
+API_EXPORT(void) ap_unregister_other_child(void *data);
+
+#endif
+
+#endif
--- /dev/null
+/* ====================================================================
+ * Copyright (c) 1995-1999 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. For written permission, please contact
+ * apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ * nor may "Apache" appear in their names without prior written
+ * permission of the Apache Group.
+ *
+ * 6. 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/>.
+ *
+ */
+
+#ifndef APACHE_HTTP_CONNECTION_H
+#define APACHE_HTTP_CONNECTION_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+CORE_EXPORT(void) ap_process_connection(conn_rec *);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* !APACHE_HTTP_REQUEST_H */
--- /dev/null
+includes_module
--- /dev/null
+asis_module
--- /dev/null
+autoindex_module
--- /dev/null
+cgi_module
--- /dev/null
+info_module
--- /dev/null
+status_module
--- /dev/null
+mime_module
--- /dev/null
+config_log_module
--- /dev/null
+action_module
--- /dev/null
+alias_module
--- /dev/null
+dir_module
--- /dev/null
+imap_module
--- /dev/null
+negotiation_module
--- /dev/null
+rewrite_module
--- /dev/null
+speling_module
--- /dev/null
+userdir_module
--- /dev/null
+cern_meta_module
--- /dev/null
+env_module
--- /dev/null
+expires_module
--- /dev/null
+headers_module
--- /dev/null
+mime_magic_module
--- /dev/null
+setenvif_module
--- /dev/null
+unique_id_module
--- /dev/null
+usertrack_module
--- /dev/null
+proxy_module
--- /dev/null
+/* ====================================================================
+ * Copyright (c) 1995-1999 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. For written permission, please contact
+ * apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ * nor may "Apache" appear in their names without prior written
+ * permission of the Apache Group.
+ *
+ * 6. 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/>.
+ *
+ */
+
+#define CORE_PRIVATE
+#include "httpd.h"
+#include "http_connection.h"
+#include "http_request.h"
+#include "http_protocol.h"
+#include "ap_mpm.h"
+#include "http_config.h"
+#include "http_vhost.h"
+
+#include <poll.h>
+
+/*
+ * More machine-dependent networking gooo... on some systems,
+ * you've got to be *really* sure that all the packets are acknowledged
+ * before closing the connection, since the client will not be able
+ * to see the last response if their TCP buffer is flushed by a RST
+ * packet from us, which is what the server's TCP stack will send
+ * if it receives any request data after closing the connection.
+ *
+ * In an ideal world, this function would be accomplished by simply
+ * setting the socket option SO_LINGER and handling it within the
+ * server's TCP stack while the process continues on to the next request.
+ * Unfortunately, it seems that most (if not all) operating systems
+ * block the server process on close() when SO_LINGER is used.
+ * For those that don't, see USE_SO_LINGER below. For the rest,
+ * we have created a home-brew lingering_close.
+ *
+ * Many operating systems tend to block, puke, or otherwise mishandle
+ * calls to shutdown only half of the connection. You should define
+ * NO_LINGCLOSE in ap_config.h if such is the case for your system.
+ */
+#ifndef MAX_SECS_TO_LINGER
+#define MAX_SECS_TO_LINGER 30
+#endif
+
+#ifdef USE_SO_LINGER
+#define NO_LINGCLOSE /* The two lingering options are exclusive */
+
+static void sock_enable_linger(int s) // ZZZZZ abstract the socket, s
+{
+ struct linger li; // ZZZZZ SocketOptions...
+
+ li.l_onoff = 1;
+ li.l_linger = MAX_SECS_TO_LINGER;
+
+ if (setsockopt(s, SOL_SOCKET, SO_LINGER, // ZZZZZ abstract, return SUCCESS or not
+ (char *) &li, sizeof(struct linger)) < 0) {
+ ap_log_error(APLOG_MARK, APLOG_WARNING, server_conf,
+ "setsockopt: (SO_LINGER)");
+ /* not a fatal error */
+ }
+}
+
+#else
+#define sock_enable_linger(s) /* NOOP */
+#endif /* USE_SO_LINGER */
+
+#ifndef NO_LINGCLOSE
+
+/* Since many clients will abort a connection instead of closing it,
+ * attempting to log an error message from this routine will only
+ * confuse the webmaster. There doesn't seem to be any portable way to
+ * distinguish between a dropped connection and something that might be
+ * worth logging.
+ */
+/*ZZZ this routine needs to be adapted for use with poll()*/
+static void lingering_close(request_rec *r)
+{
+ /*ZZZ remove the hardwired 512. This is an IO Buffer Size */
+ char dummybuf[512];
+ struct pollfd pd;
+ int lsd;
+ int max_wait;
+
+ /* Prevent a slow-drip client from holding us here indefinitely */
+
+ max_wait = 30;
+ ap_bsetopt(r->connection->client, BO_TIMEOUT, &max_wait);
+
+ /* Send any leftover data to the client, but never try to again */
+
+ if (ap_bflush(r->connection->client) == -1) {
+ ap_bclose(r->connection->client);
+ return;
+ }
+ ap_bsetflag(r->connection->client, B_EOUT, 1);
+
+ /* Close our half of the connection --- send the client a FIN */
+
+ lsd = r->connection->client->fd;
+
+ if ((shutdown(lsd, 1) != 0) /* ZZZ abstract shutdown */
+ || ap_is_aborted(r->connection)) {
+ ap_bclose(r->connection->client);
+ return;
+ }
+
+ /* Set up to wait for readable data on socket... */
+ pd.fd = lsd;
+ pd.events = POLLIN;
+
+ /* Wait for readable data or error condition on socket;
+ * slurp up any data that arrives... We exit when we go for an
+ * interval of tv length without getting any more data, get an error
+ * from poll(), get an error or EOF on a read, or the timer expires.
+ */
+ /* We use a 2 second timeout because current (Feb 97) browsers
+ * fail to close a connection after the server closes it. Thus,
+ * to avoid keeping the child busy, we are only lingering long enough
+ * for a client that is actively sending data on a connection.
+ * This should be sufficient unless the connection is massively
+ * losing packets, in which case we might have missed the RST anyway.
+ * These parameters are reset on each pass, since they might be
+ * changed by poll.
+ */
+ do {
+ pd.revents = 0;
+ } while ((poll(&pd, 1, 2) == 1)
+ && read(lsd, dummybuf, sizeof(dummybuf)));
+ /* && (time() = epoch) < max_wait); */ /* ZZZZ time function is not good... */
+
+ /* Should now have seen final ack. Safe to finally kill socket */
+ ap_bclose(r->connection->client);
+}
+#endif /* ndef NO_LINGCLOSE */
+
+
+CORE_EXPORT(void) ap_process_connection(conn_rec *c)
+{
+ request_rec *r;
+
+ ap_update_vhost_given_ip(c);
+
+ /*
+ * Read and process each request found on our connection
+ * until no requests are left or we decide to close.
+ */
+
+ while ((r = ap_read_request(c)) != NULL) {
+
+ /* process the request if it was read without error */
+
+ if (r->status == HTTP_OK)
+ ap_process_request(r);
+
+ if (!c->keepalive || c->aborted)
+ break;
+
+ ap_destroy_pool(r->pool);
+
+ if (ap_mpm_graceful_stop()) {
+ /* XXX: hey wait, this should do a lingering_close! */
+ ap_bclose(c->client);
+ return;
+ }
+ }
+
+ /*
+ * Close the connection, being careful to send out whatever is still
+ * in our buffers. If possible, try to avoid a hard close until the
+ * client has ACKed our FIN and/or has stopped sending us data.
+ */
+
+#ifdef NO_LINGCLOSE
+ ap_bclose(c->client); /* just close it */
+#else
+ if (r && r->connection
+ && !r->connection->aborted
+ && r->connection->client
+ && (r->connection->client->fd >= 0)) {
+
+ lingering_close(r);
+ }
+ else {
+ ap_bsetflag(c->client, B_EOUT, 1);
+ ap_bclose(c->client);
+ }
+#endif
+}
projects / thirdparty / apache / httpd.git / commitdiff
