diff options
143 files changed, 0 insertions, 39497 deletions
diff --git a/build/binbuild.sh b/build/binbuild.sh deleted file mode 100755 index e6c3a4b4a9..0000000000 --- a/build/binbuild.sh +++ /dev/null @@ -1,295 +0,0 @@ -#!/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 - - -CONFIGPARAM="--with-layout=BinaryDistribution --enable-module=most --enable-shared=max" -APDIR=`pwd` -APDIR=`basename $APDIR` -VER=`echo $APDIR |sed s/apache_//` -OS=`src/helpers/GuessOS` -TAR="`src/helpers/PrintPath tar`" -GTAR="`src/helpers/PrintPath gtar`" -GZIP="`src/helpers/PrintPath gzip`" - -if [ x$1 != x ] -then - USER=$1 -else - USER="`src/helpers/buildinfo.sh -n %u@%h%d`" -fi - -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 image successfully created..." - -./bindist/bin/httpd -v - -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 "lmkdir()" && \ - echo "{" && \ - echo " path=\"\"" && \ - echo " dirs=\`echo \$1 | sed -e 's%/% %g'\`" && \ - echo " mode=\$2" && \ - echo " " && \ - echo " set -- \${dirs}" && \ - echo " " && \ - echo " for d in \${dirs}" && \ - echo " do" && \ - echo " path=\"\${path}/\$d\"" && \ - echo " if test ! -d \"\${path}\" ; then" && \ - echo " mkdir \${path}" && \ - echo " if test \$? -ne 0 ; then" && \ - echo " echo \"Failed to create directory: \${path}\"" && \ - echo " exit 1" && \ - echo " fi" && \ - echo " chmod \${mode} \${path}" && \ - echo " fi" && \ - echo " done" && \ - echo "}" && \ - echo " " && \ - echo "lcopy()" && \ - echo "{" && \ - echo " from=\$1" && \ - echo " to=\$2" && \ - echo " dmode=\$3" && \ - echo " fmode=\$4" && \ - echo " " && \ - echo " test -d \${to} || lmkdir \${to} \${dmode}" && \ - echo " (cd \${from} && tar -cf - *) | (cd \${to} && tar -xf -)" && \ - echo " " && \ - echo " if test \"X\${fmode}\" != X ; then" && \ - echo " find \${to} -type f -print | xargs chmod \${fmode}" && \ - echo " fi" && \ - echo " if test \"X\${dmode}\" != X ; then" && \ - echo " find \${to} -type d -print | xargs chmod \${dmode}" && \ - echo " fi" && \ - echo "}" && \ - echo " " && \ - echo "##" && \ - echo "## determine path to (optional) Perl interpreter" && \ - echo "##" && \ - echo "PERL=no-perl5-on-this-system" && \ - echo "perls='perl5 perl'" && \ - echo "path=\`echo \$PATH | sed -e 's/:/ /g'\`" && \ - echo " " && \ - echo "for dir in \${path} ; do" && \ - echo " for pperl in \${perls} ; do" && \ - echo " if test -f \"\${dir}/\${pperl}\" ; then" && \ - echo " if \`\${dir}/\${pperl} -v | grep 'version 5\.' >/dev/null 2>&1\` ; then" && \ - echo " PERL=\"\${dir}/\${pperl}\"" && \ - echo " break" && \ - echo " fi" && \ - echo " fi" && \ - echo " done" && \ - echo "done" && \ - 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 "lmkdir \$SR 755" && \ - echo "lmkdir \$SR/proxy 750" && \ - echo "lmkdir \$SR/logs 750" && \ - echo "lcopy bindist/man \$SR/man 755 644" && \ - echo "lcopy bindist/libexec \$SR/libexec 750 644" && \ - echo "lcopy bindist/include \$SR/include 755 644" && \ - echo "lcopy bindist/icons \$SR/icons 755 644" && \ - echo "lcopy bindist/cgi-bin \$SR/cgi-bin 750 750" && \ - echo "lcopy bindist/bin \$SR/bin 750 750" && \ - echo "if [ -d \$SR/conf ]" && \ - echo "then" && \ - echo " echo \"[Preserving existing configuration files.]\"" && \ - echo " cp bindist/conf/*.default \$SR/conf/" && \ - echo "else" && \ - echo " lcopy bindist/conf \$SR/conf 750 640" && \ - echo "fi" && \ - echo "if [ -d \$SR/htdocs ]" && \ - echo "then" && \ - echo " echo \"[Preserving existing htdocs directory.]\"" && \ - echo "else" && \ - echo " lcopy bindist/htdocs \$SR/htdocs 755 644" && \ - echo "fi" && \ - echo " " && \ - echo "sed -e \"s;^#!/.*;#!\$PERL;\" -e \"s;\@prefix\@;\$SR;\" -e \"s;\@sbindir\@;\$SR/bin;\" \\" && \ - echo " -e \"s;\@libexecdir\@;\$SR/libexec;\" -e \"s;\@includedir\@;\$SR/include;\" \\" && \ - echo " -e \"s;\@sysconfdir\@;\$SR/conf;\" bindist/bin/apxs > \$SR/bin/apxs" && \ - echo "sed -e \"s;^#!/.*;#!\$PERL;\" bindist/bin/dbmmanage > \$SR/bin/dbmmanage" && \ - 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 -R \$SR/libexec\\\"%\" 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 should first check the (initially |\"" && \ - echo "echo \" | created or preserved) configuration files: |\"" && \ - echo "echo \" | |\"" && \ - echo "echo \" | \$SR/conf/httpd.conf\"" && \ - echo "echo \" | |\"" && \ - echo "echo \" | You should then 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%\"proxy%\"/usr/local/apache/proxy%" \ - -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 [ "x$GTAR" != "x" ] - then - $GTAR -zcf ../apache_$VER-$OS.tar.gz -C .. apache_$VER - else - if [ "x$TAR" != "x" ] - then - $TAR -cf ../apache_$VER-$OS.tar -C .. apache_$VER - if [ "x$GZIP" != "x" ] - 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 diff --git a/docs/docroot/apache_pb.gif b/docs/docroot/apache_pb.gif Binary files differdeleted file mode 100644 index 3a1c139fc4..0000000000 --- a/docs/docroot/apache_pb.gif +++ /dev/null diff --git a/docs/manual/LICENSE b/docs/manual/LICENSE deleted file mode 100644 index 6ac6538b3c..0000000000 --- a/docs/manual/LICENSE +++ /dev/null @@ -1,59 +0,0 @@ -/* ==================================================================== - * 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/>. - * - */ - - - diff --git a/docs/manual/bind.html b/docs/manual/bind.html deleted file mode 100644 index 75bacbb253..0000000000 --- a/docs/manual/bind.html +++ /dev/null @@ -1,135 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Setting which addresses and ports Apache uses</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Setting which addresses and ports Apache uses</H1> - -<HR> - -When Apache starts, it connects to some port and address on the -local machine and waits for incoming requests. By default, it -listens to all addresses on the machine, and to the port -as specified by the <TT>Port</TT> directive in the server configuration. -However, it can be told to listen to more the one port, or to listen -to only selected addresses, or a combination. This is often combined -with the Virtual Host feature which determines how Apache -responds to different IP addresses, hostnames and ports.<P> - -There are two directives used to restrict or specify which addresses -and ports Apache listens to. - -<UL> -<LI><A HREF="#bindaddress">BindAddress</A> is used to restrict the server to - listening to - a single address, and can be used to permit multiple Apache servers - on the same machine listening to different IP addresses. -<LI><A HREF="#listen">Listen</A> can be used to make a single Apache server - listen - to more than one address and/or port. -</UL> - -<H3><A NAME="bindaddress">BindAddress</A></H3> -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> BindAddress <EM>[ * | IP-address - | hostname ]</EM><BR> -<A - HREF="mod/directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>BindAddress *</CODE><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Core<P> - -Makes the server listen to just the specified address. If the argument -is *, the server listens to all addresses. The port listened to -is set with the <TT>Port</TT> directive. Only one BindAddress -should be used. - -<H3><A NAME="listen">Listen</A></H3> -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Listen <EM>[ port | IP-address:port ]</EM><BR> -<A - HREF="mod/directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>none</CODE><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Core<P> - -<TT>Listen</TT> can be used instead of <TT>BindAddress</TT> and -<TT>Port</TT>. It tells the server to accept incoming requests on the -specified port or address-and-port combination. If the first format is -used, with a port number only, the server listens to the given port on -all interfaces, instead of the port given by the <TT>Port</TT> -directive. If an IP address is given as well as a port, the server -will listen on the given port and interface. <P> Multiple Listen -directives may be used to specify a number of addresses and ports to -listen to. The server will respond to requests from any of the listed -addresses and ports.<P> - -For example, to make the server accept connections on both port -80 and port 8000, use: -<PRE> - Listen 80 - Listen 8000 -</PRE> - -To make the server accept connections on two specified -interfaces and port numbers, use -<PRE> - Listen 192.170.2.1:80 - Listen 192.170.2.5:8000 -</PRE> - -<H2>How this works with Virtual Hosts</H2> - -BindAddress and Listen do not implement Virtual Hosts. They tell the -main server what addresses and ports to listen to. If no -<VirtualHost> directives are used, the server will behave the -same for all accepted requests. However, <VirtualHost> can be -used to specify a different behavior for one or more of the addresses -and ports. To implement a VirtualHost, the server must first be told -to listen to the address and port to be used. Then a -<VirtualHost> section should be created for a specified address -and port to set the behavior of this virtual host. Note that if the -<VirtualHost> is set for an address and port that the server is -not listening to, it cannot be accessed. - -<H2>See also</H2> - -See also the documentation on -<A HREF="vhosts/index.html">Virtual Hosts</A>, -<A HREF="mod/core.html#bindaddress">BindAddress directive</A>, -<A HREF="mod/core.html#port">Port directive</A>, -<A HREF="dns-caveats.html">DNS Issues</A> -and -<A HREF="mod/core.html#virtualhost"><VirtualHost> section</A>. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/bind.html.en b/docs/manual/bind.html.en deleted file mode 100644 index 75bacbb253..0000000000 --- a/docs/manual/bind.html.en +++ /dev/null @@ -1,135 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Setting which addresses and ports Apache uses</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Setting which addresses and ports Apache uses</H1> - -<HR> - -When Apache starts, it connects to some port and address on the -local machine and waits for incoming requests. By default, it -listens to all addresses on the machine, and to the port -as specified by the <TT>Port</TT> directive in the server configuration. -However, it can be told to listen to more the one port, or to listen -to only selected addresses, or a combination. This is often combined -with the Virtual Host feature which determines how Apache -responds to different IP addresses, hostnames and ports.<P> - -There are two directives used to restrict or specify which addresses -and ports Apache listens to. - -<UL> -<LI><A HREF="#bindaddress">BindAddress</A> is used to restrict the server to - listening to - a single address, and can be used to permit multiple Apache servers - on the same machine listening to different IP addresses. -<LI><A HREF="#listen">Listen</A> can be used to make a single Apache server - listen - to more than one address and/or port. -</UL> - -<H3><A NAME="bindaddress">BindAddress</A></H3> -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> BindAddress <EM>[ * | IP-address - | hostname ]</EM><BR> -<A - HREF="mod/directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>BindAddress *</CODE><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Core<P> - -Makes the server listen to just the specified address. If the argument -is *, the server listens to all addresses. The port listened to -is set with the <TT>Port</TT> directive. Only one BindAddress -should be used. - -<H3><A NAME="listen">Listen</A></H3> -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Listen <EM>[ port | IP-address:port ]</EM><BR> -<A - HREF="mod/directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>none</CODE><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Core<P> - -<TT>Listen</TT> can be used instead of <TT>BindAddress</TT> and -<TT>Port</TT>. It tells the server to accept incoming requests on the -specified port or address-and-port combination. If the first format is -used, with a port number only, the server listens to the given port on -all interfaces, instead of the port given by the <TT>Port</TT> -directive. If an IP address is given as well as a port, the server -will listen on the given port and interface. <P> Multiple Listen -directives may be used to specify a number of addresses and ports to -listen to. The server will respond to requests from any of the listed -addresses and ports.<P> - -For example, to make the server accept connections on both port -80 and port 8000, use: -<PRE> - Listen 80 - Listen 8000 -</PRE> - -To make the server accept connections on two specified -interfaces and port numbers, use -<PRE> - Listen 192.170.2.1:80 - Listen 192.170.2.5:8000 -</PRE> - -<H2>How this works with Virtual Hosts</H2> - -BindAddress and Listen do not implement Virtual Hosts. They tell the -main server what addresses and ports to listen to. If no -<VirtualHost> directives are used, the server will behave the -same for all accepted requests. However, <VirtualHost> can be -used to specify a different behavior for one or more of the addresses -and ports. To implement a VirtualHost, the server must first be told -to listen to the address and port to be used. Then a -<VirtualHost> section should be created for a specified address -and port to set the behavior of this virtual host. Note that if the -<VirtualHost> is set for an address and port that the server is -not listening to, it cannot be accessed. - -<H2>See also</H2> - -See also the documentation on -<A HREF="vhosts/index.html">Virtual Hosts</A>, -<A HREF="mod/core.html#bindaddress">BindAddress directive</A>, -<A HREF="mod/core.html#port">Port directive</A>, -<A HREF="dns-caveats.html">DNS Issues</A> -and -<A HREF="mod/core.html#virtualhost"><VirtualHost> section</A>. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/cgi_path.html b/docs/manual/cgi_path.html deleted file mode 100644 index 2b7bd963b1..0000000000 --- a/docs/manual/cgi_path.html +++ /dev/null @@ -1,93 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>PATH_INFO Changes in the CGI Environment</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">PATH_INFO Changes in the CGI Environment</H1> - -<HR> - -<H2><A NAME="over">Overview</A></H2> - -<P>As implemented in Apache 1.1.1 and earlier versions, the method -Apache used to create PATH_INFO in the CGI environment was -counterintuitive, and could result in crashes in certain cases. In -Apache 1.2 and beyond, this behavior has changed. Although this -results in some compatibility problems with certain legacy CGI -applications, the Apache 1.2 behavior is still compatible with the -CGI/1.1 specification, and CGI scripts can be easily modified (<A -HREF="#compat">see below</A>). - -<H2><A NAME="prob">The Problem</A></H2> - -<P>Apache 1.1.1 and earlier implemented the PATH_INFO and SCRIPT_NAME -environment variables by looking at the filename, not the URL. While -this resulted in the correct values in many cases, when the filesystem -path was overloaded to contain path information, it could result in -errant behavior. For example, if the following appeared in a config -file: -<PRE> - Alias /cgi-ralph /usr/local/httpd/cgi-bin/user.cgi/ralph -</PRE> -<P>In this case, <CODE>user.cgi</CODE> is the CGI script, the "/ralph" -is information to be passed onto the CGI. If this configuration was in -place, and a request came for "<CODE>/cgi-ralph/script/</CODE>", the -code would set PATH_INFO to "<CODE>/ralph/script</CODE>", and -SCRIPT_NAME to "<CODE>/cgi-</CODE>". Obviously, the latter is -incorrect. In certain cases, this could even cause the server to -crash.</P> - -<H2><A NAME="solution">The Solution</A></H2> - -<P>Apache 1.2 and later now determine SCRIPT_NAME and PATH_INFO by -looking directly at the URL, and determining how much of the URL is -client-modifiable, and setting PATH_INFO to it. To use the above -example, PATH_INFO would be set to "<CODE>/script</CODE>", and -SCRIPT_NAME to "<CODE>/cgi-ralph</CODE>". This makes sense and results -in no server behavior problems. It also permits the script to be -guaranteed that -"<CODE>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</CODE>" -will always be an accessible URL that points to the current script, -something which was not necessarily true with previous versions of -Apache. - -<P>However, the "<CODE>/ralph</CODE>" -information from the <CODE>Alias</CODE> directive is lost. This is -unfortunate, but we feel that using the filesystem to pass along this -sort of information is not a recommended method, and a script making -use of it "deserves" not to work. Apache 1.2b3 and later, however, do -provide <A HREF="#compat">a workaround.</A> - -<H2><A NAME="compat">Compatibility with Previous Servers</A></H2> - -<P>It may be necessary for a script that was designed for earlier -versions of Apache or other servers to need the information that the -old PATH_INFO variable provided. For this purpose, Apache 1.2 (1.2b3 -and later) sets an additional variable, FILEPATH_INFO. This -environment variable contains the value that PATH_INFO would have had -with Apache 1.1.1.</P> - -<P>A script that wishes to work with both Apache 1.2 and earlier -versions can simply test for the existence of FILEPATH_INFO, and use -it if available. Otherwise, it can use PATH_INFO. For example, in -Perl, one might use: -<PRE> - $path_info = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'}; -</PRE> - -<P>By doing this, a script can work with all servers supporting the -CGI/1.1 specification, including all versions of Apache.</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/cgi_path.html.en b/docs/manual/cgi_path.html.en deleted file mode 100644 index 2b7bd963b1..0000000000 --- a/docs/manual/cgi_path.html.en +++ /dev/null @@ -1,93 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>PATH_INFO Changes in the CGI Environment</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">PATH_INFO Changes in the CGI Environment</H1> - -<HR> - -<H2><A NAME="over">Overview</A></H2> - -<P>As implemented in Apache 1.1.1 and earlier versions, the method -Apache used to create PATH_INFO in the CGI environment was -counterintuitive, and could result in crashes in certain cases. In -Apache 1.2 and beyond, this behavior has changed. Although this -results in some compatibility problems with certain legacy CGI -applications, the Apache 1.2 behavior is still compatible with the -CGI/1.1 specification, and CGI scripts can be easily modified (<A -HREF="#compat">see below</A>). - -<H2><A NAME="prob">The Problem</A></H2> - -<P>Apache 1.1.1 and earlier implemented the PATH_INFO and SCRIPT_NAME -environment variables by looking at the filename, not the URL. While -this resulted in the correct values in many cases, when the filesystem -path was overloaded to contain path information, it could result in -errant behavior. For example, if the following appeared in a config -file: -<PRE> - Alias /cgi-ralph /usr/local/httpd/cgi-bin/user.cgi/ralph -</PRE> -<P>In this case, <CODE>user.cgi</CODE> is the CGI script, the "/ralph" -is information to be passed onto the CGI. If this configuration was in -place, and a request came for "<CODE>/cgi-ralph/script/</CODE>", the -code would set PATH_INFO to "<CODE>/ralph/script</CODE>", and -SCRIPT_NAME to "<CODE>/cgi-</CODE>". Obviously, the latter is -incorrect. In certain cases, this could even cause the server to -crash.</P> - -<H2><A NAME="solution">The Solution</A></H2> - -<P>Apache 1.2 and later now determine SCRIPT_NAME and PATH_INFO by -looking directly at the URL, and determining how much of the URL is -client-modifiable, and setting PATH_INFO to it. To use the above -example, PATH_INFO would be set to "<CODE>/script</CODE>", and -SCRIPT_NAME to "<CODE>/cgi-ralph</CODE>". This makes sense and results -in no server behavior problems. It also permits the script to be -guaranteed that -"<CODE>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</CODE>" -will always be an accessible URL that points to the current script, -something which was not necessarily true with previous versions of -Apache. - -<P>However, the "<CODE>/ralph</CODE>" -information from the <CODE>Alias</CODE> directive is lost. This is -unfortunate, but we feel that using the filesystem to pass along this -sort of information is not a recommended method, and a script making -use of it "deserves" not to work. Apache 1.2b3 and later, however, do -provide <A HREF="#compat">a workaround.</A> - -<H2><A NAME="compat">Compatibility with Previous Servers</A></H2> - -<P>It may be necessary for a script that was designed for earlier -versions of Apache or other servers to need the information that the -old PATH_INFO variable provided. For this purpose, Apache 1.2 (1.2b3 -and later) sets an additional variable, FILEPATH_INFO. This -environment variable contains the value that PATH_INFO would have had -with Apache 1.1.1.</P> - -<P>A script that wishes to work with both Apache 1.2 and earlier -versions can simply test for the existence of FILEPATH_INFO, and use -it if available. Otherwise, it can use PATH_INFO. For example, in -Perl, one might use: -<PRE> - $path_info = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'}; -</PRE> - -<P>By doing this, a script can work with all servers supporting the -CGI/1.1 specification, including all versions of Apache.</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/content-negotiation.html b/docs/manual/content-negotiation.html deleted file mode 100644 index 7bfaee5afa..0000000000 --- a/docs/manual/content-negotiation.html +++ /dev/null @@ -1,588 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache Content Negotiation</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Content Negotiation</H1> - -<P> -Apache's support for content negotiation has been updated to meet the -HTTP/1.1 specification. It can choose the best representation of a -resource based on the browser-supplied preferences for media type, -languages, character set and encoding. It is also implements a -couple of features to give more intelligent handling of requests from -browsers which send incomplete negotiation information. <P> - -Content negotiation is provided by the -<A HREF="mod/mod_negotiation.html">mod_negotiation</A> module, -which is compiled in by default. - -<HR> - -<H2>About Content Negotiation</H2> - -<P> -A resource may be available in several different representations. For -example, it might be available in different languages or different -media types, or a combination. One way of selecting the most -appropriate choice is to give the user an index page, and let them -select. However it is often possible for the server to choose -automatically. This works because browsers can send as part of each -request information about what representations they prefer. For -example, a browser could indicate that it would like to see -information in French, if possible, else English will do. Browsers -indicate their preferences by headers in the request. To request only -French representations, the browser would send - -<PRE> - Accept-Language: fr -</PRE> - -<P> -Note that this preference will only be applied when there is a choice -of representations and they vary by language. -<P> - -As an example of a more complex request, this browser has been -configured to accept French and English, but prefer French, and to -accept various media types, preferring HTML over plain text or other -text types, and preferring GIF or JPEG over other media types, but also -allowing any other media type as a last resort: - -<PRE> - Accept-Language: fr; q=1.0, en; q=0.5 - Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6, - image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1 -</PRE> - -Apache 1.2 supports 'server driven' content negotiation, as defined in -the HTTP/1.1 specification. It fully supports the Accept, -Accept-Language, Accept-Charset and Accept-Encoding request headers. -Apache 1.3.4 also supports 'transparent' content negotiation, which is -an experimental negotiation protocol defined in RFC 2295 and RFC 2296. -It does not offer support for 'feature negotiation' as defined in -these RFCs. -<P> - -A <STRONG>resource</STRONG> is a conceptual entity identified by a URI -(RFC 2396). An HTTP server like Apache provides access to -<STRONG>representations</STRONG> of the resource(s) within its namespace, -with each representation in the form of a sequence of bytes with a -defined media type, character set, encoding, etc. Each resource may be -associated with zero, one, or more than one representation -at any given time. If multiple representations are available, -the resource is referred to as <STRONG>negotiable</STRONG> and each of its -representations is termed a <STRONG>variant</STRONG>. The ways in which the -variants for a negotiable resource vary are called the -<STRONG>dimensions</STRONG> of negotiation. - -<H2>Negotiation in Apache</H2> - -<P> -In order to negotiate a resource, the server needs to be given -information about each of the variants. This is done in one of two -ways: - -<UL> - <LI> Using a type map (<EM>i.e.</EM>, a <CODE>*.var</CODE> file) which - names the files containing the variants explicitly, or - <LI> Using a 'MultiViews' search, where the server does an implicit - filename pattern match and chooses from among the results. -</UL> - -<H3>Using a type-map file</H3> - -<P> -A type map is a document which is associated with the handler -named <CODE>type-map</CODE> (or, for backwards-compatibility with -older Apache configurations, the mime type -<CODE>application/x-type-map</CODE>). Note that to use this feature, -you must have a handler set in the configuration that defines a -file suffix as <CODE>type-map</CODE>; this is best done with a - -<PRE> - AddHandler type-map var -</PRE> - -in the server configuration file. See the comments in the sample config -file for more details. <P> - -Type map files have an entry for each available variant; these entries -consist of contiguous HTTP-format header lines. Entries for -different variants are separated by blank lines. Blank lines are -illegal within an entry. It is conventional to begin a map file with -an entry for the combined entity as a whole (although this -is not required, and if present will be ignored). An example -map file is: - -<PRE> - URI: foo - - URI: foo.en.html - Content-type: text/html - Content-language: en - - URI: foo.fr.de.html - Content-type: text/html;charset=iso-8859-2 - Content-language: fr, de -</PRE> - -If the variants have different source qualities, that may be indicated -by the "qs" parameter to the media type, as in this picture (available -as jpeg, gif, or ASCII-art): - -<PRE> - URI: foo - - URI: foo.jpeg - Content-type: image/jpeg; qs=0.8 - - URI: foo.gif - Content-type: image/gif; qs=0.5 - - URI: foo.txt - Content-type: text/plain; qs=0.01 -</PRE> -<P> - -qs values can vary in the range 0.000 to 1.000. Note that any variant with -a qs value of 0.000 will never be chosen. Variants with no 'qs' -parameter value are given a qs factor of 1.0. The qs parameter indicates -the relative 'quality' of this variant compared to the other available -variants, independent of the client's capabilities. For example, a jpeg -file is usually of higher source quality than an ascii file if it is -attempting to represent a photograph. However, if the resource being -represented is an original ascii art, then an ascii representation would -have a higher source quality than a jpeg representation. A qs value -is therefore specific to a given variant depending on the nature of -the resource it represents. - -<P> -The full list of headers recognized is: - -<DL> - <DT> <CODE>URI:</CODE> - <DD> uri of the file containing the variant (of the given media - type, encoded with the given content encoding). These are - interpreted as URLs relative to the map file; they must be on - the same server (!), and they must refer to files to which the - client would be granted access if they were to be requested - directly. - <DT> <CODE>Content-Type:</CODE> - <DD> media type --- charset, level and "qs" parameters may be given. These - are often referred to as MIME types; typical media types are - <CODE>image/gif</CODE>, <CODE>text/plain</CODE>, or - <CODE>text/html; level=3</CODE>. - <DT> <CODE>Content-Language:</CODE> - <DD> The languages of the variant, specified as an Internet standard - language tag from RFC 1766 (<EM>e.g.</EM>, <CODE>en</CODE> for English, - <CODE>kr</CODE> for Korean, <EM>etc.</EM>). - <DT> <CODE>Content-Encoding:</CODE> - <DD> If the file is compressed, or otherwise encoded, rather than - containing the actual raw data, this says how that was done. - Apache only recognizes encodings that are defined by an - <A HREF="mod/mod_mime.html#addencoding">AddEncoding</A> directive. - This normally includes the encodings <CODE>x-compress</CODE> - for compress'd files, and <CODE>x-gzip</CODE> for gzip'd files. - The <CODE>x-</CODE> prefix is ignored for encoding comparisons. - <DT> <CODE>Content-Length:</CODE> - <DD> The size of the file. Specifying content - lengths in the type-map allows the server to compare file sizes - without checking the actual files. - <DT> <CODE>Description:</CODE> - <DD> A human-readable textual description of the variant. If Apache cannot - find any appropriate variant to return, it will return an error - response which lists all available variants instead. Such a variant - list will include the human-readable variant descriptions. -</DL> - -<H3>Multiviews</H3> - -<P> -<CODE>MultiViews</CODE> is a per-directory option, meaning it can be set with -an <CODE>Options</CODE> directive within a <CODE><Directory></CODE>, -<CODE><Location></CODE> or <CODE><Files></CODE> -section in <CODE>access.conf</CODE>, or (if <CODE>AllowOverride</CODE> -is properly set) in <CODE>.htaccess</CODE> files. Note that -<CODE>Options All</CODE> does not set <CODE>MultiViews</CODE>; you -have to ask for it by name. - -<P> -The effect of <CODE>MultiViews</CODE> is as follows: if the server -receives a request for <CODE>/some/dir/foo</CODE>, if -<CODE>/some/dir</CODE> has <CODE>MultiViews</CODE> enabled, and -<CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the -directory looking for files named foo.*, and effectively fakes up a -type map which names all those files, assigning them the same media -types and content-encodings it would have if the client had asked for -one of them by name. It then chooses the best match to the client's -requirements. - -<P> -<CODE>MultiViews</CODE> may also apply to searches for the file named by the -<CODE>DirectoryIndex</CODE> directive, if the server is trying to -index a directory. If the configuration files specify - -<PRE> - DirectoryIndex index -</PRE> - -then the server will arbitrate between <CODE>index.html</CODE> -and <CODE>index.html3</CODE> if both are present. If neither are -present, and <CODE>index.cgi</CODE> is there, the server will run it. - -<P> -If one of the files found when reading the directive is a CGI script, -it's not obvious what should happen. The code gives that case -special treatment --- if the request was a POST, or a GET with -QUERY_ARGS or PATH_INFO, the script is given an extremely high quality -rating, and generally invoked; otherwise it is given an extremely low -quality rating, which generally causes one of the other views (if any) -to be retrieved. - -<H2>The Negotiation Methods</H2> - -After Apache has obtained a list of the variants for a given resource, -either from a type-map file or from the filenames in the directory, it -invokes one of two methods to decide on the 'best' variant to -return, if any. It is not necessary to know any of the details of how -negotiation actually takes place in order to use Apache's content -negotiation features. However the rest of this document explains the -methods used for those interested. -<P> - -There are two negotiation methods: - -<OL> - -<LI><STRONG>Server driven negotiation with the Apache -algorithm</STRONG> is used in the normal case. The Apache algorithm is -explained in more detail below. When this algorithm is used, Apache -can sometimes 'fiddle' the quality factor of a particular dimension to -achieve a better result. The ways Apache can fiddle quality factors is -explained in more detail below. - -<LI><STRONG>Transparent content negotiation</STRONG> is used when the -browser specifically requests this through the mechanism defined in RFC -2295. This negotiation method gives the browser full control over -deciding on the 'best' variant, the result is therefore dependent on -the specific algorithms used by the browser. As part of the -transparent negotiation process, the browser can ask Apache to run the -'remote variant selection algorithm' defined in RFC 2296. </UL> - - -<H3>Dimensions of Negotiation</H3> - -<TABLE> -<TR valign="top"> -<TH>Dimension -<TH>Notes -<TR valign="top"> -<TD>Media Type -<TD>Browser indicates preferences with the Accept header field. Each item -can have an associated quality factor. Variant description can also -have a quality factor (the "qs" parameter). -<TR valign="top"> -<TD>Language -<TD>Browser indicates preferences with the Accept-Language header field. -Each item can have a quality factor. Variants can be associated with none, one -or more than one language. -<TR valign="top"> -<TD>Encoding -<TD>Browser indicates preference with the Accept-Encoding header field. -Each item can have a quality factor. -<TR valign="top"> -<TD>Charset -<TD>Browser indicates preference with the Accept-Charset header field. -Each item can have a quality factor. -Variants can indicate a charset as a parameter of the media type. -</TABLE> - -<H3>Apache Negotiation Algorithm</H3> - -<P> -Apache can use the following algorithm to select the 'best' variant -(if any) to return to the browser. This algorithm is not -further configurable. It operates as follows: - -<OL> -<LI>First, for each dimension of the negotiation, check the appropriate -<EM>Accept*</EM> header field and assign a quality to each -variant. If the <EM>Accept*</EM> header for any dimension implies that this -variant is not acceptable, eliminate it. If no variants remain, go -to step 4. - -<LI>Select the 'best' variant by a process of elimination. Each of the -following tests is applied in order. Any variants not selected at each -test are eliminated. After each test, if only one variant remains, -select it as the best match and proceed to step 3. If more than one -variant remains, move on to the next test. - -<OL> -<LI>Multiply the quality factor from the Accept header with the - quality-of-source factor for this variant's media type, and select - the variants with the highest value. - -<LI>Select the variants with the highest language quality factor. - -<LI>Select the variants with the best language match, using either the - order of languages in the Accept-Language header (if present), or else - else the order of languages in the <CODE>LanguagePriority</CODE> - directive (if present). - -<LI>Select the variants with the highest 'level' media parameter - (used to give the version of text/html media types). - -<LI>Select variants with the best charset media parameters, - as given on the Accept-Charset header line. Charset ISO-8859-1 - is acceptable unless explicitly excluded. Variants with a - <CODE>text/*</CODE> media type but not explicitly associated - with a particular charset are assumed to be in ISO-8859-1. - -<LI>Select those variants which have associated - charset media parameters that are <EM>not</EM> ISO-8859-1. - If there are no such variants, select all variants instead. - -<LI>Select the variants with the best encoding. If there are - variants with an encoding that is acceptable to the user-agent, - select only these variants. Otherwise if there is a mix of encoded - and non-encoded variants, select only the unencoded variants. - If either all variants are encoded or all variants are not encoded, - select all variants. - -<LI>Select the variants with the smallest content length. - -<LI>Select the first variant of those remaining. This will be either the - first listed in the type-map file, or when variants are read from - the directory, the one whose file name comes first when sorted using - ASCII code order. - -</OL> - -<LI>The algorithm has now selected one 'best' variant, so return - it as the response. The HTTP response header Vary is set to indicate the - dimensions of negotiation (browsers and caches can use this - information when caching the resource). End. - -<LI>To get here means no variant was selected (because none are acceptable - to the browser). Return a 406 status (meaning "No acceptable representation") - with a response body consisting of an HTML document listing the - available variants. Also set the HTTP Vary header to indicate the - dimensions of variance. - -</OL> - -<H2><A NAME="better">Fiddling with Quality Values</A></H2> - -<P> -Apache sometimes changes the quality values from what would be -expected by a strict interpretation of the Apache negotiation -algorithm above. This is to get a better result from the algorithm for -browsers which do not send full or accurate information. Some of the -most popular browsers send Accept header information which would -otherwise result in the selection of the wrong variant in many -cases. If a browser sends full and correct information these fiddles -will not be applied. -<P> - -<H3>Media Types and Wildcards</H3> - -<P> -The Accept: request header indicates preferences for media types. It -can also include 'wildcard' media types, such as "image/*" or "*/*" -where the * matches any string. So a request including: -<PRE> - Accept: image/*, */* -</PRE> - -would indicate that any type starting "image/" is acceptable, -as is any other type (so the first "image/*" is redundant). Some -browsers routinely send wildcards in addition to explicit types they -can handle. For example: -<PRE> - Accept: text/html, text/plain, image/gif, image/jpeg, */* -</PRE> - -The intention of this is to indicate that the explicitly -listed types are preferred, but if a different representation is -available, that is ok too. However under the basic algorithm, as given -above, the */* wildcard has exactly equal preference to all the other -types, so they are not being preferred. The browser should really have -sent a request with a lower quality (preference) value for *.*, such -as: -<PRE> - Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01 -</PRE> - -The explicit types have no quality factor, so they default to a -preference of 1.0 (the highest). The wildcard */* is given -a low preference of 0.01, so other types will only be returned if -no variant matches an explicitly listed type. -<P> - -If the Accept: header contains <EM>no</EM> q factors at all, Apache sets -the q value of "*/*", if present, to 0.01 to emulate the desired -behavior. It also sets the q value of wildcards of the format -"type/*" to 0.02 (so these are preferred over matches against -"*/*". If any media type on the Accept: header contains a q factor, -these special values are <EM>not</EM> applied, so requests from browsers -which send the correct information to start with work as expected. - -<H3>Variants with no Language</H3> - -<P> -If some of the variants for a particular resource have a language -attribute, and some do not, those variants with no language -are given a very low language quality factor of 0.001.<P> - -The reason for setting this language quality factor for -variant with no language to a very low value is to allow -for a default variant which can be supplied if none of the -other variants match the browser's language preferences. - -For example, consider the situation with three variants: - -<UL> -<LI>foo.en.html, language en -<LI>foo.fr.html, language en -<LI>foo.html, no language -</UL> - -<P> -The meaning of a variant with no language is that it is -always acceptable to the browser. If the request Accept-Language -header includes either en or fr (or both) one of foo.en.html -or foo.fr.html will be returned. If the browser does not list -either en or fr as acceptable, foo.html will be returned instead. - -<H2>Extensions to Transparent Content Negotiation</H2> - -Apache extends the transparent content negotiation protocol (RFC 2295) -as follows. A new <CODE> {encoding ..}</CODE> element is used in -variant lists to label variants which are available with a specific -content-encoding only. The implementation of the -RVSA/1.0 algorithm (RFC 2296) is extended to recognize encoded -variants in the list, and to use them as candidate variants whenever -their encodings are acceptable according to the Accept-Encoding -request header. The RVSA/1.0 implementation does not round computed -quality factors to 5 decimal places before choosing the best variant. - -<H2>Note on hyperlinks and naming conventions</H2> - -<P> -If you are using language negotiation you can choose between -different naming conventions, because files can have more than one -extension, and the order of the extensions is normally irrelevant -(see <A HREF="mod/mod_mime.html">mod_mime</A> documentation for details). -<P> -A typical file has a MIME-type extension (<EM>e.g.</EM>, <SAMP>html</SAMP>), -maybe an encoding extension (<EM>e.g.</EM>, <SAMP>gz</SAMP>), and of course a -language extension (<EM>e.g.</EM>, <SAMP>en</SAMP>) when we have different -language variants of this file. - -<P> -Examples: -<UL> -<LI>foo.en.html -<LI>foo.html.en -<LI>foo.en.html.gz -</UL> - -<P> -Here some more examples of filenames together with valid and invalid -hyperlinks: -</P> - -<TABLE BORDER=1 CELLPADDING=8 CELLSPACING=0> -<TR> - <TH>Filename</TH> - <TH>Valid hyperlink</TH> - <TH>Invalid hyperlink</TH> -</TR> -<TR> - <TD><EM>foo.html.en</EM></TD> - <TD>foo<BR> - foo.html</TD> - <TD>-</TD> -</TR> -<TR> - <TD><EM>foo.en.html</EM></TD> - <TD>foo</TD> - <TD>foo.html</TD> -</TR> -<TR> - <TD><EM>foo.html.en.gz</EM></TD> - <TD>foo<BR> - foo.html</TD> - <TD>foo.gz<BR> - foo.html.gz</TD> -</TR> -<TR> - <TD><EM>foo.en.html.gz</EM></TD> - <TD>foo</TD> - <TD>foo.html<BR> - foo.html.gz<BR> - foo.gz</TD> -</TR> -<TR> - <TD><EM>foo.gz.html.en</EM></TD> - <TD>foo<BR> - foo.gz<BR> - foo.gz.html</TD> - <TD>foo.html</TD> -</TR> -<TR> - <TD><EM>foo.html.gz.en</EM></TD> - <TD>foo<BR> - foo.html<BR> - foo.html.gz</TD> - <TD>foo.gz</TD> -</TR> -</TABLE> - -<P> -Looking at the table above you will notice that it is always possible to -use the name without any extensions in an hyperlink (<EM>e.g.</EM>, <SAMP>foo</SAMP>). -The advantage is that you can hide the actual type of a -document rsp. file and can change it later, <EM>e.g.</EM>, from <SAMP>html</SAMP> -to <SAMP>shtml</SAMP> or <SAMP>cgi</SAMP> without changing any -hyperlink references. - -<P> -If you want to continue to use a MIME-type in your hyperlinks (<EM>e.g.</EM> -<SAMP>foo.html</SAMP>) the language extension (including an encoding extension -if there is one) must be on the right hand side of the MIME-type extension -(<EM>e.g.</EM>, <SAMP>foo.html.en</SAMP>). - - -<H2>Note on Caching</H2> - -<P> -When a cache stores a representation, it associates it with the request URL. -The next time that URL is requested, the cache can use the stored -representation. But, if the resource is negotiable at the server, -this might result in only the first requested variant being cached and -subsequent cache hits might return the wrong response. To prevent this, -Apache normally marks all responses that are returned after content negotiation -as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1 -protocol features to allow caching of negotiated responses. <P> - -For requests which come from a HTTP/1.0 compliant client (either a -browser or a cache), the directive <TT>CacheNegotiatedDocs</TT> can be -used to allow caching of responses which were subject to negotiation. -This directive can be given in the server config or virtual host, and -takes no arguments. It has no effect on requests from HTTP/1.1 clients. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/content-negotiation.html.en b/docs/manual/content-negotiation.html.en deleted file mode 100644 index 7bfaee5afa..0000000000 --- a/docs/manual/content-negotiation.html.en +++ /dev/null @@ -1,588 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache Content Negotiation</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Content Negotiation</H1> - -<P> -Apache's support for content negotiation has been updated to meet the -HTTP/1.1 specification. It can choose the best representation of a -resource based on the browser-supplied preferences for media type, -languages, character set and encoding. It is also implements a -couple of features to give more intelligent handling of requests from -browsers which send incomplete negotiation information. <P> - -Content negotiation is provided by the -<A HREF="mod/mod_negotiation.html">mod_negotiation</A> module, -which is compiled in by default. - -<HR> - -<H2>About Content Negotiation</H2> - -<P> -A resource may be available in several different representations. For -example, it might be available in different languages or different -media types, or a combination. One way of selecting the most -appropriate choice is to give the user an index page, and let them -select. However it is often possible for the server to choose -automatically. This works because browsers can send as part of each -request information about what representations they prefer. For -example, a browser could indicate that it would like to see -information in French, if possible, else English will do. Browsers -indicate their preferences by headers in the request. To request only -French representations, the browser would send - -<PRE> - Accept-Language: fr -</PRE> - -<P> -Note that this preference will only be applied when there is a choice -of representations and they vary by language. -<P> - -As an example of a more complex request, this browser has been -configured to accept French and English, but prefer French, and to -accept various media types, preferring HTML over plain text or other -text types, and preferring GIF or JPEG over other media types, but also -allowing any other media type as a last resort: - -<PRE> - Accept-Language: fr; q=1.0, en; q=0.5 - Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6, - image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1 -</PRE> - -Apache 1.2 supports 'server driven' content negotiation, as defined in -the HTTP/1.1 specification. It fully supports the Accept, -Accept-Language, Accept-Charset and Accept-Encoding request headers. -Apache 1.3.4 also supports 'transparent' content negotiation, which is -an experimental negotiation protocol defined in RFC 2295 and RFC 2296. -It does not offer support for 'feature negotiation' as defined in -these RFCs. -<P> - -A <STRONG>resource</STRONG> is a conceptual entity identified by a URI -(RFC 2396). An HTTP server like Apache provides access to -<STRONG>representations</STRONG> of the resource(s) within its namespace, -with each representation in the form of a sequence of bytes with a -defined media type, character set, encoding, etc. Each resource may be -associated with zero, one, or more than one representation -at any given time. If multiple representations are available, -the resource is referred to as <STRONG>negotiable</STRONG> and each of its -representations is termed a <STRONG>variant</STRONG>. The ways in which the -variants for a negotiable resource vary are called the -<STRONG>dimensions</STRONG> of negotiation. - -<H2>Negotiation in Apache</H2> - -<P> -In order to negotiate a resource, the server needs to be given -information about each of the variants. This is done in one of two -ways: - -<UL> - <LI> Using a type map (<EM>i.e.</EM>, a <CODE>*.var</CODE> file) which - names the files containing the variants explicitly, or - <LI> Using a 'MultiViews' search, where the server does an implicit - filename pattern match and chooses from among the results. -</UL> - -<H3>Using a type-map file</H3> - -<P> -A type map is a document which is associated with the handler -named <CODE>type-map</CODE> (or, for backwards-compatibility with -older Apache configurations, the mime type -<CODE>application/x-type-map</CODE>). Note that to use this feature, -you must have a handler set in the configuration that defines a -file suffix as <CODE>type-map</CODE>; this is best done with a - -<PRE> - AddHandler type-map var -</PRE> - -in the server configuration file. See the comments in the sample config -file for more details. <P> - -Type map files have an entry for each available variant; these entries -consist of contiguous HTTP-format header lines. Entries for -different variants are separated by blank lines. Blank lines are -illegal within an entry. It is conventional to begin a map file with -an entry for the combined entity as a whole (although this -is not required, and if present will be ignored). An example -map file is: - -<PRE> - URI: foo - - URI: foo.en.html - Content-type: text/html - Content-language: en - - URI: foo.fr.de.html - Content-type: text/html;charset=iso-8859-2 - Content-language: fr, de -</PRE> - -If the variants have different source qualities, that may be indicated -by the "qs" parameter to the media type, as in this picture (available -as jpeg, gif, or ASCII-art): - -<PRE> - URI: foo - - URI: foo.jpeg - Content-type: image/jpeg; qs=0.8 - - URI: foo.gif - Content-type: image/gif; qs=0.5 - - URI: foo.txt - Content-type: text/plain; qs=0.01 -</PRE> -<P> - -qs values can vary in the range 0.000 to 1.000. Note that any variant with -a qs value of 0.000 will never be chosen. Variants with no 'qs' -parameter value are given a qs factor of 1.0. The qs parameter indicates -the relative 'quality' of this variant compared to the other available -variants, independent of the client's capabilities. For example, a jpeg -file is usually of higher source quality than an ascii file if it is -attempting to represent a photograph. However, if the resource being -represented is an original ascii art, then an ascii representation would -have a higher source quality than a jpeg representation. A qs value -is therefore specific to a given variant depending on the nature of -the resource it represents. - -<P> -The full list of headers recognized is: - -<DL> - <DT> <CODE>URI:</CODE> - <DD> uri of the file containing the variant (of the given media - type, encoded with the given content encoding). These are - interpreted as URLs relative to the map file; they must be on - the same server (!), and they must refer to files to which the - client would be granted access if they were to be requested - directly. - <DT> <CODE>Content-Type:</CODE> - <DD> media type --- charset, level and "qs" parameters may be given. These - are often referred to as MIME types; typical media types are - <CODE>image/gif</CODE>, <CODE>text/plain</CODE>, or - <CODE>text/html; level=3</CODE>. - <DT> <CODE>Content-Language:</CODE> - <DD> The languages of the variant, specified as an Internet standard - language tag from RFC 1766 (<EM>e.g.</EM>, <CODE>en</CODE> for English, - <CODE>kr</CODE> for Korean, <EM>etc.</EM>). - <DT> <CODE>Content-Encoding:</CODE> - <DD> If the file is compressed, or otherwise encoded, rather than - containing the actual raw data, this says how that was done. - Apache only recognizes encodings that are defined by an - <A HREF="mod/mod_mime.html#addencoding">AddEncoding</A> directive. - This normally includes the encodings <CODE>x-compress</CODE> - for compress'd files, and <CODE>x-gzip</CODE> for gzip'd files. - The <CODE>x-</CODE> prefix is ignored for encoding comparisons. - <DT> <CODE>Content-Length:</CODE> - <DD> The size of the file. Specifying content - lengths in the type-map allows the server to compare file sizes - without checking the actual files. - <DT> <CODE>Description:</CODE> - <DD> A human-readable textual description of the variant. If Apache cannot - find any appropriate variant to return, it will return an error - response which lists all available variants instead. Such a variant - list will include the human-readable variant descriptions. -</DL> - -<H3>Multiviews</H3> - -<P> -<CODE>MultiViews</CODE> is a per-directory option, meaning it can be set with -an <CODE>Options</CODE> directive within a <CODE><Directory></CODE>, -<CODE><Location></CODE> or <CODE><Files></CODE> -section in <CODE>access.conf</CODE>, or (if <CODE>AllowOverride</CODE> -is properly set) in <CODE>.htaccess</CODE> files. Note that -<CODE>Options All</CODE> does not set <CODE>MultiViews</CODE>; you -have to ask for it by name. - -<P> -The effect of <CODE>MultiViews</CODE> is as follows: if the server -receives a request for <CODE>/some/dir/foo</CODE>, if -<CODE>/some/dir</CODE> has <CODE>MultiViews</CODE> enabled, and -<CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the -directory looking for files named foo.*, and effectively fakes up a -type map which names all those files, assigning them the same media -types and content-encodings it would have if the client had asked for -one of them by name. It then chooses the best match to the client's -requirements. - -<P> -<CODE>MultiViews</CODE> may also apply to searches for the file named by the -<CODE>DirectoryIndex</CODE> directive, if the server is trying to -index a directory. If the configuration files specify - -<PRE> - DirectoryIndex index -</PRE> - -then the server will arbitrate between <CODE>index.html</CODE> -and <CODE>index.html3</CODE> if both are present. If neither are -present, and <CODE>index.cgi</CODE> is there, the server will run it. - -<P> -If one of the files found when reading the directive is a CGI script, -it's not obvious what should happen. The code gives that case -special treatment --- if the request was a POST, or a GET with -QUERY_ARGS or PATH_INFO, the script is given an extremely high quality -rating, and generally invoked; otherwise it is given an extremely low -quality rating, which generally causes one of the other views (if any) -to be retrieved. - -<H2>The Negotiation Methods</H2> - -After Apache has obtained a list of the variants for a given resource, -either from a type-map file or from the filenames in the directory, it -invokes one of two methods to decide on the 'best' variant to -return, if any. It is not necessary to know any of the details of how -negotiation actually takes place in order to use Apache's content -negotiation features. However the rest of this document explains the -methods used for those interested. -<P> - -There are two negotiation methods: - -<OL> - -<LI><STRONG>Server driven negotiation with the Apache -algorithm</STRONG> is used in the normal case. The Apache algorithm is -explained in more detail below. When this algorithm is used, Apache -can sometimes 'fiddle' the quality factor of a particular dimension to -achieve a better result. The ways Apache can fiddle quality factors is -explained in more detail below. - -<LI><STRONG>Transparent content negotiation</STRONG> is used when the -browser specifically requests this through the mechanism defined in RFC -2295. This negotiation method gives the browser full control over -deciding on the 'best' variant, the result is therefore dependent on -the specific algorithms used by the browser. As part of the -transparent negotiation process, the browser can ask Apache to run the -'remote variant selection algorithm' defined in RFC 2296. </UL> - - -<H3>Dimensions of Negotiation</H3> - -<TABLE> -<TR valign="top"> -<TH>Dimension -<TH>Notes -<TR valign="top"> -<TD>Media Type -<TD>Browser indicates preferences with the Accept header field. Each item -can have an associated quality factor. Variant description can also -have a quality factor (the "qs" parameter). -<TR valign="top"> -<TD>Language -<TD>Browser indicates preferences with the Accept-Language header field. -Each item can have a quality factor. Variants can be associated with none, one -or more than one language. -<TR valign="top"> -<TD>Encoding -<TD>Browser indicates preference with the Accept-Encoding header field. -Each item can have a quality factor. -<TR valign="top"> -<TD>Charset -<TD>Browser indicates preference with the Accept-Charset header field. -Each item can have a quality factor. -Variants can indicate a charset as a parameter of the media type. -</TABLE> - -<H3>Apache Negotiation Algorithm</H3> - -<P> -Apache can use the following algorithm to select the 'best' variant -(if any) to return to the browser. This algorithm is not -further configurable. It operates as follows: - -<OL> -<LI>First, for each dimension of the negotiation, check the appropriate -<EM>Accept*</EM> header field and assign a quality to each -variant. If the <EM>Accept*</EM> header for any dimension implies that this -variant is not acceptable, eliminate it. If no variants remain, go -to step 4. - -<LI>Select the 'best' variant by a process of elimination. Each of the -following tests is applied in order. Any variants not selected at each -test are eliminated. After each test, if only one variant remains, -select it as the best match and proceed to step 3. If more than one -variant remains, move on to the next test. - -<OL> -<LI>Multiply the quality factor from the Accept header with the - quality-of-source factor for this variant's media type, and select - the variants with the highest value. - -<LI>Select the variants with the highest language quality factor. - -<LI>Select the variants with the best language match, using either the - order of languages in the Accept-Language header (if present), or else - else the order of languages in the <CODE>LanguagePriority</CODE> - directive (if present). - -<LI>Select the variants with the highest 'level' media parameter - (used to give the version of text/html media types). - -<LI>Select variants with the best charset media parameters, - as given on the Accept-Charset header line. Charset ISO-8859-1 - is acceptable unless explicitly excluded. Variants with a - <CODE>text/*</CODE> media type but not explicitly associated - with a particular charset are assumed to be in ISO-8859-1. - -<LI>Select those variants which have associated - charset media parameters that are <EM>not</EM> ISO-8859-1. - If there are no such variants, select all variants instead. - -<LI>Select the variants with the best encoding. If there are - variants with an encoding that is acceptable to the user-agent, - select only these variants. Otherwise if there is a mix of encoded - and non-encoded variants, select only the unencoded variants. - If either all variants are encoded or all variants are not encoded, - select all variants. - -<LI>Select the variants with the smallest content length. - -<LI>Select the first variant of those remaining. This will be either the - first listed in the type-map file, or when variants are read from - the directory, the one whose file name comes first when sorted using - ASCII code order. - -</OL> - -<LI>The algorithm has now selected one 'best' variant, so return - it as the response. The HTTP response header Vary is set to indicate the - dimensions of negotiation (browsers and caches can use this - information when caching the resource). End. - -<LI>To get here means no variant was selected (because none are acceptable - to the browser). Return a 406 status (meaning "No acceptable representation") - with a response body consisting of an HTML document listing the - available variants. Also set the HTTP Vary header to indicate the - dimensions of variance. - -</OL> - -<H2><A NAME="better">Fiddling with Quality Values</A></H2> - -<P> -Apache sometimes changes the quality values from what would be -expected by a strict interpretation of the Apache negotiation -algorithm above. This is to get a better result from the algorithm for -browsers which do not send full or accurate information. Some of the -most popular browsers send Accept header information which would -otherwise result in the selection of the wrong variant in many -cases. If a browser sends full and correct information these fiddles -will not be applied. -<P> - -<H3>Media Types and Wildcards</H3> - -<P> -The Accept: request header indicates preferences for media types. It -can also include 'wildcard' media types, such as "image/*" or "*/*" -where the * matches any string. So a request including: -<PRE> - Accept: image/*, */* -</PRE> - -would indicate that any type starting "image/" is acceptable, -as is any other type (so the first "image/*" is redundant). Some -browsers routinely send wildcards in addition to explicit types they -can handle. For example: -<PRE> - Accept: text/html, text/plain, image/gif, image/jpeg, */* -</PRE> - -The intention of this is to indicate that the explicitly -listed types are preferred, but if a different representation is -available, that is ok too. However under the basic algorithm, as given -above, the */* wildcard has exactly equal preference to all the other -types, so they are not being preferred. The browser should really have -sent a request with a lower quality (preference) value for *.*, such -as: -<PRE> - Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01 -</PRE> - -The explicit types have no quality factor, so they default to a -preference of 1.0 (the highest). The wildcard */* is given -a low preference of 0.01, so other types will only be returned if -no variant matches an explicitly listed type. -<P> - -If the Accept: header contains <EM>no</EM> q factors at all, Apache sets -the q value of "*/*", if present, to 0.01 to emulate the desired -behavior. It also sets the q value of wildcards of the format -"type/*" to 0.02 (so these are preferred over matches against -"*/*". If any media type on the Accept: header contains a q factor, -these special values are <EM>not</EM> applied, so requests from browsers -which send the correct information to start with work as expected. - -<H3>Variants with no Language</H3> - -<P> -If some of the variants for a particular resource have a language -attribute, and some do not, those variants with no language -are given a very low language quality factor of 0.001.<P> - -The reason for setting this language quality factor for -variant with no language to a very low value is to allow -for a default variant which can be supplied if none of the -other variants match the browser's language preferences. - -For example, consider the situation with three variants: - -<UL> -<LI>foo.en.html, language en -<LI>foo.fr.html, language en -<LI>foo.html, no language -</UL> - -<P> -The meaning of a variant with no language is that it is -always acceptable to the browser. If the request Accept-Language -header includes either en or fr (or both) one of foo.en.html -or foo.fr.html will be returned. If the browser does not list -either en or fr as acceptable, foo.html will be returned instead. - -<H2>Extensions to Transparent Content Negotiation</H2> - -Apache extends the transparent content negotiation protocol (RFC 2295) -as follows. A new <CODE> {encoding ..}</CODE> element is used in -variant lists to label variants which are available with a specific -content-encoding only. The implementation of the -RVSA/1.0 algorithm (RFC 2296) is extended to recognize encoded -variants in the list, and to use them as candidate variants whenever -their encodings are acceptable according to the Accept-Encoding -request header. The RVSA/1.0 implementation does not round computed -quality factors to 5 decimal places before choosing the best variant. - -<H2>Note on hyperlinks and naming conventions</H2> - -<P> -If you are using language negotiation you can choose between -different naming conventions, because files can have more than one -extension, and the order of the extensions is normally irrelevant -(see <A HREF="mod/mod_mime.html">mod_mime</A> documentation for details). -<P> -A typical file has a MIME-type extension (<EM>e.g.</EM>, <SAMP>html</SAMP>), -maybe an encoding extension (<EM>e.g.</EM>, <SAMP>gz</SAMP>), and of course a -language extension (<EM>e.g.</EM>, <SAMP>en</SAMP>) when we have different -language variants of this file. - -<P> -Examples: -<UL> -<LI>foo.en.html -<LI>foo.html.en -<LI>foo.en.html.gz -</UL> - -<P> -Here some more examples of filenames together with valid and invalid -hyperlinks: -</P> - -<TABLE BORDER=1 CELLPADDING=8 CELLSPACING=0> -<TR> - <TH>Filename</TH> - <TH>Valid hyperlink</TH> - <TH>Invalid hyperlink</TH> -</TR> -<TR> - <TD><EM>foo.html.en</EM></TD> - <TD>foo<BR> - foo.html</TD> - <TD>-</TD> -</TR> -<TR> - <TD><EM>foo.en.html</EM></TD> - <TD>foo</TD> - <TD>foo.html</TD> -</TR> -<TR> - <TD><EM>foo.html.en.gz</EM></TD> - <TD>foo<BR> - foo.html</TD> - <TD>foo.gz<BR> - foo.html.gz</TD> -</TR> -<TR> - <TD><EM>foo.en.html.gz</EM></TD> - <TD>foo</TD> - <TD>foo.html<BR> - foo.html.gz<BR> - foo.gz</TD> -</TR> -<TR> - <TD><EM>foo.gz.html.en</EM></TD> - <TD>foo<BR> - foo.gz<BR> - foo.gz.html</TD> - <TD>foo.html</TD> -</TR> -<TR> - <TD><EM>foo.html.gz.en</EM></TD> - <TD>foo<BR> - foo.html<BR> - foo.html.gz</TD> - <TD>foo.gz</TD> -</TR> -</TABLE> - -<P> -Looking at the table above you will notice that it is always possible to -use the name without any extensions in an hyperlink (<EM>e.g.</EM>, <SAMP>foo</SAMP>). -The advantage is that you can hide the actual type of a -document rsp. file and can change it later, <EM>e.g.</EM>, from <SAMP>html</SAMP> -to <SAMP>shtml</SAMP> or <SAMP>cgi</SAMP> without changing any -hyperlink references. - -<P> -If you want to continue to use a MIME-type in your hyperlinks (<EM>e.g.</EM> -<SAMP>foo.html</SAMP>) the language extension (including an encoding extension -if there is one) must be on the right hand side of the MIME-type extension -(<EM>e.g.</EM>, <SAMP>foo.html.en</SAMP>). - - -<H2>Note on Caching</H2> - -<P> -When a cache stores a representation, it associates it with the request URL. -The next time that URL is requested, the cache can use the stored -representation. But, if the resource is negotiable at the server, -this might result in only the first requested variant being cached and -subsequent cache hits might return the wrong response. To prevent this, -Apache normally marks all responses that are returned after content negotiation -as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1 -protocol features to allow caching of negotiated responses. <P> - -For requests which come from a HTTP/1.0 compliant client (either a -browser or a cache), the directive <TT>CacheNegotiatedDocs</TT> can be -used to allow caching of responses which were subject to negotiation. -This directive can be given in the server config or virtual host, and -takes no arguments. It has no effect on requests from HTTP/1.1 clients. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/custom-error.html b/docs/manual/custom-error.html deleted file mode 100644 index 09604ea972..0000000000 --- a/docs/manual/custom-error.html +++ /dev/null @@ -1,177 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Custom error responses</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Custom error responses</H1> - -<DL> - -<DT>Purpose - - <DD>Additional functionality. Allows webmasters to configure the response of - Apache to some error or problem. - - <P>Customizable responses can be defined to be activated in the - event of a server detected error or problem. - - <P>e.g. if a script crashes and produces a "500 Server Error" - response, then this response can be replaced with either some - friendlier text or by a redirection to another URL (local or - external). - <P> - -<DT>Old behavior - - <DD>NCSA httpd 1.3 would return some boring old error/problem message - which would often be meaningless to the user, and would provide no - means of logging the symptoms which caused it.<BR> - - <P> - -<DT>New behavior - - <DD>The server can be asked to; - <OL> - <LI>Display some other text, instead of the NCSA hard coded messages, or - <LI>redirect to a local URL, or - <LI>redirect to an external URL. - </OL> - - <P>Redirecting to another URL can be useful, but only if some information - can be passed which can then be used to explain and/or log the - error/problem - more clearly. - - <P>To achieve this, Apache will define new CGI-like environment - variables, <EM>e.g.</EM> - - <BLOCKQUOTE><CODE> -REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <BR> -REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <BR> -REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <BR> -REDIRECT_QUERY_STRING= <BR> -REDIRECT_REMOTE_ADDR=121.345.78.123 <BR> -REDIRECT_REMOTE_HOST=ooh.ahhh.com <BR> -REDIRECT_SERVER_NAME=crash.bang.edu <BR> -REDIRECT_SERVER_PORT=80 <BR> -REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <BR> -REDIRECT_URL=/cgi-bin/buggy.pl <BR> - </CODE></BLOCKQUOTE> - - <P>note the <CODE>REDIRECT_</CODE> prefix. - - <P>At least <CODE>REDIRECT_URL</CODE> and <CODE>REDIRECT_QUERY_STRING</CODE> - will - be passed to the new URL (assuming it's a cgi-script or a cgi-include). - The - other variables will exist only if they existed prior to the - error/problem. - <STRONG>None</STRONG> of these will be set if your ErrorDocument is an - <EM>external</EM> redirect (<EM>i.e.</EM>, anything starting with a - scheme name - like <CODE>http:</CODE>, even if it refers to the same host as the - server).<P> - -<DT>Configuration - - <DD> Use of "ErrorDocument" is enabled for .htaccess files when the - <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is - allowed. - - <P>Here are some examples... - - <BLOCKQUOTE><CODE> -ErrorDocument 500 /cgi-bin/crash-recover <BR> -ErrorDocument 500 "Sorry, our script crashed. Oh dear<BR> -ErrorDocument 500 http://xxx/ <BR> -ErrorDocument 404 /Lame_excuses/not_found.html <BR> -ErrorDocument 401 /Subscription/how_to_subscribe.html - </CODE></BLOCKQUOTE> - - <P>The syntax is, - - <P><CODE><A HREF="mod/core.html#errordocument">ErrorDocument</A></CODE> -<3-digit-code> action - - <P>where the action can be, - - <OL> - <LI>Text to be displayed. Prefix the text with a quote ("). Whatever - follows the quote is displayed. <EM>Note: the (") prefix isn't - displayed.</EM> - - <LI>An external URL to redirect to. - - <LI>A local URL to redirect to. - - </OL> -</DL> - -<P><HR><P> - -<H2>Custom error responses and redirects</H2> - -<DL> - -<DT>Purpose - - <DD>Apache's behavior to redirected URLs has been modified so that additional - environment variables are available to a script/server-include.<P> - -<DT>Old behavior - - <DD>Standard CGI vars were made available to a script which has been - redirected to. No indication of where the redirection came from was - provided. - - <P> - -<DT>New behavior - <DD> - -A new batch of environment variables will be initialized for use by a -script which has been redirected to. Each new variable will have the -prefix <CODE>REDIRECT_</CODE>. <CODE>REDIRECT_</CODE> environment -variables are created from the CGI environment variables which existed -prior to the redirect, they are renamed with a <CODE>REDIRECT_</CODE> -prefix, <EM>i.e.</EM>, <CODE>HTTP_USER_AGENT</CODE> becomes -<CODE>REDIRECT_HTTP_USER_AGENT</CODE>. In addition to these new -variables, Apache will define <CODE>REDIRECT_URL</CODE> and -<CODE>REDIRECT_STATUS</CODE> to help the script trace its origin. -Both the original URL and the URL being redirected to can be logged in -the access log. - -</DL> -<P> -If the ErrorDocument specifies a local redirect to a CGI script, the script -should include a "<SAMP>Status:</SAMP>" header field in its output -in order to ensure the propagation all the way back to the client -of the error condition that caused it to be invoked. For instance, a Perl -ErrorDocument script might include the following: -</P> -<PRE> - : - print "Content-type: text/html\n"; - printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; - : -</PRE> -<P> -If the script is dedicated to handling a particular error condition, such as -<SAMP>404 Not Found</SAMP>, it can use the specific code and -error text instead. -</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/custom-error.html.en b/docs/manual/custom-error.html.en deleted file mode 100644 index 09604ea972..0000000000 --- a/docs/manual/custom-error.html.en +++ /dev/null @@ -1,177 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Custom error responses</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Custom error responses</H1> - -<DL> - -<DT>Purpose - - <DD>Additional functionality. Allows webmasters to configure the response of - Apache to some error or problem. - - <P>Customizable responses can be defined to be activated in the - event of a server detected error or problem. - - <P>e.g. if a script crashes and produces a "500 Server Error" - response, then this response can be replaced with either some - friendlier text or by a redirection to another URL (local or - external). - <P> - -<DT>Old behavior - - <DD>NCSA httpd 1.3 would return some boring old error/problem message - which would often be meaningless to the user, and would provide no - means of logging the symptoms which caused it.<BR> - - <P> - -<DT>New behavior - - <DD>The server can be asked to; - <OL> - <LI>Display some other text, instead of the NCSA hard coded messages, or - <LI>redirect to a local URL, or - <LI>redirect to an external URL. - </OL> - - <P>Redirecting to another URL can be useful, but only if some information - can be passed which can then be used to explain and/or log the - error/problem - more clearly. - - <P>To achieve this, Apache will define new CGI-like environment - variables, <EM>e.g.</EM> - - <BLOCKQUOTE><CODE> -REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <BR> -REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <BR> -REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <BR> -REDIRECT_QUERY_STRING= <BR> -REDIRECT_REMOTE_ADDR=121.345.78.123 <BR> -REDIRECT_REMOTE_HOST=ooh.ahhh.com <BR> -REDIRECT_SERVER_NAME=crash.bang.edu <BR> -REDIRECT_SERVER_PORT=80 <BR> -REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <BR> -REDIRECT_URL=/cgi-bin/buggy.pl <BR> - </CODE></BLOCKQUOTE> - - <P>note the <CODE>REDIRECT_</CODE> prefix. - - <P>At least <CODE>REDIRECT_URL</CODE> and <CODE>REDIRECT_QUERY_STRING</CODE> - will - be passed to the new URL (assuming it's a cgi-script or a cgi-include). - The - other variables will exist only if they existed prior to the - error/problem. - <STRONG>None</STRONG> of these will be set if your ErrorDocument is an - <EM>external</EM> redirect (<EM>i.e.</EM>, anything starting with a - scheme name - like <CODE>http:</CODE>, even if it refers to the same host as the - server).<P> - -<DT>Configuration - - <DD> Use of "ErrorDocument" is enabled for .htaccess files when the - <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is - allowed. - - <P>Here are some examples... - - <BLOCKQUOTE><CODE> -ErrorDocument 500 /cgi-bin/crash-recover <BR> -ErrorDocument 500 "Sorry, our script crashed. Oh dear<BR> -ErrorDocument 500 http://xxx/ <BR> -ErrorDocument 404 /Lame_excuses/not_found.html <BR> -ErrorDocument 401 /Subscription/how_to_subscribe.html - </CODE></BLOCKQUOTE> - - <P>The syntax is, - - <P><CODE><A HREF="mod/core.html#errordocument">ErrorDocument</A></CODE> -<3-digit-code> action - - <P>where the action can be, - - <OL> - <LI>Text to be displayed. Prefix the text with a quote ("). Whatever - follows the quote is displayed. <EM>Note: the (") prefix isn't - displayed.</EM> - - <LI>An external URL to redirect to. - - <LI>A local URL to redirect to. - - </OL> -</DL> - -<P><HR><P> - -<H2>Custom error responses and redirects</H2> - -<DL> - -<DT>Purpose - - <DD>Apache's behavior to redirected URLs has been modified so that additional - environment variables are available to a script/server-include.<P> - -<DT>Old behavior - - <DD>Standard CGI vars were made available to a script which has been - redirected to. No indication of where the redirection came from was - provided. - - <P> - -<DT>New behavior - <DD> - -A new batch of environment variables will be initialized for use by a -script which has been redirected to. Each new variable will have the -prefix <CODE>REDIRECT_</CODE>. <CODE>REDIRECT_</CODE> environment -variables are created from the CGI environment variables which existed -prior to the redirect, they are renamed with a <CODE>REDIRECT_</CODE> -prefix, <EM>i.e.</EM>, <CODE>HTTP_USER_AGENT</CODE> becomes -<CODE>REDIRECT_HTTP_USER_AGENT</CODE>. In addition to these new -variables, Apache will define <CODE>REDIRECT_URL</CODE> and -<CODE>REDIRECT_STATUS</CODE> to help the script trace its origin. -Both the original URL and the URL being redirected to can be logged in -the access log. - -</DL> -<P> -If the ErrorDocument specifies a local redirect to a CGI script, the script -should include a "<SAMP>Status:</SAMP>" header field in its output -in order to ensure the propagation all the way back to the client -of the error condition that caused it to be invoked. For instance, a Perl -ErrorDocument script might include the following: -</P> -<PRE> - : - print "Content-type: text/html\n"; - printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; - : -</PRE> -<P> -If the script is dedicated to handling a particular error condition, such as -<SAMP>404 Not Found</SAMP>, it can use the specific code and -error text instead. -</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/developer/API.html b/docs/manual/developer/API.html deleted file mode 100644 index bf0fb77d7a..0000000000 --- a/docs/manual/developer/API.html +++ /dev/null @@ -1,1153 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Apache API notes</TITLE> -</HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache API notes</H1> - -These are some notes on the Apache API and the data structures you -have to deal with, <EM>etc.</EM> They are not yet nearly complete, but -hopefully, they will help you get your bearings. Keep in mind that -the API is still subject to change as we gain experience with it. -(See the TODO file for what <EM>might</EM> be coming). However, -it will be easy to adapt modules to any changes that are made. -(We have more modules to adapt than you do). -<P> - -A few notes on general pedagogical style here. In the interest of -conciseness, all structure declarations here are incomplete --- the -real ones have more slots that I'm not telling you about. For the -most part, these are reserved to one component of the server core or -another, and should be altered by modules with caution. However, in -some cases, they really are things I just haven't gotten around to -yet. Welcome to the bleeding edge.<P> - -Finally, here's an outline, to give you some bare idea of what's -coming up, and in what order: - -<UL> -<LI> <A HREF="#basics">Basic concepts.</A> -<MENU> - <LI> <A HREF="#HMR">Handlers, Modules, and Requests</A> - <LI> <A HREF="#moduletour">A brief tour of a module</A> -</MENU> -<LI> <A HREF="#handlers">How handlers work</A> -<MENU> - <LI> <A HREF="#req_tour">A brief tour of the <CODE>request_rec</CODE></A> - <LI> <A HREF="#req_orig">Where request_rec structures come from</A> - <LI> <A HREF="#req_return">Handling requests, declining, and returning error - codes</A> - <LI> <A HREF="#resp_handlers">Special considerations for response handlers</A> - <LI> <A HREF="#auth_handlers">Special considerations for authentication - handlers</A> - <LI> <A HREF="#log_handlers">Special considerations for logging handlers</A> -</MENU> -<LI> <A HREF="#pools">Resource allocation and resource pools</A> -<LI> <A HREF="#config">Configuration, commands and the like</A> -<MENU> - <LI> <A HREF="#per-dir">Per-directory configuration structures</A> - <LI> <A HREF="#commands">Command handling</A> - <LI> <A HREF="#servconf">Side notes --- per-server configuration, - virtual servers, <EM>etc</EM>.</A> -</MENU> -</UL> - -<H2><A NAME="basics">Basic concepts.</A></H2> - -We begin with an overview of the basic concepts behind the -API, and how they are manifested in the code. - -<H3><A NAME="HMR">Handlers, Modules, and Requests</A></H3> - -Apache breaks down request handling into a series of steps, more or -less the same way the Netscape server API does (although this API has -a few more stages than NetSite does, as hooks for stuff I thought -might be useful in the future). These are: - -<UL> - <LI> URI -> Filename translation - <LI> Auth ID checking [is the user who they say they are?] - <LI> Auth access checking [is the user authorized <EM>here</EM>?] - <LI> Access checking other than auth - <LI> Determining MIME type of the object requested - <LI> `Fixups' --- there aren't any of these yet, but the phase is - intended as a hook for possible extensions like - <CODE>SetEnv</CODE>, which don't really fit well elsewhere. - <LI> Actually sending a response back to the client. - <LI> Logging the request -</UL> - -These phases are handled by looking at each of a succession of -<EM>modules</EM>, looking to see if each of them has a handler for the -phase, and attempting invoking it if so. The handler can typically do -one of three things: - -<UL> - <LI> <EM>Handle</EM> the request, and indicate that it has done so - by returning the magic constant <CODE>OK</CODE>. - <LI> <EM>Decline</EM> to handle the request, by returning the magic - integer constant <CODE>DECLINED</CODE>. In this case, the - server behaves in all respects as if the handler simply hadn't - been there. - <LI> Signal an error, by returning one of the HTTP error codes. - This terminates normal handling of the request, although an - ErrorDocument may be invoked to try to mop up, and it will be - logged in any case. -</UL> - -Most phases are terminated by the first module that handles them; -however, for logging, `fixups', and non-access authentication -checking, all handlers always run (barring an error). Also, the -response phase is unique in that modules may declare multiple handlers -for it, via a dispatch table keyed on the MIME type of the requested -object. Modules may declare a response-phase handler which can handle -<EM>any</EM> request, by giving it the key <CODE>*/*</CODE> (<EM>i.e.</EM>, a -wildcard MIME type specification). However, wildcard handlers are -only invoked if the server has already tried and failed to find a more -specific response handler for the MIME type of the requested object -(either none existed, or they all declined).<P> - -The handlers themselves are functions of one argument (a -<CODE>request_rec</CODE> structure. vide infra), which returns an -integer, as above.<P> - -<H3><A NAME="moduletour">A brief tour of a module</A></H3> - -At this point, we need to explain the structure of a module. Our -candidate will be one of the messier ones, the CGI module --- this -handles both CGI scripts and the <CODE>ScriptAlias</CODE> config file -command. It's actually a great deal more complicated than most -modules, but if we're going to have only one example, it might as well -be the one with its fingers in every place.<P> - -Let's begin with handlers. In order to handle the CGI scripts, the -module declares a response handler for them. Because of -<CODE>ScriptAlias</CODE>, it also has handlers for the name -translation phase (to recognize <CODE>ScriptAlias</CODE>ed URIs), the -type-checking phase (any <CODE>ScriptAlias</CODE>ed request is typed -as a CGI script).<P> - -The module needs to maintain some per (virtual) -server information, namely, the <CODE>ScriptAlias</CODE>es in effect; -the module structure therefore contains pointers to a functions which -builds these structures, and to another which combines two of them (in -case the main server and a virtual server both have -<CODE>ScriptAlias</CODE>es declared).<P> - -Finally, this module contains code to handle the -<CODE>ScriptAlias</CODE> command itself. This particular module only -declares one command, but there could be more, so modules have -<EM>command tables</EM> which declare their commands, and describe -where they are permitted, and how they are to be invoked. <P> - -A final note on the declared types of the arguments of some of these -commands: a <CODE>pool</CODE> is a pointer to a <EM>resource pool</EM> -structure; these are used by the server to keep track of the memory -which has been allocated, files opened, <EM>etc.</EM>, either to service a -particular request, or to handle the process of configuring itself. -That way, when the request is over (or, for the configuration pool, -when the server is restarting), the memory can be freed, and the files -closed, <EM>en masse</EM>, without anyone having to write explicit code to -track them all down and dispose of them. Also, a -<CODE>cmd_parms</CODE> structure contains various information about -the config file being read, and other status information, which is -sometimes of use to the function which processes a config-file command -(such as <CODE>ScriptAlias</CODE>). - -With no further ado, the module itself: - -<PRE> -/* Declarations of handlers. */ - -int translate_scriptalias (request_rec *); -int type_scriptalias (request_rec *); -int cgi_handler (request_rec *); - -/* Subsidiary dispatch table for response-phase handlers, by MIME type */ - -handler_rec cgi_handlers[] = { -{ "application/x-httpd-cgi", cgi_handler }, -{ NULL } -}; - -/* Declarations of routines to manipulate the module's configuration - * info. Note that these are returned, and passed in, as void *'s; - * the server core keeps track of them, but it doesn't, and can't, - * know their internal structure. - */ - -void *make_cgi_server_config (pool *); -void *merge_cgi_server_config (pool *, void *, void *); - -/* Declarations of routines to handle config-file commands */ - -extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake, - char *real); - -command_rec cgi_cmds[] = { -{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2, - "a fakename and a realname"}, -{ NULL } -}; - -module cgi_module = { - STANDARD_MODULE_STUFF, - NULL, /* initializer */ - NULL, /* dir config creator */ - NULL, /* dir merger --- default is to override */ - make_cgi_server_config, /* server config */ - merge_cgi_server_config, /* merge server config */ - cgi_cmds, /* command table */ - cgi_handlers, /* handlers */ - translate_scriptalias, /* filename translation */ - NULL, /* check_user_id */ - NULL, /* check auth */ - NULL, /* check access */ - type_scriptalias, /* type_checker */ - NULL, /* fixups */ - NULL, /* logger */ - NULL /* header parser */ -}; -</PRE> - -<H2><A NAME="handlers">How handlers work</A></H2> - -The sole argument to handlers is a <CODE>request_rec</CODE> structure. -This structure describes a particular request which has been made to -the server, on behalf of a client. In most cases, each connection to -the client generates only one <CODE>request_rec</CODE> structure.<P> - -<H3><A NAME="req_tour">A brief tour of the <CODE>request_rec</CODE></A></H3> - -The <CODE>request_rec</CODE> contains pointers to a resource pool -which will be cleared when the server is finished handling the -request; to structures containing per-server and per-connection -information, and most importantly, information on the request itself.<P> - -The most important such information is a small set of character -strings describing attributes of the object being requested, including -its URI, filename, content-type and content-encoding (these being filled -in by the translation and type-check handlers which handle the -request, respectively). <P> - -Other commonly used data items are tables giving the MIME headers on -the client's original request, MIME headers to be sent back with the -response (which modules can add to at will), and environment variables -for any subprocesses which are spawned off in the course of servicing -the request. These tables are manipulated using the -<CODE>ap_table_get</CODE> and <CODE>ap_table_set</CODE> routines. <P> -<BLOCKQUOTE> - Note that the <SAMP>Content-type</SAMP> header value <EM>cannot</EM> be - set by module content-handlers using the <SAMP>ap_table_*()</SAMP> - routines. Rather, it is set by pointing the <SAMP>content_type</SAMP> - field in the <SAMP>request_rec</SAMP> structure to an appropriate - string. <EM>E.g.</EM>, - <PRE> - r->content_type = "text/html"; - </PRE> -</BLOCKQUOTE> -Finally, there are pointers to two data structures which, in turn, -point to per-module configuration structures. Specifically, these -hold pointers to the data structures which the module has built to -describe the way it has been configured to operate in a given -directory (via <CODE>.htaccess</CODE> files or -<CODE><Directory></CODE> sections), for private data it has -built in the course of servicing the request (so modules' handlers for -one phase can pass `notes' to their handlers for other phases). There -is another such configuration vector in the <CODE>server_rec</CODE> -data structure pointed to by the <CODE>request_rec</CODE>, which -contains per (virtual) server configuration data.<P> - -Here is an abridged declaration, giving the fields most commonly used:<P> - -<PRE> -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, <EM>etc.</EM> */ - int method_number; /* M_GET, M_POST, <EM>etc.</EM> */ - - /* 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, <EM>etc.</EM> */ - void *request_config; /* Notes on *this* request */ - -}; - -</PRE> - -<H3><A NAME="req_orig">Where request_rec structures come from</A></H3> - -Most <CODE>request_rec</CODE> structures are built by reading an HTTP -request from a client, and filling in the fields. However, there are -a few exceptions: - -<UL> - <LI> If the request is to an imagemap, a type map (<EM>i.e.</EM>, a - <CODE>*.var</CODE> file), or a CGI script which returned a - local `Location:', then the resource which the user requested - is going to be ultimately located by some URI other than what - the client originally supplied. In this case, the server does - an <EM>internal redirect</EM>, constructing a new - <CODE>request_rec</CODE> for the new URI, and processing it - almost exactly as if the client had requested the new URI - directly. <P> - - <LI> If some handler signaled an error, and an - <CODE>ErrorDocument</CODE> is in scope, the same internal - redirect machinery comes into play.<P> - - <LI> Finally, a handler occasionally needs to investigate `what - would happen if' some other request were run. For instance, - the directory indexing module needs to know what MIME type - would be assigned to a request for each directory entry, in - order to figure out what icon to use.<P> - - Such handlers can construct a <EM>sub-request</EM>, using the - functions <CODE>ap_sub_req_lookup_file</CODE>, - <CODE>ap_sub_req_lookup_uri</CODE>, and - <CODE>ap_sub_req_method_uri</CODE>; these construct a new - <CODE>request_rec</CODE> structure and processes it as you - would expect, up to but not including the point of actually - sending a response. (These functions skip over the access - checks if the sub-request is for a file in the same directory - as the original request).<P> - - (Server-side includes work by building sub-requests and then - actually invoking the response handler for them, via the - function <CODE>ap_run_sub_req</CODE>). -</UL> - -<H3><A NAME="req_return">Handling requests, declining, and returning error - codes</A></H3> - -As discussed above, each handler, when invoked to handle a particular -<CODE>request_rec</CODE>, has to return an <CODE>int</CODE> to -indicate what happened. That can either be - -<UL> - <LI> OK --- the request was handled successfully. This may or may - not terminate the phase. - <LI> DECLINED --- no erroneous condition exists, but the module - declines to handle the phase; the server tries to find another. - <LI> an HTTP error code, which aborts handling of the request. -</UL> - -Note that if the error code returned is <CODE>REDIRECT</CODE>, then -the module should put a <CODE>Location</CODE> in the request's -<CODE>headers_out</CODE>, to indicate where the client should be -redirected <EM>to</EM>. <P> - -<H3><A NAME="resp_handlers">Special considerations for response - handlers</A></H3> - -Handlers for most phases do their work by simply setting a few fields -in the <CODE>request_rec</CODE> structure (or, in the case of access -checkers, simply by returning the correct error code). However, -response handlers have to actually send a request back to the client. <P> - -They should begin by sending an HTTP response header, using the -function <CODE>ap_send_http_header</CODE>. (You don't have to do -anything special to skip sending the header for HTTP/0.9 requests; the -function figures out on its own that it shouldn't do anything). If -the request is marked <CODE>header_only</CODE>, that's all they should -do; they should return after that, without attempting any further -output. <P> - -Otherwise, they should produce a request body which responds to the -client as appropriate. The primitives for this are <CODE>ap_rputc</CODE> -and <CODE>ap_rprintf</CODE>, for internally generated output, and -<CODE>ap_send_fd</CODE>, to copy the contents of some <CODE>FILE *</CODE> -straight to the client. <P> - -At this point, you should more or less understand the following piece -of code, which is the handler which handles <CODE>GET</CODE> requests -which have no more specific handler; it also shows how conditional -<CODE>GET</CODE>s can be handled, if it's desirable to do so in a -particular response handler --- <CODE>ap_set_last_modified</CODE> checks -against the <CODE>If-modified-since</CODE> value supplied by the -client, if any, and returns an appropriate code (which will, if -nonzero, be USE_LOCAL_COPY). No similar considerations apply for -<CODE>ap_set_content_length</CODE>, but it returns an error code for -symmetry.<P> - -<PRE> -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 = ap_set_content_length (r, r->finfo.st_size)) - || (errstatus = ap_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); - ap_send_http_header (r); - - if (!r->header_only) send_fd (f, r); - ap_pfclose (r->pool, f); - return OK; -} -</PRE> - -Finally, if all of this is too much of a challenge, there are a few -ways out of it. First off, as shown above, a response handler which -has not yet produced any output can simply return an error code, in -which case the server will automatically produce an error response. -Secondly, it can punt to some other handler by invoking -<CODE>ap_internal_redirect</CODE>, which is how the internal redirection -machinery discussed above is invoked. A response handler which has -internally redirected should always return <CODE>OK</CODE>. <P> - -(Invoking <CODE>ap_internal_redirect</CODE> from handlers which are -<EM>not</EM> response handlers will lead to serious confusion). - -<H3><A NAME="auth_handlers">Special considerations for authentication - handlers</A></H3> - -Stuff that should be discussed here in detail: - -<UL> - <LI> Authentication-phase handlers not invoked unless auth is - configured for the directory. - <LI> Common auth configuration stored in the core per-dir - configuration; it has accessors <CODE>ap_auth_type</CODE>, - <CODE>ap_auth_name</CODE>, and <CODE>ap_requires</CODE>. - <LI> Common routines, to handle the protocol end of things, at least - for HTTP basic authentication (<CODE>ap_get_basic_auth_pw</CODE>, - which sets the <CODE>connection->user</CODE> structure field - automatically, and <CODE>ap_note_basic_auth_failure</CODE>, which - arranges for the proper <CODE>WWW-Authenticate:</CODE> header - to be sent back). -</UL> - -<H3><A NAME="log_handlers">Special considerations for logging handlers</A></H3> - -When a request has internally redirected, there is the question of -what to log. Apache handles this by bundling the entire chain of -redirects into a list of <CODE>request_rec</CODE> structures which are -threaded through the <CODE>r->prev</CODE> and <CODE>r->next</CODE> -pointers. The <CODE>request_rec</CODE> which is passed to the logging -handlers in such cases is the one which was originally built for the -initial request from the client; note that the bytes_sent field will -only be correct in the last request in the chain (the one for which a -response was actually sent). - -<H2><A NAME="pools">Resource allocation and resource pools</A></H2> -<P> -One of the problems of writing and designing a server-pool server is -that of preventing leakage, that is, allocating resources (memory, -open files, <EM>etc.</EM>), without subsequently releasing them. The resource -pool machinery is designed to make it easy to prevent this from -happening, by allowing resource to be allocated in such a way that -they are <EM>automatically</EM> released when the server is done with -them. -</P> -<P> -The way this works is as follows: the memory which is allocated, file -opened, <EM>etc.</EM>, to deal with a particular request are tied to a -<EM>resource pool</EM> which is allocated for the request. The pool -is a data structure which itself tracks the resources in question. -</P> -<P> -When the request has been processed, the pool is <EM>cleared</EM>. At -that point, all the memory associated with it is released for reuse, -all files associated with it are closed, and any other clean-up -functions which are associated with the pool are run. When this is -over, we can be confident that all the resource tied to the pool have -been released, and that none of them have leaked. -</P> -<P> -Server restarts, and allocation of memory and resources for per-server -configuration, are handled in a similar way. There is a -<EM>configuration pool</EM>, which keeps track of resources which were -allocated while reading the server configuration files, and handling -the commands therein (for instance, the memory that was allocated for -per-server module configuration, log files and other files that were -opened, and so forth). When the server restarts, and has to reread -the configuration files, the configuration pool is cleared, and so the -memory and file descriptors which were taken up by reading them the -last time are made available for reuse. -</P> -<P> -It should be noted that use of the pool machinery isn't generally -obligatory, except for situations like logging handlers, where you -really need to register cleanups to make sure that the log file gets -closed when the server restarts (this is most easily done by using the -function <CODE><A HREF="#pool-files">ap_pfopen</A></CODE>, which also -arranges for the underlying file descriptor to be closed before any -child processes, such as for CGI scripts, are <CODE>exec</CODE>ed), or -in case you are using the timeout machinery (which isn't yet even -documented here). However, there are two benefits to using it: -resources allocated to a pool never leak (even if you allocate a -scratch string, and just forget about it); also, for memory -allocation, <CODE>ap_palloc</CODE> is generally faster than -<CODE>malloc</CODE>. -</P> -<P> -We begin here by describing how memory is allocated to pools, and then -discuss how other resources are tracked by the resource pool -machinery. -</P> -<H3>Allocation of memory in pools</H3> -<P> -Memory is allocated to pools by calling the function -<CODE>ap_palloc</CODE>, which takes two arguments, one being a pointer to -a resource pool structure, and the other being the amount of memory to -allocate (in <CODE>char</CODE>s). Within handlers for handling -requests, the most common way of getting a resource pool structure is -by looking at the <CODE>pool</CODE> slot of the relevant -<CODE>request_rec</CODE>; hence the repeated appearance of the -following idiom in module code: -</P> -<PRE> -int my_handler(request_rec *r) -{ - struct my_structure *foo; - ... - - foo = (foo *)ap_palloc (r->pool, sizeof(my_structure)); -} -</PRE> -<P> -Note that <EM>there is no <CODE>ap_pfree</CODE></EM> --- -<CODE>ap_palloc</CODE>ed memory is freed only when the associated -resource pool is cleared. This means that <CODE>ap_palloc</CODE> does not -have to do as much accounting as <CODE>malloc()</CODE>; all it does in -the typical case is to round up the size, bump a pointer, and do a -range check. -</P> -<P> -(It also raises the possibility that heavy use of <CODE>ap_palloc</CODE> -could cause a server process to grow excessively large. There are -two ways to deal with this, which are dealt with below; briefly, you -can use <CODE>malloc</CODE>, and try to be sure that all of the memory -gets explicitly <CODE>free</CODE>d, or you can allocate a sub-pool of -the main pool, allocate your memory in the sub-pool, and clear it out -periodically. The latter technique is discussed in the section on -sub-pools below, and is used in the directory-indexing code, in order -to avoid excessive storage allocation when listing directories with -thousands of files). -</P> -<H3>Allocating initialized memory</H3> -<P> -There are functions which allocate initialized memory, and are -frequently useful. The function <CODE>ap_pcalloc</CODE> has the same -interface as <CODE>ap_palloc</CODE>, but clears out the memory it -allocates before it returns it. The function <CODE>ap_pstrdup</CODE> -takes a resource pool and a <CODE>char *</CODE> as arguments, and -allocates memory for a copy of the string the pointer points to, -returning a pointer to the copy. Finally <CODE>ap_pstrcat</CODE> is a -varargs-style function, which takes a pointer to a resource pool, and -at least two <CODE>char *</CODE> arguments, the last of which must be -<CODE>NULL</CODE>. It allocates enough memory to fit copies of each -of the strings, as a unit; for instance: -</P> -<PRE> - ap_pstrcat (r->pool, "foo", "/", "bar", NULL); -</PRE> -<P> -returns a pointer to 8 bytes worth of memory, initialized to -<CODE>"foo/bar"</CODE>. -</P> -<H3><A NAME="pools-used">Commonly-used pools in the Apache Web server</A></H3> -<P> -A pool is really defined by its lifetime more than anything else. There -are some static pools in http_main which are passed to various -non-http_main functions as arguments at opportune times. Here they are: -</P> -<DL COMPACT> - <DT>permanent_pool - </DT> - <DD> - <UL> - <LI>never passed to anything else, this is the ancestor of all pools - </LI> - </UL> - </DD> - <DT>pconf - </DT> - <DD> - <UL> - <LI>subpool of permanent_pool - </LI> - <LI>created at the beginning of a config "cycle"; exists until the - server is terminated or restarts; passed to all config-time - routines, either via cmd->pool, or as the "pool *p" argument on - those which don't take pools - </LI> - <LI>passed to the module init() functions - </LI> - </UL> - </DD> - <DT>ptemp - </DT> - <DD> - <UL> - <LI>sorry I lie, this pool isn't called this currently in 1.3, I - renamed it this in my pthreads development. I'm referring to - the use of ptrans in the parent... contrast this with the later - definition of ptrans in the child. - </LI> - <LI>subpool of permanent_pool - </LI> - <LI>created at the beginning of a config "cycle"; exists until the - end of config parsing; passed to config-time routines <EM>via</EM> - cmd->temp_pool. Somewhat of a "bastard child" because it isn't - available everywhere. Used for temporary scratch space which - may be needed by some config routines but which is deleted at - the end of config. - </LI> - </UL> - </DD> - <DT>pchild - </DT> - <DD> - <UL> - <LI>subpool of permanent_pool - </LI> - <LI>created when a child is spawned (or a thread is created); lives - until that child (thread) is destroyed - </LI> - <LI>passed to the module child_init functions - </LI> - <LI>destruction happens right after the child_exit functions are - called... (which may explain why I think child_exit is redundant - and unneeded) - </LI> - </UL> - </DD> - <DT>ptrans - <DT> - <DD> - <UL> - <LI>should be a subpool of pchild, but currently is a subpool of - permanent_pool, see above - </LI> - <LI>cleared by the child before going into the accept() loop to receive - a connection - </LI> - <LI>used as connection->pool - </LI> - </UL> - </DD> - <DT>r->pool - </DT> - <DD> - <UL> - <LI>for the main request this is a subpool of connection->pool; for - subrequests it is a subpool of the parent request's pool. - </LI> - <LI>exists until the end of the request (<EM>i.e.</EM>, - ap_destroy_sub_req, or - in child_main after process_request has finished) - </LI> - <LI>note that r itself is allocated from r->pool; <EM>i.e.</EM>, - r->pool is - first created and then r is the first thing palloc()d from it - </LI> - </UL> - </DD> -</DL> -<P> -For almost everything folks do, r->pool is the pool to use. But you -can see how other lifetimes, such as pchild, are useful to some -modules... such as modules that need to open a database connection once -per child, and wish to clean it up when the child dies. -</P> -<P> -You can also see how some bugs have manifested themself, such as setting -connection->user to a value from r->pool -- in this case -connection exists -for the lifetime of ptrans, which is longer than r->pool (especially if -r->pool is a subrequest!). So the correct thing to do is to allocate -from connection->pool. -</P> -<P> -And there was another interesting bug in mod_include/mod_cgi. You'll see -in those that they do this test to decide if they should use r->pool -or r->main->pool. In this case the resource that they are registering -for cleanup is a child process. If it were registered in r->pool, -then the code would wait() for the child when the subrequest finishes. -With mod_include this could be any old #include, and the delay can be up -to 3 seconds... and happened quite frequently. Instead the subprocess -is registered in r->main->pool which causes it to be cleaned up when -the entire request is done -- <EM>i.e.</EM>, after the output has been sent to -the client and logging has happened. -</P> -<H3><A NAME="pool-files">Tracking open files, etc.</A></H3> -<P> -As indicated above, resource pools are also used to track other sorts -of resources besides memory. The most common are open files. The -routine which is typically used for this is <CODE>ap_pfopen</CODE>, which -takes a resource pool and two strings as arguments; the strings are -the same as the typical arguments to <CODE>fopen</CODE>, <EM>e.g.</EM>, -</P> -<PRE> - ... - FILE *f = ap_pfopen (r->pool, r->filename, "r"); - - if (f == NULL) { ... } else { ... } -</PRE> -<P> -There is also a <CODE>ap_popenf</CODE> routine, which parallels the -lower-level <CODE>open</CODE> system call. Both of these routines -arrange for the file to be closed when the resource pool in question -is cleared. -</P> -<P> -Unlike the case for memory, there <EM>are</EM> functions to close -files allocated with <CODE>ap_pfopen</CODE>, and <CODE>ap_popenf</CODE>, -namely <CODE>ap_pfclose</CODE> and <CODE>ap_pclosef</CODE>. (This is -because, on many systems, the number of files which a single process -can have open is quite limited). It is important to use these -functions to close files allocated with <CODE>ap_pfopen</CODE> and -<CODE>ap_popenf</CODE>, since to do otherwise could cause fatal errors on -systems such as Linux, which react badly if the same -<CODE>FILE*</CODE> is closed more than once. -</P> -<P> -(Using the <CODE>close</CODE> functions is not mandatory, since the -file will eventually be closed regardless, but you should consider it -in cases where your module is opening, or could open, a lot of files). -</P> -<H3>Other sorts of resources --- cleanup functions</H3> -<BLOCKQUOTE> -More text goes here. Describe the the cleanup primitives in terms of -which the file stuff is implemented; also, <CODE>spawn_process</CODE>. -</BLOCKQUOTE> -<P> -Pool cleanups live until clear_pool() is called: clear_pool(a) recursively -calls destroy_pool() on all subpools of a; then calls all the cleanups for a; -then releases all the memory for a. destroy_pool(a) calls clear_pool(a) -and then releases the pool structure itself. <EM>i.e.</EM>, clear_pool(a) doesn't -delete a, it just frees up all the resources and you can start using it -again immediately. -</P> -<H3>Fine control --- creating and dealing with sub-pools, with a note -on sub-requests</H3> - -On rare occasions, too-free use of <CODE>ap_palloc()</CODE> and the -associated primitives may result in undesirably profligate resource -allocation. You can deal with such a case by creating a -<EM>sub-pool</EM>, allocating within the sub-pool rather than the main -pool, and clearing or destroying the sub-pool, which releases the -resources which were associated with it. (This really <EM>is</EM> a -rare situation; the only case in which it comes up in the standard -module set is in case of listing directories, and then only with -<EM>very</EM> large directories. Unnecessary use of the primitives -discussed here can hair up your code quite a bit, with very little -gain). <P> - -The primitive for creating a sub-pool is <CODE>ap_make_sub_pool</CODE>, -which takes another pool (the parent pool) as an argument. When the -main pool is cleared, the sub-pool will be destroyed. The sub-pool -may also be cleared or destroyed at any time, by calling the functions -<CODE>ap_clear_pool</CODE> and <CODE>ap_destroy_pool</CODE>, respectively. -(The difference is that <CODE>ap_clear_pool</CODE> frees resources -associated with the pool, while <CODE>ap_destroy_pool</CODE> also -deallocates the pool itself. In the former case, you can allocate new -resources within the pool, and clear it again, and so forth; in the -latter case, it is simply gone). <P> - -One final note --- sub-requests have their own resource pools, which -are sub-pools of the resource pool for the main request. The polite -way to reclaim the resources associated with a sub request which you -have allocated (using the <CODE>ap_sub_req_...</CODE> functions) -is <CODE>ap_destroy_sub_req</CODE>, which frees the resource pool. -Before calling this function, be sure to copy anything that you care -about which might be allocated in the sub-request's resource pool into -someplace a little less volatile (for instance, the filename in its -<CODE>request_rec</CODE> structure). <P> - -(Again, under most circumstances, you shouldn't feel obliged to call -this function; only 2K of memory or so are allocated for a typical sub -request, and it will be freed anyway when the main request pool is -cleared. It is only when you are allocating many, many sub-requests -for a single main request that you should seriously consider the -<CODE>ap_destroy_...</CODE> functions). - -<H2><A NAME="config">Configuration, commands and the like</A></H2> - -One of the design goals for this server was to maintain external -compatibility with the NCSA 1.3 server --- that is, to read the same -configuration files, to process all the directives therein correctly, -and in general to be a drop-in replacement for NCSA. On the other -hand, another design goal was to move as much of the server's -functionality into modules which have as little as possible to do with -the monolithic server core. The only way to reconcile these goals is -to move the handling of most commands from the central server into the -modules. <P> - -However, just giving the modules command tables is not enough to -divorce them completely from the server core. The server has to -remember the commands in order to act on them later. That involves -maintaining data which is private to the modules, and which can be -either per-server, or per-directory. Most things are per-directory, -including in particular access control and authorization information, -but also information on how to determine file types from suffixes, -which can be modified by <CODE>AddType</CODE> and -<CODE>DefaultType</CODE> directives, and so forth. In general, the -governing philosophy is that anything which <EM>can</EM> be made -configurable by directory should be; per-server information is -generally used in the standard set of modules for information like -<CODE>Alias</CODE>es and <CODE>Redirect</CODE>s which come into play -before the request is tied to a particular place in the underlying -file system. <P> - -Another requirement for emulating the NCSA server is being able to -handle the per-directory configuration files, generally called -<CODE>.htaccess</CODE> files, though even in the NCSA server they can -contain directives which have nothing at all to do with access -control. Accordingly, after URI -> filename translation, but before -performing any other phase, the server walks down the directory -hierarchy of the underlying filesystem, following the translated -pathname, to read any <CODE>.htaccess</CODE> files which might be -present. The information which is read in then has to be -<EM>merged</EM> with the applicable information from the server's own -config files (either from the <CODE><Directory></CODE> sections -in <CODE>access.conf</CODE>, or from defaults in -<CODE>srm.conf</CODE>, which actually behaves for most purposes almost -exactly like <CODE><Directory /></CODE>).<P> - -Finally, after having served a request which involved reading -<CODE>.htaccess</CODE> files, we need to discard the storage allocated -for handling them. That is solved the same way it is solved wherever -else similar problems come up, by tying those structures to the -per-transaction resource pool. <P> - -<H3><A NAME="per-dir">Per-directory configuration structures</A></H3> - -Let's look out how all of this plays out in <CODE>mod_mime.c</CODE>, -which defines the file typing handler which emulates the NCSA server's -behavior of determining file types from suffixes. What we'll be -looking at, here, is the code which implements the -<CODE>AddType</CODE> and <CODE>AddEncoding</CODE> commands. These -commands can appear in <CODE>.htaccess</CODE> files, so they must be -handled in the module's private per-directory data, which in fact, -consists of two separate <CODE>table</CODE>s for MIME types and -encoding information, and is declared as follows: - -<PRE> -typedef struct { - table *forced_types; /* Additional AddTyped stuff */ - table *encoding_types; /* Added with AddEncoding... */ -} mime_dir_config; -</PRE> - -When the server is reading a configuration file, or -<CODE><Directory></CODE> section, which includes one of the MIME -module's commands, it needs to create a <CODE>mime_dir_config</CODE> -structure, so those commands have something to act on. It does this -by invoking the function it finds in the module's `create per-dir -config slot', with two arguments: the name of the directory to which -this configuration information applies (or <CODE>NULL</CODE> for -<CODE>srm.conf</CODE>), and a pointer to a resource pool in which the -allocation should happen. <P> - -(If we are reading a <CODE>.htaccess</CODE> file, that resource pool -is the per-request resource pool for the request; otherwise it is a -resource pool which is used for configuration data, and cleared on -restarts. Either way, it is important for the structure being created -to vanish when the pool is cleared, by registering a cleanup on the -pool if necessary). <P> - -For the MIME module, the per-dir config creation function just -<CODE>ap_palloc</CODE>s the structure above, and a creates a couple of -<CODE>table</CODE>s to fill it. That looks like this: - -<PRE> -void *create_mime_dir_config (pool *p, char *dummy) -{ - mime_dir_config *new = - (mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config)); - - new->forced_types = ap_make_table (p, 4); - new->encoding_types = ap_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 *)ap_palloc (p, sizeof(mime_dir_config)); - - new->forced_types = ap_overlay_tables (p, subdir->forced_types, - parent_dir->forced_types); - new->encoding_types = ap_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 (<EM>e.g.</EM>, for the -includes module, whose per-directory configuration information -consists solely of the state of the <CODE>XBITHACK</CODE>), and for -those modules, you can just not declare one, and leave the -corresponding structure slot in the module itself <CODE>NULL</CODE>.<P> - -<H3><A NAME="commands">Command handling</A></H3> - -Now that we have these structures, we need to be able to figure out -how to fill them. That involves processing the actual -<CODE>AddType</CODE> and <CODE>AddEncoding</CODE> commands. To find -commands, the server looks in the module's <CODE>command table</CODE>. -That table contains information on how many arguments the commands -take, and in what formats, where it is permitted, and so forth. That -information is sufficient to allow the server to invoke most -command-handling functions with pre-parsed arguments. Without further -ado, let's look at the <CODE>AddType</CODE> command handler, which -looks like this (the <CODE>AddEncoding</CODE> command looks basically -the same, and won't be shown here): - -<PRE> -char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext) -{ - if (*ext == '.') ++ext; - ap_table_set (m->forced_types, ext, ct); - return NULL; -} -</PRE> - -This command handler is unusually simple. As you can see, it takes -four arguments, two of which are pre-parsed arguments, the third being -the per-directory configuration structure for the module in question, -and the fourth being a pointer to a <CODE>cmd_parms</CODE> structure. -That structure contains a bunch of arguments which are frequently of -use to some, but not all, commands, including a resource pool (from -which memory can be allocated, and to which cleanups should be tied), -and the (virtual) server being configured, from which the module's -per-server configuration data can be obtained if required.<P> - -Another way in which this particular command handler is unusually -simple is that there are no error conditions which it can encounter. -If there were, it could return an error message instead of -<CODE>NULL</CODE>; this causes an error to be printed out on the -server's <CODE>stderr</CODE>, followed by a quick exit, if it is in -the main config files; for a <CODE>.htaccess</CODE> file, the syntax -error is logged in the server error log (along with an indication of -where it came from), and the request is bounced with a server error -response (HTTP error status, code 500). <P> - -The MIME module's command table has entries for these commands, which -look like this: - -<PRE> -command_rec mime_cmds[] = { -{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2, - "a mime type followed by a file extension" }, -{ "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2, - "an encoding (<EM>e.g.</EM>, gzip), followed by a file extension" }, -{ 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>ap_get_module_config</CODE> function. - -<PRE> -int find_ct(request_rec *r) -{ - int i; - char *fn = ap_pstrdup (r->pool, r->filename); - mime_dir_config *conf = (mime_dir_config *) - ap_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=ap_rind(fn,'.')) < 0) return DECLINED; - ++i; - - if ((type = ap_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=ap_rind(fn,'.')) < 0) return OK; - ++i; - } - - if ((type = ap_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, <EM>etc</EM>.</A></H3> - -The basic ideas behind per-server module configuration are basically -the same as those for per-directory configuration; there is a creation -function and a merge function, the latter being invoked where a -virtual server has partially overridden the base server configuration, -and a combined structure must be computed. (As with per-directory -configuration, the default if no merge function is specified, and a -module is configured in some virtual server, is that the base -configuration is simply ignored). <P> - -The only substantial difference is that when a command needs to -configure the per-server private module data, it needs to go to the -<CODE>cmd_parms</CODE> data to get at it. Here's an example, from the -alias module, which also indicates how a syntax error can be returned -(note that the per-directory configuration argument to the command -handler is declared as a dummy, since the module doesn't actually have -per-directory config data): - -<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 *) - ap_get_module_config(s->module_config,&alias_module); - alias_entry *new = ap_push_array (conf->redirects); - - if (!ap_is_url (url)) return "Redirect to non-URL"; - - new->fake = f; new->real = url; - return NULL; -} -</PRE> -<!--#include virtual="footer.html" --> -</BODY></HTML> diff --git a/docs/manual/dns-caveats.html b/docs/manual/dns-caveats.html deleted file mode 100644 index cbf8a57a9d..0000000000 --- a/docs/manual/dns-caveats.html +++ /dev/null @@ -1,189 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Issues Regarding DNS and Apache</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Issues Regarding DNS and Apache</H1> - -<P>This page could be summarized with the statement: <EM>don't require -Apache to use DNS for any parsing of the configuration files</EM>. -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 <STRONG>will not be configured</STRONG>. 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/details.html"> is available</A>. - -<H3>The "main server" Address</H3> - -<P>The addition of <A HREF="vhosts/name-based.html">name-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><A NAME="tips">Tips to Avoid these problems</A></H3> - -<UL> -<LI> use IP addresses in <CODE><VirtualHost></CODE> -<LI> use IP addresses in <CODE>Listen</CODE> -<LI> use IP addresses in <CODE>BindAddress</CODE> -<LI> ensure all virtual hosts have an explicit <CODE>ServerName</CODE> -<LI> create a <CODE><VirtualHost _default_:*></CODE> server that - has no pages to serve -</UL> - -<H3>Appendix: Future Directions</H3> - -<P>The situation regarding DNS is highly undesirable. For Apache -1.2 we've attempted to make the server at least continue booting -in the event of failed DNS, but it might not be the best we -can do. In any event requiring the use of explicit IP addresses in -configuration files is highly undesirable in today's Internet where <A -HREF="http://www.ietf.org/html.charters/pier-charter.html">renumbering -</A> is a necessity. - -<P>A possible work around to the theft of service attack described above -would be to perform a reverse DNS lookup on the ip address returned by -the forward lookup and compare the two names. In the event of a mismatch -the virtualhost would be disabled. This would require reverse DNS to be -configured properly (which is something that most admins are familiar with -because of the common use of "double-reverse" DNS lookups by FTP servers -and TCP wrappers). - -<P>In any event it doesn't seem possible to reliably boot a virtual-hosted -web server when DNS has failed unless IP addresses are used. Partial -solutions such as disabling portions of the configuration might be worse -than not booting at all depending on what the webserver is supposed -to accomplish. - -<P>As HTTP/1.1 is deployed and browsers and proxies start issuing the -<CODE>Host</CODE> header it will become possible to avoid the use of -IP-based virtual hosts entirely. In this event a webserver has no requirement -to do DNS lookups during configuration. But as of March 1997 these -features have not been deployed widely enough to be put into use on -critical webservers. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/dso.html b/docs/manual/dso.html deleted file mode 100644 index 5e6d26e814..0000000000 --- a/docs/manual/dso.html +++ /dev/null @@ -1,392 +0,0 @@ -<!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" -> -<BLOCKQUOTE> -<!--#include virtual="header.html" --> - -<DIV ALIGN=CENTER> - -<H1> -Apache 1.3<BR> -Dynamic Shared Object (DSO)<BR> -Support -</H1> - -<ADDRESS>Originally written by<BR> -Ralf S. Engelschall <rse@apache.org>, April 1998</ADDRESS> - -</DIV> - -<H3>Background</H3> - -<P>On modern Unix derivatives there exists a nifty mechanism usually called -dynamic linking/loading of <EM>Dynamic Shared Objects</EM> (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 <EM>shared libraries</EM> or -<EM>DSO libraries</EM> 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 build-time by specifying <CODE>-lfoo</CODE> to the linker command. This -hard-codes 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>, in paths hard-coded via linker-options like -<CODE>-R</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 reusable 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 <EM>shared objects</EM> or -<EM>DSO files</EM> 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 <EM>etc.</EM> 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), Netscape Server, <EM>etc.</EM> 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 <A HREF="mod/mod_so.html"><CODE>mod_so.c</CODE></A> which has to be -statically compiled into the Apache core. It is the only module besides -<CODE>http_core.c</CODE> 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 -<CODE>configure</CODE>'s <CODE>--enable-shared</CODE> option (see top-level -<CODE>INSTALL</CODE> file) or by changing the <CODE>AddModule</CODE> command -in your <CODE>src/Configuration</CODE> into a <CODE>SharedModule</CODE> -command (see <CODE>src/INSTALL</CODE> file). After a module is compiled into -a DSO named <CODE>mod_foo.so</CODE> you can use <A -HREF="mod/mod_so.html"><CODE>mod_so</CODE></A>'s <A -HREF="mod/mod_so.html#loadmodule"><CODE>LoadModule</CODE></A> command in your -<CODE>httpd.conf</CODE> 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 <CODE>apxs</CODE> (<EM>APache -eXtenSion</EM>) is available. It can be used to build DSO based modules -<EM>outside of</EM> the Apache source tree. The idea is simple: When -installing Apache the <CODE>configure</CODE>'s <CODE>make install</CODE> -procedure installs the Apache C header files and puts the platform-dependent -compiler and linker flags for building DSO files into the <CODE>apxs</CODE> -program. This way the user can use <CODE>apxs</CODE> to compile his Apache -module sources without the Apache distribution source tree and without having -to fiddle with the platform-dependent 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 -<CODE>SHARED_CORE</CODE> has to be enabled via <CODE>configure</CODE>'s -<CODE>--enable-rule=SHARED_CORE</CODE> option (see top-level -<CODE>INSTALL</CODE> file) or by changing the <CODE>Rule</CODE> command in -your <CODE>Configuration</CODE> file to <CODE>Rule SHARED_CORE=yes</CODE> (see -<CODE>src/INSTALL</CODE> file). The Apache core code is then placed into a DSO -library named <CODE>libhttpd.so</CODE>. Because one cannot link a DSO against -static libraries on all platforms, an additional executable program named -<CODE>libhttpd.ep</CODE> is created which both binds this static code and -provides a stub for the <CODE>main()</CODE> function. Finally the -<CODE>httpd</CODE> executable program itself is replaced by a bootstrapping -code which automatically makes sure the Unix loader is able to load and start -<CODE>libhttpd.ep</CODE> by providing the <CODE>LD_LIBRARY_PATH</CODE> to -<CODE>libhttpd.so</CODE>. - -<H3>Supported Platforms</H3> - -<P>Apache's <CODE>src/Configure</CODE> script currently has only limited but -adequate 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 1999) is this: - -<P> -<UL> -<LI>Out-of-the-box supported platforms:<BR> -(actually tested versions in parenthesis) - -<PRE> -o FreeBSD (2.1.5, 2.2.x, 3.x, 4.x) -o OpenBSD (2.x) -o NetBSD (1.3.1) -o BSDI (3.x, 4.x) -o Linux (Debian/1.3.1, RedHat/4.2) -o Solaris (2.4, 2.5, 2.6, 2.7) -o SunOS (4.1.3) -o Digital UNIX (4.0) -o IRIX (5.3, 6.2) -o HP/UX (10.20) -o UnixWare (2.01, 2.1.2) -o SCO (5.0.4) -o AIX (3.2, 4.1.5, 4.2, 4.3) -o ReliantUNIX/SINIX (5.43) -o SVR4 (-) -o Mac OS X Server (1.0) -o Mac OS (10.0 preview 1) -o OpenStep/Mach (4.2) -o DGUX (??) -</PRE> - -<P> -<LI> Explicitly unsupported platforms: - -<PRE> -o Ultrix (no dlopen-style interface under this platform) -</PRE> - -</UL> - -<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 -<CODE>httpd</CODE> binary) into a DSO <CODE>libhttpd.so</CODE>, an executable -program <CODE>libhttpd.ep</CODE> and a bootstrapping executable program -<CODE>httpd</CODE> (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): - -<P> -<UL> -<LI>Build and install via <CODE>configure</CODE> (preferred): -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ ./configure --prefix=/path/to/install - --enable-rule=SHARED_CORE ... -$ make install -</PRE> -</TD></TR></TABLE> - -<LI>Build and install manually: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -- 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> -</TD></TR></TABLE> -</UL> - -<LI>Build and install a <EM>distributed</EM> Apache module, say -<CODE>mod_foo.c</CODE>, into its own DSO <CODE>mod_foo.so</CODE>: - -<P> -<UL> -<LI>Build and install via <CODE>configure</CODE> (preferred): -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ ./configure --prefix=/path/to/install - --enable-shared=foo -$ make install -</PRE> -</TD></TR></TABLE> - -<LI>Build and install manually: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -- 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> -</TD></TR></TABLE> -</UL> - -<LI>Build and install a <EM>third-party</EM> Apache module, say -<CODE>mod_foo.c</CODE>, into its own DSO <CODE>mod_foo.so</CODE> - -<P> -<UL> -<LI>Build and install via <CODE>configure</CODE> (preferred): -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ ./configure --add-module=/path/to/3rdparty/mod_foo.c - --enable-shared=foo -$ make install -</PRE> -</TD></TR></TABLE> - -<LI>Build and install manually: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ 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> -</TD></TR></TABLE> -</UL> - -<P> -<LI>Build and install a <EM>third-party</EM> Apache module, say -<CODE>mod_foo.c</CODE>, into its own DSO <CODE>mod_foo.so</CODE> <EM>outside -of</EM> the Apache source tree: - -<P> -<UL> -<LI>Build and install via <CODE>apxs</CODE>: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ cd /path/to/3rdparty -$ apxs -c mod_foo.c -$ apxs -i -a -n foo mod_foo.so -</PRE> -</TD></TR></TABLE> -</UL> - -</OL> - -<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 <A - HREF="mod/mod_so.html#loadmodule"><CODE>LoadModule</CODE></A> - <CODE>httpd.conf</CODE> configuration commands instead of - <CODE>Configuration</CODE> <CODE>AddModule</CODE> 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], <EM>etc.</EM>) with only one Apache installation. -<P> -<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, <EM>etc.</EM> -<P> -<LI> Easier Apache module prototyping because with the DSO/<CODE>apxs</CODE> - pair you can both work outside the Apache source tree and only need an - <CODE>apxs -i</CODE> command followed by an <CODE>apachectl - restart</CODE> 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 of code into the address space - of a program. -<P> -<LI> The server is approximately 20% slower at startup time because of the - symbol resolving overhead the Unix loader now has to do. -<P> -<LI> The server is approximately 5% slower at execution time under some - platforms because position independent code (PIC) sometimes needs - complicated assembler tricks for relative addressing which are not - necessarily as fast as absolute addressing. -<P> -<LI> Because DSO modules cannot be linked against other DSO-based libraries - (<CODE>ld -lfoo</CODE>) 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 (<CODE>libc</CODE>) - and all other dynamic or static libraries used by the Apache core, or - from static library archives (<CODE>libfoo.a</CODE>) containing position - independent code. The only chances to use other code is to either make - sure the Apache core itself already contains a reference to it, loading - the code yourself via <CODE>dlopen()</CODE> or enabling the - <CODE>SHARED_CHAIN</CODE> rule while building Apache when your platform - supports linking DSO files against DSO libraries. -<P> -<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 <CODE>SHARED_CORE</CODE> feature because this - way the global symbols are forced to be exported. As a consequence the - Apache <CODE>src/Configure</CODE> script automatically enforces - <CODE>SHARED_CORE</CODE> on these platforms when DSO features are used in - the <CODE>Configuration</CODE> file or on the configure command line. -</UL> - -<!--#include virtual="footer.html" --> -</BLOCKQUOTE> -</BODY> -</HTML> diff --git a/docs/manual/dso.html.en b/docs/manual/dso.html.en deleted file mode 100644 index 5e6d26e814..0000000000 --- a/docs/manual/dso.html.en +++ /dev/null @@ -1,392 +0,0 @@ -<!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" -> -<BLOCKQUOTE> -<!--#include virtual="header.html" --> - -<DIV ALIGN=CENTER> - -<H1> -Apache 1.3<BR> -Dynamic Shared Object (DSO)<BR> -Support -</H1> - -<ADDRESS>Originally written by<BR> -Ralf S. Engelschall <rse@apache.org>, April 1998</ADDRESS> - -</DIV> - -<H3>Background</H3> - -<P>On modern Unix derivatives there exists a nifty mechanism usually called -dynamic linking/loading of <EM>Dynamic Shared Objects</EM> (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 <EM>shared libraries</EM> or -<EM>DSO libraries</EM> 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 build-time by specifying <CODE>-lfoo</CODE> to the linker command. This -hard-codes 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>, in paths hard-coded via linker-options like -<CODE>-R</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 reusable 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 <EM>shared objects</EM> or -<EM>DSO files</EM> 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 <EM>etc.</EM> 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), Netscape Server, <EM>etc.</EM> 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 <A HREF="mod/mod_so.html"><CODE>mod_so.c</CODE></A> which has to be -statically compiled into the Apache core. It is the only module besides -<CODE>http_core.c</CODE> 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 -<CODE>configure</CODE>'s <CODE>--enable-shared</CODE> option (see top-level -<CODE>INSTALL</CODE> file) or by changing the <CODE>AddModule</CODE> command -in your <CODE>src/Configuration</CODE> into a <CODE>SharedModule</CODE> -command (see <CODE>src/INSTALL</CODE> file). After a module is compiled into -a DSO named <CODE>mod_foo.so</CODE> you can use <A -HREF="mod/mod_so.html"><CODE>mod_so</CODE></A>'s <A -HREF="mod/mod_so.html#loadmodule"><CODE>LoadModule</CODE></A> command in your -<CODE>httpd.conf</CODE> 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 <CODE>apxs</CODE> (<EM>APache -eXtenSion</EM>) is available. It can be used to build DSO based modules -<EM>outside of</EM> the Apache source tree. The idea is simple: When -installing Apache the <CODE>configure</CODE>'s <CODE>make install</CODE> -procedure installs the Apache C header files and puts the platform-dependent -compiler and linker flags for building DSO files into the <CODE>apxs</CODE> -program. This way the user can use <CODE>apxs</CODE> to compile his Apache -module sources without the Apache distribution source tree and without having -to fiddle with the platform-dependent 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 -<CODE>SHARED_CORE</CODE> has to be enabled via <CODE>configure</CODE>'s -<CODE>--enable-rule=SHARED_CORE</CODE> option (see top-level -<CODE>INSTALL</CODE> file) or by changing the <CODE>Rule</CODE> command in -your <CODE>Configuration</CODE> file to <CODE>Rule SHARED_CORE=yes</CODE> (see -<CODE>src/INSTALL</CODE> file). The Apache core code is then placed into a DSO -library named <CODE>libhttpd.so</CODE>. Because one cannot link a DSO against -static libraries on all platforms, an additional executable program named -<CODE>libhttpd.ep</CODE> is created which both binds this static code and -provides a stub for the <CODE>main()</CODE> function. Finally the -<CODE>httpd</CODE> executable program itself is replaced by a bootstrapping -code which automatically makes sure the Unix loader is able to load and start -<CODE>libhttpd.ep</CODE> by providing the <CODE>LD_LIBRARY_PATH</CODE> to -<CODE>libhttpd.so</CODE>. - -<H3>Supported Platforms</H3> - -<P>Apache's <CODE>src/Configure</CODE> script currently has only limited but -adequate 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 1999) is this: - -<P> -<UL> -<LI>Out-of-the-box supported platforms:<BR> -(actually tested versions in parenthesis) - -<PRE> -o FreeBSD (2.1.5, 2.2.x, 3.x, 4.x) -o OpenBSD (2.x) -o NetBSD (1.3.1) -o BSDI (3.x, 4.x) -o Linux (Debian/1.3.1, RedHat/4.2) -o Solaris (2.4, 2.5, 2.6, 2.7) -o SunOS (4.1.3) -o Digital UNIX (4.0) -o IRIX (5.3, 6.2) -o HP/UX (10.20) -o UnixWare (2.01, 2.1.2) -o SCO (5.0.4) -o AIX (3.2, 4.1.5, 4.2, 4.3) -o ReliantUNIX/SINIX (5.43) -o SVR4 (-) -o Mac OS X Server (1.0) -o Mac OS (10.0 preview 1) -o OpenStep/Mach (4.2) -o DGUX (??) -</PRE> - -<P> -<LI> Explicitly unsupported platforms: - -<PRE> -o Ultrix (no dlopen-style interface under this platform) -</PRE> - -</UL> - -<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 -<CODE>httpd</CODE> binary) into a DSO <CODE>libhttpd.so</CODE>, an executable -program <CODE>libhttpd.ep</CODE> and a bootstrapping executable program -<CODE>httpd</CODE> (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): - -<P> -<UL> -<LI>Build and install via <CODE>configure</CODE> (preferred): -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ ./configure --prefix=/path/to/install - --enable-rule=SHARED_CORE ... -$ make install -</PRE> -</TD></TR></TABLE> - -<LI>Build and install manually: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -- 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> -</TD></TR></TABLE> -</UL> - -<LI>Build and install a <EM>distributed</EM> Apache module, say -<CODE>mod_foo.c</CODE>, into its own DSO <CODE>mod_foo.so</CODE>: - -<P> -<UL> -<LI>Build and install via <CODE>configure</CODE> (preferred): -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ ./configure --prefix=/path/to/install - --enable-shared=foo -$ make install -</PRE> -</TD></TR></TABLE> - -<LI>Build and install manually: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -- 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> -</TD></TR></TABLE> -</UL> - -<LI>Build and install a <EM>third-party</EM> Apache module, say -<CODE>mod_foo.c</CODE>, into its own DSO <CODE>mod_foo.so</CODE> - -<P> -<UL> -<LI>Build and install via <CODE>configure</CODE> (preferred): -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ ./configure --add-module=/path/to/3rdparty/mod_foo.c - --enable-shared=foo -$ make install -</PRE> -</TD></TR></TABLE> - -<LI>Build and install manually: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ 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> -</TD></TR></TABLE> -</UL> - -<P> -<LI>Build and install a <EM>third-party</EM> Apache module, say -<CODE>mod_foo.c</CODE>, into its own DSO <CODE>mod_foo.so</CODE> <EM>outside -of</EM> the Apache source tree: - -<P> -<UL> -<LI>Build and install via <CODE>apxs</CODE>: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ cd /path/to/3rdparty -$ apxs -c mod_foo.c -$ apxs -i -a -n foo mod_foo.so -</PRE> -</TD></TR></TABLE> -</UL> - -</OL> - -<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 <A - HREF="mod/mod_so.html#loadmodule"><CODE>LoadModule</CODE></A> - <CODE>httpd.conf</CODE> configuration commands instead of - <CODE>Configuration</CODE> <CODE>AddModule</CODE> 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], <EM>etc.</EM>) with only one Apache installation. -<P> -<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, <EM>etc.</EM> -<P> -<LI> Easier Apache module prototyping because with the DSO/<CODE>apxs</CODE> - pair you can both work outside the Apache source tree and only need an - <CODE>apxs -i</CODE> command followed by an <CODE>apachectl - restart</CODE> 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 of code into the address space - of a program. -<P> -<LI> The server is approximately 20% slower at startup time because of the - symbol resolving overhead the Unix loader now has to do. -<P> -<LI> The server is approximately 5% slower at execution time under some - platforms because position independent code (PIC) sometimes needs - complicated assembler tricks for relative addressing which are not - necessarily as fast as absolute addressing. -<P> -<LI> Because DSO modules cannot be linked against other DSO-based libraries - (<CODE>ld -lfoo</CODE>) 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 (<CODE>libc</CODE>) - and all other dynamic or static libraries used by the Apache core, or - from static library archives (<CODE>libfoo.a</CODE>) containing position - independent code. The only chances to use other code is to either make - sure the Apache core itself already contains a reference to it, loading - the code yourself via <CODE>dlopen()</CODE> or enabling the - <CODE>SHARED_CHAIN</CODE> rule while building Apache when your platform - supports linking DSO files against DSO libraries. -<P> -<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 <CODE>SHARED_CORE</CODE> feature because this - way the global symbols are forced to be exported. As a consequence the - Apache <CODE>src/Configure</CODE> script automatically enforces - <CODE>SHARED_CORE</CODE> on these platforms when DSO features are used in - the <CODE>Configuration</CODE> file or on the configure command line. -</UL> - -<!--#include virtual="footer.html" --> -</BLOCKQUOTE> -</BODY> -</HTML> diff --git a/docs/manual/ebcdic.html b/docs/manual/ebcdic.html deleted file mode 100644 index 0e93aaa490..0000000000 --- a/docs/manual/ebcdic.html +++ /dev/null @@ -1,497 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>The Apache EBCDIC Port</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">Overview of the Apache EBCDIC Port</H1> - - <P> - Version 1.3 of the Apache HTTP Server is the first version which - includes a port to a (non-ASCII) mainframe machine which uses - the EBCDIC character set as its native codeset.<BR> - (It is the SIEMENS family of mainframes running the - <A HREF="http://www.siemens.de/servers/bs2osd/osdbc_us.htm">BS2000/OSD - operating system</A>. This mainframe OS nowadays features a - SVR4-derived POSIX subsystem). - </P> - - <P> - The port was started initially to - <UL> - <LI> prove the feasibility of porting - <A HREF="http://dev.apache.org/">the Apache HTTP server</A> - to this platform - <LI> find a "worthy and capable" successor for the venerable - <A HREF="http://www.w3.org/Daemon/">CERN-3.0</A> daemon - (which was ported a couple of years ago), and to - <LI> prove that Apache's preforking process model can on this platform - easily outperform the accept-fork-serve model used by CERN by a - factor of 5 or more. - </UL> - </P> - - <P> - This document serves as a rationale to describe some of the design - decisions of the port to this machine. - </P> - - <H2 ALIGN=CENTER>Design Goals</H2> - <P> - One objective of the EBCDIC port was to maintain enough backwards - compatibility with the (EBCDIC) CERN server to make the transition to - the new server attractive and easy. This required the addition of - a configurable method to define whether a HTML document was stored - in ASCII (the only format accepted by the old server) or in EBCDIC - (the native document format in the POSIX subsystem, and therefore - the only realistic format in which the other POSIX tools like grep - or sed could operate on the documents). The current solution to - this is a "pseudo-MIME-format" which is intercepted and - interpreted by the Apache server (see below). Future versions - might solve the problem by defining an "ebcdic-handler" for all - documents which must be converted. - </P> - - <H2 ALIGN=CENTER>Technical Solution</H2> - <P> - Since all Apache input and output is based upon the BUFF data type - and its methods, the easiest solution was to add the conversion to - the BUFF handling routines. The conversion must be settable at any - time, so a BUFF flag was added which defines whether a BUFF object - has currently enabled conversion or not. This flag is modified at - several points in the HTTP protocol: - <UL> - <LI><STRONG>set</STRONG> before a request is received (because the - request and the request header lines are always in ASCII - format) - - <LI><STRONG>set/unset</STRONG> when the request body is - received - depending on the content type of the request body - (because the request body may contain ASCII text or a binary file) - - <LI><STRONG>set</STRONG> before a reply header is sent (because the - response header lines are always in ASCII format) - - <LI><STRONG>set/unset</STRONG> when the response body is - sent - depending on the content type of the response body - (because the response body may contain text or a binary file) - </UL> - </P> - -<H2 ALIGN=CENTER>Porting Notes</H2> - <P> - <OL> - <LI> - The relevant changes in the source are #ifdef'ed into two - categories: - <DL> - <DT><CODE><STRONG>#ifdef CHARSET_EBCDIC</STRONG></CODE> - <DD>Code which is needed for any EBCDIC based machine. This - includes character translations, differences in - contiguity of the two character sets, flags which - indicate which part of the HTTP protocol has to be - converted and which part doesn't <EM>etc.</EM> - <DT><CODE><STRONG>#ifdef _OSD_POSIX</STRONG></CODE> - <DD>Code which is needed for the SIEMENS BS2000/OSD - mainframe platform only. This deals with include file - differences and socket implementation topics which are - only required on the BS2000/OSD platform. - </DL> - </LI><BR> - - <LI> - The possibility to translate between ASCII and EBCDIC at the - socket level (on BS2000 POSIX, there is a socket option which - supports this) was intentionally <EM>not</EM> chosen, because - the byte stream at the HTTP protocol level consists of a - mixture of protocol related strings and non-protocol related - raw file data. HTTP protocol strings are always encoded in - ASCII (the GET request, any Header: lines, the chunking - information <EM>etc.</EM>) whereas the file transfer parts (<EM>i.e.</EM>, GIF - images, CGI output <EM>etc.</EM>) should usually be just "passed through" - by the server. This separation between "protocol string" and - "raw data" is reflected in the server code by functions like - bgets() or rvputs() for strings, and functions like bwrite() - for binary data. A global translation of everything would - therefore be inadequate.<BR> - (In the case of text files of course, provisions must be made so - that EBCDIC documents are always served in ASCII) - </LI><BR> - - <LI> - This port therefore features a built-in protocol level conversion - for the server-internal strings (which the compiler translated to - EBCDIC strings) and thus for all server-generated documents. - The hard coded ASCII escapes \012 and \015 which are - ubiquitous in the server code are an exception: they are - already the binary encoding of the ASCII \n and \r and must - not be converted to ASCII a second time. This exception is - only relevant for server-generated strings; and <EM>external</EM> - EBCDIC documents are not expected to contain ASCII newline characters. - </LI><BR> - - <LI> - By examining the call hierarchy for the BUFF management - routines, I added an "ebcdic/ascii conversion layer" which - would be crossed on every puts/write/get/gets, and a - conversion flag which allowed enabling/disabling the - conversions on-the-fly. Usually, a document crosses this - layer twice from its origin source (a file or CGI output) to - its destination (the requesting client): <SAMP>file -> - Apache</SAMP>, and <SAMP>Apache -> client</SAMP>.<BR> - The server can now read the header - lines of a CGI-script output in EBCDIC format, and then find - out that the remainder of the script's output is in ASCII - (like in the case of the output of a WWW Counter program: the - document body contains a GIF image). All header processing is - done in the native EBCDIC format; the server then determines, - based on the type of document being served, whether the - document body (except for the chunking information, of - course) is in ASCII already or must be converted from EBCDIC. - </LI><BR> - - <LI> - For Text documents (MIME types text/plain, text/html <EM>etc.</EM>), - an implicit translation to ASCII can be used, or (if the - users prefer to store some documents in raw ASCII form for - faster serving, or because the files reside on a NFS-mounted - directory tree) can be served without conversion. - <BR> - <STRONG>Example:</STRONG><BLOCKQUOTE> - to serve files with the suffix .ahtml as a raw ASCII text/html - document without implicit conversion (and suffix .ascii - as ASCII text/plain), use the directives:<PRE> - AddType text/x-ascii-html .ahtml - AddType text/x-ascii-plain .ascii - </PRE></BLOCKQUOTE> - Similarly, any text/XXXX MIME type can be served as "raw ASCII" by - configuring a MIME type "text/x-ascii-XXXX" for it using AddType. - </LI><BR> - - <LI> - Non-text documents are always served "binary" without conversion. - This seems to be the most sensible choice for, .<EM>e.g.</EM>, GIF/ZIP/AU - file types. This of course requires the user to copy them to the - mainframe host using the "rcp -b" binary switch. - </LI><BR> - - <LI> - Server parsed files are always assumed to be in native (<EM>i.e.</EM>, - EBCDIC) format as used on the machine, and are converted after - processing. - </LI><BR> - - <LI> - For CGI output, the CGI script determines whether a conversion is - needed or not: by setting the appropriate Content-Type, text files - can be converted, or GIF output can be passed through unmodified. - An example for the latter case is the wwwcount program which we ported - as well. - </LI><BR> - </OL> - </P> - - <H2 ALIGN=CENTER>Document Storage Notes</H2> - <H3 ALIGN=CENTER>Binary Files</H3> - <P> - All files with a <SAMP>Content-Type:</SAMP> which does not - start with <SAMP>text/</SAMP> are regarded as <EM>binary files</EM> - by the server and are not subject to any conversion. - Examples for binary files are GIF images, gzip-compressed - files and the like. - </P> - <P> - When exchanging binary files between the mainframe host and a - Unix machine or Windows PC, be sure to use the ftp "binary" - (<SAMP>TYPE I</SAMP>) command, or use the - <SAMP>rcp -b</SAMP> command from the mainframe host - (the -b switch is not supported in unix rcp's). - </P> - - <H3 ALIGN=CENTER>Text Documents</H3> - <P> - The default assumption of the server is that Text Files - (<EM>i.e.</EM>, all files whose <SAMP>Content-Type:</SAMP> starts with - <SAMP>text/</SAMP>) are stored in the native character - set of the host, EBCDIC. - </P> - - <H3 ALIGN=CENTER>Server Side Included Documents</H3> - <P> - SSI documents must currently be stored in EBCDIC only. No - provision is made to convert it from ASCII before processing. - </P> - - <H2 ALIGN=CENTER>Apache Modules' Status</H2> - <TABLE BORDER ALIGN=middle> - <TR> - <TH>Module - <TH>Status - <TH>Notes - </TR> - - <TR> - <TD ALIGN=LEFT>http_core - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_access - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_actions - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_alias - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_asis - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_auth - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_auth_anon - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_auth_db - <TD ALIGN=CENTER>? - <TD>with own libdb.a - </TR> - - <TR> - <TD ALIGN=LEFT>mod_auth_dbm - <TD ALIGN=CENTER>? - <TD>with own libdb.a - </TR> - - <TR> - <TD ALIGN=LEFT>mod_autoindex - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_cern_meta - <TD ALIGN=CENTER>? - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_cgi - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_digest - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_dir - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_so - <TD ALIGN=CENTER>- - <TD>no shared libs - </TR> - - <TR> - <TD ALIGN=LEFT>mod_env - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_example - <TD ALIGN=CENTER>- - <TD>(test bed only) - </TR> - - <TR> - <TD ALIGN=LEFT>mod_expires - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_headers - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_imap - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_include - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_info - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_log_agent - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_log_config - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_log_referer - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_mime - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_mime_magic - <TD ALIGN=CENTER>? - <TD>not ported yet - </TR> - - <TR> - <TD ALIGN=LEFT>mod_negotiation - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_proxy - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_rewrite - <TD ALIGN=CENTER>+ - <TD>untested - </TR> - - <TR> - <TD ALIGN=LEFT>mod_setenvif - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_speling - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_status - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_unique_id - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_userdir - <TD ALIGN=CENTER>+ - <TD> - </TR> - - <TR> - <TD ALIGN=LEFT>mod_usertrack - <TD ALIGN=CENTER>? - <TD>untested - </TR> - </TABLE> - - <H2 ALIGN=CENTER>Third Party Modules' Status</H2> - <TABLE BORDER ALIGN=middle> - <TR> - <TH>Module - <TH>Status - <TH>Notes - </TR> - - <TR> - <TD ALIGN=LEFT><A HREF="http://java.apache.org/">mod_jserv</A> - <TD ALIGN=CENTER>- - <TD>JAVA still being ported. - </TR> - - <TR> - <TD ALIGN=LEFT><A HREF="http://www.php.net/">mod_php3</A> - <TD ALIGN=CENTER>+ - <TD>mod_php3 runs fine, with LDAP and GD and FreeType libraries - </TR> - - <TR> - <TD ALIGN=LEFT - ><A HREF="http://hpwww.ec-lyon.fr/~vincent/apache/mod_put.html">mod_put</A> - <TD ALIGN=CENTER>? - <TD>untested - </TR> - - <TR> - <TD ALIGN=LEFT - ><A HREF="ftp://hachiman.vidya.com/pub/apache/">mod_session</A> - <TD ALIGN=CENTER>- - <TD>untested - </TR> - - </TABLE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/env.html b/docs/manual/env.html deleted file mode 100644 index 962dbe90ae..0000000000 --- a/docs/manual/env.html +++ /dev/null @@ -1,64 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Special Purpose Environment Variables</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Special Purpose Environment Variables</H1> -<P> -Interoperability problems have led to the introduction of -mechanisms to modify the way Apache behaves when talking to particular -clients. To make these mechanisms as flexible as possible, they -are invoked by defining environment variables, typically with -<A HREF="mod/mod_browser.html#browsermatch">BrowserMatch</A>, though -<A HREF="mod/mod_env.html#setenv">SetEnv</A> and -<A HREF="mod/mod_env.html#passenv">PassEnv</A> could also be used, for -example. -</P> - -<H2>downgrade-1.0</H2> -<P> -This forces the request to be treated as a HTTP/1.0 request even if it -was in a later dialect. -</P> - -<H2>force-no-vary</H2> -<P> -This causes any <CODE>Vary</CODE> fields to be removed from the response -header before it is sent back to the client. Some clients don't -interpret this field correctly (see the -<A HREF="misc/known_client_problems.html">known client problems</A> -page); setting this variable can work around this problem. Setting -this variable also implies <STRONG>force-response-1.0</STRONG>. -</P> - -<H2>force-response-1.0</H2> -<P> -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. -</P> - -<H2>nokeepalive</H2> -<P> -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: -</P> -<PRE> - BrowserMatch Mozilla/2 nokeepalive -</PRE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/env.html.en b/docs/manual/env.html.en deleted file mode 100644 index 962dbe90ae..0000000000 --- a/docs/manual/env.html.en +++ /dev/null @@ -1,64 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Special Purpose Environment Variables</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Special Purpose Environment Variables</H1> -<P> -Interoperability problems have led to the introduction of -mechanisms to modify the way Apache behaves when talking to particular -clients. To make these mechanisms as flexible as possible, they -are invoked by defining environment variables, typically with -<A HREF="mod/mod_browser.html#browsermatch">BrowserMatch</A>, though -<A HREF="mod/mod_env.html#setenv">SetEnv</A> and -<A HREF="mod/mod_env.html#passenv">PassEnv</A> could also be used, for -example. -</P> - -<H2>downgrade-1.0</H2> -<P> -This forces the request to be treated as a HTTP/1.0 request even if it -was in a later dialect. -</P> - -<H2>force-no-vary</H2> -<P> -This causes any <CODE>Vary</CODE> fields to be removed from the response -header before it is sent back to the client. Some clients don't -interpret this field correctly (see the -<A HREF="misc/known_client_problems.html">known client problems</A> -page); setting this variable can work around this problem. Setting -this variable also implies <STRONG>force-response-1.0</STRONG>. -</P> - -<H2>force-response-1.0</H2> -<P> -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. -</P> - -<H2>nokeepalive</H2> -<P> -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: -</P> -<PRE> - BrowserMatch Mozilla/2 nokeepalive -</PRE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/expand.pl b/docs/manual/expand.pl deleted file mode 100644 index d286149880..0000000000 --- a/docs/manual/expand.pl +++ /dev/null @@ -1,104 +0,0 @@ -#!/usr/local/bin/perl5 - -# This is a very simple Perl script to expand server-side includes -# in the directory it is run, and direct subdirectories. It will -# work only on SSI directives of the form -# -# <!--#include virtual="filename" --> -# -# Filename must be relative to the directory the file appears in. -# -# Nov 30, 1996 - Alexei Kosut <akosut@apache.org> - -# ==================================================================== -# Copyright (c) 1996-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. -# -# 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/>. - -# Put a list of dirs (except ..) into @dirs - -opendir DIR, "." or die "Could not open directory: $!"; -@dirs = grep !/^\.\.$/, (grep -d, readdir DIR); -closedir DIR; - -foreach $dir (@dirs) { - print "Entering directory $dir\n"; - opendir SUBDIR, "$dir" or die "Could not open subdir $dir: $!"; - foreach $file (grep /\.html$/, readdir SUBDIR) { - print "Expanding file $dir/$file\n"; - rename "$dir/$file", "$dir/${file}.old"; - open READ, "$dir/${file}.old" or die "Couldn't read $dir/$file: $!"; - open WRITE, ">$dir/$file" or die "Couldn't write $dir/$file: $!"; - while ($r = <READ>) { - if ($r =~ /<!--#include virtual="(.*)" -->/) { - ($pre, $include, $post) = ($`, $1, $'); - print WRITE $pre; - - open INC, "$dir/$include" or - print "Could not include file $dir/$include: $!"; - print WRITE while (<INC>); - close INC; - - print WRITE $post; - } - else { - print WRITE $r; - } - } - close READ; - close WRITE; - unlink "$dir/$file.old"; - } - closedir SUBDIR; -} - - diff --git a/docs/manual/footer.html b/docs/manual/footer.html deleted file mode 100644 index c82d24e722..0000000000 --- a/docs/manual/footer.html +++ /dev/null @@ -1,6 +0,0 @@ -<HR> - <H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.3 - </H3> - -<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> diff --git a/docs/manual/handler.html b/docs/manual/handler.html deleted file mode 100644 index 72f16fd170..0000000000 --- a/docs/manual/handler.html +++ /dev/null @@ -1,195 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache's Handler Use</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache's Handler Use</H1> - -<H2>What is a Handler</H2> - -<P>A "handler" is an internal Apache representation of the action to be -performed when a file is called. Generally, files have implicit -handlers, based on the file type. Normally, all files are simply -served by the server, but certain file typed are "handled" -separately. For example, you may use a type of -"application/x-httpd-cgi" to invoke CGI scripts.</P> - -<P>Apache 1.1 adds the additional ability to use handlers -explicitly. Either based on filename extensions or on location, these -handlers are unrelated to file type. This is advantageous both because -it is a more elegant solution, but it also allows for both a type -<STRONG>and</STRONG> a handler to be associated with a file (See also -<A HREF="mod/mod_mime.html#multipleext">Files with Multiple Extensions</A>) - -</P> - -<P>Handlers can either be built into the server or to a module, or -they can be added with the <A -HREF="mod/mod_actions.html#action">Action</A> directive. The built-in -handlers in the standard distribution are as follows:</P> - -<UL> -<LI><STRONG>default-handler</STRONG>: - Send the file using the <CODE>default_handler()</CODE>, which is the - handler used by default to handle static content. - (core) -<LI><STRONG>send-as-is</STRONG>: - Send file with HTTP headers as is. - (<A HREF="mod/mod_asis.html">mod_asis</A>) -<LI><STRONG>cgi-script</STRONG>: - Treat the file as a CGI script. - (<A HREF="mod/mod_cgi.html">mod_cgi</A>) -<LI><STRONG>imap-file</STRONG>: - Imagemap rule file. - (<A HREF="mod/mod_imap.html">mod_imap</A>) -<LI><STRONG>server-info</STRONG>: - Get the server's configuration information - (<A HREF="mod/mod_info.html">mod_info</A>) -<LI><STRONG>server-parsed</STRONG>: - Parse for server-side includes - (<A HREF="mod/mod_include.html">mod_include</A>) -<LI><STRONG>server-status</STRONG>: - Get the server's status report - (<A HREF="mod/mod_status.html">mod_status</A>) -<LI><STRONG>type-map</STRONG>: - Parse as a type map file for content negotiation - (<A HREF="mod/mod_negotiation.html">mod_negotiation</A>) -</UL> - -<P> - -<H2>Directives</H2> -<UL> -<LI><A HREF="#addhandler">AddHandler</A> -<LI><A HREF="#sethandler">SetHandler</A> -</UL> - -<HR> - -<H2><A NAME="addhandler">AddHandler</A></H2> - -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddHandler <EM>handler-name extension extension...</EM><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="mod/directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="mod/directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<BR> -<A - HREF="mod/directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> AddHandler is only available in Apache -1.1 and later<P> - -<P>AddHandler maps the filename extensions <EM>extension</EM> to the -handler <EM>handler-name</EM>. This mapping is added to any already -in force, overriding any mappings that already exist for the same -<EM>extension</EM>. - -For example, to activate CGI scripts -with the file extension "<CODE>.cgi</CODE>", you might use: -<PRE> - AddHandler cgi-script cgi -</PRE> - -<P>Once that has been put into your srm.conf or httpd.conf file, any -file containing the "<CODE>.cgi</CODE>" extension will be treated as a -CGI program.</P> - -<P> - -<STRONG>See also</STRONG>: <A HREF="mod/mod_mime.html#multipleext">Files with -multiple extensions</A> - -<HR> - -<H2><A NAME="sethandler">SetHandler</A></H2> - -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> SetHandler <EM>handler-name</EM><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="mod/directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<BR> -<A - HREF="mod/directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> SetHandler is only available in Apache -1.1 and later.<P> - -<P>When placed into an <CODE>.htaccess</CODE> file or a -<CODE><Directory></CODE> or <CODE><Location></CODE> -section, this directive forces all matching files to be parsed through -the handler given by <EM>handler-name</EM>. For example, if you had a -directory you wanted to be parsed entirely as imagemap rule files, -regardless of extension, you might put the following into an -<CODE>.htaccess</CODE> file in that directory: -<PRE> - SetHandler imap-file -</PRE> - -<P>Another example: if you wanted to have the server display a status -report whenever a URL of <CODE>http://servername/status</CODE> was -called, you might put the following into access.conf: -<PRE> - <Location /status> - SetHandler server-status - </Location> -</PRE> -<HR> - -<H2>Programmer's Note</H2> - -<P>In order to implement the handler features, an addition has been -made to the <A HREF="misc/API.html">Apache API</A> that you may wish to -make use of. Specifically, a new record has been added to the -<CODE>request_rec</CODE> structure:</P> -<PRE> - char *handler -</PRE> -<P>If you wish to have your module engage a handler, you need only to -set <CODE>r->handler</CODE> to the name of the handler at any time -prior to the <CODE>invoke_handler</CODE> stage of the -request. Handlers are implemented as they were before, albeit using -the handler name instead of a content type. While it is not -necessary, the naming convention for handlers is to use a -dash-separated word, with no slashes, so as to not invade the media -type name-space.</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/handler.html.en b/docs/manual/handler.html.en deleted file mode 100644 index 72f16fd170..0000000000 --- a/docs/manual/handler.html.en +++ /dev/null @@ -1,195 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache's Handler Use</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache's Handler Use</H1> - -<H2>What is a Handler</H2> - -<P>A "handler" is an internal Apache representation of the action to be -performed when a file is called. Generally, files have implicit -handlers, based on the file type. Normally, all files are simply -served by the server, but certain file typed are "handled" -separately. For example, you may use a type of -"application/x-httpd-cgi" to invoke CGI scripts.</P> - -<P>Apache 1.1 adds the additional ability to use handlers -explicitly. Either based on filename extensions or on location, these -handlers are unrelated to file type. This is advantageous both because -it is a more elegant solution, but it also allows for both a type -<STRONG>and</STRONG> a handler to be associated with a file (See also -<A HREF="mod/mod_mime.html#multipleext">Files with Multiple Extensions</A>) - -</P> - -<P>Handlers can either be built into the server or to a module, or -they can be added with the <A -HREF="mod/mod_actions.html#action">Action</A> directive. The built-in -handlers in the standard distribution are as follows:</P> - -<UL> -<LI><STRONG>default-handler</STRONG>: - Send the file using the <CODE>default_handler()</CODE>, which is the - handler used by default to handle static content. - (core) -<LI><STRONG>send-as-is</STRONG>: - Send file with HTTP headers as is. - (<A HREF="mod/mod_asis.html">mod_asis</A>) -<LI><STRONG>cgi-script</STRONG>: - Treat the file as a CGI script. - (<A HREF="mod/mod_cgi.html">mod_cgi</A>) -<LI><STRONG>imap-file</STRONG>: - Imagemap rule file. - (<A HREF="mod/mod_imap.html">mod_imap</A>) -<LI><STRONG>server-info</STRONG>: - Get the server's configuration information - (<A HREF="mod/mod_info.html">mod_info</A>) -<LI><STRONG>server-parsed</STRONG>: - Parse for server-side includes - (<A HREF="mod/mod_include.html">mod_include</A>) -<LI><STRONG>server-status</STRONG>: - Get the server's status report - (<A HREF="mod/mod_status.html">mod_status</A>) -<LI><STRONG>type-map</STRONG>: - Parse as a type map file for content negotiation - (<A HREF="mod/mod_negotiation.html">mod_negotiation</A>) -</UL> - -<P> - -<H2>Directives</H2> -<UL> -<LI><A HREF="#addhandler">AddHandler</A> -<LI><A HREF="#sethandler">SetHandler</A> -</UL> - -<HR> - -<H2><A NAME="addhandler">AddHandler</A></H2> - -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddHandler <EM>handler-name extension extension...</EM><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="mod/directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="mod/directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<BR> -<A - HREF="mod/directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> AddHandler is only available in Apache -1.1 and later<P> - -<P>AddHandler maps the filename extensions <EM>extension</EM> to the -handler <EM>handler-name</EM>. This mapping is added to any already -in force, overriding any mappings that already exist for the same -<EM>extension</EM>. - -For example, to activate CGI scripts -with the file extension "<CODE>.cgi</CODE>", you might use: -<PRE> - AddHandler cgi-script cgi -</PRE> - -<P>Once that has been put into your srm.conf or httpd.conf file, any -file containing the "<CODE>.cgi</CODE>" extension will be treated as a -CGI program.</P> - -<P> - -<STRONG>See also</STRONG>: <A HREF="mod/mod_mime.html#multipleext">Files with -multiple extensions</A> - -<HR> - -<H2><A NAME="sethandler">SetHandler</A></H2> - -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> SetHandler <EM>handler-name</EM><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="mod/directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<BR> -<A - HREF="mod/directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> SetHandler is only available in Apache -1.1 and later.<P> - -<P>When placed into an <CODE>.htaccess</CODE> file or a -<CODE><Directory></CODE> or <CODE><Location></CODE> -section, this directive forces all matching files to be parsed through -the handler given by <EM>handler-name</EM>. For example, if you had a -directory you wanted to be parsed entirely as imagemap rule files, -regardless of extension, you might put the following into an -<CODE>.htaccess</CODE> file in that directory: -<PRE> - SetHandler imap-file -</PRE> - -<P>Another example: if you wanted to have the server display a status -report whenever a URL of <CODE>http://servername/status</CODE> was -called, you might put the following into access.conf: -<PRE> - <Location /status> - SetHandler server-status - </Location> -</PRE> -<HR> - -<H2>Programmer's Note</H2> - -<P>In order to implement the handler features, an addition has been -made to the <A HREF="misc/API.html">Apache API</A> that you may wish to -make use of. Specifically, a new record has been added to the -<CODE>request_rec</CODE> structure:</P> -<PRE> - char *handler -</PRE> -<P>If you wish to have your module engage a handler, you need only to -set <CODE>r->handler</CODE> to the name of the handler at any time -prior to the <CODE>invoke_handler</CODE> stage of the -request. Handlers are implemented as they were before, albeit using -the handler name instead of a content type. While it is not -necessary, the naming convention for handlers is to use a -dash-separated word, with no slashes, so as to not invade the media -type name-space.</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/header.html b/docs/manual/header.html deleted file mode 100644 index c0959dc7aa..0000000000 --- a/docs/manual/header.html +++ /dev/null @@ -1,6 +0,0 @@ -<DIV ALIGN="CENTER"> - <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> - <H3> - Apache HTTP Server Version 1.3 - </H3> -</DIV> diff --git a/docs/manual/images/custom_errordocs.gif b/docs/manual/images/custom_errordocs.gif Binary files differdeleted file mode 100644 index d566c5d891..0000000000 --- a/docs/manual/images/custom_errordocs.gif +++ /dev/null diff --git a/docs/manual/images/home.gif b/docs/manual/images/home.gif Binary files differdeleted file mode 100644 index 11299c1cb7..0000000000 --- a/docs/manual/images/home.gif +++ /dev/null diff --git a/docs/manual/images/index.gif b/docs/manual/images/index.gif Binary files differdeleted file mode 100644 index 741c8939d7..0000000000 --- a/docs/manual/images/index.gif +++ /dev/null diff --git a/docs/manual/images/mod_rewrite_fig1.fig b/docs/manual/images/mod_rewrite_fig1.fig deleted file mode 100644 index 7c80fea3f1..0000000000 --- a/docs/manual/images/mod_rewrite_fig1.fig +++ /dev/null @@ -1,60 +0,0 @@ -#FIG 3.2 -Landscape -Center -Inches -Letter -100.00 -Single --2 -1200 2 -0 32 #efefef -0 33 #cfcfef -0 34 #bebebe -2 1 0 4 4 7 0 0 -1 0.000 0 0 -1 1 0 6 - 1 1 2.00 120.00 240.00 - 6675 5250 6900 5250 6900 4650 4950 4650 4950 4050 5475 4050 -2 1 0 4 4 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 2.00 120.00 240.00 - 6900 4050 7650 4050 -2 1 0 4 4 7 0 0 -1 0.000 0 0 -1 1 0 6 - 1 1 2.00 120.00 240.00 - 9375 4050 9900 4050 9900 4650 7200 4650 7200 5250 7650 5250 -2 1 0 4 9 7 0 0 -1 0.000 0 0 -1 1 0 4 - 1 1 2.00 120.00 240.00 - 9300 5250 9900 5250 9900 6300 6975 6300 -2 1 2 4 0 7 0 0 -1 7.500 1 1 -1 0 0 2 - 3900 2100 3900 1500 -2 1 2 4 0 7 0 0 -1 7.500 1 1 -1 0 0 2 - 3900 7950 3900 7350 -2 1 1 4 9 7 0 0 -1 10.000 0 0 -1 1 0 4 - 1 1 2.00 120.00 240.00 - 5625 6300 2700 6300 2700 7050 3225 7050 -2 1 0 4 9 7 0 0 -1 0.000 0 0 -1 1 0 4 - 1 1 2.00 120.00 240.00 - 5550 3000 2700 3000 2700 5250 3225 5250 -2 1 1 4 9 7 0 0 -1 10.000 0 0 -1 1 0 4 - 1 1 2.00 120.00 240.00 - 9225 2325 9900 2325 9900 3000 6975 3000 -2 1 0 4 9 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 2.00 120.00 240.00 - 4800 5250 5550 5250 -2 4 0 2 9 7 0 0 -1 0.000 0 0 7 0 0 5 - 6900 3300 5700 3300 5700 2700 6900 2700 6900 3300 -2 4 0 2 9 7 0 0 -1 0.000 0 0 7 0 0 5 - 6900 6600 5700 6600 5700 6000 6900 6000 6900 6600 -4 0 0 0 0 0 20 0.0000 4 195 1455 3300 5400 RewriteRule\001 -4 0 0 0 0 1 20 0.0000 4 210 1440 7800 4200 CondPattern\001 -4 0 0 0 0 1 20 0.0000 4 270 1110 5625 4200 TestString\001 -4 0 0 0 0 0 20 0.0000 4 195 1905 3300 4200 RewriteCond \001 -4 0 0 0 0 1 20 0.0000 4 210 1320 7800 5400 Substitution\001 -4 0 0 0 0 1 20 0.0000 4 195 825 5700 5400 Pattern\001 -4 0 0 0 0 0 20 0.0000 4 195 1455 3300 7200 RewriteRule\001 -4 0 0 0 0 0 20 0.0000 4 195 1455 3300 2400 RewriteRule\001 -4 0 0 0 0 1 20 0.0000 4 195 825 5700 7200 Pattern\001 -4 0 0 0 0 1 20 0.0000 4 210 1320 7800 7200 Substitution\001 -4 0 0 0 0 1 20 0.0000 4 210 1320 7800 2400 Substitution\001 -4 0 0 0 0 1 20 0.0000 4 195 825 5700 2400 Pattern\001 -4 0 9 0 0 18 12 0.0000 4 135 645 6000 2925 current\001 -4 0 9 0 0 18 12 0.0000 4 135 375 6075 3150 URL\001 -4 0 9 0 0 18 12 0.0000 4 135 825 5925 6225 rewritten\001 -4 0 9 0 0 18 12 0.0000 4 135 375 6075 6450 URL\001 diff --git a/docs/manual/images/mod_rewrite_fig1.gif b/docs/manual/images/mod_rewrite_fig1.gif Binary files differdeleted file mode 100644 index 664ac1e7bb..0000000000 --- a/docs/manual/images/mod_rewrite_fig1.gif +++ /dev/null diff --git a/docs/manual/images/mod_rewrite_fig2.fig b/docs/manual/images/mod_rewrite_fig2.fig deleted file mode 100644 index facf410fc9..0000000000 --- a/docs/manual/images/mod_rewrite_fig2.fig +++ /dev/null @@ -1,50 +0,0 @@ -#FIG 3.2 -Landscape -Center -Inches -Letter -100.00 -Single --2 -1200 2 -0 32 #efefef -0 33 #cfcfef -0 34 #bebebe -2 1 2 4 0 7 0 0 -1 10.000 1 1 -1 0 0 2 - 4050 3750 4050 4425 -2 1 0 2 9 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 2.00 120.00 240.00 - 4950 4800 5550 4800 -2 1 0 2 9 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 2.00 120.00 240.00 - 4950 3600 5550 3600 -2 1 0 2 9 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 2.00 120.00 240.00 - 6600 5700 7725 5700 -2 1 0 2 9 7 0 0 -1 0.000 0 0 -1 1 0 6 - 1 1 2.00 120.00 240.00 - 6600 5550 6900 5550 6900 5100 4950 5100 4950 2850 5550 2850 -2 1 0 2 4 7 0 0 -1 0.000 0 0 -1 1 0 6 - 1 1 2.00 120.00 240.00 - 9525 4800 9750 4800 9750 5100 7200 5100 7200 5550 7725 5550 -2 1 0 2 4 7 0 0 -1 0.000 0 0 -1 1 0 6 - 1 1 2.00 120.00 240.00 - 9450 3000 9750 3000 9750 3225 5100 3225 5100 3450 5550 3450 -2 1 0 2 4 7 0 0 -1 0.000 0 0 -1 1 0 6 - 1 1 2.00 120.00 240.00 - 9450 3600 9750 3600 9750 3825 5100 3825 5100 4050 5550 4050 -2 1 0 2 4 7 0 0 -1 0.000 0 0 -1 1 0 6 - 1 1 2.00 120.00 240.00 - 9450 4200 9750 4200 9750 4425 5100 4425 5100 4650 5550 4650 -4 0 0 0 0 0 20 0.0000 4 195 1905 3300 4800 RewriteCond \001 -4 0 0 0 0 1 20 0.0000 4 210 1620 7800 4800 CondPatternN\001 -4 0 0 0 0 0 20 0.0000 4 195 1905 3300 3600 RewriteCond \001 -4 0 0 0 0 1 20 0.0000 4 210 1575 7800 3600 CondPattern2\001 -4 0 0 0 0 1 20 0.0000 4 270 1290 5625 4800 TestStringN\001 -4 0 0 0 0 1 20 0.0000 4 270 1245 5625 3600 TestString2\001 -4 0 0 0 0 0 20 0.0000 4 195 1905 3300 3000 RewriteCond \001 -4 0 0 0 0 1 20 0.0000 4 270 1245 5625 3000 TestString1\001 -4 0 0 0 0 1 20 0.0000 4 210 1575 7800 3000 CondPattern1\001 -4 0 0 0 0 1 20 0.0000 4 210 1320 7800 5700 Substitution\001 -4 0 0 0 0 1 20 0.0000 4 195 825 5700 5700 Pattern\001 -4 0 0 0 0 0 20 0.0000 4 195 1455 3300 5700 RewriteRule\001 diff --git a/docs/manual/images/mod_rewrite_fig2.gif b/docs/manual/images/mod_rewrite_fig2.gif Binary files differdeleted file mode 100644 index 3ea8cb65a3..0000000000 --- a/docs/manual/images/mod_rewrite_fig2.gif +++ /dev/null diff --git a/docs/manual/images/sub.gif b/docs/manual/images/sub.gif Binary files differdeleted file mode 100644 index 93061c5ad7..0000000000 --- a/docs/manual/images/sub.gif +++ /dev/null diff --git a/docs/manual/install-tpf.html b/docs/manual/install-tpf.html deleted file mode 100644 index 6a357452ae..0000000000 --- a/docs/manual/install-tpf.html +++ /dev/null @@ -1,277 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Installing Apache on TPF</TITLE> -</HEAD> - -<BODY> -<H1 ALIGN="center"> - <A NAME="top">Installing the Apache 1.3 HTTP Server on TPF</A> -</H1> -<HR> -<CENTER>[ <A HREF="#setup">Setup</A> - | <A HREF="#compilation">Compilation</A> - | <A HREF="#installation">Installation</A> - | <A HREF="#visualage">VisualAge</A> ] -</CENTER> -<HR> -<BR> - -<P> -This document outlines the steps needed to install Apache onto a TPF system. -</P> -<P> -You should first read -htdocs/manual/<A HREF="readme-tpf.html">readme-tpf.html</A> -for basic information on the port of Apache to TPF including required PUT level -and supported functions & modules. -</P> - -<H2 align=center><A NAME="setup">Setup</A></H2> -<P> -Due to the use of EBCDIC on MVS OS/390 Open Edition -(later referred to simply as -"Open Edition"), we've found that the most reliable -method for loading Apache onto your system is to unzip and tar the distribution -file on your PC, and then copy the extracted files to Open Edition -via an NFS client -capable of transferring the data in EBCDIC format. -</P> -<P> -Before moving the distribution to an -Open Edition environment, verify that the NFS drive will transfer the -filenames with upper/lower case preserved. -</P> -<P> -Since Open Edition is not the ultimate destination of the files, -the only required files and subdirectories that need to be moved to -Open Edition -are in /src. -</P> -<P> -<FONT COLOR=red><STRONG>WARNING</STRONG></FONT>: -If you are using a product such as WinZip on your PC, verify that -the <EM>"TAR File Smart CR/LF Conversion"</EM> option is NOT checked. -You can find this in WinZip under Options, Configuration. -This will save you lots of headaches later on. -</P> -<P> -<FONT COLOR=red><STRONG>WARNING</STRONG></FONT>: -Editing files on a PC before moving them to Open Edition may result -in the loss/addition of unprintable characters. Files of concern include shell -scripts and src/Configuration. The most common problems are with -tab characters -and CR/LF characters. Most editors will handle the CR/LF problem correctly -but none seem to handle tab characters. If you need to edit files, edit them -in a UNIX editor such as vi or emacs. -</P> - -<H2 align=center><A NAME="compilation">Compilation</A></H2> -<P> -Apache supports the notion of "optional modules". However, -the server has to know which modules are compiled into it. In order for -those modules to be effective, it is necessary to generate a short bit of -code ("modules.c") which simply has a list of them. If you are using the -make and Configure utility, "modules.c" will be created for you. -</P> -<P> -The provided scripts assume a c89 compiler and have only been tested on an -Open Edition environment. If you are using a platform other that -Open Edition you may need to modify src/os/tpf/TPFExport and src/Configure -to match your environment. -</P> -<P> -Note that UNIX/Open Edition commands in this section are shown in -<TT><STRONG>bold</STRONG></TT>, -are case sensitive, and must be made from the "src" directory. -</P> -<OL> -<LI>Overlay src/Configuration with src/Configuration.tmpl: - <TT><STRONG>cp Configuration.tmpl Configuration</STRONG></TT> - <BR><BR> -<LI>Edit src/Configuration. It contains the list and settings - of various "Rules" and an additional section at the bottom that determines - which modules to compile: - <BR><BR> - <OL type=a> - <LI>Adjust the Rules and <TT>EXTRA_CFLAGS|LIBS|LDFLAGS|INCLUDES</TT> - if you feel so inclined. - <BR><BR> - <LI>Comment out (by preceding the line with a "#") lines corresponding - to those modules you DO NOT wish to include. - At present the following modules MUST be commented out - as they are not yet supported on TPF: mod_actions, mod_auth, - mod_cgi, mod_env, mod_include, & mod_status. - <BR><BR> - <LI>Uncomment (by removing the initial "#", if present) lines - corresponding to those optional modules you wish - to include or add new lines corresponding to any custom modules - you have written. - The htdocs/manual/<A HREF="readme-tpf.html">readme-tpf.html</A> - document lists the modules that have been tested on TPF. - </OL> - <BR> -<LI>Set the TPF environment variables: - <TT><STRONG>. os/tpf/TPFExport</STRONG></TT> - <BR> - (The initial period and blank on the command are required to ensure - the environment variables exist beyond the scope of the shell script.) - This script will set the environment variables required to compile the - programs for TPF. Verify that the export variables are valid for your - installation, in particular, the system include file directories. The - system include files must reside on your Open Edition system in the - appropriate file structure similar to /usr/include and /usr/include/sys. - DO NOT modify the <TT>TPF=YES</TT> export variable. If this is - changed, the "Configure" script will not recognize TPF. - <BR><BR> -<LI>Remove the src/lib/expat-lite directory: - <TT><STRONG>rm -r lib/expat-lite</STRONG></TT> - <BR><BR> -<LI>Run the "Configure" script: - <TT><STRONG>Configure</STRONG></TT> - <BR> - The output will look something like this... - <PRE> - Using config file: Configuration - Creating Makefile - + configured for TPF platform - + setting C compiler to c89 - + setting C pre-processor to c89 -E - + checking for system header files - + adding selected modules - Creating Makefile in support - Creating Makefile in main - Creating Makefile in ap - Creating Makefile in regex - Creating Makefile in os/tpf - Creating Makefile in modules/standard - Creating Makefile in modules/example - $ _ - </PRE> - This generates modules.c and new versions of the Makefiles. - <BR><BR> - If you want to maintain multiple configurations, you can - say, <EM>e.g.</EM>, - <BR> - <TT><STRONG>Configure -file Configuration.ai</STRONG></TT> - <BR> - <PRE> - Using config file: Configuration.ai - Creating Makefile - + configured for <whatever> platform - + setting C compiler to <whatever> - et cetera - </PRE> - - If you receive an error such as "<TT>Configure 146: FSUM7351 not found</TT>" - the most likely explanation is that one or more of the make related - files were edited on a non-UNIX platform, corrupting the end-of-line marks. - Verify that lines ending with "\" in the flagged file do not have trailing - spaces. Using the vi editor and the sample error above as an example... - <BR><BR><PRE> - pull up the flagged file: <STRONG>vi Configure</STRONG> - turn on punctuation: <STRONG>:set list</STRONG> - go to the line in question: <STRONG>146G</STRONG> - or find a line with a "\": <STRONG>/\\</STRONG></PRE> - The end of line should display as "<TT>\$</TT>". If it is displayed as - "<TT>\ $</TT>" (with a blank between \ and $) then you should revert to the - distributed version of the file and make the site-specific - changes again using a UNIX compatible editor such as vi or emacs. - Then try the Configure command again. - <BR><PRE> close the file: <STRONG>:q </STRONG>(or - -<STRONG>:quit!</STRONG>)</PRE> -<LI>Now compile the programs: <TT><STRONG>make</STRONG></TT><BR> - The modules placed in the Apache distribution are the ones that have been - tested and are used regularly by various members of the Apache development - group. Additional modules contributed by members or third parties with specific - needs or functions are available at - <A -HREF="http://www.apache.org/dist/contrib/modules/">http://www.apache.org/dist/contrib/modules/</A>. - There are instructions on that page for linking these modules into the core Apache - code. - <BR><BR> - If during compilation you get a warning about a missing 'regex.h', set - <TT>WANTHSREGEX=yes</TT> in the src/Configuration file and start back at the - <TT><STRONG>Configure</STRONG></TT> step. -</OL> - -<A NAME="installation"> </A> -<H2 align=center>Installation</H2> -<OL> -<LI>After compilation, you will have all the object files required to build an - "httpd" loadset. The next step is to link the object files and create a loadset to be - stored in a PDS. Sample JCL for linking and loadsets has been included in - src/os/tpf/samples as "linkdll.jcl" and "loadset.jcl". You can submit these jobs - from CMS or directly from Open Edition if you have the proper authority. After - the jobs have completed, you can <TT>ZOLDR LOAD</TT> them to your TPF system. - <BR><BR> - NOTE: The <TT>mod_<EM>xxx</EM>.o</TT> files in the linkdll.jcl file must correspond to the - <TT>mod_<EM>xxx</EM>.o</TT> lines in the src/Configuration file. - <BR><BR> -<LI> - Apache requires a configuration file to initialize itself during activation. - (Previously three configuration files were used.) - Copy the distribution version, /conf/httpd.conf-dist, to /conf/httpd.conf and then - edit the /conf/httpd.conf copy with your site specific information. If your system is pre-PUT09 you - <font color=red><STRONG>must</STRONG></FONT> change <TT>ServerType</TT> from <TT>standalone</TT> - to <TT>inetd</TT>. - <BR><BR> - General documentation for Apache is located at - <A HREF="http://www.apache.org/docs/">http://www.apache.org/docs/</A> - and in the HTML pages included with this distribution under the - /htdocs/manual directory. - <BR><BR> -<LI>On TPF activate ZCLAW and update INETD using ZINET entries, the common case: - <BR><BR> - <PRE> - ZINET ADD S-TFTP PGM-CTFT PORT-69 PROTOCOL-UDP MODEL-NOWAIT - ZINET ADD S-APACHE PGM-<EM>pppp</EM> PROTOCOL-TCP MODEL-NOWAIT PORT-80 (if inetd mode) - ZINET ADD S-APACHE PGM-<EM>pppp</EM> PROTOCOL-TCP MODEL-NOLISTEN (if standalone mode)</PRE> - Please refer to <EM>IBM Transaction Processing Facility Transmission Control - Protocol/Internet Protocol Version 4 Release 1</EM> for more information - on ZCLAW, INETD, and TFTP. - <BR><BR> -<LI>Prior to sending a request to your Apache server from a browser, - TFTP the configuration file, log, icons and web pages to your TPF system. - A typical directory structure for Apache is as follows: -<PRE> /usr/local/apache/conf - /usr/local/apache/logs - /usr/local/apache/icons - /usr/local/apache/htdocs</PRE> - The logs directory must exist in order to avoid an - <CODE>fopen</CODE> error while running Apache. TFTP an empty file into - the logs subdirectory to create it. All gif, jpg, and zip files should be - TFTP'd as binary; conf files and html pages should be TFTP'd as text. -</OL> -<A NAME="visualage"> </A> -<H2 align=center>Compiling with VisualAge TPF</H2> -<P> - It is not required that "make" be used to compile Apache for TPF: - Individual programs may be compiled using IBM's VisualAge TPF product. - This is particularly useful when compiling selected programs for the Debug Tool. - <BR><BR> - The following VisualAge compile settings are required: - <UL> - <LI><EM>"DEFINE - Define preprocessor macro name(s)"</EM> must include - <TT><STRONG>TPF, CHARSET_EBCDIC, _POSIX_SOURCE,</STRONG></TT> and - <TT><STRONG>USE_HSREGEX</STRONG></TT> - <BR><BR> - <LI><EM>"LSEARCH - Path for user include files"</EM> must include - <TT><STRONG>../src/include</STRONG></TT> and <TT><STRONG>../src/os/tpf</STRONG></TT> - <BR><BR> - <LI><EM>"DLL - Generate DLL code"</EM> must be checked - <BR><BR> - <LI><EM>"LONGNAME - Support long names"</EM> must be checked - </UL> -</P> -<HR> -<CENTER>[ <A HREF="#top">top</A> - | <A HREF="#setup">Setup</A> - | <A HREF="#compilation">Compilation</A> - | <A HREF="#installation">Installation</A> - | <A HREF="#visualage">VisualAge</A> ] -</CENTER> - -</BODY> -</HTML> diff --git a/docs/manual/install.html b/docs/manual/install.html deleted file mode 100644 index cc9dcf1af1..0000000000 --- a/docs/manual/install.html +++ /dev/null @@ -1,270 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Compiling and Installing Apache</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Compiling and Installing Apache 1.3</H1> - -This document covers compilation and installation of Apache on Unix -systems only. For compiling and installation on Windows, see <A -HREF="windows.html">Using Apache with Microsoft Windows</A> and for -TPF see <A HREF="install-tpf.html">Installing the Apache 1.3 HTTP -Server on TPF</A>. - -<P> - -UnixWare users will want to consult <A HREF="unixware.html">build notes</A> -for various UnixWare versions before compiling. - -<H2>Downloading Apache</H2> - -Information on the latest version of Apache can be found on the Apache -web server at <A -HREF="http://www.apache.org/">http://www.apache.org/</A>. This will -list the current release, any more recent beta-test release, together -with details of mirror web and anonymous ftp sites. - -<P> - -If you downloaded a binary distribution, skip to <A -HREF="#install">Installing Apache</A>. Otherwise read the next section -for how to compile the server. - -<H2>Compiling Apache</H2> - -Compiling Apache consists of three steps: Firstly select which Apache -<STRONG>modules</STRONG> you want to include into the server. Secondly create a -configuration for your operating system. Thirdly compile the -executable. -<P> - -All configuration of Apache is performed in the <CODE>src</CODE> -directory of the Apache distribution. Change into this directory. - -<OL> - <LI> - Select modules to compile into Apache in the - <CODE>Configuration</CODE> file. Uncomment lines corresponding to - those optional modules you wish to include (among the AddModule lines - at the bottom of the file), or add new lines corresponding to - additional modules you have downloaded or written. (See <A - HREF="misc/API.html">API.html</A> for preliminary docs on how to - write Apache modules). Advanced users can comment out some of the - default modules if they are sure they will not need them (be careful - though, since many of the default modules are vital for the correct - operation and security of the server). - <P> - - You should also read the instructions in the <CODE>Configuration</CODE> - file to see if you need to set any of the <CODE>Rule</CODE> lines. - - - <LI> - Configure Apache for your operating system. Normally you can just - type run the <CODE>Configure</CODE> script as given below. However - if this fails or you have any special requirements (<EM>e.g.</EM>, to include - an additional library required by an optional module) you might need - to edit one or more of the following options in the - <CODE>Configuration</CODE> file: - <CODE>EXTRA_CFLAGS, LIBS, LDFLAGS, INCLUDES</CODE>. - <P> - - Run the <CODE>Configure</CODE> script: - <BLOCKQUOTE> - <PRE> - % Configure - Using 'Configuration' as config file - + configured for <whatever> platform - + setting C compiler to <whatever> * - + setting C compiler optimization-level to <whatever> * - + Adding selected modules - + doing sanity check on compiler and options - Creating Makefile in support - Creating Makefile in main - Creating Makefile in os/unix - Creating Makefile in modules/standard - </PRE> - </BLOCKQUOTE> - - (*: Depending on Configuration and your system, Configure - might not print these lines. That's OK).<P> - - This generates a Makefile for use in stage 3. It also creates a - Makefile in the support directory, for compilation of the optional - support programs. - <P> - - (If you want to maintain multiple configurations, you can give a - option to <CODE>Configure</CODE> to tell it to read an alternative - Configuration file, such as <CODE>Configure -file - Configuration.ai</CODE>). - <P> - - <LI> - Type <CODE>make</CODE>. -</OL> - -The modules we place in the Apache distribution are the ones we have -tested and are used regularly by various members of the Apache -development group. Additional modules contributed by members or third -parties with specific needs or functions are available at -<<A HREF="http://www.apache.org/dist/contrib/modules/" - >http://www.apache.org/dist/contrib/modules/</A>>. -There are instructions on that page for linking these modules into the -core Apache code. - -<H2><A NAME="install">Installing Apache</A></H2> - -You will have a binary file called <CODE>httpd</CODE> in the -<CODE>src</CODE> directory. A binary distribution of Apache will -supply this file. <P> - -The next step is to install the program and configure it. Apache is -designed to be configured and run from the same set of directories -where it is compiled. If you want to run it from somewhere else, make -a directory and copy the <CODE>conf</CODE>, <CODE>logs</CODE> and -<CODE>icons</CODE> directories into it. In either case you should -read the <A HREF="misc/security_tips.html#serverroot">security tips</A> -describing how to set the permissions on the server root directory.<P> - -The next step is to edit the configuration files for the server. This -consists of setting up various <STRONG>directives</STRONG> in up to three -central configuration files. By default, these files are located in -the <CODE>conf</CODE> directory and are called <CODE>srm.conf</CODE>, -<CODE>access.conf</CODE> and <CODE>httpd.conf</CODE>. To help you get -started there are same files in the <CODE>conf</CODE> directory of the -distribution, called <CODE>srm.conf-dist</CODE>, -<CODE>access.conf-dist</CODE> and <CODE>httpd.conf-dist</CODE>. Copy -or rename these files to the names without the <CODE>-dist</CODE>. -Then edit each of the files. Read the comments in each file carefully. -Failure to setup these files correctly could lead to your server not -working or being insecure. You should also have an additional file in -the <CODE>conf</CODE> directory called <CODE>mime.types</CODE>. This -file usually does not need editing. - -<P> - -First edit <CODE>httpd.conf</CODE>. This sets up general attributes -about the server: the port number, the user it runs as, <EM>etc.</EM> Next -edit the <CODE>srm.conf</CODE> file; this sets up the root of the -document tree, special functions like server-parsed HTML or internal -imagemap parsing, <EM>etc.</EM> Finally, edit the <CODE>access.conf</CODE> -file to at least set the base cases of access. - -<P> - -In addition to these three files, the server behavior can be configured -on a directory-by-directory basis by using <CODE>.htaccess</CODE> -files in directories accessed by the server. - -<H3>Set your system time properly!</H3> - -Proper operation of a public web server requires accurate time -keeping, since elements of the HTTP protocol are expressed as the time -of day. So, it's time to investigate setting up NTP or some other -time synchronization system on your Unix box, or whatever the -equivalent on NT would be. - -<H3>Starting and Stopping the Server</H3> - -To start the server, simply run <CODE>httpd</CODE>. This will look for -<CODE>httpd.conf</CODE> in the location compiled into the code (by -default <CODE>/usr/local/apache/conf/httpd.conf</CODE>). If -this file is somewhere else, you can give the real -location with the -f argument. For example: - -<PRE> - /usr/local/apache/httpd -f /usr/local/apache/conf/httpd.conf -</PRE> - -If all goes well this will return to the command prompt almost -immediately. This indicates that the server is now up and running. If -anything goes wrong during the initialization of the server you will -see an error message on the screen. - -If the server started ok, you can now use your browser to -connect to the server and read the documentation. If you are running -the browser on the same machine as the server and using the default -port of 80, a suitable URL to enter into your browser is - -<PRE> - http://localhost/ -</PRE> - -<P> - -Note that when the server starts it will create a number of -<EM>child</EM> processes to handle the requests. If you started Apache -as the root user, the parent process will continue to run as root -while the children will change to the user as given in the httpd.conf -file. - -<P> - -If when you run <CODE>httpd</CODE> it complained about being unable to -"bind" to an address, then either some other process is already using -the port you have configured Apache to use, or you are running httpd -as a normal user but trying to use port below 1024 (such as the -default port 80). - -<P> - -If the server is not running, read the error message displayed -when you run httpd. You should also check the server -error_log for additional information (with the default configuration, -this will be located in the file <CODE>error_log</CODE> in the -<CODE>logs</CODE> directory). - -<P> - -If you want your server to continue running after a system reboot, you -should add a call to <CODE>httpd</CODE> to your system startup files -(typically <CODE>rc.local</CODE> or a file in an -<CODE>rc.<EM>N</EM></CODE> directory). This will start Apache as root. -Before doing this ensure that your server is properly configured -for security and access restrictions. - -<P> - -To stop Apache send the parent process a TERM signal. The PID of this -process is written to the file <CODE>httpd.pid</CODE> in the -<CODE>logs</CODE> directory (unless configured otherwise). Do not -attempt to kill the child processes because they will be renewed by -the parent. A typical command to stop the server is: - -<PRE> - kill -TERM `cat /usr/local/apache/logs/httpd.pid` -</PRE> - -<P> - -For more information about Apache command line options, configuration -and log files, see <A HREF="invoking.html">Starting Apache</A>. For a -reference guide to all Apache directives supported by the distributed -modules, see the <A HREF="mod/directives.html">Apache directives</A>. - -<H2>Compiling Support Programs</H2> - -In addition to the main <CODE>httpd</CODE> server which is compiled -and configured as above, Apache includes a number of support programs. -These are not compiled by default. The support programs are in the -<CODE>support</CODE> directory of the distribution. To compile -the support programs, change into this directory and type -<PRE> - make -</PRE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/install.html.en b/docs/manual/install.html.en deleted file mode 100644 index cc9dcf1af1..0000000000 --- a/docs/manual/install.html.en +++ /dev/null @@ -1,270 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Compiling and Installing Apache</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Compiling and Installing Apache 1.3</H1> - -This document covers compilation and installation of Apache on Unix -systems only. For compiling and installation on Windows, see <A -HREF="windows.html">Using Apache with Microsoft Windows</A> and for -TPF see <A HREF="install-tpf.html">Installing the Apache 1.3 HTTP -Server on TPF</A>. - -<P> - -UnixWare users will want to consult <A HREF="unixware.html">build notes</A> -for various UnixWare versions before compiling. - -<H2>Downloading Apache</H2> - -Information on the latest version of Apache can be found on the Apache -web server at <A -HREF="http://www.apache.org/">http://www.apache.org/</A>. This will -list the current release, any more recent beta-test release, together -with details of mirror web and anonymous ftp sites. - -<P> - -If you downloaded a binary distribution, skip to <A -HREF="#install">Installing Apache</A>. Otherwise read the next section -for how to compile the server. - -<H2>Compiling Apache</H2> - -Compiling Apache consists of three steps: Firstly select which Apache -<STRONG>modules</STRONG> you want to include into the server. Secondly create a -configuration for your operating system. Thirdly compile the -executable. -<P> - -All configuration of Apache is performed in the <CODE>src</CODE> -directory of the Apache distribution. Change into this directory. - -<OL> - <LI> - Select modules to compile into Apache in the - <CODE>Configuration</CODE> file. Uncomment lines corresponding to - those optional modules you wish to include (among the AddModule lines - at the bottom of the file), or add new lines corresponding to - additional modules you have downloaded or written. (See <A - HREF="misc/API.html">API.html</A> for preliminary docs on how to - write Apache modules). Advanced users can comment out some of the - default modules if they are sure they will not need them (be careful - though, since many of the default modules are vital for the correct - operation and security of the server). - <P> - - You should also read the instructions in the <CODE>Configuration</CODE> - file to see if you need to set any of the <CODE>Rule</CODE> lines. - - - <LI> - Configure Apache for your operating system. Normally you can just - type run the <CODE>Configure</CODE> script as given below. However - if this fails or you have any special requirements (<EM>e.g.</EM>, to include - an additional library required by an optional module) you might need - to edit one or more of the following options in the - <CODE>Configuration</CODE> file: - <CODE>EXTRA_CFLAGS, LIBS, LDFLAGS, INCLUDES</CODE>. - <P> - - Run the <CODE>Configure</CODE> script: - <BLOCKQUOTE> - <PRE> - % Configure - Using 'Configuration' as config file - + configured for <whatever> platform - + setting C compiler to <whatever> * - + setting C compiler optimization-level to <whatever> * - + Adding selected modules - + doing sanity check on compiler and options - Creating Makefile in support - Creating Makefile in main - Creating Makefile in os/unix - Creating Makefile in modules/standard - </PRE> - </BLOCKQUOTE> - - (*: Depending on Configuration and your system, Configure - might not print these lines. That's OK).<P> - - This generates a Makefile for use in stage 3. It also creates a - Makefile in the support directory, for compilation of the optional - support programs. - <P> - - (If you want to maintain multiple configurations, you can give a - option to <CODE>Configure</CODE> to tell it to read an alternative - Configuration file, such as <CODE>Configure -file - Configuration.ai</CODE>). - <P> - - <LI> - Type <CODE>make</CODE>. -</OL> - -The modules we place in the Apache distribution are the ones we have -tested and are used regularly by various members of the Apache -development group. Additional modules contributed by members or third -parties with specific needs or functions are available at -<<A HREF="http://www.apache.org/dist/contrib/modules/" - >http://www.apache.org/dist/contrib/modules/</A>>. -There are instructions on that page for linking these modules into the -core Apache code. - -<H2><A NAME="install">Installing Apache</A></H2> - -You will have a binary file called <CODE>httpd</CODE> in the -<CODE>src</CODE> directory. A binary distribution of Apache will -supply this file. <P> - -The next step is to install the program and configure it. Apache is -designed to be configured and run from the same set of directories -where it is compiled. If you want to run it from somewhere else, make -a directory and copy the <CODE>conf</CODE>, <CODE>logs</CODE> and -<CODE>icons</CODE> directories into it. In either case you should -read the <A HREF="misc/security_tips.html#serverroot">security tips</A> -describing how to set the permissions on the server root directory.<P> - -The next step is to edit the configuration files for the server. This -consists of setting up various <STRONG>directives</STRONG> in up to three -central configuration files. By default, these files are located in -the <CODE>conf</CODE> directory and are called <CODE>srm.conf</CODE>, -<CODE>access.conf</CODE> and <CODE>httpd.conf</CODE>. To help you get -started there are same files in the <CODE>conf</CODE> directory of the -distribution, called <CODE>srm.conf-dist</CODE>, -<CODE>access.conf-dist</CODE> and <CODE>httpd.conf-dist</CODE>. Copy -or rename these files to the names without the <CODE>-dist</CODE>. -Then edit each of the files. Read the comments in each file carefully. -Failure to setup these files correctly could lead to your server not -working or being insecure. You should also have an additional file in -the <CODE>conf</CODE> directory called <CODE>mime.types</CODE>. This -file usually does not need editing. - -<P> - -First edit <CODE>httpd.conf</CODE>. This sets up general attributes -about the server: the port number, the user it runs as, <EM>etc.</EM> Next -edit the <CODE>srm.conf</CODE> file; this sets up the root of the -document tree, special functions like server-parsed HTML or internal -imagemap parsing, <EM>etc.</EM> Finally, edit the <CODE>access.conf</CODE> -file to at least set the base cases of access. - -<P> - -In addition to these three files, the server behavior can be configured -on a directory-by-directory basis by using <CODE>.htaccess</CODE> -files in directories accessed by the server. - -<H3>Set your system time properly!</H3> - -Proper operation of a public web server requires accurate time -keeping, since elements of the HTTP protocol are expressed as the time -of day. So, it's time to investigate setting up NTP or some other -time synchronization system on your Unix box, or whatever the -equivalent on NT would be. - -<H3>Starting and Stopping the Server</H3> - -To start the server, simply run <CODE>httpd</CODE>. This will look for -<CODE>httpd.conf</CODE> in the location compiled into the code (by -default <CODE>/usr/local/apache/conf/httpd.conf</CODE>). If -this file is somewhere else, you can give the real -location with the -f argument. For example: - -<PRE> - /usr/local/apache/httpd -f /usr/local/apache/conf/httpd.conf -</PRE> - -If all goes well this will return to the command prompt almost -immediately. This indicates that the server is now up and running. If -anything goes wrong during the initialization of the server you will -see an error message on the screen. - -If the server started ok, you can now use your browser to -connect to the server and read the documentation. If you are running -the browser on the same machine as the server and using the default -port of 80, a suitable URL to enter into your browser is - -<PRE> - http://localhost/ -</PRE> - -<P> - -Note that when the server starts it will create a number of -<EM>child</EM> processes to handle the requests. If you started Apache -as the root user, the parent process will continue to run as root -while the children will change to the user as given in the httpd.conf -file. - -<P> - -If when you run <CODE>httpd</CODE> it complained about being unable to -"bind" to an address, then either some other process is already using -the port you have configured Apache to use, or you are running httpd -as a normal user but trying to use port below 1024 (such as the -default port 80). - -<P> - -If the server is not running, read the error message displayed -when you run httpd. You should also check the server -error_log for additional information (with the default configuration, -this will be located in the file <CODE>error_log</CODE> in the -<CODE>logs</CODE> directory). - -<P> - -If you want your server to continue running after a system reboot, you -should add a call to <CODE>httpd</CODE> to your system startup files -(typically <CODE>rc.local</CODE> or a file in an -<CODE>rc.<EM>N</EM></CODE> directory). This will start Apache as root. -Before doing this ensure that your server is properly configured -for security and access restrictions. - -<P> - -To stop Apache send the parent process a TERM signal. The PID of this -process is written to the file <CODE>httpd.pid</CODE> in the -<CODE>logs</CODE> directory (unless configured otherwise). Do not -attempt to kill the child processes because they will be renewed by -the parent. A typical command to stop the server is: - -<PRE> - kill -TERM `cat /usr/local/apache/logs/httpd.pid` -</PRE> - -<P> - -For more information about Apache command line options, configuration -and log files, see <A HREF="invoking.html">Starting Apache</A>. For a -reference guide to all Apache directives supported by the distributed -modules, see the <A HREF="mod/directives.html">Apache directives</A>. - -<H2>Compiling Support Programs</H2> - -In addition to the main <CODE>httpd</CODE> server which is compiled -and configured as above, Apache includes a number of support programs. -These are not compiled by default. The support programs are in the -<CODE>support</CODE> directory of the distribution. To compile -the support programs, change into this directory and type -<PRE> - make -</PRE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/invoking.html b/docs/manual/invoking.html deleted file mode 100644 index 02ee07659f..0000000000 --- a/docs/manual/invoking.html +++ /dev/null @@ -1,220 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Starting Apache</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Starting Apache</H1> - -<H2>Invoking Apache</H2> - -On Unix, the <CODE>httpd</CODE> program is usually run as a daemon -which executes continuously, handling requests. It is possible to -invoke Apache by the Internet daemon <CODE>inetd</CODE> each time a -connection to the HTTP service is made (use the <A -HREF="mod/core.html#servertype">ServerType</A> directive) but this is -not recommended. - -<P> - -On Windows, Apache is normally run as a service on Windows NT, or as a -console application on Windows 95. See also <A -HREF="windows.html#run">running Apache for Windows</A>. - -<H2>Command line options</H2> -The following options are recognized on the httpd command line: -<DL> -<DT><CODE>-d</CODE> <EM>serverroot</EM> -<DD>Set the initial value for the -<A HREF="mod/core.html#serverroot">ServerRoot</A> variable to -<EM>serverroot</EM>. This can be overridden by the ServerRoot command -in the configuration file. The default is -<CODE>/usr/local/apache</CODE> on Unix, <CODE>/apache</CODE> on -Windows and <CODE>/os2httpd</CODE> on OS/2. - -<DT><CODE>-D</CODE> <EM>name</EM> -<DD>Define a name for use in in -<A HREF="mod/core.html#ifdefine">IfDefine</A> directives. -This option can be used to optionally enable certain functionality in the -configuration file, or to use a common configuration for -several independent hosts, where host specific information is enclosed in -<IfDefine> sections. - -<DT><CODE>-f</CODE> <EM>config</EM> -<DD>Execute the commands in the file <EM>config</EM> on startup. If -<EM>config</EM> does not begin with a <CODE>/</CODE>, then it is taken to be a -path relative to the <A HREF="mod/core.html#serverroot">ServerRoot</A>. The -default is <CODE>conf/httpd.conf</CODE>. - -<DT><CODE>-C</CODE> <EM>"directive"</EM> -<DD>Process the given apache "directive" (just as if it had been part of a -configuration file) <STRONG>before</STRONG> actually reading the regular configuration files. - -<DT><CODE>-c</CODE> <EM>"directive"</EM> -<DD>Process the given apache "directive" <STRONG>after</STRONG> reading -all the regular configuration files. - -<DT><CODE>-X</CODE> -<DD>Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do <EM>NOT</EM> -use this mode to provide ordinary web service. - -<DT><CODE>-v</CODE> -<DD>Print the version of httpd and its build date, and then exit. - -<DT><A NAME="version"><CODE>-V</CODE></A> -<DD>Print the base version of httpd, its -build date, and a list of compile time settings which influence the -behavior and performance of the apache server (<EM>e.g.</EM>, -<SAMP>-DUSE_MMAP_FILES</SAMP>), -then exit. - -<DT><A NAME="help"><CODE>-L</CODE></A> -<DD> - -Give a list of directives together with expected arguments and places -where the directive is valid, then exit. (Apache 1.3.4 and -later. Earlier versions used -l instead). - - -<DT><CODE>-l</CODE></A> -<DD> - -Give a list of all modules compiled into the server, then exit. -(Apache 1.3.4 and later. Earlier versions used -h instead).<br> - -Give a list of directives together with expected arguments and places -where the directive is valid, then exit. (Apache 1.2 to 1.3.3. Later -versions use -L instead). - - - -<DT><CODE>-h</CODE> -<DD> - -Print a list of the httpd options, then exit. (Apache 1.3.4 and -later. Earlier versions used -? instead).<br> - -Give a list of all modules compiled into the server, then exit. (Up to -Apache 1.3.3. Later versions use -l instead).<br> - - -<DT><CODE>-S</CODE> -<DD>Show the settings as parsed from the config file (currently only -shows a breakdown of the vhost settings) but do not start the -server. (Up to Apache 1.3.3, this option also started the server). - -<DT><CODE>-t</CODE> -<DD>Test the configuration file syntax (<EM>i.e.</EM>, read all configuration files -and interpret them) but do not start the server. If the configuration contains -errors, display an error message and exit with a non-zero exit status, -otherwise display "Syntax OK" and terminate with a zero exit status. This -command checks to see if all DocumentRoot entries exist and are directories. -For sites with many vhosts, this is expensive; consider the <CODE>-T</CODE> -command instead. - -<DT><CODE>-T</CODE> -<DD>Test the configuration file syntax (<EM>i.e.</EM>, read all configuration files -and interpret them) but do not start the server. If the configuration contains -errors, display an error message and exit with a non-zero exit status, -otherwise display "Syntax OK" and terminate with a zero exit status. This -command does not perform any checking of the DocumentRoot entries. - -<DT><CODE>-k</CODE> <EM>option</EM> -<DD>Windows only: signal Apache to restart or shutdown. <EM>option</EM> -is one of "shutdown" or "restart". (Apache 1.3.3 and later). - -<DT><CODE>-?</CODE> -<DD>Print a list of the httpd options, and then exit (up to Apache -1.3.3. Later version use -h instead). - -</DL> - -<H2>Configuration files</H2> -The server will read three files for configuration directives. Any -directive may appear in any of these files. The the names of these -files are taken to be relative to the server root; this is set by the -<A HREF="mod/core.html#serverroot">ServerRoot</A> directive, the -<CODE>-d</CODE> command line flag, or (on Windows only) the registry -(see <A HREF="windows.html#run">Running Apache for Windows</A>). - -Conventionally, the files are: -<DL> -<DT><CODE>conf/httpd.conf</CODE> -<DD>Contains directives that control the operation of the server daemon. -The filename may be overridden with the <CODE>-f</CODE> command line flag. - -<DT><CODE>conf/srm.conf</CODE> -<DD>Contains directives that control the specification of documents that -the server can provide to clients. The filename may be overridden with -the <A HREF="mod/core.html#resourceconfig">ResourceConfig</A> directive. - -<DT><CODE>conf/access.conf</CODE> -<DD>Contains directives that control access to documents. -The filename may be overridden with the -<A HREF="mod/core.html#accessconfig">AccessConfig</A> directive. -</DL> -However, these conventions need not be adhered to. -<P> -The server also reads a file containing mime document types; the filename -is set by the <A HREF="mod/mod_mime.html#typesconfig">TypesConfig</A> -directive, -and is <CODE>conf/mime.types</CODE> by default. - -<H2>Log files</H2> -<H3>security warning</H3> -Anyone who can write to the directory where Apache is writing a -log file can almost certainly gain access to the uid that the server is -started as, which is normally root. Do <EM>NOT</EM> give people write -access to the directory the logs are stored in without being aware of -the consequences; see the <A HREF="misc/security_tips.html">security tips</A> -document for details. -<H3>pid file</H3> - -On startup, Apache saves the process id of the parent httpd process to -the file <CODE>logs/httpd.pid</CODE>. This filename can be changed -with the <A HREF="mod/core.html#pidfile">PidFile</A> directive. The -process-id is for use by the administrator in restarting and -terminating the daemon: on Unix, a HUP or USR1 signal causes the -daemon to re-read its configuration files and a TERM signal causes it -to die gracefully; on Windows, use the -k command line option instead. -For more information see the <A HREF="stopping.html">Stopping and -Restarting</A> page. - -<P> -If the process dies (or is killed) abnormally, then it will be necessary to -kill the children httpd processes. - -<H3>Error log</H3> - -The server will log error messages to a log file, by default -<CODE>logs/error_log</CODE> on Unix or <CODE>logs/error.log</CODE> on -Windows and OS/2. The filename can be set using the <A -HREF="mod/core.html#errorlog">ErrorLog</A> directive; different error -logs can be set for different <A -HREF="mod/core.html#virtualhost">virtual hosts</A>. - -<H3>Transfer log</H3> - -The server will typically log each request to a transfer file, by -default <CODE>logs/access_log</CODE> on Unix or -<CODE>logs/access.log</CODE> on Windows and OS/2. The filename can be -set using a <A -HREF="mod/mod_log_config.html#transferlog">TransferLog</A> directive -or additional log files created with the <A -HREF="mod/mod_log_config.html#customlog">CustomLog</A> directive; -different transfer logs can be set for different <A -HREF="mod/core.html#virtualhost">virtual hosts</A>. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/invoking.html.en b/docs/manual/invoking.html.en deleted file mode 100644 index 02ee07659f..0000000000 --- a/docs/manual/invoking.html.en +++ /dev/null @@ -1,220 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Starting Apache</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Starting Apache</H1> - -<H2>Invoking Apache</H2> - -On Unix, the <CODE>httpd</CODE> program is usually run as a daemon -which executes continuously, handling requests. It is possible to -invoke Apache by the Internet daemon <CODE>inetd</CODE> each time a -connection to the HTTP service is made (use the <A -HREF="mod/core.html#servertype">ServerType</A> directive) but this is -not recommended. - -<P> - -On Windows, Apache is normally run as a service on Windows NT, or as a -console application on Windows 95. See also <A -HREF="windows.html#run">running Apache for Windows</A>. - -<H2>Command line options</H2> -The following options are recognized on the httpd command line: -<DL> -<DT><CODE>-d</CODE> <EM>serverroot</EM> -<DD>Set the initial value for the -<A HREF="mod/core.html#serverroot">ServerRoot</A> variable to -<EM>serverroot</EM>. This can be overridden by the ServerRoot command -in the configuration file. The default is -<CODE>/usr/local/apache</CODE> on Unix, <CODE>/apache</CODE> on -Windows and <CODE>/os2httpd</CODE> on OS/2. - -<DT><CODE>-D</CODE> <EM>name</EM> -<DD>Define a name for use in in -<A HREF="mod/core.html#ifdefine">IfDefine</A> directives. -This option can be used to optionally enable certain functionality in the -configuration file, or to use a common configuration for -several independent hosts, where host specific information is enclosed in -<IfDefine> sections. - -<DT><CODE>-f</CODE> <EM>config</EM> -<DD>Execute the commands in the file <EM>config</EM> on startup. If -<EM>config</EM> does not begin with a <CODE>/</CODE>, then it is taken to be a -path relative to the <A HREF="mod/core.html#serverroot">ServerRoot</A>. The -default is <CODE>conf/httpd.conf</CODE>. - -<DT><CODE>-C</CODE> <EM>"directive"</EM> -<DD>Process the given apache "directive" (just as if it had been part of a -configuration file) <STRONG>before</STRONG> actually reading the regular configuration files. - -<DT><CODE>-c</CODE> <EM>"directive"</EM> -<DD>Process the given apache "directive" <STRONG>after</STRONG> reading -all the regular configuration files. - -<DT><CODE>-X</CODE> -<DD>Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do <EM>NOT</EM> -use this mode to provide ordinary web service. - -<DT><CODE>-v</CODE> -<DD>Print the version of httpd and its build date, and then exit. - -<DT><A NAME="version"><CODE>-V</CODE></A> -<DD>Print the base version of httpd, its -build date, and a list of compile time settings which influence the -behavior and performance of the apache server (<EM>e.g.</EM>, -<SAMP>-DUSE_MMAP_FILES</SAMP>), -then exit. - -<DT><A NAME="help"><CODE>-L</CODE></A> -<DD> - -Give a list of directives together with expected arguments and places -where the directive is valid, then exit. (Apache 1.3.4 and -later. Earlier versions used -l instead). - - -<DT><CODE>-l</CODE></A> -<DD> - -Give a list of all modules compiled into the server, then exit. -(Apache 1.3.4 and later. Earlier versions used -h instead).<br> - -Give a list of directives together with expected arguments and places -where the directive is valid, then exit. (Apache 1.2 to 1.3.3. Later -versions use -L instead). - - - -<DT><CODE>-h</CODE> -<DD> - -Print a list of the httpd options, then exit. (Apache 1.3.4 and -later. Earlier versions used -? instead).<br> - -Give a list of all modules compiled into the server, then exit. (Up to -Apache 1.3.3. Later versions use -l instead).<br> - - -<DT><CODE>-S</CODE> -<DD>Show the settings as parsed from the config file (currently only -shows a breakdown of the vhost settings) but do not start the -server. (Up to Apache 1.3.3, this option also started the server). - -<DT><CODE>-t</CODE> -<DD>Test the configuration file syntax (<EM>i.e.</EM>, read all configuration files -and interpret them) but do not start the server. If the configuration contains -errors, display an error message and exit with a non-zero exit status, -otherwise display "Syntax OK" and terminate with a zero exit status. This -command checks to see if all DocumentRoot entries exist and are directories. -For sites with many vhosts, this is expensive; consider the <CODE>-T</CODE> -command instead. - -<DT><CODE>-T</CODE> -<DD>Test the configuration file syntax (<EM>i.e.</EM>, read all configuration files -and interpret them) but do not start the server. If the configuration contains -errors, display an error message and exit with a non-zero exit status, -otherwise display "Syntax OK" and terminate with a zero exit status. This -command does not perform any checking of the DocumentRoot entries. - -<DT><CODE>-k</CODE> <EM>option</EM> -<DD>Windows only: signal Apache to restart or shutdown. <EM>option</EM> -is one of "shutdown" or "restart". (Apache 1.3.3 and later). - -<DT><CODE>-?</CODE> -<DD>Print a list of the httpd options, and then exit (up to Apache -1.3.3. Later version use -h instead). - -</DL> - -<H2>Configuration files</H2> -The server will read three files for configuration directives. Any -directive may appear in any of these files. The the names of these -files are taken to be relative to the server root; this is set by the -<A HREF="mod/core.html#serverroot">ServerRoot</A> directive, the -<CODE>-d</CODE> command line flag, or (on Windows only) the registry -(see <A HREF="windows.html#run">Running Apache for Windows</A>). - -Conventionally, the files are: -<DL> -<DT><CODE>conf/httpd.conf</CODE> -<DD>Contains directives that control the operation of the server daemon. -The filename may be overridden with the <CODE>-f</CODE> command line flag. - -<DT><CODE>conf/srm.conf</CODE> -<DD>Contains directives that control the specification of documents that -the server can provide to clients. The filename may be overridden with -the <A HREF="mod/core.html#resourceconfig">ResourceConfig</A> directive. - -<DT><CODE>conf/access.conf</CODE> -<DD>Contains directives that control access to documents. -The filename may be overridden with the -<A HREF="mod/core.html#accessconfig">AccessConfig</A> directive. -</DL> -However, these conventions need not be adhered to. -<P> -The server also reads a file containing mime document types; the filename -is set by the <A HREF="mod/mod_mime.html#typesconfig">TypesConfig</A> -directive, -and is <CODE>conf/mime.types</CODE> by default. - -<H2>Log files</H2> -<H3>security warning</H3> -Anyone who can write to the directory where Apache is writing a -log file can almost certainly gain access to the uid that the server is -started as, which is normally root. Do <EM>NOT</EM> give people write -access to the directory the logs are stored in without being aware of -the consequences; see the <A HREF="misc/security_tips.html">security tips</A> -document for details. -<H3>pid file</H3> - -On startup, Apache saves the process id of the parent httpd process to -the file <CODE>logs/httpd.pid</CODE>. This filename can be changed -with the <A HREF="mod/core.html#pidfile">PidFile</A> directive. The -process-id is for use by the administrator in restarting and -terminating the daemon: on Unix, a HUP or USR1 signal causes the -daemon to re-read its configuration files and a TERM signal causes it -to die gracefully; on Windows, use the -k command line option instead. -For more information see the <A HREF="stopping.html">Stopping and -Restarting</A> page. - -<P> -If the process dies (or is killed) abnormally, then it will be necessary to -kill the children httpd processes. - -<H3>Error log</H3> - -The server will log error messages to a log file, by default -<CODE>logs/error_log</CODE> on Unix or <CODE>logs/error.log</CODE> on -Windows and OS/2. The filename can be set using the <A -HREF="mod/core.html#errorlog">ErrorLog</A> directive; different error -logs can be set for different <A -HREF="mod/core.html#virtualhost">virtual hosts</A>. - -<H3>Transfer log</H3> - -The server will typically log each request to a transfer file, by -default <CODE>logs/access_log</CODE> on Unix or -<CODE>logs/access.log</CODE> on Windows and OS/2. The filename can be -set using a <A -HREF="mod/mod_log_config.html#transferlog">TransferLog</A> directive -or additional log files created with the <A -HREF="mod/mod_log_config.html#customlog">CustomLog</A> directive; -different transfer logs can be set for different <A -HREF="mod/core.html#virtualhost">virtual hosts</A>. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/location.html b/docs/manual/location.html deleted file mode 100644 index 2dddd2ee2c..0000000000 --- a/docs/manual/location.html +++ /dev/null @@ -1,68 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Access Control by URL</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Access Control by URL</H1> - -<H2><A NAME="location">The <CODE><Location></CODE> Directive</A></H2> - -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <Location <EM>URL prefix</EM>><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> - -<P>The <Location> directive provides for access control by -URL. It is comparable to the <A -HREF="mod/core.html#directory"><Directory></A> directive, and -should be matched with a </Location> directive. Directives that -apply to the URL given should be listen -within. <CODE><Location></CODE> sections are processed in the -order they appear in the configuration file, after the -<Directory> sections and <CODE>.htaccess</CODE> files are -read.</P> - -<P>Note that, due to the way HTTP functions, <EM>URL prefix</EM> -should, save for proxy requests, be of the form <CODE>/path/</CODE>, -and should not include the <CODE>http://servername</CODE>. It doesn't -necessarily have to protect a directory (it can be an individual -file, or a number of files), and can include wild-cards. In a wild-card -string, `?' matches any single character, and `*' matches any -sequences of characters. - -<P>This functionality is especially useful when combined with the -<CODE><A HREF="mod/mod_mime.html#sethandler">SetHandler</A></CODE> -directive. For example, to enable status requests, but allow them only -from browsers at foo.com, you might use: - -<PRE> - <Location /status> - SetHandler server-status - order deny,allow - deny from all - allow from .foo.com - </Location> -</PRE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/misc/API.html b/docs/manual/misc/API.html deleted file mode 100644 index bf0fb77d7a..0000000000 --- a/docs/manual/misc/API.html +++ /dev/null @@ -1,1153 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Apache API notes</TITLE> -</HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache API notes</H1> - -These are some notes on the Apache API and the data structures you -have to deal with, <EM>etc.</EM> They are not yet nearly complete, but -hopefully, they will help you get your bearings. Keep in mind that -the API is still subject to change as we gain experience with it. -(See the TODO file for what <EM>might</EM> be coming). However, -it will be easy to adapt modules to any changes that are made. -(We have more modules to adapt than you do). -<P> - -A few notes on general pedagogical style here. In the interest of -conciseness, all structure declarations here are incomplete --- the -real ones have more slots that I'm not telling you about. For the -most part, these are reserved to one component of the server core or -another, and should be altered by modules with caution. However, in -some cases, they really are things I just haven't gotten around to -yet. Welcome to the bleeding edge.<P> - -Finally, here's an outline, to give you some bare idea of what's -coming up, and in what order: - -<UL> -<LI> <A HREF="#basics">Basic concepts.</A> -<MENU> - <LI> <A HREF="#HMR">Handlers, Modules, and Requests</A> - <LI> <A HREF="#moduletour">A brief tour of a module</A> -</MENU> -<LI> <A HREF="#handlers">How handlers work</A> -<MENU> - <LI> <A HREF="#req_tour">A brief tour of the <CODE>request_rec</CODE></A> - <LI> <A HREF="#req_orig">Where request_rec structures come from</A> - <LI> <A HREF="#req_return">Handling requests, declining, and returning error - codes</A> - <LI> <A HREF="#resp_handlers">Special considerations for response handlers</A> - <LI> <A HREF="#auth_handlers">Special considerations for authentication - handlers</A> - <LI> <A HREF="#log_handlers">Special considerations for logging handlers</A> -</MENU> -<LI> <A HREF="#pools">Resource allocation and resource pools</A> -<LI> <A HREF="#config">Configuration, commands and the like</A> -<MENU> - <LI> <A HREF="#per-dir">Per-directory configuration structures</A> - <LI> <A HREF="#commands">Command handling</A> - <LI> <A HREF="#servconf">Side notes --- per-server configuration, - virtual servers, <EM>etc</EM>.</A> -</MENU> -</UL> - -<H2><A NAME="basics">Basic concepts.</A></H2> - -We begin with an overview of the basic concepts behind the -API, and how they are manifested in the code. - -<H3><A NAME="HMR">Handlers, Modules, and Requests</A></H3> - -Apache breaks down request handling into a series of steps, more or -less the same way the Netscape server API does (although this API has -a few more stages than NetSite does, as hooks for stuff I thought -might be useful in the future). These are: - -<UL> - <LI> URI -> Filename translation - <LI> Auth ID checking [is the user who they say they are?] - <LI> Auth access checking [is the user authorized <EM>here</EM>?] - <LI> Access checking other than auth - <LI> Determining MIME type of the object requested - <LI> `Fixups' --- there aren't any of these yet, but the phase is - intended as a hook for possible extensions like - <CODE>SetEnv</CODE>, which don't really fit well elsewhere. - <LI> Actually sending a response back to the client. - <LI> Logging the request -</UL> - -These phases are handled by looking at each of a succession of -<EM>modules</EM>, looking to see if each of them has a handler for the -phase, and attempting invoking it if so. The handler can typically do -one of three things: - -<UL> - <LI> <EM>Handle</EM> the request, and indicate that it has done so - by returning the magic constant <CODE>OK</CODE>. - <LI> <EM>Decline</EM> to handle the request, by returning the magic - integer constant <CODE>DECLINED</CODE>. In this case, the - server behaves in all respects as if the handler simply hadn't - been there. - <LI> Signal an error, by returning one of the HTTP error codes. - This terminates normal handling of the request, although an - ErrorDocument may be invoked to try to mop up, and it will be - logged in any case. -</UL> - -Most phases are terminated by the first module that handles them; -however, for logging, `fixups', and non-access authentication -checking, all handlers always run (barring an error). Also, the -response phase is unique in that modules may declare multiple handlers -for it, via a dispatch table keyed on the MIME type of the requested -object. Modules may declare a response-phase handler which can handle -<EM>any</EM> request, by giving it the key <CODE>*/*</CODE> (<EM>i.e.</EM>, a -wildcard MIME type specification). However, wildcard handlers are -only invoked if the server has already tried and failed to find a more -specific response handler for the MIME type of the requested object -(either none existed, or they all declined).<P> - -The handlers themselves are functions of one argument (a -<CODE>request_rec</CODE> structure. vide infra), which returns an -integer, as above.<P> - -<H3><A NAME="moduletour">A brief tour of a module</A></H3> - -At this point, we need to explain the structure of a module. Our -candidate will be one of the messier ones, the CGI module --- this -handles both CGI scripts and the <CODE>ScriptAlias</CODE> config file -command. It's actually a great deal more complicated than most -modules, but if we're going to have only one example, it might as well -be the one with its fingers in every place.<P> - -Let's begin with handlers. In order to handle the CGI scripts, the -module declares a response handler for them. Because of -<CODE>ScriptAlias</CODE>, it also has handlers for the name -translation phase (to recognize <CODE>ScriptAlias</CODE>ed URIs), the -type-checking phase (any <CODE>ScriptAlias</CODE>ed request is typed -as a CGI script).<P> - -The module needs to maintain some per (virtual) -server information, namely, the <CODE>ScriptAlias</CODE>es in effect; -the module structure therefore contains pointers to a functions which -builds these structures, and to another which combines two of them (in -case the main server and a virtual server both have -<CODE>ScriptAlias</CODE>es declared).<P> - -Finally, this module contains code to handle the -<CODE>ScriptAlias</CODE> command itself. This particular module only -declares one command, but there could be more, so modules have -<EM>command tables</EM> which declare their commands, and describe -where they are permitted, and how they are to be invoked. <P> - -A final note on the declared types of the arguments of some of these -commands: a <CODE>pool</CODE> is a pointer to a <EM>resource pool</EM> -structure; these are used by the server to keep track of the memory -which has been allocated, files opened, <EM>etc.</EM>, either to service a -particular request, or to handle the process of configuring itself. -That way, when the request is over (or, for the configuration pool, -when the server is restarting), the memory can be freed, and the files -closed, <EM>en masse</EM>, without anyone having to write explicit code to -track them all down and dispose of them. Also, a -<CODE>cmd_parms</CODE> structure contains various information about -the config file being read, and other status information, which is -sometimes of use to the function which processes a config-file command -(such as <CODE>ScriptAlias</CODE>). - -With no further ado, the module itself: - -<PRE> -/* Declarations of handlers. */ - -int translate_scriptalias (request_rec *); -int type_scriptalias (request_rec *); -int cgi_handler (request_rec *); - -/* Subsidiary dispatch table for response-phase handlers, by MIME type */ - -handler_rec cgi_handlers[] = { -{ "application/x-httpd-cgi", cgi_handler }, -{ NULL } -}; - -/* Declarations of routines to manipulate the module's configuration - * info. Note that these are returned, and passed in, as void *'s; - * the server core keeps track of them, but it doesn't, and can't, - * know their internal structure. - */ - -void *make_cgi_server_config (pool *); -void *merge_cgi_server_config (pool *, void *, void *); - -/* Declarations of routines to handle config-file commands */ - -extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake, - char *real); - -command_rec cgi_cmds[] = { -{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2, - "a fakename and a realname"}, -{ NULL } -}; - -module cgi_module = { - STANDARD_MODULE_STUFF, - NULL, /* initializer */ - NULL, /* dir config creator */ - NULL, /* dir merger --- default is to override */ - make_cgi_server_config, /* server config */ - merge_cgi_server_config, /* merge server config */ - cgi_cmds, /* command table */ - cgi_handlers, /* handlers */ - translate_scriptalias, /* filename translation */ - NULL, /* check_user_id */ - NULL, /* check auth */ - NULL, /* check access */ - type_scriptalias, /* type_checker */ - NULL, /* fixups */ - NULL, /* logger */ - NULL /* header parser */ -}; -</PRE> - -<H2><A NAME="handlers">How handlers work</A></H2> - -The sole argument to handlers is a <CODE>request_rec</CODE> structure. -This structure describes a particular request which has been made to -the server, on behalf of a client. In most cases, each connection to -the client generates only one <CODE>request_rec</CODE> structure.<P> - -<H3><A NAME="req_tour">A brief tour of the <CODE>request_rec</CODE></A></H3> - -The <CODE>request_rec</CODE> contains pointers to a resource pool -which will be cleared when the server is finished handling the -request; to structures containing per-server and per-connection -information, and most importantly, information on the request itself.<P> - -The most important such information is a small set of character -strings describing attributes of the object being requested, including -its URI, filename, content-type and content-encoding (these being filled -in by the translation and type-check handlers which handle the -request, respectively). <P> - -Other commonly used data items are tables giving the MIME headers on -the client's original request, MIME headers to be sent back with the -response (which modules can add to at will), and environment variables -for any subprocesses which are spawned off in the course of servicing -the request. These tables are manipulated using the -<CODE>ap_table_get</CODE> and <CODE>ap_table_set</CODE> routines. <P> -<BLOCKQUOTE> - Note that the <SAMP>Content-type</SAMP> header value <EM>cannot</EM> be - set by module content-handlers using the <SAMP>ap_table_*()</SAMP> - routines. Rather, it is set by pointing the <SAMP>content_type</SAMP> - field in the <SAMP>request_rec</SAMP> structure to an appropriate - string. <EM>E.g.</EM>, - <PRE> - r->content_type = "text/html"; - </PRE> -</BLOCKQUOTE> -Finally, there are pointers to two data structures which, in turn, -point to per-module configuration structures. Specifically, these -hold pointers to the data structures which the module has built to -describe the way it has been configured to operate in a given -directory (via <CODE>.htaccess</CODE> files or -<CODE><Directory></CODE> sections), for private data it has -built in the course of servicing the request (so modules' handlers for -one phase can pass `notes' to their handlers for other phases). There -is another such configuration vector in the <CODE>server_rec</CODE> -data structure pointed to by the <CODE>request_rec</CODE>, which -contains per (virtual) server configuration data.<P> - -Here is an abridged declaration, giving the fields most commonly used:<P> - -<PRE> -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, <EM>etc.</EM> */ - int method_number; /* M_GET, M_POST, <EM>etc.</EM> */ - - /* 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, <EM>etc.</EM> */ - void *request_config; /* Notes on *this* request */ - -}; - -</PRE> - -<H3><A NAME="req_orig">Where request_rec structures come from</A></H3> - -Most <CODE>request_rec</CODE> structures are built by reading an HTTP -request from a client, and filling in the fields. However, there are -a few exceptions: - -<UL> - <LI> If the request is to an imagemap, a type map (<EM>i.e.</EM>, a - <CODE>*.var</CODE> file), or a CGI script which returned a - local `Location:', then the resource which the user requested - is going to be ultimately located by some URI other than what - the client originally supplied. In this case, the server does - an <EM>internal redirect</EM>, constructing a new - <CODE>request_rec</CODE> for the new URI, and processing it - almost exactly as if the client had requested the new URI - directly. <P> - - <LI> If some handler signaled an error, and an - <CODE>ErrorDocument</CODE> is in scope, the same internal - redirect machinery comes into play.<P> - - <LI> Finally, a handler occasionally needs to investigate `what - would happen if' some other request were run. For instance, - the directory indexing module needs to know what MIME type - would be assigned to a request for each directory entry, in - order to figure out what icon to use.<P> - - Such handlers can construct a <EM>sub-request</EM>, using the - functions <CODE>ap_sub_req_lookup_file</CODE>, - <CODE>ap_sub_req_lookup_uri</CODE>, and - <CODE>ap_sub_req_method_uri</CODE>; these construct a new - <CODE>request_rec</CODE> structure and processes it as you - would expect, up to but not including the point of actually - sending a response. (These functions skip over the access - checks if the sub-request is for a file in the same directory - as the original request).<P> - - (Server-side includes work by building sub-requests and then - actually invoking the response handler for them, via the - function <CODE>ap_run_sub_req</CODE>). -</UL> - -<H3><A NAME="req_return">Handling requests, declining, and returning error - codes</A></H3> - -As discussed above, each handler, when invoked to handle a particular -<CODE>request_rec</CODE>, has to return an <CODE>int</CODE> to -indicate what happened. That can either be - -<UL> - <LI> OK --- the request was handled successfully. This may or may - not terminate the phase. - <LI> DECLINED --- no erroneous condition exists, but the module - declines to handle the phase; the server tries to find another. - <LI> an HTTP error code, which aborts handling of the request. -</UL> - -Note that if the error code returned is <CODE>REDIRECT</CODE>, then -the module should put a <CODE>Location</CODE> in the request's -<CODE>headers_out</CODE>, to indicate where the client should be -redirected <EM>to</EM>. <P> - -<H3><A NAME="resp_handlers">Special considerations for response - handlers</A></H3> - -Handlers for most phases do their work by simply setting a few fields -in the <CODE>request_rec</CODE> structure (or, in the case of access -checkers, simply by returning the correct error code). However, -response handlers have to actually send a request back to the client. <P> - -They should begin by sending an HTTP response header, using the -function <CODE>ap_send_http_header</CODE>. (You don't have to do -anything special to skip sending the header for HTTP/0.9 requests; the -function figures out on its own that it shouldn't do anything). If -the request is marked <CODE>header_only</CODE>, that's all they should -do; they should return after that, without attempting any further -output. <P> - -Otherwise, they should produce a request body which responds to the -client as appropriate. The primitives for this are <CODE>ap_rputc</CODE> -and <CODE>ap_rprintf</CODE>, for internally generated output, and -<CODE>ap_send_fd</CODE>, to copy the contents of some <CODE>FILE *</CODE> -straight to the client. <P> - -At this point, you should more or less understand the following piece -of code, which is the handler which handles <CODE>GET</CODE> requests -which have no more specific handler; it also shows how conditional -<CODE>GET</CODE>s can be handled, if it's desirable to do so in a -particular response handler --- <CODE>ap_set_last_modified</CODE> checks -against the <CODE>If-modified-since</CODE> value supplied by the -client, if any, and returns an appropriate code (which will, if -nonzero, be USE_LOCAL_COPY). No similar considerations apply for -<CODE>ap_set_content_length</CODE>, but it returns an error code for -symmetry.<P> - -<PRE> -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 = ap_set_content_length (r, r->finfo.st_size)) - || (errstatus = ap_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); - ap_send_http_header (r); - - if (!r->header_only) send_fd (f, r); - ap_pfclose (r->pool, f); - return OK; -} -</PRE> - -Finally, if all of this is too much of a challenge, there are a few -ways out of it. First off, as shown above, a response handler which -has not yet produced any output can simply return an error code, in -which case the server will automatically produce an error response. -Secondly, it can punt to some other handler by invoking -<CODE>ap_internal_redirect</CODE>, which is how the internal redirection -machinery discussed above is invoked. A response handler which has -internally redirected should always return <CODE>OK</CODE>. <P> - -(Invoking <CODE>ap_internal_redirect</CODE> from handlers which are -<EM>not</EM> response handlers will lead to serious confusion). - -<H3><A NAME="auth_handlers">Special considerations for authentication - handlers</A></H3> - -Stuff that should be discussed here in detail: - -<UL> - <LI> Authentication-phase handlers not invoked unless auth is - configured for the directory. - <LI> Common auth configuration stored in the core per-dir - configuration; it has accessors <CODE>ap_auth_type</CODE>, - <CODE>ap_auth_name</CODE>, and <CODE>ap_requires</CODE>. - <LI> Common routines, to handle the protocol end of things, at least - for HTTP basic authentication (<CODE>ap_get_basic_auth_pw</CODE>, - which sets the <CODE>connection->user</CODE> structure field - automatically, and <CODE>ap_note_basic_auth_failure</CODE>, which - arranges for the proper <CODE>WWW-Authenticate:</CODE> header - to be sent back). -</UL> - -<H3><A NAME="log_handlers">Special considerations for logging handlers</A></H3> - -When a request has internally redirected, there is the question of -what to log. Apache handles this by bundling the entire chain of -redirects into a list of <CODE>request_rec</CODE> structures which are -threaded through the <CODE>r->prev</CODE> and <CODE>r->next</CODE> -pointers. The <CODE>request_rec</CODE> which is passed to the logging -handlers in such cases is the one which was originally built for the -initial request from the client; note that the bytes_sent field will -only be correct in the last request in the chain (the one for which a -response was actually sent). - -<H2><A NAME="pools">Resource allocation and resource pools</A></H2> -<P> -One of the problems of writing and designing a server-pool server is -that of preventing leakage, that is, allocating resources (memory, -open files, <EM>etc.</EM>), without subsequently releasing them. The resource -pool machinery is designed to make it easy to prevent this from -happening, by allowing resource to be allocated in such a way that -they are <EM>automatically</EM> released when the server is done with -them. -</P> -<P> -The way this works is as follows: the memory which is allocated, file -opened, <EM>etc.</EM>, to deal with a particular request are tied to a -<EM>resource pool</EM> which is allocated for the request. The pool -is a data structure which itself tracks the resources in question. -</P> -<P> -When the request has been processed, the pool is <EM>cleared</EM>. At -that point, all the memory associated with it is released for reuse, -all files associated with it are closed, and any other clean-up -functions which are associated with the pool are run. When this is -over, we can be confident that all the resource tied to the pool have -been released, and that none of them have leaked. -</P> -<P> -Server restarts, and allocation of memory and resources for per-server -configuration, are handled in a similar way. There is a -<EM>configuration pool</EM>, which keeps track of resources which were -allocated while reading the server configuration files, and handling -the commands therein (for instance, the memory that was allocated for -per-server module configuration, log files and other files that were -opened, and so forth). When the server restarts, and has to reread -the configuration files, the configuration pool is cleared, and so the -memory and file descriptors which were taken up by reading them the -last time are made available for reuse. -</P> -<P> -It should be noted that use of the pool machinery isn't generally -obligatory, except for situations like logging handlers, where you -really need to register cleanups to make sure that the log file gets -closed when the server restarts (this is most easily done by using the -function <CODE><A HREF="#pool-files">ap_pfopen</A></CODE>, which also -arranges for the underlying file descriptor to be closed before any -child processes, such as for CGI scripts, are <CODE>exec</CODE>ed), or -in case you are using the timeout machinery (which isn't yet even -documented here). However, there are two benefits to using it: -resources allocated to a pool never leak (even if you allocate a -scratch string, and just forget about it); also, for memory -allocation, <CODE>ap_palloc</CODE> is generally faster than -<CODE>malloc</CODE>. -</P> -<P> -We begin here by describing how memory is allocated to pools, and then -discuss how other resources are tracked by the resource pool -machinery. -</P> -<H3>Allocation of memory in pools</H3> -<P> -Memory is allocated to pools by calling the function -<CODE>ap_palloc</CODE>, which takes two arguments, one being a pointer to -a resource pool structure, and the other being the amount of memory to -allocate (in <CODE>char</CODE>s). Within handlers for handling -requests, the most common way of getting a resource pool structure is -by looking at the <CODE>pool</CODE> slot of the relevant -<CODE>request_rec</CODE>; hence the repeated appearance of the -following idiom in module code: -</P> -<PRE> -int my_handler(request_rec *r) -{ - struct my_structure *foo; - ... - - foo = (foo *)ap_palloc (r->pool, sizeof(my_structure)); -} -</PRE> -<P> -Note that <EM>there is no <CODE>ap_pfree</CODE></EM> --- -<CODE>ap_palloc</CODE>ed memory is freed only when the associated -resource pool is cleared. This means that <CODE>ap_palloc</CODE> does not -have to do as much accounting as <CODE>malloc()</CODE>; all it does in -the typical case is to round up the size, bump a pointer, and do a -range check. -</P> -<P> -(It also raises the possibility that heavy use of <CODE>ap_palloc</CODE> -could cause a server process to grow excessively large. There are -two ways to deal with this, which are dealt with below; briefly, you -can use <CODE>malloc</CODE>, and try to be sure that all of the memory -gets explicitly <CODE>free</CODE>d, or you can allocate a sub-pool of -the main pool, allocate your memory in the sub-pool, and clear it out -periodically. The latter technique is discussed in the section on -sub-pools below, and is used in the directory-indexing code, in order -to avoid excessive storage allocation when listing directories with -thousands of files). -</P> -<H3>Allocating initialized memory</H3> -<P> -There are functions which allocate initialized memory, and are -frequently useful. The function <CODE>ap_pcalloc</CODE> has the same -interface as <CODE>ap_palloc</CODE>, but clears out the memory it -allocates before it returns it. The function <CODE>ap_pstrdup</CODE> -takes a resource pool and a <CODE>char *</CODE> as arguments, and -allocates memory for a copy of the string the pointer points to, -returning a pointer to the copy. Finally <CODE>ap_pstrcat</CODE> is a -varargs-style function, which takes a pointer to a resource pool, and -at least two <CODE>char *</CODE> arguments, the last of which must be -<CODE>NULL</CODE>. It allocates enough memory to fit copies of each -of the strings, as a unit; for instance: -</P> -<PRE> - ap_pstrcat (r->pool, "foo", "/", "bar", NULL); -</PRE> -<P> -returns a pointer to 8 bytes worth of memory, initialized to -<CODE>"foo/bar"</CODE>. -</P> -<H3><A NAME="pools-used">Commonly-used pools in the Apache Web server</A></H3> -<P> -A pool is really defined by its lifetime more than anything else. There -are some static pools in http_main which are passed to various -non-http_main functions as arguments at opportune times. Here they are: -</P> -<DL COMPACT> - <DT>permanent_pool - </DT> - <DD> - <UL> - <LI>never passed to anything else, this is the ancestor of all pools - </LI> - </UL> - </DD> - <DT>pconf - </DT> - <DD> - <UL> - <LI>subpool of permanent_pool - </LI> - <LI>created at the beginning of a config "cycle"; exists until the - server is terminated or restarts; passed to all config-time - routines, either via cmd->pool, or as the "pool *p" argument on - those which don't take pools - </LI> - <LI>passed to the module init() functions - </LI> - </UL> - </DD> - <DT>ptemp - </DT> - <DD> - <UL> - <LI>sorry I lie, this pool isn't called this currently in 1.3, I - renamed it this in my pthreads development. I'm referring to - the use of ptrans in the parent... contrast this with the later - definition of ptrans in the child. - </LI> - <LI>subpool of permanent_pool - </LI> - <LI>created at the beginning of a config "cycle"; exists until the - end of config parsing; passed to config-time routines <EM>via</EM> - cmd->temp_pool. Somewhat of a "bastard child" because it isn't - available everywhere. Used for temporary scratch space which - may be needed by some config routines but which is deleted at - the end of config. - </LI> - </UL> - </DD> - <DT>pchild - </DT> - <DD> - <UL> - <LI>subpool of permanent_pool - </LI> - <LI>created when a child is spawned (or a thread is created); lives - until that child (thread) is destroyed - </LI> - <LI>passed to the module child_init functions - </LI> - <LI>destruction happens right after the child_exit functions are - called... (which may explain why I think child_exit is redundant - and unneeded) - </LI> - </UL> - </DD> - <DT>ptrans - <DT> - <DD> - <UL> - <LI>should be a subpool of pchild, but currently is a subpool of - permanent_pool, see above - </LI> - <LI>cleared by the child before going into the accept() loop to receive - a connection - </LI> - <LI>used as connection->pool - </LI> - </UL> - </DD> - <DT>r->pool - </DT> - <DD> - <UL> - <LI>for the main request this is a subpool of connection->pool; for - subrequests it is a subpool of the parent request's pool. - </LI> - <LI>exists until the end of the request (<EM>i.e.</EM>, - ap_destroy_sub_req, or - in child_main after process_request has finished) - </LI> - <LI>note that r itself is allocated from r->pool; <EM>i.e.</EM>, - r->pool is - first created and then r is the first thing palloc()d from it - </LI> - </UL> - </DD> -</DL> -<P> -For almost everything folks do, r->pool is the pool to use. But you -can see how other lifetimes, such as pchild, are useful to some -modules... such as modules that need to open a database connection once -per child, and wish to clean it up when the child dies. -</P> -<P> -You can also see how some bugs have manifested themself, such as setting -connection->user to a value from r->pool -- in this case -connection exists -for the lifetime of ptrans, which is longer than r->pool (especially if -r->pool is a subrequest!). So the correct thing to do is to allocate -from connection->pool. -</P> -<P> -And there was another interesting bug in mod_include/mod_cgi. You'll see -in those that they do this test to decide if they should use r->pool -or r->main->pool. In this case the resource that they are registering -for cleanup is a child process. If it were registered in r->pool, -then the code would wait() for the child when the subrequest finishes. -With mod_include this could be any old #include, and the delay can be up -to 3 seconds... and happened quite frequently. Instead the subprocess -is registered in r->main->pool which causes it to be cleaned up when -the entire request is done -- <EM>i.e.</EM>, after the output has been sent to -the client and logging has happened. -</P> -<H3><A NAME="pool-files">Tracking open files, etc.</A></H3> -<P> -As indicated above, resource pools are also used to track other sorts -of resources besides memory. The most common are open files. The -routine which is typically used for this is <CODE>ap_pfopen</CODE>, which -takes a resource pool and two strings as arguments; the strings are -the same as the typical arguments to <CODE>fopen</CODE>, <EM>e.g.</EM>, -</P> -<PRE> - ... - FILE *f = ap_pfopen (r->pool, r->filename, "r"); - - if (f == NULL) { ... } else { ... } -</PRE> -<P> -There is also a <CODE>ap_popenf</CODE> routine, which parallels the -lower-level <CODE>open</CODE> system call. Both of these routines -arrange for the file to be closed when the resource pool in question -is cleared. -</P> -<P> -Unlike the case for memory, there <EM>are</EM> functions to close -files allocated with <CODE>ap_pfopen</CODE>, and <CODE>ap_popenf</CODE>, -namely <CODE>ap_pfclose</CODE> and <CODE>ap_pclosef</CODE>. (This is -because, on many systems, the number of files which a single process -can have open is quite limited). It is important to use these -functions to close files allocated with <CODE>ap_pfopen</CODE> and -<CODE>ap_popenf</CODE>, since to do otherwise could cause fatal errors on -systems such as Linux, which react badly if the same -<CODE>FILE*</CODE> is closed more than once. -</P> -<P> -(Using the <CODE>close</CODE> functions is not mandatory, since the -file will eventually be closed regardless, but you should consider it -in cases where your module is opening, or could open, a lot of files). -</P> -<H3>Other sorts of resources --- cleanup functions</H3> -<BLOCKQUOTE> -More text goes here. Describe the the cleanup primitives in terms of -which the file stuff is implemented; also, <CODE>spawn_process</CODE>. -</BLOCKQUOTE> -<P> -Pool cleanups live until clear_pool() is called: clear_pool(a) recursively -calls destroy_pool() on all subpools of a; then calls all the cleanups for a; -then releases all the memory for a. destroy_pool(a) calls clear_pool(a) -and then releases the pool structure itself. <EM>i.e.</EM>, clear_pool(a) doesn't -delete a, it just frees up all the resources and you can start using it -again immediately. -</P> -<H3>Fine control --- creating and dealing with sub-pools, with a note -on sub-requests</H3> - -On rare occasions, too-free use of <CODE>ap_palloc()</CODE> and the -associated primitives may result in undesirably profligate resource -allocation. You can deal with such a case by creating a -<EM>sub-pool</EM>, allocating within the sub-pool rather than the main -pool, and clearing or destroying the sub-pool, which releases the -resources which were associated with it. (This really <EM>is</EM> a -rare situation; the only case in which it comes up in the standard -module set is in case of listing directories, and then only with -<EM>very</EM> large directories. Unnecessary use of the primitives -discussed here can hair up your code quite a bit, with very little -gain). <P> - -The primitive for creating a sub-pool is <CODE>ap_make_sub_pool</CODE>, -which takes another pool (the parent pool) as an argument. When the -main pool is cleared, the sub-pool will be destroyed. The sub-pool -may also be cleared or destroyed at any time, by calling the functions -<CODE>ap_clear_pool</CODE> and <CODE>ap_destroy_pool</CODE>, respectively. -(The difference is that <CODE>ap_clear_pool</CODE> frees resources -associated with the pool, while <CODE>ap_destroy_pool</CODE> also -deallocates the pool itself. In the former case, you can allocate new -resources within the pool, and clear it again, and so forth; in the -latter case, it is simply gone). <P> - -One final note --- sub-requests have their own resource pools, which -are sub-pools of the resource pool for the main request. The polite -way to reclaim the resources associated with a sub request which you -have allocated (using the <CODE>ap_sub_req_...</CODE> functions) -is <CODE>ap_destroy_sub_req</CODE>, which frees the resource pool. -Before calling this function, be sure to copy anything that you care -about which might be allocated in the sub-request's resource pool into -someplace a little less volatile (for instance, the filename in its -<CODE>request_rec</CODE> structure). <P> - -(Again, under most circumstances, you shouldn't feel obliged to call -this function; only 2K of memory or so are allocated for a typical sub -request, and it will be freed anyway when the main request pool is -cleared. It is only when you are allocating many, many sub-requests -for a single main request that you should seriously consider the -<CODE>ap_destroy_...</CODE> functions). - -<H2><A NAME="config">Configuration, commands and the like</A></H2> - -One of the design goals for this server was to maintain external -compatibility with the NCSA 1.3 server --- that is, to read the same -configuration files, to process all the directives therein correctly, -and in general to be a drop-in replacement for NCSA. On the other -hand, another design goal was to move as much of the server's -functionality into modules which have as little as possible to do with -the monolithic server core. The only way to reconcile these goals is -to move the handling of most commands from the central server into the -modules. <P> - -However, just giving the modules command tables is not enough to -divorce them completely from the server core. The server has to -remember the commands in order to act on them later. That involves -maintaining data which is private to the modules, and which can be -either per-server, or per-directory. Most things are per-directory, -including in particular access control and authorization information, -but also information on how to determine file types from suffixes, -which can be modified by <CODE>AddType</CODE> and -<CODE>DefaultType</CODE> directives, and so forth. In general, the -governing philosophy is that anything which <EM>can</EM> be made -configurable by directory should be; per-server information is -generally used in the standard set of modules for information like -<CODE>Alias</CODE>es and <CODE>Redirect</CODE>s which come into play -before the request is tied to a particular place in the underlying -file system. <P> - -Another requirement for emulating the NCSA server is being able to -handle the per-directory configuration files, generally called -<CODE>.htaccess</CODE> files, though even in the NCSA server they can -contain directives which have nothing at all to do with access -control. Accordingly, after URI -> filename translation, but before -performing any other phase, the server walks down the directory -hierarchy of the underlying filesystem, following the translated -pathname, to read any <CODE>.htaccess</CODE> files which might be -present. The information which is read in then has to be -<EM>merged</EM> with the applicable information from the server's own -config files (either from the <CODE><Directory></CODE> sections -in <CODE>access.conf</CODE>, or from defaults in -<CODE>srm.conf</CODE>, which actually behaves for most purposes almost -exactly like <CODE><Directory /></CODE>).<P> - -Finally, after having served a request which involved reading -<CODE>.htaccess</CODE> files, we need to discard the storage allocated -for handling them. That is solved the same way it is solved wherever -else similar problems come up, by tying those structures to the -per-transaction resource pool. <P> - -<H3><A NAME="per-dir">Per-directory configuration structures</A></H3> - -Let's look out how all of this plays out in <CODE>mod_mime.c</CODE>, -which defines the file typing handler which emulates the NCSA server's -behavior of determining file types from suffixes. What we'll be -looking at, here, is the code which implements the -<CODE>AddType</CODE> and <CODE>AddEncoding</CODE> commands. These -commands can appear in <CODE>.htaccess</CODE> files, so they must be -handled in the module's private per-directory data, which in fact, -consists of two separate <CODE>table</CODE>s for MIME types and -encoding information, and is declared as follows: - -<PRE> -typedef struct { - table *forced_types; /* Additional AddTyped stuff */ - table *encoding_types; /* Added with AddEncoding... */ -} mime_dir_config; -</PRE> - -When the server is reading a configuration file, or -<CODE><Directory></CODE> section, which includes one of the MIME -module's commands, it needs to create a <CODE>mime_dir_config</CODE> -structure, so those commands have something to act on. It does this -by invoking the function it finds in the module's `create per-dir -config slot', with two arguments: the name of the directory to which -this configuration information applies (or <CODE>NULL</CODE> for -<CODE>srm.conf</CODE>), and a pointer to a resource pool in which the -allocation should happen. <P> - -(If we are reading a <CODE>.htaccess</CODE> file, that resource pool -is the per-request resource pool for the request; otherwise it is a -resource pool which is used for configuration data, and cleared on -restarts. Either way, it is important for the structure being created -to vanish when the pool is cleared, by registering a cleanup on the -pool if necessary). <P> - -For the MIME module, the per-dir config creation function just -<CODE>ap_palloc</CODE>s the structure above, and a creates a couple of -<CODE>table</CODE>s to fill it. That looks like this: - -<PRE> -void *create_mime_dir_config (pool *p, char *dummy) -{ - mime_dir_config *new = - (mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config)); - - new->forced_types = ap_make_table (p, 4); - new->encoding_types = ap_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 *)ap_palloc (p, sizeof(mime_dir_config)); - - new->forced_types = ap_overlay_tables (p, subdir->forced_types, - parent_dir->forced_types); - new->encoding_types = ap_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 (<EM>e.g.</EM>, for the -includes module, whose per-directory configuration information -consists solely of the state of the <CODE>XBITHACK</CODE>), and for -those modules, you can just not declare one, and leave the -corresponding structure slot in the module itself <CODE>NULL</CODE>.<P> - -<H3><A NAME="commands">Command handling</A></H3> - -Now that we have these structures, we need to be able to figure out -how to fill them. That involves processing the actual -<CODE>AddType</CODE> and <CODE>AddEncoding</CODE> commands. To find -commands, the server looks in the module's <CODE>command table</CODE>. -That table contains information on how many arguments the commands -take, and in what formats, where it is permitted, and so forth. That -information is sufficient to allow the server to invoke most -command-handling functions with pre-parsed arguments. Without further -ado, let's look at the <CODE>AddType</CODE> command handler, which -looks like this (the <CODE>AddEncoding</CODE> command looks basically -the same, and won't be shown here): - -<PRE> -char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext) -{ - if (*ext == '.') ++ext; - ap_table_set (m->forced_types, ext, ct); - return NULL; -} -</PRE> - -This command handler is unusually simple. As you can see, it takes -four arguments, two of which are pre-parsed arguments, the third being -the per-directory configuration structure for the module in question, -and the fourth being a pointer to a <CODE>cmd_parms</CODE> structure. -That structure contains a bunch of arguments which are frequently of -use to some, but not all, commands, including a resource pool (from -which memory can be allocated, and to which cleanups should be tied), -and the (virtual) server being configured, from which the module's -per-server configuration data can be obtained if required.<P> - -Another way in which this particular command handler is unusually -simple is that there are no error conditions which it can encounter. -If there were, it could return an error message instead of -<CODE>NULL</CODE>; this causes an error to be printed out on the -server's <CODE>stderr</CODE>, followed by a quick exit, if it is in -the main config files; for a <CODE>.htaccess</CODE> file, the syntax -error is logged in the server error log (along with an indication of -where it came from), and the request is bounced with a server error -response (HTTP error status, code 500). <P> - -The MIME module's command table has entries for these commands, which -look like this: - -<PRE> -command_rec mime_cmds[] = { -{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2, - "a mime type followed by a file extension" }, -{ "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2, - "an encoding (<EM>e.g.</EM>, gzip), followed by a file extension" }, -{ 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>ap_get_module_config</CODE> function. - -<PRE> -int find_ct(request_rec *r) -{ - int i; - char *fn = ap_pstrdup (r->pool, r->filename); - mime_dir_config *conf = (mime_dir_config *) - ap_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=ap_rind(fn,'.')) < 0) return DECLINED; - ++i; - - if ((type = ap_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=ap_rind(fn,'.')) < 0) return OK; - ++i; - } - - if ((type = ap_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, <EM>etc</EM>.</A></H3> - -The basic ideas behind per-server module configuration are basically -the same as those for per-directory configuration; there is a creation -function and a merge function, the latter being invoked where a -virtual server has partially overridden the base server configuration, -and a combined structure must be computed. (As with per-directory -configuration, the default if no merge function is specified, and a -module is configured in some virtual server, is that the base -configuration is simply ignored). <P> - -The only substantial difference is that when a command needs to -configure the per-server private module data, it needs to go to the -<CODE>cmd_parms</CODE> data to get at it. Here's an example, from the -alias module, which also indicates how a syntax error can be returned -(note that the per-directory configuration argument to the command -handler is declared as a dummy, since the module doesn't actually have -per-directory config data): - -<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 *) - ap_get_module_config(s->module_config,&alias_module); - alias_entry *new = ap_push_array (conf->redirects); - - if (!ap_is_url (url)) return "Redirect to non-URL"; - - new->fake = f; new->real = url; - return NULL; -} -</PRE> -<!--#include virtual="footer.html" --> -</BODY></HTML> diff --git a/docs/manual/misc/FAQ-A.html b/docs/manual/misc/FAQ-A.html deleted file mode 100644 index bf436858de..0000000000 --- a/docs/manual/misc/FAQ-A.html +++ /dev/null @@ -1,279 +0,0 @@ -<!--#if expr="$FAQMASTER" --> - <!--#set var="STANDALONE" value="" --> - <!--#set var="INCLUDED" value="YES" --> - <!--#if expr="$QUERY_STRING = TOC" --> - <!--#set var="TOC" value="YES" --> - <!--#set var="CONTENT" value="" --> - <!--#else --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="YES" --> - <!--#endif --> -<!--#else --> - <!--#set var="STANDALONE" value="YES" --> - <!--#set var="INCLUDED" value="" --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="" --> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Server Frequently Asked Questions</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> - <P> - $Revision: 1.2 $ ($Date: 1999/07/03 22:12:49 $) - </P> - <P> - The latest version of this FAQ is always available from the main - Apache web site, at - <<A - HREF="http://www.apache.org/docs/misc/FAQ.html" - REL="Help" - ><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>>. - </P> -<!-- Notes about changes: --> -<!-- - If adding a relative link to another part of the --> -<!-- documentation, *do* include the ".html" portion. There's a --> -<!-- good chance that the user will be reading the documentation --> -<!-- on his own system, which may not be configured for --> -<!-- multiviews. --> -<!-- - When adding items, make sure they're put in the right place --> -<!-- - verify that the numbering matches up. --> -<!-- - *Don't* use <PRE></PRE> blocks - they don't appear --> -<!-- correctly in a reliable way when this is converted to text --> -<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> --> -<!-- blocks inside a <P></P> instead. This is necessary to get --> -<!-- the horizontal and vertical indenting right. --> -<!-- - Don't forget to include an HR tag after the last /P tag --> -<!-- but before the /LI in an item. --> - <P> - If you are reading a text-only version of this FAQ, you may find numbers - enclosed in brackets (such as "[12]"). These refer to the list of - reference URLs to be found at the end of the document. These references - do not appear, and are not needed, for the hypertext version. - </P> - <H2>The Questions</H2> -<OL TYPE="A"> -<!--#endif --> -<!--#if expr="$TOC || $STANDALONE" --> - <LI VALUE="1"><STRONG>Background</STRONG> - <OL> - <LI><A HREF="#what">What is Apache?</A> - </LI> - <LI><A HREF="#why">Why was Apache created?</A> - </LI> - <LI><A HREF="#relate">How does The Apache Group's work relate to - other servers?</A> - </LI> - <LI><A HREF="#name">Why the name "Apache"?</A> - </LI> - <LI><A HREF="#compare">OK, so how does Apache compare to other servers?</A> - </LI> - <LI><A HREF="#tested">How thoroughly tested is Apache?</A> - </LI> - <LI><A HREF="#future">What are the future plans for Apache?</A> - </LI> - <LI><A HREF="#support">Whom do I contact for support?</A> - </LI> - <LI><A HREF="#more">Is there any more information on Apache?</A> - </LI> - <LI><A HREF="#where">Where can I get Apache?</A> - </LI> - </OL> - </LI> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -</OL> - -<HR> - - <H2>The Answers</H2> -<!--#endif --> -<!--#if expr="! $TOC" --> - <H3>A. Background</H3> -<OL> - <LI><A NAME="what"> - <STRONG>What is Apache?</STRONG> - </A> - <P> - Apache was originally based on code and ideas found in the most - popular HTTP server of the time.. NCSA httpd 1.3 (early 1995). It has - since evolved into a far superior system which can rival (and probably - surpass) almost any other UNIX based HTTP server in terms of functionality, - efficiency and speed. - </P> - <P> - Since it began, it has been completely rewritten, and includes many new - features. Apache is, as of January 1997, the most popular WWW server on - the Internet, according to the - <A HREF="http://www.netcraft.com/Survey/">Netcraft Survey</A>. - </P> - <HR> - </LI> - - <LI><A NAME="why"> - <STRONG>Why was Apache created?</STRONG> - </A> - <P> - To address the concerns of a group of WWW providers and part-time httpd - programmers that httpd didn't behave as they wanted it to behave. - Apache is an entirely volunteer effort, completely funded by its - members, not by commercial sales. - </P> - <HR> - </LI> - - <LI><A NAME="relate"> - <STRONG>How does The Apache Group's work relate to other - server efforts, such as NCSA's?</STRONG> - </A> - <P> - We, of course, owe a great debt to NCSA and their programmers for - making the server Apache was based on. We now, however, have our own - server, and our project is mostly our own. The Apache Project is an - entirely independent venture. - </P> - <HR> - </LI> - - <LI><A NAME="name"> - <STRONG>Why the name "Apache"?</STRONG> - </A> - <P> - A cute name which stuck. Apache is "<STRONG>A - PA</STRONG>t<STRONG>CH</STRONG>y server". It was - based on some existing code and a series of "patch files". - </P> - <HR> - </LI> - - <LI><A NAME="compare"> - <STRONG>OK, so how does Apache compare to other servers?</STRONG> - </A> - <P> - For an independent assessment, see - <A HREF="http://webcompare.internet.com/chart.html">Web Compare</A>'s - comparison chart. - </P> - <P> - Apache has been shown to be substantially faster than many other - free servers. Although certain commercial servers have claimed to - surpass Apache's speed (it has not been demonstrated that any of these - "benchmarks" are a good way of measuring WWW server speed at any - rate), we feel that it is better to have a mostly-fast free server - than an extremely-fast server that costs thousands of dollars. Apache - is run on sites that get millions of hits per day, and they have - experienced no performance difficulties. - </P> - <HR> - </LI> - - <LI><A NAME="tested"> - <STRONG>How thoroughly tested is Apache?</STRONG> - </A> - <P> - Apache is run on over 3 million Internet servers (as of June 1999). It has - been tested thoroughly by both developers and users. The Apache Group - maintains rigorous standards before releasing new versions of their - server, and our server runs without a hitch on over one half of all - WWW servers available on the Internet. When bugs do show up, we - release patches and new versions as soon as they are available. - </P> - <P> - The Apache project's web site includes a page with a partial list of - <A HREF="http://www.apache.org/info/apache_users.html">sites running - Apache</A>. - </P> - <HR> - </LI> - - <LI><A NAME="future"> - <STRONG>What are the future plans for Apache?</STRONG> - </A> - <P> - <UL> - <LI>to continue to be an "open source" no-charge-for-use HTTP server, - </LI> - <LI>to keep up with advances in HTTP protocol and web developments in - general, - </LI> - <LI>to collect suggestions for fixes/improvements from its users, - </LI> - <LI>to respond to needs of large volume providers as well as - occasional users. - </LI> - </UL> - <P></P> - <HR> - </LI> - - <LI><A NAME="support"> - <STRONG>Whom do I contact for support?</STRONG> - </A> - <P> - There is no official support for Apache. None of the developers want to - be swamped by a flood of trivial questions that can be resolved elsewhere. - Bug reports and suggestions should be sent <EM>via</EM> - <A HREF="http://www.apache.org/bug_report.html">the bug report page</A>. - Other questions should be directed to the - <A HREF="news:comp.infosystems.www.servers.unix" - >comp.infosystems.www.servers.unix</A> or <A HREF= - "news:comp.infosystems.www.servers.ms-windows" - >comp.infosystems.www.servers.ms-windows</A> - newsgroup (as appropriate for the platform you use), where some of the - Apache team lurk, in the company of many other httpd gurus who - should be able to help. - </P> - <P> - Commercial support for Apache is, however, available from a number - of third parties. - </P> - <HR> - </LI> - - <LI><A NAME="more"> - <STRONG>Is there any more information available on - Apache?</STRONG> - </A> - <P> - Indeed there is. See the main - <A HREF="http://www.apache.org/">Apache web site</A>. - There is also a regular electronic publication called - <A HREF="http://www.apacheweek.com/" REL="Help"><CITE>Apache Week</CITE></A> - available. Links to relevant <CITE>Apache Week</CITE> articles are - included below where appropriate. There are also some - <A HREF="http://www.apache.org/info/apache_books.html" - >Apache-specific books</A> available. - </P> - <HR> - </LI> - - <LI><A NAME="where"> - <STRONG>Where can I get Apache?</STRONG> - </A> - <P> - You can find out how to download the source for Apache at the - project's - <A HREF="http://www.apache.org/">main web page</A>. - </P> - <HR> - </LI> -</OL> -<!--#endif --> -<!--#if expr="$STANDALONE" --> - <!-- Don't forget to add HR tags at the end of each list item.. --> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> -<!--#endif --> diff --git a/docs/manual/misc/FAQ-B.html b/docs/manual/misc/FAQ-B.html deleted file mode 100644 index 27dbad618f..0000000000 --- a/docs/manual/misc/FAQ-B.html +++ /dev/null @@ -1,378 +0,0 @@ -<!--#if expr="$FAQMASTER" --> - <!--#set var="STANDALONE" value="" --> - <!--#set var="INCLUDED" value="YES" --> - <!--#if expr="$QUERY_STRING = TOC" --> - <!--#set var="TOC" value="YES" --> - <!--#set var="CONTENT" value="" --> - <!--#else --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="YES" --> - <!--#endif --> -<!--#else --> - <!--#set var="STANDALONE" value="YES" --> - <!--#set var="INCLUDED" value="" --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="" --> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Server Frequently Asked Questions</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> - <P> - $Revision: 1.1 $ ($Date: 1999/06/24 15:02:51 $) - </P> - <P> - The latest version of this FAQ is always available from the main - Apache web site, at - <<A - HREF="http://www.apache.org/docs/misc/FAQ.html" - REL="Help" - ><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>>. - </P> -<!-- Notes about changes: --> -<!-- - If adding a relative link to another part of the --> -<!-- documentation, *do* include the ".html" portion. There's a --> -<!-- good chance that the user will be reading the documentation --> -<!-- on his own system, which may not be configured for --> -<!-- multiviews. --> -<!-- - When adding items, make sure they're put in the right place --> -<!-- - verify that the numbering matches up. --> -<!-- - *Don't* use <PRE></PRE> blocks - they don't appear --> -<!-- correctly in a reliable way when this is converted to text --> -<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> --> -<!-- blocks inside a <P></P> instead. This is necessary to get --> -<!-- the horizontal and vertical indenting right. --> -<!-- - Don't forget to include an HR tag after the last /P tag --> -<!-- but before the /LI in an item. --> - <P> - If you are reading a text-only version of this FAQ, you may find numbers - enclosed in brackets (such as "[12]"). These refer to the list of - reference URLs to be found at the end of the document. These references - do not appear, and are not needed, for the hypertext version. - </P> - <H2>The Questions</H2> -<OL TYPE="A"> -<!--#endif --> -<!--#if expr="$TOC || $STANDALONE" --> - <LI value="2"><STRONG>General Technical Questions</STRONG> - <OL> - <LI><A HREF="#what2do">"Why can't I ...? Why won't ... - work?" What to do in case of problems</A> - </LI> - <LI><A HREF="#compatible">How compatible is Apache with my existing - NCSA 1.3 setup?</A> - </LI> - <LI><A HREF="#year2000">Is Apache Year 2000 compliant?</A> - </LI> - <LI><A HREF="#submit_patch">How do I submit a patch to the Apache Group?</A> - </LI> - <LI><A HREF="#domination">Why has Apache stolen my favourite site's - Internet address?</A> - </LI> - <LI><A HREF="#apspam">Why am I getting spam mail from the Apache site?</A> - </LI> - <LI><A HREF="#redist">May I include the Apache software on a CD or other - package I'm distributing?</A> - </LI> - <LI><A HREF="#zoom">What's the best hardware/operating system/... How do - I get the most out of my Apache Web server?</A> - </LI> - <LI><A HREF="#regex">What are "regular expressions"?</A> - </LI> - </OL> - </LI> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -</OL> - -<HR> - - <H2>The Answers</H2> -<!--#endif --> -<!--#if expr="! $TOC" --> - - <H3>B. General Technical Questions</H3> -<OL> - - <LI><A NAME="what2do"> - <STRONG>"Why can't I ...? Why won't ... work?" What to - do in case of problems</STRONG> - </A> - <P> - If you are having trouble with your Apache server software, you should - take the following steps: - </P> - <OL> - <LI><STRONG>Check the errorlog!</STRONG> - <P> - Apache tries to be helpful when it encounters a problem. In many - cases, it will provide some details by writing one or messages to - the server error log. Sometimes this is enough for you to diagnose - & fix the problem yourself (such as file permissions or the like). - The default location of the error log is - <SAMP>/usr/local/apache/logs/error_log</SAMP>, but see the - <A HREF="../mod/core.html#errorlog"><SAMP>ErrorLog</SAMP></A> - directive in your config files for the location on your server. - </P> - </LI> - <LI><STRONG>Check the - <A HREF="http://www.apache.org/docs/misc/FAQ.html">FAQ</A>!</STRONG> - <P> - The latest version of the Apache Frequently-Asked Questions list can - always be found at the main Apache web site. - </P> - </LI> - <LI><STRONG>Check the Apache bug database</STRONG> - <P> - Most problems that get reported to The Apache Group are recorded in - the - <A HREF="http://bugs.apache.org/">bug database</A>. - <EM><STRONG>Please</STRONG> check the existing reports, open - <STRONG>and</STRONG> closed, before adding one.</EM> If you find - that your issue has already been reported, please <EM>don't</EM> add - a "me, too" report. If the original report isn't closed - yet, we suggest that you check it periodically. You might also - consider contacting the original submitter, because there may be an - email exchange going on about the issue that isn't getting recorded - in the database. - </P> - </LI> - <LI><STRONG>Ask in the <SAMP>comp.infosystems.www.servers.unix</SAMP> - or <SAMP>comp.infosystems.www.servers.ms-windows</SAMP> USENET - newsgroup (as appropriate for the platform you use).</STRONG> - <P> - A lot of common problems never make it to the bug database because - there's already high Q&A traffic about them in the - <A HREF="news:comp.infosystems.www.servers.unix" - ><SAMP>comp.infosystems.www.servers.unix</SAMP></A> - newsgroup. Many Apache users, and some of the developers, can be - found roaming its virtual halls, so it is suggested that you seek - wisdom there. The chances are good that you'll get a faster answer - there than from the bug database, even if you <EM>don't</EM> see - your question already posted. - </P> - </LI> - <LI><STRONG>If all else fails, report the problem in the bug - database</STRONG> - <P> - If you've gone through those steps above that are appropriate and - have obtained no relief, then please <EM>do</EM> let The Apache - Group know about the problem by - <A HREF="http://www.apache.org/bug_report.html">logging a bug report</A>. - </P> - <P> - If your problem involves the server crashing and generating a core - dump, please include a backtrace (if possible). As an example, - </P> - <P> - <DL> - <DD><CODE># cd <EM>ServerRoot</EM><BR> - # dbx httpd core<BR> - (dbx) where</CODE> - </DD> - </DL> - <P></P> - <P> - (Substitute the appropriate locations for your - <SAMP>ServerRoot</SAMP> and your <SAMP>httpd</SAMP> and - <SAMP>core</SAMP> files. You may have to use <CODE>gdb</CODE> - instead of <CODE>dbx</CODE>.) - </P> - </LI> - </OL> - <HR> - </LI> - - <LI><A NAME="compatible"> - <STRONG>How compatible is Apache with my existing NCSA 1.3 - setup?</STRONG> - </A> - <P> - Apache attempts to offer all the features and configuration options - of NCSA httpd 1.3, as well as many of the additional features found in - NCSA httpd 1.4 and NCSA httpd 1.5. - </P> - <P> - NCSA httpd appears to be moving toward adding experimental features - which are not generally required at the moment. Some of the experiments - will succeed while others will inevitably be dropped. The Apache - philosophy is to add what's needed as and when it is needed. - </P> - <P> - Friendly interaction between Apache and NCSA developers should ensure - that fundamental feature enhancements stay consistent between the two - servers for the foreseeable future. - </P> - <HR> - </LI> - - <LI><A NAME="year2000"> - <STRONG>Is Apache Year 2000 compliant?</STRONG> - </A> - <P> - Yes, Apache is Year 2000 compliant. - </P> - <P> - Apache internally never stores years as two digits. - On the HTTP protocol level RFC1123-style addresses are generated - which is the only format a HTTP/1.1-compliant server should - generate. To be compatible with older applications Apache - recognizes ANSI C's <CODE>asctime()</CODE> and - RFC850-/RFC1036-style date formats, too. - The <CODE>asctime()</CODE> format uses four-digit years, - but the RFC850 and RFC1036 date formats only define a two-digit year. - If Apache sees such a date with a value less than 70 it assumes that - the century is <SAMP>20</SAMP> rather than <SAMP>19</SAMP>. - </P> - <P> - Although Apache is Year 2000 compliant, you may still get problems - if the underlying OS has problems with dates past year 2000 - (<EM>e.g.</EM>, OS calls which accept or return year numbers). - Most (UNIX) systems store dates internally as signed 32-bit integers - which contain the number of seconds since 1<SUP>st</SUP> January 1970, so - the magic boundary to worry about is the year 2038 and not 2000. - But modern operating systems shouldn't cause any trouble - at all. - </P> - <P> - Users of Apache 1.2.x should upgrade to a current version of Apache 1.3 - (see <A HREF="../new_features_1_3.html#misc">year-2000 improvements in - Apache 1.3</A> for details). - </P> - <HR> - </LI> - - <LI><A NAME="submit_patch"> - <STRONG>How do I submit a patch to the Apache Group?</STRONG></A> - <P> - The Apache Group encourages patches from outside developers. There - are 2 main "types" of patches: small bugfixes and general - improvements. Bugfixes should be submitting using the Apache <A - HREF="http://www.apache.org/bug_report.html">bug report page</A>. - Improvements, modifications, and additions should follow the - instructions below. - </P> - <P> - In general, the first course of action is to be a member of the - <SAMP>new-httpd@apache.org</SAMP> mailing list. This indicates to - the Group that you are closely following the latest Apache - developments. Your patch file should be generated using either - '<CODE>diff -c</CODE>' or '<CODE>diff -u</CODE>' against - the latest CVS tree. To submit your patch, send email to - <SAMP>new-httpd@apache.org</SAMP> with a <SAMP>Subject:</SAMP> line - that starts with <SAMP>[PATCH]</SAMP> and includes a general - description of the patch. In the body of the message, the patch - should be clearly described and then included at the end of the - message. If the patch-file is long, you can note a URL to the file - instead of the file itself. Use of MIME enclosures/attachments - should be avoided. - </P> - <P> - Be prepared to respond to any questions about your patches and - possibly defend your code. If your patch results in a lot of - discussion, you may be asked to submit an updated patch that - incorporate all changes and suggestions. - </P> - <HR> - </LI> - - <LI><A NAME="domination"><STRONG>Why has Apache stolen my favourite site's - Internet address?</STRONG></A> - <P> - The simple answer is: "It hasn't." This misconception is usually - caused by the site in question having migrated to the Apache Web - server software, but not having migrated the site's content yet. When - Apache is installed, the default page that gets installed tells the - Webmaster the installation was successful. The expectation is that - this default page will be replaced with the site's real content. - If it doesn't, complain to the Webmaster, not to the Apache project -- - we just make the software and aren't responsible for what people - do (or don't do) with it. - </P> - <HR> - </LI> - - <LI><A NAME="apspam"><STRONG>Why am I getting spam mail from the - Apache site?</STRONG></A> - <P> - The short answer is: "You aren't." Usually when someone thinks the - Apache site is originating spam, it's because they've traced the - spam to a Web site, and the Web site says it's using Apache. See the - <A HREF="#domination">previous FAQ entry</A> for more details on this - phenomenon. - </P> - <P> - No marketing spam originates from the Apache site. The only mail - that comes from the site goes only to addresses that have been - <EM>requested</EM> to receive the mail. - </P> - <HR> - </LI> - - <LI><A NAME="redist"><STRONG>May I include the Apache software on a - CD or other package I'm distributing?</STRONG></A> - <P> - The detailed answer to this question can be found in the - Apache license, which is included in the Apache distribution in - the file <CODE>LICENSE</CODE>. You can also find it on the Web at - <SAMP><<A HREF="http://www.apache.org/LICENSE.txt" - >http://www.apache.org/LICENSE.txt</A>></SAMP>. - </P> - <HR> - </LI> - - <LI><A NAME="zoom"> - <STRONG>What's the best hardware/operating system/... How do - I get the most out of my Apache Web server?</STRONG> - </A> - <P> - Check out Dean Gaudet's - <A HREF="http://www.apache.org/docs/misc/perf-tuning.html" - >performance tuning page</A>. - </P> - <HR> - </LI> - - <LI><A NAME="regex"> - <STRONG>What are "regular expressions"?</STRONG></A> - <P> - Regular expressions are a way of describing a pattern - for example, "all - the words that begin with the letter A" or "every 10-digit phone number" - or even "Every sentence with two commas in it, and no capital letter Q". - Regular expressions (aka "regexp"s) are useful in Apache because they - let you apply certain attributes against collections of files or resources - in very flexible ways - for example, all .gif and .jpg files under - any "images" directory could be written as /.*\/images\/.*[jpg|gif]/. - </P> - <P> - The best overview around is probably the one which comes with Perl. - We implement a simple subset of Perl's regexp support, but it's - still a good way to learn what they mean. You can start by going - to the <A - HREF="http://www.perl.com/CPAN-local/doc/manual/html/pod/perlre.html#Version_8_Regular_Expresions" - >CPAN page on regular expressions</A>, and branching out from - there. - </P> - <HR> - </LI> -</OL> -<!--#endif --> -<!--#if expr="$STANDALONE" --> - <!-- Don't forget to add HR tags at the end of each list item.. --> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> -<!--#endif --> diff --git a/docs/manual/misc/FAQ-C.html b/docs/manual/misc/FAQ-C.html deleted file mode 100644 index 3f226c08f8..0000000000 --- a/docs/manual/misc/FAQ-C.html +++ /dev/null @@ -1,273 +0,0 @@ -<!--#if expr="$FAQMASTER" --> - <!--#set var="STANDALONE" value="" --> - <!--#set var="INCLUDED" value="YES" --> - <!--#if expr="$QUERY_STRING = TOC" --> - <!--#set var="TOC" value="YES" --> - <!--#set var="CONTENT" value="" --> - <!--#else --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="YES" --> - <!--#endif --> -<!--#else --> - <!--#set var="STANDALONE" value="YES" --> - <!--#set var="INCLUDED" value="" --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="" --> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Server Frequently Asked Questions</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> - <P> - $Revision: 1.1 $ ($Date: 1999/06/24 15:02:51 $) - </P> - <P> - The latest version of this FAQ is always available from the main - Apache web site, at - <<A - HREF="http://www.apache.org/docs/misc/FAQ.html" - REL="Help" - ><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>>. - </P> -<!-- Notes about changes: --> -<!-- - If adding a relative link to another part of the --> -<!-- documentation, *do* include the ".html" portion. There's a --> -<!-- good chance that the user will be reading the documentation --> -<!-- on his own system, which may not be configured for --> -<!-- multiviews. --> -<!-- - When adding items, make sure they're put in the right place --> -<!-- - verify that the numbering matches up. --> -<!-- - *Don't* use <PRE></PRE> blocks - they don't appear --> -<!-- correctly in a reliable way when this is converted to text --> -<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> --> -<!-- blocks inside a <P></P> instead. This is necessary to get --> -<!-- the horizontal and vertical indenting right. --> -<!-- - Don't forget to include an HR tag after the last /P tag --> -<!-- but before the /LI in an item. --> - <P> - If you are reading a text-only version of this FAQ, you may find numbers - enclosed in brackets (such as "[12]"). These refer to the list of - reference URLs to be found at the end of the document. These references - do not appear, and are not needed, for the hypertext version. - </P> - <H2>The Questions</H2> -<OL TYPE="A"> -<!--#endif --> -<!--#if expr="$TOC || $STANDALONE" --> - <LI VALUE="3"><STRONG>Building Apache</STRONG> - <OL> - <LI><A HREF="#bind8.1">Why do I get an error about an undefined - reference to "<SAMP>__inet_ntoa</SAMP>" or other - <SAMP>__inet_*</SAMP> symbols?</A> - </LI> - <LI><A HREF="#cantbuild">Why won't Apache compile with my - system's <SAMP>cc</SAMP>?</A> - </LI> - <LI><A HREF="#linuxiovec">Why do I get complaints about redefinition - of "<CODE>struct iovec</CODE>" when compiling under Linux?</A> - </LI> - <LI><A HREF="#broken-gcc">I'm using gcc and I get some compilation errors, - what is wrong?</A> - </LI> - <LI><A HREF="#glibc-crypt">I'm using RedHat Linux 5.0, or some other - <SAMP>glibc</SAMP>-based Linux system, and I get errors with the - <CODE>crypt</CODE> function when I attempt to build Apache 1.2.</A> - </LI> - </OL> - </LI> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -</OL> - -<HR> - - <H2>The Answers</H2> -<!--#endif --> -<!--#if expr="! $TOC" --> - - <H3>C. Building Apache</H3> -<OL> - - <LI><A NAME="bind8.1"> - <STRONG>Why do I get an error about an undefined reference to - "<SAMP>__inet_ntoa</SAMP>" or other - <SAMP>__inet_*</SAMP> symbols?</STRONG> - </A> - <P> - If you have installed <A HREF="http://www.isc.org/bind.html">BIND-8</A> - then this is normally due to a conflict between your include files - and your libraries. BIND-8 installs its include files and libraries - <CODE>/usr/local/include/</CODE> and <CODE>/usr/local/lib/</CODE>, while - the resolver that comes with your system is probably installed in - <CODE>/usr/include/</CODE> and <CODE>/usr/lib/</CODE>. If - your system uses the header files in <CODE>/usr/local/include/</CODE> - before those in <CODE>/usr/include/</CODE> but you do not use the new - resolver library, then the two versions will conflict. - </P> - <P> - To resolve this, you can either make sure you use the include files - and libraries that came with your system or make sure to use the - new include files and libraries. Adding <CODE>-lbind</CODE> to the - <CODE>EXTRA_LDFLAGS</CODE> line in your <SAMP>Configuration</SAMP> - file, then re-running <SAMP>Configure</SAMP>, should resolve the - problem. (Apache versions 1.2.* and earlier use - <CODE>EXTRA_LFLAGS</CODE> instead.) - </P> - <P> - <STRONG>Note:</STRONG>As of BIND 8.1.1, the bind libraries and files are - installed under <SAMP>/usr/local/bind</SAMP> by default, so you - should not run into this problem. Should you want to use the bind - resolvers you'll have to add the following to the respective lines: - </P> - <P> - <DL> - <DD><CODE>EXTRA_CFLAGS=-I/usr/local/bind/include - <BR> - EXTRA_LDFLAGS=-L/usr/local/bind/lib - <BR> - EXTRA_LIBS=-lbind</CODE> - </DD> - </DL> - <P></P> - <HR> - </LI> - - <LI><A NAME="cantbuild"> - <STRONG>Why won't Apache compile with my system's - <SAMP>cc</SAMP>?</STRONG> - </A> - <P> - If the server won't compile on your system, it is probably due to one - of the following causes: - </P> - <UL> - <LI><STRONG>The <SAMP>Configure</SAMP> script doesn't recognize your system - environment.</STRONG> - <BR> - This might be either because it's completely unknown or because - the specific environment (include files, OS version, <EM>et - cetera</EM>) isn't explicitly handled. If this happens, you may - need to port the server to your OS yourself. - </LI> - <LI><STRONG>Your system's C compiler is garbage.</STRONG> - <BR> - Some operating systems include a default C compiler that is either - not ANSI C-compliant or suffers from other deficiencies. The usual - recommendation in cases like this is to acquire, install, and use - <SAMP>gcc</SAMP>. - </LI> - <LI><STRONG>Your <SAMP>include</SAMP> files may be confused.</STRONG> - <BR> - In some cases, we have found that a compiler installation or system - upgrade has left the C header files in an inconsistent state. Make - sure that your include directory tree is in sync with the compiler and - the operating system. - </LI> - <LI><STRONG>Your operating system or compiler may be out of - revision.</STRONG> - <BR> - Software vendors (including those that develop operating systems) - issue new releases for a reason; sometimes to add functionality, but - more often to fix bugs that have been discovered. Try upgrading - your compiler and/or your operating system. - </LI> - </UL> - <P> - The Apache Group tests the ability to build the server on many - different platforms. Unfortunately, we can't test all of the OS - platforms there are. If you have verified that none of the above - issues is the cause of your problem, and it hasn't been reported - before, please submit a - <A HREF="http://www.apache.org/bug_report.html">problem report</A>. - Be sure to include <EM>complete</EM> details, such as the compiler - & OS versions and exact error messages. - </P> - <HR> - </LI> - - <LI><A NAME="linuxiovec"> - <STRONG>Why do I get complaints about redefinition - of "<CODE>struct iovec</CODE>" when - compiling under Linux?</STRONG> - </A> - <P> - This is a conflict between your C library includes and your kernel - includes. You need to make sure that the versions of both are matched - properly. There are two workarounds, either one will solve the problem: - </P> - <P> - <UL> - <LI>Remove the definition of <CODE>struct iovec</CODE> from your C - library includes. It is located in <CODE>/usr/include/sys/uio.h</CODE>. - <STRONG>Or,</STRONG> - </LI> - <LI>Add <CODE>-DNO_WRITEV</CODE> to the <CODE>EXTRA_CFLAGS</CODE> - line in your <SAMP>Configuration</SAMP> and reconfigure/rebuild. - This hurts performance and should only be used as a last resort. - </LI> - </UL> - <P></P> - <HR> - </LI> - - <LI><A NAME="broken-gcc"><STRONG>I'm using gcc and I get some - compilation errors, what is wrong?</STRONG></A> - <P> - GCC parses your system header files and produces a modified subset which - it uses for compiling. This behaviour ties GCC tightly to the version - of your operating system. So, for example, if you were running IRIX 5.3 - when you built GCC and then upgrade to IRIX 6.2 later, you will have to - rebuild GCC. Similarly for Solaris 2.4, 2.5, or 2.5.1 when you upgrade - to 2.6. Sometimes you can type "gcc -v" and it will tell you the version - of the operating system it was built against. - </P> - <P> - If you fail to do this, then it is very likely that Apache will fail - to build. One of the most common errors is with <CODE>readv</CODE>, - <CODE>writev</CODE>, or <CODE>uio.h</CODE>. This is <STRONG>not</STRONG> a - bug with Apache. You will need to re-install GCC. - </P> - <HR> - </LI> - - <LI><A NAME="glibc-crypt"> - <STRONG>I'm using RedHat Linux 5.0, or some other - <SAMP>glibc</SAMP>-based Linux system, and I get errors with the - <CODE>crypt</CODE> function when I attempt to build Apache 1.2.</STRONG> - </A> - - <P> - <SAMP>glibc</SAMP> puts the <CODE>crypt</CODE> function into a separate - library. Edit your <CODE>src/Configuration</CODE> file and set this: - </P> - <DL> - <DD><CODE>EXTRA_LIBS=-lcrypt</CODE> - </DD> - </DL> - <P> - Then re-run <SAMP>src/Configure</SAMP> and re-execute the make. - </P> - <HR> - </LI> - -</OL> -<!--#endif --> -<!--#if expr="$STANDALONE" --> - <!-- Don't forget to add HR tags at the end of each list item.. --> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> -<!--#endif --> diff --git a/docs/manual/misc/FAQ-D.html b/docs/manual/misc/FAQ-D.html deleted file mode 100644 index 679de4afd3..0000000000 --- a/docs/manual/misc/FAQ-D.html +++ /dev/null @@ -1,370 +0,0 @@ -<!--#if expr="$FAQMASTER" --> - <!--#set var="STANDALONE" value="" --> - <!--#set var="INCLUDED" value="YES" --> - <!--#if expr="$QUERY_STRING = TOC" --> - <!--#set var="TOC" value="YES" --> - <!--#set var="CONTENT" value="" --> - <!--#else --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="YES" --> - <!--#endif --> -<!--#else --> - <!--#set var="STANDALONE" value="YES" --> - <!--#set var="INCLUDED" value="" --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="" --> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Server Frequently Asked Questions</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> - <P> - $Revision: 1.3 $ ($Date: 1999/08/04 18:10:40 $) - </P> - <P> - The latest version of this FAQ is always available from the main - Apache web site, at - <<A - HREF="http://www.apache.org/docs/misc/FAQ.html" - REL="Help" - ><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>>. - </P> -<!-- Notes about changes: --> -<!-- - If adding a relative link to another part of the --> -<!-- documentation, *do* include the ".html" portion. There's a --> -<!-- good chance that the user will be reading the documentation --> -<!-- on his own system, which may not be configured for --> -<!-- multiviews. --> -<!-- - When adding items, make sure they're put in the right place --> -<!-- - verify that the numbering matches up. --> -<!-- - *Don't* use <PRE></PRE> blocks - they don't appear --> -<!-- correctly in a reliable way when this is converted to text --> -<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> --> -<!-- blocks inside a <P></P> instead. This is necessary to get --> -<!-- the horizontal and vertical indenting right. --> -<!-- - Don't forget to include an HR tag after the last /P tag --> -<!-- but before the /LI in an item. --> - <P> - If you are reading a text-only version of this FAQ, you may find numbers - enclosed in brackets (such as "[12]"). These refer to the list of - reference URLs to be found at the end of the document. These references - do not appear, and are not needed, for the hypertext version. - </P> - <H2>The Questions</H2> -<OL TYPE="A"> -<!--#endif --> -<!--#if expr="$TOC || $STANDALONE" --> - <LI VALUE="4"><STRONG>Error Log Messages and Problems Starting Apache</STRONG> - <OL> - <LI><A HREF="#setgid">Why do I get "<SAMP>setgid: Invalid - argument</SAMP>" at startup?</A> - </LI> - <LI><A HREF="#nodelay">Why am I getting "<SAMP>httpd: could not - set socket option TCP_NODELAY</SAMP>" in my error log?</A> - </LI> - <LI><A HREF="#peerreset">Why am I getting "<SAMP>connection - reset by peer</SAMP>" in my error log?</A> - </LI> - <LI><A HREF="#wheres-the-dump">The errorlog says Apache dumped core, - but where's the dump file?</A> - </LI> - <LI><A HREF="#linux-shmget">When I run it under Linux I get "shmget: - function not found", what should I do?</A> - </LI> - <LI><A HREF="#nfslocking">Server hangs, or fails to start, and/or error log - fills with "<SAMP>fcntl: F_SETLKW: No record locks - available</SAMP>" or similar messages</A> - </LI> - <LI><A HREF="#aixccbug">Why am I getting "<SAMP>Expected </Directory> - but saw </Directory></SAMP>" when I try to start Apache?</A> - </LI> - <LI><A HREF="#redhat">I'm using RedHat Linux and I have problems with httpd - dying randomly or not restarting properly</A> - </LI> - <LI><A HREF="#stopping">I upgraded from an Apache version earlier - than 1.2.0 and suddenly I have problems with Apache dying randomly - or not restarting properly</A> - </LI> - <LI><A HREF="#setservername">When I try to start Apache from a DOS - window, I get a message like "<samp>Cannot determine host name. - Use ServerName directive to set it manually.</samp>" What does - this mean?</A> - </LI> - </OL> - </LI> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -</OL> - -<HR> - - <H2>The Answers</H2> -<!--#endif --> -<!--#if expr="! $TOC" --> - - <H3>D. Error Log Messages and Problems Starting Apache</H3> -<OL> - - <LI><A NAME="setgid"> - <STRONG>Why do I get "<SAMP>setgid: Invalid - argument</SAMP>" at startup?</STRONG> - </A> - <P> - Your - <A HREF="../mod/core.html#group"><SAMP>Group</SAMP></A> - directive (probably in <SAMP>conf/httpd.conf</SAMP>) needs to name a - group that actually exists in the <SAMP>/etc/group</SAMP> file (or - your system's equivalent). This problem is also frequently seen when - a negative number is used in the <CODE>Group</CODE> directive - (<EM>e.g.</EM>, "<CODE>Group #-1</CODE>"). Using a group name - -- not group number -- found in your system's group database should - solve this problem in all cases. - </P> - <HR> - </LI> - - <LI><A NAME="nodelay"> - <STRONG>Why am I getting "<SAMP>httpd: could not set socket - option TCP_NODELAY</SAMP>" in my error log?</STRONG> - </A> - <P> - This message almost always indicates that the client disconnected - before Apache reached the point of calling <CODE>setsockopt()</CODE> - for the connection. It shouldn't occur for more than about 1% of the - requests your server handles, and it's advisory only in any case. - </P> - <HR> - </LI> - - <LI><A NAME="peerreset"> - <STRONG>Why am I getting "<SAMP>connection reset by - peer</SAMP>" in my error log?</STRONG> - </A> - <P> - This is a normal message and nothing about which to be alarmed. It simply - means that the client canceled the connection before it had been - completely set up - such as by the end-user pressing the "Stop" - button. People's patience being what it is, sites with response-time - problems or slow network links may experiences this more than - high-capacity ones or those with large pipes to the network. - </P> - <HR> - </LI> - - <LI><A NAME="wheres-the-dump"> - <STRONG>The errorlog says Apache dumped core, but where's the dump - file?</STRONG> - </A> - <P> - In Apache version 1.2, the error log message - about dumped core includes the directory where the dump file should be - located. However, many Unixes do not allow a process that has - called <CODE>setuid()</CODE> to dump core for security reasons; - the typical Apache setup has the server started as root to bind to - port 80, after which it changes UIDs to a non-privileged user to - serve requests. - </P> - <P> - Dealing with this is extremely operating system-specific, and may - require rebuilding your system kernel. Consult your operating system - documentation or vendor for more information about whether your system - does this and how to bypass it. If there <EM>is</EM> a documented way - of bypassing it, it is recommended that you bypass it only for the - <SAMP>httpd</SAMP> server process if possible. - </P> - <P> - The canonical location for Apache's core-dump files is the - <A HREF="../mod/core.html#serverroot">ServerRoot</A> - directory. As of Apache version 1.3, the location can be set <EM>via</EM> - the - <A HREF="../mod/core.html#coredumpdirectory" - ><SAMP>CoreDumpDirectory</SAMP></A> - directive to a different directory. Make sure that this directory is - writable by the user the server runs as (as opposed to the user the server - is <EM>started</EM> as). - </P> - <HR> - </LI> - - <LI><A NAME="linux-shmget"> - <STRONG>When I run it under Linux I get "shmget: - function not found", what should I do?</STRONG> - </A> - <P> - Your kernel has been built without SysV IPC support. You will have - to rebuild the kernel with that support enabled (it's under the - "General Setup" submenu). Documentation for kernel - building is beyond the scope of this FAQ; you should consult the <A - HREF="http://www.linuxhq.com/HOWTO/Kernel-HOWTO.html" >Kernel - HOWTO</A>, or the documentation provided with your distribution, or - a <A HREF="http://www.linuxhq.com/HOWTO/META-FAQ.html" >Linux - newsgroup/mailing list</A>. As a last-resort workaround, you can - comment out the <CODE>#define USE_SHMGET_SCOREBOARD</CODE> - definition in the <SAMP>LINUX</SAMP> section of - <SAMP>src/conf.h</SAMP> and rebuild the server (prior to 1.3b4, - simply removing <CODE>#define HAVE_SHMGET</CODE> would have - sufficed). This will produce a server which is slower and less - reliable. - </P> - <HR> - </LI> - - <LI><A NAME="nfslocking"> - <STRONG>Server hangs, or fails to start, and/or error log - fills with "<SAMP>fcntl: F_SETLKW: No record locks - available</SAMP>" or similar messages</STRONG> - </A> - - <P> - These are symptoms of a fine locking problem, which usually means that - the server is trying to use a synchronization file on an NFS filesystem. - </P> - <P> - Because of its parallel-operation model, the Apache Web server needs to - provide some form of synchronization when accessing certain resources. - One of these synchronization methods involves taking out locks on a file, - which means that the filesystem whereon the lockfile resides must support - locking. In many cases this means it <EM>can't</EM> be kept on an - NFS-mounted filesystem. - </P> - <P> - To cause the Web server to work around the NFS locking limitations, include - a line such as the following in your server configuration files: - </P> - <DL> - <DD><CODE>LockFile /var/run/apache-lock</CODE> - </DD> - </DL> - <P> - The directory should not be generally writable (<EM>e.g.</EM>, don't use - <SAMP>/var/tmp</SAMP>). - See the <A HREF="../mod/core.html#lockfile"><SAMP>LockFile</SAMP></A> - documentation for more information. - </P> - <HR> - </LI> - - <LI><A NAME="aixccbug"><STRONG>Why am I getting "<SAMP>Expected - </Directory> but saw </Directory></SAMP>" when - I try to start Apache?</STRONG></A> - <P> - This is a known problem with certain versions of the AIX C compiler. - IBM are working on a solution, and the issue is being tracked by - <A HREF="http://bugs.apache.org/index/full/2312">problem report #2312</A>. - </P> - <HR> - </LI> - - <LI><A NAME="redhat"> - <STRONG>I'm using RedHat Linux and I have problems with httpd - dying randomly or not restarting properly</STRONG> - </A> - - <P> - RedHat Linux versions 4.x (and possibly earlier) RPMs contain - various nasty scripts which do not stop or restart Apache properly. - These can affect you even if you're not running the RedHat supplied - RPMs. - </P> - <P> - If you're using the default install then you're probably running - Apache 1.1.3, which is outdated. From RedHat's ftp site you can - pick up a more recent RPM for Apache 1.2.x. This will solve one of - the problems. - </P> - <P> - If you're using a custom built Apache rather than the RedHat RPMs - then you should <CODE>rpm -e apache</CODE>. In particular you want - the mildly broken <CODE>/etc/logrotate.d/apache</CODE> script to be - removed, and you want the broken <CODE>/etc/rc.d/init.d/httpd</CODE> - (or <CODE>httpd.init</CODE>) script to be removed. The latter is - actually fixed by the apache-1.2.5 RPMs but if you're building your - own Apache then you probably don't want the RedHat files. - </P> - <P> - We can't stress enough how important it is for folks, <EM>especially - vendors</EM> to follow the <A HREF="../stopping.html">stopping Apache - directions</A> given in our documentation. In RedHat's defense, - the broken scripts were necessary with Apache 1.1.x because the - Linux support in 1.1.x was very poor, and there were various race - conditions on all platforms. None of this should be necessary with - Apache 1.2 and later. - </P> - <HR> - </LI> - - <LI><A NAME="stopping"> - <STRONG>I upgraded from an Apache version earlier - than 1.2.0 and suddenly I have problems with Apache dying randomly - or not restarting properly</STRONG> - </A> - - <P> - You should read <A HREF="#redhat">the previous note</A> about - problems with RedHat installations. It is entirely likely that your - installation has start/stop/restart scripts which were built for - an earlier version of Apache. Versions earlier than 1.2.0 had - various race conditions that made it necessary to use - <CODE>kill -9</CODE> at times to take out all the httpd servers. - But that should not be necessary any longer. You should follow - the <A HREF="../stopping.html">directions on how to stop - and restart Apache</A>. - </P> - <P>As of Apache 1.3 there is a script - <CODE>src/support/apachectl</CODE> which, after a bit of - customization, is suitable for starting, stopping, and restarting - your server. - </P> - <HR> - </LI> - - <LI><A name="setservername"> - <b>When I try to start Apache from a DOS - window, I get a message like "<samp>Cannot determine host name. - Use ServerName directive to set it manually.</samp>" What does - this mean?</b></A> - - <p> - It means what it says; the Apache software can't determine the - hostname of your system. Edit your <samp>conf\httpd.conf</samp> - file, look for the string "ServerName", and make sure there's an - uncommented directive such as - </p> - <dl> - <dd><code>ServerName localhost</code></dd> - </dl> - <p> - or - </p> - <dl> - <dd><code>ServerName www.foo.com</code></dd> - </dl> - <p> - in the file. Correct it if there one there with wrong information, or - add one if you don't already have one. Then try to start the server - again. - </p> - <hr> - </LI> - -</OL> -<!--#endif --> -<!--#if expr="$STANDALONE" --> - <!-- Don't forget to add HR tags at the end of each list item.. --> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> -<!--#endif --> diff --git a/docs/manual/misc/FAQ-E.html b/docs/manual/misc/FAQ-E.html deleted file mode 100644 index b0ef556ec4..0000000000 --- a/docs/manual/misc/FAQ-E.html +++ /dev/null @@ -1,598 +0,0 @@ -<!--#if expr="$FAQMASTER" --> - <!--#set var="STANDALONE" value="" --> - <!--#set var="INCLUDED" value="YES" --> - <!--#if expr="$QUERY_STRING = TOC" --> - <!--#set var="TOC" value="YES" --> - <!--#set var="CONTENT" value="" --> - <!--#else --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="YES" --> - <!--#endif --> -<!--#else --> - <!--#set var="STANDALONE" value="YES" --> - <!--#set var="INCLUDED" value="" --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="" --> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Server Frequently Asked Questions</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> - <P> - $Revision: 1.4 $ ($Date: 1999/07/04 16:33:00 $) - </P> - <P> - The latest version of this FAQ is always available from the main - Apache web site, at - <<A - HREF="http://www.apache.org/docs/misc/FAQ.html" - REL="Help" - ><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>>. - </P> -<!-- Notes about changes: --> -<!-- - If adding a relative link to another part of the --> -<!-- documentation, *do* include the ".html" portion. There's a --> -<!-- good chance that the user will be reading the documentation --> -<!-- on his own system, which may not be configured for --> -<!-- multiviews. --> -<!-- - When adding items, make sure they're put in the right place --> -<!-- - verify that the numbering matches up. --> -<!-- - *Don't* use <PRE></PRE> blocks - they don't appear --> -<!-- correctly in a reliable way when this is converted to text --> -<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> --> -<!-- blocks inside a <P></P> instead. This is necessary to get --> -<!-- the horizontal and vertical indenting right. --> -<!-- - Don't forget to include an HR tag after the last /P tag --> -<!-- but before the /LI in an item. --> - <P> - If you are reading a text-only version of this FAQ, you may find numbers - enclosed in brackets (such as "[12]"). These refer to the list of - reference URLs to be found at the end of the document. These references - do not appear, and are not needed, for the hypertext version. - </P> - <H2>The Questions</H2> -<OL TYPE="A"> -<!--#endif --> -<!--#if expr="$TOC || $STANDALONE" --> - <LI VALUE="5"><STRONG>Configuration Questions</STRONG> - <OL> - <LI><A HREF="#fdlim">Why can't I run more than <<EM>n</EM>> - virtual hosts?</A> - </LI> - <LI><A HREF="#freebsd-setsize">Can I increase <SAMP>FD_SETSIZE</SAMP> - on FreeBSD?</A> - </LI> - <LI><A HREF="#errordoc401">Why doesn't my <CODE>ErrorDocument - 401</CODE> work?</A> - </LI> - <LI><A HREF="#cookies1">Why does Apache send a cookie on every response?</A> - </LI> - <LI><A HREF="#cookies2">Why don't my cookies work, I even compiled in - <SAMP>mod_cookies</SAMP>?</A> - </LI> - <LI><A HREF="#jdk1-and-http1.1">Why do my Java app[let]s give me plain text - when I request an URL from an Apache server?</A> - </LI> - <LI><A HREF="#midi">How do I get Apache to send a MIDI file so the - browser can play it?</A> - </LI> - <LI><A HREF="#addlog">How do I add browsers and referrers to my logs?</A> - </LI> - <LI><A HREF="#set-servername">Why does accessing directories only work - when I include the trailing "/" - (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user/</SAMP>) but - not when I omit it - (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user</SAMP>)?</A> - </LI> - <LI><A HREF="#no-info-directives">Why doesn't mod_info list any - directives?</A> - </LI> - <LI><A HREF="#namevhost">I upgraded to Apache 1.3 and now my - virtual hosts don't work!</A> - </LI> - <LI><A HREF="#redhat-htm">I'm using RedHat Linux and my .htm files are - showing up as HTML source rather than being formatted!</A> - </LI> - <LI><A HREF="#htaccess-work">My <CODE>.htaccess</CODE> files are being - ignored.</A> - </LI> - <LI><A HREF="#forbidden">Why do I get a - "<SAMP>Forbidden</SAMP>" message whenever I try to - access a particular directory?</A> - </OL> - </LI> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -</OL> - -<HR> - - <H2>The Answers</H2> -<!--#endif --> -<!--#if expr="! $TOC" --> - - <H3>E. Configuration Questions</H3> -<OL> - - <LI><A NAME="fdlim"> - <STRONG>Why can't I run more than <<EM>n</EM>> - virtual hosts?</STRONG> - </A> - <P> - You are probably running into resource limitations in your - operating system. The most common limitation is the - <EM>per</EM>-process limit on <STRONG>file descriptors</STRONG>, - which is almost always the cause of problems seen when adding - virtual hosts. Apache often does not give an intuitive error - message because it is normally some library routine (such as - <CODE>gethostbyname()</CODE>) which needs file descriptors and - doesn't complain intelligibly when it can't get them. - </P> - <P> - Each log file requires a file descriptor, which means that if you are - using separate access and error logs for each virtual host, each - virtual host needs two file descriptors. Each - <A HREF="../mod/core.html#listen"><SAMP>Listen</SAMP></A> - directive also needs a file descriptor. - </P> - <P> - Typical values for <<EM>n</EM>> that we've seen are in - the neighborhood of 128 or 250. When the server bumps into the file - descriptor limit, it may dump core with a SIGSEGV, it might just - hang, or it may limp along and you'll see (possibly meaningful) errors - in the error log. One common problem that occurs when you run into - a file descriptor limit is that CGI scripts stop being executed - properly. - </P> - <P> - As to what you can do about this: - </P> - <OL> - <LI>Reduce the number of - <A HREF="../mod/core.html#listen"><SAMP>Listen</SAMP></A> - directives. If there are no other servers running on the machine - on the same port then you normally don't - need any Listen directives at all. By default Apache listens to - all addresses on port 80. - </LI> - <LI>Reduce the number of log files. You can use - <A HREF="../mod/mod_log_config.html"><SAMP>mod_log_config</SAMP></A> - to log all requests to a single log file while including the name - of the virtual host in the log file. You can then write a - script to split the logfile into separate files later if - necessary. Such a script is provided with the Apache 1.3 distribution - in the <SAMP>src/support/split-logfile</SAMP> file. - </LI> - <LI>Increase the number of file descriptors available to the server - (see your system's documentation on the <CODE>limit</CODE> or - <CODE>ulimit</CODE> commands). For some systems, information on - how to do this is available in the - <A HREF="perf.html">performance hints</A> page. There is a specific - note for <A HREF="#freebsd-setsize">FreeBSD</A> below. - <P> - For Windows 95, try modifying your <SAMP>C:\CONFIG.SYS</SAMP> file to - include a line like - </P> - <DL> - <DD><CODE>FILES=300</CODE> - </DD> - </DL> - <P> - Remember that you'll need to reboot your Windows 95 system in order - for the new value to take effect. - </P> - </LI> - <LI>"Don't do that" - try to run with fewer virtual hosts - </LI> - <LI>Spread your operation across multiple server processes (using - <A HREF="../mod/core.html#listen"><SAMP>Listen</SAMP></A> - for example, but see the first point) and/or ports. - </LI> - </OL> - <P> - Since this is an operating-system limitation, there's not much else - available in the way of solutions. - </P> - <P> - As of 1.2.1 we have made attempts to work around various limitations - involving running with many descriptors. - <A HREF="descriptors.html">More information is available.</A> - </P> - <HR> - </LI> - - <LI><A NAME="freebsd-setsize"> - <STRONG>Can I increase <SAMP>FD_SETSIZE</SAMP> on FreeBSD?</STRONG> - </A> - <P> - On versions of FreeBSD before 3.0, the <SAMP>FD_SETSIZE</SAMP> define - defaults to 256. This means that you will have trouble usefully using - more than 256 file descriptors in Apache. This can be increased, but - doing so can be tricky. - </P> - <P> - If you are using a version prior to 2.2, you need to recompile your - kernel with a larger <SAMP>FD_SETSIZE</SAMP>. This can be done by adding a - line such as: - </P> - <DL> - <DD><CODE>options FD_SETSIZE <EM>nnn</EM></CODE> - </DD> - </DL> - <P> - to your kernel config file. Starting at version 2.2, this is no - longer necessary. - </P> - <P> - If you are using a version of 2.1-stable from after 1997/03/10 or - 2.2 or 3.0-current from before 1997/06/28, there is a limit in - the resolver library that prevents it from using more file descriptors - than what <SAMP>FD_SETSIZE</SAMP> is set to when libc is compiled. To - increase this, you have to recompile libc with a higher - <SAMP>FD_SETSIZE</SAMP>. - </P> - <P> - In FreeBSD 3.0, the default <SAMP>FD_SETSIZE</SAMP> has been increased to - 1024 and the above limitation in the resolver library - has been removed. - </P> - <P> - After you deal with the appropriate changes above, you can increase - the setting of <SAMP>FD_SETSIZE</SAMP> at Apache compilation time - by adding "<SAMP>-DFD_SETSIZE=<EM>nnn</EM></SAMP>" to the - <SAMP>EXTRA_CFLAGS</SAMP> line in your <SAMP>Configuration</SAMP> - file. - </P> - <HR> - </LI> - - <LI><A NAME="errordoc401"> - <STRONG>Why doesn't my <CODE>ErrorDocument 401</CODE> work?</STRONG> - </A> - <P> - You need to use it with a URL in the form - "<SAMP>/foo/bar</SAMP>" and not one with a method and - hostname such as "<SAMP>http://host/foo/bar</SAMP>". See the - <A HREF="../mod/core.html#errordocument"><SAMP>ErrorDocument</SAMP></A> - documentation for details. This was incorrectly documented in the past. - </P> - <HR> - </LI> - - <LI><A NAME="cookies1"> - <STRONG>Why does Apache send a cookie on every response?</STRONG> - </A> - <P> - Apache does <EM>not</EM> automatically send a cookie on every - response, unless you have re-compiled it with the - <A HREF="../mod/mod_usertrack.html"><SAMP>mod_usertrack</SAMP></A> - module, and specifically enabled it with the - <A HREF="../mod/mod_usertrack.html#cookietracking" - ><SAMP>CookieTracking</SAMP></A> - directive. - This module has been in Apache since version 1.2. - This module may help track users, and uses cookies to do this. If - you are not using the data generated by <SAMP>mod_usertrack</SAMP>, do - not compile it into Apache. - </P> - <HR> - </LI> - - <LI><A NAME="cookies2"> - <STRONG>Why don't my cookies work, I even compiled in - <SAMP>mod_cookies</SAMP>? - </STRONG> - </A> - <P> - Firstly, you do <EM>not</EM> need to compile in - <SAMP>mod_cookies</SAMP> in order for your scripts to work (see the - <A HREF="#cookies1">previous question</A> - for more about <SAMP>mod_cookies</SAMP>). Apache passes on your - <SAMP>Set-Cookie</SAMP> header fine, with or without this module. If - cookies do not work it will be because your script does not work - properly or your browser does not use cookies or is not set-up to - accept them. - </P> - <HR> - </LI> - - <LI><A NAME="jdk1-and-http1.1"> - <STRONG>Why do my Java app[let]s give me plain text when I request - an URL from an Apache server?</STRONG> - </A> - <P> - As of version 1.2, Apache is an HTTP/1.1 (HyperText Transfer Protocol - version 1.1) server. This fact is reflected in the protocol version - that's included in the response headers sent to a client when - processing a request. Unfortunately, low-level Web access classes - included in the Java Development Kit (JDK) version 1.0.2 expect to see - the version string "HTTP/1.0" and do not correctly interpret - the "HTTP/1.1" value Apache is sending (this part of the - response is a declaration of what the server can do rather than a - declaration of the dialect of the response). The result - is that the JDK methods do not correctly parse the headers, and - include them with the document content by mistake. - </P> - <P> - This is definitely a bug in the JDK 1.0.2 foundation classes from Sun, - and it has been fixed in version 1.1. However, the classes in - question are part of the virtual machine environment, which means - they're part of the Web browser (if Java-enabled) or the Java - environment on the client system - so even if you develop - <EM>your</EM> classes with a recent JDK, the eventual users might - encounter the problem. - The classes involved are replaceable by vendors implementing the - Java virtual machine environment, and so even those that are based - upon the 1.0.2 version may not have this problem. - </P> - <P> - In the meantime, a workaround is to tell - Apache to "fake" an HTTP/1.0 response to requests that come - from the JDK methods; this can be done by including a line such as the - following in your server configuration files: - </P> - <P> - <DL> - <DD><CODE>BrowserMatch Java1.0 force-response-1.0 - <BR> - BrowserMatch JDK/1.0 force-response-1.0</CODE> - </DD> - </DL> - <P></P> - <P> - More information about this issue can be found in the - <A HREF="http://www.apache.org/info/jdk-102.html" - ><CITE>Java and HTTP/1.1</CITE></A> - page at the Apache web site. - </P> - <HR> - </LI> - - <LI><A NAME="midi"> - <STRONG>How do I get Apache to send a MIDI file so the browser can - play it?</STRONG> - </A> - <P> - Even though the registered MIME type for MIDI files is - <SAMP>audio/midi</SAMP>, some browsers are not set up to recognize it - as such; instead, they look for <SAMP>audio/x-midi</SAMP>. There are - two things you can do to address this: - </P> - <OL> - <LI>Configure your browser to treat documents of type - <SAMP>audio/midi</SAMP> correctly. This is the type that Apache - sends by default. This may not be workable, however, if you have - many client installations to change, or if some or many of the - clients are not under your control. - </LI> - <LI>Instruct Apache to send a different <SAMP>Content-type</SAMP> - header for these files by adding the following line to your server's - configuration files: - <P> - <DL> - <DD><CODE>AddType audio/x-midi .mid .midi .kar</CODE> - </DD> - </DL> - <P></P> - <P> - Note that this may break browsers that <EM>do</EM> recognize the - <SAMP>audio/midi</SAMP> MIME type unless they're prepared to also - handle <SAMP>audio/x-midi</SAMP> the same way. - </P> - </LI> - </OL> - <HR> - </LI> - - <LI><A NAME="addlog"> - <STRONG>How do I add browsers and referrers to my logs?</STRONG> - </A> - <P> - Apache provides a couple of different ways of doing this. The - recommended method is to compile the - <A HREF="../mod/mod_log_config.html"><SAMP>mod_log_config</SAMP></A> - module into your configuration and use the - <A HREF="../mod/mod_log_config.html#customlog"><SAMP>CustomLog</SAMP></A> - directive. - </P> - <P> - You can either log the additional information in files other than your - normal transfer log, or you can add them to the records already being - written. For example: - </P> - <P> - <CODE> - CustomLog logs/access_log "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"" - </CODE> - </P> - <P> - This will add the values of the <SAMP>User-agent:</SAMP> and - <SAMP>Referer:</SAMP> headers, which indicate the client and the - referring page, respectively, to the end of each line in the access - log. - </P> - <P> - You may want to check out the <CITE>Apache Week</CITE> article - entitled: - "<A HREF="http://www.apacheweek.com/features/logfiles" REL="Help" - ><CITE>Gathering Visitor Information: Customizing Your - Logfiles</CITE></A>". - </P> - <HR> - </LI> - - <LI><A NAME="set-servername"> - <STRONG>Why does accessing directories only work when I include - the trailing "/" - (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user/</SAMP>) - but not when I omit it - (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user</SAMP>)?</STRONG> - </A> - <P> - When you access a directory without a trailing "/", Apache needs - to send what is called a redirect to the client to tell it to - add the trailing slash. If it did not do so, relative URLs would - not work properly. When it sends the redirect, it needs to know - the name of the server so that it can include it in the redirect. - There are two ways for Apache to find this out; either it can guess, - or you can tell it. If your DNS is configured correctly, it can - normally guess without any problems. If it is not, however, then - you need to tell it. - </P> - <P> - Add a <A HREF="../mod/core.html#servername">ServerName</A> directive - to the config file to tell it what the domain name of the server is. - </P> - <HR> - </LI> - - <LI><A NAME="no-info-directives"> - <STRONG>Why doesn't mod_info list any directives?</STRONG> - </A> - <P> - The <A HREF="../mod/mod_info.html"><SAMP>mod_info</SAMP></A> - module allows you to use a Web browser to see how your server is - configured. Among the information it displays is the list modules and - their configuration directives. The "current" values for - the directives are not necessarily those of the running server; they - are extracted from the configuration files themselves at the time of - the request. If the files have been changed since the server was last - reloaded, the display will will not match the values actively in use. - If the files and the path to the files are not readable by the user as - which the server is running (see the - <A HREF="../mod/core.html#user"><SAMP>User</SAMP></A> - directive), then <SAMP>mod_info</SAMP> cannot read them in order to - list their values. An entry <EM>will</EM> be made in the error log in - this event, however. - </P> - <HR> - </LI> - - <LI><A NAME="namevhost"> - <STRONG>I upgraded to Apache 1.3 and now my virtual hosts don't - work!</STRONG> - </A> - <P> - In versions of Apache prior to 1.3b2, there was a lot of confusion - regarding address-based virtual hosts and (HTTP/1.1) name-based - virtual hosts, and the rules concerning how the server processed - <SAMP><VirtualHost></SAMP> definitions were very complex and not - well documented. - </P> - <P> - Apache 1.3b2 introduced a new directive, - <A HREF="http://www.apache.org/docs/mod/core.html#namevirtualhost" - ><SAMP>NameVirtualHost</SAMP></A>, - which simplifies the rules quite a bit. However, changing the rules - like this means that your existing name-based - <SAMP><VirtualHost></SAMP> containers probably won't work - correctly immediately following the upgrade. - </P> - <P> - To correct this problem, add the following line to the beginning of - your server configuration file, before defining any virtual hosts: - </P> - <DL> - <DD><CODE>NameVirtualHost <EM>n.n.n.n</EM></CODE> - </DD> - </DL> - <P> - Replace the "<SAMP>n.n.n.n</SAMP>" with the IP address to - which the name-based virtual host names resolve; if you have multiple - name-based hosts on multiple addresses, repeat the directive for each - address. - </P> - <P> - Make sure that your name-based <SAMP><VirtualHost></SAMP> blocks - contain <SAMP>ServerName</SAMP> and possibly <SAMP>ServerAlias</SAMP> - directives so Apache can be sure to tell them apart correctly. - </P> - <P> - Please see the - <A HREF="http://www.apache.org/docs/vhosts/">Apache - Virtual Host documentation</A> for further details about configuration. - </P> - <HR> - </LI> - - <LI><A NAME="redhat-htm"> - <STRONG>I'm using RedHat Linux and my .htm files are showing - up as HTML source rather than being formatted!</STRONG> - </A> - - <P> - RedHat messed up and forgot to put a content type for <CODE>.htm</CODE> - files into <CODE>/etc/mime.types</CODE>. Edit <CODE>/etc/mime.types</CODE>, - find the line containing <CODE>html</CODE> and add <CODE>htm</CODE> to it. - Then restart your httpd server: - </P> - <DL> - <DD><CODE>kill -HUP `cat /var/run/httpd.pid`</CODE> - </DD> - </DL> - <P> - Then <STRONG>clear your browsers' caches</STRONG>. (Many browsers won't - re-examine the content type after they've reloaded a page.) - </P> - <HR> - </LI> - - <LI><A NAME="htaccess-work"> - <STRONG>My <CODE>.htaccess</CODE> files are being ignored.</STRONG></A> - <P> - This is almost always due to your <A HREF="../mod/core.html#allowoverride"> - AllowOverride</A> directive being set incorrectly for the directory in - question. If it is set to <CODE>None</CODE> then .htaccess files will - not even be looked for. If you do have one that is set, then be certain - it covers the directory you are trying to use the .htaccess file in. - This is normally accomplished by ensuring it is inside the proper - <A HREF="../mod/core.html#directory">Directory</A> container. - </P> - <HR> - </LI> - <LI><A NAME="forbidden"> - <STRONG>Why do I get a "<SAMP>Forbidden</SAMP>" message - whenever I try to access a particular directory?</STRONG></A> - <P> - This message is generally caused because either - </P> - <UL> - <LI>The underlying file system permissions do not allow the - User/Group under which Apache is running to access the necessary - files; or - <LI>The Apache configuration has some access restrictions in - place which forbid access to the files. - </UL> - <P> - You can determine which case applies to your situation by checking the - error log. - </P> - <P> - In the case where file system permission are at fault, remember - that not only must the directory and files in question be readable, - but also all parent directories must be at least searchable by the - web server in order for the content to be accessible. - </P> - <HR> - </LI> -</OL> -<!--#endif --> -<!--#if expr="$STANDALONE" --> - <!-- Don't forget to add HR tags at the end of each list item.. --> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> -<!--#endif --> diff --git a/docs/manual/misc/FAQ-F.html b/docs/manual/misc/FAQ-F.html deleted file mode 100644 index a4442a481e..0000000000 --- a/docs/manual/misc/FAQ-F.html +++ /dev/null @@ -1,524 +0,0 @@ -<!--#if expr="$FAQMASTER" --> - <!--#set var="STANDALONE" value="" --> - <!--#set var="INCLUDED" value="YES" --> - <!--#if expr="$QUERY_STRING = TOC" --> - <!--#set var="TOC" value="YES" --> - <!--#set var="CONTENT" value="" --> - <!--#else --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="YES" --> - <!--#endif --> -<!--#else --> - <!--#set var="STANDALONE" value="YES" --> - <!--#set var="INCLUDED" value="" --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="" --> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Server Frequently Asked Questions</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> - <P> - $Revision: 1.2 $ ($Date: 1999/07/03 22:12:50 $) - </P> - <P> - The latest version of this FAQ is always available from the main - Apache web site, at - <<A - HREF="http://www.apache.org/docs/misc/FAQ.html" - REL="Help" - ><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>>. - </P> -<!-- Notes about changes: --> -<!-- - If adding a relative link to another part of the --> -<!-- documentation, *do* include the ".html" portion. There's a --> -<!-- good chance that the user will be reading the documentation --> -<!-- on his own system, which may not be configured for --> -<!-- multiviews. --> -<!-- - When adding items, make sure they're put in the right place --> -<!-- - verify that the numbering matches up. --> -<!-- - *Don't* use <PRE></PRE> blocks - they don't appear --> -<!-- correctly in a reliable way when this is converted to text --> -<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> --> -<!-- blocks inside a <P></P> instead. This is necessary to get --> -<!-- the horizontal and vertical indenting right. --> -<!-- - Don't forget to include an HR tag after the last /P tag --> -<!-- but before the /LI in an item. --> - <P> - If you are reading a text-only version of this FAQ, you may find numbers - enclosed in brackets (such as "[12]"). These refer to the list of - reference URLs to be found at the end of the document. These references - do not appear, and are not needed, for the hypertext version. - </P> - <H2>The Questions</H2> -<OL TYPE="A"> -<!--#endif --> -<!--#if expr="$TOC || $STANDALONE" --> - <LI VALUE="6"><STRONG>Dynamic Content (CGI and SSI)</STRONG> - <OL> - <LI><A HREF="#CGIoutsideScriptAlias">How do I enable CGI execution - in directories other than the ScriptAlias?</A> - </LI> - <LI><A HREF="#premature-script-headers">What does it mean when my - CGIs fail with "<SAMP>Premature end of script - headers</SAMP>"?</A> - </LI> - <LI><A HREF="#POSTnotallowed">Why do I keep getting "Method Not - Allowed" for form POST requests?</A> - </LI> - <LI><A HREF="#nph-scripts">How can I get my script's output without - Apache buffering it? Why doesn't my server push work?</A> - </LI> - <LI><A HREF="#cgi-spec">Where can I find the "CGI - specification"?</A> - </LI> - <LI><A HREF="#fastcgi">Why isn't FastCGI included with Apache any - more?</A> - </LI> - <LI><A HREF="#ssi-part-i">How do I enable SSI (parsed HTML)?</A> - </LI> - <LI><A HREF="#ssi-part-ii">Why don't my parsed files get cached?</A> - </LI> - <LI><A HREF="#ssi-part-iii">How can I have my script output parsed?</A> - </LI> - <LI><A HREF="#ssi-part-iv">SSIs don't work for VirtualHosts and/or - user home directories</A> - </LI> - <LI><A HREF="#errordocssi">How can I use <CODE>ErrorDocument</CODE> - and SSI to simplify customized error messages?</A> - </LI> - <LI><A HREF="#remote-user-var">Why is the environment variable - <SAMP>REMOTE_USER</SAMP> not set?</A> - </LI> - </OL> - </LI> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -</OL> - -<HR> - - <H2>The Answers</H2> -<!--#endif --> -<!--#if expr="! $TOC" --> - - <H3>F. Dynamic Content (CGI and SSI)</H3> -<OL> - - <LI><A NAME="CGIoutsideScriptAlias"> - <STRONG>How do I enable CGI execution in directories other than - the ScriptAlias?</STRONG> - </A> - <P> - Apache recognizes all files in a directory named as a - <A HREF="../mod/mod_alias.html#scriptalias"><SAMP>ScriptAlias</SAMP></A> - as being eligible for execution rather than processing as normal - documents. This applies regardless of the file name, so scripts in a - ScriptAlias directory don't need to be named - "<SAMP>*.cgi</SAMP>" or "<SAMP>*.pl</SAMP>" or - whatever. In other words, <EM>all</EM> files in a ScriptAlias - directory are scripts, as far as Apache is concerned. - </P> - <P> - To persuade Apache to execute scripts in other locations, such as in - directories where normal documents may also live, you must tell it how - to recognize them - and also that it's okay to execute them. For - this, you need to use something like the - <A HREF="../mod/mod_mime.html#addhandler"><SAMP>AddHandler</SAMP></A> - directive. - </P> - <P> - <OL> - <LI>In an appropriate section of your server configuration files, add - a line such as - <P> - <DL> - <DD><CODE>AddHandler cgi-script .cgi</CODE> - </DD> - </DL> - <P></P> - <P> - The server will then recognize that all files in that location (and - its logical descendants) that end in "<SAMP>.cgi</SAMP>" - are script files, not documents. - </P> - </LI> - <LI>Make sure that the directory location is covered by an - <A HREF="../mod/core.html#options"><SAMP>Options</SAMP></A> - declaration that includes the <SAMP>ExecCGI</SAMP> option. - </LI> - </OL> - <P></P> - <P> - In some situations, you might not want to actually - allow all files named "<SAMP>*.cgi</SAMP>" to be executable. - Perhaps all you want is to enable a particular file in a normal directory to - be executable. This can be alternatively accomplished - <EM>via</EM> <A HREF="../mod/mod_rewrite.html"><SAMP>mod_rewrite</SAMP></A> - and the following steps: - </P> - <P> - <OL> - <LI>Locally add to the corresponding <SAMP>.htaccess</SAMP> file a ruleset - similar to this one: - <P> - <DL> - <DD><CODE>RewriteEngine on - <BR> - RewriteBase /~foo/bar/ - <BR> - RewriteRule ^quux\.cgi$ - [T=application/x-httpd-cgi]</CODE> - </DD> - </DL> - <P></P> - </LI> - <LI>Make sure that the directory location is covered by an - <A HREF="../mod/core.html#options"><SAMP>Options</SAMP></A> - declaration that includes the <SAMP>ExecCGI</SAMP> and - <SAMP>FollowSymLinks</SAMP> option. - </LI> - </OL> - <P></P> - <HR> - </LI> - - <LI><A NAME="premature-script-headers"> - <STRONG>What does it mean when my CGIs fail with - "<SAMP>Premature end of script headers</SAMP>"?</STRONG> - </A> - <P> - It means just what it says: the server was expecting a complete set of - HTTP headers (one or more followed by a blank line), and didn't get - them. - </P> - <P> - The most common cause of this problem is the script dying before - sending the complete set of headers, or possibly any at all, to the - server. To see if this is the case, try running the script standalone - from an interactive session, rather than as a script under the server. - If you get error messages, this is almost certainly the cause of the - "premature end of script headers" message. Even if the CGI - runs fine from the command line, remember that the environment and - permissions may be different when running under the web server. The - CGI can only access resources allowed for the <A - HREF="../mod/core.html#user"><CODE>User</CODE></A> and - <A HREF="../mod/core.html#group"><CODE>Group</CODE></A> specified in - your Apache configuration. In addition, the environment will not be - the same as the one provided on the command line, but it can be - adjusted using the directives provided by <A - HREF="../mod/mod_env.html">mod_env</A>. - </P> - <P> - The second most common cause of this (aside from people not - outputting the required headers at all) is a result of an interaction - with Perl's output buffering. To make Perl flush its buffers - after each output statement, insert the following statements around - the <CODE>print</CODE> or <CODE>write</CODE> statements that send your - HTTP headers: - </P> - <P> - <DL> - <DD><CODE>{<BR> - local ($oldbar) = $|;<BR> - $cfh = select (STDOUT);<BR> - $| = 1;<BR> - #<BR> - # print your HTTP headers here<BR> - #<BR> - $| = $oldbar;<BR> - select ($cfh);<BR> - }</CODE> - </DD> - </DL> - <P></P> - <P> - This is generally only necessary when you are calling external - programs from your script that send output to stdout, or if there will - be a long delay between the time the headers are sent and the actual - content starts being emitted. To maximize performance, you should - turn buffer-flushing back <EM>off</EM> (with <CODE>$| = 0</CODE> or the - equivalent) after the statements that send the headers, as displayed - above. - </P> - <P> - If your script isn't written in Perl, do the equivalent thing for - whatever language you <EM>are</EM> using (<EM>e.g.</EM>, for C, call - <CODE>fflush()</CODE> after writing the headers). - </P> - <P> - Another cause for the "premature end of script headers" - message are the RLimitCPU and RLimitMEM directives. You may - get the message if the CGI script was killed due to a - resource limit. - </P> - <P> - In addition, a configuration problem in <A - HREF="../suexec.html">suEXEC</A>, mod_perl, or another third party - module can often interfere with the execution of your CGI and cause - the "premature end of script headers" message. - </P> - <HR> - </LI> - - <LI><A NAME="POSTnotallowed"> - <STRONG>Why do I keep getting "Method Not Allowed" for - form POST requests?</STRONG> - </A> - <P> - This is almost always due to Apache not being configured to treat the - file you are trying to POST to as a CGI script. You can not POST - to a normal HTML file; the operation has no meaning. See the FAQ - entry on <A HREF="#CGIoutsideScriptAlias">CGIs outside ScriptAliased - directories</A> for details on how to configure Apache to treat the - file in question as a CGI. - </P> - <HR> - </LI> - - <LI><A NAME="nph-scripts"> - <STRONG>How can I get my script's output without Apache buffering - it? Why doesn't my server push work?</STRONG> - </A> - <P> - As of Apache 1.3, CGI scripts are essentially not buffered. Every time - your script does a "flush" to output data, that data gets relayed on to - the client. Some scripting languages, for example Perl, have their own - buffering for output - this can be disabled by setting the <CODE>$|</CODE> - special variable to 1. Of course this does increase the overall number - of packets being transmitted, which can result in a sense of slowness for - the end user. - </P> - <P>Prior to 1.3, you needed to use "nph-" scripts to accomplish - non-buffering. Today, the only difference between nph scripts and - normal scripts is that nph scripts require the full HTTP headers to - be sent. - </P> - <HR> - </LI> - - <LI><A NAME="cgi-spec"> - <STRONG>Where can I find the "CGI specification"?</STRONG> - </A> - <P> - The Common Gateway Interface (CGI) specification can be found at - the original NCSA site - <<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"> - <SAMP>http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</SAMP></A>>. - This version hasn't been updated since 1995, and there have been - some efforts to update it. - </P> - <P> - A new draft is being worked on with the intent of making it an informational - RFC; you can find out more about this project at - <<A HREF="http://web.golux.com/coar/cgi/" - ><SAMP>http://web.golux.com/coar/cgi/</SAMP></A>>. - </P> - <HR> - </LI> - - <LI><A NAME="fastcgi"> - <STRONG>Why isn't FastCGI included with Apache any more?</STRONG> - </A> - <P> - The simple answer is that it was becoming too difficult to keep the - version being included with Apache synchronized with the master copy - at the - <A HREF="http://www.fastcgi.com/" - >FastCGI web site</A>. When a new version of Apache was released, the - version of the FastCGI module included with it would soon be out of date. - </P> - <P> - You can still obtain the FastCGI module for Apache from the master - FastCGI web site. - </P> - <HR> - </LI> - - <LI><A NAME="ssi-part-i"> - <STRONG>How do I enable SSI (parsed HTML)?</STRONG> - </A> - <P> - SSI (an acronym for Server-Side Include) directives allow static HTML - documents to be enhanced at run-time (<EM>e.g.</EM>, when delivered to - a client by Apache). The format of SSI directives is covered - in the <A HREF="../mod/mod_include.html">mod_include manual</A>; - suffice it to say that Apache supports not only SSI but - xSSI (eXtended SSI) directives. - </P> - <P> - Processing a document at run-time is called <EM>parsing</EM> it; hence - the term "parsed HTML" sometimes used for documents that - contain SSI instructions. Parsing tends to be <EM>extremely</EM> - resource-consumptive, and is not enabled by default. It can also - interfere with the cachability of your documents, which can put a - further load on your server. (see the - <A HREF="#ssi-part-ii">next question</A> for more information about this.) - </P> - <P> - To enable SSI processing, you need to - </P> - <UL> - <LI>Build your server with the - <A HREF="../mod/mod_include.html"><SAMP>mod_include</SAMP></A> - module. This is normally compiled in by default. - </LI> - <LI>Make sure your server configuration files have an - <A HREF="../mod/core.html#options"><SAMP>Options</SAMP></A> - directive which permits <SAMP>Includes</SAMP>. - </LI> - <LI>Make sure that the directory where you want the SSI documents to - live is covered by the "server-parsed" content handler, - either explicitly or in some ancestral location. That can be done - with the following - <A HREF="../mod/mod_mime.html#addhandler"><SAMP>AddHandler</SAMP></A> - directive: - <P> - <DL> - <DD><CODE>AddHandler server-parsed .shtml</CODE> - </DD> - </DL> - <P></P> - <P> - This indicates that all files ending in ".shtml" in that - location (or its descendants) should be parsed. Note that using - ".html" will cause all normal HTML files to be parsed, - which may put an inordinate load on your server. - </P> - </LI> - </UL> - <P> - For additional information, see the <CITE>Apache Week</CITE> article on - <A HREF="http://www.apacheweek.com/features/ssi" REL="Help" - ><CITE>Using Server Side Includes</CITE></A>. - </P> - <HR> - </LI> - - <LI><A NAME="ssi-part-ii"> - <STRONG>Why don't my parsed files get cached?</STRONG> - </A> - <P> - Since the server is performing run-time processing of your SSI - directives, which may change the content shipped to the client, it - can't know at the time it starts parsing what the final size of the - result will be, or whether the parsed result will always be the same. - This means that it can't generate <SAMP>Content-Length</SAMP> or - <SAMP>Last-Modified</SAMP> headers. Caches commonly work by comparing - the <SAMP>Last-Modified</SAMP> of what's in the cache with that being - delivered by the server. Since the server isn't sending that header - for a parsed document, whatever's doing the caching can't tell whether - the document has changed or not - and so fetches it again to be on the - safe side. - </P> - <P> - You can work around this in some cases by causing an - <SAMP>Expires</SAMP> header to be generated. (See the - <A HREF="../mod/mod_expires.html" REL="Help"><SAMP>mod_expires</SAMP></A> - documentation for more details.) Another possibility is to use the - <A HREF="../mod/mod_include.html#xbithack" REL="Help" - ><SAMP>XBitHack Full</SAMP></A> - mechanism, which tells Apache to send (under certain circumstances - detailed in the XBitHack directive description) a - <SAMP>Last-Modified</SAMP> header based upon the last modification - time of the file being parsed. Note that this may actually be lying - to the client if the parsed file doesn't change but the SSI-inserted - content does; if the included content changes often, this can result - in stale copies being cached. - </P> - <HR> - </LI> - - <LI><A NAME="ssi-part-iii"> - <STRONG>How can I have my script output parsed?</STRONG> - </A> - <P> - So you want to include SSI directives in the output from your CGI - script, but can't figure out how to do it? - The short answer is "you can't." This is potentially - a security liability and, more importantly, it can not be cleanly - implemented under the current server API. The best workaround - is for your script itself to do what the SSIs would be doing. - After all, it's generating the rest of the content. - </P> - <P> - This is a feature The Apache Group hopes to add in the next major - release after 1.3. - </P> - <HR> - </LI> - - <LI><A NAME="ssi-part-iv"> - <STRONG>SSIs don't work for VirtualHosts and/or - user home directories.</STRONG> - </A> - <P> - This is almost always due to having some setting in your config file that - sets "Options Includes" or some other setting for your DocumentRoot - but not for other directories. If you set it inside a Directory - section, then that setting will only apply to that directory. - </P> - <HR> - </LI> - - <LI><A NAME="errordocssi"> - <STRONG>How can I use <CODE>ErrorDocument</CODE> - and SSI to simplify customized error messages?</STRONG> - </A> - <P> - Have a look at <A HREF="custom_errordocs.html">this document</A>. - It shows in example form how you can a combination of XSSI and - negotiation to tailor a set of <CODE>ErrorDocument</CODE>s to your - personal taste, and returning different internationalized error - responses based on the client's native language. - </P> - <HR> - </LI> - - <LI><A NAME="remote-user-var"> - <STRONG>Why is the environment variable - <SAMP>REMOTE_USER</SAMP> not set?</STRONG> - </A> - <P> - This variable is set and thus available in SSI or CGI scripts <STRONG>if and - only if</STRONG> the requested document was protected by access - authentication. For an explanation on how to implement these restrictions, - see - <A HREF="http://www.apacheweek.com/"><CITE>Apache Week</CITE></A>'s - articles on - <A HREF="http://www.apacheweek.com/features/userauth" - ><CITE>Using User Authentication</CITE></A> - or - <A HREF="http://www.apacheweek.com/features/dbmauth" - ><CITE>DBM User Authentication</CITE></A>. - </P> - <P> - Hint: When using a CGI script to receive the data of a HTML <SAMP>FORM</SAMP> - notice that protecting the document containing the <SAMP>FORM</SAMP> is not - sufficient to provide <SAMP>REMOTE_USER</SAMP> to the CGI script. You have - to protect the CGI script, too. Or alternatively only the CGI script (then - authentication happens only after filling out the form). - </P> - <HR> - </LI> - -</OL> -<!--#endif --> -<!--#if expr="$STANDALONE" --> - <!-- Don't forget to add HR tags at the end of each list item.. --> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> -<!--#endif --> diff --git a/docs/manual/misc/FAQ-G.html b/docs/manual/misc/FAQ-G.html deleted file mode 100644 index 4461ff424f..0000000000 --- a/docs/manual/misc/FAQ-G.html +++ /dev/null @@ -1,371 +0,0 @@ -<!--#if expr="$FAQMASTER" --> - <!--#set var="STANDALONE" value="" --> - <!--#set var="INCLUDED" value="YES" --> - <!--#if expr="$QUERY_STRING = TOC" --> - <!--#set var="TOC" value="YES" --> - <!--#set var="CONTENT" value="" --> - <!--#else --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="YES" --> - <!--#endif --> -<!--#else --> - <!--#set var="STANDALONE" value="YES" --> - <!--#set var="INCLUDED" value="" --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="" --> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Server Frequently Asked Questions</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> - <P> - $Revision: 1.1 $ ($Date: 1999/06/24 15:02:52 $) - </P> - <P> - The latest version of this FAQ is always available from the main - Apache web site, at - <<A - HREF="http://www.apache.org/docs/misc/FAQ.html" - REL="Help" - ><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>>. - </P> -<!-- Notes about changes: --> -<!-- - If adding a relative link to another part of the --> -<!-- documentation, *do* include the ".html" portion. There's a --> -<!-- good chance that the user will be reading the documentation --> -<!-- on his own system, which may not be configured for --> -<!-- multiviews. --> -<!-- - When adding items, make sure they're put in the right place --> -<!-- - verify that the numbering matches up. --> -<!-- - *Don't* use <PRE></PRE> blocks - they don't appear --> -<!-- correctly in a reliable way when this is converted to text --> -<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> --> -<!-- blocks inside a <P></P> instead. This is necessary to get --> -<!-- the horizontal and vertical indenting right. --> -<!-- - Don't forget to include an HR tag after the last /P tag --> -<!-- but before the /LI in an item. --> - <P> - If you are reading a text-only version of this FAQ, you may find numbers - enclosed in brackets (such as "[12]"). These refer to the list of - reference URLs to be found at the end of the document. These references - do not appear, and are not needed, for the hypertext version. - </P> - <H2>The Questions</H2> -<OL TYPE="A"> -<!--#endif --> -<!--#if expr="$TOC || $STANDALONE" --> - <LI VALUE="7"><STRONG>Authentication and Access Restrictions</STRONG> - <OL> - <LI><A HREF="#dnsauth">Why isn't restricting access by host or domain name - working correctly?</A> - </LI> - <LI><A HREF="#user-authentication">How do I set up Apache to require - a username and password to access certain documents?</A> - </LI> - <LI><A HREF="#remote-auth-only">How do I set up Apache to allow access - to certain documents only if a site is either a local site - <EM>or</EM> the user supplies a password and username?</A> - </LI> - <LI><A HREF="#authauthoritative">Why does my authentication give - me a server error?</A> - </LI> - <LI><A HREF="#auth-on-same-machine">Do I have to keep the (mSQL) - authentication information on the same machine?</A> - </LI> - <LI><A HREF="#msql-slow">Why is my mSQL authentication terribly slow?</A> - </LI> - <LI><A HREF="#passwdauth">Can I use my <SAMP>/etc/passwd</SAMP> file - for Web page authentication?</A> - </LI> - </OL> - </LI> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -</OL> - -<HR> - - <H2>The Answers</H2> -<!--#endif --> -<!--#if expr="! $TOC" --> - <H3>G. Authentication and Access Restrictions</H3> -<OL> - - <LI><A NAME="dnsauth"> - <STRONG>Why isn't restricting access by host or domain name - working correctly?</STRONG> - </A> - <P> - Two of the most common causes of this are: - </P> - <OL> - <LI><STRONG>An error, inconsistency, or unexpected mapping in the DNS - registration</STRONG> - <BR> - This happens frequently: your configuration restricts access to - <SAMP>Host.FooBar.Com</SAMP>, but you can't get in from that host. - The usual reason for this is that <SAMP>Host.FooBar.Com</SAMP> is - actually an alias for another name, and when Apache performs the - address-to-name lookup it's getting the <EM>real</EM> name, not - <SAMP>Host.FooBar.Com</SAMP>. You can verify this by checking the - reverse lookup yourself. The easiest way to work around it is to - specify the correct host name in your configuration. - </LI> - <LI><STRONG>Inadequate checking and verification in your - configuration of Apache</STRONG> - <BR> - If you intend to perform access checking and restriction based upon - the client's host or domain name, you really need to configure - Apache to double-check the origin information it's supplied. You do - this by adding the <SAMP>-DMAXIMUM_DNS</SAMP> clause to the - <SAMP>EXTRA_CFLAGS</SAMP> definition in your - <SAMP>Configuration</SAMP> file. For example: - <P> - <DL> - <DD><CODE>EXTRA_CFLAGS=-DMAXIMUM_DNS</CODE> - </DD> - </DL> - <P></P> - <P> - This will cause Apache to be very paranoid about making sure a - particular host address is <EM>really</EM> assigned to the name it - claims to be. Note that this <EM>can</EM> incur a significant - performance penalty, however, because of all the name resolution - requests being sent to a nameserver. - </P> - </LI> - </OL> - <HR> - </LI> - - <LI><A NAME="user-authentication"> - <STRONG>How do I set up Apache to require a username and - password to access certain documents?</STRONG> - </A> - <P> - There are several ways to do this; some of the more popular - ones are to use the <A HREF="../mod/mod_auth.html">mod_auth</A>, - <A HREF="../mod/mod_auth_db.html">mod_auth_db</A>, or - <A HREF="../mod/mod_auth_dbm.html">mod_auth_dbm</A> modules. - </P> - <P> - For an explanation on how to implement these restrictions, see - <A HREF="http://www.apacheweek.com/"><CITE>Apache Week</CITE></A>'s - articles on - <A HREF="http://www.apacheweek.com/features/userauth" - ><CITE>Using User Authentication</CITE></A> - or - <A HREF="http://www.apacheweek.com/features/dbmauth" - ><CITE>DBM User Authentication</CITE></A>. - </P> - <HR> - </LI> - - <LI><A NAME="remote-auth-only"> - <STRONG>How do I set up Apache to allow access to certain - documents only if a site is either a local site <EM>or</EM> - the user supplies a password and username?</STRONG> - </A> - <P> - Use the <A HREF="../mod/core.html#satisfy">Satisfy</A> directive, - in particular the <CODE>Satisfy Any</CODE> directive, to require - that only one of the access restrictions be met. For example, - adding the following configuration to a <SAMP>.htaccess</SAMP> - or server configuration file would restrict access to people who - either are accessing the site from a host under domain.com or - who can supply a valid username and password: - </P> - <P> - <DL> - <DD><CODE>deny from all - <BR> - allow from .domain.com - <BR> - AuthType Basic - <BR> - AuthUserFile /usr/local/apache/conf/htpasswd.users - <BR> - AuthName "special directory" - <BR> - require valid-user - <BR> - satisfy any</CODE> - </DD> - </DL> - <P></P> - <P> - See the <A HREF="#user-authentication">user authentication</A> - question and the <A HREF="../mod/mod_access.html">mod_access</A> - module for details on how the above directives work. - </P> - <HR> - </LI> - - <LI><A NAME="authauthoritative"> - <STRONG>Why does my authentication give me a server error?</STRONG> - </A> - <P> - Under normal circumstances, the Apache access control modules will - pass unrecognized user IDs on to the next access control module in - line. Only if the user ID is recognized and the password is validated - (or not) will it give the usual success or "authentication - failed" messages. - </P> - <P> - However, if the last access module in line 'declines' the validation - request (because it has never heard of the user ID or because it is not - configured), the <SAMP>http_request</SAMP> handler will give one of - the following, confusing, errors: - </P> - <UL> - <LI><SAMP>check access</SAMP> - </LI> - <LI><SAMP>check user. No user file?</SAMP> - </LI> - <LI><SAMP>check access. No groups file?</SAMP> - </LI> - </UL> - <P> - This does <EM>not</EM> mean that you have to add an - '<SAMP>AuthUserFile /dev/null</SAMP>' line as some magazines suggest! - </P> - <P> - The solution is to ensure that at least the last module is authoritative - and <STRONG>CONFIGURED</STRONG>. By default, <SAMP>mod_auth</SAMP> is - authoritative and will give an OK/Denied, but only if it is configured - with the proper <SAMP>AuthUserFile</SAMP>. Likewise, if a valid group - is required. (Remember that the modules are processed in the reverse - order from that in which they appear in your compile-time - <SAMP>Configuration</SAMP> file.) - </P> - <P> - A typical situation for this error is when you are using the - <SAMP>mod_auth_dbm</SAMP>, <SAMP>mod_auth_msql</SAMP>, - <SAMP>mod_auth_mysql</SAMP>, <SAMP>mod_auth_anon</SAMP> or - <SAMP>mod_auth_cookie</SAMP> modules on their own. These are by - default <STRONG>not</STRONG> authoritative, and this will pass the - buck on to the (non-existent) next authentication module when the - user ID is not in their respective database. Just add the appropriate - '<SAMP><EM>XXX</EM>Authoritative yes</SAMP>' line to the configuration. - </P> - <P> - In general it is a good idea (though not terribly efficient) to have the - file-based <SAMP>mod_auth</SAMP> a module of last resort. This allows - you to access the web server with a few special passwords even if the - databases are down or corrupted. This does cost a - file open/seek/close for each request in a protected area. - </P> - <HR> - </LI> - - <LI><A NAME="auth-on-same-machine"> - <STRONG>Do I have to keep the (mSQL) authentication information - on the same machine?</STRONG> - </A> - <P> - Some organizations feel very strongly about keeping the authentication - information on a different machine than the webserver. With the - <SAMP>mod_auth_msql</SAMP>, <SAMP>mod_auth_mysql</SAMP>, and other SQL - modules connecting to (R)DBMses this is quite possible. Just configure - an explicit host to contact. - </P> - <P> - Be aware that with mSQL and Oracle, opening and closing these database - connections is very expensive and time consuming. You might want to - look at the code in the <SAMP>auth_*</SAMP> modules and play with the - compile time flags to alleviate this somewhat, if your RDBMS licences - allow for it. - </P> - <HR> - </LI> - - <LI><A NAME="msql-slow"> - <STRONG>Why is my mSQL authentication terribly slow?</STRONG> - </A> - <P> - You have probably configured the Host by specifying a FQHN, - and thus the <SAMP>libmsql</SAMP> will use a full blown TCP/IP socket - to talk to the database, rather than a fast internal device. The - <SAMP>libmsql</SAMP>, the mSQL FAQ, and the <SAMP>mod_auth_msql</SAMP> - documentation warn you about this. If you have to use different - hosts, check out the <SAMP>mod_auth_msql</SAMP> code for - some compile time flags which might - or might not - suit you. - </P> - <HR> - </LI> - - <LI><A NAME="passwdauth"> - <STRONG>Can I use my <SAMP>/etc/passwd</SAMP> file - for Web page authentication?</STRONG> - </A> - <P> - Yes, you can - but it's a <STRONG>very bad idea</STRONG>. Here are - some of the reasons: - </P> - <UL> - <LI>The Web technology provides no governors on how often or how - rapidly password (authentication failure) retries can be made. That - means that someone can hammer away at your system's - <SAMP>root</SAMP> password using the Web, using a dictionary or - similar mass attack, just as fast as the wire and your server can - handle the requests. Most operating systems these days include - attack detection (such as <EM>n</EM> failed passwords for the same - account within <EM>m</EM> seconds) and evasion (breaking the - connection, disabling the account under attack, disabling - <EM>all</EM> logins from that source, <EM>et cetera</EM>), but the - Web does not. - </LI> - <LI>An account under attack isn't notified (unless the server is - heavily modified); there's no "You have 19483 login - failures" message when the legitimate owner logs in. - </LI> - <LI>Without an exhaustive and error-prone examination of the server - logs, you can't tell whether an account has been compromised. - Detecting that an attack has occurred, or is in progress, is fairly - obvious, though - <EM>if</EM> you look at the logs. - </LI> - <LI>Web authentication passwords (at least for Basic authentication) - generally fly across the wire, and through intermediate proxy - systems, in what amounts to plain text. "O'er the net we - go/Caching all the way;/O what fun it is to surf/Giving my password - away!" - </LI> - <LI>Since HTTP is stateless, information about the authentication is - transmitted <EM>each and every time</EM> a request is made to the - server. Essentially, the client caches it after the first - successful access, and transmits it without asking for all - subsequent requests to the same server. - </LI> - <LI>It's relatively trivial for someone on your system to put up a - page that will steal the cached password from a client's cache - without them knowing. Can you say "password grabber"? - </LI> - </UL> - <P> - If you still want to do this in light of the above disadvantages, the - method is left as an exercise for the reader. It'll void your Apache - warranty, though, and you'll lose all accumulated UNIX guru points. - </P> - <HR> - </LI> -</OL> -<!--#endif --> -<!--#if expr="$STANDALONE" --> - <!-- Don't forget to add HR tags at the end of each list item.. --> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> -<!--#endif --> diff --git a/docs/manual/misc/FAQ-H.html b/docs/manual/misc/FAQ-H.html deleted file mode 100644 index 3369ec9c3d..0000000000 --- a/docs/manual/misc/FAQ-H.html +++ /dev/null @@ -1,265 +0,0 @@ -<!--#if expr="$FAQMASTER" --> - <!--#set var="STANDALONE" value="" --> - <!--#set var="INCLUDED" value="YES" --> - <!--#if expr="$QUERY_STRING = TOC" --> - <!--#set var="TOC" value="YES" --> - <!--#set var="CONTENT" value="" --> - <!--#else --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="YES" --> - <!--#endif --> -<!--#else --> - <!--#set var="STANDALONE" value="YES" --> - <!--#set var="INCLUDED" value="" --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="" --> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Server Frequently Asked Questions</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> - <P> - $Revision: 1.1 $ ($Date: 1999/06/24 15:02:52 $) - </P> - <P> - The latest version of this FAQ is always available from the main - Apache web site, at - <<A - HREF="http://www.apache.org/docs/misc/FAQ.html" - REL="Help" - ><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>>. - </P> -<!-- Notes about changes: --> -<!-- - If adding a relative link to another part of the --> -<!-- documentation, *do* include the ".html" portion. There's a --> -<!-- good chance that the user will be reading the documentation --> -<!-- on his own system, which may not be configured for --> -<!-- multiviews. --> -<!-- - When adding items, make sure they're put in the right place --> -<!-- - verify that the numbering matches up. --> -<!-- - *Don't* use <PRE></PRE> blocks - they don't appear --> -<!-- correctly in a reliable way when this is converted to text --> -<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> --> -<!-- blocks inside a <P></P> instead. This is necessary to get --> -<!-- the horizontal and vertical indenting right. --> -<!-- - Don't forget to include an HR tag after the last /P tag --> -<!-- but before the /LI in an item. --> - <P> - If you are reading a text-only version of this FAQ, you may find numbers - enclosed in brackets (such as "[12]"). These refer to the list of - reference URLs to be found at the end of the document. These references - do not appear, and are not needed, for the hypertext version. - </P> - <H2>The Questions</H2> -<OL TYPE="A"> -<!--#endif --> -<!--#if expr="$TOC || $STANDALONE" --> - <LI VALUE="8"><STRONG>URL Rewriting</STRONG> - <OL> - <LI><A HREF="#rewrite-more-config">Where can I find mod_rewrite rulesets - which already solve particular URL-related problems?</A> - </LI> - <LI><A HREF="#rewrite-article">Where can I find any published information - about URL-manipulations and mod_rewrite?</A> - </LI> - <LI><A HREF="#rewrite-complexity">Why is mod_rewrite so difficult to learn - and seems so complicated?</A> - </LI> - <LI><A HREF="#rewrite-dontwork">What can I do if my RewriteRules don't work - as expected?</A> - </LI> - <LI><A HREF="#rewrite-prefixdocroot">Why don't some of my URLs get - prefixed with DocumentRoot when using mod_rewrite?</A> - </LI> - <LI><A HREF="#rewrite-nocase">How can I make all my URLs case-insensitive - with mod_rewrite?</A> - </LI> - <LI><A HREF="#rewrite-virthost">Why are RewriteRules in my VirtualHost - parts ignored?</A> - </LI> - <LI><A HREF="#rewrite-envwhitespace">How can I use strings with whitespaces - in RewriteRule's ENV flag?</A> - </LI> - </OL> - </LI> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -</OL> - -<HR> - - <H2>The Answers</H2> -<!--#endif --> -<!--#if expr="! $TOC" --> - - <H3>H. URL Rewriting</H3> -<OL> - - <LI><A NAME="rewrite-more-config"> - <STRONG>Where can I find mod_rewrite rulesets which already solve - particular URL-related problems?</STRONG> - </A> - <P> - There is a collection of - <A HREF="http://www.engelschall.com/pw/apache/rewriteguide/" - >Practical Solutions for URL-Manipulation</A> - where you can - find all typical solutions the author of - <A HREF="../mod/mod_rewrite.html"><SAMP>mod_rewrite</SAMP></A> - currently knows of. If you have more - interesting rulesets which solve particular problems not currently covered in - this document, send it to - <A HREF="mailto:rse@apache.org">Ralf S. Engelschall</A> - for inclusion. The - other webmasters will thank you for avoiding the reinvention of the wheel. - </P> - <HR> - </LI> - - <LI><A NAME="rewrite-article"> - <STRONG>Where can I find any published information about - URL-manipulations and mod_rewrite?</STRONG> - </A> - <P> - There is an article from - <A HREF="mailto:rse@apache.org" - >Ralf S. Engelschall</A> - about URL-manipulations based on - <A HREF="../mod/mod_rewrite.html"><SAMP>mod_rewrite</SAMP></A> - in the "iX Multiuser Multitasking Magazin" issue #12/96. The - german (original) version - can be read online at - <<A HREF="http://www.heise.de/ix/artikel/9612149/" - >http://www.heise.de/ix/artikel/9612149/</A>>, - the English (translated) version can be found at - <<A HREF="http://www.heise.de/ix/artikel/E/9612149/" - >http://www.heise.de/ix/artikel/E/9612149/</A>>. - </P> - <HR> - </LI> - - <LI><A NAME="rewrite-complexity"> - <STRONG>Why is mod_rewrite so difficult to learn and seems so - complicated?</STRONG> - </A> - <P> - Hmmm... there are a lot of reasons. First, mod_rewrite itself is a powerful - module which can help you in really <STRONG>all</STRONG> aspects of URL - rewriting, so it can be no trivial module per definition. To accomplish - its hard job it uses software leverage and makes use of a powerful regular - expression - library by Henry Spencer which is an integral part of Apache since its - version 1.2. And regular expressions itself can be difficult to newbies, - while providing the most flexible power to the advanced hacker. - </P> - <P> - On the other hand mod_rewrite has to work inside the Apache API environment - and needs to do some tricks to fit there. For instance the Apache API as of - 1.x really was not designed for URL rewriting at the <TT>.htaccess</TT> - level of processing. Or the problem of multiple rewrites in sequence, which - is also not handled by the API per design. To provide this features - mod_rewrite has to do some special (but API compliant!) handling which leads - to difficult processing inside the Apache kernel. While the user usually - doesn't see anything of this processing, it can be difficult to find - problems when some of your RewriteRules seem not to work. - </P> - <HR> - </LI> - - <LI><A NAME="rewrite-dontwork"> - <STRONG>What can I do if my RewriteRules don't work as expected? - </STRONG> - </A> - <P> - Use "<SAMP>RewriteLog somefile</SAMP>" and - "<SAMP>RewriteLogLevel 9</SAMP>" and have a precise look at the - steps the rewriting engine performs. This is really the only one and best - way to debug your rewriting configuration. - </P> - <HR> - </LI> - - <LI><A NAME="rewrite-prefixdocroot"><STRONG>Why don't some of my URLs - get prefixed with DocumentRoot when using mod_rewrite?</STRONG> - </A> - <P> - If the rule starts with <SAMP>/somedir/...</SAMP> make sure that - really no <SAMP>/somedir</SAMP> exists on the filesystem if you - don't want to lead the URL to match this directory, <EM>i.e.</EM>, - there must be no root directory named <SAMP>somedir</SAMP> on the - filesystem. Because if there is such a directory, the URL will not - get prefixed with DocumentRoot. This behaviour looks ugly, but is - really important for some other aspects of URL rewriting. - </P> - <HR> - </LI> - - <LI><A NAME="rewrite-nocase"> - <STRONG>How can I make all my URLs case-insensitive with mod_rewrite? - </STRONG> - </A> - <P> - You can't! The reason is: First, case translations for arbitrary - length URLs cannot be done <EM>via</EM> regex patterns and - corresponding substitutions. One need a per-character pattern like - sed/Perl <SAMP>tr|..|..|</SAMP> feature. Second, just making URLs - always upper or lower case will not resolve the complete problem of - case-INSENSITIVE URLs, because actually the URLs had to be rewritten - to the correct case-variant residing on the filesystem because in - later processing Apache needs to access the file. And Unix - filesystem is always case-SENSITIVE. - </P> - <P> - But there is a module named <CODE>mod_speling.c</CODE> (yes, it is named - this way!) out there on the net. Try this one. - </P> - <HR> - </LI> - - <LI><A NAME="rewrite-virthost"> - <STRONG> Why are RewriteRules in my VirtualHost parts ignored?</STRONG> - </A> - <P> - Because you have to enable the engine for every virtual host explicitly due - to security concerns. Just add a "RewriteEngine on" to your - virtual host configuration parts. - </P> - <HR> - </LI> - - <LI><A NAME="rewrite-envwhitespace"> - <STRONG> How can I use strings with whitespaces in RewriteRule's ENV - flag?</STRONG> - </A> - <P> - There is only one ugly solution: You have to surround the complete - flag argument by quotation marks (<SAMP>"[E=...]"</SAMP>). Notice: - The argument to quote here is not the argument to the E-flag, it is - the argument of the Apache config file parser, <EM>i.e.</EM>, the - third argument of the RewriteRule here. So you have to write - <SAMP>"[E=any text with whitespaces]"</SAMP>. - </P> - <HR> - </LI> - -</OL> -<!--#endif --> -<!--#if expr="$STANDALONE" --> - <!-- Don't forget to add HR tags at the end of each list item.. --> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> -<!--#endif --> diff --git a/docs/manual/misc/FAQ-I.html b/docs/manual/misc/FAQ-I.html deleted file mode 100644 index 80d51656bf..0000000000 --- a/docs/manual/misc/FAQ-I.html +++ /dev/null @@ -1,215 +0,0 @@ -<!--#if expr="$FAQMASTER" --> - <!--#set var="STANDALONE" value="" --> - <!--#set var="INCLUDED" value="YES" --> - <!--#if expr="$QUERY_STRING = TOC" --> - <!--#set var="TOC" value="YES" --> - <!--#set var="CONTENT" value="" --> - <!--#else --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="YES" --> - <!--#endif --> -<!--#else --> - <!--#set var="STANDALONE" value="YES" --> - <!--#set var="INCLUDED" value="" --> - <!--#set var="TOC" value="" --> - <!--#set var="CONTENT" value="" --> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Server Frequently Asked Questions</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> - <P> - $Revision: 1.3 $ ($Date: 1999/07/03 22:12:50 $) - </P> - <P> - The latest version of this FAQ is always available from the main - Apache web site, at - <<A - HREF="http://www.apache.org/docs/misc/FAQ.html" - REL="Help" - ><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>>. - </P> -<!-- Notes about changes: --> -<!-- - If adding a relative link to another part of the --> -<!-- documentation, *do* include the ".html" portion. There's a --> -<!-- good chance that the user will be reading the documentation --> -<!-- on his own system, which may not be configured for --> -<!-- multiviews. --> -<!-- - When adding items, make sure they're put in the right place --> -<!-- - verify that the numbering matches up. --> -<!-- - *Don't* use <PRE></PRE> blocks - they don't appear --> -<!-- correctly in a reliable way when this is converted to text --> -<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> --> -<!-- blocks inside a <P></P> instead. This is necessary to get --> -<!-- the horizontal and vertical indenting right. --> -<!-- - Don't forget to include an HR tag after the last /P tag --> -<!-- but before the /LI in an item. --> - <P> - If you are reading a text-only version of this FAQ, you may find numbers - enclosed in brackets (such as "[12]"). These refer to the list of - reference URLs to be found at the end of the document. These references - do not appear, and are not needed, for the hypertext version. - </P> - <H2>The Questions</H2> -<OL TYPE="A"> -<!--#endif --> -<!--#if expr="$TOC || $STANDALONE" --> - <LI VALUE="9"><STRONG>Features</STRONG> - <OL> - <LI><A HREF="#proxy">Does or will Apache act as a Proxy server?</A> - </LI> - <LI><A HREF="#multiviews">What are "multiviews"?</A> - </LI> - <LI><A HREF="#putsupport">Why can't I publish to my Apache server - using PUT on Netscape Gold and other programs?</A> - </LI> - <LI><A HREF="#SSL-i">Why doesn't Apache include SSL?</A> - </LI> - <LI><A HREF="#footer">How can I attach a footer to my documents - without using SSI?</A> - </LI> - <LI><A HREF="#search">Does Apache include a search engine?</A> - </LI> - </OL> - </LI> -<!--#endif --> -<!--#if expr="$STANDALONE" --> -</OL> - -<HR> - - <H2>The Answers</H2> -<!--#endif --> -<!--#if expr="! $TOC" --> - - <H3>I. Features</H3> -<OL> - - <LI><A NAME="proxy"> - <STRONG>Does or will Apache act as a Proxy server?</STRONG> - </A> - <P> - Apache version 1.1 and above comes with a - <A HREF="../mod/mod_proxy.html">proxy module</A>. - If compiled in, this will make Apache act as a caching-proxy server. - </P> - <HR> - </LI> - - <LI><A NAME="multiviews"> - <STRONG>What are "multiviews"?</STRONG> - </A> - <P> - "Multiviews" is the general name given to the Apache - server's ability to provide language-specific document variants in - response to a request. This is documented quite thoroughly in the - <A HREF="../content-negotiation.html" REL="Help">content negotiation</A> - description page. In addition, <CITE>Apache Week</CITE> carried an - article on this subject entitled - "<A HREF="http://www.apacheweek.com/features/negotiation" REL="Help" - ><CITE>Content Negotiation Explained</CITE></A>". - </P> - <HR> - </LI> - - <LI><A NAME="putsupport"> - <STRONG>Why can't I publish to my Apache server using PUT on - Netscape Gold and other programs?</STRONG> - </A> - <P> - Because you need to install and configure a script to handle - the uploaded files. This script is often called a "PUT" handler. - There are several available, but they may have security problems. - Using FTP uploads may be easier and more secure, at least for now. - For more information, see the <CITE>Apache Week</CITE> article - <A HREF="http://www.apacheweek.com/features/put" - ><CITE>Publishing Pages with PUT</CITE></A>. - </P> - <HR> - </LI> - - <LI><A NAME="SSL-i"> - <STRONG>Why doesn't Apache include SSL?</STRONG> - </A> - <P> - SSL (Secure Socket Layer) data transport requires encryption, and many - governments have restrictions upon the import, export, and use of - encryption technology. If Apache included SSL in the base package, - its distribution would involve all sorts of legal and bureaucratic - issues, and it would no longer be freely available. Also, some of - the technology required to talk to current clients using SSL is - patented by <A HREF="http://www.rsa.com/">RSA Data Security</A>, - who restricts its use without a license. - </P> - <P> - Some SSL implementations of Apache are available, however; see the - "<A HREF="http://www.apache.org/related_projects.html" - >related projects</A>" - page at the main Apache web site. - </P> - <P> - You can find out more about this topic in the <CITE>Apache Week</CITE> - article about - <A HREF="http://www.apacheweek.com/features/ssl" REL="Help" - ><CITE>Apache and Secure Transactions</CITE></A>. - </P> - <HR> - </LI> - <LI><A NAME="footer"> - <STRONG>How can I attach a footer to my documents - without using SSI?</STRONG> - </A> - <P> - You can make arbitrary changes to static documents by configuring an - <A HREF="http://www.apache.org/docs/mod/mod_actions.html#action"> - Action</A> which launches a CGI script. The CGI is then - responsible for setting a content-type and delivering the requested - document (the location of which is passed in the - <SAMP>PATH_TRANSLATED</SAMP> environment variable), along with - whatever footer is needed. - </P> - <P> - Busy sites may not want to run a CGI script on every request, and - should consider using an Apache module to add the footer. There are - several third party modules available through the <A - HREF="http://modules.apache.org/">Apache Module Registry</A> which - will add footers to documents. These include mod_trailer, PHP - (<SAMP>php3_auto_append_file</SAMP>), and mod_perl - (<SAMP>Apache::Sandwich</SAMP>). - </P> - <HR> - </LI> - <LI><A NAME="search"> - <STRONG>Does Apache include a search engine?</STRONG> - </A> - <P>Apache does not include a search engine, but there are many good - commercial and free search engines which can be used easily with - Apache. Some of them are listed on the <A - HREF="http://www.searchtools.com/tools/tools.html">Web Site Search - Tools</A> page. Open source search engines that are often used with - Apache include <A HREF="http://www.htdig.org/">ht://Dig</A> and <A - HREF="http://sunsite.berkeley.edu/SWISH-E/">SWISH-E</A>. - </P> - <HR> - </LI> -</OL> -<!--#endif --> -<!--#if expr="$STANDALONE" --> - <!-- Don't forget to add HR tags at the end of each list item.. --> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> -<!--#endif --> diff --git a/docs/manual/misc/FAQ.html b/docs/manual/misc/FAQ.html deleted file mode 100644 index b9a926f84a..0000000000 --- a/docs/manual/misc/FAQ.html +++ /dev/null @@ -1,111 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Server Frequently Asked Questions</TITLE> -<!--#set var="FAQMASTER" value="YES" --> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> - <P> - $Revision: 1.145 $ ($Date: 1999/06/24 15:02:53 $) - </P> - <P> - The latest version of this FAQ is always available from the main - Apache web site, at - <<A - HREF="http://www.apache.org/docs/misc/FAQ.html" - REL="Help" - ><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>>. - </P> -<!-- Notes about changes: --> -<!-- - If adding a relative link to another part of the --> -<!-- documentation, *do* include the ".html" portion. There's a --> -<!-- good chance that the user will be reading the documentation --> -<!-- on his own system, which may not be configured for --> -<!-- multiviews. --> -<!-- - When adding items, make sure they're put in the right place --> -<!-- - verify that the numbering matches up. --> -<!-- - *Don't* use <PRE></PRE> blocks - they don't appear --> -<!-- correctly in a reliable way when this is converted to text --> -<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> --> -<!-- blocks inside a <P></P> instead. This is necessary to get --> -<!-- the horizontal and vertical indenting right. --> -<!-- - Don't forget to include an HR tag after the last /P tag --> -<!-- but before the /LI in an item. --> - <P> - If you are reading a text-only version of this FAQ, you may find numbers - enclosed in brackets (such as "[12]"). These refer to the list of - reference URLs to be found at the end of the document. These references - do not appear, and are not needed, for the hypertext version. - </P> - <H2>The Questions</H2> -<!-- Stuff to Add: --> -<!-- - can't bind to port 80 --> -<!-- - permission denied --> -<!-- - address already in use --> -<!-- - mod_auth & passwd lines "user:pw:.*" - ++1st colon onward is --> -<!-- treated as pw, not just ++1st to --2nd. --> -<!-- - SSL: --> -<!-- - Can I use Apache-SSL for free in Canada? --> -<!-- - Why can't I use Apache-SSL in the U.S.? --> -<!-- - How can I found out how many visitors my site gets? --> -<!-- - How do I add a counter? --> -<!-- - How do I configure Apache as a proxy? --> -<!-- - What browsers support HTTP/1.1? --> -<!-- - What's the point of vhosts-by-name is there aren't any --> -<!-- HTTP/1.1 browsers? --> -<!-- - Is there an Apache for W95/WNT? --> -<!-- - Why does Apache die when a vhost can't be DNS-resolved? --> -<!-- - Why do I get "send lost connection" messages in my error --> -<!-- log? --> -<!-- - specifically consider .pdf files which seem to cause this --> -<!-- a lot when accessed via the plugin ... and also mention --> -<!-- how range-requests can cause bytes served < file size --> -<!-- - Why do directory indexes appear as garbage? (A: -lucb) --> -<!-- - How do I add a footer to all pages offered by my server? --> -<!-- - Fix midi question; a bigger problem than midi vs. x-midi is --> -<!-- the simple fact that older versions of Apache (and new ones --> -<!-- that have been upgraded without upgrading the mime.types --> -<!-- file) don't have the type listed at all. --> -<!-- - RewriteRule /~fraggle/* /cgi-bin/fraggle.pl does not work --> -<!-- - how do I disable authentication for a subdirectory? --> -<!-- (A: you can't but "satisfy any; allow from all" can be close --> -<!-- - '400 malformed request' on Win32 might mean stale proxy; see --> -<!-- PR #2300. --> -<!-- - how do I tell what version of Apache I am running? --> -<OL TYPE="A"> -<!--#include virtual="FAQ-A.html?TOC" --> -<!--#include virtual="FAQ-B.html?TOC" --> -<!--#include virtual="FAQ-C.html?TOC" --> -<!--#include virtual="FAQ-D.html?TOC" --> -<!--#include virtual="FAQ-E.html?TOC" --> -<!--#include virtual="FAQ-F.html?TOC" --> -<!--#include virtual="FAQ-G.html?TOC" --> -<!--#include virtual="FAQ-H.html?TOC" --> -<!--#include virtual="FAQ-I.html?TOC" --> -</OL> - -<HR> - - <H2>The Answers</H2> -<!--#include virtual="FAQ-A.html?" --> -<!--#include virtual="FAQ-B.html?" --> -<!--#include virtual="FAQ-C.html?" --> -<!--#include virtual="FAQ-D.html?" --> -<!--#include virtual="FAQ-E.html?" --> -<!--#include virtual="FAQ-F.html?" --> -<!--#include virtual="FAQ-G.html?" --> -<!--#include virtual="FAQ-H.html?" --> -<!--#include virtual="FAQ-I.html?" --> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/misc/client_block_api.html b/docs/manual/misc/client_block_api.html deleted file mode 100644 index c451d19fd9..0000000000 --- a/docs/manual/misc/client_block_api.html +++ /dev/null @@ -1,87 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Reading Client Input in Apache 1.2</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Reading Client Input in Apache 1.2</H1> - -<HR> - -<P>Apache 1.1 and earlier let modules handle POST and PUT requests by -themselves. The module would, on its own, determine whether the -request had an entity, how many bytes it was, and then called a -function (<CODE>read_client_block</CODE>) to get the data. - -<P>However, HTTP/1.1 requires several things of POST and PUT request -handlers that did not fit into this module, and all existing modules -have to be rewritten. The API calls for handling this have been -further abstracted, so that future HTTP protocol changes can be -accomplished while remaining backwards-compatible.</P> - -<HR> - -<H3>The New API Functions</H3> - -<PRE> - int ap_setup_client_block (request_rec *, int read_policy); - int ap_should_client_block (request_rec *); - long ap_get_client_block (request_rec *, char *buffer, int buffer_size); -</PRE> - -<OL> -<LI>Call <CODE>ap_setup_client_block()</CODE> near the beginning of the request - handler. This will set up all the necessary properties, and - will return either OK, or an error code. If the latter, - the module should return that error code. The second parameter - selects the policy to apply if the request message indicates a - body, and how a chunked - transfer-coding should be interpreted. Choose one of -<PRE> - REQUEST_NO_BODY Send 413 error if message has any body - REQUEST_CHUNKED_ERROR Send 411 error if body without Content-Length - REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks for me. - REQUEST_CHUNKED_PASS Pass the chunks to me without removal. -</PRE> - In order to use the last two options, the caller MUST provide a buffer - large enough to hold a chunk-size line, including any extensions. - - - -<LI>When you are ready to possibly accept input, call - <CODE>ap_should_client_block()</CODE>. - This will tell the module whether or not to read input. If it is 0, - the module should assume that the input is of a non-entity type - (<EM>e.g.</EM>, a GET request). A nonzero response indicates that the module - should proceed (to step 3). - This step also sends a 100 Continue response - to HTTP/1.1 clients, so should not be called until the module - is <STRONG>*definitely*</STRONG> ready to read content. (otherwise, the - point of the - 100 response is defeated). Never call this function more than once. - -<LI>Finally, call <CODE>ap_get_client_block</CODE> in a loop. Pass it a - buffer and its - size. It will put data into the buffer (not necessarily the full - buffer, in the case of chunked inputs), and return the length of - the input block. When it is done reading, it will - return 0 if EOF, or -1 if there was an error. - -</OL> - -<P>As an example, please look at the code in -<CODE>mod_cgi.c</CODE>. This is properly written to the new API -guidelines.</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/misc/compat_notes.html b/docs/manual/misc/compat_notes.html deleted file mode 100644 index 719ee93ea9..0000000000 --- a/docs/manual/misc/compat_notes.html +++ /dev/null @@ -1,126 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" - "http://www.w3.org/TR/REC-html40/loose.dtd"> -<HTML> -<HEAD> -<TITLE>Apache HTTP Server: Notes about Compatibility with NCSA's Server</TITLE> -</HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Compatibility Notes with NCSA's Server</H1> - -<HR> - -While Apache is for the most part a drop-in replacement for NCSA's -httpd, there are a couple gotcha's to watch out for. These are mostly -due to the fact that the parser for config and access control files -was rewritten from scratch, so certain liberties the earlier servers -took may not be available here. These are all easily fixable. If you -know of other non-fatal problems that belong here, <A -HREF="http://www.apache.org/bug_report.html">let us know.</A> - -<P>Please also check the <A HREF="known_client_problems.html">known -client problems</A> page. - -<OL> -<LI>As of Apache 1.3.1, methods named in a - <A HREF="../mod/core.html#limit"><SAMP><Limit></SAMP></A> - section <EM>must</EM> be listed in upper-case. Lower- or mixed-case - method names will result in a configuration error. - <P> - </P> -</LI> - -<LI>The basic mod_auth <CODE>AuthGroupFile</CODE>-specified group file - format allows commas between user names - Apache does not. - -<P> -<LI>If you follow the NCSA guidelines for setting up access - restrictions based on client domain, you may well have added - entries for, <CODE>AuthType, AuthName, AuthUserFile</CODE> or - <CODE>AuthGroupFile</CODE>. <STRONG>None</STRONG> of these are - needed (or appropriate) for restricting access based on client - domain. When Apache sees <CODE>AuthType</CODE> it (reasonably) - assumes you are using some authorization type based on username - and password. Please remove <CODE>AuthType</CODE>, it's - unnecessary even for NCSA. - -<P> -<LI><CODE>OldScriptAlias</CODE> is no longer supported. - -<P> -<LI><CODE>exec cgi=""</CODE> produces reasonable <STRONG>malformed - header</STRONG> responses when used to invoke non-CGI scripts.<BR> - The NCSA code ignores the missing header. (bad idea) - <BR>Solution: write CGI to the CGI spec and use - <CODE>include virtual</CODE>, or use <CODE>exec cmd=""</CODE> instead. - -<P> -<LI>Icons for FancyIndexing broken - well, no, they're not broken, - we've just upgraded the icons from flat .xbm files to pretty and - much smaller .gif files, courtesy of <A - HREF="mailto:kevinh@eit.com">Kevin Hughes</A> at <A - HREF="http://www.eit.com/">EIT</A>. If you are using the same - srm.conf from an old distribution, make sure you add the new <A - HREF="../mod/mod_autoindex.html#addicon">AddIcon</A>, <A - HREF="../mod/mod_autoindex.html#addiconbytype">AddIconByType</A>, - and <A - HREF="../mod/mod_autoindex.html#defaulticon">DefaultIcon</A> - directives. - -<P> -<LI>Apache versions before 1.2b1 will ignore the last line of configuration - files if the last line does not have a trailing newline. This affects - configuration files (httpd.conf, access.conf and srm.conf), and - htpasswd and htgroup files. - -<P> -<LI>Apache does not permit commas delimiting the methods in <Limit>. - -<P> -<LI>Apache's <CODE><VirtualHost></CODE> treats all addresses as - "optional" (<EM>i.e.</EM>, the server should continue booting if it can't - resolve the address). Whereas in NCSA the default is to fail - booting unless an added <CODE>optional</CODE> keyword is included. - -<P> -<LI>Apache does not implement <CODE>OnDeny</CODE> use - <A HREF="../mod/core.html#errordocument"><CODE>ErrorDocument</CODE></A> - instead. - -<P> -<LI>Apache (as of 1.3) always performs the equivalent of - <CODE>HostnameLookups minimal</CODE>. <CODE>minimal</CODE> is not an - option to <A HREF="../mod/core.html#hostnamelookups"><CODE> - HostnameLookups</CODE></A>. - -<P> -<LI>To embed spaces in directive arguments NCSA used a backslash - before the space. Apache treats backslashes as normal characters. To - embed spaces surround the argument with double-quotes instead. - -<P> -<LI>Apache does not implement the NCSA <CODE>referer</CODE> - directive. See <A HREF="http://bugs.apache.org/index/full/968"> - PR#968</A> for a few brief suggestions on alternative ways to - implement the same thing under Apache. - -<P> -<LI>Apache does not allow ServerRoot settings inside a VirtualHost - container. There is only one global ServerRoot in Apache; any desired - changes in paths for virtual hosts need to be made with the explicit - directives, eg. DocumentRoot, TransferLog, <EM>etc.</EM> - -</OL> - -More to come when we notice them.... - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/misc/custom_errordocs.html b/docs/manual/misc/custom_errordocs.html deleted file mode 100644 index 47d50a19aa..0000000000 --- a/docs/manual/misc/custom_errordocs.html +++ /dev/null @@ -1,431 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>International Customized Server Error Messages</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Using XSSI and <SAMP>ErrorDocument</SAMP> to configure -customized international server error responses</H1> -<P> -<H2>Index</H2> -<UL> - <LI><A HREF="#intro">Introduction</A> - <LI><A HREF="#createdir">Creating an ErrorDocument directory</A> - <LI><A HREF="#docnames">Naming the individual error document files</A> - <LI><A HREF="#headfoot">The common header and footer files</A> - <LI><A HREF="#createdocs">Creating ErrorDocuments in different languages</A> - <LI><A HREF="#fallback">The fallback language</A> - <LI><A HREF="#proxy">Customizing Proxy Error Messages</A> - <LI><A HREF="#listings">HTML listing of the discussed example</A> -</UL> -<HR> -<H2><A NAME="intro">Introduction</A></H2> -This document describes an easy way to provide your apache WWW server -with a set of customized error messages which take advantage of -<A HREF="../content-negotiation.html">Content Negotiation</A> -and <A HREF="../mod/mod_include.html">eXtended Server Side Includes (XSSI)</A> -to return error messages generated by the server in the client's -native language. -</P> -<P> -By using XSSI, all -<A HREF="../mod/core.html#errordocument">customized messages</A> -can share a homogenous and consistent style and layout, and maintenance work -(changing images, changing links) is kept to a minimum because all layout -information can be kept in a single file.<BR> -Error documents can be shared across different servers, or even hosts, -because all varying information is inserted at the time the error document -is returned on behalf of a failed request. -</P> -<P> -Content Negotiation then selects the appropriate language version of a -particular error message text, honoring the language preferences passed -in the client's request. (Users usually select their favorite languages -in the preferences options menu of today's browsers). When an error -document in the client's primary language version is unavailable, the -secondary languages are tried or a default (fallback) version is used. -</P> -<P> -You have full flexibility in designing your error documents to -your personal taste (or your company's conventions). For demonstration -purposes, we present a simple generic error document scheme. -For this hypothetic server, we assume that all error messages... -<UL> -<LI>possibly are served by different virtual hosts (different host name, - different IP address, or different port) on the server machine, -<LI>show a predefined company logo in the right top of the message - (selectable by virtual host), -<LI>print the error title first, followed by an explanatory text and - (depending on the error context) help on how to resolve the error, -<LI>have some kind of standardized background image, -<LI>display an apache logo and a feedback email address at the bottom - of the error message. -</UL> -</P> - -<P> -An example of a "document not found" message for a german client might -look like this:<BR> -<IMG SRC="../images/custom_errordocs.gif" - ALT="[Needs graphics capability to display]"><BR> -All links in the document as well as links to the server's administrator -mail address, and even the name and port of the serving virtual host -are inserted in the error document at "run-time", <EM>i.e.</EM>, when the error -actually occurs. -</P> - -<H2><A NAME="createdir">Creating an ErrorDocument directory</A></H2> - -For this concept to work as easily as possible, we must take advantage -of as much server support as we can get: -<OL> - <LI>By defining the <A HREF="../mod/core.html#options">MultiViews option</A>, - we enable the language selection of the most appropriate language - alternative (content negotiation). - <LI>By setting the - <A HREF="../mod/mod_negotiation.html#languagepriority" - >LanguagePriority</A> - directive we define a set of default fallback languages in the situation - where the client's browser did not express any preference at all. - <LI>By enabling <A HREF="../mod/mod_include.html">Server Side Includes</A> - (and disallowing execution of cgi scripts for security reasons), - we allow the server to include building blocks of the error message, - and to substitute the value of certain environment variables into the - generated document (dynamic HTML) or even to conditionally include - or omit parts of the text. - <LI>The <A HREF="../mod/mod_mime.html#addhandler">AddHandler</A> and - <A HREF="../mod/mod_mime.html#addtype">AddType</A> directives are useful - for automatically XSSI-expanding all files with a <SAMP>.shtml</SAMP> - suffix to <EM>text/html</EM>. - <LI>By using the <A HREF="../mod/mod_alias.html#alias">Alias</A> directive, - we keep the error document directory outside of the document tree - because it can be regarded more as a server part than part of - the document tree. - <LI>The <A HREF="../mod/core.html#directory"><Directory></A>-Block - restricts these "special" settings to the error document directory - and avoids an impact on any of the settings for the regular document tree. - <LI>For each of the error codes to be handled (see RFC2068 for an exact - description of each error code, or look at - <CODE>src/main/http_protocol.c</CODE> - if you wish to see apache's standard messages), an - <A HREF="../mod/core.html#errordocument">ErrorDocument</A> - in the aliased <SAMP>/errordocs</SAMP> directory is defined. - Note that we only define the basename of the document here - because the MultiViews option will select the best candidate - based on the language suffixes and the client's preferences. - Any error situation with an error code <EM>not</EM> handled by a - custom document will be dealt with by the server in the standard way - (<EM>i.e.</EM>, a plain error message in english). - <LI>Finally, the <A HREF="../mod/core.html#allowoverride">AllowOverride</A> - directive tells apache that it is not necessary to look for - a .htaccess file in the /errordocs directory: a minor speed - optimization. -</OL> -The resulting <SAMP>httpd.conf</SAMP> configuration would then look -similar to this: <SMALL>(Note that you can define your own error -messages using this method for only part of the document tree, -e.g., a /~user/ subtree. In this case, the configuration could as well -be put into the .htaccess file at the root of the subtree, and -the <Directory> and </Directory> directives -but not -the contained directives- must be omitted.)</SMALL> -<PRE> - LanguagePriority en fr de - Alias /errordocs /usr/local/apache/errordocs - <Directory /usr/local/apache/errordocs> - AllowOverride none - Options MultiViews IncludesNoExec FollowSymLinks - AddType text/html .shtml - AddHandler server-parsed .shtml - </Directory> - # "400 Bad Request", - ErrorDocument 400 /errordocs/400 - # "401 Authorization Required", - ErrorDocument 401 /errordocs/401 - # "403 Forbidden", - ErrorDocument 403 /errordocs/403 - # "404 Not Found", - ErrorDocument 404 /errordocs/404 - # "500 Internal Server Error", - ErrorDocument 500 /errordocs/500 -</PRE> -The directory for the error messages (here: -<SAMP>/usr/local/apache/errordocs/</SAMP>) must then be created with the -appropriate permissions (readable and executable by the server uid or gid, -only writable for the administrator). - -<H3><A NAME="docnames">Naming the individual error document files</A></H3> - -By defining the <SAMP>MultiViews</SAMP> option, the server was told to -automatically scan the directory for matching variants (looking at language -and content type suffixes) when a requested document was not found. -In the configuration, we defined the names for the error documents to be -just their error number (without any suffix). -<P> -The names of the individual error documents are now determined like this -(I'm using 403 as an example, think of it as a placeholder for any of -the configured error documents): -<UL> - <LI>No file errordocs/403 should exist. Otherwise, it would be found and - served (with the DefaultType, usually text/plain), all negotiation - would be bypassed. - <LI>For each language for which we have an internationalized version - (note that this need not be the same set of languages for each - error code - you can get by with a single language version until - you actually <EM>have</EM> translated versions), a document - <SAMP>errordocs/403.shtml.<EM>lang</EM></SAMP> is created and - filled with the error text in that language (<A HREF="#createdocs">see - below</A>). - <LI>One fallback document called <SAMP>errordocs/403.shtml</SAMP> is - created, usually by creating a symlink to the default language - variant (<A HREF="#fallback">see below</A>). -</UL> - -<H3><A NAME="headfoot">The common header and footer files</A></H3> - -By putting as much layout information in two special "include files", -the error documents can be reduced to a bare minimum. -<P> -One of these layout files defines the HTML document header -and a configurable list of paths to the icons to be shown in the resulting -error document. These paths are exported as a set of XSSI environment -variables and are later evaluated by the "footer" special file. -The title of the current error (which is -put into the TITLE tag and an H1 header) is simply passed in from the main -error document in a variable called <CODE>title</CODE>.<BR> -<STRONG>By changing this file, the layout of all generated error -messages can be changed in a second.</STRONG> -(By exploiting the features of XSSI, you can easily define different -layouts based on the current virtual host, or even based on the -client's domain name). -<P> -The second layout file describes the footer to be displayed at the bottom -of every error message. In this example, it shows an apache logo, the current -server time, the server version string and adds a mail reference to the -site's webmaster. -<P> -For simplicity, the header file is simply called <CODE>head.shtml</CODE> -because it contains server-parsed content but no language specific -information. The footer file exists once for each language translation, -plus a symlink for the default language.<P> -<STRONG>Example:</STRONG> for English, French and German versions -(default english)<BR> -<CODE>foot.shtml.en</CODE>,<BR> -<CODE>foot.shtml.fr</CODE>,<BR> -<CODE>foot.shtml.de</CODE>,<BR> -<CODE>foot.shtml</CODE> symlink to <CODE>foot.shtml.en</CODE><P> -Both files are included into the error document by using the -directives <CODE><!--#include virtual="head" --></CODE> -and <CODE><!--#include virtual="foot" --></CODE> -respectively: the rest of the magic occurs in mod_negotiation and -in mod_include. -<P> - -See <A HREF="#listings">the listings below</A> to see an actual HTML -implementation of the discussed example. - - -<H3><A NAME="createdocs">Creating ErrorDocuments in different languages</A> -</H3> - -After all this preparation work, little remains to be said about the -actual documents. They all share a simple common structure: -<PRE> -<!--#set var="title" value="<EM>error description title</EM>" --> -<!--#include virtual="head" --> - <EM>explanatory error text</EM> -<!--#include virtual="foot" --> -</PRE> -In the <A HREF="#listings">listings section</A>, you can see an example -of a [400 Bad Request] error document. Documents as simple as that -certainly cause no problems to translate or expand. - -<H3><A NAME="fallback">The fallback language</A></H3> - -Do we need a special handling for languages other than those we have -translations for? We did set the LanguagePriority, didn't we?! -<P> -Well, the LanguagePriority directive is for the case where the client does -not express any language priority at all. But what -happens in the situation where the client wants one -of the languages we do not have, and none of those we do have? -<P> -Without doing anything, the Apache server will usually return a -[406 no acceptable variant] error, listing the choices from which the client -may select. But we're in an error message already, and important error -information might get lost when the client had to choose a language -representation first. -<P> -So, in this situation it appears to be easier to define a fallback language -(by copying or linking, <EM>e.g.</EM>, the english version to a language-less version). -Because the negotiation algorithm prefers "more specialized" variants over -"more generic" variants, these generic alternatives will only be chosen -when the normal negotiation did not succeed. -<P> -A simple shell script to do it (execute within the errordocs/ dir): -<PRE> - for f in *.shtml.en - do - ln -s $f `basename $f .en` - done -</PRE> - -<P> -</P> - -<H2><A NAME="proxy">Customizing Proxy Error Messages</A></H2> - -<P> - As of Apache-1.3, it is possible to use the <CODE>ErrorDocument</CODE> - mechanism for proxy error messages as well (previous versions always - returned fixed predefined error messages). -</P> -<P> - Most proxy errors return an error code of [500 Internal Server Error]. - To find out whether a particular error document was invoked on behalf - of a proxy error or because of some other server error, and what the reason - for the failure was, you can check the contents of the new - <CODE>ERROR_NOTES</CODE> CGI environment variable: - if invoked for a proxy error, this variable will contain the actual proxy - error message text in HTML form. -</P> -<P> - The following excerpt demonstrates how to exploit the <CODE>ERROR_NOTES</CODE> - variable within an error document: -</P> -<PRE> - <!--#if expr="\"$REDIRECT_ERROR_NOTES\" = \"\"" --> - <p> - The server encountered an unexpected condition - which prevented it from fulfilling the request. - </p> - <p> - <A HREF="mailto:<!--#echo var="SERVER_ADMIN" -->" - SUBJECT="Error message [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> for <!--#echo var="REQUEST_URI" -->"> - Please forward this error screen to <!--#echo var="SERVER_NAME" -->'s - WebMaster</A>; it includes useful debugging information about - the Request which caused the error. - <pre><!--#printenv --></pre> - </p> - <!--#else --> - <!--#echo var="REDIRECT_ERROR_NOTES" --> - <!--#endif --> -</PRE> - -<H2><A NAME="listings">HTML listing of the discussed example</A></H2> - -So, to summarize our example, here's the complete listing of the -<SAMP>400.shtml.en</SAMP> document. You will notice that it contains -almost nothing but the error text (with conditional additions). -Starting with this example, you will find it easy to add more error -documents, or to translate the error documents to different languages. -<HR><PRE> -<!--#set var="title" value="Bad Request" ---><!--#include virtual="head" --><P> - Your browser sent a request that this server could not understand: - <BLOCKQUOTE> - <STRONG><!--#echo var="REQUEST_URI" --></STRONG> - </BLOCKQUOTE> - The request could not be understood by the server due to malformed - syntax. The client should not repeat the request without - modifications. - </P> - <P> - <!--#if expr="\"$HTTP_REFERER\" != \"\"" --> - Please inform the owner of - <A HREF="<!--#echo var="HTTP_REFERER" -->">the referring page</A> about - the malformed link. - <!--#else --> - Please check your request for typing errors and retry. - <!--#endif --> - </P> -<!--#include virtual="foot" --> -</PRE><HR> - -Here is the complete <SAMP>head.shtml</SAMP> file (the funny line -breaks avoid empty lines in the document after XSSI processing). Note the -configuration section at top. That's where you configure the images and logos -as well as the apache documentation directory. Look how this file displays -two different logos depending on the content of the virtual host name -($SERVER_NAME), and that an animated apache logo is shown if the browser -appears to support it (the latter requires server configuration lines -of the form <BR><CODE>BrowserMatch "^Mozilla/[2-4]" anigif</CODE><BR> -for browser types which support animated GIFs). -<HR><PRE> -<!--#if expr="\"$SERVER_NAME\" = /.*\.mycompany\.com/" ---><!--#set var="IMG_CorpLogo" - value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif" ---><!--#set var="ALT_CorpLogo" value="Powered by Linux!" ---><!--#else ---><!--#set var="IMG_CorpLogo" - value="http://$SERVER_NAME:$SERVER_PORT/errordocs/PrivLogo.gif" ---><!--#set var="ALT_CorpLogo" value="Powered by Linux!" ---><!--#endif ---><!--#set var="IMG_BgImage" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/BgImage.gif" ---><!--#set var="DOC_Apache" value="http://$SERVER_NAME:$SERVER_PORT/Apache/" ---><!--#if expr="$anigif" ---><!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_anim.gif" ---><!--#else ---><!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_pb.gif" ---><!--#endif ---><!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<HTML> - <HEAD> - <TITLE> - [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> - </TITLE> - </HEAD> - <BODY BGCOLOR="white" BACKGROUND="<!--#echo var="IMG_BgImage" -->"><UL> - <H1 ALIGN="center"> - [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> - <IMG SRC="<!--#echo var="IMG_CorpLogo" -->" - ALT="<!--#echo var="ALT_CorpLogo" -->" ALIGN=right> - </H1> - <HR><!-- ======================================================== --> - <DIV> -</PRE><HR> - and this is the <SAMP>foot.shtml.en</SAMP> file: -<HR><PRE> - - </DIV> - <HR> - <DIV ALIGN="right"><SMALL><SUP>Local Server time: - <!--#echo var="DATE_LOCAL" --> - </SUP></SMALL></DIV> - <DIV ALIGN="center"> - <A HREF="<!--#echo var="DOC_Apache" -->"> - <IMG SRC="<!--#echo var="IMG_Apache" -->" BORDER=0 ALIGN="bottom" - ALT="Powered by <!--#echo var="SERVER_SOFTWARE" -->"></A><BR> - <SMALL><SUP><!--#set var="var" - value="Powered by $SERVER_SOFTWARE -- File last modified on $LAST_MODIFIED" - --><!--#echo var="var" --></SUP></SMALL> - </DIV> - <ADDRESS>If the indicated error looks like a misconfiguration, please inform - <A HREF="mailto:<!--#echo var="SERVER_ADMIN" -->" - SUBJECT="Feedback about Error message [<!--#echo var="REDIRECT_STATUS" - -->] <!--#echo var="title" -->, req=<!--#echo var="REQUEST_URI" -->"> - <!--#echo var="SERVER_NAME" -->'s WebMaster</A>. - </ADDRESS> - </UL></BODY> -</HTML> -</PRE><HR> - - -<H3>More welcome!</H3> - -If you have tips to contribute, send mail to <A -HREF="mailto:martin@apache.org">martin@apache.org</A> - - <!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/misc/descriptors.html b/docs/manual/misc/descriptors.html deleted file mode 100644 index dadb7cc78d..0000000000 --- a/docs/manual/misc/descriptors.html +++ /dev/null @@ -1,155 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Descriptors and Apache</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Descriptors and Apache</H1> - -<P>A <EM>descriptor</EM>, also commonly called a <EM>file handle</EM> is -an object that a program uses to read or write an open file, or open -network socket, or a variety of other devices. It is represented -by an integer, and you may be familiar with <CODE>stdin</CODE>, -<CODE>stdout</CODE>, and <CODE>stderr</CODE> which are descriptors 0, -1, and 2 respectively. -Apache needs a descriptor for each log file, plus one for each -network socket that it listens on, plus a handful of others. Libraries -that Apache uses may also require descriptors. Normal programs don't -open up many descriptors at all, and so there are some latent problems -that you may experience should you start running Apache with many -descriptors (<EM>i.e.</EM>, with many virtual hosts). - -<P>The operating system enforces a limit on the number of descriptors -that a program can have open at a time. There are typically three limits -involved here. One is a kernel limitation, depending on your operating -system you will either be able to tune the number of descriptors available -to higher numbers (this is frequently called <EM>FD_SETSIZE</EM>). Or you -may be stuck with a (relatively) low amount. The second limit is called -the <EM>hard resource</EM> limit, and it is sometimes set by root in an -obscure operating system file, but frequently is the same as the kernel -limit. The third limit is called the <EM>soft -resource</EM> limit. The soft limit is always less than or equal to -the hard limit. For example, the hard limit may be 1024, but the soft -limit only 64. Any user can raise their soft limit up to the hard limit. -Root can raise the hard limit up to the system maximum limit. The soft -limit is the actual limit that is used when enforcing the maximum number -of files a process can have open. - -<P>To summarize: - -<CENTER><PRE> - #open files <= soft limit <= hard limit <= kernel limit -</PRE></CENTER> - -<P>You control the hard and soft limits using the <CODE>limit</CODE> (csh) -or <CODE>ulimit</CODE> (sh) directives. See the respective man pages -for more information. For example you can probably use -<CODE>ulimit -n unlimited</CODE> to raise your soft limit up to the -hard limit. You should include this command in a shell script which -starts your webserver. - -<P>Unfortunately, it's not always this simple. As mentioned above, -you will probably run into some system limitations that will need to be -worked around somehow. Work was done in version 1.2.1 to improve the -situation somewhat. Here is a partial list of systems and workarounds -(assuming you are using 1.2.1 or later): - -<DL> - - <DT><STRONG>BSDI 2.0</STRONG> - <DD>Under BSDI 2.0 you can build Apache to support more descriptors - by adding <CODE>-DFD_SETSIZE=nnn</CODE> to - <CODE>EXTRA_CFLAGS</CODE> (where nnn is the number of descriptors - you wish to support, keep it less than the hard limit). But it - will run into trouble if more than approximately 240 Listen - directives are used. This may be cured by rebuilding your kernel - with a higher FD_SETSIZE. - <P> - - <DT><STRONG>FreeBSD 2.2, BSDI 2.1+</STRONG> - <DD>Similar to the BSDI 2.0 case, you should define - <CODE>FD_SETSIZE</CODE> and rebuild. But the extra - Listen limitation doesn't exist. - <P> - - <DT><STRONG>Linux</STRONG> - <DD>By default Linux has a kernel maximum of 256 open descriptors - per process. There are several patches available for the - 2.0.x series which raise this to 1024 and beyond, and you - can find them in the "unofficial patches" section of <A - HREF="http://www.linuxhq.com/">the Linux Information HQ</A>. - None of these patches are perfect, and an entirely different - approach is likely to be taken during the 2.1.x development. - Applying these patches will raise the FD_SETSIZE used to compile - all programs, and unless you rebuild all your libraries you should - avoid running any other program with a soft descriptor limit above - 256. As of this writing the patches available for increasing - the number of descriptors do not take this into account. On a - dedicated webserver you probably won't run into trouble. - <P> - - <DT><STRONG>Solaris through 2.5.1</STRONG> - <DD>Solaris has a kernel hard limit of 1024 (may be lower in earlier - versions). But it has a limitation that files using - the stdio library cannot have a descriptor above 255. - Apache uses the stdio library for the ErrorLog directive. - When you have more than approximately 110 virtual hosts - (with an error log and an access log each) you will need to - build Apache with <CODE>-DHIGH_SLACK_LINE=256</CODE> added to - <CODE>EXTRA_CFLAGS</CODE>. You will be limited to approximately - 240 error logs if you do this. - <P> - - <DT><STRONG>AIX</STRONG> - <DD>AIX version 3.2?? appears to have a hard limit of 128 descriptors. - End of story. Version 4.1.5 has a hard limit of 2000. - <P> - - <DT><STRONG>Others</STRONG> - <DD>If you have details on another operating system, please submit - it through our <A HREF="http://www.apache.org/bug_report.html">Bug - Report Page</A>. - <P> - -</DL> - -<P>In addition to the problems described above there are problems with -many libraries that Apache uses. The most common example is the bind -DNS resolver library that is used by pretty much every unix, which -fails if it ends up with a descriptor above 256. We suspect there -are other libraries that similar limitations. So the code as of 1.2.1 -takes a defensive stance and tries to save descriptors less than 16 -for use while processing each request. This is called the <EM>low -slack line</EM>. - -<P>Note that this shouldn't waste descriptors. If you really are pushing -the limits and Apache can't get a descriptor above 16 when it wants -it, it will settle for one below 16. - -<P>In extreme situations you may want to lower the low slack line, -but you shouldn't ever need to. For example, lowering it can -increase the limits 240 described above under Solaris and BSDI 2.0. -But you'll play a delicate balancing game with the descriptors needed -to serve a request. Should you want to play this game, the compile -time parameter is <CODE>LOW_SLACK_LINE</CODE> and there's a tiny -bit of documentation in the header file <CODE>httpd.h</CODE>. - -<P>Finally, if you suspect that all this slack stuff is causing you -problems, you can disable it. Add <CODE>-DNO_SLACK</CODE> to -<CODE>EXTRA_CFLAGS</CODE> and rebuild. But please report it to -our <A HREF="http://www.apache.org/bug_report.html">Bug -Report Page</A> so that -we can investigate. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/misc/fin_wait_2.html b/docs/manual/misc/fin_wait_2.html deleted file mode 100644 index e1e313d75c..0000000000 --- a/docs/manual/misc/fin_wait_2.html +++ /dev/null @@ -1,324 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Connections in FIN_WAIT_2 and Apache</TITLE> -<LINK REV="made" HREF="mailto:marc@apache.org"> - -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Connections in the FIN_WAIT_2 state and Apache</H1> -<OL> -<LI><H2>What is the FIN_WAIT_2 state?</H2> -Starting with the Apache 1.2 betas, people are reporting many more -connections in the FIN_WAIT_2 state (as reported by -<CODE>netstat</CODE>) than they saw using older versions. When the -server closes a TCP connection, it sends a packet with the FIN bit -sent to the client, which then responds with a packet with the ACK bit -set. The client then sends a packet with the FIN bit set to the -server, which responds with an ACK and the connection is closed. The -state that the connection is in during the period between when the -server gets the ACK from the client and the server gets the FIN from -the client is known as FIN_WAIT_2. See the <A -HREF="ftp://ds.internic.net/rfc/rfc793.txt">TCP RFC</A> for the -technical details of the state transitions.<P> - -The FIN_WAIT_2 state is somewhat unusual in that there is no timeout -defined in the standard for it. This means that on many operating -systems, a connection in the FIN_WAIT_2 state will stay around until -the system is rebooted. If the system does not have a timeout and -too many FIN_WAIT_2 connections build up, it can fill up the space -allocated for storing information about the connections and crash -the kernel. The connections in FIN_WAIT_2 do not tie up an httpd -process.<P> - -<LI><H2>But why does it happen?</H2> - -There are numerous reasons for it happening, some of them may not -yet be fully clear. What is known follows.<P> - -<H3>Buggy clients and persistent connections</H3> - -Several clients have a bug which pops up when dealing with -<A HREF="../keepalive.html">persistent connections</A> (aka keepalives). -When the connection is idle and the server closes the connection -(based on the <A HREF="../mod/core.html#keepalivetimeout"> -KeepAliveTimeout</A>), the client is programmed so that the client does -not send back a FIN and ACK to the server. This means that the -connection stays in the FIN_WAIT_2 state until one of the following -happens:<P> -<UL> - <LI>The client opens a new connection to the same or a different - site, which causes it to fully close the older connection on - that socket. - <LI>The user exits the client, which on some (most?) clients - causes the OS to fully shutdown the connection. - <LI>The FIN_WAIT_2 times out, on servers that have a timeout - for this state. -</UL><P> -If you are lucky, this means that the buggy client will fully close the -connection and release the resources on your server. However, there -are some cases where the socket is never fully closed, such as a dialup -client disconnecting from their provider before closing the client. -In addition, a client might sit idle for days without making another -connection, and thus may hold its end of the socket open for days -even though it has no further use for it. -<STRONG>This is a bug in the browser or in its operating system's -TCP implementation.</STRONG> <P> - -The clients on which this problem has been verified to exist:<P> -<UL> - <LI>Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE i386) - <LI>Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE i386) - <LI>Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m) - <LI>MSIE 3.01 on the Macintosh - <LI>MSIE 3.01 on Windows 95 -</UL><P> - -This does not appear to be a problem on: -<UL> - <LI>Mozilla/3.01 (Win95; I) -</UL> -<P> - -It is expected that many other clients have the same problem. What a -client <STRONG>should do</STRONG> is periodically check its open -socket(s) to see if they have been closed by the server, and close their -side of the connection if the server has closed. This check need only -occur once every few seconds, and may even be detected by a OS signal -on some systems (<EM>e.g.</EM>, Win95 and NT clients have this capability, but -they seem to be ignoring it).<P> - -Apache <STRONG>cannot</STRONG> avoid these FIN_WAIT_2 states unless it -disables persistent connections for the buggy clients, just -like we recommend doing for Navigator 2.x clients due to other bugs. -However, non-persistent connections increase the total number of -connections needed per client and slow retrieval of an image-laden -web page. Since non-persistent connections have their own resource -consumptions and a short waiting period after each closure, a busy server -may need persistence in order to best serve its clients.<P> - -As far as we know, the client-caused FIN_WAIT_2 problem is present for -all servers that support persistent connections, including Apache 1.1.x -and 1.2.<P> - -<H3>A necessary bit of code introduced in 1.2</H3> - -While the above bug is a problem, it is not the whole problem. -Some users have observed no FIN_WAIT_2 problems with Apache 1.1.x, -but with 1.2b enough connections build up in the FIN_WAIT_2 state to -crash their server. - -The most likely source for additional FIN_WAIT_2 states -is a function called <CODE>lingering_close()</CODE> which was added -between 1.1 and 1.2. This function is necessary for the proper -handling of persistent connections and any request which includes -content in the message body (<EM>e.g.</EM>, PUTs and POSTs). -What it does is read any data sent by the client for -a certain time after the server closes the connection. The exact -reasons for doing this are somewhat complicated, but involve what -happens if the client is making a request at the same time the -server sends a response and closes the connection. Without lingering, -the client might be forced to reset its TCP input buffer before it -has a chance to read the server's response, and thus understand why -the connection has closed. -See the <A HREF="#appendix">appendix</A> for more details.<P> - -The code in <CODE>lingering_close()</CODE> appears to cause problems -for a number of factors, including the change in traffic patterns -that it causes. The code has been thoroughly reviewed and we are -not aware of any bugs in it. It is possible that there is some -problem in the BSD TCP stack, aside from the lack of a timeout -for the FIN_WAIT_2 state, exposed by the <CODE>lingering_close</CODE> -code that causes the observed problems.<P> - -<H2><LI>What can I do about it?</H2> - -There are several possible workarounds to the problem, some of -which work better than others.<P> - -<H3>Add a timeout for FIN_WAIT_2</H3> - -The obvious workaround is to simply have a timeout for the FIN_WAIT_2 state. -This is not specified by the RFC, and could be claimed to be a -violation of the RFC, but it is widely recognized as being necessary. -The following systems are known to have a timeout: -<P> -<UL> - <LI><A HREF="http://www.freebsd.org/">FreeBSD</A> versions starting at - 2.0 or possibly earlier. - <LI><A HREF="http://www.netbsd.org/">NetBSD</A> version 1.2(?) - <LI><A HREF="http://www.openbsd.org/">OpenBSD</A> all versions(?) - <LI><A HREF="http://www.bsdi.com/">BSD/OS</A> 2.1, with the - <A HREF="ftp://ftp.bsdi.com/bsdi/patches/patches-2.1/K210-027"> - K210-027</A> patch installed. - <LI><A HREF="http://www.sun.com/">Solaris</A> as of around version - 2.2. The timeout can be tuned by using <CODE>ndd</CODE> to - modify <CODE>tcp_fin_wait_2_flush_interval</CODE>, but the - default should be appropriate for most servers and improper - tuning can have negative impacts. - <LI><A HREF="http://www.linux.org/">Linux</A> 2.0.x and - earlier(?) - <LI><A HREF="http://www.hp.com/">HP-UX</A> 10.x defaults to - terminating connections in the FIN_WAIT_2 state after the - normal keepalive timeouts. This does not - refer to the persistent connection or HTTP keepalive - timeouts, but the <CODE>SO_LINGER</CODE> socket option - which is enabled by Apache. This parameter can be adjusted - by using <CODE>nettune</CODE> to modify parameters such as - <CODE>tcp_keepstart</CODE> and <CODE>tcp_keepstop</CODE>. - In later revisions, there is an explicit timer for - connections in FIN_WAIT_2 that can be modified; contact HP - support for details. - <LI><A HREF="http://www.sgi.com/">SGI IRIX</A> can be patched to - support a timeout. For IRIX 5.3, 6.2, and 6.3, - use patches 1654, 1703 and 1778 respectively. If you - have trouble locating these patches, please contact your - SGI support channel for help. - <LI><A HREF="http://www.ncr.com/">NCR's MP RAS Unix</A> 2.xx and - 3.xx both have FIN_WAIT_2 timeouts. In 2.xx it is non-tunable - at 600 seconds, while in 3.xx it defaults to 600 seconds and - is calculated based on the tunable "max keep alive probes" - (default of 8) multiplied by the "keep alive interval" (default - 75 seconds). - <LI><A HREF="http://www.sequent.com">Sequent's ptx/TCP/IP for - DYNIX/ptx</A> has had a FIN_WAIT_2 timeout since around - release 4.1 in mid-1994. -</UL> -<P> -The following systems are known to not have a timeout: -<P> -<UL> - <LI><A HREF="http://www.sun.com/">SunOS 4.x</A> does not and - almost certainly never will have one because it as at the - very end of its development cycle for Sun. If you have kernel - source should be easy to patch. -</UL> -<P> -There is a -<A HREF="http://www.apache.org/dist/contrib/patches/1.2/fin_wait_2.patch" ->patch available</A> for adding a timeout to the FIN_WAIT_2 state; it -was originally intended for BSD/OS, but should be adaptable to most -systems using BSD networking code. You need kernel source code to be -able to use it. If you do adapt it to work for any other systems, -please drop me a note at <A HREF="mailto:marc@apache.org">marc@apache.org</A>. -<P> -<H3>Compile without using <CODE>lingering_close()</CODE></H3> - -It is possible to compile Apache 1.2 without using the -<CODE>lingering_close()</CODE> function. This will result in that -section of code being similar to that which was in 1.1. If you do -this, be aware that it can cause problems with PUTs, POSTs and -persistent connections, especially if the client uses pipelining. -That said, it is no worse than on 1.1, and we understand that keeping your -server running is quite important.<P> - -To compile without the <CODE>lingering_close()</CODE> function, add -<CODE>-DNO_LINGCLOSE</CODE> to the end of the -<CODE>EXTRA_CFLAGS</CODE> line in your <CODE>Configuration</CODE> file, -rerun <CODE>Configure</CODE> and rebuild the server. -<P> -<H3>Use <CODE>SO_LINGER</CODE> as an alternative to -<CODE>lingering_close()</CODE></H3> - -On most systems, there is an option called <CODE>SO_LINGER</CODE> that -can be set with <CODE>setsockopt(2)</CODE>. It does something very -similar to <CODE>lingering_close()</CODE>, except that it is broken -on many systems so that it causes far more problems than -<CODE>lingering_close</CODE>. On some systems, it could possibly work -better so it may be worth a try if you have no other alternatives. <P> - -To try it, add <CODE>-DUSE_SO_LINGER -DNO_LINGCLOSE</CODE> to the end of the -<CODE>EXTRA_CFLAGS</CODE> line in your <CODE>Configuration</CODE> -file, rerun <CODE>Configure</CODE> and rebuild the server. <P> - -<STRONG>NOTE:</STRONG> Attempting to use <CODE>SO_LINGER</CODE> and -<CODE>lingering_close()</CODE> at the same time is very likely to do -very bad things, so don't.<P> - -<H3>Increase the amount of memory used for storing connection state</H3> -<DL> -<DT>BSD based networking code: -<DD>BSD stores network data, such as connection states, -in something called an mbuf. When you get so many connections -that the kernel does not have enough mbufs to put them all in, your -kernel will likely crash. You can reduce the effects of the problem -by increasing the number of mbufs that are available; this will not -prevent the problem, it will just make the server go longer before -crashing.<P> - -The exact way to increase them may depend on your OS; look -for some reference to the number of "mbufs" or "mbuf clusters". On -many systems, this can be done by adding the line -<CODE>NMBCLUSTERS="n"</CODE>, where <CODE>n</CODE> is the number of -mbuf clusters you want to your kernel config file and rebuilding your -kernel.<P> -</DL> - -<H3>Disable KeepAlive</H3> -<P>If you are unable to do any of the above then you should, as a last -resort, disable KeepAlive. Edit your httpd.conf and change "KeepAlive On" -to "KeepAlive Off". - -<H2><LI>Feedback</H2> - -If you have any information to add to this page, please contact me at -<A HREF="mailto:marc@apache.org">marc@apache.org</A>.<P> - -<H2><A NAME="appendix"><LI>Appendix</A></H2> -<P> -Below is a message from Roy Fielding, one of the authors of HTTP/1.1. - -<H3>Why the lingering close functionality is necessary with HTTP</H3> - -The need for a server to linger on a socket after a close is noted a couple -times in the HTTP specs, but not explained. This explanation is based on -discussions between myself, Henrik Frystyk, Robert S. Thau, Dave Raggett, -and John C. Mallery in the hallways of MIT while I was at W3C.<P> - -If a server closes the input side of the connection while the client -is sending data (or is planning to send data), then the server's TCP -stack will signal an RST (reset) back to the client. Upon -receipt of the RST, the client will flush its own incoming TCP buffer -back to the un-ACKed packet indicated by the RST packet argument. -If the server has sent a message, usually an error response, to the -client just before the close, and the client receives the RST packet -before its application code has read the error message from its incoming -TCP buffer and before the server has received the ACK sent by the client -upon receipt of that buffer, then the RST will flush the error message -before the client application has a chance to see it. The result is -that the client is left thinking that the connection failed for no -apparent reason.<P> - -There are two conditions under which this is likely to occur: -<OL> -<LI>sending POST or PUT data without proper authorization -<LI>sending multiple requests before each response (pipelining) - and one of the middle requests resulting in an error or - other break-the-connection result. -</OL> -<P> -The solution in all cases is to send the response, close only the -write half of the connection (what shutdown is supposed to do), and -continue reading on the socket until it is either closed by the -client (signifying it has finally read the response) or a timeout occurs. -That is what the kernel is supposed to do if SO_LINGER is set. -Unfortunately, SO_LINGER has no effect on some systems; on some other -systems, it does not have its own timeout and thus the TCP memory -segments just pile-up until the next reboot (planned or not).<P> - -Please note that simply removing the linger code will not solve the -problem -- it only moves it to a different and much harder one to detect. -</OL> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/misc/footer.html b/docs/manual/misc/footer.html deleted file mode 100644 index 7fe745dcfd..0000000000 --- a/docs/manual/misc/footer.html +++ /dev/null @@ -1,8 +0,0 @@ -<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> diff --git a/docs/manual/misc/header.html b/docs/manual/misc/header.html deleted file mode 100644 index 5662300029..0000000000 --- a/docs/manual/misc/header.html +++ /dev/null @@ -1,6 +0,0 @@ -<DIV ALIGN="CENTER"> - <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> - <H3> - Apache HTTP Server Version 1.3 - </H3> -</DIV> diff --git a/docs/manual/misc/howto.html b/docs/manual/misc/howto.html deleted file mode 100644 index 9ce92a41ba..0000000000 --- a/docs/manual/misc/howto.html +++ /dev/null @@ -1,209 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<META NAME="description" - CONTENT="Some 'how to' tips for the Apache httpd server"> -<META NAME="keywords" CONTENT="apache,redirect,robots,rotate,logfiles"> -<TITLE>Apache HOWTO documentation</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache HOWTO documentation</H1> - -How to: -<UL> -<LI><A HREF="#redirect">redirect an entire server or directory to a single - URL</A> -<LI><A HREF="#logreset">reset your log files</A> -<LI><A HREF="#stoprob">stop/restrict robots</A> -<LI><A HREF="#proxyssl">proxy SSL requests <EM>through</EM> your non-SSL - server</A> -</UL> - -<HR> -<H2><A NAME="redirect">How to redirect an entire server or directory to a -single URL</A></H2> - -<P>There are two chief ways to redirect all requests for an entire -server to a single location: one which requires the use of -<CODE>mod_rewrite</CODE>, and another which uses a CGI script. - -<P>First: if all you need to do is migrate a server from one name to -another, simply use the <CODE>Redirect</CODE> directive, as supplied -by <CODE>mod_alias</CODE>: - -<BLOCKQUOTE><PRE> - Redirect / http://www.apache.org/ -</PRE></BLOCKQUOTE> - -<P>Since <CODE>Redirect</CODE> will forward along the complete path, -however, it may not be appropriate - for example, when the directory -structure has changed after the move, and you simply want to direct people -to the home page. - -<P>The best option is to use the standard Apache module -<CODE>mod_rewrite</CODE>. -If that module is compiled in, the following lines - -<BLOCKQUOTE><PRE>RewriteEngine On -RewriteRule /.* http://www.apache.org/ [R] -</PRE></BLOCKQUOTE> - -This will send an HTTP 302 Redirect back to the client, and no matter -what they gave in the original URL, they'll be sent to -"http://www.apache.org". - -The second option is to set up a <CODE>ScriptAlias</CODE> pointing to -a <STRONG>CGI script</STRONG> which outputs a 301 or 302 status and the -location -of the other server.</P> - -<P>By using a <STRONG>CGI script</STRONG> you can intercept various requests -and -treat them specially, <EM>e.g.</EM>, you might want to intercept -<STRONG>POST</STRONG> -requests, so that the client isn't redirected to a script on the other -server which expects POST information (a redirect will lose the POST -information.) You might also want to use a CGI script if you don't -want to compile mod_rewrite into your server. - -<P>Here's how to redirect all requests to a script... In the server -configuration file, -<BLOCKQUOTE><PRE>ScriptAlias / /usr/local/httpd/cgi-bin/redirect_script/</PRE> -</BLOCKQUOTE> - -and here's a simple perl script to redirect requests: - -<BLOCKQUOTE><PRE> -#!/usr/local/bin/perl - -print "Status: 302 Moved Temporarily\r\n" . - "Location: http://www.some.where.else.com/\r\n" . - "\r\n"; - -</PRE></BLOCKQUOTE></P> - -<HR> - -<H2><A NAME="logreset">How to reset your log files</A></H2> - -<P>Sooner or later, you'll want to reset your log files (access_log and -error_log) because they are too big, or full of old information you don't -need.</P> - -<P><CODE>access.log</CODE> typically grows by 1Mb for each 10,000 requests.</P> - -<P>Most people's first attempt at replacing the logfile is to just move the -logfile or remove the logfile. This doesn't work.</P> - -<P>Apache will continue writing to the logfile at the same offset as before the -logfile moved. This results in a new logfile being created which is just -as big as the old one, but it now contains thousands (or millions) of null -characters.</P> - -<P>The correct procedure is to move the logfile, then signal Apache to tell -it to reopen the logfiles.</P> - -<P>Apache is signaled using the <STRONG>SIGHUP</STRONG> (-1) signal. -<EM>e.g.</EM> -<BLOCKQUOTE><CODE> -mv access_log access_log.old<BR> -kill -1 `cat httpd.pid` -</CODE></BLOCKQUOTE> -</P> - -<P>Note: <CODE>httpd.pid</CODE> is a file containing the -<STRONG>p</STRONG>rocess <STRONG>id</STRONG> -of the Apache httpd daemon, Apache saves this in the same directory as the log -files.</P> - -<P>Many people use this method to replace (and backup) their logfiles on a -nightly or weekly basis.</P> -<HR> - -<H2><A NAME="stoprob">How to stop or restrict robots</A></H2> - -<P>Ever wondered why so many clients are interested in a file called -<CODE>robots.txt</CODE> which you don't have, and never did have?</P> - -<P>These clients are called <STRONG>robots</STRONG> (also known as crawlers, -spiders and other cute name) - special automated clients which -wander around the web looking for interesting resources.</P> - -<P>Most robots are used to generate some kind of <EM>web index</EM> which -is then used by a <EM>search engine</EM> to help locate information.</P> - -<P><CODE>robots.txt</CODE> provides a means to request that robots limit their -activities at the site, or more often than not, to leave the site alone.</P> - -<P>When the first robots were developed, they had a bad reputation for -sending hundreds/thousands of requests to each site, often resulting -in the site being overloaded. Things have improved dramatically since -then, thanks to <A -HREF="http://info.webcrawler.com/mak/projects/robots/guidelines.html"> -Guidelines for Robot Writers</A>, but even so, some robots may exhibit -unfriendly behavior which the webmaster isn't willing to tolerate, and -will want to stop.</P> - -<P>Another reason some webmasters want to block access to robots, is to -stop them indexing dynamic information. Many search engines will use the -data collected from your pages for months to come - not much use if your -serving stock quotes, news, weather reports or anything else that will be -stale by the time people find it in a search engine.</P> - -<P>If you decide to exclude robots completely, or just limit the areas -in which they can roam, create a <CODE>robots.txt</CODE> file; refer -to the <A HREF="http://info.webcrawler.com/mak/projects/robots/robots.html" ->robot information pages</A> provided by Martijn Koster for the syntax.</P> - -<HR> -<H2><A NAME="proxyssl">How to proxy SSL requests <EM>through</EM> - your non-SSL Apache server</A> - <BR> - <SMALL>(<EM>submitted by David Sedlock</EM>)</SMALL> -</H2> -<P> -SSL uses port 443 for requests for secure pages. If your browser just -sits there for a long time when you attempt to access a secure page -over your Apache proxy, then the proxy may not be configured to handle -SSL. You need to instruct Apache to listen on port 443 in addition to -any of the ports on which it is already listening: -</P> -<PRE> - Listen 80 - Listen 443 -</PRE> -<P> -Then set the security proxy in your browser to 443. That might be it! -</P> -<P> -If your proxy is sending requests to another proxy, then you may have -to set the directive ProxyRemote differently. Here are my settings: -</P> -<PRE> - ProxyRemote http://nicklas:80/ http://proxy.mayn.franken.de:8080 - ProxyRemote http://nicklas:443/ http://proxy.mayn.franken.de:443 -</PRE> -<P> -Requests on port 80 of my proxy <SAMP>nicklas</SAMP> are forwarded to -proxy<SAMP>.mayn.franken.de:8080</SAMP>, while requests on port 443 are -forwarded to <SAMP>proxy.mayn.franken.de:443</SAMP>. -If the remote proxy is not set up to -handle port 443, then the last directive can be left out. SSL requests -will only go over the first proxy. -</P> -<P> -Note that your Apache does NOT have to be set up to serve secure pages -with SSL. Proxying SSL is a different thing from using it. -</P> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/misc/index.html b/docs/manual/misc/index.html deleted file mode 100644 index 7d1013b2bd..0000000000 --- a/docs/manual/misc/index.html +++ /dev/null @@ -1,151 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache Miscellaneous Documentation</TITLE> - </HEAD> - - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Apache Miscellaneous Documentation</H1> - - <P> - Below is a list of additional documentation pages that apply to the - Apache web server development project. - </P> - <DL> - <DT><A - HREF="API.html" - >API</A> - </DT> - <DD>Description of Apache's Application Programming Interface. - </DD> - <DT><A - HREF="FAQ.html" - >FAQ</A> - </DT> - <DD>Frequently-Asked Questions concerning the Apache project and server. - </DD> - <DT><A - HREF="client_block_api.html" - >Reading Client Input in Apache 1.2</A> - </DT> - <DD>Describes differences between Apache 1.1 and 1.2 in how modules - read information from the client. - </DD> - <DT><A - HREF="compat_notes.html" - >Compatibility with NCSA</A> - </DT> - <DD>Notes about Apache's compatibility with the NCSA server. - </DD> - <DT><A HREF="custom_errordocs.html">How to use XSSI and Negotiation - for custom ErrorDocuments</A> - </DT> - <DD>Describes a solution which uses XSSI and negotiation - to custom-tailor the Apache ErrorDocuments to taste, adding the - advantage of returning internationalized versions of the error - messages depending on the client's language preferences. - </DD> - <DT><A HREF="descriptors.html">File Descriptor use in Apache</A> - <DD>Describes how Apache uses file descriptors and talks about various - limits imposed on the number of descriptors available by various - operating systems. - </DD> - <DT><A - HREF="fin_wait_2.html" - ><SAMP>FIN_WAIT_2</SAMP></A> - </DT> - <DD>A description of the causes of Apache processes going into the - <SAMP>FIN_WAIT_2</SAMP> state, and what you can do about it. - </DD> - <DT><A - HREF="howto.html" - >"How-To"</A> - </DT> - <DD>Instructions about how to accomplish some commonly-desired server - functionality changes. - </DD> - <DT><A HREF="HTTP_Features.tsv">HTTP Features list</A></DT> - <DD>A tab-separate table of HTTP features implemented and tested in Apache. - </DD> - <DT><A - HREF="known_client_problems.html" - >Known Client Problems</A> - </DT> - <DD>A list of problems in HTTP clients which can be mitigated by Apache. - </DD> - <DT><A - HREF="nopgp.html" - >No PGP</A> - </DT> - <DD>Why we took PEM and PGP support out of the base Apache distribution. - </DD> - <DT><A - HREF="perf-bsd44.html" - >Performance Notes (BSD 4.4)</A> - </DT> - <DD>Some notes about ways to improve/optimize Apache performance on - BSD 4.4 systems. - </DD> - <DT><A - HREF="perf-dec.html" - >Performance Notes (Digital UNIX)</A> - </DT> - <DD>Extracts of USENET postings describing how to optimize Apache - performance on Digital UNIX systems. - </DD> - <DT><A - HREF="perf-hp.html" - >Performance Notes (HPUX)</A> - </DT> - <DD>Email from an HP engineer on how to optimize HP-UX 10.20. - </DD> - <DT><A - HREF="perf.html" - >Performance Notes (General)</A> - </DT> - <DD>Some generic notes about how to improve the performance of your - machine/OS. - </DD> - <DT><A - HREF="perf-tuning.html" - >Performance Notes -- Apache Tuning</A> - </DT> - <DD>Notes about how to (run-time and compile-time) configure - Apache for highest performance. Notes explaining why Apache does - some things, and why it doesn't do other things (which make it - slower/faster). - </DD> - <DT><A - HREF="security_tips.html" - >Security Tips</A> - </DT> - <DD>Some "do"s - and "don't"s - for keeping your - Apache web site secure. - </DD> - <DT><A - HREF="vif-info.html" - >Virtual Hosts (IP-based)</A> - </DT> - <DD>Excerpts and notes about configuring and using Apache IP-based virtual - hosts. - </DD> - <DT><A - HREF="windoz_keepalive.html" - >Windows Bug with Web Keepalive</A> - </DT> - <DD>A brief description of a known problem with Microsoft Windows and - web sites accessed using keepalive connections. - </DD> - </DL> - - <!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/misc/known_client_problems.html b/docs/manual/misc/known_client_problems.html deleted file mode 100644 index 4d41fc7707..0000000000 --- a/docs/manual/misc/known_client_problems.html +++ /dev/null @@ -1,305 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache HTTP Server Project</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Known Problems in Clients</H1> - -<P>Over time the Apache Group has discovered or been notified of problems -with various clients which we have had to work around, or explain. -This document describes these problems and the workarounds available. -It's not arranged in any particular order. Some familiarity with the -standards is assumed, but not necessary. - -<P>For brevity, <EM>Navigator</EM> will refer to Netscape's Navigator -product (which in later versions was renamed "Communicator" and -various other names), and <EM>MSIE</EM> will refer to Microsoft's -Internet Explorer product. All trademarks and copyrights belong to -their respective companies. We welcome input from the various client -authors to correct inconsistencies in this paper, or to provide us with -exact version numbers where things are broken/fixed. - -<P>For reference, -<A HREF="ftp://ds.internic.net/rfc/rfc1945.txt">RFC1945</A> -defines HTTP/1.0, and -<A HREF="ftp://ds.internic.net/rfc/rfc2068.txt">RFC2068</A> -defines HTTP/1.1. Apache as of version 1.2 is an HTTP/1.1 server (with an -optional HTTP/1.0 proxy). - -<P>Various of these workarounds are triggered by environment variables. -The admin typically controls which are set, and for which clients, by using -<A HREF="../mod/mod_browser.html">mod_browser</A>. Unless otherwise -noted all of these workarounds exist in versions 1.2 and later. - -<H3><A NAME="trailing-crlf">Trailing CRLF on POSTs</A></H3> - -<P>This is a legacy issue. The CERN webserver required <CODE>POST</CODE> -data to have an extra <CODE>CRLF</CODE> following it. Thus many -clients send an extra <CODE>CRLF</CODE> that -is not included in the <CODE>Content-Length</CODE> of the request. -Apache works around this problem by eating any empty lines which -appear before a request. - -<H3><A NAME="broken-keepalive">Broken keepalive</A></H3> - -<P>Various clients have had broken implementations of <EM>keepalive</EM> -(persistent connections). In particular the Windows versions of -Navigator 2.0 get very confused when the server times out an -idle connection. The workaround is present in the default config files: -<BLOCKQUOTE><CODE> -BrowserMatch Mozilla/2 nokeepalive -</CODE></BLOCKQUOTE> -Note that this matches some earlier versions of MSIE, which began the -practice of calling themselves <EM>Mozilla</EM> in their user-agent -strings just like Navigator. - -<P>MSIE 4.0b2, which claims to support HTTP/1.1, does not properly -support keepalive when it is used on 301 or 302 (redirect) -responses. Unfortunately Apache's <CODE>nokeepalive</CODE> code -prior to 1.2.2 would not work with HTTP/1.1 clients. You must apply -<A -HREF="http://www.apache.org/dist/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch" ->this patch</A> to version 1.2.1. Then add this to your config: -<BLOCKQUOTE><CODE> -BrowserMatch "MSIE 4\.0b2;" nokeepalive -</CODE></BLOCKQUOTE> - -<H3><A NAME="force-response-1.0">Incorrect interpretation of -<CODE>HTTP/1.1</CODE> in response</A></H3> - -<P>To quote from section 3.1 of RFC1945: -<BLOCKQUOTE> -HTTP uses a "<MAJOR>.<MINOR>" numbering scheme to indicate versions -of the protocol. The protocol versioning policy is intended to allow -the sender to indicate the format of a message and its capacity for -understanding further HTTP communication, rather than the features -obtained via that communication. -</BLOCKQUOTE> -Since Apache is an HTTP/1.1 server, it indicates so as part of its -response. Many client authors mistakenly treat this part of the response -as an indication of the protocol that the response is in, and then refuse -to accept the response. - -<P>The first major indication of this problem was with AOL's proxy servers. -When Apache 1.2 went into beta it was the first wide-spread HTTP/1.1 -server. After some discussion, AOL fixed their proxies. In -anticipation of similar problems, the <CODE>force-response-1.0</CODE> -environment variable was added to Apache. When present Apache will -indicate "HTTP/1.0" in response to an HTTP/1.0 client, -but will not in any other way change the response. - -<P>The pre-1.1 Java Development Kit (JDK) that is used in many clients -(including Navigator 3.x and MSIE 3.x) exhibits this problem. As do some -of the early pre-releases of the 1.1 JDK. We think it is fixed in the -1.1 JDK release. In any event the workaround: -<BLOCKQUOTE><CODE> -BrowserMatch Java/1.0 force-response-1.0 <BR> -BrowserMatch JDK/1.0 force-response-1.0 -</CODE></BLOCKQUOTE> - -<P>RealPlayer 4.0 from Progressive Networks also exhibits this problem. -However they have fixed it in version 4.01 of the player, but version -4.01 uses the same <CODE>User-Agent</CODE> as version 4.0. The -workaround is still: -<BLOCKQUOTE><CODE> -BrowserMatch "RealPlayer 4.0" force-response-1.0 -</CODE></BLOCKQUOTE> - -<H3><A NAME="msie4.0b2">Requests use HTTP/1.1 but responses must be -in HTTP/1.0</A></H3> - -<P>MSIE 4.0b2 has this problem. Its Java VM makes requests in HTTP/1.1 -format but the responses must be in HTTP/1.0 format (in particular, it -does not understand <EM>chunked</EM> responses). The workaround -is to fool Apache into believing the request came in HTTP/1.0 format. -<BLOCKQUOTE><CODE> -BrowserMatch "MSIE 4\.0b2;" downgrade-1.0 force-response-1.0 -</CODE></BLOCKQUOTE> -This workaround is available in 1.2.2, and in a -<A -HREF="http://www.apache.org/dist/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch" ->patch</A> against 1.2.1. - -<H3><A NAME="257th-byte">Boundary problems with header parsing</A></H3> - -<P>All versions of Navigator from 2.0 through 4.0b2 (and possibly later) -have a problem if the trailing CRLF of the response header starts at -offset 256, 257 or 258 of the response. A BrowserMatch for this would -match on nearly every hit, so the workaround is enabled automatically -on all responses. The workaround implemented detects when this condition would -occur in a response and adds extra padding to the header to push the -trailing CRLF past offset 258 of the response. - -<H3><A NAME="boundary-string">Multipart responses and Quoted Boundary -Strings</A></H3> - -<P>On multipart responses some clients will not accept quotes (") -around the boundary string. The MIME standard recommends that -such quotes be used. But the clients were probably written based -on one of the examples in RFC2068, which does not include quotes. -Apache does not include quotes on its boundary strings to workaround -this problem. - -<H3><A NAME="byterange-requests">Byterange requests</A></H3> - -<P>A byterange request is used when the client wishes to retrieve a -portion of an object, not necessarily the entire object. There -was a very old draft which included these byteranges in the URL. -Old clients such as Navigator 2.0b1 and MSIE 3.0 for the MAC -exhibit this behaviour, and -it will appear in the servers' access logs as (failed) attempts to -retrieve a URL with a trailing ";xxx-yyy". Apache does not attempt -to implement this at all. - -<P>A subsequent draft of this standard defines a header -<CODE>Request-Range</CODE>, and a response type -<CODE>multipart/x-byteranges</CODE>. The HTTP/1.1 standard includes -this draft with a few fixes, and it defines the header -<CODE>Range</CODE> and type <CODE>multipart/byteranges</CODE>. - -<P>Navigator (versions 2 and 3) sends both <CODE>Range</CODE> and -<CODE>Request-Range</CODE> headers (with the same value), but does not -accept a <CODE>multipart/byteranges</CODE> response. The response must -be <CODE>multipart/x-byteranges</CODE>. As a workaround, if Apache -receives a <CODE>Request-Range</CODE> header it considers it "higher -priority" than a <CODE>Range</CODE> header and in response uses -<CODE>multipart/x-byteranges</CODE>. - -<P>The Adobe Acrobat Reader plugin makes extensive use of byteranges and -prior to version 3.01 supports only the <CODE>multipart/x-byterange</CODE> -response. Unfortunately there is no clue that it is the plugin -making the request. If the plugin is used with Navigator, the above -workaround works fine. But if the plugin is used with MSIE 3 (on -Windows) the workaround won't work because MSIE 3 doesn't give the -<CODE>Range-Request</CODE> clue that Navigator does. To workaround this, -Apache special cases "MSIE 3" in the <CODE>User-Agent</CODE> and serves -<CODE>multipart/x-byteranges</CODE>. Note that the necessity for this -with MSIE 3 is actually due to the Acrobat plugin, not due to the browser. - -<P>Netscape Communicator appears to not issue the non-standard -<CODE>Request-Range</CODE> header. When an Acrobat plugin prior to -version 3.01 is used with it, it will not properly understand byteranges. -The user must upgrade their Acrobat reader to 3.01. - -<H3><A NAME="cookie-merge"><CODE>Set-Cookie</CODE> header is -unmergeable</A></H3> - -<P>The HTTP specifications say that it is legal to merge headers with -duplicate names into one (separated by commas). Some browsers -that support Cookies don't like merged headers and prefer that each -<CODE>Set-Cookie</CODE> header is sent separately. When parsing the -headers returned by a CGI, Apache will explicitly avoid merging any -<CODE>Set-Cookie</CODE> headers. - -<H3><A NAME="gif89-expires"><CODE>Expires</CODE> headers and GIF89A -animations</A></H3> - -<P>Navigator versions 2 through 4 will erroneously re-request -GIF89A animations on each loop of the animation if the first -response included an <CODE>Expires</CODE> header. This happens -regardless of how far in the future the expiry time is set. There -is no workaround supplied with Apache, however there are hacks for <A -HREF="http://www.arctic.org/~dgaudet/patches/apache-1.2-gif89-expires-hack.patch">1.2</A> -and for <A -HREF="http://www.arctic.org/~dgaudet/patches/apache-1.3-gif89-expires-hack.patch">1.3</A>. - -<H3><A NAME="no-content-length"><CODE>POST</CODE> without -<CODE>Content-Length</CODE></A></H3> - -<P>In certain situations Navigator 3.01 through 3.03 appear to incorrectly -issue a POST without the request body. There is no -known workaround. It has been fixed in Navigator 3.04, Netscapes -provides some -<A HREF="http://help.netscape.com/kb/client/971014-42.html">information</A>. -There's also -<A HREF="http://www.arctic.org/~dgaudet/apache/no-content-length/"> -some information</A> about the actual problem. - -<H3><A NAME="jdk-12-bugs">JDK 1.2 betas lose parts of responses.</A></H3> - -<P>The http client in the JDK1.2beta2 and beta3 will throw away the first part of -the response body when both the headers and the first part of the body are sent -in the same network packet AND keep-alive's are being used. If either condition -is not met then it works fine. - -<P>See also Bug-ID's 4124329 and 4125538 at the java developer connection. - -<P>If you are seeing this bug yourself, you can add the following BrowserMatch -directive to work around it: - -<BLOCKQUOTE><CODE> -BrowserMatch "Java1\.2beta[23]" nokeepalive -</CODE></BLOCKQUOTE> - -<P>We don't advocate this though since bending over backwards for beta software -is usually not a good idea; ideally it gets fixed, new betas or a final release -comes out, and no one uses the broken old software anymore. In theory. - -<H3><A NAME="content-type-persistence"><CODE>Content-Type</CODE> change -is not noticed after reload</A></H3> - -<P>Navigator (all versions?) will cache the <CODE>content-type</CODE> -for an object "forever". Using reload or shift-reload will not cause -Navigator to notice a <CODE>content-type</CODE> change. The only -work-around is for the user to flush their caches (memory and disk). By -way of an example, some folks may be using an old <CODE>mime.types</CODE> -file which does not map <CODE>.htm</CODE> to <CODE>text/html</CODE>, -in this case Apache will default to sending <CODE>text/plain</CODE>. -If the user requests the page and it is served as <CODE>text/plain</CODE>. -After the admin fixes the server, the user will have to flush their caches -before the object will be shown with the correct <CODE>text/html</CODE> -type. - -<h3><a name="msie-cookie-y2k">MSIE Cookie problem with expiry date in -the year 2000</a></h3> - -<p>MSIE versions 3.00 and 3.02 (without the Y2K patch) do not handle -cookie expiry dates in the year 2000 properly. Years after 2000 and -before 2000 work fine. This is fixed in IE4.01 service pack 1, and in -the Y2K patch for IE3.02. Users should avoid using expiry dates in the -year 2000. - -<h3><a name="lynx-negotiate-trans">Lynx incorrectly asking for transparent -content negotiation</a></h3> - -<p>The Lynx browser versions 2.7 and 2.8 send a "negotiate: trans" header -in their requests, which is an indication the browser supports transparent -content negotiation (TCN). However the browser does not support TCN. -As of version 1.3.4, Apache supports TCN, and this causes problems with -these versions of Lynx. As a workaround future versions of Apache will -ignore this header when sent by the Lynx client. - -<h3><a name="ie40-vary">MSIE 4.0 mishandles Vary response header</a></h3> - -<p>MSIE 4.0 does not handle a Vary header properly. The Vary header is -generated by mod_rewrite in apache 1.3. The result is an error from MSIE -saying it cannot download the requested file. There are more details -in <a href="http://bugs.apache.org/index/full/4118">PR#4118</a>. -</P> -<P> -A workaround is to add the following to your server's configuration -files: -</P> -<PRE> - BrowserMatch "MSIE 4\.0" force-no-vary -</PRE> -<P> -(This workaround is only available with releases <STRONG>after</STRONG> -1.3.6 of the Apache Web server.) -</P> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/misc/perf-tuning.html b/docs/manual/misc/perf-tuning.html deleted file mode 100644 index 46995c9ecc..0000000000 --- a/docs/manual/misc/perf-tuning.html +++ /dev/null @@ -1,871 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> - <TITLE>Apache Performance Notes</TITLE> -</HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<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 0, which -means that there is no limit to the number of requests handled -per child. If your configuration currently has this set to some -very low number, such as 30, you may want to bump this up significantly. -If you are running SunOS or an old version of Solaris, limit this -to 10000 or so because of memory leaks. - -<P>When keep-alives are in use, children will be kept busy -doing nothing waiting for more requests on the already open -connection. The default <CODE>KeepAliveTimeout</CODE> of -15 seconds attempts to minimize this effect. The tradeoff -here is between network bandwidth and server resources. -In no event should you raise this above about 60 seconds, as -<A HREF="http://www.research.digital.com/wrl/techreports/abstracts/95.4.html" ->most of the benefits are lost</A>. - -<H3>Compile-Time Configuration Issues</H3> - -<H4>mod_status and ExtendedStatus On</H4> - -<P>If you include <CODE>mod_status</CODE> -and you also set <CODE>ExtendedStatus On</CODE> when building and running -Apache, then on every request Apache will perform two calls to -<CODE>gettimeofday(2)</CODE> (or <CODE>times(2)</CODE> depending -on your operating system), and (pre-1.3) several extra calls to -<CODE>time(2)</CODE>. This is all done so that the status report -contains timing indications. For highest performance, set -<CODE>ExtendedStatus off</CODE> (which is the default). - -<H4>accept Serialization - multiple sockets</H4> - -<P>This discusses a shortcoming in the Unix socket API. -Suppose your -web server uses multiple <CODE>Listen</CODE> statements to listen on -either multiple ports or multiple addresses. In order to test each -socket to see if a connection is ready Apache uses <CODE>select(2)</CODE>. -<CODE>select(2)</CODE> indicates that a socket has <EM>zero</EM> or -<EM>at least one</EM> connection waiting on it. Apache's model includes -multiple children, and all the idle ones test for new connections at the -same time. A naive implementation looks something like this -(these examples do not match the code, they're contrived for -pedagogical purposes): - -<BLOCKQUOTE><PRE> - 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 <EM>blocked</EM> in -<CODE>accept</CODE>. -This effectively locks those children into serving requests from that -one socket and no other sockets, and they'll be stuck there until enough -new requests appear on that socket to wake them all up. -This starvation problem was first documented in -<A HREF="http://bugs.apache.org/index/full/467">PR#467</A>. There -are at least two solutions. - -<P>One solution is to make the sockets non-blocking. In this case the -<CODE>accept</CODE> won't block the children, and they will be allowed -to continue immediately. But this wastes CPU time. Suppose you have -ten idle children in <CODE>select</CODE>, and one connection arrives. -Then nine of those children will wake up, try to <CODE>accept</CODE> the -connection, fail, and loop back into <CODE>select</CODE>, accomplishing -nothing. Meanwhile none of those children are servicing requests that -occurred on other sockets until they get back up to the <CODE>select</CODE> -again. Overall this solution does not seem very fruitful unless you -have as many idle CPUs (in a multiprocessor box) as you have idle children, -not a very likely situation. - -<P>Another solution, the one used by Apache, is to serialize entry into -the inner loop. The loop looks like this (differences highlighted): - -<BLOCKQUOTE><PRE> - for (;;) { - <STRONG>accept_mutex_on ();</STRONG> - for (;;) { - fd_set accept_fds; - - FD_ZERO (&accept_fds); - for (i = first_socket; i <= last_socket; ++i) { - FD_SET (i, &accept_fds); - } - rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL); - if (rc < 1) continue; - new_connection = -1; - for (i = first_socket; i <= last_socket; ++i) { - if (FD_ISSET (i, &accept_fds)) { - new_connection = accept (i, NULL, NULL); - if (new_connection != -1) break; - } - } - if (new_connection != -1) break; - } - <STRONG>accept_mutex_off ();</STRONG> - process the new_connection; - } -</PRE></BLOCKQUOTE> - -<A NAME="serialize">The functions</A> -<CODE>accept_mutex_on</CODE> and <CODE>accept_mutex_off</CODE> -implement a mutual exclusion semaphore. Only one child can have the -mutex at any time. There are several choices for implementing these -mutexes. The choice is defined in <CODE>src/conf.h</CODE> (pre-1.3) or -<CODE>src/include/ap_config.h</CODE> (1.3 or later). Some architectures -do not have any locking choice made, on these architectures it is unsafe -to use multiple <CODE>Listen</CODE> directives. - -<DL> -<DT><CODE>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 (<EM>i.e.</EM>, all CGIs unless you use something -like suexec or cgiwrapper). For these reasons this method is not used -on any architecture except IRIX (where the previous two are prohibitively -expensive on most IRIX boxes). - -<DT><CODE>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_PTHREAD_SERIALIZED_ACCEPT</CODE> -<DD>(1.3 or later) This method uses POSIX mutexes and should work on -any architecture implementing the full POSIX threads specification, -however appears to only work on Solaris (2.5 or later), and even then -only in certain configurations. If you experiment with this you should -watch out for your server hanging and not responding. Static content -only servers may work just fine. -</DL> - -<P>If your system has another method of serialization which isn't in the -above list then it may be worthwhile adding code for it (and submitting -a patch back to Apache). - -<P>Another solution that has been considered but never implemented is -to partially serialize the loop -- that is, let in a certain number -of processes. This would only be of interest on multiprocessor boxes -where it's possible multiple children could run simultaneously, and the -serialization actually doesn't take advantage of the full bandwidth. -This is a possible area of future investigation, but priority remains -low because highly parallel web servers are not the norm. - -<P>Ideally you should run servers without multiple <CODE>Listen</CODE> -statements if you want the highest performance. But read on. - -<H4>accept Serialization - single socket</H4> - -<P>The above is fine and dandy for multiple socket servers, but what -about single socket servers? In theory they shouldn't experience -any of these same problems because all children can just block in -<CODE>accept(2)</CODE> until a connection arrives, and no starvation -results. In practice this hides almost the same "spinning" behaviour -discussed above in the non-blocking solution. The way that most TCP -stacks are implemented, the kernel actually wakes up all processes blocked -in <CODE>accept</CODE> when a single connection arrives. One of those -processes gets the connection and returns to user-space, the rest spin in -the kernel and go back to sleep when they discover there's no connection -for them. This spinning is hidden from the user-land code, but it's -there nonetheless. This can result in the same load-spiking wasteful -behaviour that a non-blocking solution to the multiple sockets case can. - -<P>For this reason we have found that many architectures behave more -"nicely" if we serialize even the single socket case. So this is -actually the default in almost all cases. Crude experiments under -Linux (2.0.30 on a dual Pentium pro 166 w/128Mb RAM) have shown that -the serialization of the single socket case causes less than a 3% -decrease in requests per second over unserialized single-socket. -But unserialized single-socket showed an extra 100ms latency on -each request. This latency is probably a wash on long haul lines, -and only an issue on LANs. If you want to override the single socket -serialization you can define <CODE>SINGLE_LISTEN_UNSERIALIZED_ACCEPT</CODE> -and then single-socket servers will not serialize at all. - -<H4>Lingering Close</H4> - -<P>As discussed in -<A - HREF="http://www.ics.uci.edu/pub/ietf/http/draft-ietf-http-connection-00.txt" ->draft-ietf-http-connection-00.txt</A> section 8, -in order for an HTTP server to <STRONG>reliably</STRONG> implement the protocol -it needs to shutdown each direction of the communication independently -(recall that a TCP connection is bi-directional, each half is independent -of the other). This fact is often overlooked by other servers, but -is correctly implemented in Apache as of 1.2. - -<P>When this feature was added to Apache it caused a flurry of -problems on various versions of Unix because of a shortsightedness. -The TCP specification does not state that the FIN_WAIT_2 state has a -timeout, but it doesn't prohibit it. On systems without the timeout, -Apache 1.2 induces many sockets stuck forever in the FIN_WAIT_2 state. -In many cases this can be avoided by simply upgrading to the latest -TCP/IP patches supplied by the vendor, in cases where the vendor has -never released patches (<EM>i.e.</EM>, SunOS4 -- although folks with a source -license can patch it themselves) we have decided to disable this feature. - -<P>There are two ways of accomplishing this. One is the -socket option <CODE>SO_LINGER</CODE>. But as fate would have it, -this has never been implemented properly in most TCP/IP stacks. Even -on those stacks with a proper implementation (<EM>i.e.</EM>, Linux 2.0.31) this -method proves to be more expensive (cputime) than the next solution. - -<P>For the most part, Apache implements this in a function called -<CODE>lingering_close</CODE> (in <CODE>http_main.c</CODE>). The -function looks roughly like this: - -<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>USE_MMAP_SCOREBOARD</CODE> or -<CODE>USE_SHMGET_SCOREBOARD</CODE>. Defining one of those two (as -well as their companions <CODE>HAVE_MMAP</CODE> and <CODE>HAVE_SHMGET</CODE> -respectively) enables the supplied shared memory code. If your system has -another type of shared memory, edit the file <CODE>src/main/http_main.c</CODE> -and add the hooks necessary to use it in Apache. (Send us back a patch -too please.) - -<P>Historical note: The Linux port of Apache didn't start to use -shared memory until version 1.2 of Apache. This oversight resulted -in really poor and unreliable behaviour of earlier versions of Apache -on Linux. - -<H4><CODE>DYNAMIC_MODULE_LIMIT</CODE></H4> - -<P>If you have no intention of using dynamically loaded modules -(you probably don't if you're reading this and tuning your -server for every last ounce of performance) then you should add -<CODE>-DDYNAMIC_MODULE_LIMIT=0</CODE> when building your server. -This will save RAM that's allocated only for supporting dynamically -loaded modules. - -<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>SINGLE_LISTEN_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 -(<EM>i.e.</EM>, due to a timeout or because of a maximum number of requests). -But, if the connection is closed before the first response has been -received the typical browser will display a "document contains no data" -dialogue (or a broken image icon). This is done on the assumption that -the server is broken in some way (or maybe too overloaded to respond -at all). So Apache tries to avoid ever deliberately closing the connection -before it has sent a single response. This is the cause of those -<CODE>SIGUSR1</CODE> manipulations. - -<P>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. Or you can use a method which moves the time into shared memory, -see the <A HREF="#patches">patches section below</A>. - -<P>As described earlier, <CODE>ExtendedStatus On</CODE> causes two -<CODE>gettimeofday</CODE> calls and a call to <CODE>times</CODE>: - -<BLOCKQUOTE><PRE> -gettimeofday({873959960, 404935}, NULL) = 0 -... -gettimeofday({873959960, 417742}, NULL) = 0 -times({tms_utime=5, tms_stime=0, tms_cutime=0, tms_cstime=0}) = 446747 -</PRE></BLOCKQUOTE> - -These can be removed by setting <CODE>ExtendedStatus Off</CODE> (which -is the default). - -<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://www.bitmover.com/lmbench/">lmbench</A> you -can determine the optimal setting for your environment. - -<P>You may also wish to experiment with <CODE>MMAP_SEGMENT_SIZE</CODE> -(default 32768) which determines the maximum number of bytes that -will be written at a time from mmap()d files. Apache only resets the -client's <CODE>Timeout</CODE> in between write()s. So setting this -large may lock out low bandwidth clients unless you also increase the -<CODE>Timeout</CODE>. - -<P>It may even be the case that <CODE>mmap</CODE> isn't -used on your architecture, if so then defining <CODE>USE_MMAP_FILES</CODE> -and <CODE>HAVE_MMAP</CODE> might work (if it works then report back to us). - -<P>Apache does its best to avoid copying bytes around in memory. The -first write of any request typically is turned into a <CODE>writev</CODE> -which combines both the headers and the first hunk of data: - -<BLOCKQUOTE><PRE> -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. (<EM>i.e.</EM>, 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>-DSINGLE_LISTEN_UNSERIALIZED_ACCEPT -DBUFFERED_LOGS</CODE> and -<CODE>ExtendedStatus Off</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><A NAME="patches">Appendix: Patches Available</A></H3> - -There are -<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/"> -several performance patches available for 1.3.</A> But they may -be slightly out of date by the time Apache 1.3.0 has been released, -it shouldn't be difficult for someone with a little C knowledge to -update them. In particular: - -<UL> -<LI>A -<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/shared_time.patch" ->patch</A> to remove all <CODE>time(2)</CODE> system calls. -<LI>A -<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/mod_include_speedups.patch" ->patch</A> to remove various system calls from <CODE>mod_include</CODE>, -these calls are used by few sites but required for backwards compatibility. -<LI>A -<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/top_fuel.patch" ->patch</A> which integrates the above two plus a few other speedups at the -cost of removing some functionality. -</UL> - -<H3>Appendix: The Pre-Forking Model</H3> - -<P>Apache (on Unix) is a <EM>pre-forking</EM> model server. The -<EM>parent</EM> process is responsible only for forking <EM>child</EM> -processes, it does not serve any requests or service any network -sockets. The child processes actually process connections, they serve -multiple connections (one at a time) before dying. -The parent spawns new or kills off old -children in response to changes in the load on the server (it does so -by monitoring a scoreboard which the children keep up to date). - -<P>This model for servers offers a robustness that other models do -not. In particular, the parent code is very simple, and with a high -degree of confidence the parent will continue to do its job without -error. The children are complex, and when you add in third party -code via modules, you risk segmentation faults and other forms of -corruption. Even should such a thing happen, it only affects one -connection and the server continues serving requests. The parent -quickly replaces the dead child. - -<P>Pre-forking is also very portable across dialects of Unix. -Historically this has been an important goal for Apache, and it continues -to remain so. - -<P>The pre-forking model comes under criticism for various -performance aspects. Of particular concern are the overhead -of forking a process, the overhead of context switches between -processes, and the memory overhead of having multiple processes. -Furthermore it does not offer as many opportunities for data-caching -between requests (such as a pool of <CODE>mmapped</CODE> files). -Various other models exist and extensive analysis can be found in the -<A HREF="http://www.cs.wustl.edu/~jxh/research/research.html"> papers -of the JAWS project</A>. In practice all of these costs vary drastically -depending on the operating system. - -<P>Apache's core code is already multithread aware, and Apache version -1.3 is multithreaded on NT. There have been at least two other experimental -implementations of threaded Apache, one using the 1.3 code base on DCE, -and one using a custom user-level threads package and the 1.0 code base, -neither are available publically. There is also an experimental port of -Apache 1.3 to <A HREF="http://www.mozilla.org/docs/refList/refNSPR/"> -Netscape's Portable Run Time</A>, which -<A HREF="http://www.arctic.org/~dgaudet/apache/2.0/">is available</A> -(but you're encouraged to join the -<A HREF="http://dev.apache.org/mailing-lists">new-httpd mailing list</A> -if you intend to use it). -Part of our redesign for version 2.0 -of Apache will include abstractions of the server model so that we -can continue to support the pre-forking model, and also support various -threaded models. - -</BODY> -</HTML> diff --git a/docs/manual/misc/security_tips.html b/docs/manual/misc/security_tips.html deleted file mode 100644 index f5b337e805..0000000000 --- a/docs/manual/misc/security_tips.html +++ /dev/null @@ -1,232 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache HTTP Server: Security Tips</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Security Tips for Server Configuration</H1> - -<HR> - -<P>Some hints and tips on security issues in setting up a web server. Some of -the suggestions will be general, others specific to Apache. - -<HR> - -<H2><A NAME="serverroot">Permissions on ServerRoot Directories</A></H2> -<P>In typical operation, Apache is started by the root -user, and it switches to the user defined by the <A -HREF="../mod/core.html#user"><STRONG>User</STRONG></A> directive to serve hits. -As is the case with any command that root executes, you must take care -that it is protected from modification by non-root users. Not only -must the files themselves be writeable only by root, but so must the -directories, and parents of all directories. For example, if you -choose to place ServerRoot in <CODE>/usr/local/apache</CODE> then it is -suggested that you create that directory as root, with commands -like these: - -<BLOCKQUOTE><PRE> - mkdir /usr/local/apache - cd /usr/local/apache - mkdir bin conf logs - chown 0 . bin conf logs - chgrp 0 . bin conf logs - chmod 755 . bin conf logs -</PRE></BLOCKQUOTE> - -It is assumed that /, /usr, and /usr/local are only modifiable by root. -When you install the httpd executable, you should ensure that it is -similarly protected: - -<BLOCKQUOTE><PRE> - cp httpd /usr/local/apache/bin - chown 0 /usr/local/apache/bin/httpd - chgrp 0 /usr/local/apache/bin/httpd - chmod 511 /usr/local/apache/bin/httpd -</PRE></BLOCKQUOTE> - -<P>You can create an htdocs subdirectory which is modifiable by other -users -- since root never executes any files out of there, and shouldn't -be creating files in there. - -<P>If you allow non-root users to modify any files that root either -executes or writes on then you open your system to root compromises. -For example, someone could replace the httpd binary so that the next -time you start it, it will execute some arbitrary code. If the logs -directory is writeable (by a non-root user), someone -could replace a log file with a symlink to some other system file, -and then root might overwrite that file with arbitrary data. If the -log files themselves are writeable (by a non-root user), then someone -may be able to overwrite the log itself with bogus data. -<P> -<HR> -<H2>Server Side Includes</H2> -<P>Server side includes (SSI) can be configured so that users can execute -arbitrary programs on the server. That thought alone should send a shiver -down the spine of any sys-admin.<P> - -One solution is to disable that part of SSI. To do that you use the -IncludesNOEXEC option to the <A HREF="../mod/core.html#options">Options</A> -directive.<P> - -<HR> - -<H2>Non Script Aliased CGI</H2> -<P>Allowing users to execute <STRONG>CGI</STRONG> scripts in any directory -should only -be considered if; -<OL> - <LI>You trust your users not to write scripts which will deliberately or -accidentally expose your system to an attack. - <LI>You consider security at your site to be so feeble in other areas, as to -make one more potential hole irrelevant. - <LI>You have no users, and nobody ever visits your server. -</OL><P> -<HR> - -<H2>Script Alias'ed CGI</H2> -<P>Limiting <STRONG>CGI</STRONG> to special directories gives the admin -control over -what goes into those directories. This is inevitably more secure than -non script aliased CGI, but <STRONG>only if users with write access to the -directories are trusted</STRONG> or the admin is willing to test each new CGI -script/program for potential security holes.<P> - -Most sites choose this option over the non script aliased CGI approach.<P> - -<HR> -<H2>CGI in general</H2> -<P>Always remember that you must trust the writers of the CGI script/programs -or your ability to spot potential security holes in CGI, whether they were -deliberate or accidental.<P> - -All the CGI scripts will run as the same user, so they have potential to -conflict (accidentally or deliberately) with other scripts <EM>e.g.</EM> -User A hates User B, so he writes a script to trash User B's CGI -database. One program which can be used to allow scripts to run -as different users is <A HREF="../suexec.html">suEXEC</A> which is -included with Apache as of 1.2 and is called from special hooks in -the Apache server code. Another popular way of doing this is with -<A HREF="http://wwwcgi.umr.edu/~cgiwrap/">CGIWrap</A>. <P> - -<HR> - - -<H2>Stopping users overriding system wide settings...</H2> -<P>To run a really tight ship, you'll want to stop users from setting -up <CODE>.htaccess</CODE> files which can override security features -you've configured. Here's one way to do it...<P> - -In the server configuration file, put -<BLOCKQUOTE><CODE> -<Directory /> <BR> -AllowOverride None <BR> -Options None <BR> -allow from all <BR> -</Directory> <BR> -</CODE></BLOCKQUOTE> - -Then setup for specific directories<P> - -This stops all overrides, Includes and accesses in all directories apart -from those named.<P> -<HR> -<H2> - Protect server files by default -</H2> -<P> -One aspect of Apache which is occasionally misunderstood is the feature -of default access. That is, unless you take steps to change it, if the -server can find its way to a file through normal URL mapping rules, it -can serve it to clients. -</P> -<P> -For instance, consider the following example: -</P> -<OL> - <LI><SAMP># cd /; ln -s / public_html</SAMP> - </LI> - <LI>Accessing <SAMP>http://localhost/~root/</SAMP> - </LI> -</OL> -<P> -This would allow clients to walk through the entire filesystem. To work -around this, add the following block to your server's configuration: -</P> -<PRE> - <Directory /> - Order deny,allow - Deny from all - </Directory> -</PRE> -<P> -This will forbid default access to filesystem locations. Add -appropriate -<A - HREF="../mod/core.html#directory" -><SAMP><Directory></SAMP></A> -blocks to allow access only -in those areas you wish. For example, -</P> -<PRE> - <Directory /usr/users/*/public_html> - Order deny,allow - Allow from all - </Directory> - <Directory /usr/local/httpd> - Order deny,allow - Allow from all - </Directory> -</PRE> -<P> -Pay particular attention to the interactions of -<A - HREF="../mod/core.html#location" -><SAMP><Location></SAMP></A> -and -<A - HREF="../mod/core.html#directory" -><SAMP><Directory></SAMP></A> -directives; for instance, even if <SAMP><Directory /></SAMP> -denies access, a <SAMP><Location /></SAMP> directive might -overturn it. -</P> -<P> -Also be wary of playing games with the -<A - HREF="../mod/mod_userdir.html#userdir" ->UserDir</A> -directive; setting it to something like <SAMP>"./"</SAMP> -would have the same effect, for root, as the first example above. -If you are using Apache 1.3 or above, we strongly recommend that you -include the following line in your server configuration files: -</P> -<DL> - <DD><SAMP>UserDir disabled root</SAMP> - </DD> -</DL> - -<HR> -<P>Please send any other useful security tips to The Apache Group -by filling out a -<A HREF="http://www.apache.org/bug_report.html">problem report</A>. -If you are confident you have found a security bug in the Apache -source code itself, <A -HREF="http://www.apache.org/security_report.html">please let us -know</A>. - -<P> -<HR> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/core.html b/docs/manual/mod/core.html deleted file mode 100644 index 0aa8ad84ad..0000000000 --- a/docs/manual/mod/core.html +++ /dev/null @@ -1,3295 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache Core Features</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Apache Core Features</H1> -<P> -These configuration parameters control the core Apache features, and are -always available. -</P> -<H2>Directives</H2> -<UL> -<LI><A HREF="#accessconfig">AccessConfig</A> -<LI><A HREF="#accessfilename">AccessFileName</A> -<LI><A HREF="#addmodule">AddModule</A> -<LI><A HREF="#allowoverride">AllowOverride</A> -<LI><A HREF="#authname">AuthName</A> -<LI><A HREF="#authtype">AuthType</A> -<LI><A HREF="#bindaddress">BindAddress</A> -<LI><A HREF="#bs2000account">BS2000Account</A> -<LI><A HREF="#clearmodulelist">ClearModuleList</A> -<LI><A HREF="#contentdigest">ContentDigest</A> -<LI><A HREF="#coredumpdirectory">CoreDumpDirectory</A> -<LI><A HREF="#defaulttype">DefaultType</A> -<LI><A HREF="#directory"><Directory></A> -<LI><A HREF="#directorymatch"><DirectoryMatch></A> -<LI><A HREF="#documentroot">DocumentRoot</A> -<LI><A HREF="#errordocument">ErrorDocument</A> -<LI><A HREF="#errorlog">ErrorLog</A> -<LI><A HREF="#files"><Files></A> -<LI><A HREF="#filesmatch"><FilesMatch></A> -<LI><A HREF="#group">Group</A> -<LI><A HREF="#hostnamelookups">HostNameLookups</A> -<LI><A HREF="#identitycheck">IdentityCheck</A> -<LI><A HREF="#ifdefine"><IfDefine></A> -<LI><A HREF="#ifmodule"><IfModule></A> -<LI><A HREF="#include">Include</A> -<LI><A HREF="#keepalive">KeepAlive</A> -<LI><A HREF="#keepalivetimeout">KeepAliveTimeout</A> -<LI><A HREF="#limit"><Limit></A> -<LI><A HREF="#limitexcept"><LimitExcept></A> -<LI><A HREF="#limitrequestbody">LimitRequestBody</A> -<LI><A HREF="#limitrequestfields">LimitRequestFields</A> -<LI><A HREF="#limitrequestfieldsize">LimitRequestFieldsize</A> -<LI><A HREF="#limitrequestline">LimitRequestLine</A> -<LI><A HREF="#listen">Listen</A> -<LI><A HREF="#listenbacklog">ListenBacklog</A> -<LI><A HREF="#location"><Location></A> -<LI><A HREF="#locationmatch"><LocationMatch></A> -<LI><A HREF="#lockfile">LockFile</A> -<LI><A HREF="#loglevel">LogLevel</A> -<LI><A HREF="#maxclients">MaxClients</A> -<LI><A HREF="#maxkeepaliverequests">MaxKeepAliveRequests</A> -<LI><A HREF="#maxrequestsperchild">MaxRequestsPerChild</A> -<LI><A HREF="#maxspareservers">MaxSpareServers</A> -<LI><A HREF="#minspareservers">MinSpareServers</A> -<LI><A HREF="#namevirtualhost">NameVirtualHost</A> -<LI><A HREF="#options">Options</A> -<LI><A HREF="#pidfile">PidFile</A> -<LI><A HREF="#port">Port</A> -<LI><A HREF="#require">require</A> -<LI><A HREF="#resourceconfig">ResourceConfig</A> -<LI><A HREF="#rlimitcpu">RLimitCPU</A> -<LI><A HREF="#rlimitmem">RLimitMEM</A> -<LI><A HREF="#rlimitnproc">RLimitNPROC</A> -<LI><A HREF="#satisfy">Satisfy</A> -<LI><A HREF="#scoreboardfile">ScoreBoardFile</A> -<LI><A HREF="#scriptinterpretersource">ScriptInterpreterSource</A> -<LI><A HREF="#sendbuffersize">SendBufferSize</A> -<LI><A HREF="#serveradmin">ServerAdmin</A> -<LI><A HREF="#serveralias">ServerAlias</A> -<LI><A HREF="#servername">ServerName</A> -<LI><A HREF="#serverpath">ServerPath</A> -<LI><A HREF="#serverroot">ServerRoot</A> -<LI><A HREF="#serversignature">ServerSignature</A> -<LI><A HREF="#servertokens">ServerTokens</A> -<LI><A HREF="#servertype">ServerType</A> -<LI><A HREF="#startservers">StartServers</A> -<LI><A HREF="#threadsperchild">ThreadsPerChild</A> -<LI><A HREF="#timeout">TimeOut</A> -<LI><A HREF="#usecanonicalname">UseCanonicalName</A> -<LI><A HREF="#user">User</A> -<LI><A HREF="#virtualhost"><VirtualHost></A> -</UL> -<HR> - -<H2><A NAME="accessconfig">AccessConfig directive</A></H2> -<!--%plaintext <?INDEX {\tt AccessConfig} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AccessConfig <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AccessConfig conf/access.conf</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -The server will read this file for more directives after reading the -<A HREF="#resourceconfig">ResourceConfig</A> file. <EM>Filename</EM> is -relative to the <A HREF="#serverroot">ServerRoot</A>. -This feature can be disabled using: -<BLOCKQUOTE><CODE>AccessConfig /dev/null</CODE></BLOCKQUOTE> -Historically, this file only contained -<A HREF="#directory"><Directory></A> sections; in fact it can now -contain any server directive allowed in the <EM>server config</EM> context. -<P><HR> - -<H2><A NAME="accessfilename">AccessFileName directive</A></H2> -<!--%plaintext <?INDEX {\tt AccessFileName} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AccessFileName <EM>filename filename ...</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AccessFileName .htaccess</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> AccessFileName can accept more than -one filename only in Apache 1.3 and later<P> - -When returning a document to the client the server looks for the first existing -access control file from this list of names in every directory of the path to -the document, if access control files are enabled for that directory. - -For example: -<BLOCKQUOTE><CODE>AccessFileName .acl</CODE></BLOCKQUOTE> -before returning the document /usr/local/web/index.html, the -server will read /.acl, /usr/.acl, /usr/local/.acl and /usr/local/web/.acl -for directives, unless they have been disabled with -<BLOCKQUOTE><CODE> -<Directory /><BR> -AllowOverride None<BR> -</Directory></CODE></BLOCKQUOTE><P><HR> - -<H2><A NAME="addmodule">AddModule directive</A></H2> -<!--%plaintext <?INDEX {\tt AddModule} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddModule <EM>module module ...</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> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> AddModule is only available in -Apache 1.2 and later<P> - -The server can have modules compiled in which are not actively in use. -This directive can be used to enable the use of those modules. The -server comes with a pre-loaded list of active modules; this list can -be cleared with the <A HREF="#clearmodulelist">ClearModuleList</A> -directive.<P><HR> - -<H2><A NAME="allowoverride">AllowOverride directive</A></H2> -<!--%plaintext <?INDEX {\tt AllowOverride} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AllowOverride <EM>override override ...</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AllowOverride All</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -When the server finds an .htaccess file (as specified by -<A HREF="#accessfilename">AccessFileName</A>) it needs to know which -directives declared in that file can override earlier access information.<P> - -<EM>Override</EM> can be set to <CODE>None</CODE>, in which case the server -will not read the file, <CODE>All</CODE> in which case the server will -allow all the directives, or one or more of the following: -<DL> -<DT>AuthConfig -<DD> -<!--%plaintext <?INDEX {\tt AuthConfig} override> --> -Allow use of the authorization directives -(<A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A>, -<A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A>, -<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A>, -<A HREF="#authname">AuthName</A>, <A HREF="#authtype">AuthType</A>, -<A HREF="mod_auth.html#authuserfile">AuthUserFile</A>, -<A HREF="#require">require</A>, <EM>etc.</EM>). -<DT>FileInfo -<DD> -<!--%plaintext <?INDEX {\tt FileInfo} override> --> -Allow use of the directives controlling document types -(<A HREF="mod_mime.html#addencoding">AddEncoding</A>, -<A HREF="mod_mime.html#addlanguage">AddLanguage</A>, -<A HREF="mod_mime.html#addtype">AddType</A>, -<A HREF="#defaulttype">DefaultType</A>, -<A HREF="#errordocument">ErrorDocument</A>, -<A HREF="mod_negotiation.html#languagepriority">LanguagePriority</A>, <EM>etc.</EM>). -<DT>Indexes -<DD> -<!--%plaintext <?INDEX {\tt Indexes} override> --> -Allow use of the directives controlling directory indexing -(<A HREF="mod_autoindex.html#adddescription">AddDescription</A>, -<A HREF="mod_autoindex.html#addicon">AddIcon</A>, -<A HREF="mod_autoindex.html#addiconbyencoding">AddIconByEncoding</A>, -<A HREF="mod_autoindex.html#addiconbytype">AddIconByType</A>, -<A HREF="mod_autoindex.html#defaulticon">DefaultIcon</A>, -<A HREF="mod_dir.html#directoryindex">DirectoryIndex</A>, -<A HREF="mod_autoindex.html#fancyindexing">FancyIndexing</A>, -<A HREF="mod_autoindex.html#headername">HeaderName</A>, -<A HREF="mod_autoindex.html#indexignore">IndexIgnore</A>, -<A HREF="mod_autoindex.html#indexoptions">IndexOptions</A>, -<A HREF="mod_autoindex.html#readmename">ReadmeName</A>, <EM>etc.</EM>). -<DT>Limit -<DD> -<!--%plaintext <?INDEX {\tt Limit} override> --> -Allow use of the directives controlling host access (allow, deny and order). -<DT>Options -<DD> -<!--%plaintext <?INDEX {\tt Options} override> --> -Allow use of the directives controlling specific directory features -(<A HREF="#options">Options</A> and -<A HREF="mod_include.html#xbithack">XBitHack</A>). -</DL><P><HR> - -<H2><A NAME="authname">AuthName directive</A></H2> -<!--%plaintext <?INDEX {\tt AuthName} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthName <EM>auth-domain</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -This directive sets the name of the authorization realm for a directory. -This realm is given to the client so that the user knows which username and -password to send. <SAMP>AuthName</SAMP> takes a single argument; -if the realm name contains spaces, it must be enclosed in quotation marks. -It must be accompanied by <A HREF="#authtype">AuthType</A> and -<A HREF="#require">require</A> directives, and directives such as -<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and -<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> to work.<P><HR> - -<H2><A NAME="authtype">AuthType directive</A></H2> -<!--%plaintext <?INDEX {\tt AuthType} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthType <EM>type</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -This directive selects the type of user authentication for a directory. -Only <CODE>Basic</CODE> and <CODE>Digest</CODE> are currently implemented. -<!--%plaintext <?INDEX {\tt Basic} authentication scheme> --> -It must be accompanied by <A HREF="#authname">AuthName</A> and -<A HREF="#require">require</A> directives, and directives such as -<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and -<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> to work.<P><HR> - -<H2><A NAME="bindaddress">BindAddress directive</A></H2> -<!--%plaintext <?INDEX {\tt BindAddress} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> BindAddress <EM>saddr</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>BindAddress *</CODE><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> core<P> - -A Unix® http server can either listen for connections to every -IP address of the server machine, or just one IP address of the server -machine. <EM>Saddr</EM> can be - -<MENU> -<LI>* -<LI>An IP address -<LI>A fully-qualified Internet domain name -</MENU> -If the value is *, then the server will listen for connections on -every IP address, otherwise it will only listen on the IP address -specified. <P> - -Only one <CODE>BindAddress</CODE> directive can be used. For more -control over which address and ports Apache listens to, use the -<CODE><A HREF="#listen">Listen</A></CODE> directive instead of -<CODE>BindAddress</CODE>.<P> - -<CODE>BindAddress</CODE> can be used as an alternative method for -supporting <A HREF="../vhosts/index.html">virtual hosts</A> using -multiple independent servers, instead of using <CODE><A -HREF="#virtualhost"><VirtualHost></A></CODE> sections. - -<P><STRONG>See Also:</STRONG> -<A HREF="../dns-caveats.html">DNS Issues</A><BR> -<STRONG>See Also:</STRONG> -<A HREF="../bind.html">Setting which addresses and ports Apache uses</A></P> - -<HR> - -<H2><A NAME="bs2000account">BS2000Account directive</A></H2> -<!--%plaintext <?INDEX {\tt BS2000Account} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> BS2000Account <EM>account</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>none</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> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> BS2000Account is only available for -BS2000 machines, as of Apache 1.3 and later.<P> - -The <CODE>BS2000Account</CODE> directive is available for BS2000 hosts -only. It must be used to define the account number for the non-privileged -apache server user (which was configured using the -<A HREF="#user">User</A> directive). -This is required by the BS2000 POSIX subsystem (to change the underlying -BS2000 task environment by performing a sub-LOGON) to prevent CGI scripts -from accessing resources of the privileged account which started the -server, usually <SAMP>SYSROOT</SAMP>.<BR> -Only one <CODE>BS2000Account</CODE> directive can be used. <P> - -<P><STRONG>See Also:</STRONG> -<A HREF="../ebcdic.html">Apache EBCDIC port</A></P> - -<HR> - -<H2><A NAME="clearmodulelist">ClearModuleList directive</A></H2> -<!--%plaintext <?INDEX {\tt ClearModuleList} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ClearModuleList<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> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ClearModuleList is only available in -Apache 1.2 and later<P> - -The server comes with a built-in list of active modules. This -directive clears the list. It is assumed that the list will then be -re-populated using the <A HREF="#addmodule">AddModule</A> directive.<P><HR> - -<H2><A NAME="contentdigest">ContentDigest directive</A></H2> -<!--%plaintext <?INDEX {\tt ContentDigest} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ContentDigest <EM>on|off</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ContentDigest off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, -.htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Options<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> experimental<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ContentDigest is only available in -Apache 1.1 and later<P> - -This directive enables the generation of <CODE>Content-MD5</CODE> headers -as defined in RFC1864 respectively RFC2068.<P> - -MD5 is an algorithm for computing a "message digest" (sometimes called -"fingerprint") of arbitrary-length data, with a high degree of confidence -that any alterations in the data will be reflected in alterations in the -message digest.<P> - -The <CODE>Content-MD5</CODE> header provides an end-to-end message -integrity check (MIC) of the entity-body. A proxy or client may check this -header for detecting accidental modification of the entity-body -in transit. -Example header: -<PRE> Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==</PRE><P> - -Note that this can cause performance problems on your server -since the message digest is computed on every request -(the values are not cached).<P> - -<CODE>Content-MD5</CODE> is only sent for documents served by the -core, and not by any module. For example, SSI documents, output from -CGI scripts, and byte range responses do not have this header. - -<HR> - -<H2><A NAME="coredumpdirectory">CoreDumpDirectory directive</A></H2> -<!--%plaintext <?INDEX {\tt CoreDumpDirectory} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CoreDumpDirectory <EM>directory</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> the same location as ServerRoot<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> core<P> - -This controls the directory to which Apache attempts to switch before -dumping core. The default is in the <A HREF="#serverroot">ServerRoot</A> -directory, however since this should not be writable by the user -the server runs as, core dumps won't normally get written. If you -want a core dump for debugging, you can use this directive to place -it in a different location.<P><HR> - -<H2><A NAME="defaulttype">DefaultType directive</A></H2> -<!--%plaintext <?INDEX {\tt DefaultType} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> DefaultType <EM>MIME-type</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>DefaultType text/html</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, -.htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -There will be times when the server is asked to provide a document -whose type cannot be determined by its MIME types mappings.<P> - -The server must inform the client of the content-type of the document, so in -the event of an unknown type it uses the <CODE>DefaultType</CODE>. For -example: -<BLOCKQUOTE><CODE>DefaultType image/gif</CODE></BLOCKQUOTE> -would be appropriate for a directory which contained many gif images -with filenames missing the .gif extension.<P><HR> - -<H2><A NAME="directory"><Directory> directive</A></H2> -<!--%plaintext <?INDEX {\tt Directory} section directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <Directory <EM>directory</EM>> - ... </Directory> <BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Core. <P> - -<Directory> and </Directory> are used to enclose a group of -directives which will apply only to the named directory and sub-directories -of that directory. Any directive which is allowed in a directory -context may be used. <EM>Directory</EM> is either the full path to a directory, -or a wild-card string. In a wild-card string, `?' matches any single character, -and `*' matches any sequences of characters. As of Apache 1.3, you -may also use `[]' character ranges like in the shell. Also as of Apache 1.3 -none of the wildcards match a `/' character, which more closely mimics the -behaviour of Unix shells. -Example: -<PRE> - <Directory /usr/local/httpd/htdocs> - Options Indexes FollowSymLinks - </Directory> -</PRE> - -<P><STRONG>Apache 1.2 and above:</STRONG> -Extended regular expressions can also be used, with the addition of the -<CODE>~</CODE> character. For example:</P> - -<PRE> - <Directory ~ "^/www/.*/[0-9]{3}"> -</PRE> - -would match directories in /www/ that consisted of three numbers. - -<P>If multiple (non-regular expression) directory sections match the -directory (or its parents) containing -a document, then the directives are applied in the order of shortest match -first, interspersed with the directives from the -<A HREF="#accessfilename">.htaccess</A> files. For example, with -<BLOCKQUOTE><CODE> -<Directory /><BR> -AllowOverride None<BR> -</Directory><BR><BR> -<Directory /home/*><BR> -AllowOverride FileInfo<BR> -</Directory></CODE></BLOCKQUOTE> -for access to the document <CODE>/home/web/dir/doc.html</CODE> the -steps are: -<MENU> -<LI>Apply directive <CODE>AllowOverride None</CODE> (disabling -<CODE>.htaccess</CODE> files). -<LI>Apply directive <CODE>AllowOverride FileInfo</CODE> (for directory -<CODE>/home/web</CODE>). -<LI>Apply any FileInfo directives in <CODE>/home/web/.htaccess</CODE> -</MENU> - -<P> -Regular expression directory sections are handled slightly differently -by Apache 1.2 and 1.3. In Apache 1.2 they are interspersed with the normal -directory sections and applied in the order they appear in the configuration -file. They are applied only once, and apply when the shortest match -possible occurs. In Apache 1.3 regular expressions are not considered -until after all of the normal sections have been applied. Then all of -the regular expressions are tested in the order they appeared in the -configuration file. For example, with -<BLOCKQUOTE><CODE> -<Directory ~ abc$><BR> -... directives here ...<BR> -</Directory><BR> -</CODE></BLOCKQUOTE> -Suppose that the filename being accessed is -<CODE>/home/abc/public_html/abc/index.html</CODE>. The server -considers each of <CODE>/</CODE>, <CODE>/home</CODE>, <CODE>/home/abc</CODE>, -<CODE>/home/abc/public_html</CODE>, and <CODE>/home/abc/public_html/abc</CODE> -in that order. In Apache 1.2, when -<CODE>/home/abc</CODE> is considered, the regular expression will match -and be applied. In Apache 1.3 the regular expression isn't considered -at all at that point in the tree. It won't be considered until after -all normal <Directory>s and <CODE>.htaccess</CODE> files have -been applied. Then the regular expression will -match on <CODE>/home/abc/public_html/abc</CODE> and be applied. - -<P> - -<STRONG> -Note that the default Apache access for <Directory /> is -<SAMP>Allow from All</SAMP>. This means that Apache will serve any file -mapped from an URL. It is recommended that you change this with a block -such as -</STRONG> -<PRE> - <Directory /> - Order Deny,Allow - Deny from All - </Directory> -</PRE> -<P> -<STRONG> -and then override this for directories you <EM>want</EM> accessible. -See the -<A - HREF="../misc/security_tips.html" ->Security Tips</A> -page for more details. -</STRONG> -</P> - -The directory sections typically occur in the access.conf file, but they -may appear in any configuration file. <Directory> directives cannot -nest, and cannot appear in a <A HREF="#limit"><Limit></A> or -<A HREF="#limitexcept"><LimitExcept></A> section. -<P> - -<STRONG>See also</STRONG>: <A HREF="../sections.html">How Directory, -Location and Files sections work</A> for an explanation of how these -different sections are combined when a request is received - -<HR> - -<H2><A NAME="directorymatch"><DirectoryMatch></A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <DirectoryMatch <EM>regex</EM>> - ... </DirectoryMatch> <BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Core.<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later - -<P><DirectoryMatch> and </DirectoryMatch> are used to enclose a -group of -directives which will apply only to the named directory and sub-directories -of that directory, the same as <A -HREF="#directory"><Directory></A>. However, it takes as an -argument a regular expression. For example:</P> - -<PRE> - <DirectoryMatch "^/www/.*/[0-9]{3}"> -</PRE> - -<P>would match directories in /www/ that consisted of three numbers.</P> - -<P><STRONG>See Also:</STRONG> -<A HREF="#directory"><Directory></A> for a description of how -regular expressions are mixed in with normal <Directory>s. -<BR> -<STRONG>See also</STRONG>: <A HREF="../sections.html">How Directory, -Location and Files sections work</A> for an explanation of how these -different sections are combined when a request is received - -<HR> - -<H2><A NAME="documentroot">DocumentRoot directive</A></H2> -<!--%plaintext <?INDEX {\tt DocumentRoot} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> DocumentRoot <EM>directory-filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>DocumentRoot -/usr/local/apache/htdocs</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -This directive sets the directory from which httpd will serve files. -Unless matched by a directive like Alias, the server appends the path -from the requested URL to the document root to make the path to the -document. Example: -<BLOCKQUOTE><CODE>DocumentRoot /usr/web</CODE></BLOCKQUOTE> -then an access to <CODE>http://www.my.host.com/index.html</CODE> refers -to <CODE>/usr/web/index.html</CODE>. - -<P>There appears to be a bug in mod_dir which causes problems when the -DocumentRoot has a trailing slash (<EM>i.e.</EM>, "DocumentRoot /usr/web/") so -please avoid that. - -<P><HR> - -<H2><A NAME="errordocument">ErrorDocument directive</A></H2> -<!--%plaintext <?INDEX {\tt ErrorDocument} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ErrorDocument <EM>error-code document</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, -.htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> The directory and .htaccess contexts -are only available in Apache 1.1 and later.<P> - -In the event of a problem or error, Apache can be configured to do -one of four things, - -<OL> -<LI>output a simple hardcoded error message -<LI>output a customized message -<LI>redirect to a local URL to handle the problem/error -<LI>redirect to an external URL to handle the problem/error -</OL> - -<P>The first option is the default, while options 2-4 are configured -using the <CODE>ErrorDocument</CODE> directive, which is followed by -the HTTP response code and a message or URL. - -<P><EM>Messages</EM> in this context begin with a single quote -(<CODE>"</CODE>), which does not form part of the message itself. -Apache will sometimes offer additional information regarding the -problem/error. - -<P>URLs can begin with a slash (/) for local URLs, or be a full -URL which the client can resolve. Examples: -<BLOCKQUOTE><CODE> -ErrorDocument 500 http://foo.example.com/cgi-bin/tester<BR> -ErrorDocument 404 /cgi-bin/bad_urls.pl<BR> -ErrorDocument 401 /subscription_info.html<BR> -ErrorDocument 403 "Sorry can't allow you access today -</CODE></BLOCKQUOTE> - -<P>Note that when you specify an <CODE>ErrorDocument</CODE> that -points to a remote URL (ie. anything with a method such as "http" in -front of it) Apache will send a redirect to the client to tell it -where to find the document, even if the document ends up being -on the same server.. This has several implications, the -most important being that <STRONG>if you use an "ErrorDocument 401" -directive then it must refer to a local document.</STRONG> This results -from the nature of the HTTP basic authentication scheme. - -<P>See Also: <A HREF="../custom-error.html">documentation of customizable -responses.</A><P><HR> - -<H2><A NAME="errorlog">ErrorLog directive</A></H2> -<!--%plaintext <?INDEX {\tt ErrorLog} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ErrorLog <EM>filename</EM>|<CODE>syslog[:facility]</CODE> -<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ErrorLog logs/error_log</CODE> (Unix)<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ErrorLog logs/error.log</CODE> - (Windows and OS/2)<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -The error log directive sets the name of the file to which the server will log -any errors it encounters. If the filename does not begin with a slash (/) -then it is assumed to be relative to the <A HREF="#serverroot">ServerRoot</A>. -If the filename begins with a pipe (|) then it is assumed to be a command to -spawn to handle the error log. - -<P><STRONG>Apache 1.3 and above:</STRONG> -Using <CODE>syslog</CODE> instead of a filename enables logging via syslogd(8) -if the system supports it. The default is to use syslog facility -<CODE>local7</CODE>, but you can override this by using the -<CODE>syslog:</CODE><EM>facility</EM> syntax where <EM>facility</EM> can be -one of the names usually documented in syslog(1). - -<P> -SECURITY: See the -<A HREF="../misc/security_tips.html#serverroot">security tips</A> -document for details on why your security could be compromised if -the directory where logfiles are stored is writable by anyone other -than the user that starts the server. - -<P><STRONG>See also:</STRONG> <A HREF="#loglevel">LogLevel</A> -<P><HR> - -<H2><A NAME="files"><Files> directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <Files <EM>filename</EM>> -... </Files><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, .htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> only available in Apache -1.2 and above.<P> - -<P>The <Files> directive provides for access control by -filename. It is comparable to the <A -HREF="#directory"><Directory></A> directive and -<A HREF="#location"><Location></A> directives. It -should be matched with a </Files> directive. The -directives given within this section will be applied to any -object with a basename (last component of filename) matching -the specified filename. -<CODE><Files></CODE> sections are processed in the -order they appear in the configuration file, after the -<Directory> sections and <CODE>.htaccess</CODE> files are -read, but before <Location> sections. Note that -<Files> can be nested inside <Directory> -sections to restrict the portion of the filesystem they -apply to.</P> - -<P>The <EM>filename</EM> argument should include a filename, or a -wild-card string, where `?' matches any single character, and `*' matches any -sequences of characters. Extended regular expressions can also be used, -with the addition of -the <CODE>~</CODE> character. For example:</P> - -<PRE> - <Files ~ "\.(gif|jpe?g|png)$"> -</PRE> - -would match most common Internet graphics formats. In Apache 1.3 and -later, <A HREF="#filesmatch"><FilesMatch></A> is preferred, -however. - -<P>Note that unlike <A -HREF="#directory"><CODE><Directory></CODE></A> and <A -HREF="#location"><CODE><Location></CODE></A> sections, -<CODE><Files></CODE> sections can be used inside .htaccess -files. This allows users to control access to their own files, at a -file-by-file level. - -<P> - -<STRONG>See also</STRONG>: <A HREF="../sections.html">How Directory, -Location and Files sections work</A> for an explanation of how these -different sections are combined when a request is received - -<HR> - -<H2><A NAME="filesmatch"><FilesMatch></A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <FilesMatch <EM>regex</EM>> -... </FilesMatch><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, .htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> only available in Apache -1.3 and above.<P> - -<P>The <FilesMatch> directive provides for access control by -filename, just as the <A HREF="#files"><Files></A> directive -does. However, it accepts a regular expression. For example:</P> - -<PRE> - <FilesMatch "\.(gif|jpe?g|png)$"> -</PRE> - -<P>would match most common Internet graphics formats.</P> - -<STRONG>See also</STRONG>: <A HREF="../sections.html">How Directory, -Location and Files sections work</A> for an explanation of how these -different sections are combined when a request is received - -<HR> - -<H2><A NAME="group">Group directive</A></H2> -<!--%plaintext <?INDEX {\tt Group} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Group <EM>unix-group</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Group #-1</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -The Group directive sets the group under which the server will answer requests. -In order to use this directive, the stand-alone server must be run initially -as root. <EM>Unix-group</EM> is one of: -<DL> -<DT>A group name -<DD>Refers to the given group by name. -<DT># followed by a group number. -<DD>Refers to a group by its number. -</DL> - -It is recommended that you set up a new group specifically for running the -server. Some admins use user <CODE>nobody</CODE>, but this is not always -possible or desirable.<P> - -Note: if you start the server as a non-root user, it will fail to change -to the specified group, and will instead continue to run as the group of the -original user. <P> - -Special note: Use of this directive in <VirtualHost> requires a -properly configured <A HREF="../suexec.html">suEXEC wrapper</A>. -When used inside a <VirtualHost> in this manner, only the group -that CGIs are run as is affected. Non-CGI requests are still processed -as the group specified in the main Group directive.<P> - -SECURITY: See <A HREF="#user">User</A> for a discussion of the security -considerations.<P><HR> - -<H2><A NAME="hostnamelookups">HostNameLookups directive</A></H2> -<!--%plaintext <?INDEX {\tt HostNameLookups} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> HostNameLookups <EM>on | off | double</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>HostNameLookups off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> <CODE>double</CODE> available only in -Apache -1.3 and above.<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Default was <CODE>on</CODE> prior to -Apache 1.3.<P> - -This directive enables DNS lookups so that host names can be logged (and -passed to CGIs/SSIs in <CODE>REMOTE_HOST</CODE>). -The value <CODE>double</CODE> refers to doing double-reverse DNS. -That is, after a reverse lookup is performed, a forward lookup is then -performed on that result. At least one of the ip addresses in the forward -lookup must match the original address. (In "tcpwrappers" terminology -this is called <CODE>PARANOID</CODE>.)<P> - -Regardless of the setting, when <A HREF="mod_access.html">mod_access</A> -is used for controlling access by hostname, a double reverse lookup -will be performed. This is necessary for security. Note that the -result of this double-reverse isn't generally available unless -you set <CODE>HostnameLookups double</CODE>. For example, if only -<CODE>HostnameLookups on</CODE> and a request is made to an object that -is protected by hostname restrictions, regardless of whether the -double-reverse fails or not, CGIs will still be passed the single-reverse -result in <CODE>REMOTE_HOST</CODE>.<P> - -The default for this directive was previously <CODE>on</CODE> in -versions of Apache prior to 1.3. It was changed to <CODE>off</CODE> -in order to save the network traffic for those sites that don't truly -need the reverse lookups done. It is also better for the end users -because they don't have to suffer the extra latency that a lookup -entails. -Heavily loaded sites should leave this directive <CODE>off</CODE>, since DNS -lookups can take considerable amounts of time. The utility <EM>logresolve</EM>, -provided in the <EM>/support</EM> directory, can be used to look up host names -from logged IP addresses offline.<P><HR> - -<H2><A NAME="identitycheck">IdentityCheck directive</A></H2> -<!--%plaintext <?INDEX {\tt IdentityCheck} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> IdentityCheck <EM>boolean</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>IdentityCheck off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -This directive enables RFC1413-compliant logging of the remote user name -for each connection, where the client machine runs identd or something similar. -This information is logged in the access log. <EM>Boolean</EM> is either -<CODE>on</CODE> or <CODE>off</CODE>.<P> - -The information should not be trusted in any way except for rudimentary usage -tracking.<P> - -Note that this can cause serious latency problems accessing your server -since every request requires one of these lookups to be performed. When -firewalls are involved each lookup might possibly fail and add 30 seconds -of latency to each hit. So in general this is not very useful on public -servers accessible from the Internet. -<P><HR> - -<H2><A NAME="ifdefine"><IfDefine> directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <IfDefine [!]<EM>parameter-name</EM>> <EM>...</EM> -</IfDefine><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> all<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> <IfDefine> is only available in -1.3.1 and later.<P> - -<P> - -The <IfDefine <EM>test</EM>>...</IfDefine> -section is used to mark directives that are conditional. The -directives within an IfDefine section are only -processed if the <EM>test</EM> is true. If <EM>test</EM> -is false, everything between the start and end markers -is ignored.<P> - -The <EM>test</EM> in the <IfDefine> section directive -can be one of two forms: - -<UL> -<LI><EM>parameter-name</EM> -<LI><CODE>!</CODE><EM>parameter-name</EM> -</UL> - -<P>In the former case, the directives between the start and end markers are -only processed if the parameter named <EM>parameter-name</EM> is defined. -The second format reverses the test, and only processes the directives if -<EM>parameter-name</EM> is <STRONG>not</STRONG> defined. - -<P>The <EM>parameter-name</EM> argument is a define as given on the -<CODE>httpd</CODE> command line via <CODE>-D</CODE><EM>parameter-</EM>, at the -time the server was started. - -<P><IfDefine> sections are nest-able, which can be used to implement -simple multiple-parameter tests. - -Example: - -<PRE> - $ httpd -DReverseProxy ... - - # httpd.conf - <IfDefine ReverseProxy> - LoadModule rewrite_module libexec/mod_rewrite.so - LoadModule proxy_module libexec/libproxy.so - </IfDefine> -</PRE> - -<P> <HR> - -<H2><A NAME="ifmodule"><IfModule> directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <IfModule [!]<EM>module-name</EM>> - <EM>...</EM> -</IfModule><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> all<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> IfModule is only available in 1.2 and -later.<P> - -<P> - -The <IfModule <EM>test</EM>>...</IfModule> -section is used to mark directives that are conditional. The -directives within an IfModule section are only -processed if the <EM>test</EM> is true. If <EM>test</EM> -is false, everything between the start and end markers -is ignored.<P> - -The <EM>test</EM> in the <IfModule> section directive -can be one of two forms: - -<UL> -<LI><EM>module name</EM> -<LI>!<EM>module name</EM> -</UL> - -<P>In the former case, the directives between the start and end markers -are only processed if the module named <EM>module name</EM> is compiled -in to Apache. The second format reverses the test, and only processes -the directives if <EM>module name</EM> is <STRONG>not</STRONG> compiled in. - -<P>The <EM>module name</EM> argument is a module name as given as the file -name of the module, at the time it was compiled. For example, -<CODE>mod_rewrite.c</CODE>. - -<P><IfModule> sections are nest-able, which can be used to implement -simple multiple-module tests. - -<P> <HR> - -<H2><A NAME="include">Include directive</A></H2> -<STRONG>Syntax:</STRONG> Include <EM>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> Core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Include is only available in Apache 1.3 -and later. -<P> -This directive allows inclusion of other configuration files from within the -server configuration files. - -<P> <HR> - -<H2><A NAME="keepalive">KeepAlive directive</A></H2> -<STRONG>Syntax: (Apache 1.1)</STRONG> KeepAlive <EM>max-requests</EM><BR> -<STRONG>Default: (Apache 1.1)</STRONG> <CODE>KeepAlive 5</CODE><BR> -<STRONG>Syntax: (Apache 1.2)</STRONG> KeepAlive <EM>on/off</EM><BR> -<STRONG>Default: (Apache 1.2)</STRONG> <CODE>KeepAlive On</CODE><BR> -<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> Core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> KeepAlive is only available in Apache -1.1 and later.<P> - -This directive enables -<A HREF="../keepalive.html">Keep-Alive</A> -support. - -<P><STRONG>Apache 1.1</STRONG>: Set <EM>max-requests</EM> -to the maximum number of requests you want Apache to entertain per -request. A limit is imposed to prevent a client from hogging your -server resources. Set this to <CODE>0</CODE> to disable support. - -<P><STRONG>Apache 1.2 and later</STRONG>: Set to "On" to enable -persistent connections, "Off" to disable. See also the <A -HREF="#maxkeepaliverequests">MaxKeepAliveRequests</A> directive.</P><HR> - -<H2><A NAME="keepalivetimeout">KeepAliveTimeout directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> KeepAliveTimeout <EM>seconds</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>KeepAliveTimeout 15</CODE><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> Core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> KeepAliveTimeout is only available in -Apache 1.1 and later.<P> - -The number of seconds Apache will wait for a subsequent request before -closing the connection. Once a request has been received, the timeout -value specified by the <A -HREF="#timeout"><CODE>Timeout</CODE></A> directive -applies. -<HR> - -<H2><A NAME="limit"><Limit> directive</A></H2> -<!--%plaintext <?INDEX {\tt Limit} section directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> - <Limit <EM>method method</EM> ... > ... </Limit><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> any<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -Access controls are normally effective for <STRONG>all</STRONG> access -methods, and this is the usual desired behaviour. <STRONG>In the -general case, access control directives should not be placed within a -<CODE><limit></CODE> section.</STRONG> - -<P>The purpose of the <Limit> directive is to restrict the effect -of the access controls to the nominated HTTP methods. For all other -methods, the access restrictions that are enclosed in the -<Limit> bracket <STRONG>will have no effect</STRONG>. The -following example applies the access control only to the methods POST, -PUT, and DELETE, leaving all other methods unprotected: - -<BLOCKQUOTE><CODE> -<Limit POST PUT DELETE><BR> -require valid-user<BR> -</Limit></CODE></BLOCKQUOTE> - -The method names listed can be one or more of: GET, POST, PUT, DELETE, -CONNECT, OPTIONS, TRACE, PATCH, PROPFIND, PROPPATCH, MKCOL, COPY, -MOVE, LOCK, and UNLOCK. <STRONG>The method name is -case-sensitive.</STRONG> If GET is used it will also restrict HEAD -requests. - -<P><HR> - -<H2><A NAME="limitexcept"><LimitExcept> directive</A></H2> -<!--%plaintext <?INDEX {\tt LimitExcept} section directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> - <LimitExcept <EM>method method</EM> ... > ... </LimitExcept><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> any<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3.5 and later<P> - -<LimitExcept> and </LimitExcept> are used to enclose a group of -access control directives which will then apply to any HTTP access method -<STRONG>not</STRONG> listed in the arguments; i.e., it is the opposite of a -<A HREF="#limit"><Limit></A> section and can be used to control both -standard and nonstandard/unrecognized methods. See the documentation for -<A HREF="#limit"><Limit></A> for more details. - -<P><HR> - -<H2><A NAME="limitrequestbody">LimitRequestBody directive</A></H2> -<!--%plaintext <?INDEX {\tt LimitRequestBody} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LimitRequestBody <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>LimitRequestBody 0</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, -.htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> LimitRequestBody is only available in -Apache 1.3.2 and later. -<P> - -<EM>Number</EM> is a long integer from 0 (meaning unlimited) to 2147483647 -(2GB). The default value is defined by the compile-time constant -<CODE>DEFAULT_LIMIT_REQUEST_BODY</CODE> (0 as distributed). -<P> - -The LimitRequestBody directive allows the user to set a -limit on the allowed size of an HTTP request message body within -the context in which the directive is given (server, per-directory, -per-file or per-location). If the client request exceeds that limit, -the server will return an error response instead of servicing the request. -The size of a normal request message body will vary greatly depending -on the nature of the resource and the methods allowed on that resource. -CGI scripts typically use the message body for passing form information -to the server. Implementations of the PUT method will require a value -at least as large as any representation that the server wishes -to accept for that resource. -<P> - -This directive gives the server administrator greater control over abnormal -client request behavior, which may be useful for avoiding some forms -of denial-of-service attacks. -<P> - -<P><HR> - -<H2><A NAME="limitrequestfields">LimitRequestFields directive</A></H2> -<!--%plaintext <?INDEX {\tt LimitRequestFields} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LimitRequestFields <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>LimitRequestFields 100</CODE><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> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> LimitRequestFields is only available in -Apache 1.3.2 and later. -<P> - -<EM>Number</EM> is an integer from 0 (meaning unlimited) to 32767. -The default value is defined by the compile-time constant -<CODE>DEFAULT_LIMIT_REQUEST_FIELDS</CODE> (100 as distributed). -<P> - -The LimitRequestFields directive allows the server administrator to modify -the limit on the number of request header fields allowed in an HTTP request. -A server needs this value to be larger than the number of fields that a -normal client request might include. The number of request header fields -used by a client rarely exceeds 20, but this may vary among different -client implementations, often depending upon the extent to which a user -has configured their browser to support detailed content negotiation. -Optional HTTP extensions are often expressed using request header fields. -<P> - -This directive gives the server administrator greater control over abnormal -client request behavior, which may be useful for avoiding some forms -of denial-of-service attacks. The value should be increased if normal -clients see an error response from the server that indicates too many -fields were sent in the request.<P> - -<P><HR> - -<H2><A NAME="limitrequestfieldsize">LimitRequestFieldsize directive</A></H2> -<!--%plaintext <?INDEX {\tt LimitRequestFieldsize} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LimitRequestFieldsize <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>LimitRequestFieldsize 8190</CODE><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> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> LimitRequestFieldsize is only available in -Apache 1.3.2 and later. -<P> - -<EM>Number</EM> is an integer size in bytes from 0 to the value of the -compile-time constant <CODE>DEFAULT_LIMIT_REQUEST_FIELDSIZE</CODE> -(8190 as distributed). -<P> - -The LimitRequestFieldsize directive allows the server administrator to reduce -the limit on the allowed size of an HTTP request header field below the -normal input buffer size compiled with the server. A server needs this -value to be large enough to hold any one header field from a normal client -request. The size of a normal request header field will vary greatly -among different client implementations, often depending upon the extent -to which a user has configured their browser to support detailed -content negotiation. -<P> - -This directive gives the server administrator greater control over abnormal -client request behavior, which may be useful for avoiding some forms -of denial-of-service attacks. Under normal conditions, the value should -not be changed from the default.<P> - -<P><HR> - -<H2><A NAME="limitrequestline">LimitRequestLine directive</A></H2> -<!--%plaintext <?INDEX {\tt LimitRequestLine} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LimitRequestLine <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>LimitRequestLine 8190</CODE><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> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> LimitRequestLine is only available in -Apache 1.3.2 and later. -<P> - -<EM>Number</EM> is an integer size in bytes from 0 to the value of the -compile-time constant <CODE>DEFAULT_LIMIT_REQUEST_LINE</CODE> -(8190 as distributed). -<P> - -The LimitRequestLine directive allows the server administrator to reduce -the limit on the allowed size of a client's HTTP request-line below the -normal input buffer size compiled with the server. Since the request-line -consists of the HTTP method, URI, and protocol version, the -LimitRequestLine directive places a restriction on the length of a -request-URI allowed for a request on the server. A server needs this -value to be large enough to hold any of its resource names, including -any information that might be passed in the query part of a GET request. -<P> - -This directive gives the server administrator greater control over abnormal -client request behavior, which may be useful for avoiding some forms -of denial-of-service attacks. Under normal conditions, the value should -not be changed from the default.<P> - -<P><HR> - -<H2><A NAME="listen">Listen directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> -Listen [<EM>IP address</EM>:]<EM>port number</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> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Listen is only available in Apache -1.1 and later.<P> - -<P>The Listen directive instructs Apache to listen to more than one IP -address or port; by default it responds to requests on all IP -interfaces, but only on the port given by the <CODE><A -HREF="#port">Port</A></CODE> directive.</P> - -<TT>Listen</TT> can be used instead of <TT><A -HREF="#bindaddress">BindAddress</A></TT> and <TT>Port</TT>. It tells -the server to accept incoming requests on the specified port or -address-and-port combination. If the first format is used, with a port -number only, the server listens to the given port on all interfaces, -instead of the port given by the <TT>Port</TT> directive. If an IP -address is given as well as a port, the server will listen on the -given port and interface. <P> - -Note that you may still require a <TT>Port</TT> directive so -that URLs that Apache generates that point to your server still -work.<P> - -Multiple Listen directives may be used -to specify a number of addresses and ports to listen to. The server -will respond to requests from any of the listed addresses and -ports. -<P> - -For example, to make the server accept connections on both port -80 and port 8000, use: -<PRE> - Listen 80 - Listen 8000 -</PRE> - -To make the server accept connections on two specified -interfaces and port numbers, use -<PRE> - Listen 192.170.2.1:80 - Listen 192.170.2.5:8000 -</PRE> - -<P><STRONG>See Also:</STRONG> -<A HREF="../dns-caveats.html">DNS Issues</A><BR> -<STRONG>See Also:</STRONG> -<A HREF="../bind.html">Setting which addresses and ports Apache uses</A><BR> -<STRONG>See Also:</STRONG> -<A HREF="http://www.apache.org/info/known_bugs.html#listenbug">Known Bugs</A> -</P> -<HR> - -<H2><A NAME="listenbacklog">ListenBacklog directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ListenBacklog <EM>backlog</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ListenBacklog 511</CODE><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> Core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ListenBacklog is only available in Apache -versions after 1.2.0. - -<P>The maximum length of the queue of pending connections. Generally no -tuning is needed or desired, however on some systems it is desirable -to increase this when under a TCP SYN flood attack. See -the backlog parameter to the <CODE>listen(2)</CODE> system call. - -<P>This will often be limited to a smaller number by the operating -system. This varies from OS to OS. Also note that many OSes do not -use exactly what is specified as the backlog, but use a number based on -(but normally larger than) what is set. -<HR> - -<H2><A NAME="location"><Location> directive</A></H2> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <Location <EM>URL</EM>> -... </Location><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Location is only available in Apache -1.1 and later.<P> - -<P>The <Location> directive provides for access control by -URL. It is similar to the <A -HREF="#directory"><Directory></A> directive, and -starts a subsection which is terminated with a </Location> -directive. <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, and after the <Files> sections.</P> - -<P>Note that URLs do not have to line up with the filesystem at all, -it should be emphasized that <Location> operates completely outside -the filesystem. - -<P>For all origin (non-proxy) requests, the URL to be matched is -of the form <CODE>/path/</CODE>, and you should not include any -<CODE>http://servername</CODE> prefix. For proxy requests, the URL -to be matched is of the form <CODE>scheme://servername/path</CODE>, -and you must include the prefix. - -<P>The URL may use wildcards In a wild-card string, `?' matches any -single character, and `*' matches any sequences of characters. - -<P><STRONG>Apache 1.2 and above:</STRONG> -Extended regular expressions can also be used, with the addition of -the <CODE>~</CODE> character. - -For example:</P> - -<PRE> - <Location ~ "/(extra|special)/data"> -</PRE> - -<P>would match URLs that contained the substring "/extra/data" or -"/special/data". In Apache 1.3 and above, a new directive -<A HREF="#locationmatch"><LocationMatch></A> exists which -behaves identical to the regex version of -<CODE><Location></CODE>. - -<P>The <CODE>Location</CODE> functionality is especially useful when -combined with the <CODE><A -HREF="mod_mime.html#sethandler">SetHandler</A></CODE> directive. For example, -to enable status requests, but allow them only -from browsers at foo.com, you might use: - -<PRE> - <Location /status> - SetHandler server-status - order deny,allow - deny from all - allow from .foo.com - </Location> -</PRE> - -<P><STRONG>Apache 1.3 and above note about / (slash)</STRONG>: The slash -character has special -meaning depending on where in a URL it appears. People may be used -to its behaviour in the filesystem where multiple adjacent slashes are -frequently collapsed to a single slash (<EM>i.e.</EM>, <CODE>/home///foo</CODE> -is the same as <CODE>/home/foo</CODE>). In URL-space this is not -necessarily true. The <CODE><LocationMatch></CODE> directive -and the regex version of <CODE><Location></CODE> require you -to explicitly specify multiple slashes if that is your intention. -For example, <CODE><LocationMatch ^/abc></CODE> would match the -request URL <CODE>/abc</CODE> but not the request URL <CODE>//abc</CODE>. -The (non-regex) <CODE><Location></CODE> directive behaves -similarly when used for proxy requests. But when (non-regex) -<CODE><Location></CODE> is used for non-proxy requests it will -implicitly match multiple slashes with a single slash. For example, -if you specify <CODE><Location /abc/def></CODE> and the request -is to <CODE>/abc//def</CODE> then it will match. - -<P> -<STRONG>See also</STRONG>: <A HREF="../sections.html">How Directory, -Location and Files sections work</A> for an explanation of how these -different sections are combined when a request is received - -<HR> - -<H2><A NAME="locationmatch"><LocationMatch></A></H2> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <LocationMatch <EM>regex</EM>> -... </LocationMatch><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> LocationMatch is only available in -Apache 1.3 and later.<P> - -<P>The <LocationMatch> directive provides for access control by -URL, in an identical manner to <A -HREF="#location"><Location></A>. However, it takes a regular -expression as an argument instead of a simple string. For example:</P> - -<PRE> - <LocationMatch "/(extra|special)/data"> -</PRE> - -<P>would match URLs that contained the substring "/extra/data" or -"/special/data".</P> - -<STRONG>See also</STRONG>: <A HREF="../sections.html">How Directory, -Location and Files sections work</A> for an explanation of how these -different sections are combined when a request is received - -<HR> - -<H2><A NAME="lockfile">LockFile directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LockFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>LockFile logs/accept.lock</CODE><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> core<P> - -The LockFile directive sets the path to the lockfile used when -Apache is compiled with either USE_FCNTL_SERIALIZED_ACCEPT or -USE_FLOCK_SERIALIZED_ACCEPT. This directive should normally be -left at its default value. The main reason for changing it is if -the <CODE>logs</CODE> directory is NFS mounted, since <STRONG>the lockfile -must be stored on a local disk</STRONG>. The PID of the main -server process is automatically appended to the filename. <P> - -<STRONG>SECURITY:</STRONG> It is best to avoid putting this file in a -world writable directory such as <CODE>/var/tmp</CODE> because someone -could create a denial of service attack and prevent the server from -starting by creating a lockfile with the same name as the one the -server will try to create.<P> - -<P><HR> - -<H2><A NAME="loglevel">LogLevel directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LogLevel <EM>level</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>LogLevel error</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> LogLevel is only available in 1.3 or -later. - -<P>LogLevel adjusts the verbosity of the messages recorded in the -error logs (see <A HREF="#errorlog">ErrorLog</A> directive). -The following <EM>level</EM>s are available, in order of -decreasing significance: - -<P><TABLE> - <TR><TH ALIGN="LEFT"><STRONG>Level</STRONG> - <TH ALIGN="LEFT"><STRONG>Description</STRONG> - <TR><TH><TH ALIGN="LEFT"><STRONG>Example</STRONG> - <TR><TD><CODE>emerg</CODE> - <TD>Emergencies - system is unusable. - <TR><TD><TD>"Child cannot open lock file. Exiting" - <TR><TD><CODE>alert</CODE> - <TD>Action must be taken immediately. - <TR><TD><TD>"getpwuid: couldn't determine user name from uid" - <TR><TD><CODE>crit</CODE> - <TD>Critical Conditions. - <TR><TD><TD>"socket: Failed to get a socket, exiting child" - <TR><TD><CODE>error</CODE> - <TD>Error conditions. - <TR><TD><TD>"Premature end of script headers" - <TR><TD><CODE>warn</CODE> - <TD>Warning conditions. - <TR><TD><TD>"child process 1234 did not exit, sending another SIGHUP" - <TR><TD><CODE>notice</CODE> - <TD>Normal but significant condition. - <TR><TD><TD>"httpd: caught SIGBUS, attempting to dump core in ..." - <TR><TD><CODE>info</CODE> - <TD>Informational. - <TR><TD><TD>"Server seems busy, (you may need to increase StartServers, or - Min/MaxSpareServers)..." - <TR><TD><CODE>debug</CODE> - <TD>Debug-level messages - <TR><TD><TD>"Opening config file ..." -</TABLE> - -<P>When a particular level is specified, messages from all other levels -of higher significance will be reported as well. <EM>E.g.</EM>, when -<CODE>LogLevel info</CODE> is specified, then messages with log levels of -<CODE>notice</CODE> and <CODE>warn</CODE> will also be posted. -<P> -Using a level of at least <CODE>crit</CODE> is recommended. -<P><HR> - -<H2><A NAME="maxclients">MaxClients directive</A></H2> -<!--%plaintext <?INDEX {\tt MaxClients} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MaxClients <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MaxClients 256</CODE><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> core<P> - -<P>The MaxClients directive sets the limit on the number of simultaneous -requests that can be supported; not more than this number of child server -processes will be created. To configure more than 256 clients, you must -edit the HARD_SERVER_LIMIT entry in httpd.h and recompile. - -<P>Any connection attempts over the MaxClients limit will normally -be queued, up to a number based on the <A HREF="#listenbacklog"> -ListenBacklog</A> directive. Once a child process is freed at the -end of a different request, the connection will then be serviced. - -<HR> - -<H2><A NAME="maxkeepaliverequests">MaxKeepAliveRequests directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MaxKeepAliveRequests <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MaxKeepAliveRequests 100</CODE><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> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Only available in Apache -1.2 and later. - -<P>The MaxKeepAliveRequests directive limits the number of requests -allowed per connection when <A HREF="#keepalive">KeepAlive</A> is -on. If it is set to "<CODE>0</CODE>", unlimited requests will be -allowed. We recommend that this setting be kept to a high value for -maximum server performance.</P><HR> - -<H2><A NAME="maxrequestsperchild">MaxRequestsPerChild directive</A></H2> -<!--%plaintext <?INDEX {\tt MaxRequestsPerChild} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MaxRequestsPerChild <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MaxRequestsPerChild 0</CODE><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> core<P> - -The MaxRequestsPerChild directive sets the limit on the number of requests -that an individual child server process will handle. After MaxRequestsPerChild -requests, the child process will die. If MaxRequestsPerChild is 0, then -the process will never expire.<P> - -Setting MaxRequestsPerChild to a non-zero limit has two beneficial effects: -<UL> -<LI>it limits the amount of memory that process can consume by (accidental) -memory leakage; -<LI> by giving processes a finite lifetime, it helps reduce the -number of processes when the server load reduces. -</UL> - -<P>This directive has no effect on Win32. - -<P><STRONG>NOTE:</STRONG> For <EM>KeepAlive</EM> requests, only the first -request is counted towards this limit. In effect, it changes the -behavior to limit the number of <EM>connections</EM> per child. - -<P><HR> - -<H2><A NAME="maxspareservers">MaxSpareServers directive</A></H2> -<!--%plaintext <?INDEX {\tt MaxSpareServers} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MaxSpareServers <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MaxSpareServers 10</CODE><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> core<P> - -The MaxSpareServers directive sets the desired maximum number of <EM>idle</EM> -child server processes. An idle process is one which is not handling -a request. If there are more than MaxSpareServers idle, then the parent -process will kill off the excess processes.<P> - -Tuning of this parameter should only be necessary on very busy sites. -Setting this parameter to a large number is almost always a bad idea.<P> - -This directive has no effect when used with the Apache Web server on a -Microsoft Windows platform. - -<P> - -See also <A HREF="#minspareservers">MinSpareServers</A> and -<A HREF="#startservers">StartServers</A>.<P><HR> - -<H2><A NAME="minspareservers">MinSpareServers directive</A></H2> -<!--%plaintext <?INDEX {\tt MinSpareServers} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MinSpareServers <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MinSpareServers 5</CODE><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> core<P> - -The MinSpareServers directive sets the desired minimum number of <EM>idle</EM> -child server processes. An idle process is one which is not handling -a request. If there are fewer than MinSpareServers idle, then the parent -process creates new children at a maximum rate of 1 per second.<P> - -Tuning of this parameter should only be necessary on very busy sites. -Setting this parameter to a large number is almost always a bad idea.<P> - -This directive has no effect on Microsoft Windows. - -<P> - -See also <A HREF="#maxspareservers">MaxSpareServers</A> and -<A HREF="#startservers">StartServers</A>.<P><HR> - -<H2><A NAME="namevirtualhost">NameVirtualHost directive</A></H2> -<!--%plaintext <?INDEX {\tt NameVirtualHost} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> NameVirtualHost <EM>addr</EM>[:<EM>port</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> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> NameVirtualHost is only available in -Apache 1.3 and later<P> - -The NameVirtualHost directive is a required directive if you want to configure -<A HREF="../vhosts/index.html">name-based virtual hosts</A>.<P> - -Although <EM>addr</EM> can be hostname it is recommended that you always use -an IP address, <EM>e.g.</EM> - -<BLOCKQUOTE><CODE>NameVirtualHost 111.22.33.44</CODE></BLOCKQUOTE> - -With the NameVirtualHost directive you specify the address to which your -name-based virtual host names resolve. If you have multiple name-based -hosts on multiple addresses, repeat the directive for each address.<P> - -Note: the "main server" and any _default_ servers will <STRONG>never</STRONG> -be served for a request to a NameVirtualHost IP Address (unless for some -reason you specify NameVirtualHost but then don't define any VirtualHosts -for that address).<P> - -Optionally you can specify a port number on which the name-based -virtual hosts should be used, <EM>e.g.</EM> - -<BLOCKQUOTE><CODE>NameVirtualHost 111.22.33.44:8080</CODE></BLOCKQUOTE> - -<STRONG>See also:</STRONG> -<A HREF="../vhosts/index.html">Apache Virtual Host documentation</A> -<HR> -<H2><A NAME="options">Options directive</A></H2> -<!--%plaintext <?INDEX {\tt Options} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Options <EM>[+|-]option [+|-]option ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, -.htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Options<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -The Options directive controls which server features are available in -a particular directory. -<P> -<EM>option</EM> can be set to <CODE>None</CODE>, in which case none of -the extra features are enabled, or one or more of the following: -<DL> -<DT>All -<DD>All options except for MultiViews. This is the default setting. -<DT>ExecCGI -<DD> -<!--%plaintext <?INDEX {\tt ExecCGI} option> --> -Execution of CGI scripts is permitted. -<DT>FollowSymLinks -<DD> -<!--%plaintext <?INDEX {\tt FollowSymLinks} option> --> -The server will follow symbolic links in this directory. -<BR> -<STRONG>Note</STRONG>: even though the server follows the symlink it -does <EM>not</EM> -change the pathname used to match against <CODE><Directory></CODE> -sections. -<BR> -<STRONG>Note</STRONG>: this option gets ignored if set inside a -<Location> section. - -<DT>Includes -<DD> -<!--%plaintext <?INDEX {\tt Includes} option> --> -Server-side includes are permitted. -<DT>IncludesNOEXEC -<DD> -<!--%plaintext <?INDEX {\tt IncludesNOEXEC} option> --> -Server-side includes are permitted, but the #exec command and -#include of CGI scripts are disabled. -<DT>Indexes -<DD> -<!--%plaintext <?INDEX {\tt Indexes} option> --> -If a URL which maps to a directory is requested, and the there is no -DirectoryIndex (<EM>e.g.</EM>, index.html) in that directory, then the server will -return a formatted listing of the directory. -<DT>MultiViews -<DD> -<!--%plaintext <?INDEX {\tt MultiViews} option> --> -<A HREF="../content-negotiation.html">Content negotiated</A> MultiViews are -allowed. -<DT>SymLinksIfOwnerMatch -<DD> -<!--%plaintext <?INDEX {\tt SymLinksIfOwnerMatch} option> --> -The server will only follow symbolic links for which the target -file or directory is owned by the same user id as the link. -<BR> -<STRONG>Note</STRONG>: this option gets ignored if set inside a -<Location> section. -</DL> - -Normally, if multiple <CODE>Options</CODE> could apply to a directory, -then the most specific one is taken complete; the options are not -merged. However if <EM>all</EM> the options on the <CODE>Options</CODE> -directive are preceded by a + or - symbol, the options are -merged. Any options preceded by a + are added to the options -currently in force, and any options preceded by a - are removed from -the options currently in force. <P> - -For example, without any + and - symbols: - -<BLOCKQUOTE><CODE> -<Directory /web/docs> <BR> -Options Indexes FollowSymLinks<BR> -</Directory><BR> -<Directory /web/docs/spec> <BR> -Options Includes<BR> -</Directory> -</CODE></BLOCKQUOTE> -then only <CODE>Includes</CODE> will be set for the /web/docs/spec -directory. However if the second <CODE>Options</CODE> directive uses the + -and - symbols:<P> - -<BLOCKQUOTE><CODE> -<Directory /web/docs> <BR> -Options Indexes FollowSymLinks<BR> -</Directory><BR> -<Directory /web/docs/spec> <BR> -Options +Includes -Indexes<BR> -</Directory> -</CODE></BLOCKQUOTE> -then the options <CODE>FollowSymLinks</CODE> and <CODE>Includes</CODE> -are set for the /web/docs/spec directory.<P> - -<STRONG>Note:</STRONG> Using <CODE>-IncludesNOEXEC</CODE> or -<CODE>-Includes</CODE> -disables server-side includes completely regardless of the previous setting.<P> - -The default in the absence of any other settings is <CODE>All</CODE>.<P> -<HR> - -<H2><A NAME="pidfile">PidFile directive</A></H2> -<!--%plaintext <?INDEX {\tt PidFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> PidFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>PidFile logs/httpd.pid</CODE><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> core<P> - -The PidFile directive sets the file to which the server records the -process id of the daemon. If the filename does not begin with a slash (/) -then it is assumed to be relative to the <A HREF="#serverroot">ServerRoot</A>. -The PidFile is only used in <A HREF="#servertype">standalone</A> mode.<P> - -It is often useful to be able to send the server a signal, so that it closes -and then reopens its <A HREF="#errorlog">ErrorLog</A> and TransferLog, and -re-reads its configuration files. This is done by sending a SIGHUP (kill -1) -signal to the process id listed in the PidFile.<P> - -The PidFile is subject to the same warnings about log file placement and -<A HREF="../misc/security_tips.html#serverroot">security</A>. - -<P><HR> - -<H2><A NAME="port">Port directive</A></H2> -<!--%plaintext <?INDEX {\tt Port} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Port <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Port 80</CODE><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> core<P> - -<EM>Number</EM> is a number from 0 to 65535; some port numbers -(especially below -1024) are reserved for particular protocols. See <CODE>/etc/services</CODE> -for a list of some defined ports; the standard port for the http protocol -is 80.<P> - -The Port directive has two behaviors, the first of which is necessary for -NCSA backwards compatibility (and which is confusing in the context of -Apache).<P> - -<UL> -<LI> -In the absence of any <A HREF="#listen">Listen</A> or -<A HREF="#bindaddress">BindAddress</A> directives specifying a port number, -a Port directive given in the "main server" -(<EM>i.e.</EM>, outside any <A HREF="#virtualhost"><VirtualHost></A> section) -sets the network port on which the server listens. -If there are any Listen or BindAddress directives specifying -<CODE>:number</CODE> then Port has no effect on what address the server -listens at. - -<LI>The Port directive -sets the <CODE>SERVER_PORT</CODE> environment variable (for -<A HREF="mod_cgi.html">CGI</A> and <A HREF="mod_include.html">SSI</A>), -and is used when the server must generate a URL that refers to itself -(for example when creating an external redirect to itself). This -behaviour is modified by -<A HREF="#usecanonicalname">UseCanonicalName</A>. -</UL> - -In no event does a Port setting affect -what ports a <A HREF="#virtualhost">VirtualHost</A> responds on, the -VirtualHost directive itself is used for that.<P> - -The primary behaviour of Port should be considered to be similar to that of -the <A HREF="#servername">ServerName</A> directive. The ServerName -and Port together specify what you consider to be the <EM>canonical</EM> -address of the server. -(See also <A HREF="#usecanonicalname">UseCanonicalName</A>.)<P> - -Port 80 is one of Unix's special ports. All ports numbered -below 1024 are reserved for system use, <EM>i.e.</EM>, regular (non-root) users cannot -make use of them; instead they can only use higher port numbers. -To use port 80, you must start the server from the root account. -After binding to the port and before accepting requests, Apache will change -to a low privileged user as set by the <A HREF="#user">User directive</A>.<P> - -If you cannot use port 80, choose any other unused port. Non-root users -will have to choose a port number higher than 1023, such as 8000.<P> - -SECURITY: if you do start the server as root, be sure -not to set <A HREF="#user">User</A> to root. If you run the server as -root whilst handling connections, your site may be open to a major security -attack.<P><HR> - -<H2><A NAME="require">require directive</A></H2> -<!--%plaintext <?INDEX {\tt require} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> require <EM>entity-name entity entity...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -This directive selects which authenticated users can access a directory. -The allowed syntaxes are: -<UL> -<LI>require user <EM>userid userid ...</EM><P> -Only the named users can access the directory.<P> -<LI>require group <EM>group-name group-name ...</EM><P> -Only users in the named groups can access the directory.<P> -<LI>require valid-user<P> -All valid users can access the directory. -</UL> -<P> -Require must be accompanied by <A HREF="#authname">AuthName</A> and -<A HREF="#authtype">AuthType</A> directives, and directives such as -<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and -<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> (to define users and -groups) in order to work correctly. Example: -<BLOCKQUOTE><CODE> -AuthType Basic<BR> -AuthName "Restricted Directory"<BR> -AuthUserFile /web/users<BR> -AuthGroupFile /web/groups<BR> -require group admin<BR> -</CODE></BLOCKQUOTE> - -Access controls which are applied in this way are effective for -<STRONG>all</STRONG> methods. <STRONG>This is what is normally -desired.</STRONG> If you wish to apply access controls only to -specific methods, while leaving other methods unprotected, then place -the <CODE>require</CODE> statement into a <A -HREF="#limit"><Limit></A> section<P><HR> - -<H2><A NAME="resourceconfig">ResourceConfig directive</A></H2> -<!--%plaintext <?INDEX {\tt ResourceConfig} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ResourceConfig <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ResourceConfig conf/srm.conf</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -The server will read this file for more directives after reading the -httpd.conf file. <EM>Filename</EM> is relative to the -<A HREF="#serverroot">ServerRoot</A>. -This feature can be disabled using: -<BLOCKQUOTE><CODE>ResourceConfig /dev/null</CODE></BLOCKQUOTE> -Historically, this file contained most directives except for server -configuration directives and <A HREF="#directory"><Directory></A> -sections; in fact it can now contain any server directive allowed in the -<EM>server config</EM> context.<P> - -See also <A HREF="#accessconfig">AccessConfig</A>.<P><HR> - -<H2><A NAME="rlimit">RLimitCPU</A> <A NAME="rlimitcpu">directive</A></H2> -<!--%plaintext <?INDEX {\tt RLimitCPU} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RLimitCPU <EM># or 'max'</EM> - <EM>[# or 'max']</EM> -<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>Unset; uses operating system defaults</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> RLimitCPU is only available in Apache 1.2 -and later<P> - -Takes 1 or 2 parameters. The first parameter sets the soft resource limit -for all processes and the second parameter sets the maximum resource limit. -Either parameter can be a number, or <EM>max</EM> to indicate to the server -that the limit should be set to the maximum allowed by the operating system -configuration. Raising the maximum resource limit requires that the server -is running as root, or in the initial startup phase.<P> - -This applies to processes forked off from Apache children servicing requests, -not the Apache children themselves. This includes CGI scripts and SSI -exec commands, but not any processes forked off from the Apache parent -such as piped logs.<P> - -CPU resource limits are expressed in seconds per process.<P> - -See also <A HREF="#rlimitmem">RLimitMEM</A> or -<A HREF="#rlimitnproc">RLimitNPROC</A>.<P><HR> - -<H2><A NAME="rlimitmem">RLimitMEM directive</A></H2> -<!--%plaintext <?INDEX {\tt RLimitMEM} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RLimitMEM <EM># or 'max'</EM> - <EM>[# or 'max']</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>Unset; uses operating system defaults</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> RLimitMEM is only available in Apache 1.2 -and later<P> - -Takes 1 or 2 parameters. The first parameter sets the soft resource limit for -all processes and the second parameter sets the maximum resource limit. Either -parameter can be a number, or <EM>max</EM> to indicate to the server that the -limit should be set to the maximum allowed by the operating system -configuration. Raising the maximum resource limit requires that the -server is running as root, or in the initial startup phase.<P> - -This applies to processes forked off from Apache children servicing requests, -not the Apache children themselves. This includes CGI scripts and SSI -exec commands, but not any processes forked off from the Apache parent -such as piped logs.<P> - -Memory resource limits are expressed in bytes per process.<P> - -See also <A HREF="#rlimitcpu">RLimitCPU</A> or -<A HREF="#rlimitnproc">RLimitNPROC</A>.<P><HR> - -<H2><A NAME="rlimitnproc">RLimitNPROC directive</A></H2> -<!--%plaintext <?INDEX {\tt RLimitNPROC} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RLimitNPROC <EM># or 'max'</EM> - <EM>[# or 'max']</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>Unset; uses operating system defaults</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> RLimitNPROC is only available in Apache -1.2 and later<P> - -Takes 1 or 2 parameters. The first parameter sets the soft resource limit -for all processes and the second parameter sets the maximum resource limit. -Either parameter can be a number, or <EM>max</EM> to indicate to the server -that the limit should be set to the maximum allowed by the operating system -configuration. Raising the maximum resource limit requires that the server -is running as root, or in the initial startup phase.<P> - -This applies to processes forked off from Apache children servicing requests, -not the Apache children themselves. This includes CGI scripts and SSI -exec commands, but not any processes forked off from the Apache parent -such as piped logs.<P> - -Process limits control the number of processes per user.<P> - -Note: If CGI processes are <STRONG>not</STRONG> running under userids other -than the -web server userid, this directive will limit the number of processes that the -server itself can create. Evidence of this situation will be indicated by -<STRONG><EM>cannot fork</EM></STRONG> messages in the error_log.<P> - -See also <A HREF="#rlimitmem">RLimitMEM</A> or -<A HREF="#rlimitcpu">RLimitCPU</A>. - -<P><HR> - -<H2><A NAME="satisfy">Satisfy directive</A></H2> -<!--%plaintext <?INDEX {\tt Satisfy} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Satisfy <EM>'any' or 'all'</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> Satisfy all<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Satisfy is only available in Apache 1.2 -and later<P> - -Access policy if both allow and require used. The parameter can be -either <EM>'all'</EM> or <EM>'any'</EM>. This directive is only useful -if access to a particular area is being restricted by both -username/password <EM>and</EM> client host address. In this case the -default behavior ("all") is to require that the client passes the -address access restriction <EM>and</EM> enters a valid username and -password. With the "any" option the client will be granted access if -they either pass the host restriction or enter a valid username and -password. This can be used to password restrict an area, but to let -clients from particular addresses in without prompting for a password. - - -<P><HR> - -<H2><A NAME="scoreboardfile">ScoreBoardFile directive</A></H2> -<!--%plaintext <?INDEX {\tt ScoreBoardFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScoreBoardFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ScoreBoardFile logs/apache_status</CODE> -<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> core<P> - -The ScoreBoardFile directive is required on some architectures to place -a file that the server will use to communicate between its children and -the parent. The easiest way to find out if your architecture requires -a scoreboard file is to run Apache and see if it creates the file named -by the directive. If your architecture requires it then you must ensure -that this file is not used at the same time by more than one invocation -of Apache.<P> - -If you have to use a ScoreBoardFile then you may see improved speed by -placing it on a RAM disk. But be careful that you heed the same warnings -about log file placement and -<A HREF="../misc/security_tips.html">security</A>.<P> - -Apache 1.2 and above:<P> - -Linux 1.x users might be able to add -<CODE>-DHAVE_SHMGET -DUSE_SHMGET_SCOREBOARD</CODE> to -the <CODE>EXTRA_CFLAGS</CODE> in your <CODE>Configuration</CODE>. This -might work with some 1.x installations, but won't work with all of -them. (Prior to 1.3b4, <CODE>HAVE_SHMGET</CODE> would have sufficed.)<P> - -SVR4 users should consider adding -<CODE>-DHAVE_SHMGET -DUSE_SHMGET_SCOREBOARD</CODE> to the -<CODE>EXTRA_CFLAGS</CODE> in your <CODE>Configuration</CODE>. This -is believed to work, but we were unable to test it in time for 1.2 -release. (Prior to 1.3b4, <CODE>HAVE_SHMGET</CODE> would have sufficed.)<P> - -<STRONG>See Also</STRONG>: -<A HREF="../stopping.html">Stopping and Restarting Apache</A></P> - -<P><HR> - -<H2><A NAME="scriptinterpretersource">ScriptInterpreterSource directive</A></H2> -<!--%plaintext <?INDEX {\tt ScriptInterpreterSource} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScriptInterpreterSource <EM>'registry' or 'script'</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ScriptInterpreterSource script</CODE> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core (Windows only)<P> - -This directive is used to control how Apache 1.3.5 and later finds the interpreter -used to run CGI scripts. The default technique is to use the interpreter pointed to by -the #! line in the script. Setting ScriptInterpreterSource registry will cause the -Windows Registry to be searched using the script file extension (e.g., .pl) as a search key. -<P><HR> - -<H2><A NAME="sendbuffersize">SendBufferSize directive</A></H2> -<!--%plaintext <?INDEX {\tt SendBufferSize} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> SendBufferSize <EM>bytes</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> core<P> - -The server will set the TCP buffer size to the number of bytes -specified. Very useful to increase past standard OS defaults on high -speed high latency (<EM>i.e.</EM>, 100ms or so, such as transcontinental -fast pipes) -<P><HR> - -<H2><A NAME="serveradmin">ServerAdmin directive</A></H2> -<!--%plaintext <?INDEX {\tt ServerAdmin} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ServerAdmin <EM>email-address</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -The ServerAdmin sets the e-mail address that the server includes in any -error messages it returns to the client.<P> - -It may be worth setting up a dedicated address for this, <EM>e.g.</EM> -<BLOCKQUOTE><CODE>ServerAdmin www-admin@foo.bar.com</CODE></BLOCKQUOTE> -as users do not always mention that they are talking about the server!<P><HR> - -<H2><A NAME="serveralias">ServerAlias directive</A></H2> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ServerAlias <EM>host1 host2 ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ServerAlias is only available in Apache -1.1 and later.<P> - -The ServerAlias directive sets the alternate names for a host, for use -with -<A HREF="../vhosts/name-based.html">name-based virtual hosts</A>. - -<P><STRONG>See also:</STRONG> -<A HREF="../vhosts/index.html">Apache Virtual Host documentation</A> - -<HR> - -<H2><A NAME="servername">ServerName directive</A></H2> -<!--%plaintext <?INDEX {\tt ServerName} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ServerName <EM>fully-qualified domain name</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -The ServerName directive sets the hostname of the server; this is only -used when creating redirection URLs. If it is not specified, then the -server attempts to deduce it from its own IP address; however this may -not work reliably, or may not return the preferred hostname. For example: -<BLOCKQUOTE><CODE>ServerName www.wibble.com</CODE></BLOCKQUOTE> -would be used if the canonical (main) name of the actual machine -were <CODE>monster.wibble.com</CODE>.<P> -<P><STRONG>See Also</STRONG>:<BR> -<A HREF="../dns-caveats.html">DNS Issues</A><BR> -<A HREF="#usecanonicalname">UseCanonicalName</A><BR> -</P> -<HR> - -<H2><A NAME="serverpath">ServerPath directive</A></H2> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ServerPath <EM>pathname</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ServerPath is only available in Apache -1.1 and later.<P> - -The ServerPath directive sets the legacy URL pathname for a host, for -use with <A HREF="../vhosts/index.html">name-based virtual hosts</A>. - -<P><STRONG>See also:</STRONG> -<A HREF="../vhosts/index.html">Apache Virtual Host documentation</A> - -<HR> - -<H2><A NAME="serverroot">ServerRoot directive</A></H2> -<!--%plaintext <?INDEX {\tt ServerRoot} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ServerRoot <EM>directory-filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ServerRoot /usr/local/apache</CODE><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> core<P> - -The ServerRoot directive sets the directory in which the server lives. -Typically it will contain the subdirectories <CODE>conf/</CODE> and -<CODE>logs/</CODE>. Relative paths for other configuration files are taken -as relative to this directory.<P> - -See also <A HREF="../invoking.html">the <CODE>-d</CODE> option to httpd</A>.<P> -See also <A HREF="../misc/security_tips.html#serverroot">the security tips</A> -for information on how to properly set permissions on the ServerRoot.<P> - -<HR> - -<H2><A NAME="serversignature">ServerSignature directive</A></H2> -<!--%plaintext <?INDEX {\tt ServerSignature} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ServerSignature <EM>Off | On | EMail</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ServerSignature Off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, -.htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ServerSignature is only available in -Apache -1.3 and later.<P> - -The ServerSignature directive allows the configuration of a trailing -footer line under server-generated documents (error messages, -mod_proxy ftp directory listings, mod_info output, ...). The reason -why you would want to enable such a footer line is that in a chain -of proxies, the user often has no possibility to tell which of the -chained servers actually produced a returned error message.<BR> -The <SAMP>Off</SAMP> setting, which is the default, suppresses the -error line (and is therefore compatible with the behavior of -Apache-1.2 and below). The <SAMP>On</SAMP> setting simply adds a -line with the server version number and <A -HREF="#servername">ServerName</A> of the serving virtual host, and -the <SAMP>EMail</SAMP> setting additionally creates a "mailto:" -reference to the <A HREF="#serveradmin">ServerAdmin</A> of the -referenced document. - -<HR> - -<H2><A NAME="servertokens">ServerTokens directive</A></H2> -<!--%plaintext <?INDEX {\tt ServerTokens} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ServerTokens <EM>Minimal|OS|Full</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ServerTokens Full</CODE><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> core<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ServerTokens is only available - in Apache 1.3 and later - -<P> -This directive controls whether <SAMP>Server</SAMP> response header -field which is sent back to clients includes a description of the generic -OS-type of the server as well as information about compiled-in modules. -</P> -<DL> - <DT><CODE>ServerTokens Min[imal]</CODE> - </DT> - <DD>Server sends (<EM>e.g.</EM>): <SAMP>Server: Apache/1.3.0</SAMP> - </DD> - <DT><CODE>ServerTokens OS</CODE> - </DT> - <DD>Server sends (<EM>e.g.</EM>): <SAMP>Server: Apache/1.3.0 (Unix)</SAMP> - </DD> - <DT><CODE>ServerTokens Full</CODE> (or not specified) - </DT> - <DD>Server sends (<EM>e.g.</EM>): <SAMP>Server: Apache/1.3.0 (Unix) PHP/3.0 - MyMod/1.2</SAMP> - </DD> -</DL> -<P> -This setting applies to the entire server, and cannot be enabled or -disabled on a virtualhost-by-virtualhost basis. -</P> - -<HR> - -<H2><A NAME="servertype">ServerType directive</A></H2> -<!--%plaintext <?INDEX {\tt ServerType} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ServerType <EM>type</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ServerType standalone</CODE><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> core<P> - -The ServerType directive sets how the server is executed by the system. -<EM>Type</EM> is one of -<DL> -<DT>inetd -<DD>The server will be run from the system process inetd; the command to start -the server is added to <CODE>/etc/inetd.conf</CODE> -<DT>standalone -<DD>The server will run as a daemon process; the command to start the server -is added to the system startup scripts. (<CODE>/etc/rc.local</CODE> or -<CODE>/etc/rc3.d/...</CODE>.) -</DL> - -Inetd is the lesser used of the two options. For each http -connection received, a new copy of the server is started from scratch; -after the connection is complete, this program exits. There is a high price to -pay per connection, but for security reasons, some admins prefer this option. -<FONT COLOR="red">Inetd mode is no longer recommended and does not always -work properly. Avoid it if at all possible.</FONT> -<P> - -Standalone is the most common setting for ServerType since -it is far more efficient. The server is started once, and services all -subsequent connections. If you intend running Apache to serve a busy site, -standalone will probably be your only option.<P> -<HR> -<H2><A NAME="startservers">StartServers directive</A></H2> -<!--%plaintext <?INDEX {\tt StartServers} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> StartServers <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>StartServers 5</CODE><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> core<P> - -The StartServers directive sets the number of child server processes created -on startup. As the number of processes is dynamically controlled depending -on the load, there is usually little reason to adjust this parameter.<P> - -<P>When running under Microsoft Windows, this directive has no effect. - There is always one child which handles all requests. Within the - child requests are handled by separate threads. The - <A HREF="#threadsperchild">ThreadsPerChild</A> directive controls - the maximum number of child threads handling requests, which will - have a similar effect to the setting of <SAMP>StartServers</SAMP> - on Unix. - -<P> - -See also <A HREF="#minspareservers">MinSpareServers</A> and -<A HREF="#maxspareservers">MaxSpareServers</A>.<P><HR> - -<H2><A NAME="threadsperchild">ThreadsPerChild</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ThreadsPerChild <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ThreadsPerChild 50</CODE><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> core (Windows)<BR> -<STRONG>Compatibility:</STRONG> Available only with Apache 1.3 and later -with Windows - -<P>This directive 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. - -<P>This directive has no effect on Unix systems. Unix users should look - at <A HREF="#startservers">StartServers</A> and <A - HREF="#maxrequestsperchild">MaxRequestsPerChild</A>.</P> - -<HR> - -<H2><A NAME="timeout">TimeOut directive</A></H2> -<!--%plaintext <?INDEX {\tt TimeOut} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> TimeOut <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>TimeOut 300</CODE><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> core<P> - -The TimeOut directive currently defines the amount of time Apache will -wait for three things: - -<OL> - <LI>The total amount of time it takes to receive a GET request. - <LI>The amount of time between receipt of TCP packets on a POST or - PUT request. - <LI>The amount of time between ACKs on transmissions of TCP packets - in responses. -</OL> - -We plan on making these separately configurable at some point down the -road. The timer used to default to 1200 before 1.2, but has been -lowered to 300 which is still far more than necessary in most -situations. It is not set any lower by default because there may -still be odd places in the code where the timer is not reset when -a packet is sent. - -<P><HR> - -<H2><A NAME="usecanonicalname">UseCanonicalName directive</A></H2> -<!--%plaintext <?INDEX {\tt UseCanonicalName} directive> --> -<A HREF="directive-dict.html#Syntax" REL="Help"> -<STRONG>Syntax:</STRONG></A> UseCanonicalName <EM>on|off|dns</EM><BR> -<A HREF="directive-dict.html#Default" REL="Help"> -<STRONG>Default:</STRONG></A> <CODE>UseCanonicalName on</CODE><BR> -<A HREF="directive-dict.html#Context" REL="Help"> -<STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A HREF="directive-dict.html#Override" REL="Help"> -<STRONG>Override:</STRONG></A> Options<BR> -<A HREF="directive-dict.html#Compatibility" REL="Help"> -<STRONG>Compatibility:</STRONG></A> UseCanonicalName is only available in -Apache 1.3 and later<P> - -In many situations Apache has to construct a <EM>self-referential</EM> -URL. That is, a URL which refers back to the same server. -With <CODE>UseCanonicalName on</CODE> (and in all versions prior to -1.3) Apache will use the <A HREF="#servername">ServerName</A> and <A -HREF="#port">Port</A> directives to construct a canonical name for the -server. This name is used in all self-referential URLs, and for the -values of <CODE>SERVER_NAME</CODE> and <CODE>SERVER_PORT</CODE> in CGIs. - -<P>With <CODE>UseCanonicalName off</CODE> Apache will form -self-referential URLs using the hostname and port supplied -by the client if any are supplied (otherwise it will use the -canonical name). These values are the same that are used to -implement <A HREF="../vhosts/name-based.html">name based virtual -hosts</A>, and are available with the same clients. The CGI variables -<CODE>SERVER_NAME</CODE> and <CODE>SERVER_PORT</CODE> will be constructed -from the client supplied values as well. - -<P>An example where this may be useful is on an intranet server where -you have users connecting to the machine using short names such as -<CODE>www</CODE>. You'll notice that if the users type a shortname, -and a URL which is a directory, such as <CODE>http://www/splat</CODE>, -<EM>without the trailing slash</EM> then Apache will redirect them to -<CODE>http://www.domain.com/splat/</CODE>. If you have authentication -enabled, this will cause the user to have to reauthenticate twice (once -for <CODE>www</CODE> and once again for <CODE>www.domain.com</CODE>). -But if <CODE>UseCanonicalName</CODE> is set off, then Apache will redirect -to <CODE>http://www/splat/</CODE>. - -<P>There is a third option, <CODE>UseCanonicalName DNS</CODE>, which -is intended for use with mass IP-based virtual hosting to support -ancient clients that do not provide a <CODE>Host:</CODE> header. With -this option Apache does a reverse DNS lookup on the server IP address -that the client connected to in order to work out self-referential URLs. - -<P><STRONG>Warning:</STRONG> if CGIs make assumptions about the values of -<CODE>SERVER_NAME</CODE> they may be broken by this option. The client -is essentially free to give whatever value they want as a hostname. -But if the CGI is only using <CODE>SERVER_NAME</CODE> to construct -self-referential URLs then it should be just fine. - -<P><STRONG>See also:</STRONG> -<A HREF="#servername">ServerName</A>, -<A HREF="#port">Port</A> - -<P><HR> - -<H2><A NAME="user">User directive</A></H2> -<!--%plaintext <?INDEX {\tt User} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> User <EM>unix-userid</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>User #-1</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<P> - -The User directive sets the userid as which the server will answer requests. -In order to use this directive, the standalone server must be run initially -as root. <EM>Unix-userid</EM> is one of: -<DL> -<DT>A username -<DD>Refers to the given user by name. -<DT># followed by a user number. -<DD>Refers to a user by their number. -</DL> - -The user should have no privileges which result in it being able to access -files which are not intended to be visible to the outside world, and -similarly, the user should not be able to execute code which is not -meant for httpd requests. It is recommended that you set up a new user and -group specifically for running the server. Some admins use user -<CODE>nobody</CODE>, but this is not always possible or desirable. -For example mod_proxy's cache, when enabled, must be accessible to this user -(see the <A HREF="mod_proxy.html#cacheroot"><CODE>CacheRoot</CODE> -directive</A>).<P> - -Notes: If you start the server as a non-root user, it will fail to change -to the lesser privileged user, and will instead continue to run as -that original user. If you do start the server as root, then it is normal -for the parent process to remain running as root.<P> - -Special note: Use of this directive in <VirtualHost> requires a -properly configured <A HREF="../suexec.html">suEXEC wrapper</A>. -When used inside a <VirtualHost> in this manner, only the user -that CGIs are run as is affected. Non-CGI requests are still processed -with the user specified in the main User directive.<P> - -SECURITY: Don't set User (or <A HREF="#group">Group</A>) to -<CODE>root</CODE> unless you know exactly what you are doing, and what the -dangers are.<P><HR> - -<H2><A NAME="virtualhost"><VirtualHost> directive</A></H2> -<!--%plaintext <?INDEX {\tt VirtualHost} section directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <VirtualHost <EM>addr</EM>[:<EM>port</EM>] - ...> ... -</VirtualHost> <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> Core.<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Non-IP address-based Virtual Hosting only -available in Apache 1.1 and later.<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Multiple address support only available in -Apache 1.2 and later.<P> - -<VirtualHost> and </VirtualHost> are used to enclose a group of -directives which will apply only to a particular virtual host. -Any directive which is allowed in a virtual host context may be used. -When the server receives a request for a document on a particular virtual -host, it uses the configuration directives enclosed in the <VirtualHost> -section. <EM>Addr</EM> can be -<MENU> -<LI>The IP address of the virtual host -<LI>A fully qualified domain name for the IP address of the virtual host. -</MENU> Example: -<BLOCKQUOTE> -<CODE> -<VirtualHost 10.1.2.3> <BR> -ServerAdmin webmaster@host.foo.com <BR> -DocumentRoot /www/docs/host.foo.com <BR> -ServerName host.foo.com <BR> -ErrorLog logs/host.foo.com-error_log <BR> -TransferLog logs/host.foo.com-access_log <BR> -</VirtualHost> -</CODE></BLOCKQUOTE> - -Each VirtualHost must correspond to a different IP address, different port -number or a -different host name for the server, in the latter case the server -machine must be configured to accept IP packets for multiple -addresses. (If the machine does not have multiple network interfaces, -then this can be accomplished with the <CODE>ifconfig alias</CODE> -command (if your OS supports it), or with kernel patches like <A -HREF="../misc/vif-info.html">VIF</A> (for SunOS(TM) 4.1.x)).<P> - -The special name <CODE>_default_</CODE> can be specified in which case -this virtual host will match any IP address that is not explicitly listed -in another virtual host. In the absence of any _default_ virtual host -the "main" server config, consisting of all those definitions outside -any VirtualHost section, is used when no match occurs.<P> - -You can specify a <CODE>:port</CODE> to change the port that is matched. -If unspecified then it defaults to the same port as the most recent -<CODE><A HREF="#port">Port</A></CODE> statement of the main server. You -may also specify <CODE>:*</CODE> to match all ports on that address. -(This is recommended when used with <CODE>_default_</CODE>.)<P> - -<STRONG>SECURITY</STRONG>: See the -<A HREF="../misc/security_tips.html">security tips</A> -document for details on why your security could be compromised if -the directory where logfiles are stored is writable by anyone other -than the user that starts the server. - -<P><STRONG>NOTE</STRONG>: The use of <VirtualHost> does -<STRONG>not</STRONG> affect what addresses Apache listens on. You may -need to ensure that Apache is listening on the correct addresses using -either <A HREF="#bindaddress">BindAddress</A> or <A -HREF="#listen">Listen</A>. - -<P><STRONG>See also:</STRONG> -<A HREF="../vhosts/index.html">Apache Virtual Host documentation</A><BR> -<STRONG>See also:</STRONG> -<A HREF="../dns-caveats.html">Warnings about DNS and Apache</A><BR> -<STRONG>See also:</STRONG> -<A HREF="../bind.html">Setting which addresses and ports Apache uses</A><BR> -<STRONG>See also</STRONG>: <A HREF="../sections.html">How Directory, -Location and Files sections work</A> for an explanation of how these -different sections are combined when a request is received -</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/directive-dict.html b/docs/manual/mod/directive-dict.html deleted file mode 100644 index 03a9c3f67e..0000000000 --- a/docs/manual/mod/directive-dict.html +++ /dev/null @@ -1,265 +0,0 @@ -<!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>, - <SAMP><Location></SAMP>, and <SAMP><Files></SAMP> - containers in the server configuration files, subject to the - restrictions outlined in <A HREF="../sections.html">How Directory, - Location and Files sections work</A>. - <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#allowoverride" - REL="Help" - ><SAMP>AllowOverride</SAMP></A> - directive, and apply to a particular scope (such as a directory) and - all descendants, unless further modified by other - <SAMP>AllowOverride</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> diff --git a/docs/manual/mod/directive-dict.html.en b/docs/manual/mod/directive-dict.html.en deleted file mode 100644 index 03a9c3f67e..0000000000 --- a/docs/manual/mod/directive-dict.html.en +++ /dev/null @@ -1,265 +0,0 @@ -<!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>, - <SAMP><Location></SAMP>, and <SAMP><Files></SAMP> - containers in the server configuration files, subject to the - restrictions outlined in <A HREF="../sections.html">How Directory, - Location and Files sections work</A>. - <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#allowoverride" - REL="Help" - ><SAMP>AllowOverride</SAMP></A> - directive, and apply to a particular scope (such as a directory) and - all descendants, unless further modified by other - <SAMP>AllowOverride</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> diff --git a/docs/manual/mod/directives.html b/docs/manual/mod/directives.html deleted file mode 100644 index a95fe97ec6..0000000000 --- a/docs/manual/mod/directives.html +++ /dev/null @@ -1,223 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache directives</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache Directives</H1> -<P> -Each Apache directive available in the standard Apache distribution is -listed here. They are described using a consistent format, and there is -<A - HREF="directive-dict.html" - REL="Glossary" ->a dictionary</A> -of the terms used in their descriptions available. -</P> -<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_autoindex.html#addalt">AddAlt</A> -<LI><A HREF="mod_autoindex.html#addaltbyencoding">AddAltByEncoding</A> -<LI><A HREF="mod_autoindex.html#addaltbytype">AddAltByType</A> -<LI><A HREF="mod_autoindex.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_autoindex.html#addicon">AddIcon</A> -<LI><A HREF="mod_autoindex.html#addiconbyencoding">AddIconByEncoding</A> -<LI><A HREF="mod_autoindex.html#addiconbytype">AddIconByType</A> -<LI><A HREF="mod_mime.html#addlanguage">AddLanguage</A> -<LI><A HREF="core.html#addmodule">AddModule</A> -<LI><A HREF="mod_info.html#addmoduleinfo">AddModuleInfo</A> -<LI><A HREF="mod_mime.html#addtype">AddType</A> -<LI><A HREF="mod_log_agent.html#agentlog">AgentLog</A> -<LI><A HREF="mod_alias.html#alias">Alias</A> -<LI><A HREF="mod_alias.html#aliasmatch">AliasMatch</A> -<LI><A HREF="mod_access.html#allow">allow</A> -<LI><A HREF="core.html#allowoverride">AllowOverride</A> -<LI><A HREF="mod_auth_anon.html#anonymous">Anonymous</A> -<LI><A HREF="mod_auth_anon.html#Authoritative">Anonymous_Authoritative</A> -<LI><A HREF="mod_auth_anon.html#LogEmail">Anonymous_LogEmail</A> -<LI><A HREF="mod_auth_anon.html#MustGiveEmail">Anonymous_MustGiveEmail</A> -<LI><A HREF="mod_auth_anon.html#NoUserID">Anonymous_NoUserID</A> -<LI><A HREF="mod_auth_anon.html#VerifyEmail">Anonymous_VerifyEmail</A> -<LI><A HREF="mod_auth.html#authauthoritative">AuthAuthoritative</A> -<LI><A HREF="mod_auth_db.html#authdbauthoritative">AuthDBAuthoritative</A> -<LI><A HREF="mod_auth_db.html#authdbgroupfile">AuthDBGroupFile</A> -<LI><A HREF="mod_auth_dbm.html#authdbmauthoritative">AuthDBMAuthoritative</A> -<LI><A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> -<LI><A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> -<LI><A HREF="mod_auth_db.html#authdbuserfile">AuthDBUserFile</A> -<LI><A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A> -<LI><A HREF="mod_digest.html#authdigestfile">AuthDigestFile</A> -<LI><A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> -<LI><A HREF="core.html#authname">AuthName</A> -<LI><A HREF="core.html#authtype">AuthType</A> -<LI><A HREF="mod_auth.html#authuserfile">AuthUserFile</A> -<LI><A HREF="core.html#bindaddress">BindAddress</A> -<LI><A HREF="mod_setenvif.html#BrowserMatch">BrowserMatch</A> -<LI><A HREF="mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</A> -<LI><A HREF="core.html#bs2000account">BS2000Account</A> -<LI><A HREF="mod_proxy.html#cachedefaultexpire">CacheDefaultExpire</A> -<LI><A HREF="mod_proxy.html#cachedirlength">CacheDirLength</A> -<LI><A HREF="mod_proxy.html#cachedirlevels">CacheDirLevels</A> -<LI><A HREF="mod_proxy.html#cacheforcecompletion">CacheForceCompletion</A> -<LI><A HREF="mod_proxy.html#cachegcinterval">CacheGcInterval</A> -<LI><A HREF="mod_proxy.html#cachelastmodifiedfactor">CacheLastModifiedFactor</A> -<LI><A HREF="mod_proxy.html#cachemaxexpire">CacheMaxExpire</A> -<LI><A HREF="mod_negotiation.html#cachenegotiateddocs">CacheNegotiatedDocs</A> -<LI><A HREF="mod_proxy.html#cacheroot">CacheRoot</A> -<LI><A HREF="mod_proxy.html#cachesize">CacheSize</A> -<LI><A HREF="mod_speling.html#checkspelling">CheckSpelling</A> -<LI><A HREF="core.html#clearmodulelist">ClearModuleList</A> -<LI><A HREF="core.html#contentdigest">ContentDigest</A> -<LI><A HREF="mod_usertrack.html#cookieexpires">CookieExpires</A> -<LI><A HREF="mod_cookies.html#cookielog">CookieLog</A> (mod_cookies) -<LI><A HREF="mod_log_config.html#cookielog">CookieLog</A> (mod_log_config) -<LI><A HREF="mod_usertrack.html#cookietracking">CookieTracking</A> -<LI><A HREF="core.html#coredumpdirectory">CoreDumpDirectory</A> -<LI><A HREF="mod_log_config.html#customlog">CustomLog</A> -<LI><A HREF="mod_autoindex.html#defaulticon">DefaultIcon</A> -<LI><A HREF="mod_mime.html#defaultlanguage">DefaultLanguage</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="core.html#directorymatch"><DirectoryMatch></A> -<LI><A HREF="mod_dir.html#directoryindex">DirectoryIndex</A> -<LI><A HREF="core.html#documentroot">DocumentRoot</A> -<LI><A HREF="core.html#errordocument">ErrorDocument</A> -<LI><A HREF="core.html#errorlog">ErrorLog</A> -<LI><A HREF="mod_example.html#example">Example</A> -<LI><A HREF="mod_expires.html#expiresactive">ExpiresActive</A> -<LI><A HREF="mod_expires.html#expiresbytype">ExpiresByType</A> -<LI><A HREF="mod_expires.html#expiresdefault">ExpiresDefault</A> -<LI><A HREF="mod_status.html#extendedstatus">ExtendedStatus</A> -<LI><A HREF="mod_autoindex.html#fancyindexing">FancyIndexing</A> -<LI><A HREF="core.html#files"><Files></A> -<LI><A HREF="core.html#filesmatch"><FilesMatch></A> -<LI><A HREF="mod_mime.html#forcetype">ForceType</A> -<LI><A HREF="core.html#group">Group</A> -<LI><A HREF="mod_headers.html#header">Header</A> -<LI><A HREF="mod_autoindex.html#headername">HeaderName</A> -<LI><A HREF="core.html#hostnamelookups">HostNameLookups</A> -<LI><A HREF="core.html#identitycheck">IdentityCheck</A> -<LI><A HREF="core.html#ifdefine"><IfDefine></A> -<LI><A HREF="core.html#ifmodule"><IfModule></A> -<LI><A HREF="mod_imap.html#imapbase">ImapBase</A> -<LI><A HREF="mod_imap.html#imapdefault">ImapDefault</A> -<LI><A HREF="mod_imap.html#imapmenu">ImapMenu</A> -<LI><A HREF="core.html#include">Include</A> -<LI><A HREF="mod_autoindex.html#indexignore">IndexIgnore</A> -<LI><A HREF="mod_autoindex.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#limitexcept"><LimitExcept></A> -<LI><A HREF="core.html#limitrequestbody">LimitRequestBody</A> -<LI><A HREF="core.html#limitrequestfields">LimitRequestFields</A> -<LI><A HREF="core.html#limitrequestfieldsize">LimitRequestFieldsize</A> -<LI><A HREF="core.html#limitrequestline">LimitRequestLine</A> -<LI><A HREF="core.html#listen">Listen</A> -<LI><A HREF="core.html#listenbacklog">ListenBacklog</A> -<LI><A HREF="mod_so.html#loadfile">LoadFile</A> -<LI><A HREF="mod_so.html#loadmodule">LoadModule</A> -<LI><A HREF="core.html#location"><Location></A> -<LI><A HREF="core.html#locationmatch"><LocationMatch></A> -<LI><A HREF="core.html#lockfile">LockFile</A> -<LI><A HREF="mod_log_config.html#logformat">LogFormat</A> -<LI><A HREF="core.html#loglevel">LogLevel</A> -<LI><A HREF="core.html#maxclients">MaxClients</A> -<LI><A HREF="core.html#maxkeepaliverequests">MaxKeepAliveRequests</A> -<LI><A HREF="core.html#maxrequestsperchild">MaxRequestsPerChild</A> -<LI><A HREF="core.html#maxspareservers">MaxSpareServers</A> -<LI><A HREF="mod_cern_meta.html#metadir">MetaDir</A> -<LI><A HREF="mod_cern_meta.html#metafiles">MetaFiles</A> -<LI><A HREF="mod_cern_meta.html#metasuffix">MetaSuffix</A> -<LI><A HREF="mod_mime_magic.html#mimemagicfile">MimeMagicFile</A> -<LI><A HREF="core.html#minspareservers">MinSpareServers</A> -<LI><A HREF="mod_mmap_static.html#mmapfile">MMapFile</A> -<LI><A HREF="core.html#namevirtualhost">NameVirtualHost</A> -<LI><A HREF="mod_proxy.html#nocache">NoCache</A> -<LI><A HREF="core.html#options">Options</A> -<LI><A HREF="mod_access.html#order">order</A> -<LI><A HREF="mod_env.html#passenv">PassEnv</A> -<LI><A HREF="core.html#pidfile">PidFile</A> -<LI><A HREF="core.html#port">Port</A> -<LI><A HREF="mod_proxy.html#proxyblock">ProxyBlock</A> -<LI><A HREF="mod_proxy.html#proxypass">ProxyPass</A> -<LI><A HREF="mod_proxy.html#proxypassreverse">ProxyPassReverse</A> -<LI><A HREF="mod_proxy.html#proxyreceivebuffersize">ProxyReceiveBufferSize</A> -<LI><A HREF="mod_proxy.html#proxyremote">ProxyRemote</A> -<LI><A HREF="mod_proxy.html#proxyrequests">ProxyRequests</A> -<LI><A HREF="mod_proxy.html#proxyvia">ProxyVia</A> -<LI><A HREF="mod_autoindex.html#readmename">ReadmeName</A> -<LI><A HREF="mod_alias.html#redirect">Redirect</A> -<LI><A HREF="mod_alias.html#redirectmatch">RedirectMatch</A> -<LI><A HREF="mod_alias.html#redirectperm">RedirectPermanent</A> -<LI><A HREF="mod_alias.html#redirecttemp">RedirectTemp</A> -<LI><A HREF="mod_log_referer.html#refererignore">RefererIgnore</A> -<LI><A HREF="mod_log_referer.html#refererlog">RefererLog</A> -<LI><A HREF="mod_mime#removehandler">RemoveHandler</A> -<LI><A HREF="core.html#require">require</A> -<LI><A HREF="core.html#resourceconfig">ResourceConfig</A> -<LI><A HREF="mod_rewrite.html#RewriteBase">RewriteBase</A> -<LI><A HREF="mod_rewrite.html#RewriteCond">RewriteCond</A> -<LI><A HREF="mod_rewrite.html#RewriteEngine">RewriteEngine</A> -<LI><A HREF="mod_rewrite.html#RewriteLock">RewriteLock</A> -<LI><A HREF="mod_rewrite.html#RewriteLog">RewriteLog</A> -<LI><A HREF="mod_rewrite.html#RewriteLogLevel">RewriteLogLevel</A> -<LI><A HREF="mod_rewrite.html#RewriteMap">RewriteMap</A> -<LI><A HREF="mod_rewrite.html#RewriteOptions">RewriteOptions</A> -<LI><A HREF="mod_rewrite.html#RewriteRule">RewriteRule</A> -<LI><A HREF="core.html#rlimitcpu">RLimitCPU</A> -<LI><A HREF="core.html#rlimitmem">RLimitMEM</A> -<LI><A HREF="core.html#rlimitnproc">RLimitNPROC</A> -<LI><A HREF="core.html#satisfy">Satisfy</A> -<LI><A HREF="core.html#scoreboardfile">ScoreBoardFile</A> -<LI><A HREF="mod_actions.html#script">Script</A> -<LI><A HREF="mod_alias.html#scriptalias">ScriptAlias</A> -<LI><A HREF="mod_alias.html#scriptaliasmatch">ScriptAliasMatch</A> -<LI><A HREF="core.html#scriptinterpretersource">ScriptInterpreterSource</A> -<LI><A HREF="mod_cgi.html#scriptlog">ScriptLog</A> -<LI><A HREF="mod_cgi.html#scriptlogbuffer">ScriptLogBuffer</A> -<LI><A HREF="mod_cgi.html#scriptloglength">ScriptLogLength</A> -<LI><A HREF="core.html#sendbuffersize">SendBufferSize</A> -<LI><A HREF="core.html#serveradmin">ServerAdmin</A> -<LI><A HREF="core.html#serveralias">ServerAlias</A> -<LI><A HREF="core.html#servername">ServerName</A> -<LI><A HREF="core.html#serverpath">ServerPath</A> -<LI><A HREF="core.html#serverroot">ServerRoot</A> -<LI><A HREF="core.html#serversignature">ServerSignature</A> -<LI><A HREF="core.html#servertokens">ServerTokens</A> -<LI><A HREF="core.html#servertype">ServerType</A> -<LI><A HREF="mod_env.html#setenv">SetEnv</A> -<LI><A HREF="mod_setenvif.html#setenvif">SetEnvIf</A> -<LI><A HREF="mod_setenvif.html#SetEnvIfNoCase">SetEnvIfNoCase</A> -<LI><A HREF="mod_mime.html#sethandler">SetHandler</A> -<LI><A HREF="core.html#startservers">StartServers</A> -<LI><A HREF="core.html#threadsperchild">ThreadsPerChild</A> -<LI><A HREF="core.html#timeout">TimeOut</A> -<LI><A HREF="mod_log_config.html#transferlog">TransferLog</A> -<LI><A HREF="mod_mime.html#typesconfig">TypesConfig</A> -<LI><A HREF="mod_env.html#unsetenv">UnsetEnv</A> -<LI><A HREF="core.html#usecanonicalname">UseCanonicalName</A> -<LI><A HREF="core.html#user">User</A> -<LI><A HREF="mod_userdir.html#userdir">UserDir</A> -<LI><A HREF="core.html#virtualhost"><VirtualHost></A> -<LI><A HREF="mod_include.html#xbithack">XBitHack</A> -</UL> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/footer.html b/docs/manual/mod/footer.html deleted file mode 100644 index 7fe745dcfd..0000000000 --- a/docs/manual/mod/footer.html +++ /dev/null @@ -1,8 +0,0 @@ -<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> diff --git a/docs/manual/mod/header.html b/docs/manual/mod/header.html deleted file mode 100644 index 5662300029..0000000000 --- a/docs/manual/mod/header.html +++ /dev/null @@ -1,6 +0,0 @@ -<DIV ALIGN="CENTER"> - <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> - <H3> - Apache HTTP Server Version 1.3 - </H3> -</DIV> diff --git a/docs/manual/mod/index.html b/docs/manual/mod/index.html deleted file mode 100644 index cb344fd670..0000000000 --- a/docs/manual/mod/index.html +++ /dev/null @@ -1,124 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache modules</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache modules</H1> - -<P> -Below is a list of all of the modules that come as part of the -Apache distribution. See also the complete alphabetical list of -<A - HREF="directives.html" ->all Apache directives</A>. -</P> - -<DL> -<DT><A HREF="core.html">Core</A> -<DD>Core Apache features. -<DT><A HREF="mod_access.html">mod_access</A> -<DD>Host based access control. -<DT><A HREF="mod_actions.html">mod_actions</A> Apache 1.1 and later. -<DD>Filetype/method-based script execution -<DT><A HREF="mod_alias.html">mod_alias</A> -<DD>Aliases and redirects. -<DT><A HREF="mod_asis.html">mod_asis</A> -<DD>The .asis file handler. -<DT><A HREF="mod_auth.html">mod_auth</A> -<DD>User authentication using text files. -<DT><A HREF="mod_auth_anon.html">mod_auth_anon</A> -<DD>Anonymous user authentication, FTP-style. -<DT><A HREF="mod_auth_db.html">mod_auth_db</A> -<DD>User authentication using Berkeley DB files. -<DT><A HREF="mod_auth_dbm.html">mod_auth_dbm</A> -<DD>User authentication using DBM files. -<DT><A HREF="mod_auth_digest.html">mod_auth_digest</A> -<DD>MD5 authentication (experimental) -<DT><A HREF="mod_autoindex.html">mod_autoindex</A> -<DD>Automatic directory listings. -<DT><A HREF="mod_browser.html">mod_browser</A> Apache 1.2.* only -<DD>Set environment variables based on User-Agent strings. Replaced by - mod_setenvif in Apache 1.3 and up -<DT><A HREF="mod_cern_meta.html">mod_cern_meta</A> -<DD>Support for HTTP header metafiles. -<DT><A HREF="mod_cgi.html">mod_cgi</A> -<DD>Invoking CGI scripts. -<DT><A HREF="mod_cookies.html">mod_cookies</A> up to Apache 1.1.1 -<DD>Support for Netscape-like cookies. Replaced in Apache 1.2 by -mod_usertrack -<DT><A HREF="mod_digest.html">mod_digest</A> -<DD>MD5 authentication -<DT><A HREF="mod_dir.html">mod_dir</A> -<DD>Basic directory handling. -<DT><A HREF="mod_dld.html">mod_dld</A> Apache 1.2.* and earlier -<DD>Start-time linking with the GNU libdld. Replaced in Apache 1.3 by mod_so -<DT><A HREF="mod_dll.html">mod_dll</A> Apache 1.3b1 to 1.3b5 only -<DD>Replaced in 1.3b6 by mod_so -<DT><A HREF="mod_env.html">mod_env</A> -<DD>Passing of environments to CGI scripts -<DT><A HREF="mod_example.html">mod_example</A> Apache 1.2 and up -<DD>Demonstrates Apache API -<DT><A HREF="mod_expires.html">mod_expires</A> Apache 1.2 and up -<DD>Apply Expires: headers to resources -<DT><A HREF="mod_headers.html">mod_headers</A> Apache 1.2 and up -<DD>Add arbitrary HTTP headers to resources -<DT><A HREF="mod_imap.html">mod_imap</A> -<DD>The imagemap file handler. -<DT><A HREF="mod_include.html">mod_include</A> -<DD>Server-parsed documents. -<DT><A HREF="mod_info.html">mod_info</A> -<DD>Server configuration information -<DT><A HREF="mod_isapi.html">mod_isapi</A> -<DD>Windows ISAPI Extension support -<DT><A HREF="mod_log_agent.html">mod_log_agent</A> -<DD>Logging of User Agents. -<DT><A HREF="mod_log_common.html">mod_log_common</A> up to Apache 1.1.1 -<DD>Standard logging in the Common Logfile Format. Replaced by the -mod_log_config module in Apache 1.2 and up -<DT><A HREF="mod_log_config.html">mod_log_config</A> -<DD>User-configurable logging replacement for mod_log_common. -<DT><A HREF="mod_log_referer.html">mod_log_referer</A> -<DD>Logging of document references. -<DT><A HREF="mod_mime.html">mod_mime</A> -<DD>Determining document types using file extensions. -<DT><A HREF="mod_mime_magic.html">mod_mime_magic</A> -<DD>Determining document types using "magic numbers". -<DT><A HREF="mod_mmap_static.html">mod_mmap_static</A> -<DD>Mapping files into memory for faster serving. -<DT><A HREF="mod_negotiation.html">mod_negotiation</A> -<DD>Content negotiation. -<DT><A HREF="mod_proxy.html">mod_proxy</A> -<DD>Caching proxy abilities -<DT><A HREF="mod_rewrite.html">mod_rewrite</A> Apache 1.2 and up -<DD>Powerful URI-to-filename mapping using regular expressions -<DT><A HREF="mod_setenvif.html">mod_setenvif</A> Apache 1.3 and up -<DD>Set environment variables based on client information -<DT><A HREF="mod_so.html">mod_so</A> Apache 1.3 and up -<DD>Experimental support for loading modules (DLLs on Windows) at runtime -<DT><A HREF="mod_speling.html">mod_speling</A> Apache 1.3 and up -<DD>Automatically correct minor typos in URLs -<DT><A HREF="mod_status.html">mod_status</A> -<DD>Server status display -<DT><A HREF="mod_userdir.html">mod_userdir</A> -<DD>User home directories. -<DT><A HREF="mod_unique_id.html">mod_unique_id</A> Apache 1.3 and up -<DD>Generate unique request identifier for every request -<DT><A HREF="mod_usertrack.html">mod_usertrack</A> Apache 1.2 and up -<DD>User tracking using Cookies (replacement for mod_cookies.c) -<DT><A HREF="mod_vhost_alias.html">mod_vhost_alias</A> Apache 1.3.7 and up -<DD>Support for dynamically configured mass virtual hosting -</DL> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_access.html b/docs/manual/mod/mod_access.html deleted file mode 100644 index 82cd71c69f..0000000000 --- a/docs/manual/mod/mod_access.html +++ /dev/null @@ -1,312 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_access</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_access</H1> -<P> -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. -</P> - -<UL> -<LI><A HREF="#allow">allow</A> -<LI><A HREF="#allowfromenv">allow from env=</A> -<LI><A HREF="#deny">deny</A> -<LI><A HREF="#denyfromenv">deny from env=</A> -<LI><A HREF="#order">order</A> -</UL> -<HR> - - -<H2><A NAME="allow">allow directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt allow} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> allow from <EM>host host ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Limit<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_access -</P> -<P> -The allow directive affects which hosts can access a given directory. -<EM>Host</EM> is one of the following: -</P> -<DL> -<DT><CODE>all</CODE> -<DD>All hosts are allowed access -<DT>A (partial) domain-name -<DD>Hosts whose names match, or end 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. -<DT>A network/netmask pair (<STRONG>Apache 1.3 and later</STRONG>) -<DD>A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet - restriction. (<EM>i.e.</EM>, 10.1.0.0/255.255.0.0) -<DT>A network/nnn CIDR specification (<STRONG>Apache 1.3 and later</STRONG>) -<DD>Similar to the previous case, except the netmask consists of nnn - high-order 1 bits. (<EM>i.e.</EM>, 10.1.0.0/16 is the same as 10.1.0.0/255.255.0.0) -</DL> -<P> -Example: -</P> -<BLOCKQUOTE><CODE>allow from .ncsa.uiuc.edu</CODE></BLOCKQUOTE> -<P> -All hosts in the specified domain are allowed access. -</P> -<P> -Note that this compares whole components; <CODE>bar.edu</CODE> -would not match <CODE>foobar.edu</CODE>. -</P> -<P> -See also <A HREF="#deny">deny</A>, <A HREF="#order">order</A>, and -<A HREF="mod_browser.html#browsermatch">BrowserMatch</A>. -</P> - -<P> -<A NAME="allowfromenv"><STRONG>Syntax:</STRONG> allow from - env=<EM>variablename</EM></A><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Limit<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_access<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above -</P> -<P> -The allow from env directive controls access to a directory by the -existence (or non-existence) of an environment variable. -</P> -<P> -Example: -</P> -<BLOCKQUOTE><PRE> -BrowserMatch ^KnockKnock/2.0 let_me_in -<Directory /docroot> - order deny,allow - deny from all - allow from env=let_me_in -</Directory> -</PRE></BLOCKQUOTE> -In this case browsers with the user-agent string <TT>KnockKnock/2.0</TT> will -be allowed access, and all others will be denied. -<P> -See also <A HREF="#denyfromenv">deny from env</A> -and <A HREF="#order">order</A>. -</P> -<HR> - -<H2><A NAME="deny">deny directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt deny} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> deny from <EM>host host ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Limit<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_access -</P> -<P> -The deny directive affects which hosts can access a given directory. -<EM>Host</EM> is one of the following: -</P> -<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. -<DT>A network/netmask pair (<STRONG>Apache 1.3 and later</STRONG>) -<DD>A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet - restriction. (<EM>i.e.</EM>, 10.1.0.0/255.255.0.0) -<DT>A network/nnn CIDR specification (<STRONG>Apache 1.3 and later</STRONG>) -<DD>Similar to the previous case, except the netmask consists of nnn - high-order 1 bits. (<EM>i.e.</EM>, 10.1.0.0/16 is the same as 10.1.0.0/255.255.0.0) -</DL> -<P> -Example: -</P> -<BLOCKQUOTE><CODE>deny from 16</CODE></BLOCKQUOTE> -<P> -All hosts in the specified network are denied access. -</P> -<P> -Note that this compares whole components; <CODE>bar.edu</CODE> -would not match <CODE>foobar.edu</CODE>. -</P> -<P> -See also <A HREF="#allow">allow</A> and <A HREF="#order">order</A>. -</P> - -<P> -<A NAME="denyfromenv"><STRONG>Syntax:</STRONG> deny from - env=<EM>variablename</EM></A><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Limit<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_access<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above -</P> -<P> -The deny from env directive controls access to a directory by the -existence (or non-existence) of an environment variable. -</P> -<P> -Example: -</P> -<BLOCKQUOTE><PRE> -BrowserMatch ^BadRobot/0.9 go_away -<Directory /docroot> - order allow,deny - allow from all - deny from env=go_away -</Directory> -</PRE></BLOCKQUOTE> -In this case browsers with the user-agent string <TT>BadRobot/0.9</TT> will -be denied access, and all others will be allowed. - -<P> -See also <A HREF="#allowfromenv">allow from env</A> -and <A HREF="#order">order</A>. -</P> -<HR> - -<H2><A NAME="order">order directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt order} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> order <EM>ordering</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>order deny,allow</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Limit<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_access -</P> -<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 -</P> -<DL> -<DT>deny,allow -<DD>the deny directives are evaluated before the allow directives. (The -initial state is OK.) -<DT>allow,deny -<DD>the allow directives are evaluated before the deny directives. (The -initial state is FORBIDDEN.) -<DT>mutual-failure -<DD>Only those hosts which appear on the allow list and do not appear -on the deny list are granted access. (The initial state is irrelevant.) -</DL> -<P> -Keywords may only be separated by a comma; no whitespace is allowed between -them. -<STRONG>Note that in all cases every <CODE>allow</CODE> and <CODE>deny</CODE> -statement is evaluated, there is no "short-circuiting".</STRONG> -</P> -<P> -Example: -</P> -<BLOCKQUOTE><CODE> - order deny,allow<BR> - deny from all<BR> - allow from .ncsa.uiuc.edu<BR> -</CODE></BLOCKQUOTE> -<P> -Hosts in the ncsa.uiuc.edu domain are allowed access; all other hosts are -denied access. -</P> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_actions.html b/docs/manual/mod/mod_actions.html deleted file mode 100644 index 43174f7701..0000000000 --- a/docs/manual/mod/mod_actions.html +++ /dev/null @@ -1,126 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Module mod_actions</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_actions</H1> -<P> -This module is contained in the <CODE>mod_actions.c</CODE> file, and -is compiled in by default. It provides for -executing CGI scripts based on media type or request method. It is not -present in versions prior to Apache 1.1. -</P> -<H2>Summary</H2> -<P> -This module lets you run CGI scripts whenever a file of a certain type -is requested. This makes it much easier to execute scripts that -process files. -</P> -<H2>Directives</H2> -<UL> -<LI><A HREF="#action">Action</A> -<LI><A HREF="#script">Script</A> -</UL> - -<HR> - -<H2><A NAME="action">Action directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Action <EM>action-type cgi-script</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_actions<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Action is only available in Apache 1.1 -and later -</P> -<P> -This directive adds an action, which will activate <EM>cgi-script</EM> when -<EM>action-type</EM> is triggered by the request. The <EM>action-type</EM> can -be either a <A HREF="../handler.html">handler</A> or a MIME content type. It -sends the URL and file path of the requested document using the standard CGI -PATH_INFO and PATH_TRANSLATED environment variables. -</P> -<HR> - -<H2><A NAME="script">Script directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Script <EM>method cgi-script</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_actions<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Script is only available in Apache 1.1 -and later -</P> - -<P> -This directive adds an action, which will activate <EM>cgi-script</EM> when -a file is requested using the method of <EM>method</EM>, which can be -one of <CODE>GET</CODE>, <CODE>POST</CODE>, <CODE>PUT</CODE> or -<CODE>DELETE</CODE>. It sends the -URL and file path of the requested document using the standard -CGI PATH_INFO and PATH_TRANSLATED environment variables. -</P> -<P> -Note that the Script command defines default actions only. If a CGI -script is called, or some other resource that is capable of handling -the requested method internally, it will do so. Also note that Script -with a method of <CODE>GET</CODE> will only be called if there are -query arguments present (<EM>e.g.</EM>, foo.html?hi). Otherwise, the request -will proceed normally. -</P> -<P> -Examples: -</P> -<PRE> - Script GET /cgi-bin/search #<EM>e.g.</EM> for <ISINDEX>-style searching - Script PUT /~bob/put.cgi -</PRE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_alias.html b/docs/manual/mod/mod_alias.html deleted file mode 100644 index 0826842cde..0000000000 --- a/docs/manual/mod/mod_alias.html +++ /dev/null @@ -1,405 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_alias</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_alias</H1> -<P> -This module is contained in the <CODE>mod_alias.c</CODE> file, and -is compiled in by default. It provides for mapping different parts of the -host filesystem in the the document tree, and for URL redirection. -</P> - -<H2>Directives</H2> -<UL> -<LI><A HREF="#alias">Alias</A> -<LI><A HREF="#aliasmatch">AliasMatch</A> -<LI><A HREF="#redirect">Redirect</A> -<LI><A HREF="#redirectmatch">RedirectMatch</A> -<LI><A HREF="#redirecttemp">RedirectTemp</A> -<LI><A HREF="#redirectperm">RedirectPermanent</A> -<LI><A HREF="#scriptalias">ScriptAlias</A> -<LI><A HREF="#scriptaliasmatch">ScriptAliasMatch</A> -</UL> -<HR> - - -<H2><A NAME="alias">Alias directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt Alias} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Alias <EM>url-path directory-filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias -</P> -<P> -The Alias directive allows documents to be stored in the local filesystem -other than under the <A HREF="core.html#documentroot">DocumentRoot</A>. -URLs with a (%-decoded) path beginning with <EM>url-path</EM> will be -mapped to local files beginning with <EM>directory-filename</EM>. -<P> -Example: -</P> -<BLOCKQUOTE><CODE>Alias /image /ftp/pub/image</CODE></BLOCKQUOTE> -<P> -A request for http://myserver/image/foo.gif would cause the server to -return the file /ftp/pub/image/foo.gif. -</P> -<P> -Note that if you include a trailing / on the <EM>url-path</EM> then the -server will require a trailing / in order to expand the alias. That is, -if you use <CODE>Alias /icons/ /usr/local/apache/icons/</CODE> then -the url <CODE>/icons</CODE> will not be aliased. -</P> -<P> -Note that you may need to specify additional -<A HREF="core.html#directory"><CODE><Directory></CODE></A> sections -which cover the <EM>destination</EM> of aliases. Aliasing occurs -before <CODE><Directory></CODE> sections are checked, so only -the destination of aliases are affected. (Note however -<A HREF="core.html#location"><CODE><Location></CODE></A> -sections are run through once before aliases are performed, so they -will apply.) -<P> -See also <A HREF="#scriptalias">ScriptAlias</A>. -</P> -<HR> - -<H2><A NAME="aliasmatch">AliasMatch</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AliasMatch <EM>regex directory-filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later -</P> - -<P>This directive is equivalent to <A HREF="#alias">Alias</A>, but -makes use of standard regular expressions, instead of simple prefix -matching. The supplied regular expression is matched against the URL, -and if it matches, the server will substitute any parenthesized -matches into the given string and use it as a filename. For example, -to activate the <CODE>/icons</CODE> directory, one might use: -<PRE> - AliasMatch ^/icons(.*) /usr/local/apache/icons$1 -</PRE> -</P> - -<HR> - -<H2><A NAME="redirect">Redirect directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt Redirect} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Redirect [ <EM>status</EM> ] - <EM>url-path url</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> The directory and .htaccess context's -are only available in versions 1.1 and later. The <EM>status</EM> -argument is only available in Apache 1.2 or later. -</P> -<P> -The Redirect directive maps an old URL into a new one. The new URL is returned -to the client which attempts to fetch it again with the new address. -<EM>Url-path</EM> a (%-decoded) path; any requests for documents beginning with -this path will be returned a redirect error to a new (%-encoded) url -beginning with <EM>url</EM>. -</P> -<P> -Example: -</P> -<BLOCKQUOTE><CODE>Redirect /service -http://foo2.bar.com/service</CODE></BLOCKQUOTE> -<P> -If the client requests http://myserver/service/foo.txt, it will be told to -access http://foo2.bar.com/service/foo.txt instead. -</P> -<P> -<STRONG>Note:</STRONG> Redirect directives take precedence over Alias -and ScriptAlias -directives, irrespective of their ordering in the configuration file. Also, -<EM>Url-path</EM> must be an absolute path, not a relative path, even -when used with .htaccess files or inside of <Directory> sections. -</P> -<P> -If no <EM>status</EM> argument is given, the redirect will be -"temporary" (HTTP status 302). This indicates to the client that the -resources is has moved temporarily. The <EM>status</EM> -argument can be used to return other HTTP status codes: -<P> -<DL> -<DT>permanent -<DD>Returns a permanent redirect status (301) indicating that -the resource has moved permanently. -<DT>temp -<DD>Returns a temporary redirect status (302). This is the -default. -<DT>seeother -<DD>Returns a "See Other" status (303) indicating that -the resource has been replaced. -<DT>gone -<DD>Returns a "Gone" status (410) indicating that the resource -has been permanently removed. When this status is used the <EM>url</EM> -argument should be omitted. -</DL> -<P> -Other status codes can be returned by giving the numeric status code -as the value of <EM>status</EM>. If the status is between 300 and 399, -the <EM>url</EM> argument must be present, otherwise it must be -omitted. Note that the status must be known to the Apache code (see -the function <CODE>send_error_response</CODE> in http_protocol.c). -</P> -<HR> - -<H2><A NAME="redirectmatch">RedirectMatch</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> - RedirectMatch [<EM>status</EM>] <EM>regex url</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later -</P> - -<P>This directive is equivalent to <A HREF="#alias">Redirect</A>, but -makes use of standard regular expressions, instead of simple prefix -matching. The supplied regular expression is matched against the URL, -and if it matches, the server will substitute any parenthesized -matches into the given string and use it as a filename. For example, -to redirect all GIF files to like-named JPEG files on another server, -one might use: -<PRE> - RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg -</PRE> -</P> - -<HR> - -<H2><A NAME="redirecttemp">RedirectTemp directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt Redirect} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RedirectTemp <EM>url-path url</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> This directive is only available in 1.2 -</P> -<P> -This directive makes the client know that the Redirect is only -temporary (status 302). Exactly equivalent to <CODE>Redirect -temp</CODE>. -</P> -<HR> - -<H2><A NAME="redirectperm">RedirectPermanent directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt Redirect} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RedirectPermanent <EM>url-path url</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> This directive is only available in 1.2 -</P> -<P> -This directive makes the client know that the Redirect is permanent -(status 301). Exactly equivalent to <CODE>Redirect permanent</CODE>. -</P> -<HR> - -<H2><A NAME="scriptalias">ScriptAlias directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt ScriptAlias} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScriptAlias <EM>url-path directory-filename</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias -</P> -<P> -The ScriptAlias directive has the same behavior as the -<A HREF="#alias">Alias</A> directive, except that in addition it -marks the target directory as containing CGI scripts. -URLs with a (%-decoded) path beginning with <EM>url-path</EM> will be -mapped to scripts beginning with <EM>directory-filename</EM>. -<P> -Example: -</P> -<BLOCKQUOTE><CODE>ScriptAlias /cgi-bin/ /web/cgi-bin/</CODE></BLOCKQUOTE> -<P> -A request for http://myserver/cgi-bin/foo would cause the server to -run the script /web/cgi-bin/foo. -</P> - -<HR> - -<H2><A NAME="scriptaliasmatch">ScriptAliasMatch</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScriptAliasMatch - <EM>regex directory-filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later -</P> - -<P>This directive is equivalent to <A HREF="#scriptalias">ScriptAlias</A>, but -makes use of standard regular expressions, instead of simple prefix -matching. The supplied regular expression is matched against the URL, -and if it matches, the server will substitute any parenthesized -matches into the given string and use it as a filename. For example, -to activate the standard <CODE>/cgi-bin</CODE>, one might use: -<PRE> - ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1 -</PRE> -</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_asis.html b/docs/manual/mod/mod_asis.html deleted file mode 100644 index 3ca8e7e906..0000000000 --- a/docs/manual/mod/mod_asis.html +++ /dev/null @@ -1,68 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_asis</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_asis</H1> - -This module is contained in the <CODE>mod_asis.c</CODE> file, and -is compiled in by default. It provides for <CODE>.asis</CODE> files. Any -document with mime type <CODE>httpd/send-as-is</CODE> will be processed by -this module. -<!--%plaintext <?INDEX {\tt httpd/send-as-is} mime type> --> - -<H2>Purpose</H2> -To allow file types to be defined such that Apache sends them without -adding HTTP headers.<P> - -This can be used to send any kind of data from the server, including redirects -and other special HTTP responses, without requiring a cgi-script or an nph -script. -<H2>Usage</H2> -In the server configuration file, define a new mime type called -<CODE>httpd/send-as-is</CODE> <EM>e.g.</EM> -<BLOCKQUOTE><CODE>AddType httpd/send-as-is asis</CODE></BLOCKQUOTE> -this defines the <CODE>.asis</CODE> file extension as being of the new -<CODE>httpd/send-as-is</CODE> mime type. The contents of any file with a -<CODE>.asis</CODE> extension will then be sent by Apache to the client with -almost no changes. Clients will need HTTP headers to be attached, so do not -forget them. A Status: header is also required; the data should be the -3-digit HTTP response code, followed by a textual message.<P> - -Here's an example of a file whose contents are sent <EM>as is</EM> so as to -tell the client that a file has redirected. -<BLOCKQUOTE><CODE> -Status: 301 Now where did I leave that URL <BR> -Location: http://xyz.abc.com/foo/bar.html <BR> -Content-type: text/html <BR> -<BR> -<HTML> <BR> -<HEAD> <BR> -<TITLE>Lame excuses'R'us</TITLE> <BR> -</HEAD> <BR> -<BODY> <BR> -<H1>Fred's exceptionally wonderful page has moved to <BR> -<A HREF="http://xyz.abc.com/foo/bar.html">Joe's</A> site. <BR> -</H1> <BR> -</BODY> <BR> -</HTML> -</CODE></BLOCKQUOTE> -Notes: the server always adds a Date: and Server: header to the data returned -to the client, so these should not be included in the file. -The server does <EM>not</EM> add a Last-Modified header; it probably should. -<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_auth.html b/docs/manual/mod/mod_auth.html deleted file mode 100644 index a3f85d54be..0000000000 --- a/docs/manual/mod/mod_auth.html +++ /dev/null @@ -1,214 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_auth</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_auth</H1> - -This module is contained in the <CODE>mod_auth.c</CODE> file, and -is compiled in by default. It provides for user authentication using -textual files. - - -<MENU> -<LI><A HREF="#authgroupfile">AuthGroupFile</A> -<LI><A HREF="#authuserfile">AuthUserFile</A> -<LI><A HREF="#authauthoritative">AuthAuthoritative</A> -</MENU> -<HR> - - -<H2><A NAME="authgroupfile">AuthGroupFile</A></H2> -<!--%plaintext <?INDEX {\tt AuthGroupFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthGroupFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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 path -to the group file. If it is not absolute (<EM>i.e.</EM>, if it -doesn't begin with a slash), it is treated as relative to the ServerRoot. -<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 text files is <EM>very</EM> inefficient; -<A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> should -be used instead.<P> - -Security: make sure that the AuthGroupFile is stored outside the -document tree of the web-server; do <EM>not</EM> put it in the directory that -it protects. Otherwise, clients will be able to download the AuthGroupFile.<P> - -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authuserfile">AuthUserFile</A>.<P><HR> - -<H2><A NAME="authuserfile">AuthUserFile</A></H2> -<!--%plaintext <?INDEX {\tt AuthUserFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthUserFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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 path to the user -file. If it is not absolute (<EM>i.e.</EM>, if it doesn't begin with a -slash), it is treated as relative to the ServerRoot. -<P> Each line of the user file file contains a username followed -by a colon, followed by the crypt() encrypted password. The behavior -of multiple occurrences of the same user is undefined. -<P> -The utility <code>htpasswd</code> which is installed as part of the -binary distribution, or which can be found in <code>src/support</code>, -is used to maintain this password file. See the <code>man</code> -page for more details. In short -<p> -<blockquote> - <code>htpasswd -c Filename username</code><br> - Create a password file 'Filename' with 'username' - as the initial ID. It will prompt for the password. - <code>htpasswd Filename username2</code><br> - Adds or modifies in password file 'Filename' the 'username'. -</blockquote> -<P> Note that -searching large text files is <EM>very</EM> inefficient; -<A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A> should be -used instead. -<P> - -Security: make sure that the AuthUserFile is stored outside the -document tree of the web-server; do <EM>not</EM> put it in the directory that -it protects. Otherwise, clients will be able to download the AuthUserFile.<P> - -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authgroupfile">AuthGroupFile</A>.<P> -<HR> -<H2><A NAME="authauthoritative">AuthAuthoritative</A></H2> -<!--%plaintext <?INDEX {\tt AuthAuthoritative} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthAuthoritative < - <STRONG> on</STRONG>(default) | off > <BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth<P> - -Setting the AuthAuthoritative directive explicitly to <STRONG>'off'</STRONG> -allows for both authentication and authorization to be passed on to -lower level modules (as defined in the <CODE>Configuration</CODE> and -<CODE>modules.c</CODE> files) if there is <STRONG>no userID</STRONG> or -<STRONG>rule</STRONG> matching the supplied userID. If there is a userID and/or -rule specified; the usual password and access checks will be applied -and a failure will give an Authorization Required reply. - -<P> - -So if a userID appears in the database of more than one module; or if -a valid require directive applies to more than one module; then the -first module will verify the credentials; and no access is passed on; -regardless of the AuthAuthoritative setting. - -<P> - -A common use for this is in conjunction with one of the database -modules; such as <A -HREF="mod_auth_db.html"><CODE>mod_auth_db.c</CODE></A>, <A -HREF="mod_auth_dbm.html"><CODE>mod_auth_dbm.c</CODE></A>, -<CODE>mod_auth_msql.c</CODE>, and <A -HREF="mod_auth_anon.html"><CODE>mod_auth_anon.c</CODE></A>. These modules -supply the bulk of the user credential checking; but a few -(administrator) related accesses fall through to a lower level with a -well protected AuthUserFile. - -<P> - -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> By default; control is not passed on; and an - unknown -userID or rule will result in an Authorization Required reply. Not -setting it thus keeps the system secure; and forces an NCSA compliant -behaviour. - -<P> - -Security: Do consider the implications of allowing a user to allow -fall-through in his .htaccess file; and verify that this is really -what you want; Generally it is easier to just secure a single -.htpasswd file, than it is to secure a database such as mSQL. Make -sure that the AuthUserFile is stored outside the document tree of the -web-server; do <EM>not</EM> put it in the directory that it -protects. Otherwise, clients will be able to download the -AuthUserFile. - -<P> -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authgroupfile">AuthGroupFile</A>.<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_auth_anon.html b/docs/manual/mod/mod_auth_anon.html deleted file mode 100644 index bbf6ce5357..0000000000 --- a/docs/manual/mod/mod_auth_anon.html +++ /dev/null @@ -1,363 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_auth_anon.c</TITLE> -</HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_auth_anon</H1> - -This module is contained in the <CODE>mod_auth_anon.c</CODE> file and -is not compiled in by default. It is only available in Apache 1.1 and -later. It allows "anonymous" user access to authenticated areas. - -<H2>Summary</H2> - -It does access control in a manner similar to anonymous-ftp sites; <EM>i.e.</EM> -have a 'magic' user id 'anonymous' and the email address as a password. -These email addresses can be logged. -<P> -Combined with other (database) access control methods, this allows for -effective user tracking and customization according to a user profile -while still keeping the site open for 'unregistered' users. One advantage -of using Auth-based user tracking is that, unlike magic-cookies and -funny URL pre/postfixes, it is completely browser independent and it -allows users to share URLs. -<P> - -<A HREF="#Directives">Directives</A> / -<A HREF="#Example">Example</A> / -<A HREF="#CompileTimeOptions">Compile time options</A> / -<A HREF="#RevisionHistory">RevisionHistory</A> / -<A HREF="#Person">Person to blame</A> / -<A HREF="#Sourcecode">Sourcecode</A> -<P> - -<H2><A NAME="Directives">Directives</A></H2> -<UL> -<LI><A HREF="#anonymous">Anonymous</A> -<LI><A HREF="#Authoritative">Anonymous_Authoritative</A> -<LI><A HREF="#LogEmail">Anonymous_LogEmail</A> -<LI><A HREF="#MustGiveEmail">Anonymous_MustGiveEmail</A> -<LI><A HREF="#NoUserID">Anonymous_NoUserID</A> -<LI><A HREF="#VerifyEmail">Anonymous_VerifyEmail</A> -</UL> - -<HR> - -<H2><A NAME="anonymous">Anonymous directive</A></H2> -<!--%plaintext <?INDEX {\tt Anonymous} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Anonymous <EM>user user ...</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> none<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_anon<P> - - A list of one or more 'magic' userIDs which are allowed access - without password verification. The userIDs are space separated. - It is possible to use the ' and " quotes to allow a space in - a userID as well as the \ escape character. - <P> - Please note that the comparison is <STRONG>case-IN-sensitive</STRONG>. - <BR> - I strongly suggest that the magic username '<CODE>anonymous</CODE>' - is always one of the allowed userIDs. - <P> - Example:<BR> - <CODE> - Anonymous anonymous "Not Registered" 'I don\'t know' - </CODE><P> - This would allow the user to enter without password verification - by using the userId's 'anonymous', 'AnonyMous','Not Registered' and - 'I Don't Know'. -<HR> - -<H2><A NAME="Authoritative">Anonymous_Authoritative directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Anonymous_Authoritative <EM>on | off</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Anonymous_Authoritative off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_anon<P> - - When set 'on', there is no - fall-through to other authorization methods. So if a - userID does not match the values specified in the - <CODE>Anonymous</CODE> directive, access is denied. - <P> - Be sure you know what you are doing when you decide to switch - it on. And remember that it is the linking order of the modules - (in the Configuration / Make file) which details the order - in which the Authorization modules are queried. -<HR> - -<H2><A NAME="LogEmail">Anonymous_LogEmail directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Anonymous_LogEmail <EM>on | off</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Anonymous_LogEmail on</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_anon<P> - - When set 'on', the default, the 'password' entered (which hopefully - contains a sensible email address) is logged in the error log. -<HR> - -<H2><A NAME="MustGiveEmail">Anonymous_MustGiveEmail directive</A></H2> -<!--%plaintext <?INDEX {\tt Anonymous_MustGiveEmail} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Anonymous_MustGiveEmail <EM>on</EM> - | <EM>off</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Anonymous_MustGiveEmail on</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_anon<P> - - Specifies whether the user must specify an email - address as the password. This prohibits blank passwords. -<HR> - -<H2><A NAME="NoUserID">Anonymous_NoUserID directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Anonymous_NoUserID <EM>on | off</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Anonymous_NoUserID off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_anon<P> - - When set 'on', users can leave - the userID (and perhaps the password field) empty. This - can be very convenient for MS-Explorer users who can - just hit return or click directly on the OK button; which - seems a natural reaction. - -<HR> - -<H2><A NAME="VerifyEmail">Anonymous_VerifyEmail directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Anonymous_VerifyEmail <EM>on | off</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Anonymous_VerifyEmail off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_anon<P> - - When set 'on' the 'password' entered is - checked for at least one '@' and a '.' to encourage users to enter - valid email addresses (see the above <CODE>Auth_LogEmail</CODE>). - -<HR> -<H2><A NAME="Example">Example</A></H2> - -The example below (when combined with the Auth directives -of a htpasswd-file based (or GDM, mSQL <EM>etc.</EM>) 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 <STRONG>not</STRONG> case sensitive. -<LI> -And the Email addresses entered in the passwd field are logged to -the error log file -(<CODE>Anonymous_LogEmail</CODE>) -</UL> -<P> -Excerpt of access.conf: -<BLOCKQUOTE><CODE> -Anonymous_NoUserId off<BR> -Anonymous_MustGiveEmail on<BR> -Anonymous_VerifyEmail on<BR> -Anonymous_LogEmail on<BR> -Anonymous anonymous guest www test welcome<P> -<P> -AuthName "Use 'anonymous' & Email address for guest entry"<BR> -AuthType basic -<P> -# An AuthUserFile/AuthDBUserFile/AuthDBMUserFile<BR> -# directive must be specified, or use<BR> -# Anonymous_Authoritative for public access.<BR> -# In the .htaccess for the public directory, add:<BR> -<Files *><BR> -order deny,allow <BR> -allow from all <BR> -<P> -require valid-user <BR> -</Files><BR> -</CODE></BLOCKQUOTE> - - -<HR> -<H2><A NAME="CompileTimeOptions">Compile Time Options</A></H2> - -Currently there are no Compile options. - -<HR> -<H2><A NAME="RevisionHistory">Revision History</A></H2> - -This version: 23 Nov 1995, 24 Feb 1996, 16 May 1996. - -<DL> - -<DT>Version 0.4<BR></DT> - <DD>First release - </DD> -<DT>Version 0.5<BR></DT> - <DD>Added 'VerifyEmail' and 'LogEmail' options. Multiple - 'anonymous' tokens allowed. more docs. Added Authoritative - functionality. - </DD> -</DL> - - -<HR> -<H2><A NAME="Person">Contact/person to blame</A></H2> - -This module was written for the -<A HREF="http://ewse.ceo.org">European Wide Service Exchange</A> by -<<A - HREF="mailto:Dirk.vanGulik@jrc.it" - ><CODE>Dirk.vanGulik@jrc.it</CODE></A>>. -Feel free to contact me if you have any problems, ice-creams or bugs. This -documentation, courtesy of Nick Himba, <A HREF="mailto:himba@cs.utwente.nl"> -<CODE><himba@cs.utwente.nl></CODE></A>. -<P> - - -<HR> -<H2><A NAME="Sourcecode">Sourcecode</A></H2> - -The source code can be found at <A HREF="http://www.apache.org"><CODE> -http://www.apache.org</CODE></A>. A snapshot of a development version -usually resides at <A HREF="http://me-www.jrc.it/~dirkx/mod_auth_anon.c"><CODE> -http://me-www.jrc.it/~dirkx/mod_auth_anon.c</CODE></A>. Please make sure -that you always quote the version you use when filing a bug report. -<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_auth_db.html b/docs/manual/mod/mod_auth_db.html deleted file mode 100644 index 2df31ba261..0000000000 --- a/docs/manual/mod/mod_auth_db.html +++ /dev/null @@ -1,220 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_auth_db</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_auth_db</H1> - -This module is contained in the <CODE>mod_auth_db.c</CODE> file, and -is not compiled in by default. It provides for user authentication using -Berkeley DB files. It is an alternative to <A HREF="mod_auth_dbm.html">DBM</A> -files for those systems which support DB and not DBM. It is only -available in Apache 1.1 and later. - -<P> -On some BSD systems (<EM>e.g.</EM>, FreeBSD and NetBSD) dbm is automatically mapped to -Berkeley DB. You can use either <A HREF="mod_auth_dbm.html">mod_auth_dbm</A> -or mod_auth_db. The latter makes it more obvious that it's Berkeley DB. On -other platforms where you want to use the DB library you usually have to -install it first. See -<A HREF="http://www.sleepycat.com/">http://www.sleepycat.com/</A> for the -distribution. The interface this module uses is the one from DB version 1.85 -and 1.86, but DB version 2.x can also be used when compatibility mode is -enabled. - -<MENU> -<LI><A HREF="#authdbgroupfile">AuthDBGroupFile</A> -<LI><A HREF="#authdbuserfile">AuthDBUserFile</A> -<LI><A HREF="#authdbauthoritative">AuthDBAuthoritative</A> -</MENU> -<HR> - - -<H2><A NAME="authdbgroupfile">AuthDBGroupFile</A></H2> -<!--%plaintext <?INDEX {\tt AuthDBGroupFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDBGroupFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_db<P> - -The AuthDBGroupFile directive sets the name of a DB file containing the list -of user groups for user authentication. <EM>Filename</EM> is the absolute path -to the group file.<P> - -The group file is keyed on the username. The value for a user is a -comma-separated list of the groups to which the users belongs. There must -be no whitespace within the value, and it must never contain any colons.<P> - -Security: make sure that the AuthDBGroupFile is stored outside the -document tree of the web-server; do <EM>not</EM> put it in the directory that -it protects. Otherwise, clients will be able to download the -AuthDBGroupFile unless otherwise protected.<P> - -Combining Group and Password DB files: In some cases it is easier to -manage a single database which contains both the password and group -details for each user. This simplifies any support programs that need -to be written: they now only have to deal with writing to and locking -a single DBM file. This can be accomplished by first setting the group -and password files to point to the same DB file:<P> - -<BLOCKQUOTE><CODE> -AuthDBGroupFile /www/userbase<BR> -AuthDBUserFile /www/userbase -</CODE></BLOCKQUOTE> - -The key for the single DB record is the username. The value consists of <P> - -<BLOCKQUOTE><CODE> -Unix Crypt-ed Password : List of Groups [ : (ignored) ] -</CODE></BLOCKQUOTE> - -The password section contains the Unix crypt() password as before. This is -followed by a colon and the comma separated list of groups. Other data may -optionally be left in the DB file after another colon; it is ignored by the -authentication module. <P> - -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authdbuserfile">AuthDBUserFile</A>.<P><HR> - -<H2><A NAME="authdbuserfile">AuthDBUserFile</A></H2> -<!--%plaintext <?INDEX {\tt AuthDBUserFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDBUserFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_db<P> - -The AuthDBUserFile directive sets the name of a DB file containing the list -of users and passwords for user authentication. <EM>Filename</EM> is the -absolute path to the user file.<P> - -The user file is keyed on the username. The value for a user is the -crypt() encrypted password, optionally followed by a colon and -arbitrary data. The colon and the data following it will be ignored -by the server.<P> - -Security: make sure that the AuthDBUserFile is stored outside the -document tree of the web-server; do <EM>not</EM> put it in the directory that -it protects. Otherwise, clients will be able to download the -AuthDBUserFile.<P> - -Important compatibility note: The implementation of "dbmopen" in the -apache modules reads the string length of the hashed values from the -DB data structures, rather than relying upon the string being -NULL-appended. Some applications, such as the Netscape web server, -rely upon the string being NULL-appended, so if you are having trouble -using DB files interchangeably between applications this may be a -part of the problem. <P> - -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authdbgroupfile">AuthDBGroupFile</A>.<P> -<HR> -<H2><A NAME="authdbauthoritative">AuthDBAuthoritative</A></H2> -<!--%plaintext <?INDEX {\tt AuthDBAuthoritative} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDBAuthoritative < - <STRONG> on</STRONG>(default) | off > <BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth<P> - -Setting the AuthDBAuthoritative directive explicitly to <STRONG>'off'</STRONG> -allows for both authentication and authorization to be passed on -to lower level modules (as defined in the <CODE>Configuration</CODE> -and <CODE>modules.c</CODE> file if there is <STRONG>no userID</STRONG> or -<STRONG>rule</STRONG> matching the supplied userID. If there is a userID -and/or rule specified; the usual password and access checks will -be applied and a failure will give an Authorization Required reply. -<P> -So if a userID appears in the database of more than one module; or -if a valid require directive applies to more than one module; then -the first module will verify the credentials; and no access is -passed on; regardless of the AuthAuthoritative setting. <P> - -A common use for this is in conjunction with one of the basic auth -modules; such as <A HREF="mod_auth.html"><CODE>mod_auth.c</CODE></A>. -Whereas this DB module supplies the bulk of the user credential -checking; a few (administrator) related accesses fall through to -a lower level with a well protected .htpasswd file. <P> - -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> By default; control is not passed on; and an -unknown -userID or rule will result in an Authorization Required reply. Not -setting it thus keeps the system secure; and forces an NCSA compliant -behaviour. <P> -Security: Do consider the implications of allowing a user to allow -fall-through in his .htaccess file; and verify that this is really -what you want; Generally it is easier to just secure a single -.htpasswd file, than it is to secure a database which might have -more access interfaces. - -<P> -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authdbgroupfile">AuthDBGroupFile</A>.<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_auth_dbm.html b/docs/manual/mod/mod_auth_dbm.html deleted file mode 100644 index 36218ef8ee..0000000000 --- a/docs/manual/mod/mod_auth_dbm.html +++ /dev/null @@ -1,210 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_auth_dbm</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_auth_dbm</H1> - -This module is contained in the <CODE>mod_auth_dbm.c</CODE> file, and -is not compiled in by default. It provides for user authentication using -DBM files. - - -<MENU> -<LI><A HREF="#authdbmgroupfile">AuthDBMGroupFile</A> -<LI><A HREF="#authdbmuserfile">AuthDBMUserFile</A> -<LI><A HREF="#authdbmauthoritative">AuthDBMAuthoritative</A> -</MENU> -<HR> - - -<H2><A NAME="authdbmgroupfile">AuthDBMGroupFile</A></H2> -<!--%plaintext <?INDEX {\tt AuthDBMGroupFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDBMGroupFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_dbm<P> - -The AuthDBMGroupFile directive sets the name of a DBM file containing the list -of user groups for user authentication. <EM>Filename</EM> is the absolute path -to the group file.<P> - -The group file is keyed on the username. The value for a user is a -comma-separated list of the groups to which the users belongs. There must -be no whitespace within the value, and it must never contain any colons.<P> - -Security: make sure that the AuthDBMGroupFile is stored outside the -document tree of the web-server; do <EM>not</EM> put it in the directory that -it protects. Otherwise, clients will be able to download the -AuthDBMGroupFile unless otherwise protected.<P> - -Combining Group and Password DBM files: In some cases it is easier to -manage a single database which contains both the password and group -details for each user. This simplifies any support programs that need -to be written: they now only have to deal with writing to and locking -a single DBM file. This can be accomplished by first setting the group -and password files to point to the same DBM:<P> - -<BLOCKQUOTE><CODE> -AuthDBMGroupFile /www/userbase<BR> -AuthDBMUserFile /www/userbase -</CODE></BLOCKQUOTE> - -The key for the single DBM is the username. The value consists of <P> - -<BLOCKQUOTE><CODE> -Unix Crypt-ed Password : List of Groups [ : (ignored) ] -</CODE></BLOCKQUOTE> - -The password section contains the Unix crypt() password as before. This is -followed by a colon and the comma separated list of groups. Other data may -optionally be left in the DBM file after another colon; it is ignored by the -authentication module. This is what www.telescope.org uses for its combined -password and group database. <P> - -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authdbmuserfile">AuthDBMUserFile</A>.<P><HR> - -<H2><A NAME="authdbmuserfile">AuthDBMUserFile</A></H2> -<!--%plaintext <?INDEX {\tt AuthDBMUserFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDBMUserFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_dbm<P> - -The AuthDBMUserFile directive sets the name of a DBM file containing the list -of users and passwords for user authentication. <EM>Filename</EM> is the -absolute path to the user file.<P> - -The user file is keyed on the username. The value for a user is the -crypt() encrypted password, optionally followed by a colon and -arbitrary data. The colon and the data following it will be ignored -by the server.<P> - -Security: make sure that the AuthDBMUserFile is stored outside the -document tree of the web-server; do <EM>not</EM> put it in the directory that -it protects. Otherwise, clients will be able to download the -AuthDBMUserFile.<P> - -Important compatibility note: The implementation of "dbmopen" in the -apache modules reads the string length of the hashed values from the -DBM data structures, rather than relying upon the string being -NULL-appended. Some applications, such as the Netscape web server, -rely upon the string being NULL-appended, so if you are having trouble -using DBM files interchangeably between applications this may be a -part of the problem. <P> - -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authdbmgroupfile">AuthDBMGroupFile</A>.<P> - -<HR> -<H2><A NAME="authdbmauthoritative">AuthDBMAuthoritative</A></H2> -<!--%plaintext <?INDEX {\tt AuthDBMAuthoritative} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDBMAuthoritative < <STRONG> on</STRONG>(default) | off > <BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth<P> - -Setting the AuthDBMAuthoritative directive explicitly to <STRONG>'off'</STRONG> -allows for both authentication and authorization to be passed on -to lower level modules (as defined in the <CODE>Configuration</CODE> -and <CODE>modules.c</CODE> file if there is <STRONG>no userID</STRONG> or -<STRONG>rule</STRONG> matching the supplied userID. If there is a userID -and/or rule specified; the usual password and access checks will -be applied and a failure will give an Authorization Required reply. -<P> -So if a userID appears in the database of more than one module; or -if a valid require directive applies to more than one module; then -the first module will verify the credentials; and no access is -passed on; regardless of the AuthAuthoritative setting. <P> - -A common use for this is in conjunction with one of the basic auth -modules; such as <A HREF="mod_auth.html"><CODE>mod_auth.c</CODE></A>. -Whereas this DBM module supplies the bulk of the user credential -checking; a few (administrator) related accesses fall through to -a lower level with a well protected .htpasswd file. <P> - -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> By default; control is not passed on; and an unknown -userID or rule will result in an Authorization Required reply. Not -setting it thus keeps the system secure; and forces an NCSA compliant -behaviour. <P> - -Security: Do consider the implications of allowing a user to allow -fall-through in his .htaccess file; and verify that this is really -what you want; Generally it is easier to just secure a single -.htpasswd file, than it is to secure a database which might have -more access interfaces. - -<P> -See also <A HREF="core.html#authname">AuthName</A>, -<A HREF="core.html#authtype">AuthType</A> and -<A HREF="#authdbmgroupfile">AuthDBMGroupFile</A>.<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_auth_digest.html b/docs/manual/mod/mod_auth_digest.html deleted file mode 100644 index 35c7f0628e..0000000000 --- a/docs/manual/mod/mod_auth_digest.html +++ /dev/null @@ -1,416 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_auth_digest</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_auth_digest</H1> - -This module is contained in the <CODE>mod_auth_digest.c</CODE> file, and is -not compiled in by default. It is only available in Apache 1.3.8 and -later. It provides for user authentication using MD5 Digest -Authentication. - -<P>Note this is an updated version of <A -HREF="mod_digest.html">mod_digest</A>. However, it has not been -extensively tested and is therefore marked experimental. If you use this -module, you must make sure to <em>not</em> use mod_digest (because they -share some of the same configuration directives). - - -<MENU> -<LI><A HREF="#authdigestfile">AuthDigestFile</A> -<LI><A HREF="#authdigestgroupfile">AuthDigestGroupFile</A> -<LI><A HREF="#authdigestqop">AuthDigestQop</A> -<LI><A HREF="#authdigestnoncelifetime">AuthDigestNonceLifetime</A> -<LI><A HREF="#authdigestnonceformat">AuthDigestNonceFormat</A> -<LI><A HREF="#authdigestnccheck">AuthDigestNcCheck</A> -<LI><A HREF="#authdigestalgorithm">AuthDigestAlgorithm</A> -<LI><A HREF="#authdigestdomain">AuthDigestDomain</A> -<LI><A HREF="#usingdigest">Using Digest Authentication</A> -</MENU> -<HR> - - -<H2><A NAME="authdigestfile">AuthDigestFile</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest<BR> - -<P>The AuthDigestFile directive sets the name of a textual file containing -the list of users and encoded passwords for digest authentication. -<EM>Filename</EM> is the absolute path to the user file. - -<P>The digest file uses a special format. Files in this format can be -created using the "htdigest" utility found in the support/ subdirectory of -the Apache distribution. - -<HR> - -<H2><A NAME="authdigestgroupfile">AuthDigestGroupFile</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestGroupFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3.8 and later - -<P>The AuthDigestGroupFile directive sets the name of a textual file -containing the list of groups and their members (user names). -<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 text files is <EM>very</EM> inefficient. - -<P>Security: make sure that the AuthGroupFile is stored outside the -document tree of the web-server; do <EM>not</EM> put it in the directory -that it protects. Otherwise, clients will be able to download the -AuthGroupFile. - -<HR> - -<H2><A NAME="authdigestqop">AuthDigestQop</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestQop <EM>none | 1*{ auth | auth-int }</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AuthDigestQop auth</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3.8 and later - -<P>The AuthDigestQop directive determines the quality-of-protection to use. -<EM>auth</EM> will only do authentication (username/password); -<EM>auth-int</EM> is authentication plus integrity checking (an MD5 hash -of the entity is also computed and checked); <EM>none</EM> will cause the -module to use the old RFC-2069 digest algorithm (which does not include -integrity checking). Both <EM>auth</em> and <EM>auth-int</EM> may be -specified, in which the case the browser will choose which of these to -use. <EM>none</EM> should only be used if the browser for some reason -does not like the challenge it receives otherwise. - -<P><STRONG><EM>auth-int</EM> is not implemented yet</STRONG>. - -<HR> - -<H2><A NAME="authdigestnoncelifetime">AuthDigestNonceLifetime</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestNonceLifetime <EM><time></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AuthDigestNonceLifetime 300</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3.8 and later - -<P>The AuthDigestNonceLifetime directive controls how long the server -nonce is valid. When the client contacts the server using an expired -nonce the server will send back a 401 with <code>stale=true</code>. If -<EM><time></EM> is greater than 0 then it specifies the number of -seconds the nonce is valid; this should probably never be set to less -than 10 seconds. If <EM><time></EM> is less than 0 then the nonce -never expires. - -<!-- Not implemented yet -If <EM><time></EM> is 0 then the nonce may be used exactly once -by the client. Note that while one-time-nonces provide higher security -against replay attacks, they also have significant performance -implications, as the browser cannot pipeline or multiple connections -for the requests. Because browsers cannot easily detect that -one-time-nonces are being used, this may lead to browsers trying to -pipeline requests and receiving 401 responses for all but the first -request, requiring the browser to resend the requests. Note also that -the protection against reply attacks only makes sense for dynamically -generated content and things like POST requests; for static content -the attacker may already have the complete response, so one-time-nonces -do not make sense here. ---> - -<HR> -<H2><A NAME="authdigestnonceformat">AuthDigestNonceFormat</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestNonceFormat <EM>???</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AuthDigestNonceFormat ???</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3.8 and later - -<P><STRONG>Not implemented yet.</STRONG> -<!-- -<P>The AuthDigestNonceFormat directive determines how the nonce is -generated. ---> - -<HR> -<H2><A NAME="authdigestnccheck">AuthDigestNcCheck</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestNcCheck <EM>On/Off</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AuthDigestNcCheck Off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3.8 and later - -<P><STRONG>Not implemented yet.</STRONG> -<!-- -<P>The AuthDigestNcCheck directive enables or disables the checking of the -nonce-count sent by the server. - -<P>While recommended from a security standpoint, turning this directive -On has one important performance implication. To check the nonce-count -*all* requests (which have an Authorization header, irrespective of -whether they require digest authentication) must be serialized through -a critical section. If the server is handling a large number of -requests which contain the Authorization header then this may noticeably -impact performance. ---> - -<HR> -<H2><A NAME="authdigestalgorithm">AuthDigestAlgorithm</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestAlgorithm <EM>MD5 | MD5-sess</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AuthDigestAlgorithm MD5</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3.8 and later - -<P>The AuthDigestAlgorithm directive selects the algorithm used to calculate -the challenge and response hashes. - -<P><STRONG><EM>MD5-sess</EM> is not correctly implemented yet</STRONG>. -<!-- -<P>To use <EM>MD5-sess</EM> you must first code up the -<VAR>get_userpw_hash()</VAR> function in <VAR>mod_auth_digest.c</VAR> . ---> - -<HR> -<H2><A NAME="authdigestdomain">AuthDigestDomain</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestDomain <EM>URI URI ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3.8 and later - -<P>The AuthDigestDomain directive allows you to specify one or more URIs -which are in the same protection space (i.e. use the same realm and -username/password info). The specified URIs are prefixes, i.e. the client -will assume that all URIs "below" these are also protected by the same -username/password. The URIs may be either absolute URIs (i.e. inluding a -scheme, host, port, etc) or relative URIs. - -<P>This directive <em>should</em> always be specified and contain at least -the (set of) root URI(s) for this space. Omiting to do so will cause the -client to send the Authorization header for <em>every request</em> sent to -this server. Apart from increasing the size of the request, it may also -have a detrimental effect on performance if "AuthDigestNcCheck" is on. - -<P>The URIs specified can also point to different servers, in which case -clients (which understand this) will then share username/password info -across multiple servers without prompting the user each time. - - -<HR> - -<H3><A NAME="usingdigest">Using Digest Authentication</A></H3> - -<P>Using MD5 Digest authentication is very simple. Simply set up -authentication normally, using "AuthType Digest" and "AuthDigestFile" -instead of the normal "AuthType Basic" and "AuthUserFile"; also, -replace any "AuthGroupFile" with "AuthDigestGroupFile". Then add a -"AuthDigestDomain" directive containing at least the root URI(s) for -this protection space. Example: - -<PRE> - <Location /private/> - AuthType Digest - AuthName "private area" - AuthDigestDomain /private/ http://mirror.my.dom/private2/ - AuthDigestFile /web/auth/.digest_pw - require valid-user - </Location> -</PRE> - -<P><strong>Note:</strong> MD5 authentication provides a more secure -password system than Basic authentication, but only works with supporting -browsers. As of this writing (July 1999), the only major browsers which -support digest authentication are <A -HREF="http://www.microsoft.com/windows/ie/">Internet Exploder 5.0</A> and -<A HREF="http://www.w3.org/Amaya/">Amaya</A>. Therefore, we do not -recommend using this feature on a large Internet site. However, for -personal and intra-net use, where browser users can be controlled, it is -ideal. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_autoindex.html b/docs/manual/mod/mod_autoindex.html deleted file mode 100644 index 7fedd69c48..0000000000 --- a/docs/manual/mod/mod_autoindex.html +++ /dev/null @@ -1,814 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_autoindex</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_autoindex</H1> - -This module is contained in the <CODE>mod_autoindex.c</CODE> file, and -is compiled in by default. It provides for automatic directory indexing. - -<H2>Summary</H2> -The index of a directory can come from one of two sources: -<UL> -<LI>A file written by the user, typically called <CODE>index.html</CODE>. -The <A HREF="mod_dir.html#directoryindex">DirectoryIndex</A> directive sets -the name of this file. -This is controlled by <A HREF="mod_dir.html"><CODE>mod_dir</CODE></A>. -<LI>Otherwise, a listing generated by the server. The other directives -control the format of this listing. The <A HREF="#addicon">AddIcon</A>, -<A HREF="#addiconbyencoding">AddIconByEncoding</A> and -<A HREF="#addiconbytype">AddIconByType</A> are used to set a list of -icons to display for various file types; for each file listed, the -first icon listed that matches the file is displayed. These -are controlled by <CODE>mod_autoindex</CODE>. -</UL> -The two functions are separated so that you can completely remove -(or replace) automatic index generation should you want to. -<P> -If -<A - HREF="#fancyindexing" -><SAMP>FancyIndexing</SAMP></A> -is enabled, or the <SAMP>FancyIndexing</SAMP> keyword is present on the -<A - HREF="#indexoptions" -><SAMP>IndexOptions</SAMP></A> -directive, the column headers are links that control the -order of the display. If you select a header link, the -listing will be regenerated, sorted by the values in that -column. Selecting the same header repeatedly toggles -between ascending and descending order. -</P> -<P> -Note that when the display is sorted by "Size", -it's the <EM>actual</EM> size of the files that's used, -not the displayed value - so a 1010-byte file will -always be displayed before a 1011-byte file (if in ascending -order) even though they both are shown as "1K". -</P> - - -<H2>Directives</H2> - -<MENU> -<LI><A HREF="#addalt">AddAlt</A> -<LI><A HREF="#addaltbyencoding">AddAltByEncoding</A> -<LI><A HREF="#addaltbytype">AddAltByType</A> -<LI><A HREF="#adddescription">AddDescription</A> -<LI><A HREF="#addicon">AddIcon</A> -<LI><A HREF="#addiconbyencoding">AddIconByEncoding</A> -<LI><A HREF="#addiconbytype">AddIconByType</A> -<LI><A HREF="#defaulticon">DefaultIcon</A> -<LI><A HREF="#fancyindexing">FancyIndexing</A> -<LI><A HREF="#headername">HeaderName</A> -<LI><A HREF="#indexignore">IndexIgnore</A> -<LI><A HREF="#indexoptions">IndexOptions</A> -<LI><A HREF="#indexorderdefault">IndexOrderDefault</A> -<LI><A HREF="#readmename">ReadmeName</A> -</MENU> -<HR> - -<H2><A NAME="addalt">AddAlt</A></H2> -<!--%plaintext <?INDEX {\tt AddAlt} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddAlt <EM>string file file...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -This sets the alternate text to display for a file, instead of an icon, for -<A HREF="#fancyindexing">FancyIndexing</A>. <EM>File</EM> is a file -extension, partial filename, wild-card expression or full filename for files -to describe. <EM>String</EM> is enclosed in double quotes -(<CODE>"</CODE>). This alternate text is displayed if the client is -image-incapable or has image loading disabled. - -<HR> -<H2><A NAME="addaltbyencoding">AddAltByEncoding</A></H2> -<!--%plaintext <?INDEX {\tt AddAltByEncoding} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddAltByEncoding <EM>string MIME-encoding - MIME-encoding...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -This sets the alternate text to display for a file, instead of an icon, for -<A HREF="#fancyindexing">FancyIndexing</A>. <EM>MIME-encoding</EM> is a -valid content-encoding, such as <SAMP>x-compress</SAMP>. -<EM>String</EM> is enclosed in double quotes -(<CODE>"</CODE>). This alternate text is displayed if the client is -image-incapable or has image loading disabled. - -<HR> -<H2><A NAME="addaltbytype">AddAltByType</A></H2> -<!--%plaintext <?INDEX {\tt AddAltByType} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddAltByType <EM>string MIME-type MIME-type - ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -This sets the alternate text to display for a file, instead of an icon, for -<A HREF="#fancyindexing">FancyIndexing</A>. <EM>MIME-type</EM> is a -valid content-type, such as <SAMP>text/html</SAMP>. -<EM>String</EM> is enclosed in double quotes -(<CODE>"</CODE>). This alternate text is displayed if the client is -image-incapable or has image loading disabled. - -<HR> - -<H2><A NAME="adddescription">AddDescription</A></H2> -<!--%plaintext <?INDEX {\tt AddDescription} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddDescription <EM>string file file...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -This sets the description to display for a file, for -<A HREF="#fancyindexing">FancyIndexing</A>. <EM>File</EM> is a file -extension, partial filename, wild-card expression or full filename for files -to describe. <EM>String</EM> is enclosed in double quotes -(<CODE>"</CODE>). Example: -<BLOCKQUOTE><CODE>AddDescription "The planet Mars" /web/pics/mars.gif -</CODE></BLOCKQUOTE> -<P> -The description field is 23 bytes wide. 7 more bytes may be -added if the directory is covered by an -<CODE>IndexOptions SuppressSize</CODE>, and 19 bytes may be -added if <CODE>IndexOptions SuppressLastModified</CODE> is -in effect. The widest this column can be is therefore 49 bytes. -</P> -<HR> - -<H2><A NAME="addicon">AddIcon</A></H2> -<!--%plaintext <?INDEX {\tt AddIcon} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddIcon <EM>icon name name ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -This sets the icon to display next to a file ending in <EM>name</EM> for -<A HREF="#fancyindexing">FancyIndexing</A>. <EM>Icon</EM> is either a -(%-escaped) relative URL to the icon, or of the format -(<EM>alttext</EM>,<EM>url</EM>) where <EM>alttext</EM> is the text tag given -for an icon for non-graphical browsers.<P> - -<EM>Name</EM> is either ^^DIRECTORY^^ for directories, ^^BLANKICON^^ for -blank lines (to format the list correctly), a file extension, a wildcard -expression, a partial filename or a complete filename. Examples: -<BLOCKQUOTE><CODE> -AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm <BR> -AddIcon /icons/dir.xbm ^^DIRECTORY^^ <BR> -AddIcon /icons/backup.xbm *~ -</CODE></BLOCKQUOTE> -<A HREF="#addiconbytype">AddIconByType</A> should be used in preference to -AddIcon, when possible.<P><HR> - -<H2><A NAME="addiconbyencoding">AddIconByEncoding</A></H2> -<!--%plaintext <?INDEX {\tt AddIconByEncoding} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddIconByEncoding <EM>icon MIME-encoding - MIME-encoding ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -This sets the icon to display next to files with -<EM>MIME-encoding</EM> for <A HREF="#fancyindexing">FancyIndexing</A>. -<EM>Icon</EM> is either a (%-escaped) relative URL to the icon, or of the -format (<EM>alttext</EM>,<EM>url</EM>) where <EM>alttext</EM> is the text tag -given for an icon for non-graphical browsers.<P> - -<EM>Mime-encoding</EM> is a wildcard expression matching required the -content-encoding. Examples: -<BLOCKQUOTE><CODE> -AddIconByEncoding /icons/compress.xbm x-compress -</CODE></BLOCKQUOTE><P><HR> - -<H2><A NAME="addiconbytype">AddIconByType</A></H2> -<!--%plaintext <?INDEX {\tt AddIconByType} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddIconByType <EM>icon MIME-type MIME-type - ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -This sets the icon to display next to files of type <EM>MIME-type</EM> for -<A HREF="#fancyindexing">FancyIndexing</A>. <EM>Icon</EM> is either a -(%-escaped) relative URL to the icon, or of the format -(<EM>alttext</EM>,<EM>url</EM>) where <EM>alttext</EM> is the text tag given -for an icon for non-graphical browsers.<P> -<EM>Mime-type</EM> is a wildcard expression matching required the mime types. -Examples: -<BLOCKQUOTE><CODE> -AddIconByType (IMG,/icons/image.xbm) image/* -</CODE></BLOCKQUOTE><P><HR> - -<H2><A NAME="defaulticon">DefaultIcon</A></H2> -<!--%plaintext <?INDEX {\tt DefaultIcon} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> DefaultIcon <EM>url</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -The DefaultIcon directive sets the icon to display for files when no -specific icon is known, for <A HREF="#fancyindexing">FancyIndexing</A>. -<EM>Url</EM> is a (%-escaped) relative URL to the icon. Examples: -<BLOCKQUOTE><CODE> -DefaultIcon /icon/unknown.xbm -</CODE></BLOCKQUOTE><P><HR> - -<H2><A NAME="fancyindexing">FancyIndexing</A></H2> -<!--%plaintext <?INDEX {\tt FancyIndexing} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> FancyIndexing <EM>boolean</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex -<P> -The FancyIndexing directive sets the FancyIndexing option for a directory. -<EM>Boolean</EM> can be <CODE>on</CODE> or <CODE>off</CODE>. The -<A HREF="#indexoptions">IndexOptions</A> directive should be used in -preference. -</P> -<BLOCKQUOTE> - <STRONG>Note that in versions of Apache prior to 1.3.2, the - <SAMP>FancyIndexing</SAMP> and - <SAMP>IndexOptions</SAMP> directives will override each other. You - should use <SAMP>IndexOptions FancyIndexing</SAMP> in preference - to the standalone <SAMP>FancyIndexing</SAMP> directive. - As of Apache 1.3.2, a standalone <SAMP>FancyIndexing</SAMP> directive - is combined with any <SAMP>IndexOptions</SAMP> directive already - specified for the current scope.</STRONG> -</BLOCKQUOTE> -<HR> - -<H2><A NAME="headername">HeaderName</A></H2> -<!--%plaintext <?INDEX {\tt HeaderName} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> HeaderName <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> some features only available after - 1.3.6; see text - -<P> -The HeaderName directive sets the name of the file that will be inserted -at the top of the index listing. <EM>Filename</EM> is the name of the file -to include. -</P> -<BLOCKQUOTE><STRONG>Apache 1.3.6 and earlier:</STRONG> -The module first attempts to include <EM>filename</EM><CODE>.html</CODE> -as an HTML document, otherwise it will try to include <EM>filename</EM> as -plain text. <EM>Filename</EM> is treated as a filesystem path relative -to the directory being indexed. In no case is SSI processing done. -Example: -<BLOCKQUOTE><CODE>HeaderName HEADER</CODE></BLOCKQUOTE> -when indexing the directory <CODE>/web</CODE>, the server will first look for -the HTML file <CODE>/web/HEADER.html</CODE> and include it if found, otherwise -it will include the plain text file <CODE>/web/HEADER</CODE>, if it exists. -</BLOCKQUOTE> -<BLOCKQUOTE><STRONG>Apache versions after 1.3.6:</STRONG> -<EM>Filename</EM> is treated as a URI path relative to the one used -to access the directory being indexed, and must resolve to a document -with a major content type of "<SAMP>text</SAMP>" (<EM>e.g.</EM>, -<SAMP>text/html</SAMP>, <SAMP>text/plain</SAMP>, <EM>etc.</EM>). -This means that <EM>filename</EM> may refer to a CGI script if the -script's actual file type (as opposed to its output) is marked as -<SAMP>text/html</SAMP> such as with a directive like: -<PRE> - AddType text/html .cgi -</PRE> -<A HREF="../content-negotiation.html">Content negotiation</A> -will be performed if the <SAMP>MultiViews</SAMP> -<A HREF="core.html#options">option</A> is enabled. -If <EM>filename</EM> resolves to a static <SAMP>text/html</SAMP> document -(not a CGI script) and the -<SAMP>Includes</SAMP> <A HREF="core.html#options">option</A> is enabled, -the file will be processed for server-side includes (see the -<A HREF="mod_include.html"><SAMP>mod_include</SAMP></A> documentation). -</BLOCKQUOTE> -<P> -See also <A HREF="#readmename">ReadmeName</A>. -<P><HR> - -<H2><A NAME="indexignore">IndexIgnore</A></H2> -<!--%plaintext <?INDEX {\tt IndexIgnore} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> IndexIgnore <EM>file file ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -The IndexIgnore directive adds to the list of files to hide when listing -a directory. <EM>File</EM> is a file extension, partial filename, -wildcard expression or full filename for files to ignore. Multiple -IndexIgnore directives add to the list, rather than the replacing the list -of ignored files. By default, the list contains `<CODE>.</CODE>'. Example: -<BLOCKQUOTE><CODE> -IndexIgnore README .htaccess *~ -</CODE></BLOCKQUOTE><P><HR> - -<H2><A NAME="indexoptions">IndexOptions</A></H2> -<!--%plaintext <?INDEX {\tt IndexOptions} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> IndexOptions <EM>option option ...</EM> - (Apache 1.3.2 and earlier) -<BR> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> IndexOptions <EM>[+|-]option [+|-]option - ...</EM> - (Apache 1.3.3 and later) -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex -<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> '+/-' syntax and merging of multiple - <SAMP>IndexOptions</SAMP> directives is only available with - Apache 1.3.3 and later -<P> - -The IndexOptions directive specifies the behavior of the directory indexing. -<EM>Option</EM> can be one of -<DL> -<DT><A NAME="indexoptions:fancyindexing">FancyIndexing</A> -<DD><!--%plaintext <?INDEX {\tt FancyIndexing} index option> --> -This turns on fancy indexing of directories. -<BLOCKQUOTE> - <STRONG>Note that in versions of Apache prior to 1.3.2, the - <SAMP>FancyIndexing</SAMP> and - <SAMP>IndexOptions</SAMP> directives will override each other. You - should use <SAMP>IndexOptions FancyIndexing</SAMP> in preference - to the standalone <SAMP>FancyIndexing</SAMP> directive. - As of Apache 1.3.2, a standalone <SAMP>FancyIndexing</SAMP> directive - is combined with any <SAMP>IndexOptions</SAMP> directive already - specified for the current scope.</STRONG> -</BLOCKQUOTE> -<DT><A NAME="indexoptions:iconheight">IconHeight[=pixels] (<EM>Apache 1.3 and later</EM>)</A> -<DD> -<!--%plaintext <?INDEX {\tt IconHeight} index option> --> -Presence of this option, when used with IconWidth, will cause the server -to include <SAMP>HEIGHT</SAMP> and <SAMP>WIDTH</SAMP> attributes in the -<SAMP>IMG</SAMP> tag for the file icon. This allows browser to -precalculate the page layout without having to wait until all the -images have been loaded. If no value is given for the option, it -defaults to the standard height of the icons supplied with the Apache -software. -<DT><A NAME="indexoptions:iconsarelinks">IconsAreLinks</A> -<DD> -<!--%plaintext <?INDEX {\tt IconsAreLinks} index option> --> -This makes the icons part of the anchor for the filename, for -fancy indexing. -<DT><A NAME="indexoptions:iconwidth">IconWidth[=pixels] (<EM>Apache 1.3 and later</EM>)</A> -<DD> -<!--%plaintext <?INDEX {\tt IconWidth} index option> --> -Presence of this option, when used with IconHeight, will cause the server -to include <SAMP>HEIGHT</SAMP> and <SAMP>WIDTH</SAMP> attributes in the -<SAMP>IMG</SAMP> tag for the file icon. This allows browser to -precalculate the page layout without having to wait until all the -images have been loaded. If no value is given for the option, it -defaults to the standard width of the icons supplied with the Apache -software. -<DT><A NAME="indexoptions:namewidth">NameWidth=[<EM>n</EM> | *] (<EM>Apache 1.3.2 and later</EM>)</A> -<DD> -The NameWidth keyword allows you to specify the width of the -filename column in bytes. If the keyword value is '<SAMP>*</SAMP>', -then the column is automatically sized to the length of the longest -filename in the display. -<DT><A NAME="indexoptions:scanhtmltitles">ScanHTMLTitles</A> -<DD><!--%plaintext <?INDEX {\tt ScanHTMLTitles} index option> --> -This enables the extraction of the title from HTML documents for fancy -indexing. If the file does not have a description given by -<A HREF="#adddescription">AddDescription</A> then httpd will read the -document for the value of the TITLE tag. This is CPU and disk intensive. -<DT><A NAME="indexoptions:suppresscolumnsorting">SuppressColumnSorting</A> -<DD> -<!--%plaintext <?INDEX {\tt SuppressColumnSorting} index option> --> -If specified, Apache will not make the column headings in a FancyIndexed -directory listing into links for sorting. The default behaviour is -for them to be links; selecting the column heading will sort the directory -listing by the values in that column. -<STRONG>Only available in Apache 1.3 and later.</STRONG> -<DT><A NAME="indexoptions:suppressdescription">SuppressDescription</A> -<DD> -<!--%plaintext <?INDEX {\tt SuppressDescription} index option> --> -This will suppress the file description in fancy indexing listings. -<DT><A NAME="indexoptions:suppresshtmlpreamble">SuppressHTMLPreamble</A> - (<EM>Apache 1.3 and later</EM>) -<DD> -<!--%plaintext <?INDEX {\tt SuppressHTMLPreamble} index option> --> -If the directory actually contains a file specified by the -<A - HREF="#headername" ->HeaderName</A> -directive, the module usually includes the contents of the file -after a standard HTML preamble (<HTML>, <HEAD>, <EM>et -cetera</EM>). The SuppressHTMLPreamble option disables this behaviour, -causing the module to start the display with the header file contents. -The header file must contain appropriate HTML instructions in this case. -If there is no header file, the preamble is generated as usual. -<DT><A NAME="indexoptions:suppresslastmodified">SuppressLastModified</A> -<DD> -<!--%plaintext <?INDEX {\tt SuppressLastModified} index option> --> -This will suppress the display of the last modification date, in fancy -indexing listings. -<DT><A NAME="indexoptions:suppresssize">SuppressSize</A> -<DD> -<!--%plaintext <?INDEX {\tt SuppressSize} index option> --> -This will suppress the file size in fancy indexing listings. -</DL> -<P> -There are some noticeable differences in the behaviour of this -directive in recent (post-1.3.0) versions of Apache. -</P> -<DL> -<DT>Apache 1.3.2 and earlier:</DT> -<DD> -<P> -The default is that no options are enabled. If multiple IndexOptions -could apply to a directory, then the most specific one is taken complete; -the options are not merged. For example: -<BLOCKQUOTE><CODE> -<Directory /web/docs> <BR> -IndexOptions FancyIndexing <BR> -</Directory><BR> -<Directory /web/docs/spec> <BR> -IndexOptions ScanHTMLTitles <BR> -</Directory> -</CODE></BLOCKQUOTE> -then only <CODE>ScanHTMLTitles</CODE> will be set for the /web/docs/spec -directory. -</P> -</DD> -<DT>Apache 1.3.3 and later:</DT> -<DD> -<P> -Apache 1.3.3 introduced some significant changes in the handling of -<SAMP>IndexOptions</SAMP> directives. In particular, -</P> -<UL> - <LI>Multiple <SAMP>IndexOptions</SAMP> directives for a single - directory are now merged together. The result of the example above - will now be the equivalent of - <CODE>IndexOptions FancyIndexing ScanHTMLTitles</CODE>. - </LI> - <LI>The addition of the incremental syntax (<EM>i.e.</EM>, prefixing - keywords with '+' or '-'). - </LI> -</UL> -<P> -Whenever a '+' or '-' prefixed keyword is encountered, it is applied -to the current <SAMP>IndexOptions</SAMP> settings (which may have been -inherited from an upper-level directory). However, whenever an unprefixed -keyword is processed, it clears all inherited options and any incremental -settings encountered so far. Consider the following example: -</P> -<BLOCKQUOTE><CODE>IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing -<BR> -IndexOptions +SuppressSize -<BR> -</CODE></BLOCKQUOTE> -<P> -The net effect is equivalent to -<CODE>IndexOptions FancyIndexing +SuppressSize</CODE>, because -the unprefixed <CODE>FancyIndexing</CODE> discarded the incremental -keywords before it, but allowed them to start accumulating again -afterward. -</P> -<P> -To unconditionally set the <CODE>IndexOptions</CODE> for a -particular directory, clearing the inherited settings, specify -keywords without either '+' or '-' prefixes. -</P> -</DD> -</DL> - -<HR> - -<H2><A NAME="indexorderdefault">IndexOrderDefault</A></H2> -<!--%plaintext <?INDEX {\tt IndexOrderDefault} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> IndexOrderDefault - <EM>Ascending|Descending</EM> <EM>Name|Date|Size|Description</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess -<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes -<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex -<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> IndexOrderDefault is only available in -Apache 1.3.4 and later. - -<P> -The <SAMP>IndexOrderDefault</SAMP> directive is used in combination with -the <A HREF="#indexoptions:fancyindexing"><SAMP>FancyIndexing</SAMP></A> -index option. By default, fancyindexed directory listings are displayed in ascending order by filename; the <SAMP>IndexOrderDefault</SAMP> allows -you to change this initial display order. -</P> -<P> -<SAMP>IndexOrderDefault</SAMP> takes two arguments. The first must be either -<SAMP>Ascending</SAMP> or <SAMP>Descending</SAMP>, indicating the direction -of the sort. The second argument must be one of the keywords -<SAMP>Name</SAMP>, <SAMP>Date</SAMP>, <SAMP>Size</SAMP>, or -<SAMP>Description</SAMP>, and identifies the primary key. The secondary -key is <EM>always</EM> the ascending filename. -</P> -<P> -You can force a directory listing to only be displayed in a particular -order by combining this directive with the -<A HREF="#indexoptions:suppresscolumnsorting" -><SAMP>SuppressColumnSorting</SAMP></A> index option; this will prevent -the client from requesting the directory listing in a different order. -</P> - -<HR> - -<H2><A NAME="readmename">ReadmeName</A></H2> -<!--%plaintext <?INDEX {\tt ReadmeName} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ReadmeName <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> some features only available after - 1.3.6; see text - -<P> -The ReadmeName directive sets the name of the file that will be appended -to the end of the index listing. <EM>Filename</EM> is the name of the file -to include, and is taken to be relative to the location being indexed. -</P> -<BLOCKQUOTE> -<STRONG>The <EM>filename</EM> argument is treated as a stub filename -in Apache 1.3.6 and earlier, and as a relative URI in later versions. -Details of how it is handled may be found under the description of -the <A HREF="#headername">HeaderName</A> directive, which uses the -same mechanism and changed at the same time as ReadmeName.</STRONG> -</BLOCKQUOTE> -<P>See also <A HREF="#headername">HeaderName</A>.<P> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_cern_meta.html b/docs/manual/mod/mod_cern_meta.html deleted file mode 100644 index 0ac5282421..0000000000 --- a/docs/manual/mod/mod_cern_meta.html +++ /dev/null @@ -1,143 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Module mod_cern_meta</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache module mod_cern_meta</H1> - -This module is contained in the <CODE>mod_cern_meta.c</CODE> file, and -is not compiled in by default. It provides for CERN httpd metafile -semantics. It is only available in Apache 1.1 and later. - -<H2>Summary</H2> - -Emulate the CERN HTTPD Meta file semantics. Meta files are HTTP -headers that can be output in addition to the normal range of headers -for each file accessed. They appear rather like the Apache -.asis files, and are able to provide a crude way of influencing -the Expires: header, as well as providing other curiosities. -There are many ways to manage meta information, this one was -chosen because there is already a large number of CERN users -who can exploit this module. - -<P>More information on the -<A HREF="http://www.w3.org/pub/WWW/Daemon/User/Config/General.html#MetaDir" ->CERN metafile semantics</A> is available. - -<H2>Directives</H2> -<UL> -<LI><A HREF="#metafiles">MetaFiles</A> -<LI><A HREF="#metadir">MetaDir</A> -<LI><A HREF="#metasuffix">MetaSuffix</A> -</UL> - -<HR> - -<H2><A NAME="metafiles">MetaFiles</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MetaFiles <EM>on/off</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MetaFiles off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> per-directory config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_cern_meta<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> MetaFiles is only available in Apache 1.3 -and later.<P> - -Turns on/off Meta file processing on a per-directory basis. This option was introduced in Apache 1.3. - -<H2><A NAME="metadir">MetaDir</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MetaDir <EM>directory name</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MetaDir .web</CODE><BR> -<STRONG>Context: (Apache prior to 1.3)</STRONG> server config<BR> -<STRONG>Context: (Apache 1.3)</STRONG> per-directory config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_cern_meta<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> MetaDir is only available in Apache 1.1 -and later.<P> - -Specifies the name of the directory in which Apache can find -meta information files. The directory is usually a 'hidden' -subdirectory of the directory that contains the file being -accessed. Set to "<CODE>.</CODE>" to look in the same directory as the -file. - -<H2><A NAME="metasuffix">MetaSuffix</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MetaSuffix <EM>suffix</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MetaSuffix .meta</CODE><BR> -<STRONG>Context: (Apache prior to 1.3)</STRONG> server config<BR> -<STRONG>Context: (Apache 1.3)</STRONG> per-directory config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_cern_meta<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> MetaSuffix is only available in Apache 1.1 -and later.<P> - -Specifies the file name suffix for the file containing the -meta information. For example, the default values for the two -directives will cause a request to <CODE> -DOCUMENT_ROOT/somedir/index.html</CODE> to look in -<CODE>DOCUMENT_ROOT/somedir/.web/index.html.meta</CODE> and will use -its contents to generate additional MIME header information. - -<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_cgi.html b/docs/manual/mod/mod_cgi.html deleted file mode 100644 index 1d5df58f60..0000000000 --- a/docs/manual/mod/mod_cgi.html +++ /dev/null @@ -1,216 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_cgi</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_cgi</H1> - -This module is contained in the <CODE>mod_cgi.c</CODE> file, and -is compiled in by default. It provides for execution of CGI scripts. -Any file with mime type <CODE>application/x-httpd-cgi</CODE> will be -processed by this module. -<!--%plaintext <?INDEX {\tt application/x-httpd-cgi} mime type> --> -<!--%plaintext <?INDEX CGI scripts> --> - -<H2>Summary</H2> -Any file that has the mime type <CODE>application/x-httpd-cgi</CODE> -or handler <CODE>cgi-script</CODE> (Apache 1.1 or later) -will be treated as a CGI script, and run by the server, with its output -being returned to the client. Files acquire this type either by -having a name containing an extension defined by the -<A HREF="mod_mime.html#addtype">AddType</A> directive, or by being in -a <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> directory. <P> - -When the server invokes a CGI script, it will add a variable called -<CODE>DOCUMENT_ROOT</CODE> to the environment. This variable will contain the -value of the <A HREF="core.html#documentroot">DocumentRoot</A> -configuration variable. - -<H2>CGI Environment variables</H2> -The server will set the CGI environment variables as described in the -<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI specification</A>, with the -following provisions: -<DL> -<DT>REMOTE_HOST -<DD>This will only be set if <A HREF="core.html#hostnamelookups"><CODE>HostnameLookups</CODE></A> -is set to <CODE>on</CODE> (it is off by default), and if a reverse DNS -lookup of the accessing host's address indeed finds a host name. -<DT>REMOTE_IDENT -<DD>This will only be set if -<A HREF="core.html#identitycheck">IdentityCheck</A> is set to <CODE>on</CODE> -and the accessing host supports the ident protocol. Note that the contents -of this variable cannot be relied upon because it can easily be faked, and if -there is a proxy between the client and the server, it is usually -totally useless. -<DT>REMOTE_USER -<DD>This will only be set if the CGI script is subject to authentication. -</DL> -<P> - -<HR> - -<H2><A NAME="cgi_debug">CGI Debugging</A></H2> - -Debugging CGI scripts has traditionally been difficult, mainly because -it has -not -been possible to study the output (standard output and error) for -scripts -which are failing to run properly. These directives, included in -Apache 1.2 and later, provide -more detailed logging of errors when they occur. - -<HR> - -<H2>CGI Logfile Format</H2> - -When configured, the CGI error log logs any CGI which does not execute -properly. Each CGI script which fails to operate causes several lines -of information to be logged. The first two lines are always of the -format: - -<PRE> - %% [<EM>time</EM>] <EM>request-line</EM> - %% <EM>HTTP-status</EM> <EM>CGI-script-filename</EM> -</PRE> - -If the error is that CGI script cannot be run, the log file will -contain -an extra two lines: - -<PRE> - %%error - <EM>error-message</EM> -</PRE> - -Alternatively, if the error is the result of the script returning -incorrect header information (often due to a bug in the script), the -following information is logged: - -<PRE> - %request - <EM>All HTTP request headers received</EM> - <EM>POST or PUT entity (if any)</EM> - %response - <EM>All headers output by the CGI script</EM> - %stdout - <EM>CGI standard output</EM> - %stderr - <EM>CGI standard error</EM> -</PRE> - -(The %stdout and %stderr parts may be missing if the script did not -output -anything on standard output or standard error). - -<HR> - -<H2>Directives</H2> - -<H3><A NAME="scriptlog">ScriptLog</A></H3> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScriptLog <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> none<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> mod_cgi -<P> - -The <TT>ScriptLog</TT> directive sets the CGI script error logfile. -If no ScriptLog is given, no error log is created. If given, any -CGI errors are logged into the filename given as argument. If this -is a relative file or path it is taken relative to the server root. - -<P>This log will be opened as the user the child processes run as, -ie. the user specified in the main <A HREF="core.html#User">User</A> -directive. This means that either the directory the script log is -in needs to be writable by that user or the file needs to be manually -created and set to be writable by that user. If you place the -script log in your main logs directory, do <STRONG>NOT</STRONG> -change the directory permissions to make it writable by the user -the child processes run as.</P> - -<P>Note that script logging is meant to be a debugging feature when -writing CGI scripts, and is not meant to be activated continuously on -running servers. It is not optimized for speed or efficiency, and may -have security problems if used in a manner other than that for which -it was designed.</P> - -<H3><A NAME="scriptloglength">ScriptLogLength</A></H3> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScriptLogLength <EM>size</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> 10385760<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> mod_cgi -<P> - -<TT>ScriptLogLength</TT> can be used to limit the size of the CGI -script logfile. Since the logfile logs a lot of information per CGI -error (all request headers, all script output) it can grow to be a big -file. To prevent problems due to unbounded growth, this directive can -be used to set an maximum file-size for the CGI logfile. If the file -exceeds this size, no more information will be written to it. - -<H3><A NAME="scriptlogbuffer">ScriptLogBuffer</A></H3> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScriptLogBuffer <EM>size</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> 1024<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> mod_cgi -<P> - -The size of any PUT or POST entity body that is logged to the file is -limited, to prevent the log file growing too big too quickly if large -bodies are being received. By default, up to 1024 bytes are logged, -but this can be changed with this directive. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_dir.html b/docs/manual/mod/mod_dir.html deleted file mode 100644 index f150aa2e11..0000000000 --- a/docs/manual/mod/mod_dir.html +++ /dev/null @@ -1,103 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_dir</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_dir</H1> - -This module is contained in the <CODE>mod_dir.c</CODE> file, and -is compiled in by default. It provides for "trailing slash" redirects and -serving directory index files. - -<H2>Summary</H2> -The index of a directory can come from one of two sources: -<UL> -<LI>A file written by the user, typically called <CODE>index.html</CODE>. -The <A HREF="#directoryindex">DirectoryIndex</A> directive sets -the name of this file. -This is controlled by <CODE>mod_dir</CODE>. -<LI>Otherwise, a listing generated by the server. This is provided by -<A HREF="mod_autoindex.html"><CODE>mod_autoindex</CODE></A>. -</UL> -The two functions are separated so that you can completely remove -(or replace) automatic index generation should you want to. -<P>A "trailing slash" redirect is issued when the server receives a -request for a URL <SAMP>http://servername/foo/dirname</SAMP> where -<SAMP>dirname</SAMP> is a directory. Directories require a trailing -slash, so <CODE>mod_dir</CODE> issues a redirect to -<SAMP>http://servername/foo/dirname/</SAMP>. - -<H2>Directives</H2> - -<MENU> -<LI><A HREF="#directoryindex">DirectoryIndex</A> -</MENU> -<HR> - -<H2><A NAME="directoryindex">DirectoryIndex</A></H2> -<!--%plaintext <?INDEX {\tt DirectoryIndex} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> DirectoryIndex <EM>local-url local-url ...</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>DirectoryIndex index.html</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_dir<P> - -The DirectoryIndex directive sets the list of resources to look for, -when the client requests an index of the directory by specifying a / -at the end of the a directory name. <EM>Local-url</EM> is the -(%-encoded) URL of a document on the server relative to the requested -directory; it is usually the name of a file in the directory. Several -URLs may be given, in which case the server will return the first one -that it finds. If none of the resources exist and the -<CODE>Indexes</CODE> option is set, the server will generate its own -listing of the directory. -<P> - -Example: -<BLOCKQUOTE><CODE> -DirectoryIndex index.html -</CODE></BLOCKQUOTE> -then a request for <CODE>http://myserver/docs/</CODE> would return -<CODE>http://myserver/docs/index.html</CODE> if it exists, or would list -the directory if it did not. <P> - -Note that the documents do not need to be relative to the directory; -<BLOCKQUOTE><CODE> -DirectoryIndex index.html index.txt /cgi-bin/index.pl</CODE></BLOCKQUOTE> -would cause the CGI script <CODE>/cgi-bin/index.pl</CODE> to be executed -if neither <CODE>index.html</CODE> or <CODE>index.txt</CODE> existed in -a directory.<P><HR> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_env.html b/docs/manual/mod/mod_env.html deleted file mode 100644 index abe1fbf795..0000000000 --- a/docs/manual/mod/mod_env.html +++ /dev/null @@ -1,137 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_env</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache module mod_env</H1> - -This module is contained in the <CODE>mod_env.c</CODE> file, and -is compiled in by default. It provides for -passing environment variables to CGI/SSI scripts. Is is only available -in Apache 1.1 and later. - -<H2>Summary</H2> - -This module allows Apache's CGI and SSI environment to inherit -environment variables from the shell which invoked the httpd process. -CERN web-servers are able to do this, so this module is especially -useful to web-admins who wish to migrate from CERN to Apache without -rewriting all their scripts - -<H2>Directives</H2> -<UL> -<LI><A HREF="#passenv">PassEnv</A> -<LI><A HREF="#setenv">SetEnv</A> -<LI><A HREF="#unsetenv">UnsetEnv</A> -</UL> - -<HR> - -<H2><A NAME="passenv">PassEnv</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> PassEnv <EM>variable variable ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_env<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> PassEnv is only available in -Apache 1.1 and later.<P> - -Specifies one or more environment variables to pass to CGI scripts -from the server's own environment. Example: -<PRE> - PassEnv LD_LIBRARY_PATH -</PRE> - -<HR> - -<H2><A NAME="setenv">SetEnv</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> SetEnv <EM>variable value</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_env<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> SetEnv is only available in -Apache 1.1 and later.<P> - -Sets an environment variable, which is then passed on to CGI -scripts. Example: -<PRE> - SetEnv SPECIAL_PATH /foo/bin -</PRE> - -<HR> - -<H2><A NAME="unsetenv">UnsetEnv</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> UnsetEnv <EM>variable variable ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_env<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> UnsetEnv is only available in -Apache 1.1 and later.<P> - -Removes one or more environment variables from those passed on to -CGI scripts. Example: -<PRE> - UnsetEnv LD_LIBRARY_PATH -</PRE> - - - -<P> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_example.html b/docs/manual/mod/mod_example.html deleted file mode 100644 index 3cee4b97a8..0000000000 --- a/docs/manual/mod/mod_example.html +++ /dev/null @@ -1,168 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_example</TITLE> - </HEAD> - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Module mod_example</H1> - <P> - This module is contained in the <CODE>modules/mod_example.c</CODE> file, and - <STRONG>is not</STRONG> compiled in by default. It illustrates many of - the aspects of the - <A - HREF="../misc/API.html" - REL="Help" - >Apache 1.2 API</A> - and, when used, demonstrates the manner in which module callbacks are - triggered by the server. - </P> - <H2>Summary</H2> - <P> - The files in the <CODE>src/modules/example directory</CODE> under the - Apache distribution directory tree are provided as an example to those - that wish to write modules that use the Apache API. - </P> - <P> - The main file is <CODE>mod_example.c</CODE>, which illustrates all - the different callback mechanisms and call syntaxes. 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 "AddModule modules/example/mod_example" line near - the bottom of - the <CODE>src/Configuration</CODE> file. If there isn't one, add - it; it should look like this: - <PRE> - AddModule modules/example/mod_example.o - </PRE> - </LI> - <LI>Run the <CODE>src/Configure</CODE> script - ("<SAMP>cd src; ./Configure</SAMP>"). This will - build the Makefile for the server itself, and update the - <CODE>src/modules/Makefile</CODE> for any additional modules you - have requested from beneath that subdirectory. - </LI> - <LI>Make the server (run "<SAMP>make</SAMP>" in the <CODE>src</CODE> - directory). - </LI> - </OL> - <P> - To add another module of your own: - </P> - <OL TYPE="A"> - <LI><SAMP>mkdir src/modules/<EM>mymodule</EM></SAMP> - </LI> - <LI><SAMP>cp src/modules/example/* src/modules/<EM>mymodule</EM></SAMP> - </LI> - <LI>Modify the files in the new directory. - </LI> - <LI>Follow steps [1] through [3] above, with appropriate changes. - </LI> - </OL> - <H3> - Using the <SAMP>mod_example</SAMP> Module - </H3> - <P> - To activate the example module, include a block similar to the - following in your <SAMP>srm.conf</SAMP> file: - </P> - <PRE> - <Location /example-info> - SetHandler example-handler - </Location> - </PRE> - <P> - As an alternative, you can put the following into a - <A - HREF="core.html#accessfilename" - ><SAMP>.htaccess</SAMP></A> - file and then request the file "test.example" from that - location: - </P> - <PRE> - AddHandler example-handler .example - </PRE> - <P> - After reloading/restarting your server, you should be able to browse - to this location and see the brief display mentioned earlier. - </P> - <H2>Directives</H2> - <P> - <UL> - <LI><A HREF="#example">Example</A> - </LI> - </UL> - </P> - <HR> - <H2><A NAME="example"> - Example - </A></H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> Example - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> None - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> Options - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Extension - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_example - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> <SAMP>Example</SAMP> is only - available in Apache 1.2 and later. - </P> - <P> - The <SAMP>Example</SAMP> directive just sets a demonstration flag which the - example module's content handler displays. 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. The effect of this directive - one can observe under the point "<SAMP>Example directive declared - here: YES/NO</SAMP>". - </P> - <!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/mod_expires.html b/docs/manual/mod/mod_expires.html deleted file mode 100644 index 141a969598..0000000000 --- a/docs/manual/mod/mod_expires.html +++ /dev/null @@ -1,327 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_expires</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Module mod_expires</H1> - <P> - This module is contained in the <CODE>mod_expires.c</CODE> file, and - is <STRONG>not</STRONG> compiled in by default. It provides for the - generation of <CODE>Expires</CODE> headers according to user-specified - criteria. - </P> - <H2>Summary</H2> - <P> - This module controls the setting of the <CODE>Expires</CODE> HTTP - header in server responses. The expiration date can set to be - relative to either the time the source file was last modified, or to - the time of the client access. - </P> - <P> - The <CODE>Expires</CODE> HTTP header is an instruction to the client - about the document's validity and persistence. If cached, the document - may be fetched from the cache rather than from the source until this - time has passed. After that, the cache copy is considered - "expired" and invalid, and a new copy must be obtained from - the source. - </P> - <H2>Directives</H2> - <P> - <MENU> - <LI><A - HREF="#expiresactive" - >ExpiresActive</A> - </LI> - <LI><A - HREF="#expiresbytype" - >ExpiresByType</A> - </LI> - <LI><A - HREF="#expiresdefault" - >ExpiresDefault</A> - </LI> - </MENU> - <HR> - <H2><A NAME="expiresactive"> - ExpiresActive directive - </A></H2> - <!--%plaintext <?INDEX {\tt ExpiresActive} directive> --> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> ExpiresActive <EM>boolean</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> Indexes - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Extension - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_expires - </P> - <P> - This directive enables or disables the generation of the - <CODE>Expires</CODE> header for the document realm in question. (That - is, if found in an <CODE>.htaccess</CODE> file, for instance, it - applies only to documents generated from that directory.) If set to - <EM><CODE>Off</CODE></EM>, no <CODE>Expires</CODE> header will be - generated for any document in the realm (unless overridden at a lower - level, such as an <CODE>.htaccess</CODE> file overriding a server - config file). If set to <EM><CODE>On</CODE></EM>, the header will be - added to served documents according to the criteria defined by the - <A - HREF="#expiresbytype" - >ExpiresByType</A> - and - <A - HREF="#expiresdefault" - >ExpiresDefault</A> - directives (<EM>q.v.</EM>). - </P> - <P> - Note that this directive does not guarantee that an - <CODE>Expires</CODE> header will be generated. If the criteria aren't - met, no header will be sent, and the effect will be as though this - directive wasn't even specified. - </P> - <HR> - <H2><A NAME="expiresbytype"> - ExpiresByType directive - </A></H2> - <!--%plaintext <?INDEX {\tt ExpiresByType} directive> --> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> ExpiresByType <EM>MIME-type - <code>seconds</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> Indexes - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Extension - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> 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> - <P> - You can also specify the expiration time calculation using an - <A - HREF="#AltSyn" - >alternate syntax</A>, - described later in this document. - </P> - <HR> - <H2><A NAME="expiresdefault"> - ExpiresDefault directive - </A></H2> - <!--%plaintext <?INDEX {\tt ExpiresDefault} directive> --> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> ExpiresDefault <EM><code>seconds</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> Indexes - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Extension - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> 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, and the - <A - HREF="#AltSyn" - >alternate syntax</A> - description as well. - </P> - <HR> - <H2> - <A NAME="AltSyn">Alternate Interval Syntax</A> - </H2> - <P> - The - <A - HREF="#expiresdefault" - ><SAMP>ExpiresDefault</SAMP></A> - and - <A - HREF="#expiresbytype" - ><SAMP>ExpiresByType</SAMP></A> - directives can also be defined in a more readable syntax of the form: - </P> - <DL> - <DD><CODE>ExpiresDefault "<base> [plus] {<num> <type>}*" - <BR> - ExpiresByType type/encoding "<base> [plus] - {<num> <type>}*"</CODE> - </DD> - </DL> - <P> - where <base> is one of: - </P> - <MENU> - <LI><SAMP>access</SAMP> - </LI> - <LI><SAMP>now</SAMP> (equivalent to '<SAMP>access</SAMP>') - </LI> - <LI><SAMP>modification</SAMP> - </LI> - </MENU> - <P> - The '<SAMP>plus</SAMP>' keyword is optional. <num> should be an - integer value [acceptable to <SAMP>atoi()</SAMP>], and <type> - is one of: - </P> - <MENU> - <LI><SAMP>years</SAMP> - </LI> - <LI><SAMP>months</SAMP> - </LI> - <LI><SAMP>weeks</SAMP> - </LI> - <LI><SAMP>days</SAMP> - </LI> - <LI><SAMP>hours</SAMP> - </LI> - <LI><SAMP>minutes</SAMP> - </LI> - <LI><SAMP>seconds</SAMP> - </LI> - </MENU> - <P> - For example, any of the following directives can be used to make - documents expire 1 month after being accessed, by default: - </P> - <DL> - <DD><CODE>ExpiresDefault "access plus 1 month" - <BR> - ExpiresDefault "access plus 4 weeks" - <BR> - ExpiresDefault "access plus 30 days"</CODE> - </DD> - </DL> - <P> - The expiry time can be fine-tuned by adding several '<num> - <type>' clauses: - </P> - <DL> - <DD><CODE>ExpiresByType text/html "access plus 1 month 15 days 2 hours" - <BR> - ExpiresByType image/gif "modification plus 5 hours 3 minutes"</CODE> - </DD> - </DL> - <P> - Note that if you use a modification date based setting, the Expires - header will <STRONG>not</STRONG> be added to content that does - not come from a file on disk. This is due to the fact that there is - no modification time for such content. - - <!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/mod_headers.html b/docs/manual/mod/mod_headers.html deleted file mode 100644 index 3d6e4f656e..0000000000 --- a/docs/manual/mod/mod_headers.html +++ /dev/null @@ -1,121 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_headers</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_headers</H1> - -The optional headers module allows for the customization of HTTP -response headers. Headers can be merged, replaced or removed. The -directives described in this document are only available if Apache is -compiled with <STRONG>mod_headers.c</STRONG>. - -<HR> - -<H2>Directive</H2> -<UL> -<LI><A HREF="#header">Header</A> -</UL> - -<HR> - -<H2><A NAME="header">Header</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Header [ set | append | add ] - <EM>header</EM> <EM>value</EM><BR> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Header unset <EM>header</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, access.conf, - .htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> optional<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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><STRONG>set</STRONG><BR> - The response header is set, replacing any previous header with this name - -<LI><STRONG>append</STRONG><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><STRONG>add</STRONG><BR> - The response header is added to the existing set of headers, even if - this header already exists. This can result in two (or more) headers - having the same name. This can lead to unforeseen consequences, and in - general "append" should be used instead. - -<LI><STRONG>unset</STRONG><BR> - The response header of this name is removed, if it exists. If there are - multiple headers of the same name, all will be removed. -</UL> - -This argument is followed by a header name, which can include the -final colon, but it is not required. Case is ignored. For -add, append and set a value is given as the third argument. If this -value contains spaces, it should be surrounded by double quotes. -For unset, no value should be given. - -<H3>Order of Processing</H3> - -The Header directive can occur almost anywhere within the server -configuration. It is valid in the main server config and virtual host -sections, inside <Directory>, <Location> and <Files> -sections, and within .htaccess files. -<P> -The Header directives are processed in the following order: -<OL> -<LI>main server -<LI>virtual host -<LI><Directory> sections and .htaccess -<LI><Location> -<LI><Files> -</OL> - -Order is important. These two headers have a different effect if reversed: -<PRE> -Header append Author "John P. Doe" -Header unset Author -</PRE> - -This way round, the Author header is not set. If reversed, the Author -header is set to "John P. Doe". -<P> - -The Header directives are processed just before the response is sent -by its handler. These means that some headers that are added just -before the response is sent cannot be unset or overridden. This -includes headers such as "Date" and "Server". -<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_imap.html b/docs/manual/mod/mod_imap.html deleted file mode 100644 index c01de8206d..0000000000 --- a/docs/manual/mod/mod_imap.html +++ /dev/null @@ -1,329 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_imap</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_imap</H1> - -This module is contained in the <CODE>mod_imap.c</CODE> file, and is -compiled in by default. It provides for <CODE>.map</CODE> files, -replacing the functionality of the <CODE>imagemap</CODE> CGI -program. Any directory or document type configured to use the handler -<CODE>imap-file</CODE> (using either <CODE><A -HREF="mod_mime.html#addhandler">AddHandler</A> </CODE> or <CODE><A -HREF="mod_mime.html#sethandler">SetHandler</A></CODE>) will be -processed by this module. - -<H2>Summary</H2> - -This module is in the default Apache distribution. The following directive will -activate files ending with <CODE>.map</CODE> as imagemap files: - -<BLOCKQUOTE><CODE>AddHandler imap-file map</CODE></BLOCKQUOTE> - -Note that the following is still supported: - - <BLOCKQUOTE><CODE>AddType application/x-httpd-imap map</CODE></BLOCKQUOTE> - -However, we are trying to phase out "magic MIME types" so we are deprecating -this method. - -<H2>New Features</H2> -The imagemap module adds some new features that were not -possible with previously distributed imagemap programs.<P> - -<UL> -<LI>URL references relative to the Referer: information. -<LI>Default <BASE> assignment through a new map directive -<CODE>base</CODE>. -<LI>No need for <CODE>imagemap.conf</CODE> file. -<LI>Point references. -<LI>Configurable generation of imagemap menus. -</UL> -<P> - -<H2>Configuration Directives</H2> -<UL> -<LI><A HREF="#imapmenu">ImapMenu</A> -<LI><A HREF="#imapdefault">ImapDefault</A> -<LI><A HREF="#imapbase">ImapBase</A> -</UL> - - -<P> - -<H3><A NAME="imapmenu">ImapMenu</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ImapMenu <CODE>{none, formatted, semiformatted, - unformatted}</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_imap.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ImapMenu is only available in Apache -1.1 and later.<P> - -The ImapMenu directive determines the action taken if an imagemap file -is called without valid coordinates. -<DL> - <DT><CODE>none</CODE> - <DD>If ImapMenu is - <CODE>none</CODE>, no menu is generated, and the <CODE>default</CODE> - action is performed. - <DT><CODE>formatted</CODE> - <DD>A <CODE>formatted</CODE> menu is the simplest menu. Comments - in the imagemap file are ignored. A level one header is - printed, then an hrule, then the links each on a separate line. - The menu has a consistent, plain look close to that of - a directory listing. - <DT><CODE>semiformatted</CODE> - <DD>In the <CODE>semiformatted</CODE> menu, comments are printed - where they occur in the imagemap file. Blank lines are turned - into HTML breaks. No header or hrule is printed, but otherwise - the menu is the same as a <CODE>formatted</CODE> menu. - <DT><CODE>unformatted</CODE> - <DD>Comments are printed, blank lines are ignored. Nothing is - printed that does not appear in the imagemap file. All breaks - and headers must be included as comments in the imagemap file. - This gives you the most flexibility over the appearance of your - menus, but requires you to treat your map files as HTML instead - of plaintext. -</DL> - -<P> - -<H3><A NAME="imapdefault">ImapDefault</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ImapDefault <CODE>{error, nocontent, - map, referer, URL}</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_imap.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ImapDefault is only available in Apache -1.1 and later.<P> - - -The ImapDefault directive sets the default <CODE>default</CODE> used in -the imagemap files. It's value is overridden by a <CODE>default</CODE> -directive within the imagemap file. If not present, the -<CODE>default</CODE> action is <CODE>nocontent</CODE>, which means -that a <CODE>204 No Content</CODE> is sent to the client. In this -case, the client should continue to display the original page. - -<P> - -<H3><A NAME="imapbase">ImapBase</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ImapBase <CODE>{map, referer, URL}</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_imap.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ImapBase is only available in Apache -1.1 and later.<P> - -The ImapBase directive sets the default <CODE>base</CODE> used in -the imagemap files. It's value is overridden by a <CODE>base</CODE> -directive within the imagemap file. If not present, the -<CODE>base</CODE> defaults to <CODE>http://servername/</CODE>. - -<HR> -<P> - -<H2>Imagemap File</H2> -The lines in the imagemap files can have one of several formats: -<BLOCKQUOTE> -<CODE>directive value [x,y ...]</CODE><BR> -<CODE>directive value "Menu text" [x,y ...]</CODE><BR> -<CODE>directive value x,y ... "Menu text"</CODE><BR> -</BLOCKQUOTE> -The directive is one of <CODE>base</CODE>, <CODE>default</CODE>, -<CODE>poly</CODE>, <CODE>circle</CODE>, <CODE>rect</CODE>, or -<CODE>point</CODE>. The value is an absolute or relative URL, or one -of the special values listed below. The coordinates are -<CODE>x,y</CODE> pairs separated by whitespace. The quoted text is -used as the text of the link if a imagemap menu is generated. Lines -beginning with '#' are comments. - -<H3>Imagemap File Directives</H3> -There are six directives allowed in the imagemap file. The directives -can come in any order, but are processed in the order they are found -in the imagemap file. -<DL> -<DT><CODE>base</CODE> Directive -<DD>Has the effect of <CODE><BASE HREF="value"></CODE>. The - non-absolute URLs of the map-file are taken relative to this value. - The <CODE>base</CODE> directive overrides ImapBase as set in a - .htaccess file or in the server configuration files. In the absence - of an ImapBase configuration directive, <CODE>base</CODE> defaults to - <CODE>http://server_name/</CODE>. <BR> - <CODE>base_uri</CODE> is synonymous with <CODE>base</CODE>. Note that - a trailing slash on the URL is significant. -<P> -<DT><CODE>default</CODE> Directive -<DD>The action taken if the coordinates given do not fit any of the - <CODE>poly</CODE>, <CODE>circle</CODE> or <CODE>rect</CODE> - directives, and there are no <CODE>point</CODE> directives. Defaults - to <CODE>nocontent</CODE> in the absence of an ImapDefault - configuration setting, causing a status code of <CODE>204 No - Content</CODE> to be returned. The client should keep the same - page displayed. -<P> -<DT><CODE>poly</CODE> Directive -<DD>Takes three to one-hundred points, and is obeyed if the user selected - coordinates fall within the polygon defined by these points. -<P> -<DT><CODE>circle</CODE> -<DD>Takes the center coordinates of a circle and a point on the circle. Is - obeyed if the user selected point is with the circle. -<P> -<DT><CODE>rect</CODE> Directive -<DD>Takes the coordinates of two opposing corners of a rectangle. Obeyed - if the point selected is within this rectangle. -<P> -<DT><CODE>point</CODE> Directive -<DD>Takes a single point. The point directive closest to the user - selected point is obeyed if no other directives are satisfied. - Note that <CODE>default</CODE> will not be followed if a - <CODE>point</CODE> directive is present and valid coordinates are - given. -</DL> - - - -<H3>Values</H3> -The values for each of the directives can any of the following: -<DL> - <DT>a URL - <DD>The URL can be relative or absolute URL. Relative URLs can - contain '..' syntax and will be resolved relative to the - <CODE>base</CODE> value. <BR> - <CODE>base</CODE> itself will not resolved according to the current - value. A statement <CODE>base mailto:</CODE> will work properly, though. -<P> - <DT><CODE>map</CODE> - <DD>Equivalent to the URL of the imagemap file itself. No - coordinates are sent with this, so a menu will be generated - unless ImapMenu is set to 'none'. -<P> - <DT><CODE>menu</CODE> - <DD>Synonymous with <CODE>map</CODE>. -<P> - <DT><CODE>referer</CODE> - <DD>Equivalent to the URL of the referring document. - Defaults to <CODE>http://servername/</CODE> if no Referer: - header was present. -<P> - <DT><CODE>nocontent</CODE> - <DD>Sends a status code of <CODE>204 No Content</CODE>, - telling the client to keep the same page displayed. Valid for - all but <CODE>base</CODE>. -<P> - <DT><CODE>error</CODE> - <DD>Fails with a <CODE>500 Server Error</CODE>. Valid for all but - <CODE>base</CODE>, but sort of silly for anything but - <CODE>default</CODE>. -</DL> - -<H3>Coordinates</H3> -<DL> - <DT><CODE>0,0 200,200</CODE> - <DD>A coordinate consists of an <TT>x</TT> and a <TT>y</TT> value - separated by a comma. The coordinates are separated from each other - by whitespace. To accommodate the way Lynx handles imagemaps, should a - user select the coordinate <CODE>0,0</CODE>, it is as if - no coordinate had been selected. -</DL> - -<H3>Quoted Text</H3> -<DL> - <DT><CODE>"Menu Text"</CODE> - <DD>After the value or after the coordinates, the line optionally may - contain text within double quotes. This string is used as the - text for the link if a menu is generated:<BR> - <CODE><a HREF="http://foo.com/">Menu text</a></CODE><BR> - If no quoted text is present, the name of the link will be used - as the text:<BR> - <CODE><a HREF="http://foo.com/">http://foo.com</a></CODE><BR> - It is impossible to escape double quotes within this text. -</DL> - -<HR> - -<H2>Example Mapfile</H2> -<BLOCKQUOTE><CODE> -#Comments are printed in a 'formatted' or 'semiformatted' menu. <BR> -#And can contain html tags. <hr> <BR> -base referer <BR> -poly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0 <BR> -rect .. 0,0 77,27 "the directory of the referer"<BR> -circle http://www.inetnebr.com/lincoln/feedback/ 195,0 305,27 <BR> -rect another_file "in same directory as referer" 306,0 419,27 <BR> -point http://www.zyzzyva.com/ 100,100 <BR> -point http://www.tripod.com/ 200,200 <BR> -rect mailto:nate@tripod.com 100,150 200,0 "Bugs?" <BR> -</CODE></BLOCKQUOTE> -<P> - -<H2>Referencing your mapfile</H2> -<BLOCKQUOTE><CODE> -<A HREF="/maps/imagemap1.map"> <BR> -<IMG ISMAP SRC="/images/imagemap1.gif"> <BR> -</A> -</CODE></BLOCKQUOTE><P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - - diff --git a/docs/manual/mod/mod_include.html b/docs/manual/mod/mod_include.html deleted file mode 100644 index ea18b80ece..0000000000 --- a/docs/manual/mod/mod_include.html +++ /dev/null @@ -1,420 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_include</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_include</H1> - -This module is contained in the <CODE>mod_include.c</CODE> file, and -is compiled in by default. It provides for server-parsed html -documents. Several directives beyond the original NCSA definition were -introduced in Apache 1.2 - these are flagged below with the phrase -"Apache 1.2 and above". Of particular significance are the new flow -control directives documented at the bottom. - -<H2>Enabling Server-Side Includes</H2> - -Any document with handler of "server-parsed" will be parsed by this -module, if the <CODE>Includes</CODE> option is set. If documents -containing server-side include directives are given the extension -.shtml, the following directives will make Apache parse them and -assign the resulting document the mime type of <CODE>text/html</CODE>: - -<PRE> -AddType text/html .shtml -AddHandler server-parsed .shtml -</PRE> - -The following directive must be given for the directories containing -the shtml files (typically in a <CODE><Directory></CODE> section, -but this directive is also valid .htaccess files if <CODE>AllowOverride -Options</CODE> is set): - -<PRE> -Options +Includes -</PRE> - -Alternatively the <A HREF="#xbithack"><CODE>XBitHack</CODE></A> -directive can be used to parse normal (<CODE>text/html</CODE>) files, -based on file permissions. <P> - -For backwards compatibility, documents with mime type -<CODE>text/x-server-parsed-html</CODE> or -<CODE>text/x-server-parsed-html3</CODE> will also be parsed -(and the resulting output given the mime type <CODE>text/html</CODE>). - -<H2>Basic Elements</H2> - -The document is parsed as an HTML document, with special commands embedded -as SGML comments. A command has the syntax: - -<BLOCKQUOTE><CODE> -<!--#</CODE><EM>element attribute=value attribute=value ...</EM> -<CODE> --> -</CODE></BLOCKQUOTE> - -The value will often be enclosed in double quotes; many commands only allow -a single attribute-value pair. Note that the comment terminator -(<SAMP>--></SAMP>) should be preceded by whitespace to ensure that it -isn't considered part of an SSI token. -<P> -The allowed elements are:<P> - -<DL> - -<DT><STRONG>config</STRONG> -<DD> -This command controls various aspects of the parsing. The valid attributes -are: -<DL> -<DT>errmsg -<DD>The value is a message that is sent back to the client if an error occurs -whilst parsing the document. -<DT>sizefmt -<DD>The value sets the format to be used which displaying the size of a file. -Valid values are <CODE>bytes</CODE> for a count in bytes, or -<CODE>abbrev</CODE> for a count in Kb or Mb as appropriate. -<DT>timefmt -<DD>The value is a string to be used by the <CODE>strftime(3)</CODE> library -routine when printing dates. -</DL> - -<DT><STRONG>echo</STRONG> -<DD> -This command prints one of the include variables, defined below. -If the variable is unset, it is printed as <CODE>(none)</CODE>. -Any dates printed are subject to the currently configured <CODE>timefmt</CODE>. -Attributes: -<DL> -<DT>var -<DD>The value is the name of the variable to print. -</DL> - -<DT><STRONG>exec</STRONG> -<DD> -The exec command executes a given shell command or CGI script. -The IncludesNOEXEC <A HREF="core.html#options">Option</A> disables this command -completely. The valid attributes are: -<DL> -<DT>cgi -<DD> -The value specifies a (%-encoded) URL relative path to the CGI script. -If the path does not begin with a (/), then it is taken to be relative to -the current document. The document referenced by this path is invoked -as a CGI script, even if the server would not normally recognize it as -such. However, the directory containing the script must be enabled for -CGI scripts (with <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> -or the ExecCGI <A HREF="core.html#options">Option</A>).<P> -The CGI script is given the PATH_INFO and query string (QUERY_STRING) of the -original request from the client; these cannot be specified in the URL path. -The include variables will be available to the script in addition to the -standard <A HREF="mod_cgi.html">CGI</A> environment.<P> -If the script returns a Location: header instead of output, then this -will be translated into an HTML anchor.<P> -The <CODE>include virtual</CODE> element should be used in preference to -<CODE>exec cgi</CODE>. -<DT>cmd -<DD>The server will execute the given string using <CODE>/bin/sh</CODE>. -The include variables are available to the command. -</DL> - -<DT><STRONG>fsize</STRONG> -<DD> -This command prints the size of the specified file, subject to the -<CODE>sizefmt</CODE> format specification. Attributes: -<DL> -<DT>file -<DD>The value is a path relative to the directory containing the current -document being parsed. -<DT>virtual -<DD>The value is a (%-encoded) URL-path relative to the current document being -parsed. If it does not begin with a slash (/) then it is taken to be relative -to the current document. -</DL> - -<DT><STRONG>flastmod</STRONG> -<DD> -This command prints the last modification date of the specified file, -subject to the <CODE>timefmt</CODE> format specification. The attributes are -the same as for the <CODE>fsize</CODE> command. - -<DT><STRONG>include</STRONG> -<DD> -This command inserts the text of another document or file into the parsed -file. Any included file is subject to the usual access control. If the -directory containing the parsed file has the -<A HREF="core.html#options">Option</A> -IncludesNOEXEC set, and the including the document would cause a program -to be executed, then it will not be included; this prevents the execution of -CGI scripts. Otherwise CGI scripts are invoked as normal using the complete -URL given in the command, including any query string. -<!--%plaintext <?INDEX CGI scripts, {\tt include} element and> --> -<P> - -An attribute defines the location of the document; the inclusion is done for -each attribute given to the include command. The valid attributes are: -<DL> -<DT>file -<DD>The value is a path relative to the directory containing the current -document being parsed. It cannot contain <CODE>../</CODE>, nor can it be an -absolute path. The <CODE>virtual</CODE> attribute should always be used -in preference to this one. -<DT>virtual -<DD>The value is a (%-encoded) URL relative to the current document being -parsed. The URL cannot contain a scheme or hostname, only a path and -an optional query string. If it does not begin with a slash (/) then it -is taken to be relative to the current document. -</DL> -A URL is constructed from the attribute, and the output the server -would return if the URL were accessed by the client is included in the parsed -output. Thus included files can be nested. - -<DT><STRONG>printenv</STRONG> -<DD>This prints out a listing of all existing variables and their values. - No attributes. -<DD>For example: <CODE><!--#printenv --></CODE> -<DD>Apache 1.2 and above. - -<DT><STRONG>set</STRONG> -<DD>This sets the value of a variable. Attributes: -<DL> -<DT>var -<DD>The name of the variable to set. -<DT>value -<DD>The value to give a variable. -</DL> -For example: - <CODE><!--#set var="category" value="help" --></CODE> -<DD>Apache 1.2 and above. - -</DL> - -<H2>Include Variables</H2> - -In addition to the variables in the standard CGI environment, these are -available for the <CODE>echo</CODE> command, for <CODE>if</CODE> and -<CODE>elif</CODE>, and to any program invoked by the document. - -<DL> -<DT>DATE_GMT -<DD>The current date in Greenwich Mean Time. -<DT>DATE_LOCAL -<DD>The current date in the local time zone. -<DT>DOCUMENT_NAME -<DD>The filename (excluding directories) of the document requested by the -user. -<DT>DOCUMENT_URI -<DD>The (%-decoded) URL path of the document requested by the user. Note that -in the case of nested include files, this is <EM>not</EM> then URL for the -current document. -<DT>LAST_MODIFIED -<DD>The last modification date of the document requested by the user. -</DL> -<P> - -<H2>Variable Substitution</H2> -<P> Variable substitution is done within quoted strings in most cases - where they may reasonably occur as an argument to an SSI directive. - This includes the - <SAMP>config</SAMP>, - <SAMP>exec</SAMP>, - <SAMP>flastmod</SAMP>, - <SAMP>fsize</SAMP>, - <SAMP>include</SAMP>, and - <SAMP>set</SAMP> - directives, as well as the arguments to conditional operators. - You can insert a literal dollar sign into the string using backslash - quoting: - -<PRE> - <!--#if expr="$a = \$test" --> -</PRE> - -<P> If a variable reference needs to be substituted in the middle of a - character sequence that might otherwise be considered a valid - identifier in its own right, it can be disambiguated by enclosing - the reference in braces, <EM>à la</EM> shell substitution: - -<PRE> - <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --> -</PRE> - -<P> This will result in the <SAMP>Zed</SAMP> variable being set to - "<SAMP>X_Y</SAMP>" if <SAMP>REMOTE_HOST</SAMP> is - "<SAMP>X</SAMP>" and <SAMP>REQUEST_METHOD</SAMP> is - "<SAMP>Y</SAMP>". - -<P> EXAMPLE: the below example will print "in foo" if the DOCUMENT_URI is -/foo/file.html, "in bar" if it is /bar/file.html and "in neither" -otherwise: -<PRE> - <!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" --> - in foo - <!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" --> - in bar - <!--#else --> - in neither - <!--#endif --> -</PRE> - -<H2><A NAME="flowctrl">Flow Control Elements</A></H2> - -These are available in Apache 1.2 and above. The basic flow control -elements are: - -<PRE> - <!--#if expr="<EM>test_condition</EM>" --> - <!--#elif expr="<EM>test_condition</EM>" --> - <!--#else --> - <!--#endif --> -</PRE> - -<P> The <STRONG><CODE>if</CODE></STRONG> element works like an - if statement in a programming language. The test condition - is evaluated and if the result is true, then the text until - the next <STRONG><CODE>elif</CODE></STRONG>, <STRONG><CODE>else</CODE></STRONG>. - or <STRONG><CODE>endif</CODE></STRONG> element is included in the - output stream. - -<P> The <STRONG><CODE>elif</CODE></STRONG> or <STRONG><CODE>else</CODE></STRONG> - statements are be used the put text into the output stream - if the original test_condition was false. These elements - are optional. - -<P> The <STRONG><CODE>endif</CODE></STRONG> element ends the - <STRONG><CODE>if</CODE></STRONG> element and is required. - -<P> <EM>test_condition</EM> is one of the following: - -<DL> - -<DT><EM>string</EM><DD>true if <EM>string</EM> is not empty - -<DT><EM>string1</EM> = <EM>string2</EM> - <BR> - <EM>string1</EM> != <EM>string2</EM> - <BR> - <EM>string1</EM> < <EM>string2</EM> - <BR> - <EM>string1</EM> <= <EM>string2</EM> - <BR> - <EM>string1</EM> > <EM>string2</EM> - <BR> - <EM>string1</EM> >= <EM>string2</EM> - -<DD>Compare string1 with string 2. If string2 has the form <EM>/string/</EM> - then it is compared as a regular expression. - Regular expressions have the same syntax as those found in the - Unix <SAMP>egrep</SAMP> command. - -<DT>( <EM>test_condition</EM> ) - <DD>true if <EM>test_condition</EM> is true -<DT>! <EM>test_condition</EM> - <DD>true if <EM>test_condition</EM> is false -<DT><EM>test_condition1</EM> && <EM>test_condition2</EM> - <DD>true if both <EM>test_condition1</EM> and - <EM>test_condition2</EM> are true -<DT><EM>test_condition1</EM> || <EM>test_condition2</EM> - <DD>true if either <EM>test_condition1</EM> or - <EM>test_condition2</EM> is true -</DL> - -<P> "<EM>=</EM>" and "<EM>!=</EM>" bind more tightly than "<EM>&&</EM>" and - "<EM>||</EM>". - "<EM>!</EM>" binds most tightly. Thus, the following are equivalent: - -<PRE> - <!--#if expr="$a = test1 && $b = test2" --> - <!--#if expr="($a = test1) && ($b = test2)" --> -</PRE> - -<P> Anything that's not recognized as a variable or an operator is - treated as a string. Strings can also be quoted: <EM>'string'</EM>. - Unquoted strings can't contain whitespace (blanks and tabs) - because it is used to separate tokens such as variables. If - multiple strings are found in a row, they are concatenated using - blanks. So, - -<PRE> - <EM>string1 string2</EM> results in <EM>string1 string2</EM> - <EM>'string1 string2'</EM> results in <EM>string1 string2</EM> -</PRE> - -<HR> -<H2>Directives</H2> -<UL> -<LI><A HREF="#xbithack">XBitHack</A> -</UL> -<HR> - - -<H2><A NAME="xbithack">XBitHack</A></H2> -<!--%plaintext <?INDEX {\tt XBitHack} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> XBitHack <EM>status</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>XBitHack off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Options<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_include<P> - -The XBitHack directives controls the parsing of ordinary html documents. -This directive only affects files associated with the MIME type -<CODE>text/html</CODE>. -<EM>Status</EM> can have the following values: -<DL> -<DT>off -<DD>No special treatment of executable files. -<DT>on -<DD>Any file that has the user-execute bit set will be treated as a -server-parsed html document. -<DT>full -<DD>As for <CODE>on</CODE> but also test the group-execute bit. If it -is set, then set the Last-modified date of the returned file to be the -last modified time of the file. If it is not set, then no last-modified date -is sent. Setting this bit allows clients and proxies to cache the result of -the request. -<P><STRONG>Note:</STRONG> you would not want to use this, for example, when you -<CODE>#include</CODE> a CGI that produces different output on each hit -(or potentially depends on the hit). -</DL> -<P> - -<HR> -<H2>Using Server Side Includes for ErrorDocuments</H2> - -There is <A HREF="../misc/custom_errordocs.html">a document</A> which -describes how to use the features of mod_include to offer internationalized -customized server error documents. -<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_info.html b/docs/manual/mod/mod_info.html deleted file mode 100644 index 8afa84dc41..0000000000 --- a/docs/manual/mod/mod_info.html +++ /dev/null @@ -1,113 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_info</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_info</H1> - -This module is contained in the <CODE>mod_info.c</CODE> file. It -provides a comprehensive overview of the server configuration -including all installed modules and directives in the configuration -files. This module is not compiled into the -server by default. It is only available in Apache 1.1 and later. To -enable it, add the following line to the server build Configuration -file, and rebuild the server: - -<PRE> -AddModule modules/standard/mod_info.o -</PRE> - -<H2>Directives</H2> -<UL> -<LI><A HREF="#addmoduleinfo">AddModuleInfo</A> -</UL> - -<HR> -<P> -To configure it, add the following to your <CODE>access.conf</CODE> file. - -<PRE> -<Location /server-info> -SetHandler server-info -</Location> -</PRE> - -You may wish to add a -<A - HREF="core.html#limit" -><Limit></A> -clause inside the -<A - HREF="core.html#location" ->location</A> -directive to limit access to your server configuration information.<P> -Once configured, the server information is obtained by accessing -<TT>http://your.host.dom/server-info</TT><P> -<BLOCKQUOTE> - <STRONG> - Note that the configuration files are read by the module at run-time, - and therefore the display may <EM>not</EM> reflect the running - server's active configuration if the files have been changed since the - server was last reloaded. Also, the configuration files must be - readable by the user as which the server is running (see the - <A - HREF="core.html#user" - ><SAMP>User</SAMP></A> - directive), or else the directive settings will not be listed. - <P> - It should also be noted that if <SAMP>mod_info</SAMP> is compiled into - the server, its handler capability is available in <EM>all</EM> - configuration files, including <EM>per</EM>-directory files - (<EM>e.g.</EM>, <SAMP>.htaccess</SAMP>). This may have - security-related ramifications for your site. - </P> - </STRONG> -</BLOCKQUOTE> - -<HR> - -<H2><A NAME="addmoduleinfo">AddModuleInfo</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddModuleInfo <EM>module-name string</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_browser<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.3 and above<P> - -This allows the content of <EM>string</EM> to be shown as -HTML interpreted, -<STRONG>Additional Information</STRONG> for the module <EM>module-name</EM>. -Example: -<BLOCKQUOTE> -<PRE> -AddModuleInfo mod_auth.c 'See <A HREF="http://www.apache.org/docs/mod/mod_auth.html">http://www.apache.org/docs/mod/mod_auth.html</A>' -</PRE> -</BLOCKQUOTE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_isapi.html b/docs/manual/mod/mod_isapi.html deleted file mode 100644 index 61c9ba6728..0000000000 --- a/docs/manual/mod/mod_isapi.html +++ /dev/null @@ -1,73 +0,0 @@ -<!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 (<EM>i.e.</EM>, 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 asynchronous 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> diff --git a/docs/manual/mod/mod_log_agent.html b/docs/manual/mod/mod_log_agent.html deleted file mode 100644 index 2084889074..0000000000 --- a/docs/manual/mod/mod_log_agent.html +++ /dev/null @@ -1,77 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Module mod_log_agent</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_log_agent</H1> - -This module is contained in the <CODE>mod_log_agent.c</CODE> file, and is not -compiled in by default. It provides for logging of the client user agents. -mod_log_agent is deprecated. Use <A HREF="mod_log_config.html">mod_log_config</A> -instead. - -<UL> -<LI><A HREF="#agentlog">AgentLog</A> -</UL> -<HR> - - -<H2><A NAME="agentlog">AgentLog</A></H2> -<!--%plaintext <?INDEX {\tt AgentLog} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AgentLog <EM>file-pipe</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AgentLog logs/agent_log</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_log_agent<P> - -The AgentLog directive sets the name of the file to which the server will -log the UserAgent header of incoming requests. <EM>File-pipe</EM> is one -of -<DL><DT>A filename -<DD>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>. -<DT> `|' followed by a command -<DD>A program to receive the agent log information on its standard input. -Note the a new program will not be started for a VirtualHost if it inherits -the AgentLog from the main server. -</DL> -<STRONG>Security:</STRONG> if a program is used, then it will be -run under the user who started httpd. This will be root if the server -was started by root; be sure that the program is secure.<P> - -<STRONG>Security:</STRONG> See the <A -HREF="../misc/security_tips.html">security tips</A> document for -details on why your security could be compromised if the directory -where logfiles are stored is writable by anyone other than the user -that starts the server.<P> - -This directive is provided for compatibility with NCSA 1.4.<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_log_config.html b/docs/manual/mod/mod_log_config.html deleted file mode 100644 index dfa21e3f27..0000000000 --- a/docs/manual/mod/mod_log_config.html +++ /dev/null @@ -1,450 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_log_config</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_log_config</H1> -<P> -This module is contained in the <CODE>mod_log_config.c</CODE> file, -and is compiled in by default in Apache 1.2. mod_log_config replaces -mod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was -an optional module. It provides for logging of the requests made to -the server, using the Common Log Format or a user-specified format. -</P> - -<H2>Summary</H2> -<P> -Three directives are provided by this module: <CODE>TransferLog</CODE> -to create a log file, <CODE>LogFormat</CODE> to set a custom format, -and <CODE>CustomLog</CODE> to define a log file and format in one go. -The <CODE>TransferLog</CODE> and <CODE>CustomLog</CODE> directives can -be used multiple times in each server to cause each request to be -logged to multiple files. -</P> - -<H3>Compatibility notes</H3> - -<UL> -<LI>This module is based on mod_log_config distributed with -previous Apache releases, now updated to handle multiple logs. -There is now no need to re-configure Apache to use configuration log -formats. - -<LI>The module also implements the <CODE>CookieLog</CODE> directive, -used to log user-tracking information created by <A -HREF="mod_usertrack.html">mod_usertrack</A>. The use of -<CODE>CookieLog</CODE> is deprecated, and a <CODE>CustomLog</CODE> -should be defined to log user-tracking information instead. - -<LI>As of Apache 1.3.5, this module allows conditional logging -based upon the setting of environment variables. That is, -you can control whether a request should be logged or not -based upon whether an arbitrary environment variable is -defined or not. This is settable on a <EM>per</EM>-logfile -basis. - -<LI>Beginning with Apache 1.3.5, the mod_log_config module has -also subsumed the <CODE>RefererIgnore</CODE> functionality from -<A HREF="mod_log_referer.html">mod_log_referer</A>. The effect -of <CODE>RefererIgnore</CODE> can be achieved by combinations of -<A HREF="mod_setenvif.html"><CODE>SetEnvIf</CODE></A> directives -and conditional <CODE>CustomLog</CODE> definitions. - -</UL> - -<H2>Log File Formats</H2> - -Unless told otherwise with <TT>LogFormat</TT> the log files created by -<TT>TransferLog</TT> will be in standard "Common Log Format" -(CLF). The contents of each line in a CLF file are explained -below. Alternatively, the log file can be customized (and if multiple -log files are used, each can have a different format). Custom formats -are set with <CODE>LogFormat</CODE> and <CODE>CustomLog</CODE>. - -<H3>Common Log Format</H3> - -The Common Log Format (CLF) file contains a separate line for each -request. A line is composed of several tokens separated by spaces: - -<BLOCKQUOTE> -host ident authuser date request status bytes -</BLOCKQUOTE> -If a token does not have a value then it is represented by a hyphen (-). -The meanings and values of these tokens are as follows: -<DL> -<DT>host -<DD>The fully-qualified domain name of the client, or its IP number if the -name is not available. -<DT>ident -<DD>If <A HREF="core.html#identitycheck">IdentityCheck</A> is enabled and the -client machine runs identd, then this is the identity information reported -by the client. -<DT>authuser -<DD>If the request was for an password protected document, then this is -the userid used in the request. -<DT>date -<DD>The date and time of the request, in the following format: -<DL><DD><BLOCKQUOTE><CODE> date = [day/month/year:hour:minute:second zone] <BR> -day = 2*digit<BR> -month = 3*letter<BR> -year = 4*digit<BR> -hour = 2*digit<BR> -minute = 2*digit<BR> -second = 2*digit<BR> -zone = (`+' | `-') 4*digit</CODE></BLOCKQUOTE></DL> -<DT>request -<DD>The request line from the client, enclosed in double quotes -(<CODE>"</CODE>). -<DT>status -<DD>The three digit status code returned to the client. -<DT>bytes -<DD>The number of bytes in the object returned to the client, not including -any headers. -</DL> - -<H3><A NAME="formats">Custom Log Formats</A></H3> - -The format argument to the <CODE>LogFormat</CODE> and -<CODE>CustomLog</CODE> is a string. This string is logged to the log -file for each request. It can contain literal characters copied into -the log files, and `%' directives which are replaced in the log file -by the values as follows: - -<PRE> -%...b: Bytes sent, excluding HTTP headers. -%...f: Filename -%...{FOOBAR}e: The contents of the environment variable FOOBAR -%...h: Remote host -%...a: Remote IP-address -%...A: Local IP-address -%...{Foobar}i: The contents of Foobar: header line(s) in the request - sent to the server. -%...l: Remote logname (from identd, if supplied) -%...{Foobar}n: The contents of note "Foobar" from another module. -%...{Foobar}o: The contents of Foobar: header line(s) in the reply. -%...p: The canonical Port of the server serving the request -%...P: The process ID of the child that serviced the request. -%...r: First line of request -%...s: Status. For requests that got internally redirected, this - is status of the *original* request --- %...>s for the last. -%...t: Time, in common log format time format (standard english format) -%...{format}t: The time, in the form given by format, which should - be in strftime(3) format. (potentially localised) -%...T: The time taken to serve the request, in seconds. -%...u: Remote user (from auth; may be bogus if return status (%s) is 401) -%...U: The URL path requested. -%...v: The canonical ServerName of the server serving the request. -%...V: The server name according to the UseCanonicalName setting. -</PRE> - -The `...' can be nothing at all (<EM>e.g.</EM>, <CODE>"%h %u %r %s %b"</CODE>), or it can -indicate conditions for inclusion of the item (which will cause it -to be replaced with `-' if the condition is not met). Note that -there is no escaping performed on the strings from %r, %...i and -%...o; some with long memories may remember that I thought this was -a bad idea, once upon a time, and I'm still not comfortable with -it, but it is difficult to see how to `do the right thing' with all -of `%..i', unless we URL-escape everything and break with CLF. - -<P> - -The forms of condition are a list of HTTP status codes, which may -or may not be preceded by `!'. Thus, `%400,501{User-agent}i' logs -User-agent: on 400 errors and 501 errors (Bad Request, Not -Implemented) only; `%!200,304,302{Referer}i' logs Referer: on all -requests which did <STRONG>not</STRONG> return some sort of normal status. - -<P> - -Note that the common log format is defined by the string <CODE>"%h %l -%u %t \"%r\" %s %b"</CODE>, which can be used as the basis for -extending for format if desired (<EM>e.g.</EM>, to add extra fields at the end). -NCSA's extended/combined log format would be <CODE>"%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\""</CODE>. - -<P> - -Note that the canonical <A HREF="core.html#servername">ServerName</A> -and <A HREF="core.html#port">Port</A> of the server serving the request -are used for <CODE>%v</CODE> and <CODE>%p</CODE> respectively. This -happens regardless of the -<A HREF="core.html#usecanonicalname">UseCanonicalName</A> setting because -otherwise log analysis programs would have to duplicate the entire -vhost matching algorithm in order to decide what host really served -the request. - -<H2>Using Multiple Log Files</H2> - -The <CODE>TransferLog</CODE> and <CODE>CustomLog</CODE> directives can -be given more than once to log requests to multiple log files. Each -request will be logged to all the log files defined by either of these -directives. - -<H3>Use with Virtual Hosts</H3> - -If a <VirtualHost> section does not contain any -<TT>TransferLog</TT> or <TT>CustomLog</TT> directives, the -logs defined for the main server will be used. If it does -contain one or more of these directives, requests serviced by -this virtual host will only be logged in the log files defined -within its definition, not in any of the main server's log files. -See the examples below. -<P> - -<H2>Security Considerations</H2> - -See the <A HREF="../misc/security_tips.html#security">security tips</A> -document for details on why your security could be compromised if the -directory where logfiles are stored is writable by anyone other than -the user that starts the server. -<P> -<H2>Directives</H2> - -<UL> -<LI><A HREF="#cookielog">CookieLog</A> -<LI><A HREF="#customlog">CustomLog</A> -<LI><A HREF="#customlog-conditional">CustomLog (conditional)</A> -<LI><A HREF="#logformat">LogFormat</A> -<LI><A HREF="#transferlog">TransferLog</A> -</UL> -<HR> - - -<H2><A NAME="cookielog">CookieLog</A></H2> -<!--%plaintext <?INDEX {\tt CookieLog} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CookieLog <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_cookies<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Only available in Apache 1.2 and above<P> - -The CookieLog directive sets the filename for logging of cookies. -The filename is relative to the <A -HREF="core.html#serverroot">ServerRoot</A>. This directive is included -only for compatibility with -<A HREF="mod_cookies.html">mod_cookies</A>, and is deprecated. -<P> - -<HR> -<H2><A NAME="customlog">CustomLog</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CustomLog <EM>file-pipe</EM> - <EM>format-or-nickname</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Nickname only available in Apache 1.3 - or later -<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_log_config -<P> -The first argument is the filename to which log records should be -written. This is used -exactly like the argument to -<A - HREF="#transferlog" -><SAMP>TransferLog</SAMP></A>; -that is, it is either a full path or relative to the current -server root. -</P> -<P> -The format argument specifies a format for each line of the log file. -The options available for the format are exactly the same as for -the argument of the <TT>LogFormat</TT> directive. If the format -includes any spaces (which it will do in almost all cases) it -should be enclosed in double quotes. -</P> -<P> -Instead of an actual format string, you can use a format nickname defined with -the -<A - HREF="#logformat" -><SAMP>LogFormat</SAMP></A> -directive. -</P> - -<HR> -<H2><A NAME="customlog-conditional">CustomLog (conditional)</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CustomLog <EM>file-pipe</EM> - <EM>format-or-nickname</EM> - env=[!]<EM>environment-variable</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Only available in Apache 1.3.5 - or later -<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_log_config -<P> - -The behaviour of this form of the <SAMP>CustomLog</SAMP> directive is almost -identical to the <A HREF="#customlog">standard <CODE>CustomLog</CODE></A> -directive. The difference is that the '<CODE>env=</CODE>' clause controls -whether a particular request will be logged in the specified file or -not. If the specified environment variable is set for the -request (or is not set, in the case of a '<CODE>env=!<EM>name</EM></CODE>' -clause), then the request will be logged. -</P> -<P> -Environment variables can be set on a <EM>per</EM>-request basis -using the <A HREF="mod_setenvif.html">mod_setenvif</A> and/or -<A HREF="mod_rewrite.html">mod_rewrite</A> modules. For example, -if you don't want to record requests for all GIF images on -your server in a separate logfile but not your main log, you -can use: -</P> -<PRE> - SetEnvIf Request_URI \.gif$ gif-image - CustomLog gif-requests.log common env=gif-image - CustomLog nongif-requests.log common env=!gif-image -</PRE> - -<HR> -<H2><A NAME="logformat">LogFormat</A></H2> -<!--%plaintext <?INDEX {\tt LogFormat} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LogFormat <EM>format</EM> [<EM>nickname</EM>] -<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>LogFormat "%h %l %u %t \"%r\" -%s %b"</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Nickname only available in Apache 1.3 - or later -<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_log_config -<P> -This sets the format of the default logfile named by the -<A - HREF="#transferlog" -><SAMP>TransferLog</SAMP></A> -directive . See the section on -<A HREF="#formats">Custom Log Formats</A> for details on the format -arguments. -</P> -<P> -If you include a nickname for the format on the directive line, you can -use it in other <SAMP>LogFormat</SAMP> and -<A HREF="#customlog"><SAMP>CustomLog</SAMP></A> -directives rather than repeating the entire format string. -</P> -<P> -A -<SAMP>LogFormat</SAMP> directive which defines a nickname <STRONG>does -nothing else</STRONG> -- that is, it <EM>only</EM> defines the nickname, -it doesn't actually apply the format and make it the default. -</P> - -<HR> - -<H2><A NAME="transferlog">TransferLog</A></H2> -<!--%plaintext <?INDEX {\tt TransferLog} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> TransferLog <EM>file-pipe</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> none<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_log_config<P> - -The TransferLog directive adds a log file in the format defined by the -most recent -<A - HREF="#logformat" -><SAMP>LogFormat</SAMP></A> -directive, or Common Log Format if no other default format has been -specified. -<EM>File-pipe</EM> is one -of -<DL><DT>A filename -<DD>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>. -<DT> `|' followed by a command -<DD>A program to receive the agent log information on its standard input. -Note the a new program will not be started for a VirtualHost if it inherits -the TransferLog from the main server. -</DL> -<STRONG>Security:</STRONG> if a program is used, then it will be -run under the user who started httpd. This will be root if the server -was started by root; be sure that the program is secure.<P> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_log_referer.html b/docs/manual/mod/mod_log_referer.html deleted file mode 100644 index 017aecd801..0000000000 --- a/docs/manual/mod/mod_log_referer.html +++ /dev/null @@ -1,117 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_log_referer</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_log_referer</H1> - -This module is contained in the <CODE>mod_log_referer.c</CODE> file, and is not -compiled in by default. It provides for logging of the documents which -reference documents on the server. As of Apache 1.3.5 it is deprecated. -Use <A HREF="mod_log_config.html#customlog-conditional">CustomLog -(conditional)</A> instead. - -<H2>Log file format</H2> -The log file contains a separate line for each refer. Each line has the -format -<BLOCKQUOTE><EM>uri</EM> <CODE>-></CODE> <EM>document</EM></BLOCKQUOTE> -where <EM>uri</EM> is the (%-escaped) URI for the document that references -the one requested by the client, and <EM>document</EM> is the (%-decoded) -local URL to the document being referred to. - - -<H2>Directives</H2> -<UL> -<LI><A HREF="#refererignore">RefererIgnore</A> -<LI><A HREF="#refererlog">RefererLog</A> -</UL> -<HR> - - -<H2><A NAME="refererignore">RefererIgnore</A></H2> -<!--%plaintext <?INDEX {\tt RefererIgnore} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RefererIgnore <EM>string string ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_log_referer<P> - -The RefererIgnore directive adds to the list of strings to ignore in -Referer headers. If any of the strings in the list is contained in -the Referer header, then no referrer information will be logged for the -request. Example: -<BLOCKQUOTE><CODE>RefererIgnore www.ncsa.uiuc.edu</CODE></BLOCKQUOTE> -This avoids logging references from www.ncsa.uiuc.edu. -<P><HR> - - -<H2><A NAME="refererlog">RefererLog</A></H2> -<!--%plaintext <?INDEX {\tt RefererLog} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RefererLog <EM>file-pipe</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>RefererLog logs/referer_log</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_log_referer<P> - -The RefererLog directive sets the name of the file to which the server will -log the Referer header of incoming requests. <EM>File-pipe</EM> is one -of -<DL><DT>A filename -<DD>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>. -<DT> `|' followed by a command -<DD>A program to receive the referrer log information on its standard input. -Note the a new program will not be started for a VirtualHost if it inherits -the RefererLog from the main server. -</DL> -<STRONG>Security:</STRONG> if a program is used, then it will be -run under the user who started httpd. This will be root if the server -was started by root; be sure that the program is secure.<P> - -<STRONG>Security:</STRONG> See the <A -HREF="../misc/security_tips.html">security tips</A> document for -details on why your security could be compromised if the directory -where logfiles are stored is writable by anyone other than the user -that starts the server.<P> - -This directive is provided for compatibility with NCSA 1.4.<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_mime.html b/docs/manual/mod/mod_mime.html deleted file mode 100644 index c222cab89b..0000000000 --- a/docs/manual/mod/mod_mime.html +++ /dev/null @@ -1,538 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_mime</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_mime</H1> - -This module is contained in the <CODE>mod_mime.c</CODE> file, and is -compiled in by default. It provides for determining the types of files -from the filename. - -<H2>Summary</H2> - -This module is used to determine various bits of "meta information" -about documents. This information relates to the content of the -document and is returned to the browser or used in content-negotiation -within the server. In addition, a "handler" can be set for a document, -which determines how the document will be processed within the server. - -<P> - -The directives <A HREF="#addencoding">AddEncoding</A>, <A -HREF="#addhandler">AddHandler</A>, <A -HREF="#addlanguage">AddLanguage</A> and <A HREF="#addtype">AddType</A> -are all used to map file extensions onto the meta-information for that -file. Respectively they set the content-encoding, handler, -content-language and MIME-type (content-type) of documents. The -directive <A HREF="#typesconfig">TypesConfig</A> is used to specify a -file which also maps extensions onto MIME types. The directives <A -HREF="#forcetype">ForceType</A> and <A -HREF="#sethandler">SetHandler</A> are used to associated all the files -in a given location (<EM>e.g.</EM>, a particular directory) onto a particular -MIME type or handler. - -<P> - -Note that changing the type or encoding of a file does not change the -value of the <CODE>Last-Modified</CODE> header. Thus, previously cached -copies may still be used by a client or proxy, with the previous headers. - -<H2><A NAME="multipleext">Files with Multiple Extensions</A></H2> - -Files can have more than one extension, and the order of the -extensions is <EM>normally</EM> irrelevant. For example, if the file -<CODE>welcome.html.fr</CODE> maps onto content type text/html and -language French then the file <CODE>welcome.fr.html</CODE> will map -onto exactly the same information. The only exception to this is if an -extension is given which Apache does not know how to handle. In this -case it will "forget" about any information it obtained from -extensions to the left of the unknown extension. So, for example, if -the extensions fr and html are mapped to the appropriate language and -type but extension xxx is not assigned to anything, then the file -<CODE>welcome.fr.xxx.html</CODE> will be associated with content-type -text/html but <EM>no</EM> language. - -<P> - -If more than one extension is given which maps onto the same type of -meta-information, then the one to the right will be used. For example, -if ".gif" maps to the MIME-type image/gif and ".html" maps to the -MIME-type text/html, then the file <CODE>welcome.gif.html</CODE> will -be associated with the MIME-type "text/html". - -<P> - -Care should be taken when a file with multiple extensions gets -associated with both a MIME-type and a handler. This will usually -result in the request being by the module associated with the -handler. For example, if the <CODE>.imap</CODE> extension is mapped to -the handler "imap-file" (from mod_imap) and the <CODE>.html</CODE> -extension is mapped to the MIME-type "text/html", then the file -<CODE>world.imap.html</CODE> will be associated with both the -"imap-file" handler and "text/html" MIME-type. When it is processed, -the "imap-file" handler will be used, and so it will be treated as a -mod_imap imagemap file. - -<H2>Directives</H2> -<UL> -<LI><A HREF="#addencoding">AddEncoding</A> -<LI><A HREF="#addhandler">AddHandler</A> -<LI><A HREF="#addlanguage">AddLanguage</A> -<LI><A HREF="#addtype">AddType</A> -<LI><A HREF="#defaultlanguage">DefaultLanguage</A> -<LI><A HREF="#forcetype">ForceType</A> -<LI><A HREF="#removehandler">RemoveHandler</A> -<LI><A HREF="#sethandler">SetHandler</A> -<LI><A HREF="#typesconfig">TypesConfig</A> -</UL> -<HR> - - -<H2><A NAME="addencoding">AddEncoding</A></H2> -<!--%plaintext <?INDEX {\tt AddEncoding} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddEncoding <EM>MIME-enc extension extension...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<P> - -The AddEncoding directive maps the given filename extensions to the -specified encoding type. <EM>MIME-enc</EM> is the MIME encoding to use -for documents containing the <EM>extension</EM>. This mapping is added -to any already in force, overriding any mappings that already exist -for the same <EM>extension</EM>. - -Example: -<BLOCKQUOTE><CODE> AddEncoding x-gzip gz<BR> AddEncoding x-compress Z -</CODE></BLOCKQUOTE> - -This will cause filenames containing the .gz extension to be marked as -encoded using the x-gzip encoding, and filenames containing the .Z -extension to be marked as encoded with x-compress.<P> - -Old clients expect <CODE>x-gzip</CODE> and <CODE>x-compress</CODE>, -however the standard dictates that they're equivalent to <CODE>gzip</CODE> -and <CODE>compress</CODE> respectively. Apache does content encoding -comparisons by ignoring any leading <CODE>x-</CODE>. When responding -with an encoding Apache will use whatever form (<EM>i.e.</EM>, <CODE>x-foo</CODE> -or <CODE>foo</CODE>) the client requested. If the client didn't -specifically request a particular form Apache will use the form given by -the <CODE>AddEncoding</CODE> directive. To make this long story short, -you should always use <CODE>x-gzip</CODE> and <CODE>x-compress</CODE> -for these two specific encodings. More recent encodings, such as -<CODE>deflate</CODE> should be specified without the <CODE>x-</CODE>. - -<P> - -<STRONG>See also</STRONG>: <A HREF="#multipleext">Files with -multiple extensions</A> - -<P><HR> - -<H2><A NAME="addhandler">AddHandler</A></H2> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddHandler <EM>handler-name extension extension...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> AddHandler is only available in Apache -1.1 and later<P> - -<P>AddHandler maps the filename extensions <EM>extension</EM> to the -<A HREF="../handler.html">handler</A> <EM>handler-name</EM>. This -mapping is added to any already in force, overriding any mappings that -already exist for the same <EM>extension</EM>. - -For example, to activate CGI scripts -with the file extension "<CODE>.cgi</CODE>", you might use: -<PRE> - AddHandler cgi-script cgi -</PRE> - -<P>Once that has been put into your srm.conf or httpd.conf file, any -file containing the "<CODE>.cgi</CODE>" extension will be treated as a -CGI program.</P> - -<P> - -<STRONG>See also</STRONG>: <A HREF="#multipleext">Files with -multiple extensions</A> - -<HR> - -<H2><A NAME="addlanguage">AddLanguage</A></H2> -<!--%plaintext <?INDEX {\tt AddLanguage} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddLanguage <EM>MIME-lang extension extension...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime - -<P> -The AddLanguage directive maps the given filename extensions to the -specified content language. <EM>MIME-lang</EM> is the MIME language of -filenames containing <EM>extension</EM>. This mapping is added to any -already in force, overriding any mappings that already exist for the -same <EM>extension</EM>. -</P> -<P> -Example: <BLOCKQUOTE><CODE> -AddEncoding x-compress Z<BR> AddLanguage en .en<BR> AddLanguage fr -.fr<BR> </CODE></BLOCKQUOTE> -</P> -<P> -Then the document <CODE>xxxx.en.Z</CODE> will be treated as being a -compressed English document (as will the document -<CODE>xxxx.Z.en</CODE>). Although the content language is reported to -the client, the browser is unlikely to use this information. The -AddLanguage directive is more useful for -<A HREF="../content-negotiation.html">content negotiation</A>, where -the server returns one from several documents based on the client's -language preference. -</P> -<P> -If multiple language assignments are made for the same extension, -the last one encountered is the one that is used. That is, for the -case of: -</P> -<PRE> - AddLanguage en .en - AddLanguage en-uk .en - AddLanguage en-us .en -</PRE> -<P> -documents with the extension "<CODE>.en</CODE>" would be treated as -being "<CODE>en-us</CODE>". -</P> -<P> -<STRONG>See also</STRONG>: <A HREF="#multipleext">Files with -multiple extensions</A> -<BR> -<STRONG>See also</STRONG>: <A -HREF="./mod_negotiation.html">mod_negotiation</A> -</P> - -<HR> - -<H2><A NAME="addtype">AddType</A></H2> -<!--%plaintext <?INDEX {\tt AddType} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddType <EM>MIME-type extension extension...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<P> - -The AddType directive maps the given filename extensions onto the -specified content type. <EM>MIME-enc</EM> is the MIME type to use for -filenames containing <EM>extension</EM>. This mapping is added to any -already in force, overriding any mappings that already exist for the -same <EM>extension</EM>. This directive can be used to add mappings -not listed in the MIME types file (see the <CODE><A -HREF="#typesconfig">TypesConfig</A></CODE> directive). - -Example: -<BLOCKQUOTE><CODE> -AddType image/gif GIF -</CODE></BLOCKQUOTE> -It is recommended that new MIME types be added using the AddType directive -rather than changing the <A HREF="#typesconfig">TypesConfig</A> file.<P> -Note that, unlike the NCSA httpd, this directive cannot be used to set the -type of particular files.<P> - -<P> - -<STRONG>See also</STRONG>: <A HREF="#multipleext">Files with -multiple extensions</A> - -<HR> - -<H2><A NAME="defaultlanguage">DefaultLanguage</A></H2> -<!--%plaintext <?INDEX {\tt DefaultLanguage} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> DefaultLanguage <EM>MIME-lang</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<P> - -The DefaultLanguage directive tells Apache that all files in the -directive's scope (<EM>e.g.</EM>, all files covered by the current -<CODE><Directory></CODE> container) that don't have an explicit -language extension (such as <SAMP>.fr</SAMP> or <SAMP>.de</SAMP> as -configured by <SAMP>AddLanguage</SAMP>) should be considered to be in -the specified <EM>MIME-lang</EM> language. This allows entire -directories to be marked as containing Dutch content, for instance, -without having to rename each file. Note that unlike using extensions -to specify languages, <SAMP>DefaultLanguage</SAMP> can only specify a -single language. - -<P> - -If no <SAMP>DefaultLanguage</SAMP> directive is in force, and a file -does not have any language extensions as configured by -<SAMP>AddLanguage</SAMP>, then that file will be considered to have no -language attribute. - -<P> - -<STRONG>See also</STRONG>: <A -HREF="./mod_negotiation.html">mod_negotiation</A> -<BR> -<STRONG>See also</STRONG>: <A HREF="#multipleext">Files with -multiple extensions</A> - -<HR> - -<H2><A NAME="forcetype">ForceType</A></H2> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ForceType <EM>media type</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ForceType is only available in Apache -1.1 and later.<P> - -<P>When placed into an <CODE>.htaccess</CODE> file or a -<CODE><Directory></CODE> or <CODE><Location></CODE> section, -this directive forces all matching files to be served -as the content type given by <EM>media type</EM>. For example, if you -had a directory full of GIF files, but did not want to label them all with -".gif", you might want to use: -<PRE> - ForceType image/gif -</PRE> -<P>Note that this will override any filename extensions that might determine -the media type.</P><HR> - -<H2><A NAME="removehandler">RemoveHandler</A></H2> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RemoveHandler <EM>extension extension...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> RemoveHandler is only available in Apache -1.3.4 and later.<P> - -<P> -The <SAMP>RemoveHandler</SAMP> directive removes any -handler associations for files with the given extensions. -This allows <CODE>.htaccess</CODE> files in subdirectories to undo -any associations inherited from parent directories or the server -config files. An example of its use might be: -</P> -<DL> - <DT><CODE>/foo/.htaccess:</CODE></DT> - <DD><CODE>AddHandler server-parsed .html</CODE></DD> - <DT><CODE>/foo/bar/.htaccess:</CODE></DT> - <DD><CODE>RemoveHandler .html</CODE></DD> -</DL> -<P> -This has the effect of returning <SAMP>.html</SAMP> files in the -<SAMP>/foo/bar</SAMP> directory to being treated as normal -files, rather than as candidates for parsing (see the -<A HREF="mod_include.html"><SAMP>mod_include</SAMP></A> module). -</P> -<HR> - -<H2><A NAME="sethandler">SetHandler</A></H2> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> SetHandler <EM>handler-name</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> SetHandler is only available in Apache -1.1 and later.<P> - -<P>When placed into an <CODE>.htaccess</CODE> file or a -<CODE><Directory></CODE> or <CODE><Location></CODE> section, -this directive forces all matching files to be parsed through the -<A HREF="../handler.html">handler</A> -given by <EM>handler-name</EM>. For example, if you had a -directory you wanted to be parsed entirely as imagemap rule files, -regardless of extension, you might put the following into an -<CODE>.htaccess</CODE> file in that directory: -<PRE> - SetHandler imap-file -</PRE> - -<P>Another example: if you wanted to have the server display a status -report whenever a URL of <CODE>http://servername/status</CODE> was -called, you might put the following into access.conf: -<PRE> - <Location /status> - SetHandler server-status - </Location> -</PRE> -<HR> - -<H2><A NAME="typesconfig">TypesConfig</A></H2> -<!--%plaintext <?INDEX {\tt TypesConfig} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> TypesConfig <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>TypesConfig conf/MIME.types</CODE><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> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<P> - -The TypesConfig directive sets the location of the MIME types configuration -file. <EM>Filename</EM> is relative to the -<A HREF="core.html#serverroot">ServerRoot</A>. This file sets the default list of -mappings from filename extensions to content types; changing this file is not -recommended. Use the <A HREF="#addtype">AddType</A> directive instead. The -file contains lines in the format of the arguments to an AddType command: -<BLOCKQUOTE><EM>MIME-type extension extension ...</EM></BLOCKQUOTE> -The extensions are lower-cased. Blank lines, and lines beginning with a hash -character (`#') are ignored.<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_mime_magic.html b/docs/manual/mod/mod_mime_magic.html deleted file mode 100644 index a85e6b46b5..0000000000 --- a/docs/manual/mod/mod_mime_magic.html +++ /dev/null @@ -1,275 +0,0 @@ -<!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" - > - <DIV ALIGN="CENTER"> - <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> - </DIV> - - <H1 align="CENTER">Module mod_mime_magic</H1> - - This module is contained in the mod_mime_magic.c file, and is - an optional extension to the Apache HTTPD server. - It can be used to determine the MIME type of a file by looking at a - few bytes of its contents, the same way the Unix file(1) command works. - To use mod_mime_magic you have to enable the following line in the - server build <TT>Configuration</TT> file: - - <PRE> - AddModule modules/standard/mod_mime_magic.o - </PRE> - - This should be listed <EM>before</EM> mod_mime in the build - <TT>Configuration</TT> file so that it will be used after mod_mime. - mod_mime_magic is intended as a "second line of defense" for cases - mod_mime cannot resolve. - - <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 active only if the magic file is specified by the - <A HREF="#mimemagicfile"><CODE>MimeMagicFile</CODE></A> directive. - <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> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> MimeMagicFile <EM>magic-file-name</EM> - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> none - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Extension - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_mime_magic - <P> - - The <CODE>MimeMagicFile</CODE> directive can be used to enable this module, - the default file is distributed at <CODE>conf/magic</CODE>. - Non-rooted paths are relative to the ServerRoot. Virtual hosts - will use the same file as the main server unless a more specific setting - is used, in which case the more specific setting overrides the main server's - file. - <P> - <HR> - - <H2><A NAME="notes">Notes</A></H2> - - The following notes apply to the mod_mime_magic module and are - included here for compliance with contributors' copyright restrictions - that require their acknowledgment. - -<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 compliance 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. (<EM>i.e.</EM>, 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> diff --git a/docs/manual/mod/mod_mmap_static.html b/docs/manual/mod/mod_mmap_static.html deleted file mode 100644 index 07ed6b7350..0000000000 --- a/docs/manual/mod/mod_mmap_static.html +++ /dev/null @@ -1,142 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_mmap_static</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_mmap_static</H1> - - <P> - This module is contained in the <CODE>mod_mmap_static.c</CODE> file, with - Apache 1.3 and later. It provides mmap()ing of a statically configured list - of frequently requested but not changed files. It is not compiled into the - server by default. To use <CODE>mod_mmap_static</CODE> you have to enable - the following line in the server build <CODE>Configuration</CODE> file: - <PRE> - AddModule modules/experimental/mod_mmap_static.o - </PRE> - </P> - - <H2>Summary</H2> - <P> - This is an <STRONG>experimental</STRONG> module and should be used with - care. You can easily create a broken site using this module, read this - document carefully. - <CODE>mod_mmap_static</CODE> maps a list of statically configured files (via - <CODE>MMapFile</CODE> directives in the main server configuration) into - memory through the system call <CODE>mmap()</CODE>. This system - call is available on most modern Unix derivates, but not on all. There - are sometimes system-specific limits on the size and number of files that - can be mmap()d, experimentation is probably the easiest way to find out. - </P> - <P> - This mmap()ing is done once at server start or restart, only. So whenever - one of the mapped files changes on the filesystem you <EM>have</EM> to - restart the server by at least sending it a HUP or USR1 signal (see the - <A HREF="../stopping.html">Stopping and Restarting</A> documentation). To - reiterate that point: if the files are modified <EM>in place</EM> without - restarting the server you may end up serving requests that are completely - bogus. You should update files by unlinking the old copy and putting a new - copy in place. Most tools such as <CODE>rdist</CODE> and <CODE>mv</CODE> do - this. The reason why this modules doesn't take care of changes to the files - is that this check would need an extra <CODE>stat()</CODE> every time which - is a waste and against the intent of I/O reduction. - </P> - - <H2>Directives</H2> - <UL> - <LI><A HREF="#mmapfile">MMapFile</A> - </LI> - </UL> - - <HR> - - <H2><A NAME="mmapfile">MMapFile</A></H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> MMapFile <EM>filename ...</EM> - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>None</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server-config - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM> - <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_mmap_static - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> Only available in Apache 1.3 or later - - <P> - The <CODE>MMapFile</CODE> directive maps one or more files (given as - whitespace separated arguments) into memory at server startup time. They - are automatically unmapped on a server shutdown. When the files have changed - on the filesystem at least a HUP or USR1 signal should be send to the server - to re-mmap them. - </P> - - <P> - Be careful with the <EM>filename</EM> arguments: They have to literally - match the filesystem path Apache's URL-to-filename translation handlers - create. We cannot compare inodes or other stuff to match paths through - symbolic links <EM>etc.</EM> because that again would cost extra <CODE>stat()</CODE> - system calls which is not acceptable. This module may or may not work - with filenames rewritten by <CODE>mod_alias</CODE> or - <CODE>mod_rewrite</CODE>... it is an experiment after all. - </P> - - <P> - Notice: You cannot use this for speeding up CGI programs or other files - which are served by special content handlers. It can only be used for - regular files which are usually served by the Apache core content handler. - </P> - - Example: - - <PRE> - MMapFile /usr/local/apache/htdocs/index.html - </PRE> - - <P> - <STRONG>Note</STRONG>: don't bother asking for a for a <CODE>MMapDir</CODE> - directive which - recursively maps all the files in a directory. Use Unix the way it was - meant to be used. For example, see the - <A HREF="core.html#include">Include</A> directive, and consider this command: - <PRE> - find /www/htdocs -type f -print \ - | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf - </PRE> - -<!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/mod_negotiation.html b/docs/manual/mod/mod_negotiation.html deleted file mode 100644 index 96222acb22..0000000000 --- a/docs/manual/mod/mod_negotiation.html +++ /dev/null @@ -1,201 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_negotiation</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_negotiation</H1> - -This module is contained in the <CODE>mod_negotiation.c</CODE> file, -and is compiled in by default. It provides for <A -HREF="../content-negotiation.html">content negotiation</A>. - -<H2>Summary</H2> -Content negotiation, or more accurately content selection, is the -selection of the document that best matches the clients -capabilities, from one of several available documents. -There are two implementations of this. -<UL> -<LI> A type map (a file with the handler <CODE>type-map</CODE>) -which explicitly lists the files containing the variants. -<LI> A MultiViews search (enabled by the MultiViews -<A HREF="core.html#options">Option</A>, where the server does an implicit -filename pattern match, and choose from amongst the results. -</UL> - -<H3>Type maps</H3> -A type map has the same format as RFC822 mail headers. It contains document -descriptions separated by blank lines, with lines beginning with a hash -character ('#') treated as comments. A document description consists of -several header records; records may be continued on multiple lines if the -continuation lines start with spaces. The leading space will be deleted -and the lines concatenated. A header record consists of a keyword -name, which always ends in a colon, followed by a value. Whitespace is allowed -between the header name and value, and between the tokens of value. - -The headers allowed are: - -<DL> -<DT>Content-Encoding: -<DD>The encoding of the file. Apache only recognizes encodings that are -defined by an <A HREF="mod_mime.html#addencoding">AddEncoding</A> directive. -This normally includes the encodings <CODE>x-compress</CODE> for compress'd -files, and <CODE>x-gzip</CODE> for gzip'd files. The <CODE>x-</CODE> prefix -is ignored for encoding comparisons. -<DT>Content-Language: -<DD>The language of the variant, as an Internet standard language tag -(RFC 1766). An example is <CODE>en</CODE>, meaning English. -<DT>Content-Length: -<DD>The length of the file, in bytes. If this header is not present, then -the actual length of the file is used. -<DT>Content-Type: -<DD>The MIME media type of the document, with optional parameters. -Parameters are separated from the media type and from one another by a -semi-colon, with a syntax of <CODE>name=value</CODE>. Common parameters -include: -<DL> -<DT>level -<DD>an integer specifying the version of the media type. -For <CODE>text/html</CODE> this defaults to 2, otherwise 0. -<DT>qs -<DD>a floating-point number with a value in the range 0.0 to 1.0, - indicating the relative 'quality' of this variant - compared to the other available variants, independent of the client's - capabilities. For example, a jpeg file is usually of higher source - quality than an ascii file if it is attempting to represent a - photograph. However, if the resource being represented is ascii art, - then an ascii file would have a higher source quality than a jpeg file. - All qs values are therefore specific to a given resource. -</DL> -Example: -<BLOCKQUOTE><CODE>Content-Type: image/jpeg; qs=0.8</CODE></BLOCKQUOTE> -<DT>URI: -<DD>The path to the file containing this variant, relative to the map file. -</DL> - -<H3>MultiViews</H3> -A MultiViews search is enabled by the MultiViews -<A HREF="core.html#options">Option</A>. -If the server receives a request for <CODE>/some/dir/foo</CODE> and -<CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the -directory looking for all files named <CODE>foo.*</CODE>, and effectively -fakes up a type map which names all those files, assigning them the same media -types and content-encodings it would have if the client had asked for -one of them by name. It then chooses the best match to the client's -requirements, and returns that document.<P> - - - -<H2>Directives</H2> -<UL> -<LI><A HREF="#cachenegotiateddocs">CacheNegotiatedDocs</A> -<LI><A HREF="#languagepriority">LanguagePriority</A> -</UL> - -<STRONG>See also</STRONG>: -<A HREF="./mod_mime.html#defaultlanguage">DefaultLanguage</A>, -<A HREF="./mod_mime.html#addencoding">AddEncoding</A>, -<A HREF="./mod_mime.html#addlanguage">AddLanguage</A>, -<A HREF="./mod_mime.html#addtype">AddType</A>, and -<A HREF="core.html#options">Option</A>. - -<HR> - - -<H2><A NAME="cachenegotiateddocs">CacheNegotiatedDocs</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CacheNegotiatedDocs<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> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_negotiation<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> CacheNegotiatedDocs is only available -in Apache 1.1 and later.<P> - -<P>If set, this directive allows content-negotiated documents to be -cached by proxy servers. This could mean that clients behind those -proxys could retrieve versions of the documents that are not the best -match for their abilities, but it will make caching more -efficient. -<P> - -This directive only applies to requests which come from HTTP/1.0 browsers. -HTTP/1.1 provides much better control over the caching of negotiated -documents, and this directive has no effect in responses to -HTTP/1.1 requests. - - - -<H2><A NAME="languagepriority">LanguagePriority</A></H2> -<!--%plaintext <?INDEX {\tt LanguagePriority} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LanguagePriority <EM>MIME-lang MIME-lang...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_negotiation<P> - -The LanguagePriority sets the precedence of language variants for the case -where the client does not express a preference, when handling a -MultiViews request. The list of <EM>MIME-lang</EM> are in order of decreasing -preference. Example: - -<BLOCKQUOTE><CODE>LanguagePriority en fr de</CODE></BLOCKQUOTE> - -For a request for <CODE>foo.html</CODE>, where <CODE>foo.html.fr</CODE> -and <CODE>foo.html.de</CODE> both existed, but the browser did not express -a language preference, then <CODE>foo.html.fr</CODE> would be returned.<P> - -<P> - -Note that this directive only has an effect if a 'best' language -cannot be determined by any other means. Correctly implemented -HTTP/1.1 requests will mean this directive has no effect. - -<P> - -<STRONG>See also</STRONG>: -<A HREF="./mod_mime.html#defaultlanguage">DefaultLanguage</A> and -<A HREF="./mod_mime.html#addlanguage">AddLanguage</A> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_proxy.html b/docs/manual/mod/mod_proxy.html deleted file mode 100644 index 6e9db4fdd9..0000000000 --- a/docs/manual/mod/mod_proxy.html +++ /dev/null @@ -1,1162 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_proxy</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache module mod_proxy</H1> - -This module is contained in the <CODE>mod_proxy.c</CODE> file for Apache 1.1.x, -or the <CODE>modules/proxy</CODE> subdirectory for Apache 1.2, and -is not compiled in by default. It provides for an <STRONG>HTTP -1.0</STRONG> caching proxy -server. It is only available in Apache 1.1 and later. Common configuration -questions are addressed <A HREF="#configs">after the directive -descriptions</A>. - -<H3>Note:</H3> -<P>This module was experimental in Apache 1.1.x. As of Apache 1.2, mod_proxy -stability is <EM>greatly</EM> improved.<P> - -<H2>Summary</H2> - -This module implements a proxy/cache for Apache. It implements -proxying capability for -<CODE>FTP</CODE>, -<CODE>CONNECT</CODE> (for SSL), -<CODE>HTTP/0.9</CODE>, and -<CODE>HTTP/1.0</CODE>. -The module can be configured to connect to other proxy modules for these -and other protocols. - -<H2>Directives</H2> -<UL> -<LI><A HREF="#proxyrequests">ProxyRequests</A> -<LI><A HREF="#proxyremote">ProxyRemote</A> -<LI><A HREF="#proxypass">ProxyPass</A> -<LI><A HREF="#proxypassreverse">ProxyPassReverse</A> -<LI><A HREF="#proxyblock">ProxyBlock</A> -<LI><A HREF="#allowconnect">AllowCONNECT</A> -<LI><A HREF="#proxyreceivebuffersize">ProxyReceiveBufferSize</A> -<LI><A HREF="#noproxy">NoProxy</A> -<LI><A HREF="#proxydomain">ProxyDomain</A> -<LI><A HREF="#proxyvia">ProxyVia</A> -<LI><A HREF="#cacheroot">CacheRoot</A> -<LI><A HREF="#cachesize">CacheSize</A> -<LI><A HREF="#cachemaxexpire">CacheMaxExpire</A> -<LI><A HREF="#cachedefaultexpire">CacheDefaultExpire</A> -<LI><A HREF="#cachelastmodifiedfactor">CacheLastModifiedFactor</A> -<LI><A HREF="#cachegcinterval">CacheGcInterval</A> -<LI><A HREF="#cachedirlevels">CacheDirLevels</A> -<LI><A HREF="#cachedirlength">CacheDirLength</A> -<LI><A HREF="#cacheforcecompletion">CacheForceCompletion</A> -<LI><A HREF="#nocache">NoCache</A> -</UL> - -<HR> - -<H2><A NAME="proxyrequests">ProxyRequests</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ProxyRequests <EM>on/off</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ProxyRequests Off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ProxyRequests is only available in -Apache 1.1 and later.<P> - -This allows or prevents Apache from functioning as a proxy -server. Setting ProxyRequests to 'off' does not disable use of the <A -HREF="#proxypass">ProxyPass</A> directive. - -<HR> - -<H2><A NAME="proxyremote">ProxyRemote</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ProxyRemote <EM><match> <remote-server></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ProxyRemote is only available in -Apache 1.1 and later.<P> - -This defines remote proxies to this proxy. <match> is either the -name of a URL-scheme that the remote server supports, or a partial URL -for which the remote server should be used, or '*' to indicate the -server should be contacted for all requests. <remote-server> is a -partial URL for the remote server. Syntax: - -<PRE> - <remote-server> = <protocol>://<hostname>[:port] -</PRE> - -<protocol> is the protocol that should be used to communicate -with the remote server; only "http" is supported by this module. -<P> -Example: -<PRE> - ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000 - ProxyRemote * http://cleversite.com - ProxyRemote ftp http://ftpproxy.mydomain.com:8080 -</PRE> - -In the last example, the proxy will forward FTP requests, encapsulated -as yet another HTTP proxy request, to another proxy which can handle -them. - -<HR> - -<H2><A NAME="proxypass">ProxyPass</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ProxyPass <EM><path> <url></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ProxyPass is only available in -Apache 1.1 and later.<P> - -This directive allows remote servers to be mapped into the space of the local -server; the local server does not act as a proxy in the conventional sense, -but appears to be a mirror of the remote server. <path> is the name of -a local virtual path; <url> is a partial URL for the remote server. -<P> -Suppose the local server has address <SAMP>http://wibble.org/</SAMP>; then -<PRE> - ProxyPass /mirror/foo/ http://foo.com/ -</PRE> -will cause a local request for the -<<SAMP>http://wibble.org/mirror/foo/bar</SAMP>> to be -internally converted into a proxy request to -<<SAMP>http://foo.com/bar</SAMP>>. - -<HR> - -<H2><A NAME="proxypassreverse">ProxyPassReverse</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ProxyPassReverse <EM><path> <url></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ProxyPassReverse is only available in -Apache 1.3b6 and later.<P> - -This directive lets Apache adjust the URL in the <TT>Location</TT> header on -HTTP redirect responses. For instance this is essential when Apache is used as -a reverse proxy to avoid by-passing the reverse proxy because of HTTP -redirects on the backend servers which stay behind the reverse proxy. -<P> -<path> is the name of a local virtual path.<BR> -<url> is a partial URL for the remote server - the same way they are -used for the <TT>ProxyPass</TT> directive. -<P> -Example:<BR> -Suppose the local server has address <SAMP>http://wibble.org/</SAMP>; then -<PRE> - ProxyPass /mirror/foo/ http://foo.com/ - ProxyPassReverse /mirror/foo/ http://foo.com/ -</PRE> -will not only cause a local request for the -<<SAMP>http://wibble.org/mirror/foo/bar</SAMP>> to be internally -converted into a proxy request to <<SAMP>http://foo.com/bar</SAMP>> (the -functionality <SAMP>ProxyPass</SAMP> provides here). It also takes care of -redirects the server foo.com sends: when <SAMP>http://foo.com/bar</SAMP> is -redirected by him to <SAMP>http://foo.com/quux</SAMP> Apache adjusts this to -<SAMP>http://wibble.org/mirror/foo/quux</SAMP> before forwarding the HTTP -redirect response to the client. -<P> -Note that this <SAMP>ProxyPassReverse</SAMP> directive can also be used in -conjunction with the proxy pass-through feature ("<SAMP>RewriteRule ... -[P]</SAMP>") from -<A - HREF="mod_rewrite.html#RewriteRule" -><TT>mod_rewrite</TT></A> because its doesn't depend on a corresponding -<SAMP>ProxyPass</SAMP> directive. - -<HR> - -<H2><A NAME="allowconnect">AllowCONNECT</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AllowCONNECT <EM><port list></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM><SAMP>AllowCONNECT</SAMP> 443 563</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> <SAMP>AllowCONNECT</SAMP> is only -available in Apache 1.3.2 and later.<P> - -The <SAMP>AllowCONNECT</SAMP> directive specifies a list of port numbers -to which the proxy <SAMP>CONNECT</SAMP> method may connect. -Today's browsers use this method when a <EM>https</EM> connection -is requested and proxy tunneling over <EM>http</EM> is in effect.<BR> -By default, only the default https port (443) and the default -snews port (563) are enabled. Use the <SAMP>AllowCONNECT</SAMP> -directive to overrride this default and allow connections to the -listed ports only. - -<HR> - -<H2><A NAME="proxyblock">ProxyBlock</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ProxyBlock <EM><word/host/domain list></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ProxyBlock is only available in -Apache 1.2 and later.<P> - -The ProxyBlock directive specifies a list of words, hosts and/or domains, -separated by spaces. HTTP, HTTPS, and FTP document requests to sites whose -names contain matched words, hosts or domains are <EM>blocked</EM> by the -proxy server. The proxy module will also attempt to determine IP addresses of -list items which may be hostnames during startup, and cache them for match -test as well. Example: - -<PRE> - ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu -</PRE> - -'rocky.wotsamattau.edu' would also be matched if referenced by IP address.<P> - -Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.<P> - -Note also that - -<PRE> -ProxyBlock * -</PRE> - -blocks connections to all sites. - -<HR> - -<H2><A NAME="proxyreceivebuffersize">ProxyReceiveBufferSize</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ProxyReceiveBufferSize <EM><bytes></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ProxyReceiveBufferSize is only available in -Apache 1.3 and later.<P> - -The ProxyReceiveBufferSize directive specifies an explicit network buffer size -for outgoing HTTP and FTP connections, for increased throughput. It has to be -greater than 512 or set to 0 to indicate that the system's default buffer size -should be used. - -<P> -Example: - -<PRE> - ProxyReceiveBufferSize 2048 -</PRE> - -<HR> - -<H2><A NAME="noproxy">NoProxy</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> NoProxy { <A HREF="#domain"><EM><Domain></EM></A> - | <A HREF="#subnet"><EM><SubNet></EM></A> - | <A HREF="#ipaddr"><EM><IpAddr></EM></A> - | <A HREF="#hostname"><EM><Hostname></EM></A> - } <BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> NoProxy is only available in -Apache 1.3 and later.<P> - -This directive is only useful for Apache proxy servers within intranets. -The NoProxy directive specifies a list of subnets, IP addresses, hosts -and/or domains, separated by spaces. A request to a host which matches -one or more of these is always served directly, without forwarding to -the configured ProxyRemote proxy server(s). -<P> -Example: - -<PRE> - ProxyRemote * http://firewall.mycompany.com:81 - NoProxy .mycompany.com 192.168.112.0/21 -</PRE> -The arguments to the NoProxy directive are one of the following type list: - <DL> - <!-- ===================== Domain ======================= --> - <A NAME="domain"> - <DT><EM>Domain</EM></A> - <DD>A <EM>Domain</EM> is a partially qualified DNS domain name, preceded - by a period. - It represents a list of hosts which logically belong to the same DNS - domain or zone (<EM>i.e.</EM>, the suffixes of the hostnames are all ending in - <EM>Domain</EM>).<BR> - Examples: <SAMP>.com</SAMP> <SAMP>.apache.org.</SAMP><BR> - To distinguish <EM>Domain</EM>s from <A HREF="#hostname"><EM>Hostname</EM></A>s (both - syntactically and semantically; a DNS domain can have a DNS A record, - too!), <EM>Domain</EM>s are always written - with a leading period.<BR> - Note: Domain name comparisons are done without regard to the case, - and <EM>Domain</EM>s are always assumed to be anchored in the root - of the DNS tree, therefore two domains <SAMP>.MyDomain.com</SAMP> and - <SAMP>.mydomain.com.</SAMP> (note the trailing period) are - considered equal. Since a domain comparison does not involve a DNS - lookup, it is much more efficient than subnet comparison. - - <!-- ===================== SubNet ======================= --> - <A NAME="subnet"> - <DT><EM>SubNet</EM></A> - <DD>A <EM>SubNet</EM> is a partially qualified internet address in - numeric (dotted quad) form, optionally followed by a slash and the - netmask, specified as the number of significant bits in the - <EM>SubNet</EM>. It is used to represent a subnet of hosts which can - be reached over a common network interface. In the absence of the - explicit net mask it is assumed that omitted (or zero valued) - trailing digits specify the mask. (In this case, the netmask can - only be multiples of 8 bits wide.)<BR> - Examples: - <DL> - <DT><SAMP>192.168</SAMP> or <SAMP>192.168.0.0</SAMP> - <DD>the subnet 192.168.0.0 with an implied netmask of 16 valid bits - (sometimes used in the netmask form <SAMP>255.255.0.0</SAMP>) - <DT><SAMP>192.168.112.0/21</SAMP> - <DD>the subnet <SAMP>192.168.112.0/21</SAMP> with a netmask of 21 - valid bits (also used in the form 255.255.248.0) - </DL> - As a degenerate case, a <EM>SubNet</EM> with 32 valid bits is the - equivalent to an <EM>IPAddr</EM>, while a <EM>SubNet</EM> with zero - valid bits (<EM>e.g.</EM>, 0.0.0.0/0) is the same as the constant - <EM>_Default_</EM>, matching any IP address. - - <!-- ===================== IPAddr ======================= --> - <A NAME="ipaddr"> - <DT><EM>IPAddr</EM></A> - <DD>A <EM>IPAddr</EM> represents a fully qualified internet address in - numeric (dotted quad) form. Usually, this address represents a - host, but there need not necessarily be a DNS domain name - connected with the address.<BR> - Example: 192.168.123.7<BR> - Note: An <EM>IPAddr</EM> does not need to be resolved by the DNS - system, so it can result in more effective apache performance. - <P><STRONG>See Also:</STRONG> - <A HREF="../dns-caveats.html">DNS Issues</A></P> - - <!-- ===================== Hostname ======================= --> - <A NAME="hostname"> - <DT><EM>Hostname</EM></A> - <DD>A <EM>Hostname</EM> is a fully qualified DNS domain name which can - be resolved to one or more <A - HREF="#ipaddr"><EM>IPAddrs</EM></A> via the DNS domain name service. - It represents a logical host (in contrast to - <A HREF="#domain"><EM>Domain</EM></A>s, see - above) and must be resolvable to at least one <A - HREF="#ipaddr"><EM>IPAddr</EM></A> (or often to a list of hosts - with different <A HREF="#ipaddr"><EM>IPAddr</EM></A>'s).<BR> - Examples: <SAMP>prep.ai.mit.edu</SAMP> - <SAMP>www.apache.org.</SAMP><BR> - Note: In many situations, it is more effective to specify an - <A HREF="#ipaddr"><EM>IPAddr</EM></A> in place of a - <EM>Hostname</EM> since a DNS lookup - can be avoided. Name resolution in Apache can take a remarkable deal - of time when the connection to the name server uses a slow PPP - link.<BR> - Note: <EM>Hostname</EM> comparisons are done without regard to the case, - and <EM>Hostname</EM>s are always assumed to be anchored in the root - of the DNS tree, therefore two hosts <SAMP>WWW.MyDomain.com</SAMP> - and <SAMP>www.mydomain.com.</SAMP> (note the trailing period) are - considered equal.<BR> -<P><STRONG>See Also:</STRONG> -<A HREF="../dns-caveats.html">DNS Issues</A></P> - </DL> - -<HR> - -<H2><A NAME="proxydomain">ProxyDomain</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ProxyDomain <EM><Domain></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ProxyDomain is only available in -Apache 1.3 and later.<P> - -This directive is only useful for Apache proxy servers within intranets. -The ProxyDomain directive specifies the default domain which the apache -proxy server will belong to. If a request to a host without a domain name -is encountered, a redirection response to the same host -with the configured <EM>Domain</EM> appended will be generated. -<P> -Example: - -<PRE> - ProxyRemote * http://firewall.mycompany.com:81 - NoProxy .mycompany.com 192.168.112.0/21 - ProxyDomain .mycompany.com -</PRE> - -<HR> - -<H2><A NAME="proxyvia">ProxyVia</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ProxyVia { <EM>off</EM> - | <EM>on</EM> - | <EM>full</EM> - | <EM>block</EM> - }<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>ProxyVia off</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ProxyVia is only available in -Apache 1.3.2 and later.<P> - -This directive controls the use of the <SAMP>Via:</SAMP> HTTP header -by the proxy. Its intended use is to control the flow of of proxy -requests along a chain of proxy servers. -See RFC2068 (HTTP/1.1) for an explanation of <SAMP>Via:</SAMP> header lines.<UL> -<LI>If set to <EM>off</EM>, which is the default, no special -processing is performed. If a request or reply contains a <SAMP>Via:</SAMP> header, -it is passed through unchanged. -<LI>If set to <EM>on</EM>, each request and reply will get a <SAMP>Via:</SAMP> header -line added for the current host. -<LI>If set to <EM>full</EM>, each generated <SAMP>Via:</SAMP> header line will -additionally have the Apache server version shown as a <SAMP>Via:</SAMP> comment field. -<LI>If set to <EM>block</EM>, every proxy request will have all its -<SAMP>Via:</SAMP> header lines removed. No new <SAMP>Via:</SAMP> header will be generated. -</UL> - -<HR> - -<H2><A NAME="cacheforcecompletion">CacheForceCompletion</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CacheForceCompletion <EM><percentage></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>90</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> CacheForceCompletion is only available in -Apache 1.3.1 and later.<P> - -If an http transfer that is being cached is cancelled, the proxy module will -complete the transfer to cache if more than the percentage specified has -already been transferred.<P> - -This is a percentage, and must be a number between 1 and 100, or 0 to use -the default. 100 will cause a document to be cached only if the transfer -was allowed to complete. A number between 60 and 90 is recommended. - -<HR> - -<H2><A NAME="cacheroot">CacheRoot</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CacheRoot <EM><directory></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> CacheRoot is only available in -Apache 1.1 and later.<P> - -Sets the name of the directory to contain cache files; this must be -writable by the httpd server. -(see the <A HREF="core.html#user"><CODE>User</CODE></A> directive).<BR> -Setting <CODE>CacheRoot</CODE> enables proxy cacheing; without defining -a <CODE>CacheRoot</CODE>, proxy functionality will be available -if <CODE>ProxyRequests</CODE> are set to <CODE>On</CODE>, but no -cacheing will be available. - -<HR> - -<H2><A NAME="cachesize">CacheSize</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CacheSize <EM><size></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>CacheSize 5</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> CacheSize is only available in -Apache 1.1 and later.<P> - -Sets the desired space usage of the cache, in KB (1024-byte units). Although -usage may grow above this setting, the garbage collection will delete files -until the usage is at or below this setting.<BR> -Depending on the expected proxy traffic volume and <CODE>CacheGcInterval</CODE>, -use a value which is at least 20 to 40 % lower than the available space. - -<HR> - -<H2><A NAME="cachegcinterval">CacheGcInterval</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CacheGcInterval <EM><time></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> CacheGcinterval is only available in -Apache 1.1 and later.<P> - -Check the cache every <time> hours, and delete files if the space -usage is greater than that set by CacheSize. Note that <time> accepts a -float value, you could for example use <CODE>CacheGcInterval 1.5</CODE> to -check the cache every 90 minutes. (If unset, no garbage collection will -be performed, and the cache will grow indefinitely.) -Note also that the larger the <CODE>CacheGcInterval</CODE>, the more -extra space beyond the configured <CODE>CacheSize</CODE> will be -needed for the cache between garbage collections.<BR> <!-- -Note that due to a design flaw, Apache does not automatically force a -garbage collection when the available space on the file system where -the cache resides is exhausted. --> - -<HR> - -<H2><A NAME="cachemaxexpire">CacheMaxExpire</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CacheMaxExpire <EM><time></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>CacheMaxExpire 24</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> CacheMaxExpire is only available in -Apache 1.1 and later.<P> - -Cachable HTTP documents will be retained for at most <time> hours without -checking the origin server. Thus documents can be at most <time> -hours out of date. This restriction is enforced even if an expiry date -was supplied with the document. - -<HR> - -<H2><A NAME="cachelastmodifiedfactor">CacheLastModifiedFactor</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CacheLastModifiedFactor <EM><factor></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>CacheLastModifiedFactor 0.1</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> CacheLastModifiedFactor is only available in -Apache 1.1 and later.<P> - -If the origin HTTP server did not supply an expiry date for the -document, then estimate one using the formula -<PRE> - expiry-period = time-since-last-modification * <factor> -</PRE> -For example, if the document was last modified 10 hours ago, and -<factor> is 0.1, then the expiry period will be set to 10*0.1 = 1 hour. - -<P>If the expiry-period would be longer than that set by CacheMaxExpire, -then the latter takes precedence. - -<HR> - -<H2><A NAME="cachedirlevels">CacheDirLevels</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CacheDirLevels <EM><levels></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>CacheDirLevels 3</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> CacheDirLevels is only available in -Apache 1.1 and later.<P> - -CacheDirLevels sets the number of levels of subdirectories in the cache. -Cached data will be saved this many directory levels below CacheRoot. - -<HR> - -<H2><A NAME="cachedirlength">CacheDirLength</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CacheDirLength <EM><length></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>CacheDirLength 1</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> CacheDirLength is only available in -Apache 1.1 and later.<P> - -CacheDirLength sets the number of characters in proxy cache subdirectory names. - -<HR> - -<H2><A NAME="cachedefaultexpire">CacheDefaultExpire</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CacheDefaultExpire <EM><time></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>CacheDefaultExpire 1</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> CacheDefaultExpire is only available in -Apache 1.1 and later.<P> - -If the document is fetched via a protocol that does not support expiry times, -then use <time> hours as the expiry time. -<A HREF="#cachemaxexpire">CacheMaxExpire</A> does <STRONG>not</STRONG> -override this setting. - -<HR> - -<H2><A NAME="nocache">NoCache</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> NoCache <EM><word/host/domain list></EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_proxy<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> NoCache is only available in -Apache 1.1 and later.<P> - -The NoCache directive specifies a list of words, hosts and/or domains, separated -by spaces. HTTP and non-passworded FTP documents from matched words, hosts or -domains are <EM>not</EM> cached by the proxy server. The proxy module will -also attempt to determine IP addresses of list items which may be hostnames -during startup, and cache them for match test as well. Example: - -<PRE> - NoCache joes-garage.com some-host.co.uk bullwinkle.wotsamattau.edu -</PRE> - -'bullwinkle.wotsamattau.edu' would also be matched if referenced by IP -address.<P> - -Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.<P> - -Note also that - -<PRE> -NoCache * -</PRE> - -disables caching completely.<P> - -<HR> - -<H2><A NAME="configs">Common configuration topics</A></H2> - -<UL> -<LI><A HREF="#access">Controlling access to your proxy</A> -<LI><A HREF="#shortname">Using Netscape hostname shortcuts</A> -<LI><A HREF="#mimetypes">Why doesn't file type <EM>xxx</EM> download via FTP?</A> -<LI><A HREF="#startup">Why does Apache start more slowly when using the - proxy module?</A> -<LI><A HREF="#socks">Can I use the Apache proxy module with my SOCKS proxy?</A> -<LI><A HREF="#intranet">What other functions are useful for an intranet proxy server?</A> -</UL> - -<H2><A NAME="access">Controlling access to your proxy</A></H2> - -You can control who can access your proxy via the normal <Directory> -control block using the following example:<P> - -<PRE> -<Directory proxy:*> -order deny,allow -deny from [machines you'd like *not* to allow by IP address or name] -allow from [machines you'd like to allow by IP address or name] -</Directory> -</PRE><P> - -A <Files> block will also work, and is the only method known to work -for all possible URLs in Apache versions earlier than 1.2b10.<P> - -<H2><A NAME="shortname">Using Netscape hostname shortcuts</A></H2> - -There is an optional patch to the proxy module to allow Netscape-like -hostname shortcuts to be used. It's available from the -<A HREF="http://www.apache.org/dist/contrib/patches/1.2/netscapehost.patch" -><SAMP>contrib/patches/1.2</SAMP></A> directory on the Apache Web site.<P> - -<H2><A NAME="mimetypes">Why doesn't file type <EM>xxx</EM> download via FTP?</A></H2> - -You probably don't have that particular file type defined as -<EM>application/octet-stream</EM> in your proxy's mime.types configuration -file. A useful line can be<P> - -<PRE> -application/octet-stream bin dms lha lzh exe class tgz taz -</PRE> - -<H2><A NAME="type">How can I force an FTP ASCII download of File <EM>xxx</EM>?</A></H2> - -In the rare situation where you must download a specific file using the FTP -<STRONG>ASCII</STRONG> transfer method (while the default transfer is in -<STRONG>binary</STRONG> mode), you can override mod_proxy's default by -suffixing the request with <SAMP>;type=a</SAMP> to force an ASCII transfer.<P> - -<H2><A NAME="startup">Why does Apache start more slowly when using the - proxy module?</A></H2> - -If you're using the <CODE>ProxyBlock</CODE> or <CODE>NoCache</CODE> -directives, hostnames' IP addresses are looked up and cached during -startup for later match test. This may take a few seconds (or more) -depending on the speed with which the hostname lookups occur.<P> - -<H2><A NAME="socks">Can I use the Apache proxy module with my SOCKS proxy?</A></H2> - -Yes. Just build Apache with the rule <CODE>SOCKS4=yes</CODE> in your -<EM>Configuration</EM> file, and follow the instructions there. SOCKS5 -capability can be added in a similar way (there's no <CODE>SOCKS5</CODE> -rule yet), so use the <CODE>EXTRA_LDFLAGS</CODE> definition, or build Apache -normally and run it with the <EM>runsocks</EM> wrapper provided with SOCKS5, -if your OS supports dynamically linked libraries.<P> - -Some users have reported problems when using SOCKS version 4.2 on Solaris. -The problem was solved by upgrading to SOCKS 4.3.<P> - -Remember that you'll also have to grant access to your Apache proxy machine by -permitting connections on the appropriate ports in your SOCKS daemon's -configuration.<P> - -<H2><A NAME="intranet">What other functions are useful for an intranet proxy server?</A></H2> - -<P>An Apache proxy server situated in an intranet needs to forward external -requests through the company's firewall. However, when it has to access -resources within the intranet, it can bypass the firewall when accessing -hosts. The <A HREF="#noproxy">NoProxy</A> directive is useful for specifying -which hosts belong to the intranet and should be accessed directly.</P> - -<P>Users within an intranet tend to omit the local domain name from their -WWW requests, thus requesting "http://somehost/" instead of -"http://somehost.my.dom.ain/". Some commercial proxy servers let them get -away with this and simply serve the request, implying a configured -local domain. When the <A HREF="#proxydomain">ProxyDomain</A> directive -is used and the server is <A HREF="#proxyrequests">configured for -proxy service</A>, Apache can return a redirect response and send the client -to the correct, fully qualified, server address. This is the preferred method -since the user's bookmark files will then contain fully qualified hosts.</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html deleted file mode 100644 index 24132d26f8..0000000000 --- a/docs/manual/mod/mod_rewrite.html +++ /dev/null @@ -1,1874 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<!--%hypertext --> -<!-- mod_rewrite.html --> -<!-- Documentation for the mod_rewrite Apache module --> -<HTML> -<HEAD> -<TITLE>Apache module mod_rewrite</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<BLOCKQUOTE><!-- page indentation --> -<!--#include virtual="header.html" --> - -<BR> -<H1 ALIGN="CENTER">Module mod_rewrite<BR>URL Rewriting Engine</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. It 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 <CODE>Configuration</CODE> file: -<PRE> - AddModule modules/standard/mod_rewrite.o -</PRE> - -<P> -<HR NOSHADE SIZE=1> - -<BR> -<H2>Summary</H2> - -<BLOCKQUOTE> -<BLOCKQUOTE> -<BLOCKQUOTE> -<EM>``The great thing about mod_rewrite is it gives you all the -configurability and flexibility of Sendmail. The downside to -mod_rewrite is that it gives you all the configurability and -flexibility of Sendmail.''</EM> -<DIV ALIGN=RIGHT> --- Brian Behlendorf<BR> -Apache Group -</DIV> -</BLOCKQUOTE> -</BLOCKQUOTE> -</BLOCKQUOTE> - -<BLOCKQUOTE> -<BLOCKQUOTE> -<BLOCKQUOTE> -<EM>`` -Despite the tons of examples and docs, mod_rewrite -is voodoo. Damned cool voodoo, but still voodoo. -''</EM> -<DIV ALIGN=RIGHT> --- Brian Moore<BR> -bem@news.cmc.net -</DIV> -</BLOCKQUOTE> -</BLOCKQUOTE> -</BLOCKQUOTE> - -Welcome to mod_rewrite, the Swiss Army Knife of URL manipulation! - -<P> -This module uses a rule-based rewriting engine (based on a regular-expression -parser) to rewrite requested URLs on the fly. It supports an unlimited number -of rules and an unlimited number of attached rule conditions for each rule to -provide a really flexible and powerful URL manipulation mechanism. The URL -manipulations can depend on various tests, for instance server variables, -environment variables, HTTP headers, time stamps and even external database -lookups in various formats can be used to achieve a really granular URL -matching. - -<P> -This module operates on the full URLs (including the path-info part) both in -per-server context (<CODE>httpd.conf</CODE>) and per-directory context -(<CODE>.htaccess</CODE>) and even can generate query-string parts on result. -The rewritten result can lead to internal sub-processing, external request -redirection or even to an internal proxy throughput. - -<P> -But all this functionality and flexibility has its drawback: complexity. So -don't expect to understand this module in it's whole in just one day. - -<P> -This module was invented and originally written in April 1996<BR> -and gifted exclusively to the The Apache Group in July 1997 by - -<P> -<BLOCKQUOTE> -<A HREF="http://www.engelschall.com/"><CODE>Ralf S. Engelschall</CODE></A><BR> -<A HREF="mailto:rse@engelschall.com"><CODE>rse@engelschall.com</CODE></A><BR> -<A HREF="http://www.engelschall.com/"><CODE>www.engelschall.com</CODE></A> -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> - -<H2>Table Of Contents</H2> - -<P> -<STRONG>Internal Processing</STRONG> -<UL> - <LI><A HREF="#InternalAPI">API Phases</A> - <LI><A HREF="#InternalRuleset">Ruleset Processing</A> - <LI><A HREF="#InternalBackRefs">Regex Back-Reference Availability</A> -</UL> -<P> -<STRONG>Configuration Directives</STRONG> -<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="#RewriteLock">RewriteLock</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> -<STRONG>Miscellaneous</STRONG> -<UL> - <LI><A HREF="#EnvVar">Environment Variables</A> - <LI><A HREF="#Solutions">Practical Solutions</A> -</UL> - -<P> -<HR NOSHADE SIZE=1> - -<CENTER> -<H1><A NAME="Internal">Internal Processing</A></H1> -</CENTER> - -<P> -<HR NOSHADE SIZE=1> - -<P> -The internal processing of this module is very complex but needs to be -explained once even to the average user to avoid common mistakes and to let -you exploit its full functionality. - -<H2><A NAME="InternalAPI">API Phases</A></H2> - -<P> -First you have to understand that when Apache processes a HTTP request it does -this in phases. A hook for each of these phases is provided by the Apache API. -Mod_rewrite uses two of these hooks: the URL-to-filename translation hook -which is used after the HTTP request was read and before any authorization -starts and the Fixup hook which is triggered after the authorization phases -and after the per-directory config files (<CODE>.htaccess</CODE>) where read, -but before the content handler is activated. - -<P> -So, after a request comes in and Apache has determined the corresponding -server (or virtual server) the rewriting engine start processing of all -mod_rewrite directives from the per-server configuration in the -URL-to-filename phase. A few steps later when the final data directories are -found, the per-directory configuration directives of mod_rewrite are triggered -in the Fixup phase. In both situations mod_rewrite either rewrites URLs to new -URLs or to filenames, although there is no obvious distinction between them. -This is a usage of the API which was not intended this way when the API -was designed, but as of Apache 1.x this is the only way mod_rewrite can -operate. To make this point more clear remember the following two points: - -<OL> -<LI>The API currently provides only a URL-to-filename hook. Although - mod_rewrite rewrites URLs to URLs, URLs to filenames and even - filenames to filenames. In Apache 2.0 the two missing hooks - will be added to make the processing more clear. But this - point has no drawbacks for the user, it is just a fact which - should be remembered: Apache does more in the URL-to-filename hook - then the API intends for it. -<P> -<LI>Unbelievably mod_rewrite provides URL manipulations in per-directory - context, <EM>i.e.</EM>, within <CODE>.htaccess</CODE> files, although - these are - reached a very long time after the URLs were translated to filenames (this - has to be this way, because <CODE>.htaccess</CODE> files stay in the - filesystem, so processing has already been reached this stage of - processing). In other words: According to the API phases at this time it - is too late for any URL manipulations. To overcome this chicken and egg - problem mod_rewrite uses a trick: When you manipulate a URL/filename in - per-directory context mod_rewrite first rewrites the filename back to its - corresponding URL (which it usually impossible, but see the - <CODE>RewriteBase</CODE> directive below for the trick to achieve this) - and then initiates a new internal sub-request with the new URL. This leads - to a new processing of the API phases from the beginning. - <P> - Again mod_rewrite tries hard to make this complicated step totally - transparent to the user, but you should remember here: While URL - manipulations in per-server context are really fast and efficient, - per-directory rewrites are slow and inefficient due to this chicken and - egg problem. But on the other hand this is the only way mod_rewrite can - provide (locally restricted) URL manipulations to the average user. -</OL> - -<P> -Don't forget these two points! - -<H2><A NAME="InternalRuleset">Ruleset Processing</A></H2> - -Now when mod_rewrite is triggered in these two API phases, it reads the -configured rulesets from its configuration structure (which itself was either -created on startup for per-server context or while the directory walk of the -Apache kernel for per-directory context). Then the URL rewriting engine is -started with the contained ruleset (one or more rules together with their -conditions). The operation of the URL rewriting engine itself is exactly the -same for both configuration contexts. Just the final result processing is -different. - -<P> -The order of rules in the ruleset is important because the rewriting engine -processes them in a special order. And this order is not very obvious. The -rule is this: The rewriting engine loops through the ruleset rule by rule -(<CODE>RewriteRule</CODE> directives!) and when a particular rule matched it -optionally loops through existing corresponding conditions -(<CODE>RewriteCond</CODE> directives). Because of historical reasons the -conditions are given first, the control flow is a little bit winded. See -Figure 1 for more details. - -<P> -<DIV ALIGN=CENTER> -<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=0> -<TR> -<TD BGCOLOR="#CCCCCC"><IMG - SRC="../images/mod_rewrite_fig1.gif" - WIDTH="428" HEIGHT="385" - ALT="[Needs graphics capability to display]"></TD> -</TR> -<TR> -<TD ALIGN=CENTER> -<STRONG>Figure 1:</STRONG> The control flow through the rewriting ruleset -</TD> -</TR> -</TABLE> -</DIV> - -<P> -As you can see, first the URL is matched against the <EM>Pattern</EM> of each -rule. When it fails mod_rewrite immediately stops processing this rule and -continues with the next rule. If the <EM>Pattern</EM> matched, mod_rewrite -looks for corresponding rule conditions. If none are present, it just -substitutes the URL with a new value which is constructed from the string -<EM>Substitution</EM> and goes on with its rule-looping. But -if conditions exists, it starts an inner loop for processing them in order -they are listed. For conditions the logic is different: We don't match a -pattern against the current URL. Instead we first create a string -<EM>TestString</EM> by expanding variables, back-references, map lookups, -<EM>etc.</EM> and then we try to match <EM>CondPattern</EM> against it. If the -pattern doesn't match, the complete set of conditions and the corresponding -rule fails. If the pattern matches, then the next condition is processed -until no more condition is available. If all conditions matched processing is -continued with the substitution of the URL with <EM>Substitution</EM>. - -<H2><A NAME="InternalBackRefs">Regex Back-Reference Availability</A></H2> - -One important thing here has to be remembered: Whenever you -use parenthesis in <EM>Pattern</EM> or in one of the <EM>CondPattern</EM> -back-reference are internally created which can be used with the -strings <CODE>$N</CODE> and <CODE>%N</CODE> (see below). And these -are available for creating the strings <EM>Substitution</EM> and -<EM>TestCond</EM>. Figure 2 shows at which locations the back-references are -transfered to for expansion. - -<P> -<DIV ALIGN=CENTER> -<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=0> -<TR> -<TD BGCOLOR="#CCCCCC"><IMG - SRC="../images/mod_rewrite_fig2.gif" - WIDTH="381" HEIGHT="179" - ALT="[Needs graphics capability to display]"></TD> -</TR> -<TR> -<TD ALIGN=CENTER> -<STRONG>Figure 2:</STRONG> The back-reference flow through a rule -</TD> -</TR> -</TABLE> -</DIV> - -<P> -We know, this was a crash course of mod_rewrite's internal processing. But -you will benefit from this knowledge when reading the following documentation -of the available directives. - -<P> -<HR NOSHADE SIZE=1> - -<CENTER> -<H1><A NAME="Configuration">Configuration Directives</A></H1> -</CENTER> - -<P> -<HR NOSHADE SIZE=1> - -<H3><A NAME="RewriteEngine">RewriteEngine</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> - <CODE>RewriteEngine</CODE> {<CODE>on,off</CODE>}<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> - <STRONG><CODE>RewriteEngine off</CODE></STRONG><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> - server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteEngine</CODE> 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 <CODE>SCRIPT_URx</CODE> -environment variables. - -<P> -Use this directive to disable the module instead of commenting out -all <CODE>RewriteRule</CODE> directives! - -<P> -Note that, by default, rewrite configurations are not inherited. -This means that you need to have a <CODE>RewriteEngine on</CODE> -directive for each virtual host you wish to use it in. - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteOptions">RewriteOptions</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <CODE>RewriteOptions</CODE> <EM>Option</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteOptions</CODE> 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 - <CODE>.htaccess</CODE> configuration gets inherited. -</UL> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteLog">RewriteLog</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <CODE>RewriteLog</CODE> <EM>Filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteLog</CODE> 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 ('<CODE>/</CODE>') 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=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice</STRONG>: 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. <STRONG>This will slow down the server with no advantage -to the administrator!</STRONG> -To disable logging either remove or comment out the -<CODE>RewriteLog</CODE> directive or use <CODE>RewriteLogLevel 0</CODE>! -</TD></TR> -</TABLE> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Security</STRONG>: See the <A -HREF="../misc/security_tips.html">Apache Security -Tips</A> document for details on why your security could be compromised if the -directory where logfiles are stored is writable by anyone other than the user -that starts the server. -</TD></TR> -</TABLE> - -<P> -<STRONG>Example:</STRONG> -<BLOCKQUOTE> -<PRE> -RewriteLog "/usr/local/var/apache/logs/rewrite.log" -</PRE> -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteLogLevel">RewriteLogLevel</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <CODE>RewriteLogLevel</CODE> <EM>Level</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <STRONG><CODE>RewriteLogLevel 0</CODE></STRONG> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteLogLevel</CODE> 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=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> Using a high value for <EM>Level</EM> 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> -<STRONG>Example:</STRONG> -<BLOCKQUOTE> -<PRE> -RewriteLogLevel 3 -</PRE> -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteLock">RewriteLock</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <CODE>RewriteLock</CODE> <EM>Filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.3<BR> - -<P> -This directive sets the filename for a synchronization lockfile which -mod_rewrite needs to communicate with <SAMP>RewriteMap</SAMP> -<EM>programs</EM>. Set this lockfile to a local path (not on a NFS-mounted -device) when you want to use a rewriting map-program. It is not required for -all other types of rewriting maps. - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteMap">RewriteMap</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <CODE>RewriteMap</CODE> <EM>MapName </EM> - <EM>MapType</EM><CODE>:</CODE><EM>MapSource</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> not used per default<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR> - -<P> -The <CODE>RewriteMap</CODE> directive defines a <EM>Rewriting Map</EM> -which can be used inside rule substitution strings by the mapping-functions -to insert/substitute fields through a key lookup. The source of this -lookup can be of various types. -<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 one of the following constructs: - -<BLOCKQUOTE><STRONG> -<CODE>${</CODE> <EM>MapName</EM> <CODE>:</CODE> <EM>LookupKey</EM> -<CODE>}</CODE><BR> -<CODE>${</CODE> <EM>MapName</EM> <CODE>:</CODE> <EM>LookupKey</EM> -<CODE>|</CODE> <EM>DefaultValue</EM> <CODE>}</CODE> -</STRONG></BLOCKQUOTE> - -When such a construct 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 construct is substituted by <EM>SubstValue</EM>. If -the key is not found then it is substituted by <EM>DefaultValue</EM> or -the empty string if no <EM>DefaultValue</EM> was specified. - -<P> -The following combinations for <EM>MapType</EM> and <EM>MapSource</EM> -can be used: - -<UL> -<LI><STRONG>Standard Plain Text</STRONG><BR> - MapType: <CODE>txt</CODE>, MapSource: Unix filesystem path to valid regular - file - <P> - This is the standard rewriting map feature where the <EM>MapSource</EM> is - a plain ASCII file containing either blank lines, comment lines (starting - with a '#' character) or pairs like the following - one per line. - - <BLOCKQUOTE><STRONG> - <EM>MatchingKey</EM> <EM>SubstValue</EM> - </STRONG></BLOCKQUOTE> - - <P> - Example: -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> -## -## map.txt -- rewriting map -## - -Ralf.S.Engelschall rse # Bastard Operator From Hell -Mr.Joe.Average joe # Mr. Average -</PRE></TD></TR> -</TABLE> - -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> -RewriteMap real-to-user txt:/path/to/file/map.txt -</PRE></TD></TR> -</TABLE> - -<P> -<LI><STRONG>Randomized Plain Text</STRONG><BR> - MapType: <CODE>rnd</CODE>, MapSource: Unix filesystem path to valid regular - file - <P> - This is identical to the Standard Plain Text variant above but with a - special - post-processing feature: After looking up a value it is parsed according - to contained ``<CODE>|</CODE>'' characters which have the meaning of - ``or''. Or - in other words: they indicate a set of alternatives from which the actual - returned value is chosen randomly. Although this sounds crazy and useless, - it - was actually designed for load balancing in a reverse proxy situation where - the looked up values are server names. - Example: -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> -## -## map.txt -- rewriting map -## - -static www1|www2|www3|www4 -dynamic www5|www6 -</PRE></TD></TR> -</TABLE> - -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> -RewriteMap servers rnd:/path/to/file/map.txt -</PRE></TD></TR> -</TABLE> - -<P> -<LI><STRONG>Hash File</STRONG><BR> - MapType: <CODE>dbm</CODE>, MapSource: Unix filesystem path to valid - regular file - <P> - Here the source is a binary NDBM format file containing the same contents - as a <EM>Plain Text</EM> format file, but in a special representation - which is optimized for really fast lookups. You can create such a file with - any NDBM tool or with the following Perl script: - <P> - <TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> - <TR><TD><PRE> -#!/path/to/bin/perl -## -## txt2dbm -- convert txt map to dbm format -## - -($txtmap, $dbmmap) = @ARGV; -open(TXT, "<$txtmap"); -dbmopen(%DB, $dbmmap, 0644); -while (<TXT>) { - next if (m|^s*#.*| or m|^s*$|); - $DB{$1} = $2 if (m|^\s*(\S+)\s+(\S+)$|); -} -dbmclose(%DB); -close(TXT)</PRE></TD></TR> - </TABLE> - <P> - <TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> - <TR><TD><PRE>$ txt2dbm map.txt map.db </PRE></TD></TR> - </TABLE> -<P> -<LI><STRONG>Internal Function</STRONG><BR> - MapType: <CODE>int</CODE>, MapSource: Internal Apache function - <P> - Here the source is an internal Apache function. Currently you cannot - create your own, but the following functions already exists: - <UL> - <LI><STRONG>toupper</STRONG>:<BR> - Converts the looked up key to all upper case. - <LI><STRONG>tolower</STRONG>:<BR> - Converts the looked up key to all lower case. - <LI><STRONG>escape</STRONG>:<BR> - Translates special characters in the looked up key to hex-encodings. - <LI><STRONG>unescape</STRONG>:<BR> - Translates hex-encodings in the looked up key back to special characters. - </UL> -<P> -<LI><STRONG>External Rewriting Program</STRONG><BR> - MapType: <CODE>prg</CODE>, MapSource: Unix filesystem path to valid - regular file - <P> - Here the source is a Unix program, not a map file. To create it you can use - the language of your choice, but the result has to be a run-able Unix - executable (<EM>i.e.</EM>, either object-code or a script with the - magic cookie trick '<CODE>#!/path/to/interpreter</CODE>' 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 <CODE>stdin</CODE> and - <CODE>stdout</CODE> file-handles. For each map-function lookup it will - receive the key to lookup as a newline-terminated string on - <CODE>stdin</CODE>. It then has to give back the looked-up value as a - newline-terminated string on <CODE>stdout</CODE> or the four-character - string ``<CODE>NULL</CODE>'' if it fails (<EM>i.e.</EM>, there is no - corresponding value - for the given key). A trivial program which will implement a 1:1 map - (<EM>i.e.</EM>, key == value) could be: - <P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> -#!/usr/bin/perl -$| = 1; -while (<STDIN>) { - # ...here any transformations - # or lookups should occur... - print $_; -} -</PRE></TD></TR> -</TABLE> - <P> - But be very careful:<BR> - <OL> - <LI>``<EM>Keep the program simple, stupid</EM>'' (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 <CODE>stdout</CODE>! - This will cause a deadloop! Hence the ``<CODE>$|=1</CODE>'' in the - above example... - <LI>Use the <SAMP>RewriteLock</SAMP> directive to define a lockfile - mod_rewrite can use to synchronize the communication to the program. - Per default no such synchronization takes place. - </OL> -</UL> - -The <CODE>RewriteMap</CODE> directive can occur more than once. For each -mapping-function use one <CODE>RewriteMap</CODE> directive to declare its -rewriting mapfile. While you cannot <STRONG>declare</STRONG> a map in -per-directory context it is of course possible to <STRONG>use</STRONG> -this map in per-directory context. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> For plain text and DBM format files the looked-up -keys are cached in-core -until the <CODE>mtime</CODE> of the mapfile changes or the server does a -restart. This way you can have map-functions in rules which are used -for <STRONG>every</STRONG> request. This is no problem, because the -external lookup only happens once! -</TD></TR> -</TABLE> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteBase">RewriteBase</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <CODE>RewriteBase</CODE> <EM>BaseURL</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>default is the physical directory path</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>FileInfo</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteBase</CODE> directive explicitly sets the base URL for -per-directory rewrites. As you will see below, <CODE>RewriteRule</CODE> can be -used in per-directory config files (<CODE>.htaccess</CODE>). There it will act -locally, <EM>i.e.</EM>, 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. <STRONG>But at most websites URLs are -<STRONG>NOT</STRONG> directly related to physical filename paths, so this -assumption will be usually be wrong!</STRONG> There you have to use the -<CODE>RewriteBase</CODE> directive to specify the correct URL-prefix. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> If your webserver's URLs are <STRONG>not</STRONG> -directly related to physical file paths, you have to use -<CODE>RewriteBase</CODE> in every -<CODE>.htaccess</CODE> files where you want to use <CODE>RewriteRule</CODE> -directives. -</TD></TR> -</TABLE> - -<P> -<STRONG>Example:</STRONG> - -<BLOCKQUOTE> - Assume the following per-directory config file: - -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> -# -# /abc/def/.htaccess -- per-dir config file for directory /abc/def -# Remember: /abc/def is the physical path of /xyz, <EM>i.e.</EM>, the server -# has a 'Alias /xyz /abc/def' directive <EM>e.g.</EM> -# - -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 <CODE>/xyz/oldstuff.html</CODE> -gets correctly -rewritten to the physical file <CODE>/abc/def/newstuff.html</CODE>. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<FONT SIZE=-1> -<STRONG>Notice - For the Apache hackers:</STRONG><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> - -<H3><A NAME="RewriteCond">RewriteCond</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <CODE>RewriteCond</CODE> <EM>TestString</EM> - <EM>CondPattern</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>FileInfo</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR> - -<P> -The <CODE>RewriteCond</CODE> directive defines a rule condition. Precede a -<CODE>RewriteRule</CODE> directive with one or more <CODE>RewriteCond</CODE> -directives. - -The following rewriting rule is only used if its pattern matches the current -state of the URI <STRONG>and</STRONG> if these additional conditions apply -too. - -<P> -<EM>TestString</EM> is a string which can contains the following -expanded constructs in addition to plain text: - -<UL> -<LI><STRONG>RewriteRule backreferences</STRONG>: These are backreferences of - the form - -<BLOCKQUOTE><STRONG> -<CODE>$N</CODE> -</STRONG></BLOCKQUOTE> - -(1 <= N <= 9) which provide access to the grouped parts (parenthesis!) -of the -pattern from the corresponding <CODE>RewriteRule</CODE> directive (the one -following the current bunch of <CODE>RewriteCond</CODE> directives). - -<P> -<LI><STRONG>RewriteCond backreferences</STRONG>: These are backreferences of -the form - -<BLOCKQUOTE><STRONG> -<CODE>%N</CODE> -</STRONG></BLOCKQUOTE> - -(1 <= N <= 9) which provide access to the grouped parts (parenthesis!) of -the pattern from the last matched <CODE>RewriteCond</CODE> directive in the -current bunch of conditions. - -<P> -<LI><STRONG>Server-Variables</STRONG>: These are variables - of the form - -<BLOCKQUOTE><STRONG> -<CODE>%{</CODE> <EM>NAME_OF_VARIABLE</EM> <CODE>}</CODE> -</STRONG></BLOCKQUOTE> - -where <EM>NAME_OF_VARIABLE</EM> can be a string -of the following list: - -<P> -<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> -<TR> -<TD VALIGN=TOP> -<STRONG>HTTP headers:</STRONG><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> -<STRONG>connection & request:</STRONG><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> -<STRONG>server internals:</STRONG><P> -<FONT SIZE=-1> -DOCUMENT_ROOT<BR> -SERVER_ADMIN<BR> -SERVER_NAME<BR> -SERVER_ADDR<BR> -SERVER_PORT<BR> -SERVER_PROTOCOL<BR> -SERVER_SOFTWARE<BR> -</FONT> -</TD> - -<TD VALIGN=TOP> -<STRONG>system stuff:</STRONG><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> -TIME<BR> -</FONT> -</TD> - -<TD VALIGN=TOP> -<STRONG>specials:</STRONG><P> -<FONT SIZE=-1> -API_VERSION<BR> -THE_REQUEST<BR> -REQUEST_URI<BR> -REQUEST_FILENAME<BR> -IS_SUBREQ<BR> -</FONT> -</TD> -</TR> -</TABLE> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> These variables all correspond to the similar named -HTTP MIME-headers, C variables of the Apache server or <CODE>struct tm</CODE> -fields of the Unix system. -</TD></TR> -</TABLE> - -</UL> - -<P> -Special Notes: - -<OL> -<LI>The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same -value, <EM>i.e.</EM>, the value of the <CODE>filename</CODE> field of -the internal -<CODE>request_rec</CODE> 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 <CODE>uri</CODE> -field of <CODE>request_rec</CODE>). - -<P> -<LI>There is the special format: <CODE>%{ENV:variable}</CODE> where -<EM>variable</EM> can be any environment variable. This is looked-up via -internal Apache structures and (if not found there) via <CODE>getenv()</CODE> -from the Apache server process. - -<P> -<LI>There is the special format: <CODE>%{HTTP:header}</CODE> where -<EM>header</EM> can be any HTTP MIME-header name. This is looked-up -from the HTTP request. Example: <CODE>%{HTTP:Proxy-Connection}</CODE> -is the value of the HTTP header ``<CODE>Proxy-Connection:</CODE>''. - -<P> -<LI>There is the special format <CODE>%{LA-U:variable}</CODE> for look-aheads -which perform an internal (URL-based) sub-request to determine the final value -of <EM>variable</EM>. Use this when you want to use a variable for rewriting -which actually is set later in an API phase and thus is not available at the -current stage. For instance when you want to rewrite according to the -<CODE>REMOTE_USER</CODE> variable from within the per-server context -(<CODE>httpd.conf</CODE> file) you have to use <CODE>%{LA-U:REMOTE_USER}</CODE> -because this variable is set by the authorization phases which come -<EM>after</EM> the URL translation phase where mod_rewrite operates. On the -other hand, because mod_rewrite implements its per-directory context -(<CODE>.htaccess</CODE> file) via the Fixup phase of the API and because the -authorization phases come <EM>before</EM> this phase, you just can use -<CODE>%{REMOTE_USER}</CODE> there. - -<P> -<LI>There is the special format: <CODE>%{LA-F:variable}</CODE> which perform an -internal (filename-based) sub-request to determine the final value of -<EM>variable</EM>. This is the most of the time the same as LA-U above. -</OL> - -<P> -<EM>CondPattern</EM> is the condition pattern, <EM>i.e.</EM>, a regular -expression -which gets applied to the current instance of the <EM>TestString</EM>, -<EM>i.e.</EM>, <EM>TestString</EM> gets evaluated and then matched against -<EM>CondPattern</EM>. - -<P> -<STRONG>Remember:</STRONG> <EM>CondPattern</EM> is a standard -<EM>Extended Regular Expression</EM> with some additions: - -<OL> -<LI>You can precede the pattern string with a '<CODE>!</CODE>' character -(exclamation mark) to specify a <STRONG>non</STRONG>-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>'<STRONG><CondPattern</STRONG>' (is lexicographically lower)<BR> -Treats the <EM>CondPattern</EM> as a plain string and compares it -lexicographically to <EM>TestString</EM> and results in a true expression if -<EM>TestString</EM> is lexicographically lower than <EM>CondPattern</EM>. -<P> -<LI>'<STRONG>>CondPattern</STRONG>' (is lexicographically greater)<BR> -Treats the <EM>CondPattern</EM> as a plain string and compares it -lexicographically to <EM>TestString</EM> and results in a true expression if -<EM>TestString</EM> is lexicographically greater than <EM>CondPattern</EM>. -<P> -<LI>'<STRONG>=CondPattern</STRONG>' (is lexicographically equal)<BR> -Treats the <EM>CondPattern</EM> as a plain string and compares it -lexicographically to <EM>TestString</EM> and results in a true expression if -<EM>TestString</EM> is lexicographically equal to <EM>CondPattern</EM>, i.e the -two strings are exactly equal (character by character). -If <EM>CondPattern</EM> is just <SAMP>""</SAMP> (two quotation marks) this -compares <EM>TestString</EM> against the empty string. -<P> -<LI>'<STRONG>-d</STRONG>' (is <STRONG>d</STRONG>irectory)<BR> -Treats the <EM>TestString</EM> as a pathname and -tests if it exists and is a directory. -<P> -<LI>'<STRONG>-f</STRONG>' (is regular <STRONG>f</STRONG>ile)<BR> -Treats the <EM>TestString</EM> as a pathname and -tests if it exists and is a regular file. -<P> -<LI>'<STRONG>-s</STRONG>' (is regular file with <STRONG>s</STRONG>ize)<BR> -Treats the <EM>TestString</EM> as a pathname and -tests if it exists and is a regular file with size greater than zero. -<P> -<LI>'<STRONG>-l</STRONG>' (is symbolic <STRONG>l</STRONG>ink)<BR> -Treats the <EM>TestString</EM> as a pathname and -tests if it exists and is a symbolic link. -<P> -<LI>'<STRONG>-F</STRONG>' (is existing file via subrequest)<BR> -Checks if <EM>TestString</EM> is a valid file and accessible via all the -server's currently-configured access controls for that path. This uses an -internal subrequest to determine the check, so use it with care because it -decreases your servers performance! -<P> -<LI>'<STRONG>-U</STRONG>' (is existing URL via subrequest)<BR> -Checks if <EM>TestString</EM> is a valid URL and accessible via all the -server's -currently-configured access controls for that path. This uses an internal -subrequest to determine the check, so use it with care because it decreases -your server's performance! -</UL> -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> -All of these tests can also be prefixed by a not ('!') character -to negate their meaning. -</TD></TR> -</TABLE> -</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 <CODE>RewriteCond</CODE> directive. <EM>Flags</EM> -is a comma-separated list of the following flags: - -<UL> -<LI>'<STRONG><CODE>nocase|NC</CODE></STRONG>' (<STRONG>n</STRONG>o <STRONG>c</STRONG>ase)<BR> - This makes the condition test case-insensitive, <EM>i.e.</EM>, 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>' (<STRONG>or</STRONG> 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. -</UL> - -<P> -<STRONG>Example:</STRONG> -<BLOCKQUOTE> - -To rewrite the Homepage of a site according to the ``<CODE>User-Agent:</CODE>'' -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, <EM>etc.</EM> If you use the Lynx browser (which is Terminal-based), then you -get the min homepage, which contains no images, no tables, <EM>etc.</EM> If you -use any other browser you get the standard homepage. -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteRule">RewriteRule</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <CODE>RewriteRule</CODE> <EM>Pattern</EM> <EM>Substitution</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>FileInfo</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR> - -<P> -The <CODE>RewriteRule</CODE> directive is the real rewriting workhorse. The -directive can occur more than once. Each directive then defines one single -rewriting rule. The <STRONG>definition order</STRONG> of these rules is -<STRONG>important</STRONG>, 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="#F0F0F0" CELLSPACING=0 CELLPADDING=5> -<TR> -<TD VALIGN=TOP> -<PRE> -<STRONG>Text:</STRONG> - <STRONG><CODE>.</CODE></STRONG> Any single character - <STRONG><CODE>[</CODE></STRONG>chars<STRONG><CODE>]</CODE></STRONG> Character class: One of chars - <STRONG><CODE>[^</CODE></STRONG>chars<STRONG><CODE>]</CODE></STRONG> Character class: None of chars - text1<STRONG><CODE>|</CODE></STRONG>text2 Alternative: text1 or text2 - -<STRONG>Quantifiers:</STRONG> - <STRONG><CODE>?</CODE></STRONG> 0 or 1 of the preceding text - <STRONG><CODE>*</CODE></STRONG> 0 or N of the preceding text (N > 1) - <STRONG><CODE>+</CODE></STRONG> 1 or N of the preceding text (N > 1) - -<STRONG>Grouping:</STRONG> - <STRONG><CODE>(</CODE></STRONG>text<STRONG><CODE>)</CODE></STRONG> Grouping of text - (either to set the borders of an alternative or - for making backreferences where the <STRONG>N</STRONG>th group can - be used on the RHS of a RewriteRule with <CODE>$</CODE><STRONG>N</STRONG>) - -<STRONG>Anchors:</STRONG> - <STRONG><CODE>^</CODE></STRONG> Start of line anchor - <STRONG><CODE>$</CODE></STRONG> End of line anchor - -<STRONG>Escaping:</STRONG> - <STRONG><CODE>\</CODE></STRONG>char escape that particular char - (for instance to specify the chars "<CODE>.[]()</CODE>" <EM>etc.</EM>) -</PRE> -</TD> -</TR> -</TABLE> - -<P> -For more information about regular expressions either have a look at your -local regex(3) manpage or its <CODE>src/regex/regex.3</CODE> copy in the -Apache 1.3 distribution. When you are interested in more detailed and deeper -information about regular expressions and its variants (POSIX regex, Perl -regex, <EM>etc.</EM>) have a look at the following dedicated book on this topic: - -<BLOCKQUOTE> -<EM>Mastering Regular Expressions</EM><BR> -Jeffrey E.F. Friedl<BR> -Nutshell Handbook Series<BR> -O'Reilly & Associates, Inc. 1997<BR> -ISBN 1-56592-257-3<BR> -</BLOCKQUOTE> - -<P> -Additionally in mod_rewrite the NOT character ('<CODE>!</CODE>') is a possible -pattern prefix. This gives you the ability to negate a pattern; to say, for -instance: ``<EM>if the current URL does <STRONG>NOT</STRONG> match to this -pattern</EM>''. 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=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> 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 <CODE>$N</CODE> 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>back-references <CODE>$N</CODE> to the RewriteRule pattern -<LI>back-references <CODE>%N</CODE> to the last matched RewriteCond pattern -<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><STRONG>N</STRONG> (<STRONG>N</STRONG>=1..9) identifiers which -will be replaced by the contents of the <STRONG>N</STRONG>th group of the matched -<EM>Pattern</EM>. The server-variables are the same as for the -<EM>TestString</EM> of a <CODE>RewriteCond</CODE> directive. The -mapping-functions come from the <CODE>RewriteMap</CODE> 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 <STRONG>completely replaced</STRONG> by the <EM>Substitution</EM> and the -rewriting process goes on until there are no more rules (unless explicitly -terminated by a <CODE><STRONG>L</STRONG></CODE> flag - see below). - -<P> -There is a special substitution string named '<CODE>-</CODE>' which means: -<STRONG>NO substitution</STRONG>! Sounds silly? No, it is useful to provide rewriting -rules which <STRONG>only</STRONG> match some URLs but do no substitution, <EM>e.g.</EM>, in -conjunction with the <STRONG>C</STRONG> (chain) flag to be able to have more than one -pattern to be applied before a substitution occurs. - -<P> -One more note: You can even create URLs in the substitution string containing -a query string part. Just use a question mark inside the substitution string -to indicate that the following stuff should be re-injected into the -QUERY_STRING. When you want to erase an existing query string, end the -substitution string with just the question mark. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice</STRONG>: There is a special feature. When you prefix a substitution -field with <CODE>http://</CODE><EM>thishost</EM>[<EM>:thisport</EM>] then -<STRONG>mod_rewrite</STRONG> 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. -</TD></TR> -</TABLE> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Remember:</STRONG> An unconditional external redirect to your own server will -not work with the prefix <CODE>http://thishost</CODE> because of this feature. -To achieve such a self-redirect, you have to use the <STRONG>R</STRONG>-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 <CODE>RewriteRule</CODE> directive. <EM>Flags</EM> is a -comma-separated list of the following flags: - -<UL> -<LI>'<STRONG><CODE>redirect|R</CODE> [=<EM>code</EM>]</STRONG>' (force <A NAME="redirect"><STRONG>r</STRONG>edirect</A>)<BR> - Prefix <EM>Substitution</EM> - with <CODE>http://thishost[:thisport]/</CODE> (which makes the new URL a URI) to - force a external redirection. If no <EM>code</EM> is given a HTTP response - of 302 (MOVED TEMPORARILY) is used. If you want to use other response - codes in the range 300-400 just specify them as a number or use - one of the following symbolic names: <CODE>temp</CODE> (default), <CODE>permanent</CODE>, - <CODE>seeother</CODE>. - Use it for rules which should - canonicalize the URL and gives it back to the client, <EM>e.g.</EM>, translate - ``<CODE>/~</CODE>'' into ``<CODE>/u/</CODE>'' or always append a slash to - <CODE>/u/</CODE><EM>user</EM>, etc.<BR> - <P> - <STRONG>Notice:</STRONG> When you use this flag, make sure that the - substitution field is a valid URL! If not, you are redirecting to an - invalid location! And remember that this flag itself only prefixes the - URL with <CODE>http://thishost[:thisport]/</CODE>, but rewriting goes on. - Usually you also want to stop and do the redirection immediately. To stop - the rewriting you also have to provide the 'L' flag. -<P> -<LI>'<STRONG><CODE>forbidden|F</CODE></STRONG>' (force URL to be <STRONG>f</STRONG>orbidden)<BR> - This forces the current URL to be forbidden, <EM>i.e.</EM>, it immediately sends - back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with - appropriate RewriteConds to conditionally block some URLs. -<P> -<LI>'<STRONG><CODE>gone|G</CODE></STRONG>' (force URL to be <STRONG>g</STRONG>one)<BR> - This forces the current URL to be gone, <EM>i.e.</EM>, it immediately sends back a - HTTP response of 410 (GONE). Use this flag to mark no longer existing - pages as gone. -<P> -<LI>'<STRONG><CODE>proxy|P</CODE></STRONG>' (force <STRONG>p</STRONG>roxy)<BR> - This flag forces the substitution part to be internally forced as a proxy - request and immediately (<EM>i.e.</EM>, rewriting rule processing stops here) put - through the <A HREF="mod_proxy.html">proxy module</A>. You have to make - sure that the substitution string is a valid URI (<EM>e.g.</EM>, typically starting - with <CODE>http://</CODE><EM>hostname</EM>) 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 <A - HREF="mod_proxy.html#proxypass">ProxyPass</A> directive, to map some - remote stuff into the namespace of the local server. - <P> - Notice: To use this functionality make sure you have the proxy module - compiled into your Apache server program. If you don't know please check - whether <CODE>mod_proxy.c</CODE> is part of the ``<CODE>httpd -l</CODE>'' - output. If yes, this functionality is available to mod_rewrite. If not, - then you first have to rebuild the ``<CODE>httpd</CODE>'' program with - mod_proxy enabled. -<P> -<LI>'<STRONG><CODE>last|L</CODE></STRONG>' (<STRONG>l</STRONG>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, <EM>e.g.</EM>, '<CODE>/e/www/</CODE>'. -<P> -<LI>'<STRONG><CODE>next|N</CODE></STRONG>' (<STRONG>n</STRONG>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, <EM>i.e.</EM>, to - immediately go to the top of the loop. <BR> - <STRONG>But be careful not to create a deadloop!</STRONG> -<P> -<LI>'<STRONG><CODE>chain|C</CODE></STRONG>' (<STRONG>c</STRONG>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, <EM>etc.</EM>). This has the following - effect: if a rule matches, then processing continues as usual, <EM>i.e.</EM>, the - flag has no effect. If the rule does <STRONG>not</STRONG> match, then all following - chained rules are skipped. For instance, use it to remove the - ``<CODE>.www</CODE>'' part inside a per-directory rule set when you let an - external redirect happen (where the ``<CODE>.www</CODE>'' part should not to - occur!). -<P> -<LI>'<STRONG><CODE>type|T</CODE></STRONG>=<EM>MIME-type</EM>' (force MIME <STRONG>t</STRONG>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 <CODE>mod_alias</CODE> - directive <CODE>ScriptAlias</CODE> which internally forces all files inside - the mapped directory to have a MIME type of - ``<CODE>application/x-httpd-cgi</CODE>''. -<P> -<LI>'<STRONG><CODE>nosubreq|NS</CODE></STRONG>' (used only if <STRONG>n</STRONG>o internal <STRONG>s</STRONG>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 <CODE>mod_include</CODE> tries to find out - information about possible directory default files (<CODE>index.xxx</CODE>). - 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>nocase|NC</CODE></STRONG>' (<STRONG>n</STRONG>o <STRONG>c</STRONG>ase)<BR> - This makes the <EM>Pattern</EM> case-insensitive, <EM>i.e.</EM>, there is - no difference between 'A-Z' and 'a-z' when <EM>Pattern</EM> is matched - against the current URL. -<P> -<LI>'<STRONG><CODE>qsappend|QSA</CODE></STRONG>' (<STRONG>q</STRONG>uery <STRONG>s</STRONG>tring - <STRONG>a</STRONG>ppend)<BR> - This flag forces the rewriting engine to append a query - string part in the substitution string to the existing one instead of - replacing it. Use this when you want to add more data to the query string - via a rewrite rule. -<P> -<LI>'<STRONG><CODE>passthrough|PT</CODE></STRONG>' (<STRONG>p</STRONG>ass <STRONG>t</STRONG>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 <CODE>RewriteRule</CODE> directives by - <CODE>Alias</CODE>, <CODE>ScriptAlias</CODE>, <CODE>Redirect</CODE>, <EM>etc.</EM> directives - from other URI-to-filename translators. A trivial example to show the - semantics: - If you want to rewrite <CODE>/abc</CODE> to <CODE>/def</CODE> via the rewriting - engine of <CODE>mod_rewrite</CODE> and then <CODE>/def</CODE> to <CODE>/ghi</CODE> - with <CODE>mod_alias</CODE>: - <PRE> - RewriteRule ^/abc(.*) /def$1 [PT] - Alias /def /ghi - </PRE> - If you omit the <CODE>PT</CODE> flag then <CODE>mod_rewrite</CODE> - will do its job fine, <EM>i.e.</EM>, it rewrites <CODE>uri=/abc/...</CODE> to - <CODE>filename=/def/...</CODE> as a full API-compliant URI-to-filename - translator should do. Then <CODE>mod_alias</CODE> comes and tries to do a - URI-to-filename transition which will not work. - <P> - Notice: <STRONG>You have to use this flag if you want to intermix directives - of different modules which contain URL-to-filename translators</STRONG>. The - typical example is the use of <CODE>mod_alias</CODE> and - <CODE>mod_rewrite</CODE>.. -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<font size=-1> - <STRONG>Notice - For the Apache hackers:</STRONG><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>' (<STRONG>s</STRONG>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 <CODE>skip=N</CODE> where N is the number of rules in the else-clause. - (This is <STRONG>not</STRONG> the same as the 'chain|C' flag!) -<P> -<LI>'<STRONG><CODE>env|E=</CODE></STRONG><EM>VAR</EM>:<EM>VAL</EM>' (set <STRONG>e</STRONG>nvironment variable)<BR> - This forces an environment variable named <EM>VAR</EM> to be set to the - value <EM>VAL</EM>, where <EM>VAL</EM> can contain regexp backreferences - <CODE>$N</CODE> and <CODE>%N</CODE> which will be expanded. You can use this flag - more than once to set more than one variable. The variables can be later - dereferenced at a lot of situations, but the usual location will be from - within XSSI (via <CODE><!--#echo var="VAR"--></CODE>) or CGI (<EM>e.g.</EM> - <CODE>$ENV{'VAR'}</CODE>). But additionally you can also dereference it in a - following RewriteCond pattern via <CODE>%{ENV:VAR}</CODE>. Use this to strip - but remember information from URLs. -</UL> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> Never forget that <EM>Pattern</EM> gets applied to a complete URL -in per-server configuration files. <STRONG>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.</STRONG> 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 -``<CODE>http://</CODE>'' then the directory prefix will be <STRONG>not</STRONG> added and a -external redirect or proxy throughput (if flag <STRONG>P</STRONG> is used!) is forced! -</TD></TR> -</TABLE> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> To enable the rewriting engine for per-directory configuration files -you need to set ``<CODE>RewriteEngine On</CODE>'' in these files <STRONG>and</STRONG> -``<CODE>Option FollowSymLinks</CODE>'' enabled. If your administrator has -disabled override of <CODE>FollowSymLinks</CODE> 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> -<STRONG>Inside per-server configuration (<CODE>httpd.conf</CODE>)<BR> -for request ``<CODE>GET /somepath/pathinfo</CODE>'':</STRONG><BR> - -<P> -<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> -<TR> -<TD> -<PRE> -<STRONG>Given Rule</STRONG> <STRONG>Resulting Substitution</STRONG> ----------------------------------------------- ---------------------------------- -^/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> -<STRONG>Inside per-directory configuration for <CODE>/somepath</CODE><BR> -(<EM>i.e.</EM>, file <CODE>.htaccess</CODE> in dir <CODE>/physical/path/to/somepath</CODE> containing -<CODE>RewriteBase /somepath</CODE>)<BR> for -request ``<CODE>GET /somepath/localpath/pathinfo</CODE>'':</STRONG><BR> - -<P> -<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> -<TR> -<TD> -<PRE> -<STRONG>Given Rule</STRONG> <STRONG>Resulting Substitution</STRONG> ----------------------------------------------- ---------------------------------- -^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> - -<P> -<STRONG>Example:</STRONG> -<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>/path/to/file/map.txt</CODE>. Then we only have to add the -following lines to the Apache server configuration file: - -<BLOCKQUOTE> -<PRE> -RewriteLog /path/to/file/rewrite.log -RewriteMap real-to-user txt:/path/to/file/map.txt -RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1 -</PRE> -</BLOCKQUOTE> - -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> - -<CENTER> -<H1><A NAME="Miscelleneous">Miscellaneous</A></H1> -</CENTER> - -<P> -<HR NOSHADE SIZE=1> - -<H2><A NAME="EnvVar">Environment Variables</A></H2> - -This module keeps track of two additional (non-standard) CGI/SSI environment -variables named <CODE>SCRIPT_URL</CODE> and <CODE>SCRIPT_URI</CODE>. These contain -the <EM>logical</EM> Web-view to the current resource, while the standard CGI/SSI -variables <CODE>SCRIPT_NAME</CODE> and <CODE>SCRIPT_FILENAME</CODE> contain the -<EM>physical</EM> System-view. - -<P> -Notice: These variables hold the URI/URL <EM>as they were initially -requested</EM>, <EM>i.e.</EM>, in a state <EM>before</EM> any rewriting. This is -important because the rewriting process is primarily used to rewrite logical -URLs to physical pathnames. - -<P> -<STRONG>Example:</STRONG> - -<BLOCKQUOTE> -<PRE> -SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html -SCRIPT_FILENAME=/u/rse/.www/index.html -SCRIPT_URL=/u/rse/ -SCRIPT_URI=http://en1.engelschall.com/u/rse/ -</PRE> -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> - -<H2><A NAME="Solutions">Practical Solutions</A></H2> - -There is a comprehensive collection of practical solutions for URL-based -problems available by the author of mod_rewrite. Here you will find real-life -rulesets and additional information. - -<BLOCKQUOTE> -<STRONG>Apache URL Rewriting Guide</STRONG><BR> -<STRONG><A HREF="http://www.engelschall.com/pw/apache/rewriteguide/" - >http://www.engelschall.com/pw/apache/rewriteguide/</A></STRONG> -</BLOCKQUOTE> - -<!--#include virtual="footer.html" --> -</BLOCKQUOTE><!-- page indentation --> -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_setenvif.html b/docs/manual/mod/mod_setenvif.html deleted file mode 100644 index 868a1106ae..0000000000 --- a/docs/manual/mod/mod_setenvif.html +++ /dev/null @@ -1,398 +0,0 @@ -<!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> - <P>The directives are considered in the order they appear in the - configuration files. So more complex sequences can be used, such - as this example, which sets <CODE>netscape</CODE> if the browser - is mozilla but not MSIE. - <BLOCKQUOTE><PRE> - BrowserMatch ^Mozilla netscape - BrowserMatch MSIE !netscape - </PRE></BLOCKQUOTE> - </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> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> BrowserMatch <EM>regex envar[=value] [...]</EM> - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>none</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>none</EM> - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Base - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_setenvif - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above (in Apache 1.2 - this directive was found in the now-obsolete mod_browser module) - </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> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> BrowserMatchNoCase <EM>regex envar[=value] - [...]</EM> - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>none</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>none</EM> - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Base - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_setenvif - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above (in Apache 1.2 - this directive was found in the now-obsolete mod_browser module) - </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> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> SetEnvIf <EM> attribute regex envar[=value] - [...]</EM> - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>none</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>none</EM> - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Base - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_setenvif - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> Apache 1.3 and above; the - Request_Protocol keyword and environment-variable matching are only - available with 1.3.7 and later - </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_Protocol</SAMP> - the name and version of the protocol - with which the request was made (<EM>e.g.</EM>, "HTTP/0.9", "HTTP/1.1", - <EM>etc.</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> - If the <EM>attribute</EM> name doesn't match any of the special keywords, - nor any of the request's header field names, it is tested as the name - of an environment variable in the list of those associated with the request. - This allows <CODE>SetEnvIf</CODE> directives to test against the result - of prior matches. - </P> - <BLOCKQUOTE> - <STRONG>Only those environment variables defined by earlier - <CODE>SetEnvIf[NoCase]</CODE> directives are available for testing in - this manner. 'Earlier' means that they were defined at a broader scope - (such as server-wide) or previously in the current directive's - scope.</STRONG> - </BLOCKQUOTE> - <P> - Example: - </P> - <PRE> - SetEnvIf Request_URI "\.gif$" object_is_image=gif - SetEnvIf Request_URI "\.jpg$" object_is_image=jpg - SetEnvIf Request_URI "\.xbm$" object_is_image=xbm - : - SetEnvIf Referer www\.mydomain\.com intra_site_referral - : - SetEnvIf object_is_image xbm XBIT_PROCESSING=1 - </PRE> - <P> - The first three will set the envariable <SAMP>object_is_image</SAMP> if the - request was for an image file, and the fourth 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> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> SetEnvIfNoCase - <EM> attribute regex envar[=value] [...]</EM> - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>none</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>none</EM> - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Base - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_setenvif - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> 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> diff --git a/docs/manual/mod/mod_so.html b/docs/manual/mod/mod_so.html deleted file mode 100644 index 6edd1a4fb3..0000000000 --- a/docs/manual/mod/mod_so.html +++ /dev/null @@ -1,164 +0,0 @@ -<!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. It is -compiled in by default on Windows and is not compiled in by default on -Unix. It provides for loading of executable code and modules into the -server at start-up or restart time. On Unix, the loaded code typically -comes from shared object files (usually with <SAMP>.so</SAMP> -extension), whilst on Windows this module loads <SAMP>DLL</SAMP> -files. This module is only available in Apache 1.3 and up. - -<P> - -In previous releases, the functionality of this module was provided -for Unix by mod_dld, and for Windows by mod_dll. On Windows, mod_dll -was used in beta release 1.3b1 through 1.3b5. mod_so combines these -two modules into a single module for all operating systems. - -<H2>Summary</H2> - -This is an experimental module. On selected operating systems it can be used -to load modules into Apache at runtime via the <A HREF="../dso.html">Dynamic -Shared Object</A> (DSO) mechanism, 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> Base<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 or restarted; this is used to load -additional code which may be required for some module to -work. <EM>Filename</EM> is either and absolute path or 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> Base<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 (Unix): -<BLOCKQUOTE><CODE> -LoadModule status_module modules/mod_status.so -</CODE></BLOCKQUOTE> - -<P> - -Example (Windows): -<BLOCKQUOTE><CODE> -LoadModule status_module modules/ApacheModuleStatus.dll<BR> -</CODE></BLOCKQUOTE> - -loads the named module from the modules subdirectory of the -ServerRoot.<P> - -<HR> - -<H2><A NAME="creating">Creating DLL Modules for Windows</A></H2> - -<P>The Apache module API is unchanged between the Unix and Windows - versions. Many modules will run on Windows with no or little change - from Unix, although others rely on aspects of the Unix architecture - which are not present in Windows, and will not work.</P> - -<P>When a module does work, it can be added to the server in one of two - ways. As with Unix, it can be compiled into the server. Because Apache - for Windows does not have the <CODE>Configure</CODE> program of Apache - for Unix, the module's source file must be added to the ApacheCore - project file, and its symbols must be added to the - <CODE>os\win32\modules.c</CODE> file.</P> - -<P>The second way is to compile the module as a DLL, a shared library - that can be loaded into the server at runtime, using the - <CODE><A HREF="#loadmodule">LoadModule</A></CODE> - directive. These module DLLs can be distributed and run on any Apache - for Windows installation, without recompilation of the server.</P> - -<P>To create a module DLL, a small change is necessary to the module's - source file: The module record must be exported from the DLL (which - will be created later; see below). To do this, add the - <CODE>MODULE_VAR_EXPORT</CODE> (defined in the Apache header files) to - your module's module record definition. For example, if your module - has:</P> -<PRE> - module foo_module; -</PRE> -<P>Replace the above with:</P> -<PRE> - module MODULE_VAR_EXPORT foo_module; -</PRE> -<P>Note that this will only be activated on Windows, so the module can - continue to be used, unchanged, with Unix if needed. Also, if you are - familiar with <CODE>.DEF</CODE> files, you can export the module - record with that method instead.</P> - -<P>Now, create a DLL containing your module. You will need to link this - against the ApacheCore.lib export library that is created when the - ApacheCore.dll shared library is compiled. You may also have to change - the compiler settings to ensure that the Apache header files are - correctly located.</P> - -<P>This should create a DLL version of your module. Now simply place it - in the <SAMP>modules</SAMP> directory of your server root, and use - the <CODE><A HREF="#loadmodule">LoadModule</A></CODE> directive to - load it.</P> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_speling.html b/docs/manual/mod/mod_speling.html deleted file mode 100644 index 3be9f8000b..0000000000 --- a/docs/manual/mod/mod_speling.html +++ /dev/null @@ -1,122 +0,0 @@ -<!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 attempts to correct misspellings 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 --> - <H2><A NAME="checkspelling">CheckSpelling</A></H2> - <!--%plaintext <?INDEX {\tt CheckSpelling} directive> --> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> CheckSpelling <EM>on/off</EM><BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <CODE>CheckSpelling Off</CODE><BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, - directory, .htaccess<BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> Options - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Base<BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_speling<BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> 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. Prior to - Apache 1.3.2, the <SAMP>CheckSpelling</SAMP> directive was only available - in the "server" and "virtual host" contexts. - <P> - This directive enables or disables the spelling module. When enabled, - keep in mind that - </P> - <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> - <LI>the document trees should not contain sensitive files which could - be matched inadvertently by a spelling "correction". - </LI> - <LI>the module is unable to correct misspelled user names - (as in <CODE>http://my.host/~apahce/</CODE>), just file names or - directory names. - </LI> - <LI>spelling corrections apply strictly to existing files, so a request for - the <SAMP><Location /status></SAMP> may get incorrectly treated - as the negotiated file "<SAMP>/stats.html</SAMP>". - </LI> - </UL> - -<!--#include virtual="footer.html" --> - </BODY> -</HTML> - diff --git a/docs/manual/mod/mod_status.html b/docs/manual/mod/mod_status.html deleted file mode 100644 index ccfabe1a83..0000000000 --- a/docs/manual/mod/mod_status.html +++ /dev/null @@ -1,131 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_status</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> - -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_status</H1> - -The Status Module is only available in Apache 1.1 and later.<P> - -<H2>Function</H2> - -The Status module allows a server administrator to find out how well -their server is performing. A HTML page is presented that gives -the current server statistics in an easily readable form. If required -this page can be made to automatically refresh (given a compatible -browser). Another page gives a simple machine-readable list of the current -server state. -<P> -The details given are: -<UL> -<LI>The number of children serving requests -<LI>The number of idle children -<LI>The status of each child, the number of requests that child has -performed and the total number of bytes served by the child (*) -<LI>A total number of accesses and byte count served (*) -<LI>The time the server was started/restarted and the -time it has been running for -<LI>Averages giving the number of requests per second, -the number of bytes served per second and the average number -of bytes per request (*) -<LI>The current percentage CPU used by each child and in total by -Apache (*) -<LI>The current hosts and requests being processed (*) -</UL> - -A compile-time option must be used to display the details marked "(*)" as -the instrumentation required for obtaining these statistics does not -exist within standard Apache. - -<H2><A NAME="extendedstatus">ExtendedStatus directive</A></H2> -<!--%plaintext <?INDEX {\tt ExtendedStatus} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ExtendedStatus <EM>On|Off</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ExtendedStatus Off</CODE><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> Base<BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_status<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ExtendedStatus is only available - in Apache 1.3.2 and later. - -<P> -This directive controls whether the server keeps track of extended -status information for each request. This is only useful if the status module -is enabled on the server. -</P> -<P> -This setting applies to the entire server, and cannot be enabled or -disabled on a virtualhost-by-virtualhost basis. -</P> - -<H2>Enabling Status Support</H2> - -To enable status reports only for browsers from the foo.com -domain add this code to your <CODE>access.conf</CODE> configuration file -<PRE> - <Location /server-status> - SetHandler server-status - - order deny,allow - deny from all - allow from .foo.com - </Location> -</PRE> -<P> -You can now access server statistics by using a Web browser to access the -page <CODE>http://your.server.name/server-status</CODE> -<P> -Note that mod_status will only work when you are running Apache in -<A HREF="core.html#servertype">standalone</A> mode and not -<A HREF="core.html#servertype">inetd</A> mode. - -<H3>Automatic Updates</H3> -You can get the status page to update itself automatically if you have -a browser that supports "refresh". Access the page -<CODE>http://your.server.name/server-status?refresh=N</CODE> to refresh the -page every N seconds. -<H3>Machine Readable Status File</H3> -A machine-readable version of the status file is available by accessing the -page <CODE>http://your.server.name/server-status?auto</CODE>. This is useful -when automatically run, see the Perl program in the <CODE>/support</CODE> -directory of Apache, <CODE>log_server_status</CODE>. - -<BLOCKQUOTE> - <STRONG> - It should be noted that if <SAMP>mod_status</SAMP> is compiled into - the server, its handler capability is available in <EM>all</EM> - configuration files, including <EM>per</EM>-directory files - (<EM>e.g.</EM>, <SAMP>.htaccess</SAMP>). This may have - security-related ramifications for your site. - </STRONG> -</BLOCKQUOTE> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_unique_id.html b/docs/manual/mod/mod_unique_id.html deleted file mode 100644 index c9c4d3afe9..0000000000 --- a/docs/manual/mod/mod_unique_id.html +++ /dev/null @@ -1,180 +0,0 @@ -<!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 <EM>( ip_addr, pid, time_stamp, -counter )</EM> 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 (<EM>i.e.</EM>, 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 <EM>flag second</EM> 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> diff --git a/docs/manual/mod/mod_userdir.html b/docs/manual/mod/mod_userdir.html deleted file mode 100644 index 570b1b042a..0000000000 --- a/docs/manual/mod/mod_userdir.html +++ /dev/null @@ -1,123 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_userdir</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_userdir</H1> - -This module is contained in the <CODE>mod_userdir.c</CODE> file, and -is compiled in by default. It provides for user-specific directories. - - -<UL> -<LI><A HREF="#userdir">UserDir</A> -</UL> -<HR> - - -<H2><A NAME="userdir">UserDir</A></H2> -<!--%plaintext <?INDEX {\tt UserDir} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> UserDir <EM>directory/filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>UserDir public_html</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_userdir<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> All forms except the <CODE>UserDir -public_html</CODE> form are only available in Apache 1.1 or above. Use -of the <SAMP>enabled</SAMP> keyword, or <SAMP>disabled</SAMP> with a -list of usernames, is only available in Apache 1.3 and above.<P> - -The UserDir directive sets the real directory in a user's home directory -to use when a request for a document for a user is received. -<EM>Directory/filename</EM> is one of the following: -</P> -<UL> - <LI>The name of a directory or a pattern such as those shown below. - </LI> - <LI>The keyword <SAMP>disabled</SAMP>. This turns off <EM>all</EM> - username-to-directory translations except those explicitly named with - the <SAMP>enabled</SAMP> keyword (see below). - </LI> - <LI>The keyword <SAMP>disabled</SAMP> followed by a space-delimited - list of usernames. Usernames that appear in such a list will - <EM>never</EM> have directory translation performed, even if they - appear in an <SAMP>enabled</SAMP> clause. - </LI> - <LI>The keyword <SAMP>enabled</SAMP> followed by a space-delimited list - of usernames. These usernames will have directory translation - performed even if a global disable is in effect, but not if they also - appear in a <SAMP>disabled</SAMP> clause. - </LI> -</UL> -<P> -If neither the <SAMP>enabled</SAMP> nor the <SAMP>disabled</SAMP> -keywords appear in the <SAMP>Userdir</SAMP> directive, the argument is -treated as a filename pattern, and is used to turn the name into a -directory specification. A request for -<CODE>http://www.foo.com/~bob/one/two.html</CODE> will be translated to: -<PRE> -UserDir public_html -> ~bob/public_html/one/two.html -UserDir /usr/web -> /usr/web/bob/one/two.html -UserDir /home/*/www -> /home/bob/www/one/two.html -</PRE> -The following directives will send redirects to the client: -<PRE> -UserDir http://www.foo.com/users -> http://www.foo.com/users/bob/one/two.html -UserDir http://www.foo.com/*/usr -> http://www.foo.com/bob/usr/one/two.html -UserDir http://www.foo.com/~*/ -> http://www.foo.com/~bob/one/two.html -</PRE> -</P> -<BLOCKQUOTE> - <STRONG> - Be careful when using this directive; for instance, - <SAMP>"UserDir ./"</SAMP> would map - <SAMP>"/~root"</SAMP> to - <SAMP>"/"</SAMP> - which is probably undesirable. If you are - running Apache 1.3 or above, it is strongly recommended that your - configuration include a - "<SAMP>UserDir disabled root</SAMP>" declaration. - See also - the - <A - HREF="core.html#directory" - ><Directory></A> - directive and the - <A - HREF="../misc/security_tips.html" - >Security Tips</A> - page for more information. - </STRONG> -</BLOCKQUOTE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_usertrack.html b/docs/manual/mod/mod_usertrack.html deleted file mode 100644 index 87d81ac0f6..0000000000 --- a/docs/manual/mod/mod_usertrack.html +++ /dev/null @@ -1,199 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_usertrack</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_usertrack</H1> - -Previous releases of Apache have included a module which generates a -'clickstream' log of user activity on a site using cookies. This was -called the "cookies" module, mod_cookies. In Apache 1.2 and later this -module has been renamed the "user tracking" module, -mod_usertrack. This module has been simplified and new directives -added. - -<HR> - -<H2>Logging</H2> - -Previously, the cookies module (now the user tracking module) did its -own logging, using the <TT>CookieLog</TT> directive. In this release, -this module does no logging at all. Instead, a configurable log -format file should be used to log user click-streams. This is possible -because the logging module now allows <A -HREF="../multilogs.html">multiple log files</A>. The cookie itself is -logged by using the text <TT>%{cookie}n </TT> - -in the log file format. For example: -<PRE> -CustomLog logs/clickstream "%{cookie}n %r %t" -</PRE> - -For backward compatibility the configurable log module implements the -old <TT>CookieLog</TT> directive, but this should be upgraded to the -above <TT>CustomLog</TT> directive. - -<H2>Directives</H2> - -<UL> -<LI><A HREF="#cookieexpires">CookieExpires</A> -<LI><A HREF="#cookiename">CookieName</A> -<LI><A HREF="#cookietracking">CookieTracking</A> -</UL> - -<HR> - -<H2><A NAME="cookieexpires">CookieExpires</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CookieExpires <EM>expiry-period</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> optional<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_usertrack<P> - -When used, this directive sets an expiry time on the cookie generated -by the usertrack module. The <EM>expiry-period</EM> can be given either -as a number of seconds, or in the format such as "2 weeks 3 days 7 -hours". Valid denominations are: years, months, weeks, hours, minutes -and seconds. If the expiry time is in any format other than one -number indicating the number of seconds, it must be enclosed by -double quotes. - -<P>If this directive is not used, cookies last only for the current -browser session.</P> - -<H2><A NAME="cookiename">CookieName</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CookieName <EM>token</EM> -<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>Apache</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, -.htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> optional<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_usertrack -<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.3.7 and later -<P> -This directive allows you to change the name of the cookie this module -uses for its tracking purposes. By default the cookie is named -"<CODE>Apache</CODE>". -</P> -<P> -You must specify a valid cookie name; results are unpredictable if -you use a name containing unusual characters. Valid characters -include A-Z, a-z, 0-9, "_", and "-". -</P> - -<H2><A NAME="cookietracking">CookieTracking</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CookieTracking <EM>on | off</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, -.htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> optional<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_usertrack<P> - -When the user track module is compiled in, and "CookieTracking on" is -set, Apache will start sending a user-tracking cookie for all new -requests. This directive can be used to turn this behavior on or off -on a per-server or per-directory basis. By default, compiling -mod_usertrack will not activate cookies. - -<HR> - -<H2>2-digit or 4-digit dates for cookies?</H2> - -(the following is from message -<022701bda43d$9d32bbb0$1201a8c0@christian.office.sane.com> in -the new-httpd archives) - -<P> - -<PRE> -From: "Christian Allen" <christian@sane.com> -Subject: Re: Apache Y2K bug in mod_usertrack.c -Date: Tue, 30 Jun 1998 11:41:56 -0400 - -Did some work with cookies and dug up some info that might be useful. - -True, Netscape claims that the correct format NOW is four digit dates, and -four digit dates do in fact work... for Netscape 4.x (Communicator), that -is. However, 3.x and below do NOT accept them. It seems that Netscape -originally had a 2-digit standard, and then with all of the Y2K hype and -probably a few complaints, changed to a four digit date for Communicator. -Fortunately, 4.x also understands the 2-digit format, and so the best way to -ensure that your expiration date is legible to the client's browser is to -use 2-digit dates. - -However, this does not limit expiration dates to the year 2000; if you use -an expiration year of "13", for example, it is interpreted as 2013, NOT -1913! In fact, you can use an expiration year of up to "37", and it will be -understood as "2037" by both MSIE and Netscape versions 3.x and up (not sure -about versions previous to those). Not sure why Netscape used that -particular year as its cut-off point, but my guess is that it was in respect -to UNIX's 2038 problem. Netscape/MSIE 4.x seem to be able to understand -2-digit years beyond that, at least until "50" for sure (I think they -understand up until about "70", but not for sure). - -Summary: Mozilla 3.x and up understands two digit dates up until "37" -(2037). Mozilla 4.x understands up until at least "50" (2050) in 2-digit -form, but also understands 4-digit years, which can probably reach up until -9999. Your best bet for sending a long-life cookie is to send it for some -time late in the year "37". -</PRE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_vhost_alias.html b/docs/manual/mod/mod_vhost_alias.html deleted file mode 100644 index 17506e3042..0000000000 --- a/docs/manual/mod/mod_vhost_alias.html +++ /dev/null @@ -1,311 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_vhost_alias</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<DIV ALIGN="CENTER"> - <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> - <H3> - Apache HTTP Server Version 1.3 - </H3> -</DIV> - -<H1 ALIGN="CENTER">Module mod_vhost_alias</H1> - -<P> -This module is contained in the <CODE>mod_vhost_alias.c</CODE> file -and is not compiled in by default. It should be mentioned near the -start of the <CODE>Configuration</CODE> file so that it doesn't -override the behaviour of other modules that do filename translation, -<EM>e.g.</EM>, <A HREF="mod_userdir.html"><CODE>mod_userdir</CODE></A> and -<A HREF="mod_alias.html"><CODE>mod_alias</CODE></A>. It provides -support for <A HREF="../vhosts/mass.html">dynamically configured mass -virtual hosting</A>. -</P> - -<H2>Directory Name Interpolation</H2> - -<P> -All the directives in this module interpolate a string into a -pathname. The interpolated string (henceforth called the "name") may -be either the server name (see the -<A HREF="core.html#usecanonicalname"><CODE>UseCanonicalName</CODE></A> -directive for details on how this is determined) or the IP address of -the virtual host on the server in dotted-quad format. The -interpolation is controlled by specifiers inspired by -<CODE>printf</CODE> which have a number of formats: -<DL> - <DT><CODE>%%</CODE> - <DD>insert a <CODE>%</CODE> - <DT><CODE>%p</CODE> - <DD>insert the port number of the virtual host - <DT><CODE>%N.M</CODE> - <DD>insert (part of) the name -</DL> -</P> - -<P> -<CODE>N</CODE> and <CODE>M</CODE> are used to specify substrings of -the name. <CODE>N</CODE> selects from the dot-separated components of -the name, and <CODE>M</CODE> selects characters within whatever -<CODE>N</CODE> has selected. <CODE>M</CODE> is optional and defaults -to zero if it isn't present; the dot must be present if and only if -<CODE>M</CODE> is present. The interpretation is as follows: -<DL> - <DT><CODE>0</CODE> - <DD>the whole name - <DT><CODE>1</CODE> - <DD>the first part - <DT><CODE>2</CODE> - <DD>the second part - <DT><CODE>-1</CODE> - <DD>the last part - <DT><CODE>-2</CODE> - <DD>the penultimate part - <DT><CODE>2+</CODE> - <DD>the second and all subsequent parts - <DT><CODE>-2+</CODE> - <DD>the penultimate and all preceding parts - <DT><CODE>1+</CODE> and <CODE>-1+</CODE> - <DD>the same as <CODE>0</CODE> -</DL> -If <CODE>N</CODE> or <CODE>M</CODE> is greater than the number of -parts available a single underscore is interpolated. -</P> - -<H3>Examples</H3> - -<P> -For simple name-based virtual hosts you might use the following -directives in your server configuration file: -<PRE> - UseCanonicalName Off - VirtualDocumentRoot /usr/local/apache/vhosts/%0 -</PRE> -A request for <CODE>http://www.example.com/directory/file.html</CODE> -will be satisfied by the file -<CODE>/usr/local/apache/vhosts/www.example.com/directory/file.html</CODE>. -</P> - -<P> -For a very large number of virtual hosts it is a good idea to arrange -the files to reduce the size of the <CODE>vhosts</CODE> directory. To -do this you might use the following in your configuration file: -<PRE> - UseCanonicalName Off - VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2 -</PRE> -A request for <CODE>http://www.example.isp.com/directory/file.html</CODE> -will be satisfied by the file -<CODE>/usr/local/apache/isp.com/e/x/a/example/directory/file.html</CODE>. -A more even spread of files can be achieved by hashing from the end of -the name, for example: -<PRE> - VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2 -</PRE> -The example request would come from -<CODE>/usr/local/apache/vhosts/isp.com/e/l/p/example/directory/file.html</CODE>. -Alternatively you might use: -<PRE> - VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+ -</PRE> -The example request would come from -<CODE>/usr/local/apache/vhosts/isp.com/e/x/a/mple/directory/file.html</CODE>. -</P> - -<P> -For IP-based virtual hosting you might use the following in your -configuration file: -<PRE> - UseCanonicalName DNS - VirtualDocumentRootIP /usr/local/apache/vhost/%1/%2/%3/%4/docs - VirtualScriptAliasIP /usr/local/apache/vhost/%1/%2/%3/%4/cgi-bin -</PRE> -A request for <CODE>http://www.example.isp.com/directory/file.html</CODE> -would be satisfied by the file -<CODE>/usr/local/apache/10/20/30/40/docs/directory/file.html</CODE> if -the IP address of <CODE>www.example.com</CODE> were 10.20.30.40. -A request for <CODE>http://www.example.isp.com/cgi-bin/script.pl</CODE> -would be satisfied by executing the program -<CODE>/usr/local/apache/10/20/30/40/cgi-bin/script.pl</CODE>. -</P> - -<P> -The <A HREF="mod_log_config.html#formats">LogFormat directives</A> -<CODE>%V</CODE> and <CODE>%A</CODE> are useful in conjunction with -this module. -</P> - -<HR> - -<H2>Directives</H2> -<UL> - <LI><A HREF="#VirtualDocumentRoot">VirtualDocumentRoot</A> - <LI><A HREF="#VirtualDocumentRootIP">VirtualDocumentRootIP</A> - <LI><A HREF="#VirtualScriptAlias">VirtualScriptAlias</A> - <LI><A HREF="#VirtualScriptAliasIP">VirtualScriptAliasIP</A> -</UL> -<HR> - -<H2><A NAME="VirtualDocumentRoot">VirtualDocumentRoot directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> VirtualDocumentRoot <EM>interpolated-directory</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_vhost_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> VirtualDocumentRoot is only available in 1.3.7 and later.</P> -<P> -The <CODE>VirtualDocumentRoot</CODE> directive allows you to determine -where Apache will find your documents based on the value of the server -name. The result of expanding <EM>interpolated-directory</EM> is used -as the root of the document tree in a similar manner to the -<A HREF="core.html#documentroot"><CODE>DocumentRoot</CODE></A> -directive's argument. If <EM>interpolated-directory</EM> is -<CODE>none</CODE> then <CODE>VirtaulDocumentRoot</CODE> is turned off. -This directive cannot be used in the same context as -<A HREF="#VirtualDocumentRootIP"><CODE>VirtualDocumentRootIP</CODE></A>. -</P> -<HR> - -<H2><A NAME="VirtualDocumentRootIP">VirtualDocumentRootIP directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> VirtualDocumentRootIP <EM>interpolated-directory</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_vhost_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> VirtualDocumentRootIP is only available in 1.3.7 and later.</P> -<P> -The <CODE>VirtualDocumentRootIP</CODE> directive is like the -<A HREF="#VirtualDocumentRoot"><CODE>VirtualDocumentRoot</CODE></A> directive, -except that it uses the IP address of the server end of the connection -instead of the server name. -</P> -<HR> - -<H2><A NAME="VirtualScriptAlias">VirtualScriptAlias directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> VirtualScriptAlias <EM>interpolated-directory</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_vhost_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> VirtualScriptAlias is only available in 1.3.7 and later.</P> -<P> -The <CODE>VirtualScriptAlias</CODE> directive allows you to determine -where Apache will find CGI scripts in a similar manner to -<A HREF="#VirtualDocumentRoot"><CODE>VirtualDocumentRoot</CODE></A> -does for other documents. It matches requests for URIs starting -<CODE>/cgi-bin/</CODE>, much like -<CODE><A HREF="mod_alias.html#scriptalias">ScriptAlias</A> /cgi-bin/</CODE> -would. -</P> -<HR> - -<H2><A NAME="VirtualScriptAlias">VirtualScriptAliasIP directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> VirtualScriptAliasIP <EM>interpolated-directory</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_vhost_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> VirtualScriptAliasIP is only available in 1.3.7 and later.</P> -<P> -The <CODE>VirtualScriptAliasIP</CODE> directibe is like the -<A HREF="#VirtualScriptAlias"><CODE>VirtualScriptAlias</CODE></A> directive, -except that it uses the IP address of the server end of the connection -instead of the server name. -</P> -<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> diff --git a/docs/manual/platform/perf-bsd44.html b/docs/manual/platform/perf-bsd44.html deleted file mode 100644 index c5e978c2b9..0000000000 --- a/docs/manual/platform/perf-bsd44.html +++ /dev/null @@ -1,254 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Running a High-Performance Web Server for BSD</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<A NAME="initial"> -<!--#include virtual="header.html" --> -</A> -<H1 ALIGN="CENTER">Running a High-Performance Web Server for BSD</H1> - -Like other OS's, the listen queue is often the <STRONG>first limit -hit</STRONG>. The -following are comments from "Aaron Gifford <agifford@InfoWest.COM>" -on how to fix this on BSDI 1.x, 2.x, and FreeBSD 2.0 (and earlier): - -<P> - -Edit the following two files: -<BLOCKQUOTE><CODE> /usr/include/sys/socket.h <BR> - /usr/src/sys/sys/socket.h </CODE></BLOCKQUOTE> -In each file, look for the following: -<PRE> - /* - * Maximum queue length specifiable by listen. - */ - #define SOMAXCONN 5 -</PRE> - -Just change the "5" to whatever appears to work. I bumped the two -machines I was having problems with up to 32 and haven't noticed the -problem since. - -<P> - -After the edit, recompile the kernel and recompile the Apache server -then reboot. - -<P> - -FreeBSD 2.1 seems to be perfectly happy, with SOMAXCONN -set to 32 already. - -<P> - -<A NAME="detail"> -<STRONG>Addendum for <EM>very</EM> heavily loaded BSD servers</STRONG><BR> -</A> -from Chuck Murcko <chuck@telebase.com> - -<P> - -If you're running a really busy BSD Apache server, the following are useful -things to do if the system is acting sluggish:<P> - -<UL> - -<LI> Run vmstat to check memory usage, page/swap rates, <EM>etc.</EM> - -<LI> Run netstat -m to check mbuf usage - -<LI> Run fstat to check file descriptor usage - -</UL> - -These utilities give you an idea what you'll need to tune in your kernel, -and whether it'll help to buy more RAM. - -Here are some BSD kernel config parameters (actually BSDI, but pertinent to -FreeBSD and other 4.4-lite derivatives) from a system getting heavy usage. -The tools mentioned above were used, and the system memory was increased to -48 MB before these tuneups. Other system parameters remained unchanged. - -<P> - -<PRE> -maxusers 256 -</PRE> - -Maxusers drives a <EM>lot</EM> 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 -<EM>/usr/src/sys/conf/param.c</EM>. -These calculated parameters can also be overridden (in part) by specifying -your own values in the kernel configuration file: - -<PRE> -# Network options. NMBCLUSTERS defines the number of mbuf clusters and -# defaults to 256. This machine is a server that handles lots of traffic, -# so we crank that value. -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> - -<P> - -In many cases, NMBCLUSTERS must be set much larger than would appear -necessary at first glance. The reason for this is that if the browser -disconnects in mid-transfer, the socket fd associated with that particular -connection ends up in the TIME_WAIT state for several minutes, during -which time its mbufs are not yet freed. Another reason is that, on server -timeouts, some connections end up in FIN_WAIT_2 state forever, because -this state doesn't time out on the server, and the browser never sent -a final FIN. For more details see the -<A HREF="fin_wait_2.html">FIN_WAIT_2</A> page. - -<P> - -Some more info on mbuf clusters (from sys/mbuf.h): -<PRE> -/* - * Mbufs are of a single size, MSIZE (machine/machparam.h), which - * includes overhead. An mbuf may add a single "mbuf cluster" of size - * MCLBYTES (also in machine/machparam.h), which has no additional overhead - * and is used instead of the internal data area; this is done when - * at least MINCLSIZE of data must be stored. - */ -</PRE> - -<P> - -CHILD_MAX and OPEN_MAX are set to allow up to 512 child processes (different -than the maximum value for processes per user ID) and file descriptors. -These values may change for your particular configuration (a higher OPEN_MAX -value if you've got modules or CGI scripts opening lots of connections or -files). If you've got a lot of other activity besides httpd on the same -machine, you'll have to set NPROC higher still. In this example, the NPROC -value derived from maxusers proved sufficient for our load. - -<P> - -To increase the size of the <CODE>listen()</CODE> queue, you need to -adjust the value of SOMAXCONN. SOMAXCONN is not derived from maxusers, -so you'll always need to increase that yourself. We use a value guaranteed -to be larger than Apache's default for the listen() of 128, currently. -The actual value for SOMAXCONN is set in <CODE>sys/socket.h</CODE>. -The best way to adjust this parameter is run-time, rather than changing -it in this header file and thus hardcoding a value in the kernel and -elsewhere. To do this, edit <CODE>/etc/rc.local</CODE> and add the -following line: -<PRE> - /usr/sbin/sysctl -w kern.somaxconn=256 -</PRE> - -<P> - -We used <CODE>256</CODE> but you can tune it for your own setup. In -many cases, however, even the default value of <CODE>128</CODE> (for -later versions of FreeBSD) is OK. - -<P> - -<STRONG>Caveats</STRONG> - -<P> - -Be aware that your system may not boot with a kernel that is configured -to use more resources than you have available system RAM. -<STRONG>ALWAYS</STRONG> -have a known bootable kernel available when tuning your system this way, -and use the system tools beforehand to learn if you need to buy more -memory before tuning. - -<P> - -RPC services will fail when the value of OPEN_MAX is larger than 256. -This is a function of the original implementations of the RPC library, -which used a byte value for holding file descriptors. BSDI has partially -addressed this limit in its 2.1 release, but a real fix may well await -the redesign of RPC itself. - -<P> - -Finally, there's the hard limit of child processes configured in Apache. - -<P> - -For versions of Apache later than 1.0.5 you'll need to change the -definition for <STRONG>HARD_SERVER_LIMIT</STRONG> in <EM>httpd.h</EM> and -recompile if you need to run more than the default 150 instances of httpd. - -<P> - -From conf/httpd.conf-dist: - -<PRE> -# Limit on total number of servers running, <EM>i.e.</EM>, limit on the number -# of clients who can simultaneously connect --- if this limit is ever -# reached, clients will be LOCKED OUT, so it should NOT BE SET TOO LOW. -# It is intended mainly as a brake to keep a runaway server from taking -# Unix with it as it spirals down... - -MaxClients 150 -</PRE> - -Know what you're doing if you bump this value up, and make sure you've -done your system monitoring, RAM expansion, and kernel tuning beforehand. -Then you're ready to service some serious hits! - -<P> - -Thanks to <EM>Tony Sanders</EM> and <EM>Chris Torek</EM> at BSDI for their -helpful suggestions and information. - -<P> - -"M. Teterin" <mi@ALDAN.ziplink.net> writes:<P> -<BLOCKQUOTE>It really does help if your kernel and frequently used utilities -are fully optimized. Rebuilding the FreeBSD kernel on an AMD-133 -(486-class CPU) web-server with<BR> -<CODE> -m486 -fexpensive-optimizations -fomit-frame-pointer -O2</CODE><BR> -helped reduce the number of "unable" errors, because the CPU was -often maxed out.</BLOCKQUOTE> -<P> - -<HR> - -<H3>More welcome!</H3> - -If you have tips to contribute, send mail to -<A HREF="mailto:apache@apache.org">apache@apache.org</A> - -<!--#include virtual="footer.html" --> -</BODY></HTML> - diff --git a/docs/manual/platform/perf-dec.html b/docs/manual/platform/perf-dec.html deleted file mode 100644 index 2b9cc9cc5e..0000000000 --- a/docs/manual/platform/perf-dec.html +++ /dev/null @@ -1,285 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Performance Tuning Tips for Digital Unix</TITLE> -</HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Performance Tuning Tips for Digital Unix</H1> - -Below is a set of newsgroup posts made by an engineer from DEC in -response to queries about how to modify DEC's Digital Unix OS for more -heavily loaded web sites. Copied with permission. - -<HR> - -<H2>Update</H2> -From: Jeffrey Mogul <mogul@pa.dec.com><BR> -Date: Fri, 28 Jun 96 16:07:56 MDT<BR> - -<OL> -<LI> The advice given in the README file regarding the - "tcbhashsize" variable is incorrect. The largest value - this should be set to is 1024. Setting it any higher - will have the perverse result of disabling the hashing - mechanism. - -<LI>Patch ID OSF350-146 has been superseded by -<BLOCKQUOTE> - Patch ID OSF350-195 for V3.2C<BR> - Patch ID OSF360-350195 for V3.2D -</BLOCKQUOTE> - Patch IDs for V3.2E and V3.2F should be available soon. - There is no known reason why the Patch ID OSF360-350195 - won't work on these releases, but such use is not officially - supported by Digital. This patch kit will not be needed for - V3.2G when it is released. -</OL> -<HR> - - -<PRE> -From mogul@pa.dec.com (Jeffrey Mogul) -Organization DEC Western Research -Date 30 May 1996 00:50:25 GMT -Newsgroups <A HREF="news:comp.unix.osf.osf1">comp.unix.osf.osf1</A> -Message-ID <4oirch$bc8@usenet.pa.dec.com> -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 - http://www.digital.com/info/alphaserver/news/webff.html - -<EM>[The document referenced above is no longer at that URL -- Ed.]</EM> - -I'm not sure if these were done using V4.0 or an earlier version -of Digital UNIX, although I suspect they were done using a test -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 <4onmmd$mmd@usenet.pa.dec.com> -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 (<EM>e.g.</EM>, if a client - sends a SYN but never answers our SYN/ACK). - Partially established connections tie up slots - on the listen queue. If the queue starts to - fill with connections in SYN_RCVD state, - tcp_keepinit can be decreased to make those - partial connects time out sooner. This should - be used with caution, since there might be - legitimate clients that are taking a while - to respond to SYN/ACK. The unit is specified - in 1/2 seconds, the default value is 150 - (ie. 75 seconds). - - The hashlist size for the TCP inpcb lookup table is regulated by: - - tcbhashsize The number of hash buckets used for the - TCP connection table used in the kernel. - The initial value is 32. For best results, - should be specified as a power of 2. For - busy Web servers, set this to 2048 or more. - - The hashlist size for the interface alias table is regulated by: - - inifaddr_hsize The number of hash buckets used for the - interface alias table used in the kernel. - The initial value is 32. For best results, - should be specified as a power of 2. - - ipport_userreserved The maximum number of concurrent non-reserved, - dynamically allocated ports. Default range - is 1025-5000. The maximum value is 65535. - This limits the numer of times you can - simultaneously telnet or ftp out to connect - to other systems. - - tcpnodelack Don't delay acknowledging TCP data; this - can sometimes improve performance of locally - run CAD packages. Default is value is 0, - the enabled value is 1. - - Digital UNIX version: - - V3.2C -Feature V3.2C patch V4.0 -======= ===== ===== ==== -somaxconn X X X -sominconn - X X -sobacklog_hiwat - X - -sobacklog_drops - X - -somaxconn_drops - X - -tcpnodelack X X X -tcp_keepidle X X X -tcp_keepintvl X X X -tcp_keepcnt - X X -tcp_keepinit - X X -TCP keepalive per-socket - - X -tcp_msl - X - -tcp_rexmit_interval_min - X - -TCP inpcb hashing - X X -tcbhashsize - X X -interface alias hashing - X X -inifaddr_hsize - X X -ipport_userreserved - X - -sysconfig -q inet - - X -sysconfig -q socket - - X - -</PRE> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/platform/perf-hp.html b/docs/manual/platform/perf-hp.html deleted file mode 100644 index ca902a09fe..0000000000 --- a/docs/manual/platform/perf-hp.html +++ /dev/null @@ -1,122 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Running a High-Performance Web Server on HPUX</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<A NAME="initial"> </A> -<!--#include virtual="header.html" --> - -<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. - -Notice that it's critically important that you use "W" to write a 32 bit -quantity, not "w" to write a 16 bit value when patching the disc image because -the tcp_hash_size variable is a 32 bit quantity. - -<P> - -How to pick the value? Examine the output of -<A HREF="ftp://ftp.cup.hp.com/dist/networking/tools/connhist"> -ftp://ftp.cup.hp.com/dist/networking/tools/connhist</A> and see how many -total TCP connections exist on the system. You probably want that number -divided by the hash table size to be reasonably small, say less than 10. -Folks can look at HP's SPECweb96 disclosures for some common settings. -These can be found at <A HREF="http://www.specbench.org/"> -http://www.specbench.org/</A>. If an HP-UX system was -performing at 1000 SPECweb96 connections per second, the TIME_WAIT time -of 60 seconds would mean 60,000 TCP "connections" being tracked. - -<P> - -Folks can check their listen queue depths with -<A HREF="ftp://ftp.cup.hp.com/dist/networking/misc/listenq"> -ftp://ftp.cup.hp.com/dist/networking/misc/listenq</A>. - -<P> - -If folks are running Apache on a PA-8000 based system, they should -consider "chatr'ing" the Apache executable to have a large page size. -This would be "chatr +pi L <BINARY>." The GID of the running executable -must have MLOCK privileges. Setprivgrp(1m) should be consulted for -assigning MLOCK. The change can be validated by running Glance and -examining the memory regions of the server(s) to make sure that they -show a non-trivial fraction of the text segment being locked. - -<P> - -If folks are running Apache on MP systems, they might consider writing a -small program that uses mpctl() to bind processes to processors. A -simple pid % numcpu algorithm is probably sufficient. This might even go -into the source code. - -<P> - -If folks are concerned about the number of FIN_WAIT_2 connections, they -can use nettune to shrink the value of tcp_keepstart. However, they -should be careful there - certainly do not make it less than oh two to -four minutes. If tcp_hash_size has been set well, it is probably OK to -let the FIN_WAIT_2's take longer to timeout (perhaps even the default -two hours) - they will not on average have a big impact on performance. - -<P> - -There are other things that could go into the code base, but that might -be left for another email. Feel free to drop me a message if you or -others are interested. - -<P> - -sincerely, - -<P> - -rick jones<BR> -<A HREF="http://www.cup.hp.com/netperf/NetperfPage.html"> -http://www.cup.hp.com/netperf/NetperfPage.html</A> - -<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> - diff --git a/docs/manual/platform/perf.html b/docs/manual/platform/perf.html deleted file mode 100644 index 73bd5b5b20..0000000000 --- a/docs/manual/platform/perf.html +++ /dev/null @@ -1,175 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Hints on Running a High-Performance Web Server</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Hints on Running a High-Performance Web Server</H1> - -Running Apache on a heavily loaded web server, one often encounters -problems related to the machine and OS configuration. "Heavy" is -relative, of course - but if you are seeing more than a couple hits -per second on a sustained basis you should consult the pointers on -this page. In general the suggestions involve how to tune your kernel -for the heavier TCP load, hardware/software conflicts that arise, <EM>etc.</EM> - -<UL> -<LI><A HREF="#AUX">A/UX (Apple's UNIX)</A> -<LI><A HREF="#BSD">BSD-based (BSDI, FreeBSD, etc)</A> -<LI><A HREF="#DEC">Digital UNIX</A> -<LI><A HREF="perf-hp.html">HPUX</A> -<LI><A HREF="#Linux">Linux</A> -<LI><A HREF="#Solaris">Solaris</A> -<LI><A HREF="#SunOS">SunOS 4.x</A> -<LI><A HREF="#SVR4">SVR4</A> -</UL> - -<HR> - -<H3><A NAME="AUX"> -A/UX (Apple's UNIX) -</A></H3> - -If you are running Apache on A/UX, a page that gives some helpful -performance hints (concerning the <EM>listen()</EM> queue and using -virtual hosts) -<A HREF="http://www.jaguNET.com/apache.html">can be found here</A> - -<P><HR> - -<H3><A NAME="BSD"> -BSD-based (BSDI, FreeBSD, etc) -</A></H3> - -<A HREF="perf-bsd44.html#initial">Quick</A> and -<A HREF="perf-bsd44.html#detail">detailed</A> -performance tuning hints for BSD-derived systems. - -<P><HR> - -<H3><A NAME="DEC"> -Digital UNIX -</A></H3> - -<UL> - <LI><A - HREF="http://www.digital.com/info/internet/document/ias/tuning.html" - >DIGITAL UNIX Tuning Parameters for Web Servers</A> - <LI>We have some <A HREF="perf-dec.html">newsgroup postings</A> on how - to tune Digital UNIX 3.2 and 4.0. -</UL> - -<P><HR> - -<H3><A NAME="Linux"> -Linux -</A></H3> - -There are no known problems with heavily loaded systems running Linux -kernels 2.0.32 or later. Earlier kernels have some problems, and an -upgrade to the latest 2.0.x is a good idea to eliminate various security -and denial of service attacks. - -<P><HR> - -<H3><A NAME="Solaris"> -Solaris 2.4 -</A></H3> - -The Solaris 2.4 TCP implementation has a few inherent limitations that -only became apparent under heavy loads. This has been fixed to some -extent in 2.5 (and completely revamped in 2.6), but for now consult -the following URL for tips on how to expand the capabilities if you -are finding slowdowns and lags are hurting performance. - -<P> - -Other links: - -<UL> - -<LI><A HREF="http://www.sun.com/sun-on-net/performance.html"> -World Wide Web Server Performance, -<http://www.sun.com/sun-on-net/performance.html></A> -<LI><A HREF="http://www.rvs.uni-hannover.de/people/voeckler/tune/EN/tune.html"> -Solaris 2.x - tuning your TCP/IP stack</A> contains some good technical -information about tuning various Solaris TCP/IP parameters. -</UL> - -<P><HR> - -<H3><A NAME="SunOS"> -SunOS 4.x -</A></H3> - -More information on tuning SOMAXCONN on SunOS can be found at -<A HREF="http://www.islandnet.com/~mark/somaxconn.html"> -http://www.islandnet.com/~mark/somaxconn.html</A>. - -<P><HR> - -<H3><A NAME="SVR4"> -SVR4 -</A></H3> - -Some SVR4 versions waste three system calls on every -<SAMP>gettimeofday()</SAMP> call. Depending on the syntactic -form of the <SAMP>TZ</SAMP> environment variable, these -systems have several different algorithms to determine the -local time zone (presumably <EM>compatible</EM> with -something). The following example uses the central european -time zone to demonstrate this: -<DL> - <DT><STRONG>TZ=:MET</STRONG> - <DD>This form delegates the knowledge of the time zone - information to an external compiled zoneinfo file - (à la BSD).<BR> - <STRONG>Caveat:</STRONG> Each time the gettimeofday() - function is called, the external zone info is read in - again (at least on some SVR4 systems). That results in - three wasted system calls with every apache request - served.<PRE> - open("/usr/lib/locale/TZ/MET", O_RDONLY) = 3 - read(3, "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 7944) = 778 - close(3) = 0</PRE> - - <DT><STRONG>TZ=MET-1MDT,M3.5.0/02:00:00,M10.5.0/03:00:00</STRONG> - <DD>This syntax form (à la SYSV) contains all the - knowledge about time zone beginning and ending times in - its external representation. It has to be parsed each - time it is evaluated, resulting in a slight computing - overhead, but it requires no system call. Though the - table lookup à la BSD is the more sophisticated - technical solution, the bad SVR4 implementation makes - this the preferred syntax on systems which otherwise - access the external zone info file repeatedly. -</DL> -You should use the <SAMP>truss</SAMP> utility on a -single-process apache server (started with the <SAMP>-X</SAMP> -debugging switch) to determine whether your system can profit -from the second form of the <SAMP>TZ</SAMP> environment -variable. If it does, you could integrate the setting of the -preferred <SAMP>TZ</SAMP> syntax into the httpd startup -script, which is usually simply a copy of (or symbolic link -to) the <SAMP>apachectl</SAMP> utility script, or into the -system's <SAMP>/etc/TIMEZONE</SAMP> script. - -<P><HR> - -<H3>More welcome!</H3> - -If you have tips to contribute, send mail to <A -HREF="mailto:apache@apache.org">apache@apache.org</A> - -<!--#include virtual="footer.html" --> -</BODY></HTML> - diff --git a/docs/manual/platform/readme-tpf.html b/docs/manual/platform/readme-tpf.html deleted file mode 100644 index a9267dfb38..0000000000 --- a/docs/manual/platform/readme-tpf.html +++ /dev/null @@ -1,205 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>The Apache TPF Port</TITLE> -</HEAD> -<BODY> -<A NAME="top"></A> -<H1 align="center">Overview of the Apache TPF Port</H1> -<HR> -<CENTER>[ <A HREF="#configuration_files">Configuration Files</A> - | <A HREF="#whats_available">What's Available</A> - | <A HREF="#porting_notes">Porting Notes</A> ] -</CENTER> -<HR> -<BR> - -<P> - This version of Apache includes changes allowing it to run on - IBM's EBCDIC-based - <A HREF="http://www.s390.ibm.com/products/tpf/tpfhp.html">TPF</A> - (Transaction Processing Facility) operating system. - Unless otherwise noted TPF version 4.1 PUT08 and APAR PJ25589 are required. - <BR><BR> - Refer to htdocs/manual/<A HREF="install-tpf.html">install-tpf.html</A> - for step-by-step installation instructions. - <BR><BR> - As this is the first cut at making Apache run on TPF, - performance tuning has not been done. - <BR><BR> - This port builds upon the <A HREF="ebcdic.html">EBCDIC changes</A> - previously made to Apache. - <BR> -</P> - -<A NAME="configuration_files"> </A> -<H2 align=center>Apache Configuration Files</H2> -<P> - The distributed configuration files (httpd.conf-dist and - mime.types, both located in the conf subdirectory) - work on TPF with only a couple of operating system specific changes - to httpd.conf:<BR> - <UL> - <LI>ServerType needs to be "inetd" on pre-PUT09 systems. - <LI>Performance considerations may dictate setting KeepAlive to "Off" - (the default is "On") or lowering the Timeout value from the default - 300 seconds (5 minutes) in order to reduce the number of active ECBs on your system. - </UL> -</P> - -<A NAME="whats_available"> </A> -<H2 align=center>What's Available in this Version</H2> - - (The Apache organization provides - <A HREF="http://www.apache.org/docs/">online documentation</A> - describing the various modules and components of the server.) - -<H3>Components/modules tested on TPF:</H3> - - <multicol COLS=3><UL> - <LI>alloc.c - <LI>ap_cpystrn.c - <LI>ap_fnmatch.c - <LI>ap_signal.c - <LI>ap_slack.c - <LI>ap_snprintf.c - <LI>buff.c - <LI>buildmark.c - <LI>ebcdic.c - <LI>gen_test.char.c - <LI>gen_uri_delims.c - <LI>http_config.c - <LI>http_core.c - <LI>http_log.c - <LI>http_main.c <A HREF="#note_1"> <i><small>(see note 1)</small></i></A> - <LI>http_protocol.c - <LI>http_request.c - <LI>http_vhost.c <i><small>(requires PUT9)</small></i> - <LI>logresolve.c <i><small>(requires PUT10)</small></i> - <LI>mod_access.c <A HREF="#note_2"> <i><small>(see note 2)</small></i></A> - <LI>mod_actions.c - <LI>mod_alias.c - <LI>mod_asis.c - <LI>mod_auth_anon.c - <LI>mod_autoindex.c - <LI>mod_cern_meta.c - <LI>mod_cgi.c <i><small>(requires PUT10)</small></i> - <LI>mod_dir.c - <LI>mod_env.c - <LI>mod_example.c - <LI>mod_expires.c - <LI>mod_headers.c - <LI>mod_imap.c - <LI>mod_include.c <A HREF="#note_3"> <i><small>(see note 3)</small></i></A> - <LI>mod_info.c - <LI>mod_log_agent.c - <LI>mod_log_config.c - <LI>mod_log_referer.c - <LI>mod_mime.c - <LI>mod_mime_magic.c - <LI>mod_negotiation.c - <LI><A HREF="http://hpwww.ec-lyon.fr/~vincent/apache/mod_put.html">mod_put.c</A> - <LI>mod_setenvif.c - <LI>mod_speling.c - <LI>mod_status.c - <LI>mod_unique_id.c <i><small>(requires PUT10)</small></i> - <LI>mod_userdir.c - <LI>mod_usertrack.c - <LI>os.c - <LI>os-inline.c - <LI>regular expression parser - <LI>rotatelogs.c <i><small>(requires PUT10)</small></i> - <LI>util.c - <LI>util_date.c - <LI>util_script.c - <LI>util_uri.c - </UL></MULTICOL> - <br><b>Notes:</b> - <A NAME="note_1"> </A> - <ol> - <li>"Standalone" mode requires TPF version 4.1 PUT09 - <A NAME="note_2"> </A> - <li>Use of mod_access directives "<tt>allow from</tt>" & "<tt>deny from</tt>" - with host <i>names</i> (verses ip addresses) requires TPF version 4.1 PUT10 - <A NAME="note_3"> </A> - <li>CGI execution requires TPF version 4.1 PUT10 - </ol> - -<H3>Components/modules not yet supported on TPF:</H3> - - <multicol COLS=3><UL> - <LI>ap_md5c.c - <LI>htpasswd.c - <LI>mod_auth.c - <LI>mod_digest.c - <LI>mod_mmap_static.c - <LI>mod_proxy.c - <LI>mod_rewrite.c - <LI>proxy_cache.c - <LI>proxy_connect.c - <LI>proxy_ftp.c - <LI>proxy_http.c - <LI>proxy_util.c - <LI>rfc1413.c - <LI>util_md5.c - </UL></MULTICOL> - -<H3>Components/modules that don't apply or that probably won't ever be available on TPF:</H3> - - <multicol COLS=3><UL> - <LI>mod_auth_db.c - <LI>mod_auth_dbm.c - <LI>mod_auth_db.module - <LI>mod_so.c - <LI>suexec.c - </UL></MULTICOL> - -<A NAME="porting_notes"> </A> -<H2 align=center>Porting Notes</H2> -<P> - <H3>Changes made due to differences between UNIX and - TPF's process models:</H3> - <UL> - <LI><STRONG>Signals</STRONG>: On TPF a signal that is sent to a process - remains unhandled until the process explicitly requests that signals - be handled using the <CODE>tpf_process_signals()</CODE> function. - Additionally, the default action for an alarm on TPF is to take - an OPR-7777 dump and exit. (On UNIX the default is the equivalent - of <CODE>exit()</CODE> with no dump taken.) - These differences necessitated a few modifications: - <BR><BR> - <UL> - <LI>bypass the use of <CODE>ap_block_alarms()</CODE> & - <CODE>ap_unblock_alarms()</CODE> - <LI>add <CODE>tpf_process_signals()</CODE> calls - <LI>add <CODE>select()</CODE> calls in buff.c to prevent blocking. - </UL> - <BR> - </UL> - - <H3>Find that function...</H3> - <P>Some simple functions & definitions needed to be added - on TPF, such as <CODE>FD_SET()</CODE>. - We've put these in src/os/tpf/os.h for now. - </P> - - <H3>EBCDIC changes:</H3> - <P>TPF-specific conversion tables between US-ASCII and - EBCDIC (character set IBM-1047 to be exact) were created - and put into ebcdic.c in the src/os/tpf directory. - </P> - - <H3>Miscellaneous, minor changes:</H3> - <P>Various minor changes (such as casting) were made due to - differences in how some functions are implemented on TPF. - </P> - -<HR> -<CENTER>[ <A HREF="#top">top</A> - | <A HREF="#configuration_files">Configuration Files</A> - | <A HREF="#whats_available">What's Available</A> - | <A HREF="#porting_notes">Porting Notes</A> ] -</CENTER> - -</BODY> -</HTML> diff --git a/docs/manual/platform/unixware.html b/docs/manual/platform/unixware.html deleted file mode 100644 index a77a3b5cd4..0000000000 --- a/docs/manual/platform/unixware.html +++ /dev/null @@ -1,62 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Compiling Apache under UnixWare</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Compiling Apache under UnixWare</H1> - -To compile a working copy of Apache under UnixWare, there are several other -steps you may need to take. These prevent such problems as zombie processes, -bind errors, and accept errors, to name a few. - -<H2>UnixWare 1.x</H2> - -Make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not -defined by Apache autoconfiguration). If using the UnixWare <EM>cc</EM> -compiler, and you still see accept() errors, don't use compiler optimization, -or get <EM>gcc</EM>. - -<H2>UnixWare 2.0.x</H2> - -SCO patch <A HREF="ftp://ftp.sco.com/UW20/tf2163.txt">tf2163</A> is required -in order for Apache to work correctly on UnixWare 2.0.x. See -<A HREF="http://www.sco.com">http://www.sco.com</A> -for UnixWare patch information.<P> - -In addition, make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not -defined by Apache autoconfiguration). To reduce instances of connections -in FIN_WAIT_2 state, you may also want to define NO_LINGCLOSE (Apache 1.2 -only). - -<H2>UnixWare 2.1.x</H2> - -SCO patch <A HREF="ftp://ftp.sco.com/UW21/ptf3123b.txt">ptf3123</A> is required -in order for Apache to work correctly on UnixWare 2.1.x. See -<A HREF="http://www.sco.com">http://www.sco.com</A> -for UnixWare patch information.<P> - -<STRONG>NOTE:</STRONG> Unixware 2.1.2 and later already have patch ptf3123 -included<P> - -In addition, make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not -defined by Apache autoconfiguration). To reduce instances of connections -in FIN_WAIT_2 state, you may also want to define NO_LINGCLOSE (Apache 1.2 -only).<P> - -Thanks to Joe Doupnik <JRD@cc.usu.edu> and Rich Vaughn -<rvaughn@aad.com> for additional info for UnixWare builds.<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/platform/windows.html b/docs/manual/platform/windows.html deleted file mode 100644 index 543b3f025f..0000000000 --- a/docs/manual/platform/windows.html +++ /dev/null @@ -1,572 +0,0 @@ -<!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 install, configure and run - Apache 1.3 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> - -<P><STRONG>Warning: Apache on NT has not yet been optimized for performance. -Apache still performs best, and is most reliable on Unix platforms. Over -time we will improve NT performance. Folks doing comparative reviews -of webserver performance are asked to compare against Apache -on a Unix platform such as Solaris, FreeBSD, or Linux.</STRONG></P> - -<P> - -Most of this document assumes that you are installing Windows from a -binary distribution. If you want to compile Apache yourself (possibly -to help with development, or to track down bugs), see the section on -<A HREF="#comp">Compiling Apache for Windows</A> below. - -<HR> - -<UL> - <LI><A HREF="#req">Requirements</A> - <LI><A HREF="#down">Downloading Apache for Windows</A> - <LI><A HREF="#inst">Installing Apache for Windows (binary install)</A> - <LI><A HREF="#run">Running Apache for Windows</A> - <LI><A HREF="#use">Using Apache for Windows</A> - <LI><A HREF="#cmdline">Running Apache for Windows from the Command Line</A> - <LI><A HREF="#service">Running Apache for Windows as a Service</A> - <LI><A HREF="#signal">Signalling Console Apache when running</A> - <LI><A HREF="#signalsrv">Signalling Service Apache when running</A> - <LI><A HREF="#comp">Compiling Apache for Windows</A> -</UL> - -<HR> - -<H2><A NAME="req">Requirements</A></H2> - -Apache 1.3 is designed to run on Windows NT 4.0. The binary installer -will only work in Intel processors. Apache may also run on Windows 95, -Windows 98 and Windows NT 3.5.1, but these have not been tested. In -all cases TCP/IP networking must be installed. - -<P> - -If running on Windows 95, using the "Winsock2" upgrade is recommended -but may not be necessary. If running on NT 4.0, installing Service Pack 2 -is recommended. - -<P> - -<STRONG>Note: "Winsock 2" is required for Apache 1.3.7 and later.</STRONG> - -<P> - -"Winsock 2" for Windows 95 is available <A HREF="http://www.microsoft.com/windows95/downloads/">here.</A> - -<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 releases, -together with details of mirror web and anonymous ftp sites.</P> - -<P> - -You should download the version of Apache for Windows with the -<CODE>.exe</CODE> extension. This is a single file containing Apache, -ready to install and run. There may also be a <CODE>.zip</CODE> file -containing the source code, to compile Apache yourself. (If there is -no <SAMP>.zip</SAMP> file, the source will be available in a -<SAMP>.tar.gz</SAMP> file but this will contain Unix line endings. You -will have to convert at least the <SAMP>.mak</SAMP> and -<SAMP>.dsp</SAMP> files to have DOS line endings before MSVC will -understand them). - -<H2><A NAME="inst">Installing Apache for Windows</A></H2> - -Run the Apache <SAMP>.exe</SAMP> file you downloaded above. This will -ask for: - -<UL> - - <LI>the directory to install Apache into (the default is - <CODE>\Program Files\Apache Group\Apache</CODE> although you can - change this to any other directory) - - <LI>the start menu name (default is "Apache Web Server") - - <LI>the installation type. The "Typical" option installs - everything except the source code. The "Minimum" option does not - install the manuals or source code. Choose the "Custom" install if - you want to install the source code. - -</UL> - -<P> - -During the installation, Apache will configure the files in the -<SAMP>conf</SAMP> directory for your chosen installation -directory. However if any of the files in this directory already exist -they will <STRONG>not</STRONG> be overwritten. Instead the new copy of -the corresponding file will be left with the extension -<SAMP>.default</SAMP>. So, for example, if -<SAMP>conf\httpd.conf</SAMP> already exists it will not be altered, -but the version which would have been installed will be left in -<SAMP>conf\httpd.conf.default</SAMP>. After the installation has -finished you should manually check to see what in new in the -<SAMP>.default</SAMP> file, and if necessary update your existing -configuration files. - -<P> - -Also, if you already have a file called <SAMP>htdocs\index.html</SAMP> -then it will not be overwritten (no <SAMP>index.html.default</SAMP> -file will be installed either). This should mean it a safe to install -Apache over an existing installation (but you will have to stop the -existing server running before doing the installation, then start the -new one after the installation is finished). - -<P> - -After installing Apache, you should edit the configuration files in -the <SAMP>conf</SAMP> directory as required. These files will be -configured during the install ready for Apache to be run from the -directory where it was installed, with the documents served from the -subdirectory <SAMP>htdocs</SAMP>. There are lots of other options -which should be set before you start really using Apache. However to -get started quickly the files should work as installed. - -<H2><A NAME="run">Running Apache for Windows</A></H2> - -There are two ways you can run Apache: - -<UL> - <LI>As a <A HREF="#service">"service"</A> (available on NT only). This is the best option if - you want Apache to automatically start when you machine boots, and to - keep Apache running when you log-off. - - <LI>From a <A HREF="#cmdline">console window</A>. This is the only option - available for - Windows 95 users. -</UL> - -To start Apache as a service, you first need to install it as a -service. Multiple Apache services can be installed, each with a -different name and configuration. To install the default Apache -service named "Apache", run the "Install Apache as Service (NT only)" -option from the Start menu. Once this is done you can start the "Apache" -service by opening the Services window (in the Control Panel), selecting Apache, -then clicking on Start. Apache will now be running in the background. You -can later stop Apache by clicking on Stop. As an alternative to using -the Services window, you can start and stop the "Apache" service from the control -line with - -<PRE> - NET START APACHE - NET STOP APACHE -</PRE> - -See <A HREF="#signalsrv">Signalling Service Apache when Running</A> -for more information on installing and controlling Apache services. - -<P> - -To run Apache from a console window, select the "Start Apache as -console app" option from the Start menu (in Apache 1.3.4 and earlier, -this option was called "Apache Server"). This will open a console -window and start Apache running inside it. The window will remain -active until you stop Apache. To stop Apache running, either select -the "Shutdown Apache console app" icon option from the Start menu -(this is not available in Apache 1.3.4 or earlier), or see <A -HREF="#signal">Signalling Console Apache when Running</A> for how -to control Apache from the command line. - -<P> - -After starting Apache running (either in a console window or as a -service) if will be listening to port 80 (unless you changed the -<SAMP>Port</SAMP>, <SAMP>Listen</SAMP> or <SAMP>BindAddress</SAMP> -directives in the configuration files). To connect to the server and -access the default page, launch a browser and enter this URL: - -<PRE> - http://localhost/ -</PRE> - -This should respond with a welcome page, and a link to the Apache -manual. If nothing happens or you get an error, look in the -<SAMP>error_log</SAMP> file in the <SAMP>logs</SAMP> directory. -If your host isn't connected to the net, you may have to use -this URL: - -<PRE> - http://127.0.0.1/ -</PRE> - -<P> - -Once your basic installation is working, you should configure it -properly by editing the files in the <SAMP>conf</SAMP> directory. - -<H2><A NAME="use">Configuring Apache for Windows</A></H2> - -Apache is configured by files in the <SAMP>conf</SAMP> -directory. These are the same as files used to configure the Unix -version, but there are a few different directives for Apache on -Windows. See the <A HREF="./">Apache documentation</A> for all the -available directives. - -<P> - -The main differences in Apache for Windows are: - -<UL> - <LI><P>Because Apache for Windows is multithreaded, it does not use a - separate process for each request, as Apache does with - Unix. Instead there are usually only two Apache processes running: - a parent process, and a child which handles the requests. Within - the child each request is handled by a separate thread. - <P> - - So the "process"-management directives are different: - <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="mod/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 50</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_so.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_so.html#creating">creating loadable - modules</A> is also available.</P> - <LI><P>Apache can also load ISAPI Extensions (<EM>i.e.</EM>, Internet Server - Applications), such as those used by Microsoft's IIS, and other - Windows servers. <A HREF="mod/mod_isapi.html">More information - is available.</A> -</UL> - -<H2><A NAME="service">Running Apache for Windows as a Service</A></H2> - <STRONG>Note: The -n option to specify a service name is only available - with Apache 1.3.7 and later. Earlier versions of Apache only support - the default service name 'Apache'.</STRONG> - -<P> - -You can install Apache as a Windows NT service as follows: - -<PRE> - apache -i -n "service name" -</PRE> - -To install a service to use a particular configuration, specify the -configuration file when the service is installed: - -<PRE> - apache -i -n "service name" -f "\my server\conf\my.conf" -</PRE> - -To remove an Apache service, use - -<PRE> - apache -u -n "service name" -</PRE> - -The default "service name", if one is not specified, is "Apache". - -<P> - -Once a service is installed, you can use the <SAMP>-n</SAMP> option, in conjunction -with other options, to refer to a service's configuration file. For example:<br> - -To test a service's configuration file: -<PRE> - apache -n "service name" -t -</PRE> - -To start a console Apache using a service's configuration file: -<PRE> - apache -n "service name" -</PRE> - -<H2><A NAME="cmdline">Running Apache for Windows from the Command Line</A></H2> - -The Start menu icons and the NT Service manager can provide a simple -interface for administering Apache. But in some cases it is easier to -work from the command line. - -<P> -When working with Apache it is important to know how it will find the -configuration files. You can specify a configuration file on the command line -in two ways: - -<UL> -<LI>-f specifies a path to a particular configuration file -</UL> -<PRE> apache -f "c:\my server\conf\my.conf"</PRE> -<PRE> apache -f test\test.conf</PRE> -<UL> -<LI>-n specifies the configuration file of an installed Apache service (Apache 1.3.7 and later) -</UL> -<PRE> apache -n "service name"</PRE> - -In these cases, the proper ServerRoot should be set in the configuration file. - -<P> - -If you don't specify a configuration file name with -f or -n, Apache will -use the file name compiled into the server, usually "conf/httpd.conf". Invoking -Apache with the -V switch will display this value labeled as SERVER_CONFIG_FILE. -Apache will then determine it's ServerRoot by trying the following, in this order: - -<UL> -<LI>A ServerRoot directive via a -C switch. -<LI>The -d switch on the command line. -<LI>Current working directory -<LI>A registry entry, created if you did a binary install. -<LI>The server root compiled into the server. -</UL> - -<P> -The server root compiled into the server is usually "/apache". -invoking apache with the -V switch will display this value -labeled as HTTPD_ROOT. - -<P> -When invoked from the start menu, Apache is usually passed no arguments, -so using the registry entry is the preferred technique for console Apache. - -<P> -During a binary installation, a registry key will have -been installed, for example: -<PRE> - HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\1.3.4\ServerRoot -</PRE> - -<P> -This key is compiled into the server and can enable you to test -new versions without affecting the current version. Of course -you must take care not to install the new version on top of the -old version in the file system. - -<P> -If you did not do a binary install then Apache will in some -scenarios complain that about the missing registry key. This -warning can be ignored if it otherwise was able to find it's -configuration files. - -<P> -The value of this key is the "ServerRoot" directory, containing the -<SAMP>conf</SAMP> directory. When Apache starts it will read the -<SAMP>httpd.conf</SAMP> file from this directory. If this file -contains a <SAMP>ServerRoot</SAMP> directive which is different from -the directory obtained from the registry key above, Apache will forget -the registry key and use the directory from the configuration file. -If you copy the Apache directory or configuration files to a new -location it is vital that you update the <SAMP>ServerRoot</SAMP> -directory in the <SAMP>httpd.conf</SAMP> file to the new location. - -<P> -To run Apache from the command line as a console application, use the -following command: - -<PRE> - apache -</PRE> - -Apache will execute, and will remain running until it is stopped by pressing -control-C. - -<H2><A NAME="signalsrv">Signalling Service Apache when running</A></H2> - -On Windows NT, multiple instances of Apache can be run as services. -Signal an Apache service to start, restart, or shutdown as follows: - -<PRE> - apache -n "service name" -k start - apache -n "service name" -k restart - apache -n "service name" -k shutdown -</PRE> - -In addition, you can use the native NT NET command to -start and stop Apache services as follows: - -<PRE> - NET START "service name" - NET STOP "service name" -</PRE> - -<H2><A NAME="signal">Signalling Console Apache when running</A></H2> - -On Windows 95, Apache runs as a console application. You can tell a -running Apache to stop by opening another console window and running - -<PRE> - apache -k shutdown -</PRE> -<BLOCKQUOTE> - <STRONG>Note: This option is only available with Apache 1.3.3 and - later. For earlier versions, you need to use Control-C in the - Apache console window to shut down the server.</STRONG> -</BLOCKQUOTE> - -<P> -This should be used instead of pressing Control-C in the running -Apache console window, because it lets Apache end any current -transactions and cleanup gracefully. - -<P> - -You can also tell Apache to restart. This makes it re-read the -configuration files. Any transactions in progress are allowed to -complete without interruption. To restart Apache, run - -<PRE> - apache -k restart -</PRE> -<BLOCKQUOTE> - <STRONG>Note: This option is only available with Apache 1.3.3 and - later. For earlier versions, you need to use Control-C in the - Apache console window to shut down the server.</STRONG> -</BLOCKQUOTE> - -<P> -Note for people familiar with the Unix version of Apache: these -commands provide a Windows equivalent to <CODE>kill -TERM -<EM>pid</EM></CODE> and <CODE>kill -USR1 <EM>pid</EM></CODE>. The command -line option used, <CODE>-k</CODE>, was chosen as a reminder of the -"kill" command used on Unix. - -<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, <EM>etc.</EM>..). 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 on Windows NT, simply - use one of the following commands: -<UL> -<LI><CODE>nmake /f Makefile.nt _apacher</CODE> (release build) -<LI><CODE>nmake /f Makefile.nt _apached</CODE> (debug build) -</UL> - -<P><em>(1.3.4 and later)</em> To compile Apache on Windows 95, use one of -<UL> -<LI><CODE>nmake /f Makefile_win32.txt</CODE> (release build) -<LI><CODE>nmake /f Makefile_win32_debug.txt</CODE> (debug build) -</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. - Project files (<CODE>.DSP</CODE>) are included for each of the - portions of Apache. To build Apache from the these projects files - you will need to build the following projects <EM>in this order</EM>: - - <OL> - <LI><CODE>os\win32\ApacheOS.dsp</CODE> - <LI><CODE>regex\regex.dsp</CODE> - <LI><CODE>ap\ap.dsp</CODE> - <LI><CODE>main\gen_uri_delims.dsp</CODE> - <LI><CODE>main\gen_test_char.dsp</CODE> - <LI><CODE>ApacheCore.dsp</CODE> - <LI><CODE>Apache.dsp</CODE> - </OL> - - In addition, the <CODE>src\os\win32</CODE> subdirectory contains - project files for the optional modules (see below).</P> - -<P>Once Apache has been compiled, it needs to be installed in its server - root directory. The default is the <CODE>\Apache</CODE> - directory, on the current hard drive. </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 INSTDIR=<EM>dir</EM></CODE> - (for release build) -<LI><CODE>nmake /f Makefile.nt installd INSTDIR=<EM>dir</EM></CODE> - (for debug build) -</UL> -or, for Windows 95 (1.3.4 and later), use one of: -<UL> -<LI><CODE>nmake /f Makefile_win32.txt install INSTDIR=<EM>dir</EM></CODE> - (for release build) -<LI><CODE>nmake /f Makefile_win32_debug.txt install INSTDIR=<EM>dir</EM></CODE> - (for debug build) -</UL> - -The dir argument to INSTDIR gives the installation directory; it can -be omitted if Apache is to be installed into <SAMP>\Apache</SAMP>. - -<P>This will install the following:</P> - -<UL> - <LI><CODE><EM>dir</EM>\Apache.exe</CODE> - Apache executable - <LI><CODE><EM>dir</EM>\ApacheCore.dll</CODE> - Main Apache shared library - <LI><CODE><EM>dir</EM>\modules\ApacheModule*.dll</CODE> - Optional Apache - modules (7 files) - <LI><CODE><EM>dir</EM>\conf</CODE> - Empty configuration directory - <LI><CODE><EM>dir</EM>\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> - -<P> -Before running the server you must fill out the conf directory. -Copy the *.conf-dist-win from the distribution conf directory -and rename *.conf. Edit the @@ServerRoot@@ entries to your -actual server root (for example "C:\apache"). Copy over -the conf/magic and conf/mime.types files as well. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/process-model.html b/docs/manual/process-model.html deleted file mode 100644 index 74f7d4e6eb..0000000000 --- a/docs/manual/process-model.html +++ /dev/null @@ -1,68 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Server Pool Management</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Server Pool Management</H1> - -<HR> -<P> -We found that many people were using values for "MaxServers" either -too high or too low, and were hanging themselves on it. The model we -adopted is still based on long-lived minimal-forking processes, but -instead of specifying one number of persistent processes, the -web-master specifies a maximum and minimum number of processes to be -"spare" - every couple of seconds the parent checks the actual number -of spare servers and adjusts accordingly. This should keep the number -of servers concurrently running relatively low while still ensuring -minimal forking. - -<P> - -We renamed the current StartServers to MinSpareServers, created -separate StartServers parameter which means what it says, and renamed -MaxServers to MaxSpareServers (though the old name still works, for -NCSA 1.4 back-compatibility). The old names were generally regarded -as too confusing. - -<P> - -The defaults for each variable are: - -<PRE> -MinSpareServers 5 -MaxSpareServers 10 -StartServers 5 -</PRE> - -There is an absolute maximum number of simultaneous children defined -by a compile-time limit which defaults to 256 and a "MaxClients" -directive which specifies the number of simultaneous children that -will be allowed. MaxClients can be adjusted up to the compile-time -limit (HARD_SERVER_LIMIT, defined in httpd.h). If you need more -than 256 simultaneous children, you need to modify both HARD_SERVER_LIMIT -and MaxClients.<P> - -In versions before 1.2, HARD_SERVER_LIMIT defaulted to 150.<P> - -We do not recommend changing either of these values unless: - -<OL> -<LI>You know you have the server resources to handle more -<LI>You use the machine for other purposes and must limit the amount of memory -Apache uses -</OL> - -<!--#include virtual="footer.html" --> -</BODY></HTML> - - diff --git a/docs/manual/search/manual-index.cgi b/docs/manual/search/manual-index.cgi deleted file mode 100644 index 033529937f..0000000000 --- a/docs/manual/search/manual-index.cgi +++ /dev/null @@ -1,246 +0,0 @@ -#!/usr/local/bin/perl5 -w -# ==================================================================== -# Copyright (c) 1995-1997 The Apache Group. All rights reserved. -# -# Redistribution and use in source and binary forms, with or without -# modification, are permitted provided that the following conditions -# are met: -# -# 1. Redistributions of source code must retain the above copyright -# notice, this list of conditions and the following disclaimer. -# -# 2. Redistributions in binary form must reproduce the above copyright -# notice, this list of conditions and the following disclaimer in -# the documentation and/or other materials provided with the -# distribution. -# -# 3. All advertising materials mentioning features or use of this -# software must display the following acknowledgment: -# "This product includes software developed by the Apache Group -# for use in the Apache HTTP server project (http://www.apache.org/)." -# -# 4. The names "Apache Server" and "Apache Group" must not be used to -# endorse or promote products derived from this software without -# prior written permission. -# -# 5. Redistributions of any form whatsoever must retain the following -# acknowledgment: -# "This product includes software developed by the Apache Group -# for use in the Apache HTTP server project (http://www.apache.org/)." -# -# THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY -# EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE GROUP OR -# ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED -# OF THE POSSIBILITY OF SUCH DAMAGE. -# ==================================================================== -# -# manual-index.cgi script -# originally written by Ken Coar <Coar@DECUS.Org> in May 1997 -# -# This script either displays a form in order to find documents in which -# a word appears, or displays the results of such a search. It is -# called as a CGI script. -# -# [FILE]PATH_INFO is the prefix to add to to the files names found in -# the index (URL prefix, not filesystem prefix), and QUERY_STRING is the -# word to be found. -# -#*** -#*** -# You may need to tweak the following line to point to the correct -# location of the index file on your system (it's in the -# apache/htdocs/manual directory of the Apache distribution tree). -#*** -#*** -$INDEX = "/www/apache.org/manual-index-data"; - -#*** -#*** -# You shouldn't have to modify anything else. -#*** -#*** - -$HTML = ""; - -# -# If we have a FILEPATH_INFO or PATH_INFO, it's there to remap the -# documents to the manual root directory. If this script is already in -# that directory, this isn't needed. -# -$prefix = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'}; -$prefix .= "/" if ($prefix && ($prefix !~ m:/$:)); - -# -# QUERY_STRING, if present, contains the word for which we are to -# search. We also use its [non]presence to determine wha we display. -# -$word = $ENV{'QUERY_STRING'}; - -# -# Make sure our HTTP header makes it to the server by causing Perl to do -# a fflush() after every write to STDOUT. -# -select (STDOUT); -$| = 1; -printf ("Content-type: text/html\n\n"); - -# -# Fine, now buffering can go back to normal. -# -$| = 0; - -# -# Set up the HTML page title -$title = "Apache Documentation Search"; -$title .= ": Results for \"$word\"" if ($word); - -# -# We'll re-use the HTML scalar several times; we use it with here -# documents for multi-line static HTML code. Lets' do the standard page -# header. -# -$HTML = <<EOHT; -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>$title - </TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <DIV ALIGN="CENTER"> - <IMG - SRC="${prefix}images/sub.gif" - ALT="" - > - </DIV> - <H1 ALIGN="CENTER"> - Apache Documentation Search - </H1> - <P> - This script performs a very simple search across the Apache - documentation for any single case-insensitive word. No combinations, - wildcards, regular expressions, word-stubbing, or other fancy options - are supported; this is just to help you find topics quickly. Only - those pages which include the <EM>exact</EM> word you type will be - listed. - </P> - <P> - Documents containing the search word are <EM>not</EM> listed in any - sort of priority order. - </P> - <ISINDEX PROMPT="Enter word to find and press ENTER: "> -EOHT - -printf ($HTML); - -# -# Now set up the next section, which is only displayed if we've been -# given a word to find. -# -$HTML = <<EOHT; - <HR> - <H2> - Results of Search for <SAMP>$word</SAMP> - </H2> -EOHT - -# -# We enblock the next section so problems can drop out to the common -# closure code. -# -QUERY: - { - if ($word) { - # - # Try and open the index file; complain bitterly if we can't. - # - if (! open (INDEX, "<$INDEX")) { - printf ("Can't find documentation index!"); - last QUERY; - } - # - # Got it; display the search-results header. - # - printf ($HTML); - # - # Read the entire index in and turn it into an hash for the - # lookup. - # - @index = <INDEX>; - close (INDEX); - chomp (@index); - foreach (@index) { - ($key, $files) = split (/:/, $_); - $Index{$key} = $files; - } - # - # The dictionary is all lowercase words. Smash our query value - # and try to find it. - # - $word = lc ($word); - if (! exists ($Index{$word})) { - printf (" <P>\n <EM>Sorry, no matches found.</EM>\n </P>\n"); - last QUERY; - } - # - # Found an entry, so turn the hash value (a comma-separated list - # of relative file names) into an array for display. - # Incidentally, tell the user how many there are. - # - @files = split (/,/, $Index{$word}); - printf (" <P>Total of %d match", scalar (@files)); - # - # Be smart about plurals. - # - if (scalar (@files) != 1) { - printf ("es") ; - } - printf (" found.\n </P>\n"); - # - # Right. Now display the files as they're listed. - # - printf (" <OL>\n"); - foreach (@files) { - printf (" <LI><A HREF=\"${prefix}$_\">"); - printf ("<SAMP>$_</SAMP></A>\n"); - printf (" </LI>\n"); - } - printf (" </OL>\n"); - # - # C'est tout! - # - } - } - -# -# Back to common code - the exit path. Display the page trailer. -# -$HTML = <<EOHT; - <A - HREF="/" - ><IMG - SRC="/images/apache_home.gif" - ALT="Home" - ></A> - <HR> - </BODY> -</HTML> -EOHT - -printf ($HTML); -exit (0); diff --git a/docs/manual/sections.html b/docs/manual/sections.html deleted file mode 100644 index 88f3329408..0000000000 --- a/docs/manual/sections.html +++ /dev/null @@ -1,170 +0,0 @@ -<!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="mod/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). Semantically however some things, and the most -notable are <CODE>AllowOverride</CODE> and the two options -<CODE>FollowSymLinks</CODE> and <CODE>SymLinksIfOwnerMatch</CODE>, -make no sense in <CODE><Location></CODE>, -<CODE><LocationMatch></CODE> or <CODE><DirectoryMatch></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 -<EM>after</EM> 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 <EM>before</EM> 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> - -<P> -Note about .htaccess parsing: -</P> -<UL> -<LI> - Modifying .htaccess parsing during Location doesn't do - anything because .htaccess parsing has already occurred. -</UL> - -<P> -<CODE><Location></CODE> and symbolic links: -</P> -<UL> -<LI> - It is not possible to use "<CODE>Options FollowSymLinks</CODE>" - or "<CODE>Options SymLinksIfOwnerMatch</CODE>" inside a - <CODE><Location></CODE>, <CODE><LocationMatch></CODE> - or <CODE><DirectoryMatch></CODE> section - (the options are simply ignored). - Using the options in question is only possible inside a - <CODE><Directory></CODE> section (or a <CODE>.htaccess</CODE> file). -</UL> - -<P> -<CODE><Files></CODE> and <CODE>Options</CODE>: -</P> -<UL> -<LI> - Apache won't check for it, but using an <CODE>Options</CODE> - directive inside a <CODE><Files></CODE> section has no effect. -</UL> - -<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> diff --git a/docs/manual/sections.html.en b/docs/manual/sections.html.en deleted file mode 100644 index 88f3329408..0000000000 --- a/docs/manual/sections.html.en +++ /dev/null @@ -1,170 +0,0 @@ -<!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="mod/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). Semantically however some things, and the most -notable are <CODE>AllowOverride</CODE> and the two options -<CODE>FollowSymLinks</CODE> and <CODE>SymLinksIfOwnerMatch</CODE>, -make no sense in <CODE><Location></CODE>, -<CODE><LocationMatch></CODE> or <CODE><DirectoryMatch></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 -<EM>after</EM> 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 <EM>before</EM> 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> - -<P> -Note about .htaccess parsing: -</P> -<UL> -<LI> - Modifying .htaccess parsing during Location doesn't do - anything because .htaccess parsing has already occurred. -</UL> - -<P> -<CODE><Location></CODE> and symbolic links: -</P> -<UL> -<LI> - It is not possible to use "<CODE>Options FollowSymLinks</CODE>" - or "<CODE>Options SymLinksIfOwnerMatch</CODE>" inside a - <CODE><Location></CODE>, <CODE><LocationMatch></CODE> - or <CODE><DirectoryMatch></CODE> section - (the options are simply ignored). - Using the options in question is only possible inside a - <CODE><Directory></CODE> section (or a <CODE>.htaccess</CODE> file). -</UL> - -<P> -<CODE><Files></CODE> and <CODE>Options</CODE>: -</P> -<UL> -<LI> - Apache won't check for it, but using an <CODE>Options</CODE> - directive inside a <CODE><Files></CODE> section has no effect. -</UL> - -<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> diff --git a/docs/manual/stopping.html b/docs/manual/stopping.html deleted file mode 100644 index 783d1c0250..0000000000 --- a/docs/manual/stopping.html +++ /dev/null @@ -1,183 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Stopping and Restarting Apache</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Stopping and Restarting Apache</H1> - -<P>This document covers stopping and restarting Apache on Unix -only. Windows users should see <A HREF="windows.html#signal">Signalling -Apache when running</A>.</P> - -<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/apache/logs/httpd.pid` -</PRE></BLOCKQUOTE> - -You can read about its progress by issuing: - -<BLOCKQUOTE><PRE> - tail -f /usr/local/apache/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. - -<P>As of Apache 1.3 we provide a script <CODE>src/support/apachectl</CODE> -which can be used to start, stop, and restart Apache. It may need a -little customization for your system, see the comments at the top of -the script. - -<H3>TERM Signal: stop now</H3> - -<P>Sending the <CODE>TERM</CODE> signal to the parent causes it to -immediately attempt to kill off all of its children. It may take it -several seconds to complete killing off its children. Then the -parent itself exits. Any requests in progress are terminated, and no -further requests are served. - -<H3>HUP Signal: restart now</H3> - -<P>Sending the <CODE>HUP</CODE> signal to the parent causes it to kill off -its children like in <CODE>TERM</CODE> but the parent doesn't exit. It -re-reads its configuration files, and re-opens any log files. -Then it spawns a new set of children and continues -serving hits. - -<P>Users of the -<A HREF="mod/mod_status.html">status module</A> -will notice that the server statistics are -set to zero when a <CODE>HUP</CODE> is sent. - -<P><STRONG>Note:</STRONG> If your configuration file has errors in it when -you issue a -restart then your parent will not restart, it will exit with an error. -See below for a method of avoiding this. - -<H3>USR1 Signal: graceful restart</H3> - -<P><STRONG>Note:</STRONG> 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 <EM>advise</EM> -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 <EM>generation</EM> 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 <STRONG>not</STRONG> 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 <EM>scoreboard</EM> used to keep track -of all children across generations. - -<P>The status module will also use a <CODE>G</CODE> to indicate those -children which are still serving requests started before the graceful -restart was given. - -<P>At present there is no way for a log rotation script using -<CODE>USR1</CODE> to know for certain that all children writing the -pre-restart log have finished. We suggest that you use a suitable delay -after sending the <CODE>USR1</CODE> signal before you do anything with the -old log. For example if most of your hits take less than 10 minutes to -complete for users on low bandwidth links then you could wait 15 minutes -before doing anything with the old log. - -<P><STRONG>Note:</STRONG> If your configuration file has errors in it when -you issue a -restart then your parent will not restart, it will exit with an error. -In the case of graceful -restarts it will also leave children running when it exits. (These are -the children which are "gracefully exiting" by handling their last request.) -This will cause problems if you attempt to restart the server -- it will -not be able to bind to its listening ports. Before doing a restart, you -can check the syntax of the configuration files with the <CODE>-t</CODE> -command line argument (see <A HREF="invoking.html">Starting -Apache</A>). This still will not guarantee that the server will restart -correctly. To check the semantics of the configuration files as well -as the syntax, you can try starting httpd as a non-root user. If -there are no errors it will attempt to open its sockets and logs and -fail because it's not root (or because the currently running httpd -already has those ports bound). If it fails for any other reason then -it's probably a config file error and the error should be fixed before -issuing the graceful restart. - - -<H3>Appendix: signals and race conditions</H3> - -<P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM> -involving the restart and die signals (a simple description of race -condition is: a time-sensitive problem, as in if something happens at just -the wrong time it won't behave as expected). For those architectures that -have the "right" feature set we have eliminated as many as we can. -But it should be noted that there still do exist race conditions on -certain architectures. - -<P>Architectures that use an on disk -<A HREF="mod/core.html#scoreboardfile">ScoreBoardFile</A> -have the potential to corrupt their scoreboards. This can result in -the "bind: Address already in use" (after <CODE>HUP</CODE>) or -"long lost child came home!" (after <CODE>USR1</CODE>). The former is -a fatal error, while the latter just causes the server to lose a scoreboard -slot. So it might be advisable to use graceful restarts, with -an occasional hard restart. These problems are very difficult to work -around, but fortunately most architectures do not require a scoreboard file. -See the ScoreBoardFile documentation for a method to determine if your -architecture uses it. - -<P><CODE>NEXT</CODE> and <CODE>MACHTEN</CODE> (68k only) have small race -conditions -which can cause a restart/die signal to be lost, but should not cause the -server to do anything otherwise problematic. -<!-- they don't have sigaction, or we're not using it -djg --> - -<P>All architectures have a small race condition in each child involving -the second and subsequent requests on a persistent HTTP connection -(KeepAlive). It may exit after reading the request line but before -reading any of the request headers. There is a fix that was discovered -too late to make 1.2. In theory this isn't an issue because the KeepAlive -client has to expect these events because of network latencies and -server timeouts. In practice it doesn't seem to affect anything either --- in a test case the server was restarted twenty times per second and -clients successfully browsed the site without getting broken images or -empty documents. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/stopping.html.en b/docs/manual/stopping.html.en deleted file mode 100644 index 783d1c0250..0000000000 --- a/docs/manual/stopping.html.en +++ /dev/null @@ -1,183 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Stopping and Restarting Apache</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Stopping and Restarting Apache</H1> - -<P>This document covers stopping and restarting Apache on Unix -only. Windows users should see <A HREF="windows.html#signal">Signalling -Apache when running</A>.</P> - -<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/apache/logs/httpd.pid` -</PRE></BLOCKQUOTE> - -You can read about its progress by issuing: - -<BLOCKQUOTE><PRE> - tail -f /usr/local/apache/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. - -<P>As of Apache 1.3 we provide a script <CODE>src/support/apachectl</CODE> -which can be used to start, stop, and restart Apache. It may need a -little customization for your system, see the comments at the top of -the script. - -<H3>TERM Signal: stop now</H3> - -<P>Sending the <CODE>TERM</CODE> signal to the parent causes it to -immediately attempt to kill off all of its children. It may take it -several seconds to complete killing off its children. Then the -parent itself exits. Any requests in progress are terminated, and no -further requests are served. - -<H3>HUP Signal: restart now</H3> - -<P>Sending the <CODE>HUP</CODE> signal to the parent causes it to kill off -its children like in <CODE>TERM</CODE> but the parent doesn't exit. It -re-reads its configuration files, and re-opens any log files. -Then it spawns a new set of children and continues -serving hits. - -<P>Users of the -<A HREF="mod/mod_status.html">status module</A> -will notice that the server statistics are -set to zero when a <CODE>HUP</CODE> is sent. - -<P><STRONG>Note:</STRONG> If your configuration file has errors in it when -you issue a -restart then your parent will not restart, it will exit with an error. -See below for a method of avoiding this. - -<H3>USR1 Signal: graceful restart</H3> - -<P><STRONG>Note:</STRONG> 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 <EM>advise</EM> -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 <EM>generation</EM> 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 <STRONG>not</STRONG> 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 <EM>scoreboard</EM> used to keep track -of all children across generations. - -<P>The status module will also use a <CODE>G</CODE> to indicate those -children which are still serving requests started before the graceful -restart was given. - -<P>At present there is no way for a log rotation script using -<CODE>USR1</CODE> to know for certain that all children writing the -pre-restart log have finished. We suggest that you use a suitable delay -after sending the <CODE>USR1</CODE> signal before you do anything with the -old log. For example if most of your hits take less than 10 minutes to -complete for users on low bandwidth links then you could wait 15 minutes -before doing anything with the old log. - -<P><STRONG>Note:</STRONG> If your configuration file has errors in it when -you issue a -restart then your parent will not restart, it will exit with an error. -In the case of graceful -restarts it will also leave children running when it exits. (These are -the children which are "gracefully exiting" by handling their last request.) -This will cause problems if you attempt to restart the server -- it will -not be able to bind to its listening ports. Before doing a restart, you -can check the syntax of the configuration files with the <CODE>-t</CODE> -command line argument (see <A HREF="invoking.html">Starting -Apache</A>). This still will not guarantee that the server will restart -correctly. To check the semantics of the configuration files as well -as the syntax, you can try starting httpd as a non-root user. If -there are no errors it will attempt to open its sockets and logs and -fail because it's not root (or because the currently running httpd -already has those ports bound). If it fails for any other reason then -it's probably a config file error and the error should be fixed before -issuing the graceful restart. - - -<H3>Appendix: signals and race conditions</H3> - -<P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM> -involving the restart and die signals (a simple description of race -condition is: a time-sensitive problem, as in if something happens at just -the wrong time it won't behave as expected). For those architectures that -have the "right" feature set we have eliminated as many as we can. -But it should be noted that there still do exist race conditions on -certain architectures. - -<P>Architectures that use an on disk -<A HREF="mod/core.html#scoreboardfile">ScoreBoardFile</A> -have the potential to corrupt their scoreboards. This can result in -the "bind: Address already in use" (after <CODE>HUP</CODE>) or -"long lost child came home!" (after <CODE>USR1</CODE>). The former is -a fatal error, while the latter just causes the server to lose a scoreboard -slot. So it might be advisable to use graceful restarts, with -an occasional hard restart. These problems are very difficult to work -around, but fortunately most architectures do not require a scoreboard file. -See the ScoreBoardFile documentation for a method to determine if your -architecture uses it. - -<P><CODE>NEXT</CODE> and <CODE>MACHTEN</CODE> (68k only) have small race -conditions -which can cause a restart/die signal to be lost, but should not cause the -server to do anything otherwise problematic. -<!-- they don't have sigaction, or we're not using it -djg --> - -<P>All architectures have a small race condition in each child involving -the second and subsequent requests on a persistent HTTP connection -(KeepAlive). It may exit after reading the request line but before -reading any of the request headers. There is a fix that was discovered -too late to make 1.2. In theory this isn't an issue because the KeepAlive -client has to expect these events because of network latencies and -server timeouts. In practice it doesn't seem to affect anything either --- in a test case the server was restarted twenty times per second and -clients successfully browsed the site without getting broken images or -empty documents. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/suexec.html b/docs/manual/suexec.html deleted file mode 100644 index 3d8623df04..0000000000 --- a/docs/manual/suexec.html +++ /dev/null @@ -1,518 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache suEXEC Support</TITLE> -</HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Apache suEXEC Support</H1> - -<P ALIGN="LEFT"> -<OL> - <LI><BIG><STRONG>CONTENTS</STRONG></BIG></LI> - <LI><A HREF="#what">What is suEXEC?</A></LI> - <LI><A HREF="#before">Before we begin.</A></LI> - <LI><A HREF="#model">suEXEC Security Model.</A></LI> - <LI><A HREF="#install">Configuring & Installing suEXEC</A></LI> - <LI><A HREF="#enable">Enabling & Disabling suEXEC</A></LI> - <LI><A HREF="#usage">Using suEXEC</A></LI> - <LI><A HREF="#debug">Debugging suEXEC</A></LI> - <LI><A HREF="#jabberwock">Beware the Jabberwock: Warnings & - Examples</A></LI> -</OL> -</P> - -<H3><A NAME="what">What is suEXEC?</A></H3> -<P ALIGN="LEFT"> -The <STRONG>suEXEC</STRONG> feature -- introduced in Apache 1.2 -- provides -Apache users the ability to run <STRONG>CGI</STRONG> and <STRONG>SSI</STRONG> -programs under user IDs different from the user ID of the calling web-server. -Normally, when a CGI or SSI program executes, it runs as the same user who is -running the web server. -</P> - -<P ALIGN="LEFT"> -Used properly, this feature can reduce considerably the security risks involved -with allowing users to develop and run private CGI or SSI programs. However, -if suEXEC is improperly configured, it can cause any number of problems and -possibly create new holes in your computer's security. If you aren't familiar -with managing setuid root programs and the security issues they present, we -highly recommend that you not consider using suEXEC. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="before">Before we begin.</A></H3> -<P ALIGN="LEFT"> -Before jumping head-first into this document, you should be aware of the -assumptions made on the part of the Apache Group and this document. -</P> - -<P ALIGN="LEFT"> -First, it is assumed that you are using a UNIX derivate operating system that -is capable of <STRONG>setuid</STRONG> and <STRONG>setgid</STRONG> operations. -All command examples are given in this regard. Other platforms, if they are -capable of supporting suEXEC, may differ in their configuration. -</P> - -<P ALIGN="LEFT"> -Second, it is assumed you are familiar with some basic concepts of your -computer's security and its administration. This involves an understanding -of <STRONG>setuid/setgid</STRONG> operations and the various effects they -may have on your system and its level of security. -</P> - -<P ALIGN="LEFT"> -Third, it is assumed that you are using an <STRONG>unmodified</STRONG> -version of suEXEC code. All code for suEXEC has been carefully scrutinized and -tested by the developers as well as numerous beta testers. Every precaution -has been taken to ensure a simple yet solidly safe base of code. Altering this -code can cause unexpected problems and new security risks. It is -<STRONG>highly</STRONG> recommended you not alter the suEXEC code unless you -are well versed in the particulars of security programming and are willing to -share your work with the Apache Group for consideration. -</P> - -<P ALIGN="LEFT"> -Fourth, and last, it has been the decision of the Apache Group to -<STRONG>NOT</STRONG> make suEXEC part of the default installation of Apache. -To this end, suEXEC configuration requires of the administrator careful -attention to details. After due consideration has been given to the various -settings for suEXEC, the administrator may install suEXEC through normal -installation methods. The values for these settings need to be carefully -determined and specified by the administrator to properly maintain system -security during the use of suEXEC functionality. It is through this detailed -process that the Apache Group hopes to limit suEXEC installation only to those -who are careful and determined enough to use it. -</P> - -<P ALIGN="LEFT"> -Still with us? Yes? Good. Let's move on! -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="model">suEXEC Security Model</A></H3> -<P ALIGN="LEFT"> -Before we begin configuring and installing suEXEC, we will first discuss -the security model you are about to implement. By doing so, you may -better understand what exactly is going on inside suEXEC and what precautions -are taken to ensure your system's security. -</P> - -<P ALIGN="LEFT"> -<STRONG>suEXEC</STRONG> is based on a setuid "wrapper" program that is -called by the main Apache web server. This wrapper is called when an HTTP -request is made for a CGI or SSI program that the administrator has designated -to run as a userid other than that of the main server. When such a request -is made, Apache provides the suEXEC wrapper with the program's name and the -user and group IDs under which the program is to execute. -</P> - -<P ALIGN="LEFT"> -The wrapper then employs the following process to determine success or -failure -- if any one of these conditions fail, the program logs the failure -and exits with an error, otherwise it will continue: -<OL> - <LI><STRONG>Was the wrapper called with the proper number of - arguments?</STRONG> - <BLOCKQUOTE> - The wrapper will only execute if it is given the proper number of arguments. - The proper argument format is known to the Apache web server. If the - wrapper - is not receiving the proper number of arguments, it is either being hacked, - or - there is something wrong with the suEXEC portion of your Apache binary. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the user executing this wrapper a valid user of this - system?</STRONG> - <BLOCKQUOTE> - This is to ensure that the user executing the wrapper is truly a user of the - system. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is this valid user allowed to run the wrapper?</STRONG> - <BLOCKQUOTE> - Is this user the user allowed to run this wrapper? Only one user (the - Apache user) is allowed to execute this program. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Does the target program have an unsafe hierarchical - reference?</STRONG> - <BLOCKQUOTE> - Does the target program contain a leading '/' or have a '..' backreference? - These are not allowed; the target program must reside within the Apache - webspace. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target user name valid?</STRONG> - <BLOCKQUOTE> - Does the target user exist? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target group name valid?</STRONG> - <BLOCKQUOTE> - Does the target group exist? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target user <EM>NOT</EM> superuser?</STRONG> - <BLOCKQUOTE> - Presently, suEXEC does not allow 'root' to execute CGI/SSI programs. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target userid <EM>ABOVE</EM> the minimum ID - number?</STRONG> - <BLOCKQUOTE> - The minimum user ID number is specified during configuration. This allows - you - to set the lowest possible userid that will be allowed to execute CGI/SSI - programs. This is useful to block out "system" accounts. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target group <EM>NOT</EM> the superuser group?</STRONG> - <BLOCKQUOTE> - Presently, suEXEC does not allow the 'root' group to execute CGI/SSI - programs. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target groupid <EM>ABOVE</EM> the minimum ID - number?</STRONG> - <BLOCKQUOTE> - The minimum group ID number is specified during configuration. This allows - you - to set the lowest possible groupid that will be allowed to execute CGI/SSI - programs. This is useful to block out "system" groups. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Can the wrapper successfully become the target user and - group?</STRONG> - <BLOCKQUOTE> - Here is where the program becomes the target user and group via setuid and - setgid - calls. The group access list is also initialized with all of the groups - of which - the user is a member. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Does the directory in which the program resides exist?</STRONG> - <BLOCKQUOTE> - If it doesn't exist, it can't very well contain files. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the directory within the Apache webspace?</STRONG> - <BLOCKQUOTE> - If the request is for a regular portion of the server, is the requested - directory - within the server's document root? If the request is for a UserDir, is - the requested - directory within the user's document root? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the directory <EM>NOT</EM> writable by anyone else?</STRONG> - <BLOCKQUOTE> - We don't want to open up the directory to others; only the owner user - may be able - to alter this directories contents. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Does the target program exist?</STRONG> - <BLOCKQUOTE> - If it doesn't exists, it can't very well be executed. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target program <EM>NOT</EM> writable by anyone - else?</STRONG> - <BLOCKQUOTE> - We don't want to give anyone other than the owner the ability to - change the program. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target program <EM>NOT</EM> setuid or setgid?</STRONG> - <BLOCKQUOTE> - We do not want to execute programs that will then change our UID/GID again. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target user/group the same as the program's - user/group?</STRONG> - <BLOCKQUOTE> - Is the user the owner of the file? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Can we successfully clean the process environment to - ensure safe operations?</STRONG> - <BLOCKQUOTE> - suEXEC cleans the process' environment by establishing a safe - execution PATH (defined - during configuration), as well as only passing through those - variables whose names - are listed in the safe environment list (also created during - configuration). - </BLOCKQUOTE> - </LI> - <LI><STRONG>Can we successfully become the target program and - execute?</STRONG> - <BLOCKQUOTE> - Here is where suEXEC ends and the target program begins. - </BLOCKQUOTE> - </LI> -</OL> -</P> - -<P ALIGN="LEFT"> -This is the standard operation of the the suEXEC wrapper's security model. -It is somewhat stringent and can impose new limitations and guidelines for -CGI/SSI design, but it was developed carefully step-by-step with security -in mind. -</P> - -<P ALIGN="LEFT"> -For more information as to how this security model can limit your possibilities -in regards to server configuration, as well as what security risks can be -avoided with a proper suEXEC setup, see the -<A HREF="#jabberwock">"Beware the Jabberwock"</A> -section of this document. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="install">Configuring & Installing suEXEC</A></H3> -<P ALIGN="LEFT"> -Here's where we begin the fun. If you use Apache 1.2 or prefer to configure -Apache 1.3 with the "<CODE>src/Configure</CODE>" script you have to edit -the suEXEC header file and install the binary in its proper location -manually. This procedure is described in an -<A HREF="suexec_1_2.html">extra document</A>. -The following sections describe the configuration and installation -for Apache 1.3 with the AutoConf-style interface (APACI). -</P> - -<P ALIGN="LEFT"> -<STRONG>APACI's suEXEC configuration options</STRONG><BR> -<DL> -<DT><CODE>--enable-suexec</CODE> -<DD>This option enables the suEXEC feature which is never installed or - activated by default. At least one --suexec-xxxxx option has to be - provided together with the --enable-suexec option to let APACI - accept your request for using the suEXEC feature. -<DT><CODE>--suexec-caller=<EM>UID</EM></CODE> -<DD>The <A HREF="mod/core.html#user">username</A> under which - Apache normally runs. - This is the only user allowed to execute this program. -<DT><CODE>--suexec-docroot=<EM>DIR</EM></CODE> -<DD>Define as the DocumentRoot set for Apache. - This will be the only hierarchy (aside from UserDirs) - that can be used for suEXEC behavior. - The default directory is the --datadir value with - the suffix "/htdocs", <EM>e.g.</EM> if you configure with - "<CODE>--datadir=/home/apache</CODE>" the directory - "/home/apache/htdocs" is used as document root for - the suEXEC wrapper. -<DT><CODE>--suexec-logfile=<EM>FILE</EM></CODE> -<DD>This defines the filename to which all suEXEC transactions and - errors are logged (useful for auditing and debugging purposes). - By default the logfile is named "suexec_log" and located in your - standard logfile directory (--logfiledir). -<DT><CODE>--suexec-userdir=<EM>DIR</EM></CODE> -<DD>Define to be the subdirectory under users' - home directories where suEXEC access should - be allowed. All executables under this directory - will be executable by suEXEC as the user so - they should be "safe" programs. If you are - using a "simple" UserDir directive (ie. one - without a "*" in it) this should be set to - the same value. suEXEC will not work properly - in cases where the UserDir directive points to - a location that is not the same as the user's - home directory as referenced in the passwd file. - Default value is "public_html". - <BR> - If you have virtual hosts with a different - UserDir for each, you will need to define them to - all reside in one parent directory; then name that - parent directory here. <STRONG>If this is not defined - properly, "~userdir" cgi requests will not work!</STRONG> -<DT><CODE>--suexec-uidmin=<EM>UID</EM></CODE> -<DD>Define this as the lowest UID allowed to be a target user - for suEXEC. For most systems, 500 or 100 is common. - Default value is 100. -<DT><CODE>--suexec-gidmin=<EM>GID</EM></CODE> -<DD>Define this as the lowest GID allowed to be a target group - for suEXEC. For most systems, 100 is common and therefore - used as default value. -<DT><CODE>--suexec-safepath=<EM>PATH</EM></CODE> -<DD>Define a safe PATH environment to pass to CGI executables. - Default value is "/usr/local/bin:/usr/bin:/bin". -</DL> -</P> - -<P ALIGN="LEFT"> -<STRONG>Checking your suEXEC setup</STRONG><BR> -Before you compile and install the suEXEC wrapper you can check -the configuration with the --layout option. -<BR> -Example output: -<PRE> - suEXEC setup: - suexec binary: /usr/local/apache/sbin/suexec - document root: /usr/local/apache/share/htdocs - userdir suffix: public_html - logfile: /usr/local/apache/var/log/suexec_log - safe path: /usr/local/bin:/usr/bin:/bin - caller ID: www - minimum user ID: 100 - minimum group ID: 100 -</PRE> -</P> - -<P ALIGN="LEFT"> -<STRONG>Compiling and installing the suEXEC wrapper</STRONG><BR> -If you have enabled the suEXEC feature with the --enable-suexec option -the suexec binary (together with Apache itself) is automatically built -if you execute the command "make". -<BR> -After all components have been built you can execute the command -"make install" to install them. -The binary image "suexec" is installed in the directory defined by -the --sbindir option. Default location is "/usr/local/apache/sbin/suexec". -<BR> -Please note that you need <STRONG><EM>root privileges</EM></STRONG> for -the installation step. In order for the wrapper to set the user ID, it -must be installed as owner <CODE><EM>root</EM></CODE> and must have the -setuserid execution bit set for file modes. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3> -<P ALIGN="LEFT"> -Upon startup of Apache, it looks for the file "suexec" in the "sbin" -directory (default is "/usr/local/apache/sbin/suexec"). -If Apache finds a properly configured suEXEC wrapper, it will print -the following message to the error log: -<PRE> - [notice] suEXEC mechanism enabled (wrapper: <EM>/path/to/suexec</EM>) -</PRE> -If you don't see this message at server startup, the server is most -likely not finding the wrapper program where it expects it, or the -executable is not installed <EM>setuid root</EM>. -<BR> -If you want to enable the suEXEC mechanism for the first time -and an Apache server is already running you must kill and restart Apache. -Restarting it with a simple HUP or USR1 signal will not be enough. -<BR> -If you want to disable suEXEC you should kill and restart Apache after -you have removed the "suexec" file. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="usage">Using suEXEC</A></H3> -<P ALIGN="LEFT"> -<STRONG>Virtual Hosts:</STRONG><BR> -One way to use the suEXEC wrapper is through the -<A HREF="mod/core.html#user">User</A> and -<A HREF="mod/core.html#group">Group</A> directives in -<A HREF="mod/core.html#virtualhost">VirtualHost</A> -definitions. By setting these directives to values different from the -main server user ID, all requests for CGI resources will be executed as -the <EM>User</EM> and <EM>Group</EM> defined for that -<CODE><VirtualHost></CODE>. If only one or -neither of these directives are specified for a -<CODE><VirtualHost></CODE> then the main -server userid is assumed. -<P> -<STRONG>User directories:</STRONG><BR> -The suEXEC wrapper can also be used to execute CGI programs as -the user to which the request is being directed. This is accomplished by -using the "<STRONG><CODE>~</CODE></STRONG>" character prefixing the user -ID for whom execution is desired. -The only requirement needed for this feature to work is for CGI -execution to be enabled for the user and that the script must meet the -scrutiny of the <A HREF="#model">security checks</A> above. - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="debug">Debugging suEXEC</A></H3> -<P ALIGN="LEFT"> -The suEXEC wrapper will write log information to the file defined -with the --suexec-logfile option as indicated above. If you feel you have -configured and installed the wrapper properly, have a look at this log -and the error_log for the server to see where you may have gone astray. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3> -<A NAME="jabberwock">Beware the Jabberwock: Warnings & Examples</A> -</H3> -<P ALIGN="LEFT"> -<STRONG>NOTE!</STRONG> This section may not be complete. For the latest -revision of this section of the documentation, see the Apache Group's -<A HREF="http://www.apache.org/docs/suexec.html">Online Documentation</A> -version. -</P> - -<P ALIGN="LEFT"> -There are a few points of interest regarding the wrapper that can cause -limitations on server setup. Please review these before submitting any -"bugs" regarding suEXEC. -<UL> - <LI><STRONG>suEXEC Points Of Interest</STRONG></LI> - <LI>Hierarchy limitations - <BLOCKQUOTE> - For security and efficiency reasons, all suexec requests must - remain within either a top-level document root for virtual - host requests, or one top-level personal document root for - userdir requests. For example, if you have four VirtualHosts - configured, you would need to structure all of your VHosts' - document roots off of one main Apache document hierarchy to - take advantage of suEXEC for VirtualHosts. (Example forthcoming.) - </BLOCKQUOTE> - </LI> - <LI>suEXEC's PATH environment variable - <BLOCKQUOTE> - This can be a dangerous thing to change. Make certain every - path you include in this define is a <STRONG>trusted</STRONG> - directory. You don't want to open people up to having someone - from across the world running a trojan horse on them. - </BLOCKQUOTE> - </LI> - <LI>Altering the suEXEC code - <BLOCKQUOTE> - Again, this can cause <STRONG>Big Trouble</STRONG> if you try - this without knowing what you are doing. Stay away from it - if at all possible. - </BLOCKQUOTE> - </LI> -</UL> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/suexec.html.en b/docs/manual/suexec.html.en deleted file mode 100644 index 3d8623df04..0000000000 --- a/docs/manual/suexec.html.en +++ /dev/null @@ -1,518 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache suEXEC Support</TITLE> -</HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Apache suEXEC Support</H1> - -<P ALIGN="LEFT"> -<OL> - <LI><BIG><STRONG>CONTENTS</STRONG></BIG></LI> - <LI><A HREF="#what">What is suEXEC?</A></LI> - <LI><A HREF="#before">Before we begin.</A></LI> - <LI><A HREF="#model">suEXEC Security Model.</A></LI> - <LI><A HREF="#install">Configuring & Installing suEXEC</A></LI> - <LI><A HREF="#enable">Enabling & Disabling suEXEC</A></LI> - <LI><A HREF="#usage">Using suEXEC</A></LI> - <LI><A HREF="#debug">Debugging suEXEC</A></LI> - <LI><A HREF="#jabberwock">Beware the Jabberwock: Warnings & - Examples</A></LI> -</OL> -</P> - -<H3><A NAME="what">What is suEXEC?</A></H3> -<P ALIGN="LEFT"> -The <STRONG>suEXEC</STRONG> feature -- introduced in Apache 1.2 -- provides -Apache users the ability to run <STRONG>CGI</STRONG> and <STRONG>SSI</STRONG> -programs under user IDs different from the user ID of the calling web-server. -Normally, when a CGI or SSI program executes, it runs as the same user who is -running the web server. -</P> - -<P ALIGN="LEFT"> -Used properly, this feature can reduce considerably the security risks involved -with allowing users to develop and run private CGI or SSI programs. However, -if suEXEC is improperly configured, it can cause any number of problems and -possibly create new holes in your computer's security. If you aren't familiar -with managing setuid root programs and the security issues they present, we -highly recommend that you not consider using suEXEC. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="before">Before we begin.</A></H3> -<P ALIGN="LEFT"> -Before jumping head-first into this document, you should be aware of the -assumptions made on the part of the Apache Group and this document. -</P> - -<P ALIGN="LEFT"> -First, it is assumed that you are using a UNIX derivate operating system that -is capable of <STRONG>setuid</STRONG> and <STRONG>setgid</STRONG> operations. -All command examples are given in this regard. Other platforms, if they are -capable of supporting suEXEC, may differ in their configuration. -</P> - -<P ALIGN="LEFT"> -Second, it is assumed you are familiar with some basic concepts of your -computer's security and its administration. This involves an understanding -of <STRONG>setuid/setgid</STRONG> operations and the various effects they -may have on your system and its level of security. -</P> - -<P ALIGN="LEFT"> -Third, it is assumed that you are using an <STRONG>unmodified</STRONG> -version of suEXEC code. All code for suEXEC has been carefully scrutinized and -tested by the developers as well as numerous beta testers. Every precaution -has been taken to ensure a simple yet solidly safe base of code. Altering this -code can cause unexpected problems and new security risks. It is -<STRONG>highly</STRONG> recommended you not alter the suEXEC code unless you -are well versed in the particulars of security programming and are willing to -share your work with the Apache Group for consideration. -</P> - -<P ALIGN="LEFT"> -Fourth, and last, it has been the decision of the Apache Group to -<STRONG>NOT</STRONG> make suEXEC part of the default installation of Apache. -To this end, suEXEC configuration requires of the administrator careful -attention to details. After due consideration has been given to the various -settings for suEXEC, the administrator may install suEXEC through normal -installation methods. The values for these settings need to be carefully -determined and specified by the administrator to properly maintain system -security during the use of suEXEC functionality. It is through this detailed -process that the Apache Group hopes to limit suEXEC installation only to those -who are careful and determined enough to use it. -</P> - -<P ALIGN="LEFT"> -Still with us? Yes? Good. Let's move on! -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="model">suEXEC Security Model</A></H3> -<P ALIGN="LEFT"> -Before we begin configuring and installing suEXEC, we will first discuss -the security model you are about to implement. By doing so, you may -better understand what exactly is going on inside suEXEC and what precautions -are taken to ensure your system's security. -</P> - -<P ALIGN="LEFT"> -<STRONG>suEXEC</STRONG> is based on a setuid "wrapper" program that is -called by the main Apache web server. This wrapper is called when an HTTP -request is made for a CGI or SSI program that the administrator has designated -to run as a userid other than that of the main server. When such a request -is made, Apache provides the suEXEC wrapper with the program's name and the -user and group IDs under which the program is to execute. -</P> - -<P ALIGN="LEFT"> -The wrapper then employs the following process to determine success or -failure -- if any one of these conditions fail, the program logs the failure -and exits with an error, otherwise it will continue: -<OL> - <LI><STRONG>Was the wrapper called with the proper number of - arguments?</STRONG> - <BLOCKQUOTE> - The wrapper will only execute if it is given the proper number of arguments. - The proper argument format is known to the Apache web server. If the - wrapper - is not receiving the proper number of arguments, it is either being hacked, - or - there is something wrong with the suEXEC portion of your Apache binary. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the user executing this wrapper a valid user of this - system?</STRONG> - <BLOCKQUOTE> - This is to ensure that the user executing the wrapper is truly a user of the - system. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is this valid user allowed to run the wrapper?</STRONG> - <BLOCKQUOTE> - Is this user the user allowed to run this wrapper? Only one user (the - Apache user) is allowed to execute this program. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Does the target program have an unsafe hierarchical - reference?</STRONG> - <BLOCKQUOTE> - Does the target program contain a leading '/' or have a '..' backreference? - These are not allowed; the target program must reside within the Apache - webspace. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target user name valid?</STRONG> - <BLOCKQUOTE> - Does the target user exist? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target group name valid?</STRONG> - <BLOCKQUOTE> - Does the target group exist? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target user <EM>NOT</EM> superuser?</STRONG> - <BLOCKQUOTE> - Presently, suEXEC does not allow 'root' to execute CGI/SSI programs. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target userid <EM>ABOVE</EM> the minimum ID - number?</STRONG> - <BLOCKQUOTE> - The minimum user ID number is specified during configuration. This allows - you - to set the lowest possible userid that will be allowed to execute CGI/SSI - programs. This is useful to block out "system" accounts. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target group <EM>NOT</EM> the superuser group?</STRONG> - <BLOCKQUOTE> - Presently, suEXEC does not allow the 'root' group to execute CGI/SSI - programs. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target groupid <EM>ABOVE</EM> the minimum ID - number?</STRONG> - <BLOCKQUOTE> - The minimum group ID number is specified during configuration. This allows - you - to set the lowest possible groupid that will be allowed to execute CGI/SSI - programs. This is useful to block out "system" groups. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Can the wrapper successfully become the target user and - group?</STRONG> - <BLOCKQUOTE> - Here is where the program becomes the target user and group via setuid and - setgid - calls. The group access list is also initialized with all of the groups - of which - the user is a member. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Does the directory in which the program resides exist?</STRONG> - <BLOCKQUOTE> - If it doesn't exist, it can't very well contain files. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the directory within the Apache webspace?</STRONG> - <BLOCKQUOTE> - If the request is for a regular portion of the server, is the requested - directory - within the server's document root? If the request is for a UserDir, is - the requested - directory within the user's document root? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the directory <EM>NOT</EM> writable by anyone else?</STRONG> - <BLOCKQUOTE> - We don't want to open up the directory to others; only the owner user - may be able - to alter this directories contents. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Does the target program exist?</STRONG> - <BLOCKQUOTE> - If it doesn't exists, it can't very well be executed. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target program <EM>NOT</EM> writable by anyone - else?</STRONG> - <BLOCKQUOTE> - We don't want to give anyone other than the owner the ability to - change the program. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target program <EM>NOT</EM> setuid or setgid?</STRONG> - <BLOCKQUOTE> - We do not want to execute programs that will then change our UID/GID again. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target user/group the same as the program's - user/group?</STRONG> - <BLOCKQUOTE> - Is the user the owner of the file? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Can we successfully clean the process environment to - ensure safe operations?</STRONG> - <BLOCKQUOTE> - suEXEC cleans the process' environment by establishing a safe - execution PATH (defined - during configuration), as well as only passing through those - variables whose names - are listed in the safe environment list (also created during - configuration). - </BLOCKQUOTE> - </LI> - <LI><STRONG>Can we successfully become the target program and - execute?</STRONG> - <BLOCKQUOTE> - Here is where suEXEC ends and the target program begins. - </BLOCKQUOTE> - </LI> -</OL> -</P> - -<P ALIGN="LEFT"> -This is the standard operation of the the suEXEC wrapper's security model. -It is somewhat stringent and can impose new limitations and guidelines for -CGI/SSI design, but it was developed carefully step-by-step with security -in mind. -</P> - -<P ALIGN="LEFT"> -For more information as to how this security model can limit your possibilities -in regards to server configuration, as well as what security risks can be -avoided with a proper suEXEC setup, see the -<A HREF="#jabberwock">"Beware the Jabberwock"</A> -section of this document. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="install">Configuring & Installing suEXEC</A></H3> -<P ALIGN="LEFT"> -Here's where we begin the fun. If you use Apache 1.2 or prefer to configure -Apache 1.3 with the "<CODE>src/Configure</CODE>" script you have to edit -the suEXEC header file and install the binary in its proper location -manually. This procedure is described in an -<A HREF="suexec_1_2.html">extra document</A>. -The following sections describe the configuration and installation -for Apache 1.3 with the AutoConf-style interface (APACI). -</P> - -<P ALIGN="LEFT"> -<STRONG>APACI's suEXEC configuration options</STRONG><BR> -<DL> -<DT><CODE>--enable-suexec</CODE> -<DD>This option enables the suEXEC feature which is never installed or - activated by default. At least one --suexec-xxxxx option has to be - provided together with the --enable-suexec option to let APACI - accept your request for using the suEXEC feature. -<DT><CODE>--suexec-caller=<EM>UID</EM></CODE> -<DD>The <A HREF="mod/core.html#user">username</A> under which - Apache normally runs. - This is the only user allowed to execute this program. -<DT><CODE>--suexec-docroot=<EM>DIR</EM></CODE> -<DD>Define as the DocumentRoot set for Apache. - This will be the only hierarchy (aside from UserDirs) - that can be used for suEXEC behavior. - The default directory is the --datadir value with - the suffix "/htdocs", <EM>e.g.</EM> if you configure with - "<CODE>--datadir=/home/apache</CODE>" the directory - "/home/apache/htdocs" is used as document root for - the suEXEC wrapper. -<DT><CODE>--suexec-logfile=<EM>FILE</EM></CODE> -<DD>This defines the filename to which all suEXEC transactions and - errors are logged (useful for auditing and debugging purposes). - By default the logfile is named "suexec_log" and located in your - standard logfile directory (--logfiledir). -<DT><CODE>--suexec-userdir=<EM>DIR</EM></CODE> -<DD>Define to be the subdirectory under users' - home directories where suEXEC access should - be allowed. All executables under this directory - will be executable by suEXEC as the user so - they should be "safe" programs. If you are - using a "simple" UserDir directive (ie. one - without a "*" in it) this should be set to - the same value. suEXEC will not work properly - in cases where the UserDir directive points to - a location that is not the same as the user's - home directory as referenced in the passwd file. - Default value is "public_html". - <BR> - If you have virtual hosts with a different - UserDir for each, you will need to define them to - all reside in one parent directory; then name that - parent directory here. <STRONG>If this is not defined - properly, "~userdir" cgi requests will not work!</STRONG> -<DT><CODE>--suexec-uidmin=<EM>UID</EM></CODE> -<DD>Define this as the lowest UID allowed to be a target user - for suEXEC. For most systems, 500 or 100 is common. - Default value is 100. -<DT><CODE>--suexec-gidmin=<EM>GID</EM></CODE> -<DD>Define this as the lowest GID allowed to be a target group - for suEXEC. For most systems, 100 is common and therefore - used as default value. -<DT><CODE>--suexec-safepath=<EM>PATH</EM></CODE> -<DD>Define a safe PATH environment to pass to CGI executables. - Default value is "/usr/local/bin:/usr/bin:/bin". -</DL> -</P> - -<P ALIGN="LEFT"> -<STRONG>Checking your suEXEC setup</STRONG><BR> -Before you compile and install the suEXEC wrapper you can check -the configuration with the --layout option. -<BR> -Example output: -<PRE> - suEXEC setup: - suexec binary: /usr/local/apache/sbin/suexec - document root: /usr/local/apache/share/htdocs - userdir suffix: public_html - logfile: /usr/local/apache/var/log/suexec_log - safe path: /usr/local/bin:/usr/bin:/bin - caller ID: www - minimum user ID: 100 - minimum group ID: 100 -</PRE> -</P> - -<P ALIGN="LEFT"> -<STRONG>Compiling and installing the suEXEC wrapper</STRONG><BR> -If you have enabled the suEXEC feature with the --enable-suexec option -the suexec binary (together with Apache itself) is automatically built -if you execute the command "make". -<BR> -After all components have been built you can execute the command -"make install" to install them. -The binary image "suexec" is installed in the directory defined by -the --sbindir option. Default location is "/usr/local/apache/sbin/suexec". -<BR> -Please note that you need <STRONG><EM>root privileges</EM></STRONG> for -the installation step. In order for the wrapper to set the user ID, it -must be installed as owner <CODE><EM>root</EM></CODE> and must have the -setuserid execution bit set for file modes. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3> -<P ALIGN="LEFT"> -Upon startup of Apache, it looks for the file "suexec" in the "sbin" -directory (default is "/usr/local/apache/sbin/suexec"). -If Apache finds a properly configured suEXEC wrapper, it will print -the following message to the error log: -<PRE> - [notice] suEXEC mechanism enabled (wrapper: <EM>/path/to/suexec</EM>) -</PRE> -If you don't see this message at server startup, the server is most -likely not finding the wrapper program where it expects it, or the -executable is not installed <EM>setuid root</EM>. -<BR> -If you want to enable the suEXEC mechanism for the first time -and an Apache server is already running you must kill and restart Apache. -Restarting it with a simple HUP or USR1 signal will not be enough. -<BR> -If you want to disable suEXEC you should kill and restart Apache after -you have removed the "suexec" file. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="usage">Using suEXEC</A></H3> -<P ALIGN="LEFT"> -<STRONG>Virtual Hosts:</STRONG><BR> -One way to use the suEXEC wrapper is through the -<A HREF="mod/core.html#user">User</A> and -<A HREF="mod/core.html#group">Group</A> directives in -<A HREF="mod/core.html#virtualhost">VirtualHost</A> -definitions. By setting these directives to values different from the -main server user ID, all requests for CGI resources will be executed as -the <EM>User</EM> and <EM>Group</EM> defined for that -<CODE><VirtualHost></CODE>. If only one or -neither of these directives are specified for a -<CODE><VirtualHost></CODE> then the main -server userid is assumed. -<P> -<STRONG>User directories:</STRONG><BR> -The suEXEC wrapper can also be used to execute CGI programs as -the user to which the request is being directed. This is accomplished by -using the "<STRONG><CODE>~</CODE></STRONG>" character prefixing the user -ID for whom execution is desired. -The only requirement needed for this feature to work is for CGI -execution to be enabled for the user and that the script must meet the -scrutiny of the <A HREF="#model">security checks</A> above. - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="debug">Debugging suEXEC</A></H3> -<P ALIGN="LEFT"> -The suEXEC wrapper will write log information to the file defined -with the --suexec-logfile option as indicated above. If you feel you have -configured and installed the wrapper properly, have a look at this log -and the error_log for the server to see where you may have gone astray. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3> -<A NAME="jabberwock">Beware the Jabberwock: Warnings & Examples</A> -</H3> -<P ALIGN="LEFT"> -<STRONG>NOTE!</STRONG> This section may not be complete. For the latest -revision of this section of the documentation, see the Apache Group's -<A HREF="http://www.apache.org/docs/suexec.html">Online Documentation</A> -version. -</P> - -<P ALIGN="LEFT"> -There are a few points of interest regarding the wrapper that can cause -limitations on server setup. Please review these before submitting any -"bugs" regarding suEXEC. -<UL> - <LI><STRONG>suEXEC Points Of Interest</STRONG></LI> - <LI>Hierarchy limitations - <BLOCKQUOTE> - For security and efficiency reasons, all suexec requests must - remain within either a top-level document root for virtual - host requests, or one top-level personal document root for - userdir requests. For example, if you have four VirtualHosts - configured, you would need to structure all of your VHosts' - document roots off of one main Apache document hierarchy to - take advantage of suEXEC for VirtualHosts. (Example forthcoming.) - </BLOCKQUOTE> - </LI> - <LI>suEXEC's PATH environment variable - <BLOCKQUOTE> - This can be a dangerous thing to change. Make certain every - path you include in this define is a <STRONG>trusted</STRONG> - directory. You don't want to open people up to having someone - from across the world running a trojan horse on them. - </BLOCKQUOTE> - </LI> - <LI>Altering the suEXEC code - <BLOCKQUOTE> - Again, this can cause <STRONG>Big Trouble</STRONG> if you try - this without knowing what you are doing. Stay away from it - if at all possible. - </BLOCKQUOTE> - </LI> -</UL> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/details.html b/docs/manual/vhosts/details.html deleted file mode 100644 index f14bd088a5..0000000000 --- a/docs/manual/vhosts/details.html +++ /dev/null @@ -1,373 +0,0 @@ -<!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 -<STRONG>Apache 1.3</STRONG>. -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 but only one -<CODE>NameVirtualHost</CODE> directive should be used for each -specific IP:port pair. - -<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 and 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 in the config file with -the specified IP address) has the highest priority and catches any request -to an unknown server name or a request without a <CODE>Host:</CODE> -header field. - -<P>If the client provided a <CODE>Host:</CODE> header field 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 field 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 field 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 field 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 - <CODE>Host:</CODE> header field 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 caught 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 (<EM>i.e.</EM>, - <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 - field if the client connected to an address (and port) which is used - for name-based vhosts, <EM>e.g.</EM>, 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> diff --git a/docs/manual/vhosts/details_1_2.html b/docs/manual/vhosts/details_1_2.html deleted file mode 100644 index 23d8e919a1..0000000000 --- a/docs/manual/vhosts/details_1_2.html +++ /dev/null @@ -1,396 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>An In-Depth Discussion of VirtualHost 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 VirtualHost Matching</H1> - -<P>This is a very rough document that was probably out of date the moment -it was written. It attempts to explain exactly what the code does when -deciding what virtual host to serve a hit from. It's provided on the -assumption that something is better than nothing. The server version -under discussion is Apache 1.2. - -<P>If you just want to "make it work" without understanding -how, there's a <A HREF="#whatworks">What Works</A> section at the bottom. - -<H3>Config File Parsing</H3> - -<P>There is a main_server 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>ServerName</CODE>, -<CODE>ServerPath</CODE>, or <CODE>ServerAlias</CODE>. - -<P>In the absence of any -<A - HREF="../mod/core.html#listen" -><SAMP>Listen</SAMP></A> -directives, the (final if there -are multiple) <CODE>Port</CODE> directive in the main_server indicates -which port httpd will listen on. - -<P> The <CODE>Port</CODE> and <CODE>ServerName</CODE> directives for -any server main or virtual are used when generating URLs such as during -redirects. - -<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> The magic <CODE>_default_</CODE> address has significance during -the matching algorithm. It essentially matches any unspecified address. - -<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. 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). Note that subsequent <CODE>Port</CODE> -statements for this vhost will not affect the ports assigned in the -address set. - -<P> -All vhosts are stored in a list which is in the reverse order that -they appeared in the config file. For example, if the config file is: - -<BLOCKQUOTE><PRE> - <VirtualHost A> - ... - </VirtualHost> - - <VirtualHost B> - ... - </VirtualHost> - - <VirtualHost C> - ... - </VirtualHost> -</PRE></BLOCKQUOTE> - -Then the list will be ordered: main_server, C, B, A. Keep this in mind. - -<P> -After parsing has completed, the list of servers is scanned, and various -merges and 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> Now a pass is made through the vhosts to fill in any missing -<CODE>ServerName</CODE> fields and to classify the vhost as either -an <EM>IP-based</EM> vhost or a <EM>name-based</EM> vhost. A vhost is -considered a name-based vhost if any of its address set overlaps the -main_server (the port associated with each address must match the -main_server's <CODE>Port</CODE>). Otherwise it is considered an IP-based -vhost. - -<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. Any vhost that includes the magic -<SAMP>_default_</SAMP> wildcard is given the same <CODE>ServerName</CODE> as -the main_server. Otherwise the vhost (which is necessarily an IP-based -vhost) is given a <CODE>ServerName</CODE> based on the result of a reverse -DNS lookup on the first address given in the <CODE>VirtualHost</CODE> -statement. - -<P> - -<H3>Vhost Matching</H3> - - -<P><STRONG>Apache 1.3 differs from what is documented -here, and documentation still has to be written.</STRONG> - -<P> -The server determines which vhost to use for a request as follows: - -<P> <CODE>find_virtual_server</CODE>: When the connection is first made -by the client, the local IP address (the IP address to which the client -connected) is looked up in the server list. A vhost is matched if it -is an IP-based vhost, the IP address matches and the port matches -(taking into account wildcards). - -<P> If no vhosts are matched then the last occurrence, if it appears, -of a <SAMP>_default_</SAMP> address (which if you recall the ordering of the -server list mentioned above means that this would be the first occurrence -of <SAMP>_default_</SAMP> in the config file) is matched. - -<P> In any event, if nothing above has matched, then the main_server is -matched. - -<P> The vhost resulting from the above search is stored with data -about the connection. We'll call this the <EM>connection vhost</EM>. -The connection vhost is constant over all requests in a particular TCP/IP -session -- that is, over all requests in a KeepAlive/persistent session. - -<P> For each request made on the connection the following sequence of -events further determines the actual vhost that will be used to serve -the request. - -<P> <CODE>check_fulluri</CODE>: If the requestURI is an absoluteURI, that -is it includes <CODE>http://hostname/</CODE>, then an attempt is made to -determine if the hostname's address (and optional port) match that of -the connection vhost. If it does then the hostname portion of the URI -is saved as the <EM>request_hostname</EM>. If it does not match, then the -URI remains untouched. <STRONG>Note</STRONG>: to achieve this address -comparison, -the hostname supplied goes through a DNS lookup unless it matches the -<CODE>ServerName</CODE> or the local IP address of the client's socket. - -<P> <CODE>parse_uri</CODE>: If the URI begins with a protocol -(<EM>i.e.</EM>, <CODE>http:</CODE>, <CODE>ftp:</CODE>) then the request is -considered a proxy request. Note that even though we may have stripped -an <CODE>http://hostname/</CODE> in the previous step, this could still -be a proxy request. - -<P> <CODE>read_request</CODE>: If the request does not have a hostname -from the earlier step, then any <CODE>Host:</CODE> header sent by the -client is used as the request hostname. - -<P> <CODE>check_hostalias</CODE>: If the request now has a hostname, -then an attempt is made to match for this hostname. The first step -of this match is to compare any port, if one was given in the request, -against the <CODE>Port</CODE> field of the connection vhost. If there's -a mismatch then the vhost used for the request is the connection vhost. -(This is a bug, see observations.) - -<P> -If the port matches, then httpd scans the list of vhosts starting with -the next server <STRONG>after</STRONG> the connection vhost. This scan does not -stop if there are any matches, it goes through all possible vhosts, -and in the end uses the last match it found. The comparisons performed -are as follows: - -<UL> -<LI>Compare the request hostname:port with the vhost - <CODE>ServerName</CODE> and <CODE>Port</CODE>. - -<LI>Compare the request hostname against any and all addresses given in - the <CODE>VirtualHost</CODE> directive for this vhost. - -<LI>Compare the request hostname against the <CODE>ServerAlias</CODE> - given for the vhost. -</UL> - -<P> -<CODE>check_serverpath</CODE>: If the request has no hostname -(back up a few paragraphs) then a scan similar to the one -in <CODE>check_hostalias</CODE> is performed to match any -<CODE>ServerPath</CODE> directives given in the vhosts. Note that the -<STRONG>last match</STRONG> is used regardless (again consider the ordering of -the virtual hosts). - -<H3>Observations</H3> - -<UL> - -<LI>It is difficult to define an IP-based vhost for the machine's - "main IP address". You essentially have to create a bogus - <CODE>ServerName</CODE> for the main_server that does not match the - machine's IPs. - <P> - -<LI>During the scans in both <CODE>check_hostalias</CODE> and - <CODE>check_serverpath</CODE> no check is made that the vhost being - scanned is actually a name-based vhost. This means, for example, that - it's possible to match an IP-based vhost through another address. But - because the scan starts in the vhost list at the first vhost that - matched the local IP address of the connection, not all IP-based vhosts - can be matched. - <P> - Consider the config file above with three vhosts A, B, C. Suppose - that B is a named-based vhost, and A and C are IP-based vhosts. If - a request comes in on B or C's address containing a header - "<SAMP>Host: A</SAMP>" then - it will be served from A's config. If a request comes in on A's - address then it will always be served from A's config regardless of - any Host: header. - </P> - -<LI>Unless you have a <SAMP>_default_</SAMP> vhost, - it doesn't matter if you mix name-based vhosts in amongst IP-based - vhosts. During the <CODE>find_virtual_server</CODE> phase above no - named-based vhost will be matched, so the main_server will remain the - connection vhost. Then scans will cover all vhosts in the vhost list. - <P> - If you do have a <SAMP>_default_</SAMP> vhost, then you cannot place - named-based vhosts after it in the config. This is because on any - connection to the main server IPs the connection vhost will always be - the <SAMP>_default_</SAMP> vhost since none of the name-based are - considered during <CODE>find_virtual_server</CODE>. - </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. - <A HREF="dns-caveats.html">There's more information - available on this and the next two topics</A>. - <P> - -<LI><CODE>ServerName</CODE> should always be set for each vhost. Otherwise - A DNS lookup is required for each vhost. - <P> - -<LI>A DNS lookup is always required for the main_server's - <CODE>ServerName</CODE> (or to generate that if it isn't specified - in the config). - <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 a vhost that would otherwise be a name-vhost includes a - <CODE>Port</CODE> statement that doesn't match the main_server - <CODE>Port</CODE> then it will be considered an IP-based vhost. - Then <CODE>find_virtual_server</CODE> will match it (because - the ports associated with each address in the address set default - to the port of the main_server) as the connection vhost. Then - <CODE>check_hostalias</CODE> will refuse to check any other name-based - vhost because of the port mismatch. The result is that the vhost - will steal all hits going to the main_server address. - <P> - -<LI>If two IP-based vhosts have an address in common, the vhost appearing - later in the file is always matched. Such a thing might happen - inadvertently. If the config has name-based vhosts and for some reason - the main_server <CODE>ServerName</CODE> resolves to the wrong address - then all the name-based vhosts will be parsed as ip-based vhosts. - Then the last of them will steal all the hits. - <P> - -<LI>The last name-based vhost in the config is always matched for any hit - which doesn't match one of the other name-based vhosts. - -</UL> - -<H3><A NAME="whatworks">What Works</A></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 VirtualHost definitions. -(This is to aid the readability of the configuration -- the post-config -merging process makes it non-obvious that definitions mixed in around -virtualhosts might affect all virtualhosts.) -<P> - -<LI>Arrange your VirtualHosts such -that all name-based virtual hosts come first, followed by IP-based -virtual hosts, followed by any <SAMP>_default_</SAMP> virtual host -<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 /abcdef"). -<P> - -<LI>Do not use <EM>port-based</EM> vhosts in the same server as -name-based vhosts. A loose definition for port-based is a vhost which -is determined by the port on the server (<EM>i.e.</EM>, one server with -ports 8000, 8080, and 80 - all of which have different configurations). -<P> - -</UL> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/examples.html b/docs/manual/vhosts/examples.html deleted file mode 100644 index 46697bcec4..0000000000 --- a/docs/manual/vhosts/examples.html +++ /dev/null @@ -1,512 +0,0 @@ -<!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><STRONG>Setup 1:</STRONG> - 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> - <STRONG>Server configuration:</STRONG> - - - <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><STRONG>Setup 2:</STRONG> - Same as setup 1, but we don't want to have a dedicated main server. - <P> - <STRONG>Server configuration:</STRONG> - - <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 addresses - of our machine are in use for IP-based virtual hosts - (only <SAMP>localhost</SAMP> requests can hit the main server). - </BLOCKQUOTE> - <P> - -<LI><STRONG>Setup 3:</STRONG> - 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> - <STRONG>Server configuration:</STRONG> - - <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 addresses - (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><STRONG>Setup 1:</STRONG> - 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> - <STRONG>Server configuration:</STRONG> - - <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><STRONG>Setup 2:</STRONG> - 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> - <STRONG>Server configuration:</STRONG> - - <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><STRONG>Setup:</STRONG> - 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> - <STRONG>Server configuration:</STRONG> - - <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><STRONG>Setup:</STRONG> - 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> - <STRONG>Server configuration:</STRONG> - - <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><STRONG>Setup 1:</STRONG> - Catching <EM>every</EM> request to any unspecified IP address and port, - <EM>i.e.</EM>, an address/port combination that is not used for any other - virtual host. - <P> - <STRONG>Server configuration:</STRONG> - - <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><STRONG>Setup 2:</STRONG> - 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> - <STRONG>Server configuration:</STRONG> - - <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><STRONG>Setup 3:</STRONG> - We want to have a default vhost for port 80, but no other default vhosts. - <P> - <STRONG>Server configuration:</STRONG> - - <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><STRONG>Setup:</STRONG> - 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> - <STRONG>Server configuration:</STRONG> - - <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><STRONG>Setup:</STRONG> - 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> - <STRONG>Server configuration:</STRONG> - - <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, <EM>i.e.</EM>, with or without URL prefix. - </BLOCKQUOTE> - -</UL> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/fd-limits.html b/docs/manual/vhosts/fd-limits.html deleted file mode 100644 index 6b9d0f93c4..0000000000 --- a/docs/manual/vhosts/fd-limits.html +++ /dev/null @@ -1,59 +0,0 @@ -<!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> - diff --git a/docs/manual/vhosts/fd-limits.html.en b/docs/manual/vhosts/fd-limits.html.en deleted file mode 100644 index 6b9d0f93c4..0000000000 --- a/docs/manual/vhosts/fd-limits.html.en +++ /dev/null @@ -1,59 +0,0 @@ -<!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> - diff --git a/docs/manual/vhosts/footer.html b/docs/manual/vhosts/footer.html deleted file mode 100644 index 7fe745dcfd..0000000000 --- a/docs/manual/vhosts/footer.html +++ /dev/null @@ -1,8 +0,0 @@ -<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> diff --git a/docs/manual/vhosts/header.html b/docs/manual/vhosts/header.html deleted file mode 100644 index 5662300029..0000000000 --- a/docs/manual/vhosts/header.html +++ /dev/null @@ -1,6 +0,0 @@ -<DIV ALIGN="CENTER"> - <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> - <H3> - Apache HTTP Server Version 1.3 - </H3> -</DIV> diff --git a/docs/manual/vhosts/host.html b/docs/manual/vhosts/host.html deleted file mode 100644 index 5788676af8..0000000000 --- a/docs/manual/vhosts/host.html +++ /dev/null @@ -1,172 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Apache non-IP 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 non-IP Virtual Hosts</H1> - -<STRONG>See Also:</STRONG> -<A HREF="virtual-host.html">Virtual Host Support</A> - -<HR> - -<H2>What is a Virtual Host</H2> - -<P>The "Virtual Host" 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 -<CODE>www.company1.com</CODE> and <CODE>www.company2.com</CODE>, -without requiring the user to know any extra path information.</P> - -<P>Apache was one of the first servers to support virtual hosts right -out of the box, but since the base <CODE>HTTP</CODE> (HyperText -Transport Protocol) standard does not allow any method for the server -to determine the hostname it is being addressed as, Apache's virtual -host support has required a separate IP address for each -server. Documentation on using this approach (which still works very -well) <A HREF="virtual-host.html">is available</A>. - -<P>While the approach described above works, with the available IP -address space growing smaller, and the number of domains increasing, -it is not the most elegant solution, and 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 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 user's browser must support this part of the protocol. The -latest versions of many browsers (including Netscape Navigator 2.0 and -later) do, but many browsers, especially older ones, 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> - <VirtualHost www.apache.org> - ServerName www.apache.org - DocumentRoot /usr/web/apache - </VirtualHost> -</PRE> - -<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 <CODE>www.apache.org</CODE> -DNS entry points to the same IP address as the main -server. Optionally, you could simply use that IP address in the -<VirtualHost> entry.</P> - -<P>Additionally, many servers may wish to be accessible by more than -one name. For example, the Apache server might want to be accessible -as <CODE>apache.org</CODE>, or <CODE>ftp.apache.org</CODE>, assuming -the IP addresses pointed to the same server. In fact, one might want it -so that all addresses at <CODE>apache.org</CODE> were picked up by the -server. This is possible with the <CODE>ServerAlias</CODE> -directive, placed inside the <VirtualHost> section. For -example:</P> - -<PRE> - ServerAlias apache.org *.apache.org -</PRE> - -<P>Note that you can use <CODE>*</CODE> and <CODE>?</CODE> as wild-card -characters.</P> - -<P>You also might need ServerAlias 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.physics" then you will need to add -<CODE>ServerAlias www www.physics</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>Security Considerations</H2> - -Apache allows all virtual hosts to be made accessible via the -<CODE>Host:</CODE> header through all IP interfaces, even those which -are configured to use different IP interfaces. For example, if the -configuration for <CODE>www.foo.com</CODE> contained a virtual host -section for <CODE>www.bar.com</CODE>, and <CODE>www.bar.com</CODE> was -a separate IP interface, such that -non-<CODE>Host:</CODE>-header-supporting browsers can use it, as -before with Apache 1.0. If a request is made to -<CODE>www.foo.com</CODE> and the request includes the header -<CODE>Host: www.bar.com</CODE>, a page from <CODE>www.bar.com</CODE> -will be sent. - -<P> - -This is a security concern if you are controlling access to a -particular server based on IP-layer controls, such as from within a -firewall or router. Let's say <CODE>www.bar.com</CODE> in the above -example was instead an intra-net server called -<CODE>private.foo.com</CODE>, and the router used by foo.com only let -internal users access <CODE>private.foo.com</CODE>. Obviously, -<CODE>Host:</CODE> header functionality now allows someone who has -access to <CODE>www.foo.com</CODE> to get -<CODE>private.foo.com</CODE>, if they send a <CODE>Host: -private.foo.com</CODE> header. It is important to note that this -condition exists only if you only implement this policy at the IP -layer - all security controls used by Apache (<EM>i.e.</EM>, <A -HREF="../mod/mod_access.html">allow, deny from,</A> <EM>etc.</EM>) are -consistently respected. - -<H2>Compatibility with Older Browsers</H2> - -<P>As mentioned earlier, a majority of browsers do not send the -required data for the new virtual hosts to work properly. These -browsers will always be sent to the main server's pages. There is a -workaround, albeit a slightly cumbersome one:</P> - -<P>To continue the <CODE>www.apache.org</CODE> example (Note: Apache's -web server does not actually function in this manner), we might use the -new <CODE>ServerPath</CODE> directive in the <CODE>www.apache.org</CODE> -virtual host, for example: - -<PRE> - ServerPath /apache -</PRE> -<P>What does this mean? It means that a request for any file beginning -with "<CODE>/apache</CODE>" will be looked for in the Apache -docs. This means that the pages can be accessed as -<CODE>http://www.apache.org/apache/</CODE> for all browsers, although -new browsers can also access it as -<CODE>http://www.apache.org/</CODE>.</P> - -<P>In order to make this work, put a link on your main server's page -to <CODE>http://www.apache.org/apache/</CODE> (Note: Do not use -<CODE>http://www.apache.org/</CODE> - this would create an endless -loop). Then, in the virtual host's pages, be sure to use either purely -relative links (<EM>e.g.</EM>, "<CODE>file.html</CODE>" or -"<CODE>../icons/image.gif</CODE>" or links containing the prefacing -<CODE>/apache/</CODE> -(<EM>e.g.</EM>, "<CODE>http://www.apache.org/apache/file.html</CODE>" or -"<CODE>/apache/docs/1.1/index.html</CODE>").</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. When -a new browser contacts <CODE>http://www.apache.org/</CODE>, they will -be directly taken to the Apache pages. Older browsers will be able to -click on the link from the main server, go to -<CODE>http://www.apache.org/apache/</CODE>, and then access the -pages.</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/index.html b/docs/manual/vhosts/index.html deleted file mode 100644 index 9a569028cf..0000000000 --- a/docs/manual/vhosts/index.html +++ /dev/null @@ -1,65 +0,0 @@ -<!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> -<LI><A HREF="mass.html">Dynamically Configured Mass Virtual Hosting with mod_rewrite</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> - -<P>Folks trying to debug their virtual host configuration may find the -Apache <CODE>-S</CODE> command line switch useful. It will dump out a -description of how Apache parsed the configuration file. Careful -examination of the IP addresses and server names may help uncover -configuration mistakes. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/index.html.en b/docs/manual/vhosts/index.html.en deleted file mode 100644 index 9a569028cf..0000000000 --- a/docs/manual/vhosts/index.html.en +++ /dev/null @@ -1,65 +0,0 @@ -<!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> -<LI><A HREF="mass.html">Dynamically Configured Mass Virtual Hosting with mod_rewrite</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> - -<P>Folks trying to debug their virtual host configuration may find the -Apache <CODE>-S</CODE> command line switch useful. It will dump out a -description of how Apache parsed the configuration file. Careful -examination of the IP addresses and server names may help uncover -configuration mistakes. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/ip-based.html b/docs/manual/vhosts/ip-based.html deleted file mode 100644 index 14e529da75..0000000000 --- a/docs/manual/vhosts/ip-based.html +++ /dev/null @@ -1,140 +0,0 @@ -<!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, these are -frequently called "ip aliases", and the "ifconfig" command -is most commonly used to set them up). - -<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>There are security partitioning issues, such as company1 does not want - anyone at company2 to be able to read their data except via the web. - In this case you would need two daemons, each running with different - <A HREF="../mod/core.html#user">User</A>, - <A HREF="../mod/core.html#group">Group</A>, - <A HREF="../mod/core.html#listen">Listen</A>, and - <A HREF="../mod/core.html#serverroot">ServerRoot</A> settings. -<LI>You can afford the memory and - <A HREF="../misc/descriptors.html">file descriptor requirements</A> of - listening to every IP alias on the machine. It's only possible to - <A HREF="../mod/core.html#listen">Listen</A> - to the "wildcard" address, or to specific addresses. So if you have - a need to listen to a specific address for whatever reason, then you - will need to listen to all specific addresses. (Although one httpd - could listen to N-1 of the addresses, and another could listen to - the remaining address.) -</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 caveats</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 caveats</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> may be 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> - diff --git a/docs/manual/vhosts/mass.html b/docs/manual/vhosts/mass.html deleted file mode 100644 index df56093680..0000000000 --- a/docs/manual/vhosts/mass.html +++ /dev/null @@ -1,403 +0,0 @@ -<!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. - -<!-- - -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</A> -<LI><A HREF="#simple">Simple dynamic virtual hosts</A> -<LI><A HREF="#homepages">A virtually hosted homepages system</A> -<LI><A HREF="#combinations">Using more than one virtual hosting system on the same server</A> -<LI><A HREF="#ipbased">More efficient IP-based virtual hosting</A> -<LI><A HREF="#oldversion">Using older versions of Apache</A> -<LI><A HREF="#simple.rewrite">Simple dynamic virtual hosts using <CODE>mod_rewrite</CODE></A> -<LI><A HREF="#homepages.rewrite">A homepages system using <CODE>mod_rewrite</CODE></A> -<LI><A HREF="#xtra-conf">Using a separate virtual host configuration file</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 many -<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 virtual host; however if you have very many virtual hosts -then doing this is dubious anyway because it eats file descriptors. It -is better to log to a pipe or a fifo and arrange for the process at -the other end to distribute the logs to the customers (it can also -accumulate statistics, etc.).</P> - - -<HR><H2><A NAME="overview">Overview</A></H2> - -<P>A virtual host is defined by two pieces of information: its IP -address, and the contents of the <CODE>Host:</CODE> header in the HTTP -request. The dynamic mass virtual hosting technique is based on -automatically inserting this information into the pathname of the file -that is used to satisfy the request. This is done most easily using -<A HREF="../mod/mod_vhost_alias.html"><CODE>mod_vhost_alias</CODE></A>, -but if you are using a version of Apache up to 1.3.6 then you must use -<A HREF="../mod/mod_rewrite.html"><CODE>mod_rewrite</CODE></A>. Both -of these modules are disabled by default; you must enable one of them -when configuring and building Apache if you want to use this technique.</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 -which is used by Apache to generate self-referential URLs, etc. It -is configured with the <CODE>ServerName</CODE> directive, and it is -available to CGIs via the <CODE>SERVER_NAME</CODE> environment -variable. The actual value used at run time is controlled by the -<A HREF="../mod/core.html#usecanonicalname"><CODE>UseCanonicalName</CODE></A> -setting. With <CODE>UseCanonicalName Off</CODE> the server name -comes from the contents of the <CODE>Host:</CODE> header in the -request. With <CODE>UseCanonicalName DNS</CODE> it comes from a -reverse DNS lookup of the virtual host's IP address. The former -setting is used for name-based dynamic virtual hosting, and the latter -is used for IP-based hosting. If Apache cannot work out the server -name because there is no <CODE>Host:</CODE> header or the DNS lookup -fails then the value configured with <CODE>ServerName</CODE> is used -instead.</P> - -<P>The other thing to `fake' is the document root (configured -with <CODE>DocumentRoot</CODE> and available to CGIs via the -<CODE>DOCUMENT_ROOT</CODE> environment variable). This setting -is used by the core module when mapping URIs to filenames, but -when the server is configured to do dynamic virtual hosting that -job is taken over by another module. If any CGIs or SSI documents -make use of the <CODE>DOCUMENT_ROOT</CODE> environment variable -they will therefore get a misleading value; there isn't any way to -change <CODE>DOCUMENT_ROOT</CODE> dynamically.</P> - - -<HR><H2><A NAME="simple">Simple 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 using -<CODE>mod_vhost_alias</CODE>.</P> - -<PRE> -# get the server name from the Host: header -UseCanonicalName Off - -# this log format can be split per-virtual-host based on the first field -LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon -CustomLog logs/access_log vcommon - -# include the server name in the filenames used to satisfy requests -VirtualDocumentRoot /www/hosts/%0/docs -VirtualScriptAlias /www/hosts/%0/cgi-bin -</PRE> - -<P>This configuration can be changed into an IP-based virtual hosting -solution by just turning <CODE>UseCanonicalName Off</CODE> into -<CODE>UseCanonicalName DNS</CODE>. The server name that is inserted -into the filename is then derived from the IP address of the virtual -host.</P> - - -<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 a slightly more complicated configuration 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> -# all the preliminary stuff is the same as above, then - -# include part of the server name in the filenames -VirtualDocumentRoot /www/hosts/%2/docs - -# single cgi-bin directory -ScriptAlias /cgi-bin/ /www/std-cgi/ -</PRE> - -<P>There are examples of more complicated -<CODE>VirtualDocumentRoot</CODE> settings in -<A HREF="../mod/mod_vhost_alias.html">the -<CODE>mod_vhost_alias</CODE> documentation</A>.</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 virtual hosting 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 conventional <CODE><VirtualHost></CODE> configuration -sections.</P> - -<PRE> -UseCanonicalName Off - -LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon - -<Directory /www/commercial> - Options FollowSymLinks - AllowOverride All -</Directory> - -<Directory /www/homepages> - Options FollowSymLinks - AllowOverride None -</Directory> - -<VirtualHost 111.22.33.44> - ServerName www.commercial.isp.com - - CustomLog logs/access_log.commercial vcommon - - VirtualDocumentRoot /www/commercial/%0/docs - VirtualScriptAlias /www/commercial/%0/cgi-bin -</VirtualHost> - -<VirtualHost 111.22.33.45> - ServerName www.homepages.isp.com - - CustomLog logs/access_log.homepages vcommon - - VirtualDocumentRoot /www/homepages/%0/docs - ScriptAlias /cgi-bin/ /www/std-cgi/ -</VirtualHost> -</PRE> - - -<HR><H2><A NAME="ipbased">More efficient IP-based virtual hosting</A></H2> - -<P>After <A HREF="#simple">the first example</A> I noted that it is -easy to turn it into an IP-based virtual hosting setup. Unfortunately -that configuration is not very efficient because it requires a DNS -lookup for every request. This can be avoided by laying out the -filesystem according to the IP addresses themselves rather than the -corresponding names and changing the logging similarly. Apache will -then usually not need to work out the server name and so incur a DNS -lookup.</P> - -<PRE> -# get the server name from the reverse DNS of the IP address -UseCanonicalName DNS - -# include the IP address in the logs so they may be split -LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon -CustomLog logs/access_log vcommon - -# include the IP address in the filenames -VirtualDocumentRootIP /www/hosts/%0/docs -VirtualScriptAliasIP /www/hosts/%0/cgi-bin -</PRE> - - -<HR><H2><A NAME="oldversion">Using older versions of Apache</A></H2> - -<P>The examples above rely on <CODE>mod_vhost_alias</CODE> which -appeared after version 1.3.6. If you are using a version of Apache -without <CODE>mod_vhost_alias</CODE> then you can implement this -technique with <CODE>mod_rewrite</CODE> as illustrated below, but -only for Host:-header-based virtual hosts.</P> - -<P>In addition there are some things to beware of with logging. Apache -1.3.6 is the first version to include the <CODE>%V</CODE> log format -directive; in versions 1.3.0 - 1.3.3 the <CODE>%v</CODE> option did -what <CODE>%V</CODE> does; version 1.3.4 has no equivalent. In -all these versions of Apache the <CODE>UseCanonicalName</CODE> -directive can appear in <CODE>.htaccess</CODE> files which means that -customers can cause the wrong thing to be logged. Therefore the best -thing to do is use the <CODE>%{Host}i</CODE> directive which logs the -<CODE>Host:</CODE> header directly; note that this may include -<CODE>:port</CODE> on the end which is not the case for -<CODE>%V</CODE>.</P> - - -<HR><H2><A NAME="simple.rewrite">Simple dynamic virtual hosts -using <CODE>mod_rewrite</CODE></A></H2> - -<P>This extract from <CODE>httpd.conf</CODE> does the same thing as -<A HREF="#simple">the first example</A>. The first half is very -similar to the corresponding part above but with some changes for -backward compatibility and to make the <CODE>mod_rewrite</CODE> part -work properly; the second half configures <CODE>mod_rewrite</CODE> to -do the actual work.</P> - -<P>There are a couple of especially tricky bits: By default, -<CODE>mod_rewrite</CODE> runs before the other URI translation modules -(<CODE>mod_alias</CODE> etc.) so if they are used then -<CODE>mod_rewrite</CODE> must be configured to accommodate them. -Also, mome magic must be performed to do a per-dynamic-virtual-host -equivalent of <CODE>ScriptAlias</CODE>.</P> - -<PRE> -# get the server name from the Host: header -UseCanonicalName Off - -# splittable logs -LogFormat "%{Host}i %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.rewrite">A homepages system -using <CODE>mod_rewrite</CODE></A></H2> - -<P>This does the same thing as <A HREF="#homepages">the -second example</A>.</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:%{SERVER_NAME}} ^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:%{SERVER_NAME}}$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 more advanced <CODE>mod_rewrite</CODE> -features to get the translation from virtual host to document root -from a separate configuration file. This provides more flexibility but -requires more complicated 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> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/name-based.html b/docs/manual/vhosts/name-based.html deleted file mode 100644 index 238cf5c721..0000000000 --- a/docs/manual/vhosts/name-based.html +++ /dev/null @@ -1,164 +0,0 @@ -<!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 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. 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 an IP address that should be used as a -target for name-based virtual hosts.</P> - -<P>For example, suppose that both <SAMP>www.domain.tld</SAMP> and -<SAMP>www.otherdomain.tld</SAMP> point at the IP address -<SAMP>111.22.33.44</SAMP>. Then 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 /www/domain - </VirtualHost> - - <VirtualHost 111.22.33.44> - ServerName www.otherdomain.tld - DocumentRoot /www/otherdomain - </VirtualHost> -</PRE> - -<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 names -<SAMP>www.domain.tld</SAMP> and <SAMP>www.otherdomain.tld</SAMP> -are pointing to the IP address <SAMP>111.22.33.44</SAMP></P> - -<P>Note: When you specify an IP address in a <CODE>NameVirtualHost</CODE> -directive then requests to that IP address will only ever be served -by matching <VirtualHost>s. The "main server" will -<STRONG>never</STRONG> be served from the specified IP address. -If you start to use virtual hosts you should stop to use the "main server" -as an independent server and rather use it as a place for -configuration directives that are common for all your virtual hosts. -In other words, you should add a <VirtualHost> section for -<EM>every</EM> server (hostname) you want to maintain on your server. - -<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. -The <CODE>ServerAlias</CODE> directive is generally a way to have different -hostnames pointing to the same virtual host. -</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 -first virtual host listed for that IP address (the -<CITE>primary</CITE> name-based virtual host).</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 (<EM>e.g.</EM>, "<SAMP>file.html</SAMP>" or -"<SAMP>../icons/image.gif</SAMP>" or links containing the prefacing -<SAMP>/domain/</SAMP> -(<EM>e.g.</EM>, "<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> diff --git a/docs/manual/vhosts/name-based.html.en b/docs/manual/vhosts/name-based.html.en deleted file mode 100644 index 238cf5c721..0000000000 --- a/docs/manual/vhosts/name-based.html.en +++ /dev/null @@ -1,164 +0,0 @@ -<!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 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. 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 an IP address that should be used as a -target for name-based virtual hosts.</P> - -<P>For example, suppose that both <SAMP>www.domain.tld</SAMP> and -<SAMP>www.otherdomain.tld</SAMP> point at the IP address -<SAMP>111.22.33.44</SAMP>. Then 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 /www/domain - </VirtualHost> - - <VirtualHost 111.22.33.44> - ServerName www.otherdomain.tld - DocumentRoot /www/otherdomain - </VirtualHost> -</PRE> - -<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 names -<SAMP>www.domain.tld</SAMP> and <SAMP>www.otherdomain.tld</SAMP> -are pointing to the IP address <SAMP>111.22.33.44</SAMP></P> - -<P>Note: When you specify an IP address in a <CODE>NameVirtualHost</CODE> -directive then requests to that IP address will only ever be served -by matching <VirtualHost>s. The "main server" will -<STRONG>never</STRONG> be served from the specified IP address. -If you start to use virtual hosts you should stop to use the "main server" -as an independent server and rather use it as a place for -configuration directives that are common for all your virtual hosts. -In other words, you should add a <VirtualHost> section for -<EM>every</EM> server (hostname) you want to maintain on your server. - -<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. -The <CODE>ServerAlias</CODE> directive is generally a way to have different -hostnames pointing to the same virtual host. -</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 -first virtual host listed for that IP address (the -<CITE>primary</CITE> name-based virtual host).</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 (<EM>e.g.</EM>, "<SAMP>file.html</SAMP>" or -"<SAMP>../icons/image.gif</SAMP>" or links containing the prefacing -<SAMP>/domain/</SAMP> -(<EM>e.g.</EM>, "<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> diff --git a/docs/manual/vhosts/vhosts-in-depth.html b/docs/manual/vhosts/vhosts-in-depth.html deleted file mode 100644 index 23d8e919a1..0000000000 --- a/docs/manual/vhosts/vhosts-in-depth.html +++ /dev/null @@ -1,396 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>An In-Depth Discussion of VirtualHost 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 VirtualHost Matching</H1> - -<P>This is a very rough document that was probably out of date the moment -it was written. It attempts to explain exactly what the code does when -deciding what virtual host to serve a hit from. It's provided on the -assumption that something is better than nothing. The server version -under discussion is Apache 1.2. - -<P>If you just want to "make it work" without understanding -how, there's a <A HREF="#whatworks">What Works</A> section at the bottom. - -<H3>Config File Parsing</H3> - -<P>There is a main_server 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>ServerName</CODE>, -<CODE>ServerPath</CODE>, or <CODE>ServerAlias</CODE>. - -<P>In the absence of any -<A - HREF="../mod/core.html#listen" -><SAMP>Listen</SAMP></A> -directives, the (final if there -are multiple) <CODE>Port</CODE> directive in the main_server indicates -which port httpd will listen on. - -<P> The <CODE>Port</CODE> and <CODE>ServerName</CODE> directives for -any server main or virtual are used when generating URLs such as during -redirects. - -<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> The magic <CODE>_default_</CODE> address has significance during -the matching algorithm. It essentially matches any unspecified address. - -<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. 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). Note that subsequent <CODE>Port</CODE> -statements for this vhost will not affect the ports assigned in the -address set. - -<P> -All vhosts are stored in a list which is in the reverse order that -they appeared in the config file. For example, if the config file is: - -<BLOCKQUOTE><PRE> - <VirtualHost A> - ... - </VirtualHost> - - <VirtualHost B> - ... - </VirtualHost> - - <VirtualHost C> - ... - </VirtualHost> -</PRE></BLOCKQUOTE> - -Then the list will be ordered: main_server, C, B, A. Keep this in mind. - -<P> -After parsing has completed, the list of servers is scanned, and various -merges and 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> Now a pass is made through the vhosts to fill in any missing -<CODE>ServerName</CODE> fields and to classify the vhost as either -an <EM>IP-based</EM> vhost or a <EM>name-based</EM> vhost. A vhost is -considered a name-based vhost if any of its address set overlaps the -main_server (the port associated with each address must match the -main_server's <CODE>Port</CODE>). Otherwise it is considered an IP-based -vhost. - -<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. Any vhost that includes the magic -<SAMP>_default_</SAMP> wildcard is given the same <CODE>ServerName</CODE> as -the main_server. Otherwise the vhost (which is necessarily an IP-based -vhost) is given a <CODE>ServerName</CODE> based on the result of a reverse -DNS lookup on the first address given in the <CODE>VirtualHost</CODE> -statement. - -<P> - -<H3>Vhost Matching</H3> - - -<P><STRONG>Apache 1.3 differs from what is documented -here, and documentation still has to be written.</STRONG> - -<P> -The server determines which vhost to use for a request as follows: - -<P> <CODE>find_virtual_server</CODE>: When the connection is first made -by the client, the local IP address (the IP address to which the client -connected) is looked up in the server list. A vhost is matched if it -is an IP-based vhost, the IP address matches and the port matches -(taking into account wildcards). - -<P> If no vhosts are matched then the last occurrence, if it appears, -of a <SAMP>_default_</SAMP> address (which if you recall the ordering of the -server list mentioned above means that this would be the first occurrence -of <SAMP>_default_</SAMP> in the config file) is matched. - -<P> In any event, if nothing above has matched, then the main_server is -matched. - -<P> The vhost resulting from the above search is stored with data -about the connection. We'll call this the <EM>connection vhost</EM>. -The connection vhost is constant over all requests in a particular TCP/IP -session -- that is, over all requests in a KeepAlive/persistent session. - -<P> For each request made on the connection the following sequence of -events further determines the actual vhost that will be used to serve -the request. - -<P> <CODE>check_fulluri</CODE>: If the requestURI is an absoluteURI, that -is it includes <CODE>http://hostname/</CODE>, then an attempt is made to -determine if the hostname's address (and optional port) match that of -the connection vhost. If it does then the hostname portion of the URI -is saved as the <EM>request_hostname</EM>. If it does not match, then the -URI remains untouched. <STRONG>Note</STRONG>: to achieve this address -comparison, -the hostname supplied goes through a DNS lookup unless it matches the -<CODE>ServerName</CODE> or the local IP address of the client's socket. - -<P> <CODE>parse_uri</CODE>: If the URI begins with a protocol -(<EM>i.e.</EM>, <CODE>http:</CODE>, <CODE>ftp:</CODE>) then the request is -considered a proxy request. Note that even though we may have stripped -an <CODE>http://hostname/</CODE> in the previous step, this could still -be a proxy request. - -<P> <CODE>read_request</CODE>: If the request does not have a hostname -from the earlier step, then any <CODE>Host:</CODE> header sent by the -client is used as the request hostname. - -<P> <CODE>check_hostalias</CODE>: If the request now has a hostname, -then an attempt is made to match for this hostname. The first step -of this match is to compare any port, if one was given in the request, -against the <CODE>Port</CODE> field of the connection vhost. If there's -a mismatch then the vhost used for the request is the connection vhost. -(This is a bug, see observations.) - -<P> -If the port matches, then httpd scans the list of vhosts starting with -the next server <STRONG>after</STRONG> the connection vhost. This scan does not -stop if there are any matches, it goes through all possible vhosts, -and in the end uses the last match it found. The comparisons performed -are as follows: - -<UL> -<LI>Compare the request hostname:port with the vhost - <CODE>ServerName</CODE> and <CODE>Port</CODE>. - -<LI>Compare the request hostname against any and all addresses given in - the <CODE>VirtualHost</CODE> directive for this vhost. - -<LI>Compare the request hostname against the <CODE>ServerAlias</CODE> - given for the vhost. -</UL> - -<P> -<CODE>check_serverpath</CODE>: If the request has no hostname -(back up a few paragraphs) then a scan similar to the one -in <CODE>check_hostalias</CODE> is performed to match any -<CODE>ServerPath</CODE> directives given in the vhosts. Note that the -<STRONG>last match</STRONG> is used regardless (again consider the ordering of -the virtual hosts). - -<H3>Observations</H3> - -<UL> - -<LI>It is difficult to define an IP-based vhost for the machine's - "main IP address". You essentially have to create a bogus - <CODE>ServerName</CODE> for the main_server that does not match the - machine's IPs. - <P> - -<LI>During the scans in both <CODE>check_hostalias</CODE> and - <CODE>check_serverpath</CODE> no check is made that the vhost being - scanned is actually a name-based vhost. This means, for example, that - it's possible to match an IP-based vhost through another address. But - because the scan starts in the vhost list at the first vhost that - matched the local IP address of the connection, not all IP-based vhosts - can be matched. - <P> - Consider the config file above with three vhosts A, B, C. Suppose - that B is a named-based vhost, and A and C are IP-based vhosts. If - a request comes in on B or C's address containing a header - "<SAMP>Host: A</SAMP>" then - it will be served from A's config. If a request comes in on A's - address then it will always be served from A's config regardless of - any Host: header. - </P> - -<LI>Unless you have a <SAMP>_default_</SAMP> vhost, - it doesn't matter if you mix name-based vhosts in amongst IP-based - vhosts. During the <CODE>find_virtual_server</CODE> phase above no - named-based vhost will be matched, so the main_server will remain the - connection vhost. Then scans will cover all vhosts in the vhost list. - <P> - If you do have a <SAMP>_default_</SAMP> vhost, then you cannot place - named-based vhosts after it in the config. This is because on any - connection to the main server IPs the connection vhost will always be - the <SAMP>_default_</SAMP> vhost since none of the name-based are - considered during <CODE>find_virtual_server</CODE>. - </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. - <A HREF="dns-caveats.html">There's more information - available on this and the next two topics</A>. - <P> - -<LI><CODE>ServerName</CODE> should always be set for each vhost. Otherwise - A DNS lookup is required for each vhost. - <P> - -<LI>A DNS lookup is always required for the main_server's - <CODE>ServerName</CODE> (or to generate that if it isn't specified - in the config). - <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 a vhost that would otherwise be a name-vhost includes a - <CODE>Port</CODE> statement that doesn't match the main_server - <CODE>Port</CODE> then it will be considered an IP-based vhost. - Then <CODE>find_virtual_server</CODE> will match it (because - the ports associated with each address in the address set default - to the port of the main_server) as the connection vhost. Then - <CODE>check_hostalias</CODE> will refuse to check any other name-based - vhost because of the port mismatch. The result is that the vhost - will steal all hits going to the main_server address. - <P> - -<LI>If two IP-based vhosts have an address in common, the vhost appearing - later in the file is always matched. Such a thing might happen - inadvertently. If the config has name-based vhosts and for some reason - the main_server <CODE>ServerName</CODE> resolves to the wrong address - then all the name-based vhosts will be parsed as ip-based vhosts. - Then the last of them will steal all the hits. - <P> - -<LI>The last name-based vhost in the config is always matched for any hit - which doesn't match one of the other name-based vhosts. - -</UL> - -<H3><A NAME="whatworks">What Works</A></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 VirtualHost definitions. -(This is to aid the readability of the configuration -- the post-config -merging process makes it non-obvious that definitions mixed in around -virtualhosts might affect all virtualhosts.) -<P> - -<LI>Arrange your VirtualHosts such -that all name-based virtual hosts come first, followed by IP-based -virtual hosts, followed by any <SAMP>_default_</SAMP> virtual host -<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 /abcdef"). -<P> - -<LI>Do not use <EM>port-based</EM> vhosts in the same server as -name-based vhosts. A loose definition for port-based is a vhost which -is determined by the port on the server (<EM>i.e.</EM>, one server with -ports 8000, 8080, and 80 - all of which have different configurations). -<P> - -</UL> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/virtual-host.html b/docs/manual/vhosts/virtual-host.html deleted file mode 100644 index aa81fad91e..0000000000 --- a/docs/manual/vhosts/virtual-host.html +++ /dev/null @@ -1,208 +0,0 @@ -<!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">Virtual Host Support</H1> - -<STRONG>See Also:</STRONG> -<A HREF="host.html">Non-IP based virtual hosts</A> - -<H2>What are virtual hosts?</H2> -This is the ability of a single machine to be a web server for multiple -domains. For example, an Internet service provider might have a machine -called <CODE>www.serve.com</CODE> which provides Web space for several -organizations including, say, <EM>smallco</EM> and <EM>baygroup</EM>. -Ordinarily, these groups would be given parts of the Web tree on www.serve.com. -So smallco's home page would have the URL -<BLOCKQUOTE> -http://www.serve.com/smallco/ -</BLOCKQUOTE> -and baygroup's home page would have the URL -<BLOCKQUOTE> -http://www.serve.com/baygroup/ -</BLOCKQUOTE> -<P> -For esthetic reasons, however, both organizations would rather their home -pages appeared under their own names rather than that of the service -provider's; but they do not want to set up their own Internet links and -servers. -<P> -Virtual hosts are the solution to this problem. smallco and baygroup would -have their own Internet name registrations, <CODE>www.smallco.com</CODE> and -<CODE>www.baygroup.org</CODE> respectively. These hostnames would both -correspond to the service provider's machine (www.serve.com). Thus -smallco's home page would now have the URL -<BLOCKQUOTE> -http://www.smallco.com/ -</BLOCKQUOTE> -and baygroup's home page would would have the URL -<BLOCKQUOTE> -http://www.baygroup.org/ -</BLOCKQUOTE> - -<H2>System requirements</H2> -Due to limitations in the HTTP/1.0 protocol, the web server <STRONG>must have a -different IP address for each virtual host</STRONG>. This can be achieved -by the machine having several physical network connections, or by use -of a <A HREF="../misc/vif-info.html">virtual interface</A> on some operating -systems. - -<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#bindaddress">BindAddress</A> directive in the -configuration -file to select which IP address (or virtual host) that daemon services. -<EM>E.g.</EM>, -<BLOCKQUOTE><CODE>BindAddress www.smallco.com</CODE></BLOCKQUOTE> -This hostname can also be given as an IP address. - -<H2>Setting up a single daemon</H2> -For this case, a single httpd will service requests for 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> configuration -directives to different values for each virtual host. -<EM>E.g.</EM>, -<BLOCKQUOTE><CODE> -<VirtualHost www.smallco.com><BR> -ServerAdmin webmaster@mail.smallco.com<BR> -DocumentRoot /groups/smallco/www<BR> -ServerName www.smallco.com<BR> -ErrorLog /groups/smallco/logs/error_log<BR> -TransferLog /groups/smallco/logs/access_log<BR> -</VirtualHost><BR> -<BR> -<VirtualHost www.baygroup.org><BR> -ServerAdmin webmaster@mail.baygroup.org<BR> -DocumentRoot /groups/baygroup/www<BR> -ServerName www.baygroup.org<BR> -ErrorLog /groups/baygroup/logs/error_log<BR> -TransferLog /groups/baygroup/logs/access_log<BR> -</VirtualHost><BR> -</CODE></BLOCKQUOTE> - -This VirtualHost hostnames can also be given as IP addresses. - -<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#user">User</A>, -<A HREF="../mod/core.html#group">Group</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#pidfile">PidFile</A>, -<A HREF="../mod/mod_mime.html#typesconfig">TypesConfig</A>, and -<A HREF="../mod/core.html#serverroot">ServerRoot</A>. - -<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> - -<H2>File Handle/Resource Limits:</H2> -When using a large number of Virtual Hosts, Apache may run out of available -file descriptors 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> - -The have been reports that Apache may start running out of resources allocated -for the root process. This will exhibit itself as errors in the error log like -"unable to fork". There are two ways you can bump this up: - -<OL> -<LI>Have a <CODE>csh</CODE> script wrapper around httpd which sets the -"rlimit" to some large number, like 512. -<LI>Edit http_main.c to add calls to setrlimit() from main(), along the lines -of -<PRE> - struct rlimit rlp; - - rlp.rlim_cur = rlp.rlim_max = 512; - if (setrlimit(RLIMIT_NPROC, &rlp)) { - fprintf(stderr, "setrlimit(RLIMIT_NPROC) failed.\n"); - exit(1); - } -</PRE> -(thanks to "Aaron Gifford <agifford@InfoWest.COM>" for the patch) -</OL> - -The latter will probably manifest itself in a later version of Apache. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/emacs-style b/emacs-style deleted file mode 100644 index 283b6f0255..0000000000 --- a/emacs-style +++ /dev/null @@ -1,10 +0,0 @@ -(add-hook 'c-mode-hook - (function (lambda () - (c-set-offset 'inclass' ++) - (c-set-offset 'defun-block-intro' ++) - (c-set-offset 'statement-block-intro' ++) - (c-set-offset 'substatement' ++) - (c-set-offset 'brace-list-intro' ++) - (c-set-offset 'statement-case-intro' ++) - ))) -(setq c++-mode-hook c-mode-hook) diff --git a/os/beos/beosd.c b/os/beos/beosd.c deleted file mode 100644 index be05feb208..0000000000 --- a/os/beos/beosd.c +++ /dev/null @@ -1,219 +0,0 @@ -/* ==================================================================== - * Copyright (c) 1998-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/>. - * - */ - -#include "httpd.h" -#include "http_config.h" -#include "http_main.h" -#include "http_log.h" -#include "unixd.h" - -unixd_config_rec unixd_config; - -void unixd_detach(void) -{ - int x; - pid_t pgrp; - - chdir("/"); - - if ((x = fork()) > 0) - exit(0); - else if (x == -1) { - perror("fork"); - fprintf(stderr, "%s: unable to fork new process\n", ap_server_argv0); - exit(1); - } - RAISE_SIGSTOP(DETACH); - - if ((pgrp = setsid()) == -1) { - perror("setsid"); - fprintf(stderr, "%s: setsid failed\n", ap_server_argv0); - exit(1); - } - - /* close out the standard file descriptors */ - if (freopen("/dev/null", "r", stdin) == NULL) { - fprintf(stderr, "%s: unable to replace stdin with /dev/null: %s\n", - ap_server_argv0, strerror(errno)); - /* continue anyhow -- note we can't close out descriptor 0 because we - * have nothing to replace it with, and if we didn't have a descriptor - * 0 the next file would be created with that value ... leading to - * havoc. - */ - } - if (freopen("/dev/null", "w", stdout) == NULL) { - fprintf(stderr, "%s: unable to replace stdout with /dev/null: %s\n", - ap_server_argv0, strerror(errno)); - } - /* stderr is a tricky one, we really want it to be the error_log, - * but we haven't opened that yet. So leave it alone for now and it'll - * be reopened moments later. - */ -} - -/* Set group privileges. - * - * Note that we use the username as set in the config files, rather than - * the lookup of to uid --- the same uid may have multiple passwd entries, - * with different sets of groups for each. - */ - -static int set_group_privs(void) -{ - if (!geteuid()) { - char *name; - - /* Get username if passed as a uid */ - - if (unixd_config.user_name[0] == '#') { - struct passwd *ent; - uid_t uid = atoi(&unixd_config.user_name[1]); - - if ((ent = getpwuid(uid)) == NULL) { - ap_log_error(APLOG_MARK, APLOG_ALERT, NULL, - "getpwuid: couldn't determine user name from uid %u, " - "you probably need to modify the User directive", - (unsigned)uid); - return -1; - } - - name = ent->pw_name; - } - else - name = unixd_config.user_name; - - if (setgid(unixd_config.group_id) == -1) { - ap_log_error(APLOG_MARK, APLOG_ALERT, NULL, - "setgid: unable to set group id to Group %u", - (unsigned)unixd_config.group_id); - return -1; - } - - /* Reset `groups' attributes. */ - - if (initgroups(name, unixd_config.group_id) == -1) { - ap_log_error(APLOG_MARK, APLOG_ALERT, NULL, - "initgroups: unable to set groups for User %s " - "and Group %u", name, (unsigned)unixd_config.group_id); - return -1; - } - } - return 0; -} - - -int unixd_setup_child(void) -{ - if (set_group_privs()) { - return -1; - } - - /* Only try to switch if we're running as root */ - if (!geteuid() && ( - setuid(unixd_config.user_id) == -1)) { - ap_log_error(APLOG_MARK, APLOG_ALERT, NULL, - "setuid: unable to change uid"); - return -1; - } - return 0; -} - - -const char *unixd_set_user(cmd_parms *cmd, void *dummy, char *arg) -{ - const char *err = ap_check_cmd_context(cmd, GLOBAL_ONLY); - if (err != NULL) { - return err; - } - - unixd_config.user_name = arg; - unixd_config.user_id = ap_uname2id(arg); -#if !defined (BIG_SECURITY_HOLE) && !defined (OS2) - if (unixd_config.user_id == 0) { - return "Error:\tApache has not been designed to serve pages while\n" - "\trunning as root. There are known race conditions that\n" - "\twill allow any local user to read any file on the system.\n" - "\tIf you still desire to serve pages as root then\n" - "\tadd -DBIG_SECURITY_HOLE to the EXTRA_CFLAGS line in your\n" - "\tsrc/Configuration file and rebuild the server. It is\n" - "\tstrongly suggested that you instead modify the User\n" - "\tdirective in your httpd.conf file to list a non-root\n" - "\tuser.\n"; - } -#endif - - return NULL; -} - -const char *unixd_set_group(cmd_parms *cmd, void *dummy, char *arg) -{ - const char *err = ap_check_cmd_context(cmd, GLOBAL_ONLY); - if (err != NULL) { - return err; - } - - unixd_config.group_id = ap_gname2id(arg); - - return NULL; -} - -void unixd_pre_config(void) -{ - unixd_config.user_name = DEFAULT_USER; - unixd_config.user_id = ap_uname2id(DEFAULT_USER); - unixd_config.group_id = ap_gname2id(DEFAULT_GROUP); -} diff --git a/os/beos/beosd.h b/os/beos/beosd.h deleted file mode 100644 index 37cb2f95b6..0000000000 --- a/os/beos/beosd.h +++ /dev/null @@ -1,82 +0,0 @@ -/* ==================================================================== - * Copyright (c) 1998-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 UNIXD_H -#define UNIXD_H - -/* common stuff that unix MPMs will want */ - -typedef struct { - char *user_name; - uid_t user_id; - gid_t group_id; -} unixd_config_rec; -extern unixd_config_rec unixd_config; - -void unixd_detach(void); -int unixd_setup_child(void); -void unixd_pre_config(void); -const char *unixd_set_user(cmd_parms *cmd, void *dummy, char *arg); -const char *unixd_set_group(cmd_parms *cmd, void *dummy, char *arg); - -#define UNIX_DAEMON_COMMANDS \ -{ "User", unixd_set_user, NULL, RSRC_CONF, TAKE1, \ - "Effective user id for this server"}, \ -{ "Group", unixd_set_group, NULL, RSRC_CONF, TAKE1, \ - "Effective group id for this server"}, \ - -#endif diff --git a/os/beos/os.c b/os/beos/os.c deleted file mode 100644 index 72281c296e..0000000000 --- a/os/beos/os.c +++ /dev/null @@ -1,75 +0,0 @@ -/* - * This file will include OS specific functions which are not inlineable. - * Any inlineable functions should be defined in os-inline.c instead. - */ - -#include "ap_config.h" -#include "os.h" - -int ap_os_is_path_absolute(const char *file) -{ - return file[0] == '/'; -} - -int ap_spawnvp(const char *file, char *const argv[]) -{ - int pid; - - if ((pid = fork()) == -1) { - return pid; - } else if (pid == 0) { - if (execvp(file, argv) == -1) - return -1; - else - return -1; /* If we get, we have a real error, but this keeps - us from getting a warning during compile time. */ - } else - return pid; -} - - -/* some linkers complain unless there's at least one function in each - * .o file... and extra prototype is for gcc -Wmissing-prototypes - */ -extern void ap_is_not_here(void); -void ap_is_not_here(void) {} - -/* - * Abstraction layer for loading - * Apache modules under run-time via - * dynamic shared object (DSO) mechanism - */ - -void ap_os_dso_init(void) -{ - /* Nothing required to be done! */ -} - -void* ap_os_dso_load(const char *path) -{ - return (void*) load_add_on(path); -} - -void ap_os_dso_unload(void* handle) -{ - unload_add_on((image_id)handle); -} - -void *ap_os_dso_sym(void *handle, const char *symname) -{ - void * retval = 0; -#if defined(DLSYM_NEEDS_UNDERSCORE) - char *symbol = (char*)malloc(sizeof(char)*(strlen(symname)+2)); - sprintf(symbol, "_%s", symname); - get_image_symbol((image_id)handle, symbol, B_SYMBOL_TYPE_ANY, (void **)&retval); - free(symbol); - return retval; -#endif - get_image_symbol((image_id)handle, symname, B_SYMBOL_TYPE_ANY, (void **)&retval); - return retval; -} - -const char *ap_os_dso_error(void) -{ - return NULL; -} diff --git a/os/beos/os.h b/os/beos/os.h deleted file mode 100644 index a4af416269..0000000000 --- a/os/beos/os.h +++ /dev/null @@ -1,100 +0,0 @@ -/* ==================================================================== - * Copyright (c) 1998-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_OS_H -#define APACHE_OS_H - -#include "ap_config.h" -#include <kernel/image.h> - -#ifndef PLATFORM -#define PLATFORM "BeOS" -#endif - -/* - * This file in included in all Apache source code. It contains definitions - * of facilities available on _this_ operating system (HAVE_* macros), - * and prototypes of OS specific functions defined in os.c or os-inline.c - */ - -extern int ap_os_is_path_absolute(const char *file); -extern int ap_spawnvp(const char *file, char *const argv[]); -#define ap_os_is_filename_valid(f) (1) -#define ap_os_kill(pid, sig) kill(pid, sig) - -/* - * Abstraction layer for loading - * Apache modules under run-time via - * dynamic shared object (DSO) mechanism - */ - -void *dlopen(const char *, int); -int dlclose(void *); -void *dlsym(void *, const char *); -const char *dlerror(void); - -#define RTLD_NOW 1 -#define RTLD_GLOBAL 0 - -#define ap_os_dso_handle_t image_id * -void ap_os_dso_init(void); -void * ap_os_dso_load(const char *); -void ap_os_dso_unload(void *); -void * ap_os_dso_sym(void *, const char *); -const char *ap_os_dso_error(void); - -#endif /* !APACHE_OS_H */ diff --git a/server/mpm/winnt/mpm_winnt.c b/server/mpm/winnt/mpm_winnt.c deleted file mode 100644 index 8c9c25897c..0000000000 --- a/server/mpm/winnt/mpm_winnt.c +++ /dev/null @@ -1,1601 +0,0 @@ -/* ==================================================================== - * 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_main.h" -#include "http_log.h" -#include "http_config.h" /* for read_config */ -#include "http_core.h" /* for get_remote_host */ -#include "http_connection.h" -#include "ap_mpm.h" -#include "ap_config.h" -#include "ap_listen.h" -#include "multithread.h" -#include "../os/win32/getopt.h" -#include "mpm_default.h" -#include "../os/win32/iol_socket.h" - -/* - * Definitions of WINNT MPM specific config globals - */ -int ap_max_requests_per_child=0; -int ap_daemons_to_start=0; -static char *mpm_pid_fname=NULL; -static int ap_threads_per_child = 0; -static int workers_may_exit = 0; -static int max_requests_per_child = 0; -static int requests_this_child; - -static struct pollfd *listenfds; -static int num_listenfds = 0; -int listenmaxfd = -1; - -static pool *pconf; /* Pool for config stuff */ - -static char ap_coredump_dir[MAX_STRING_LEN]; - - -static server_rec *server_conf; - -static int one_process = 0; -event *exit_event; -mutex *start_mutex; -int my_pid; -int parent_pid; - - -/* - * Signalling Apache on NT. - * - * Under Unix, Apache can be told to shutdown or restart by sending various - * signals (HUP, USR, TERM). On NT we don't have easy access to signals, so - * we use "events" instead. The parent apache process goes into a loop - * where it waits forever for a set of events. Two of those events are - * called - * - * apPID_shutdown - * apPID_restart - * - * (where PID is the PID of the apache parent process). When one of these - * is signalled, the Apache parent performs the appropriate action. The events - * can become signalled through internal Apache methods (e.g. if the child - * finds a fatal error and needs to kill its parent), via the service - * control manager (the control thread will signal the shutdown event when - * requested to stop the Apache service), from the -k Apache command line, - * or from any external program which finds the Apache PID from the - * httpd.pid file. - * - * The signal_parent() function, below, is used to signal one of these events. - * It can be called by any child or parent process, since it does not - * rely on global variables. - * - * On entry, type gives the event to signal. 0 means shutdown, 1 means - * graceful restart. - */ - -static void signal_parent(int type) -{ - HANDLE e; - char *signal_name; - extern char signal_shutdown_name[]; - extern char signal_restart_name[]; - - /* after updating the shutdown_pending or restart flags, we need - * to wake up the parent process so it can see the changes. The - * parent will normally be waiting for either a child process - * to die, or for a signal on the "spache-signal" event. So set the - * "apache-signal" event here. - */ - if (one_process) { - return; - } - - switch(type) { - case 0: signal_name = signal_shutdown_name; break; - case 1: signal_name = signal_restart_name; break; - default: return; - } - - e = OpenEvent(EVENT_ALL_ACCESS, FALSE, signal_name); - if (!e) { - /* Um, problem, can't signal the parent, which means we can't - * signal ourselves to die. Ignore for now... - */ - ap_log_error(APLOG_MARK, APLOG_EMERG|APLOG_WIN32ERROR, server_conf, - "OpenEvent on %s event", signal_name); - return; - } - if (SetEvent(e) == 0) { - /* Same problem as above */ - ap_log_error(APLOG_MARK, APLOG_EMERG|APLOG_WIN32ERROR, server_conf, - "SetEvent on %s event", signal_name); - CloseHandle(e); - return; - } - CloseHandle(e); -} -void ap_start_shutdown(void) -{ - signal_parent(0); -} -void ap_start_restart(int graceful) -{ - signal_parent(1); -} - -static int volatile is_graceful = 0; -API_EXPORT(int) ap_graceful_stop_signalled(void) -{ - return is_graceful; -} - -/* - * Routines that deal with sockets, some are WIN32 specific... - */ -static int s_iInitCount = 0; -static int AMCSocketInitialize(void) -{ - int iVersionRequested; - WSADATA wsaData; - int err; - - if (s_iInitCount > 0) { - s_iInitCount++; - return (0); - } - else if (s_iInitCount < 0) - return (s_iInitCount); - - /* s_iInitCount == 0. Do the initailization */ - iVersionRequested = MAKEWORD(1, 1); - err = WSAStartup((WORD) iVersionRequested, &wsaData); - if (err) { - s_iInitCount = -1; - return (s_iInitCount); - } - if (LOBYTE(wsaData.wVersion) != 1 || - HIBYTE(wsaData.wVersion) != 1) { - s_iInitCount = -2; - WSACleanup(); - return (s_iInitCount); - } - - s_iInitCount++; - return (s_iInitCount); - -} -static void AMCSocketCleanup(void) -{ - if (--s_iInitCount == 0) - WSACleanup(); - return; -} - -static void sock_disable_nagle(int s) /* ZZZ abstract */ -{ - /* The Nagle algorithm says that we should delay sending partial - * packets in hopes of getting more data. We don't want to do - * this; we are not telnet. There are bad interactions between - * persistent connections and Nagle's algorithm that have very severe - * performance penalties. (Failing to disable Nagle is not much of a - * problem with simple HTTP.) - * - * In spite of these problems, failure here is not a shooting offense. - */ - int just_say_no = 1; - - if (setsockopt(s, IPPROTO_TCP, TCP_NODELAY, (char *) &just_say_no, - sizeof(int)) < 0) { - ap_log_error(APLOG_MARK, APLOG_WARNING, server_conf, - "setsockopt: (TCP_NODELAY)"); - } -} - -/* - * Routines to deal with managing the list of listening sockets... - * find_ready_listener() - * Finds a listener which is ready for accept(). This advances - * the head_listener global. - * setup_listeners() - * setup_inherited_listeners() - */ -static ap_listen_rec *head_listener; -static ap_inline ap_listen_rec *find_ready_listener(fd_set * main_fds) -{ - ap_listen_rec *lr; - - for (lr = head_listener; lr ; lr = lr->next) { - if (FD_ISSET(lr->fd, main_fds)) { - head_listener = lr->next; - if (head_listener == NULL) - head_listener = ap_listeners; - - return (lr); - } - } - return NULL; -} -static int setup_listeners(pool *pconf, server_rec *s) -{ - ap_listen_rec *lr; - int num_listeners = 0; - - /* Setup the listeners */ - listenmaxfd = -1; - FD_ZERO(&listenfds); - - if (ap_listen_open(pconf, s->port)) { - return 0; - } - for (lr = ap_listeners; lr; lr = lr->next) { - num_listeners++; - if (lr->fd >= 0) { - FD_SET(lr->fd, &listenfds); - if (lr->fd > listenmaxfd) - listenmaxfd = lr->fd; - } - } - - head_listener = ap_listeners; - - return num_listeners; -} - -static int setup_inherited_listeners(pool *p, server_rec *s) -{ - WSAPROTOCOL_INFO WSAProtocolInfo; - HANDLE pipe; - ap_listen_rec *lr; - DWORD BytesRead; - int num_listeners = 0; - int fd; - - /* Setup the listeners */ - listenmaxfd = -1; - FD_ZERO(&listenfds); - - /* Set up a default listener if necessary */ - if (ap_listeners == NULL) { - struct sockaddr_in local_addr; - ap_listen_rec *new; - local_addr.sin_family = AF_INET; - local_addr.sin_addr.s_addr = htonl(INADDR_ANY); - local_addr.sin_port = htons(s->port ? s->port : DEFAULT_HTTP_PORT); - new = malloc(sizeof(ap_listen_rec)); - new->local_addr = local_addr; - new->fd = -1; - new->next = ap_listeners; - ap_listeners = new; - } - - /* Open the pipe to the parent process to receive the inherited socket - * data. The sockets have been set to listening in the parent process. - */ - pipe = GetStdHandle(STD_INPUT_HANDLE); - for (lr = ap_listeners; lr; lr = lr->next) { - if (!ReadFile(pipe, &WSAProtocolInfo, sizeof(WSAPROTOCOL_INFO), - &BytesRead, (LPOVERLAPPED) NULL)) { - ap_log_error(APLOG_MARK, APLOG_WIN32ERROR|APLOG_CRIT, server_conf, - "setup_inherited_listeners: Unable to read socket data from parent"); - signal_parent(0); /* tell parent to die */ - exit(1); - } - ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_INFO, server_conf, - "BytesRead = %d WSAProtocolInfo = %x20", BytesRead, WSAProtocolInfo); - fd = WSASocket(FROM_PROTOCOL_INFO, FROM_PROTOCOL_INFO, FROM_PROTOCOL_INFO, - &WSAProtocolInfo, 0, 0); - if (fd == INVALID_SOCKET) { - ap_log_error(APLOG_MARK, APLOG_WIN32ERROR|APLOG_CRIT, server_conf, - "setup_inherited_listeners: WSASocket failed to open the inherited socket."); - signal_parent(0); /* tell parent to die */ - exit(1); - } - if (fd >= 0) { - FD_SET(fd, &listenfds); - if (fd > listenmaxfd) - listenmaxfd = fd; - } - ap_note_cleanups_for_socket(p, fd); - - lr->fd = fd; - } - CloseHandle(pipe); - - - for (lr = ap_listeners; lr; lr = lr->next) { - num_listeners++; - } - - head_listener = ap_listeners; - - return num_listeners; -} - - -/********************************************************************** - * Multithreaded implementation - * - * This code is fairly specific to Win32. - * - * The model used to handle requests is a set of threads. One "main" - * thread listens for new requests. When something becomes - * available, it does a select and places the newly available socket - * onto a list of "jobs" (add_job()). Then any one of a fixed number - * of "worker" threads takes the top job off the job list with - * remove_job() and handles that connection to completion. After - * the connection has finished the thread is free to take another - * job from the job list. - * - * In the code, the "main" thread is running within the worker_main() - * function. The first thing this function does is create the - * worker threads, which operate in the child_sub_main() function. The - * main thread then goes into a loop within worker_main() where they - * do a select() on the listening sockets. The select times out once - * per second so that the thread can check for an "exit" signal - * from the parent process (see below). If this signal is set, the - * thread can exit, but only after it has accepted all incoming - * connections already in the listen queue (since Win32 appears - * to through away listened but unaccepted connections when a - * process dies). - * - * Because the main and worker threads exist within a single process - * they are vulnerable to crashes or memory leaks (crashes can also - * be caused within modules, of course). There also needs to be a - * mechanism to perform restarts and shutdowns. This is done by - * creating the main & worker threads within a subprocess. A - * main process (the "parent process") creates one (or more) - * processes to do the work, then the parent sits around waiting - * for the working process to die, in which case it starts a new - * one. The parent process also handles restarts (by creating - * a new working process then signalling the previous working process - * exit ) and shutdowns (by signalling the working process to exit). - * The parent process operates within the master_main() function. This - * process also handles requests from the service manager (NT only). - * - * Signalling between the parent and working process uses a Win32 - * event. Each child has a unique name for the event, which is - * passed to it with the -Z argument when the child is spawned. The - * parent sets (signals) this event to tell the child to die. - * At present all children do a graceful die - they finish all - * current jobs _and_ empty the listen queue before they exit. - * A non-graceful die would need a second event. The -Z argument in - * the child is also used to create the shutdown and restart events, - * since the prefix (apPID) contains the parent process PID. - * - * The code below starts with functions at the lowest level - - * worker threads, and works up to the top level - the main() - * function of the parent process. - * - * The scoreboard (in process memory) contains details of the worker - * threads (within the active working process). There is no shared - * "scoreboard" between processes, since only one is ever active - * at once (or at most, two, when one has been told to shutdown but - * is processes outstanding requests, and a new one has been started). - * This is controlled by a "start_mutex" which ensures only one working - * process is active at once. - **********************************************************************/ - -/* The code protected by #ifdef UNGRACEFUL_RESTARTS/#endif sections - * could implement a sort-of ungraceful restart for Win32. instead of - * graceful restarts. - * - * However it does not work too well because it does not intercept a - * connection already in progress (in child_sub_main()). We'd have to - * get that to poll on the exit event. - */ - -int service_init() -{ -/* - common_init(); - - ap_cpystrn(ap_server_root, HTTPD_ROOT, sizeof(ap_server_root)); - if (ap_registry_get_service_conf(pconf, ap_server_confname, sizeof(ap_server_confname), - ap_server_argv0)) - return FALSE; - - ap_setup_prelinked_modules(); - server_conf = ap_read_config(pconf, ptrans, ap_server_confname); - ap_log_pid(pconf, ap_pid_fname); - post_parse_init(); -*/ - return TRUE; -} - -/* - * Definition of jobs, shared by main and worker threads. - */ - -typedef struct joblist_s { - struct joblist_s *next; - int sock; -} joblist; - -/* - * Globals common to main and worker threads. This structure is not - * used by the parent process. - */ - -typedef struct globals_s { -#ifdef UNGRACEFUL_RESTART - HANDLE thread_exit_event; -#else - int exit_now; -#endif - semaphore *jobsemaphore; - joblist *jobhead; - joblist *jobtail; - mutex *jobmutex; - int jobcount; -} globals; - -globals allowed_globals = -{0, NULL, NULL, NULL, NULL, 0}; - -/* - * add_job()/remove_job() - add or remove an accepted socket from the - * list of sockets connected to clients. allowed_globals.jobmutex protects - * against multiple concurrent access to the linked list of jobs. - */ - -void add_job(int sock) -{ - joblist *new_job; - - ap_assert(allowed_globals.jobmutex); - /* TODO: If too many jobs in queue, sleep, check for problems */ - ap_acquire_mutex(allowed_globals.jobmutex); - new_job = (joblist *) malloc(sizeof(joblist)); - if (new_job == NULL) { - fprintf(stderr, "Ouch! Out of memory in add_job()!\n"); - } - new_job->next = NULL; - new_job->sock = sock; - if (allowed_globals.jobtail != NULL) - allowed_globals.jobtail->next = new_job; - allowed_globals.jobtail = new_job; - if (!allowed_globals.jobhead) - allowed_globals.jobhead = new_job; - allowed_globals.jobcount++; - release_semaphore(allowed_globals.jobsemaphore); - ap_release_mutex(allowed_globals.jobmutex); -} - -int remove_job(void) -{ - joblist *job; - int sock; - -#ifdef UNGRACEFUL_RESTART - HANDLE hObjects[2]; - int rv; - - hObjects[0] = allowed_globals.jobsemaphore; - hObjects[1] = allowed_globals.thread_exit_event; - - rv = WaitForMultipleObjects(2, hObjects, FALSE, INFINITE); - ap_assert(rv != WAIT_FAILED); - if (rv == WAIT_OBJECT_0 + 1) { - return -1; - } - /* must be semaphore */ -#else - acquire_semaphore(allowed_globals.jobsemaphore); -#endif - ap_assert(allowed_globals.jobmutex); - -#ifdef UNGRACEFUL_RESTART - if (!allowed_globals.jobhead) { -#else - ap_acquire_mutex(allowed_globals.jobmutex); - if (allowed_globals.exit_now && !allowed_globals.jobhead) { -#endif - ap_release_mutex(allowed_globals.jobmutex); - return (-1); - } - job = allowed_globals.jobhead; - ap_assert(job); - allowed_globals.jobhead = job->next; - if (allowed_globals.jobhead == NULL) - allowed_globals.jobtail = NULL; - ap_release_mutex(allowed_globals.jobmutex); - sock = job->sock; - free(job); - return (sock); -} - -/* - * child_main() - this is the main loop for the worker threads - * - * Each thread runs within this function. They wait within remove_job() - * for a job to become available, then handle all the requests on that - * connection until it is closed, then return to remove_job(). - * - * The worker thread will exit when it removes a job which contains - * socket number -1. This provides a graceful thread exit, since - * it will never exit during a connection. - * - * This code in this function is basically equivalent to the child_main() - * from the multi-process (Unix) environment, except that we - * - * - do not call child_init_modules (child init API phase) - * - block in remove_job, and when unblocked we have an already - * accepted socket, instead of blocking on a mutex or select(). - */ - -static void child_main(int child_num) -{ - struct sockaddr sa_server; - struct sockaddr sa_client; - int len; - BUFF *conn_io; - conn_rec *current_conn; - ap_iol *iol; - - pool *ptrans; - int requests_this_child = 0; - int csd = -1; - - ptrans = ap_make_sub_pool(pconf); - -#if 0 - (void) ap_update_child_status(child_num, SERVER_READY, (request_rec *) NULL); -#endif - - while (1) { - current_conn = NULL; - ap_clear_pool(ptrans); -#if 0 - (void) ap_update_child_status(child_num, SERVER_READY, - (request_rec *) NULL); -#endif - - /* Get job from the job list. This will block until a job is ready. - * If -1 is returned then the main thread wants us to exit. - */ - csd = remove_job(); - if (csd == -1) - break; /* time to exit */ - requests_this_child++; - - ap_note_cleanups_for_socket(ptrans, csd); - - /* - * We now have a connection, so set it up with the appropriate - * socket options, file descriptors, and read/write buffers. - */ - len = sizeof(struct sockaddr); - if (getsockname(csd, &sa_server, &len)== SOCKET_ERROR) { - ap_log_error(APLOG_MARK, APLOG_WARNING, server_conf, - "getsockname failed with error %d\n", WSAGetLastError()); - continue; - } - - len = sizeof(struct sockaddr); - if ((getpeername(csd, &sa_client, &len)) == SOCKET_ERROR) { - ap_log_error(APLOG_MARK, APLOG_WARNING, server_conf, - "getpeername failed with error %d\n", WSAGetLastError()); - memset(&sa_client, '\0', sizeof(sa_client)); - } -#if 0 - (void) ap_update_child_status(child_num, SERVER_BUSY_READ, - (request_rec *) NULL); -#endif - sock_disable_nagle(csd); - - iol = win32_attach_socket(csd); - if (iol == NULL) { - ap_log_error(APLOG_MARK, APLOG_ERR, server_conf, - "error attaching to socket"); - close(csd); - continue; - } - - conn_io = ap_bcreate(ptrans, B_RDWR); - ap_bpush_iol(conn_io, iol); - - current_conn = ap_new_connection(ptrans, server_conf, conn_io, - (struct sockaddr_in *) &sa_client, - (struct sockaddr_in *) &sa_server, - child_num); - - ap_process_connection(current_conn); - } -} - -static void cleanup_thread(thread **handles, int *thread_cnt, int thread_to_clean) -{ - int i; - - free_thread(handles[thread_to_clean]); - for (i = thread_to_clean; i < ((*thread_cnt) - 1); i++) - handles[i] = handles[i + 1]; - (*thread_cnt)--; -} - -/* - * The Win32 call WaitForMultipleObjects will only allow you to wait for - * a maximum of MAXIMUM_WAIT_OBJECTS (current 64). Since the threading - * model in the multithreaded version of apache wants to use this call, - * we are restricted to a maximum of 64 threads. This is a simplistic - * routine that will increase this size. - */ -static DWORD wait_for_many_objects(DWORD nCount, CONST HANDLE *lpHandles, - DWORD dwSeconds) -{ - time_t tStopTime; - DWORD dwRet = WAIT_TIMEOUT; - DWORD dwIndex=0; - BOOL bFirst = TRUE; - - tStopTime = time(NULL) + dwSeconds; - - do { - if (!bFirst) - Sleep(1000); - else - bFirst = FALSE; - - for (dwIndex = 0; dwIndex * MAXIMUM_WAIT_OBJECTS < nCount; dwIndex++) { - dwRet = WaitForMultipleObjects( - min(MAXIMUM_WAIT_OBJECTS, - nCount - (dwIndex * MAXIMUM_WAIT_OBJECTS)), - lpHandles + (dwIndex * MAXIMUM_WAIT_OBJECTS), - 0, 0); - - if (dwRet != WAIT_TIMEOUT) { - break; - } - } - } while((time(NULL) < tStopTime) && (dwRet == WAIT_TIMEOUT)); - - return dwRet; -} - -//extern void main_control_server(void *); /* in hellop.c */ - -#define MAX_SELECT_ERRORS 100 - -/* - * Initialise the signal names, in the global variables signal_name_prefix, - * signal_restart_name and signal_shutdown_name. - */ - -#define MAX_SIGNAL_NAME 30 /* Long enough for apPID_shutdown, where PID is an int */ -char signal_name_prefix[MAX_SIGNAL_NAME]; -char signal_restart_name[MAX_SIGNAL_NAME]; -char signal_shutdown_name[MAX_SIGNAL_NAME]; -static void setup_signal_names(char *prefix) -{ - ap_snprintf(signal_name_prefix, sizeof(signal_name_prefix), prefix); - ap_snprintf(signal_shutdown_name, sizeof(signal_shutdown_name), - "%s_shutdown", signal_name_prefix); - ap_snprintf(signal_restart_name, sizeof(signal_restart_name), - "%s_restart", signal_name_prefix); -} - - -/* - * worker_main() is main loop for the child process. The loop in - * this function becomes the controlling thread for the actually working - * threads (which run in a loop in child_sub_main()). - * Globals Used: - * exit_event, start_mutex, ap_threads_per_child, server_conf, - * h_errno defined to WSAGetLastError in winsock2.h, - */ -static void worker_main(void) -{ - int nthreads = ap_threads_per_child; - fd_set main_fds; - int srv; - int clen; - int csd; - int sd = -1; - struct sockaddr_in sa_client; - int total_jobs = 0; - thread **child_handles; - int rv; - time_t end_time; - int i; - struct timeval tv; - int wait_time = 1; - HANDLE hObjects[2]; - int count_select_errors = 0; - pool *pchild; - - pchild = ap_make_sub_pool(pconf); - -// ap_restart_time = time(NULL); - -#if 0 - reinit_scoreboard(pconf); -#endif - - /* - * Wait until we have permission to start accepting connections. - * start_mutex is used to ensure that only one child ever - * goes into the listen/accept loop at once. Also wait on exit_event, - * in case we (this child) is told to die before we get a chance to - * serve any requests. - */ - hObjects[0] = (HANDLE)start_mutex; - hObjects[1] = (HANDLE)exit_event; - rv = WaitForMultipleObjects(2, hObjects, FALSE, INFINITE); - if (rv == WAIT_FAILED) { - ap_log_error(APLOG_MARK,APLOG_ERR|APLOG_WIN32ERROR, server_conf, - "Waiting for start_mutex or exit_event -- process will exit"); - - ap_destroy_pool(pchild); -#if 0 - cleanup_scoreboard(); -#endif - exit(0); - } - if (rv == WAIT_OBJECT_0 + 1) { - /* exit event signalled - exit now */ - ap_destroy_pool(pchild); -#if 0 - cleanup_scoreboard(); -#endif - exit(0); - } - /* start_mutex obtained, continue into the select() loop */ - if (one_process) { - setup_listeners(pconf, server_conf); - } else { - /* Get listeners from the parent process */ - setup_inherited_listeners(pconf, server_conf); - } - - if (listenmaxfd == -1) { - /* Help, no sockets were made, better log something and exit */ - ap_log_error(APLOG_MARK, APLOG_CRIT|APLOG_NOERRNO, NULL, - "No sockets were created for listening"); - - signal_parent(0); /* tell parent to die */ - - ap_destroy_pool(pchild); -#if 0 - cleanup_scoreboard(); -#endif - exit(0); - } - - allowed_globals.jobsemaphore = create_semaphore(0); - allowed_globals.jobmutex = ap_create_mutex(NULL); - - /* spawn off the threads */ - child_handles = (thread *) alloca(nthreads * sizeof(int)); - for (i = 0; i < nthreads; i++) { - child_handles[i] = create_thread((void (*)(void *)) child_main, (void *) i); - } - - while (1) { - if (ap_max_requests_per_child && (total_jobs > ap_max_requests_per_child)) { - break; - } - /* Always check for the exit event being signaled. - */ - rv = WaitForSingleObject(exit_event, 0); - ap_assert((rv == WAIT_TIMEOUT) || (rv == WAIT_OBJECT_0)); - if (rv == WAIT_OBJECT_0) { - break; - } - - tv.tv_sec = wait_time; - tv.tv_usec = 0; - - memcpy(&main_fds, &listenfds, sizeof(fd_set)); - srv = ap_select(listenmaxfd + 1, &main_fds, NULL, NULL, &tv); - if (srv == SOCKET_ERROR) { - /* Error occurred - if EINTR, loop around with problem */ - if (WSAGetLastError() != WSAEINTR) { - /* A "real" error occurred, log it and increment the count of - * select errors. This count is used to ensure we don't go into - * a busy loop of continuous errors. - */ - ap_log_error(APLOG_MARK, APLOG_INFO|APLOG_WIN32ERROR, server_conf, "select: (listen)"); - count_select_errors++; - if (count_select_errors > MAX_SELECT_ERRORS) { - ap_log_error(APLOG_MARK, APLOG_ERR|APLOG_WIN32ERROR, server_conf, - "Too many errors in select loop. Child process exiting."); - break; - } - } - continue; - } - count_select_errors = 0; /* reset count of errors */ - if (srv == 0) { - continue; - } else { - ap_listen_rec *lr; - - lr = find_ready_listener(&main_fds); - if (lr != NULL) { - sd = lr->fd; - } - } - do { - clen = sizeof(sa_client); - csd = accept(sd, (struct sockaddr *) &sa_client, &clen); - if (csd == INVALID_SOCKET) { - csd = -1; - } - } while (csd < 0 && h_errno == WSAEINTR); - - if (csd < 0) { - if (h_errno != WSAECONNABORTED) { - ap_log_error(APLOG_MARK, APLOG_ERR|APLOG_WIN32ERROR, server_conf, - "accept: (client socket)"); - } - } - else { - add_job(csd); - total_jobs++; - } - } - - /* Get ready to shutdown and exit */ - allowed_globals.exit_now = 1; - ap_release_mutex(start_mutex); - -#ifdef UNGRACEFUL_RESTART - SetEvent(allowed_globals.thread_exit_event); -#else - for (i = 0; i < nthreads; i++) { - add_job(-1); - } -#endif - - /* Wait for all your children */ - end_time = time(NULL) + 180; - while (nthreads) { - rv = wait_for_many_objects(nthreads, child_handles, - end_time - time(NULL)); - if (rv != WAIT_TIMEOUT) { - rv = rv - WAIT_OBJECT_0; - ap_assert((rv >= 0) && (rv < nthreads)); - cleanup_thread(child_handles, &nthreads, rv); - continue; - } - break; - } - - for (i = 0; i < nthreads; i++) { - kill_thread(child_handles[i]); - free_thread(child_handles[i]); - } -#ifdef UNGRACEFUL_RESTART - ap_assert(CloseHandle(allowed_globals.thread_exit_event)); -#endif - destroy_semaphore(allowed_globals.jobsemaphore); - ap_destroy_mutex(allowed_globals.jobmutex); - - ap_destroy_pool(pchild); - -#if 0 - cleanup_scoreboard(); -#endif - -} - -/* - * Spawn a child Apache process. The child process has the command line arguments from - * argc and argv[], plus a -Z argument giving the name of an event. The child should - * open and poll or wait on this event. When it is signalled, the child should die. - * prefix is a prefix string for the event name. - * - * The child_num argument on entry contains a serial number for this child (used to create - * a unique event name). On exit, this number will have been incremented by one, ready - * for the next call. - * - * On exit, the value pointed to be *ev will contain the event created - * to signal the new child process. - * - * The return value is the handle to the child process if successful, else -1. If -1 is - * returned the error will already have been logged by ap_log_error(). - */ - -/********************************************************************** - * master_main - this is the parent (main) process. We create a - * child process to do the work, then sit around waiting for either - * the child to exit, or a restart or exit signal. If the child dies, - * we just respawn a new one. If we have a shutdown or graceful restart, - * tell the child to die when it is ready. If it is a non-graceful - * restart, force the child to die immediately. - **********************************************************************/ - -#define MAX_PROCESSES 50 /* must be < MAX_WAIT_OBJECTS-1 */ - -static void cleanup_process(HANDLE *handles, HANDLE *events, int position, int *processes) -{ - int i; - int handle = 0; - - CloseHandle(handles[position]); - CloseHandle(events[position]); - - handle = (int)handles[position]; - - for (i = position; i < (*processes)-1; i++) { - handles[i] = handles[i + 1]; - events[i] = events[i + 1]; - } - (*processes)--; -} - -static int create_process(pool *p, HANDLE *handles, HANDLE *events, int *processes) -{ - int rv; - char buf[1024]; - char *pCommand; - - STARTUPINFO si; /* Filled in prior to call to CreateProcess */ - PROCESS_INFORMATION pi; /* filled in on call to CreateProces */ - - ap_listen_rec *lr; - DWORD BytesWritten; - HANDLE hPipeRead = NULL; - HANDLE hPipeWrite = NULL; - SECURITY_ATTRIBUTES sa = {0}; - - sa.nLength = sizeof(sa); - sa.bInheritHandle = TRUE; - sa.lpSecurityDescriptor = NULL; - - /* Build the command line. Should look something like this: - * C:/apache/bin/apache.exe -f ap_server_confname - * First, get the path to the executable... - */ - rv = GetModuleFileName(NULL, buf, sizeof(buf)); - if (rv == sizeof(buf)) { - ap_log_error(APLOG_MARK, APLOG_WIN32ERROR | APLOG_CRIT, server_conf, - "Parent: Path to Apache process too long"); - return -1; - } else if (rv == 0) { - ap_log_error(APLOG_MARK, APLOG_WIN32ERROR | APLOG_CRIT, server_conf, - "Parent: GetModuleFileName() returned NULL for current process."); - return -1; - } - - // pCommand = ap_psprintf(p, "\"%s\" -f \"%s\"", buf, ap_server_confname); - pCommand = ap_psprintf(p, "\"%s\" -f \"%s\"", buf, SERVER_CONFIG_FILE); - - /* Create a pipe to send socket info to the child */ - if (!CreatePipe(&hPipeRead, &hPipeWrite, &sa, 0)) { - ap_log_error(APLOG_MARK, APLOG_WIN32ERROR | APLOG_CRIT, server_conf, - "Parent: Unable to create pipe to child process.\n"); - return -1; - } - - SetEnvironmentVariable("AP_PARENT_PID",ap_psprintf(p,"%d",parent_pid)); - - /* Give the read in of the pipe (hPipeRead) to the child as stdin. The - * parent will write the socket data to the child on this pipe. - */ - memset(&si, 0, sizeof(si)); - memset(&pi, 0, sizeof(pi)); - si.cb = sizeof(si); - si.dwFlags = STARTF_USESHOWWINDOW | STARTF_USESTDHANDLES; - si.wShowWindow = SW_HIDE; - si.hStdInput = hPipeRead; - - if (!CreateProcess(NULL, pCommand, NULL, NULL, - TRUE, /* Inherit handles */ - CREATE_SUSPENDED, /* Creation flags */ - NULL, /* Environment block */ - NULL, - &si, &pi)) { - ap_log_error(APLOG_MARK, APLOG_WIN32ERROR | APLOG_CRIT, server_conf, - "Parent: Not able to create the child process."); - /* - * We must close the handles to the new process and its main thread - * to prevent handle and memory leaks. - */ - CloseHandle(pi.hProcess); - CloseHandle(pi.hThread); - return -1; - } - else { - HANDLE kill_event; - LPWSAPROTOCOL_INFO lpWSAProtocolInfo; - - ap_log_error(APLOG_MARK, APLOG_NOERRNO | APLOG_INFO, server_conf, - "Parent: Created child process %d", pi.dwProcessId); - - SetEnvironmentVariable("AP_PARENT_PID",NULL); - - /* Create the exit_event, apCHILD_PID */ - kill_event = CreateEvent(NULL, TRUE, FALSE, - ap_psprintf(pconf,"apC%d", pi.dwProcessId)); // exit_event_name... - if (!kill_event) { - ap_log_error(APLOG_MARK, APLOG_WIN32ERROR | APLOG_CRIT, server_conf, - "Parent: Could not create exit event for child process"); - CloseHandle(pi.hProcess); - CloseHandle(pi.hThread); - return -1; - } - - /* Assume the child process lives. Update the process and event tables */ - handles[*processes] = pi.hProcess; - events[*processes] = kill_event; - (*processes)++; - - /* We never store the thread's handle, so close it now. */ - ResumeThread(pi.hThread); - CloseHandle(pi.hThread); - - /* Run the chain of open sockets. For each socket, duplicate it - * for the target process then send the WSAPROTOCOL_INFO - * (returned by dup socket) to the child */ - for (lr = ap_listeners; lr; lr = lr->next) { - lpWSAProtocolInfo = ap_pcalloc(p, sizeof(WSAPROTOCOL_INFO)); - ap_log_error(APLOG_MARK, APLOG_NOERRNO | APLOG_INFO, server_conf, - "Parent: Duplicating socket %d and sending it to child process %d", lr->fd, pi.dwProcessId); - if (WSADuplicateSocket(lr->fd, - pi.dwProcessId, - lpWSAProtocolInfo) == SOCKET_ERROR) { - ap_log_error(APLOG_MARK, APLOG_WIN32ERROR | APLOG_CRIT, server_conf, - "Parent: WSADuplicateSocket failed for socket %d.", lr->fd ); - return -1; - } - - if (!WriteFile(hPipeWrite, lpWSAProtocolInfo, (DWORD) sizeof(WSAPROTOCOL_INFO), - &BytesWritten, - (LPOVERLAPPED) NULL)) { - ap_log_error(APLOG_MARK, APLOG_WIN32ERROR | APLOG_CRIT, server_conf, - "Parent: Unable to write duplicated socket %d to the child.", lr->fd ); - return -1; - } - ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_INFO, server_conf, - "BytesWritten = %d WSAProtocolInfo = %x20", BytesWritten, *lpWSAProtocolInfo); - } - } - CloseHandle(hPipeRead); - CloseHandle(hPipeWrite); - - return 0; -} - -/* To share the semaphores with other processes, we need a NULL ACL - * Code from MS KB Q106387 - */ -static PSECURITY_ATTRIBUTES GetNullACL() -{ - PSECURITY_DESCRIPTOR pSD; - PSECURITY_ATTRIBUTES sa; - - sa = (PSECURITY_ATTRIBUTES) LocalAlloc(LPTR, sizeof(SECURITY_ATTRIBUTES)); - pSD = (PSECURITY_DESCRIPTOR) LocalAlloc(LPTR, - SECURITY_DESCRIPTOR_MIN_LENGTH); - if (pSD == NULL || sa == NULL) { - return NULL; - } - if (!InitializeSecurityDescriptor(pSD, SECURITY_DESCRIPTOR_REVISION) - || GetLastError()) { - LocalFree( pSD ); - LocalFree( sa ); - return NULL; - } - if (!SetSecurityDescriptorDacl(pSD, TRUE, (PACL) NULL, FALSE) - || GetLastError()) { - LocalFree( pSD ); - LocalFree( sa ); - return NULL; - } - sa->nLength = sizeof(sa); - sa->lpSecurityDescriptor = pSD; - sa->bInheritHandle = TRUE; - return sa; -} - - -static void CleanNullACL( void *sa ) { - if( sa ) { - LocalFree( ((PSECURITY_ATTRIBUTES)sa)->lpSecurityDescriptor); - LocalFree( sa ); - } -} - -static int master_main(server_rec *s, HANDLE shutdown_event, HANDLE restart_event) -{ - int remaining_children_to_start = ap_daemons_to_start; - int i; - int rv, cld; - int child_num = 0; - int restart_pending = 0; - int shutdown_pending = 0; - int current_live_processes = 0; /* number of child process we know about */ - - HANDLE process_handles[MAX_PROCESSES]; - HANDLE process_kill_events[MAX_PROCESSES]; - - setup_listeners(pconf, s); - - /* Create child process - * Should only be one in this version of Apache for WIN32 - */ - while (remaining_children_to_start--) { - if (create_process(pconf, process_handles, process_kill_events, - ¤t_live_processes) < 0) { - ap_log_error(APLOG_MARK, APLOG_NOERRNO, server_conf, - "master_main: create child process failed. Exiting."); - shutdown_pending = 1; - goto die_now; - } - } - - /* service_set_status(SERVICE_RUNNING);*/ - restart_pending = shutdown_pending = 0; - - /* Wait for shutdown or restart events or for child death */ - process_handles[current_live_processes] = shutdown_event; - process_handles[current_live_processes+1] = restart_event; - rv = WaitForMultipleObjects(current_live_processes+2, (HANDLE *)process_handles, - FALSE, INFINITE); - cld = rv - WAIT_OBJECT_0; - if (rv == WAIT_FAILED) { - /* Something serious is wrong */ - ap_log_error(APLOG_MARK,APLOG_CRIT|APLOG_WIN32ERROR, server_conf, - "master_main: : WaitForMultipeObjects on process handles and apache-signal -- doing shutdown"); - shutdown_pending = 1; - } - else if (rv == WAIT_TIMEOUT) { - /* Hey, this cannot happen */ - ap_log_error(APLOG_MARK, APLOG_ERR, s, - "master_main: WaitForMultipeObjects with INFINITE wait exited with WAIT_TIMEOUT"); - shutdown_pending = 1; - } - else if (cld == current_live_processes) { - /* shutdown_event signalled */ - shutdown_pending = 1; - ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_INFO, s, - "master_main: Shutdown event signaled. Shutting the server down."); - if (ResetEvent(shutdown_event) == 0) { - ap_log_error(APLOG_MARK, APLOG_ERR|APLOG_WIN32ERROR, s, - "ResetEvent(shutdown_event)"); - } - - } - else if (cld == current_live_processes+1) { - /* restart_event signalled */ - int children_to_kill = current_live_processes; - restart_pending = 1; - ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_INFO, s, - "master_main: Restart event signaled. Doing a graceful restart."); - if (ResetEvent(restart_event) == 0) { - ap_log_error(APLOG_MARK, APLOG_ERR|APLOG_WIN32ERROR, s, - "master_main: ResetEvent(restart_event) failed."); - } - /* Signal each child process to die - * We are making a big assumption here that the child process, once signaled, - * will REALLY go away. Since this is a restart, we do not want to hold the - * new child process up waiting for the old child to die. Remove the old - * child out of the process_handles table and hope for the best... - */ - for (i = 0; i < children_to_kill; i++) { - /* APD3("master_main: signalling child #%d handle %d to die", i, process_handles[i]); */ - if (SetEvent(process_kill_events[i]) == 0) - ap_log_error(APLOG_MARK, APLOG_ERR|APLOG_WIN32ERROR, s, - "master_main: SetEvent for child process in slot #%d failed", i); - cleanup_process(process_handles, process_kill_events, i, ¤t_live_processes); - } - } - else { - /* A child process must have exited because of MaxRequestPerChild being hit - * or a fatal error condition (seg fault, etc.). Remove the dead process - * from the process_handles and process_kill_events table and create a new - * child process. - * TODO: Consider restarting the child immediately without looping through http_main - * and without rereading the configuration. Will need this if we ever support multiple - * children. One option, create a parent thread which waits on child death and restarts it. - */ - restart_pending = 1; - ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_INFO, server_conf, - "master_main: Child processed exited (due to MaxRequestsPerChild?). Restarting the child process."); - ap_assert(cld < current_live_processes); - cleanup_process(process_handles, process_kill_events, cld, ¤t_live_processes); - /* APD2("main_process: child in slot %d died", rv); */ - /* restart_child(process_hancles, process_kill_events, cld, ¤t_live_processes); */ - } - -die_now: - if (shutdown_pending) { - int tmstart = time(NULL); - /* Signal each child processes to die */ - for (i = 0; i < current_live_processes; i++) { - if (SetEvent(process_kill_events[i]) == 0) - ap_log_error(APLOG_MARK,APLOG_ERR|APLOG_WIN32ERROR, server_conf, - "master_main: SetEvent for child process in slot #%d failed", i); - } - - while (current_live_processes && ((tmstart+60) > time(NULL))) { - rv = WaitForMultipleObjects(current_live_processes, (HANDLE *)process_handles, FALSE, 2000); - if (rv == WAIT_TIMEOUT) - continue; - ap_assert(rv != WAIT_FAILED); - cld = rv - WAIT_OBJECT_0; - ap_assert(rv < current_live_processes); - cleanup_process(process_handles, process_kill_events, cld, ¤t_live_processes); - } - for (i = 0; i < current_live_processes; i++) { - ap_log_error(APLOG_MARK,APLOG_ERR|APLOG_NOERRNO, server_conf, - "forcing termination of child #%d (handle %d)", i, process_handles[i]); - TerminateProcess((HANDLE) process_handles[i], 1); - } - return (0); /* Tell the caller we are shutting down */ - } - - return (1); /* Tell the caller we want a restart */ -} - -/* - * winnt_pre_config() - */ -static void winnt_pre_config(pool *pconf, pool *plog, pool *ptemp) -{ - char *pid; - one_process=1;//!!getenv("ONE_PROCESS"); - - /* Track parent/child pids... */ - pid = getenv("AP_PARENT_PID"); - if (pid) { - /* AP_PARENT_PID is only valid in the child */ - parent_pid = atoi(pid); - my_pid = getpid(); - } - else { - /* This is the parent... */ - parent_pid = my_pid = getpid(); - ap_log_pid(pconf, mpm_pid_fname); - } - - ap_listen_pre_config(); - ap_daemons_to_start = DEFAULT_NUM_DAEMON; - ap_threads_per_child = DEFAULT_START_THREAD; - mpm_pid_fname = DEFAULT_PIDLOG; - max_requests_per_child = DEFAULT_MAX_REQUESTS_PER_CHILD; - - ap_cpystrn(ap_coredump_dir, ap_server_root, sizeof(ap_coredump_dir)); - -} - -static void winnt_post_config(pool *pconf, pool *plog, pool *ptemp, server_rec* server_conf) -{ - server_conf = server_conf; -} - -API_EXPORT(int) ap_mpm_run(pool *_pconf, pool *plog, server_rec *s ) -{ - - char* exit_event_name; - -// time_t tmstart; - HANDLE shutdown_event; /* used to signal shutdown to parent */ - HANDLE restart_event; /* used to signal a restart to parent */ - - pconf = _pconf; - server_conf = s; - - if ((parent_pid != my_pid) || one_process) { - /* Child process */ - AMCSocketInitialize(); - exit_event_name = ap_psprintf(pconf, "apC%d", my_pid); - setup_signal_names(ap_psprintf(pconf,"ap%d", parent_pid)); - if (one_process) { - start_mutex = ap_create_mutex(signal_name_prefix); - exit_event = CreateEvent(NULL, TRUE, FALSE, exit_event_name); - } - else { - start_mutex = ap_open_mutex(signal_name_prefix); - exit_event = open_event(exit_event_name); - } - ap_assert(start_mutex); - ap_assert(exit_event); - - worker_main(); - - destroy_event(exit_event); - AMCSocketCleanup(); - } - else { - /* Parent process */ - static int restart = 0; - PSECURITY_ATTRIBUTES sa = GetNullACL(); /* returns NULL if invalid (Win95?) */ - - ap_clear_pool(plog); - ap_open_logs(server_conf, plog); - - if (!restart) { - /* service_set_status(SERVICE_START_PENDING);*/ - AMCSocketInitialize(); - setup_signal_names(ap_psprintf(pconf,"ap%d", parent_pid)); - - /* Create shutdown event, apPID_shutdown, where PID is the parent - * Apache process ID. Shutdown is signaled by 'apache -k shutdown'. - */ - shutdown_event = CreateEvent(sa, TRUE, FALSE, signal_shutdown_name); - if (!shutdown_event) { - ap_log_error(APLOG_MARK, APLOG_EMERG|APLOG_WIN32ERROR, s, - "master_main: Cannot create shutdown event %s", signal_shutdown_name); - CleanNullACL((void *)sa); - exit(1); - } - - /* Create restart event, apPID_restart, where PID is the parent - * Apache process ID. Restart is signaled by 'apache -k restart'. - */ - restart_event = CreateEvent(sa, TRUE, FALSE, signal_restart_name); - if (!restart_event) { - CloseHandle(shutdown_event); - ap_log_error(APLOG_MARK, APLOG_EMERG|APLOG_WIN32ERROR, s, - "master_main: Cannot create restart event %s", signal_restart_name); - CleanNullACL((void *)sa); - exit(1); - } - CleanNullACL((void *)sa); - - /* Create the start mutex, apPID, where PID is the parent Apache process ID. - * Ths start mutex is used during a restart to prevent more than one - * child process from entering the accept loop at once. - */ - start_mutex = ap_create_mutex(signal_name_prefix); - /* TODO: Add some code to detect failure */ - } - - /* Go to work... */ - restart = master_main(server_conf, shutdown_event, restart_event); - - if (!restart) { - const char *pidfile = NULL; - /* Shutting down. Clean up... */ - pidfile = ap_server_root_relative (pconf, mpm_pid_fname); - if ( pidfile != NULL && unlink(pidfile) == 0) - ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_INFO, - server_conf, - "removed PID file %s (pid=%ld)", - pidfile, (long)getpid()); - ap_destroy_mutex(start_mutex); - - CloseHandle(restart_event); - CloseHandle(shutdown_event); - AMCSocketCleanup(); - /* service_set_status(SERVICE_STOPPED); */ - } - return !restart; - } - return (0); -} - -static void winnt_hooks(void) -{ -// INIT_SIGLIST() - one_process = 0; - /* Configuration hooks implemented by http_config.c ... */ - ap_hook_pre_config(winnt_pre_config, NULL, NULL, HOOK_MIDDLE); -} - -/* - * Command processors - */ -static const char *set_pidfile(cmd_parms *cmd, void *dummy, char *arg) -{ - const char *err = ap_check_cmd_context(cmd, GLOBAL_ONLY); - if (err != NULL) { - return err; - } - - if (cmd->server->is_virtual) { - return "PidFile directive not allowed in <VirtualHost>"; - } - mpm_pid_fname = arg; - return NULL; -} - -static const char *set_threads_per_child (cmd_parms *cmd, void *dummy, char *arg) -{ - const char *err = ap_check_cmd_context(cmd, GLOBAL_ONLY); - if (err != NULL) { - return err; - } - - ap_threads_per_child = atoi(arg); - if (ap_threads_per_child > HARD_THREAD_LIMIT) { - fprintf(stderr, "WARNING: ThreadsPerChild of %d exceeds compile time" - "limit of %d threads,\n", ap_threads_per_child, - HARD_THREAD_LIMIT); - fprintf(stderr, " lowering ThreadsPerChild to %d. To increase, please" - "see the\n", HARD_THREAD_LIMIT); - fprintf(stderr, " HARD_THREAD_LIMIT define in src/include/httpd.h.\n"); - } - else if (ap_threads_per_child < 1) { - fprintf(stderr, "WARNING: Require ThreadsPerChild > 0, setting to 1\n"); - ap_threads_per_child = 1; - } - return NULL; -} - - -static const char *set_max_requests(cmd_parms *cmd, void *dummy, char *arg) -{ - const char *err = ap_check_cmd_context(cmd, GLOBAL_ONLY); - if (err != NULL) { - return err; - } - - max_requests_per_child = atoi(arg); - - return NULL; -} - -static const char *set_coredumpdir (cmd_parms *cmd, void *dummy, char *arg) -{ - struct stat finfo; - const char *fname; - const char *err = ap_check_cmd_context(cmd, GLOBAL_ONLY); - if (err != NULL) { - return err; - } - - fname = ap_server_root_relative(cmd->pool, arg); - /* ZZZ change this to the AP func FileInfo*/ - if ((stat(fname, &finfo) == -1) || !S_ISDIR(finfo.st_mode)) { - return ap_pstrcat(cmd->pool, "CoreDumpDirectory ", fname, - " does not exist or is not a directory", NULL); - } - ap_cpystrn(ap_coredump_dir, fname, sizeof(ap_coredump_dir)); - return NULL; -} -/* -static int -map_rv(int rv) -{ - switch(rv) - { - case WAIT_OBJECT_0: - case WAIT_ABANDONED: - return(MULTI_OK); - case WAIT_TIMEOUT: - return(MULTI_TIMEOUT); - case WAIT_FAILED: - return(MULTI_ERR); - default: - assert(0); - } - - assert(0); - return(0); -} -*/ - -/* -API_EXPORT(mutex *) ap_open_mutex(char *name) -{ - return(OpenMutex(MUTEX_ALL_ACCESS, FALSE, name)); -} -*/ - -struct ap_thread_mutex { - HANDLE _mutex; -}; - - -API_EXPORT(ap_thread_mutex *) ap_thread_mutex_new(void) -{ - ap_thread_mutex *mtx; - - mtx = malloc(sizeof(ap_thread_mutex)); - mtx->_mutex = CreateMutex(NULL, FALSE, NULL); - return mtx; -} - - -API_EXPORT(void) ap_thread_mutex_lock(ap_thread_mutex *mtx) -{ - int rv; - rv = WaitForSingleObject(mtx->_mutex, INFINITE); -} - - -API_EXPORT(void) ap_thread_mutex_unlock(ap_thread_mutex *mtx) -{ - ReleaseMutex(mtx->_mutex); -} - -API_EXPORT(void) ap_thread_mutex_destroy(ap_thread_mutex *mtx) -{ - CloseHandle(mtx->_mutex); - free(mtx); -} - -static const command_rec winnt_cmds[] = { -LISTEN_COMMANDS -{ "PidFile", set_pidfile, NULL, RSRC_CONF, TAKE1, - "A file for logging the server process ID"}, -//{ "ScoreBoardFile", set_scoreboard, NULL, RSRC_CONF, TAKE1, -// "A file for Apache to maintain runtime process management information"}, -{ "ThreadsPerChild", set_threads_per_child, NULL, RSRC_CONF, TAKE1, - "Number of threads each child creates" }, -{ "MaxRequestsPerChild", set_max_requests, NULL, RSRC_CONF, TAKE1, - "Maximum number of requests a particular child serves before dying." }, -{ "CoreDumpDirectory", set_coredumpdir, NULL, RSRC_CONF, TAKE1, - "The location of the directory Apache changes to before dumping core" }, -{ NULL } -}; - -module MODULE_VAR_EXPORT mpm_winnt_module = { - STANDARD20_MODULE_STUFF, - NULL, /* create per-directory config structure */ - NULL, /* merge per-directory config structures */ - NULL, /* create per-server config structure */ - NULL, /* merge per-server config structures */ - winnt_cmds, /* command table */ - NULL, /* handlers */ - winnt_hooks /* register_hooks */ -}; - -/* force Expat to be linked into the server executable */ -#if defined(USE_EXPAT) && !defined(SHARED_CORE_BOOTSTRAP) -#include "xmlparse.h" -const XML_LChar *suck_in_expat(void); -const XML_LChar *suck_in_expat(void) -{ - return XML_ErrorString(XML_ERROR_NONE); -} -#endif /* USE_EXPAT */ diff --git a/server/mpm/winnt/mpm_winnt.h b/server/mpm/winnt/mpm_winnt.h deleted file mode 100644 index 1d987d71bb..0000000000 --- a/server/mpm/winnt/mpm_winnt.h +++ /dev/null @@ -1,67 +0,0 @@ -/* ==================================================================== - * 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_MPM_WINNT_H -#define APACHE_MPM_WINNT_H - -extern int ap_threads_per_child; -extern int ap_max_requests_per_child; -extern void clean_child_exit(int); -extern int ap_extended_status; -extern void clean_child_exit(int); - -#endif /* APACHE_MPM_WINNT_H */ |