-<!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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>International Customized Server Error Messages</title>
+ </head>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+
+ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
+ vlink="#000080" alink="#FF0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="CENTER">Using XSSI and <samp>ErrorDocument</samp> to
+ configure customized international server error responses</h1>
+
+ <h2>Index</h2>
+
+ <ul>
+ <li><a href="#intro">Introduction</a></li>
+
+ <li><a href="#createdir">Creating an ErrorDocument
+ directory</a></li>
+
+ <li><a href="#docnames">Naming the individual error document
+ files</a></li>
+
+ <li><a href="#headfoot">The common header and footer
+ files</a></li>
+
+ <li><a href="#createdocs">Creating ErrorDocuments in
+ different languages</a></li>
+
+ <li><a href="#fallback">The fallback language</a></li>
+
+ <li><a href="#proxy">Customizing Proxy Error
+ Messages</a></li>
+
+ <li><a href="#listings">HTML listing of the discussed
+ example</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="intro" name="intro">Introduction</a></h2>
+ 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. <br />
+ <br />
+
+
+ <p>By using XSSI, all <a
+ href="../mod/core.html#errordocument">customized messages</a>
+ can share a homogenous and consistent style and layout, and
+ maintenance work (changing images, changing links) is kept to a
+ minimum because all layout information can be kept in a single
+ file.<br />
+ Error documents can be shared across different servers, or
+ even hosts, because all varying information is inserted at the
+ time the error document is returned on behalf of a failed
+ request.</p>
+
+ <p>Content Negotiation then selects the appropriate language
+ version of a particular error message text, honoring the
+ language preferences passed in the client's request. (Users
+ usually select their favorite languages in the preferences
+ options menu of today's browsers). When an error document in
+ the client's primary language version is unavailable, the
+ secondary languages are tried or a default (fallback) version
+ is used.</p>
+
+ <p>You have full flexibility in designing your error documents
+ to your personal taste (or your company's conventions). For
+ demonstration purposes, we present a simple generic error
+ document scheme. For this hypothetic server, we assume that all
+ error messages...</p>
+
+ <ul>
+ <li>possibly are served by different virtual hosts (different
+ host name, different IP address, or different port) on the
+ server machine,</li>
+
+ <li>show a predefined company logo in the right top of the
+ message (selectable by virtual host),</li>
+
+ <li>print the error title first, followed by an explanatory
+ text and (depending on the error context) help on how to
+ resolve the error,</li>
+
+ <li>have some kind of standardized background image,</li>
+
+ <li>display an apache logo and a feedback email address at
+ the bottom of the error message.</li>
+ </ul>
+ <br />
+ <br />
+
+
+ <p>An example of a "document not found" message for a german
+ client might look like this:<br />
+ <img src="../images/custom_errordocs.gif"
+ alt="[Needs graphics capability to display]" /><br />
+ All links in the document as well as links to the server's
+ administrator mail address, and even the name and port of the
+ serving virtual host are inserted in the error document at
+ "run-time", <em>i.e.</em>, when the error actually occurs.</p>
+
+ <h2><a id="createdir" name="createdir">Creating an
+ ErrorDocument directory</a></h2>
+ For this concept to work as easily as possible, we must take
+ advantage of as much server support as we can get:
+
+ <ol>
+ <li>By defining the <a
+ href="../mod/core.html#options">MultiViews option</a>, we
+ enable the language selection of the most appropriate
+ language alternative (content negotiation).</li>
+
+ <li>By setting the <a
+ href="../mod/mod_negotiation.html#languagepriority">LanguagePriority</a>
+ directive we define a set of default fallback languages in
+ the situation where the client's browser did not express any
+ preference at all.</li>
+
+ <li>By enabling <a href="../mod/mod_include.html">Server Side
+ Includes</a> (and disallowing execution of cgi scripts for
+ security reasons), we allow the server to include building
+ blocks of the error message, and to substitute the value of
+ certain environment variables into the generated document
+ (dynamic HTML) or even to conditionally include or omit parts
+ of the text.</li>
+
+ <li>The <a
+ href="../mod/mod_mime.html#addhandler">AddHandler</a> and <a
+ href="../mod/mod_mime.html#addtype">AddType</a> directives
+ are useful for automatically XSSI-expanding all files with a
+ <samp>.shtml</samp> suffix to <em>text/html</em>.</li>
+
+ <li>By using the <a
+ href="../mod/mod_alias.html#alias">Alias</a> directive, we
+ keep the error document directory outside of the document
+ tree because it can be regarded more as a server part than
+ part of the document tree.</li>
+
+ <li>The <a
+ href="../mod/core.html#directory"><Directory></a>-Block
+ restricts these "special" settings to the error document
+ directory and avoids an impact on any of the settings for the
+ regular document tree.</li>
+
+ <li>For each of the error codes to be handled (see RFC2068
+ for an exact description of each error code, or look at
+ <code>src/main/http_protocol.c</code> if you wish to see
+ apache's standard messages), an <a
+ href="../mod/core.html#errordocument">ErrorDocument</a> in
+ the aliased <samp>/errordocs</samp> directory is defined.
+ Note that we only define the basename of the document here
+ because the MultiViews option will select the best candidate
+ based on the language suffixes and the client's preferences.
+ Any error situation with an error code <em>not</em> handled
+ by a custom document will be dealt with by the server in the
+ standard way (<em>i.e.</em>, a plain error message in
+ english).</li>
+
+ <li>Finally, the <a
+ href="../mod/core.html#allowoverride">AllowOverride</a>
+ directive tells apache that it is not necessary to look for a
+ .htaccess file in the /errordocs directory: a minor speed
+ optimization.</li>
+ </ol>
+ The resulting <samp>httpd.conf</samp> configuration would then
+ look similar to this: <small>(Note that you can define your own
+ error messages using this method for only part of the document
+ tree, e.g., a /~user/ subtree. In this case, the configuration
+ could as well be put into the .htaccess file at the root of the
+ subtree, and the <Directory> and </Directory>
+ directives -but not the contained directives- must be
+ omitted.)</small>
+<pre>
LanguagePriority en fr de
Alias /errordocs /usr/local/apache/errordocs
<Directory /usr/local/apache/errordocs>
ErrorDocument 404 /errordocs/404
# "500 Internal Server Error",
ErrorDocument 500 /errordocs/500
-</PRE>
-The directory for the error messages (here:
-<SAMP>/usr/local/apache/errordocs/</SAMP>) must then be created with the
-appropriate permissions (readable and executable by the server uid or gid,
-only writable for the administrator).
-
-<H3><A NAME="docnames">Naming the individual error document files</A></H3>
-
-By defining the <SAMP>MultiViews</SAMP> option, the server was told to
-automatically scan the directory for matching variants (looking at language
-and content type suffixes) when a requested document was not found.
-In the configuration, we defined the names for the error documents to be
-just their error number (without any suffix).
-<P>
-The names of the individual error documents are now determined like this
-(I'm using 403 as an example, think of it as a placeholder for any of
-the configured error documents):
-<UL>
- <LI>No file errordocs/403 should exist. Otherwise, it would be found and
- served (with the DefaultType, usually text/plain), all negotiation
- would be bypassed.
- <LI>For each language for which we have an internationalized version
- (note that this need not be the same set of languages for each
- error code - you can get by with a single language version until
- you actually <EM>have</EM> translated versions), a document
- <SAMP>errordocs/403.shtml.<EM>lang</EM></SAMP> is created and
- filled with the error text in that language (<A HREF="#createdocs">see
- below</A>).
- <LI>One fallback document called <SAMP>errordocs/403.shtml</SAMP> is
- created, usually by creating a symlink to the default language
- variant (<A HREF="#fallback">see below</A>).
-</UL>
-
-<H3><A NAME="headfoot">The common header and footer files</A></H3>
-
-By putting as much layout information in two special "include files",
-the error documents can be reduced to a bare minimum.
-<P>
-One of these layout files defines the HTML document header
-and a configurable list of paths to the icons to be shown in the resulting
-error document. These paths are exported as a set of XSSI environment
-variables and are later evaluated by the "footer" special file.
-The title of the current error (which is
-put into the TITLE tag and an H1 header) is simply passed in from the main
-error document in a variable called <CODE>title</CODE>.<BR>
-<STRONG>By changing this file, the layout of all generated error
-messages can be changed in a second.</STRONG>
-(By exploiting the features of XSSI, you can easily define different
-layouts based on the current virtual host, or even based on the
-client's domain name).
-<P>
-The second layout file describes the footer to be displayed at the bottom
-of every error message. In this example, it shows an apache logo, the current
-server time, the server version string and adds a mail reference to the
-site's webmaster.
-<P>
-For simplicity, the header file is simply called <CODE>head.shtml</CODE>
-because it contains server-parsed content but no language specific
-information. The footer file exists once for each language translation,
-plus a symlink for the default language.<P>
-<STRONG>Example:</STRONG> for English, French and German versions
-(default english)<BR>
-<CODE>foot.shtml.en</CODE>,<BR>
-<CODE>foot.shtml.fr</CODE>,<BR>
-<CODE>foot.shtml.de</CODE>,<BR>
-<CODE>foot.shtml</CODE> symlink to <CODE>foot.shtml.en</CODE><P>
-Both files are included into the error document by using the
-directives <CODE><!--#include virtual="head" --></CODE>
-and <CODE><!--#include virtual="foot" --></CODE>
-respectively: the rest of the magic occurs in mod_negotiation and
-in mod_include.
-<P>
-
-See <A HREF="#listings">the listings below</A> to see an actual HTML
-implementation of the discussed example.
-
-
-<H3><A NAME="createdocs">Creating ErrorDocuments in different languages</A>
-</H3>
-
-After all this preparation work, little remains to be said about the
-actual documents. They all share a simple common structure:
-<PRE>
-<!--#set var="title" value="<EM>error description title</EM>" -->
+</pre>
+ The directory for the error messages (here:
+ <samp>/usr/local/apache/errordocs/</samp>) must then be created
+ with the appropriate permissions (readable and executable by
+ the server uid or gid, only writable for the administrator).
+
+ <h3><a id="docnames" name="docnames">Naming the individual
+ error document files</a></h3>
+ By defining the <samp>MultiViews</samp> option, the server was
+ told to automatically scan the directory for matching variants
+ (looking at language and content type suffixes) when a
+ requested document was not found. In the configuration, we
+ defined the names for the error documents to be just their
+ error number (without any suffix).
+
+ <p>The names of the individual error documents are now
+ determined like this (I'm using 403 as an example, think of it
+ as a placeholder for any of the configured error
+ documents):</p>
+
+ <ul>
+ <li>No file errordocs/403 should exist. Otherwise, it would
+ be found and served (with the DefaultType, usually
+ text/plain), all negotiation would be bypassed.</li>
+
+ <li>For each language for which we have an internationalized
+ version (note that this need not be the same set of languages
+ for each error code - you can get by with a single language
+ version until you actually <em>have</em> translated
+ versions), a document
+ <samp>errordocs/403.shtml.<em>lang</em></samp> is created and
+ filled with the error text in that language (<a
+ href="#createdocs">see below</a>).</li>
+
+ <li>One fallback document called
+ <samp>errordocs/403.shtml</samp> is created, usually by
+ creating a symlink to the default language variant (<a
+ href="#fallback">see below</a>).</li>
+ </ul>
+
+ <h3><a id="headfoot" name="headfoot">The common header and
+ footer files</a></h3>
+ By putting as much layout information in two special "include
+ files", the error documents can be reduced to a bare minimum.
+
+ <p>One of these layout files defines the HTML document header
+ and a configurable list of paths to the icons to be shown in
+ the resulting error document. These paths are exported as a set
+ of XSSI environment variables and are later evaluated by the
+ "footer" special file. The title of the current error (which is
+ put into the TITLE tag and an H1 header) is simply passed in
+ from the main error document in a variable called
+ <code>title</code>.<br />
+ <strong>By changing this file, the layout of all generated
+ error messages can be changed in a second.</strong> (By
+ exploiting the features of XSSI, you can easily define
+ different layouts based on the current virtual host, or even
+ based on the client's domain name).</p>
+
+ <p>The second layout file describes the footer to be displayed
+ at the bottom of every error message. In this example, it shows
+ an apache logo, the current server time, the server version
+ string and adds a mail reference to the site's webmaster.</p>
+
+ <p>For simplicity, the header file is simply called
+ <code>head.shtml</code> because it contains server-parsed
+ content but no language specific information. The footer file
+ exists once for each language translation, plus a symlink for
+ the default language.</p>
+
+ <p><strong>Example:</strong> for English, French and German
+ versions (default english)<br />
+ <code>foot.shtml.en</code>,<br />
+ <code>foot.shtml.fr</code>,<br />
+ <code>foot.shtml.de</code>,<br />
+ <code>foot.shtml</code> symlink to
+ <code>foot.shtml.en</code></p>
+
+ <p>Both files are included into the error document by using the
+ directives <code><!--#include virtual="head" --></code>
+ and <code><!--#include virtual="foot" --></code>
+ respectively: the rest of the magic occurs in mod_negotiation
+ and in mod_include.</p>
+
+ <p>See <a href="#listings">the listings below</a> to see an
+ actual HTML implementation of the discussed example.</p>
+
+ <h3><a id="createdocs" name="createdocs">Creating
+ ErrorDocuments in different languages</a></h3>
+ After all this preparation work, little remains to be said
+ about the actual documents. They all share a simple common
+ structure:
+<pre>
+<!--#set var="title" value="<em>error description title</em>" -->
<!--#include virtual="head" -->
- <EM>explanatory error text</EM>
+ <em>explanatory error text</em>
<!--#include virtual="foot" -->
-</PRE>
-In the <A HREF="#listings">listings section</A>, you can see an example
-of a [400 Bad Request] error document. Documents as simple as that
-certainly cause no problems to translate or expand.
-
-<H3><A NAME="fallback">The fallback language</A></H3>
-
-Do we need a special handling for languages other than those we have
-translations for? We did set the LanguagePriority, didn't we?!
-<P>
-Well, the LanguagePriority directive is for the case where the client does
-not express any language priority at all. But what
-happens in the situation where the client wants one
-of the languages we do not have, and none of those we do have?
-<P>
-Without doing anything, the Apache server will usually return a
-[406 no acceptable variant] error, listing the choices from which the client
-may select. But we're in an error message already, and important error
-information might get lost when the client had to choose a language
-representation first.
-<P>
-So, in this situation it appears to be easier to define a fallback language
-(by copying or linking, <EM>e.g.</EM>, the english version to a language-less version).
-Because the negotiation algorithm prefers "more specialized" variants over
-"more generic" variants, these generic alternatives will only be chosen
-when the normal negotiation did not succeed.
-<P>
-A simple shell script to do it (execute within the errordocs/ dir):
-<PRE>
+</pre>
+ In the <a href="#listings">listings section</a>, you can see an
+ example of a [400 Bad Request] error document. Documents as
+ simple as that certainly cause no problems to translate or
+ expand.
+
+ <h3><a id="fallback" name="fallback">The fallback
+ language</a></h3>
+ Do we need a special handling for languages other than those we
+ have translations for? We did set the LanguagePriority, didn't
+ we?!
+
+ <p>Well, the LanguagePriority directive is for the case where
+ the client does not express any language priority at all. But
+ what happens in the situation where the client wants one of the
+ languages we do not have, and none of those we do have?</p>
+
+ <p>Without doing anything, the Apache server will usually
+ return a [406 no acceptable variant] error, listing the choices
+ from which the client may select. But we're in an error message
+ already, and important error information might get lost when
+ the client had to choose a language representation first.</p>
+
+ <p>So, in this situation it appears to be easier to define a
+ fallback language (by copying or linking, <em>e.g.</em>, the
+ english version to a language-less version). Because the
+ negotiation algorithm prefers "more specialized" variants over
+ "more generic" variants, these generic alternatives will only
+ be chosen when the normal negotiation did not succeed.</p>
+
+ <p>A simple shell script to do it (execute within the
+ errordocs/ dir):</p>
+<pre>
for f in *.shtml.en
do
ln -s $f `basename $f .en`
done
-</PRE>
-
-<P>
-</P>
-
-<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>
+</pre>
+
+ <h2><a id="proxy" name="proxy">Customizing Proxy Error
+ Messages</a></h2>
+
+ <p>As of Apache-1.3, it is possible to use the
+ <code>ErrorDocument</code> mechanism for proxy error messages
+ as well (previous versions always returned fixed predefined
+ error messages).</p>
+
+ <p>Most proxy errors return an error code of [500 Internal
+ Server Error]. To find out whether a particular error document
+ was invoked on behalf of a proxy error or because of some other
+ server error, and what the reason for the failure was, you can
+ check the contents of the new <code>ERROR_NOTES</code> CGI
+ environment variable: if invoked for a proxy error, this
+ variable will contain the actual proxy error message text in
+ HTML form.</p>
+
+ <p>The following excerpt demonstrates how to exploit the
+ <code>ERROR_NOTES</code> variable within an error document:</p>
+<pre>
<!--#if expr="$REDIRECT_ERROR_NOTES = ''" -->
<p>
The server encountered an unexpected condition
<!--#else -->
<!--#echo var="REDIRECT_ERROR_NOTES" -->
<!--#endif -->
-</PRE>
+</pre>
-<H2><A NAME="listings">HTML listing of the discussed example</A></H2>
-
-So, to summarize our example, here's the complete listing of the
-<SAMP>400.shtml.en</SAMP> document. You will notice that it contains
-almost nothing but the error text (with conditional additions).
-Starting with this example, you will find it easy to add more error
-documents, or to translate the error documents to different languages.
-<HR><PRE>
+ <h2><a id="listings" name="listings">HTML listing of the
+ discussed example</a></h2>
+ So, to summarize our example, here's the complete listing of
+ the <samp>400.shtml.en</samp> document. You will notice that it
+ contains almost nothing but the error text (with conditional
+ additions). Starting with this example, you will find it easy
+ to add more error documents, or to translate the error
+ documents to different languages.
+ <hr />
+<pre>
<!--#set var="title" value="Bad Request"
--><!--#include virtual="head" --><P>
Your browser sent a request that this server could not understand:
<!--#endif -->
</P>
<!--#include virtual="foot" -->
-</PRE><HR>
-
-Here is the complete <SAMP>head.shtml</SAMP> file (the funny line
-breaks avoid empty lines in the document after XSSI processing). Note the
-configuration section at top. That's where you configure the images and logos
-as well as the apache documentation directory. Look how this file displays
-two different logos depending on the content of the virtual host name
-($SERVER_NAME), and that an animated apache logo is shown if the browser
-appears to support it (the latter requires server configuration lines
-of the form <BR><CODE>BrowserMatch "^Mozilla/[2-4]" anigif</CODE><BR>
-for browser types which support animated GIFs).
-<HR><PRE>
+</pre>
+ <hr />
+ Here is the complete <samp>head.shtml</samp> file (the funny
+ line breaks avoid empty lines in the document after XSSI
+ processing). Note the configuration section at top. That's
+ where you configure the images and logos as well as the apache
+ documentation directory. Look how this file displays two
+ different logos depending on the content of the virtual host
+ name ($SERVER_NAME), and that an animated apache logo is shown
+ if the browser appears to support it (the latter requires
+ server configuration lines of the form <br />
+ <code>BrowserMatch "^Mozilla/[2-4]" anigif</code><br />
+ for browser types which support animated GIFs).
+ <hr />
+<pre>
<!--#if expr="$SERVER_NAME = /.*\.mycompany\.com/"
--><!--#set var="IMG_CorpLogo"
value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif"
</H1>
<HR><!-- ======================================================== -->
<DIV>
-</PRE><HR>
- and this is the <SAMP>foot.shtml.en</SAMP> file:
-<HR><PRE>
-
+</pre>
+ <hr />
+ and this is the <samp>foot.shtml.en</samp> file:
+ <hr />
+<pre>
</DIV>
<HR>
<DIV ALIGN="right"><SMALL><SUP>Local Server time:
</ADDRESS>
</UL></BODY>
</HTML>
-</PRE><HR>
-
-
-<H3>More welcome!</H3>
-
-If you have tips to contribute, send mail to <A
-HREF="mailto:martin@apache.org">martin@apache.org</A>
+</pre>
+ <hr />
- <!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+ <h3>More welcome!</h3>
+ If you have tips to contribute, send mail to <a
+ href="mailto:martin@apache.org">martin@apache.org</a>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-<!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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Descriptors and Apache</title>
+ </head>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+
+ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
+ vlink="#000080" alink="#FF0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="CENTER">Descriptors and Apache</h1>
+
+ <p>A <em>descriptor</em>, also commonly called a <em>file
+ handle</em> is an object that a program uses to read or write
+ an open file, or open network socket, or a variety of other
+ devices. It is represented by an integer, and you may be
+ familiar with <code>stdin</code>, <code>stdout</code>, and
+ <code>stderr</code> which are descriptors 0, 1, and 2
+ respectively. Apache needs a descriptor for each log file, plus
+ one for each network socket that it listens on, plus a handful
+ of others. Libraries that Apache uses may also require
+ descriptors. Normal programs don't open up many descriptors at
+ all, and so there are some latent problems that you may
+ experience should you start running Apache with many
+ descriptors (<em>i.e.</em>, with many virtual hosts).</p>
+
+ <p>The operating system enforces a limit on the number of
+ descriptors that a program can have open at a time. There are
+ typically three limits involved here. One is a kernel
+ limitation, depending on your operating system you will either
+ be able to tune the number of descriptors available to higher
+ numbers (this is frequently called <em>FD_SETSIZE</em>). Or you
+ may be stuck with a (relatively) low amount. The second limit
+ is called the <em>hard resource</em> limit, and it is sometimes
+ set by root in an obscure operating system file, but frequently
+ is the same as the kernel limit. The third limit is called the
+ <em>soft resource</em> limit. The soft limit is always less
+ than or equal to the hard limit. For example, the hard limit
+ may be 1024, but the soft limit only 64. Any user can raise
+ their soft limit up to the hard limit. Root can raise the hard
+ limit up to the system maximum limit. The soft limit is the
+ actual limit that is used when enforcing the maximum number of
+ files a process can have open.</p>
+
+ <p>To summarize:</p>
+
+ <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>SCO OpenServer</STRONG>
- <DD>Edit the
- <CODE>/etc/conf/cf.d/stune</CODE> file or use
- <CODE>/etc/conf/cf.d/configure</CODE> choice 7
- (User and Group configuration) and modify the <CODE>NOFILES</CODE> kernel
- parameter to a suitably higher value. SCO recommends a number
- between 60 and 11000, the default is 110. Relink and reboot,
- and the new number of descriptors will be available.
-
- <P>
-
- <DT><STRONG>Compaq Tru64 UNIX/Digital UNIX/OSF</STRONG>
- <DD><OL>
- <LI>Raise <code>open_max_soft</code> and <code>open_max_hard</code>
- to 4096 in the proc subsystem.
- Do a man on sysconfig, sysconfigdb, and sysconfigtab.
- <LI>Raise <code>max-vnodes</code> to a large number which is greater
- than the number of apache processes * 4096
- (Setting it to 250,000 should be good for most people).
- Do a man on sysconfig, sysconfigdb, and sysconfigtab.
- <LI>If you are using Tru64 5.0, 5.0A, or 5.1, define
- <code>NO_SLACK</code> to work around a bug in the OS.
- <code>CFLAGS="-DNO_SLACK" ./configure</code>
- </OL>
-
- <P>
-
- <DT><STRONG>Others</STRONG>
- <DD>If you have details on another operating system, please submit
- it through our <A HREF="http://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>
+</pre>
+ </center>
+
+ <p>You control the hard and soft limits using the
+ <code>limit</code> (csh) or <code>ulimit</code> (sh)
+ directives. See the respective man pages for more information.
+ For example you can probably use <code>ulimit -n
+ unlimited</code> to raise your soft limit up to the hard limit.
+ You should include this command in a shell script which starts
+ your webserver.</p>
+
+ <p>Unfortunately, it's not always this simple. As mentioned
+ above, you will probably run into some system limitations that
+ will need to be worked around somehow. Work was done in version
+ 1.2.1 to improve the situation somewhat. Here is a partial list
+ of systems and workarounds (assuming you are using 1.2.1 or
+ later):</p>
+
+ <dl>
+ <dt><strong>BSDI 2.0</strong></dt>
+
+ <dd>Under BSDI 2.0 you can build Apache to support more
+ descriptors by adding <code>-DFD_SETSIZE=nnn</code> to
+ <code>EXTRA_CFLAGS</code> (where nnn is the number of
+ descriptors you wish to support, keep it less than the hard
+ limit). But it will run into trouble if more than
+ approximately 240 Listen directives are used. This may be
+ cured by rebuilding your kernel with a higher
+ FD_SETSIZE.</dd>
+
+ <dt><strong>FreeBSD 2.2, BSDI 2.1+</strong></dt>
+
+ <dd>Similar to the BSDI 2.0 case, you should define
+ <code>FD_SETSIZE</code> and rebuild. But the extra Listen
+ limitation doesn't exist.</dd>
+
+ <dt><strong>Linux</strong></dt>
+
+ <dd>By default Linux has a kernel maximum of 256 open
+ descriptors per process. There are several patches available
+ for the 2.0.x series which raise this to 1024 and beyond, and
+ you can find them in the "unofficial patches" section of <a
+ href="http://www.linuxhq.com/">the Linux Information HQ</a>.
+ None of these patches are perfect, and an entirely different
+ approach is likely to be taken during the 2.1.x development.
+ Applying these patches will raise the FD_SETSIZE used to
+ compile all programs, and unless you rebuild all your
+ libraries you should avoid running any other program with a
+ soft descriptor limit above 256. As of this writing the
+ patches available for increasing the number of descriptors do
+ not take this into account. On a dedicated webserver you
+ probably won't run into trouble.</dd>
+
+ <dt><strong>Solaris through 2.5.1</strong></dt>
+
+ <dd>Solaris has a kernel hard limit of 1024 (may be lower in
+ earlier versions). But it has a limitation that files using
+ the stdio library cannot have a descriptor above 255. Apache
+ uses the stdio library for the ErrorLog directive. When you
+ have more than approximately 110 virtual hosts (with an error
+ log and an access log each) you will need to build Apache
+ with <code>-DHIGH_SLACK_LINE=256</code> added to
+ <code>EXTRA_CFLAGS</code>. You will be limited to
+ approximately 240 error logs if you do this.</dd>
+
+ <dt><strong>AIX</strong></dt>
+
+ <dd>AIX version 3.2?? appears to have a hard limit of 128
+ descriptors. End of story. Version 4.1.5 has a hard limit of
+ 2000.</dd>
+
+ <dt><strong>SCO OpenServer</strong></dt>
+
+ <dd>Edit the <code>/etc/conf/cf.d/stune</code> file or use
+ <code>/etc/conf/cf.d/configure</code> choice 7 (User and
+ Group configuration) and modify the <code>NOFILES</code>
+ kernel parameter to a suitably higher value. SCO recommends a
+ number between 60 and 11000, the default is 110. Relink and
+ reboot, and the new number of descriptors will be
+ available.</dd>
+
+ <dt><strong>Compaq Tru64 UNIX/Digital UNIX/OSF</strong></dt>
+
+ <dd>
+ <ol>
+ <li>Raise <code>open_max_soft</code> and
+ <code>open_max_hard</code> to 4096 in the proc subsystem.
+ Do a man on sysconfig, sysconfigdb, and
+ sysconfigtab.</li>
+
+ <li>Raise <code>max-vnodes</code> to a large number which
+ is greater than the number of apache processes * 4096
+ (Setting it to 250,000 should be good for most people).
+ Do a man on sysconfig, sysconfigdb, and
+ sysconfigtab.</li>
+
+ <li>If you are using Tru64 5.0, 5.0A, or 5.1, define
+ <code>NO_SLACK</code> to work around a bug in the OS.
+ <code>CFLAGS="-DNO_SLACK" ./configure</code></li>
+ </ol>
+ </dd>
+
+ <dt><strong>Others</strong></dt>
+
+ <dd>If you have details on another operating system, please
+ submit it through our <a
+ href="http://www.apache.org/bug_report.html">Bug Report
+ Page</a>.</dd>
+ </dl>
+
+ <p>In addition to the problems described above there are
+ problems with many libraries that Apache uses. The most common
+ example is the bind DNS resolver library that is used by pretty
+ much every unix, which fails if it ends up with a descriptor
+ above 256. We suspect there are other libraries that similar
+ limitations. So the code as of 1.2.1 takes a defensive stance
+ and tries to save descriptors less than 16 for use while
+ processing each request. This is called the <em>low slack
+ line</em>.</p>
+
+ <p>Note that this shouldn't waste descriptors. If you really
+ are pushing the limits and Apache can't get a descriptor above
+ 16 when it wants it, it will settle for one below 16.</p>
+
+ <p>In extreme situations you may want to lower the low slack
+ line, but you shouldn't ever need to. For example, lowering it
+ can increase the limits 240 described above under Solaris and
+ BSDI 2.0. But you'll play a delicate balancing game with the
+ descriptors needed to serve a request. Should you want to play
+ this game, the compile time parameter is
+ <code>LOW_SLACK_LINE</code> and there's a tiny bit of
+ documentation in the header file <code>httpd.h</code>.</p>
+
+ <p>Finally, if you suspect that all this slack stuff is causing
+ you problems, you can disable it. Add <code>-DNO_SLACK</code>
+ to <code>EXTRA_CFLAGS</code> and rebuild. But please report it
+ to our <a href="http://www.apache.org/bug_report.html">Bug
+ Report Page</a> so that we can investigate.
+ <!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Connections in FIN_WAIT_2 and Apache</TITLE>
-<LINK REV="made" HREF="mailto:marc@apache.org">
-
-</HEAD>
-
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
-
-<H1 ALIGN="CENTER">Connections in the FIN_WAIT_2 state and Apache</H1>
-<OL>
-<LI><H2>What is the FIN_WAIT_2 state?</H2>
-Starting with the Apache 1.2 betas, people are reporting many more
-connections in the FIN_WAIT_2 state (as reported by
-<CODE>netstat</CODE>) than they saw using older versions. When the
-server closes a TCP connection, it sends a packet with the FIN bit
-sent to the client, which then responds with a packet with the ACK bit
-set. The client then sends a packet with the FIN bit set to the
-server, which responds with an ACK and the connection is closed. The
-state that the connection is in during the period between when the
-server gets the ACK from the client and the server gets the FIN from
-the client is known as FIN_WAIT_2. See the <A
-HREF="ftp://ds.internic.net/rfc/rfc793.txt">TCP RFC</A> for the
-technical details of the state transitions.<P>
-
-The FIN_WAIT_2 state is somewhat unusual in that there is no timeout
-defined in the standard for it. This means that on many operating
-systems, a connection in the FIN_WAIT_2 state will stay around until
-the system is rebooted. If the system does not have a timeout and
-too many FIN_WAIT_2 connections build up, it can fill up the space
-allocated for storing information about the connections and crash
-the kernel. The connections in FIN_WAIT_2 do not tie up an httpd
-process.<P>
-
-<LI><H2>But why does it happen?</H2>
-
-There are numerous reasons for it happening, some of them may not
-yet be fully clear. What is known follows.<P>
-
-<H3>Buggy clients and persistent connections</H3>
-
-Several clients have a bug which pops up when dealing with
-<A HREF="../keepalive.html">persistent connections</A> (aka keepalives).
-When the connection is idle and the server closes the connection
-(based on the <A HREF="../mod/core.html#keepalivetimeout">
-KeepAliveTimeout</A>), the client is programmed so that the client does
-not send back a FIN and ACK to the server. This means that the
-connection stays in the FIN_WAIT_2 state until one of the following
-happens:<P>
-<UL>
- <LI>The client opens a new connection to the same or a different
- site, which causes it to fully close the older connection on
- that socket.
- <LI>The user exits the client, which on some (most?) clients
- causes the OS to fully shutdown the connection.
- <LI>The FIN_WAIT_2 times out, on servers that have a timeout
- for this state.
-</UL><P>
-If you are lucky, this means that the buggy client will fully close the
-connection and release the resources on your server. However, there
-are some cases where the socket is never fully closed, such as a dialup
-client disconnecting from their provider before closing the client.
-In addition, a client might sit idle for days without making another
-connection, and thus may hold its end of the socket open for days
-even though it has no further use for it.
-<STRONG>This is a bug in the browser or in its operating system's
-TCP implementation.</STRONG> <P>
-
-The clients on which this problem has been verified to exist:<P>
-<UL>
- <LI>Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE i386)
- <LI>Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE i386)
- <LI>Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m)
- <LI>MSIE 3.01 on the Macintosh
- <LI>MSIE 3.01 on Windows 95
-</UL><P>
-
-This does not appear to be a problem on:
-<UL>
- <LI>Mozilla/3.01 (Win95; I)
-</UL>
-<P>
-
-It is expected that many other clients have the same problem. What a
-client <STRONG>should do</STRONG> is periodically check its open
-socket(s) to see if they have been closed by the server, and close their
-side of the connection if the server has closed. This check need only
-occur once every few seconds, and may even be detected by a OS signal
-on some systems (<EM>e.g.</EM>, Win95 and NT clients have this capability, but
-they seem to be ignoring it).<P>
-
-Apache <STRONG>cannot</STRONG> avoid these FIN_WAIT_2 states unless it
-disables persistent connections for the buggy clients, just
-like we recommend doing for Navigator 2.x clients due to other bugs.
-However, non-persistent connections increase the total number of
-connections needed per client and slow retrieval of an image-laden
-web page. Since non-persistent connections have their own resource
-consumptions and a short waiting period after each closure, a busy server
-may need persistence in order to best serve its clients.<P>
-
-As far as we know, the client-caused FIN_WAIT_2 problem is present for
-all servers that support persistent connections, including Apache 1.1.x
-and 1.2.<P>
-
-<H3>A necessary bit of code introduced in 1.2</H3>
-
-While the above bug is a problem, it is not the whole problem.
-Some users have observed no FIN_WAIT_2 problems with Apache 1.1.x,
-but with 1.2b enough connections build up in the FIN_WAIT_2 state to
-crash their server.
-
-The most likely source for additional FIN_WAIT_2 states
-is a function called <CODE>lingering_close()</CODE> which was added
-between 1.1 and 1.2. This function is necessary for the proper
-handling of persistent connections and any request which includes
-content in the message body (<EM>e.g.</EM>, PUTs and POSTs).
-What it does is read any data sent by the client for
-a certain time after the server closes the connection. The exact
-reasons for doing this are somewhat complicated, but involve what
-happens if the client is making a request at the same time the
-server sends a response and closes the connection. Without lingering,
-the client might be forced to reset its TCP input buffer before it
-has a chance to read the server's response, and thus understand why
-the connection has closed.
-See the <A HREF="#appendix">appendix</A> for more details.<P>
-
-The code in <CODE>lingering_close()</CODE> appears to cause problems
-for a number of factors, including the change in traffic patterns
-that it causes. The code has been thoroughly reviewed and we are
-not aware of any bugs in it. It is possible that there is some
-problem in the BSD TCP stack, aside from the lack of a timeout
-for the FIN_WAIT_2 state, exposed by the <CODE>lingering_close</CODE>
-code that causes the observed problems.<P>
-
-<H2><LI>What can I do about it?</H2>
-
-There are several possible workarounds to the problem, some of
-which work better than others.<P>
-
-<H3>Add a timeout for FIN_WAIT_2</H3>
-
-The obvious workaround is to simply have a timeout for the FIN_WAIT_2 state.
-This is not specified by the RFC, and could be claimed to be a
-violation of the RFC, but it is widely recognized as being necessary.
-The following systems are known to have a timeout:
-<P>
-<UL>
- <LI><A HREF="http://www.freebsd.org/">FreeBSD</A> versions starting at
- 2.0 or possibly earlier.
- <LI><A HREF="http://www.netbsd.org/">NetBSD</A> version 1.2(?)
- <LI><A HREF="http://www.openbsd.org/">OpenBSD</A> all versions(?)
- <LI><A HREF="http://www.bsdi.com/">BSD/OS</A> 2.1, with the
- <A HREF="ftp://ftp.bsdi.com/bsdi/patches/patches-2.1/K210-027">
- K210-027</A> patch installed.
- <LI><A HREF="http://www.sun.com/">Solaris</A> as of around version
- 2.2. The timeout can be tuned by using <CODE>ndd</CODE> to
- modify <CODE>tcp_fin_wait_2_flush_interval</CODE>, but the
- default should be appropriate for most servers and improper
- tuning can have negative impacts.
- <LI><A HREF="http://www.linux.org/">Linux</A> 2.0.x and
- earlier(?)
- <LI><A HREF="http://www.hp.com/">HP-UX</A> 10.x defaults to
- terminating connections in the FIN_WAIT_2 state after the
- normal keepalive timeouts. This does not
- refer to the persistent connection or HTTP keepalive
- timeouts, but the <CODE>SO_LINGER</CODE> socket option
- which is enabled by Apache. This parameter can be adjusted
- by using <CODE>nettune</CODE> to modify parameters such as
- <CODE>tcp_keepstart</CODE> and <CODE>tcp_keepstop</CODE>.
- In later revisions, there is an explicit timer for
- connections in FIN_WAIT_2 that can be modified; contact HP
- support for details.
- <LI><A HREF="http://www.sgi.com/">SGI IRIX</A> can be patched to
- support a timeout. For IRIX 5.3, 6.2, and 6.3,
- use patches 1654, 1703 and 1778 respectively. If you
- have trouble locating these patches, please contact your
- SGI support channel for help.
- <LI><A HREF="http://www.ncr.com/">NCR's MP RAS Unix</A> 2.xx and
- 3.xx both have FIN_WAIT_2 timeouts. In 2.xx it is non-tunable
- at 600 seconds, while in 3.xx it defaults to 600 seconds and
- is calculated based on the tunable "max keep alive probes"
- (default of 8) multiplied by the "keep alive interval" (default
- 75 seconds).
- <LI><A HREF="http://www.sequent.com">Sequent's ptx/TCP/IP for
- DYNIX/ptx</A> has had a FIN_WAIT_2 timeout since around
- release 4.1 in mid-1994.
-</UL>
-<P>
-The following systems are known to not have a timeout:
-<P>
-<UL>
- <LI><A HREF="http://www.sun.com/">SunOS 4.x</A> does not and
- almost certainly never will have one because it as at the
- very end of its development cycle for Sun. If you have kernel
- source should be easy to patch.
-</UL>
-<P>
-There is a
-<A HREF="http://www.apache.org/dist/httpd/contrib/patches/1.2/fin_wait_2.patch"
->patch available</A> for adding a timeout to the FIN_WAIT_2 state; it
-was originally intended for BSD/OS, but should be adaptable to most
-systems using BSD networking code. You need kernel source code to be
-able to use it. If you do adapt it to work for any other systems,
-please drop me a note at <A HREF="mailto:marc@apache.org">marc@apache.org</A>.
-<P>
-<H3>Compile without using <CODE>lingering_close()</CODE></H3>
-
-It is possible to compile Apache 1.2 without using the
-<CODE>lingering_close()</CODE> function. This will result in that
-section of code being similar to that which was in 1.1. If you do
-this, be aware that it can cause problems with PUTs, POSTs and
-persistent connections, especially if the client uses pipelining.
-That said, it is no worse than on 1.1, and we understand that keeping your
-server running is quite important.<P>
-
-To compile without the <CODE>lingering_close()</CODE> function, add
-<CODE>-DNO_LINGCLOSE</CODE> to the end of the
-<CODE>EXTRA_CFLAGS</CODE> line in your <CODE>Configuration</CODE> file,
-rerun <CODE>Configure</CODE> and rebuild the server.
-<P>
-<H3>Use <CODE>SO_LINGER</CODE> as an alternative to
-<CODE>lingering_close()</CODE></H3>
-
-On most systems, there is an option called <CODE>SO_LINGER</CODE> that
-can be set with <CODE>setsockopt(2)</CODE>. It does something very
-similar to <CODE>lingering_close()</CODE>, except that it is broken
-on many systems so that it causes far more problems than
-<CODE>lingering_close</CODE>. On some systems, it could possibly work
-better so it may be worth a try if you have no other alternatives. <P>
-
-To try it, add <CODE>-DUSE_SO_LINGER -DNO_LINGCLOSE</CODE> to the end of the
-<CODE>EXTRA_CFLAGS</CODE> line in your <CODE>Configuration</CODE>
-file, rerun <CODE>Configure</CODE> and rebuild the server. <P>
-
-<STRONG>NOTE:</STRONG> Attempting to use <CODE>SO_LINGER</CODE> and
-<CODE>lingering_close()</CODE> at the same time is very likely to do
-very bad things, so don't.<P>
-
-<H3>Increase the amount of memory used for storing connection state</H3>
-<DL>
-<DT>BSD based networking code:
-<DD>BSD stores network data, such as connection states,
-in something called an mbuf. When you get so many connections
-that the kernel does not have enough mbufs to put them all in, your
-kernel will likely crash. You can reduce the effects of the problem
-by increasing the number of mbufs that are available; this will not
-prevent the problem, it will just make the server go longer before
-crashing.<P>
-
-The exact way to increase them may depend on your OS; look
-for some reference to the number of "mbufs" or "mbuf clusters". On
-many systems, this can be done by adding the line
-<CODE>NMBCLUSTERS="n"</CODE>, where <CODE>n</CODE> is the number of
-mbuf clusters you want to your kernel config file and rebuilding your
-kernel.<P>
-</DL>
-
-<H3>Disable KeepAlive</H3>
-<P>If you are unable to do any of the above then you should, as a last
-resort, disable KeepAlive. Edit your httpd.conf and change "KeepAlive On"
-to "KeepAlive Off".
-
-<H2><LI>Feedback</H2>
-
-If you have any information to add to this page, please contact me at
-<A HREF="mailto:marc@apache.org">marc@apache.org</A>.<P>
-
-<H2><A NAME="appendix"><LI>Appendix</A></H2>
-<P>
-Below is a message from Roy Fielding, one of the authors of HTTP/1.1.
-
-<H3>Why the lingering close functionality is necessary with HTTP</H3>
-
-The need for a server to linger on a socket after a close is noted a couple
-times in the HTTP specs, but not explained. This explanation is based on
-discussions between myself, Henrik Frystyk, Robert S. Thau, Dave Raggett,
-and John C. Mallery in the hallways of MIT while I was at W3C.<P>
-
-If a server closes the input side of the connection while the client
-is sending data (or is planning to send data), then the server's TCP
-stack will signal an RST (reset) back to the client. Upon
-receipt of the RST, the client will flush its own incoming TCP buffer
-back to the un-ACKed packet indicated by the RST packet argument.
-If the server has sent a message, usually an error response, to the
-client just before the close, and the client receives the RST packet
-before its application code has read the error message from its incoming
-TCP buffer and before the server has received the ACK sent by the client
-upon receipt of that buffer, then the RST will flush the error message
-before the client application has a chance to see it. The result is
-that the client is left thinking that the connection failed for no
-apparent reason.<P>
-
-There are two conditions under which this is likely to occur:
-<OL>
-<LI>sending POST or PUT data without proper authorization
-<LI>sending multiple requests before each response (pipelining)
- and one of the middle requests resulting in an error or
- other break-the-connection result.
-</OL>
-<P>
-The solution in all cases is to send the response, close only the
-write half of the connection (what shutdown is supposed to do), and
-continue reading on the socket until it is either closed by the
-client (signifying it has finally read the response) or a timeout occurs.
-That is what the kernel is supposed to do if SO_LINGER is set.
-Unfortunately, SO_LINGER has no effect on some systems; on some other
-systems, it does not have its own timeout and thus the TCP memory
-segments just pile-up until the next reboot (planned or not).<P>
-
-Please note that simply removing the linger code will not solve the
-problem -- it only moves it to a different and much harder one to detect.
-</OL>
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Connections in FIN_WAIT_2 and Apache</title>
+ <link rev="made" href="mailto:marc@apache.org" />
+ </head>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+
+ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
+ vlink="#000080" alink="#FF0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="CENTER">Connections in the FIN_WAIT_2 state and
+ Apache</h1>
+
+ <ol>
+ <li>
+ <h2>What is the FIN_WAIT_2 state?</h2>
+ Starting with the Apache 1.2 betas, people are reporting
+ many more connections in the FIN_WAIT_2 state (as reported
+ by <code>netstat</code>) than they saw using older
+ versions. When the server closes a TCP connection, it sends
+ a packet with the FIN bit sent to the client, which then
+ responds with a packet with the ACK bit set. The client
+ then sends a packet with the FIN bit set to the server,
+ which responds with an ACK and the connection is closed.
+ The state that the connection is in during the period
+ between when the server gets the ACK from the client and
+ the server gets the FIN from the client is known as
+ FIN_WAIT_2. See the <a
+ href="ftp://ds.internic.net/rfc/rfc793.txt">TCP RFC</a> for
+ the technical details of the state transitions.
+
+ <p>The FIN_WAIT_2 state is somewhat unusual in that there
+ is no timeout defined in the standard for it. This means
+ that on many operating systems, a connection in the
+ FIN_WAIT_2 state will stay around until the system is
+ rebooted. If the system does not have a timeout and too
+ many FIN_WAIT_2 connections build up, it can fill up the
+ space allocated for storing information about the
+ connections and crash the kernel. The connections in
+ FIN_WAIT_2 do not tie up an httpd process.</p>
+ </li>
+
+ <li>
+ <h2>But why does it happen?</h2>
+ There are numerous reasons for it happening, some of them
+ may not yet be fully clear. What is known follows.
+
+ <h3>Buggy clients and persistent connections</h3>
+ Several clients have a bug which pops up when dealing with
+ <a href="../keepalive.html">persistent connections</a> (aka
+ keepalives). When the connection is idle and the server
+ closes the connection (based on the <a
+ href="../mod/core.html#keepalivetimeout">KeepAliveTimeout</a>),
+ the client is programmed so that the client does not send
+ back a FIN and ACK to the server. This means that the
+ connection stays in the FIN_WAIT_2 state until one of the
+ following happens:
+
+ <ul>
+ <li>The client opens a new connection to the same or a
+ different site, which causes it to fully close the older
+ connection on that socket.</li>
+
+ <li>The user exits the client, which on some (most?)
+ clients causes the OS to fully shutdown the
+ connection.</li>
+
+ <li>The FIN_WAIT_2 times out, on servers that have a
+ timeout for this state.</li>
+ </ul>
+
+ <p>If you are lucky, this means that the buggy client will
+ fully close the connection and release the resources on
+ your server. However, there are some cases where the socket
+ is never fully closed, such as a dialup client
+ disconnecting from their provider before closing the
+ client. In addition, a client might sit idle for days
+ without making another connection, and thus may hold its
+ end of the socket open for days even though it has no
+ further use for it. <strong>This is a bug in the browser or
+ in its operating system's TCP implementation.</strong></p>
+
+ <p>The clients on which this problem has been verified to
+ exist:</p>
+
+ <ul>
+ <li>Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE
+ i386)</li>
+
+ <li>Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE
+ i386)</li>
+
+ <li>Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m)</li>
+
+ <li>MSIE 3.01 on the Macintosh</li>
+
+ <li>MSIE 3.01 on Windows 95</li>
+ </ul>
+
+ <p>This does not appear to be a problem on:</p>
+
+ <ul>
+ <li>Mozilla/3.01 (Win95; I)</li>
+ </ul>
+
+ <p>It is expected that many other clients have the same
+ problem. What a client <strong>should do</strong> is
+ periodically check its open socket(s) to see if they have
+ been closed by the server, and close their side of the
+ connection if the server has closed. This check need only
+ occur once every few seconds, and may even be detected by a
+ OS signal on some systems (<em>e.g.</em>, Win95 and NT
+ clients have this capability, but they seem to be ignoring
+ it).</p>
+
+ <p>Apache <strong>cannot</strong> avoid these FIN_WAIT_2
+ states unless it disables persistent connections for the
+ buggy clients, just like we recommend doing for Navigator
+ 2.x clients due to other bugs. However, non-persistent
+ connections increase the total number of connections needed
+ per client and slow retrieval of an image-laden web page.
+ Since non-persistent connections have their own resource
+ consumptions and a short waiting period after each closure,
+ a busy server may need persistence in order to best serve
+ its clients.</p>
+
+ <p>As far as we know, the client-caused FIN_WAIT_2 problem
+ is present for all servers that support persistent
+ connections, including Apache 1.1.x and 1.2.</p>
+
+ <h3>A necessary bit of code introduced in 1.2</h3>
+ While the above bug is a problem, it is not the whole
+ problem. Some users have observed no FIN_WAIT_2 problems
+ with Apache 1.1.x, but with 1.2b enough connections build
+ up in the FIN_WAIT_2 state to crash their server. The most
+ likely source for additional FIN_WAIT_2 states is a
+ function called <code>lingering_close()</code> which was
+ added between 1.1 and 1.2. This function is necessary for
+ the proper handling of persistent connections and any
+ request which includes content in the message body
+ (<em>e.g.</em>, PUTs and POSTs). What it does is read any
+ data sent by the client for a certain time after the server
+ closes the connection. The exact reasons for doing this are
+ somewhat complicated, but involve what happens if the
+ client is making a request at the same time the server
+ sends a response and closes the connection. Without
+ lingering, the client might be forced to reset its TCP
+ input buffer before it has a chance to read the server's
+ response, and thus understand why the connection has
+ closed. See the <a href="#appendix">appendix</a> for more
+ details.
+
+ <p>The code in <code>lingering_close()</code> appears to
+ cause problems for a number of factors, including the
+ change in traffic patterns that it causes. The code has
+ been thoroughly reviewed and we are not aware of any bugs
+ in it. It is possible that there is some problem in the BSD
+ TCP stack, aside from the lack of a timeout for the
+ FIN_WAIT_2 state, exposed by the
+ <code>lingering_close</code> code that causes the observed
+ problems.</p>
+ </li>
+
+ <li>
+ What can I do about it? There are several possible
+ workarounds to the problem, some of which work better than
+ others.
+
+ <h3>Add a timeout for FIN_WAIT_2</h3>
+ The obvious workaround is to simply have a timeout for the
+ FIN_WAIT_2 state. This is not specified by the RFC, and
+ could be claimed to be a violation of the RFC, but it is
+ widely recognized as being necessary. The following systems
+ are known to have a timeout:
+
+ <ul>
+ <li><a href="http://www.freebsd.org/">FreeBSD</a>
+ versions starting at 2.0 or possibly earlier.</li>
+
+ <li><a href="http://www.netbsd.org/">NetBSD</a> version
+ 1.2(?)</li>
+
+ <li><a href="http://www.openbsd.org/">OpenBSD</a> all
+ versions(?)</li>
+
+ <li><a href="http://www.bsdi.com/">BSD/OS</a> 2.1, with
+ the <a
+ href="ftp://ftp.bsdi.com/bsdi/patches/patches-2.1/K210-027">
+ K210-027</a> patch installed.</li>
+
+ <li><a href="http://www.sun.com/">Solaris</a> as of
+ around version 2.2. The timeout can be tuned by using
+ <code>ndd</code> to modify
+ <code>tcp_fin_wait_2_flush_interval</code>, but the
+ default should be appropriate for most servers and
+ improper tuning can have negative impacts.</li>
+
+ <li><a href="http://www.linux.org/">Linux</a> 2.0.x and
+ earlier(?)</li>
+
+ <li><a href="http://www.hp.com/">HP-UX</a> 10.x defaults
+ to terminating connections in the FIN_WAIT_2 state after
+ the normal keepalive timeouts. This does not refer to the
+ persistent connection or HTTP keepalive timeouts, but the
+ <code>SO_LINGER</code> socket option which is enabled by
+ Apache. This parameter can be adjusted by using
+ <code>nettune</code> to modify parameters such as
+ <code>tcp_keepstart</code> and <code>tcp_keepstop</code>.
+ In later revisions, there is an explicit timer for
+ connections in FIN_WAIT_2 that can be modified; contact
+ HP support for details.</li>
+
+ <li><a href="http://www.sgi.com/">SGI IRIX</a> can be
+ patched to support a timeout. For IRIX 5.3, 6.2, and 6.3,
+ use patches 1654, 1703 and 1778 respectively. If you have
+ trouble locating these patches, please contact your SGI
+ support channel for help.</li>
+
+ <li><a href="http://www.ncr.com/">NCR's MP RAS Unix</a>
+ 2.xx and 3.xx both have FIN_WAIT_2 timeouts. In 2.xx it
+ is non-tunable at 600 seconds, while in 3.xx it defaults
+ to 600 seconds and is calculated based on the tunable
+ "max keep alive probes" (default of 8) multiplied by the
+ "keep alive interval" (default 75 seconds).</li>
+
+ <li><a href="http://www.sequent.com">Sequent's ptx/TCP/IP
+ for DYNIX/ptx</a> has had a FIN_WAIT_2 timeout since
+ around release 4.1 in mid-1994.</li>
+ </ul>
+
+ <p>The following systems are known to not have a
+ timeout:</p>
+
+ <ul>
+ <li><a href="http://www.sun.com/">SunOS 4.x</a> does not
+ and almost certainly never will have one because it as at
+ the very end of its development cycle for Sun. If you
+ have kernel source should be easy to patch.</li>
+ </ul>
+
+ <p>There is a <a
+ href="http://www.apache.org/dist/httpd/contrib/patches/1.2/fin_wait_2.patch">
+ patch available</a> for adding a timeout to the FIN_WAIT_2
+ state; it was originally intended for BSD/OS, but should be
+ adaptable to most systems using BSD networking code. You
+ need kernel source code to be able to use it. If you do
+ adapt it to work for any other systems, please drop me a
+ note at <a
+ href="mailto:marc@apache.org">marc@apache.org</a>.</p>
+
+ <h3>Compile without using
+ <code>lingering_close()</code></h3>
+ It is possible to compile Apache 1.2 without using the
+ <code>lingering_close()</code> function. This will result
+ in that section of code being similar to that which was in
+ 1.1. If you do this, be aware that it can cause problems
+ with PUTs, POSTs and persistent connections, especially if
+ the client uses pipelining. That said, it is no worse than
+ on 1.1, and we understand that keeping your server running
+ is quite important.
+
+ <p>To compile without the <code>lingering_close()</code>
+ function, add <code>-DNO_LINGCLOSE</code> to the end of the
+ <code>EXTRA_CFLAGS</code> line in your
+ <code>Configuration</code> file, rerun
+ <code>Configure</code> and rebuild the server.</p>
+
+ <h3>Use <code>SO_LINGER</code> as an alternative to
+ <code>lingering_close()</code></h3>
+ On most systems, there is an option called
+ <code>SO_LINGER</code> that can be set with
+ <code>setsockopt(2)</code>. It does something very similar
+ to <code>lingering_close()</code>, except that it is broken
+ on many systems so that it causes far more problems than
+ <code>lingering_close</code>. On some systems, it could
+ possibly work better so it may be worth a try if you have
+ no other alternatives.
+
+ <p>To try it, add <code>-DUSE_SO_LINGER
+ -DNO_LINGCLOSE</code> to the end of the
+ <code>EXTRA_CFLAGS</code> line in your
+ <code>Configuration</code> file, rerun
+ <code>Configure</code> and rebuild the server.</p>
+
+ <p><strong>NOTE:</strong> Attempting to use
+ <code>SO_LINGER</code> and <code>lingering_close()</code>
+ at the same time is very likely to do very bad things, so
+ don't.</p>
+
+ <h3>Increase the amount of memory used for storing
+ connection state</h3>
+
+ <dl>
+ <dt>BSD based networking code:</dt>
+
+ <dd>
+ BSD stores network data, such as connection states, in
+ something called an mbuf. When you get so many
+ connections that the kernel does not have enough mbufs
+ to put them all in, your kernel will likely crash. You
+ can reduce the effects of the problem by increasing the
+ number of mbufs that are available; this will not
+ prevent the problem, it will just make the server go
+ longer before crashing.
+
+ <p>The exact way to increase them may depend on your
+ OS; look for some reference to the number of "mbufs" or
+ "mbuf clusters". On many systems, this can be done by
+ adding the line <code>NMBCLUSTERS="n"</code>, where
+ <code>n</code> is the number of mbuf clusters you want
+ to your kernel config file and rebuilding your
+ kernel.</p>
+ </dd>
+ </dl>
+
+ <h3>Disable KeepAlive</h3>
+
+ <p>If you are unable to do any of the above then you
+ should, as a last resort, disable KeepAlive. Edit your
+ httpd.conf and change "KeepAlive On" to "KeepAlive
+ Off".</p>
+ </li>
+
+ <li>
+ Feedback If you have any information to add to this page,
+ please contact me at <a
+ href="mailto:marc@apache.org">marc@apache.org</a>.
+
+ <h2><a id="appendix" name="appendix"></a></h2>
+ </li>
+
+ <li>
+ Appendix
+
+ <p>Below is a message from Roy Fielding, one of the authors
+ of HTTP/1.1.</p>
+
+ <h3>Why the lingering close functionality is necessary with
+ HTTP</h3>
+ The need for a server to linger on a socket after a close
+ is noted a couple times in the HTTP specs, but not
+ explained. This explanation is based on discussions between
+ myself, Henrik Frystyk, Robert S. Thau, Dave Raggett, and
+ John C. Mallery in the hallways of MIT while I was at W3C.
+
+ <p>If a server closes the input side of the connection
+ while the client is sending data (or is planning to send
+ data), then the server's TCP stack will signal an RST
+ (reset) back to the client. Upon receipt of the RST, the
+ client will flush its own incoming TCP buffer back to the
+ un-ACKed packet indicated by the RST packet argument. If
+ the server has sent a message, usually an error response,
+ to the client just before the close, and the client
+ receives the RST packet before its application code has
+ read the error message from its incoming TCP buffer and
+ before the server has received the ACK sent by the client
+ upon receipt of that buffer, then the RST will flush the
+ error message before the client application has a chance to
+ see it. The result is that the client is left thinking that
+ the connection failed for no apparent reason.</p>
+
+ <p>There are two conditions under which this is likely to
+ occur:</p>
+
+ <ol>
+ <li>sending POST or PUT data without proper
+ authorization</li>
+
+ <li>sending multiple requests before each response
+ (pipelining) and one of the middle requests resulting in
+ an error or other break-the-connection result.</li>
+ </ol>
+
+ <p>The solution in all cases is to send the response, close
+ only the write half of the connection (what shutdown is
+ supposed to do), and continue reading on the socket until
+ it is either closed by the client (signifying it has
+ finally read the response) or a timeout occurs. That is
+ what the kernel is supposed to do if SO_LINGER is set.
+ Unfortunately, SO_LINGER has no effect on some systems; on
+ some other systems, it does not have its own timeout and
+ thus the TCP memory segments just pile-up until the next
+ reboot (planned or not).</p>
+
+ <p>Please note that simply removing the linger code will
+ not solve the problem -- it only moves it to a different
+ and much harder one to detect.</p>
+ </li>
+ </ol>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<HR>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<H3 ALIGN="CENTER">
- Apache HTTP Server Version 2.0
-</H3>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title></title>
+ </head>
+
+ <body>
+ <hr />
+
+ <h3 align="CENTER">Apache HTTP Server Version 2.0</h3>
+ <a href="./"><img src="../images/index.gif" alt="Index" /></a>
+ <a href="../"><img src="../images/home.gif" alt="Home" /></a>
+ </body>
+</html>
-<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A>
-<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A>
-<DIV ALIGN="CENTER">
- <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]">
- <H3>
- Apache HTTP Server Version 2.0
- </H3>
-</DIV>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title></title>
+ </head>
+
+ <body>
+ <div align="CENTER">
+ <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" />
+
+ <h3>Apache HTTP Server Version 2.0</h3>
+ </div>
+ </body>
+</html>
+
-<!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="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="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="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>
- </DL>
-
- <!--#include virtual="footer.html" -->
- </BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache Miscellaneous Documentation</title>
+ </head>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+
+ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
+ vlink="#000080" alink="#FF0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="CENTER">Apache Miscellaneous Documentation</h1>
+
+ <p>Below is a list of additional documentation pages that apply
+ to the Apache web server development project.</p>
+
+ <dl>
+ <dt><a href="custom_errordocs.html">How to use XSSI and
+ Negotiation for custom ErrorDocuments</a></dt>
+
+ <dd>Describes a solution which uses XSSI and negotiation to
+ custom-tailor the Apache ErrorDocuments to taste, adding the
+ advantage of returning internationalized versions of the
+ error messages depending on the client's language
+ preferences.</dd>
+
+ <dt><a href="descriptors.html">File Descriptor use in
+ Apache</a></dt>
+
+ <dd>Describes how Apache uses file descriptors and talks
+ about various limits imposed on the number of descriptors
+ available by various operating systems.</dd>
+
+ <dt><a
+ href="fin_wait_2.html"><samp>FIN_WAIT_2</samp></a></dt>
+
+ <dd>A description of the causes of Apache processes going
+ into the <samp>FIN_WAIT_2</samp> state, and what you can do
+ about it.</dd>
+
+ <dt><a href="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="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>
+ </dl>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache HTTP Server Project</TITLE>
-</HEAD>
-
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
-<H1 ALIGN="CENTER">Known Problems in Clients</H1>
-
-<P>Over time the Apache Group has discovered or been notified of problems
-with various clients which we have had to work around, or explain.
-This document describes these problems and the workarounds available.
-It's not arranged in any particular order. Some familiarity with the
-standards is assumed, but not necessary.
-
-<P>For brevity, <EM>Navigator</EM> will refer to Netscape's Navigator
-product (which in later versions was renamed "Communicator" and
-various other names), and <EM>MSIE</EM> will refer to Microsoft's
-Internet Explorer product. All trademarks and copyrights belong to
-their respective companies. We welcome input from the various client
-authors to correct inconsistencies in this paper, or to provide us with
-exact version numbers where things are broken/fixed.
-
-<P>For reference,
-<A HREF="ftp://ds.internic.net/rfc/rfc1945.txt">RFC1945</A>
-defines HTTP/1.0, and
-<A HREF="ftp://ds.internic.net/rfc/rfc2068.txt">RFC2068</A>
-defines HTTP/1.1. Apache as of version 1.2 is an HTTP/1.1 server (with an
-optional HTTP/1.0 proxy).
-
-<P>Various of these workarounds are triggered by environment variables.
-The admin typically controls which are set, and for which clients, by using
-<A HREF="../mod/mod_browser.html">mod_browser</A>. Unless otherwise
-noted all of these workarounds exist in versions 1.2 and later.
-
-<H3><A NAME="trailing-crlf">Trailing CRLF on POSTs</A></H3>
-
-<P>This is a legacy issue. The CERN webserver required <CODE>POST</CODE>
-data to have an extra <CODE>CRLF</CODE> following it. Thus many
-clients send an extra <CODE>CRLF</CODE> that
-is not included in the <CODE>Content-Length</CODE> of the request.
-Apache works around this problem by eating any empty lines which
-appear before a request.
-
-<H3><A NAME="broken-keepalive">Broken keepalive</A></H3>
-
-<P>Various clients have had broken implementations of <EM>keepalive</EM>
-(persistent connections). In particular the Windows versions of
-Navigator 2.0 get very confused when the server times out an
-idle connection. The workaround is present in the default config files:
-<BLOCKQUOTE><CODE>
-BrowserMatch Mozilla/2 nokeepalive
-</CODE></BLOCKQUOTE>
-Note that this matches some earlier versions of MSIE, which began the
-practice of calling themselves <EM>Mozilla</EM> in their user-agent
-strings just like Navigator.
-
-<P>MSIE 4.0b2, which claims to support HTTP/1.1, does not properly
-support keepalive when it is used on 301 or 302 (redirect)
-responses. Unfortunately Apache's <CODE>nokeepalive</CODE> code
-prior to 1.2.2 would not work with HTTP/1.1 clients. You must apply
-<A
-HREF="http://www.apache.org/dist/httpd/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch"
->this patch</A> to version 1.2.1. Then add this to your config:
-<BLOCKQUOTE><CODE>
-BrowserMatch "MSIE 4\.0b2;" nokeepalive
-</CODE></BLOCKQUOTE>
-
-<H3><A NAME="force-response-1.0">Incorrect interpretation of
-<CODE>HTTP/1.1</CODE> in response</A></H3>
-
-<P>To quote from section 3.1 of RFC1945:
-<BLOCKQUOTE>
-HTTP uses a "<MAJOR>.<MINOR>" numbering scheme to indicate versions
-of the protocol. The protocol versioning policy is intended to allow
-the sender to indicate the format of a message and its capacity for
-understanding further HTTP communication, rather than the features
-obtained via that communication.
-</BLOCKQUOTE>
-Since Apache is an HTTP/1.1 server, it indicates so as part of its
-response. Many client authors mistakenly treat this part of the response
-as an indication of the protocol that the response is in, and then refuse
-to accept the response.
-
-<P>The first major indication of this problem was with AOL's proxy servers.
-When Apache 1.2 went into beta it was the first wide-spread HTTP/1.1
-server. After some discussion, AOL fixed their proxies. In
-anticipation of similar problems, the <CODE>force-response-1.0</CODE>
-environment variable was added to Apache. When present Apache will
-indicate "HTTP/1.0" in response to an HTTP/1.0 client,
-but will not in any other way change the response.
-
-<P>The pre-1.1 Java Development Kit (JDK) that is used in many clients
-(including Navigator 3.x and MSIE 3.x) exhibits this problem. As do some
-of the early pre-releases of the 1.1 JDK. We think it is fixed in the
-1.1 JDK release. In any event the workaround:
-<BLOCKQUOTE><CODE>
-BrowserMatch Java/1.0 force-response-1.0 <BR>
-BrowserMatch JDK/1.0 force-response-1.0
-</CODE></BLOCKQUOTE>
-
-<P>RealPlayer 4.0 from Progressive Networks also exhibits this problem.
-However they have fixed it in version 4.01 of the player, but version
-4.01 uses the same <CODE>User-Agent</CODE> as version 4.0. The
-workaround is still:
-<BLOCKQUOTE><CODE>
-BrowserMatch "RealPlayer 4.0" force-response-1.0
-</CODE></BLOCKQUOTE>
-
-<H3><A NAME="msie4.0b2">Requests use HTTP/1.1 but responses must be
-in HTTP/1.0</A></H3>
-
-<P>MSIE 4.0b2 has this problem. Its Java VM makes requests in HTTP/1.1
-format but the responses must be in HTTP/1.0 format (in particular, it
-does not understand <EM>chunked</EM> responses). The workaround
-is to fool Apache into believing the request came in HTTP/1.0 format.
-<BLOCKQUOTE><CODE>
-BrowserMatch "MSIE 4\.0b2;" downgrade-1.0 force-response-1.0
-</CODE></BLOCKQUOTE>
-This workaround is available in 1.2.2, and in a
-<A
-HREF="http://www.apache.org/dist/httpd/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch"
->patch</A> against 1.2.1.
-
-<H3><A NAME="257th-byte">Boundary problems with header parsing</A></H3>
-
-<P>All versions of Navigator from 2.0 through 4.0b2 (and possibly later)
-have a problem if the trailing CRLF of the response header starts at
-offset 256, 257 or 258 of the response. A BrowserMatch for this would
-match on nearly every hit, so the workaround is enabled automatically
-on all responses. The workaround implemented detects when this condition would
-occur in a response and adds extra padding to the header to push the
-trailing CRLF past offset 258 of the response.
-
-<H3><A NAME="boundary-string">Multipart responses and Quoted Boundary
-Strings</A></H3>
-
-<P>On multipart responses some clients will not accept quotes (")
-around the boundary string. The MIME standard recommends that
-such quotes be used. But the clients were probably written based
-on one of the examples in RFC2068, which does not include quotes.
-Apache does not include quotes on its boundary strings to workaround
-this problem.
-
-<H3><A NAME="byterange-requests">Byterange requests</A></H3>
-
-<P>A byterange request is used when the client wishes to retrieve a
-portion of an object, not necessarily the entire object. There
-was a very old draft which included these byteranges in the URL.
-Old clients such as Navigator 2.0b1 and MSIE 3.0 for the MAC
-exhibit this behaviour, and
-it will appear in the servers' access logs as (failed) attempts to
-retrieve a URL with a trailing ";xxx-yyy". Apache does not attempt
-to implement this at all.
-
-<P>A subsequent draft of this standard defines a header
-<CODE>Request-Range</CODE>, and a response type
-<CODE>multipart/x-byteranges</CODE>. The HTTP/1.1 standard includes
-this draft with a few fixes, and it defines the header
-<CODE>Range</CODE> and type <CODE>multipart/byteranges</CODE>.
-
-<P>Navigator (versions 2 and 3) sends both <CODE>Range</CODE> and
-<CODE>Request-Range</CODE> headers (with the same value), but does not
-accept a <CODE>multipart/byteranges</CODE> response. The response must
-be <CODE>multipart/x-byteranges</CODE>. As a workaround, if Apache
-receives a <CODE>Request-Range</CODE> header it considers it "higher
-priority" than a <CODE>Range</CODE> header and in response uses
-<CODE>multipart/x-byteranges</CODE>.
-
-<P>The Adobe Acrobat Reader plugin makes extensive use of byteranges and
-prior to version 3.01 supports only the <CODE>multipart/x-byterange</CODE>
-response. Unfortunately there is no clue that it is the plugin
-making the request. If the plugin is used with Navigator, the above
-workaround works fine. But if the plugin is used with MSIE 3 (on
-Windows) the workaround won't work because MSIE 3 doesn't give the
-<CODE>Range-Request</CODE> clue that Navigator does. To workaround this,
-Apache special cases "MSIE 3" in the <CODE>User-Agent</CODE> and serves
-<CODE>multipart/x-byteranges</CODE>. Note that the necessity for this
-with MSIE 3 is actually due to the Acrobat plugin, not due to the browser.
-
-<P>Netscape Communicator appears to not issue the non-standard
-<CODE>Request-Range</CODE> header. When an Acrobat plugin prior to
-version 3.01 is used with it, it will not properly understand byteranges.
-The user must upgrade their Acrobat reader to 3.01.
-
-<H3><A NAME="cookie-merge"><CODE>Set-Cookie</CODE> header is
-unmergeable</A></H3>
-
-<P>The HTTP specifications say that it is legal to merge headers with
-duplicate names into one (separated by commas). Some browsers
-that support Cookies don't like merged headers and prefer that each
-<CODE>Set-Cookie</CODE> header is sent separately. When parsing the
-headers returned by a CGI, Apache will explicitly avoid merging any
-<CODE>Set-Cookie</CODE> headers.
-
-<H3><A NAME="gif89-expires"><CODE>Expires</CODE> headers and GIF89A
-animations</A></H3>
-
-<P>Navigator versions 2 through 4 will erroneously re-request
-GIF89A animations on each loop of the animation if the first
-response included an <CODE>Expires</CODE> header. This happens
-regardless of how far in the future the expiry time is set. There
-is no workaround supplied with Apache, however there are hacks for <A
-HREF="http://www.arctic.org/~dgaudet/patches/apache-1.2-gif89-expires-hack.patch">1.2</A>
-and for <A
-HREF="http://www.arctic.org/~dgaudet/patches/apache-1.3-gif89-expires-hack.patch">1.3</A>.
-
-<H3><A NAME="no-content-length"><CODE>POST</CODE> without
-<CODE>Content-Length</CODE></A></H3>
-
-<P>In certain situations Navigator 3.01 through 3.03 appear to incorrectly
-issue a POST without the request body. There is no
-known workaround. It has been fixed in Navigator 3.04, Netscapes
-provides some
-<A HREF="http://help.netscape.com/kb/client/971014-42.html">information</A>.
-There's also
-<A HREF="http://www.arctic.org/~dgaudet/apache/no-content-length/">
-some information</A> about the actual problem.
-
-<H3><A NAME="jdk-12-bugs">JDK 1.2 betas lose parts of responses.</A></H3>
-
-<P>The http client in the JDK1.2beta2 and beta3 will throw away the first part of
-the response body when both the headers and the first part of the body are sent
-in the same network packet AND keep-alive's are being used. If either condition
-is not met then it works fine.
-
-<P>See also Bug-ID's 4124329 and 4125538 at the java developer connection.
-
-<P>If you are seeing this bug yourself, you can add the following BrowserMatch
-directive to work around it:
-
-<BLOCKQUOTE><CODE>
-BrowserMatch "Java1\.2beta[23]" nokeepalive
-</CODE></BLOCKQUOTE>
-
-<P>We don't advocate this though since bending over backwards for beta software
-is usually not a good idea; ideally it gets fixed, new betas or a final release
-comes out, and no one uses the broken old software anymore. In theory.
-
-<H3><A NAME="content-type-persistence"><CODE>Content-Type</CODE> change
-is not noticed after reload</A></H3>
-
-<P>Navigator (all versions?) will cache the <CODE>content-type</CODE>
-for an object "forever". Using reload or shift-reload will not cause
-Navigator to notice a <CODE>content-type</CODE> change. The only
-work-around is for the user to flush their caches (memory and disk). By
-way of an example, some folks may be using an old <CODE>mime.types</CODE>
-file which does not map <CODE>.htm</CODE> to <CODE>text/html</CODE>,
-in this case Apache will default to sending <CODE>text/plain</CODE>.
-If the user requests the page and it is served as <CODE>text/plain</CODE>.
-After the admin fixes the server, the user will have to flush their caches
-before the object will be shown with the correct <CODE>text/html</CODE>
-type.
-
-<h3><a name="msie-cookie-y2k">MSIE Cookie problem with expiry date in
-the year 2000</a></h3>
-
-<p>MSIE versions 3.00 and 3.02 (without the Y2K patch) do not handle
-cookie expiry dates in the year 2000 properly. Years after 2000 and
-before 2000 work fine. This is fixed in IE4.01 service pack 1, and in
-the Y2K patch for IE3.02. Users should avoid using expiry dates in the
-year 2000.
-
-<h3><a name="lynx-negotiate-trans">Lynx incorrectly asking for transparent
-content negotiation</a></h3>
-
-<p>The Lynx browser versions 2.7 and 2.8 send a "negotiate: trans" header
-in their requests, which is an indication the browser supports transparent
-content negotiation (TCN). However the browser does not support TCN.
-As of version 1.3.4, Apache supports TCN, and this causes problems with
-these versions of Lynx. As a workaround future versions of Apache will
-ignore this header when sent by the Lynx client.
-
-<h3><a name="ie40-vary">MSIE 4.0 mishandles Vary response header</a></h3>
-
-<p>MSIE 4.0 does not handle a Vary header properly. The Vary header is
-generated by mod_rewrite in apache 1.3. The result is an error from MSIE
-saying it cannot download the requested file. There are more details
-in <a href="http://bugs.apache.org/index/full/4118">PR#4118</a>.
-</P>
-<P>
-A workaround is to add the following to your server's configuration
-files:
-</P>
-<PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache HTTP Server Project</title>
+ </head>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+
+ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
+ vlink="#000080" alink="#FF0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="CENTER">Known Problems in Clients</h1>
+
+ <p>Over time the Apache Group has discovered or been notified
+ of problems with various clients which we have had to work
+ around, or explain. This document describes these problems and
+ the workarounds available. It's not arranged in any particular
+ order. Some familiarity with the standards is assumed, but not
+ necessary.</p>
+
+ <p>For brevity, <em>Navigator</em> will refer to Netscape's
+ Navigator product (which in later versions was renamed
+ "Communicator" and various other names), and <em>MSIE</em> will
+ refer to Microsoft's Internet Explorer product. All trademarks
+ and copyrights belong to their respective companies. We welcome
+ input from the various client authors to correct
+ inconsistencies in this paper, or to provide us with exact
+ version numbers where things are broken/fixed.</p>
+
+ <p>For reference, <a
+ href="ftp://ds.internic.net/rfc/rfc1945.txt">RFC1945</a>
+ defines HTTP/1.0, and <a
+ href="ftp://ds.internic.net/rfc/rfc2068.txt">RFC2068</a>
+ defines HTTP/1.1. Apache as of version 1.2 is an HTTP/1.1
+ server (with an optional HTTP/1.0 proxy).</p>
+
+ <p>Various of these workarounds are triggered by environment
+ variables. The admin typically controls which are set, and for
+ which clients, by using <a
+ href="../mod/mod_browser.html">mod_browser</a>. Unless
+ otherwise noted all of these workarounds exist in versions 1.2
+ and later.</p>
+
+ <h3><a id="trailing-crlf" name="trailing-crlf">Trailing CRLF on
+ POSTs</a></h3>
+
+ <p>This is a legacy issue. The CERN webserver required
+ <code>POST</code> data to have an extra <code>CRLF</code>
+ following it. Thus many clients send an extra <code>CRLF</code>
+ that is not included in the <code>Content-Length</code> of the
+ request. Apache works around this problem by eating any empty
+ lines which appear before a request.</p>
+
+ <h3><a id="broken-keepalive" name="broken-keepalive">Broken
+ keepalive</a></h3>
+
+ <p>Various clients have had broken implementations of
+ <em>keepalive</em> (persistent connections). In particular the
+ Windows versions of Navigator 2.0 get very confused when the
+ server times out an idle connection. The workaround is present
+ in the default config files:</p>
+
+ <blockquote>
+ <code>BrowserMatch Mozilla/2 nokeepalive</code>
+ </blockquote>
+ Note that this matches some earlier versions of MSIE, which
+ began the practice of calling themselves <em>Mozilla</em> in
+ their user-agent strings just like Navigator.
+
+ <p>MSIE 4.0b2, which claims to support HTTP/1.1, does not
+ properly support keepalive when it is used on 301 or 302
+ (redirect) responses. Unfortunately Apache's
+ <code>nokeepalive</code> code prior to 1.2.2 would not work
+ with HTTP/1.1 clients. You must apply <a
+ href="http://www.apache.org/dist/httpd/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch">
+ this patch</a> to version 1.2.1. Then add this to your
+ config:</p>
+
+ <blockquote>
+ <code>BrowserMatch "MSIE 4\.0b2;" nokeepalive</code>
+ </blockquote>
+
+ <h3><a id="force-response-1.0"
+ name="force-response-1.0">Incorrect interpretation of
+ <code>HTTP/1.1</code> in response</a></h3>
+
+ <p>To quote from section 3.1 of RFC1945:</p>
+
+ <blockquote>
+ HTTP uses a "<MAJOR>.<MINOR>" numbering scheme to
+ indicate versions of the protocol. The protocol versioning
+ policy is intended to allow the sender to indicate the format
+ of a message and its capacity for understanding further HTTP
+ communication, rather than the features obtained via that
+ communication.
+ </blockquote>
+ Since Apache is an HTTP/1.1 server, it indicates so as part of
+ its response. Many client authors mistakenly treat this part of
+ the response as an indication of the protocol that the response
+ is in, and then refuse to accept the response.
+
+ <p>The first major indication of this problem was with AOL's
+ proxy servers. When Apache 1.2 went into beta it was the first
+ wide-spread HTTP/1.1 server. After some discussion, AOL fixed
+ their proxies. In anticipation of similar problems, the
+ <code>force-response-1.0</code> environment variable was added
+ to Apache. When present Apache will indicate "HTTP/1.0" in
+ response to an HTTP/1.0 client, but will not in any other way
+ change the response.</p>
+
+ <p>The pre-1.1 Java Development Kit (JDK) that is used in many
+ clients (including Navigator 3.x and MSIE 3.x) exhibits this
+ problem. As do some of the early pre-releases of the 1.1 JDK.
+ We think it is fixed in the 1.1 JDK release. In any event the
+ workaround:</p>
+
+ <blockquote>
+ <code>BrowserMatch Java/1.0 force-response-1.0<br />
+ BrowserMatch JDK/1.0 force-response-1.0</code>
+ </blockquote>
+
+ <p>RealPlayer 4.0 from Progressive Networks also exhibits this
+ problem. However they have fixed it in version 4.01 of the
+ player, but version 4.01 uses the same <code>User-Agent</code>
+ as version 4.0. The workaround is still:</p>
+
+ <blockquote>
+ <code>BrowserMatch "RealPlayer 4.0" force-response-1.0</code>
+ </blockquote>
+
+ <h3><a id="msie4.0b2" name="msie4.0b2">Requests use HTTP/1.1
+ but responses must be in HTTP/1.0</a></h3>
+
+ <p>MSIE 4.0b2 has this problem. Its Java VM makes requests in
+ HTTP/1.1 format but the responses must be in HTTP/1.0 format
+ (in particular, it does not understand <em>chunked</em>
+ responses). The workaround is to fool Apache into believing the
+ request came in HTTP/1.0 format.</p>
+
+ <blockquote>
+ <code>BrowserMatch "MSIE 4\.0b2;" downgrade-1.0
+ force-response-1.0</code>
+ </blockquote>
+ This workaround is available in 1.2.2, and in a <a
+ href="http://www.apache.org/dist/httpd/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch">
+ patch</a> against 1.2.1.
+
+ <h3><a id="257th-byte" name="257th-byte">Boundary problems with
+ header parsing</a></h3>
+
+ <p>All versions of Navigator from 2.0 through 4.0b2 (and
+ possibly later) have a problem if the trailing CRLF of the
+ response header starts at offset 256, 257 or 258 of the
+ response. A BrowserMatch for this would match on nearly every
+ hit, so the workaround is enabled automatically on all
+ responses. The workaround implemented detects when this
+ condition would occur in a response and adds extra padding to
+ the header to push the trailing CRLF past offset 258 of the
+ response.</p>
+
+ <h3><a id="boundary-string" name="boundary-string">Multipart
+ responses and Quoted Boundary Strings</a></h3>
+
+ <p>On multipart responses some clients will not accept quotes
+ (") around the boundary string. The MIME standard recommends
+ that such quotes be used. But the clients were probably written
+ based on one of the examples in RFC2068, which does not include
+ quotes. Apache does not include quotes on its boundary strings
+ to workaround this problem.</p>
+
+ <h3><a id="byterange-requests"
+ name="byterange-requests">Byterange requests</a></h3>
+
+ <p>A byterange request is used when the client wishes to
+ retrieve a portion of an object, not necessarily the entire
+ object. There was a very old draft which included these
+ byteranges in the URL. Old clients such as Navigator 2.0b1 and
+ MSIE 3.0 for the MAC exhibit this 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>
+
+ <p>A subsequent draft of this standard defines a header
+ <code>Request-Range</code>, and a response type
+ <code>multipart/x-byteranges</code>. The HTTP/1.1 standard
+ includes this draft with a few fixes, and it defines the header
+ <code>Range</code> and type
+ <code>multipart/byteranges</code>.</p>
+
+ <p>Navigator (versions 2 and 3) sends both <code>Range</code>
+ and <code>Request-Range</code> headers (with the same value),
+ but does not accept a <code>multipart/byteranges</code>
+ response. The response must be
+ <code>multipart/x-byteranges</code>. As a workaround, if Apache
+ receives a <code>Request-Range</code> header it considers it
+ "higher priority" than a <code>Range</code> header and in
+ response uses <code>multipart/x-byteranges</code>.</p>
+
+ <p>The Adobe Acrobat Reader plugin makes extensive use of
+ byteranges and prior to version 3.01 supports only the
+ <code>multipart/x-byterange</code> response. Unfortunately
+ there is no clue that it is the plugin making the request. If
+ the plugin is used with Navigator, the above workaround works
+ fine. But if the plugin is used with MSIE 3 (on Windows) the
+ workaround won't work because MSIE 3 doesn't give the
+ <code>Range-Request</code> clue that Navigator does. To
+ workaround this, Apache special cases "MSIE 3" in the
+ <code>User-Agent</code> and serves
+ <code>multipart/x-byteranges</code>. Note that the necessity
+ for this with MSIE 3 is actually due to the Acrobat plugin, not
+ due to the browser.</p>
+
+ <p>Netscape Communicator appears to not issue the non-standard
+ <code>Request-Range</code> header. When an Acrobat plugin prior
+ to version 3.01 is used with it, it will not properly
+ understand byteranges. The user must upgrade their Acrobat
+ reader to 3.01.</p>
+
+ <h3><a id="cookie-merge"
+ name="cookie-merge"><code>Set-Cookie</code> header is
+ unmergeable</a></h3>
+
+ <p>The HTTP specifications say that it is legal to merge
+ headers with duplicate names into one (separated by commas).
+ Some browsers that support Cookies don't like merged headers
+ and prefer that each <code>Set-Cookie</code> header is sent
+ separately. When parsing the headers returned by a CGI, Apache
+ will explicitly avoid merging any <code>Set-Cookie</code>
+ headers.</p>
+
+ <h3><a id="gif89-expires"
+ name="gif89-expires"><code>Expires</code> headers and GIF89A
+ animations</a></h3>
+
+ <p>Navigator versions 2 through 4 will erroneously re-request
+ GIF89A animations on each loop of the animation if the first
+ response included an <code>Expires</code> header. This happens
+ regardless of how far in the future the expiry time is set.
+ There is no workaround supplied with Apache, however there are
+ hacks for <a
+ href="http://www.arctic.org/~dgaudet/patches/apache-1.2-gif89-expires-hack.patch">
+ 1.2</a> and for <a
+ href="http://www.arctic.org/~dgaudet/patches/apache-1.3-gif89-expires-hack.patch">
+ 1.3</a>.</p>
+
+ <h3><a id="no-content-length"
+ name="no-content-length"><code>POST</code> without
+ <code>Content-Length</code></a></h3>
+
+ <p>In certain situations Navigator 3.01 through 3.03 appear to
+ incorrectly issue a POST without the request body. There is no
+ known workaround. It has been fixed in Navigator 3.04,
+ Netscapes provides some <a
+ href="http://help.netscape.com/kb/client/971014-42.html">information</a>.
+ There's also <a
+ href="http://www.arctic.org/~dgaudet/apache/no-content-length/">
+ some information</a> about the actual problem.</p>
+
+ <h3><a id="jdk-12-bugs" name="jdk-12-bugs">JDK 1.2 betas lose
+ parts of responses.</a></h3>
+
+ <p>The http client in the JDK1.2beta2 and beta3 will throw away
+ the first part of the response body when both the headers and
+ the first part of the body are sent in the same network packet
+ AND keep-alive's are being used. If either condition is not met
+ then it works fine.</p>
+
+ <p>See also Bug-ID's 4124329 and 4125538 at the java developer
+ connection.</p>
+
+ <p>If you are seeing this bug yourself, you can add the
+ following BrowserMatch directive to work around it:</p>
+
+ <blockquote>
+ <code>BrowserMatch "Java1\.2beta[23]" nokeepalive</code>
+ </blockquote>
+
+ <p>We don't advocate this though since bending over backwards
+ for beta software is usually not a good idea; ideally it gets
+ fixed, new betas or a final release comes out, and no one uses
+ the broken old software anymore. In theory.</p>
+
+ <h3><a id="content-type-persistence"
+ name="content-type-persistence"><code>Content-Type</code>
+ change is not noticed after reload</a></h3>
+
+ <p>Navigator (all versions?) will cache the
+ <code>content-type</code> for an object "forever". Using reload
+ or shift-reload will not cause Navigator to notice a
+ <code>content-type</code> change. The only work-around is for
+ the user to flush their caches (memory and disk). By way of an
+ example, some folks may be using an old <code>mime.types</code>
+ file which does not map <code>.htm</code> to
+ <code>text/html</code>, in this case Apache will default to
+ sending <code>text/plain</code>. If the user requests the page
+ and it is served as <code>text/plain</code>. After the admin
+ fixes the server, the user will have to flush their caches
+ before the object will be shown with the correct
+ <code>text/html</code> type.</p>
+
+ <h3><a id="msie-cookie-y2k" name="msie-cookie-y2k">MSIE Cookie
+ problem with expiry date in the year 2000</a></h3>
+
+ <p>MSIE versions 3.00 and 3.02 (without the Y2K patch) do not
+ handle cookie expiry dates in the year 2000 properly. Years
+ after 2000 and before 2000 work fine. This is fixed in IE4.01
+ service pack 1, and in the Y2K patch for IE3.02. Users should
+ avoid using expiry dates in the year 2000.</p>
+
+ <h3><a id="lynx-negotiate-trans"
+ name="lynx-negotiate-trans">Lynx incorrectly asking for
+ transparent content negotiation</a></h3>
+
+ <p>The Lynx browser versions 2.7 and 2.8 send a "negotiate:
+ trans" header in their requests, which is an indication the
+ browser supports transparent content negotiation (TCN). However
+ the browser does not support TCN. As of version 1.3.4, Apache
+ supports TCN, and this causes problems with these versions of
+ Lynx. As a workaround future versions of Apache will ignore
+ this header when sent by the Lynx client.</p>
+
+ <h3><a id="ie40-vary" name="ie40-vary">MSIE 4.0 mishandles Vary
+ response header</a></h3>
+
+ <p>MSIE 4.0 does not handle a Vary header properly. The Vary
+ header is generated by mod_rewrite in apache 1.3. The result is
+ an error from MSIE saying it cannot download the requested
+ file. There are more details in <a
+ href="http://bugs.apache.org/index/full/4118">PR#4118</a>.</p>
+
+ <p>A workaround is to add the following to your server's
+ configuration files:</p>
+<pre>
BrowserMatch "MSIE 4\.0" force-no-vary
-</PRE>
-<P>
-(This workaround is only available with releases <STRONG>after</STRONG>
-1.3.6 of the Apache Web server.)
-</P>
+</pre>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+ <p>(This workaround is only available with releases
+ <strong>after</strong> 1.3.6 of the Apache Web server.)</p>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
- <TITLE>Apache Performance Notes</TITLE>
-</HEAD>
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
-
-<blockquote><strong>Warning:</strong>
-This document has not been updated to take into account changes
-made in the 2.0 version of the Apache HTTP Server. Some of the
-information may still be relevant, but please use it
-with care.
-</blockquote>
-
-<H1 align="center">Apache Performance Notes</H1>
-
-<P>Author: Dean Gaudet
-
-<ul>
-<li><a href="#introduction">Introduction</a></li>
-<li><a href="#hardware">Hardware and Operating System Issues</a></li>
-<li><a href="#runtime">Run-Time Configuration Issues</a></li>
-<li><a href="#compiletime">Compile-Time Configuration Issues</a></li>
-<li>Appendixes
- <ul>
- <li><a href="#trace">Detailed Analysis of a Trace</a></li>
- <li><a href="#patches">Patches Available</a></li>
- <li><a href="#preforking">The Pre-Forking Model</a></li>
- </ul></li>
-</ul>
-
-<hr>
-
-<table border="1">
-<tr><td valign="top">
-<strong>Related Modules</strong><br><br>
-
-<a href="../mod/mod_dir.html">mod_dir</a><br>
-<a href="../mod/mpm_common.html">Multi-Processing module</a><br>
-<a href="../mod/mod_status.html">mod_status</a><br>
-
-</td><td valign="top">
-<strong>Related Directives</strong><br><br>
-
-<a href="../mod/core.html#allowoverride">AllowOverride</a><br>
-<a href="../mod/mod_dir.html#directoryindex">DirectoryIndex</a><br>
-<a href="../mod/core.html#hostnamelookups">HostNameLookups</a><br>
-<a href="../mod/core.html#keepalivetimeout">KeepAliveTimeout</a><br>
-<a href="../mod/prefork.html#maxspareservers">MaxSpareServers</a><br>
-<a href="../mod/prefork.html#mixspareservers">MinSpareServers</a><br>
-<a href="../mod/core.html#options">Options</a> (FollowSymLinks and
-FollowIfOwnerMatch)<br>
-<a href="../mod/mpm_common.html#startservers">StartServers</a><br>
-
-</td></tr></table>
-
-<H3><a name="introduction">Introduction</A></H3>
-<P>Apache is a general webserver, which is designed to be correct first, and
-fast second. Even so, its performance is quite satisfactory. Most
-sites have less than 10Mbits of outgoing bandwidth, which Apache can
-fill using only a low end Pentium-based webserver. In practice sites
-with more bandwidth require more than one machine to fill the bandwidth
-due to other constraints (such as CGI or database transaction overhead).
-For these reasons the development focus has been mostly on correctness
-and configurability.
-
-<P>Unfortunately many folks overlook these facts and cite raw performance
-numbers as if they are some indication of the quality of a web server
-product. There is a bare minimum performance that is acceptable, beyond
-that extra speed only caters to a much smaller segment of the market.
-But in order to avoid this hurdle to the acceptance of Apache in some
-markets, effort was put into Apache 1.3 to bring performance up to a
-point where the difference with other high-end webservers is minimal.
-
-<P>Finally there are the folks who just plain want to see how fast something
-can go. The author falls into this category. The rest of this document
-is dedicated to these folks who want to squeeze every last bit of
-performance out of Apache's current model, and want to understand why
-it does some things which slow it down.
-
-<P>Note that this is tailored towards Apache 1.3 on Unix. Some of it applies
-to Apache on NT. Apache on NT has not been tuned for performance yet;
-in fact it probably performs very poorly because NT performance requires
-a different programming model.
-
-<hr>
-
-<H3><a name="hardware">Hardware and Operating System Issues</a></H3>
-
-<P>The single biggest hardware issue affecting webserver performance
-is RAM. A webserver should never ever have to swap, swapping increases
-the latency of each request beyond a point that users consider "fast
-enough". This causes users to hit stop and reload, further increasing
-the load. You can, and should, control the <CODE>MaxClients</CODE>
-setting so that your server does not spawn so many children it starts
-swapping.
-
-<P>Beyond that the rest is mundane: get a fast enough CPU, a fast enough
-network card, and fast enough disks, where "fast enough" is something
-that needs to be determined by experimentation.
-
-<P>Operating system choice is largely a matter of local concerns. But
-a general guideline is to always apply the latest vendor TCP/IP patches.
-HTTP serving completely breaks many of the assumptions built into Unix
-kernels up through 1994 and even 1995. Good choices include
-recent FreeBSD, and Linux.
-
-<hr>
-
-<H3><a name="runtime">Run-Time Configuration Issues</a></H3>
-
-<H4>HostnameLookups</H4>
-<P>Prior to Apache 1.3, <CODE>HostnameLookups</CODE> defaulted to On.
-This adds latency
-to every request because it requires a DNS lookup to complete before
-the request is finished. In Apache 1.3 this setting defaults to Off.
-However (1.3 or later), if you use any <CODE>Allow from domain</CODE> or
-<CODE>Deny from domain</CODE> directives then you will pay for a
-double reverse DNS lookup (a reverse, followed by a forward to make sure
-that the reverse is not being spoofed). So for the highest performance
-avoid using these directives (it's fine to use IP addresses rather than
-domain names).
-
-<P>Note that it's possible to scope the directives, such as within
-a <CODE><Location /server-status></CODE> section. In this
-case the DNS lookups are only performed on requests matching the
-criteria. Here's an example which disables
-lookups except for .html and .cgi files:
-
-<BLOCKQUOTE><PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache Performance Notes</title>
+ </head>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+
+ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
+ vlink="#000080" alink="#FF0000">
+ <!--#include virtual="header.html" -->
+
+ <blockquote>
+ <strong>Warning:</strong> This document has not been updated
+ to take into account changes made in the 2.0 version of the
+ Apache HTTP Server. Some of the information may still be
+ relevant, but please use it with care.
+ </blockquote>
+
+ <h1 align="center">Apache Performance Notes</h1>
+
+ <p>Author: Dean Gaudet</p>
+
+ <ul>
+ <li><a href="#introduction">Introduction</a></li>
+
+ <li><a href="#hardware">Hardware and Operating System
+ Issues</a></li>
+
+ <li><a href="#runtime">Run-Time Configuration Issues</a></li>
+
+ <li><a href="#compiletime">Compile-Time Configuration
+ Issues</a></li>
+
+ <li>
+ Appendixes
+
+ <ul>
+ <li><a href="#trace">Detailed Analysis of a
+ Trace</a></li>
+
+ <li><a href="#patches">Patches Available</a></li>
+
+ <li><a href="#preforking">The Pre-Forking Model</a></li>
+ </ul>
+ </li>
+ </ul>
+ <hr />
+
+ <table border="1">
+ <tr>
+ <td valign="top"><strong>Related Modules</strong><br />
+ <br />
+ <a href="../mod/mod_dir.html">mod_dir</a><br />
+ <a href="../mod/mpm_common.html">Multi-Processing
+ module</a><br />
+ <a href="../mod/mod_status.html">mod_status</a><br />
+ </td>
+
+ <td valign="top"><strong>Related Directives</strong><br />
+ <br />
+ <a
+ href="../mod/core.html#allowoverride">AllowOverride</a><br />
+ <a
+ href="../mod/mod_dir.html#directoryindex">DirectoryIndex</a><br />
+ <a
+ href="../mod/core.html#hostnamelookups">HostNameLookups</a><br />
+ <a
+ href="../mod/core.html#keepalivetimeout">KeepAliveTimeout</a><br />
+ <a
+ href="../mod/prefork.html#maxspareservers">MaxSpareServers</a><br />
+ <a
+ href="../mod/prefork.html#mixspareservers">MinSpareServers</a><br />
+ <a href="../mod/core.html#options">Options</a>
+ (FollowSymLinks and FollowIfOwnerMatch)<br />
+ <a
+ href="../mod/mpm_common.html#startservers">StartServers</a><br />
+ </td>
+ </tr>
+ </table>
+
+ <h3><a id="introduction"
+ name="introduction">Introduction</a></h3>
+
+ <p>Apache is a general webserver, which is designed to be
+ correct first, and fast second. Even so, its performance is
+ quite satisfactory. Most sites have less than 10Mbits of
+ outgoing bandwidth, which Apache can fill using only a low end
+ Pentium-based webserver. In practice sites with more bandwidth
+ require more than one machine to fill the bandwidth due to
+ other constraints (such as CGI or database transaction
+ overhead). For these reasons the development focus has been
+ mostly on correctness and configurability.</p>
+
+ <p>Unfortunately many folks overlook these facts and cite raw
+ performance numbers as if they are some indication of the
+ quality of a web server product. There is a bare minimum
+ performance that is acceptable, beyond that extra speed only
+ caters to a much smaller segment of the market. But in order to
+ avoid this hurdle to the acceptance of Apache in some markets,
+ effort was put into Apache 1.3 to bring performance up to a
+ point where the difference with other high-end webservers is
+ minimal.</p>
+
+ <p>Finally there are the folks who just plain want to see how
+ fast something can go. The author falls into this category. The
+ rest of this document is dedicated to these folks who want to
+ squeeze every last bit of performance out of Apache's current
+ model, and want to understand why it does some things which
+ slow it down.</p>
+
+ <p>Note that this is tailored towards Apache 1.3 on Unix. Some
+ of it applies to Apache on NT. Apache on NT has not been tuned
+ for performance yet; in fact it probably performs very poorly
+ because NT performance requires a different programming
+ model.</p>
+ <hr />
+
+ <h3><a id="hardware" name="hardware">Hardware and Operating
+ System Issues</a></h3>
+
+ <p>The single biggest hardware issue affecting webserver
+ performance is RAM. A webserver should never ever have to swap,
+ swapping increases the latency of each request beyond a point
+ that users consider "fast enough". This causes users to hit
+ stop and reload, further increasing the load. You can, and
+ should, control the <code>MaxClients</code> setting so that
+ your server does not spawn so many children it starts
+ swapping.</p>
+
+ <p>Beyond that the rest is mundane: get a fast enough CPU, a
+ fast enough network card, and fast enough disks, where "fast
+ enough" is something that needs to be determined by
+ experimentation.</p>
+
+ <p>Operating system choice is largely a matter of local
+ concerns. But a general guideline is to always apply the latest
+ vendor TCP/IP patches. HTTP serving completely breaks many of
+ the assumptions built into Unix kernels up through 1994 and
+ even 1995. Good choices include recent FreeBSD, and Linux.</p>
+ <hr />
+
+ <h3><a id="runtime" name="runtime">Run-Time Configuration
+ Issues</a></h3>
+
+ <h4>HostnameLookups</h4>
+
+ <p>Prior to Apache 1.3, <code>HostnameLookups</code> defaulted
+ to On. This adds latency to every request because it requires a
+ DNS lookup to complete before the request is finished. In
+ Apache 1.3 this setting defaults to Off. However (1.3 or
+ later), if you use any <code>Allow from domain</code> or
+ <code>Deny from domain</code> directives then you will pay for
+ a double reverse DNS lookup (a reverse, followed by a forward
+ to make sure that the reverse is not being spoofed). So for the
+ highest performance avoid using these directives (it's fine to
+ use IP addresses rather than domain names).</p>
+
+ <p>Note that it's possible to scope the directives, such as
+ within a <code><Location /server-status></code> section.
+ In this case the DNS lookups are only performed on requests
+ matching the criteria. Here's an example which disables lookups
+ except for .html and .cgi files:</p>
+
+ <blockquote>
+<pre>
HostnameLookups off
<Files ~ "\.(html|cgi)$">
HostnameLookups on
</Files>
-</PRE></BLOCKQUOTE>
-
-But even still, if you just need DNS names
-in some CGIs you could consider doing the
-<CODE>gethostbyname</CODE> call in the specific CGIs that need it.
-
-<p>Similarly, if you need to have hostname information in your server
-logs in order to generate reports of this information, you can
-postprocess your log file with <a href="../programs/logresolve.html"
->logresolve</a>, so that these lookups can be done without making the
-client wait. It is recommended that you do this postprocessing, and any
-other statistical analysis of the log file, somewhere other than your
-production web server machine, in order that this activity does not
-adversely affect server performance.</p>
-
-<H4>FollowSymLinks and SymLinksIfOwnerMatch</H4>
-<P>Wherever in your URL-space you do not have an
-<CODE>Options FollowSymLinks</CODE>, or you do have an
-<CODE>Options SymLinksIfOwnerMatch</CODE> Apache will have to
-issue extra system calls to check up on symlinks. One extra call per
-filename component. For example, if you had:
-
-<BLOCKQUOTE><PRE>
+</pre>
+ </blockquote>
+ But even still, if you just need DNS names in some CGIs you
+ could consider doing the <code>gethostbyname</code> call in the
+ specific CGIs that need it.
+
+ <p>Similarly, if you need to have hostname information in your
+ server logs in order to generate reports of this information,
+ you can postprocess your log file with <a
+ href="../programs/logresolve.html">logresolve</a>, so that
+ these lookups can be done without making the client wait. It is
+ recommended that you do this postprocessing, and any other
+ statistical analysis of the log file, somewhere other than your
+ production web server machine, in order that this activity does
+ not adversely affect server performance.</p>
+
+ <h4>FollowSymLinks and SymLinksIfOwnerMatch</h4>
+
+ <p>Wherever in your URL-space you do not have an <code>Options
+ FollowSymLinks</code>, or you do have an <code>Options
+ SymLinksIfOwnerMatch</code> Apache will have to issue extra
+ system calls to check up on symlinks. One extra call per
+ filename component. For example, if you had:</p>
+
+ <blockquote>
+<pre>
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>
+</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 /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>
+</pre>
+ </blockquote>
+ This at least avoids the extra checks for the
+ <code>DocumentRoot</code> path. Note that you'll need to add
+ similar sections if you have any <code>Alias</code> or
+ <code>RewriteRule</code> paths outside of your document root.
+ For highest performance, and no symlink protection, set
+ <code>FollowSymLinks</code> everywhere, and never set
+ <code>SymLinksIfOwnerMatch</code>.
+
+ <h4>AllowOverride</h4>
+
+ <p>Wherever in your URL-space you allow overrides (typically
+ <code>.htaccess</code> files) Apache will attempt to open
+ <code>.htaccess</code> for each filename component. For
+ example,</p>
+
+ <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>
+</pre>
+ </blockquote>
+ and a request is made for the URI <code>/index.html</code>.
+ Then Apache will attempt to open <code>/.htaccess</code>,
+ <code>/www/.htaccess</code>, and
+ <code>/www/htdocs/.htaccess</code>. The solutions are similar
+ to the previous case of <code>Options FollowSymLinks</code>.
+ For highest performance use <code>AllowOverride None</code>
+ everywhere in your filesystem.
+
+ <h4>Negotiation</h4>
+
+ <p>If at all possible, avoid content-negotiation if you're
+ really interested in every last ounce of performance. In
+ practice the benefits of negotiation outweigh the performance
+ penalties. There's one case where you can speed up the server.
+ Instead of using a wildcard such as:</p>
+
+ <blockquote>
+<pre>
DirectoryIndex index
-</PRE></BLOCKQUOTE>
+</pre>
+ </blockquote>
+ Use a complete list of options:
-Use a complete list of options:
-
-<BLOCKQUOTE><PRE>
+ <blockquote>
+<pre>
DirectoryIndex index.cgi index.pl index.shtml index.html
-</PRE></BLOCKQUOTE>
-
-where you list the most common choice first.
-
-<p>Also note that explicitly creating a <code>type-map</code> file
-provides better performance than using <code>MultiViews</code>, as the
-necessary information can be determined by reading this single file,
-rather than having to scan the directory for files.</p>
-
-<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>.
-
-<hr>
-
-<H3><a name="compiletime">Compile-Time Configuration Issues</a></H3>
-
-<H4>mod_status and ExtendedStatus On</H4>
-
-<P>If you include <CODE>mod_status</CODE>
-and you also set <CODE>ExtendedStatus On</CODE> when building and running
-Apache, then on every request Apache will perform two calls to
-<CODE>gettimeofday(2)</CODE> (or <CODE>times(2)</CODE> depending
-on your operating system), and (pre-1.3) several extra calls to
-<CODE>time(2)</CODE>. This is all done so that the status report
-contains timing indications. For highest performance, set
-<CODE>ExtendedStatus off</CODE> (which is the default).
-
-<H4>accept Serialization - multiple sockets</H4>
-
-<P>This discusses a shortcoming in the Unix socket API.
-Suppose your
-web server uses multiple <CODE>Listen</CODE> statements to listen on
-either multiple ports or multiple addresses. In order to test each
-socket to see if a connection is ready Apache uses <CODE>select(2)</CODE>.
-<CODE>select(2)</CODE> indicates that a socket has <EM>zero</EM> or
-<EM>at least one</EM> connection waiting on it. Apache's model includes
-multiple children, and all the idle ones test for new connections at the
-same time. A naive implementation looks something like this
-(these examples do not match the code, they're contrived for
-pedagogical purposes):
-
-<BLOCKQUOTE><PRE>
+</pre>
+ </blockquote>
+ where you list the most common choice first.
+
+ <p>Also note that explicitly creating a <code>type-map</code>
+ file provides better performance than using
+ <code>MultiViews</code>, as the necessary information can be
+ determined by reading this single file, rather than having to
+ scan the directory for files.</p>
+
+ <h4>Process Creation</h4>
+
+ <p>Prior to Apache 1.3 the <code>MinSpareServers</code>,
+ <code>MaxSpareServers</code>, and <code>StartServers</code>
+ settings all had drastic effects on benchmark results. In
+ particular, Apache required a "ramp-up" period in order to
+ reach a number of children sufficient to serve the load being
+ applied. After the initial spawning of
+ <code>StartServers</code> children, only one child per second
+ would be created to satisfy the <code>MinSpareServers</code>
+ setting. So a server being accessed by 100 simultaneous
+ clients, using the default <code>StartServers</code> of 5 would
+ take on the order 95 seconds to spawn enough children to handle
+ the load. This works fine in practice on real-life servers,
+ because they aren't restarted frequently. But does really
+ poorly on benchmarks which might only run for ten minutes.</p>
+
+ <p>The one-per-second rule was implemented in an effort to
+ avoid swamping the machine with the startup of new children. If
+ the machine is busy spawning children it can't service
+ requests. But it has such a drastic effect on the perceived
+ performance of Apache that it had to be replaced. As of Apache
+ 1.3, the code will relax the one-per-second rule. It will spawn
+ one, wait a second, then spawn two, wait a second, then spawn
+ four, and it will continue exponentially until it is spawning
+ 32 children per second. It will stop whenever it satisfies the
+ <code>MinSpareServers</code> setting.</p>
+
+ <p>This appears to be responsive enough that it's almost
+ unnecessary to twiddle the <code>MinSpareServers</code>,
+ <code>MaxSpareServers</code> and <code>StartServers</code>
+ knobs. When more than 4 children are spawned per second, a
+ message will be emitted to the <code>ErrorLog</code>. If you
+ see a lot of these errors then consider tuning these settings.
+ Use the <code>mod_status</code> output as a guide.</p>
+
+ <p>Related to process creation is process death induced by the
+ <code>MaxRequestsPerChild</code> setting. By default this is 0,
+ which means that there is no limit to the number of requests
+ handled per child. If your configuration currently has this set
+ to some very low number, such as 30, you may want to bump this
+ up significantly. If you are running SunOS or an old version of
+ Solaris, limit this to 10000 or so because of memory leaks.</p>
+
+ <p>When keep-alives are in use, children will be kept busy
+ doing nothing waiting for more requests on the already open
+ connection. The default <code>KeepAliveTimeout</code> of 15
+ seconds attempts to minimize this effect. The tradeoff here is
+ between network bandwidth and server resources. In no event
+ should you raise this above about 60 seconds, as <a
+ href="http://www.research.digital.com/wrl/techreports/abstracts/95.4.html">
+ most of the benefits are lost</a>.</p>
+ <hr />
+
+ <h3><a id="compiletime" name="compiletime">Compile-Time
+ Configuration Issues</a></h3>
+
+ <h4>mod_status and ExtendedStatus On</h4>
+
+ <p>If you include <code>mod_status</code> and you also set
+ <code>ExtendedStatus On</code> when building and running
+ Apache, then on every request Apache will perform two calls to
+ <code>gettimeofday(2)</code> (or <code>times(2)</code>
+ depending on your operating system), and (pre-1.3) several
+ extra calls to <code>time(2)</code>. This is all done so that
+ the status report contains timing indications. For highest
+ performance, set <code>ExtendedStatus off</code> (which is the
+ default).</p>
+
+ <h4>accept Serialization - multiple sockets</h4>
+
+ <p>This discusses a shortcoming in the Unix socket API. Suppose
+ your web server uses multiple <code>Listen</code> statements to
+ listen on either multiple ports or multiple addresses. In order
+ to test each socket to see if a connection is ready Apache uses
+ <code>select(2)</code>. <code>select(2)</code> indicates that a
+ socket has <em>zero</em> or <em>at least one</em> connection
+ waiting on it. Apache's model includes multiple children, and
+ all the idle ones test for new connections at the same time. A
+ naive implementation looks something like this (these examples
+ do not match the code, they're contrived for pedagogical
+ purposes):</p>
+
+ <blockquote>
+<pre>
+ for (;;) {
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;
+ 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>
+</pre>
+ </blockquote>
+ But this naive implementation has a serious starvation problem.
+ Recall that multiple children execute this loop at the same
+ time, and so multiple children will block at
+ <code>select</code> when they are in between requests. All
+ those blocked children will awaken and return from
+ <code>select</code> when a single request appears on any socket
+ (the number of children which awaken varies depending on the
+ operating system and timing issues). They will all then fall
+ down into the loop and try to <code>accept</code> the
+ connection. But only one will succeed (assuming there's still
+ only one connection ready), the rest will be <em>blocked</em>
+ in <code>accept</code>. This effectively locks those children
+ into serving requests from that one socket and no other
+ sockets, and they'll be stuck there until enough new requests
+ appear on that socket to wake them all up. This starvation
+ problem was first documented in <a
+ href="http://bugs.apache.org/index/full/467">PR#467</a>. There
+ are at least two solutions.
+
+ <p>One solution is to make the sockets non-blocking. In this
+ case the <code>accept</code> won't block the children, and they
+ will be allowed to continue immediately. But this wastes CPU
+ time. Suppose you have ten idle children in
+ <code>select</code>, and one connection arrives. Then nine of
+ those children will wake up, try to <code>accept</code> the
+ connection, fail, and loop back into <code>select</code>,
+ accomplishing nothing. Meanwhile none of those children are
+ servicing requests that occurred on other sockets until they
+ get back up to the <code>select</code> again. Overall this
+ solution does not seem very fruitful unless you have as many
+ idle CPUs (in a multiprocessor box) as you have idle children,
+ not a very likely situation.</p>
+
+ <p>Another solution, the one used by Apache, is to serialize
+ entry into the inner loop. The loop looks like this
+ (differences highlighted):</p>
+
+ <blockquote>
+<pre>
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;
+ <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>
+</pre>
+ </blockquote>
+ <a id="serialize" name="serialize">The functions</a>
+ <code>accept_mutex_on</code> and <code>accept_mutex_off</code>
+ implement a mutual exclusion semaphore. Only one child can have
+ the mutex at any time. There are several choices for
+ implementing these mutexes. The choice is defined in
+ <code>src/conf.h</code> (pre-1.3) or
+ <code>src/include/ap_config.h</code> (1.3 or later). Some
+ architectures do not have any locking choice made, on these
+ architectures it is unsafe to use multiple <code>Listen</code>
+ directives.
+
+ <dl>
+ <dt><code>USE_FLOCK_SERIALIZED_ACCEPT</code></dt>
+
+ <dd>This method uses the <code>flock(2)</code> system call to
+ lock a lock file (located by the <code>LockFile</code>
+ directive).</dd>
+
+ <dt><code>USE_FCNTL_SERIALIZED_ACCEPT</code></dt>
+
+ <dd>This method uses the <code>fcntl(2)</code> system call to
+ lock a lock file (located by the <code>LockFile</code>
+ directive).</dd>
+
+ <dt><code>USE_SYSVSEM_SERIALIZED_ACCEPT</code></dt>
+
+ <dd>(1.3 or later) This method uses SysV-style semaphores to
+ implement the mutex. Unfortunately SysV-style semaphores have
+ some bad side-effects. One is that it's possible Apache will
+ die without cleaning up the semaphore (see the
+ <code>ipcs(8)</code> man page). The other is that the
+ semaphore API allows for a denial of service attack by any
+ CGIs running under the same uid as the webserver
+ (<em>i.e.</em>, all CGIs, unless you use something like
+ suexec or cgiwrapper). For these reasons this method is not
+ used on any architecture except IRIX (where the previous two
+ are prohibitively expensive on most IRIX boxes).</dd>
+
+ <dt><code>USE_USLOCK_SERIALIZED_ACCEPT</code></dt>
+
+ <dd>(1.3 or later) This method is only available on IRIX, and
+ uses <code>usconfig(2)</code> to create a mutex. While this
+ method avoids the hassles of SysV-style semaphores, it is not
+ the default for IRIX. This is because on single processor
+ IRIX boxes (5.3 or 6.2) the uslock code is two orders of
+ magnitude slower than the SysV-semaphore code. On
+ multi-processor IRIX boxes the uslock code is an order of
+ magnitude faster than the SysV-semaphore code. Kind of a
+ messed up situation. So if you're using a multiprocessor IRIX
+ box then you should rebuild your webserver with
+ <code>-DUSE_USLOCK_SERIALIZED_ACCEPT</code> on the
+ <code>EXTRA_CFLAGS</code>.</dd>
+
+ <dt><code>USE_PTHREAD_SERIALIZED_ACCEPT</code></dt>
+
+ <dd>(1.3 or later) This method uses POSIX mutexes and should
+ work on any architecture implementing the full POSIX threads
+ specification, however appears to only work on Solaris (2.5
+ or later), and even then only in certain configurations. If
+ you experiment with this you should watch out for your server
+ hanging and not responding. Static content only servers may
+ work just fine.</dd>
+ </dl>
+
+ <p>If your system has another method of serialization which
+ isn't in the above list then it may be worthwhile adding code
+ for it (and submitting a patch back to Apache).</p>
+
+ <p>Another solution that has been considered but never
+ implemented is to partially serialize the loop -- that is, let
+ in a certain number of processes. This would only be of
+ interest on multiprocessor boxes where it's possible multiple
+ children could run simultaneously, and the serialization
+ actually doesn't take advantage of the full bandwidth. This is
+ a possible area of future investigation, but priority remains
+ low because highly parallel web servers are not the norm.</p>
+
+ <p>Ideally you should run servers without multiple
+ <code>Listen</code> statements if you want the highest
+ performance. But read on.</p>
+
+ <h4>accept Serialization - single socket</h4>
+
+ <p>The above is fine and dandy for multiple socket servers, but
+ what about single socket servers? In theory they shouldn't
+ experience any of these same problems because all children can
+ just block in <code>accept(2)</code> until a connection
+ arrives, and no starvation results. In practice this hides
+ almost the same "spinning" 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>
+
+ <p>For this reason we have found that many architectures behave
+ more "nicely" if we serialize even the single socket case. So
+ this is actually the default in almost all cases. Crude
+ experiments under Linux (2.0.30 on a dual Pentium pro 166
+ w/128Mb RAM) have shown that the serialization of the single
+ socket case causes less than a 3% decrease in requests per
+ second over unserialized single-socket. But unserialized
+ single-socket showed an extra 100ms latency on each request.
+ This latency is probably a wash on long haul lines, and only an
+ issue on LANs. If you want to override the single socket
+ serialization you can define
+ <code>SINGLE_LISTEN_UNSERIALIZED_ACCEPT</code> and then
+ single-socket servers will not serialize at all.</p>
+
+ <h4>Lingering Close</h4>
+
+ <p>As discussed in <a
+ href="http://www.ics.uci.edu/pub/ietf/http/draft-ietf-http-connection-00.txt">
+ draft-ietf-http-connection-00.txt</a> section 8, in order for
+ an HTTP server to <strong>reliably</strong> implement the
+ protocol it needs to shutdown each direction of the
+ communication independently (recall that a TCP connection is
+ bi-directional, each half is independent of the other). This
+ fact is often overlooked by other servers, but is correctly
+ implemented in Apache as of 1.2.</p>
+
+ <p>When this feature was added to Apache it caused a flurry of
+ problems on various versions of Unix because of a
+ shortsightedness. The TCP specification does not state that the
+ FIN_WAIT_2 state has a timeout, but it doesn't prohibit it. On
+ systems without the timeout, Apache 1.2 induces many sockets
+ stuck forever in the FIN_WAIT_2 state. In many cases this can
+ be avoided by simply upgrading to the latest TCP/IP patches
+ supplied by the vendor. In cases where the vendor has never
+ released patches (<em>i.e.</em>, SunOS4 -- although folks with
+ a source license can patch it themselves) we have decided to
+ disable this feature.</p>
+
+ <p>There are two ways of accomplishing this. One is the socket
+ option <code>SO_LINGER</code>. But as fate would have it, this
+ has never been implemented properly in most TCP/IP stacks. Even
+ on those stacks with a proper implementation (<em>i.e.</em>,
+ Linux 2.0.31) this method proves to be more expensive (cputime)
+ than the next solution.</p>
+
+ <p>For the most part, Apache implements this in a function
+ called <code>lingering_close</code> (in
+ <code>http_main.c</code>). The function looks roughly like
+ this:</p>
+
+ <blockquote>
+<pre>
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) {
- if (read (s, junk_buffer, sizeof (junk_buffer)) <= 0) {
- break;
- }
- /* just toss away whatever is here */
- }
- }
-
- close (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) {
+ if (read (s, junk_buffer, sizeof (junk_buffer)) <= 0) {
+ break;
+ }
+ /* just toss away whatever is here */
+ }
}
-</PRE></BLOCKQUOTE>
-
-This naturally adds some expense at the end of a connection, but it
-is required for a reliable implementation. As HTTP/1.1 becomes more
-prevalent, and all connections are persistent, this expense will be
-amortized over more requests. If you want to play with fire and
-disable this feature you can define <CODE>NO_LINGCLOSE</CODE>, but
-this is not recommended at all. In particular, as HTTP/1.1 pipelined
-persistent connections come into use <CODE>lingering_close</CODE>
-is an absolute necessity (and
-<A HREF="http://www.w3.org/Protocols/HTTP/Performance/Pipeline.html">
-pipelined connections are faster</A>, so you
-want to support them).
-
-<H4>Scoreboard File</H4>
-
-<P>Apache's parent and children communicate with each other through
-something called the scoreboard. Ideally this should be implemented
-in shared memory. For those operating systems that we either have
-access to, or have been given detailed ports for, it typically is
-implemented using shared memory. The rest default to using an
-on-disk file. The on-disk file is not only slow, but it is unreliable
-(and less featured). Peruse the <CODE>src/main/conf.h</CODE> file
-for your architecture and look for either <CODE>USE_MMAP_SCOREBOARD</CODE> or
-<CODE>USE_SHMGET_SCOREBOARD</CODE>. Defining one of those two (as
-well as their companions <CODE>HAVE_MMAP</CODE> and <CODE>HAVE_SHMGET</CODE>
-respectively) enables the supplied shared memory code. If your system has
-another type of shared memory, edit the file <CODE>src/main/http_main.c</CODE>
-and add the hooks necessary to use it in Apache. (Send us back a patch
-too please.)
-
-<P>Historical note: The Linux port of Apache didn't start to use
-shared memory until version 1.2 of Apache. This oversight resulted
-in really poor and unreliable behaviour of earlier versions of Apache
-on Linux.
-
-<H4><CODE>DYNAMIC_MODULE_LIMIT</CODE></H4>
-
-<P>If you have no intention of using dynamically loaded modules
-(you probably don't if you're reading this and tuning your
-server for every last ounce of performance) then you should add
-<CODE>-DDYNAMIC_MODULE_LIMIT=0</CODE> when building your server.
-This will save RAM that's allocated only for supporting dynamically
-loaded modules.
-
-<hr>
-
-<H3><a name="trace">Appendix: Detailed Analysis of a Trace</a></H3>
-
-Here is a system call trace of Apache 1.3 running on Linux. The run-time
-configuration file is essentially the default plus:
-
-<BLOCKQUOTE><PRE>
+
+ close (s);
+ }
+</pre>
+ </blockquote>
+ This naturally adds some expense at the end of a connection,
+ but it is required for a reliable implementation. As HTTP/1.1
+ becomes more prevalent, and all connections are persistent,
+ this expense will be amortized over more requests. If you want
+ to play with fire and disable this feature you can define
+ <code>NO_LINGCLOSE</code>, but this is not recommended at all.
+ In particular, as HTTP/1.1 pipelined persistent connections
+ come into use <code>lingering_close</code> is an absolute
+ necessity (and <a
+ href="http://www.w3.org/Protocols/HTTP/Performance/Pipeline.html">
+ pipelined connections are faster</a>, so you want to support
+ them).
+
+ <h4>Scoreboard File</h4>
+
+ <p>Apache's parent and children communicate with each other
+ through something called the scoreboard. Ideally this should be
+ implemented in shared memory. For those operating systems that
+ we either have access to, or have been given detailed ports
+ for, it typically is implemented using shared memory. The rest
+ default to using an on-disk file. The on-disk file is not only
+ slow, but it is unreliable (and less featured). Peruse the
+ <code>src/main/conf.h</code> file for your architecture and
+ look for either <code>USE_MMAP_SCOREBOARD</code> or
+ <code>USE_SHMGET_SCOREBOARD</code>. Defining one of those two
+ (as well as their companions <code>HAVE_MMAP</code> and
+ <code>HAVE_SHMGET</code> respectively) enables the supplied
+ shared memory code. If your system has another type of shared
+ memory, edit the file <code>src/main/http_main.c</code> and add
+ the hooks necessary to use it in Apache. (Send us back a patch
+ too please.)</p>
+
+ <p>Historical note: The Linux port of Apache didn't start to
+ use shared memory until version 1.2 of Apache. This oversight
+ resulted in really poor and unreliable behaviour of earlier
+ versions of Apache on Linux.</p>
+
+ <h4><code>DYNAMIC_MODULE_LIMIT</code></h4>
+
+ <p>If you have no intention of using dynamically loaded modules
+ (you probably don't if you're reading this and tuning your
+ server for every last ounce of performance) then you should add
+ <code>-DDYNAMIC_MODULE_LIMIT=0</code> when building your
+ server. This will save RAM that's allocated only for supporting
+ dynamically loaded modules.</p>
+ <hr />
+
+ <h3><a id="trace" name="trace">Appendix: Detailed Analysis of a
+ Trace</a></h3>
+ Here is a system call trace of Apache 1.3 running on Linux. The
+ run-time configuration file is essentially the default plus:
+
+ <blockquote>
+<pre>
<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>
+</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
sigaction(SIGUSR1, {0x8059954, [], SA_INTERRUPT}, {SIG_IGN}) = 0
munmap(0x400ee000, 6144) = 0
flock(18, LOCK_EX) = 0
-</PRE></BLOCKQUOTE>
+</pre>
+ </blockquote>
-<P>Notice the accept serialization:
+ <p>Notice the accept serialization:</p>
-<BLOCKQUOTE><PRE>
+ <blockquote>
+<pre>
flock(18, LOCK_UN) = 0
...
flock(18, LOCK_EX) = 0
-</PRE></BLOCKQUOTE>
-
-These two calls can be removed by defining
-<CODE>SINGLE_LISTEN_UNSERIALIZED_ACCEPT</CODE> as described earlier.
+</pre>
+ </blockquote>
+ These two calls can be removed by defining
+ <code>SINGLE_LISTEN_UNSERIALIZED_ACCEPT</code> as described
+ earlier.
-<P>Notice the <CODE>SIGUSR1</CODE> manipulation:
+ <p>Notice the <code>SIGUSR1</code> manipulation:</p>
-<BLOCKQUOTE><PRE>
+ <blockquote>
+<pre>
sigaction(SIGUSR1, {SIG_IGN}, {0x8059954, [], SA_INTERRUPT}) = 0
...
sigaction(SIGUSR1, {SIG_IGN}, {SIG_IGN}) = 0
...
sigaction(SIGUSR1, {0x8059954, [], SA_INTERRUPT}, {SIG_IGN}) = 0
-</PRE></BLOCKQUOTE>
-
-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>
+</pre>
+ </blockquote>
+ This is caused by the implementation of graceful restarts. When
+ the parent receives a <code>SIGUSR1</code> it sends a
+ <code>SIGUSR1</code> to all of its children (and it also
+ increments a "generation counter" in shared memory). Any
+ children that are idle (between connections) will immediately
+ die off when they receive the signal. Any children that are in
+ keep-alive connections, but are in between requests will die
+ off immediately. But any children that have a connection and
+ are still waiting for the first request will not die off
+ immediately.
+
+ <p>To see why this is necessary, consider how a browser reacts
+ to a closed connection. If the connection was a keep-alive
+ connection and the request being serviced was not the first
+ request then the browser will quietly reissue the request on a
+ new connection. It has to do this because the server is always
+ free to close a keep-alive connection in between requests
+ (<em>i.e.</em>, due to a timeout or because of a maximum number
+ of requests). But, if the connection is closed before the first
+ response has been received the typical browser will display a
+ "document contains no data" dialogue (or a broken image icon).
+ This is done on the assumption that the server is broken in
+ some way (or maybe too overloaded to respond at all). So Apache
+ tries to avoid ever deliberately closing the connection before
+ it has sent a single response. This is the cause of those
+ <code>SIGUSR1</code> manipulations.</p>
+
+ <p>Note that it is theoretically possible to eliminate all
+ three of these calls. But in rough tests the gain proved to be
+ almost unnoticeable.</p>
+
+ <p>In order to implement virtual hosts, Apache needs to know
+ the local socket address used to accept the connection:</p>
+
+ <blockquote>
+<pre>
getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0
-</PRE></BLOCKQUOTE>
+</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.
-It is possible to eliminate this call in many situations (such as when
-there are no virtual hosts, or when <CODE>Listen</CODE> directives are
-used which do not have wildcard addresses). But no effort has yet been
-made to do these optimizations.
+ <p>Apache turns off the Nagle algorithm:</p>
-<P>Apache turns off the Nagle algorithm:
-
-<BLOCKQUOTE><PRE>
+ <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>.
+</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:
+ <p>Notice the two <code>time</code> calls:</p>
-<BLOCKQUOTE><PRE>
+ <blockquote>
+<pre>
time(NULL) = 873959960
...
time(NULL) = 873959960
-</PRE></BLOCKQUOTE>
-
-One of these occurs at the beginning of the request, and the other occurs
-as a result of writing the log. At least one of these is required to
-properly implement the HTTP protocol. The second occurs because the
-Common Log Format dictates that the log record include a timestamp of the
-end of the request. A custom logging module could eliminate one of the
-calls. Or you can use a method which moves the time into shared memory,
-see the <A HREF="#patches">patches section below</A>.
-
-<P>As described earlier, <CODE>ExtendedStatus On</CODE> causes two
-<CODE>gettimeofday</CODE> calls and a call to <CODE>times</CODE>:
-
-<BLOCKQUOTE><PRE>
+</pre>
+ </blockquote>
+ One of these occurs at the beginning of the request, and the
+ other occurs as a result of writing the log. At least one of
+ these is required to properly implement the HTTP protocol. The
+ second occurs because the Common Log Format dictates that the
+ log record include a timestamp of the end of the request. A
+ custom logging module could eliminate one of the calls. Or you
+ can use a method which moves the time into shared memory, see
+ the <a href="#patches">patches section below</a>.
+
+ <p>As described earlier, <code>ExtendedStatus On</code> causes
+ two <code>gettimeofday</code> calls and a call to
+ <code>times</code>:</p>
+
+ <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>
+</pre>
+ </blockquote>
+ These can be removed by setting <code>ExtendedStatus Off</code>
+ (which is the default).
-These can be removed by setting <CODE>ExtendedStatus Off</CODE> (which
-is the default).
+ <p>It might seem odd to call <code>stat</code>:</p>
-<P>It might seem odd to call <CODE>stat</CODE>:
-
-<BLOCKQUOTE><PRE>
+ <blockquote>
+<pre>
stat("/home/dgaudet/ap/apachen/htdocs/6k", {st_mode=S_IFREG|0644, st_size=6144, ...}) = 0
-</PRE></BLOCKQUOTE>
-
-This is part of the algorithm which calculates the
-<CODE>PATH_INFO</CODE> for use by CGIs. In fact if the request had been
-for the URI <CODE>/cgi-bin/printenv/foobar</CODE> then there would be
-two calls to <CODE>stat</CODE>. The first for
-<CODE>/home/dgaudet/ap/apachen/cgi-bin/printenv/foobar</CODE>
-which does not exist, and the second for
-<CODE>/home/dgaudet/ap/apachen/cgi-bin/printenv</CODE>, which does exist.
-Regardless, at least one <CODE>stat</CODE> call is necessary when
-serving static files because the file size and modification times are
-used to generate HTTP headers (such as <CODE>Content-Length</CODE>,
-<CODE>Last-Modified</CODE>) and implement protocol features (such
-as <CODE>If-Modified-Since</CODE>). A somewhat more clever server
-could avoid the <CODE>stat</CODE> when serving non-static files,
-however doing so in Apache is very difficult given the modular structure.
-
-<P>All static files are served using <CODE>mmap</CODE>:
-
-<BLOCKQUOTE><PRE>
+</pre>
+ </blockquote>
+ This is part of the algorithm which calculates the
+ <code>PATH_INFO</code> for use by CGIs. In fact if the request
+ had been for the URI <code>/cgi-bin/printenv/foobar</code> then
+ there would be two calls to <code>stat</code>. The first for
+ <code>/home/dgaudet/ap/apachen/cgi-bin/printenv/foobar</code>
+ which does not exist, and the second for
+ <code>/home/dgaudet/ap/apachen/cgi-bin/printenv</code>, which
+ does exist. Regardless, at least one <code>stat</code> call is
+ necessary when serving static files because the file size and
+ modification times are used to generate HTTP headers (such as
+ <code>Content-Length</code>, <code>Last-Modified</code>) and
+ implement protocol features (such as
+ <code>If-Modified-Since</code>). A somewhat more clever server
+ could avoid the <code>stat</code> when serving non-static
+ files, however doing so in Apache is very difficult given the
+ modular structure.
+
+ <p>All static files are served using <code>mmap</code>:</p>
+
+ <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>
+</pre>
+ </blockquote>
+ On some architectures it's slower to <code>mmap</code> small
+ files than it is to simply <code>read</code> them. The define
+ <code>MMAP_THRESHOLD</code> can be set to the minimum size
+ required before using <code>mmap</code>. By default it's set to
+ 0 (except on SunOS4 where experimentation has shown 8192 to be
+ a better value). Using a tool such as <a
+ href="http://www.bitmover.com/lmbench/">lmbench</a> you can
+ determine the optimal setting for your environment.
+
+ <p>You may also wish to experiment with
+ <code>MMAP_SEGMENT_SIZE</code> (default 32768) which determines
+ the maximum number of bytes that will be written at a time from
+ mmap()d files. Apache only resets the client's
+ <code>Timeout</code> in between write()s. So setting this large
+ may lock out low bandwidth clients unless you also increase the
+ <code>Timeout</code>.</p>
+
+ <p>It may even be the case that <code>mmap</code> isn't used on
+ your architecture; if so then defining
+ <code>USE_MMAP_FILES</code> and <code>HAVE_MMAP</code> might
+ work (if it works then report back to us).</p>
+
+ <p>Apache does its best to avoid copying bytes around in
+ memory. The first write of any request typically is turned into
+ a <code>writev</code> which combines both the headers and the
+ first hunk of data:</p>
+
+ <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>
+</pre>
+ </blockquote>
+ When doing HTTP/1.1 chunked encoding Apache will generate up to
+ four element <code>writev</code>s. The goal is to push the byte
+ copying into the kernel, where it typically has to happen
+ anyhow (to assemble network packets). On testing, various
+ Unixes (BSDI 2.x, Solaris 2.5, Linux 2.0.31+) properly combine
+ the elements into network packets. Pre-2.0.31 Linux will not
+ combine, and will create a packet for each element, so
+ upgrading is a good idea. Defining <code>NO_WRITEV</code> will
+ disable this combining, but result in very poor chunked
+ encoding performance.
+
+ <p>The log write:</p>
+
+ <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 its best to flush this buffer when a child dies.
-
-<P>The lingering close code causes four system calls:
-
-<BLOCKQUOTE><PRE>
+</pre>
+ </blockquote>
+ can be deferred by defining <code>BUFFERED_LOGS</code>. In this
+ case up to <code>PIPE_BUF</code> bytes (a POSIX defined
+ constant) of log entries are buffered before writing. At no
+ time does it split a log entry across a <code>PIPE_BUF</code>
+ boundary because those writes may not be atomic.
+ (<em>i.e.</em>, entries from multiple children could become
+ mixed together). The code does its best to flush this buffer
+ when a child dies.
+
+ <p>The lingering close code causes four system calls:</p>
+
+ <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>
+</pre>
+ </blockquote>
+ which were described earlier.
-which were described earlier.
+ <p>Let's apply some of these optimizations:
+ <code>-DSINGLE_LISTEN_UNSERIALIZED_ACCEPT
+ -DBUFFERED_LOGS</code> and <code>ExtendedStatus Off</code>.
+ Here's the final trace:</p>
-<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>
+ <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
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> Although they may
-not apply cleanly to the current version,
-it shouldn't be difficult for someone with a little C knowledge to
-update them. In particular:
-
-<UL>
-<LI>A
-<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/shared_time.patch"
->patch</A> to remove all <CODE>time(2)</CODE> system calls.
-<LI>A
-<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/mod_include_speedups.patch"
->patch</A> to remove various system calls from <CODE>mod_include</CODE>,
-these calls are used by few sites but required for backwards compatibility.
-<LI>A
-<A HREF="http://www.arctic.org/~dgaudet/apache/1.3/top_fuel.patch"
->patch</A> which integrates the above two plus a few other speedups at the
-cost of removing some functionality.
-</UL>
-
-<H3><a name="preforking">Appendix: The Pre-Forking Model</a></H3>
-
-<P>Apache (on Unix) is a <EM>pre-forking</EM> model server. The
-<EM>parent</EM> process is responsible only for forking <EM>child</EM>
-processes, it does not serve any requests or service any network
-sockets. The child processes actually process connections, they serve
-multiple connections (one at a time) before dying.
-The parent spawns new or kills off old
-children in response to changes in the load on the server (it does so
-by monitoring a scoreboard which the children keep up to date).
-
-<P>This model for servers offers a robustness that other models do
-not. In particular, the parent code is very simple, and with a high
-degree of confidence the parent will continue to do its job without
-error. The children are complex, and when you add in third party
-code via modules, you risk segmentation faults and other forms of
-corruption. Even should such a thing happen, it only affects one
-connection and the server continues serving requests. The parent
-quickly replaces the dead child.
-
-<P>Pre-forking is also very portable across dialects of Unix.
-Historically this has been an important goal for Apache, and it continues
-to remain so.
-
-<P>The pre-forking model comes under criticism for various
-performance aspects. Of particular concern are the overhead
-of forking a process, the overhead of context switches between
-processes, and the memory overhead of having multiple processes.
-Furthermore it does not offer as many opportunities for data-caching
-between requests (such as a pool of <CODE>mmapped</CODE> files).
-Various other models exist and extensive analysis can be found in the
-<A HREF="http://www.cs.wustl.edu/~jxh/research/research.html"> papers
-of the JAWS project</A>. In practice all of these costs vary drastically
-depending on the operating system.
-
-<P>Apache's core code is already multithread aware, and Apache version
-1.3 is multithreaded on NT. There have been at least two other experimental
-implementations of threaded Apache, one using the 1.3 code base on DCE,
-and one using a custom user-level threads package and the 1.0 code base;
-neither is publicly available. There is also an experimental port of
-Apache 1.3 to <A HREF="http://www.mozilla.org/docs/refList/refNSPR/">
-Netscape's Portable Run Time</A>, which
-<A HREF="http://www.arctic.org/~dgaudet/apache/2.0/">is available</A>
-(but you're encouraged to join the
-<A HREF="http://dev.apache.org/mailing-lists">new-httpd mailing list</A>
-if you intend to use it).
-Part of our redesign for version 2.0
-of Apache will include abstractions of the server model so that we
-can continue to support the pre-forking model, and also support various
-threaded models.
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</pre>
+ </blockquote>
+ That's 19 system calls, of which 4 remain relatively easy to
+ remove, but don't seem worth the effort.
+
+ <h3><a id="patches" name="patches">Appendix: Patches
+ Available</a></h3>
+ There are <a
+ href="http://www.arctic.org/~dgaudet/apache/1.3/">several
+ performance patches available for 1.3.</a> Although they may
+ not apply cleanly to the current version, it shouldn't be
+ difficult for someone with a little C knowledge to update them.
+ In particular:
+
+ <ul>
+ <li>A <a
+ href="http://www.arctic.org/~dgaudet/apache/1.3/shared_time.patch">
+ patch</a> to remove all <code>time(2)</code> system
+ calls.</li>
+
+ <li>A <a
+ href="http://www.arctic.org/~dgaudet/apache/1.3/mod_include_speedups.patch">
+ patch</a> to remove various system calls from
+ <code>mod_include</code>, these calls are used by few sites
+ but required for backwards compatibility.</li>
+
+ <li>A <a
+ href="http://www.arctic.org/~dgaudet/apache/1.3/top_fuel.patch">
+ patch</a> which integrates the above two plus a few other
+ speedups at the cost of removing some functionality.</li>
+ </ul>
+
+ <h3><a id="preforking" name="preforking">Appendix: The
+ Pre-Forking Model</a></h3>
+
+ <p>Apache (on Unix) is a <em>pre-forking</em> model server. The
+ <em>parent</em> process is responsible only for forking
+ <em>child</em> processes, it does not serve any requests or
+ service any network sockets. The child processes actually
+ process connections, they serve multiple connections (one at a
+ time) before dying. The parent spawns new or kills off old
+ children in response to changes in the load on the server (it
+ does so by monitoring a scoreboard which the children keep up
+ to date).</p>
+
+ <p>This model for servers offers a robustness that other models
+ do not. In particular, the parent code is very simple, and with
+ a high degree of confidence the parent will continue to do its
+ job without error. The children are complex, and when you add
+ in third party code via modules, you risk segmentation faults
+ and other forms of corruption. Even should such a thing happen,
+ it only affects one connection and the server continues serving
+ requests. The parent quickly replaces the dead child.</p>
+
+ <p>Pre-forking is also very portable across dialects of Unix.
+ Historically this has been an important goal for Apache, and it
+ continues to remain so.</p>
+
+ <p>The pre-forking model comes under criticism for various
+ performance aspects. Of particular concern are the overhead of
+ forking a process, the overhead of context switches between
+ processes, and the memory overhead of having multiple
+ processes. Furthermore it does not offer as many opportunities
+ for data-caching between requests (such as a pool of
+ <code>mmapped</code> files). Various other models exist and
+ extensive analysis can be found in the <a
+ href="http://www.cs.wustl.edu/~jxh/research/research.html">papers
+ of the JAWS project</a>. In practice all of these costs vary
+ drastically depending on the operating system.</p>
+
+ <p>Apache's core code is already multithread aware, and Apache
+ version 1.3 is multithreaded on NT. There have been at least
+ two other experimental implementations of threaded Apache, one
+ using the 1.3 code base on DCE, and one using a custom
+ user-level threads package and the 1.0 code base; neither is
+ publicly available. There is also an experimental port of
+ Apache 1.3 to <a
+ href="http://www.mozilla.org/docs/refList/refNSPR/">Netscape's
+ Portable Run Time</a>, which <a
+ href="http://www.arctic.org/~dgaudet/apache/2.0/">is
+ available</a> (but you're encouraged to join the <a
+ href="http://dev.apache.org/mailing-lists">new-httpd mailing
+ list</a> if you intend to use it). Part of our redesign for
+ version 2.0 of Apache will include abstractions of the server
+ model so that we can continue to support the pre-forking model,
+ and also support various threaded models.
+ <!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML><HEAD>
-<TITLE>Apache 1.3 URL Rewriting Guide</TITLE>
-</HEAD>
-
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<BLOCKQUOTE>
-<!--#include virtual="header.html" -->
-
-<DIV ALIGN=CENTER>
-
-<H1>
-Apache 1.3<BR>
-URL Rewriting Guide<BR>
-</H1>
-
-<ADDRESS>Originally written by<BR>
-Ralf S. Engelschall <rse@apache.org><BR>
-December 1997</ADDRESS>
-
-</DIV>
-
-<P>
-This document supplements the mod_rewrite <A
-HREF="../mod/mod_rewrite.html">reference documentation</A>. It describes
-how one can use Apache's mod_rewrite to solve typical URL-based problems
-webmasters are usually confronted with in practice. I give detailed
-descriptions on how to solve each problem by configuring URL rewriting
-rulesets.
-
-<H2><A name="ToC1">Introduction to mod_rewrite</A></H2>
-
-The Apache module mod_rewrite is a killer one, i.e. it is a really
-sophisticated module which provides a powerful way to do URL manipulations.
-With it you can nearly do all types of URL manipulations you ever dreamed
-about. The price you have to pay is to accept complexity, because
-mod_rewrite's major drawback is that it is not easy to understand and use for
-the beginner. And even Apache experts sometimes discover new aspects where
-mod_rewrite can help.
-<P>
-In other words: With mod_rewrite you either shoot yourself in the foot the
-first time and never use it again or love it for the rest of your life because
-of its power. This paper tries to give you a few initial success events to
-avoid the first case by presenting already invented solutions to you.
-
-<H2><A name="ToC2">Practical Solutions</A></H2>
-
-Here come a lot of practical solutions I've either invented myself or
-collected from other peoples solutions in the past. Feel free to learn the
-black magic of URL rewriting from these examples.
-
-<P>
-<TABLE BGCOLOR="#FFE0E0" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD>
-ATTENTION: Depending on your server-configuration it can be necessary to
-slightly change the examples for your situation, e.g. adding the [PT] flag
-when additionally using mod_alias and mod_userdir, etc. Or rewriting a ruleset
-to fit in <CODE>.htaccess</CODE> context instead of per-server context. Always try
-to understand what a particular ruleset really does before you use it. It
-avoid problems.
-</TD></TR></TABLE>
-
-<H1>URL Layout</H1>
-
-<P>
-<H2>Canonical URLs</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-On some webservers there are more than one URL for a resource. Usually there
-are canonical URLs (which should be actually used and distributed) and those
-which are just shortcuts, internal ones, etc. Independed which URL the user
-supplied with the request he should finally see the canonical one only.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We do an external HTTP redirect for all non-canonical URLs to fix them in the
-location view of the Browser and for all subsequent requests. In the example
-ruleset below we replace <CODE>/~user</CODE> by the canonical <CODE>/u/user</CODE> and
-fix a missing trailing slash for <CODE>/u/user</CODE>.
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
-RewriteRule ^/<STRONG>~</STRONG>([^/]+)/?(.*) /<STRONG>u</STRONG>/$1/$2 [<STRONG>R</STRONG>]
-RewriteRule ^/([uge])/(<STRONG>[^/]+</STRONG>)$ /$1/$2<STRONG>/</STRONG> [<STRONG>R</STRONG>]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Canonical Hostnames</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-...
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 1.3 URL Rewriting Guide</title>
+ </head>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+
+ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
+ vlink="#000080" alink="#FF0000">
+ <blockquote>
+ <!--#include virtual="header.html" -->
+
+ <div align="CENTER">
+ <h1>Apache 1.3<br />
+ URL Rewriting Guide<br />
+ </h1>
+
+ <address>
+ Originally written by<br />
+ Ralf S. Engelschall <rse@apache.org><br />
+ December 1997
+ </address>
+ </div>
+
+ <p>This document supplements the mod_rewrite <a
+ href="../mod/mod_rewrite.html">reference documentation</a>.
+ It describes how one can use Apache's mod_rewrite to solve
+ typical URL-based problems webmasters are usually confronted
+ with in practice. I give detailed descriptions on how to
+ solve each problem by configuring URL rewriting rulesets.</p>
+
+ <h2><a id="ToC1" name="ToC1">Introduction to
+ mod_rewrite</a></h2>
+ The Apache module mod_rewrite is a killer one, i.e. it is a
+ really sophisticated module which provides a powerful way to
+ do URL manipulations. With it you can nearly do all types of
+ URL manipulations you ever dreamed about. The price you have
+ to pay is to accept complexity, because mod_rewrite's major
+ drawback is that it is not easy to understand and use for the
+ beginner. And even Apache experts sometimes discover new
+ aspects where mod_rewrite can help.
+
+ <p>In other words: With mod_rewrite you either shoot yourself
+ in the foot the first time and never use it again or love it
+ for the rest of your life because of its power. This paper
+ tries to give you a few initial success events to avoid the
+ first case by presenting already invented solutions to
+ you.</p>
+
+ <h2><a id="ToC2" name="ToC2">Practical Solutions</a></h2>
+ Here come a lot of practical solutions I've either invented
+ myself or collected from other peoples solutions in the past.
+ Feel free to learn the black magic of URL rewriting from
+ these examples.
+
+ <table bgcolor="#FFE0E0" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>ATTENTION: Depending on your server-configuration it
+ can be necessary to slightly change the examples for your
+ situation, e.g. adding the [PT] flag when additionally
+ using mod_alias and mod_userdir, etc. Or rewriting a
+ ruleset to fit in <code>.htaccess</code> context instead
+ of per-server context. Always try to understand what a
+ particular ruleset really does before you use it. It
+ avoid problems.</td>
+ </tr>
+ </table>
+
+ <h1>URL Layout</h1>
+
+ <h2>Canonical URLs</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>On some webservers there are more than one URL for a
+ resource. Usually there are canonical URLs (which should be
+ actually used and distributed) and those which are just
+ shortcuts, internal ones, etc. Independed which URL the
+ user supplied with the request he should finally see the
+ canonical one only.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We do an external HTTP redirect for all non-canonical
+ URLs to fix them in the location view of the Browser and
+ for all subsequent requests. In the example ruleset below
+ we replace <code>/~user</code> by the canonical
+ <code>/u/user</code> and fix a missing trailing slash for
+ <code>/u/user</code>.
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
+RewriteRule ^/<strong>~</strong>([^/]+)/?(.*) /<strong>u</strong>/$1/$2 [<strong>R</strong>]
+RewriteRule ^/([uge])/(<strong>[^/]+</strong>)$ /$1/$2<strong>/</strong> [<strong>R</strong>]
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Canonical Hostnames</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>...</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteCond %{HTTP_HOST} !^fully\.qualified\.domain\.name [NC]
RewriteCond %{HTTP_HOST} !^$
RewriteCond %{SERVER_PORT} !^80$
RewriteCond %{HTTP_HOST} !^fully\.qualified\.domain\.name [NC]
RewriteCond %{HTTP_HOST} !^$
RewriteRule ^/(.*) http://fully.qualified.domain.name/$1 [L,R]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Moved DocumentRoot</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Usually the DocumentRoot of the webserver directly relates to the URL
-``<CODE>/</CODE>''. But often this data is not really of top-level priority, it is
-perhaps just one entity of a lot of data pools. For instance at our Intranet
-sites there are <CODE>/e/www/</CODE> (the homepage for WWW), <CODE>/e/sww/</CODE> (the
-homepage for the Intranet) etc. Now because the data of the DocumentRoot stays
-at <CODE>/e/www/</CODE> we had to make sure that all inlined images and other
-stuff inside this data pool work for subsequent requests.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We just redirect the URL <CODE>/</CODE> to <CODE>/e/www/</CODE>. While is seems
-trivial it is actually trivial with mod_rewrite, only. Because the typical
-old mechanisms of URL <EM>Aliases</EM> (as provides by mod_alias and friends)
-only used <EM>prefix</EM> matching. With this you cannot do such a redirection
-because the DocumentRoot is a prefix of all URLs. With mod_rewrite it is
-really trivial:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Moved DocumentRoot</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Usually the DocumentRoot of the webserver directly
+ relates to the URL ``<code>/</code>''. But often this data
+ is not really of top-level priority, it is perhaps just one
+ entity of a lot of data pools. For instance at our Intranet
+ sites there are <code>/e/www/</code> (the homepage for
+ WWW), <code>/e/sww/</code> (the homepage for the Intranet)
+ etc. Now because the data of the DocumentRoot stays at
+ <code>/e/www/</code> we had to make sure that all inlined
+ images and other stuff inside this data pool work for
+ subsequent requests.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We just redirect the URL <code>/</code> to
+ <code>/e/www/</code>. While is seems trivial it is
+ actually trivial with mod_rewrite, only. Because the
+ typical old mechanisms of URL <em>Aliases</em> (as
+ provides by mod_alias and friends) only used
+ <em>prefix</em> matching. With this you cannot do such a
+ redirection because the DocumentRoot is a prefix of all
+ URLs. With mod_rewrite it is really trivial:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
-RewriteRule <STRONG>^/$</STRONG> /e/www/ [<STRONG>R</STRONG>]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Trailing Slash Problem</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Every webmaster can sing a song about the problem of the trailing slash on
-URLs referencing directories. If they are missing, the server dumps an error,
-because if you say <CODE>/~quux/foo</CODE> instead of
-<CODE>/~quux/foo/</CODE> then the server searches for a <EM>file</EM> named
-<CODE>foo</CODE>. And because this file is a directory it complains. Actually
-is tries to fix it themself in most of the cases, but sometimes this mechanism
-need to be emulated by you. For instance after you have done a lot of
-complicated URL rewritings to CGI scripts etc.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-The solution to this subtle problem is to let the server add the trailing
-slash automatically. To do this correctly we have to use an external redirect,
-so the browser correctly requests subsequent images etc. If we only did a
-internal rewrite, this would only work for the directory page, but would go
-wrong when any images are included into this page with relative URLs, because
-the browser would request an in-lined object. For instance, a request for
-<CODE>image.gif</CODE> in <CODE>/~quux/foo/index.html</CODE> would become
-<CODE>/~quux/image.gif</CODE> without the external redirect!
-<P>
-So, to do this trick we write:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteRule <strong>^/$</strong> /e/www/ [<strong>R</strong>]
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Trailing Slash Problem</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Every webmaster can sing a song about the problem of
+ the trailing slash on URLs referencing directories. If they
+ are missing, the server dumps an error, because if you say
+ <code>/~quux/foo</code> instead of <code>/~quux/foo/</code>
+ then the server searches for a <em>file</em> named
+ <code>foo</code>. And because this file is a directory it
+ complains. Actually is tries to fix it themself in most of
+ the cases, but sometimes this mechanism need to be emulated
+ by you. For instance after you have done a lot of
+ complicated URL rewritings to CGI scripts etc.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ The solution to this subtle problem is to let the server
+ add the trailing slash automatically. To do this
+ correctly we have to use an external redirect, so the
+ browser correctly requests subsequent images etc. If we
+ only did a internal rewrite, this would only work for the
+ directory page, but would go wrong when any images are
+ included into this page with relative URLs, because the
+ browser would request an in-lined object. For instance, a
+ request for <code>image.gif</code> in
+ <code>/~quux/foo/index.html</code> would become
+ <code>/~quux/image.gif</code> without the external
+ redirect!
+
+ <p>So, to do this trick we write:</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteBase /~quux/
-RewriteRule ^foo<STRONG>$</STRONG> foo<STRONG>/</STRONG> [<STRONG>R</STRONG>]
-</PRE></TD></TR></TABLE>
-
-<P>
-The crazy and lazy can even do the following in the top-level
-<CODE>.htaccess</CODE> file of their homedir. But notice that this creates some
-processing overhead.
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteRule ^foo<strong>$</strong> foo<strong>/</strong> [<strong>R</strong>]
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>The crazy and lazy can even do the following in the
+ top-level <code>.htaccess</code> file of their homedir.
+ But notice that this creates some processing
+ overhead.</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteBase /~quux/
-RewriteCond %{REQUEST_FILENAME} <STRONG>-d</STRONG>
-RewriteRule ^(.+<STRONG>[^/]</STRONG>)$ $1<STRONG>/</STRONG> [R]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Webcluster through Homogeneous URL Layout</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-We want to create a homogenous and consistent URL layout over all WWW servers
-on a Intranet webcluster, i.e. all URLs (per definition server local and thus
-server dependent!) become actually server <EM>independed</EM>! What we want is
-to give the WWW namespace a consistent server-independend layout: no URL
-should have to include any physically correct target server. The cluster
-itself should drive us automatically to the physical target host.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-First, the knowledge of the target servers come from (distributed) external
-maps which contain information where our users, groups and entities stay.
-The have the form
-
-<P><PRE>
+RewriteCond %{REQUEST_FILENAME} <strong>-d</strong>
+RewriteRule ^(.+<strong>[^/]</strong>)$ $1<strong>/</strong> [R]
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Webcluster through Homogeneous URL Layout</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>We want to create a homogenous and consistent URL
+ layout over all WWW servers on a Intranet webcluster, i.e.
+ all URLs (per definition server local and thus server
+ dependent!) become actually server <em>independed</em>!
+ What we want is to give the WWW namespace a consistent
+ server-independend layout: no URL should have to include
+ any physically correct target server. The cluster itself
+ should drive us automatically to the physical target
+ host.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ First, the knowledge of the target servers come from
+ (distributed) external maps which contain information
+ where our users, groups and entities stay. The have the
+ form
+<pre>
user1 server_of_user1
user2 server_of_user2
: :
-</PRE><P>
-
-We put them into files <CODE>map.xxx-to-host</CODE>. Second we need to instruct
-all servers to redirect URLs of the forms
+</pre>
-<P><PRE>
+ <p>We put them into files <code>map.xxx-to-host</code>.
+ Second we need to instruct all servers to redirect URLs
+ of the forms</p>
+<pre>
/u/user/anypath
/g/group/anypath
/e/entity/anypath
-</PRE><P>
+</pre>
-to
-
-<P><PRE>
+ <p>to</p>
+<pre>
http://physical-host/u/user/anypath
http://physical-host/g/group/anypath
http://physical-host/e/entity/anypath
-</PRE><P>
-
-when the URL is not locally valid to a server. The following ruleset does
-this for us by the help of the map files (assuming that server0 is a default
-server which will be used if a user has no entry in the map):
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+
+ <p>when the URL is not locally valid to a server. The
+ following ruleset does this for us by the help of the map
+ files (assuming that server0 is a default server which
+ will be used if a user has no entry in the map):</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteMap user-to-host txt:/path/to/map.user-to-host
RewriteMap group-to-host txt:/path/to/map.group-to-host
RewriteMap entity-to-host txt:/path/to/map.entity-to-host
-RewriteRule ^/u/<STRONG>([^/]+)</STRONG>/?(.*) http://<STRONG>${user-to-host:$1|server0}</STRONG>/u/$1/$2
-RewriteRule ^/g/<STRONG>([^/]+)</STRONG>/?(.*) http://<STRONG>${group-to-host:$1|server0}</STRONG>/g/$1/$2
-RewriteRule ^/e/<STRONG>([^/]+)</STRONG>/?(.*) http://<STRONG>${entity-to-host:$1|server0}</STRONG>/e/$1/$2
+RewriteRule ^/u/<strong>([^/]+)</strong>/?(.*) http://<strong>${user-to-host:$1|server0}</strong>/u/$1/$2
+RewriteRule ^/g/<strong>([^/]+)</strong>/?(.*) http://<strong>${group-to-host:$1|server0}</strong>/g/$1/$2
+RewriteRule ^/e/<strong>([^/]+)</strong>/?(.*) http://<strong>${entity-to-host:$1|server0}</strong>/e/$1/$2
RewriteRule ^/([uge])/([^/]+)/?$ /$1/$2/.www/
RewriteRule ^/([uge])/([^/]+)/([^.]+.+) /$1/$2/.www/$3\
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Move Homedirs to Different Webserver</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-A lot of webmaster aksed for a solution to the following situation: They
-wanted to redirect just all homedirs on a webserver to another webserver.
-They usually need such things when establishing a newer webserver which will
-replace the old one over time.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-The solution is trivial with mod_rewrite. On the old webserver we just
-redirect all <CODE>/~user/anypath</CODE> URLs to
-<CODE>http://newserver/~user/anypath</CODE>.
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Move Homedirs to Different Webserver</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>A lot of webmaster aksed for a solution to the
+ following situation: They wanted to redirect just all
+ homedirs on a webserver to another webserver. They usually
+ need such things when establishing a newer webserver which
+ will replace the old one over time.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ The solution is trivial with mod_rewrite. On the old
+ webserver we just redirect all
+ <code>/~user/anypath</code> URLs to
+ <code>http://newserver/~user/anypath</code>.
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
-RewriteRule ^/~(.+) http://<STRONG>newserver</STRONG>/~$1 [R,L]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Structured Homedirs</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Some sites with thousend of users usually use a structured homedir layout,
-i.e. each homedir is in a subdirectory which begins for instance with the
-first character of the username. So, <CODE>/~foo/anypath</CODE> is
-<CODE>/home/<STRONG>f</STRONG>/foo/.www/anypath</CODE> while <CODE>/~bar/anypath</CODE> is
-<CODE>/home/<STRONG>b</STRONG>/bar/.www/anypath</CODE>.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We use the following ruleset to expand the tilde URLs into exactly the above
-layout.
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteRule ^/~(.+) http://<strong>newserver</strong>/~$1 [R,L]
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Structured Homedirs</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Some sites with thousend of users usually use a
+ structured homedir layout, i.e. each homedir is in a
+ subdirectory which begins for instance with the first
+ character of the username. So, <code>/~foo/anypath</code>
+ is <code>/home/<strong>f</strong>/foo/.www/anypath</code>
+ while <code>/~bar/anypath</code> is
+ <code>/home/<strong>b</strong>/bar/.www/anypath</code>.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We use the following ruleset to expand the tilde URLs
+ into exactly the above layout.
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
-RewriteRule ^/~(<STRONG>([a-z])</STRONG>[a-z0-9]+)(.*) /home/<STRONG>$2</STRONG>/$1/.www$3
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Filesystem Reorganisation</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-This really is a hardcore example: a killer application which heavily uses
-per-directory <CODE>RewriteRules</CODE> to get a smooth look and feel on the Web
-while its data structure is never touched or adjusted.
-
-Background: <STRONG><EM>net.sw</EM></STRONG> is my archive of freely available Unix
-software packages, which I started to collect in 1992. It is both my hobby and
-job to to this, because while I'm studying computer science I have also worked
-for many years as a system and network administrator in my spare time. Every
-week I need some sort of software so I created a deep hierarchy of
-directories where I stored the packages:
-
-<P><PRE>
+RewriteRule ^/~(<strong>([a-z])</strong>[a-z0-9]+)(.*) /home/<strong>$2</strong>/$1/.www$3
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Filesystem Reorganisation</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>
+ This really is a hardcore example: a killer application
+ which heavily uses per-directory
+ <code>RewriteRules</code> to get a smooth look and feel
+ on the Web while its data structure is never touched or
+ adjusted. Background: <strong><em>net.sw</em></strong> is
+ my archive of freely available Unix software packages,
+ which I started to collect in 1992. It is both my hobby
+ and job to to this, because while I'm studying computer
+ science I have also worked for many years as a system and
+ network administrator in my spare time. Every week I need
+ some sort of software so I created a deep hierarchy of
+ directories where I stored the packages:
+<pre>
drwxrwxr-x 2 netsw users 512 Aug 3 18:39 Audio/
drwxrwxr-x 2 netsw users 512 Jul 9 14:37 Benchmark/
drwxrwxr-x 12 netsw users 512 Jul 9 00:34 Crypto/
drwxrwxr-x 7 netsw users 512 Jul 9 12:17 System/
drwxrwxr-x 12 netsw users 512 Aug 3 20:15 Typesetting/
drwxrwxr-x 10 netsw users 512 Jul 9 14:08 X11/
-</PRE><P>
-
-In July 1996 I decided to make this archive public to the world via a
-nice Web interface. "Nice" means that I wanted to
-offer an interface where you can browse directly through the archive hierarchy.
-And "nice" means that I didn't wanted to change anything inside this hierarchy
-- not even by putting some CGI scripts at the top of it. Why? Because the
-above structure should be later accessible via FTP as well, and I didn't
-want any Web or CGI stuff to be there.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-The solution has two parts: The first is a set of CGI scripts which create all
-the pages at all directory levels on-the-fly. I put them under
-<CODE>/e/netsw/.www/</CODE> as follows:
-
-<P><PRE>
+</pre>
+
+ <p>In July 1996 I decided to make this archive public to
+ the world via a nice Web interface. "Nice" means that I
+ wanted to offer an interface where you can browse
+ directly through the archive hierarchy. And "nice" means
+ that I didn't wanted to change anything inside this
+ hierarchy - not even by putting some CGI scripts at the
+ top of it. Why? Because the above structure should be
+ later accessible via FTP as well, and I didn't want any
+ Web or CGI stuff to be there.</p>
+ </dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ The solution has two parts: The first is a set of CGI
+ scripts which create all the pages at all directory
+ levels on-the-fly. I put them under
+ <code>/e/netsw/.www/</code> as follows:
+<pre>
-rw-r--r-- 1 netsw users 1318 Aug 1 18:10 .wwwacl
drwxr-xr-x 18 netsw users 512 Aug 5 15:51 DATA/
-rw-rw-rw- 1 netsw users 372982 Aug 5 16:35 LOGFILE
-rwxr-xr-x 1 netsw users 1589 Aug 3 18:43 netsw-search.cgi
-rwxr-xr-x 1 netsw users 1885 Aug 1 17:41 netsw-tree.cgi
-rw-r--r-- 1 netsw users 234 Jul 30 16:35 netsw-unlimit.lst
-</PRE><P>
-
-The <CODE>DATA/</CODE> subdirectory holds the above directory structure, i.e. the
-real <STRONG><EM>net.sw</EM></STRONG> stuff and gets automatically updated via
-<CODE>rdist</CODE> from time to time.
-
-The second part of the problem remains: how to link these two structures
-together into one smooth-looking URL tree? We want to hide the <CODE>DATA/</CODE>
-directory from the user while running the appropriate CGI scripts for the
-various URLs.
-
-Here is the solution: first I put the following into the per-directory
-configuration file in the Document Root of the server to rewrite the announced
-URL <CODE>/net.sw/</CODE> to the internal path <CODE>/e/netsw</CODE>:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+
+ <p>The <code>DATA/</code> subdirectory holds the above
+ directory structure, i.e. the real
+ <strong><em>net.sw</em></strong> stuff and gets
+ automatically updated via <code>rdist</code> from time to
+ time. The second part of the problem remains: how to link
+ these two structures together into one smooth-looking URL
+ tree? We want to hide the <code>DATA/</code> directory
+ from the user while running the appropriate CGI scripts
+ for the various URLs. Here is the solution: first I put
+ the following into the per-directory configuration file
+ in the Document Root of the server to rewrite the
+ announced URL <code>/net.sw/</code> to the internal path
+ <code>/e/netsw</code>:</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteRule ^net.sw$ net.sw/ [R]
RewriteRule ^net.sw/(.*)$ e/netsw/$1
-</PRE></TD></TR></TABLE>
-
-<P>
-The first rule is for requests which miss the trailing slash! The second rule
-does the real thing. And then comes the killer configuration which stays in
-the per-directory config file <CODE>/e/netsw/.www/.wwwacl</CODE>:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>The first rule is for requests which miss the trailing
+ slash! The second rule does the real thing. And then
+ comes the killer configuration which stays in the
+ per-directory config file
+ <code>/e/netsw/.www/.wwwacl</code>:</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
Options ExecCGI FollowSymLinks Includes MultiViews
RewriteEngine on
# by another cgi script
RewriteRule !^netsw-lsdir\.cgi.* - [C]
RewriteRule (.*) netsw-lsdir.cgi/$1
-</PRE></TD></TR></TABLE>
-
-<P>
-Some hints for interpretation:
- <ol>
- <li> Notice the L (last) flag and no substitution field ('-') in the
- forth part
- <li> Notice the ! (not) character and the C (chain) flag
- at the first rule in the last part
- <li> Notice the catch-all pattern in the last rule
- </ol>
-
-</DL>
-
-<P>
-<H2>NCSA imagemap to Apache mod_imap</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-When switching from the NCSA webserver to the more modern Apache webserver a
-lot of people want a smooth transition. So they want pages which use their old
-NCSA <CODE>imagemap</CODE> program to work under Apache with the modern
-<CODE>mod_imap</CODE>. The problem is that there are a lot of
-hyperlinks around which reference the <CODE>imagemap</CODE> program via
-<CODE>/cgi-bin/imagemap/path/to/page.map</CODE>. Under Apache this
-has to read just <CODE>/path/to/page.map</CODE>.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We use a global rule to remove the prefix on-the-fly for all requests:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Some hints for interpretation:</p>
+
+ <ol>
+ <li>Notice the L (last) flag and no substitution field
+ ('-') in the forth part</li>
+
+ <li>Notice the ! (not) character and the C (chain) flag
+ at the first rule in the last part</li>
+
+ <li>Notice the catch-all pattern in the last rule</li>
+ </ol>
+ </dd>
+ </dl>
+
+ <h2>NCSA imagemap to Apache mod_imap</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>When switching from the NCSA webserver to the more
+ modern Apache webserver a lot of people want a smooth
+ transition. So they want pages which use their old NCSA
+ <code>imagemap</code> program to work under Apache with the
+ modern <code>mod_imap</code>. The problem is that there are
+ a lot of hyperlinks around which reference the
+ <code>imagemap</code> program via
+ <code>/cgi-bin/imagemap/path/to/page.map</code>. Under
+ Apache this has to read just
+ <code>/path/to/page.map</code>.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We use a global rule to remove the prefix on-the-fly for
+ all requests:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteRule ^/cgi-bin/imagemap(.*) $1 [PT]
-</PRE></TD></TR></TABLE>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
-</DL>
+ <h2>Search pages in more than one directory</h2>
-<P>
-<H2>Search pages in more than one directory</H2>
-<P>
+ <dl>
+ <dt><strong>Description:</strong></dt>
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Sometimes it is neccessary to let the webserver search for pages in more than
-one directory. Here MultiViews or other techniques cannot help.
+ <dd>Sometimes it is neccessary to let the webserver search
+ for pages in more than one directory. Here MultiViews or
+ other techniques cannot help.</dd>
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We program a explicit ruleset which searches for the files in the directories.
+ <dt><strong>Solution:</strong></dt>
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+ <dd>
+ We program a explicit ruleset which searches for the
+ files in the directories.
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
# first try to find it in custom/...
# ...and if found stop and be happy:
-RewriteCond /your/docroot/<STRONG>dir1</STRONG>/%{REQUEST_FILENAME} -f
-RewriteRule ^(.+) /your/docroot/<STRONG>dir1</STRONG>/$1 [L]
+RewriteCond /your/docroot/<strong>dir1</strong>/%{REQUEST_FILENAME} -f
+RewriteRule ^(.+) /your/docroot/<strong>dir1</strong>/$1 [L]
# second try to find it in pub/...
# ...and if found stop and be happy:
-RewriteCond /your/docroot/<STRONG>dir2</STRONG>/%{REQUEST_FILENAME} -f
-RewriteRule ^(.+) /your/docroot/<STRONG>dir2</STRONG>/$1 [L]
+RewriteCond /your/docroot/<strong>dir2</strong>/%{REQUEST_FILENAME} -f
+RewriteRule ^(.+) /your/docroot/<strong>dir2</strong>/$1 [L]
# else go on for other Alias or ScriptAlias directives,
# etc.
RewriteRule ^(.+) - [PT]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Set Environment Variables According To URL Parts</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Perhaps you want to keep status information between requests and use the URL
-to encode it. But you don't want to use a CGI wrapper for all pages just to
-strip out this information.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We use a rewrite rule to strip out the status information and remember it via
-an environment variable which can be later dereferenced from within XSSI or
-CGI. This way a URL <CODE>/foo/S=java/bar/</CODE> gets translated to
-<CODE>/foo/bar/</CODE> and the environment variable named <CODE>STATUS</CODE> is set
-to the value "java".
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Set Environment Variables According To URL Parts</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Perhaps you want to keep status information between
+ requests and use the URL to encode it. But you don't want
+ to use a CGI wrapper for all pages just to strip out this
+ information.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We use a rewrite rule to strip out the status information
+ and remember it via an environment variable which can be
+ later dereferenced from within XSSI or CGI. This way a
+ URL <code>/foo/S=java/bar/</code> gets translated to
+ <code>/foo/bar/</code> and the environment variable named
+ <code>STATUS</code> is set to the value "java".
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
-RewriteRule ^(.*)/<STRONG>S=([^/]+)</STRONG>/(.*) $1/$3 [E=<STRONG>STATUS:$2</STRONG>]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Virtual User Hosts</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Assume that you want to provide <CODE>www.<STRONG>username</STRONG>.host.domain.com</CODE>
-for the homepage of username via just DNS A records to the same machine and
-without any virtualhosts on this machine.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-For HTTP/1.0 requests there is no solution, but for HTTP/1.1 requests which
-contain a Host: HTTP header we can use the following ruleset to rewrite
-<CODE>http://www.username.host.com/anypath</CODE> internally to
-<CODE>/home/username/anypath</CODE>:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteRule ^(.*)/<strong>S=([^/]+)</strong>/(.*) $1/$3 [E=<strong>STATUS:$2</strong>]
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Virtual User Hosts</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Assume that you want to provide
+ <code>www.<strong>username</strong>.host.domain.com</code>
+ for the homepage of username via just DNS A records to the
+ same machine and without any virtualhosts on this
+ machine.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ For HTTP/1.0 requests there is no solution, but for
+ HTTP/1.1 requests which contain a Host: HTTP header we
+ can use the following ruleset to rewrite
+ <code>http://www.username.host.com/anypath</code>
+ internally to <code>/home/username/anypath</code>:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
-RewriteCond %{<STRONG>HTTP_HOST</STRONG>} ^www\.<STRONG>[^.]+</STRONG>\.host\.com$
+RewriteCond %{<strong>HTTP_HOST</strong>} ^www\.<strong>[^.]+</strong>\.host\.com$
RewriteRule ^(.+) %{HTTP_HOST}$1 [C]
-RewriteRule ^www\.<STRONG>([^.]+)</STRONG>\.host\.com(.*) /home/<STRONG>$1</STRONG>$2
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Redirect Homedirs For Foreigners</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-We want to redirect homedir URLs to another webserver
-<CODE>www.somewhere.com</CODE> when the requesting user does not stay in the local
-domain <CODE>ourdomain.com</CODE>. This is sometimes used in virtual host
-contexts.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-Just a rewrite condition:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteRule ^www\.<strong>([^.]+)</strong>\.host\.com(.*) /home/<strong>$1</strong>$2
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Redirect Homedirs For Foreigners</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>We want to redirect homedir URLs to another webserver
+ <code>www.somewhere.com</code> when the requesting user
+ does not stay in the local domain
+ <code>ourdomain.com</code>. This is sometimes used in
+ virtual host contexts.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ Just a rewrite condition:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
-RewriteCond %{REMOTE_HOST} <STRONG>!^.+\.ourdomain\.com$</STRONG>
+RewriteCond %{REMOTE_HOST} <strong>!^.+\.ourdomain\.com$</strong>
RewriteRule ^(/~.+) http://www.somewhere.com/$1 [R,L]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Redirect Failing URLs To Other Webserver</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-A typical FAQ about URL rewriting is how to redirect failing requests on
-webserver A to webserver B. Usually this is done via ErrorDocument
-CGI-scripts in Perl, but there is also a mod_rewrite solution. But notice that
-this is less performant than using a ErrorDocument CGI-script!
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-The first solution has the best performance but less flexibility and is less
-error safe:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Redirect Failing URLs To Other Webserver</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>A typical FAQ about URL rewriting is how to redirect
+ failing requests on webserver A to webserver B. Usually
+ this is done via ErrorDocument CGI-scripts in Perl, but
+ there is also a mod_rewrite solution. But notice that this
+ is less performant than using a ErrorDocument
+ CGI-script!</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ The first solution has the best performance but less
+ flexibility and is less error safe:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
-RewriteCond /your/docroot/%{REQUEST_FILENAME} <STRONG>!-f</STRONG>
-RewriteRule ^(.+) http://<STRONG>webserverB</STRONG>.dom/$1
-</PRE></TD></TR></TABLE>
-
-<P>
-The problem here is that this will only work for pages inside the
-DocumentRoot. While you can add more Conditions (for instance to also handle
-homedirs, etc.) there is better variant:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteCond /your/docroot/%{REQUEST_FILENAME} <strong>!-f</strong>
+RewriteRule ^(.+) http://<strong>webserverB</strong>.dom/$1
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>The problem here is that this will only work for pages
+ inside the DocumentRoot. While you can add more
+ Conditions (for instance to also handle homedirs, etc.)
+ there is better variant:</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
-RewriteCond %{REQUEST_URI} <STRONG>!-U</STRONG>
-RewriteRule ^(.+) http://<STRONG>webserverB</STRONG>.dom/$1
-</PRE></TD></TR></TABLE>
-
-<P>
-This uses the URL look-ahead feature of mod_rewrite. The result is that this
-will work for all types of URLs and is a safe way. But it does a performance
-impact on the webserver, because for every request there is one more internal
-subrequest. So, if your webserver runs on a powerful CPU, use this one. If it
-is a slow machine, use the first approach or better a ErrorDocument
-CGI-script.
-
-</DL>
-
-<P>
-<H2>Extended Redirection</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Sometimes we need more control (concerning the character escaping mechanism)
-of URLs on redirects. Usually the Apache kernels URL escape function also
-escapes anchors, i.e. URLs like "url#anchor". You cannot use this directly on
-redirects with mod_rewrite because the uri_escape() function of Apache would
-also escape the hash character. How can we redirect to such a URL?
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We have to use a kludge by the use of a NPH-CGI script which does the redirect
-itself. Because here no escaping is done (NPH=non-parseable headers). First
-we introduce a new URL scheme <CODE>xredirect:</CODE> by the following per-server
-config-line (should be one of the last rewrite rules):
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteCond %{REQUEST_URI} <strong>!-U</strong>
+RewriteRule ^(.+) http://<strong>webserverB</strong>.dom/$1
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>This uses the URL look-ahead feature of mod_rewrite.
+ The result is that this will work for all types of URLs
+ and is a safe way. But it does a performance impact on
+ the webserver, because for every request there is one
+ more internal subrequest. So, if your webserver runs on a
+ powerful CPU, use this one. If it is a slow machine, use
+ the first approach or better a ErrorDocument
+ CGI-script.</p>
+ </dd>
+ </dl>
+
+ <h2>Extended Redirection</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Sometimes we need more control (concerning the
+ character escaping mechanism) of URLs on redirects. Usually
+ the Apache kernels URL escape function also escapes
+ anchors, i.e. URLs like "url#anchor". You cannot use this
+ directly on redirects with mod_rewrite because the
+ uri_escape() function of Apache would also escape the hash
+ character. How can we redirect to such a URL?</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We have to use a kludge by the use of a NPH-CGI script
+ which does the redirect itself. Because here no escaping
+ is done (NPH=non-parseable headers). First we introduce a
+ new URL scheme <code>xredirect:</code> by the following
+ per-server config-line (should be one of the last rewrite
+ rules):
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteRule ^xredirect:(.+) /path/to/nph-xredirect.cgi/$1 \
[T=application/x-httpd-cgi,L]
-</PRE></TD></TR></TABLE>
-
-<P>
-This forces all URLs prefixed with <CODE>xredirect:</CODE> to be piped through the
-<CODE>nph-xredirect.cgi</CODE> program. And this program just looks like:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
-<PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>This forces all URLs prefixed with
+ <code>xredirect:</code> to be piped through the
+ <code>nph-xredirect.cgi</code> program. And this program
+ just looks like:</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
#!/path/to/perl
##
## nph-xredirect.cgi -- NPH/CGI script for extended redirects
print "</html>\n";
##EOF##
-</PRE>
-</PRE></TD></TR></TABLE>
-
-<P>
-This provides you with the functionality to do redirects to all URL schemes,
-i.e. including the one which are not directly accepted by mod_rewrite. For
-instance you can now also redirect to <CODE>news:newsgroup</CODE> via
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>This provides you with the functionality to do
+ redirects to all URL schemes, i.e. including the one
+ which are not directly accepted by mod_rewrite. For
+ instance you can now also redirect to
+ <code>news:newsgroup</code> via</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteRule ^anyurl xredirect:news:newsgroup
-</PRE></TD></TR></TABLE>
-
-<P>
-Notice: You have not to put [R] or [R,L] to the above rule because the
-<CODE>xredirect:</CODE> need to be expanded later by our special "pipe through"
-rule above.
-
-</DL>
-
-<P>
-<H2>Archive Access Multiplexer</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Do you know the great CPAN (Comprehensive Perl Archive Network) under <A
-HREF="http://www.perl.com/CPAN">http://www.perl.com/CPAN</A>? This does a
-redirect to one of several FTP servers around the world which carry a CPAN
-mirror and is approximately near the location of the requesting client.
-Actually this can be called an FTP access multiplexing service. While CPAN
-runs via CGI scripts, how can a similar approach implemented via mod_rewrite?
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-First we notice that from version 3.0.0 mod_rewrite can also use the "ftp:"
-scheme on redirects. And second, the location approximation can be done by a
-rewritemap over the top-level domain of the client. With a tricky chained
-ruleset we can use this top-level domain as a key to our multiplexing map.
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Notice: You have not to put [R] or [R,L] to the above
+ rule because the <code>xredirect:</code> need to be
+ expanded later by our special "pipe through" rule
+ above.</p>
+ </dd>
+ </dl>
+
+ <h2>Archive Access Multiplexer</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Do you know the great CPAN (Comprehensive Perl Archive
+ Network) under <a
+ href="http://www.perl.com/CPAN">http://www.perl.com/CPAN</a>?
+ This does a redirect to one of several FTP servers around
+ the world which carry a CPAN mirror and is approximately
+ near the location of the requesting client. Actually this
+ can be called an FTP access multiplexing service. While
+ CPAN runs via CGI scripts, how can a similar approach
+ implemented via mod_rewrite?</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ First we notice that from version 3.0.0 mod_rewrite can
+ also use the "ftp:" scheme on redirects. And second, the
+ location approximation can be done by a rewritemap over
+ the top-level domain of the client. With a tricky chained
+ ruleset we can use this top-level domain as a key to our
+ multiplexing map.
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteMap multiplex txt:/path/to/map.cxan
RewriteRule ^/CxAN/(.*) %{REMOTE_HOST}::$1 [C]
-RewriteRule ^.+\.<STRONG>([a-zA-Z]+)</STRONG>::(.*)$ ${multiplex:<STRONG>$1</STRONG>|ftp.default.dom}$2 [R,L]
-</PRE></TD></TR></TABLE>
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteRule ^.+\.<strong>([a-zA-Z]+)</strong>::(.*)$ ${multiplex:<strong>$1</strong>|ftp.default.dom}$2 [R,L]
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
##
## map.cxan -- Multiplexing Map for CxAN
##
com ftp://ftp.cxan.com/CxAN/
:
##EOF##
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Time-Dependend Rewriting</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-When tricks like time-dependend content should happen a lot of webmasters
-still use CGI scripts which do for instance redirects to specialized pages.
-How can it be done via mod_rewrite?
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-There are a lot of variables named <CODE>TIME_xxx</CODE> for rewrite conditions.
-In conjunction with the special lexicographic comparison patterns <STRING,
->STRING and =STRING we can do time-dependend redirects:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Time-Dependend Rewriting</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>When tricks like time-dependend content should happen a
+ lot of webmasters still use CGI scripts which do for
+ instance redirects to specialized pages. How can it be done
+ via mod_rewrite?</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ There are a lot of variables named <code>TIME_xxx</code>
+ for rewrite conditions. In conjunction with the special
+ lexicographic comparison patterns <STRING, >STRING
+ and =STRING we can do time-dependend redirects:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteCond %{TIME_HOUR}%{TIME_MIN} >0700
RewriteCond %{TIME_HOUR}%{TIME_MIN} <1900
RewriteRule ^foo\.html$ foo.day.html
RewriteRule ^foo\.html$ foo.night.html
-</PRE></TD></TR></TABLE>
-
-<P>
-This provides the content of <CODE>foo.day.html</CODE> under the URL
-<CODE>foo.html</CODE> from 07:00-19:00 and at the remaining time the contents of
-<CODE>foo.night.html</CODE>. Just a nice feature for a homepage...
-
-</DL>
-
-<P>
-<H2>Backward Compatibility for YYYY to XXXX migration</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-How can we make URLs backward compatible (still existing virtually) after
-migrating document.YYYY to document.XXXX, e.g. after translating a bunch of
-.html files to .phtml?
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We just rewrite the name to its basename and test for existence of the new
-extension. If it exists, we take that name, else we rewrite the URL to its
-original state.
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>This provides the content of <code>foo.day.html</code>
+ under the URL <code>foo.html</code> from 07:00-19:00 and
+ at the remaining time the contents of
+ <code>foo.night.html</code>. Just a nice feature for a
+ homepage...</p>
+ </dd>
+ </dl>
+
+ <h2>Backward Compatibility for YYYY to XXXX migration</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>How can we make URLs backward compatible (still
+ existing virtually) after migrating document.YYYY to
+ document.XXXX, e.g. after translating a bunch of .html
+ files to .phtml?</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We just rewrite the name to its basename and test for
+ existence of the new extension. If it exists, we take
+ that name, else we rewrite the URL to its original state.
+
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
# backward compatibility ruleset for
# rewriting document.html to document.phtml
# when and only when document.phtml exists
# else reverse the previous basename cutout
RewriteCond %{ENV:WasHTML} ^yes$
RewriteRule ^(.*)$ $1.html
-</PRE></TD></TR></TABLE>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h1>Content Handling</h1>
-</DL>
+ <h2>From Old to New (intern)</h2>
-<H1>Content Handling</H1>
+ <dl>
+ <dt><strong>Description:</strong></dt>
-<P>
-<H2>From Old to New (intern)</H2>
-<P>
+ <dd>Assume we have recently renamed the page
+ <code>bar.html</code> to <code>foo.html</code> and now want
+ to provide the old URL for backward compatibility. Actually
+ we want that users of the old URL even not recognize that
+ the pages was renamed.</dd>
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Assume we have recently renamed the page <CODE>bar.html</CODE> to
-<CODE>foo.html</CODE> and now want to provide the old URL for backward
-compatibility. Actually we want that users of the old URL even not recognize
-that the pages was renamed.
+ <dt><strong>Solution:</strong></dt>
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We rewrite the old URL to the new one internally via the following rule:
+ <dd>
+ We rewrite the old URL to the new one internally via the
+ following rule:
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteBase /~quux/
-RewriteRule ^<STRONG>foo</STRONG>\.html$ <STRONG>bar</STRONG>.html
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>From Old to New (extern)</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Assume again that we have recently renamed the page <CODE>bar.html</CODE> to
-<CODE>foo.html</CODE> and now want to provide the old URL for backward
-compatibility. But this time we want that the users of the old URL get hinted
-to the new one, i.e. their browsers Location field should change, too.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We force a HTTP redirect to the new URL which leads to a change of the
-browsers and thus the users view:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteRule ^<strong>foo</strong>\.html$ <strong>bar</strong>.html
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>From Old to New (extern)</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Assume again that we have recently renamed the page
+ <code>bar.html</code> to <code>foo.html</code> and now want
+ to provide the old URL for backward compatibility. But this
+ time we want that the users of the old URL get hinted to
+ the new one, i.e. their browsers Location field should
+ change, too.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We force a HTTP redirect to the new URL which leads to a
+ change of the browsers and thus the users view:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteBase /~quux/
-RewriteRule ^<STRONG>foo</STRONG>\.html$ <STRONG>bar</STRONG>.html [<STRONG>R</STRONG>]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Browser Dependend Content</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-At least for important top-level pages it is sometimes necesarry to provide
-the optimum of browser dependend content, i.e. one has to provide a maximum
-version for the latest Netscape variants, a minimum version for the Lynx
-browsers and a average feature version for all others.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We cannot use content negotiation because the browsers do not provide their
-type in that form. Instead we have to act on the HTTP header "User-Agent".
-The following condig does the following: If the HTTP header "User-Agent"
-begins with "Mozilla/3", the page <CODE>foo.html</CODE> is rewritten to
-<CODE>foo.NS.html</CODE> and and the rewriting stops. If the browser is "Lynx" or
-"Mozilla" of version 1 or 2 the URL becomes <CODE>foo.20.html</CODE>. All other
-browsers receive page <CODE>foo.32.html</CODE>. This is done by the following
-ruleset:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
-RewriteCond %{HTTP_USER_AGENT} ^<STRONG>Mozilla/3</STRONG>.*
-RewriteRule ^foo\.html$ foo.<STRONG>NS</STRONG>.html [<STRONG>L</STRONG>]
-
-RewriteCond %{HTTP_USER_AGENT} ^<STRONG>Lynx/</STRONG>.* [OR]
-RewriteCond %{HTTP_USER_AGENT} ^<STRONG>Mozilla/[12]</STRONG>.*
-RewriteRule ^foo\.html$ foo.<STRONG>20</STRONG>.html [<STRONG>L</STRONG>]
-
-RewriteRule ^foo\.html$ foo.<STRONG>32</STRONG>.html [<STRONG>L</STRONG>]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Dynamic Mirror</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Assume there are nice webpages on remote hosts we want to bring into our
-namespace. For FTP servers we would use the <CODE>mirror</CODE> program which
-actually maintains an explicit up-to-date copy of the remote data on the local
-machine. For a webserver we could use the program <CODE>webcopy</CODE> which acts
-similar via HTTP. But both techniques have one major drawback: The local copy
-is always just as up-to-date as often we run the program. It would be much
-better if the mirror is not a static one we have to establish explicitly.
-Instead we want a dynamic mirror with data which gets updated automatically
-when there is need (updated data on the remote host).
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-To provide this feature we map the remote webpage or even the complete remote
-webarea to our namespace by the use of the <I>Proxy Throughput</I> feature
-(flag [P]):
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteRule ^<strong>foo</strong>\.html$ <strong>bar</strong>.html [<strong>R</strong>]
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Browser Dependend Content</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>At least for important top-level pages it is sometimes
+ necesarry to provide the optimum of browser dependend
+ content, i.e. one has to provide a maximum version for the
+ latest Netscape variants, a minimum version for the Lynx
+ browsers and a average feature version for all others.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We cannot use content negotiation because the browsers do
+ not provide their type in that form. Instead we have to
+ act on the HTTP header "User-Agent". The following condig
+ does the following: If the HTTP header "User-Agent"
+ begins with "Mozilla/3", the page <code>foo.html</code>
+ is rewritten to <code>foo.NS.html</code> and and the
+ rewriting stops. If the browser is "Lynx" or "Mozilla" of
+ version 1 or 2 the URL becomes <code>foo.20.html</code>.
+ All other browsers receive page <code>foo.32.html</code>.
+ This is done by the following ruleset:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
+RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/3</strong>.*
+RewriteRule ^foo\.html$ foo.<strong>NS</strong>.html [<strong>L</strong>]
+
+RewriteCond %{HTTP_USER_AGENT} ^<strong>Lynx/</strong>.* [OR]
+RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/[12]</strong>.*
+RewriteRule ^foo\.html$ foo.<strong>20</strong>.html [<strong>L</strong>]
+
+RewriteRule ^foo\.html$ foo.<strong>32</strong>.html [<strong>L</strong>]
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Dynamic Mirror</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Assume there are nice webpages on remote hosts we want
+ to bring into our namespace. For FTP servers we would use
+ the <code>mirror</code> program which actually maintains an
+ explicit up-to-date copy of the remote data on the local
+ machine. For a webserver we could use the program
+ <code>webcopy</code> which acts similar via HTTP. But both
+ techniques have one major drawback: The local copy is
+ always just as up-to-date as often we run the program. It
+ would be much better if the mirror is not a static one we
+ have to establish explicitly. Instead we want a dynamic
+ mirror with data which gets updated automatically when
+ there is need (updated data on the remote host).</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ To provide this feature we map the remote webpage or even
+ the complete remote webarea to our namespace by the use
+ of the <i>Proxy Throughput</i> feature (flag [P]):
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteBase /~quux/
-RewriteRule ^<STRONG>hotsheet/</STRONG>(.*)$ <STRONG>http://www.tstimpreso.com/hotsheet/</STRONG>$1 [<STRONG>P</STRONG>]
-</PRE></TD></TR></TABLE>
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteRule ^<strong>hotsheet/</strong>(.*)$ <strong>http://www.tstimpreso.com/hotsheet/</strong>$1 [<strong>P</strong>]
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteBase /~quux/
-RewriteRule ^<STRONG>usa-news\.html</STRONG>$ <STRONG>http://www.quux-corp.com/news/index.html</STRONG> [<STRONG>P</STRONG>]
-</PRE></TD></TR></TABLE>
+RewriteRule ^<strong>usa-news\.html</strong>$ <strong>http://www.quux-corp.com/news/index.html</strong> [<strong>P</strong>]
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
-</DL>
+ <h2>Reverse Dynamic Mirror</h2>
-<P>
-<H2>Reverse Dynamic Mirror</H2>
-<P>
+ <dl>
+ <dt><strong>Description:</strong></dt>
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-...
+ <dd>...</dd>
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
+ <dt><strong>Solution:</strong></dt>
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+ <dd>
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteCond /mirror/of/remotesite/$1 -U
RewriteRule ^http://www\.remotesite\.com/(.*)$ /mirror/of/remotesite/$1
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Retrieve Missing Data from Intranet</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-This is a tricky way of virtually running a corporates (external) Internet
-webserver (<CODE>www.quux-corp.dom</CODE>), while actually keeping and maintaining
-its data on a (internal) Intranet webserver
-(<CODE>www2.quux-corp.dom</CODE>) which is protected by a firewall. The
-trick is that on the external webserver we retrieve the requested data
-on-the-fly from the internal one.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-First, we have to make sure that our firewall still protects the internal
-webserver and that only the external webserver is allowed to retrieve data
-from it. For a packet-filtering firewall we could for instance configure a
-firewall ruleset like the following:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
-<STRONG>ALLOW</STRONG> Host www.quux-corp.dom Port >1024 --> Host www2.quux-corp.dom Port <STRONG>80</STRONG>
-<STRONG>DENY</STRONG> Host * Port * --> Host www2.quux-corp.dom Port <STRONG>80</STRONG>
-</PRE></TD></TR></TABLE>
-
-<P>
-Just adjust it to your actual configuration syntax. Now we can establish the
-mod_rewrite rules which request the missing data in the background through the
-proxy throughput feature:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Retrieve Missing Data from Intranet</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>This is a tricky way of virtually running a corporates
+ (external) Internet webserver
+ (<code>www.quux-corp.dom</code>), while actually keeping
+ and maintaining its data on a (internal) Intranet webserver
+ (<code>www2.quux-corp.dom</code>) which is protected by a
+ firewall. The trick is that on the external webserver we
+ retrieve the requested data on-the-fly from the internal
+ one.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ First, we have to make sure that our firewall still
+ protects the internal webserver and that only the
+ external webserver is allowed to retrieve data from it.
+ For a packet-filtering firewall we could for instance
+ configure a firewall ruleset like the following:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
+<strong>ALLOW</strong> Host www.quux-corp.dom Port >1024 --> Host www2.quux-corp.dom Port <strong>80</strong>
+<strong>DENY</strong> Host * Port * --> Host www2.quux-corp.dom Port <strong>80</strong>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Just adjust it to your actual configuration syntax.
+ Now we can establish the mod_rewrite rules which request
+ the missing data in the background through the proxy
+ throughput feature:</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteRule ^/~([^/]+)/?(.*) /home/$1/.www/$2
-RewriteCond %{REQUEST_FILENAME} <STRONG>!-f</STRONG>
-RewriteCond %{REQUEST_FILENAME} <STRONG>!-d</STRONG>
-RewriteRule ^/home/([^/]+)/.www/?(.*) http://<STRONG>www2</STRONG>.quux-corp.dom/~$1/pub/$2 [<STRONG>P</STRONG>]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Load Balancing</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Suppose we want to load balance the traffic to <CODE>www.foo.com</CODE> over
-<CODE>www[0-5].foo.com</CODE> (a total of 6 servers). How can this be done?
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-There are a lot of possible solutions for this problem. We will discuss first
-a commonly known DNS-based variant and then the special one with mod_rewrite:
-
-<ol>
-<li><STRONG>DNS Round-Robin</STRONG>
-
-<P>
-The simplest method for load-balancing is to use the DNS round-robin feature
-of BIND. Here you just configure <CODE>www[0-9].foo.com</CODE> as usual in your
-DNS with A(address) records, e.g.
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteCond %{REQUEST_FILENAME} <strong>!-f</strong>
+RewriteCond %{REQUEST_FILENAME} <strong>!-d</strong>
+RewriteRule ^/home/([^/]+)/.www/?(.*) http://<strong>www2</strong>.quux-corp.dom/~$1/pub/$2 [<strong>P</strong>]
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Load Balancing</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Suppose we want to load balance the traffic to
+ <code>www.foo.com</code> over <code>www[0-5].foo.com</code>
+ (a total of 6 servers). How can this be done?</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ There are a lot of possible solutions for this problem.
+ We will discuss first a commonly known DNS-based variant
+ and then the special one with mod_rewrite:
+
+ <ol>
+ <li>
+ <strong>DNS Round-Robin</strong>
+
+ <p>The simplest method for load-balancing is to use
+ the DNS round-robin feature of BIND. Here you just
+ configure <code>www[0-9].foo.com</code> as usual in
+ your DNS with A(address) records, e.g.</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
www0 IN A 1.2.3.1
www1 IN A 1.2.3.2
www2 IN A 1.2.3.3
www3 IN A 1.2.3.4
www4 IN A 1.2.3.5
www5 IN A 1.2.3.6
-</PRE></TD></TR></TABLE>
-
-<P>
-Then you additionally add the following entry:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Then you additionally add the following entry:</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
www IN CNAME www0.foo.com.
IN CNAME www1.foo.com.
IN CNAME www2.foo.com.
IN CNAME www4.foo.com.
IN CNAME www5.foo.com.
IN CNAME www6.foo.com.
-</PRE></TD></TR></TABLE>
-
-<P>
-Notice that this seems wrong, but is actually an intended feature of BIND and
-can be used in this way. However, now when <CODE>www.foo.com</CODE> gets resolved,
-BIND gives out <CODE>www0-www6</CODE> - but in a slightly permutated/rotated order
-every time. This way the clients are spread over the various servers.
-
-But notice that this not a perfect load balancing scheme, because DNS resolve
-information gets cached by the other nameservers on the net, so once a client
-has resolved <CODE>www.foo.com</CODE> to a particular <CODE>wwwN.foo.com</CODE>, all
-subsequent requests also go to this particular name <CODE>wwwN.foo.com</CODE>. But
-the final result is ok, because the total sum of the requests are really
-spread over the various webservers.
-
-<P>
-<li><STRONG>DNS Load-Balancing</STRONG>
-
-<P>
-A sophisticated DNS-based method for load-balancing is to use the program
-<CODE>lbnamed</CODE> which can be found at <A
-HREF="http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html">http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html</A>.
-It is a Perl 5 program in conjunction with auxilliary tools which provides a
-real load-balancing for DNS.
-
-<P>
-<li><STRONG>Proxy Throughput Round-Robin</STRONG>
-
-<P>
-In this variant we use mod_rewrite and its proxy throughput feature. First we
-dedicate <CODE>www0.foo.com</CODE> to be actually <CODE>www.foo.com</CODE> by using a
-single
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Notice that this seems wrong, but is actually an
+ intended feature of BIND and can be used in this way.
+ However, now when <code>www.foo.com</code> gets
+ resolved, BIND gives out <code>www0-www6</code> - but
+ in a slightly permutated/rotated order every time.
+ This way the clients are spread over the various
+ servers. But notice that this not a perfect load
+ balancing scheme, because DNS resolve information
+ gets cached by the other nameservers on the net, so
+ once a client has resolved <code>www.foo.com</code>
+ to a particular <code>wwwN.foo.com</code>, all
+ subsequent requests also go to this particular name
+ <code>wwwN.foo.com</code>. But the final result is
+ ok, because the total sum of the requests are really
+ spread over the various webservers.</p>
+ </li>
+
+ <li>
+ <strong>DNS Load-Balancing</strong>
+
+ <p>A sophisticated DNS-based method for
+ load-balancing is to use the program
+ <code>lbnamed</code> which can be found at <a
+ href="http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html">
+ http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html</a>.
+ It is a Perl 5 program in conjunction with auxilliary
+ tools which provides a real load-balancing for
+ DNS.</p>
+ </li>
+
+ <li>
+ <strong>Proxy Throughput Round-Robin</strong>
+
+ <p>In this variant we use mod_rewrite and its proxy
+ throughput feature. First we dedicate
+ <code>www0.foo.com</code> to be actually
+ <code>www.foo.com</code> by using a single</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
www IN CNAME www0.foo.com.
-</PRE></TD></TR></TABLE>
-
-<P>
-entry in the DNS. Then we convert <CODE>www0.foo.com</CODE> to a proxy-only
-server, i.e. we configure this machine so all arriving URLs are just pushed
-through the internal proxy to one of the 5 other servers (<CODE>www1-www5</CODE>).
-To accomplish this we first establish a ruleset which contacts a load
-balancing script <CODE>lb.pl</CODE> for all URLs.
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>entry in the DNS. Then we convert
+ <code>www0.foo.com</code> to a proxy-only server,
+ i.e. we configure this machine so all arriving URLs
+ are just pushed through the internal proxy to one of
+ the 5 other servers (<code>www1-www5</code>). To
+ accomplish this we first establish a ruleset which
+ contacts a load balancing script <code>lb.pl</code>
+ for all URLs.</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteMap lb prg:/path/to/lb.pl
RewriteRule ^/(.+)$ ${lb:$1} [P,L]
-</PRE></TD></TR></TABLE>
-
-<P>
-Then we write <CODE>lb.pl</CODE>:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Then we write <code>lb.pl</code>:</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
#!/path/to/perl
##
## lb.pl -- load balancing script
}
##EOF##
-</PRE></TD></TR></TABLE>
-
-<P>
-A last notice: Why is this useful? Seems like <CODE>www0.foo.com</CODE> still is
-overloaded? The answer is yes, it is overloaded, but with plain proxy
-throughput requests, only! All SSI, CGI, ePerl, etc. processing is completely
-done on the other machines. This is the essential point.
-
-<P>
-<li><STRONG>Hardware/TCP Round-Robin</STRONG>
-
-<P>
-There is a hardware solution available, too. Cisco has a beast called
-LocalDirector which does a load balancing at the TCP/IP level. Actually this
-is some sort of a circuit level gateway in front of a webcluster. If you have
-enough money and really need a solution with high performance, use this one.
-
-</ol>
-
-</DL>
-
-<P>
-<H2>Reverse Proxy</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-...
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>A last notice: Why is this useful? Seems like
+ <code>www0.foo.com</code> still is overloaded? The
+ answer is yes, it is overloaded, but with plain proxy
+ throughput requests, only! All SSI, CGI, ePerl, etc.
+ processing is completely done on the other machines.
+ This is the essential point.</p>
+ </li>
+
+ <li>
+ <strong>Hardware/TCP Round-Robin</strong>
+
+ <p>There is a hardware solution available, too. Cisco
+ has a beast called LocalDirector which does a load
+ balancing at the TCP/IP level. Actually this is some
+ sort of a circuit level gateway in front of a
+ webcluster. If you have enough money and really need
+ a solution with high performance, use this one.</p>
+ </li>
+ </ol>
+ </dd>
+ </dl>
+
+ <h2>Reverse Proxy</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>...</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
##
## apache-rproxy.conf -- Apache configuration for Reverse Proxy Usage
##
ProxyPassReverse / http://www4.foo.dom/
ProxyPassReverse / http://www5.foo.dom/
ProxyPassReverse / http://www6.foo.dom/
-</PRE></TD></TR></TABLE>
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
##
## apache-rproxy.conf-servers -- Apache/mod_rewrite selection table
##
# list of backend servers which serve dynamically
# generated page (CGI programs or mod_perl scripts)
dynamic www5.foo.dom|www6.foo.dom
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>New MIME-type, New Service</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-On the net there are a lot of nifty CGI programs. But their usage is usually
-boring, so a lot of webmaster don't use them. Even Apache's Action handler
-feature for MIME-types is only appropriate when the CGI programs don't need
-special URLs (actually PATH_INFO and QUERY_STRINGS) as their input.
-
-First, let us configure a new file type with extension <CODE>.scgi</CODE>
-(for secure CGI) which will be processed by the popular <CODE>cgiwrap</CODE>
-program. The problem here is that for instance we use a Homogeneous URL Layout
-(see above) a file inside the user homedirs has the URL
-<CODE>/u/user/foo/bar.scgi</CODE>. But <CODE>cgiwrap</CODE> needs the URL in the form
-<CODE>/~user/foo/bar.scgi/</CODE>. The following rule solves the problem:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
-RewriteRule ^/[uge]/<STRONG>([^/]+)</STRONG>/\.www/(.+)\.scgi(.*) ...
-... /internal/cgi/user/cgiwrap/~<STRONG>$1</STRONG>/$2.scgi$3 [NS,<STRONG>T=application/x-http-cgi</STRONG>]
-</PRE></TD></TR></TABLE>
-
-<P>
-Or assume we have some more nifty programs:
-<CODE>wwwlog</CODE> (which displays the <CODE>access.log</CODE> for a URL subtree and
-<CODE>wwwidx</CODE> (which runs Glimpse on a URL subtree). We have to
-provide the URL area to these programs so they know on which area
-they have to act on. But usually this ugly, because they are all the
-times still requested from that areas, i.e. typically we would run
-the <CODE>swwidx</CODE> program from within <CODE>/u/user/foo/</CODE> via
-hyperlink to
-
-<P><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>New MIME-type, New Service</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>
+ On the net there are a lot of nifty CGI programs. But
+ their usage is usually boring, so a lot of webmaster
+ don't use them. Even Apache's Action handler feature for
+ MIME-types is only appropriate when the CGI programs
+ don't need special URLs (actually PATH_INFO and
+ QUERY_STRINGS) as their input. First, let us configure a
+ new file type with extension <code>.scgi</code> (for
+ secure CGI) which will be processed by the popular
+ <code>cgiwrap</code> program. The problem here is that
+ for instance we use a Homogeneous URL Layout (see above)
+ a file inside the user homedirs has the URL
+ <code>/u/user/foo/bar.scgi</code>. But
+ <code>cgiwrap</code> needs the URL in the form
+ <code>/~user/foo/bar.scgi/</code>. The following rule
+ solves the problem:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
+RewriteRule ^/[uge]/<strong>([^/]+)</strong>/\.www/(.+)\.scgi(.*) ...
+... /internal/cgi/user/cgiwrap/~<strong>$1</strong>/$2.scgi$3 [NS,<strong>T=application/x-http-cgi</strong>]
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Or assume we have some more nifty programs:
+ <code>wwwlog</code> (which displays the
+ <code>access.log</code> for a URL subtree and
+ <code>wwwidx</code> (which runs Glimpse on a URL
+ subtree). We have to provide the URL area to these
+ programs so they know on which area they have to act on.
+ But usually this ugly, because they are all the times
+ still requested from that areas, i.e. typically we would
+ run the <code>swwidx</code> program from within
+ <code>/u/user/foo/</code> via hyperlink to</p>
+<pre>
/internal/cgi/user/swwidx?i=/u/user/foo/
-</PRE><P>
-
-which is ugly. Because we have to hard-code <STRONG>both</STRONG> the location of the
-area <STRONG>and</STRONG> the location of the CGI inside the hyperlink. When we have to
-reorganise or area, we spend a lot of time changing the various hyperlinks.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-The solution here is to provide a special new URL format which automatically
-leads to the proper CGI invocation. We configure the following:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+
+ <p>which is ugly. Because we have to hard-code
+ <strong>both</strong> the location of the area
+ <strong>and</strong> the location of the CGI inside the
+ hyperlink. When we have to reorganise or area, we spend a
+ lot of time changing the various hyperlinks.</p>
+ </dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ The solution here is to provide a special new URL format
+ which automatically leads to the proper CGI invocation.
+ We configure the following:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteRule ^/([uge])/([^/]+)(/?.*)/\* /internal/cgi/user/wwwidx?i=/$1/$2$3/
RewriteRule ^/([uge])/([^/]+)(/?.*):log /internal/cgi/user/wwwlog?f=/$1/$2$3
-</PRE></TD></TR></TABLE>
-
-<P>
-Now the hyperlink to search at <CODE>/u/user/foo/</CODE> reads only
-
-<P><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Now the hyperlink to search at
+ <code>/u/user/foo/</code> reads only</p>
+<pre>
HREF="*"
-</PRE><P>
-
-which internally gets automatically transformed to
+</pre>
-<P><PRE>
+ <p>which internally gets automatically transformed to</p>
+<pre>
/internal/cgi/user/wwwidx?i=/u/user/foo/
-</PRE><P>
-
-The same approach leads to an invocation for the access log CGI
-program when the hyperlink <CODE>:log</CODE> gets used.
-
-</DL>
-
-<P>
-<H2>From Static to Dynamic</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-How can we transform a static page <CODE>foo.html</CODE> into a dynamic variant
-<CODE>foo.cgi</CODE> in a seemless way, i.e. without notice by the browser/user.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We just rewrite the URL to the CGI-script and force the correct MIME-type so
-it gets really run as a CGI-script. This way a request to
-<CODE>/~quux/foo.html</CODE> internally leads to the invokation of
-<CODE>/~quux/foo.cgi</CODE>.
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+
+ <p>The same approach leads to an invocation for the
+ access log CGI program when the hyperlink
+ <code>:log</code> gets used.</p>
+ </dd>
+ </dl>
+
+ <h2>From Static to Dynamic</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>How can we transform a static page
+ <code>foo.html</code> into a dynamic variant
+ <code>foo.cgi</code> in a seemless way, i.e. without notice
+ by the browser/user.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We just rewrite the URL to the CGI-script and force the
+ correct MIME-type so it gets really run as a CGI-script.
+ This way a request to <code>/~quux/foo.html</code>
+ internally leads to the invokation of
+ <code>/~quux/foo.cgi</code>.
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteBase /~quux/
-RewriteRule ^foo\.<STRONG>html</STRONG>$ foo.<STRONG>cgi</STRONG> [T=<STRONG>application/x-httpd-cgi</STRONG>]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>On-the-fly Content-Regeneration</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Here comes a really esoteric feature: Dynamically generated but statically
-served pages, i.e. pages should be delivered as pure static pages (read from
-the filesystem and just passed through), but they have to be generated
-dynamically by the webserver if missing. This way you can have CGI-generated
-pages which are statically served unless one (or a cronjob) removes the static
-contents. Then the contents gets refreshed.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-This is done via the following ruleset:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
-RewriteCond %{REQUEST_FILENAME} <STRONG>!-s</STRONG>
-RewriteRule ^page\.<STRONG>html</STRONG>$ page.<STRONG>cgi</STRONG> [T=application/x-httpd-cgi,L]
-</PRE></TD></TR></TABLE>
-
-<P>
-Here a request to <CODE>page.html</CODE> leads to a internal run of a
-corresponding <CODE>page.cgi</CODE> if <CODE>page.html</CODE> is still missing or has
-filesize null. The trick here is that <CODE>page.cgi</CODE> is a usual CGI script
-which (additionally to its STDOUT) writes its output to the file
-<CODE>page.html</CODE>. Once it was run, the server sends out the data of
-<CODE>page.html</CODE>. When the webmaster wants to force a refresh the contents,
-he just removes <CODE>page.html</CODE> (usually done by a cronjob).
-
-</DL>
-
-<P>
-<H2>Document With Autorefresh</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Wouldn't it be nice while creating a complex webpage if the webbrowser would
-automatically refresh the page every time we write a new version from within
-our editor? Impossible?
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-No! We just combine the MIME multipart feature, the webserver NPH feature and
-the URL manipulation power of mod_rewrite. First, we establish a new URL
-feature: Adding just <CODE>:refresh</CODE> to any URL causes this to be refreshed
-every time it gets updated on the filesystem.
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteRule ^foo\.<strong>html</strong>$ foo.<strong>cgi</strong> [T=<strong>application/x-httpd-cgi</strong>]
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>On-the-fly Content-Regeneration</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Here comes a really esoteric feature: Dynamically
+ generated but statically served pages, i.e. pages should be
+ delivered as pure static pages (read from the filesystem
+ and just passed through), but they have to be generated
+ dynamically by the webserver if missing. This way you can
+ have CGI-generated pages which are statically served unless
+ one (or a cronjob) removes the static contents. Then the
+ contents gets refreshed.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ This is done via the following ruleset:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
+RewriteCond %{REQUEST_FILENAME} <strong>!-s</strong>
+RewriteRule ^page\.<strong>html</strong>$ page.<strong>cgi</strong> [T=application/x-httpd-cgi,L]
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Here a request to <code>page.html</code> leads to a
+ internal run of a corresponding <code>page.cgi</code> if
+ <code>page.html</code> is still missing or has filesize
+ null. The trick here is that <code>page.cgi</code> is a
+ usual CGI script which (additionally to its STDOUT)
+ writes its output to the file <code>page.html</code>.
+ Once it was run, the server sends out the data of
+ <code>page.html</code>. When the webmaster wants to force
+ a refresh the contents, he just removes
+ <code>page.html</code> (usually done by a cronjob).</p>
+ </dd>
+ </dl>
+
+ <h2>Document With Autorefresh</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Wouldn't it be nice while creating a complex webpage if
+ the webbrowser would automatically refresh the page every
+ time we write a new version from within our editor?
+ Impossible?</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ No! We just combine the MIME multipart feature, the
+ webserver NPH feature and the URL manipulation power of
+ mod_rewrite. First, we establish a new URL feature:
+ Adding just <code>:refresh</code> to any URL causes this
+ to be refreshed every time it gets updated on the
+ filesystem.
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteRule ^(/[uge]/[^/]+/?.*):refresh /internal/cgi/apache/nph-refresh?f=$1
-</PRE></TD></TR></TABLE>
+</pre>
+ </td>
+ </tr>
+ </table>
-<P>
-Now when we reference the URL
-
-<P><PRE>
+ <p>Now when we reference the URL</p>
+<pre>
/u/foo/bar/page.html:refresh
-</PRE><P>
-
-this leads to the internal invocation of the URL
+</pre>
-<P><PRE>
+ <p>this leads to the internal invocation of the URL</p>
+<pre>
/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html
-</PRE><P>
+</pre>
-The only missing part is the NPH-CGI script. Although one would usually say
-"left as an exercise to the reader" ;-) I will provide this, too.
-
-<P><PRE>
+ <p>The only missing part is the NPH-CGI script. Although
+ one would usually say "left as an exercise to the reader"
+ ;-) I will provide this, too.</p>
+<pre>
#!/sw/bin/perl
##
## nph-refresh -- NPH/CGI script for auto refreshing pages
exit(0);
##EOF##
-</PRE>
+</pre>
+ </dd>
+ </dl>
+
+ <h2>Mass Virtual Hosting</h2>
-</DL>
+ <dl>
+ <dt><strong>Description:</strong></dt>
-<P>
-<H2>Mass Virtual Hosting</H2>
-<P>
+ <dd>The <code><VirtualHost></code> feature of Apache
+ is nice and works great when you just have a few dozens
+ virtual hosts. But when you are an ISP and have hundreds of
+ virtual hosts to provide this feature is not the best
+ choice.</dd>
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-The <CODE><VirtualHost></CODE> feature of Apache is nice and works great
-when you just have a few dozens virtual hosts. But when you are an ISP and
-have hundreds of virtual hosts to provide this feature is not the best choice.
+ <dt><strong>Solution:</strong></dt>
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-To provide this feature we map the remote webpage or even the complete remote
-webarea to our namespace by the use of the <I>Proxy Throughput</I> feature
-(flag [P]):
+ <dd>
+ To provide this feature we map the remote webpage or even
+ the complete remote webarea to our namespace by the use
+ of the <i>Proxy Throughput</i> feature (flag [P]):
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
##
## vhost.map
##
www.vhost2.dom:80 /path/to/docroot/vhost2
:
www.vhostN.dom:80 /path/to/docroot/vhostN
-</PRE></TD></TR></TABLE>
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
##
## httpd.conf
##
# and remember the virtual host for logging puposes
RewriteRule ^/(.*)$ %1/$1 [E=VHOST:${lowercase:%{HTTP_HOST}}]
:
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<H1>Access Restriction</H1>
-
-<P>
-<H2>Blocking of Robots</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-How can we block a really annoying robot from retrieving pages of a specific
-webarea? A <CODE>/robots.txt</CODE> file containing entries of the "Robot
-Exclusion Protocol" is typically not enough to get rid of such a robot.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We use a ruleset which forbids the URLs of the webarea
-<CODE>/~quux/foo/arc/</CODE> (perhaps a very deep directory indexed area where the
-robot traversal would create big server load). We have to make sure that we
-forbid access only to the particular robot, i.e. just forbidding the host
-where the robot runs is not enough. This would block users from this host,
-too. We accomplish this by also matching the User-Agent HTTP header
-information.
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
-RewriteCond %{HTTP_USER_AGENT} ^<STRONG>NameOfBadRobot</STRONG>.*
-RewriteCond %{REMOTE_ADDR} ^<STRONG>123\.45\.67\.[8-9]</STRONG>$
-RewriteRule ^<STRONG>/~quux/foo/arc/</STRONG>.+ - [<STRONG>F</STRONG>]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Blocked Inline-Images</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Assume we have under http://www.quux-corp.de/~quux/ some pages with inlined
-GIF graphics. These graphics are nice, so others directly incorporate them via
-hyperlinks to their pages. We don't like this practice because it adds useless
-traffic to our server.
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-While we cannot 100% protect the images from inclusion, we
-can at least restrict the cases where the browser sends
-a HTTP Referer header.
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
-RewriteCond %{HTTP_REFERER} <STRONG>!^$</STRONG>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h1>Access Restriction</h1>
+
+ <h2>Blocking of Robots</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>How can we block a really annoying robot from
+ retrieving pages of a specific webarea? A
+ <code>/robots.txt</code> file containing entries of the
+ "Robot Exclusion Protocol" is typically not enough to get
+ rid of such a robot.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We use a ruleset which forbids the URLs of the webarea
+ <code>/~quux/foo/arc/</code> (perhaps a very deep
+ directory indexed area where the robot traversal would
+ create big server load). We have to make sure that we
+ forbid access only to the particular robot, i.e. just
+ forbidding the host where the robot runs is not enough.
+ This would block users from this host, too. We accomplish
+ this by also matching the User-Agent HTTP header
+ information.
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
+RewriteCond %{HTTP_USER_AGENT} ^<strong>NameOfBadRobot</strong>.*
+RewriteCond %{REMOTE_ADDR} ^<strong>123\.45\.67\.[8-9]</strong>$
+RewriteRule ^<strong>/~quux/foo/arc/</strong>.+ - [<strong>F</strong>]
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Blocked Inline-Images</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Assume we have under http://www.quux-corp.de/~quux/
+ some pages with inlined GIF graphics. These graphics are
+ nice, so others directly incorporate them via hyperlinks to
+ their pages. We don't like this practice because it adds
+ useless traffic to our server.</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ While we cannot 100% protect the images from inclusion,
+ we can at least restrict the cases where the browser
+ sends a HTTP Referer header.
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
+RewriteCond %{HTTP_REFERER} <strong>!^$</strong>
RewriteCond %{HTTP_REFERER} !^http://www.quux-corp.de/~quux/.*$ [NC]
-RewriteRule <STRONG>.*\.gif$</STRONG> - [F]
-</PRE></TD></TR></TABLE>
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteRule <strong>.*\.gif$</strong> - [F]
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !.*/foo-with-gif\.html$
-RewriteRule <STRONG>^inlined-in-foo\.gif$</STRONG> - [F]
-</PRE></TD></TR></TABLE>
+RewriteRule <strong>^inlined-in-foo\.gif$</strong> - [F]
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
-</DL>
+ <h2>Host Deny</h2>
-<P>
-<H2>Host Deny</H2>
-<P>
+ <dl>
+ <dt><strong>Description:</strong></dt>
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-How can we forbid a list of externally configured hosts from using our server?
+ <dd>How can we forbid a list of externally configured hosts
+ from using our server?</dd>
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
+ <dt><strong>Solution:</strong></dt>
-For Apache >= 1.3b6:
+ <dd>
+ For Apache >= 1.3b6:
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteMap hosts-deny txt:/path/to/hosts.deny
RewriteCond ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND [OR]
RewriteCond ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND
RewriteRule ^/.* - [F]
-</PRE></TD></TR></TABLE><P>
-
-For Apache <= 1.3b6:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>For Apache <= 1.3b6:</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
RewriteMap hosts-deny txt:/path/to/hosts.deny
RewriteRule ^/(.*)$ ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND}/$1
RewriteRule ^NOT-FOUND/(.*)$ ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND}/$1
RewriteRule !^NOT-FOUND/.* - [F]
RewriteRule ^NOT-FOUND/(.*)$ /$1
-</PRE></TD></TR></TABLE>
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
##
## hosts.deny
##
193.102.180.41 -
bsdti1.sdm.de -
192.76.162.40 -
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Proxy Deny</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-How can we forbid a certain host or even a user of a special host from using
-the Apache proxy?
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We first have to make sure mod_rewrite is below(!) mod_proxy in the
-<CODE>Configuration</CODE> file when compiling the Apache webserver. This way it
-gets called _before_ mod_proxy. Then we configure the following for a
-host-dependend deny...
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
-RewriteCond %{REMOTE_HOST} <STRONG>^badhost\.mydomain\.com$</STRONG>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Proxy Deny</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>How can we forbid a certain host or even a user of a
+ special host from using the Apache proxy?</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We first have to make sure mod_rewrite is below(!)
+ mod_proxy in the <code>Configuration</code> file when
+ compiling the Apache webserver. This way it gets called
+ _before_ mod_proxy. Then we configure the following for a
+ host-dependend deny...
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
+RewriteCond %{REMOTE_HOST} <strong>^badhost\.mydomain\.com$</strong>
RewriteRule !^http://[^/.]\.mydomain.com.* - [F]
-</PRE></TD></TR></TABLE>
-
-<P>...and this one for a user@host-dependend deny:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <STRONG>^badguy@badhost\.mydomain\.com$</STRONG>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>...and this one for a user@host-dependend deny:</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
+RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>^badguy@badhost\.mydomain\.com$</strong>
RewriteRule !^http://[^/.]\.mydomain.com.* - [F]
-</PRE></TD></TR></TABLE>
-
-</DL>
-
-<P>
-<H2>Special Authentication Variant</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-Sometimes a very special authentication is needed, for instance a
-authentication which checks for a set of explicitly configured users. Only
-these should receive access and without explicit prompting (which would occur
-when using the Basic Auth via mod_access).
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-We use a list of rewrite conditions to exclude all except our friends:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <STRONG>!^friend1@client1.quux-corp\.com$</STRONG>
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <STRONG>!^friend2</STRONG>@client2.quux-corp\.com$
-RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <STRONG>!^friend3</STRONG>@client3.quux-corp\.com$
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <h2>Special Authentication Variant</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>Sometimes a very special authentication is needed, for
+ instance a authentication which checks for a set of
+ explicitly configured users. Only these should receive
+ access and without explicit prompting (which would occur
+ when using the Basic Auth via mod_access).</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ We use a list of rewrite conditions to exclude all except
+ our friends:
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
+RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend1@client1.quux-corp\.com$</strong>
+RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend2</strong>@client2.quux-corp\.com$
+RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend3</strong>@client3.quux-corp\.com$
RewriteRule ^/~quux/only-for-friends/ - [F]
-</PRE></TD></TR></TABLE>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
-</DL>
+ <h2>Referer-based Deflector</h2>
-<P>
-<H2>Referer-based Deflector</H2>
-<P>
+ <dl>
+ <dt><strong>Description:</strong></dt>
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-How can we program a flexible URL Deflector which acts on the "Referer" HTTP
-header and can be configured with as many referring pages as we like?
+ <dd>How can we program a flexible URL Deflector which acts
+ on the "Referer" HTTP header and can be configured with as
+ many referring pages as we like?</dd>
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-Use the following really tricky ruleset...
+ <dt><strong>Solution:</strong></dt>
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+ <dd>
+ Use the following really tricky ruleset...
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteMap deflector txt:/path/to/deflector.map
RewriteCond %{HTTP_REFERER} !=""
RewriteCond %{HTTP_REFERER} !=""
RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND
RewriteRule ^.* ${deflector:%{HTTP_REFERER}} [R,L]
-</PRE></TD></TR></TABLE>
-
-<P>...
-in conjunction with a corresponding rewrite map:
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>... in conjunction with a corresponding rewrite
+ map:</p>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
##
## deflector.map
##
http://www.badguys.com/bad/index.html -
http://www.badguys.com/bad/index2.html -
http://www.badguys.com/bad/index3.html http://somewhere.com/
-</PRE></TD></TR></TABLE>
-
-<P>
-This automatically redirects the request back to the referring page (when "-"
-is used as the value in the map) or to a specific URL (when an URL is
-specified in the map as the second argument).
-
-</DL>
-
-<H1>Other</H1>
-
-<P>
-<H2>External Rewriting Engine</H2>
-<P>
-
-<DL>
-<DT><STRONG>Description:</STRONG>
-<DD>
-A FAQ: How can we solve the FOO/BAR/QUUX/etc. problem? There seems no solution
-by the use of mod_rewrite...
-
-<P>
-<DT><STRONG>Solution:</STRONG>
-<DD>
-Use an external rewrite map, i.e. a program which acts like a rewrite map. It
-is run once on startup of Apache receives the requested URLs on STDIN and has
-to put the resulting (usually rewritten) URL on STDOUT (same order!).
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>This automatically redirects the request back to the
+ referring page (when "-" is used as the value in the map)
+ or to a specific URL (when an URL is specified in the map
+ as the second argument).</p>
+ </dd>
+ </dl>
+
+ <h1>Other</h1>
+
+ <h2>External Rewriting Engine</h2>
+
+ <dl>
+ <dt><strong>Description:</strong></dt>
+
+ <dd>A FAQ: How can we solve the FOO/BAR/QUUX/etc. problem?
+ There seems no solution by the use of mod_rewrite...</dd>
+
+ <dt><strong>Solution:</strong></dt>
+
+ <dd>
+ Use an external rewrite map, i.e. a program which acts
+ like a rewrite map. It is run once on startup of Apache
+ receives the requested URLs on STDIN and has to put the
+ resulting (usually rewritten) URL on STDOUT (same
+ order!).
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
RewriteEngine on
-RewriteMap quux-map <STRONG>prg:</STRONG>/path/to/map.quux.pl
-RewriteRule ^/~quux/(.*)$ /~quux/<STRONG>${quux-map:$1}</STRONG>
-</PRE></TD></TR></TABLE>
-
-<P><TABLE BGCOLOR="#E0E5F5" BORDER="0" CELLSPACING="0" CELLPADDING="5"><TR><TD><PRE>
+RewriteMap quux-map <strong>prg:</strong>/path/to/map.quux.pl
+RewriteRule ^/~quux/(.*)$ /~quux/<strong>${quux-map:$1}</strong>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <table bgcolor="#E0E5F5" border="0" cellspacing="0"
+ cellpadding="5">
+ <tr>
+ <td>
+<pre>
#!/path/to/perl
# disable buffered I/O which would lead
s|^foo/|bar/|;
print $_;
}
-</PRE></TD></TR></TABLE>
-
-<P>
-This is a demonstration-only example and just rewrites all URLs
-<CODE>/~quux/foo/...</CODE> to <CODE>/~quux/bar/...</CODE>. Actually you can program
-whatever you like. But notice that while such maps can be <STRONG>used</STRONG> also by
-an average user, only the system administrator can <STRONG>define</STRONG> it.
-
-</DL>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>This is a demonstration-only example and just rewrites
+ all URLs <code>/~quux/foo/...</code> to
+ <code>/~quux/bar/...</code>. Actually you can program
+ whatever you like. But notice that while such maps can be
+ <strong>used</strong> also by an average user, only the
+ system administrator can <strong>define</strong> it.</p>
+ </dd>
+ </dl>
+ <!--#include virtual="footer.html" -->
+ </blockquote>
+ </body>
+</html>
-<!--#include virtual="footer.html" -->
-</BLOCKQUOTE>
-</BODY>
-</HTML>
-<!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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache HTTP Server: 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.</p>
+ <hr />
+
+ <h2><a id="serverroot" 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:</p>
+
+ <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>
+</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>
+</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>
+
+ <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>
+
+ <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;</p>
+
+ <ol>
+ <li>You trust your users not to write scripts which will
+ deliberately or accidentally expose your system to an
+ attack.</li>
+
+ <li>You consider security at your site to be so feeble in
+ other areas, as to make one more potential hole
+ irrelevant.</li>
+
+ <li>You have no users, and nobody ever visits your
+ server.</li>
+ </ol>
+ <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>
+
+ <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>
+
+ <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>
+
+ <p>In the server configuration file, put</p>
+
+ <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>
+</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
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>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</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>
+
+ <p><!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache Tutorials</TITLE>
-</HEAD>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache Tutorials</title>
+ </head>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+
+ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
+ vlink="#000080" alink="#FF0000">
+ <!--#include virtual="header.html" -->
+
+ <blockquote>
+ <strong>Warning:</strong> This document has not been updated
+ to take into account changes made in the 2.0 version of the
+ Apache HTTP Server. Some of the information may still be
+ relevant, but please use it with care.
+ </blockquote>
+
+ <h1 align="CENTER">Apache Tutorials</h1>
+
+ <p>The following documents give you step-by-step instructions
+ on how to accomplish common tasks with the Apache http server.
+ Many of these documents are located at external sites and are
+ not the work of the Apache Software Foundation. Copyright to
+ documents on external sites is owned by the authors or their
+ assignees. Please consult the <a href="../">official Apache
+ Server documentation</a> to verify what you read on external
+ sites.</p>
+
+ <h2>Installation & Getting Started</h2>
+
+ <ul>
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-06-1-001-01-NW-DP-LF">
+ Getting Started with Apache 1.3</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-07-10-001-01-NW-LF-SW">
+ Configuring Your Apache Server Installation</a>
+ (ApacheToday)</li>
+
+ <li><a
+ href="http://oreilly.apacheweek.com/pub/a/apache/2000/02/24/installing_apache.html">
+ Getting, Installing, and Running Apache (on Unix)</a>
+ (O'Reilly Network Apache DevCenter)</li>
+
+ <li><a
+ href="http://www.builder.com/Servers/Apache/ss01.html">Maximum
+ Apache: Getting Started</a> (CNET Builder.com)</li>
+
+ <li><a
+ href="http://www.devshed.com/Server_Side/Administration/APACHE/">
+ How to Build the Apache of Your Dreams</a> (Developer
+ Shed)</li>
+ </ul>
+
+ <h2>Basic Configuration</h2>
+
+ <ul>
+ <li><a
+ href="http://oreilly.apacheweek.com/pub/a/apache/2000/03/02/configuring_apache.html">
+ An Amble Through Apache Configuration</a> (O'Reilly Network
+ Apache DevCenter)</li>
+
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-07-19-002-01-NW-LF-SW">
+ Using .htaccess Files with Apache</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-07-17-001-01-PS">
+ Setting Up Virtual Hosts</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://www.builder.com/Servers/Apache/ss02.html">Maximum
+ Apache: Configure Apache</a> (CNET Builder.com)</li>
+
+ <li>Getting More Out of Apache <a
+ href="http://www.devshed.com/Server_Side/Administration/MoreApache/">
+ Part 1</a> - <a
+ href="http://www.devshed.com/Server_Side/Administration/MoreApache2/">
+ Part 2</a> (Developer Shed)</li>
+ </ul>
+
+ <h2>Security</h2>
+
+ <ul>
+ <li><a
+ href="http://www.linuxplanet.com/linuxplanet/tutorials/1527/1/">
+ Security and Apache: An Essential Primer</a>
+ (LinuxPlanet)</li>
+
+ <li><a
+ href="http://www.apacheweek.com/features/userauth">Using User
+ Authentication</a> (Apacheweek)</li>
+
+ <li><a href="http://www.apacheweek.com/features/dbmauth">DBM
+ User Authentication</a> (Apacheweek)</li>
+
+ <li><a
+ href="http://linux.com/security/newsitem.phtml?sid=12&aid=3549">
+ An Introduction to Securing Apache</a> (Linux.com)</li>
+
+ <li><a
+ href="http://linux.com/security/newsitem.phtml?sid=12&aid=3667">
+ Securing Apache - Access Control</a> (Linux.com)</li>
+
+ <li>Apache Authentication <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-07-24-002-01-NW-LF-SW">
+ Part 1</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-07-31-001-01-NW-DP-LF">
+ Part 2</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-08-07-001-01-NW-LF-SW">
+ Part 3</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-08-14-001-01-NW-LF-SW">
+ Part 4</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-11-13-003-01-SC-LF-SW">
+ mod_access: Restricting Access by Host</a> (ApacheToday)</li>
+ </ul>
+
+ <h2>Logging</h2>
+
+ <ul>
+ <li><a
+ href="http://oreilly.apacheweek.com/pub/a/apache/2000/03/10/log_rhythms.html">
+ Log Rhythms</a> (O'Reilly Network Apache DevCenter)</li>
+
+ <li><a
+ href="http://www.apacheweek.com/features/logfiles">Gathering
+ Visitor Information: Customising Your Logfiles</a>
+ (Apacheweek)</li>
+
+ <li>Apache Guide: Logging <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-08-21-003-01-NW-LF-SW">
+ Part 1</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-08-28-001-01-NW-LF-SW">
+ Part 2</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-09-05-001-01-NW-LF-SW">
+ Part 3</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-09-18-003-01-NW-LF-SW">
+ Part 4</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-09-25-001-01-NW-LF-SW">
+ Part 5</a> (ApacheToday)</li>
+ </ul>
+
+ <h2>CGI and SSI</h2>
+
+ <ul>
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-06-05-001-10-NW-LF-SW">
+ Dynamic Content with CGI</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://www.perl.com/CPAN-local/doc/FAQs/cgi/idiots-guide.html">
+ The Idiot's Guide to Solving Perl CGI Problems</a>
+ (CPAN)</li>
+
+ <li><a
+ href="http://www.linuxplanet.com/linuxplanet/tutorials/1445/1/">
+ Executing CGI Scripts as Other Users</a> (LinuxPlanet)</li>
+
+ <li><a href="http://www.htmlhelp.org/faq/cgifaq.html">CGI
+ Programming FAQ</a> (Web Design Group)</li>
+
+ <li>Introduction to Server Side Includes <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-06-12-001-01-PS">
+ Part 1</a> - <a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-06-19-002-01-NW-LF-SW">
+ Part 2</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-06-26-001-01-NW-LF-SW">
+ Advanced SSI Techniques</a> (ApacheToday)</li>
+
+ <li><a
+ href="http://www.builder.com/Servers/ApacheFiles/082400/">Setting
+ up CGI and SSI with Apache</a> (CNET Builder.com)</li>
+ </ul>
+
+ <h2>Other Features</h2>
+
+ <ul>
+ <li><a
+ href="http://www.apacheweek.com/features/negotiation">Content
+ Negotiation Explained</a> (Apacheweek)</li>
+
+ <li><a
+ href="http://www.apacheweek.com/features/imagemaps">Using
+ Apache Imagemaps</a> (Apacheweek)</li>
+
+ <li><a
+ href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS">
+ Keeping Your Images from Adorning Other Sites</a>
+ (ApacheToday)</li>
+
+ <li><a
+ href="http://ppewww.ph.gla.ac.uk/~flavell/www/lang-neg.html">Language
+ Negotiation Notes</a> (Alan J. Flavell)</li>
+ </ul>
+
+ <p>If you have a pointer to a an accurate and well-written
+ tutorial not included here, please let us know by submitting it
+ to the <a href="http://bugs.apache.org/">Apache Bug
+ Database</a>. <!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
-
-<blockquote><strong>Warning:</strong>
-This document has not been updated to take into account changes
-made in the 2.0 version of the Apache HTTP Server. Some of the
-information may still be relevant, but please use it
-with care.
-</blockquote>
-
-
-<H1 ALIGN="CENTER">Apache Tutorials</H1>
-
-<P>The following documents give you step-by-step instructions on how
-to accomplish common tasks with the Apache http server. Many of these
-documents are located at external sites and are not the work of the
-Apache Software Foundation. Copyright to documents on external sites
-is owned by the authors or their assignees. Please consult the <A
-HREF="../">official Apache Server documentation</A> to verify what you
-read on external sites.
-
-
-<H2>Installation & Getting Started</H2>
-
-<UL>
-
-<LI><A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-06-1-001-01-NW-DP-LF"
->Getting Started with Apache 1.3</A> (ApacheToday)
-
-<LI><A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-07-10-001-01-NW-LF-SW"
->Configuring Your Apache Server Installation</A> (ApacheToday)
-
-<LI><A
-HREF="http://oreilly.apacheweek.com/pub/a/apache/2000/02/24/installing_apache.html"
->Getting, Installing, and Running Apache (on Unix)</A> (O'Reilly
-Network Apache DevCenter)
-
-<LI><A HREF="http://www.builder.com/Servers/Apache/ss01.html">Maximum
-Apache: Getting Started</A> (CNET Builder.com)
-
-<LI><A HREF="http://www.devshed.com/Server_Side/Administration/APACHE/"
->How to Build the Apache of Your Dreams</A> (Developer Shed)
-
-</UL>
-
-
-<H2>Basic Configuration</H2>
-
-<UL>
-
-<LI><A
-HREF="http://oreilly.apacheweek.com/pub/a/apache/2000/03/02/configuring_apache.html"
->An Amble Through Apache Configuration</A> (O'Reilly Network Apache
-DevCenter)
-
-<LI><A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-07-19-002-01-NW-LF-SW"
->Using .htaccess Files with Apache</A> (ApacheToday)
-
-<LI><A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-07-17-001-01-PS"
->Setting Up Virtual Hosts</A> (ApacheToday)
-
-<LI><A HREF="http://www.builder.com/Servers/Apache/ss02.html">Maximum
-Apache: Configure Apache</A> (CNET Builder.com)
-
-<LI>Getting More Out of Apache <A HREF="http://www.devshed.com/Server_Side/Administration/MoreApache/">Part 1</A> - <A HREF="http://www.devshed.com/Server_Side/Administration/MoreApache2/">Part 2</A> (Developer Shed)
-
-</UL>
-
-<H2>Security</H2>
-
-<UL>
-
-<LI><A
-HREF="http://www.linuxplanet.com/linuxplanet/tutorials/1527/1/">Security
-and Apache: An Essential Primer</A> (LinuxPlanet)
-
-<LI><A HREF="http://www.apacheweek.com/features/userauth">Using User
-Authentication</A> (Apacheweek)
-
-<LI><A HREF="http://www.apacheweek.com/features/dbmauth">DBM User
-Authentication</A> (Apacheweek)
-
-<LI><A
-HREF="http://linux.com/security/newsitem.phtml?sid=12&aid=3549">An
-Introduction to Securing Apache</A> (Linux.com)
-
-<LI><A
-HREF="http://linux.com/security/newsitem.phtml?sid=12&aid=3667">Securing
-Apache - Access Control</A> (Linux.com)
-
-<LI>Apache Authentication <A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-07-24-002-01-NW-LF-SW"
->Part 1</A> - <A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-07-31-001-01-NW-DP-LF"
->Part 2</A> - <A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-08-07-001-01-NW-LF-SW"
->Part 3</A> - <A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-08-14-001-01-NW-LF-SW"
->Part 4</A> (ApacheToday)
-
-<LI><a href="http://apachetoday.com/news_story.php3?ltsn=2000-11-13-003-01-SC-LF-SW"
->mod_access: Restricting Access by Host</a> (ApacheToday)
-
-</UL>
-
-<H2>Logging</H2>
-
-<UL>
-
-<LI><A
-HREF="http://oreilly.apacheweek.com/pub/a/apache/2000/03/10/log_rhythms.html"
->Log Rhythms</A> (O'Reilly Network Apache DevCenter)
-
-<LI><A HREF="http://www.apacheweek.com/features/logfiles">Gathering
-Visitor Information: Customising Your Logfiles</A> (Apacheweek)
-
-<LI>Apache Guide: Logging
-<A HREF="http://apachetoday.com/news_story.php3?ltsn=2000-08-21-003-01-NW-LF-SW"
->Part 1</A> -
-<A HREF="http://apachetoday.com/news_story.php3?ltsn=2000-08-28-001-01-NW-LF-SW"
->Part 2</A> -
-<A HREF="http://apachetoday.com/news_story.php3?ltsn=2000-09-05-001-01-NW-LF-SW"
->Part 3</A> -
-<A HREF="http://apachetoday.com/news_story.php3?ltsn=2000-09-18-003-01-NW-LF-SW"
->Part 4</A> -
-<A HREF="http://apachetoday.com/news_story.php3?ltsn=2000-09-25-001-01-NW-LF-SW"
->Part 5</A> (ApacheToday)
-
-</UL>
-
-<H2>CGI and SSI</H2>
-
-<UL>
-
-<LI><A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-06-05-001-10-NW-LF-SW"
->Dynamic Content with CGI</A> (ApacheToday)
-
-<LI><A
-HREF="http://www.perl.com/CPAN-local/doc/FAQs/cgi/idiots-guide.html">The
-Idiot's Guide to Solving Perl CGI Problems</A> (CPAN)
-
-<LI><A
-HREF="http://www.linuxplanet.com/linuxplanet/tutorials/1445/1/">Executing
-CGI Scripts as Other Users</A> (LinuxPlanet)
-
-<LI><A HREF="http://www.htmlhelp.org/faq/cgifaq.html">CGI Programming
-FAQ</A> (Web Design Group)
-
-<LI>Introduction to Server Side Includes <A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-06-12-001-01-PS">Part
-1</A> - <A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-06-19-002-01-NW-LF-SW"
->Part 2</A> (ApacheToday)
-
-<LI><A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-06-26-001-01-NW-LF-SW"
->Advanced SSI Techniques</A> (ApacheToday)
-
-<LI><A
-HREF="http://www.builder.com/Servers/ApacheFiles/082400/">Setting up
-CGI and SSI with Apache</A> (CNET Builder.com)
-
-</UL>
-
-<H2>Other Features</H2>
-
-<UL>
-
-<LI><A HREF="http://www.apacheweek.com/features/negotiation">Content
-Negotiation Explained</A> (Apacheweek)
-
-<LI><A HREF="http://www.apacheweek.com/features/imagemaps">Using
-Apache Imagemaps</A> (Apacheweek)
-
-<LI><A
-HREF="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS"
->Keeping Your Images from Adorning Other Sites</A> (ApacheToday)
-
-<LI><A HREF="http://ppewww.ph.gla.ac.uk/~flavell/www/lang-neg.html"
->Language Negotiation Notes</A> (Alan J. Flavell)
-
-</UL>
-
-
-<P>If you have a pointer to a an accurate and well-written tutorial
-not included here, please let us know by submitting it to the
-<A HREF="http://bugs.apache.org/">Apache Bug Database</A>.
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
<li><a
href="mod_autoindex.html#addiconbytype">AddIconByType</a></li>
- <li><a href="mod_mime.html#addinputfilter">AddInputFilter</a></li>
+ <li><a
+ href="mod_mime.html#addinputfilter">AddInputFilter</a></li>
<li><a href="mod_mime.html#addlanguage">AddLanguage</a></li>
<li><a
href="mod_info.html#addmoduleinfo">AddModuleInfo</a></li>
- <li><a href="mod_mime.html#addoutputfilter">AddOutputFilter</a></li>
+ <li><a
+ href="mod_mime.html#addoutputfilter">AddOutputFilter</a></li>
<li><a href="mod_mime.html#addtype">AddType</a></li>
-<HR>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<H3 ALIGN="CENTER">
- Apache HTTP Server Version 2.0
-</H3>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title></title>
+ </head>
+
+ <body>
+ <hr />
+
+ <h3 align="CENTER">Apache HTTP Server Version 2.0</h3>
+ <a href="./"><img src="../images/index.gif" alt="Index" /></a>
+ <a href="../"><img src="../images/home.gif" alt="Home" /></a>
+ </body>
+</html>
-<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A>
-<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A>
-<DIV ALIGN="CENTER">
- <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]">
- <H3>
- Apache HTTP Server Version 2.0
- </H3>
-</DIV>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title></title>
+ </head>
+
+ <body>
+ <div align="CENTER">
+ <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" />
+
+ <h3>Apache HTTP Server Version 2.0</h3>
+ </div>
+ </body>
+</html>
+
-<!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 list of modules <A
-HREF="index.html">sorted alphabetically</A> and the complete
-alphabetical list of <A HREF="directives.html" >all Apache
-directives</A>.
-</P>
-
-<H2>Core and Mutli-Processing Modules</H2>
-
-<DL>
-<DT><A HREF="core.html">Core</A>
-<DD>Core Apache features.
-<DT><A HREF="threaded.html">threaded</A>
-<DD>Multi-Processing Module with Threading via Pthreads; Variable number
-of processes, constant number of threads/child
-<DT><a href="mpm_winnt.html">mpm_winnt</a>
-<DD>Multi-Processing Module with a single control process and a single
-server process with multiple threads for Windows NT
-<DT><a href="perchild.html">perchild</a>
-<DD>Multi-Processing Module with the ability to server different
-virtual hosts under different userids.
-<DT><a href="prefork.html">prefork</a>
-<DD>Non-threaded preforking processes model similar to Apache 1.3
-</DL>
-
-<H2>Environment Creation</H2>
-
-<DL>
-<DT><A HREF="mod_env.html">mod_env</A>
-<DD>Passing of environments to CGI scripts
-<DT><A HREF="mod_setenvif.html">mod_setenvif</A>
-<DD>Set environment variables based on client information
-<DT><A HREF="mod_unique_id.html">mod_unique_id</A>
-<DD>Generate unique request identifier for every request
-</DL>
-
-<H2>Content Type Decisions</H2>
-
-<DL>
-<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_negotiation.html">mod_negotiation</A>
-<DD>Content negotiation.
-<DT><A HREF="mod_charset_lite.html">mod_charset_lite</A>
-<DD>Configuring character set translation.
-</DL>
-
-<H2>URL Mapping</H2>
-
-<DL>
-<DT><A HREF="mod_alias.html">mod_alias</A>
-<DD>Mapping different parts of the host filesystem in the document tree,
- and URL redirection.
-<DT><A HREF="mod_rewrite.html">mod_rewrite</A>
-<DD>Powerful URI-to-filename mapping using regular expressions
-<DT><A HREF="mod_userdir.html">mod_userdir</A>
-<DD>User home directories.
-<DT><A HREF="mod_speling.html">mod_speling</A>
-<DD>Automatically correct minor typos in URLs
-<DT><A HREF="mod_vhost_alias.html">mod_vhost_alias</A>
-<DD>Support for dynamically configured mass virtual hosting
-</DL>
-
-<H2>Directory Handling</H2>
-
-<DL>
-<DT><A HREF="mod_dir.html">mod_dir</A>
-<DD>Basic directory handling.
-<DT><A HREF="mod_autoindex.html">mod_autoindex</A>
-<DD>Automatic directory listings.
-</DL>
-
-<H2>Access Control</H2>
-
-<DL>
-<DT><A HREF="mod_access.html">mod_access</A>
-<DD>Access control based on client hostname or IP address.
-<DT><A HREF="mod_auth.html">mod_auth</A>
-<DD>User authentication using text files.
-<DT><A HREF="mod_auth_dbm.html">mod_auth_dbm</A>
-<DD>User authentication using DBM files.
-<DT><A HREF="mod_auth_db.html">mod_auth_db</A>
-<DD>User authentication using Berkeley DB files.
-<DT><A HREF="mod_auth_anon.html">mod_auth_anon</A>
-<DD>Anonymous user access to authenticated areas.
-<DT><A HREF="mod_auth_digest.html">mod_auth_digest</A>
-<DD>MD5 authentication
-<DT><A HREF="mod_auth_ldap.html">mod_auth_ldap</A>
-<DD>User authentication using LDAP.
-
-</DL>
-
-<H2>HTTP Response</H2>
-
-<DL>
-<DT><A HREF="mod_headers.html">mod_headers</A>
-<DD>Add arbitrary HTTP headers to resources
-<DT><A HREF="mod_cern_meta.html">mod_cern_meta</A>
-<DD>Support for HTTP header metafiles.
-<DT><A HREF="mod_expires.html">mod_expires</A>
-<DD>Apply Expires: headers to resources
-<DT><A HREF="mod_asis.html">mod_asis</A>
-<DD>Sending files which contain their own HTTP headers.
-</DL>
-
-<H2>Dynamic Content</H2>
-
-<DL>
-<DT><A HREF="mod_include.html">mod_include</A>
-<DD>Server-parsed documents.
-<DT><A HREF="mod_cgi.html">mod_cgi</A>
-<DD>Invoking CGI scripts.
-<DT><A HREF="mod_cgid.html">mod_cgid</A>
-<DD>Invoking CGI scripts using an external daemon.
-<DT><A HREF="mod_actions.html">mod_actions</A>
-<DD>Executing CGI scripts based on media type or request method.
-<DT><A HREF="mod_isapi.html">mod_isapi</A>
-<DD>Windows ISAPI Extension support
-<DT><A HREF="mod_ext_filter.html">mod_ext_filter</A>
-<DD>Filtering content with external programs.
-<DT><A HREF="mod_suexec.html">mod_suexec</A>
-<DD>Run CGI requests as a specified user and group.
-</DL>
-
-<H2>Internal Content Handlers</H2>
-
-<DL>
-<DT><A HREF="mod_status.html">mod_status</A>
-<DD>Server status display
-<DT><A HREF="mod_info.html">mod_info</A>
-<DD>Server configuration information
-</DL>
-
-<H2>Logging</H2>
-
-<DL>
-<DT><A HREF="mod_log_config.html">mod_log_config</A>
-<DD>User-configurable logging replacement for mod_log_common.
-<DT><A HREF="mod_usertrack.html">mod_usertrack</A>
-<DD>User tracking using Cookies
-</DL>
-
-<H2>Miscellaneous</H2>
-
-<DL>
-<DT><A HREF="mod_imap.html">mod_imap</A>
-<DD>The imagemap file handler.
-<DT><A HREF="mod_proxy.html">mod_proxy</A>
-<DD>Caching proxy abilities
-<DT><A HREF="mod_so.html">mod_so</A>
-<DD>Support for loading modules at runtime
-<DT><A HREF="mod_file_cache.html">mod_file_cache</A>
-<DD>Caching files in memory for faster serving.
-<DT><A HREF="mod_dav.html">mod_dav</A>
-<DD>Class 1,2 <A HREF="http://www.webdav.org">WebDAV</A> HTTP extensions
-<DT><A HREF="mod_ldap.html">mod_ldap</A>
-<DD>LDAP connection pool and shared memory cache.
-</DL>
-
-
-<H2>Development</H2>
-
-<DL>
-<DT><A HREF="mod_example.html">mod_example</A>
-<DD>Demonstrates Apache API
-</DL>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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 list of modules <a
+ href="index.html">sorted alphabetically</a> and the complete
+ alphabetical list of <a href="directives.html">all Apache
+ directives</a>.</p>
+
+ <h2>Core and Mutli-Processing Modules</h2>
+
+ <dl>
+ <dt><a href="core.html">Core</a></dt>
+
+ <dd>Core Apache features.</dd>
+
+ <dt><a href="threaded.html">threaded</a></dt>
+
+ <dd>Multi-Processing Module with Threading via Pthreads;
+ Variable number of processes, constant number of
+ threads/child</dd>
+
+ <dt><a href="mpm_winnt.html">mpm_winnt</a></dt>
+
+ <dd>Multi-Processing Module with a single control process and
+ a single server process with multiple threads for Windows
+ NT</dd>
+
+ <dt><a href="perchild.html">perchild</a></dt>
+
+ <dd>Multi-Processing Module with the ability to server
+ different virtual hosts under different userids.</dd>
+
+ <dt><a href="prefork.html">prefork</a></dt>
+
+ <dd>Non-threaded preforking processes model similar to Apache
+ 1.3</dd>
+ </dl>
+
+ <h2>Environment Creation</h2>
+
+ <dl>
+ <dt><a href="mod_env.html">mod_env</a></dt>
+
+ <dd>Passing of environments to CGI scripts</dd>
+
+ <dt><a href="mod_setenvif.html">mod_setenvif</a></dt>
+
+ <dd>Set environment variables based on client
+ information</dd>
+
+ <dt><a href="mod_unique_id.html">mod_unique_id</a></dt>
+
+ <dd>Generate unique request identifier for every request</dd>
+ </dl>
+
+ <h2>Content Type Decisions</h2>
+
+ <dl>
+ <dt><a href="mod_mime.html">mod_mime</a></dt>
+
+ <dd>Determining document types using file extensions.</dd>
+
+ <dt><a href="mod_mime_magic.html">mod_mime_magic</a></dt>
+
+ <dd>Determining document types using "magic numbers".</dd>
+
+ <dt><a href="mod_negotiation.html">mod_negotiation</a></dt>
+
+ <dd>Content negotiation.</dd>
+
+ <dt><a href="mod_charset_lite.html">mod_charset_lite</a></dt>
+
+ <dd>Configuring character set translation.</dd>
+ </dl>
+
+ <h2>URL Mapping</h2>
+
+ <dl>
+ <dt><a href="mod_alias.html">mod_alias</a></dt>
+
+ <dd>Mapping different parts of the host filesystem in the
+ document tree, and URL redirection.</dd>
+
+ <dt><a href="mod_rewrite.html">mod_rewrite</a></dt>
+
+ <dd>Powerful URI-to-filename mapping using regular
+ expressions</dd>
+
+ <dt><a href="mod_userdir.html">mod_userdir</a></dt>
+
+ <dd>User home directories.</dd>
+
+ <dt><a href="mod_speling.html">mod_speling</a></dt>
+
+ <dd>Automatically correct minor typos in URLs</dd>
+
+ <dt><a href="mod_vhost_alias.html">mod_vhost_alias</a></dt>
+
+ <dd>Support for dynamically configured mass virtual
+ hosting</dd>
+ </dl>
+
+ <h2>Directory Handling</h2>
+
+ <dl>
+ <dt><a href="mod_dir.html">mod_dir</a></dt>
+
+ <dd>Basic directory handling.</dd>
+
+ <dt><a href="mod_autoindex.html">mod_autoindex</a></dt>
+
+ <dd>Automatic directory listings.</dd>
+ </dl>
+
+ <h2>Access Control</h2>
+
+ <dl>
+ <dt><a href="mod_access.html">mod_access</a></dt>
+
+ <dd>Access control based on client hostname or IP
+ address.</dd>
+
+ <dt><a href="mod_auth.html">mod_auth</a></dt>
+
+ <dd>User authentication using text files.</dd>
+
+ <dt><a href="mod_auth_dbm.html">mod_auth_dbm</a></dt>
+
+ <dd>User authentication using DBM files.</dd>
+
+ <dt><a href="mod_auth_db.html">mod_auth_db</a></dt>
+
+ <dd>User authentication using Berkeley DB files.</dd>
+
+ <dt><a href="mod_auth_anon.html">mod_auth_anon</a></dt>
+
+ <dd>Anonymous user access to authenticated areas.</dd>
+
+ <dt><a href="mod_auth_digest.html">mod_auth_digest</a></dt>
+
+ <dd>MD5 authentication</dd>
+
+ <dt><a href="mod_auth_ldap.html">mod_auth_ldap</a></dt>
+
+ <dd>User authentication using LDAP.</dd>
+ </dl>
+
+ <h2>HTTP Response</h2>
+
+ <dl>
+ <dt><a href="mod_headers.html">mod_headers</a></dt>
+
+ <dd>Add arbitrary HTTP headers to resources</dd>
+
+ <dt><a href="mod_cern_meta.html">mod_cern_meta</a></dt>
+
+ <dd>Support for HTTP header metafiles.</dd>
+
+ <dt><a href="mod_expires.html">mod_expires</a></dt>
+
+ <dd>Apply Expires: headers to resources</dd>
+
+ <dt><a href="mod_asis.html">mod_asis</a></dt>
+
+ <dd>Sending files which contain their own HTTP headers.</dd>
+ </dl>
+
+ <h2>Dynamic Content</h2>
+
+ <dl>
+ <dt><a href="mod_include.html">mod_include</a></dt>
+
+ <dd>Server-parsed documents.</dd>
+
+ <dt><a href="mod_cgi.html">mod_cgi</a></dt>
+
+ <dd>Invoking CGI scripts.</dd>
+
+ <dt><a href="mod_cgid.html">mod_cgid</a></dt>
+
+ <dd>Invoking CGI scripts using an external daemon.</dd>
+
+ <dt><a href="mod_actions.html">mod_actions</a></dt>
+
+ <dd>Executing CGI scripts based on media type or request
+ method.</dd>
+
+ <dt><a href="mod_isapi.html">mod_isapi</a></dt>
+
+ <dd>Windows ISAPI Extension support</dd>
+
+ <dt><a href="mod_ext_filter.html">mod_ext_filter</a></dt>
+
+ <dd>Filtering content with external programs.</dd>
+
+ <dt><a href="mod_suexec.html">mod_suexec</a></dt>
+
+ <dd>Run CGI requests as a specified user and group.</dd>
+ </dl>
+
+ <h2>Internal Content Handlers</h2>
+
+ <dl>
+ <dt><a href="mod_status.html">mod_status</a></dt>
+
+ <dd>Server status display</dd>
+
+ <dt><a href="mod_info.html">mod_info</a></dt>
+
+ <dd>Server configuration information</dd>
+ </dl>
+
+ <h2>Logging</h2>
+
+ <dl>
+ <dt><a href="mod_log_config.html">mod_log_config</a></dt>
+
+ <dd>User-configurable logging replacement for
+ mod_log_common.</dd>
+
+ <dt><a href="mod_usertrack.html">mod_usertrack</a></dt>
+
+ <dd>User tracking using Cookies</dd>
+ </dl>
+
+ <h2>Miscellaneous</h2>
+
+ <dl>
+ <dt><a href="mod_imap.html">mod_imap</a></dt>
+
+ <dd>The imagemap file handler.</dd>
+
+ <dt><a href="mod_proxy.html">mod_proxy</a></dt>
+
+ <dd>Caching proxy abilities</dd>
+
+ <dt><a href="mod_so.html">mod_so</a></dt>
+
+ <dd>Support for loading modules at runtime</dd>
+
+ <dt><a href="mod_file_cache.html">mod_file_cache</a></dt>
+
+ <dd>Caching files in memory for faster serving.</dd>
+
+ <dt><a href="mod_dav.html">mod_dav</a></dt>
+
+ <dd>Class 1,2 <a href="http://www.webdav.org">WebDAV</a> HTTP
+ extensions</dd>
+
+ <dt><a href="mod_ldap.html">mod_ldap</a></dt>
+
+ <dd>LDAP connection pool and shared memory cache.</dd>
+ </dl>
+
+ <h2>Development</h2>
+
+ <dl>
+ <dt><a href="mod_example.html">mod_example</a></dt>
+
+ <dd>Demonstrates Apache API</dd>
+ </dl>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!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 list of modules <A
-HREF="index-bytype.html">sorted by type</A> and the complete
-alphabetical list of <A HREF="directives.html">all Apache
-directives</A>.
-
-</P>
-
-<h2>Core Features and Multi-Processing Modules</h2>
-
-<DL>
-<DT><A HREF="core.html">Core</A>
-<DD>Core Apache features.
-<DT><A HREF="threaded.html">threaded</A>
-<DD>Multi-Processing Module with Threading via Pthreads; Variable number
-of processes, constant number of threads/child
-<DT><a href="mpm_winnt.html">mpm_winnt</a>
-<DD>Multi-Processing Module with a single control process and a single
-server process with multiple threads for Windows NT
-<DT><a href="perchild.html">perchild</a>
-<DD>Multi-Processing Module with the ability to server different
-virtual hosts under different userids.
-<DT><a href="prefork.html">prefork</a>
-<DD>Non-threaded preforking processes model similar to Apache 1.3
-</DL>
-
-<h2>Other Modules</h2>
-
-<DL>
-<DT><A HREF="mod_access.html">mod_access</A>
-<DD>Access control based on client hostname or IP address.
-<DT><A HREF="mod_actions.html">mod_actions</A>
-<DD>Executing CGI scripts based on media type or request method.
-<DT><A HREF="mod_alias.html">mod_alias</A>
-<DD>Mapping different parts of the host filesystem in the document tree,
- and URL redirection.
-<DT><A HREF="mod_asis.html">mod_asis</A>
-<DD>Sending files which contain their own HTTP headers.
-<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 access to authenticated areas.
-<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
-<DT><A HREF="mod_auth_ldap.html">mod_auth_ldap</A>
-<DD>User authentication using LDAP.
-<DT><A HREF="mod_autoindex.html">mod_autoindex</A>
-<DD>Automatic directory listings.
-<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_cgid.html">mod_cgid</A>
-<DD>Invoking CGI scripts using an external daemon.
-<DT><A HREF="mod_charset_lite.html">mod_charset_lite</A>
-<DD>Configuring character set translation.
-<DT><A HREF="mod_dav.html">mod_dav</A>
-<DD>Class 1,2 <A HREF="http://www.webdav.org">WebDAV</A> HTTP extensions
-<DT><A HREF="mod_dir.html">mod_dir</A>
-<DD>Basic directory handling.
-<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>
-<DD>Demonstrates Apache API
-<DT><A HREF="mod_expires.html">mod_expires</A>
-<DD>Apply Expires: headers to resources
-<DT><A HREF="mod_ext_filter.html">mod_ext_filter</A>
-<DD>Filtering output with external programs.
-<DT><A HREF="mod_file_cache.html">mod_file_cache</A>
-<DD>Caching files in memory for faster serving.
-<DT><A HREF="mod_headers.html">mod_headers</A>
-<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_ldap.html">mod_ldap</A>
-<DD>LDAP connection pool and shared memory cache.
-<DT><A HREF="mod_log_config.html">mod_log_config</A>
-<DD>User-configurable logging replacement for mod_log_common.
-<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_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>
-<DD>Powerful URI-to-filename mapping using regular expressions
-<DT><A HREF="mod_setenvif.html">mod_setenvif</A>
-<DD>Set environment variables based on client information
-<DT><A HREF="mod_so.html">mod_so</A>
-<DD>Support for loading modules at runtime
-<DT><A HREF="mod_speling.html">mod_speling</A>
-<DD>Automatically correct minor typos in URLs
-<DT><A HREF="mod_status.html">mod_status</A>
-<DD>Server status display
-<DT><A HREF="mod_suexec.html">mod_suexec</A>
-<DD>Run CGI requests as a specified user and group.
-<DT><A HREF="mod_userdir.html">mod_userdir</A>
-<DD>User home directories.
-<DT><A HREF="mod_unique_id.html">mod_unique_id</A>
-<DD>Generate unique request identifier for every request
-<DT><A HREF="mod_usertrack.html">mod_usertrack</A>
-<DD>User tracking using Cookies (replacement for mod_cookies.c)
-<DT><A HREF="mod_vhost_alias.html">mod_vhost_alias</A>
-<DD>Support for dynamically configured mass virtual hosting
-</DL>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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 list of modules <a
+ href="index-bytype.html">sorted by type</a> and the complete
+ alphabetical list of <a href="directives.html">all Apache
+ directives</a>.</p>
+
+ <h2>Core Features and Multi-Processing Modules</h2>
+
+ <dl>
+ <dt><a href="core.html">Core</a></dt>
+
+ <dd>Core Apache features.</dd>
+
+ <dt><a href="threaded.html">threaded</a></dt>
+
+ <dd>Multi-Processing Module with Threading via Pthreads;
+ Variable number of processes, constant number of
+ threads/child</dd>
+
+ <dt><a href="mpm_winnt.html">mpm_winnt</a></dt>
+
+ <dd>Multi-Processing Module with a single control process and
+ a single server process with multiple threads for Windows
+ NT</dd>
+
+ <dt><a href="perchild.html">perchild</a></dt>
+
+ <dd>Multi-Processing Module with the ability to server
+ different virtual hosts under different userids.</dd>
+
+ <dt><a href="prefork.html">prefork</a></dt>
+
+ <dd>Non-threaded preforking processes model similar to Apache
+ 1.3</dd>
+ </dl>
+
+ <h2>Other Modules</h2>
+
+ <dl>
+ <dt><a href="mod_access.html">mod_access</a></dt>
+
+ <dd>Access control based on client hostname or IP
+ address.</dd>
+
+ <dt><a href="mod_actions.html">mod_actions</a></dt>
+
+ <dd>Executing CGI scripts based on media type or request
+ method.</dd>
+
+ <dt><a href="mod_alias.html">mod_alias</a></dt>
+
+ <dd>Mapping different parts of the host filesystem in the
+ document tree, and URL redirection.</dd>
+
+ <dt><a href="mod_asis.html">mod_asis</a></dt>
+
+ <dd>Sending files which contain their own HTTP headers.</dd>
+
+ <dt><a href="mod_auth.html">mod_auth</a></dt>
+
+ <dd>User authentication using text files.</dd>
+
+ <dt><a href="mod_auth_anon.html">mod_auth_anon</a></dt>
+
+ <dd>Anonymous user access to authenticated areas.</dd>
+
+ <dt><a href="mod_auth_db.html">mod_auth_db</a></dt>
+
+ <dd>User authentication using Berkeley DB files.</dd>
+
+ <dt><a href="mod_auth_dbm.html">mod_auth_dbm</a></dt>
+
+ <dd>User authentication using DBM files.</dd>
+
+ <dt><a href="mod_auth_digest.html">mod_auth_digest</a></dt>
+
+ <dd>MD5 authentication</dd>
+
+ <dt><a href="mod_auth_ldap.html">mod_auth_ldap</a></dt>
+
+ <dd>User authentication using LDAP.</dd>
+
+ <dt><a href="mod_autoindex.html">mod_autoindex</a></dt>
+
+ <dd>Automatic directory listings.</dd>
+
+ <dt><a href="mod_cern_meta.html">mod_cern_meta</a></dt>
+
+ <dd>Support for HTTP header metafiles.</dd>
+
+ <dt><a href="mod_cgi.html">mod_cgi</a></dt>
+
+ <dd>Invoking CGI scripts.</dd>
+
+ <dt><a href="mod_cgid.html">mod_cgid</a></dt>
+
+ <dd>Invoking CGI scripts using an external daemon.</dd>
+
+ <dt><a href="mod_charset_lite.html">mod_charset_lite</a></dt>
+
+ <dd>Configuring character set translation.</dd>
+
+ <dt><a href="mod_dav.html">mod_dav</a></dt>
+
+ <dd>Class 1,2 <a href="http://www.webdav.org">WebDAV</a> HTTP
+ extensions</dd>
+
+ <dt><a href="mod_dir.html">mod_dir</a></dt>
+
+ <dd>Basic directory handling.</dd>
+
+ <dt><a href="mod_env.html">mod_env</a></dt>
+
+ <dd>Passing of environments to CGI scripts</dd>
+
+ <dt><a href="mod_example.html">mod_example</a></dt>
+
+ <dd>Demonstrates Apache API</dd>
+
+ <dt><a href="mod_expires.html">mod_expires</a></dt>
+
+ <dd>Apply Expires: headers to resources</dd>
+
+ <dt><a href="mod_ext_filter.html">mod_ext_filter</a></dt>
+
+ <dd>Filtering output with external programs.</dd>
+
+ <dt><a href="mod_file_cache.html">mod_file_cache</a></dt>
+
+ <dd>Caching files in memory for faster serving.</dd>
+
+ <dt><a href="mod_headers.html">mod_headers</a></dt>
+
+ <dd>Add arbitrary HTTP headers to resources</dd>
+
+ <dt><a href="mod_imap.html">mod_imap</a></dt>
+
+ <dd>The imagemap file handler.</dd>
+
+ <dt><a href="mod_include.html">mod_include</a></dt>
+
+ <dd>Server-parsed documents.</dd>
+
+ <dt><a href="mod_info.html">mod_info</a></dt>
+
+ <dd>Server configuration information</dd>
+
+ <dt><a href="mod_isapi.html">mod_isapi</a></dt>
+
+ <dd>Windows ISAPI Extension support</dd>
+
+ <dt><a href="mod_ldap.html">mod_ldap</a></dt>
+
+ <dd>LDAP connection pool and shared memory cache.</dd>
+
+ <dt><a href="mod_log_config.html">mod_log_config</a></dt>
+
+ <dd>User-configurable logging replacement for
+ mod_log_common.</dd>
+
+ <dt><a href="mod_mime.html">mod_mime</a></dt>
+
+ <dd>Determining document types using file extensions.</dd>
+
+ <dt><a href="mod_mime_magic.html">mod_mime_magic</a></dt>
+
+ <dd>Determining document types using "magic numbers".</dd>
+
+ <dt><a href="mod_negotiation.html">mod_negotiation</a></dt>
+
+ <dd>Content negotiation.</dd>
+
+ <dt><a href="mod_proxy.html">mod_proxy</a></dt>
+
+ <dd>Caching proxy abilities</dd>
+
+ <dt><a href="mod_rewrite.html">mod_rewrite</a></dt>
+
+ <dd>Powerful URI-to-filename mapping using regular
+ expressions</dd>
+
+ <dt><a href="mod_setenvif.html">mod_setenvif</a></dt>
+
+ <dd>Set environment variables based on client
+ information</dd>
+
+ <dt><a href="mod_so.html">mod_so</a></dt>
+
+ <dd>Support for loading modules at runtime</dd>
+
+ <dt><a href="mod_speling.html">mod_speling</a></dt>
+
+ <dd>Automatically correct minor typos in URLs</dd>
+
+ <dt><a href="mod_status.html">mod_status</a></dt>
+
+ <dd>Server status display</dd>
+
+ <dt><a href="mod_suexec.html">mod_suexec</a></dt>
+
+ <dd>Run CGI requests as a specified user and group.</dd>
+
+ <dt><a href="mod_userdir.html">mod_userdir</a></dt>
+
+ <dd>User home directories.</dd>
+
+ <dt><a href="mod_unique_id.html">mod_unique_id</a></dt>
+
+ <dd>Generate unique request identifier for every request</dd>
+
+ <dt><a href="mod_usertrack.html">mod_usertrack</a></dt>
+
+ <dd>User tracking using Cookies (replacement for
+ mod_cookies.c)</dd>
+
+ <dt><a href="mod_vhost_alias.html">mod_vhost_alias</a></dt>
+
+ <dd>Support for dynamically configured mass virtual
+ hosting</dd>
+ </dl>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
rel="Help"><strong>Module:</strong></a> mod_foo
<p><em>Directive3</em> is described here, and so on.
-
-
<!--#include virtual="footer.html" -->
</p>
</body>
-<!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 provides access control based on client hostname, IP
-address, or other characteristics of the client request.
-</P>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_access.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> access_module
-</P>
-
-<h2>Summary</h2>
-
-<p>The directives provided by mod_access are used in <CODE><A
-HREF="core.html#directory"><Directory></A>, <A
-HREF="core.html#files"><Files></A>,</code> and <code> <A
-HREF="core.html#location"><Location></A></code> sections as
-well as <code><a
-href="core.html#accessfilename">.htaccess</a></code> files
-to control access to particular parts of the server. Access
-can be controlled based on the client hostname, IP address,
-or other characteristics of the client request, as captured
-in <a href="../env.html">environment variables</a>. The
-<code>Allow</code> and <code>Deny</code> directives are used
-to specify which clients are or are not allowed access to the
-server, while the <code>Order</code> directive sets the
-default access state, and configures how the <code>Allow</code>
-and <code>Deny</code> directives interact with each other.</p>
-
-<p>Both host-based access restrictions and password-based
-authentication may be implemented simultaneously. In
-that case, the <a href="core.html#satsify">Satisfy</a> directive
-is used to determine how the two sets of restrictions
-interact.</p>
-
-<p>In general, access restriction directives apply to all access
-methods (<code>GET</code>, <code>PUT</code>, <code>POST</code>, etc).
-This is the desired behavior in most cases. However, it is possible
-to restrict some methods, while leaving other methods unrestricted, by
-enclosing the directives in a <a
-href="core.html#limit"><Limit></a> section.</p>
-
-<H2>Directives</H2>
-
-<UL>
-<LI><A HREF="#allow">Allow</A>
-<LI><A HREF="#deny">Deny</A>
-<LI><A HREF="#order">Order</A>
-</UL>
-
-<P>See also <A HREF="core.html#satisfy">Satisfy</A>
- and <A HREF="core.html#require">Require</A>.
-
-<HR>
-
-
-<H2><A NAME="allow">Allow</a> <a name="allowfromenv">directive</A></H2>
-<P>
-<!--%plaintext <?INDEX {\tt Allow} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> Allow from
- all|<EM>host</em>|env=<em>env-variable</em>
- [<em>host</em>|env=<em>env-variable</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 <code>Allow</code> directive affects which hosts can access an
-area of the server. Access can be controlled by hostname, IP Address,
-IP Address range, or by other characteristics of the client
-request captured in environment variables.</p>
-
-<p>The first argument to this directive is always <code>from</code>.
-The subsequent arguments can take three different forms. If
-<code>Allow from all</code> is specified, then all hosts are allowed
-access, subject to the configuration of the <code>Deny</code> and
-<code>Order</code> directives as discussed below. To allow only
-particular hosts or groups of hosts to access the server, the
-<em>host</em> can be specified in any of the following formats:</p>
-<DL>
-
-<DT>A (partial) domain-name</dt> <dd>Example: <code>Allow from
-apache.org</code><br> Hosts whose names match, or end in, this string
-are allowed access. Only complete components are matched, so the
-above example will match <code>foo.apache.org</code> but it will not
-match <code>fooapache.org</code>. This configuration will cause the
-server to perform a reverse DNS lookup on the client IP address,
-regardless of the setting of the <a
-href="core.html#hostnamelookups">HostNameLookups</a> directive.</dd>
-
-<DT>A full IP address</dt>
-<DD>Example: <code>Allow from 10.1.2.3</code><br>
-An IP address of a host allowed access</dd>
-
-<DT>A partial IP address</dt>
-<dd>Example: <code>Allow from 10.1</code><br>
-The first 1 to 3 bytes of an IP address, for subnet restriction.</dd>
-
-<DT>A network/netmask pair</dt>
-<dd>Example: <code>Allow from 10.1.0.0/255.255.0.0</code><br>
- A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet
- restriction.</dd>
-
-<DT>A network/nnn CIDR specification</dt> <dd>Example: <code>Allow
-from 10.1.0.0/16</code><br> Similar to the previous case, except the
-netmask consists of nnn high-order 1 bits.</dd>
-</DL>
-
-<p>Note that the last three examples above match exactly the
-same set of hosts.</p>
-
-<p>The third format of the arguments to the <code>Allow</code>
-directive allows access to the server to be controlled based on the
-existence of an <a href="../env.html">environment variable</a>. When
-<code>Allow from env=</code><em>env-variable</em> is specified, then
-the request is allowed access if the environment variable
-<em>env-variable</em> exists. The server provides the ability to set
-environment variables in a flexible way based on characteristics of
-the client request using the directives provided by <a
-href="mod_setenvif.html">mod_setenvif</a>. Therefore, this directive
-can be used to allow access based on such factors as the clients
-<code>User-Agent</code> (browser type), <code>Referer</code>, or other
-HTTP request header fields.</P>
-
-<P>
-Example:
-</P>
-<BLOCKQUOTE><PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>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 provides access control based on client
+ hostname, IP address, or other characteristics of the client
+ request.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_access.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ access_module</p>
+
+ <h2>Summary</h2>
+
+ <p>The directives provided by mod_access are used in <code><a
+ href="core.html#directory"><Directory></a>, <a
+ href="core.html#files"><Files></a>,</code> and <code><a
+ href="core.html#location"><Location></a></code> sections
+ as well as <code><a
+ href="core.html#accessfilename">.htaccess</a></code> files to
+ control access to particular parts of the server. Access can be
+ controlled based on the client hostname, IP address, or other
+ characteristics of the client request, as captured in <a
+ href="../env.html">environment variables</a>. The
+ <code>Allow</code> and <code>Deny</code> directives are used to
+ specify which clients are or are not allowed access to the
+ server, while the <code>Order</code> directive sets the default
+ access state, and configures how the <code>Allow</code> and
+ <code>Deny</code> directives interact with each other.</p>
+
+ <p>Both host-based access restrictions and password-based
+ authentication may be implemented simultaneously. In that case,
+ the <a href="core.html#satsify">Satisfy</a> directive is used
+ to determine how the two sets of restrictions interact.</p>
+
+ <p>In general, access restriction directives apply to all
+ access methods (<code>GET</code>, <code>PUT</code>,
+ <code>POST</code>, etc). This is the desired behavior in most
+ cases. However, it is possible to restrict some methods, while
+ leaving other methods unrestricted, by enclosing the directives
+ in a <a href="core.html#limit"><Limit></a> section.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#allow">Allow</a></li>
+
+ <li><a href="#deny">Deny</a></li>
+
+ <li><a href="#order">Order</a></li>
+ </ul>
+
+ <p>See also <a href="core.html#satisfy">Satisfy</a> and <a
+ href="core.html#require">Require</a>.</p>
+ <hr />
+
+ <h2><a id="allow" name="allow">Allow</a> <a id="allowfromenv"
+ name="allowfromenv">directive</a></h2>
+
+ <p><!--%plaintext <?INDEX {\tt Allow} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> Allow from
+ all|<em>host</em>|env=<em>env-variable</em>
+ [<em>host</em>|env=<em>env-variable</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 <code>Allow</code> directive affects which hosts can
+ access an area of the server. Access can be controlled by
+ hostname, IP Address, IP Address range, or by other
+ characteristics of the client request captured in environment
+ variables.</p>
+
+ <p>The first argument to this directive is always
+ <code>from</code>. The subsequent arguments can take three
+ different forms. If <code>Allow from all</code> is specified,
+ then all hosts are allowed access, subject to the configuration
+ of the <code>Deny</code> and <code>Order</code> directives as
+ discussed below. To allow only particular hosts or groups of
+ hosts to access the server, the <em>host</em> can be specified
+ in any of the following formats:</p>
+
+ <dl>
+ <dt>A (partial) domain-name</dt>
+
+ <dd>Example: <code>Allow from apache.org</code><br />
+ Hosts whose names match, or end in, this string are allowed
+ access. Only complete components are matched, so the above
+ example will match <code>foo.apache.org</code> but it will
+ not match <code>fooapache.org</code>. This configuration will
+ cause the server to perform a reverse DNS lookup on the
+ client IP address, regardless of the setting of the <a
+ href="core.html#hostnamelookups">HostNameLookups</a>
+ directive.</dd>
+
+ <dt>A full IP address</dt>
+
+ <dd>Example: <code>Allow from 10.1.2.3</code><br />
+ An IP address of a host allowed access</dd>
+
+ <dt>A partial IP address</dt>
+
+ <dd>Example: <code>Allow from 10.1</code><br />
+ The first 1 to 3 bytes of an IP address, for subnet
+ restriction.</dd>
+
+ <dt>A network/netmask pair</dt>
+
+ <dd>Example: <code>Allow from
+ 10.1.0.0/255.255.0.0</code><br />
+ A network a.b.c.d, and a netmask w.x.y.z. For more
+ fine-grained subnet restriction.</dd>
+
+ <dt>A network/nnn CIDR specification</dt>
+
+ <dd>Example: <code>Allow from 10.1.0.0/16</code><br />
+ Similar to the previous case, except the netmask consists of
+ nnn high-order 1 bits.</dd>
+ </dl>
+
+ <p>Note that the last three examples above match exactly the
+ same set of hosts.</p>
+
+ <p>The third format of the arguments to the <code>Allow</code>
+ directive allows access to the server to be controlled based on
+ the existence of an <a href="../env.html">environment
+ variable</a>. When <code>Allow from
+ env=</code><em>env-variable</em> is specified, then the request
+ is allowed access if the environment variable
+ <em>env-variable</em> exists. The server provides the ability
+ to set environment variables in a flexible way based on
+ characteristics of the client request using the directives
+ provided by <a href="mod_setenvif.html">mod_setenvif</a>.
+ Therefore, this directive can be used to allow access based on
+ such factors as the clients <code>User-Agent</code> (browser
+ type), <code>Referer</code>, or other HTTP request header
+ fields.</p>
+
+ <p>Example:</p>
+
+ <blockquote>
+<pre>
SetEnvIf User-Agent ^KnockKnock/2.0 let_me_in
<Directory /docroot>
Order Deny,Allow
Deny from all
Allow from env=let_me_in
</Directory>
-</PRE></BLOCKQUOTE>
-
-<p>In this case, browsers with a user-agent string beginning with
-<TT>KnockKnock/2.0</TT> will be allowed access, and all others will be
-denied.</p>
-<P>
-See also <a href="#deny">Deny</a>, <A HREF="#order">Order</A>
-and <A HREF="mod_setenvif.html#SetEnvIf">SetEnvIf</A>.
-</P>
-<HR>
-
-<H2><A NAME="deny">Deny</a> <a name="denyfromenv">directive</A></H2>
-<P>
-<!--%plaintext <?INDEX {\tt Deny} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> Deny from
- all|<EM>host</em>|env=<em>env-variable</em>
- [<em>host</em>|env=<em>env-variable</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>This directive allows access to the server to be restricted based
-on hostname, IP address, or environment variables. The arguments for
-the <code>Deny</code> directive are identical to the arguments for the
-<a href="#allow">Allow</a> directive.</p>
-
-<p>See also <a href="#allow">Allow</a>, <A HREF="#order">Order</A>
-and <A HREF="mod_setenvif.html#SetEnvIf">SetEnvIf</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 <CODE>Order</CODE> directive controls the default access state and
-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</dt> <DD>The <CODE>Deny</CODE> directives are evaluated
-before the <CODE>Allow</CODE> directives. Access is allowed
-by default. Any client which does not match a <code>Deny</code>
-directive or does match an <code>Allow</code> directive will be
-allowed access to the server.</dd>
-
-<DT>Allow,Deny</dt> <DD>The <CODE>Allow</CODE> directives are
-evaluated before the <CODE>Deny</CODE> directives. Access is
-denied by default. Any client which does not match
-an <code>Allow</code> directive or does match a <code>Deny</code>
-directive will be denied access to the server.</dd>
-
-<DT>Mutual-failure</dt> <DD>Only those hosts which appear on the
-<CODE>Allow</CODE> list and do not appear on the <CODE>Deny</CODE>
-list are granted access. This ordering has the same effect as
-<code>Order Allow,Deny</code> and is deprecated in favor of that
-configuration.</dd>
-</DL>
-
-<P>Keywords may only be separated by a comma; no whitespace is allowed
-between them. Note that in all cases every <CODE>Allow</CODE>
-and <CODE>Deny</CODE> statement is evaluated.</P>
-
-<P>In the following example, all hosts in the apache.org domain are
-allowed access; all other hosts are denied access.
-</P>
-
-<BLOCKQUOTE><CODE>
- Order Deny,Allow<BR>
- Deny from all<BR>
- Allow from apache.org<BR>
-</CODE></BLOCKQUOTE>
-
-<P>In the next example, all hosts in the apache.org domain are allowed
-access, except for the hosts which are in the foo.apache.org
-subdomain, who are denied access. All hosts not in the apache.org
-domain are denied access because the default state is to deny access
-to the server.
-</P>
-
-<blockquote><code>
- Order Allow,Deny<br>
- Allow from apache.org<br>
- Deny from foo.apache.org<br>
-</code></blockquote>
-
-<p>On the other hand, if the <code>Order</code> in the last example is
-changed to <code>Deny,Allow</code>, all hosts will be allowed access.
-This happens because, regardless of the actual ordering of the
-directives in the configuration file, the <code>Allow from
-apache.org</code> will be evaluated last and will override the
-<code>Deny from foo.apache.org</code>. All hosts not in the
-<code>apache.org</code> domain will also be allowed access because the
-default state will change to <em>allow</em>.</p>
-
-<p>The presence of an <code>Order</code> directive can
-affect access to a part of the server even in the absence
-of accompanying <code>Allow</code> and <code>Deny</code>
-directives because of its effect on the default access state.
-For example,</p>
-
-<blockquote><code>
-<Directory /www><br>
- Order Allow,Deny<br>
-</Directory>
-</code></blockquote>
-
-<p>will deny all access to the <code>/www</code> directory because
-the default access state will be set to <em>deny</em>.</p>
-
-<p>The <code>Order</code> directive controls the order of access
-directive processing only within each phase of the server's
-configuration processing. This implies, for example, that an
-<code>Allow</code> or <code>Deny</code> directive occurring
-in a <Location> section will always be evaluated after
-an <code>Allow</code> or <code>Deny</code> directive occurring
-in a <Directory> section or <code>.htaccess</code> file,
-regardless of the setting of the <code>Order</code> directive.
-For details on the merging of configuration sections,
-see the documentation on <a href="../sections.html">How Directory,
-Location and Files sections work</a>.</p>
-
-<P>See also: <A HREF="#deny">Deny</A> and <A HREF="#allow">Allow</A>.
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</pre>
+ </blockquote>
+
+ <p>In this case, browsers with a user-agent string beginning
+ with <tt>KnockKnock/2.0</tt> will be allowed access, and all
+ others will be denied.</p>
+
+ <p>See also <a href="#deny">Deny</a>, <a
+ href="#order">Order</a> and <a
+ href="mod_setenvif.html#SetEnvIf">SetEnvIf</a>.</p>
+ <hr />
+
+ <h2><a id="deny" name="deny">Deny</a> <a id="denyfromenv"
+ name="denyfromenv">directive</a></h2>
+
+ <p><!--%plaintext <?INDEX {\tt Deny} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> Deny from
+ all|<em>host</em>|env=<em>env-variable</em>
+ [<em>host</em>|env=<em>env-variable</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>This directive allows access to the server to be restricted
+ based on hostname, IP address, or environment variables. The
+ arguments for the <code>Deny</code> directive are identical to
+ the arguments for the <a href="#allow">Allow</a> directive.</p>
+
+ <p>See also <a href="#allow">Allow</a>, <a
+ href="#order">Order</a> and <a
+ href="mod_setenvif.html#SetEnvIf">SetEnvIf</a>.</p>
+ <hr />
+
+ <h2><a id="order" 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 <code>Order</code> directive controls the default access
+ state and 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</dt>
+
+ <dd>The <code>Deny</code> directives are evaluated before the
+ <code>Allow</code> directives. Access is allowed by default.
+ Any client which does not match a <code>Deny</code> directive
+ or does match an <code>Allow</code> directive will be allowed
+ access to the server.</dd>
+
+ <dt>Allow,Deny</dt>
+
+ <dd>The <code>Allow</code> directives are evaluated before
+ the <code>Deny</code> directives. Access is denied by
+ default. Any client which does not match an
+ <code>Allow</code> directive or does match a
+ <code>Deny</code> directive will be denied access to the
+ server.</dd>
+
+ <dt>Mutual-failure</dt>
+
+ <dd>Only those hosts which appear on the <code>Allow</code>
+ list and do not appear on the <code>Deny</code> list are
+ granted access. This ordering has the same effect as
+ <code>Order Allow,Deny</code> and is deprecated in favor of
+ that configuration.</dd>
+ </dl>
+
+ <p>Keywords may only be separated by a comma; no whitespace is
+ allowed between them. Note that in all cases every
+ <code>Allow</code> and <code>Deny</code> statement is
+ evaluated.</p>
+
+ <p>In the following example, all hosts in the apache.org domain
+ are allowed access; all other hosts are denied access.</p>
+
+ <blockquote>
+ <code>Order Deny,Allow<br />
+ Deny from all<br />
+ Allow from apache.org<br />
+ </code>
+ </blockquote>
+
+ <p>In the next example, all hosts in the apache.org domain are
+ allowed access, except for the hosts which are in the
+ foo.apache.org subdomain, who are denied access. All hosts not
+ in the apache.org domain are denied access because the default
+ state is to deny access to the server.</p>
+
+ <blockquote>
+ <code>Order Allow,Deny<br />
+ Allow from apache.org<br />
+ Deny from foo.apache.org<br />
+ </code>
+ </blockquote>
+
+ <p>On the other hand, if the <code>Order</code> in the last
+ example is changed to <code>Deny,Allow</code>, all hosts will
+ be allowed access. This happens because, regardless of the
+ actual ordering of the directives in the configuration file,
+ the <code>Allow from apache.org</code> will be evaluated last
+ and will override the <code>Deny from foo.apache.org</code>.
+ All hosts not in the <code>apache.org</code> domain will also
+ be allowed access because the default state will change to
+ <em>allow</em>.</p>
+
+ <p>The presence of an <code>Order</code> directive can affect
+ access to a part of the server even in the absence of
+ accompanying <code>Allow</code> and <code>Deny</code>
+ directives because of its effect on the default access state.
+ For example,</p>
+
+ <blockquote>
+ <code><Directory /www><br />
+ Order Allow,Deny<br />
+ </Directory></code>
+ </blockquote>
+
+ <p>will deny all access to the <code>/www</code> directory
+ because the default access state will be set to
+ <em>deny</em>.</p>
+
+ <p>The <code>Order</code> directive controls the order of
+ access directive processing only within each phase of the
+ server's configuration processing. This implies, for example,
+ that an <code>Allow</code> or <code>Deny</code> directive
+ occurring in a <Location> section will always be
+ evaluated after an <code>Allow</code> or <code>Deny</code>
+ directive occurring in a <Directory> section or
+ <code>.htaccess</code> file, regardless of the setting of the
+ <code>Order</code> directive. For details on the merging of
+ configuration sections, see the documentation on <a
+ href="../sections.html">How Directory, Location and Files
+ sections work</a>.</p>
+
+ <p>See also: <a href="#deny">Deny</a> and <a
+ href="#allow">Allow</a>. <!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
+
-<!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 provides for executing CGI scripts based on media type or
-request method.
-</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_actions.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> actions_module
-</P>
-
-<H2>Summary</H2>
-<P>
-This module has two directives. The Action directive lets you run CGI
-scripts whenever a file of a certain type is requested. The Script
-directive lets you run CGI scripts whenever a particular method is
-used in a request. This makes it much easier to execute scripts that
-process files.
-</P>
-
-<H2>Directives</H2>
-<UL>
-<LI><A HREF="#action">Action</A></LI>
-<LI><A HREF="#script">Script</A></LI>
-</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
-</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
-</P>
-
-<P>
-This directive adds an action, which will activate <i>cgi-script</i> when
-a file is requested using the method of <i>method</i>. It sends the
-URL and file path of the requested document using the standard
-CGI PATH_INFO and PATH_TRANSLATED environment variables.
-</P>
-<blockquote>
-Any arbitrary method name may be used. <b>Method names are
-case-sensitive</b>, so <code>Script PUT</code> and
-<code>Script put</code> have two entirely different effects.
-</blockquote>
-<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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>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 provides for executing CGI scripts based on
+ media type or request method.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_actions.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ actions_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This module has two directives. The Action directive lets
+ you run CGI scripts whenever a file of a certain type is
+ requested. The Script directive lets you run CGI scripts
+ whenever a particular method is used in a request. This makes
+ it much easier to execute scripts that process files.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#action">Action</a></li>
+
+ <li><a href="#script">Script</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="action" 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</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 id="script" 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</p>
+
+ <p>This directive adds an action, which will activate
+ <i>cgi-script</i> when a file is requested using the method of
+ <i>method</i>. It sends the URL and file path of the requested
+ document using the standard CGI PATH_INFO and PATH_TRANSLATED
+ environment variables.</p>
+
+ <blockquote>
+ Any arbitrary method name may be used. <b>Method names are
+ case-sensitive</b>, so <code>Script PUT</code> and
+ <code>Script put</code> have two entirely different
+ effects.
+ </blockquote>
+
+ <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>
# For <ISINDEX>-style searching
Script GET /cgi-bin/search
# A CGI PUT handler
Script PUT /~bob/put.cgi
-</PRE>
+</pre>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
-<!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 provides for mapping different parts of the
-host filesystem in the document tree, and for URL redirection.
-</P>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_alias.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> alias_module
-</P>
-
-<H2>Summary</H2>
-
-<P>The directives contained in this module allow for manipulation and
-control of URLs as requests arrive at the server. The
-<CODE>Alias</CODE> and <CODE>ScriptAlias</CODE> directives are used to
-map between URLs and filesystem paths. This allows for content which
-is not directly under the <A
-HREF="core.html#documentroot"><CODE>DocumentRoot</CODE></A> to be
-served as part of the web document tree. The <CODE>ScriptAlias</CODE>
-directive has the additional effect of marking the target directory as
-containing only CGI scripts.
-
-<P>The <CODE>Redirect</CODE> directives are used to instruct clients
-to make a new request with a different URL. They are often used
-when a resource has moved to a new location.
-
-<P>A more powerful and flexible set of directives for manipulating
-URLs is contained in the <A
-HREF="mod_rewrite.html"><CODE>mod_rewrite</CODE></A> module.
-
-
-<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 file-path</em>|<em>directory-path</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 file-path</em>|<em>directory-path</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>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-path, 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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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 provides for mapping different parts of the host
+ filesystem in the document tree, and for URL redirection.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_alias.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ alias_module</p>
+
+ <h2>Summary</h2>
+
+ <p>The directives contained in this module allow for
+ manipulation and control of URLs as requests arrive at the
+ server. The <code>Alias</code> and <code>ScriptAlias</code>
+ directives are used to map between URLs and filesystem paths.
+ This allows for content which is not directly under the <a
+ href="core.html#documentroot"><code>DocumentRoot</code></a> to
+ be served as part of the web document tree. The
+ <code>ScriptAlias</code> directive has the additional effect of
+ marking the target directory as containing only CGI
+ scripts.</p>
+
+ <p>The <code>Redirect</code> directives are used to instruct
+ clients to make a new request with a different URL. They are
+ often used when a resource has moved to a new location.</p>
+
+ <p>A more powerful and flexible set of directives for
+ manipulating URLs is contained in the <a
+ href="mod_rewrite.html"><code>mod_rewrite</code></a>
+ module.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#alias">Alias</a></li>
+
+ <li><a href="#aliasmatch">AliasMatch</a></li>
+
+ <li><a href="#redirect">Redirect</a></li>
+
+ <li><a href="#redirectmatch">RedirectMatch</a></li>
+
+ <li><a href="#redirecttemp">RedirectTemp</a></li>
+
+ <li><a href="#redirectperm">RedirectPermanent</a></li>
+
+ <li><a href="#scriptalias">ScriptAlias</a></li>
+
+ <li><a href="#scriptaliasmatch">ScriptAliasMatch</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="alias" 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
+ file-path</em>|<em>directory-path</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>
+
+ <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>
+
+ <p>See also <a href="#scriptalias">ScriptAlias</a>.</p>
+ <hr />
+
+ <h2><a id="aliasmatch" name="aliasmatch">AliasMatch</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AliasMatch <em>regex
+ file-path</em>|<em>directory-path</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>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-path, 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:</p>
+<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
-</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
-resource 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
-</P>
-
-<P>This directive is equivalent to <A HREF="#redirect">Redirect</A>,
-but makes use of standard regular expressions, instead of simple
-prefix matching. The supplied regular expression is matched against
-the URL-path, 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>
+</pre>
+ <br />
+ <br />
+
+ <hr />
+
+ <h2><a id="redirect" 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</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 resource has moved temporarily. The <em>status</em>
+ argument can be used to return other HTTP status codes:</p>
+
+ <dl>
+ <dt>permanent</dt>
+
+ <dd>Returns a permanent redirect status (301) indicating that
+ the resource has moved permanently.</dd>
+
+ <dt>temp</dt>
+
+ <dd>Returns a temporary redirect status (302). This is the
+ default.</dd>
+
+ <dt>seeother</dt>
+
+ <dd>Returns a "See Other" status (303) indicating that the
+ resource has been replaced.</dd>
+
+ <dt>gone</dt>
+
+ <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.</dd>
+ </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 id="redirectmatch"
+ 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</p>
+
+ <p>This directive is equivalent to <a
+ href="#redirect">Redirect</a>, but makes use of standard
+ regular expressions, instead of simple prefix matching. The
+ supplied regular expression is matched against the URL-path,
+ 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:</p>
+<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
-</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
-</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 file-path</em>|<em>directory-path</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 the second argument which is a full
-pathname in the local filesystem.
-<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 file-path</em>|<em>directory-path</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>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-path, 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>
+</pre>
+ <br />
+ <br />
+
+ <hr />
+
+ <h2><a id="redirecttemp" 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</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 id="redirectperm" 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</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 id="scriptalias" 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 file-path</em>|<em>directory-path</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 the second argument which is a
+ full pathname in the local filesystem.</p>
+
+ <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 id="scriptaliasmatch"
+ name="scriptaliasmatch">ScriptAliasMatch</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ScriptAliasMatch
+ <em>regex file-path</em>|<em>directory-path</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>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-path,
+ 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:</p>
+<pre>
ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
-</PRE>
-</P>
+</pre>
+ <br />
+ <br />
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
-<!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>
-
-<P>This module provides for user authentication using text files.
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_auth.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> auth_module
-</P>
-
-<H2>Summary</H2>
-
-<P>This module allows the use of HTTP Basic Authentication to restrict
-access by looking up users in plain text password and group files.
-Similar functionality and greater scalability is provided by <A
-HREF="mod_auth_dbm.html">mod_auth_dbm</A> and <A
-HREF="mod_auth_db.html">mod_auth_db</A>. HTTP Digest Authentication
-is provided by <A HREF="mod_auth_digest.html">mod_auth_digest</A>.
-
-
-<H2>Directives</H2>
-
-<UL>
-<LI><A HREF="#authgroupfile">AuthGroupFile</A>
-<LI><A HREF="#authuserfile">AuthUserFile</A>
-<LI><A HREF="#authauthoritative">AuthAuthoritative</A>
-</UL>
-
-<P>See also: <A HREF="core.html#require">require</A>
-and <A HREF="core.html#satisfy">satisfy</A>.</P>
-
-<HR>
-
-
-<H2><A NAME="authgroupfile">AuthGroupFile</A> directive</H2>
-<!--%plaintext <?INDEX {\tt AuthGroupFile} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthGroupFile <EM>file-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> 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>File-path</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> directive</H2>
-<!--%plaintext <?INDEX {\tt AuthUserFile} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthUserFile <EM>file-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> 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>File-path</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 <a href="../programs/htpasswd.html">htpasswd</a> 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> directive</H2>
-<!--%plaintext <?INDEX {\tt AuthAuthoritative} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthAuthoritative on|off<BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> <CODE>AuthAuthoritative 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> 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 <CODE>Require</CODE> 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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module provides for user authentication using text
+ files.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_auth.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ auth_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This module allows the use of HTTP Basic Authentication to
+ restrict access by looking up users in plain text password and
+ group files. Similar functionality and greater scalability is
+ provided by <a href="mod_auth_dbm.html">mod_auth_dbm</a> and <a
+ href="mod_auth_db.html">mod_auth_db</a>. HTTP Digest
+ Authentication is provided by <a
+ href="mod_auth_digest.html">mod_auth_digest</a>.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#authgroupfile">AuthGroupFile</a></li>
+
+ <li><a href="#authuserfile">AuthUserFile</a></li>
+
+ <li><a href="#authauthoritative">AuthAuthoritative</a></li>
+ </ul>
+
+ <p>See also: <a href="core.html#require">require</a> and <a
+ href="core.html#satisfy">satisfy</a>.</p>
+ <hr />
+
+ <h2><a id="authgroupfile"
+ name="authgroupfile">AuthGroupFile</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt AuthGroupFile} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthGroupFile
+ <em>file-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> 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>File-path</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>
+
+ <p>Each line of the group file contains a groupname followed by
+ a colon, followed by the member usernames separated by spaces.
+ Example:</p>
+
+ <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>
+
+ <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 id="authuserfile" name="authuserfile">AuthUserFile</a>
+ directive</h2>
+ <!--%plaintext <?INDEX {\tt AuthUserFile} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthUserFile
+ <em>file-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> 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>File-path</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>
+
+ <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>
+
+ <p>The utility <a href="../programs/htpasswd.html">htpasswd</a>
+ 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>
+
+ <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>
+
+ <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 id="authauthoritative"
+ name="authauthoritative">AuthAuthoritative</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt AuthAuthoritative} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthAuthoritative
+ on|off<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a>
+ <code>AuthAuthoritative 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> 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>
+
+ <p>So if a userID appears in the database of more than one
+ module; or if a valid <code>Require</code> 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>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <p>See also <a href="core.html#authname">AuthName</a>, <a
+ href="core.html#authtype">AuthType</a> and <a
+ href="#authgroupfile">AuthGroupFile</a>.</p>
+
+ <p><!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
-<!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 allows "anonymous" user access to authenticated areas.
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_auth_anon.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> anon_auth_module
-</P>
-
-
-<H2>Summary</H2>
-
-<P>This module 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>
-
-<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>
-
-<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>
-
-<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="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</em> [<em>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 on|off<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 on|off<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 on|off<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 on|off<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 on|off<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>).
-
-
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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 allows "anonymous" user access to authenticated
+ areas.
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_auth_anon.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ anon_auth_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This module 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>
+
+ <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>
+
+ <h2><a id="Directives" name="Directives">Directives</a></h2>
+
+ <ul>
+ <li><a href="#anonymous">Anonymous</a></li>
+
+ <li><a href="#Authoritative">Anonymous_Authoritative</a></li>
+
+ <li><a href="#LogEmail">Anonymous_LogEmail</a></li>
+
+ <li><a href="#MustGiveEmail">Anonymous_MustGiveEmail</a></li>
+
+ <li><a href="#NoUserID">Anonymous_NoUserID</a></li>
+
+ <li><a href="#VerifyEmail">Anonymous_VerifyEmail</a></li>
+ </ul>
+
+ <h2><a id="Example" 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>
+
+ <li>It insists that the user enters a password.
+ (<code>Anonymous_MustGiveEmail</code>)</li>
+
+ <li>The password entered must be a valid email address, ie.
+ contain at least one '@' and a '.'.
+ (<code>Anonymous_VerifyEmail</code>)</li>
+
+ <li>The userID must be one of <code>anonymous guest www test
+ welcome</code> and comparison is <strong>not</strong> case
+ sensitive.</li>
+
+ <li>And the Email addresses entered in the passwd field are
+ logged to the error log file
+ (<code>Anonymous_LogEmail</code>)</li>
+ </ul>
+
+ <p>Excerpt of access.conf:</p>
+
+ <blockquote>
+ <code>Anonymous_NoUserId off<br />
+ Anonymous_MustGiveEmail on<br />
+ Anonymous_VerifyEmail on<br />
+ Anonymous_LogEmail on<br />
+ Anonymous anonymous guest www test welcome</code>
+
+ <p><code>AuthName "Use 'anonymous' & Email address for
+ guest entry"<br />
+ AuthType basic</code></p>
+
+ <p><code># 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 />
+ </code></p>
+
+ <p><code>Require valid-user<br />
+ </Files><br />
+ </code></p>
+ </blockquote>
+ <hr />
+
+ <h2><a id="anonymous" 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</em>
+ [<em>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>
+
+ <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>
+
+ <p>Example:<br />
+ <code>Anonymous anonymous "Not Registered" 'I don\'t
+ know'</code></p>
+
+ <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'.</p>
+ <hr />
+
+ <h2><a id="Authoritative"
+ name="Authoritative">Anonymous_Authoritative directive</a></h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> Anonymous_Authoritative
+ on|off<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>
+
+ <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.</p>
+ <hr />
+
+ <h2><a id="LogEmail" name="LogEmail">Anonymous_LogEmail
+ directive</a></h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> Anonymous_LogEmail
+ on|off<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.</p>
+ <hr />
+
+ <h2><a id="MustGiveEmail"
+ 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
+ on|off<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.</p>
+ <hr />
+
+ <h2><a id="NoUserID" name="NoUserID">Anonymous_NoUserID
+ directive</a></h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> Anonymous_NoUserID
+ on|off<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.</p>
+ <hr />
+
+ <h2><a id="VerifyEmail"
+ name="VerifyEmail">Anonymous_VerifyEmail directive</a></h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> Anonymous_VerifyEmail
+ on|off<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>).
+ <!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
-<!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>
-
-<p>This module provides for user authentication using Berkeley DB
-files. </p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_auth_db.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> db_auth_module
-</P>
-
-<h2>Summary</h2>
-
-<p>This module provides 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>
-
-<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.</p>
-
-<h2>Directives</h2>
-
-<UL>
-<LI><A HREF="#authdbgroupfile">AuthDBGroupFile</A>
-<LI><A HREF="#authdbuserfile">AuthDBUserFile</A>
-<LI><A HREF="#authdbauthoritative">AuthDBAuthoritative</A>
-</UL>
-
-<p>See also: <a href="core.html#satisfy">satisfy</a> and
-<a href="core.html#require">require</a>.</p>
-
-<HR>
-
-
-<H2><A NAME="authdbgroupfile">AuthDBGroupFile directive</A></H2>
-<!--%plaintext <?INDEX {\tt AuthDBGroupFile} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthDBGroupFile <EM>file-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> 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>File-path</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> directive</H2>
-<!--%plaintext <?INDEX {\tt AuthDBUserFile} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthDBUserFile <EM>file-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> 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>File-path</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>
-
-<p>A perl script called
-href="../programs/dbmmanage.html">dbmmanage</a> is included with
-Apache. This program can be used to create and update DB format
-password files for use with this module.</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> directive</H2>
-<!--%plaintext <?INDEX {\tt AuthDBAuthoritative} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthDBAuthoritative on|off<BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> <CODE>AuthDBAuthoritative 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> 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 <CODE>Require</CODE> 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>
-
-
-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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module provides for user authentication using Berkeley
+ DB files.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_auth_db.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ db_auth_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This module provides 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>
+
+ <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.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#authdbgroupfile">AuthDBGroupFile</a></li>
+
+ <li><a href="#authdbuserfile">AuthDBUserFile</a></li>
+
+ <li><a
+ href="#authdbauthoritative">AuthDBAuthoritative</a></li>
+ </ul>
+
+ <p>See also: <a href="core.html#satisfy">satisfy</a> and <a
+ href="core.html#require">require</a>.</p>
+ <hr />
+
+ <h2><a id="authdbgroupfile"
+ name="authdbgroupfile">AuthDBGroupFile directive</a></h2>
+ <!--%plaintext <?INDEX {\tt AuthDBGroupFile} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDBGroupFile
+ <em>file-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> 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>File-path</em> is the absolute path to the group file.</p>
+
+ <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>
+
+ <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>
+
+ <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
+
+ <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 id="authdbuserfile"
+ name="authdbuserfile">AuthDBUserFile</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt AuthDBUserFile} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDBUserFile
+ <em>file-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> 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>File-path</em> is the absolute path to the
+ user file.</p>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <p>A perl script called
+ href="../programs/dbmmanage.html">dbmmanage is included with
+ Apache. This program can be used to create and update DB format
+ password files for use with this module.</p>
+ See also <a href="core.html#authname">AuthName</a>, <a
+ href="core.html#authtype">AuthType</a> and <a
+ href="#authdbgroupfile">AuthDBGroupFile</a>.
+ <hr />
+
+ <h2><a id="authdbauthoritative"
+ name="authdbauthoritative">AuthDBAuthoritative</a>
+ directive</h2>
+ <!--%plaintext <?INDEX {\tt AuthDBAuthoritative} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDBAuthoritative
+ on|off<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a>
+ <code>AuthDBAuthoritative 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> 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>
+
+ <p>So if a userID appears in the database of more than one
+ module; or if a valid <code>Require</code> 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>
+
+ <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>
+
+ <p>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>
+
+ <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>
+
+ <p>See also <a href="core.html#authname">AuthName</a>, <a
+ href="core.html#authtype">AuthType</a> and <a
+ href="#authdbgroupfile">AuthDBGroupFile</a>.</p>
+
+ <p><!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
-<!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>
-
-<p>This module provides for user authentication using DBM files.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_auth_dbm.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> dbm_auth_module
-</P>
-
-<h2>Summary</h2>
-
-<p>This module provides for HTTP Basic Authentication, where the
-usernames and passwords are stored in DBM type database files. It is
-an alternative to the plain text password files provided by <a
-href="mod_auth.html">mod_auth</A> and the Berkely DB password files
-provided by <a href="mod_auth_db.html">mod_auth_db</a>.</p>
-
-<h2>Directives</h2>
-
-<ul>
-<LI><A HREF="#authdbmgroupfile">AuthDBMGroupFile</A>
-<LI><A HREF="#authdbmuserfile">AuthDBMUserFile</A>
-<LI><A HREF="#authdbmauthoritative">AuthDBMAuthoritative</A>
-</ul>
-
-<p>See also: <a href="core.html#satisfy">Satisfy</a> and
-<a href="core.html#require">Require</a>.
-<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>file-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> 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>File-path</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>file-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> 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>File-path</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>
-
-<p>A perl script called
-href="../programs/dbmmanage.html">dbmmanage</a> is included with
-Apache. This program can be used to create and update DBM format
-password files for use with this module.</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 on|off<BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> <code>AuthDBMAuthoritative 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_dbm<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 <CODE>Require</CODE> 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>
-
-
-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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module provides for user authentication using DBM
+ files.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_auth_dbm.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ dbm_auth_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This module provides for HTTP Basic Authentication, where
+ the usernames and passwords are stored in DBM type database
+ files. It is an alternative to the plain text password files
+ provided by <a href="mod_auth.html">mod_auth</a> and the
+ Berkely DB password files provided by <a
+ href="mod_auth_db.html">mod_auth_db</a>.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#authdbmgroupfile">AuthDBMGroupFile</a></li>
+
+ <li><a href="#authdbmuserfile">AuthDBMUserFile</a></li>
+
+ <li><a
+ href="#authdbmauthoritative">AuthDBMAuthoritative</a></li>
+ </ul>
+
+ <p>See also: <a href="core.html#satisfy">Satisfy</a> and <a
+ href="core.html#require">Require</a>.</p>
+ <hr />
+
+ <h2><a id="authdbmgroupfile"
+ name="authdbmgroupfile">AuthDBMGroupFile</a></h2>
+ <!--%plaintext <?INDEX {\tt AuthDBMGroupFile} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDBMGroupFile
+ <em>file-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> 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>File-path</em> is the absolute path to the group file.</p>
+
+ <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>
+
+ <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>
+
+ <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
+
+ <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 id="authdbmuserfile"
+ name="authdbmuserfile">AuthDBMUserFile</a></h2>
+ <!--%plaintext <?INDEX {\tt AuthDBMUserFile} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDBMUserFile
+ <em>file-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> 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>File-path</em> is the absolute path to the
+ user file.</p>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <p>A perl script called
+ href="../programs/dbmmanage.html">dbmmanage is included with
+ Apache. This program can be used to create and update DBM
+ format password files for use with this module.</p>
+ See also <a href="core.html#authname">AuthName</a>, <a
+ href="core.html#authtype">AuthType</a> and <a
+ href="#authdbmgroupfile">AuthDBMGroupFile</a>.
+ <hr />
+
+ <h2><a id="authdbmauthoritative"
+ name="authdbmauthoritative">AuthDBMAuthoritative</a></h2>
+ <!--%plaintext <?INDEX {\tt AuthDBMAuthoritative} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDBMAuthoritative
+ on|off<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a>
+ <code>AuthDBMAuthoritative 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_dbm
+
+ <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>
+
+ <p>So if a userID appears in the database of more than one
+ module; or if a valid <code>Require</code> 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>
+
+ <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>
+
+ <p>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>
+
+ <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>
+
+ <p>See also <a href="core.html#authname">AuthName</a>, <a
+ href="core.html#authtype">AuthType</a> and <a
+ href="#authdbmgroupfile">AuthDBMGroupFile</a>.</p>
+
+ <p><!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
-<!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>
-
-<p>This module provides for user authentication using MD5 Digest
-Authentication.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Experimental
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_auth_digest.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> digest_auth_module
-</P>
-
-<h2>Summary</h2>
-
-<P>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).
-
-<h2>Directives</h2>
-
-<ul>
-<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>
-</ul>
-
-<p>See also: <a href="core.html#require">Require</a> and
-<a href="core.html#satisfy">Satisfy</a>.
-
-<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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module provides for user authentication using MD5
+ Digest Authentication.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Experimental<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_auth_digest.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ digest_auth_module</p>
+
+ <h2>Summary</h2>
+
+ <p>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).</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#authdigestfile">AuthDigestFile</a></li>
+
+ <li><a
+ href="#authdigestgroupfile">AuthDigestGroupFile</a></li>
+
+ <li><a href="#authdigestqop">AuthDigestQop</a></li>
+
+ <li><a
+ href="#authdigestnoncelifetime">AuthDigestNonceLifetime</a></li>
+
+ <li><a
+ href="#authdigestnonceformat">AuthDigestNonceFormat</a></li>
+
+ <li><a href="#authdigestnccheck">AuthDigestNcCheck</a></li>
+
+ <li><a
+ href="#authdigestalgorithm">AuthDigestAlgorithm</a></li>
+
+ <li><a href="#authdigestdomain">AuthDigestDomain</a></li>
+ </ul>
+
+ <p>See also: <a href="core.html#require">Require</a> and <a
+ href="core.html#satisfy">Satisfy</a>.</p>
+
+ <h3><a id="usingdigest" 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:</p>
+<pre>
<Location /private/>
AuthType Digest
AuthName "private area"
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 Explorer 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.
-
-
-<HR>
-
-
-
-
-<H2><A NAME="authdigestfile">AuthDigestFile</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthDigestFile <EM>file-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> AuthConfig<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_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>File-path</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 <a href="../programs/htdigest.html">htdigest</a>
-utility found in the support/ subdirectory of the Apache distribution.
-
-<HR>
-
-<H2><A NAME="authdigestgroupfile">AuthDigestGroupFile</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthDigestGroupFile <EM>file-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> AuthConfig<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_auth_digest
-
-<P>The AuthDigestGroupFile directive sets the name of a textual file
-containing the list of groups and their members (user names).
-<EM>File-path</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> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthDigestQop none|auth|auth-int
-[auth|auth-int]<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> Experimental<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_auth_digest
-
-<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>
-directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthDigestNonceLifetime <EM>seconds</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> Experimental<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_auth_digest
-
-<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>seconds</EM> is greater than 0 then it specifies the amount of
-time for which the nonce is valid; this should probably never be set
-to less than 10 seconds. If <EM>seconds</EM> is less than 0 then
-the nonce never expires.
-
-<!-- Not implemented yet
-If <EM>seconds</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> directive</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> Experimental<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_auth_digest
-
-<P><STRONG>Not implemented yet.</STRONG>
-<!--
-<P>The AuthDigestNonceFormat directive determines how the nonce is
-generated.
--->
-
-<HR>
-<H2><A NAME="authdigestnccheck">AuthDigestNcCheck</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthDigestNcCheck On|Off<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> Experimental<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_auth_digest
-
-<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> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthDigestAlgorithm MD5|MD5-sess<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> Experimental<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_auth_digest
-
-<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> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AuthDigestDomain <EM>URI</em>
-[<em>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> Experimental<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_auth_digest
-
-<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. Omitting 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.
-
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</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
+ Explorer 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.</p>
+ <hr />
+
+ <h2><a id="authdigestfile"
+ name="authdigestfile">AuthDigestFile</a> directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDigestFile
+ <em>file-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> AuthConfig<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_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>File-path</em> is the absolute path to the
+ user file.</p>
+
+ <p>The digest file uses a special format. Files in this format
+ can be created using the <a
+ href="../programs/htdigest.html">htdigest</a> utility found in
+ the support/ subdirectory of the Apache distribution.</p>
+ <hr />
+
+ <h2><a id="authdigestgroupfile"
+ name="authdigestgroupfile">AuthDigestGroupFile</a>
+ directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDigestGroupFile
+ <em>file-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> AuthConfig<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_auth_digest
+
+ <p>The AuthDigestGroupFile directive sets the name of a textual
+ file containing the list of groups and their members (user
+ names). <em>File-path</em> is the absolute path to the group
+ file.</p>
+
+ <p>Each line of the group file contains a groupname followed by
+ a colon, followed by the member usernames separated by spaces.
+ Example:</p>
+
+ <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.</p>
+ <hr />
+
+ <h2><a id="authdigestqop"
+ name="authdigestqop">AuthDigestQop</a> directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDigestQop
+ none|auth|auth-int [auth|auth-int]<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> Experimental<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_auth_digest
+
+ <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>
+
+ <p><strong><em>auth-int</em> is not implemented
+ yet</strong>.</p>
+ <hr />
+
+ <h2><a id="authdigestnoncelifetime"
+ name="authdigestnoncelifetime">AuthDigestNonceLifetime</a>
+ directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDigestNonceLifetime
+ <em>seconds</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> Experimental<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_auth_digest
+
+ <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>seconds</em> is greater than 0
+ then it specifies the amount of time for which the nonce is
+ valid; this should probably never be set to less than 10
+ seconds. If <em>seconds</em> is less than 0 then the nonce
+ never expires. <!-- Not implemented yet
+ If <EM>seconds</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.
+ -->
+ </p>
+ <hr />
+
+ <h2><a id="authdigestnonceformat"
+ name="authdigestnonceformat">AuthDigestNonceFormat</a>
+ directive</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> Experimental<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_auth_digest
+
+ <p><strong>Not implemented yet.</strong> <!--
+ <P>The AuthDigestNonceFormat directive determines how the nonce is
+ generated.
+ -->
+ </p>
+ <hr />
+
+ <h2><a id="authdigestnccheck"
+ name="authdigestnccheck">AuthDigestNcCheck</a> directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDigestNcCheck
+ On|Off<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> Experimental<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_auth_digest
+
+ <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.
+ -->
+ </p>
+ <hr />
+
+ <h2><a id="authdigestalgorithm"
+ name="authdigestalgorithm">AuthDigestAlgorithm</a>
+ directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDigestAlgorithm
+ MD5|MD5-sess<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> Experimental<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_auth_digest
+
+ <p>The AuthDigestAlgorithm directive selects the algorithm used
+ to calculate the challenge and response hashes.</p>
+
+ <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> .
+ -->
+ </p>
+ <hr />
+
+ <h2><a id="authdigestdomain"
+ name="authdigestdomain">AuthDigestDomain</a> directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AuthDigestDomain
+ <em>URI</em> [<em>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> Experimental<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_auth_digest
+
+ <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>
+
+ <p>This directive <em>should</em> always be specified and
+ contain at least the (set of) root URI(s) for this space.
+ Omitting 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>
+
+ <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.
+ <!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
-<!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>
-
-The module mod_autoindex generates directory indexes, automatically, similar to
-the Unix <em>ls</em> command or the Win32 <em>dir</em> shell command.
-<P>
-
-Automatic index generation must be enabled with by the <CODE>Options</CODE>
-directive's <CODE><I>[+]</I>Indexes</CODE> option. See the
-<A HREF="core.html#options"><CODE>Options</CODE></a> directive for
-more details.
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_autoindex.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> autoindex_module
-</P>
-
-
-<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>
-Automatic index generation is enabled with using
-<CODE>Options +Indexes</CODE>. See the
-<A HREF="core.html#options"><CODE>Options</CODE></a> directive for
-more details.
-<P>
-If the <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>
-option is given with 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. These column header links are
-suppressed with <A HREF="#indexoptions">IndexOptions</A> directive's
-<SAMP>SuppressColumnSorting</SAMP> option.
-</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>
-
-<UL>
-<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="#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>
-</UL>
-
-<p>See also: <A HREF="core.html#options">Options</A> and <A
-HREF="mod_dir.html#directoryindex">DirectoryIndex</A>.</p>
-
-<H2>Autoindex Request Query Arguments</H2>
-
-<P>Apache 2.0.23 reorganized the Query Arguments for Column Sorting, and introduced
-an entire group of new query options. To effectively eliminate all client control
-over the output, the <SAMP><A HREF="#indexoptions:ignoreclient">IndexOptions
-IgnoreClient</A></SAMP> option was introduced.</P>
-
-<P>The column sorting headers themselves are self-referencing hyperlinks that add the
-sort query options shown below. Any option below may be added to any request for the
-directory resource.
-
-<ul>
-<li><SAMP>C=N</SAMP> sorts the directory by file name
-<li><SAMP>C=M</SAMP> sorts the directory by last-modified date, then file name
-<li><SAMP>C=S</SAMP> sorts the directory by size, then file name
-<li><SAMP>C=D</SAMP> sorts the directory by description, then file name<br />
-
-<li><SAMP>O=A</SAMP> sorts the listing in Ascending Order
-<li><SAMP>O=D</SAMP> sorts the listing in Descending Order<br />
-
-<li><SAMP>F=0</SAMP> formats the listing as a simple list (not FancyIndexed)
-<li><SAMP>F=1</SAMP> formats the listing as a FancyIndexed list
-<li><SAMP>F=2</SAMP> formats the listing as an HTMLTable FancyIndexed list<br />
-
-<li><SAMP>V=0</SAMP> disables version sorting
-<li><SAMP>V=1</SAMP> enables version sorting<br />
-
-<li><SAMP>P=<EM>pattern</EM></SAMP> lists only files matching the given <EM>pattern</EM>
-</ul>
-
-<P>Note that the 'P'attern query argument is tested <em>after</em> the usual IndexIgnore
-directives are processed, and all file names are still subjected to the same criteria
-as any other autoindex listing. The Query Arguments parser in mod_autoindex will stop
-abruptly when an unrecognized option is encountered. The Query Arguments must be well
-formed, according to the table above.</P>
-
-<P>The simple example below, which can be clipped and saved in a header.html file,
-illustrates these query options. Note that the unknown "X" argument, for the
-submit button, is listed last to assure the arguments are all parsed before
-mod_autoindex encounters the X=Go input.</P>
-
-<pre><FORM METHOD="GET">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+ The module mod_autoindex generates directory indexes,
+ automatically, similar to the Unix <em>ls</em> command or the
+ Win32 <em>dir</em> shell command.
+
+ <p>Automatic index generation must be enabled with by the
+ <code>Options</code> directive's <code><i>[+]</i>Indexes</code>
+ option. See the <a
+ href="core.html#options"><code>Options</code></a> directive for
+ more details.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_autoindex.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ autoindex_module</p>
+
+ <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>
+
+ <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>.</li>
+ </ul>
+ The two functions are separated so that you can completely
+ remove (or replace) automatic index generation should you want
+ to.
+
+ <p>Automatic index generation is enabled with using
+ <code>Options +Indexes</code>. See the <a
+ href="core.html#options"><code>Options</code></a> directive for
+ more details.</p>
+
+ <p>If the <samp><a
+ href="#indexoptions:fancyindexing">FancyIndexing</a></samp>
+ option is given with 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. These column header links are suppressed with <a
+ href="#indexoptions">IndexOptions</a> directive's
+ <samp>SuppressColumnSorting</samp> option.</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>
+
+ <ul>
+ <li><a href="#addalt">AddAlt</a></li>
+
+ <li><a href="#addaltbyencoding">AddAltByEncoding</a></li>
+
+ <li><a href="#addaltbytype">AddAltByType</a></li>
+
+ <li><a href="#adddescription">AddDescription</a></li>
+
+ <li><a href="#addicon">AddIcon</a></li>
+
+ <li><a href="#addiconbyencoding">AddIconByEncoding</a></li>
+
+ <li><a href="#addiconbytype">AddIconByType</a></li>
+
+ <li><a href="#defaulticon">DefaultIcon</a></li>
+
+ <li><a href="#headername">HeaderName</a></li>
+
+ <li><a href="#indexignore">IndexIgnore</a></li>
+
+ <li><a href="#indexoptions">IndexOptions</a></li>
+
+ <li><a href="#indexorderdefault">IndexOrderDefault</a></li>
+
+ <li><a href="#readmename">ReadmeName</a></li>
+ </ul>
+
+ <p>See also: <a href="core.html#options">Options</a> and <a
+ href="mod_dir.html#directoryindex">DirectoryIndex</a>.</p>
+
+ <h2>Autoindex Request Query Arguments</h2>
+
+ <p>Apache 2.0.23 reorganized the Query Arguments for Column
+ Sorting, and introduced an entire group of new query options.
+ To effectively eliminate all client control over the output,
+ the <samp><a href="#indexoptions:ignoreclient">IndexOptions
+ IgnoreClient</a></samp> option was introduced.</p>
+
+ <p>The column sorting headers themselves are self-referencing
+ hyperlinks that add the sort query options shown below. Any
+ option below may be added to any request for the directory
+ resource.</p>
+
+ <ul>
+ <li><samp>C=N</samp> sorts the directory by file name</li>
+
+ <li><samp>C=M</samp> sorts the directory by last-modified
+ date, then file name</li>
+
+ <li><samp>C=S</samp> sorts the directory by size, then file
+ name</li>
+
+ <li><samp>C=D</samp> sorts the directory by description, then
+ file name<br />
+ </li>
+
+ <li><samp>O=A</samp> sorts the listing in Ascending
+ Order</li>
+
+ <li><samp>O=D</samp> sorts the listing in Descending
+ Order<br />
+ </li>
+
+ <li><samp>F=0</samp> formats the listing as a simple list
+ (not FancyIndexed)</li>
+
+ <li><samp>F=1</samp> formats the listing as a FancyIndexed
+ list</li>
+
+ <li><samp>F=2</samp> formats the listing as an HTMLTable
+ FancyIndexed list<br />
+ </li>
+
+ <li><samp>V=0</samp> disables version sorting</li>
+
+ <li><samp>V=1</samp> enables version sorting<br />
+ </li>
+
+ <li><samp>P=<em>pattern</em></samp> lists only files matching
+ the given <em>pattern</em></li>
+ </ul>
+
+ <p>Note that the 'P'attern query argument is tested
+ <em>after</em> the usual IndexIgnore directives are processed,
+ and all file names are still subjected to the same criteria as
+ any other autoindex listing. The Query Arguments parser in
+ mod_autoindex will stop abruptly when an unrecognized option is
+ encountered. The Query Arguments must be well formed, according
+ to the table above.</p>
+
+ <p>The simple example below, which can be clipped and saved in
+ a header.html file, illustrates these query options. Note that
+ the unknown "X" argument, for the submit button, is listed last
+ to assure the arguments are all parsed before mod_autoindex
+ encounters the X=Go input.</p>
+<pre>
+<FORM METHOD="GET">
Show me a <SELECT NAME="F">
<OPTION VALUE="0"> Plain list
<OPTION VALUE="1" SELECTED> Fancy list
<INPUT TYPE="submit" NAME="X" VALUE="Go">
</FORM>
</pre>
-
-<HR>
-
-<H2><A NAME="addalt">AddAlt</A> directive</H2>
-<!--%plaintext <?INDEX {\tt AddAlt} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AddAlt <EM>string file</em>
-[<em>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>
-
-<EM>AddAlt</EM> provides the alternate text to display for a file, instead of an icon,
-for <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. <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, has image loading
-disabled, or fails to retrieve the icon.
-
-<HR>
-<H2><A NAME="addaltbyencoding">AddAltByEncoding</A> directive</H2>
-<!--%plaintext <?INDEX {\tt AddAltByEncoding} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AddAltByEncoding <EM>string MIME-encoding</em>
- [<em>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>
-
-<EM>AddAltByEncoding</EM> provides the alternate text to display for a file, instead
-of an icon, for <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>.
-<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, has image loading disabled, or
-fails to retrieve the icon.
-
-<HR>
-<H2><A NAME="addaltbytype">AddAltByType</A> directive</H2>
-<!--%plaintext <?INDEX {\tt AddAltByType} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AddAltByType <EM>string MIME-type</em>
- [<em>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>
-
-<EM>AddAltByType</EM> sets the alternate text to display for a file, instead of
-an icon, for <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>.
-<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, has image loading
-disabled, or fails to retrieve the icon.
-
-<HR>
-
-<H2><A NAME="adddescription">AddDescription</A> directive</H2>
-<!--%plaintext <?INDEX {\tt AddDescription} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AddDescription <EM>string file</em>
- [<em>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
-<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>.
-<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 typical, default description field is 23 bytes wide. 6 more bytes are
-added by the <CODE>IndexOptions SuppressIcon</CODE> option, 7 bytes are
-added by the <CODE>IndexOptions SuppressSize</CODE> option, and 19 bytes
-are added by the <CODE>IndexOptions SuppressLastModified</CODE> option.
-Therefore, the widest default the description column is ever assigned is 55 bytes.
-<P>
-See the <a href="#indexoptions:descriptionwidth">DescriptionWidth</a>
-<samp>IndexOptions</samp> keyword for details on overriding the size of this
-column, or allowing descriptions of unlimited length.
-</P>
-<blockquote>
-<b>Caution:</b> Descriptive text defined with <samp>AddDescription</samp>
-may contain HTML markup, such as tags and character entities. If the
-width of the description column should happen to truncate a tagged
-element (such as cutting off the end of a bolded phrase), the results
-may affect the rest of the directory listing.
-</blockquote>
-<HR>
-
-<H2><A NAME="addicon">AddIcon</A> directive</H2>
-<!--%plaintext <?INDEX {\tt AddIcon} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AddIcon <EM>icon name</em>
- [<em>name</em>] ...</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
-<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. <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> directive</H2>
-<!--%plaintext <?INDEX {\tt AddIconByEncoding} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AddIconByEncoding <EM>icon MIME-encoding</em>
- [<em>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
-<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>.
-<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> directive</H2>
-<!--%plaintext <?INDEX {\tt AddIconByType} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AddIconByType <EM>icon MIME-type</em>
- [<em>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
-<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. <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> directive</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
-<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>.
-<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> directive</H2>
-<!--%plaintext <?INDEX {\tt FancyIndexing} directive> -->
-<A
- HREF="directive-dict.html#Deprecated"
- REL="Help"
-><STRONG>Deprecated:</STRONG></A> See <A HREF="#indexoptions">IndexOptions</A>
- <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP><BR>
-<P>
-The FancyIndexing directive was replaced by the
-<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP> option to the
-<A HREF="#indexoptions">IndexOptions</A> directive, and is no longer supported
-in Apache 2.0.
-</P>
-<HR>
-
-<H2><A NAME="headername">HeaderName</A> directive</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> behavior changed in version 1.3.7;
- 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>Changes with Apache 1.3.7:</STRONG>
-Both HeaderName and <A HREF="#readmename">ReadmeName</A> now treat <EM>Filename</EM>
-as a URI path relative to the one used to access the directory being indexed.
-<EM>Filename</EM> 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>
+ <hr />
+
+ <h2><a id="addalt" name="addalt">AddAlt</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt AddAlt} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AddAlt <em>string
+ file</em> [<em>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><em>AddAlt</em> provides the alternate text to display for a
+ file, instead of an icon, for <samp><a
+ href="#indexoptions:fancyindexing">FancyIndexing</a></samp>.
+ <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, has image loading disabled, or fails to
+ retrieve the icon.</p>
+ <hr />
+
+ <h2><a id="addaltbyencoding"
+ name="addaltbyencoding">AddAltByEncoding</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt AddAltByEncoding} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AddAltByEncoding
+ <em>string MIME-encoding</em> [<em>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><em>AddAltByEncoding</em> provides the alternate text to
+ display for a file, instead of an icon, for <samp><a
+ href="#indexoptions:fancyindexing">FancyIndexing</a></samp>.
+ <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, has image loading disabled, or
+ fails to retrieve the icon.</p>
+ <hr />
+
+ <h2><a id="addaltbytype" name="addaltbytype">AddAltByType</a>
+ directive</h2>
+ <!--%plaintext <?INDEX {\tt AddAltByType} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AddAltByType <em>string
+ MIME-type</em> [<em>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><em>AddAltByType</em> sets the alternate text to display for
+ a file, instead of an icon, for <samp><a
+ href="#indexoptions:fancyindexing">FancyIndexing</a></samp>.
+ <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, has image loading disabled, or
+ fails to retrieve the icon.</p>
+ <hr />
+
+ <h2><a id="adddescription"
+ name="adddescription">AddDescription</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt AddDescription} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AddDescription
+ <em>string file</em> [<em>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
+ <samp><a
+ href="#indexoptions:fancyindexing">FancyIndexing</a></samp>.
+ <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:</p>
+
+ <blockquote>
+ <code>AddDescription "The planet Mars"
+ /web/pics/mars.gif</code>
+ </blockquote>
+
+ <p>The typical, default description field is 23 bytes wide. 6
+ more bytes are added by the
+ <code>IndexOptions SuppressIcon</code> option, 7 bytes are
+ added by the <code>IndexOptions SuppressSize</code>
+ option, and 19 bytes are added by the
+ <code>IndexOptions SuppressLastModified</code> option.
+ Therefore, the widest default the description column is ever
+ assigned is 55 bytes.</p>
+
+ <p>See the <a
+ href="#indexoptions:descriptionwidth">DescriptionWidth</a>
+ <samp>IndexOptions</samp> keyword for details on overriding the
+ size of this column, or allowing descriptions of unlimited
+ length.</p>
+
+ <blockquote>
+ <b>Caution:</b> Descriptive text defined with
+ <samp>AddDescription</samp> may contain HTML markup, such as
+ tags and character entities. If the width of the description
+ column should happen to truncate a tagged element (such as
+ cutting off the end of a bolded phrase), the results may
+ affect the rest of the directory listing.
+ </blockquote>
+ <hr />
+
+ <h2><a id="addicon" name="addicon">AddIcon</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt AddIcon} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AddIcon <em>icon
+ name</em> [<em>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 <samp><a
+ href="#indexoptions:fancyindexing">FancyIndexing</a></samp>.
+ <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>
+
+ <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:</p>
+
+ <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.
+ <hr />
+
+ <h2><a id="addiconbyencoding"
+ name="addiconbyencoding">AddIconByEncoding</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt AddIconByEncoding} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AddIconByEncoding
+ <em>icon MIME-encoding</em> [<em>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 <samp><a
+ href="#indexoptions:fancyindexing">FancyIndexing</a></samp>.
+ <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>
+
+ <p><em>Mime-encoding</em> is a wildcard expression matching
+ required the content-encoding. Examples:</p>
+
+ <blockquote>
+ <code>AddIconByEncoding /icons/compress.xbm x-compress</code>
+ </blockquote>
+ <hr />
+
+ <h2><a id="addiconbytype"
+ name="addiconbytype">AddIconByType</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt AddIconByType} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AddIconByType <em>icon
+ MIME-type</em> [<em>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 <samp><a
+ href="#indexoptions:fancyindexing">FancyIndexing</a></samp>.
+ <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>
+
+ <p><em>Mime-type</em> is a wildcard expression matching
+ required the mime types. Examples:</p>
+
+ <blockquote>
+ <code>AddIconByType (IMG,/icons/image.xbm) image/*</code>
+ </blockquote>
+ <hr />
+
+ <h2><a id="defaulticon" name="defaulticon">DefaultIcon</a>
+ directive</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 <samp><a
+ href="#indexoptions:fancyindexing">FancyIndexing</a></samp>.
+ <em>Url</em> is a (%-escaped) relative URL to the icon.
+ Examples:</p>
+
+ <blockquote>
+ <code>DefaultIcon /icon/unknown.xbm</code>
+ </blockquote>
+ <hr />
+
+ <h2><a id="fancyindexing"
+ name="fancyindexing">FancyIndexing</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt FancyIndexing} directive> -->
+ <a href="directive-dict.html#Deprecated"
+ rel="Help"><strong>Deprecated:</strong></a> See <a
+ href="#indexoptions">IndexOptions</a> <samp><a
+ href="#indexoptions:fancyindexing">FancyIndexing</a></samp><br />
+
+
+ <p>The FancyIndexing directive was replaced by the <samp><a
+ href="#indexoptions:fancyindexing">FancyIndexing</a></samp>
+ option to the <a href="#indexoptions">IndexOptions</a>
+ directive, and is no longer supported in Apache 2.0.</p>
+ <hr />
+
+ <h2><a id="headername" name="headername">HeaderName</a>
+ directive</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> behavior changed
+ in version 1.3.7; 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>Changes with Apache 1.3.7:</strong> Both HeaderName
+ and <a href="#readmename">ReadmeName</a> now treat
+ <em>Filename</em> as a URI path relative to the one used to
+ access the directory being indexed. <em>Filename</em> 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>
-If the file specified by <SAMP>HeaderName</SAMP> contains the
-beginnings of an HTML document (<HTML>, <HEAD>, etc) then
-you will probably want to set <A
-HREF="#indexoptions:suppresshtmlpreamble"><SAMP>IndexOptions
-+SuppressHTMLPreamble</SAMP></A>, so that these tags are not
-repeated.
-<P>
-See also <A HREF="#readmename">ReadmeName</A>.
-<P><HR>
-
-<H2><A NAME="indexignore">IndexIgnore</A> directive</H2>
-<!--%plaintext <?INDEX {\tt IndexIgnore} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> IndexIgnore <EM>file</em> [<em>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> directive</H2>
-<!--%plaintext <?INDEX {\tt IndexOptions} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> IndexOptions [+|-]<em>option</em>
- [[+|-]<em>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; specific options are listed below.
-<P>
-
-The IndexOptions directive specifies the behavior of the directory indexing.
-<EM>Option</EM> can be one of
-<DL>
-<dt><a name="indexoptions:descriptionwidth">DescriptionWidth=[<em>n</em> | *]
- (<em>Apache 1.3.10 or 2.0.23 and later</em>)</a></dt>
-<dd>The <samp>DescriptionWidth</samp> keyword allows you to specify the
-width of the description column in characters.</dd>
-<dd><samp>-DescriptionWidth</samp> (or unset) allows mod_autoindex to calculate
-the best width.</dd>
-<dd><samp>DescriptionWidth=n</samp> fixes the column width to n bytes wide.</dd>
-<dd><samp>DescriptionWidth=*</samp> grows the column to the width necessary to
-accommodate the longest description string.</dd>
-<dd><b>See the section on <a href="#adddescription"><samp>AddDescription</samp></a>
-for dangers inherent in truncating descriptions.</b></dd>
-<DT><A NAME="indexoptions:fancyindexing">FancyIndexing</A>
-<DD><!--%plaintext <?INDEX {\tt FancyIndexing} index option> -->
-This turns on fancy indexing of directories.
-<dt><a name="indexoptions:foldersfirst">FoldersFirst
- (<i>Apache 1.3.10 or 2.0.23 and later</i>)</a></dt>
-<dd>
-If this option is enabled, subdirectory listings
-will <i>always</i> appear first, followed by normal files in the
-directory. The listing is basically broken into two components,
-the files and the subdirectories, and each is sorted separately and
-then displayed subdirectories-first. For instance, if the sort order
-is descending by name, and <samp>FoldersFirst</samp> is enabled,
-subdirectory <samp>Zed</samp> will be listed before subdirectory
-<samp>Beta</samp>, which will be listed before normal files
-<samp>Gamma</samp> and <samp>Alpha</samp>.
-<b>This option only has an effect if
-<a href="#indexoptions:fancyindexing"><samp>FancyIndexing</samp></a>
-is also enabled.</b></dd>
-<DT><A NAME="indexoptions:htmltable">HTMLTable</A>
- <i>(Experimental, Apache 2.0.23 and later)</i>
-<DD><!--%plaintext <?INDEX {\tt HTMLTable} index option> -->
-This experimental option with FancyIndexing constructs a simple table for the
-fancy directory listing. Note this will confuse older browsers. It is particularly
-necessary if file names or description text will alternate between left-to-right
-and right-to-left reading order, as can happen on WinNT or other utf-8
-enabled platforms.
-<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: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: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:ignoreclient">IgnoreClient</A>
-<DD>
-<!--%plaintext <?INDEX {\tt IgnoreClient} index option> -->
-This option causes mod_autoindex to ignore all query variables from the
-client, including sort order (implies <SAMP><A
- HREF="#indexoptions:suppresscolumnsorting">SuppressColumnSorting</A></SAMP>.)
-<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.
-<dd><samp>-NameWidth</samp> (or unset) allows mod_autoindex to calculate
-the best width.</dd>
-<dd><samp>NameWidth=n</samp> fixes the column width to n bytes wide.</dd>
-<dd><samp>NameWidth=*</samp> grows the column to the necessary width.</dd>
-<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>
- (<EM>Apache 1.3 and later</EM>)
-<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 behavior is
-for them to be links; selecting the column heading will sort the directory
-listing by the values in that column. <STRONG>Prior to Apache 2.0.23, this
-also disabled parsing the Query Arguments for the sort string.</STRONG>
-That behavior is now controlled by <A HREF="#indexoptions:ignoreclient"
- >IndexOptions IgnoreClient</A> in Apache 2.0.23.
-<DT><A NAME="indexoptions:suppressdescription">SuppressDescription</A>
-<DD>
-<!--%plaintext <?INDEX {\tt SuppressDescription} index option> -->
-This will suppress the file description in fancy indexing listings.
-By default, no file descriptions are defined, and so the use of this option
-will regain 23 characters of screen space to use for something else.
-See <A HREF="#adddescription"><samp>AddDescription</samp></A>
-for information about setting the file description. See also the
-<A
-HREF="#indexoptions:descriptionwidth"><samp>DescriptionWidth</samp></A>
-index option to limit the size of the description column.
-
-<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:suppressicon">SuppressIcon</A>
- (<EM>Apache 2.0.23 and later</EM>)
-<DD>
-<!--%plaintext <?INDEX {\tt SuppressIcon} index option> -->
-This will suppress the icon in fancy indexing listings. Combining
-both <EM>SuppressIcon</EM> and <EM>SuppressRules</EM> yields proper
-HTML 3.2 output, which by the final specification prohibits IMG and HR
-tags from the PRE block (used to format FancyIndexed listings.)
-<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:suppressrules">SuppressRules</A>
- (<EM>Apache 2.0.23 and later</EM>)
-<DD>
-<!--%plaintext <?INDEX {\tt SuppressRules} index option> -->
-This will suppress the horizontal rule lines (HR tags) in directory listings.
-Combining both <EM>SuppressIcon</EM> and <EM>SuppressRules</EM> yeilds proper
-HTML 3.2 output, which by the final specification prohibits IMG and HR tags
-from the PRE block (used to format FancyIndexed 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.
-<DT><A NAME="indexoptions:trackmodified">TrackModified
-(<EM>Apache 1.3.15 or 2.0.23 and later</EM>)</A>
-<DD>
-<!--%plaintext <?INDEX {\tt TrackModified} index option> -->
-This returns the Last-Modified and ETag values for the listed directory
-in the HTTP header. It is only valid if the operating system and file
-system return appropriate stat() results. Some Unix systems do so, as
-do OS2's JFS and Win32's NTFS volumes. OS2 and Win32 FAT volumes,
-for example, do not. Once this feature is enabled, the client or proxy
-can track changes to the list of files when they perform a HEAD request.
-Note some operating systems correctly track new and removed files, but
-do not track changes for sizes or dates of the files within the directory.
-<STRONG>Changes to the size or date stamp of an existing file will not
-update the Last-Modified header on all Unix platforms.</STRONG> If this
-is a concern, leave this option disabled.
-<DT><A NAME="indexoptions:versionsort">VersionSort (<EM>Apache 2.0a3 and later</EM>)</A>
-<DD>
-The VersionSort keyword causes files containing version numbers to
-sort in a natural way. Strings are sorted as usual, except that
-substrings of digits in the name and description are compared
-according to their numeric value.
-
-For example:
-<BLOCKQUOTE><pre>
+</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>If the file specified by <samp>HeaderName</samp> contains
+ the beginnings of an HTML document (<HTML>, <HEAD>,
+ etc) then you will probably want to set <a
+ href="#indexoptions:suppresshtmlpreamble"><samp>IndexOptions
+ +SuppressHTMLPreamble</samp></a>, so that these tags are not
+ repeated.</p>
+
+ <p>See also <a href="#readmename">ReadmeName</a>.</p>
+ <hr />
+
+ <h2><a id="indexignore" name="indexignore">IndexIgnore</a>
+ directive</h2>
+ <!--%plaintext <?INDEX {\tt IndexIgnore} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> IndexIgnore
+ <em>file</em> [<em>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:</p>
+
+ <blockquote>
+ <code>IndexIgnore README .htaccess *~</code>
+ </blockquote>
+ <hr />
+
+ <h2><a id="indexoptions" name="indexoptions">IndexOptions</a>
+ directive</h2>
+ <!--%plaintext <?INDEX {\tt IndexOptions} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> IndexOptions
+ [+|-]<em>option</em> [[+|-]<em>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; specific options
+ are listed below.
+
+ <p>The IndexOptions directive specifies the behavior of the
+ directory indexing. <em>Option</em> can be one of</p>
+
+ <dl>
+ <dt><a id="indexoptions:descriptionwidth"
+ name="indexoptions:descriptionwidth">DescriptionWidth=[<em>n</em>
+ | *] (<em>Apache 1.3.10 or 2.0.23 and later</em>)</a></dt>
+
+ <dd>The <samp>DescriptionWidth</samp> keyword allows you to
+ specify the width of the description column in
+ characters.</dd>
+
+ <dd><samp>-DescriptionWidth</samp> (or unset) allows
+ mod_autoindex to calculate the best width.</dd>
+
+ <dd><samp>DescriptionWidth=n</samp> fixes the column width to
+ n bytes wide.</dd>
+
+ <dd><samp>DescriptionWidth=*</samp> grows the column to the
+ width necessary to accommodate the longest description
+ string.</dd>
+
+ <dd><b>See the section on <a
+ href="#adddescription"><samp>AddDescription</samp></a> for
+ dangers inherent in truncating descriptions.</b></dd>
+
+ <dt><a id="indexoptions:fancyindexing"
+ name="indexoptions:fancyindexing">FancyIndexing</a></dt>
+
+ <dd>
+ <!--%plaintext <?INDEX {\tt FancyIndexing} index option> -->
+ This turns on fancy indexing of directories.</dd>
+
+ <dt><a id="indexoptions:foldersfirst"
+ name="indexoptions:foldersfirst">FoldersFirst (<i>Apache
+ 1.3.10 or 2.0.23 and later</i>)</a></dt>
+
+ <dd>If this option is enabled, subdirectory listings will
+ <i>always</i> appear first, followed by normal files in the
+ directory. The listing is basically broken into two
+ components, the files and the subdirectories, and each is
+ sorted separately and then displayed subdirectories-first.
+ For instance, if the sort order is descending by name, and
+ <samp>FoldersFirst</samp> is enabled, subdirectory
+ <samp>Zed</samp> will be listed before subdirectory
+ <samp>Beta</samp>, which will be listed before normal files
+ <samp>Gamma</samp> and <samp>Alpha</samp>. <b>This option
+ only has an effect if <a
+ href="#indexoptions:fancyindexing"><samp>FancyIndexing</samp></a>
+ is also enabled.</b></dd>
+
+ <dt><a id="indexoptions:htmltable"
+ name="indexoptions:htmltable">HTMLTable</a> <i>(Experimental,
+ Apache 2.0.23 and later)</i></dt>
+
+ <dd>
+ <!--%plaintext <?INDEX {\tt HTMLTable} index option> -->
+ This experimental option with FancyIndexing constructs a
+ simple table for the fancy directory listing. Note this will
+ confuse older browsers. It is particularly necessary if file
+ names or description text will alternate between
+ left-to-right and right-to-left reading order, as can happen
+ on WinNT or other utf-8 enabled platforms.</dd>
+
+ <dt><a id="indexoptions:iconsarelinks"
+ name="indexoptions:iconsarelinks">IconsAreLinks</a></dt>
+
+ <dd>
+ <!--%plaintext <?INDEX {\tt IconsAreLinks} index option> -->
+ This makes the icons part of the anchor for the filename, for
+ fancy indexing.</dd>
+
+ <dt><a id="indexoptions:iconheight"
+ name="indexoptions:iconheight">IconHeight[=pixels]
+ (<em>Apache 1.3 and later</em>)</a></dt>
+
+ <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.</dd>
+
+ <dt><a id="indexoptions:iconwidth"
+ name="indexoptions:iconwidth">IconWidth[=pixels] (<em>Apache
+ 1.3 and later</em>)</a></dt>
+
+ <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.</dd>
+
+ <dt><a id="indexoptions:ignoreclient"
+ name="indexoptions:ignoreclient">IgnoreClient</a></dt>
+
+ <dd>
+ <!--%plaintext <?INDEX {\tt IgnoreClient} index option> -->
+ This option causes mod_autoindex to ignore all query
+ variables from the client, including sort order (implies
+ <samp><a
+ href="#indexoptions:suppresscolumnsorting">SuppressColumnSorting</a></samp>.)</dd>
+
+ <dt><a id="indexoptions:namewidth"
+ name="indexoptions:namewidth">NameWidth=[<em>n</em> | *]
+ (<em>Apache 1.3.2 and later</em>)</a></dt>
+
+ <dd>The NameWidth keyword allows you to specify the width of
+ the filename column in bytes.</dd>
+
+ <dd><samp>-NameWidth</samp> (or unset) allows mod_autoindex
+ to calculate the best width.</dd>
+
+ <dd><samp>NameWidth=n</samp> fixes the column width to n
+ bytes wide.</dd>
+
+ <dd><samp>NameWidth=*</samp> grows the column to the
+ necessary width.</dd>
+
+ <dt><a id="indexoptions:scanhtmltitles"
+ name="indexoptions:scanhtmltitles">ScanHTMLTitles</a></dt>
+
+ <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.</dd>
+
+ <dt><a id="indexoptions:suppresscolumnsorting"
+ name="indexoptions:suppresscolumnsorting">SuppressColumnSorting</a>
+ (<em>Apache 1.3 and later</em>)</dt>
+
+ <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 behavior is for them to be links; selecting the
+ column heading will sort the directory listing by the values
+ in that column. <strong>Prior to Apache 2.0.23, this also
+ disabled parsing the Query Arguments for the sort
+ string.</strong> That behavior is now controlled by <a
+ href="#indexoptions:ignoreclient">IndexOptions
+ IgnoreClient</a> in Apache 2.0.23.</dd>
+
+ <dt><a id="indexoptions:suppressdescription"
+ name="indexoptions:suppressdescription">SuppressDescription</a></dt>
+
+ <dd>
+ <!--%plaintext <?INDEX {\tt SuppressDescription} index option> -->
+ This will suppress the file description in fancy indexing
+ listings. By default, no file descriptions are defined, and
+ so the use of this option will regain 23 characters of screen
+ space to use for something else. See <a
+ href="#adddescription"><samp>AddDescription</samp></a> for
+ information about setting the file description. See also the
+ <a
+ href="#indexoptions:descriptionwidth"><samp>DescriptionWidth</samp></a>
+ index option to limit the size of the description
+ column.</dd>
+
+ <dt><a id="indexoptions:suppresshtmlpreamble"
+ name="indexoptions:suppresshtmlpreamble">SuppressHTMLPreamble</a>
+ (<em>Apache 1.3 and later</em>)</dt>
+
+ <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.</dd>
+
+ <dt><a id="indexoptions:suppressicon"
+ name="indexoptions:suppressicon">SuppressIcon</a> (<em>Apache
+ 2.0.23 and later</em>)</dt>
+
+ <dd>
+ <!--%plaintext <?INDEX {\tt SuppressIcon} index option> -->
+ This will suppress the icon in fancy indexing listings.
+ Combining both <em>SuppressIcon</em> and
+ <em>SuppressRules</em> yields proper HTML 3.2 output, which
+ by the final specification prohibits IMG and HR tags from the
+ PRE block (used to format FancyIndexed listings.)</dd>
+
+ <dt><a id="indexoptions:suppresslastmodified"
+ name="indexoptions:suppresslastmodified">SuppressLastModified</a></dt>
+
+ <dd>
+ <!--%plaintext <?INDEX {\tt SuppressLastModified} index option> -->
+ This will suppress the display of the last modification date,
+ in fancy indexing listings.</dd>
+
+ <dt><a id="indexoptions:suppressrules"
+ name="indexoptions:suppressrules">SuppressRules</a>
+ (<em>Apache 2.0.23 and later</em>)</dt>
+
+ <dd>
+ <!--%plaintext <?INDEX {\tt SuppressRules} index option> -->
+ This will suppress the horizontal rule lines (HR tags) in
+ directory listings. Combining both <em>SuppressIcon</em> and
+ <em>SuppressRules</em> yeilds proper HTML 3.2 output, which
+ by the final specification prohibits IMG and HR tags from the
+ PRE block (used to format FancyIndexed listings.)</dd>
+
+ <dt><a id="indexoptions:suppresssize"
+ name="indexoptions:suppresssize">SuppressSize</a></dt>
+
+ <dd>
+ <!--%plaintext <?INDEX {\tt SuppressSize} index option> -->
+ This will suppress the file size in fancy indexing
+ listings.</dd>
+
+ <dt><a id="indexoptions:trackmodified"
+ name="indexoptions:trackmodified">TrackModified (<em>Apache
+ 1.3.15 or 2.0.23 and later</em>)</a></dt>
+
+ <dd>
+ <!--%plaintext <?INDEX {\tt TrackModified} index option> -->
+ This returns the Last-Modified and ETag values for the listed
+ directory in the HTTP header. It is only valid if the
+ operating system and file system return appropriate stat()
+ results. Some Unix systems do so, as do OS2's JFS and Win32's
+ NTFS volumes. OS2 and Win32 FAT volumes, for example, do not.
+ Once this feature is enabled, the client or proxy can track
+ changes to the list of files when they perform a HEAD
+ request. Note some operating systems correctly track new and
+ removed files, but do not track changes for sizes or dates of
+ the files within the directory. <strong>Changes to the size
+ or date stamp of an existing file will not update the
+ Last-Modified header on all Unix platforms.</strong> If this
+ is a concern, leave this option disabled.</dd>
+
+ <dt><a id="indexoptions:versionsort"
+ name="indexoptions:versionsort">VersionSort (<em>Apache 2.0a3
+ and later</em>)</a></dt>
+
+ <dd>
+ The VersionSort keyword causes files containing version
+ numbers to sort in a natural way. Strings are sorted as
+ usual, except that substrings of digits in the name and
+ description are compared according to their numeric value.
+ For example:
+
+ <blockquote>
+<pre>
foo-1.7
foo-1.7.2
foo-1.7.12
foo-1.8.2
foo-1.8.2a
foo-1.12
-</pre></BLOCKQUOTE>
+</pre>
+ </blockquote>
+ If the number starts with a zero, then it is considered to
+ be a fraction:
-If the number starts with a zero, then it is considered to be a
- fraction:
-<BLOCKQUOTE><pre>
+ <blockquote>
+<pre>
foo-1.001
foo-1.002
foo-1.030
foo-1.04
-</pre></BLOCKQUOTE>
-<DT><H3>Incremental IndexOptions</H3>
-<DD>Apache 1.3.3 introduced some significant changes in the handling of
-<SAMP>IndexOptions</SAMP> directives. In particular,
-<BR /><BR />
-<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>
-<BR />
-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:
-<BLOCKQUOTE><CODE>IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing
-<BR />
-IndexOptions +SuppressSize
-<BR />
-</CODE></BLOCKQUOTE>
-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.
-<BR /><BR />
-To unconditionally set the <CODE>IndexOptions</CODE> for a
-particular directory, clearing the inherited settings, specify
-keywords without any '+' or '-' prefixes.
-</DD>
-</DL>
-
-<HR>
-
-<H2><A NAME="indexorderdefault">IndexOrderDefault</A> directive</H2>
-<!--%plaintext <?INDEX {\tt IndexOrderDefault} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> IndexOrderDefault
- Ascending|Descending Name|Date|Size|Description
-<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> directive</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 <A HREF="#headername">HeaderName</A>
-
-<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>
-<P>See also <A HREF="#headername">HeaderName</A>, where this behavior is
-described in greater detail.<P>
-
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</pre>
+ </blockquote>
+ </dd>
+
+ <dd>
+ <h3>Incremental IndexOptions</h3>
+ </dd>
+
+ <dd>
+ Apache 1.3.3 introduced some significant changes in the
+ handling of <samp>IndexOptions</samp> directives. In
+ particular,<br />
+ <br />
+
+
+ <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>
+ <br />
+ 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:
+
+ <blockquote>
+ <code>IndexOptions +ScanHTMLTitles -IconsAreLinks
+ FancyIndexing<br />
+ IndexOptions +SuppressSize<br />
+ </code>
+ </blockquote>
+ 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.<br />
+ <br />
+ To unconditionally set the <code>IndexOptions</code> for a
+ particular directory, clearing the inherited settings,
+ specify keywords without any '+' or '-' prefixes.
+ </dd>
+ </dl>
+ <hr />
+
+ <h2><a id="indexorderdefault"
+ name="indexorderdefault">IndexOrderDefault</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt IndexOrderDefault} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> IndexOrderDefault
+ Ascending|Descending Name|Date|Size|Description <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 id="readmename" name="readmename">ReadmeName</a>
+ directive</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 <a
+ href="#headername">HeaderName</a>
+
+ <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>
+
+ <p>See also <a href="#headername">HeaderName</a>, where this
+ behavior is described in greater detail.</p>
+
+ <p><!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
+
-<!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>
-
-<p>This module provides for CERN httpd metafile semantics.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_cern_meta.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> cern_meta_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.1 and later.
-</P>
-
-
-<H2>Summary</H2>
-
-<!-- XXX: Should mention other possibilities in Apache: mod_header -->
-
-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> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> MetaFiles on|off<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.
-
-<hr>
-
-<H2><A NAME="metadir">MetaDir</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> MetaDir <EM>directory</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.
-
-<hr>
-
-<H2><A NAME="metasuffix">MetaSuffix</A> directive</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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>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>
+
+ <p>This module provides for CERN httpd metafile semantics.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_cern_meta.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ cern_meta_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.1 and later.</p>
+
+ <h2>Summary</h2>
+ <!-- XXX: Should mention other possibilities in Apache: mod_header -->
+ 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.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#metafiles">MetaFiles</a></li>
+
+ <li><a href="#metadir">MetaDir</a></li>
+
+ <li><a href="#metasuffix">MetaSuffix</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="metafiles" name="metafiles">MetaFiles</a>
+ directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> MetaFiles on|off<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.</p>
+ <hr />
+
+ <h2><a id="metadir" name="metadir">MetaDir</a> directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> MetaDir
+ <em>directory</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.</p>
+ <hr />
+
+ <h2><a id="metasuffix" name="metasuffix">MetaSuffix</a>
+ directive</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>
+
+ <p><!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
-<!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>
-
-<p>This module provides for execution of CGI scripts.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_cgi.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> cgi_module
-</P>
-
-
-<H2>Summary</H2>
-<!-- XXX: Should have references to CGI definition/RFC -->
-<!-- XXX: Should mention Options ExecCGI -->
-
-<p>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>
-
-<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.</p>
-
-<p>For an introduction to using CGI scripts with Apache, see our
-tutorial on <a href="../howto/cgi.html">Dynamic Content With CGI</a>.</p>
-
-<p>When using a multi-threaded MPM under unix, the module <a
-href="mod_cgid.html">mod_cgid</a> should be used in place of this
-module. At the user level, the two modules are essentially
-identical.</p>
-
-<h2>Directives</h2>
-
-<ul>
-<li><a href="#scriptlog">ScriptLog</a></li>
-<li><a href="#scriptloglength">ScriptLogLength</a></li>
-<li><a href="#scriptlogbuffer">ScriptLogBuffer</a></li>
-</ul>
-
-<p>See also: <a href="core.html#options">Options</a>, <a
-href="mod_alias.html#scriptalias">ScriptAlias</a>, <a
-href="mod_mime.html#addtype">AddType</a> and <a
-href="mod_mime.html#addhandler">AddHandler</a>.
-
-<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>
-
-<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.
-
-<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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module provides for execution of CGI scripts.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_cgi.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ cgi_module</p>
+
+ <h2>Summary</h2>
+ <!-- XXX: Should have references to CGI definition/RFC -->
+ <!-- XXX: Should mention Options ExecCGI -->
+
+ <p>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>
+
+ <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.</p>
+
+ <p>For an introduction to using CGI scripts with Apache, see
+ our tutorial on <a href="../howto/cgi.html">Dynamic Content
+ With CGI</a>.</p>
+
+ <p>When using a multi-threaded MPM under unix, the module <a
+ href="mod_cgid.html">mod_cgid</a> should be used in place of
+ this module. At the user level, the two modules are essentially
+ identical.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#scriptlog">ScriptLog</a></li>
+
+ <li><a href="#scriptloglength">ScriptLogLength</a></li>
+
+ <li><a href="#scriptlogbuffer">ScriptLogBuffer</a></li>
+ </ul>
+
+ <p>See also: <a href="core.html#options">Options</a>, <a
+ href="mod_alias.html#scriptalias">ScriptAlias</a>, <a
+ href="mod_mime.html#addtype">AddType</a> and <a
+ href="mod_mime.html#addhandler">AddHandler</a>.</p>
+
+ <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</dt>
+
+ <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.</dd>
+
+ <dt>REMOTE_IDENT</dt>
+
+ <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.</dd>
+
+ <dt>REMOTE_USER</dt>
+
+ <dd>This will only be set if the CGI script is subject to
+ authentication.</dd>
+ </dl>
+
+ <h2><a id="cgi_debug" 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.
+
+ <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>
+ <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>
+ <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>
+ <em>All headers output by the CGI script</em>
%stdout
- <EM>CGI standard output</EM>
+ <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>
-
-<H3><A NAME="scriptlog">ScriptLog</A> directive</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>
-
-<hr>
-
-<H3><A NAME="scriptloglength">ScriptLogLength</A> directive</H3>
-
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> ScriptLogLength <EM>bytes</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.
-
-<hr>
-
-<H3><A NAME="scriptlogbuffer">ScriptLogBuffer</A></H3>
-
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> ScriptLogBuffer <EM>bytes</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>
+ <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 />
+
+ <h3><a id="scriptlog" name="scriptlog">ScriptLog</a>
+ directive</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>
+
+ <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>
+ <hr />
+
+ <h3><a id="scriptloglength"
+ name="scriptloglength">ScriptLogLength</a> directive</h3>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ScriptLogLength
+ <em>bytes</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.</p>
+ <hr />
+
+ <h3><a id="scriptlogbuffer"
+ name="scriptlogbuffer">ScriptLogBuffer</a></h3>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ScriptLogBuffer
+ <em>bytes</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" -->
+ </p>
+ </body>
+</html>
-<!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_cgid</H1>
-
-<p>This module provides for execution of CGI scripts using an external
-CGI daemon.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base (unix threaded MPMs only)
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_cgid.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> cgid_module
-</P>
-
-
-<H2>Summary</H2>
-
-<p>On certain unix operating systems, forking a process from a
-multi-threaded server is a very expensive operation because the new
-process will replicate all the threads of the parent process. In
-order to avoid incurring this expense on each CGI invocation, mod_cgid
-creates an external daemon that is responsible for forking child
-processes to run CGI scripts. The main server communicates with this
-daemon using a unix domain socket.</p>
-
-<p>This module is used by default whenever a multi-threaded MPM is
-selected during the compilation process. At the user level, this
-module is identical in configuration and operation to <a
-href="mod_cgi.html">mod_cgi</a>. The only exception is the additional
-directive <code>ScriptSock</code> which gives the name of the socket
-to use for communication with the cgi daemon.</p>
-
-<h2>Directives</h2>
-
-<ul>
-<li><a href="mod_cgi.html#scriptlog">ScriptLog</a></li>
-<li><a href="mod_cgi.html#scriptloglength">ScriptLogLength</a></li>
-<li><a href="mod_cgi.html#scriptlogbuffer">ScriptLogBuffer</a></li>
-<li><a href="#scriptsock">ScriptSock</a></li>
-</ul>
-
-<hr>
-
-<H3><A NAME="scriptsock">ScriptSock</A> directive</H3>
-
-<p><A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> Scriptsock <EM>filename</EM><BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> logs/cgisock<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_cgid</p>
-
-<p>This directive sets the name of the socket to use for communication
-with the CGI daemon. The socket will be opened using the permissions
-of the user who starts Apache (usually root). To maintain the security
-of communications with CGI scripts, it is important that no other
-user has permission to write in the directory where the socket is
-located.</p>
-
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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_cgid</h1>
+
+ <p>This module provides for execution of CGI scripts using an
+ external CGI daemon.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base (unix threaded
+ MPMs only)<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_cgid.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ cgid_module</p>
+
+ <h2>Summary</h2>
+
+ <p>On certain unix operating systems, forking a process from a
+ multi-threaded server is a very expensive operation because the
+ new process will replicate all the threads of the parent
+ process. In order to avoid incurring this expense on each CGI
+ invocation, mod_cgid creates an external daemon that is
+ responsible for forking child processes to run CGI scripts. The
+ main server communicates with this daemon using a unix domain
+ socket.</p>
+
+ <p>This module is used by default whenever a multi-threaded MPM
+ is selected during the compilation process. At the user level,
+ this module is identical in configuration and operation to <a
+ href="mod_cgi.html">mod_cgi</a>. The only exception is the
+ additional directive <code>ScriptSock</code> which gives the
+ name of the socket to use for communication with the cgi
+ daemon.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="mod_cgi.html#scriptlog">ScriptLog</a></li>
+
+ <li><a
+ href="mod_cgi.html#scriptloglength">ScriptLogLength</a></li>
+
+ <li><a
+ href="mod_cgi.html#scriptlogbuffer">ScriptLogBuffer</a></li>
+
+ <li><a href="#scriptsock">ScriptSock</a></li>
+ </ul>
+ <hr />
+
+ <h3><a id="scriptsock" name="scriptsock">ScriptSock</a>
+ directive</h3>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> Scriptsock
+ <em>filename</em><br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> logs/cgisock<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_cgid</p>
+
+ <p>This directive sets the name of the socket to use for
+ communication with the CGI daemon. The socket will be opened
+ using the permissions of the user who starts Apache (usually
+ root). To maintain the security of communications with CGI
+ scripts, it is important that no other user has permission to
+ write in the directory where the socket is located.</p>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
- <HEAD>
- <TITLE>Apache module mod_charset_lite</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_charset_lite</H1>
-
-<p>This module provides the ability to specify character set
- translation or recoding.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Experimental
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_charset_lite.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> charset_lite_module
-</P>
-
- <H2>Summary</H2>
- <P>
- This is an <STRONG>experimental</STRONG> module and should be used with
- care. Experiment with your <CODE>mod_charset_lite</CODE> configuration to
- ensure that it performs the desired function.
- </P>
- <P>
- <CODE>mod_charset_lite</CODE> allows the administrator to specify the
- source character set of objects as well as the character set they should
- be translated into before sending to the client.
- <CODE>mod_charset_lite</CODE> does not translate the data itself but
- instead tells Apache what translation to perform.
- <CODE>mod_charset_lite</CODE> is applicable to EBCDIC and ASCII
- host environments. In an EBCDIC environment, Apache normally translates
- text content from the code page of the Apache process locale to
- ISO-8859-1. <CODE>mod_charset_lite</CODE> can be used to specify that
- a different translation is to be performed. In an ASCII environment,
- Apache normally performs no translation, so <CODE>mod_charset_lite</CODE>
- is needed in order for any translation to take place.
- </P>
-
- <p>This module will only work if <code>APACHE_XLATE</code> is defined
- at compile time.</p>
-
- <P>
- This module provides a small subset of configuration mechanisms
- implemented by Russian Apache and its associated <CODE>mod_charset</CODE>.
- </P>
-
- <H2>Directives</H2>
- <UL>
- <LI><A HREF="#charsetsourceenc">CharsetSourceEnc</A>
- <LI><A HREF="#charsetdefault">CharsetDefault</A>
- <LI><A HREF="#charsetoptions">CharsetOptions</A>
- </LI>
- </UL>
-
- <H2>Common Problems</H2>
-
- <H3>Invalid character set names</H3>
-
- <P>
- The character set name parameters of CharsetSourceEnc and CharsetDefault
- must be acceptable to the translation mechanism used by APR on the system
- where mod_charset_lite is deployed. These character set names are not
- standardized and are usually not the same as the corresponding values used
- in http headers. Currently, APR can only use iconv(3), so you can easily
- test your character set names using the iconv(1) program, as follows:
- </P>
-
- <PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache module mod_charset_lite</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_charset_lite</h1>
+
+ <p>This module provides the ability to specify character set
+ translation or recoding.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Experimental<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_charset_lite.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ charset_lite_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This is an <strong>experimental</strong> module and should
+ be used with care. Experiment with your
+ <code>mod_charset_lite</code> configuration to ensure that it
+ performs the desired function.</p>
+
+ <p><code>mod_charset_lite</code> allows the administrator to
+ specify the source character set of objects as well as the
+ character set they should be translated into before sending to
+ the client. <code>mod_charset_lite</code> does not translate
+ the data itself but instead tells Apache what translation to
+ perform. <code>mod_charset_lite</code> is applicable to EBCDIC
+ and ASCII host environments. In an EBCDIC environment, Apache
+ normally translates text content from the code page of the
+ Apache process locale to ISO-8859-1.
+ <code>mod_charset_lite</code> can be used to specify that a
+ different translation is to be performed. In an ASCII
+ environment, Apache normally performs no translation, so
+ <code>mod_charset_lite</code> is needed in order for any
+ translation to take place.</p>
+
+ <p>This module will only work if <code>APACHE_XLATE</code> is
+ defined at compile time.</p>
+
+ <p>This module provides a small subset of configuration
+ mechanisms implemented by Russian Apache and its associated
+ <code>mod_charset</code>.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#charsetsourceenc">CharsetSourceEnc</a></li>
+
+ <li><a href="#charsetdefault">CharsetDefault</a></li>
+
+ <li><a href="#charsetoptions">CharsetOptions</a></li>
+ </ul>
+
+ <h2>Common Problems</h2>
+
+ <h3>Invalid character set names</h3>
+
+ <p>The character set name parameters of CharsetSourceEnc and
+ CharsetDefault must be acceptable to the translation mechanism
+ used by APR on the system where mod_charset_lite is deployed.
+ These character set names are not standardized and are usually
+ not the same as the corresponding values used in http headers.
+ Currently, APR can only use iconv(3), so you can easily test
+ your character set names using the iconv(1) program, as
+ follows:</p>
+<pre>
iconv -f charsetsourceenc-value -t charsetdefault-value
- </PRE>
-
- <H3>Mismatch between character set of content and translation rules</H3>
-
- <P>
- If the translation rules don't make sense for the content, translation
- can fail in various ways, including:
- </P>
-
- <UL>
- <LI>
- The translation mechanism may return a bad return code, and the connection
- will be aborted.
- <LI>
- The translation mechanism may silently place special characters (e.g., question
- marks) in the output buffer when it cannot translate the input buffer.
- </UL>
-
- <HR>
-
- <H2><A NAME="charsetsourceenc">CharsetSourceEnc</A></H2>
- <P>
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> CharsetSourceEnc <EM>charset</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> directory, virtual host
- <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> Experimental
- <BR>
- <A
- HREF="directive-dict.html#Module"
- REL="Help"
- ><STRONG>Module:</STRONG></A> mod_charset_lite
- <BR>
-
- <P>
- The <CODE>CharsetSourceEnc</CODE> directive specifies the source charset
- of files in the associated container.
- </P>
-
- <P>
- The value of the <EM>charset</EM> argument must be accepted as a valid
- character set name by the character set support in APR. Generally, this
- means that it must be supported by iconv.
- </P>
-
- Example:
-
- <PRE>
+
+</pre>
+
+ <h3>Mismatch between character set of content and translation
+ rules</h3>
+
+ <p>If the translation rules don't make sense for the content,
+ translation can fail in various ways, including:</p>
+
+ <ul>
+ <li>The translation mechanism may return a bad return code,
+ and the connection will be aborted.</li>
+
+ <li>The translation mechanism may silently place special
+ characters (e.g., question marks) in the output buffer when
+ it cannot translate the input buffer.</li>
+ </ul>
+ <hr />
+
+ <h2><a id="charsetsourceenc"
+ name="charsetsourceenc">CharsetSourceEnc</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> CharsetSourceEnc
+ <em>charset</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> directory, virtual
+ host<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> Experimental<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_charset_lite<br />
+ </p>
+
+ <p>The <code>CharsetSourceEnc</code> directive specifies the
+ source charset of files in the associated container.</p>
+
+ <p>The value of the <em>charset</em> argument must be accepted
+ as a valid character set name by the character set support in
+ APR. Generally, this means that it must be supported by
+ iconv.</p>
+ Example:
+<pre>
<Directory "/export/home/trawick/apacheinst/htdocs/convert">
CharsetSourceEnc UTF-16BE
CharsetDefault ISO8859-1
</Directory>
- </PRE>
-
- The character set names in this example work with the iconv
- translation support in Solaris 8.
- <P>
-
-<hr>
-
- <H2><A NAME="charsetdefault">CharsetDefault</A></H2>
- <P>
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> CharsetDefault <EM>charset</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> directory, virtual host
- <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> Experimental
- <BR>
- <A
- HREF="directive-dict.html#Module"
- REL="Help"
- ><STRONG>Module:</STRONG></A> mod_charset_lite
- <BR>
-
- <P>
- The <CODE>CharsetDefault</CODE> directive specifies the charset that
- content in the associated container should be translated to.
- </P>
-
- <P>
- The value of the <EM>charset</EM> argument must be accepted as a valid
- character set name by the character set support in APR. Generally, this
- means that it must be supported by iconv.
- </P>
-
- Example:
-
- <PRE>
+
+</pre>
+ The character set names in this example work with the iconv
+ translation support in Solaris 8.
+ <hr />
+
+ <h2><a id="charsetdefault"
+ name="charsetdefault">CharsetDefault</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> CharsetDefault
+ <em>charset</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> directory, virtual
+ host<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> Experimental<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_charset_lite<br />
+ </p>
+
+ <p>The <code>CharsetDefault</code> directive specifies the
+ charset that content in the associated container should be
+ translated to.</p>
+
+ <p>The value of the <em>charset</em> argument must be accepted
+ as a valid character set name by the character set support in
+ APR. Generally, this means that it must be supported by
+ iconv.</p>
+ Example:
+<pre>
<Directory "/export/home/trawick/apacheinst/htdocs/convert">
CharsetSourceEnc UTF-16BE
CharsetDefault ISO8859-1
</Directory>
- </PRE>
-
- <P>
-
-<hr>
-
- <H2><A NAME="charsetoptions">CharsetOptions</A></H2>
- <P>
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> CharsetOptions <EM>option</em>
- [<em>option</em>] ...
- <BR>
- <A
- HREF="directive-dict.html#Default"
- REL="Help"
- ><STRONG>Default:</STRONG></A> <EM>DebugLevel=0</EM> <EM>NoImplicitAdd</EM>
- <BR>
- <A
- HREF="directive-dict.html#Context"
- REL="Help"
- ><STRONG>Context:</STRONG></A> directory, virtual host
- <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> Experimental
- <BR>
- <A
- HREF="directive-dict.html#Module"
- REL="Help"
- ><STRONG>Module:</STRONG></A> mod_charset_lite
- <BR>
-
- <P>
- The <CODE>CharsetOptions</CODE> directive configures certain behaviors
- of <CODE>mod_charset_lite</CODE>. <EM>Option</EM> can be one of
- <DL>
- <DT>DebugLevel=<EM>n</EM>
- <DD>
- The <SAMP>DebugLevel</SAMP> keyword allows you to specify the level of
- debug messages generated by <CODE>mod_charset_lite</CODE>. By default, no
- messages are generated. This is equivalent to <SAMP>DebugLevel=0</SAMP>.
- With higher numbers, more debug messages are generated, and server
- performance will be degraded. The actual meanings of the numeric values
- are described with the definitions of the DBGLVL_ constants near the
- beginning of <CODE>mod_charset_lite.c</CODE>.
- <DT>ImplicitAdd | NoImplicitAdd
- <DD>
- The <SAMP>ImplicitAdd</SAMP> keyword specifies that
- <CODE>mod_charset_lite</CODE> should implicitly insert its filter when
- the configuration specifies that the character set of content should be
- translated. If the filter chain is explicitly configured using the
- AddOutputFilter directive, <SAMP>NoImplicitAdd</SAMP> should be specified so
- that <CODE>mod_charset_lite</CODE> doesn't add its filter.
- </DL>
- </P>
-
-<!--#include virtual="footer.html" -->
- </BODY>
-</HTML>
+</pre>
+ <hr />
+
+ <h2><a id="charsetoptions"
+ name="charsetoptions">CharsetOptions</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> CharsetOptions
+ <em>option</em> [<em>option</em>] ...<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> <em>DebugLevel=0</em>
+ <em>NoImplicitAdd</em><br />
+ <a href="directive-dict.html#Context"
+ rel="Help"><strong>Context:</strong></a> directory, virtual
+ host<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> Experimental<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_charset_lite<br />
+ </p>
+
+ <p>The <code>CharsetOptions</code> directive configures certain
+ behaviors of <code>mod_charset_lite</code>. <em>Option</em> can
+ be one of</p>
+
+ <dl>
+ <dt>DebugLevel=<em>n</em></dt>
+
+ <dd>The <samp>DebugLevel</samp> keyword allows you to specify
+ the level of debug messages generated by
+ <code>mod_charset_lite</code>. By default, no messages are
+ generated. This is equivalent to <samp>DebugLevel=0</samp>.
+ With higher numbers, more debug messages are generated, and
+ server performance will be degraded. The actual meanings of
+ the numeric values are described with the definitions of the
+ DBGLVL_ constants near the beginning of
+ <code>mod_charset_lite.c</code>.</dd>
+
+ <dt>ImplicitAdd | NoImplicitAdd</dt>
+
+ <dd>The <samp>ImplicitAdd</samp> keyword specifies that
+ <code>mod_charset_lite</code> should implicitly insert its
+ filter when the configuration specifies that the character
+ set of content should be translated. If the filter chain is
+ explicitly configured using the AddOutputFilter directive,
+ <samp>NoImplicitAdd</samp> should be specified so that
+ <code>mod_charset_lite</code> doesn't add its filter.</dd>
+ </dl>
+ <br />
+ <br />
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache module mod_dav</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_dav</H1>
-
-<p>This module provides Distributed Authoring and Versioning
-(<a href="http://www.webdav.org/">WebDAV</a>) functionality.</p>
-
-<A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_dav.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> dav_module
-
-<h2>Summary</h2>
-
-<p>This module provides class 1 and class 2
-<A HREF="http://www.webdav.org">WebDAV</A> ('Web-based
-Distributed Authoring and Versioning') functionality for Apache.
-This extension to the HTTP protocol allows creating, moving,
-copying, and deleting resources and collections on a remote web
-server.</p>
-
-<P>
-To enable mod_dav, add the following to a container in your <CODE>httpd.conf</CODE> file:</P>
-
-<blockquote>
-<CODE>Dav On</CODE>
-</blockquote>
-
-<p>Also, specify a valid filename for the DAV lock database by adding
-the following to the global section in your <CODE>httpd.conf</CODE>
-file:</p>
-
-<blockquote>
-<CODE>DavLockDB /tmp/DavLock </CODE><EM>(Any web-server writable filename, without an extension)</EM>
-</blockquote>
-
-
-
-<H2>Directives</H2>
-<UL>
-<LI><A HREF="#DAV">Dav</A>
-<LI><A HREF="#DAVLockDB">DavLockDB</A>
-<LI><A HREF="#DAVMinTimeout">DavMinTimeout</A>
-<LI><A HREF="#DAVDepthInfinity">DavDepthInfinity</A>
-</UL>
-
-<HR>
-
-<H2><A NAME="DAV">Dav</A></H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> Dav on|off<BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A>
- <CODE>Dav off</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> extension<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_dav<BR>
-<A
- HREF="directive-dict.html#Compatibility"
- REL="Help"
-><STRONG>Compatibility:</STRONG></A> Apache 1.3.4 and above
-
-<p>Use the <CODE>Dav</CODE> directive to enable the WebDAV HTTP methods
-for the given container.
-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 DAV-enabled locations.</P>
-
-<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
-<TR><TD>
-<STRONG>Example</STRONG>:<BR><BR>
-<CODE>DavLockDB /tmp/DavLock<BR>
-<BR>
-<Location /foo><BR>
-Dav On<BR>
-<BR>
-AuthType Basic<BR>
-AuthName DAV<BR>
-AuthUserFile user.passwd<BR>
-<BR>
- <LimitExcept GET HEAD OPTIONS><BR>
- require user admin<BR>
- </LimitExcept><BR>
-</Location><BR>
-</CODE>
-</TD></TR>
-</TABLE>
-
-<BR>
-<HR>
-
-<H2><A NAME="DavLockDB">DavLockDB</A></H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> DavLockDB <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#Status"
- REL="Help"
-><STRONG>Status:</STRONG></A> extension<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_dav
-
-<p>Use the <CODE>DavLockDB</CODE> directive to specify the full path to the
-lock database, excluding an extension. The default (file system)
-implementation of mod_dav uses a SDBM database to track user locks.
-The utility <CODE>modules/dav/util/lockview</CODE> can be
-used from the server to display all locks in a lock database.</P>
-
-<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
-<TR><TD>
-<STRONG>Example</STRONG>:<BR><BR>
-<CODE>DavLockDB /tmp/DavLock<BR>
-<BR>
-</CODE>
-</TD></TR>
-</TABLE>
-
-<BR>
-<HR>
-
-<H2><A NAME="DavMinTimeout">DavMinTimeout</A></H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> DavMinTimeout <em>seconds</em><BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A>
- <CODE>DavMinTimeout 0</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> extension<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_dav
-
-<p>When a client requests a DAV resource lock, it can also specify a time
-when the lock will be automatically removed by the server. This value
-is only a request, and the server can ignore it or inform the client
-of an arbitrary value.</P>
-
-<p>Use the <CODE>DavMinTimeout</CODE> directive to specify, in seconds,
-the minimum lock timeout to return to a client. Microsoft Web Folders
-defaults to a timeout of 120 seconds; the <CODE>DavMinTimeout</CODE>
-can override this to a higher value (like 600 seconds) to reduce the chance
-of the client losing the lock due to network latency.</P>
-
-<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
-<TR><TD>
-<STRONG>Example</STRONG>:<BR><BR>
-<CODE><Location /MSWord><BR>
-DavMinTimeout 600<BR>
-</Location><BR>
-<BR>
-</CODE>
-</TD></TR>
-</TABLE>
-
-<BR>
-<HR>
-
-<H2><A NAME="DavDepthInfinity">DavDepthInfinity</A></H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> DavDepthInfinity on|off<BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A>
- <CODE>DavDepthInfinity off</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> extension<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_dav
-
-<p>Use the <CODE>DavDepthInfinity</CODE> directive to allow the processing
-of PROPFIND requests containing the header 'Depth: Infinity'.
-Because this type of request could constitute a denial-of-service attack,
-by default it is not allowed.</P>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache module mod_dav</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_dav</h1>
+
+ <p>This module provides Distributed Authoring and Versioning
+ (<a href="http://www.webdav.org/">WebDAV</a>)
+ functionality.</p>
+ <a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension <br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_dav.c <br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a> dav_module
+
+ <h2>Summary</h2>
+
+ <p>This module provides class 1 and class 2 <a
+ href="http://www.webdav.org">WebDAV</a> ('Web-based Distributed
+ Authoring and Versioning') functionality for Apache. This
+ extension to the HTTP protocol allows creating, moving,
+ copying, and deleting resources and collections on a remote web
+ server.</p>
+
+ <p>To enable mod_dav, add the following to a container in your
+ <code>httpd.conf</code> file:</p>
+
+ <blockquote>
+ <code>Dav On</code>
+ </blockquote>
+
+ <p>Also, specify a valid filename for the DAV lock database by
+ adding the following to the global section in your
+ <code>httpd.conf</code> file:</p>
+
+ <blockquote>
+ <code>DavLockDB /tmp/DavLock </code>
+ <em>(Any web-server writable filename, without an
+ extension)</em>
+ </blockquote>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#DAV">Dav</a></li>
+
+ <li><a href="#DAVLockDB">DavLockDB</a></li>
+
+ <li><a href="#DAVMinTimeout">DavMinTimeout</a></li>
+
+ <li><a href="#DAVDepthInfinity">DavDepthInfinity</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="DAV" name="DAV">Dav</a></h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> Dav on|off<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> <code>Dav
+ off</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> extension<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_dav<br />
+ <a href="directive-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Apache 1.3.4 and
+ above
+
+ <p>Use the <code>Dav</code> directive to enable the WebDAV HTTP
+ methods for the given container. 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 DAV-enabled locations.</p>
+
+ <table width="70%" border="0" bgcolor="#E0E0F0" cellspacing="0"
+ cellpadding="10">
+ <tr>
+ <td><strong>Example</strong>:<br />
+ <br />
+ <code>DavLockDB /tmp/DavLock<br />
+ <br />
+ <Location /foo><br />
+ Dav On<br />
+ <br />
+ AuthType Basic<br />
+ AuthName DAV<br />
+ AuthUserFile user.passwd<br />
+ <br />
+ <LimitExcept GET HEAD OPTIONS><br />
+ require user admin<br />
+ </LimitExcept><br />
+ </Location><br />
+ </code> </td>
+ </tr>
+ </table>
+ <br />
+
+ <hr />
+
+ <h2><a id="DavLockDB" name="DavLockDB">DavLockDB</a></h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> DavLockDB
+ <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#Status"
+ rel="Help"><strong>Status:</strong></a> extension<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_dav
+
+ <p>Use the <code>DavLockDB</code> directive to specify the full
+ path to the lock database, excluding an extension. The default
+ (file system) implementation of mod_dav uses a SDBM database to
+ track user locks. The utility
+ <code>modules/dav/util/lockview</code> can be used from the
+ server to display all locks in a lock database.</p>
+
+ <table width="70%" border="0" bgcolor="#E0E0F0" cellspacing="0"
+ cellpadding="10">
+ <tr>
+ <td><strong>Example</strong>:<br />
+ <br />
+ <code>DavLockDB /tmp/DavLock<br />
+ <br />
+ </code> </td>
+ </tr>
+ </table>
+ <br />
+
+ <hr />
+
+ <h2><a id="DavMinTimeout"
+ name="DavMinTimeout">DavMinTimeout</a></h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> DavMinTimeout
+ <em>seconds</em><br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> <code>DavMinTimeout
+ 0</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> extension<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_dav
+
+ <p>When a client requests a DAV resource lock, it can also
+ specify a time when the lock will be automatically removed by
+ the server. This value is only a request, and the server can
+ ignore it or inform the client of an arbitrary value.</p>
+
+ <p>Use the <code>DavMinTimeout</code> directive to specify, in
+ seconds, the minimum lock timeout to return to a client.
+ Microsoft Web Folders defaults to a timeout of 120 seconds; the
+ <code>DavMinTimeout</code> can override this to a higher value
+ (like 600 seconds) to reduce the chance of the client losing
+ the lock due to network latency.</p>
+
+ <table width="70%" border="0" bgcolor="#E0E0F0" cellspacing="0"
+ cellpadding="10">
+ <tr>
+ <td><strong>Example</strong>:<br />
+ <br />
+ <code><Location /MSWord><br />
+ DavMinTimeout 600<br />
+ </Location><br />
+ <br />
+ </code> </td>
+ </tr>
+ </table>
+ <br />
+
+ <hr />
+
+ <h2><a id="DavDepthInfinity"
+ name="DavDepthInfinity">DavDepthInfinity</a></h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> DavDepthInfinity
+ on|off<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> <code>DavDepthInfinity
+ off</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> extension<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_dav
+
+ <p>Use the <code>DavDepthInfinity</code> directive to allow the
+ processing of PROPFIND requests containing the header 'Depth:
+ Infinity'. Because this type of request could constitute a
+ denial-of-service attack, by default it is not allowed.</p>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!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>
-
-<p>This module provides for "trailing slash" redirects and serving
-directory index files.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_dir.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> dir_module
-</P>
-
-<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> directive</H2>
-<!--%plaintext <?INDEX {\tt DirectoryIndex} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> DirectoryIndex <EM>local-url</em>
- [<em>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>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module provides for "trailing slash" redirects and
+ serving directory index files.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_dir.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ dir_module</p>
+
+ <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>
+
+ <li>Otherwise, a listing generated by the server. This is
+ provided by <a
+ href="mod_autoindex.html"><code>mod_autoindex</code></a>.</li>
+ </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>.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#directoryindex">DirectoryIndex</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="directoryindex"
+ name="directoryindex">DirectoryIndex</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt DirectoryIndex} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> DirectoryIndex
+ <em>local-url</em> [<em>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>
+
+ <p>Example:</p>
+
+ <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;</p>
+
+ <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><!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
-<!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>
-
-<p>This module provides for modifying the environment which
-is passed to CGI scripts and SSI pages.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_env.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> env_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.1 and later.
-</P>
-
-<H2>Summary</H2>
-
-<p>This module allows for control of the environment that will be
-provided to CGI scripts and SSI pages. Environment variables may be
-passed from the shell which invoked the httpd process. Alternatively,
-environment variables may be set or unset within the configuration
-process.</p>
-
-<p>For additional information, we provide a document on
-<a href="../env.html">Environment Variables in Apache</a>.</p>
-
-<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> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> PassEnv <EM>env-variable</em>
- [<em>env-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
-and SSI pages from the environment of the shell which invoked
-the httpd process. Example:
-<PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>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>
+
+ <p>This module provides for modifying the environment which is
+ passed to CGI scripts and SSI pages.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_env.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ env_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.1 and later.</p>
+
+ <h2>Summary</h2>
+
+ <p>This module allows for control of the environment that will
+ be provided to CGI scripts and SSI pages. Environment variables
+ may be passed from the shell which invoked the httpd process.
+ Alternatively, environment variables may be set or unset within
+ the configuration process.</p>
+
+ <p>For additional information, we provide a document on <a
+ href="../env.html">Environment Variables in Apache</a>.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#passenv">PassEnv</a></li>
+
+ <li><a href="#setenv">SetEnv</a></li>
+
+ <li><a href="#unsetenv">UnsetEnv</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="passenv" name="passenv">PassEnv</a> directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> PassEnv
+ <em>env-variable</em> [<em>env-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 and SSI pages from the environment of the shell which
+ invoked the httpd process. Example:</p>
+<pre>
PassEnv LD_LIBRARY_PATH
-</PRE>
-
-<HR>
-
-<H2><A NAME="setenv">SetEnv</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> SetEnv <EM>env-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 and SSI pages. Example:
-<PRE>
+</pre>
+ <hr />
+
+ <h2><a id="setenv" name="setenv">SetEnv</a> directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> SetEnv <em>env-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 and SSI pages. Example:</p>
+<pre>
SetEnv SPECIAL_PATH /foo/bin
-</PRE>
-
-<HR>
-
-<H2><A NAME="unsetenv">UnsetEnv</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> UnsetEnv <EM>env-variable</em>
- [<em>env-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 and SSI pages. Example:
-<PRE>
+</pre>
+ <hr />
+
+ <h2><a id="unsetenv" name="unsetenv">UnsetEnv</a>
+ directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> UnsetEnv
+ <em>env-variable</em> [<em>env-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 and SSI pages. Example:</p>
+<pre>
UnsetEnv LD_LIBRARY_PATH
-</PRE>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</pre>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-<!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" -->
-
-<blockquote><strong>Warning:</strong>
-This document has not been updated to take into account changes
-made in the 2.0 version of the Apache HTTP Server. Some of the
-information may still be relevant, but please use it
-with care.
-</blockquote>
-
- <H1 ALIGN="CENTER">Module mod_example</H1>
- <P>
- This module 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>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_example.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> example_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later.
-</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>
- <H2>Directives</H2>
- <P>
- <UL>
- <LI><A HREF="#example">Example</A>
- </LI>
- </UL>
- </P>
-
- <h2>Compiling the example module</h2>
- <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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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" -->
+
+ <blockquote>
+ <strong>Warning:</strong> This document has not been updated
+ to take into account changes made in the 2.0 version of the
+ Apache HTTP Server. Some of the information may still be
+ relevant, but please use it with care.
+ </blockquote>
+
+ <h1 align="CENTER">Module mod_example</h1>
+
+ <p>This module 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>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_example.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ example_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.2 and later.</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>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#example">Example</a></li>
+ </ul>
+ <br />
+ <br />
+
+
+ <h2>Compiling the example module</h2>
+
+ <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>
- <H2>
- Using the <SAMP>mod_example</SAMP> Module
- </H2>
- <P>
- To activate the example module, include a block similar to the
- following in your <SAMP>srm.conf</SAMP> file:
- </P>
- <PRE>
+
+</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>
+
+ <h2>Using the <samp>mod_example</samp> Module</h2>
+
+ <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>
+
+</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>
-
- <HR>
- <H2><A NAME="example">
- Example directive
- </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>
+
+</pre>
+
+ <p>After reloading/restarting your server, you should be able
+ to browse to this location and see the brief display mentioned
+ earlier.</p>
+ <hr />
+
+ <h2><a id="example" name="example">Example directive</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>
+
-<!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 provides for the generation of <CODE>Expires</CODE> HTTP
- headers according to user-specified criteria.
- </P>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_expires.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> expires_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later.
-</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>
- <ul>
- <LI><A
- HREF="#expiresactive"
- >ExpiresActive</A>
- </LI>
- <LI><A
- HREF="#expiresbytype"
- >ExpiresByType</A>
- </LI>
- <LI><A
- HREF="#expiresdefault"
- >ExpiresDefault</A>
- </LI>
- </ul>
-
- <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.
-
- <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 on|off
- <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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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 provides for the generation of
+ <code>Expires</code> HTTP headers according to user-specified
+ criteria.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_expires.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ expires_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.2 and later.</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>
+
+ <ul>
+ <li><a href="#expiresactive">ExpiresActive</a></li>
+
+ <li><a href="#expiresbytype">ExpiresByType</a></li>
+
+ <li><a href="#expiresdefault">ExpiresDefault</a></li>
+ </ul>
+
+ <h2><a id="AltSyn" 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>
+
+ <ul>
+ <li><samp>access</samp></li>
+
+ <li><samp>now</samp> (equivalent to
+ '<samp>access</samp>')</li>
+
+ <li><samp>modification</samp></li>
+ </ul>
+
+ <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>
+
+ <ul>
+ <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>
+ </ul>
+
+ <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.</p>
+ <hr />
+
+ <h2><a id="expiresactive" 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
+ on|off<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 id="expiresbytype" 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>
+<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>
-
- <!--#include virtual="footer.html" -->
- </BODY>
-</HTML>
+
+</pre>
+ <br />
+ <br />
+
+
+ <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 id="expiresdefault" 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>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
- <HEAD>
- <TITLE>Apache module mod_ext_filter</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_ext_filter</H1>
-
- <P>This module provides the ability to pass the response body
- through an external program before delivering to the client.</p>
-
-<p><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Experimental
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_ext_filter.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> ext_filter_module</p>
-
-
- <H2>Summary</H2>
- <P>
- This is an <STRONG>experimental</STRONG> module and should be used with
- care. Test your <CODE>mod_ext_filter</CODE> configuration carefully to
- ensure that it performs the desired function. You may wish to review
- XXX for background on the Apache filtering model.
- </P>
-
- <P>
- <CODE>mod_ext_filter</CODE> presents a simple and familiar programming
- model for filters. With this module, a program which reads from stdin and
- writes to stdout (i.e., a Unix-style filter command) can be a filter for
- Apache. This filtering mechanism is much slower than using a filter which
- is specially written for the Apache API and runs inside of the Apache
- server process, but it does have the following benefits:
- </P>
-
- <UL>
- <LI>the programming model is much simpler
- <LI>any programming/scripting language can be used, provided that
- it allows the program to read from standard input and write to standard
- output
- <LI>existing programs can be used unmodified as Apache filters
- </UL>
-
- <P>
- Even when the performance characteristics are not suitable for production
- use, <CODE>mod_ext_filter</CODE> can be used as a prototype environment
- for filters.
- </P>
-
- <H2>Directives</H2>
- <UL>
- <LI><A HREF="#extfilterdefine">ExtFilterDefine</A>
- <LI><A HREF="#extfilteroptions">ExtFilterOptions</A>
- </LI>
- </UL>
-
-
- <H2>Examples</H2>
-
- <H3>Generating HTML from some other type of response</H3>
-
- <PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache module mod_ext_filter</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_ext_filter</h1>
+
+ <p>This module provides the ability to pass the response body
+ through an external program before delivering to the
+ client.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Experimental<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_ext_filter.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ ext_filter_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This is an <strong>experimental</strong> module and should
+ be used with care. Test your <code>mod_ext_filter</code>
+ configuration carefully to ensure that it performs the desired
+ function. You may wish to review XXX for background on the
+ Apache filtering model.</p>
+
+ <p><code>mod_ext_filter</code> presents a simple and familiar
+ programming model for filters. With this module, a program
+ which reads from stdin and writes to stdout (i.e., a Unix-style
+ filter command) can be a filter for Apache. This filtering
+ mechanism is much slower than using a filter which is specially
+ written for the Apache API and runs inside of the Apache server
+ process, but it does have the following benefits:</p>
+
+ <ul>
+ <li>the programming model is much simpler</li>
+
+ <li>any programming/scripting language can be used, provided
+ that it allows the program to read from standard input and
+ write to standard output</li>
+
+ <li>existing programs can be used unmodified as Apache
+ filters</li>
+ </ul>
+
+ <p>Even when the performance characteristics are not suitable
+ for production use, <code>mod_ext_filter</code> can be used as
+ a prototype environment for filters.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#extfilterdefine">ExtFilterDefine</a></li>
+
+ <li><a href="#extfilteroptions">ExtFilterOptions</a></li>
+ </ul>
+
+ <h2>Examples</h2>
+
+ <h3>Generating HTML from some other type of response</h3>
+<pre>
# mod_ext_filter directive to define a filter to HTML-ize text/c files
# using the external program /usr/bin/enscript, with the type of the
# result set to text/html
ExtFilterOptions DebugLevel=1
</Directory>
- </PRE>
+
+</pre>
- <H3>Implementing a content encoding filter</H3>
-
- <PRE>
+ <h3>Implementing a content encoding filter</h3>
+<pre>
# mod_ext_filter directive to define the external filter
ExtFilterDefine gzip mode=output cmd=/bin/gzip
Header set Content-Encoding gzip
</Location>
- </PRE>
+
+</pre>
- <H3>Slowing down the server</H3>
- <PRE>
+ <h3>Slowing down the server</h3>
+<pre>
# mod_ext_filter directive to define a filter which runs everything
# through cat; cat doesn't modify anything; it just introduces extra
# pathlength and consumes more resources
SetOutputFilter slowdown slowdown slowdown
</Location>
- </PRE>
-
- <HR>
-
- <H2><A NAME="extfilterdefine">ExtFilterDefine</A></H2>
- <P>
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> ExtFilterDefine <EM>filtername</EM> <EM>parameters</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
- <BR>
- <A
- HREF="directive-dict.html#Override"
- REL="Help"
- ><STRONG>Override:</STRONG></A> none
- <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_ext_filter
-
- <P>
- The <CODE>ExtFilterDefine</CODE> directive defines the characteristics of
- an external filter, including the program to run and its arguments.
- </P>
-
- <P>
- <EM>filtername</EM> specifies the name of the filter being defined. This name
- can then be used in SetOutputFilter directives. It must be unique among all
- registered filters. <EM>At the present time, no error is reported by the
- register-filter API, so a problem with duplicate names isn't reported to the
- user.</EM>
- </P>
-
- <P>
- Subsequent parameters can appear in any order and define the external command
- to run and certain other characteristics. The only required parameter is
- <EM>cmd=</EM>. These parameters are:
- </P>
-
- <DL>
- <DT>cmd=<EM>cmdline</EM>
- <DD>
- The <SAMP>cmd=</SAMP> keyword allows you to specify the external command
- to run. If there are arguments after the program name, the command line
- should be surrounded in quotation marks.
- <DT>mode=<EM>mode</EM>
- <DD>
- <EM>mode</EM> should be <EM>output</EM> for now (the default). In the
- future, <EM>mode=input</EM> will be used to specify a filter for request
- bodies.
- <DT>intype=<EM>imt</EM>
- <DD>
- This parameter specifies the internet media
- type (i.e., MIME type) of documents which should be filtered. By default,
- all documents are filtered. If <CODE>intype=</CODE> is specified,
- the filter will be disabled for documents of other types.
- <DT>outtype=<EM>imt</EM>
- <DD>
- This parameter specifies the internet media
- type (i.e., MIME type) of filtered documents. It is useful when the filter
- changes the internet media type as part of the filtering operation. By
- default, the internet media type is unchanged.
- <DT>PreservesContentLength
- <DD>
- The <SAMP>PreservesContentLength</SAMP> keyword specifies that the filter
- preserves the content length. This is not the default, as most filters
- change the content length. In the event that the filter doesn't modify the
- length, this keyword should be specified.
- </DL>
-
-<hr>
-
- <H2><A NAME="extfilteroptions">ExtFilterOptions</A></H2>
- <P>
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> ExtFilterOptions <EM>option</em>
- [<em>option</EM>] ...
- <BR>
- <A
- HREF="directive-dict.html#Default"
- REL="Help"
- ><STRONG>Default:</STRONG></A> <EM>DebugLevel=0</EM> <EM>NoLogStderr</EM>
- <BR>
- <A
- HREF="directive-dict.html#Context"
- REL="Help"
- ><STRONG>Context:</STRONG></A> directory
- <BR>
- <A
- HREF="directive-dict.html#Override"
- REL="Help"
- ><STRONG>Override:</STRONG></A> none
- <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_ext_filter
-
- <P>
- The <CODE>ExtFilterOptions</CODE> directive specifies special processing
- options for <CODE>mod_ext_filter</CODE>. <EM>Option</EM> can be one of
- <DL>
- <DT>DebugLevel=<EM>n</EM>
- <DD>
- The <SAMP>DebugLevel</SAMP> keyword allows you to specify the level of
- debug messages generated by <CODE>mod_ext_filter</CODE>. By default, no
- debug messages are generated. This is equivalent to
- <SAMP>DebugLevel=0</SAMP>. With higher numbers, more debug messages are
- generated, and server performance will be degraded. The actual meanings
- of the numeric values are described with the definitions of the DBGLVL_
- constants near the beginning of <CODE>mod_ext_filter.c</CODE>.
- <P>
- Note: The core directive LogLevel should be used to cause debug messages
- to be stored in the Apache error log.
- <DT>LogStderr | NoLogStderr
- <DD>
- The <SAMP>LogStderr</SAMP> keyword specifies that messages written to
- standard error by the external filter program will be saved in the Apache
- error log. <SAMP>NoLogStderr</SAMP> disables this feature.
- </DL>
- </P>
-
- Example:
-
- <PRE>
+
+</pre>
+ <hr />
+
+ <h2><a id="extfilterdefine"
+ name="extfilterdefine">ExtFilterDefine</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ExtFilterDefine
+ <em>filtername</em> <em>parameters</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<br />
+ <a href="directive-dict.html#Override"
+ rel="Help"><strong>Override:</strong></a> none<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_ext_filter</p>
+
+ <p>The <code>ExtFilterDefine</code> directive defines the
+ characteristics of an external filter, including the program to
+ run and its arguments.</p>
+
+ <p><em>filtername</em> specifies the name of the filter being
+ defined. This name can then be used in SetOutputFilter
+ directives. It must be unique among all registered filters.
+ <em>At the present time, no error is reported by the
+ register-filter API, so a problem with duplicate names isn't
+ reported to the user.</em></p>
+
+ <p>Subsequent parameters can appear in any order and define the
+ external command to run and certain other characteristics. The
+ only required parameter is <em>cmd=</em>. These parameters
+ are:</p>
+
+ <dl>
+ <dt>cmd=<em>cmdline</em></dt>
+
+ <dd>The <samp>cmd=</samp> keyword allows you to specify the
+ external command to run. If there are arguments after the
+ program name, the command line should be surrounded in
+ quotation marks.</dd>
+
+ <dt>mode=<em>mode</em></dt>
+
+ <dd><em>mode</em> should be <em>output</em> for now (the
+ default). In the future, <em>mode=input</em> will be used to
+ specify a filter for request bodies.</dd>
+
+ <dt>intype=<em>imt</em></dt>
+
+ <dd>This parameter specifies the internet media type (i.e.,
+ MIME type) of documents which should be filtered. By default,
+ all documents are filtered. If <code>intype=</code> is
+ specified, the filter will be disabled for documents of other
+ types.</dd>
+
+ <dt>outtype=<em>imt</em></dt>
+
+ <dd>This parameter specifies the internet media type (i.e.,
+ MIME type) of filtered documents. It is useful when the
+ filter changes the internet media type as part of the
+ filtering operation. By default, the internet media type is
+ unchanged.</dd>
+
+ <dt>PreservesContentLength</dt>
+
+ <dd>The <samp>PreservesContentLength</samp> keyword specifies
+ that the filter preserves the content length. This is not the
+ default, as most filters change the content length. In the
+ event that the filter doesn't modify the length, this keyword
+ should be specified.</dd>
+ </dl>
+ <hr />
+
+ <h2><a id="extfilteroptions"
+ name="extfilteroptions">ExtFilterOptions</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ExtFilterOptions
+ <em>option</em> [<em>option</em>] ...<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> <em>DebugLevel=0</em>
+ <em>NoLogStderr</em><br />
+ <a href="directive-dict.html#Context"
+ rel="Help"><strong>Context:</strong></a> directory<br />
+ <a href="directive-dict.html#Override"
+ rel="Help"><strong>Override:</strong></a> none<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_ext_filter</p>
+
+ <p>The <code>ExtFilterOptions</code> directive specifies
+ special processing options for <code>mod_ext_filter</code>.
+ <em>Option</em> can be one of</p>
+
+ <dl>
+ <dt>DebugLevel=<em>n</em></dt>
+
+ <dd>
+ The <samp>DebugLevel</samp> keyword allows you to specify
+ the level of debug messages generated by
+ <code>mod_ext_filter</code>. By default, no debug messages
+ are generated. This is equivalent to
+ <samp>DebugLevel=0</samp>. With higher numbers, more debug
+ messages are generated, and server performance will be
+ degraded. The actual meanings of the numeric values are
+ described with the definitions of the DBGLVL_ constants
+ near the beginning of <code>mod_ext_filter.c</code>.
+
+ <p>Note: The core directive LogLevel should be used to
+ cause debug messages to be stored in the Apache error
+ log.</p>
+ </dd>
+
+ <dt>LogStderr | NoLogStderr</dt>
+
+ <dd>The <samp>LogStderr</samp> keyword specifies that
+ messages written to standard error by the external filter
+ program will be saved in the Apache error log.
+ <samp>NoLogStderr</samp> disables this feature.</dd>
+ </dl>
+ <br />
+ <br />
+ Example:
+<pre>
ExtFilterOptions LogStderr DebugLevel=0
- </PRE>
-
- Messages written to the filter's standard error will be stored in the Apache
- error log. No debug messages will be generated by
- <CODE>mod_ext_filter</CODE>.
+
+</pre>
+ Messages written to the filter's standard error will be stored
+ in the Apache error log. No debug messages will be generated by
+ <code>mod_ext_filter</code>.
- <P>
+ <p><!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
-<!--#include virtual="footer.html" -->
- </BODY>
-</HTML>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
- <HEAD>
- <TITLE>Apache module mod_file_cache</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_file_cache</H1>
- <P>
- <STRONG>This module should be used with care. You can easily create a
- broken site using mod_file_cache, so read this document
- carefully.</STRONG>
- </P>
-
- <P>
- <EM>Caching</EM> frequently requested files that change very
- infrequently is a technique for reducing server load. mod_file_cache
- provides two techniques for caching frequently requested
- <EM>static</EM> files.
- Through configuration directives, you can direct mod_file_cache
- to either open then mmap()a file, or to pre-open a file and save
- the file's open <EM>file handle</EM>. Both techniques reduce server
- load when processing requests for these files by doing part of the
- work (specifically, the file I/O) for serving the file when the server
- is started rather than during each request.
- </P>
-
- <P>
- <CODE>mod_file_cache</CODE> is not compiled into the server by
- default. To use <CODE>mod_file_cache</CODE> you have to enable the
- following line in the server build <CODE>Configuration</CODE> file:
- <PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache module mod_file_cache</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_file_cache</h1>
+
+ <p><strong>This module should be used with care. You can easily
+ create a broken site using mod_file_cache, so read this
+ document carefully.</strong></p>
+
+ <p><em>Caching</em> frequently requested files that change very
+ infrequently is a technique for reducing server load.
+ mod_file_cache provides two techniques for caching frequently
+ requested <em>static</em> files. Through configuration
+ directives, you can direct mod_file_cache to either open then
+ mmap()a file, or to pre-open a file and save the file's open
+ <em>file handle</em>. Both techniques reduce server load when
+ processing requests for these files by doing part of the work
+ (specifically, the file I/O) for serving the file when the
+ server is started rather than during each request.</p>
+
+ <p><code>mod_file_cache</code> is not compiled into the server
+ by default. To use <code>mod_file_cache</code> you have to
+ enable the following line in the server build
+ <code>Configuration</code> file:</p>
+<pre>
AddModule modules/experimental/mod_file_cache.o
- </PRE>
- </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>
-
- <P>
- This module is an extension of and borrows heavily from the
- mod_mmap_static module in Apache 1.3.
- </P>
- <H2>Summary</H2>
- <P>
- <CODE>mod_file_cache</CODE> caches a list of statically configured
- files via <CODE>MMapFile</CODE> or <CODE>CacheFile</CODE> directives
- in the main server configuration.
- </P>
-
- <P>
- Not all platforms support both directives. For
- example, Apache on Windows does not currently support the MMapStatic
- directive, while other platforms, like AIX, support both. You will
- receive an error message in the server error log if you attempt to
- use an unsupported directive. If given an unsupported directive, the
- server will start but the file will not be cached. On platforms that
- support both directives, you should experiment with both to see
- which works best for you.
- </P>
-
- <H3><CODE>MmapFile</CODE> Directive </H3>
- <P>
- The <CODE>MmapFile</CODE> directive of <CODE>mod_file_cache</CODE>
- maps a list of statically configured files 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 (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>
-
- <H3><CODE>CacheFile</CODE> Directive </H3>
- <P>
- The <CODE>CacheFile</CODE> directive of <CODE>mod_file_cache</CODE>
- opens an active <EM>handle</EM> or <EM>file descriptor</EM> to the
- file (or files) listed in the configuration directive and places
- these open file handles in the cache. When the file is requested,
- the server retrieves the handle from the cache and passes it to the
- sendfile() (or TransmitFile() on Windows), socket API.
- </P>
- <P>
- Insert more details about sendfile API...
- </P>
- <P>
- This file handle caching is done once at server start or restart,
- only. So whenever one of the cached files changes on the filesystem
- you <EM>have</EM> to restart the server (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.
- </P>
-
- <H2>Directives</H2>
- <UL>
- <LI><A HREF="#mmapfile">MMapFile</A>
- </LI>
- <LI><A HREF="#cachefile">CacheFile</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> [<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_file_cache
- <BR>
- <A
- HREF="directive-dict.html#Compatibility"
- REL="Help"
- ><STRONG>Compatibility:</STRONG></A> Only in Apache 1.3 (via
- mod_mmap_statis) 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>.
- </P>
-
- Example:
-
- <PRE>
+
+</pre>
+ <br />
+ <br />
+
+
+ <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>
+
+ <p>This module is an extension of and borrows heavily from the
+ mod_mmap_static module in Apache 1.3.</p>
+
+ <h2>Summary</h2>
+
+ <p><code>mod_file_cache</code> caches a list of statically
+ configured files via <code>MMapFile</code> or
+ <code>CacheFile</code> directives in the main server
+ configuration.</p>
+
+ <p>Not all platforms support both directives. For example,
+ Apache on Windows does not currently support the MMapStatic
+ directive, while other platforms, like AIX, support both. You
+ will receive an error message in the server error log if you
+ attempt to use an unsupported directive. If given an
+ unsupported directive, the server will start but the file will
+ not be cached. On platforms that support both directives, you
+ should experiment with both to see which works best for
+ you.</p>
+
+ <h3><code>MmapFile</code> Directive</h3>
+
+ <p>The <code>MmapFile</code> directive of
+ <code>mod_file_cache</code> maps a list of statically
+ configured files 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 (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>
+
+ <h3><code>CacheFile</code> Directive</h3>
+
+ <p>The <code>CacheFile</code> directive of
+ <code>mod_file_cache</code> opens an active <em>handle</em> or
+ <em>file descriptor</em> to the file (or files) listed in the
+ configuration directive and places these open file handles in
+ the cache. When the file is requested, the server retrieves the
+ handle from the cache and passes it to the sendfile() (or
+ TransmitFile() on Windows), socket API.</p>
+
+ <p>Insert more details about sendfile API...</p>
+
+ <p>This file handle caching is done once at server start or
+ restart, only. So whenever one of the cached files changes on
+ the filesystem you <em>have</em> to restart the server (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.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#mmapfile">MMapFile</a></li>
+
+ <li><a href="#cachefile">CacheFile</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="mmapfile" name="mmapfile">MMapFile</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> MMapFile
+ <em>filename</em> [<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_file_cache<br />
+ <a href="directive-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Only in Apache
+ 1.3 (via mod_mmap_statis) or later.</p>
+
+ <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>.</p>
+ Example:
+<pre>
MMapFile /usr/local/apache/htdocs/index.html
- </PRE>
-
-<hr>
-
- <H2><A NAME="cachefile">CacheFile</A></H2>
- <P>
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> CacheFile <EM>filename</EM> [<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_file_cache
- <BR>
- <A
- HREF="directive-dict.html#Compatibility"
- REL="Help"
- ><STRONG>Compatibility:</STRONG></A> Only available in Apache 2.0 or later.
-
- <P>
- The <CODE>CacheFile</CODE> directive opens handles to one or more
- files (given as whitespace separated arguments) and places these
- handles into the cache at server startup time. Handles to cached
- files are automatically closed on a server shutdown. When the files
- have changed on the filesystem, the server should be restarted to
- to re-cache 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>.
- </P>
-
- Example:
-
- <PRE>
+
+</pre>
+ <hr />
+
+ <h2><a id="cachefile" name="cachefile">CacheFile</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> CacheFile
+ <em>filename</em> [<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_file_cache<br />
+ <a href="directive-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Only available
+ in Apache 2.0 or later.</p>
+
+ <p>The <code>CacheFile</code> directive opens handles to one or
+ more files (given as whitespace separated arguments) and places
+ these handles into the cache at server startup time. Handles to
+ cached files are automatically closed on a server shutdown.
+ When the files have changed on the filesystem, the server
+ should be restarted to to re-cache 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>.</p>
+ Example:
+<pre>
CacheFile /usr/local/apache/htdocs/index.html
- </PRE>
-
- <P>
- <STRONG>Note</STRONG>: don't bother asking for a for a directive which
- recursively caches all the files in a directory. Try this
- instead...
- See the <A HREF="core.html#include">Include</A> directive, and consider this command:
- <PRE>
+
+</pre>
+
+ <p><strong>Note</strong>: don't bother asking for a for a
+ directive which recursively caches all the files in a
+ directory. Try this instead... See the <a
+ href="core.html#include">Include</a> directive, and consider
+ this command:</p>
+<pre>
find /www/htdocs -type f -print \
| sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf
- </PRE>
+
+</pre>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-<!--#include virtual="footer.html" -->
- </BODY>
-</HTML>
-<!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>
-
-<p>This module provides for the customization of HTTP request and
-response headers.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_headers.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> headers_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later.
-RequestHeader appeared in Apache 2.0.
-</P>
-
-<h2>Summary</h2>
-
-This module provides directives to control and modify HTTP
-request and response headers. Headers can be merged,
-replaced or removed.
-
-<H2>Directives</H2>
-<UL>
-<LI><A HREF="#requestheader">RequestHeader</A>
-<LI><A HREF="#header">Header</A>
-</UL>
-
-<H2>Order of Processing</H2>
-
-<p>The directives provided by mod_header can occur almost anywhere within
-the server configuration. They are valid in the main server config and virtual
-host sections, inside <Directory>, <Location> and <Files>
-sections, and within .htaccess files.</p>
-
-<P>The directives are processed in the following order:
-<OL>
-<LI>main server
-<LI>virtual host
-<LI><Directory> sections and .htaccess
-<LI><Location>
-<LI><Files>
-</OL>
-
-<p>Order is important. These two headers have a different effect if
-reversed:</p>
-
-<blockquote><code>
-RequestHeader append MirrorID "mirror 12"<br>
-RequestHeader unset MirrorID
-</code></blockquote>
-
-<p>This way round, the MirrorID header is not set. If reversed, the
-MirrorID header is set to "mirror 12".</P>
-
-<H2>Examples</H2>
-<OL>
-<LI>Copy all request headers that begin with "TS" to the response headers:</LI>
-<PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>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>
+
+ <p>This module provides for the customization of HTTP request
+ and response headers.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_headers.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ headers_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.2 and later. RequestHeader appeared in Apache 2.0.</p>
+
+ <h2>Summary</h2>
+ This module provides directives to control and modify HTTP
+ request and response headers. Headers can be merged, replaced
+ or removed.
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#requestheader">RequestHeader</a></li>
+
+ <li><a href="#header">Header</a></li>
+ </ul>
+
+ <h2>Order of Processing</h2>
+
+ <p>The directives provided by mod_header can occur almost
+ anywhere within the server configuration. They are valid in the
+ main server config and virtual host sections, inside
+ <Directory>, <Location> and <Files> sections,
+ and within .htaccess files.</p>
+
+ <p>The directives are processed in the following order:</p>
+
+ <ol>
+ <li>main server</li>
+
+ <li>virtual host</li>
+
+ <li><Directory> sections and .htaccess</li>
+
+ <li><Location></li>
+
+ <li><Files></li>
+ </ol>
+
+ <p>Order is important. These two headers have a different
+ effect if reversed:</p>
+
+ <blockquote>
+ <code>RequestHeader append MirrorID "mirror 12"<br />
+ RequestHeader unset MirrorID</code>
+ </blockquote>
+
+ <p>This way round, the MirrorID header is not set. If reversed,
+ the MirrorID header is set to "mirror 12".</p>
+
+ <h2>Examples</h2>
+
+ <ol>
+ <li>Copy all request headers that begin with "TS" to the
+ response headers:</li>
+
+ <li style="list-style: none">
+<pre>
Header echo ^TS*
-</PRE>
-
-<LI>Add a header, MyHeader, to the response including a timestamp for when
-the request was received and how long it took to begin serving the
-request. This header can be used by the client to intuit load on
-the server or in isolating bottlenecks between the client and the
-server.</LI>
-<PRE>
+</pre>
+ </li>
+
+ <li>Add a header, MyHeader, to the response including a
+ timestamp for when the request was received and how long it
+ took to begin serving the request. This header can be used by
+ the client to intuit load on the server or in isolating
+ bottlenecks between the client and the server.</li>
+
+ <li style="list-style: none">
+<pre>
Header add MyHeader "%D %t"
-</PRE>
-results in this header being added to the response:
-<PRE>
+</pre>
+ results in this header being added to the response:
+<pre>
MyHeader: D=3775428 t=991424704447256
-</PRE>
-<LI>Say hello to Joe</LI>
-<PRE>
+</pre>
+ </li>
+
+ <li>Say hello to Joe</li>
+
+ <li style="list-style: none">
+<pre>
Header add MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."
-</PRE>
-results in this header being added to the response:
-<PRE>
+</pre>
+ results in this header being added to the response:
+<pre>
MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.
-</PRE>
-
-<LI>Conditionally send MyHeader on the response if and only if header
-"MyRequestHeader" is present on the request. This is useful for
-constructing headers in response to some client stimulus. Note that
-this example requires the services of the mod_setenvif module.</LI>
-<PRE>
- SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<BR>
+</pre>
+ </li>
+
+ <li>Conditionally send MyHeader on the response if and only
+ if header "MyRequestHeader" is present on the request. This
+ is useful for constructing headers in response to some client
+ stimulus. Note that this example requires the services of the
+ mod_setenvif module.</li>
+
+ <li style="list-style: none">
+<pre>
+ SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<br />
Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
-</PRE>
-If the header "MyRequestHeader: value" is present on the HTTP request, the response
-will contain the following header:
-<PRE>
+</pre>
+ If the header "MyRequestHeader: value" is present on the
+ HTTP request, the response will contain the following
+ header:
+<pre>
MyHeader: D=3775428 t=991424704447256 mytext
-</PRE>
-</OL>
-
-<HR>
-
-<H2><A NAME="requestheader">RequestHeader</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> RequestHeader set|append|add
- <EM>header</EM> <EM>value</EM><BR>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> RequestHeader 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#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_header<P>
-
-<p>This directive can replace, merge or remove HTTP request
-headers. The header is modified just before the content handler is
-run, allowing incoming headers to be modified. The action it performs
-is determined by the first argument. This can be one of the following
-values:</p>
-
-<UL>
-<LI><STRONG>set</STRONG><BR>
- The request header is set, replacing any previous header with this name
-
-<LI><STRONG>append</STRONG><BR>
- The request 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 request 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 request header of this name is removed, if it exists. If there are
- multiple headers of the same name, all will be removed.
-</UL>
-
-<p>This argument is followed by a header name, which can include the
-final colon, but it is not required. Case is ignored. For
-<code>add</code>, <code>append</code> and <code>set</code> 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.</p>
-
-<p>The <code>RequestHeader</code> directive is processed just before
-the request is run by its handler in the fixup phase. This should
-allow headers generated by the browser, or by Apache input filters to
-be overridden or modified.</p>
-
-<HR>
-
-<H2><A NAME="header">Header</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> Header set|append|add
- <EM>header</EM> <EM>value</EM> <EM>[env=[!]environment-variable]</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#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> Header echo <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#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_header<P>
-
-<p>This directive can replace, merge or remove HTTP response
-headers. The header is modified just after the content handler and
-output filters are run, allowing outgoing headers to be modified. The
-action it performs is determined by the first argument. This can be
-one of the following values:</p>
-
-<UL>
-<LI><STRONG>set</STRONG><BR>
- The response header is set, replacing any previous header with this name.
- The <EM>value</EM> may be a format string.
-
-<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.
-
-<LI><STRONG>echo</STRONG><BR>
- Request headers with this name are echoed back in the response headers.
- <EM>header</EM> may be a regular expression.
-</UL>
-
-<p>This argument is followed by a <EM>header</EM> name, which can include the
-final colon, but it is not required. Case is ignored for set, append, add
-and unset. The <EM>header</EM> name for echo is case sensitive and may be a
-regular expression.</p>
-
-<P>For <code>add</code>, <code>append</code> and <code>set</code> a
-<EM>value</EM> is specified as the third argument. If <EM>value</EM>
-contains spaces, it should be surrounded by doublequotes.
-<EM>value</EM> may be a character string, a string containing format
-specifiers or a combination of both. The following format specifiers
-are supported in <EM>value</EM>:
-<PRE>
-%t: The time the request was received in Universal Coordinated Time
- since the epoch (Jan. 1, 1970) measured in microseconds. The
- value is preceded by "t=".
+</pre>
+ </li>
+ </ol>
+ <hr />
+
+ <h2><a id="requestheader"
+ name="requestheader">RequestHeader</a> directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> RequestHeader
+ set|append|add <em>header</em> <em>value</em><br />
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> RequestHeader 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#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_header
+
+ <p>This directive can replace, merge or remove HTTP request
+ headers. The header is modified just before the content handler
+ is run, allowing incoming headers to be modified. The action it
+ performs is determined by the first argument. This can be one
+ of the following values:</p>
+
+ <ul>
+ <li><strong>set</strong><br />
+ The request header is set, replacing any previous header
+ with this name</li>
+
+ <li><strong>append</strong><br />
+ The request 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>
+
+ <li><strong>add</strong><br />
+ The request 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>
+
+ <li><strong>unset</strong><br />
+ The request header of this name is removed, if it exists. If
+ there are multiple headers of the same name, all will be
+ removed.</li>
+ </ul>
+
+ <p>This argument is followed by a header name, which can
+ include the final colon, but it is not required. Case is
+ ignored. For <code>add</code>, <code>append</code> and
+ <code>set</code> 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.</p>
+
+ <p>The <code>RequestHeader</code> directive is processed just
+ before the request is run by its handler in the fixup phase.
+ This should allow headers generated by the browser, or by
+ Apache input filters to be overridden or modified.</p>
+ <hr />
+
+ <h2><a id="header" name="header">Header</a> directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> Header set|append|add
+ <em>header</em> <em>value</em>
+ <em>[env=[!]environment-variable]</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#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> Header echo
+ <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#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_header
+
+ <p>This directive can replace, merge or remove HTTP response
+ headers. The header is modified just after the content handler
+ and output filters are run, allowing outgoing headers to be
+ modified. The action it performs is determined by the first
+ argument. This can be one of the following values:</p>
+
+ <ul>
+ <li><strong>set</strong><br />
+ The response header is set, replacing any previous header
+ with this name. The <em>value</em> may be a format
+ string.</li>
+
+ <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>
+
+ <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>
+
+ <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.</li>
+
+ <li><strong>echo</strong><br />
+ Request headers with this name are echoed back in the
+ response headers. <em>header</em> may be a regular
+ expression.</li>
+ </ul>
+
+ <p>This argument is followed by a <em>header</em> name, which
+ can include the final colon, but it is not required. Case is
+ ignored for set, append, add and unset. The <em>header</em>
+ name for echo is case sensitive and may be a regular
+ expression.</p>
+
+ <p>For <code>add</code>, <code>append</code> and
+ <code>set</code> a <em>value</em> is specified as the third
+ argument. If <em>value</em> contains spaces, it should be
+ surrounded by doublequotes. <em>value</em> may be a character
+ string, a string containing format specifiers or a combination
+ of both. The following format specifiers are supported in
+ <em>value</em>:</p>
+<pre>
+%t: The time the request was received in Universal Coordinated Time
+ since the epoch (Jan. 1, 1970) measured in microseconds. The
+ value is preceded by "t=".
%D: The time from when the request was received to the time the
headers are sent on the wire. This is a measure of the
- duration of the request. The value is preceded by "D=".
-</PRE>
-
-<p>When the <code>Header</code> directive is used with the
-<code>add</code>, <code>append</code>, or <code>set</code> argument, a
-fourth argument may be used to specify conditions under which the
-action will be taken. If the <a href="../env.html">environment
-variable</a> specified in the <code>env=...</code> argument exists (or
-if the environment variable does not exist and <code>env=!...</code>
-is specified) then the action specified by the <code>Header</code>
-directive will take effect. Otherwise, the directive will have no
-effect on the request.</p>
-
-<p>The Header directives are processed just before the response is
-sent to the network. These means that it is possible to set and/or
-override most headers, except for those headers added by the header
-filter.</p>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+ duration of the request. The value is preceded by "D=".
+</pre>
+
+ <p>When the <code>Header</code> directive is used with the
+ <code>add</code>, <code>append</code>, or <code>set</code>
+ argument, a fourth argument may be used to specify conditions
+ under which the action will be taken. If the <a
+ href="../env.html">environment variable</a> specified in the
+ <code>env=...</code> argument exists (or if the environment
+ variable does not exist and <code>env=!...</code> is specified)
+ then the action specified by the <code>Header</code> directive
+ will take effect. Otherwise, the directive will have no effect
+ on the request.</p>
+
+ <p>The Header directives are processed just before the response
+ is sent to the network. These means that it is possible to set
+ and/or override most headers, except for those headers added by
+ the header filter.</p>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!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>
-
-<p>This module provides for server-side imagemap processing.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_imap.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> imap_module
-<BR>
-<A
-HREF="module-dict.html#compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.1 and later.
-</P>
-
-
-
-<H2>Summary</H2>
-
-<p>This module processes <CODE>.map</CODE> files, thereby 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.</p>
-
-<p>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>Directives</H2>
-<UL>
-<LI><A HREF="#imapmenu">ImapMenu</A>
-<LI><A HREF="#imapdefault">ImapDefault</A>
-<LI><A HREF="#imapbase">ImapBase</A>
-</UL>
-
-<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>
-
-
-<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>
-
-<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>
-
-
-<hr>
-
-<H2><A NAME="imapmenu">ImapMenu</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> ImapMenu
- none|formatted|semiformatted|unformatted<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<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>
-
-<hr>
-
-<H2><A NAME="imapdefault">ImapDefault</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> ImapDefault
- error|nocontent|map|referer|<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#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_imap<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. Its 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.
-
-<hr>
-
-<H2><A NAME="imapbase">ImapBase</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> ImapBase map|referer|<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#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_imap<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. Its 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>.
-
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module provides for server-side imagemap
+ processing.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_imap.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ imap_module<br />
+ <a href="module-dict.html#compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.1 and later.</p>
+
+ <h2>Summary</h2>
+
+ <p>This module processes <code>.map</code> files, thereby
+ 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.</p>
+
+ <p>The following directive will activate files ending with
+ <code>.map</code> as imagemap files:</p>
+
+ <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>Directives</h2>
+
+ <ul>
+ <li><a href="#imapmenu">ImapMenu</a></li>
+
+ <li><a href="#imapdefault">ImapDefault</a></li>
+
+ <li><a href="#imapbase">ImapBase</a></li>
+ </ul>
+
+ <h2>New Features</h2>
+ The imagemap module adds some new features that were not
+ possible with previously distributed imagemap programs.
+
+ <ul>
+ <li>URL references relative to the Referer: information.</li>
+
+ <li>Default <BASE> assignment through a new map
+ directive <code>base</code>.</li>
+
+ <li>No need for <code>imagemap.conf</code> file.</li>
+
+ <li>Point references.</li>
+
+ <li>Configurable generation of imagemap menus.</li>
+ </ul>
+ <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</dt>
+
+ <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.</dd>
+
+ <dt><code>default</code> Directive</dt>
+
+ <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.</dd>
+
+ <dt><code>poly</code> Directive</dt>
+
+ <dd>Takes three to one-hundred points, and is obeyed if the
+ user selected coordinates fall within the polygon defined by
+ these points.</dd>
+
+ <dt><code>circle</code></dt>
+
+ <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.</dd>
+
+ <dt><code>rect</code> Directive</dt>
+
+ <dd>Takes the coordinates of two opposing corners of a
+ rectangle. Obeyed if the point selected is within this
+ rectangle.</dd>
+
+ <dt><code>point</code> Directive</dt>
+
+ <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.</dd>
+ </dl>
+
+ <h3>Values</h3>
+ The values for each of the directives can any of the following:
+
+
+ <dl>
+ <dt>a URL</dt>
+
+ <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.</dd>
+
+ <dt><code>map</code></dt>
+
+ <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'.</dd>
+
+ <dt><code>menu</code></dt>
+
+ <dd>Synonymous with <code>map</code>.</dd>
+
+ <dt><code>referer</code></dt>
+
+ <dd>Equivalent to the URL of the referring document. Defaults
+ to <code>http://servername/</code> if no Referer: header was
+ present.</dd>
+
+ <dt><code>nocontent</code></dt>
+
+ <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>.</dd>
+
+ <dt><code>error</code></dt>
+
+ <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>.</dd>
+ </dl>
+
+ <h3>Coordinates</h3>
+
+ <dl>
+ <dt><code>0,0 200,200</code></dt>
+
+ <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.</dd>
+ </dl>
+
+ <h3>Quoted Text</h3>
+
+ <dl>
+ <dt><code>"Menu Text"</code></dt>
+
+ <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.</dd>
+ </dl>
+
+ <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>
+
+ <h2>Referencing your mapfile</h2>
+
+ <blockquote>
+ <code><A HREF="/maps/imagemap1.map"><br />
+ <IMG ISMAP SRC="/images/imagemap1.gif"><br />
+ </A></code>
+ </blockquote>
+ <hr />
+
+ <h2><a id="imapmenu" name="imapmenu">ImapMenu</a>
+ directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ImapMenu
+ none|formatted|semiformatted|unformatted<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<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.</p>
+
+ <dl>
+ <dt><code>none</code></dt>
+
+ <dd>If ImapMenu is <code>none</code>, no menu is generated,
+ and the <code>default</code> action is performed.</dd>
+
+ <dt><code>formatted</code></dt>
+
+ <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.</dd>
+
+ <dt><code>semiformatted</code></dt>
+
+ <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.</dd>
+
+ <dt><code>unformatted</code></dt>
+
+ <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.</dd>
+ </dl>
+ <hr />
+
+ <h2><a id="imapdefault" name="imapdefault">ImapDefault</a>
+ directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ImapDefault
+ error|nocontent|map|referer|<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#Module"
+ rel="Help"><strong>Module:</strong></a> mod_imap<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. Its 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>
+ <hr />
+
+ <h2><a id="imapbase" name="imapbase">ImapBase</a>
+ directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ImapBase
+ map|referer|<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#Module"
+ rel="Help"><strong>Module:</strong></a> mod_imap<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. Its 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>.
+ <!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
-<!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>
-
-<p>This module provides for server-parsed html documents.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_include.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> includes_module
-</P>
-
-<h2>Summary</h2>
-
-<p>This module provides a filter which will process files before they
-are sent to the client. The processing is controlled by specially
-formated SGML comments, referred to as <em>elements</em>. These
-elements allow conditional text, the inclusion other files or
-programs, as well as the setting and printing of environment
-variables.</p>
-
-<H2>Directives</H2>
-<UL>
-<LI><A HREF="#xbithack">XBitHack</A>
-</UL>
-
-<p>See also: <a href="core.html#options">Options</a>
-and <a href="core.html.html#SetOutputFilter">SetOutputFilter</a>.</p>
-
-
-<H2>Enabling Server-Side Includes</H2>
-
-<p>Server Side Includes are implemented by the <code>INCLUDES</code>
-<a href="../filter.html">filter</a>. 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>:
-</p>
-
-<blockquote><code>
-AddType text/html .shtml<br>
-<FilesMatch "\.shtml(\..+)?$"><br>
- SetOutputFilter INCLUDES<br>
-</FilesMatch>
-</code></blockquote>
-
-<p>Be careful to properly scope the INCLUDES filter to process only
-the correct files. The filter is <strong>not</strong> restricted to
-processing only HTML files. So, for example, if the INCLUDES filter
-is activated using a <code><Directory></code> section and that
-directory includes GIF files, mod_include will process the GIF files.
-This can have two adverse consequences: 1. there will be extra
-overhead in serving these files, and 2. these files could become
-corrupted if they happen to contain something that looks like an SSI
-element.</p>
-
-<p>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):</p>
-
-<blockquote><code>
-Options +Includes
-</code></blockquote>
-
-<p>For backwards compatibility, the <code>server-parsed</code> <a
-href="../handler.html">handler</a> also activates the INCLUDES filter.
-As well, Apache will activate the INCLUDES filter for any document
-with mime type <code>text/x-server-parsed-html</code> or
-<code>text/x-server-parsed-html3</code> (and the resulting output will
-have the mime type <code>text/html</code>).</p>
-
-<p>For more information, see our <a href="../howto/ssi.html">Tutorial
-on Server Side Includes</a>.</p>
-
-<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><a name="echo">echo</a></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.
-<DT>encoding
-<DD>Specifies how Apache should encode special characters contained
-in the variable before outputting them. If set to "none", no encoding
-will be done. If set to "url", then URL encoding (also known as
-%-encoding; this is appropriate for use within URLs in links, etc.)
-will be performed. At the start of an <CODE>echo</CODE> element,
-the default is set to "entity", resulting in entity encoding (which
-is appropriate in the context of a block-level HTML element, eg.
-a paragraph of text). This can be changed by adding an
-<CODE>encoding</CODE> attribute, which will remain in effect until
-the next <CODE>encoding</CODE> attribute is encountered or the
-element ends, whichever comes first. Note that the
-<CODE>encoding</CODE> attribute must <EM>precede</EM> the corresponding
-<CODE>var</CODE> attribute to be effective, and that only special
-characters as defined in the ISO-8859-1 character encoding will be
-encoded. This encoding process may not have the desired result if
-a different character encoding is in use.
-Apache 1.3.12 and above; previous versions do no encoding.
-
-</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.
- Starting with Apache 1.3.12, special characters are entity encoded (see the
- <A HREF="#echo"><CODE>echo</CODE></A> element for details) before being
- output. 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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module provides for server-parsed html documents.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_include.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ includes_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This module provides a filter which will process files
+ before they are sent to the client. The processing is
+ controlled by specially formated SGML comments, referred to as
+ <em>elements</em>. These elements allow conditional text, the
+ inclusion other files or programs, as well as the setting and
+ printing of environment variables.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#xbithack">XBitHack</a></li>
+ </ul>
+
+ <p>See also: <a href="core.html#options">Options</a> and <a
+ href="core.html.html#SetOutputFilter">SetOutputFilter</a>.</p>
+
+ <h2>Enabling Server-Side Includes</h2>
+
+ <p>Server Side Includes are implemented by the
+ <code>INCLUDES</code> <a href="../filter.html">filter</a>. 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>:</p>
+
+ <blockquote>
+ <code>AddType text/html .shtml<br />
+ <FilesMatch "\.shtml(\..+)?$"><br />
+ SetOutputFilter INCLUDES<br />
+ </FilesMatch></code>
+ </blockquote>
+
+ <p>Be careful to properly scope the INCLUDES filter to process
+ only the correct files. The filter is <strong>not</strong>
+ restricted to processing only HTML files. So, for example, if
+ the INCLUDES filter is activated using a
+ <code><Directory></code> section and that directory
+ includes GIF files, mod_include will process the GIF files.
+ This can have two adverse consequences: 1. there will be extra
+ overhead in serving these files, and 2. these files could
+ become corrupted if they happen to contain something that looks
+ like an SSI element.</p>
+
+ <p>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):</p>
+
+ <blockquote>
+ <code>Options +Includes</code>
+ </blockquote>
+
+ <p>For backwards compatibility, the <code>server-parsed</code>
+ <a href="../handler.html">handler</a> also activates the
+ INCLUDES filter. As well, Apache will activate the INCLUDES
+ filter for any document with mime type
+ <code>text/x-server-parsed-html</code> or
+ <code>text/x-server-parsed-html3</code> (and the resulting
+ output will have the mime type <code>text/html</code>).</p>
+
+ <p>For more information, see our <a
+ href="../howto/ssi.html">Tutorial on Server Side
+ Includes</a>.</p>
+
+ <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></dt>
+
+ <dd>
+ This command controls various aspects of the parsing. The
+ valid attributes are:
+
+ <dl>
+ <dt>errmsg</dt>
+
+ <dd>The value is a message that is sent back to the
+ client if an error occurs whilst parsing the
+ document.</dd>
+
+ <dt>sizefmt</dt>
+
+ <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.</dd>
+
+ <dt>timefmt</dt>
+
+ <dd>The value is a string to be used by the
+ <code>strftime(3)</code> library routine when printing
+ dates.</dd>
+ </dl>
+ </dd>
+
+ <dt><strong><a id="echo" name="echo">echo</a></strong></dt>
+
+ <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</dt>
+
+ <dd>The value is the name of the variable to print.</dd>
+
+ <dt>encoding</dt>
+
+ <dd>Specifies how Apache should encode special characters
+ contained in the variable before outputting them. If set
+ to "none", no encoding will be done. If set to "url",
+ then URL encoding (also known as %-encoding; this is
+ appropriate for use within URLs in links, etc.) will be
+ performed. At the start of an <code>echo</code> element,
+ the default is set to "entity", resulting in entity
+ encoding (which is appropriate in the context of a
+ block-level HTML element, eg. a paragraph of text). This
+ can be changed by adding an <code>encoding</code>
+ attribute, which will remain in effect until the next
+ <code>encoding</code> attribute is encountered or the
+ element ends, whichever comes first. Note that the
+ <code>encoding</code> attribute must <em>precede</em> the
+ corresponding <code>var</code> attribute to be effective,
+ and that only special characters as defined in the
+ ISO-8859-1 character encoding will be encoded. This
+ encoding process may not have the desired result if a
+ different character encoding is in use. Apache 1.3.12 and
+ above; previous versions do no encoding.</dd>
+ </dl>
+ </dd>
+
+ <dt><strong>exec</strong></dt>
+
+ <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</dt>
+
+ <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>
+
+ <p>If the script returns a Location: header instead of
+ output, then this will be translated into an HTML
+ anchor.</p>
+
+ <p>The <code>include virtual</code> element should be
+ used in preference to <code>exec cgi</code>.</p>
+ </dd>
+
+ <dt>cmd</dt>
+
+ <dd>The server will execute the given string using
+ <code>/bin/sh</code>. The include variables are available
+ to the command.</dd>
+ </dl>
+ </dd>
+
+ <dt><strong>fsize</strong></dt>
+
+ <dd>
+ This command prints the size of the specified file, subject
+ to the <code>sizefmt</code> format specification.
+ Attributes:
+
+ <dl>
+ <dt>file</dt>
+
+ <dd>The value is a path relative to the directory
+ containing the current document being parsed.</dd>
+
+ <dt>virtual</dt>
+
+ <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.</dd>
+ </dl>
+ </dd>
+
+ <dt><strong>flastmod</strong></dt>
+
+ <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.</dd>
+
+ <dt><strong>include</strong></dt>
+
+ <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:</p>
+
+ <dl>
+ <dt>file</dt>
+
+ <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.</dd>
+
+ <dt>virtual</dt>
+
+ <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.</dd>
+ </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.
+ </dd>
+
+ <dt><strong>printenv</strong></dt>
+
+ <dd>This prints out a listing of all existing variables and
+ their values. Starting with Apache 1.3.12, special characters
+ are entity encoded (see the <a
+ href="#echo"><code>echo</code></a> element for details)
+ before being output. No attributes.</dd>
+
+ <dd>For example: <code><!--#printenv --></code></dd>
+
+ <dd>Apache 1.2 and above.</dd>
+
+ <dt><strong>set</strong></dt>
+
+ <dd>
+ This sets the value of a variable. Attributes:
+
+ <dl>
+ <dt>var</dt>
+
+ <dd>The name of the variable to set.</dd>
+
+ <dt>value</dt>
+
+ <dd>The value to give a variable.</dd>
+ </dl>
+ For example: <code><!--#set var="category" value="help"
+ --></code>
+ </dd>
+
+ <dd>Apache 1.2 and above.</dd>
+ </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</dt>
-<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:
+ <dd>The current date in Greenwich Mean Time.</dd>
-<PRE>
+ <dt>DATE_LOCAL</dt>
+
+ <dd>The current date in the local time zone.</dd>
+
+ <dt>DOCUMENT_NAME</dt>
+
+ <dd>The filename (excluding directories) of the document
+ requested by the user.</dd>
+
+ <dt>DOCUMENT_URI</dt>
+
+ <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.</dd>
+
+ <dt>LAST_MODIFIED</dt>
+
+ <dd>The last modification date of the document requested by
+ the user.</dd>
+ </dl>
+
+ <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:</p>
+<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:</p>
+<pre>
<!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->
-</PRE>
+</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>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>
-<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>
+ <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:</p>
+<pre>
<!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" -->
in foo
<!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" -->
<!--#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>" -->
+</pre>
+
+ <h2><a id="flowctrl" 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>
-
-<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>
-
-<HR>
-
-<H2><A NAME="xbithack">XBitHack</A> directive</H2>
-<!--%plaintext <?INDEX {\tt XBitHack} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> XBitHack on|off|full<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>. XBitHack can take on 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>
-
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</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>
+
+ <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>
+
+ <p>The <strong><code>endif</code></strong> element ends the
+ <strong><code>if</code></strong> element and is required.</p>
+
+ <p><em>test_condition</em> is one of the following:</p>
+
+ <dl>
+ <dt><em>string</em></dt>
+
+ <dd>true if <em>string</em> is not empty</dd>
+
+ <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></dt>
+
+ <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.</dd>
+
+ <dt>( <em>test_condition</em> )</dt>
+
+ <dd>true if <em>test_condition</em> is true</dd>
+
+ <dt>! <em>test_condition</em></dt>
+
+ <dd>true if <em>test_condition</em> is false</dd>
+
+ <dt><em>test_condition1</em> &&
+ <em>test_condition2</em></dt>
+
+ <dd>true if both <em>test_condition1</em> and
+ <em>test_condition2</em> are true</dd>
+
+ <dt><em>test_condition1</em> || <em>test_condition2</em></dt>
+
+ <dd>true if either <em>test_condition1</em> or
+ <em>test_condition2</em> is true</dd>
+ </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:</p>
+<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,</p>
+<pre>
+ <em>string1 string2</em> results in <em>string1 string2</em>
+ <em>'string1 string2'</em> results in <em>string1 string2</em>
+</pre>
+
+ <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.
+ <hr />
+
+ <h2><a id="xbithack" name="xbithack">XBitHack</a>
+ directive</h2>
+ <!--%plaintext <?INDEX {\tt XBitHack} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> XBitHack
+ on|off|full<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>. XBitHack can take on
+ the following values:</p>
+
+ <dl>
+ <dt>off</dt>
+
+ <dd>No special treatment of executable files.</dd>
+
+ <dt>on</dt>
+
+ <dd>Any file that has the user-execute bit set will be
+ treated as a server-parsed html document.</dd>
+
+ <dt>full</dt>
+
+ <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).</p>
+ </dd>
+ </dl>
+
+ <p><!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
+
-<!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>
-
-<p>This module provides a comprehensive overview of the server
-configuration including all installed modules and directives in the
-configuration files.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_info.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> info_module
-<BR>
-<A
-HREF="module-dict.html#compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.1 and later.
-</P>
-
-<H2>Directives</H2>
-<UL>
-<LI><A HREF="#addmoduleinfo">AddModuleInfo</A>
-</UL>
-
-<h2>Using mod_info</h2>
-
-<P>
-To configure it, add the following to your <CODE>httpd.conf</CODE> file.
-
-<PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>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>
+
+ <p>This module provides a comprehensive overview of the server
+ configuration including all installed modules and directives in
+ the configuration files.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_info.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ info_module<br />
+ <a href="module-dict.html#compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.1 and later.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#addmoduleinfo">AddModuleInfo</a></li>
+ </ul>
+
+ <h2>Using mod_info</h2>
+
+ <p>To configure it, add the following to your
+ <code>httpd.conf</code> file.</p>
+<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> Extension<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_info<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>
+</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.</strong>
+
+ <p><strong>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.</strong></p>
+ </blockquote>
+ <hr />
+
+ <h2><a id="addmoduleinfo"
+ 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> Extension<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_info<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:</p>
+
+ <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>
+</pre>
+ </blockquote>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
-<!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 supports ISAPI Extensions within Apache for Windows.</P>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_isapi.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> isapi_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> WIN32 only
-</P>
-
-<H2>Summary</H2>
-
-<P>This module implements the Internet Server extension API. It allows
- Internet Server extensions (<EM>e.g.</EM> ISAPI .dll modules) to be
- served by Apache for Windows, subject to the noted restrictions.</P>
-
-<P>ISAPI extension modules (.dll files) are written by third parties. The
- Apache Group does not author these modules, so we provide no support for
- them. Please contact the ISAPI's author directly if you are experiencing
- problems running their ISAPI extention. <STRONG>Please <EM>do not</EM>
- post such problems to Apache's lists or bug reporting pages.</STRONG></P>
-
-<H2>Directives</H2>
-<UL>
-<LI><A HREF="#isapifilecache">ISAPIFileCache</A>
-<LI><A HREF="#isapireadaheadbuffer">ISAPIReadAheadBuffer</A>
-<LI><A HREF="#isapilognotsupported">ISAPILogNotSupported</A>
-<LI><A HREF="#isapiappendlogtoerrors">ISAPIAppendLogToErrors</A>
-<LI><A HREF="#isapiappendlogtoquery">ISAPIAppendLogToQuery</A>
-</UL>
-
-<H2>Usage</H2>
-
-<P>In the server configuration file, use the AddHandler directive to
- associate ISAPI files with the <CODE>isapi-isa</CODE> handler, and map
- it to the with their file extensions. To enable any .dll file to be
- processed as an ISAPI extention, edit the httpd.conf file and add the
- following line:</P>
-
-<PRE>
- AddHandler isapi-isa .dll
-</PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>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 supports ISAPI Extensions within Apache for
+ Windows.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_isapi.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ isapi_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> WIN32 only</p>
+
+ <h2>Summary</h2>
+
+ <p>This module implements the Internet Server extension API. It
+ allows Internet Server extensions (<em>e.g.</em> ISAPI .dll
+ modules) to be served by Apache for Windows, subject to the
+ noted restrictions.</p>
+
+ <p>ISAPI extension modules (.dll files) are written by third
+ parties. The Apache Group does not author these modules, so we
+ provide no support for them. Please contact the ISAPI's author
+ directly if you are experiencing problems running their ISAPI
+ extention. <strong>Please <em>do not</em> post such problems to
+ Apache's lists or bug reporting pages.</strong></p>
+
+ <h2>Directives</h2>
-<P>There is no capability within the Apache server to leave a requested
- module loaded. However, you may preload and keep a specific module loaded
- by using the following syntax in your httpd.conf:
+ <ul>
+ <li><a href="#isapifilecache">ISAPIFileCache</a></li>
-<PRE>
+ <li><a
+ href="#isapireadaheadbuffer">ISAPIReadAheadBuffer</a></li>
+
+ <li><a
+ href="#isapilognotsupported">ISAPILogNotSupported</a></li>
+
+ <li><a
+ href="#isapiappendlogtoerrors">ISAPIAppendLogToErrors</a></li>
+
+ <li><a
+ href="#isapiappendlogtoquery">ISAPIAppendLogToQuery</a></li>
+ </ul>
+
+ <h2>Usage</h2>
+
+ <p>In the server configuration file, use the AddHandler
+ directive to associate ISAPI files with the
+ <code>isapi-isa</code> handler, and map it to the with their
+ file extensions. To enable any .dll file to be processed as an
+ ISAPI extention, edit the httpd.conf file and add the following
+ line:</p>
+<pre>
+ AddHandler isapi-isa .dll
+</pre>
+
+ <p>There is no capability within the Apache server to leave a
+ requested module loaded. However, you may preload and keep a
+ specific module loaded by using the following syntax in your
+ httpd.conf:</p>
+<pre>
ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll
-</PRE>
-
-<P>Whether or not you have preloaded an ISAPI extension, all ISAPI
- extensions are governed by the same permissions and restrictions
- as CGI scripts. That is, <CODE>Options ExecCGI</CODE> must be set for
- the directory that contains the ISAPI .dll file.</P>
-
-<P>Review the <A HREF="#notes">Additional Notes</A> and the
- <A HREF="#journal">Programmer's Journal</A> for additional details and
- clarification of the specific ISAPI support offered by mod_isapi.</P>
-
-<H2><A NAME="notes">Additional Notes</A></H2>
-
-<P>Apache's ISAPI implementation conforms to all of the ISAPI 2.0
- specification, except for some "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 unsupported features, including async I/O, a message is
- placed in the error log to help with debugging. Since these messages
- can become a flood, the directive <CODE>ISAPILogNotSupported Off</CODE>
- exists to quiet this noise.</P>
-
-<P>Some servers, like Microsoft IIS, load the ISAPI extension into the server
- and keep it loaded until memory usage is too high, or unless configuration
- options are specified. Apache currently loads and unloads the ISAPI
- extension each time it is requested, unless the ISAPICacheFile directive
- is specified. This is inefficient, but Apache's memory model makes this
- the most effective method. Many ISAPI modules are subtly incompatible
- with the Apache server, and unloading these modules helps to ensure the
- stability of the server.</P>
-
-<P>Also, remember that while Apache supports ISAPI Extensions, it
- <STRONG>does not support ISAPI Filters.</STRONG> Support for filters may
- be added at a later date, but no support is planned at this time.</P>
-
-<H2><A NAME="journal">Programmer's Journal</A></H2>
-
-<P>If you are programming Apache 2.0 mod_isapi modules, you must limit your
- calls to ServerSupportFunction to the following directives:</P>
-
-<DL>
- <DT>HSE_REQ_SEND_URL_REDIRECT_RESP
- <DD>Redirect the user to another location.<BR>
- This must be a fully qualified URL (e.g. http://server/location).
- <DT>HSE_REQ_SEND_URL
- <DD>Redirect the user to another location.<BR>
- This cannot be a fully qualified URL, you are not allowed
- to pass the protocol or a server name (e.g. simply /location).<BR>
- This redirection is handled by the server, not the browser.<BR>
- <STRONG>Warning:</STRONG> in their recent documentation, Microsoft
- appears to have abandoned the distinction between the two
- HSE_REQ_SEND_URL functions. Apache continues to treat them as two
- distinct functions with different requirements and behaviors.
- <DT>HSE_REQ_SEND_RESPONSE_HEADER
- <DD>Apache accepts a response body following the header if it follows
- the blank line (two consecutive newlines) in the headers string
- argument. This body cannot contain NULLs, since the headers
- argument is NULL terminated.
- <DT>HSE_REQ_DONE_WITH_SESSION
- <DD>Apache considers this a no-op, since the session will be finished
- when the ISAPI returns from processing.
- <DT>HSE_REQ_MAP_URL_TO_PATH
- <DD>Apache will translate a virtual name to a physical name.
- <DT>HSE_APPEND_LOG_PARAMETER
- <DD>This logged message may be captured in any of the following logs:
- <UL>
- <LI>in the \"%{isapi-parameter}n\" component in a CustomLog directive
- <LI>in the %q log component with the ISAPIAppendLogToQuery On directive
- <LI>in the error log with the ISAPIAppendLogToErrors On directive
- </UL>
- The first option, the %{isapi-parameter}n component, is always available
- and prefered.
- <DT>HSE_REQ_IS_KEEP_CONN
- <DD>Will return the negotiated Keep-Alive status.
- <DT>HSE_REQ_SEND_RESPONSE_HEADER_EX
- <DD>Will behave as documented, although the fKeepConn flag is ignored.
- <DT>HSE_REQ_IS_CONNECTED
- <DD>Will report false if the request has been aborted.
-</DL>
-
-<P>Apache returns FALSE to any unsupported call to ServerSupportFunction, and
- sets the GetLastError value to ERROR_INVALID_PARAMETER.</P>
-
-<P>ReadClient retrieves the request body exceeding the initial buffer
- (defined by ISAPIReadAheadBuffer). Based on the ISAPIReadAheadBuffer
- setting (number of bytes to buffer prior to calling the ISAPI handler)
- shorter requests are sent complete to the extension when it is invoked.
- If the request is longer, the ISAPI extension must use ReadClient to
- retrieve the remaining request body.</P>
-
-<P>WriteClient is supported, but only with the HSE_IO_SYNC flag or
- no option flag (value of 0). Any other WriteClient request will
- be rejected with a return value of FALSE, and a GetLastError
- value of ERROR_INVALID_PARAMETER.</P>
-
-<P>GetServerVariable is supported, although extended server variables do not
- exist (as defined by other servers.) All the usual Apache CGI environment
- variables are available from GetServerVariable, as well as the ALL_HTTP
- and ALL_RAW values.</P>
-
-<P>Apache 2.0 mod_isapi supports additional features introduced in later
- versions of the ISAPI specification, as well as limited emulation of
- async I/O and the TransmitFile semantics. Apache also supports preloading
- ISAPI .dlls for performance, neither of which were not available under
- Apache 1.3 mod_isapi.</P>
-
-<HR>
-
-<H2><A NAME="isapifilecache">ISAPIFileCache directive</A></H2>
-<!--%plaintext <?INDEX {\tt ISAPIFileCache} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> ISAPIFileCache <EM>file</em> [<em>file</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> None<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_isapi<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Apache 2.0 and later, Win32 only<P>
-
- Specifies a space-separated list of file names to be loaded
- when the Apache server is launched, and remain loaded until
- the server is shut down. This directive may be repeated
- for every ISAPI .dll file desired. The full path name of
- each file should be specified.
- <P>
-<HR>
-
-<H2><A NAME="isapireadaheadbuffer">ISAPIReadAheadBuffer directive</A></H2>
-<!--%plaintext <?INDEX {\tt ISAPIReadAheadBuffer} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> ISAPIReadAheadBuffer <EM>size</EM><BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> 49152<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> None<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_isapi<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
-
-
- Defines the maximum size of the Read Ahead Buffer sent to
- ISAPI extensions when they are initially invoked. All
- remaining data must be retrieved using the ReadClient
- callback; some ISAPI extensions may not support the
- ReadClient function. Refer questions to the ISAPI extension's
- author.
- <P>
-<HR>
-
-<H2><A NAME="isapilognotsupported">ISAPILogNotSupported directive</A></H2>
-<!--%plaintext <?INDEX {\tt ISAPILogNotSupported} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> ISAPILogNotSupported on|off<BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> on<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> None<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_isapi<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
-
- Logs all requests for unsupported features from ISAPI extensions
- in the server error log. While this should be turned off once
- all desired ISAPI modules are functioning, it defaults to on
- to help administrators track down problems.
- <P>
-<HR>
-
-<H2><A NAME="isapiappendlogtoerrors">ISAPIAppendLogToErrors directive</A></H2>
-<!--%plaintext <?INDEX {\tt ISAPIAppendLogToErrors} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> ISAPIAppendLogToErrors on|off<BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> off<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> None<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_isapi<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
-
- Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions
- to the server error log.
- <P>
-<HR>
-
-<H2><A NAME="isapiappendlogtoquery">ISAPIAppendLogToQuery directive</A></H2>
-<!--%plaintext <?INDEX {\tt ISAPIAppendLogToQuery} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> ISAPIAppendLogToQuery on|off<BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> off<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> None<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_isapi<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
-
- Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions
- to the query field (appended to the CustomLog %q component).
- <P>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</pre>
+
+ <p>Whether or not you have preloaded an ISAPI extension, all
+ ISAPI extensions are governed by the same permissions and
+ restrictions as CGI scripts. That is, <code>Options
+ ExecCGI</code> must be set for the directory that contains the
+ ISAPI .dll file.</p>
+
+ <p>Review the <a href="#notes">Additional Notes</a> and the <a
+ href="#journal">Programmer's Journal</a> for additional details
+ and clarification of the specific ISAPI support offered by
+ mod_isapi.</p>
+
+ <h2><a id="notes" name="notes">Additional Notes</a></h2>
+
+ <p>Apache's ISAPI implementation conforms to all of the ISAPI
+ 2.0 specification, except for some "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
+ unsupported features, including async I/O, a message is placed
+ in the error log to help with debugging. Since these messages
+ can become a flood, the directive <code>ISAPILogNotSupported
+ Off</code> exists to quiet this noise.</p>
+
+ <p>Some servers, like Microsoft IIS, load the ISAPI extension
+ into the server and keep it loaded until memory usage is too
+ high, or unless configuration options are specified. Apache
+ currently loads and unloads the ISAPI extension each time it is
+ requested, unless the ISAPICacheFile directive is specified.
+ This is inefficient, but Apache's memory model makes this the
+ most effective method. Many ISAPI modules are subtly
+ incompatible with the Apache server, and unloading these
+ modules helps to ensure the stability of the server.</p>
+
+ <p>Also, remember that while Apache supports ISAPI Extensions,
+ it <strong>does not support ISAPI Filters.</strong> Support for
+ filters may be added at a later date, but no support is planned
+ at this time.</p>
+
+ <h2><a id="journal" name="journal">Programmer's
+ Journal</a></h2>
+
+ <p>If you are programming Apache 2.0 mod_isapi modules, you
+ must limit your calls to ServerSupportFunction to the following
+ directives:</p>
+
+ <dl>
+ <dt>HSE_REQ_SEND_URL_REDIRECT_RESP</dt>
+
+ <dd>Redirect the user to another location.<br />
+ This must be a fully qualified URL (e.g.
+ http://server/location).</dd>
+
+ <dt>HSE_REQ_SEND_URL</dt>
+
+ <dd>Redirect the user to another location.<br />
+ This cannot be a fully qualified URL, you are not allowed to
+ pass the protocol or a server name (e.g. simply
+ /location).<br />
+ This redirection is handled by the server, not the
+ browser.<br />
+ <strong>Warning:</strong> in their recent documentation,
+ Microsoft appears to have abandoned the distinction between
+ the two HSE_REQ_SEND_URL functions. Apache continues to treat
+ them as two distinct functions with different requirements
+ and behaviors.</dd>
+
+ <dt>HSE_REQ_SEND_RESPONSE_HEADER</dt>
+
+ <dd>Apache accepts a response body following the header if it
+ follows the blank line (two consecutive newlines) in the
+ headers string argument. This body cannot contain NULLs,
+ since the headers argument is NULL terminated.</dd>
+
+ <dt>HSE_REQ_DONE_WITH_SESSION</dt>
+
+ <dd>Apache considers this a no-op, since the session will be
+ finished when the ISAPI returns from processing.</dd>
+
+ <dt>HSE_REQ_MAP_URL_TO_PATH</dt>
+
+ <dd>Apache will translate a virtual name to a physical
+ name.</dd>
+
+ <dt>HSE_APPEND_LOG_PARAMETER</dt>
+
+ <dd>
+ This logged message may be captured in any of the following
+ logs:
+
+ <ul>
+ <li>in the \"%{isapi-parameter}n\" component in a
+ CustomLog directive</li>
+
+ <li>in the %q log component with the
+ ISAPIAppendLogToQuery On directive</li>
+
+ <li>in the error log with the ISAPIAppendLogToErrors On
+ directive</li>
+ </ul>
+ The first option, the %{isapi-parameter}n component, is
+ always available and prefered.
+ </dd>
+
+ <dt>HSE_REQ_IS_KEEP_CONN</dt>
+
+ <dd>Will return the negotiated Keep-Alive status.</dd>
+
+ <dt>HSE_REQ_SEND_RESPONSE_HEADER_EX</dt>
+
+ <dd>Will behave as documented, although the fKeepConn flag is
+ ignored.</dd>
+
+ <dt>HSE_REQ_IS_CONNECTED</dt>
+
+ <dd>Will report false if the request has been aborted.</dd>
+ </dl>
+
+ <p>Apache returns FALSE to any unsupported call to
+ ServerSupportFunction, and sets the GetLastError value to
+ ERROR_INVALID_PARAMETER.</p>
+
+ <p>ReadClient retrieves the request body exceeding the initial
+ buffer (defined by ISAPIReadAheadBuffer). Based on the
+ ISAPIReadAheadBuffer setting (number of bytes to buffer prior
+ to calling the ISAPI handler) shorter requests are sent
+ complete to the extension when it is invoked. If the request is
+ longer, the ISAPI extension must use ReadClient to retrieve the
+ remaining request body.</p>
+
+ <p>WriteClient is supported, but only with the HSE_IO_SYNC flag
+ or no option flag (value of 0). Any other WriteClient request
+ will be rejected with a return value of FALSE, and a
+ GetLastError value of ERROR_INVALID_PARAMETER.</p>
+
+ <p>GetServerVariable is supported, although extended server
+ variables do not exist (as defined by other servers.) All the
+ usual Apache CGI environment variables are available from
+ GetServerVariable, as well as the ALL_HTTP and ALL_RAW
+ values.</p>
+
+ <p>Apache 2.0 mod_isapi supports additional features introduced
+ in later versions of the ISAPI specification, as well as
+ limited emulation of async I/O and the TransmitFile semantics.
+ Apache also supports preloading ISAPI .dlls for performance,
+ neither of which were not available under Apache 1.3
+ mod_isapi.</p>
+ <hr />
+
+ <h2><a id="isapifilecache" name="isapifilecache">ISAPIFileCache
+ directive</a></h2>
+ <!--%plaintext <?INDEX {\tt ISAPIFileCache} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ISAPIFileCache
+ <em>file</em> [<em>file</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> None<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_isapi<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Apache 2.0 and
+ later, Win32 only
+
+ <p>Specifies a space-separated list of file names to be loaded
+ when the Apache server is launched, and remain loaded until the
+ server is shut down. This directive may be repeated for every
+ ISAPI .dll file desired. The full path name of each file should
+ be specified.</p>
+ <hr />
+
+ <h2><a id="isapireadaheadbuffer"
+ name="isapireadaheadbuffer">ISAPIReadAheadBuffer
+ directive</a></h2>
+ <!--%plaintext <?INDEX {\tt ISAPIReadAheadBuffer} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ISAPIReadAheadBuffer
+ <em>size</em><br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> 49152<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> None<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_isapi<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Apache 1.3.13
+ and later, Win32 only
+
+ <p>Defines the maximum size of the Read Ahead Buffer sent to
+ ISAPI extensions when they are initially invoked. All remaining
+ data must be retrieved using the ReadClient callback; some
+ ISAPI extensions may not support the ReadClient function. Refer
+ questions to the ISAPI extension's author.</p>
+ <hr />
+
+ <h2><a id="isapilognotsupported"
+ name="isapilognotsupported">ISAPILogNotSupported
+ directive</a></h2>
+ <!--%plaintext <?INDEX {\tt ISAPILogNotSupported} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ISAPILogNotSupported
+ on|off<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> on<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> None<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_isapi<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Apache 1.3.13
+ and later, Win32 only
+
+ <p>Logs all requests for unsupported features from ISAPI
+ extensions in the server error log. While this should be turned
+ off once all desired ISAPI modules are functioning, it defaults
+ to on to help administrators track down problems.</p>
+ <hr />
+
+ <h2><a id="isapiappendlogtoerrors"
+ name="isapiappendlogtoerrors">ISAPIAppendLogToErrors
+ directive</a></h2>
+ <!--%plaintext <?INDEX {\tt ISAPIAppendLogToErrors} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ISAPIAppendLogToErrors
+ on|off<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> off<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> None<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_isapi<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Apache 1.3.13
+ and later, Win32 only
+
+ <p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
+ extensions to the server error log.</p>
+ <hr />
+
+ <h2><a id="isapiappendlogtoquery"
+ name="isapiappendlogtoquery">ISAPIAppendLogToQuery
+ directive</a></h2>
+ <!--%plaintext <?INDEX {\tt ISAPIAppendLogToQuery} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ISAPIAppendLogToQuery
+ on|off<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> off<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> None<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_isapi<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Apache 1.3.13
+ and later, Win32 only
+
+ <p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
+ extensions to the query field (appended to the CustomLog %q
+ component).</p>
+
+ <p><!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
+
-<!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 provides for logging of the requests made to
-the server, using the Common Log Format or a user-specified format.
-</P>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_log_config.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> config_log_module
-</P>
-
-
-<H2>Summary</H2>
-
-<p>This module provides for flexible logging of client requests. Logs
-are written in a customizable format, and may be written directly to a
-file, or to an external program. Conditional logging is provided so
-that individual requests may be included or excluded from the logs
-based on characteristics of the request.</p>
-
-<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 step.
-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>
-
-<p>See also: <a href="../logs.html">Apache Log Files</a>.</p>
-
-<H2>Directives</H2>
-
-<UL>
-<LI><A HREF="#cookielog">CookieLog</A></LI>
-<LI><A HREF="#customlog">CustomLog</A></LI>
-<LI><A HREF="#logformat">LogFormat</A></LI>
-<LI><A HREF="#transferlog">TransferLog</A></LI>
-</UL>
-
-<H2><A NAME="formats">Custom Log Formats</A></H2>
-
-<p>The format argument to the <CODE>LogFormat</CODE> and
-<CODE>CustomLog</CODE> directives 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 the c-type control characters "\n" and
-"\t" to represent new-lines and tabs. Literal quotes and back-slashes
-should be escaped with back-slashes.</p>
-
-<p>The characteristics of the request itself are logged by placing
-"%" directives in the format string, which are replaced in the log file
-by the values as follows:</p>
-
-<PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>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 provides for logging of the requests made to the
+ server, using the Common Log Format or a user-specified
+ format.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_log_config.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ config_log_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This module provides for flexible logging of client
+ requests. Logs are written in a customizable format, and may be
+ written directly to a file, or to an external program.
+ Conditional logging is provided so that individual requests may
+ be included or excluded from the logs based on characteristics
+ of the request.</p>
+
+ <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
+ step. 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>
+
+ <p>See also: <a href="../logs.html">Apache Log Files</a>.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#cookielog">CookieLog</a></li>
+
+ <li><a href="#customlog">CustomLog</a></li>
+
+ <li><a href="#logformat">LogFormat</a></li>
+
+ <li><a href="#transferlog">TransferLog</a></li>
+ </ul>
+
+ <h2><a id="formats" name="formats">Custom Log Formats</a></h2>
+
+ <p>The format argument to the <code>LogFormat</code> and
+ <code>CustomLog</code> directives 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 the c-type control
+ characters "\n" and "\t" to represent new-lines and tabs.
+ Literal quotes and back-slashes should be escaped with
+ back-slashes.</p>
+
+ <p>The characteristics of the request itself are logged by
+ placing "%" directives in the format string, which are replaced
+ in the log file by the values as follows:</p>
+<pre>
%...a: Remote IP-address
%...A: Local IP-address
%...B: Bytes sent, excluding HTTP headers.
%...b: Bytes sent, excluding HTTP headers. In CLF format
- i.e. a '-' rather than a 0 when no bytes are sent.
-%...{Foobar}C: The contents of cookie "Foobar" in the request sent to the
+ i.e. a '-' rather than a 0 when no bytes are sent.
+%...{Foobar}C: The contents of cookie "Foobar" in the request sent to the
server.
%...D: The time taken to serve the request, in microseconds.
%...{FOOBAR}e: The contents of the environment variable FOOBAR
%...f: Filename
%...h: Remote host
-%...H The request protocol
+%...H The request protocol
%...{Foobar}i: The contents of Foobar: header line(s) in the request
sent to the server.
%...l: Remote logname (from identd, if supplied)
-%...m The request method
+%...m The request method
%...{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.
-%...q The query string (prepended with a ? if a query string exists,
- otherwise an empty string)
+%...q The query string (prepended with a ? if a query string exists,
+ otherwise an empty string)
%...r: First line of request
%...s: Status. For requests that got internally redirected, this is
the status of the *original* request --- %...>s for the last.
'-' = connection will be closed after the response is sent.
(This directive was %...c in late versions of Apache 1.3, but
this conflicted with the historical ssl %...{var}c syntax.)
-</PRE>
-
-<p>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). 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>
-
-<p>Note that there is no escaping performed on the strings from
-%...r, %...i and %...o. This is mainly to comply with the requirements
-of the Common Log Format. This implies that clients can insert
-control characters into the log, so care should be taken when dealing
-with raw log files.</p>
-
-<p>Some commonly used log format strings are:</p>
-
-<dl>
-<dt>Common Log Format (CLF)</dt>
-<dd><CODE>"%h %l %u %t \"%r\" %>s %b"</CODE></dd>
-
-<dt>Common Log Format with Virtual Host</dt>
-<dd><code>"%v %h %l %u %t \"%r\" %>s %b"</CODE></dd>
-
-<dt>NCSA extended/combined log format</dt>
-<dd> <CODE>"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""</CODE></dd>
-
-<dt>Referer log format</dt>
-<dd><code>"%{Referer}i -> %U"</code></dd>
-
-<dt>Agent (Browser) log format</dt>
-<dd><code>"%{User-agent}i"</code></dd>
-</dl>
-
-<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.</p>
-
-<H2>Security Considerations</H2>
-
-<p>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>
-
-<HR>
-
-
-<H2><A NAME="cookielog">CookieLog</A> directive</H2>
-<!--%plaintext <?INDEX {\tt CookieLog} directive> -->
-<p><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>
-
-<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 mod_cookies, and is deprecated.</p>
-
-<HR>
-<H2><A NAME="customlog">CustomLog</A>
-<a NAME="customlogconditional">directive</a></H2>
-<p><A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> CustomLog <EM>file</em>|<em>pipe</EM>
- <EM>format</em>|<em>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> Nickname only available in Apache 1.3
- or later. Conditional logging available in 1.3.5 or later.
-<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> mod_log_config</p>
-
-<p>The <code>CustomLog</code> directive is used to log requests
-to the server. A log format is specified, and the logging can
-optionally be made conditional on request characteristics
-using environment variables.</p>
-
-<P>The first argument, which specifies the location to which the
-logs will be written, can take on one of the following two
-types of values:</p>
-
-<dl>
-<dt><em>file</em>
-<dd>A filename, relative to the
-<a href="core.html#serverroot">ServerRoot</a>.</dd>
-
-<dt><em>pipe</em>
-<dd>The pipe character "<code>|</code>", followed by the path to a
-program to receive the log information on its standard input.
-<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.</dd>
-</dl>
-
-<P>The second argument specifies what will be written to the
-log file. It can specify either a <em>nickname</em>
-defined by a previous <a href="#logformat">LogFormat</a>
-directive, or it can be an explicit <em>format</em> string
-as described in the <a href="#formats">log formats</a> section.</p>
-
-<p>For example, the following two sets of directives have exactly
-the same effect:</p>
+</pre>
+ <p>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). 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>
+
+ <p>Note that there is no escaping performed on the strings from
+ %...r, %...i and %...o. This is mainly to comply with the
+ requirements of the Common Log Format. This implies that
+ clients can insert control characters into the log, so care
+ should be taken when dealing with raw log files.</p>
+
+ <p>Some commonly used log format strings are:</p>
+
+ <dl>
+ <dt>Common Log Format (CLF)</dt>
+
+ <dd><code>"%h %l %u %t \"%r\" %>s %b"</code></dd>
+
+ <dt>Common Log Format with Virtual Host</dt>
+
+ <dd><code>"%v %h %l %u %t \"%r\" %>s %b"</code></dd>
+
+ <dt>NCSA extended/combined log format</dt>
+
+ <dd><code>"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\"
+ \"%{User-agent}i\""</code></dd>
+
+ <dt>Referer log format</dt>
+
+ <dd><code>"%{Referer}i -> %U"</code></dd>
+
+ <dt>Agent (Browser) log format</dt>
+
+ <dd><code>"%{User-agent}i"</code></dd>
+ </dl>
+
+ <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.</p>
+
+ <h2>Security Considerations</h2>
+
+ <p>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>
+ <hr />
+
+ <h2><a id="cookielog" name="cookielog">CookieLog</a>
+ directive</h2>
+ <!--%plaintext <?INDEX {\tt CookieLog} directive> -->
+
+ <p><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>
+
+ <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 mod_cookies, and is
+ deprecated.</p>
+ <hr />
+
+ <h2><a id="customlog" name="customlog">CustomLog</a> <a
+ id="customlogconditional"
+ name="customlogconditional">directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> CustomLog
+ <em>file</em>|<em>pipe</em> <em>format</em>|<em>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> Nickname only
+ available in Apache 1.3 or later. Conditional logging available
+ in 1.3.5 or later.<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> mod_log_config</p>
+
+ <p>The <code>CustomLog</code> directive is used to log requests
+ to the server. A log format is specified, and the logging can
+ optionally be made conditional on request characteristics using
+ environment variables.</p>
+
+ <p>The first argument, which specifies the location to which
+ the logs will be written, can take on one of the following two
+ types of values:</p>
+
+ <dl>
+ <dt><em>file</em></dt>
+
+ <dd>A filename, relative to the <a
+ href="core.html#serverroot">ServerRoot</a>.</dd>
+
+ <dt><em>pipe</em></dt>
+
+ <dd>The pipe character "<code>|</code>", followed by the path
+ to a program to receive the log information on its standard
+ input. <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.</dd>
+ </dl>
+
+ <p>The second argument specifies what will be written to the
+ log file. It can specify either a <em>nickname</em> defined by
+ a previous <a href="#logformat">LogFormat</a> directive, or it
+ can be an explicit <em>format</em> string as described in the
+ <a href="#formats">log formats</a> section.</p>
+
+ <p>For example, the following two sets of directives have
+ exactly the same effect:</p>
<pre>
# CustomLog with format nickname
- LogFormat "%h %l %u %t \"%r\" %>s %b" common
+ LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common
# CustomLog with explicit format string
- CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"
+ CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"
</pre>
-<p>The third argument is optional and allows the decision on whether
-or not to log a particular request to be based on the presence or
-absence of a particular variable in the server environment. If the
-specified <a href="../env.html">environment variable</a> 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>
+ <p>The third argument is optional and allows the decision on
+ whether or not to log a particular request to be based on the
+ presence or absence of a particular variable in the server
+ environment. If the specified <a href="../env.html">environment
+ variable</a> 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> directive</H2>
-<!--%plaintext <?INDEX {\tt LogFormat} directive> -->
-<p><A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> LogFormat <EM>format</em>|<em>nickname</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>
-
-<p>This directive specifies the format of the access log file.</p>
-
-<p>The <code>LogFormat</code> directive can take one of two forms. In
-the first form, where only one argument is specified, this directive
-sets the log format which will be used by logs specified in subsequent
-<a href="#transferlog">TransferLog</a> directives. The single
-argument can specify an explicit <em>format</em> as discussed in <a
-href="#formats">custom log formats</a> section above. Alternatively,
-it can use a <em>nickname</em> to refer to a log format defined
-in a previous <code>LogFormat</code> directive as described below.</p>
-
-<p>The second form of the <code>LogFormat</code> directive associates
-an explicit <em>format</em> with a <em>nickname</em>. This
-<em>nickname</em> can then be used in subsequent
-<code>LogFormat</code> or <a href="#customlog">CustomLog</a>
-directives rather than repeating the entire format string. 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. Therefore, it will not affect subsequent <a
-href="#transferlog">TransferLog</a> directives.
-</P>
-
-<HR>
-
-<H2><A NAME="transferlog">TransferLog</A> directive</H2>
-<!--%plaintext <?INDEX {\tt TransferLog} directive> -->
-<p><A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> TransferLog <EM>file</em>|<em>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>
-
-<p>This directive has exactly the same arguments and effect as the <a
-href="#customlog">CustomLog</a> directive, with the exception that it
-does not allow the log format to be specified explicitly or for
-conditional logging of requests. Instead, the log format is
-determined by the most recently specified specified <a
-href="#logformat">LogFormat</a> directive (which does not define a
-nickname). Common Log Format is used if no other format has been
-specified.</p>
-
-<p>Example:</p>
-
+</pre>
+ <hr />
+
+ <h2><a id="logformat" name="logformat">LogFormat</a>
+ directive</h2>
+ <!--%plaintext <?INDEX {\tt LogFormat} directive> -->
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> LogFormat
+ <em>format</em>|<em>nickname</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>
+
+ <p>This directive specifies the format of the access log
+ file.</p>
+
+ <p>The <code>LogFormat</code> directive can take one of two
+ forms. In the first form, where only one argument is specified,
+ this directive sets the log format which will be used by logs
+ specified in subsequent <a href="#transferlog">TransferLog</a>
+ directives. The single argument can specify an explicit
+ <em>format</em> as discussed in <a href="#formats">custom log
+ formats</a> section above. Alternatively, it can use a
+ <em>nickname</em> to refer to a log format defined in a
+ previous <code>LogFormat</code> directive as described
+ below.</p>
+
+ <p>The second form of the <code>LogFormat</code> directive
+ associates an explicit <em>format</em> with a
+ <em>nickname</em>. This <em>nickname</em> can then be used in
+ subsequent <code>LogFormat</code> or <a
+ href="#customlog">CustomLog</a> directives rather than
+ repeating the entire format string. 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. Therefore, it will not affect subsequent <a
+ href="#transferlog">TransferLog</a> directives.</p>
+ <hr />
+
+ <h2><a id="transferlog" name="transferlog">TransferLog</a>
+ directive</h2>
+ <!--%plaintext <?INDEX {\tt TransferLog} directive> -->
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> TransferLog
+ <em>file</em>|<em>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>
+
+ <p>This directive has exactly the same arguments and effect as
+ the <a href="#customlog">CustomLog</a> directive, with the
+ exception that it does not allow the log format to be specified
+ explicitly or for conditional logging of requests. Instead, the
+ log format is determined by the most recently specified
+ specified <a href="#logformat">LogFormat</a> directive (which
+ does not define a nickname). Common Log Format is used if no
+ other format has been specified.</p>
+
+ <p>Example:</p>
<pre>
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog logs/access_log
</pre>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
-<!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>
-
- <p>This module provides for determining the MIME type of a file by
- looking at a few bytes of its contents.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_mime_magic.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> mime_magic_module
-</P>
-
-
-
- <H2>Summary</H2>
-
- <p>This module determines the MIME type of files in the same way the
- Unix file(1) command works: it looks at the first few bytes of
- the file. It is intended as a "second line of defense" for cases
- that <a href="mod_mime.html">mod_mime</a> can't resolve. To assure
- that mod_mime gets first try at determining a file's MIME type,
- be sure to list mod_mime_magic <STRONG>before</STRONG> mod_mime
- in the configuration.
-
- <p>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. This module is active only if the magic file is
- specified by the <A
- HREF="#mimemagicfile"><CODE>MimeMagicFile</CODE></A> directive.
-
-
- <H2>Directives</H2>
- <P>
- <UL>
- <LI><A HREF="#mimemagicfile">MimeMagicFile</A>
- </LI>
- </UL>
- </P>
-
- <h2>Format of the Magic File</h2>
-
-<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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module provides for determining the MIME type of a file
+ by looking at a few bytes of its contents.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_mime_magic.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ mime_magic_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This module determines the MIME type of files in the same
+ way the Unix file(1) command works: it looks at the first few
+ bytes of the file. It is intended as a "second line of defense"
+ for cases that <a href="mod_mime.html">mod_mime</a> can't
+ resolve. To assure that mod_mime gets first try at determining
+ a file's MIME type, be sure to list mod_mime_magic
+ <strong>before</strong> mod_mime in the configuration.</p>
+
+ <p>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. This module is active only if the magic
+ file is specified by the <a
+ href="#mimemagicfile"><code>MimeMagicFile</code></a>
+ directive.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#mimemagicfile">MimeMagicFile</a></li>
+ </ul>
+ <br />
+ <br />
+
+
+ <h2>Format of the Magic File</h2>
+
+ <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:</p>
+
+ <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.</p>
+<pre>
# Sun/NeXT audio data
0 string .snd
>12 belong 1 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>
+</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 \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>
+</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>
-
- <H2>Performance Issues</H2>
-
- 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><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>
+</pre>
+
+ <h2>Performance Issues</h2>
+ 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>
+
+ <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.</p>
+
+ <h2><a id="notes" 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.
* - 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
+ * 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
* - Command-line flags have been removed since they will never be used here.
*
*/
-</PRE>
-
- <HR>
- <H2><A NAME="mimemagicfile">
- MimeMagicFile
- </A></H2>
- <P>
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> MimeMagicFile <EM>file-path</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>
-
- </BODY>
-</HTML>
+</pre>
+ <hr />
+
+ <h2><a id="mimemagicfile"
+ name="mimemagicfile">MimeMagicFile</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> MimeMagicFile
+ <em>file-path</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>
+
+ <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>
+ </body>
+</html>
+
-<!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 provides mmap()ing of a statically configured list
- of frequently requested but not changed files.
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Experimental
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_mmap_static.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> mmap_static_module
-</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> directive</H2>
- <P>
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> MMapFile <EM>filename</em>
- [<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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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 provides mmap()ing of a statically configured
+ list of frequently requested but not changed files.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Experimental<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_mmap_static.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ mmap_static_module</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 id="mmapfile" name="mmapfile">MMapFile</a>
+ directive</h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> MMapFile
+ <em>filename</em> [<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>
+
+ <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>
+
+</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:</p>
+<pre>
find /www/htdocs -type f -print \
| sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf
- </PRE>
+
+</pre>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-<!--#include virtual="footer.html" -->
- </BODY>
-</HTML>
-<!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>
-
-<p>This module provides for <A
-HREF="../content-negotiation.html">content negotiation</A>.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_negotiation.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> negotiation_module
-</P>
-
-<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>
-
-<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">Options</A>.
-
-<H2>Type maps</H2>
-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>
-
-<H2>MultiViews</H2>
-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>
-
-
-
-<HR>
-
-
-<H2><A NAME="cachenegotiateddocs">CacheNegotiatedDocs</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> CacheNegotiatedDocs on|off<BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> <CODE>CacheNegotiatedDocs 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_negotiation<BR>
-<A
- HREF="directive-dict.html#Compatibility"
- REL="Help"
-><STRONG>Compatibility:</STRONG></A> CacheNegotiatedDocs is only available
-in Apache 1.1 and later. The syntax changed in version 2.0.<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.
-
-<P>Prior to version 2.0, CacheNegotiatedDocs did not take an argument;
-it was turned on by the presence of the directive by itself.
-
-<hr>
-
-<H2><A NAME="languagepriority">LanguagePriority</A> directive</H2>
-<!--%plaintext <?INDEX {\tt LanguagePriority} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> LanguagePriority <EM>MIME-lang</em>
- [<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_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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module provides for <a
+ href="../content-negotiation.html">content negotiation</a>.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_negotiation.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ negotiation_module</p>
+
+ <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>
+
+ <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.</li>
+ </ul>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a
+ href="#cachenegotiateddocs">CacheNegotiatedDocs</a></li>
+
+ <li><a href="#languagepriority">LanguagePriority</a></li>
+ </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">Options</a>.
+
+ <h2>Type maps</h2>
+ 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:</dt>
+
+ <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.</dd>
+
+ <dt>Content-Language:</dt>
+
+ <dd>The language of the variant, as an Internet standard
+ language tag (RFC 1766). An example is <code>en</code>,
+ meaning English.</dd>
+
+ <dt>Content-Length:</dt>
+
+ <dd>The length of the file, in bytes. If this header is not
+ present, then the actual length of the file is used.</dd>
+
+ <dt>Content-Type:</dt>
+
+ <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</dt>
+
+ <dd>an integer specifying the version of the media type.
+ For <code>text/html</code> this defaults to 2, otherwise
+ 0.</dd>
+
+ <dt>qs</dt>
+
+ <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.</dd>
+ </dl>
+ Example:
+
+ <blockquote>
+ <code>Content-Type: image/jpeg; qs=0.8</code>
+ </blockquote>
+ </dd>
+
+ <dt>URI:</dt>
+
+ <dd>The path to the file containing this variant, relative to
+ the map file.</dd>
+ </dl>
+
+ <h2>MultiViews</h2>
+ 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.
+ <hr />
+
+ <h2><a id="cachenegotiateddocs"
+ name="cachenegotiateddocs">CacheNegotiatedDocs</a>
+ directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> CacheNegotiatedDocs
+ on|off<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a>
+ <code>CacheNegotiatedDocs 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_negotiation<br />
+ <a href="directive-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a>
+ CacheNegotiatedDocs is only available in Apache 1.1 and later.
+ The syntax changed in version 2.0.
+
+ <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>
+
+ <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.</p>
+
+ <p>Prior to version 2.0, CacheNegotiatedDocs did not take an
+ argument; it was turned on by the presence of the directive by
+ itself.</p>
+ <hr />
+
+ <h2><a id="languagepriority"
+ name="languagepriority">LanguagePriority</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt LanguagePriority} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> LanguagePriority
+ <em>MIME-lang</em> [<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_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:</p>
+
+ <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>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>
+
+ <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" -->
+ </p>
+ </body>
+</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache module mod_proxy</TITLE>
-</HEAD>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
-<blockquote><strong>Note:</strong>
-Mod_proxy has been moved out of the httpd-2.0 tree, but is available
-elsewhere <insert location> for building with the httpd-2.0 source
-distribution.
-</blockquote>
+ <title>Apache module mod_proxy</title>
+ </head>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
+ vlink="#000080" alink="#FF0000">
+ <!--#include virtual="header.html" -->
+
+ <blockquote>
+ <strong>Note:</strong> Mod_proxy has been moved out of the
+ httpd-2.0 tree, but is available elsewhere <insert
+ location> for building with the httpd-2.0 source
+ distribution.
+ </blockquote>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--%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>
-
-<p>This module provides a rule-based rewriting engine to rewrite requested
-URLs on the fly.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_rewrite.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> rewrite_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later.
-</P>
-
-
-<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 can even 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 entire module 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 has been read but 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>) have been
-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 starts 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 rewrites URLs either 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 to be 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>Although mod_rewrite rewrites URLs to URLs, URLs to filenames and
- even filenames to filenames, the API currently provides only a
- URL-to-filename hook. 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 than 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 have
- been translated to filenames. It has to be this way because
- <CODE>.htaccess</CODE> files live in the filesystem, so processing
- has already reached this stage. 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 is 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 restarts
- processing of the API phases.
- <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 during 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. Only 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 (and not very obvious) order. The
-rule is this: The rewriting engine loops through the ruleset rule by rule
-(<CODE>RewriteRule</CODE> directives) and when a particular rule matches it
-optionally loops through existing corresponding conditions
-(<CODE>RewriteCond</CODE> directives). For historical reasons the conditions
-are given first, and so the control flow is a little bit long-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> matches, 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
-exist, it starts an inner loop for processing them in the order that
-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 conditions are available. If all conditions match, processing
-is continued with the substitution of the URL with <EM>Substitution</EM>.
-
-<h2><a name="quoting">Quoting Special Characters</a></h2>
-<p>
-As of Apache 1.3.20, special characters in <i>TestString</i> and
-<i>Substitution</i> strings can be escaped (that is, treated as
-normal characters without their usual special meaning) by prefixing them
-with a slosh ('\') character. In other words, you can include an
-actual dollar-sign character in a <i>Substitution</i> string
-by using '<code>\$</code>'; this keeps mod_rewrite from trying
-to treat it as a backreference.
-</p>
-
-<H2><A NAME="InternalBackRefs">Regex Back-Reference Availability</A></H2>
-
-One important thing here has to be remembered: Whenever you
-use parentheses in <EM>Pattern</EM> or in one of the <EM>CondPattern</EM>,
-back-references are internally created which can be used with the
-strings <CODE>$N</CODE> and <CODE>%N</CODE> (see below). These
-are available for creating the strings <EM>Substitution</EM> and
-<EM>TestString</EM>. Figure 2 shows to which locations the back-references are
-transfered 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 on 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>
- RewriteEngine on|off<BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A>
- <CODE>RewriteEngine 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> 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 the <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 in which you wish to use it.
-
-<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> RewriteOptions <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 are inherited. In per-directory
- context this means that conditions and rules of the parent directory's
- <CODE>.htaccess</CODE> configuration are 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> RewriteLog <EM>file-path</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>Note</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 then 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>
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <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>
+
+ <p>This module provides a rule-based rewriting engine to
+ rewrite requested URLs on the fly.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_rewrite.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ rewrite_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.2 and later.</p>
+ <hr noshade="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>
+
+ <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 can even 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>
+
+ <p>But all this functionality and flexibility has its
+ drawback: complexity. So don't expect to understand this
+ entire module in just one day.</p>
+
+ <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>
+ <hr noshade="noshade" size="1" />
+
+ <h2>Table Of Contents</h2>
+
+ <p><strong>Internal Processing</strong></p>
+
+ <ul>
+ <li><a href="#InternalAPI">API Phases</a></li>
+
+ <li><a href="#InternalRuleset">Ruleset Processing</a></li>
+
+ <li><a href="#InternalBackRefs">Regex Back-Reference
+ Availability</a></li>
+ </ul>
+
+ <p><strong>Configuration Directives</strong></p>
+
+ <ul>
+ <li><a href="#RewriteEngine">RewriteEngine</a></li>
+
+ <li><a href="#RewriteOptions">RewriteOptions</a></li>
+
+ <li><a href="#RewriteLog">RewriteLog</a></li>
+
+ <li><a href="#RewriteLogLevel">RewriteLogLevel</a></li>
+
+ <li><a href="#RewriteLock">RewriteLock</a></li>
+
+ <li><a href="#RewriteMap">RewriteMap</a></li>
+
+ <li><a href="#RewriteBase">RewriteBase</a></li>
+
+ <li><a href="#RewriteCond">RewriteCond</a></li>
+
+ <li><a href="#RewriteRule">RewriteRule</a></li>
+ </ul>
+ <strong>Miscellaneous</strong>
+
+ <ul>
+ <li><a href="#EnvVar">Environment Variables</a></li>
+
+ <li><a href="#Solutions">Practical Solutions</a></li>
+ </ul>
+ <hr noshade="noshade" size="1" />
+
+ <center>
+ <h1><a id="Internal" name="Internal">Internal
+ Processing</a></h1>
+ </center>
+ <hr noshade="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.</p>
+
+ <h2><a id="InternalAPI" 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 has been read but 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>) have been read, but
+ before the content handler is activated.</p>
+
+ <p>So, after a request comes in and Apache has determined the
+ corresponding server (or virtual server) the rewriting engine
+ starts 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
+ rewrites URLs either 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 to be 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:</p>
+
+ <ol>
+ <li>Although mod_rewrite rewrites URLs to URLs, URLs to
+ filenames and even filenames to filenames, the API
+ currently provides only a URL-to-filename hook. 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 than the API
+ intends for it.</li>
+
+ <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 have been translated to
+ filenames. It has to be this way because
+ <code>.htaccess</code> files live in the filesystem, so
+ processing has already reached this stage. 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 is 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 restarts processing of
+ the API phases.
+
+ <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.</p>
+ </li>
+ </ol>
+
+ <p>Don't forget these two points!</p>
+
+ <h2><a id="InternalRuleset" 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 during 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. Only 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 (and not very
+ obvious) order. The rule is this: The rewriting engine loops
+ through the ruleset rule by rule (<code>RewriteRule</code>
+ directives) and when a particular rule matches it optionally
+ loops through existing corresponding conditions
+ (<code>RewriteCond</code> directives). For historical reasons
+ the conditions are given first, and so the control flow is a
+ little bit long-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> matches, 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 exist, it starts an
+ inner loop for processing them in the order that 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 conditions are
+ available. If all conditions match, processing is continued
+ with the substitution of the URL with
+ <em>Substitution</em>.</p>
+
+ <h2><a id="quoting" name="quoting">Quoting Special
+ Characters</a></h2>
+
+ <p>As of Apache 1.3.20, special characters in
+ <i>TestString</i> and <i>Substitution</i> strings can be
+ escaped (that is, treated as normal characters without their
+ usual special meaning) by prefixing them with a slosh ('\')
+ character. In other words, you can include an actual
+ dollar-sign character in a <i>Substitution</i> string by
+ using '<code>\$</code>'; this keeps mod_rewrite from trying
+ to treat it as a backreference.</p>
+
+ <h2><a id="InternalBackRefs" name="InternalBackRefs">Regex
+ Back-Reference Availability</a></h2>
+ One important thing here has to be remembered: Whenever you
+ use parentheses in <em>Pattern</em> or in one of the
+ <em>CondPattern</em>, back-references are internally created
+ which can be used with the strings <code>$N</code> and
+ <code>%N</code> (see below). These are available for creating
+ the strings <em>Substitution</em> and <em>TestString</em>.
+ Figure 2 shows to which locations the back-references are
+ transfered for expansion.
+
+ <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 on mod_rewrite's internal
+ processing. But you will benefit from this knowledge when
+ reading the following documentation of the available
+ directives.</p>
+ <hr noshade="noshade" size="1" />
+
+ <center>
+ <h1><a id="Configuration"
+ name="Configuration">Configuration Directives</a></h1>
+ </center>
+ <hr noshade="noshade" size="1" />
+
+ <h3><a id="RewriteEngine"
+ name="RewriteEngine">RewriteEngine</a></h3>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> RewriteEngine
+ on|off<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> <code>RewriteEngine
+ 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> 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>
+
+ <p>Use this directive to disable the module instead of
+ commenting out all the <code>RewriteRule</code>
+ directives!</p>
+
+ <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
+ in which you wish to use it.</p>
+ <hr noshade="noshade" size="1" />
+
+ <h3><a id="RewriteOptions"
+ name="RewriteOptions">RewriteOptions</a></h3>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> RewriteOptions
+ <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:</p>
+
+ <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 are inherited. In per-directory context this means
+ that conditions and rules of the parent directory's
+ <code>.htaccess</code> configuration are inherited.</li>
+ </ul>
+ <hr noshade="noshade" size="1" />
+
+ <h3><a id="RewriteLog" name="RewriteLog">RewriteLog</a></h3>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> RewriteLog
+ <em>file-path</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>Note</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 then 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>
+
+ <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></p>
+
+ <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> RewriteLogLevel <EM>Level</EM><BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> <CODE>RewriteLogLevel 0</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> 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 sets 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 at
-a <EM>Level</EM> greater than 2 only for debugging!
-</TD></TR>
-</TABLE>
-
-
-<P>
-<STRONG>Example:</STRONG>
-<BLOCKQUOTE>
-<PRE>
+</pre>
+ </blockquote>
+ <hr noshade="noshade" size="1" />
+
+ <h3><a id="RewriteLogLevel"
+ name="RewriteLogLevel">RewriteLogLevel</a></h3>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> RewriteLogLevel
+ <em>Level</em><br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a>
+ <code>RewriteLogLevel 0</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> 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 sets 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>
+
+ <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 at a
+ <em>Level</em> greater than 2 only for debugging!</td>
+ </tr>
+ </table>
+
+ <p><strong>Example:</strong></p>
+
+ <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> RewriteLock <EM>file-path</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
-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> RewriteMap <EM>MapName </EM>
- <EM>MapType</EM>:<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
-by 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>
+</pre>
+ </blockquote>
+ <hr noshade="noshade" size="1" />
+
+ <h3><a id="RewriteLock"
+ name="RewriteLock">RewriteLock</a></h3>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> RewriteLock
+ <em>file-path</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 other
+ types of rewriting maps.</p>
+ <hr noshade="noshade" size="1" />
+
+ <h3><a id="RewriteMap" name="RewriteMap">RewriteMap</a></h3>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> RewriteMap
+ <em>MapName</em> <em>MapType</em>:<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>
+
+ <p>The <a id="mapfunc" 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:</p>
+
+ <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 by 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:</p>
+
+ <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.</p>
+
+ <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>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <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''.
- 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>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </li>
+
+ <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''. 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>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <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>
+</pre>
+ </td>
+ </tr>
+ </table>
+ </li>
+
+ <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
$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 program, not a map file. To create it you
- can use the language of your choice, but the result has to be a
- 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 is 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>
+close(TXT)
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <table border="0" cellspacing="1" cellpadding="5"
+ bgcolor="#F0F0F0">
+ <tr>
+ <td>
+<pre>
+$ txt2dbm map.txt map.db
+</pre>
+ </td>
+ </tr>
+ </table>
+ </li>
+
+ <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:</p>
+
+ <ul>
+ <li><strong>toupper</strong>:<br />
+ Converts the looked up key to all upper case.</li>
+
+ <li><strong>tolower</strong>:<br />
+ Converts the looked up key to all lower case.</li>
+
+ <li><strong>escape</strong>:<br />
+ Translates special characters in the looked up key to
+ hex-encodings.</li>
+
+ <li><strong>unescape</strong>:<br />
+ Translates hex-encodings in the looked up key back to
+ special characters.</li>
+ </ul>
+ </li>
+
+ <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 program, not a map file. To
+ create it you can use the language of your choice, but
+ the result has to be a 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>
+
+ <p>This program is 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>) {
# ...put here any transformations or lookups...
print $_;
}
-</PRE></TD></TR>
-</TABLE>
- <P>
- But be very careful:<BR>
- <OL>
- <LI>``<EM>Keep it simple, stupid</EM>'' (KISS), because
- if this program hangs it will hang 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.
- By 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>Note:</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> RewriteBase <EM>URL-path</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 back to the path.
-
-<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
-NOT directly related to physical filename paths, so this
-assumption will 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>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>But be very careful:<br />
+ </p>
+
+ <ol>
+ <li>``<em>Keep it simple, stupid</em>'' (KISS), because
+ if this program hangs it will hang the Apache server
+ when the rule occurs.</li>
+
+ <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>
+
+ <li>Use the <samp>RewriteLock</samp> directive to
+ define a lockfile mod_rewrite can use to synchronize
+ the communication to the program. By default no such
+ synchronization takes place.</li>
+ </ol>
+ </li>
+ </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.
+
+ <table width="70%" border="0" bgcolor="#E0E0F0"
+ cellspacing="0" cellpadding="10">
+ <tr>
+ <td><strong>Note:</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>
+ <hr noshade="noshade" size="1" />
+
+ <h3><a id="RewriteBase"
+ name="RewriteBase">RewriteBase</a></h3>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> RewriteBase
+ <em>URL-path</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 back to the
+ path.</p>
+
+ <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 NOT
+ directly related to physical filename paths, so this
+ assumption will 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></p>
+
+ <blockquote>
+ Assume the following per-directory config file:
+
+ <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>
+# 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
# 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>Note - For Apache hackers:</STRONG><BR>
-The following list gives detailed information about the internal
-processing steps:
-
-<P>
-<PRE>
-Request:
+</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>Note - For Apache
+ hackers:</strong><br />
+ The following list gives detailed information about
+ the internal processing steps:</font>
+<pre>
+<font size="-1">Request:
/xyz/oldstuff.html
Internal Processing:
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 internally 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> RewriteCond <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>
-
-(0 <= 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 (parentheses!) of
-the pattern from the last matched <CODE>RewriteCond</CODE> directive in the
-current bunch of conditions.
-
-<P>
-<LI><STRONG>RewriteMap expansions</STRONG>: These are expansions of the form
-
-<BLOCKQUOTE><STRONG>
-<CODE>${mapname:key|default}</CODE>
-</STRONG></BLOCKQUOTE>
-
-See <A HREF="#mapfunc">the documentation for RewriteMap</A> for more details.
-
-<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
-taken from 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>
-
-<p><STRONG>Notice:</STRONG> These variables all correspond to
-the similarly named HTTP MIME-headers, C variables of the Apache
-server or <CODE>struct tm</CODE> fields of the Unix system. Most
-are documented elsewhere in the Manual or in the CGI specification.
-Those that are special to mod_rewrite include:</p>
-
-<dl>
-<dt><code>IS_SUBREQ</code></dt>
-<dd>Will contain the text "true" if the request currently
-being processed is a sub-request, "false" otherwise. Sub-requests may
-be generated by modules that need to resolve additional files or URIs
-in order to complete their tasks.</dd>
-
-<dt><code>API_VERSION</code></dt>
-<dd>This is the version of the Apache module API (the internal
-interface between server and module) in the current httpd build, as
-defined in include/ap_mmn.h. The module API version corresponds to the
-version of Apache in use (in the release version of Apache 1.3.14, for
-instance, it is 19990320:10), but is mainly of interest to module
-authors.</dd>
-
-<dt><code>THE_REQUEST</code></dt>
-<dd>The full HTTP request line sent by the browser to the server
-(e.g., "<code>GET /index.html HTTP/1.1</code>"). This does not include
-any additional headers sent by the browser.</dd>
-
-<dt><code>REQUEST_URI</code></dt>
-<dd>The resource requested in the HTTP request line. (In the
-example above, this would be "/index.html".)</dd>
-
-<dt><code>REQUEST_FILENAME</code></dt>
-<dd>The full local filesystem path to the file or script
-matching the request.</dd>
-</dl>
-
-</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 is actually 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 performs an
-internal (filename-based) sub-request to determine the final value of
-<EM>variable</EM>. Most of the time this is the same as LA-U above.
-</OL>
-
-<P>
-<EM>CondPattern</EM> is the condition pattern, <EM>i.e.</EM>, a regular
-expression
-which is applied to the current instance of the <EM>TestString</EM>,
-<EM>i.e.</EM>, <EM>TestString</EM> is 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 prefix 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 lexically lower)<BR>
-Treats the <EM>CondPattern</EM> as a plain string and compares it
-lexically to <EM>TestString</EM>. True if
-<EM>TestString</EM> is lexically lower than <EM>CondPattern</EM>.
-<P>
-<LI>'<STRONG>>CondPattern</STRONG>' (is lexically greater)<BR>
-Treats the <EM>CondPattern</EM> as a plain string and compares it
-lexically to <EM>TestString</EM>. True if
-<EM>TestString</EM> is lexically greater than <EM>CondPattern</EM>.
-<P>
-<LI>'<STRONG>=CondPattern</STRONG>' (is lexically equal)<BR>
-Treats the <EM>CondPattern</EM> as a plain string and compares it
-lexically to <EM>TestString</EM>. True if
-<EM>TestString</EM> is lexically 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> to 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 an exclamation mark ('!')
-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 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>.
- This flag is effective only for comparisons between
- <EM>TestString</EM> and <EM>CondPattern</EM>. It has no
- effect on filesystem and subrequest checks.
-<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>
+</font>
+</pre>
+ <font size="-1">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
+ internally 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>
+ <hr noshade="noshade" size="1" />
+
+ <h3><a id="RewriteCond"
+ name="RewriteCond">RewriteCond</a></h3>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> RewriteCond
+ <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>
+
+ <p><em>TestString</em> is a string which can contains the
+ following expanded constructs in addition to plain text:</p>
+
+ <ul>
+ <li>
+ <strong>RewriteRule backreferences</strong>: These are
+ backreferences of the form
+
+ <blockquote>
+ <strong><code>$N</code></strong>
+ </blockquote>
+ (0 <= 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).
+ </li>
+
+ <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 (parentheses!) of the pattern from the last matched
+ <code>RewriteCond</code> directive in the current bunch
+ of conditions.
+ </li>
+
+ <li>
+ <strong>RewriteMap expansions</strong>: These are
+ expansions of the form
+
+ <blockquote>
+ <strong><code>${mapname:key|default}</code></strong>
+ </blockquote>
+ See <a href="#mapfunc">the documentation for
+ RewriteMap</a> for more details.
+ </li>
+
+ <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 taken
+ from the following list:
+
+ <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></p>
+ </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></p>
+ </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></p>
+ </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></p>
+ </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></p>
+ </td>
+ </tr>
+ </table>
+
+ <table width="70%" border="0" bgcolor="#E0E0F0"
+ cellspacing="0" cellpadding="10">
+ <tr>
+ <td>
+ <p><strong>Notice:</strong> These variables all
+ correspond to the similarly named HTTP
+ MIME-headers, C variables of the Apache server or
+ <code>struct tm</code> fields of the Unix system.
+ Most are documented elsewhere in the Manual or in
+ the CGI specification. Those that are special to
+ mod_rewrite include:</p>
+
+ <dl>
+ <dt><code>IS_SUBREQ</code></dt>
+
+ <dd>Will contain the text "true" if the request
+ currently being processed is a sub-request,
+ "false" otherwise. Sub-requests may be generated
+ by modules that need to resolve additional files
+ or URIs in order to complete their tasks.</dd>
+
+ <dt><code>API_VERSION</code></dt>
+
+ <dd>This is the version of the Apache module API
+ (the internal interface between server and
+ module) in the current httpd build, as defined in
+ include/ap_mmn.h. The module API version
+ corresponds to the version of Apache in use (in
+ the release version of Apache 1.3.14, for
+ instance, it is 19990320:10), but is mainly of
+ interest to module authors.</dd>
+
+ <dt><code>THE_REQUEST</code></dt>
+
+ <dd>The full HTTP request line sent by the
+ browser to the server (e.g., "<code>GET
+ /index.html HTTP/1.1</code>"). This does not
+ include any additional headers sent by the
+ browser.</dd>
+
+ <dt><code>REQUEST_URI</code></dt>
+
+ <dd>The resource requested in the HTTP request
+ line. (In the example above, this would be
+ "/index.html".)</dd>
+
+ <dt><code>REQUEST_FILENAME</code></dt>
+
+ <dd>The full local filesystem path to the file or
+ script matching the request.</dd>
+ </dl>
+ </td>
+ </tr>
+ </table>
+ </li>
+ </ul>
+
+ <p>Special Notes:</p>
+
+ <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>).</li>
+
+ <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.</li>
+
+ <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>''.</li>
+
+ <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 is actually 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.</li>
+
+ <li>There is the special format:
+ <code>%{LA-F:variable}</code> which performs an internal
+ (filename-based) sub-request to determine the final value
+ of <em>variable</em>. Most of the time this is the same as
+ LA-U above.</li>
+ </ol>
+
+ <p><em>CondPattern</em> is the condition pattern,
+ <em>i.e.</em>, a regular expression which is applied to the
+ current instance of the <em>TestString</em>, <em>i.e.</em>,
+ <em>TestString</em> is evaluated and then matched against
+ <em>CondPattern</em>.</p>
+
+ <p><strong>Remember:</strong> <em>CondPattern</em> is a
+ standard <em>Extended Regular Expression</em> with some
+ additions:</p>
+
+ <ol>
+ <li>You can prefix the pattern string with a
+ '<code>!</code>' character (exclamation mark) to specify a
+ <strong>non</strong>-matching pattern.</li>
+
+ <li>
+ There are some special variants of <em>CondPatterns</em>.
+ Instead of real regular expression strings you can also
+ use one of the following:
+
+ <ul>
+ <li>'<strong><CondPattern</strong>' (is lexically
+ lower)<br />
+ Treats the <em>CondPattern</em> as a plain string and
+ compares it lexically to <em>TestString</em>. True if
+ <em>TestString</em> is lexically lower than
+ <em>CondPattern</em>.</li>
+
+ <li>'<strong>>CondPattern</strong>' (is lexically
+ greater)<br />
+ Treats the <em>CondPattern</em> as a plain string and
+ compares it lexically to <em>TestString</em>. True if
+ <em>TestString</em> is lexically greater than
+ <em>CondPattern</em>.</li>
+
+ <li>'<strong>=CondPattern</strong>' (is lexically
+ equal)<br />
+ Treats the <em>CondPattern</em> as a plain string and
+ compares it lexically to <em>TestString</em>. True if
+ <em>TestString</em> is lexically 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> to the empty string.</li>
+
+ <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.</li>
+
+ <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.</li>
+
+ <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.</li>
+
+ <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.</li>
+
+ <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!</li>
+
+ <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!</li>
+ </ul>
+
+ <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 an exclamation mark ('!') to
+ negate their meaning.</td>
+ </tr>
+ </table>
+ </li>
+ </ol>
+
+ <p>Additionally you can set special flags for
+ <em>CondPattern</em> by appending</p>
+
+ <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 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>.
+ This flag is effective only for comparisons between
+ <em>TestString</em> and <em>CondPattern</em>. It has no
+ effect on filesystem and subrequest checks.</li>
+
+ <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:
+
+ <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 would have to write 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>
+</pre>
+ </blockquote>
+ Without this flag you would have to write the cond/rule
+ three times.
+ </li>
+ </ul>
+
+ <p><strong>Example:</strong></p>
+
+ <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]
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> RewriteRule <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 and later 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 originally requested URL, because
-any number of rules may already have 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 > 0)
- <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
+</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>
+ <hr noshade="noshade" size="1" />
+
+ <h3><a id="RewriteRule"
+ name="RewriteRule">RewriteRule</a></h3>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> RewriteRule
+ <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>
+
+ <p><a id="patterns" name="patterns"><em>Pattern</em></a> can
+ be (for Apache 1.1.x a System V8 and for Apache 1.2.x and
+ later a POSIX) <a id="regexp" 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 originally requested URL,
+ because any number of rules may already have matched and made
+ alterations to it.</p>
+
+ <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 > 0)
+ <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. If you are interested in more detailed
-information about regular expressions and their 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 this
-pattern</EM>''. This can be used for exceptional cases, where it is easier 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>=0..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>Note</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 give 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>Note:</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>, rewriting continues.
- 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 pages which no longer
- exist 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. 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 an infinite loop!</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
- be chained with the 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>noescape|NE</CODE></STRONG>' (<STRONG>n</STRONG>o URI <STRONG>e</STRONG>scaping of output)<BR>
- This flag keeps mod_rewrite from applying the usual URI escaping
- rules to the result of a rewrite. Ordinarily, special characters
- (such as '%', '$', ';', and so on) will be escaped into their
- hexcode equivalents ('%25', '%24', and '%3B', respectively); this
- flag prevents this from being done. This allows percent symbols
- to appear in the output, as in
- <pre>
+ 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. If you are interested in more detailed
+ information about regular expressions and their variants
+ (POSIX regex, Perl regex, <em>etc.</em>) have a look at the
+ following dedicated book on this topic:</p>
+
+ <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 this
+ pattern</em>''. This can be used for exceptional cases, where
+ it is easier 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 id="rhs" 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</p>
+
+ <ol>
+ <li>back-references <code>$N</code> to the RewriteRule
+ pattern</li>
+
+ <li>back-references <code>%N</code> to the last matched
+ RewriteCond pattern</li>
+
+ <li>server-variables as in rule condition test-strings
+ (<code>%{VARNAME}</code>)</li>
+
+ <li><a href="#mapfunc">mapping-function</a> calls
+ (<code>${mapname:key|default}</code>)</li>
+ </ol>
+ Back-references are <code>$</code><strong>N</strong>
+ (<strong>N</strong>=0..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>
+
+ <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>
+
+ <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>Note</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>
+
+ <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</p>
+
+ <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 id="redirect"
+ 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 give 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>Note:</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>, rewriting
+ continues. 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>
+
+ <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.</li>
+
+ <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 pages which no longer exist as gone.</li>
+
+ <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>
+
+ <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. For example, use it to rewrite the root-path URL
+ ('<code>/</code>') to a real one, <em>e.g.</em>,
+ '<code>/e/www/</code>'.</li>
+
+ <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 an infinite
+ loop!</strong></li>
+
+ <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 be chained with the 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!).</li>
+
+ <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>''.</li>
+
+ <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>
+
+ <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.</li>
+
+ <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.</li>
+
+ <li>
+ '<strong><code>noescape|NE</code></strong>'
+ (<strong>n</strong>o URI <strong>e</strong>scaping of
+ output)<br />
+ This flag keeps mod_rewrite from applying the usual URI
+ escaping rules to the result of a rewrite. Ordinarily,
+ special characters (such as '%', '$', ';', and so on)
+ will be escaped into their hexcode equivalents ('%25',
+ '%24', and '%3B', respectively); this flag prevents this
+ from being done. This allows percent symbols to appear in
+ the output, as in
+<pre>
RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
- </pre>
- which would turn '<code>/foo/zed</code>' into a safe request
- for '<code>/bar?arg=P1=zed</code>'.
- <TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
- <TR><TD>
- <STRONG>Notice:</STRONG> The <code>noescape</code> flag is only available
- with Apache 1.3.20 and later versions.
- </TD></TR>
- </TABLE>
-<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>
+
+</pre>
+ which would turn '<code>/foo/zed</code>' into a safe
+ request for '<code>/bar?arg=P1=zed</code>'.
+
+ <table width="70%" border="0" bgcolor="#E0E0F0"
+ cellspacing="0" cellpadding="10">
+ <tr>
+ <td><strong>Notice:</strong> The
+ <code>noescape</code> flag is only available with
+ Apache 1.3.20 and later versions.</td>
+ </tr>
+ </table>
+ </li>
+
+ <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>
- Note: <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>Note - For 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 a hook in 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
- <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 in many situations, but usually from
- within XSSI (via <CODE><!--#echo var="VAR"--></CODE>) or CGI (<EM>e.g.</EM>
- <CODE>$ENV{'VAR'}</CODE>). Additionally you can 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>Note:</STRONG> Never forget that <EM>Pattern</EM> is 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!) is 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 <STRONG>not</STRONG> be added and an
-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>Note:</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>Options FollowSymLinks</CODE>'' must be 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>
+
+</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>Note: <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>Note - For 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 a hook in
+ Apache version 2.0.</font> </td>
+ </tr>
+ </table>
+ </li>
+
+ <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
+ <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!)</li>
+
+ <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 in many situations, but
+ usually from within XSSI (via <code><!--#echo
+ var="VAR"--></code>) or CGI (<em>e.g.</em>
+ <code>$ENV{'VAR'}</code>). Additionally you can dereference
+ it in a following RewriteCond pattern via
+ <code>%{ENV:VAR}</code>. Use this to strip but remember
+ information from URLs.</li>
+ </ul>
+
+ <table width="70%" border="0" bgcolor="#E0E0F0"
+ cellspacing="0" cellpadding="10">
+ <tr>
+ <td>
+ <strong>Note:</strong> Never forget that
+ <em>Pattern</em> is 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!) is 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 <strong>not</strong> be added and an
+ external redirect or proxy throughput (if flag
+ <strong>P</strong> is used!) is forced!</p>
+ </td>
+ </tr>
+ </table>
+
+ <table width="70%" border="0" bgcolor="#E0E0F0"
+ cellspacing="0" cellpadding="10">
+ <tr>
+ <td><strong>Note:</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>Options
+ FollowSymLinks</code>'' must be 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>
+
+ <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(.*) 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>
+</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(.*) 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>
+</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:</p>
+
+ <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>, <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>
+</pre>
+ </blockquote>
+ </blockquote>
+ <hr noshade="noshade" size="1" />
+
+ <center>
+ <h1><a id="Miscelleneous"
+ name="Miscelleneous">Miscellaneous</a></h1>
+ </center>
+ <hr noshade="noshade" size="1" />
+
+ <h2><a id="EnvVar" 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>, <em>before</em> any
+ rewriting. This is important because the rewriting process is
+ primarily used to rewrite logical URLs to physical
+ pathnames.</p>
+
+ <p><strong>Example:</strong></p>
+
+ <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>
-
-We also have an <a href="../misc/rewriteguide.html">URL Rewriting
-Guide</a> available, which provides a collection of practical solutions
-for URL-based problems. There you can find real-life rulesets and
-additional information about mod_rewrite.
+</pre>
+ </blockquote>
+ <hr noshade="noshade" size="1" />
+
+ <h2><a id="Solutions" name="Solutions">Practical
+ Solutions</a></h2>
+ We also have an <a href="../misc/rewriteguide.html">URL
+ Rewriting Guide</a> available, which provides a collection of
+ practical solutions for URL-based problems. There you can
+ find real-life rulesets and additional information about
+ mod_rewrite. <!--#include virtual="footer.html" -->
+ </blockquote>
+ <!-- page indentation -->
+ <!--/%hypertext -->
+ </body>
+</html>
-<!--#include virtual="footer.html" -->
-</BLOCKQUOTE><!-- page indentation -->
-</BODY>
-</HTML>
-<!--/%hypertext -->
-<!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 provides the ability to set environment variables based
- upon attributes of the request.
- </P>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_setenvif.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> setenvif_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later.
-</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 environment variables
- 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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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 provides the ability to set environment
+ variables based upon attributes of the request.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_setenvif.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ setenvif_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.3 and later.</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
+ environment variables 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.</p>
+
+ <blockquote>
+<pre>
BrowserMatch ^Mozilla netscape
BrowserMatch MSIE !netscape
- </PRE></BLOCKQUOTE>
- </P>
-
- <p>For additional information, we provide a document on
- <a href="../env.html">Environment Variables in Apache</a>.</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">BrowserMatch directive</A></H2>
- <P>
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> BrowserMatch <EM>regex
- env-variable</em>[=<em>value</em>] [<em>env-variable</em>[=<em>value</em>]] ...
- <BR>
- <A
- HREF="directive-dict.html#Default"
- REL="Help"
- ><STRONG>Default:</STRONG></A> <i>none</i>
- <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_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>
+
+</pre>
+ </blockquote>
+ <br />
+ <br />
+
+
+ <p>For additional information, we provide a document on <a
+ href="../env.html">Environment Variables in Apache</a>.</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 id="BrowserMatch" name="BrowserMatch">BrowserMatch
+ directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> BrowserMatch <em>regex
+ env-variable</em>[=<em>value</em>]
+ [<em>env-variable</em>[=<em>value</em>]] ...<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> <i>none</i><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_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 case-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>
+
+</pre>
+
+ <p>Note that the regular expression string is
+ <strong>case-sensitive</strong>. For case-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">BrowserMatchNoCase directive
- </A>
- </H2>
- <P>
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> BrowserMatchNoCase <EM>regex
- env-variable</em>[=<em>value</em>] [<em>env-variable</em>[=<em>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, 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_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>
+
+</pre>
+ <hr />
+ <!-- the HR is part of the directive description -->
+
+ <h2><a id="BrowserMatchNoCase"
+ name="BrowserMatchNoCase">BrowserMatchNoCase directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> BrowserMatchNoCase
+ <em>regex env-variable</em>[=<em>value</em>]
+ [<em>env-variable</em>[=<em>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, 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_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>
+
+</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">SetEnvIf directive
- </A>
- </H2>
- <P>
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> SetEnvIf <EM> attribute regex
- env-variable</em>[=<em>value</em>] [<em>env-variable</em>[=<em>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, 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_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://www.rfc-editor.org/rfc/rfc2616.txt">RFC2616</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>
- <EM>attribute</EM> may be a regular expression when used to match a request header.
- If <EM>attribute</EM> is a regular expression and it doesn't match any of the
- request's header names, then <EM>attribute</EM> is not tested against the request's
- environment variable list.
- </P>
- <P>
- Example:
- </P>
- <PRE>
+
+</pre>
+ <hr />
+ <!-- the HR is part of the directive description -->
+
+ <h2><a id="SetEnvIf" name="SetEnvIf">SetEnvIf
+ directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> SetEnvIf <em>attribute
+ regex env-variable</em>[=<em>value</em>]
+ [<em>env-variable</em>[=<em>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, 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_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://www.rfc-editor.org/rfc/rfc2616.txt">RFC2616</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><em>attribute</em> may be a regular expression when used to
+ match a request header. If <em>attribute</em> is a regular
+ expression and it doesn't match any of the request's header
+ names, then <em>attribute</em> is not tested against the
+ request's environment variable list.</p>
+
+ <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 object_is_image xbm XBIT_PROCESSING=1
:
SetEnvIf ^TS* ^[a-z].* HAVE_TS
- </PRE>
- <P>
- The first three will set the environment variable <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>
- <P>
- The last example will set environment variable <SAMP>HAVE_TS</SAMP> if the request
- contains any headers that begin with "TS" whose values begins with any character
- in the set [a-z].
- </P>
- <HR> <!-- the HR is part of the directive description -->
- <H2>
- <A NAME="SetEnvIfNoCase">SetEnvIfNoCase directive
- </A>
- </H2>
- <P>
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> SetEnvIfNoCase <EM> attribute regex
- env-variable</em>[=<em>value</em>] [<em>env-variable</em>[=<em>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, 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_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>
+
+</pre>
+
+ <p>The first three will set the environment variable
+ <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>
+
+ <p>The last example will set environment variable
+ <samp>HAVE_TS</samp> if the request contains any headers that
+ begin with "TS" whose values begins with any character in the
+ set [a-z].</p>
+ <hr />
+ <!-- the HR is part of the directive description -->
+
+ <h2><a id="SetEnvIfNoCase" name="SetEnvIfNoCase">SetEnvIfNoCase
+ directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> SetEnvIfNoCase
+ <em>attribute regex env-variable</em>[=<em>value</em>]
+ [<em>env-variable</em>[=<em>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, 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_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> environment variable 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>
+
+</pre>
+
+ <p>This will cause the <samp>site</samp> environment variable
+ 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>
+
-<!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>
-
-<p>This module provides for loading of executable code and modules into the
-server at start-up or restart time.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base (Windows); Optional (Unix)
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_so.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> so_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later.
-</P>
-
-
-<H2>Summary</H2>
-
-<P>On selected operating systems this module 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.
-
-<P>
-On Unix, the loaded code typically comes from shared object files
-(usually with <SAMP>.so</SAMP> extension), on Windows this may either
-the <SAMP>.so</SAMP> or <SAMP>.dll</SAMP> extension. 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.
-
-<P><STRONG> Warning: Apache 1.3 modules cannot be directly used with
- Apache 2.0 - the module must be modified to dynamically load or
- compile into Apache 2.0</STRONG>.</P>
-
-<H2>Directives</H2>
-<UL>
-<LI><A HREF="#loadfile">LoadFile</A>
-<LI><A HREF="#loadmodule">LoadModule</A>
-</UL>
-
-<H2><A NAME="creating">Creating Loadable Modules for Windows</A></H2>
-
-<P><STRONG>Note: the module name format changed for Windows with Apache
- 1.3.15 and 2.0 - the modules are now named as mod_foo.so</STRONG>.
- While mod_so still loads modules with ApacheModuleFoo.dll names, the
- new naming convention is preferred; if you are converting your loadable
- module for 2.0, please fix the name to this 2.0 convention.</P>
-
-<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
- >AP_MODULE_DECLARE_DATA</CODE> (defined in the Apache header files)
- to your module's module record definition. For example, if your module
- has:</P>
-<PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>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>
+
+ <p>This module provides for loading of executable code and
+ modules into the server at start-up or restart time.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base (Windows);
+ Optional (Unix)<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_so.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ so_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.3 and later.</p>
+
+ <h2>Summary</h2>
+
+ <p>On selected operating systems this module 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.</p>
+
+ <p>On Unix, the loaded code typically comes from shared object
+ files (usually with <samp>.so</samp> extension), on Windows
+ this may either the <samp>.so</samp> or <samp>.dll</samp>
+ extension. This module is only available in Apache 1.3 and
+ up.</p>
+
+ <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.</p>
+
+ <p><strong>Warning: Apache 1.3 modules cannot be directly used
+ with Apache 2.0 - the module must be modified to dynamically
+ load or compile into Apache 2.0</strong>.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#loadfile">LoadFile</a></li>
+
+ <li><a href="#loadmodule">LoadModule</a></li>
+ </ul>
+
+ <h2><a id="creating" name="creating">Creating Loadable Modules
+ for Windows</a></h2>
+
+ <p><strong>Note: the module name format changed for Windows
+ with Apache 1.3.15 and 2.0 - the modules are now named as
+ mod_foo.so</strong>. While mod_so still loads modules with
+ ApacheModuleFoo.dll names, the new naming convention is
+ preferred; if you are converting your loadable module for 2.0,
+ please fix the name to this 2.0 convention.</p>
+
+ <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>AP_MODULE_DECLARE_DATA</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>
+</pre>
+
+ <p>Replace the above with:</p>
+<pre>
module AP_MODULE_DECLARE_DATA 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 libhttpd.lib export library that is created when the
- libhttpd.dll shared library is compiled. You may also have to change
- the compiler settings to ensure that the Apache header files are
- correctly located. You can find this library in your server root's
- modules directory. It is best to grab an existing module .dsp file
- from the tree to assure the build environment is configured correctly,
- or alternately compare the compiler and link options to your .dsp.</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>
-
-<HR>
-
-<H2><A NAME="loadfile">LoadFile</A> directive</H2>
-<!--%plaintext <?INDEX {\tt LoadFile} directive> -->
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> LoadFile <EM>filename</em>
- [<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> 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 an absolute path or relative to <A
-HREF="core.html#serverroot">ServerRoot</A>.<P><HR>
-
-<H2><A NAME="loadmodule">LoadModule</A> directive</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, and is
-listed as the <a href="module-dict.html#ModuleIdentifier">Module
-Identifier</a> in the module documentation. Example:
-<BLOCKQUOTE><CODE>
-LoadModule status_module modules/mod_status.so
-</CODE></BLOCKQUOTE>
-
-<P>loads the named module from the modules subdirectory of the
- ServerRoot.<P>
-
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</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 libhttpd.lib export library that is
+ created when the libhttpd.dll shared library is compiled. You
+ may also have to change the compiler settings to ensure that
+ the Apache header files are correctly located. You can find
+ this library in your server root's modules directory. It is
+ best to grab an existing module .dsp file from the tree to
+ assure the build environment is configured correctly, or
+ alternately compare the compiler and link options to your
+ .dsp.</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>
+ <hr />
+
+ <h2><a id="loadfile" name="loadfile">LoadFile</a>
+ directive</h2>
+ <!--%plaintext <?INDEX {\tt LoadFile} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> LoadFile
+ <em>filename</em> [<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> 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 an absolute path or
+ relative to <a href="core.html#serverroot">ServerRoot</a>.</p>
+ <hr />
+
+ <h2><a id="loadmodule" name="loadmodule">LoadModule</a>
+ directive</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, and is listed as the <a
+ href="module-dict.html#ModuleIdentifier">Module Identifier</a>
+ in the module documentation. Example:</p>
+
+ <blockquote>
+ <code>LoadModule status_module modules/mod_status.so</code>
+ </blockquote>
+
+ <p>loads the named module from the modules subdirectory of the
+ ServerRoot.</p>
+
+ <p><!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
-<!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 attempts to correct misspellings of URLs that users
- might have entered, by ignoring capitalization and by allowing up to
- one misspelling.</P>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_speling.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> speling_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later. Available as an External module in Apache 1.1 and later.
-</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>
-
- <UL>
- <LI><A HREF="#checkspelling">CheckSpelling</A>
- </UL>
-
- <HR> <!-- the HR is part of the directive description -->
- <H2><A NAME="checkspelling">CheckSpelling</A> directive</H2>
- <!--%plaintext <?INDEX {\tt CheckSpelling} directive> -->
- <A
- HREF="directive-dict.html#Syntax"
- REL="Help"
- ><STRONG>Syntax:</STRONG></A> CheckSpelling on|off<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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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 attempts to correct misspellings of URLs that
+ users might have entered, by ignoring capitalization and by
+ allowing up to one misspelling.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_speling.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ speling_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.3 and later. Available as an External module in Apache
+ 1.1 and later.</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,</p>
+
+ <ul>
+ <li>no matching document was found, Apache will proceed as
+ usual and return a "document not found" error.</li>
+
+ <li>only one document is found that "almost" matches the
+ request, then it is returned in the form of a redirection
+ response.</li>
+
+ <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.</li>
+ </ul>
+ <br />
+ <br />
+
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#checkspelling">CheckSpelling</a></li>
+ </ul>
+ <hr />
+ <!-- the HR is part of the directive description -->
+
+ <h2><a id="checkspelling"
+ name="checkspelling">CheckSpelling</a> directive</h2>
+ <!--%plaintext <?INDEX {\tt CheckSpelling} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> CheckSpelling
+ on|off<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>
-<!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" -->
-
-<blockquote><strong>Warning:</strong>
-This document has not been updated to take into account changes
-made in the 2.0 version of the Apache HTTP Server. Some of the
-information may still be relevant, but please use it
-with care.
-</blockquote>
-
-<H1 ALIGN="CENTER">Module mod_status</H1>
-
-<p>This module provides information on server activity and
-performance.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_status.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> status_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.1 and later.
-</P>
-
-
-<H2>Summary</H2>
-
-<p>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>
-
-<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>Directives</h2>
-
-<ul>
-<li><a href="#extendedstatus">ExtendedStatus</a></li>
-</ul>
-
-
-<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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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" -->
+
+ <blockquote>
+ <strong>Warning:</strong> This document has not been updated
+ to take into account changes made in the 2.0 version of the
+ Apache HTTP Server. Some of the information may still be
+ relevant, but please use it with care.
+ </blockquote>
+
+ <h1 align="CENTER">Module mod_status</h1>
+
+ <p>This module provides information on server activity and
+ performance.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_status.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ status_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.1 and later.</p>
+
+ <h2>Summary</h2>
+
+ <p>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>
+
+ <p>The details given are:</p>
+
+ <ul>
+ <li>The number of children serving requests</li>
+
+ <li>The number of idle children</li>
+
+ <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>
+
+ <li>A total number of accesses and byte count served (*)</li>
+
+ <li>The time the server was started/restarted and the time it
+ has been running for</li>
+
+ <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>
+
+ <li>The current percentage CPU used by each child and in
+ total by Apache (*)</li>
+
+ <li>The current hosts and requests being processed (*)</li>
+ </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>Directives</h2>
+
+ <ul>
+ <li><a href="#extendedstatus">ExtendedStatus</a></li>
+ </ul>
+
+ <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
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>
-
-<hr>
-
-<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 On|Off<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>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</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>
+
+ <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.</p>
+
+ <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>
+ <hr />
+
+ <h2><a id="extendedstatus" name="extendedstatus">ExtendedStatus
+ directive</a></h2>
+ <!--%plaintext <?INDEX {\tt ExtendedStatus} directive> -->
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ExtendedStatus
+ On|Off<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>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache module mod_suexec</TITLE>
-</HEAD>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
-<H1 ALIGN="CENTER">Module mod_suexec</H1>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
-<P>
-This module provides support for <A HREF="../suexec.html">
-running CGI scripts as a specified User and Group</A>.
-</P>
+ <title>Apache module mod_suexec</title>
+ </head>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_suexec.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> suexec_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 2.0 and later.
-</P>
+ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
+ vlink="#000080" alink="#FF0000">
+ <!--#include virtual="header.html" -->
-<h2>Summary</h2>
+ <h1 align="CENTER">Module mod_suexec</h1>
-<p>This module allows CGI scripts to run as a specified user and Group.</p>
+ <p>This module provides support for <a
+ href="../suexec.html">running CGI scripts as a specified User
+ and Group</a>.</p>
-<H2>Directives</H2>
-<UL>
- <LI><A HREF="#suexecusergroup">SuexecUserGroup</A>
-</UL>
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mod_suexec.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ suexec_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 2.0 and later.</p>
-<H2><A NAME="suexecusergroup">SuexecUserGroup directive</A></H2>
-<P>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> SuexecUserGroup <EM>User Group</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_suexec<BR>
-<A
- HREF="directive-dict.html#Compatibility"
- REL="Help"
-><STRONG>Compatibility:</STRONG></A> SuexecUserGroup is only available in 2.0 and later.</P>
-<P>
-The <CODE>SuexecUserGroup</CODE> directive allows you to specify a user and
-group for CGI programs to run as. Non-CGI requests are still processes
-with the user specified in the User directive. This directive replaces
-using the User and Group directives inside of VirtualHosts.
-</P>
-<HR>
+ <h2>Summary</h2>
-<H3 ALIGN="CENTER">
- Apache HTTP Server Version 2.0
-</H3>
+ <p>This module allows CGI scripts to run as a specified user
+ and Group.</p>
-<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A>
-<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A>
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#suexecusergroup">SuexecUserGroup</a></li>
+ </ul>
+
+ <h2><a id="suexecusergroup"
+ name="suexecusergroup">SuexecUserGroup directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> SuexecUserGroup
+ <em>User Group</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_suexec<br />
+ <a href="directive-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> SuexecUserGroup
+ is only available in 2.0 and later.</p>
+
+ <p>The <code>SuexecUserGroup</code> directive allows you to
+ specify a user and group for CGI programs to run as. Non-CGI
+ requests are still processes with the user specified in the
+ User directive. This directive replaces using the User and
+ Group directives inside of VirtualHosts.</p>
+ <hr />
+
+ <h3 align="CENTER">Apache HTTP Server Version 2.0</h3>
+ <a href="./"><img src="../images/index.gif" alt="Index" /></a>
+ <a href="../"><img src="../images/home.gif" alt="Home" /></a>
+ </body>
+</html>
-</BODY>
-</HTML>
-<!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>
-
-<p>This module provides an environment variable with a unique identifier
-for each request.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_unique_id.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> unique_id_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later.
-</P>
-
-<h2>Summary</h2>
-
-<p>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.</p>
-
-<h2>Directives</h2>
-
-<p>This module has no directives.</p>
-
-
-<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? 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).
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module provides an environment variable with a unique
+ identifier for each request.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_unique_id.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ unique_id_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.3 and later.</p>
+
+ <h2>Summary</h2>
+
+ <p>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.</p>
+
+ <h2>Directives</h2>
+
+ <p>This module has no directives.</p>
+
+ <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>
+
+ <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>
+
+ <p>The machines in your cluster should satisfy these
+ requirements. (Even if you have only one machine you should
+ synchronize its clock with NTP.)</p>
+
+ <ul>
+ <li>The machines' times are synchronized via NTP or other
+ network time protocol.</li>
+
+ <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.</li>
+ </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>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <p>How good a defense is it? 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>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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).
+ <!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
+
-<!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>
-
-<p>This module provides for user-specific directories.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Base
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_userdir.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> userdir_module
-</P>
-
-<h2>Directives</h2>
-
-
-<UL>
-<LI><A HREF="#userdir">UserDir</A>
-</UL>
-<HR>
-
-<H2><A NAME="userdir">UserDir</A> directive</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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module provides for user-specific directories.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Base<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_userdir.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ userdir_module</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#userdir">UserDir</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="userdir" name="userdir">UserDir</a> directive</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:</p>
+<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>
+</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>
+</pre>
+ <br />
+ <br />
+
+
+ <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>
-<!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>
-
-<p>This module uses cookies to provide for a <em>clickstream</em> log of user
-activity on a site.</p>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_usertrack.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> usertrack_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Known as mod_cookies prior to
-Apache 1.3.
-</P>
-
-<h2>Summary</h2>
-
-<p>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.</p>
-
-<H2>Directives</H2>
-
-<UL>
-<li><a href="#cookiedomain">CookieDomain</a></li>
-<LI><A HREF="#cookieexpires">CookieExpires</A>
-<LI><A HREF="#cookiename">CookieName</A>
-<li><a href="#cookiestyle">CookieStyle</a></li>
-<LI><A HREF="#cookietracking">CookieTracking</A>
-</UL>
-
-<H2>Logging</H2>
-
-<p>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 multiple log files. 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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>
+
+ <p>This module uses cookies to provide for a
+ <em>clickstream</em> log of user activity on a site.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_usertrack.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ usertrack_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Known as
+ mod_cookies prior to Apache 1.3.</p>
-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>Summary</h2>
-<H2>2-digit or 4-digit dates for cookies?</H2>
+ <p>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.</p>
-(the following is from message
-<022701bda43d$9d32bbb0$1201a8c0@christian.office.sane.com> in
-the new-httpd archives)
+ <h2>Directives</h2>
-<P>
+ <ul>
+ <li><a href="#cookiedomain">CookieDomain</a></li>
-<PRE>
+ <li><a href="#cookieexpires">CookieExpires</a></li>
+
+ <li><a href="#cookiename">CookieName</a></li>
+
+ <li><a href="#cookiestyle">CookieStyle</a></li>
+
+ <li><a href="#cookietracking">CookieTracking</a></li>
+ </ul>
+
+ <h2>Logging</h2>
+
+ <p>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 multiple log files. The cookie itself is logged by
+ using the text <tt>%{cookie}n</tt> in the log file format. For
+ example:</p>
+<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>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)
+<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
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>
-
-<hr>
-
-<h2><a name="cookiedomain">CookieDomain</a> directive</h2>
-<a
- href="directive-dict.html#Syntax"
- rel="Help"
-><b>Syntax:</b></a> CookieDomain <i>domain</i><br>
-<a
- href="directive-dict.html#Context"
- rel="Help"
-><b>Context:</b></a> server config, virtual host, directory, .htaccess<br>
-<a
- href="directive-dict.html#Status"
- rel="Help"
-><b>Status:</b></a> optional<br>
-<a
- href="directive-dict.html#Module"
- rel="Help"
-><b>Module:</b></a> mod_usertrack
-
-<p>
-This directive controls the setting of the domain to which the
-tracking cookie applies. If not present, no domain is included
-in the cookie header field.
-</p>
-<p>
-The domain string <b>must</b> begin with a dot, and <b>must</b>
-include at least one embedded dot. That is, ".foo.com" is legal,
-but "foo.bar.com" and ".com" are not.
-</p>
-
-<HR>
-
-<H2><A NAME="cookieexpires">CookieExpires</A> directive</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>
-<b>1.3.20 and earlier:</b> server config, virtual host;
-<b>1.3.21 and later:</b> 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<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>
-
-<HR>
-<H2><A NAME="cookiename">CookieName</A> directive</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>
-
-<hr>
-
-<h2><a name="cookiestyle">CookieStyle</a> directive</h2>
-<a
- href="directive-dict.html#Syntax"
- rel="Help"
-><b>Syntax:</b></a> CookieStyle <i>Netscape|Cookie|Cookie2|RFC2109|RFC2965</i><br>
-<a
- href="directive-dict.html#Context"
- rel="Help"
-><b>Context:</b></a> server config, virtual host, directory, .htaccess<br>
-<a
- href="directive-dict.html#Status"
- rel="Help"
-><b>Status:</b></a> optional<br>
-<a
- href="directive-dict.html#Module"
- rel="Help"
-><b>Module:</b></a> mod_usertrack
-
-<p>
-This directive controls the format of the cookie header field.
-The three formats allowed are:
-</p>
-<ul>
- <li><b>Netscape</b>, which is the original but now deprecated
- syntax. This is the default, and the syntax Apache has
- historically used.</li>
- <li><b>Cookie</b> or <b>RFC2109</b>, which is the syntax that
- superseded the Netscape syntax.</li>
- <li><b>Cookie2</b> or <b>RFC2965</b>, which is the most current
- cookie syntax.</li>
-</ul>
-
-<p>
-Not all clients can understand all of these formats. but you should use
-the newest one that is generally acceptable to your users' browsers.
-</p>
-
-<hr>
-<H2><A NAME="cookietracking">CookieTracking</A> directive</H2>
-<A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> CookieTracking on|off<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.
-
-
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</pre>
+ <hr />
+
+ <h2><a id="cookiedomain" name="cookiedomain">CookieDomain</a>
+ directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><b>Syntax:</b></a> CookieDomain <i>domain</i><br />
+ <a href="directive-dict.html#Context"
+ rel="Help"><b>Context:</b></a> server config, virtual host,
+ directory, .htaccess<br />
+ <a href="directive-dict.html#Status"
+ rel="Help"><b>Status:</b></a> optional<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><b>Module:</b></a> mod_usertrack
+
+ <p>This directive controls the setting of the domain to which
+ the tracking cookie applies. If not present, no domain is
+ included in the cookie header field.</p>
+
+ <p>The domain string <b>must</b> begin with a dot, and
+ <b>must</b> include at least one embedded dot. That is,
+ ".foo.com" is legal, but "foo.bar.com" and ".com" are not.</p>
+ <hr />
+
+ <h2><a id="cookieexpires"
+ name="cookieexpires">CookieExpires</a> directive</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> <b>1.3.20 and
+ earlier:</b> server config, virtual host; <b>1.3.21 and
+ later:</b> 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
+
+ <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>
+
+ <p>If this directive is not used, cookies last only for the
+ current browser session.</p>
+ <hr />
+
+ <h2><a id="cookiename" name="cookiename">CookieName</a>
+ directive</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>
+ <hr />
+
+ <h2><a id="cookiestyle" name="cookiestyle">CookieStyle</a>
+ directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><b>Syntax:</b></a> CookieStyle
+ <i>Netscape|Cookie|Cookie2|RFC2109|RFC2965</i><br />
+ <a href="directive-dict.html#Context"
+ rel="Help"><b>Context:</b></a> server config, virtual host,
+ directory, .htaccess<br />
+ <a href="directive-dict.html#Status"
+ rel="Help"><b>Status:</b></a> optional<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><b>Module:</b></a> mod_usertrack
+
+ <p>This directive controls the format of the cookie header
+ field. The three formats allowed are:</p>
+
+ <ul>
+ <li><b>Netscape</b>, which is the original but now deprecated
+ syntax. This is the default, and the syntax Apache has
+ historically used.</li>
+
+ <li><b>Cookie</b> or <b>RFC2109</b>, which is the syntax that
+ superseded the Netscape syntax.</li>
+
+ <li><b>Cookie2</b> or <b>RFC2965</b>, which is the most
+ current cookie syntax.</li>
+ </ul>
+
+ <p>Not all clients can understand all of these formats. but you
+ should use the newest one that is generally acceptable to your
+ users' browsers.</p>
+ <hr />
+
+ <h2><a id="cookietracking"
+ name="cookietracking">CookieTracking</a> directive</h2>
+ <a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> CookieTracking
+ on|off<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. <!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
+
-<!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"
->
-<!--#include virtual="header.html" -->
-<H1 ALIGN="CENTER">Module mod_vhost_alias</H1>
-
-<P>
-This module provides support for <A
-HREF="../vhosts/mass.html">dynamically configured mass virtual
-hosting</A>.
-</P>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> Extension
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mod_vhost_alias.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> vhost_alias_module
-<BR>
-<A
-HREF="module-dict.html#Compatibility"
-REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3.7 and later.
-</P>
-
-<h2>Summary</h2>
-
-<p>This module creates dynamically configured virtual hosts, by
-allowing the IP address and/or the <code>Host:</code> header of the
-HTTP request to be used as part of the pathname to determine what
-files to serve. This allows for easy use of a huge number of virtual
-hosts with similar configurations.</p>
-
-<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>
-
-<p>See also: <a href="core.html#usecanonicalname">UseCanonicalName</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/vhosts/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/vhosts/%1/%2/%3/%4/docs
- VirtualScriptAliasIP /usr/local/apache/vhosts/%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/vhosts/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/vhosts/10/20/30/40/cgi-bin/script.pl</CODE>.
-</P>
-
-<P>
-If you want to include the <CODE>.</CODE> character in a
-<CODE>VirtualDocumentRoot</CODE> directive, but it clashes with a
-<CODE>%</CODE> directive, you can work around the problem in the
-following way:
-<PRE>
- VirtualDocumentRoot /usr/local/apache/vhosts/%2.0.%3.0
-</PRE>
-A request for <CODE>http://www.example.isp.com/directory/file.html</CODE>
-will be satisfied by the file
-<CODE>/usr/local/apache/vhosts/example.isp/directory/file.html</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><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="virtualscriptaliasip">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> directive 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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="CENTER">Module mod_vhost_alias</h1>
+
+ <p>This module provides support for <a
+ href="../vhosts/mass.html">dynamically configured mass virtual
+ hosting</a>.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> Extension<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a>
+ mod_vhost_alias.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ vhost_alias_module<br />
+ <a href="module-dict.html#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a> Available in
+ Apache 1.3.7 and later.</p>
+
+ <h2>Summary</h2>
+
+ <p>This module creates dynamically configured virtual hosts, by
+ allowing the IP address and/or the <code>Host:</code> header of
+ the HTTP request to be used as part of the pathname to
+ determine what files to serve. This allows for easy use of a
+ huge number of virtual hosts with similar configurations.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a
+ href="#virtualdocumentroot">VirtualDocumentRoot</a></li>
+
+ <li><a
+ href="#virtualdocumentrootip">VirtualDocumentRootIP</a></li>
+
+ <li><a href="#virtualscriptalias">VirtualScriptAlias</a></li>
+
+ <li><a
+ href="#virtualscriptaliasip">VirtualScriptAliasIP</a></li>
+ </ul>
+
+ <p>See also: <a
+ href="core.html#usecanonicalname">UseCanonicalName</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:</p>
+
+ <dl>
+ <dt><code>%%</code></dt>
+
+ <dd>insert a <code>%</code></dd>
+
+ <dt><code>%p</code></dt>
+
+ <dd>insert the port number of the virtual host</dd>
+
+ <dt><code>%N.M</code></dt>
+
+ <dd>insert (part of) the name</dd>
+ </dl>
+ <br />
+ <br />
+
+
+ <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:</p>
+
+ <dl>
+ <dt><code>0</code></dt>
+
+ <dd>the whole name</dd>
+
+ <dt><code>1</code></dt>
+
+ <dd>the first part</dd>
+
+ <dt><code>2</code></dt>
+
+ <dd>the second part</dd>
+
+ <dt><code>-1</code></dt>
+
+ <dd>the last part</dd>
+
+ <dt><code>-2</code></dt>
+
+ <dd>the penultimate part</dd>
+
+ <dt><code>2+</code></dt>
+
+ <dd>the second and all subsequent parts</dd>
+
+ <dt><code>-2+</code></dt>
+
+ <dd>the penultimate and all preceding parts</dd>
+
+ <dt><code>1+</code> and <code>-1+</code></dt>
+
+ <dd>the same as <code>0</code></dd>
+ </dl>
+ If <code>N</code> or <code>M</code> is greater than the number
+ of parts available a single underscore is interpolated. <br />
+ <br />
+
+
+ <h3>Examples</h3>
+
+ <p>For simple name-based virtual hosts you might use the
+ following directives in your server configuration file:</p>
+<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>.
+ <br />
+ <br />
+
+
+ <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:</p>
+<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/vhosts/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>.
+ <br />
+ <br />
+
+
+ <p>For IP-based virtual hosting you might use the following in
+ your configuration file:</p>
+<pre>
+ UseCanonicalName DNS
+ VirtualDocumentRootIP /usr/local/apache/vhosts/%1/%2/%3/%4/docs
+ VirtualScriptAliasIP /usr/local/apache/vhosts/%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/vhosts/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/vhosts/10/20/30/40/cgi-bin/script.pl</code>.
+ <br />
+ <br />
+
+
+ <p>If you want to include the <code>.</code> character in a
+ <code>VirtualDocumentRoot</code> directive, but it clashes with
+ a <code>%</code> directive, you can work around the problem in
+ the following way:</p>
+<pre>
+ VirtualDocumentRoot /usr/local/apache/vhosts/%2.0.%3.0
+</pre>
+ A request for
+ <code>http://www.example.isp.com/directory/file.html</code>
+ will be satisfied by the file
+ <code>/usr/local/apache/vhosts/example.isp/directory/file.html</code>.
+ <br />
+ <br />
+
+
+ <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><a id="virtualdocumentroot"
+ 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 id="virtualdocumentrootip"
+ 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 id="virtualscriptalias"
+ 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 id="virtualscriptaliasip"
+ name="virtualscriptaliasip">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> directive 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>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
- <HEAD>
- <TITLE>Definitions of terms used to describe 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">Terms Used to Describe Apache Modules</H1>
-
- <P>
- Each Apache module is described using a common format that looks
- like this:
- </P>
- <DL>
- <DD><A
- HREF="#Status"
- REL="Help"
- ><STRONG>Status:</STRONG></A> <EM>status</EM>
- <BR>
- <A
- HREF="#SourceFile"
- REL="Help"
- ><STRONG>Source File:</STRONG></A> <EM>source-file</EM>
- <BR>
- <A
- HREF="#ModuleIdentifier"
- REL="Help"
- ><STRONG>Module Identifier:</STRONG></A> <EM>module-identifier</EM>
- <BR>
- <A
- HREF="#Compatibility"
- REL="Help"
- ><STRONG>Compatibility:</STRONG></A> <EM>compatibility notes</EM>
- </DD>
- </DL>
- <P>
- Each of the attributes, complete with values where possible, are
- described in this document.
- </P>
-
- <H2>Module Terms</H2>
- <UL>
- <LI><A HREF="#Status">Status</A>
- </LI>
- <LI><A HREF="#SourceFile">Source File</A>
- </LI>
- <LI><A HREF="#ModuleIdentifier">Module Identifier</A>
- </LI>
- <LI><A HREF="#Compatibility">Compatibility</A>
- </LI>
- </UL>
-
- <HR>
- <H2><A NAME="Status">Status</A></H2>
- <P>
- This indicates how tightly bound into the Apache Web server the
- module is; in other words, you may need to recompile the server in
- order to gain access to the module and its functionality. Possible
- values for this attribute are:
- </P>
- <DL>
- <DT><STRONG>MPM</STRONG>
- </DT>
- <DD>A module with status "MPM" is a <a
- href="../mpm.html">Multi-Processing Module</a>. Unlike the other
- types of modules, Apache must have one and only one MPM in use at
- any time. This type of module is responsible for basic request
- handling and dispatching.
- <P>
- </P>
- <DT><STRONG>Base</STRONG>
- </DT>
- <DD>A module labeled as having "Base" status is compiled
- and loaded into the server by default, and is therefore normally
- available unless you have taken steps to remove the module from your
- configuration.
- <P>
- </P>
- </DD>
- <DT><STRONG>Extension</STRONG>
- </DT>
- <DD>A module with "Extension" status is not normally
- compiled and loaded into the server. To enable the module and its
- functionality, you may 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 module is
- available as part of the Apache kit, but you are on your own if you
- try to use it. The module is being documented for completeness,
- and is not necessarily supported.
- <P>
- </P>
- </DD>
- <DT><STRONG>External</STRONG>
- </DT>
- <DD>Modules which are not included with the base Apache
- distribution ("third-party modules") may use the
- "External" status. We are not responsible for, nor do we
- support such modules.
- <P>
- </P>
- </DD>
- </DL>
-
- <HR>
- <H2><A NAME="SourceFile">Source File</A></H2>
- <P>
- This quite simply lists the name of the source file which contains
- the code for the module. This is also the name used by the <A
- HREF="core.html#ifmodule"><CODE><IfModule></CODE></A>
- directive.
- </P>
-
- <HR>
- <H2><A NAME="ModuleIdentifier">Module Identifier</A></H2>
- <P>
- This is a string which identifies the module for use in the <A
- HREF="mod_so.html#loadmodule">LoadModule</A> directive when
- dynamically loading modules. In particular, it is the name
- of the external variable of type module in the source file.
- </P>
-
- <HR>
- <H2><A NAME="Compatibility">Compatibility</A></H2>
- <P>
- If the module was not part of the original Apache version 2
- distribution, the version in which it was introduced should be listed
- here.
- </P>
-<!--#include virtual="footer.html" -->
- </BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Definitions of terms used to describe 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">Terms Used to Describe Apache Modules</h1>
+
+ <p>Each Apache module is described using a common format that
+ looks like this:</p>
+
+ <dl>
+ <dd><a href="#Status" rel="Help"><strong>Status:</strong></a>
+ <em>status</em><br />
+ <a href="#SourceFile" rel="Help"><strong>Source
+ File:</strong></a> <em>source-file</em><br />
+ <a href="#ModuleIdentifier" rel="Help"><strong>Module
+ Identifier:</strong></a> <em>module-identifier</em><br />
+ <a href="#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a>
+ <em>compatibility notes</em></dd>
+ </dl>
+
+ <p>Each of the attributes, complete with values where possible,
+ are described in this document.</p>
+
+ <h2>Module Terms</h2>
+
+ <ul>
+ <li><a href="#Status">Status</a></li>
+
+ <li><a href="#SourceFile">Source File</a></li>
+
+ <li><a href="#ModuleIdentifier">Module Identifier</a></li>
+
+ <li><a href="#Compatibility">Compatibility</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="Status" name="Status">Status</a></h2>
+
+ <p>This indicates how tightly bound into the Apache Web server
+ the module is; in other words, you may need to recompile the
+ server in order to gain access to the module and its
+ functionality. Possible values for this attribute are:</p>
+
+ <dl>
+ <dt><strong>MPM</strong></dt>
+
+ <dd>A module with status "MPM" is a <a
+ href="../mpm.html">Multi-Processing Module</a>. Unlike the
+ other types of modules, Apache must have one and only one MPM
+ in use at any time. This type of module is responsible for
+ basic request handling and dispatching.</dd>
+
+ <dt><strong>Base</strong></dt>
+
+ <dd>A module labeled as having "Base" status is compiled and
+ loaded into the server by default, and is therefore normally
+ available unless you have taken steps to remove the module
+ from your configuration.</dd>
+
+ <dt><strong>Extension</strong></dt>
+
+ <dd>A module with "Extension" status is not normally compiled
+ and loaded into the server. To enable the module and its
+ functionality, you may need to change the server build
+ configuration files and re-compile Apache.</dd>
+
+ <dt><strong>Experimental</strong></dt>
+
+ <dd>"Experimental" status indicates that the module is
+ available as part of the Apache kit, but you are on your own
+ if you try to use it. The module is being documented for
+ completeness, and is not necessarily supported.</dd>
+
+ <dt><strong>External</strong></dt>
+
+ <dd>Modules which are not included with the base Apache
+ distribution ("third-party modules") may use the "External"
+ status. We are not responsible for, nor do we support such
+ modules.</dd>
+ </dl>
+ <hr />
+
+ <h2><a id="SourceFile" name="SourceFile">Source File</a></h2>
+
+ <p>This quite simply lists the name of the source file which
+ contains the code for the module. This is also the name used by
+ the <a
+ href="core.html#ifmodule"><code><IfModule></code></a>
+ directive.</p>
+ <hr />
+
+ <h2><a id="ModuleIdentifier" name="ModuleIdentifier">Module
+ Identifier</a></h2>
+
+ <p>This is a string which identifies the module for use in the
+ <a href="mod_so.html#loadmodule">LoadModule</a> directive when
+ dynamically loading modules. In particular, it is the name of
+ the external variable of type module in the source file.</p>
+ <hr />
+
+ <h2><a id="Compatibility"
+ name="Compatibility">Compatibility</a></h2>
+
+ <p>If the module was not part of the original Apache version 2
+ distribution, the version in which it was introduced should be
+ listed here.</p>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
- <HEAD>
- <TITLE>Definitions of terms used to describe 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">Terms Used to Describe Apache Modules</H1>
-
- <P>
- Each Apache module is described using a common format that looks
- like this:
- </P>
- <DL>
- <DD><A
- HREF="#Status"
- REL="Help"
- ><STRONG>Status:</STRONG></A> <EM>status</EM>
- <BR>
- <A
- HREF="#SourceFile"
- REL="Help"
- ><STRONG>Source File:</STRONG></A> <EM>source-file</EM>
- <BR>
- <A
- HREF="#ModuleIdentifier"
- REL="Help"
- ><STRONG>Module Identifier:</STRONG></A> <EM>module-identifier</EM>
- <BR>
- <A
- HREF="#Compatibility"
- REL="Help"
- ><STRONG>Compatibility:</STRONG></A> <EM>compatibility notes</EM>
- </DD>
- </DL>
- <P>
- Each of the attributes, complete with values where possible, are
- described in this document.
- </P>
-
- <H2>Module Terms</H2>
- <UL>
- <LI><A HREF="#Status">Status</A>
- </LI>
- <LI><A HREF="#SourceFile">Source File</A>
- </LI>
- <LI><A HREF="#ModuleIdentifier">Module Identifier</A>
- </LI>
- <LI><A HREF="#Compatibility">Compatibility</A>
- </LI>
- </UL>
-
- <HR>
- <H2><A NAME="Status">Status</A></H2>
- <P>
- This indicates how tightly bound into the Apache Web server the
- module is; in other words, you may need to recompile the server in
- order to gain access to the module and its functionality. Possible
- values for this attribute are:
- </P>
- <DL>
- <DT><STRONG>MPM</STRONG>
- </DT>
- <DD>A module with status "MPM" is a <a
- href="../mpm.html">Multi-Processing Module</a>. Unlike the other
- types of modules, Apache must have one and only one MPM in use at
- any time. This type of module is responsible for basic request
- handling and dispatching.
- <P>
- </P>
- <DT><STRONG>Base</STRONG>
- </DT>
- <DD>A module labeled as having "Base" status is compiled
- and loaded into the server by default, and is therefore normally
- available unless you have taken steps to remove the module from your
- configuration.
- <P>
- </P>
- </DD>
- <DT><STRONG>Extension</STRONG>
- </DT>
- <DD>A module with "Extension" status is not normally
- compiled and loaded into the server. To enable the module and its
- functionality, you may 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 module is
- available as part of the Apache kit, but you are on your own if you
- try to use it. The module is being documented for completeness,
- and is not necessarily supported.
- <P>
- </P>
- </DD>
- <DT><STRONG>External</STRONG>
- </DT>
- <DD>Modules which are not included with the base Apache
- distribution ("third-party modules") may use the
- "External" status. We are not responsible for, nor do we
- support such modules.
- <P>
- </P>
- </DD>
- </DL>
-
- <HR>
- <H2><A NAME="SourceFile">Source File</A></H2>
- <P>
- This quite simply lists the name of the source file which contains
- the code for the module. This is also the name used by the <A
- HREF="core.html#ifmodule"><CODE><IfModule></CODE></A>
- directive.
- </P>
-
- <HR>
- <H2><A NAME="ModuleIdentifier">Module Identifier</A></H2>
- <P>
- This is a string which identifies the module for use in the <A
- HREF="mod_so.html#loadmodule">LoadModule</A> directive when
- dynamically loading modules. In particular, it is the name
- of the external variable of type module in the source file.
- </P>
-
- <HR>
- <H2><A NAME="Compatibility">Compatibility</A></H2>
- <P>
- If the module was not part of the original Apache version 2
- distribution, the version in which it was introduced should be listed
- here.
- </P>
-<!--#include virtual="footer.html" -->
- </BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Definitions of terms used to describe 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">Terms Used to Describe Apache Modules</h1>
+
+ <p>Each Apache module is described using a common format that
+ looks like this:</p>
+
+ <dl>
+ <dd><a href="#Status" rel="Help"><strong>Status:</strong></a>
+ <em>status</em><br />
+ <a href="#SourceFile" rel="Help"><strong>Source
+ File:</strong></a> <em>source-file</em><br />
+ <a href="#ModuleIdentifier" rel="Help"><strong>Module
+ Identifier:</strong></a> <em>module-identifier</em><br />
+ <a href="#Compatibility"
+ rel="Help"><strong>Compatibility:</strong></a>
+ <em>compatibility notes</em></dd>
+ </dl>
+
+ <p>Each of the attributes, complete with values where possible,
+ are described in this document.</p>
+
+ <h2>Module Terms</h2>
+
+ <ul>
+ <li><a href="#Status">Status</a></li>
+
+ <li><a href="#SourceFile">Source File</a></li>
+
+ <li><a href="#ModuleIdentifier">Module Identifier</a></li>
+
+ <li><a href="#Compatibility">Compatibility</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="Status" name="Status">Status</a></h2>
+
+ <p>This indicates how tightly bound into the Apache Web server
+ the module is; in other words, you may need to recompile the
+ server in order to gain access to the module and its
+ functionality. Possible values for this attribute are:</p>
+
+ <dl>
+ <dt><strong>MPM</strong></dt>
+
+ <dd>A module with status "MPM" is a <a
+ href="../mpm.html">Multi-Processing Module</a>. Unlike the
+ other types of modules, Apache must have one and only one MPM
+ in use at any time. This type of module is responsible for
+ basic request handling and dispatching.</dd>
+
+ <dt><strong>Base</strong></dt>
+
+ <dd>A module labeled as having "Base" status is compiled and
+ loaded into the server by default, and is therefore normally
+ available unless you have taken steps to remove the module
+ from your configuration.</dd>
+
+ <dt><strong>Extension</strong></dt>
+
+ <dd>A module with "Extension" status is not normally compiled
+ and loaded into the server. To enable the module and its
+ functionality, you may need to change the server build
+ configuration files and re-compile Apache.</dd>
+
+ <dt><strong>Experimental</strong></dt>
+
+ <dd>"Experimental" status indicates that the module is
+ available as part of the Apache kit, but you are on your own
+ if you try to use it. The module is being documented for
+ completeness, and is not necessarily supported.</dd>
+
+ <dt><strong>External</strong></dt>
+
+ <dd>Modules which are not included with the base Apache
+ distribution ("third-party modules") may use the "External"
+ status. We are not responsible for, nor do we support such
+ modules.</dd>
+ </dl>
+ <hr />
+
+ <h2><a id="SourceFile" name="SourceFile">Source File</a></h2>
+
+ <p>This quite simply lists the name of the source file which
+ contains the code for the module. This is also the name used by
+ the <a
+ href="core.html#ifmodule"><code><IfModule></code></a>
+ directive.</p>
+ <hr />
+
+ <h2><a id="ModuleIdentifier" name="ModuleIdentifier">Module
+ Identifier</a></h2>
+
+ <p>This is a string which identifies the module for use in the
+ <a href="mod_so.html#loadmodule">LoadModule</a> directive when
+ dynamically loading modules. In particular, it is the name of
+ the external variable of type module in the source file.</p>
+ <hr />
+
+ <h2><a id="Compatibility"
+ name="Compatibility">Compatibility</a></h2>
+
+ <p>If the module was not part of the original Apache version 2
+ distribution, the version in which it was introduced should be
+ listed here.</p>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache MPM Common 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">Multi-Processing Module Common Directives</H1>
-
-<P>This file documents directives that are implemented by more
-than one multi-processing module (MPM).
-</P>
-
-<H2>Directives</H2>
-<UL>
-<li><a href="#connectionstatus">ConnectionStatus</a></li>
-<li><a href="#coredumpdirectory">CoreDumpDirectory</a></li>
-<li><a href="#group">Group</a></li>
-<li><a href="#pidfile">PidFile</a></li>
-<li><a href="#listen">Listen</a></li>
-<li><a href="#listenbacklog">ListenBacklog</a></li>
-<li><a href="#lockfile">LockFile</a></li>
-<li><a href="#maxclients">MaxClients</a></li>
-<li><a href="#maxrequestsperchild">MaxRequestsPerChild</a></li>
-<li><a href="#maxsparethreads">MaxSpareThreads</a></li>
-<li><a href="#maxthreadsperchild">MaxThreadsPerChild</a></li>
-<li><a href="#minsparethreads">MinSpareThreads</a></li>
-<li><a href="#numservers">NumServers</a></li>
-<li><a href="#scoreboardfile">ScoreBoardFile</a></li>
-<li><a href="#sendbuffersize">SendBufferSize</a></li>
-<li><a href="#startservers">StartServers</a></li>
-<li><a href="#startthreads">StartThreads</a></li>
-<li><a href="#threadsperchild">ThreadsPerChild</a></li>
-<li><a href="#user">User</a></li>
-</UL>
-<HR>
-
-<H2><A NAME="connectionstatus">ConnectionStatus directive</A></H2>
-<p><A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A>
- ConnectionStatus on|off<BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A>
- <CODE>ConnectionStatus 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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> perchild</p>
-
-<p>Whether or not to maintain status information on current
-connections. If this is off then mod_status will not work properly.</p>
-
-<hr>
-
-<H2><A NAME="coredumpdirectory">CoreDumpDirectory directive</A></H2>
-<!--%plaintext <?INDEX {\tt CoreDumpDirectory} directive> -->
-<p><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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, perchild, prefork, mpm_winnt</p>
-
-<p>This controls the directory to which Apache attempts to switch
-before dumping core. The default is in the <A
-HREF="core.html#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="group">Group directive</A></H2>
-<!--%plaintext <?INDEX {\tt Group} directive> -->
-<p><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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, perchild, prefork</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< is no longer
-supported. To implement the <A HREF="../suexec.html">suEXEC wrapper</A>
-with Apache 2.0, use the <A HREF=mod_suexec.html#suexecusergroup>
-SuexecUserGroup</A> directive.
-
-SECURITY: See <A HREF="#user">User</A> for a discussion of the security
-considerations.<P><HR>
-
-<H2><A NAME="pidfile">PidFile directive</A></H2>
-<!--%plaintext <?INDEX {\tt PidFile} directive> -->
-<p><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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, perchild, prefork, mpm_winnt</p>
-
-<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="core.html#serverroot">ServerRoot</A>.</p>
-
-<p>It is often useful to be able to send the server a signal, so that
-it closes and then reopens its <A
-HREF="core.html#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>
-
-<p>The PidFile is subject to the same warnings about log file placement and
-<A HREF="../misc/security_tips.html#serverroot">security</A>.</p>
-
-<p><hr>
-
-<H2><A NAME="listen">Listen directive</A></H2>
-<p><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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, perchild, prefork, mpm_winnt</p>
-
-
-<P>The Listen directive instructs Apache to listen to only specific IP
-addresses or ports; by default it responds to requests on all IP
-interfaces, but only on the port given by the <CODE><A
-HREF="core.html#port">Port</A></CODE> directive.</P>
-
-<p>The Listen directive tells
-the server to accept incoming requests on the specified port or
-address-and-port combination. If only a port number is specified,
-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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache MPM Common 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">Multi-Processing Module Common
+ Directives</h1>
+
+ <p>This file documents directives that are implemented by more
+ than one multi-processing module (MPM).</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#connectionstatus">ConnectionStatus</a></li>
+
+ <li><a href="#coredumpdirectory">CoreDumpDirectory</a></li>
+
+ <li><a href="#group">Group</a></li>
+
+ <li><a href="#pidfile">PidFile</a></li>
+
+ <li><a href="#listen">Listen</a></li>
+
+ <li><a href="#listenbacklog">ListenBacklog</a></li>
+
+ <li><a href="#lockfile">LockFile</a></li>
+
+ <li><a href="#maxclients">MaxClients</a></li>
+
+ <li><a
+ href="#maxrequestsperchild">MaxRequestsPerChild</a></li>
+
+ <li><a href="#maxsparethreads">MaxSpareThreads</a></li>
+
+ <li><a href="#maxthreadsperchild">MaxThreadsPerChild</a></li>
+
+ <li><a href="#minsparethreads">MinSpareThreads</a></li>
+
+ <li><a href="#numservers">NumServers</a></li>
+
+ <li><a href="#scoreboardfile">ScoreBoardFile</a></li>
+
+ <li><a href="#sendbuffersize">SendBufferSize</a></li>
+
+ <li><a href="#startservers">StartServers</a></li>
+
+ <li><a href="#startthreads">StartThreads</a></li>
+
+ <li><a href="#threadsperchild">ThreadsPerChild</a></li>
+
+ <li><a href="#user">User</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="connectionstatus"
+ name="connectionstatus">ConnectionStatus directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> ConnectionStatus
+ on|off<br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> <code>ConnectionStatus
+ 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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> perchild</p>
+
+ <p>Whether or not to maintain status information on current
+ connections. If this is off then mod_status will not work
+ properly.</p>
+ <hr />
+
+ <h2><a id="coredumpdirectory"
+ name="coredumpdirectory">CoreDumpDirectory directive</a></h2>
+ <!--%plaintext <?INDEX {\tt CoreDumpDirectory} directive> -->
+
+ <p><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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, perchild,
+ prefork, mpm_winnt</p>
+
+ <p>This controls the directory to which Apache attempts to
+ switch before dumping core. The default is in the <a
+ href="core.html#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 id="group" name="group">Group directive</a></h2>
+ <!--%plaintext <?INDEX {\tt Group} directive> -->
+
+ <p><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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, perchild,
+ prefork</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</dt>
+
+ <dd>Refers to the given group by name.</dd>
+
+ <dt># followed by a group number.</dt>
+
+ <dd>Refers to a group by its number.</dd>
+ </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>
+
+ <p>Special note: Use of this directive in <VirtualHost<
+ is no longer supported. To implement the <a
+ href="../suexec.html">suEXEC wrapper</a> with Apache 2.0, use
+ the <a
+ href="mod_suexec.html#suexecusergroup">SuexecUserGroup</a>
+ directive. SECURITY: See <a href="#user">User</a> for a
+ discussion of the security considerations.</p>
+ <hr />
+
+ <h2><a id="pidfile" name="pidfile">PidFile directive</a></h2>
+ <!--%plaintext <?INDEX {\tt PidFile} directive> -->
+
+ <p><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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, perchild,
+ prefork, mpm_winnt</p>
+
+ <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="core.html#serverroot">ServerRoot</a>.</p>
+
+ <p>It is often useful to be able to send the server a signal,
+ so that it closes and then reopens its <a
+ href="core.html#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>
+
+ <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 id="listen" name="listen">Listen directive</a></h2>
+
+ <p><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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, perchild,
+ prefork, mpm_winnt</p>
+
+ <p>The Listen directive instructs Apache to listen to only
+ specific IP addresses or ports; by default it responds to
+ requests on all IP interfaces, but only on the port given by
+ the <code><a href="core.html#port">Port</a></code>
+ directive.</p>
+
+ <p>The Listen directive tells the server to accept incoming
+ requests on the specified port or address-and-port combination.
+ If only a port number is specified, 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>
+
+ <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>
+
+ <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>
+
+ <p>For example, to make the server accept connections on both
+ port 80 and port 8000, use:</p>
+<pre>
Listen 80
Listen 8000
-</PRE>
-
-To make the server accept connections on two specified
-interfaces and port numbers, use
-<PRE>
+</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>
-<p><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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, perchild, prefork, mpm_winnt</p>
-
-<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="lockfile">LockFile directive</A></H2>
-<p><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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, perchild, prefork</p>
-
-<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>
-
-<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>
-
-<hr>
-
-<H2><A NAME="maxclients">MaxClients directive</A></H2>
-<!--%plaintext <?INDEX {\tt MaxClients} directive> -->
-<p><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 8</code> (with threads)
-<code>MaxClients 256</code> (no threads)<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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, prefork</p>
-
-<P>The MaxClients directive sets the limit on the number of child
-processes that will be created to serve requests. When the server is
-built without threading, no more than this number of clients can be
-served simultaneously. To configure more than 256 clients, you must
-edit the <code>HARD_SERVER_LIMIT</code> entry in
-<code>mpm_default.h</code> 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.</p>
-
-<p>When the server is compiled with threading, then the maximum number
-of simultaneous requests that can be served is obtained from the value
-of this directive multiplied by <a
-href="#threadsperchild">ThreadsPerChild</a>.</p>
-
-<HR>
-
-<H2><A NAME="maxrequestsperchild">MaxRequestsPerChild directive</A></H2>
-<!--%plaintext <?INDEX {\tt MaxRequestsPerChild} directive> -->
-<p><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 10000</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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, prefork, perchild, mpm_winnt</p>
-
-<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><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="maxsparethreads">MaxSpareThreads directive</A></H2>
-<p><A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> MaxSpareThreads <EM>number</EM><BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> <CODE>MaxSpareThreads 10 (Perchild) or 500 (threaded) </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#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, perchild</p>
-
-<P>Maximum number of idle threads. Different MPMs deal with this directive
-differently. Perchild monitor the number of idle threads on a
-per-child basis. If there are too many idle threads in that child, the server
-will begin to kill threads within that child.</P>
-<P>threaded deals with idle threads on a server-wide basis. If there are
-too many idle threads in the server then child processes are killed
-until the number of idle threads is less than this number.</p>
-
-<p>See also <A HREF="#minsparethreads">MinSpareThreads</A> and
-<A HREF="#startservers">StartServers</A>.
-
-<P><HR>
-
-<H2><A NAME="maxthreadsperchild">MaxThreadsPerChild directive</A></H2>
-<p><A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> MaxThreadsPerChild <EM>number</EM><BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> <CODE>MaxThreadsPerChild 64</code>
-<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#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, perchild</p>
-
-<P>Maximum number of threads per child. For MPMs with a variable
-number of threads per child, this directive sets the maximum number of
-threads that will be created in each child process. To increase this
-value beyond its default, it is necessary to change the value of
-the compile-time define <code>HARD_THREAD_LIMIT</code> and recompile
-the server.</p>
-
-<P><HR>
-
-<H2><A NAME="minsparethreads">MinSpareThreads directive</A></H2>
-<!--%plaintext <?INDEX {\tt MinSpareServers} directive> -->
-<p><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>MaxSpareThreads 5 (Perchild) or 250 (threaded) </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#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, perchild</p>
-
-<P>Minimum number of idle threads to handle request spikes. Different MPMs
-deal with this directive differently. Perchild monitor the number
-of idle threads on a per-child basis. If there aren't enough idle threads in
-that child, the server will begin to create new threads within that child.
-</P>
-<P>threaded deals with idle threads on a server-wide basis. If there
-aren't enough idle threads in the server then child processes are created
-until the number of idle threads is greater than number.</p>
-
-See also <A HREF="#maxsparethreads">MaxSpareThreads</A> and
-<A HREF="#startservers">StartServers</A>.<P><HR>
-
-
-<H2><A NAME="numservers">NumServers directive</A></H2>
-<p><A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> NumServers <EM>number</EM><BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> <CODE>NumServers 2</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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> perchild</p>
-
-<p>Number of children alive at the same time. MPMs that use this directive
-do not dynamically create new child processes so this number should be
-large enough to handle the requests for the entire site.</p>
-
-<hr>
-
-<H2><A NAME="scoreboardfile">ScoreBoardFile directive</A></H2>
-<!--%plaintext <?INDEX {\tt ScoreBoardFile} directive> -->
-<p><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> MPM<BR>
-<A
- HREF="directive-dict.html#Compatibility"
- REL="Help"
-></a>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, perchild, prefork</p>
-
-<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>
-
-<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>
-
-<p><STRONG>See Also</STRONG>:
-<A HREF="../stopping.html">Stopping and Restarting Apache</A></P>
-
-
-<P><HR>
-
-<H2><A NAME="sendbuffersize">SendBufferSize directive</A></H2>
-<!--%plaintext <?INDEX {\tt SendBufferSize} directive> -->
-<p><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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, perchild, prefork, mpm_winnt</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="startservers">StartServers directive</A></H2>
-<!--%plaintext <?INDEX {\tt StartServers} directive> -->
-<p><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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, prefork</p>
-
-<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>See also <A HREF="#minsparethreads">MinSpareThreads</A> and
-<A HREF="#maxsparethreads">MaxSpareThreads</A>.<P><HR>
-
-
-<H2><A NAME="startthreads">StartThreads directive</A></H2>
-<p><A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> StartThreads <EM>number</EM><BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> <CODE>StartThreads 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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> perchild</p>
-
-<p>Number of threads each child creates on startup. As the number of threads
-is dynamically controlled depending on the load, there is usually little
-reason to adjust this parameter.</p>
-
-<hr>
-
-<H2><A NAME="threadsperchild">ThreadsPerChild</A></H2>
-<p><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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, mpm_winnt</p>
-
-<P>This directive sets the number of threads created by each child
-process. The child creates these threads at startup and never creates
-more. if using an MPM like mpmt_winnt, where there is only one child process,
-this number should be high enough to handle the entire load of the server.
-If using an MPM like threaded, where there are multiple child processes,
-the total number of threads should be high enough to handle the common load
-on the server.</p>
-
-<p><hr>
-
-
-<H2><A NAME="user">User directive</A></H2>
-<!--%plaintext <?INDEX {\tt User} directive> -->
-<p><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<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> threaded, perchild, prefork</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 <A HREF="mod_proxy.html">mod_proxy's</A> <CODE>CacheRoot</CODE>
-directive).<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> is no longer
-supported. To configure your server for <A HREF="mod_suexec.html">
-suexec</A> use <A HREF="mod_suexec.html#suexecusergroup">SuexecUserGroup</A>.
-
-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>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</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 id="listenbacklog" name="listenbacklog">ListenBacklog
+ directive</a></h2>
+
+ <p><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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, perchild,
+ prefork, mpm_winnt</p>
+
+ <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>
+
+ <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.</p>
+ <hr />
+
+ <h2><a id="lockfile" name="lockfile">LockFile
+ directive</a></h2>
+
+ <p><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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, perchild,
+ prefork</p>
+
+ <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>
+
+ <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>
+ <hr />
+
+ <h2><a id="maxclients" name="maxclients">MaxClients
+ directive</a></h2>
+ <!--%plaintext <?INDEX {\tt MaxClients} directive> -->
+
+ <p><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
+ 8</code> (with threads) <code>MaxClients 256</code> (no
+ threads)<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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, prefork</p>
+
+ <p>The MaxClients directive sets the limit on the number of
+ child processes that will be created to serve requests. When
+ the server is built without threading, no more than this number
+ of clients can be served simultaneously. To configure more than
+ 256 clients, you must edit the <code>HARD_SERVER_LIMIT</code>
+ entry in <code>mpm_default.h</code> and recompile.</p>
+
+ <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.</p>
+
+ <p>When the server is compiled with threading, then the maximum
+ number of simultaneous requests that can be served is obtained
+ from the value of this directive multiplied by <a
+ href="#threadsperchild">ThreadsPerChild</a>.</p>
+ <hr />
+
+ <h2><a id="maxrequestsperchild"
+ name="maxrequestsperchild">MaxRequestsPerChild
+ directive</a></h2>
+ <!--%plaintext <?INDEX {\tt MaxRequestsPerChild} directive> -->
+
+ <p><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 10000</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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, prefork,
+ perchild, mpm_winnt</p>
+
+ <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>
+
+ <p>Setting MaxRequestsPerChild to a non-zero limit has two
+ beneficial effects:</p>
+
+ <ul>
+ <li>it limits the amount of memory that process can consume
+ by (accidental) memory leakage;</li>
+
+ <li>by giving processes a finite lifetime, it helps reduce
+ the number of processes when the server load reduces.</li>
+ </ul>
+
+ <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 id="maxsparethreads"
+ name="maxsparethreads">MaxSpareThreads directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> MaxSpareThreads
+ <em>number</em><br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> <code>MaxSpareThreads
+ 10 (Perchild) or 500 (threaded)</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#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, perchild</p>
+
+ <p>Maximum number of idle threads. Different MPMs deal with
+ this directive differently. Perchild monitor the number of idle
+ threads on a per-child basis. If there are too many idle
+ threads in that child, the server will begin to kill threads
+ within that child.</p>
+
+ <p>threaded deals with idle threads on a server-wide basis. If
+ there are too many idle threads in the server then child
+ processes are killed until the number of idle threads is less
+ than this number.</p>
+
+ <p>See also <a href="#minsparethreads">MinSpareThreads</a> and
+ <a href="#startservers">StartServers</a>.</p>
+ <hr />
+
+ <h2><a id="maxthreadsperchild"
+ name="maxthreadsperchild">MaxThreadsPerChild directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> MaxThreadsPerChild
+ <em>number</em><br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a>
+ <code>MaxThreadsPerChild 64</code> <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#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, perchild</p>
+
+ <p>Maximum number of threads per child. For MPMs with a
+ variable number of threads per child, this directive sets the
+ maximum number of threads that will be created in each child
+ process. To increase this value beyond its default, it is
+ necessary to change the value of the compile-time define
+ <code>HARD_THREAD_LIMIT</code> and recompile the server.</p>
+ <hr />
+
+ <h2><a id="minsparethreads"
+ name="minsparethreads">MinSpareThreads directive</a></h2>
+ <!--%plaintext <?INDEX {\tt MinSpareServers} directive> -->
+
+ <p><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>MaxSpareThreads
+ 5 (Perchild) or 250 (threaded)</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#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, perchild</p>
+
+ <p>Minimum number of idle threads to handle request spikes.
+ Different MPMs deal with this directive differently. Perchild
+ monitor the number of idle threads on a per-child basis. If
+ there aren't enough idle threads in that child, the server will
+ begin to create new threads within that child.</p>
+
+ <p>threaded deals with idle threads on a server-wide basis. If
+ there aren't enough idle threads in the server then child
+ processes are created until the number of idle threads is
+ greater than number.</p>
+ See also <a href="#maxsparethreads">MaxSpareThreads</a> and <a
+ href="#startservers">StartServers</a>.
+ <hr />
+
+ <h2><a id="numservers" name="numservers">NumServers
+ directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> NumServers
+ <em>number</em><br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> <code>NumServers
+ 2</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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> perchild</p>
+
+ <p>Number of children alive at the same time. MPMs that use
+ this directive do not dynamically create new child processes so
+ this number should be large enough to handle the requests for
+ the entire site.</p>
+ <hr />
+
+ <h2><a id="scoreboardfile" name="scoreboardfile">ScoreBoardFile
+ directive</a></h2>
+ <!--%plaintext <?INDEX {\tt ScoreBoardFile} directive> -->
+
+ <p><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> MPM<br />
+ <a href="directive-dict.html#Compatibility" rel="Help"></a> <a
+ href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, perchild,
+ prefork</p>
+
+ <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>
+
+ <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>
+
+ <p><strong>See Also</strong>: <a
+ href="../stopping.html">Stopping and Restarting Apache</a></p>
+ <hr />
+
+ <h2><a id="sendbuffersize" name="sendbuffersize">SendBufferSize
+ directive</a></h2>
+ <!--%plaintext <?INDEX {\tt SendBufferSize} directive> -->
+
+ <p><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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, perchild,
+ prefork, mpm_winnt</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)
+ <hr />
+
+ <h2><a id="startservers" name="startservers">StartServers
+ directive</a></h2>
+ <!--%plaintext <?INDEX {\tt StartServers} directive> -->
+
+ <p><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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, prefork</p>
+
+ <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>See also <a href="#minsparethreads">MinSpareThreads</a> and
+ <a href="#maxsparethreads">MaxSpareThreads</a>.</p>
+ <hr />
+
+ <h2><a id="startthreads" name="startthreads">StartThreads
+ directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> StartThreads
+ <em>number</em><br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> <code>StartThreads
+ 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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> perchild</p>
+
+ <p>Number of threads each child creates on startup. As the
+ number of threads is dynamically controlled depending on the
+ load, there is usually little reason to adjust this
+ parameter.</p>
+ <hr />
+
+ <h2><a id="threadsperchild"
+ name="threadsperchild">ThreadsPerChild</a></h2>
+
+ <p><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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, mpm_winnt</p>
+
+ <p>This directive sets the number of threads created by each
+ child process. The child creates these threads at startup and
+ never creates more. if using an MPM like mpmt_winnt, where
+ there is only one child process, this number should be high
+ enough to handle the entire load of the server. If using an MPM
+ like threaded, where there are multiple child processes, the
+ total number of threads should be high enough to handle the
+ common load on the server.</p>
+ <hr />
+
+ <h2><a id="user" name="user">User directive</a></h2>
+ <!--%plaintext <?INDEX {\tt User} directive> -->
+
+ <p><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<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> threaded, perchild,
+ prefork</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</dt>
+
+ <dd>Refers to the given user by name.</dd>
+
+ <dt># followed by a user number.</dt>
+
+ <dd>Refers to a user by their number.</dd>
+ </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 <a
+ href="mod_proxy.html">mod_proxy's</a> <code>CacheRoot</code>
+ directive).
+
+ <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>
+
+ <p>Special note: Use of this directive in <VirtualHost>
+ is no longer supported. To configure your server for <a
+ href="mod_suexec.html">suexec</a> use <a
+ href="mod_suexec.html#suexecusergroup">SuexecUserGroup</a>.
+ 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>
+
+ <p><!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache MPM pthread</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">Multi-Processing Module mpm_winnt</H1>
-<P>
-This Multi-Processing Module is optimized for Windows NT.
-</P>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> MPM
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> mpm_winnt.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> mpm_winnt_module
-</P>
-
-<H2>Summary</H2>
-
-<p>This Multi-Processing Module (MPM) is the default for
-the Windows NT operating systems. It uses a single control
-process which launches a single child process which in turn
-creates threads to handle requests</p>
-
-
-<H2>Directives</H2>
-<UL>
-<li><a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li>
-<li><a href="mpm_common.html#pidfile">PidFile</a></li>
-<li><a href="mpm_common.html#listen">Listen</a></li>
-<li><a href="mpm_common.html#listenbacklog">ListenBacklog</a></li>
-<li><a href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li>
-<li><a href="mpm_common.html#sendbuffersize">SendBufferSize</a></li>
-<li><a href="mpm_common.html#threadsperchild">ThreadsPerChild</a></li>
-</UL>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache MPM pthread</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">Multi-Processing Module mpm_winnt</h1>
+
+ <p>This Multi-Processing Module is optimized for Windows
+ NT.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> MPM<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> mpm_winnt.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ mpm_winnt_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This Multi-Processing Module (MPM) is the default for the
+ Windows NT operating systems. It uses a single control process
+ which launches a single child process which in turn creates
+ threads to handle requests</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a
+ href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li>
+
+ <li><a href="mpm_common.html#pidfile">PidFile</a></li>
+
+ <li><a href="mpm_common.html#listen">Listen</a></li>
+
+ <li><a
+ href="mpm_common.html#listenbacklog">ListenBacklog</a></li>
+
+ <li><a
+ href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li>
+
+ <li><a
+ href="mpm_common.html#sendbuffersize">SendBufferSize</a></li>
+
+ <li><a
+ href="mpm_common.html#threadsperchild">ThreadsPerChild</a></li>
+ </ul>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache MPM perchild</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">Multi-Processing Module perchild</H1>
-<P>
-This Multi-Processing Module allows for daemon processes serving requests
-to be assigned a variety of different userids.
-</P>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> MPM
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> perchild.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> mpm_perchild_module
-</P>
-
-<H2>Summary</H2>
-
-<p>This Multi-Processing Module (MPM) implements a hybrid
-multi-process, multi-threaded web server. A fixed number of processes
-create threads to handle requests. Fluctuations in load are handled
-by increasing or decreasing the number of threads in each process.</p>
-
-<p>A single control process launches the number of child processes
-indicated by the <code>NumServers</code> directive at server startup.
-Each child process creates threads as specified in the
-<code>StartThreads</code> directive. The individual threads then
-listen for connections and serve them when they arrive.</p>
-
-<p>Apache always tries to maintain a pool of <em>spare</em> or idle
-server threads, which stand ready to serve incoming requests. In this
-way, clients do not need to wait for new threads to be created. For
-each child process, Apache assesses the number of idle threads and
-creates or destroys threads to keep this number within the boundaries
-specified by <code>MinSpareThreads</code> and
-<code>MaxSpareThreads</code>. Since this process is very
-self-regulating, it is rarely necessary to modify these directives
-from their default values. The maximum number of clients that may be
-served simultaneously is determined by multiplying the number
-of server processes that will be created (<code>NumServers</code>) by
-the maximum number of threads created in each process
-(<code>MaxThreadsPerChild</code>).</p>
-
-<p>While the parent process is usually started as root under Unix in
-order to bind to port 80, the child processes and threads are launched
-by Apache as a less-privileged user. The <code>User</code> and
-<code>Group</code> directives are used to set the privileges of the
-Apache child processes. The child processes must be able to read all
-the content that will be served, but should have as few privileges
-beyond that as possible. In addition, unless <a
-href="../suexec.html">suexec</a> is used, these directives also set
-the privileges which will be inherited by CGI scripts.</p>
-
-<p><code>MaxRequestsPerChild</code> controls how frequently the server
-recycles processes by killing old ones and launching new ones.</p>
-
-<p>See also: <a href="../bind.html">Setting which addresses and ports
-Apache uses</a>.</p>
-
-<p>In addition it adds the extra ability to specify that specific processes
-should serve requests under different userids. These processes can
-then be associated with specific virtual hosts.</p>
-
-<!-- XXX: This desperately needs more explanation. -->
-
-
-<H2>Directives</H2>
-<UL>
-<li><a href="#assignuserid">AssignUserID</a></li>
-<li><a href="#childperuserid">ChildPerUserID</a></li>
-<li><a href="mpm_common.html#connectionstatus">ConnectionStatus</a></li>
-<li><a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li>
-<li><a href="mpm_common.html#group">Group</a></li>
-<li><a href="mpm_common.html#pidfile">PidFile</a></li>
-<li><a href="mpm_common.html#listen">Listen</a></li>
-<li><a href="mpm_common.html#listenbacklog">ListenBacklog</a></li>
-<li><a href="mpm_common.html#lockfile">LockFile</a></li>
-<li><a href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li>
-<li><a href="mpm_common.html#maxsparethreads">MaxSpareThreads</a></li>
-<li><a href="mpm_common.html#maxthreadsperchild">MaxThreadsPerChild</a></li>
-<li><a href="mpm_common.html#minsparethreads">MinSpareThreads</a></li>
-<li><a href="mpm_common.html#numservers">NumServers</a></li>
-<li><a href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li>
-<li><a href="mpm_common.html#sendbuffersize">SendBufferSize</a></li>
-<li><a href="mpm_common.html#startthreads">StartThreads</a></li>
-<li><a href="mpm_common.html#user">User</a></li>
-</UL>
-
-<hr>
-
-<H2><A NAME="assignuserid">AssignUserID directive</A></H2>
-<p><A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A><BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A><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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> perchild</p>
-
-<p>Tie a virtual host to a specific child process.</p>
-
-<hr>
-
-<H2><A NAME="childperuserid">ChildPerUserID directive</A></H2>
-<p><A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A><BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A><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> MPM<BR>
-<A
- HREF="directive-dict.html#Module"
- REL="Help"
-><STRONG>Module:</STRONG></A> perchild</p>
-
-<p>Specify a User and Group for a specific child process.</p>
-
-
-
-
-
-<!--#include virtual="footer.html" -->
-
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache MPM perchild</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">Multi-Processing Module perchild</h1>
+
+ <p>This Multi-Processing Module allows for daemon processes
+ serving requests to be assigned a variety of different
+ userids.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> MPM<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> perchild.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ mpm_perchild_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This Multi-Processing Module (MPM) implements a hybrid
+ multi-process, multi-threaded web server. A fixed number of
+ processes create threads to handle requests. Fluctuations in
+ load are handled by increasing or decreasing the number of
+ threads in each process.</p>
+
+ <p>A single control process launches the number of child
+ processes indicated by the <code>NumServers</code> directive at
+ server startup. Each child process creates threads as specified
+ in the <code>StartThreads</code> directive. The individual
+ threads then listen for connections and serve them when they
+ arrive.</p>
+
+ <p>Apache always tries to maintain a pool of <em>spare</em> or
+ idle server threads, which stand ready to serve incoming
+ requests. In this way, clients do not need to wait for new
+ threads to be created. For each child process, Apache assesses
+ the number of idle threads and creates or destroys threads to
+ keep this number within the boundaries specified by
+ <code>MinSpareThreads</code> and <code>MaxSpareThreads</code>.
+ Since this process is very self-regulating, it is rarely
+ necessary to modify these directives from their default values.
+ The maximum number of clients that may be served simultaneously
+ is determined by multiplying the number of server processes
+ that will be created (<code>NumServers</code>) by the maximum
+ number of threads created in each process
+ (<code>MaxThreadsPerChild</code>).</p>
+
+ <p>While the parent process is usually started as root under
+ Unix in order to bind to port 80, the child processes and
+ threads are launched by Apache as a less-privileged user. The
+ <code>User</code> and <code>Group</code> directives are used to
+ set the privileges of the Apache child processes. The child
+ processes must be able to read all the content that will be
+ served, but should have as few privileges beyond that as
+ possible. In addition, unless <a
+ href="../suexec.html">suexec</a> is used, these directives also
+ set the privileges which will be inherited by CGI scripts.</p>
+
+ <p><code>MaxRequestsPerChild</code> controls how frequently the
+ server recycles processes by killing old ones and launching new
+ ones.</p>
+
+ <p>See also: <a href="../bind.html">Setting which addresses and
+ ports Apache uses</a>.</p>
+
+ <p>In addition it adds the extra ability to specify that
+ specific processes should serve requests under different
+ userids. These processes can then be associated with specific
+ virtual hosts.</p>
+ <!-- XXX: This desperately needs more explanation. -->
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#assignuserid">AssignUserID</a></li>
+
+ <li><a href="#childperuserid">ChildPerUserID</a></li>
+
+ <li><a
+ href="mpm_common.html#connectionstatus">ConnectionStatus</a></li>
+
+ <li><a
+ href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li>
+
+ <li><a href="mpm_common.html#group">Group</a></li>
+
+ <li><a href="mpm_common.html#pidfile">PidFile</a></li>
+
+ <li><a href="mpm_common.html#listen">Listen</a></li>
+
+ <li><a
+ href="mpm_common.html#listenbacklog">ListenBacklog</a></li>
+
+ <li><a href="mpm_common.html#lockfile">LockFile</a></li>
+
+ <li><a
+ href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li>
+
+ <li><a
+ href="mpm_common.html#maxsparethreads">MaxSpareThreads</a></li>
+
+ <li><a
+ href="mpm_common.html#maxthreadsperchild">MaxThreadsPerChild</a></li>
+
+ <li><a
+ href="mpm_common.html#minsparethreads">MinSpareThreads</a></li>
+
+ <li><a href="mpm_common.html#numservers">NumServers</a></li>
+
+ <li><a
+ href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li>
+
+ <li><a
+ href="mpm_common.html#sendbuffersize">SendBufferSize</a></li>
+
+ <li><a
+ href="mpm_common.html#startthreads">StartThreads</a></li>
+
+ <li><a href="mpm_common.html#user">User</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="assignuserid" name="assignuserid">AssignUserID
+ directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a><br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a><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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> perchild</p>
+
+ <p>Tie a virtual host to a specific child process.</p>
+ <hr />
+
+ <h2><a id="childperuserid" name="childperuserid">ChildPerUserID
+ directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a><br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a><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> MPM<br />
+ <a href="directive-dict.html#Module"
+ rel="Help"><strong>Module:</strong></a> perchild</p>
+
+ <p>Specify a User and Group for a specific child process.</p>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache MPM prefork</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">Multi-Processing Module prefork</H1>
-<P>
-This Multi-Processing Module implements a non-threaded, pre-forking
-web server.
-</P>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> MPM
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> prefork.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> mpm_prefork_module
-</P>
-
-<H2>Summary</H2>
-
-<p>This Multi-Processing Module (MPM) implements a non-threaded,
-pre-forking web server which handles request in a manner very similar
-to the default behavior of Apache 1.3 on Unix.</p>
-
-<p>A single control process is responsible for launching child
-processes which listen for connections and serve them when they
-arrive. Apache always tries to maintain several <em>spare</em> or
-idle server processes, which stand ready to serve incoming requests.
-In this way, clients do not need to wait for a new child processes to
-be forked before their requests can be served.</p>
-
-<p>The <code>StartServers</code>, <code>MinSpareServers</code>,
-<code>MaxSpareServers</code>, and <code>MaxClients</code> regulate how
-the parent process creates children to serve requests. In general,
-Apache is very self-regulating, so most sites do not need to adjust
-these directives from their default values. Sites which need to serve
-more than 256 simultaneous requests may need to increase
-<code>MaxClients</code>, while sites with limited memory may need to
-decrease <code>MaxClients</code> to keep the server from thrashing
-(swapping memory to disk and back). More information about tuning
-process creation is provided in the <a
-href="../misc/perf-tuning.html">performance hints</a> documentation.</p>
-
-<p>While the parent process is usually started as root under Unix
-in order to bind to port 80, the child processes are launched
-by Apache as a less-privileged user. The <code>User</code> and
-<code>Group</code> directives are used to set the privileges
-of the Apache child processes. The child processes must
-be able to read all the content that will be served, but
-should have as few privileges beyond that as possible.
-In addition, unless <a href="../suexec.html">suexec</a> is used,
-these directives also set the privileges which will be inherited
-by CGI scripts.</p>
-
-<p><code>MaxRequestsPerChild</code> controls how frequently the server
-recycles processes by killing old ones and launching new ones.</p>
-
-<p>See also: <a href="../bind.html">Setting which addresses and ports
-Apache uses</a>.</p>
-
-<H2>Directives</H2>
-<UL>
-<li><a href="#acceptmutex">AcceptMutex</a>
-<li><a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li>
-<li><a href="mpm_common.html#group">Group</a></li>
-<li><a href="mpm_common.html#pidfile">PidFile</a></li>
-<li><a href="mpm_common.html#listen">Listen</a></li>
-<li><a href="mpm_common.html#listenbacklog">ListenBacklog</a></li>
-<li><a href="mpm_common.html#lockfile">LockFile</a></li>
-<li><a href="mpm_common.html#maxclients">MaxClients</a></li>
-<li><a href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li>
-<li><a href="#maxspareservers">MaxSpareServers</a></li>
-<li><a href="#minspareservers">MinSpareServers</a></li>
-<li><a href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li>
-<li><a href="mpm_common.html#sendbuffersize">SendBufferSize</a></li>
-<li><a href="mpm_common.html#startservers">StartServers</a></li>
-<li><a href="mpm_common.html#user">User</a></li>
-</UL>
-
-<p><hr>
-
-
-<H2><A NAME="AcceptMutex">AcceptMutex Directive</A></H2>
-<p><A
- HREF="directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> AcceptMutex default|<EM>method</EM><BR>
-<A
- HREF="directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> <code>AcceptMutex default</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 <code>AcceptMutex</code> directives sets the method that Apache
-uses to serialize multiple children accepting requests on network
-sockets. Prior to Apache 2.0, the method was selectable only at
-compile time. The optimal method to use is highly architecture and
-platform dependent. For further details, see the <a
-href="../misc/perf-tuning.html">performance tuning</a>
-documentation.</p>
-
-<p>If this directive is set to <code>default</code>, then the
-compile-time selected default will be used. Other possible
-methods are listed below. Note that not all methods are available
-on all platforms. If a method is specified which is not available,
-a message will be written to the error log listing the available
-methods.</p>
-
-<dl>
-
-<dt><code>flock</code></dt>
-<dd>uses the <code>flock(2)</code> system call to lock the
-file defined by the <a href="mpm_common.html#lockfile">LockFile</a>
-directive.</dd>
-
-<dt><code>fcntl</code></dt>
-<dd>uses the <code>fnctl(2)</code> system call to lock the
-file defined by the <a href="mpm_common.html#lockfile">LockFile</a>
-directive.</dd>
-
-<dt><code>sysvsem</code></dt>
-<dd>uses SySV-style semaphores to implement the mutex.</dd>
-
-<dt><code>proc_pthread</code></dt>
-<dd>uses POSIX mutexes as implemented by the POSIX Threads (PThreads)
-specification.</dd>
-
-</dl>
-
-<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>
-
-<P>
-
-See also <A HREF="#minspareservers">MinSpareServers</A> and
-<A HREF="mpm_common.html#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="mpm_common.html#startservers">StartServers</A>.
-
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache MPM prefork</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">Multi-Processing Module prefork</h1>
+
+ <p>This Multi-Processing Module implements a non-threaded,
+ pre-forking web server.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> MPM<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> prefork.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ mpm_prefork_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This Multi-Processing Module (MPM) implements a
+ non-threaded, pre-forking web server which handles request in a
+ manner very similar to the default behavior of Apache 1.3 on
+ Unix.</p>
+
+ <p>A single control process is responsible for launching child
+ processes which listen for connections and serve them when they
+ arrive. Apache always tries to maintain several <em>spare</em>
+ or idle server processes, which stand ready to serve incoming
+ requests. In this way, clients do not need to wait for a new
+ child processes to be forked before their requests can be
+ served.</p>
+
+ <p>The <code>StartServers</code>, <code>MinSpareServers</code>,
+ <code>MaxSpareServers</code>, and <code>MaxClients</code>
+ regulate how the parent process creates children to serve
+ requests. In general, Apache is very self-regulating, so most
+ sites do not need to adjust these directives from their default
+ values. Sites which need to serve more than 256 simultaneous
+ requests may need to increase <code>MaxClients</code>, while
+ sites with limited memory may need to decrease
+ <code>MaxClients</code> to keep the server from thrashing
+ (swapping memory to disk and back). More information about
+ tuning process creation is provided in the <a
+ href="../misc/perf-tuning.html">performance hints</a>
+ documentation.</p>
+
+ <p>While the parent process is usually started as root under
+ Unix in order to bind to port 80, the child processes are
+ launched by Apache as a less-privileged user. The
+ <code>User</code> and <code>Group</code> directives are used to
+ set the privileges of the Apache child processes. The child
+ processes must be able to read all the content that will be
+ served, but should have as few privileges beyond that as
+ possible. In addition, unless <a
+ href="../suexec.html">suexec</a> is used, these directives also
+ set the privileges which will be inherited by CGI scripts.</p>
+
+ <p><code>MaxRequestsPerChild</code> controls how frequently the
+ server recycles processes by killing old ones and launching new
+ ones.</p>
+
+ <p>See also: <a href="../bind.html">Setting which addresses and
+ ports Apache uses</a>.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a href="#acceptmutex">AcceptMutex</a></li>
+
+ <li><a
+ href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li>
+
+ <li><a href="mpm_common.html#group">Group</a></li>
+
+ <li><a href="mpm_common.html#pidfile">PidFile</a></li>
+
+ <li><a href="mpm_common.html#listen">Listen</a></li>
+
+ <li><a
+ href="mpm_common.html#listenbacklog">ListenBacklog</a></li>
+
+ <li><a href="mpm_common.html#lockfile">LockFile</a></li>
+
+ <li><a href="mpm_common.html#maxclients">MaxClients</a></li>
+
+ <li><a
+ href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li>
+
+ <li><a href="#maxspareservers">MaxSpareServers</a></li>
+
+ <li><a href="#minspareservers">MinSpareServers</a></li>
+
+ <li><a
+ href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li>
+
+ <li><a
+ href="mpm_common.html#sendbuffersize">SendBufferSize</a></li>
+
+ <li><a
+ href="mpm_common.html#startservers">StartServers</a></li>
+
+ <li><a href="mpm_common.html#user">User</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="AcceptMutex" name="AcceptMutex">AcceptMutex
+ Directive</a></h2>
+
+ <p><a href="directive-dict.html#Syntax"
+ rel="Help"><strong>Syntax:</strong></a> AcceptMutex
+ default|<em>method</em><br />
+ <a href="directive-dict.html#Default"
+ rel="Help"><strong>Default:</strong></a> <code>AcceptMutex
+ default</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 <code>AcceptMutex</code> directives sets the method that
+ Apache uses to serialize multiple children accepting requests
+ on network sockets. Prior to Apache 2.0, the method was
+ selectable only at compile time. The optimal method to use is
+ highly architecture and platform dependent. For further
+ details, see the <a href="../misc/perf-tuning.html">performance
+ tuning</a> documentation.</p>
+
+ <p>If this directive is set to <code>default</code>, then the
+ compile-time selected default will be used. Other possible
+ methods are listed below. Note that not all methods are
+ available on all platforms. If a method is specified which is
+ not available, a message will be written to the error log
+ listing the available methods.</p>
+
+ <dl>
+ <dt><code>flock</code></dt>
+
+ <dd>uses the <code>flock(2)</code> system call to lock the
+ file defined by the <a
+ href="mpm_common.html#lockfile">LockFile</a> directive.</dd>
+
+ <dt><code>fcntl</code></dt>
+
+ <dd>uses the <code>fnctl(2)</code> system call to lock the
+ file defined by the <a
+ href="mpm_common.html#lockfile">LockFile</a> directive.</dd>
+
+ <dt><code>sysvsem</code></dt>
+
+ <dd>uses SySV-style semaphores to implement the mutex.</dd>
+
+ <dt><code>proc_pthread</code></dt>
+
+ <dd>uses POSIX mutexes as implemented by the POSIX Threads
+ (PThreads) specification.</dd>
+ </dl>
+ <hr />
+
+ <h2><a id="maxspareservers"
+ 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>
+
+ <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>
+
+ <p>See also <a href="#minspareservers">MinSpareServers</a> and
+ <a href="mpm_common.html#startservers">StartServers</a>.</p>
+ <hr />
+
+ <h2><a id="minspareservers"
+ 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>
+
+ <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>
+
+ <p>This directive has no effect on Microsoft Windows.</p>
+
+ <p>See also <a href="#maxspareservers">MaxSpareServers</a> and
+ <a href="mpm_common.html#startservers">StartServers</a>.
+ <!--#include virtual="footer.html" -->
+ </p>
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache MPM threaded</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">Multi-Processing Module threaded</H1>
-<P>
-This Multi-Processing Module implements a hybrid multi-threaded
-multi-process web server.
-</P>
-
-<P><A
-HREF="module-dict.html#Status"
-REL="Help"
-><STRONG>Status:</STRONG></A> MPM
-<BR>
-<A
-HREF="module-dict.html#SourceFile"
-REL="Help"
-><STRONG>Source File:</STRONG></A> threaded.c
-<BR>
-<A
-HREF="module-dict.html#ModuleIdentifier"
-REL="Help"
-><STRONG>Module Identifier:</STRONG></A> mpm_threaded_module
-</P>
-
-<H2>Summary</H2>
-
-<p>This Multi-Processing Module (MPM) is the default for most unix-like
-operating systems. It implements a hybrid
-multi-process multi-threaded server. Each process has a fixed number
-of threads. The server adjusts to handle load by increasing or
-decreasing the number of processes.</p>
-
-<p>A single control process is responsible for launching child
-processes. Each child process creates a fixed number of threads as
-specified in the <code>ThreadsPerChild</code> directive.
-The individual threads then listen for connections and
-serve them when they arrive.</p>
-
-<p>Apache always tries to maintain a pool of <em>spare</em> or idle
-server threads, which stand ready to serve incoming requests. In this
-way, clients do not need to wait for a new threads or processes to be
-created before their requests can be served. Apache assesses the
-total number of idle threads in all processes, and forks or kills
-processes to keep this number within the boundaries specified by
-<code>MinSpareThreads</code> and <code>MaxSpareThreads</code>.
-Since this process is very self-regulating, it is rarely necessary to
-modify these directives from their default values. The maximum
-number of clients that may be served simultaneously is determined
-by multiplying the maximum number of server processes that
-will be created (<code>MaxClients</code>) by the number of threads
-created in each process (<code>ThreadsPerChild</code>).</p>
-
-<p>While the parent process is usually started as root under Unix in
-order to bind to port 80, the child processes and threads are launched
-by Apache as a less-privileged user. The <code>User</code> and
-<code>Group</code> directives are used to set the privileges of the
-Apache child processes. The child processes must be able to read all
-the content that will be served, but should have as few privileges
-beyond that as possible. In addition, unless <a
-href="../suexec.html">suexec</a> is used, these directives also set
-the privileges which will be inherited by CGI scripts.</p>
-
-<p><code>MaxRequestsPerChild</code> controls how frequently the server
-recycles processes by killing old ones and launching new ones.</p>
-
-<p>See also: <a href="../bind.html">Setting which addresses and ports
-Apache uses</a>.</p>
-
-
-<H2>Directives</H2>
-<UL>
-<li><a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li>
-<li><a href="mpm_common.html#group">Group</a></li>
-<li><a href="mpm_common.html#pidfile">PidFile</a></li>
-<li><a href="mpm_common.html#listen">Listen</a></li>
-<li><a href="mpm_common.html#listenbacklog">ListenBacklog</a></li>
-<li><a href="mpm_common.html#lockfile">LockFile</a></li>
-<li><a href="mpm_common.html#maxclients">MaxClients</a></li>
-<li><a href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li>
-<li><a href="mpm_common.html#maxsparethreads">MaxSpareThreads</a></li>
-<li><a href="mpm_common.html#minsparethreads">MinSpareThreads</a></li>
-<li><a href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li>
-<li><a href="mpm_common.html#sendbuffersize">SendBufferSize</a></li>
-<li><a href="mpm_common.html#startservers">StartServers</a></li>
-<li><a href="mpm_common.html#threadsperchild">ThreadsPerChild</a></li>
-<li><a href="mpm_common.html#user">User</a></li>
-</UL>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache MPM threaded</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">Multi-Processing Module threaded</h1>
+
+ <p>This Multi-Processing Module implements a hybrid
+ multi-threaded multi-process web server.</p>
+
+ <p><a href="module-dict.html#Status"
+ rel="Help"><strong>Status:</strong></a> MPM<br />
+ <a href="module-dict.html#SourceFile"
+ rel="Help"><strong>Source File:</strong></a> threaded.c<br />
+ <a href="module-dict.html#ModuleIdentifier"
+ rel="Help"><strong>Module Identifier:</strong></a>
+ mpm_threaded_module</p>
+
+ <h2>Summary</h2>
+
+ <p>This Multi-Processing Module (MPM) is the default for most
+ unix-like operating systems. It implements a hybrid
+ multi-process multi-threaded server. Each process has a fixed
+ number of threads. The server adjusts to handle load by
+ increasing or decreasing the number of processes.</p>
+
+ <p>A single control process is responsible for launching child
+ processes. Each child process creates a fixed number of threads
+ as specified in the <code>ThreadsPerChild</code> directive. The
+ individual threads then listen for connections and serve them
+ when they arrive.</p>
+
+ <p>Apache always tries to maintain a pool of <em>spare</em> or
+ idle server threads, which stand ready to serve incoming
+ requests. In this way, clients do not need to wait for a new
+ threads or processes to be created before their requests can be
+ served. Apache assesses the total number of idle threads in all
+ processes, and forks or kills processes to keep this number
+ within the boundaries specified by <code>MinSpareThreads</code>
+ and <code>MaxSpareThreads</code>. Since this process is very
+ self-regulating, it is rarely necessary to modify these
+ directives from their default values. The maximum number of
+ clients that may be served simultaneously is determined by
+ multiplying the maximum number of server processes that will be
+ created (<code>MaxClients</code>) by the number of threads
+ created in each process (<code>ThreadsPerChild</code>).</p>
+
+ <p>While the parent process is usually started as root under
+ Unix in order to bind to port 80, the child processes and
+ threads are launched by Apache as a less-privileged user. The
+ <code>User</code> and <code>Group</code> directives are used to
+ set the privileges of the Apache child processes. The child
+ processes must be able to read all the content that will be
+ served, but should have as few privileges beyond that as
+ possible. In addition, unless <a
+ href="../suexec.html">suexec</a> is used, these directives also
+ set the privileges which will be inherited by CGI scripts.</p>
+
+ <p><code>MaxRequestsPerChild</code> controls how frequently the
+ server recycles processes by killing old ones and launching new
+ ones.</p>
+
+ <p>See also: <a href="../bind.html">Setting which addresses and
+ ports Apache uses</a>.</p>
+
+ <h2>Directives</h2>
+
+ <ul>
+ <li><a
+ href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li>
+
+ <li><a href="mpm_common.html#group">Group</a></li>
+
+ <li><a href="mpm_common.html#pidfile">PidFile</a></li>
+
+ <li><a href="mpm_common.html#listen">Listen</a></li>
+
+ <li><a
+ href="mpm_common.html#listenbacklog">ListenBacklog</a></li>
+
+ <li><a href="mpm_common.html#lockfile">LockFile</a></li>
+
+ <li><a href="mpm_common.html#maxclients">MaxClients</a></li>
+
+ <li><a
+ href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li>
+
+ <li><a
+ href="mpm_common.html#maxsparethreads">MaxSpareThreads</a></li>
+
+ <li><a
+ href="mpm_common.html#minsparethreads">MinSpareThreads</a></li>
+
+ <li><a
+ href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li>
+
+ <li><a
+ href="mpm_common.html#sendbuffersize">SendBufferSize</a></li>
+
+ <li><a
+ href="mpm_common.html#startservers">StartServers</a></li>
+
+ <li><a
+ href="mpm_common.html#threadsperchild">ThreadsPerChild</a></li>
+
+ <li><a href="mpm_common.html#user">User</a></li>
+ </ul>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<HR>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<H3 ALIGN="CENTER">
- Apache HTTP Server Version 2.0
-</H3>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title></title>
+ </head>
+
+ <body>
+ <hr />
+
+ <h3 align="CENTER">Apache HTTP Server Version 2.0</h3>
+ <a href="./"><img src="../images/index.gif" alt="Index" /></a>
+ <a href="../"><img src="../images/home.gif" alt="Home" /></a>
+ </body>
+</html>
-<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A>
-<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A>
-<DIV ALIGN="CENTER">
- <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]">
- <H3>
- Apache HTTP Server Version 2.0
- </H3>
-</DIV>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title></title>
+ </head>
+
+ <body>
+ <div align="CENTER">
+ <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" />
+
+ <h3>Apache HTTP Server Version 2.0</h3>
+ </div>
+ </body>
+</html>
+
-<!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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Running a High-Performance Web Server on HPUX</title>
+ </head>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+
+ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
+ vlink="#000080" alink="#FF0000">
+ <a id="initial" name="initial"> </a>
+ <!--#include virtual="header.html" -->
+
+
+ <h1 align="CENTER">Running a High-Performance Web Server for
+ HPUX</h1>
+<pre>
Date: Wed, 05 Nov 1997 16:59:34 -0800
-From: Rick Jones <<A HREF="mailto:raj@cup.hp.com">raj@cup.hp.com</A>>
+From: Rick Jones <<a
+href="mailto:raj@cup.hp.com">raj@cup.hp.com</a>>
Reply-To: raj@cup.hp.com
Organization: Network Performance
Subject: HP-UX tuning tips
-</PRE>
-
-Here are some tuning tips for HP-UX to add to the tuning page.
-
-<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>
+</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>
+
+ <p>For HP-UX 10.20:</p>
+
+ <p>Install the latest cumulative ARPA Transport Patch. This
+ will allow you to configure the size of the TCP connection
+ lookup hash table. The default is 256 buckets and must be set
+ to a power of two. This is accomplished with adb against the
+ *disc* image of the kernel. The variable name is tcp_hash_size.
+ Notice that it's critically important that you use "W" to write
+ a 32 bit quantity, not "w" to write a 16 bit value when
+ patching the disc image because the tcp_hash_size variable is a
+ 32 bit quantity.</p>
+
+ <p>How to pick the value? Examine the output of <a
+ href="ftp://ftp.cup.hp.com/dist/networking/tools/connhist">ftp://ftp.cup.hp.com/dist/networking/tools/connhist</a>
+ and see how many total TCP connections exist on the system. You
+ probably want that number divided by the hash table size to be
+ reasonably small, say less than 10. Folks can look at HP's
+ SPECweb96 disclosures for some common settings. These can be
+ found at <a
+ href="http://www.specbench.org/">http://www.specbench.org/</a>.
+ If an HP-UX system was performing at 1000 SPECweb96 connections
+ per second, the TIME_WAIT time of 60 seconds would mean 60,000
+ TCP "connections" being tracked.</p>
+
+ <p>Folks can check their listen queue depths with <a
+ href="ftp://ftp.cup.hp.com/dist/networking/misc/listenq">ftp://ftp.cup.hp.com/dist/networking/misc/listenq</a>.</p>
+
+ <p>If folks are running Apache on a PA-8000 based system, they
+ should consider "chatr'ing" the Apache executable to have a
+ large page size. This would be "chatr +pi L <BINARY>."
+ The GID of the running executable must have MLOCK privileges.
+ Setprivgrp(1m) should be consulted for assigning MLOCK. The
+ change can be validated by running Glance and examining the
+ memory regions of the server(s) to make sure that they show a
+ non-trivial fraction of the text segment being locked.</p>
+
+ <p>If folks are running Apache on MP systems, they might
+ consider writing a small program that uses mpctl() to bind
+ processes to processors. A simple pid % numcpu algorithm is
+ probably sufficient. This might even go into the source
+ code.</p>
+
+ <p>If folks are concerned about the number of FIN_WAIT_2
+ connections, they can use nettune to shrink the value of
+ tcp_keepstart. However, they should be careful there -
+ certainly do not make it less than oh two to four minutes. If
+ tcp_hash_size has been set well, it is probably OK to let the
+ FIN_WAIT_2's take longer to timeout (perhaps even the default
+ two hours) - they will not on average have a big impact on
+ performance.</p>
+
+ <p>There are other things that could go into the code base, but
+ that might be left for another email. Feel free to drop me a
+ message if you or others are interested.</p>
+
+ <p>sincerely,</p>
+
+ <p>rick jones<br />
+ <a
+ href="http://www.cup.hp.com/netperf/NetperfPage.html">http://www.cup.hp.com/netperf/NetperfPage.html</a></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>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head>
-<title>Compiling Apache for 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">Compiling Apache for Microsoft Windows</h1>
-
-<p>There are many important points before you begin compiling Apache.
- See <a href="windows.html">Using Apache with Microsoft Windows</a>
- before you begin.</p>
-
-<h3><a name="requirements">Requirements</a></h3>
-
-<p>Compiling Apache requires the following environment to be properly
- installed;
-
-<ul>
-
-<li>Disk Space<br><br> Make sure you have at least 50 MB of free disk space
- available. After installation Apache requires approximately 10 MB of disk
- space, plus space for log and cache files, which can grow rapidly. The
- actual disk space requirements will vary considerably based on your chosen
- configuration and any third-party modules or libraries.<br><br></li>
-
-<li>Microsoft Visual C++ 5.0 or higher.<br><br>Apache can be built using
- the command line tools, or from within the Visual Studio IDE Workbench.
- the command line tools are configured with the vcvars32 batch file:
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Compiling Apache for 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">Compiling Apache for Microsoft Windows</h1>
+
+ <p>There are many important points before you begin compiling
+ Apache. See <a href="windows.html">Using Apache with Microsoft
+ Windows</a> before you begin.</p>
+
+ <h3><a id="requirements"
+ name="requirements">Requirements</a></h3>
+
+ <p>Compiling Apache requires the following environment to be
+ properly installed;</p>
+
+ <ul>
+ <li>Disk Space<br />
+ <br />
+ Make sure you have at least 50 MB of free disk space
+ available. After installation Apache requires approximately
+ 10 MB of disk space, plus space for log and cache files,
+ which can grow rapidly. The actual disk space requirements
+ will vary considerably based on your chosen configuration and
+ any third-party modules or libraries.<br />
+ <br />
+ </li>
+
+ <li>
+ Microsoft Visual C++ 5.0 or higher.<br />
+ <br />
+ Apache can be built using the command line tools, or from
+ within the Visual Studio IDE Workbench. the command line
+ tools are configured with the vcvars32 batch file:
<pre>
"c:\Program Files\DevStudio\VC\Bin\vcvars32.bat"
</pre>
-
-<li>The Windows Platform SDK.<br><br>Visual C++ 5.0 need the updated Microsoft
- Windows Platform SDK to enable some Apache features. For command line
- builds, the Platform SDK environment is prepared by the setenv batch file:
+ </li>
+
+ <li>
+ The Windows Platform SDK.<br />
+ <br />
+ Visual C++ 5.0 need the updated Microsoft Windows Platform
+ SDK to enable some Apache features. For command line
+ builds, the Platform SDK environment is prepared by the
+ setenv batch file:
<pre>
"c:\Program Files\Platform SDK\setenv.bat"
</pre>
- The Platform SDK files distributed with Visual C++ 6.0 and later are
- sufficient, so those users may skip this requirement.<br><br>
-
- <strong>Note</strong> that the Windows
- Platform SDK update is required to enable all supported mod_isapi features.
- Without a recent update, Apache will issue warnings under MSVC++ 5.0
- that some mod_isapi features will be disabled. Look for the update at
- <a href="http://msdn.microsoft.com/downloads/sdks/platform/platform.asp"
- >http://msdn.microsoft.com/downloads/sdks/platform/platform.asp</a>.</p>
-
-<li>The awk utility (awk, gawk or similar.)<br><br>
- To install Apache within the build system, several files are modified using
- the awk utility. awk was chosen since it is a very small download (compared
- with Perl or WSH/VB) and accomplishes the task. Brian Kernighan's
- <a href="http://cm.bell-labs.com/cm/cs/who/bwk/"
- >http://cm.bell-labs.com/cm/cs/who/bwk/</a> site has a compiled native Win32
- binary, <a href="http://cm.bell-labs.com/cm/cs/who/bwk/awk95.exe"
- >http://cm.bell-labs.com/cm/cs/who/bwk/awk95.exe</a>
- which you should name awk.exe rather than awk95.exe.<br>
- Note that Developer Studio IDE will only find awk.exe from the <u>T</u>ools
- menu <u>O</u>ptions... Directories settings for the Executable files. Add
- the path for awk.exe to this list, as needed.</p>
-
-</ul>
-
-<h3><a name="commandbuild">Command-Line Build</a></h3>
-
-<p>First, unpack the Apache distribution into an appropriate
- directory. Open a command-line prompt and cd to that directory.</p>
-
-<p>The master Apache makefile instructions are contained in the
- <code>Makefile.win</code> file. To compile Apache on Windows NT, simply
- use one of the following commands to compiled the release or debug build,
- respectively:
+ The Platform SDK files distributed with Visual C++ 6.0 and
+ later are sufficient, so those users may skip this
+ requirement.<br />
+ <br />
+ <strong>Note</strong> that the Windows Platform SDK update
+ is required to enable all supported mod_isapi features.
+ Without a recent update, Apache will issue warnings under
+ MSVC++ 5.0 that some mod_isapi features will be disabled.
+ Look for the update at <a
+ href="http://msdn.microsoft.com/downloads/sdks/platform/platform.asp">
+ http://msdn.microsoft.com/downloads/sdks/platform/platform.asp</a>.<br />
+ <br />
+ </li>
+
+ <li>The awk utility (awk, gawk or similar.)<br />
+ <br />
+ To install Apache within the build system, several files are
+ modified using the awk utility. awk was chosen since it is a
+ very small download (compared with Perl or WSH/VB) and
+ accomplishes the task. Brian Kernighan's <a
+ href="http://cm.bell-labs.com/cm/cs/who/bwk/">http://cm.bell-labs.com/cm/cs/who/bwk/</a>
+ site has a compiled native Win32 binary, <a
+ href="http://cm.bell-labs.com/cm/cs/who/bwk/awk95.exe">http://cm.bell-labs.com/cm/cs/who/bwk/awk95.exe</a>
+ which you should name awk.exe rather than awk95.exe.<br />
+ Note that Developer Studio IDE will only find awk.exe from
+ the <u>T</u>ools menu <u>O</u>ptions... Directories settings
+ for the Executable files. Add the path for awk.exe to this
+ list, as needed.<br />
+ <br />
+ </li>
+ </ul>
+
+ <h3><a id="commandbuild" name="commandbuild">Command-Line
+ Build</a></h3>
+
+ <p>First, unpack the Apache distribution into an appropriate
+ directory. Open a command-line prompt and cd to that
+ directory.</p>
+
+ <p>The master Apache makefile instructions are contained in the
+ <code>Makefile.win</code> file. To compile Apache on Windows
+ NT, simply use one of the following commands to compiled the
+ release or debug build, respectively:</p>
<pre>
nmake /f Makefile.win _apacher
nmake /f Makefile.win _apached
</pre>
-<p>Either command will compile Apache. The latter will include debugging
- information in the resulting files, making it easier to find bugs and
- track down problems.</p>
-
-<h3><a name="workspacebuild">Developer Studio Workspace IDE Build</a></h3>
-
-<p>Apache can also be compiled using VC++'s VisualStudio development
- environment. To simplify this process, a VisualStudio workspace,
- Apache.dsw, is provided. This workspace exposes the entire list of
- working .dsp projects that are required for the complete Apache binary
- release. It includes dependencies between the projects to assure that
- they are built in the appropriate order.</p>
-
-<p>Open the Apache.dsw workspace, and choose InstallBin (Release or Debug
- build, as desired) as the Active Project. InstallBin causes all related
- project to be build, and then invokes Makefile.win to move the compiled
- executables and dlls. You may personalize the INSTDIR= choice by changing
- InstallBin's Settings, General tab, Build command line entry. INSTDIR
- defaults to the /Apache2 directory.</p>
-
-<p>The .dsp project files are distributed in Visual C++ 6.0 format. Visual
- C++ 5.0 (97) will recognize them with the single exception of the /ZI flag
- (which corresponds to the VC 5.0 /Zi flag for debugging symbols.) To quickly
- prepare the .dsp files for the Visual Studio 5.0 (97), you can run this command
- from the top-level httpd-2.0 directory:
+ <p>Either command will compile Apache. The latter will include
+ debugging information in the resulting files, making it easier
+ to find bugs and track down problems.</p>
+
+ <h3><a id="workspacebuild" name="workspacebuild">Developer
+ Studio Workspace IDE Build</a></h3>
+
+ <p>Apache can also be compiled using VC++'s VisualStudio
+ development environment. To simplify this process, a
+ VisualStudio workspace, Apache.dsw, is provided. This workspace
+ exposes the entire list of working .dsp projects that are
+ required for the complete Apache binary release. It includes
+ dependencies between the projects to assure that they are built
+ in the appropriate order.</p>
+
+ <p>Open the Apache.dsw workspace, and choose InstallBin
+ (Release or Debug build, as desired) as the Active Project.
+ InstallBin causes all related project to be build, and then
+ invokes Makefile.win to move the compiled executables and dlls.
+ You may personalize the INSTDIR= choice by changing
+ InstallBin's Settings, General tab, Build command line entry.
+ INSTDIR defaults to the /Apache2 directory.</p>
+
+ <p>The .dsp project files are distributed in Visual C++ 6.0
+ format. Visual C++ 5.0 (97) will recognize them with the single
+ exception of the /ZI flag (which corresponds to the VC 5.0 /Zi
+ flag for debugging symbols.) To quickly prepare the .dsp files
+ for the Visual Studio 5.0 (97), you can run this command from
+ the top-level httpd-2.0 directory:</p>
<pre>
perl srclib\apr\build\cvtdsp.pl -5
</pre>
- You must type this command from the <em>top level</em> directory of the httpd
- source tree. Every VC6 .dsp project file within the current directory and
- below will be listed as it is converted. If you contribute back a patch that
- revises project files, please convert them back with the the -6 option instead
- of -5, which returns the project files to Visual Studio 6.0 format.</p>
-
-<h3><a name="projectcomponents">Project Components</a></h3>
-
-<p>The Apache.dsw workspace and makefile.win nmake script both build the
- .dsp projects of the Apache server in the following sequence:</p>
-
-<ol>
- <li><code>srclib\apr\apr.dsp</code>
- <li><code>srclib\apr\libapr.dsp</code>
- <li><code>srclib\apr-util\uri\gen_uri_delims.dsp</code>
- <li><code>srclib\apr-util\aprutil.dsp</code>
- <li><code>srclib\apr-util\libaprutil.dsp</code>
- <li><code>srclib\pcre\dftables.dsp</code>
- <li><code>srclib\pcre\pcre.dsp</code>
- <li><code>srclib\pcre\pcreposix.dsp</code>
- <li><code>srclib\expat-lite\libexpat.dsp</code>
- <li><code>server\gen_test_char.dsp</code>
- <li><code>libhttpd.dsp</code>
- <li><code>Apache.dsp</code>
-</ol>
-
- <p>In addition, the <code>os\win32</code> subdirectory contains
- project files for the optional modules.</p>
-
-<ol>
- <li><code>modules\aaa\mod_auth_dbm.dsp</code>
- <li><code>modules\aaa\mod_auth_anon.dsp</code>
- <li><code>modules\aaa\mod_auth_digest.dsp</code>
- <li><code>modules\cache\mod_file_cache.dsp</code>
- <li><code>modules\dav\fs\mod_dav_fs.dsp</code>
- <li><code>modules\dav\main\mod_dav.dsp</code>
- <li><code>modules\generators\mod_info.dsp</code>
- <li><code>modules\generators\mod_status.dsp</code>
- <li><code>modules\mappers\mod_rewrite.dsp</code>
- <li><code>modules\mappers\mod_speling.dsp</code>
- <li><code>modules\metadata\mod_usertrack.dsp</code>
- <li><code>modules\metadata\mod_cern_meta.dsp</code>
- <li><code>modules\metadata\mod_headers.dsp</code>
- <li><code>modules\metadata\mod_expires.dsp</code>
- <li><code>modules\ssl\mod_ssl.dsp</code>
- <li><code>modules\tls\mod_tls.dsp</code>
-</ol>
-
-<p>The <code>support\</code> folder contains project files for additional
- programs that are not part of the Apache runtime, but are used by
- the administrator to test Apache and maintain password and log files.</p>
-
-<ol>
- <li><code>support\ab.dsp</code>
- <li><code>support\htdigest.dsp</code>
- <li><code>support\htpasswd.dsp</code>
- <li><code>support\logresolve.dsp</code>
- <li><code>support\rotatelogs.dsp</code>
- <li><code>support\win32\wintty.dsp</code>
-</ol>
-
-<p>Once Apache has been compiled, it needs to be installed in its server
- root directory. The default is the <code>\Apache2</code>
- directory, of the same drive.</p>
-
-<p>To build and install all the files into the desired folder <em>dir</em>
- automatically, use one the following nmake commands:
+ You must type this command from the <em>top level</em>
+ directory of the httpd source tree. Every VC6 .dsp project file
+ within the current directory and below will be listed as it is
+ converted. If you contribute back a patch that revises project
+ files, please convert them back with the the -6 option instead
+ of -5, which returns the project files to Visual Studio 6.0
+ format.<br />
+ <br />
+
+
+ <h3><a id="projectcomponents" name="projectcomponents">Project
+ Components</a></h3>
+
+ <p>The Apache.dsw workspace and makefile.win nmake script both
+ build the .dsp projects of the Apache server in the following
+ sequence:</p>
+
+ <ol>
+ <li><code>srclib\apr\apr.dsp</code></li>
+
+ <li><code>srclib\apr\libapr.dsp</code></li>
+
+ <li><code>srclib\apr-util\uri\gen_uri_delims.dsp</code></li>
+
+ <li><code>srclib\apr-util\aprutil.dsp</code></li>
+
+ <li><code>srclib\apr-util\libaprutil.dsp</code></li>
+
+ <li><code>srclib\pcre\dftables.dsp</code></li>
+
+ <li><code>srclib\pcre\pcre.dsp</code></li>
+
+ <li><code>srclib\pcre\pcreposix.dsp</code></li>
+
+ <li><code>srclib\expat-lite\libexpat.dsp</code></li>
+
+ <li><code>server\gen_test_char.dsp</code></li>
+
+ <li><code>libhttpd.dsp</code></li>
+
+ <li><code>Apache.dsp</code></li>
+ </ol>
+
+ <p>In addition, the <code>os\win32</code> subdirectory contains
+ project files for the optional modules.</p>
+
+ <ol>
+ <li><code>modules\aaa\mod_auth_dbm.dsp</code></li>
+
+ <li><code>modules\aaa\mod_auth_anon.dsp</code></li>
+
+ <li><code>modules\aaa\mod_auth_digest.dsp</code></li>
+
+ <li><code>modules\cache\mod_file_cache.dsp</code></li>
+
+ <li><code>modules\dav\fs\mod_dav_fs.dsp</code></li>
+
+ <li><code>modules\dav\main\mod_dav.dsp</code></li>
+
+ <li><code>modules\generators\mod_info.dsp</code></li>
+
+ <li><code>modules\generators\mod_status.dsp</code></li>
+
+ <li><code>modules\mappers\mod_rewrite.dsp</code></li>
+
+ <li><code>modules\mappers\mod_speling.dsp</code></li>
+
+ <li><code>modules\metadata\mod_usertrack.dsp</code></li>
+
+ <li><code>modules\metadata\mod_cern_meta.dsp</code></li>
+
+ <li><code>modules\metadata\mod_headers.dsp</code></li>
+
+ <li><code>modules\metadata\mod_expires.dsp</code></li>
+
+ <li><code>modules\ssl\mod_ssl.dsp</code></li>
+
+ <li><code>modules\tls\mod_tls.dsp</code></li>
+ </ol>
+
+ <p>The <code>support\</code> folder contains project files for
+ additional programs that are not part of the Apache runtime,
+ but are used by the administrator to test Apache and maintain
+ password and log files.</p>
+
+ <ol>
+ <li><code>support\ab.dsp</code></li>
+
+ <li><code>support\htdigest.dsp</code></li>
+
+ <li><code>support\htpasswd.dsp</code></li>
+
+ <li><code>support\logresolve.dsp</code></li>
+
+ <li><code>support\rotatelogs.dsp</code></li>
+
+ <li><code>support\win32\wintty.dsp</code></li>
+ </ol>
+
+ <p>Once Apache has been compiled, it needs to be installed in
+ its server root directory. The default is the
+ <code>\Apache2</code> directory, of the same drive.</p>
+
+ <p>To build and install all the files into the desired folder
+ <em>dir</em> automatically, use one the following nmake
+ commands:</p>
<pre>
nmake /f Makefile.win installr INSTDIR=<em>dir</em>
nmake /f Makefile.win installd INSTDIR=<em>dir</em>
</pre>
- The <em>dir</em> argument to INSTDIR gives the installation directory; it
- can be omitted if Apache is to be installed into <samp>\Apache2</samp>.</p>
-
-<p>This will install the following:</p>
-
-<ul>
- <li><code><em>dir</em>\bin\Apache.exe</code> - Apache executable
- <li><code><em>dir</em>\bin\htdigest.exe</code> - Digest auth password file utility
- <li><code><em>dir</em>\bin\htpasswd.exe</code> - Basic auth password file utility
- <li><code><em>dir</em>\bin\logresolve.exe</code> - Log file dns name lookup utility
- <li><code><em>dir</em>\bin\rotatelogs.exe</code> - Log file cycling utility
- <li><code><em>dir</em>\bin\wintty.exe</code> - Console window utility
- <li><code><em>dir</em>\bin\libapr.dll</code> - Apache Portable Runtime shared library
- <li><code><em>dir</em>\bin\libaprutil.dll</code> - Apache Utility Runtime shared library
- <li><code><em>dir</em>\bin\libhttpd.dll</code> - Apache Core library
- <li><code><em>dir</em>\modules\mod_*.so</code> - Loadable Apache modules
- <li><code><em>dir</em>\conf</code> - Configuration directory
- <li><code><em>dir</em>\logs</code> - Empty logging directory
- <li><code><em>dir</em>\include</code> - C language header files
- <li><code><em>dir</em>\lib</code> - Static Link library files
- <li><code><em>dir</em>\libexec</code> - DLL link library files
-</ul>
-
-<p><strong>Warning about building Apache from the development tree</strong></p>
-
-<p>Only the .dsp files are maintained between release builds. The
- .mak files are NOT regenerated, due to the tremendous waste of
- reviewer's time. Therefore, you cannot rely on the NMAKE commands
- above to build revised .dsp project files unless you then export
- all .mak files yourself from the project. This is unnecessary if
- you build from within the Microsoft DeveloperStudio environment.</p>
-
-<!--#include virtual="footer.html" -->
-</body>
-</body>
+ The <em>dir</em> argument to INSTDIR gives the installation
+ directory; it can be omitted if Apache is to be installed into
+ <samp>\Apache2</samp>.<br />
+ <br />
+
+
+ <p>This will install the following:</p>
+
+ <ul>
+ <li><code><em>dir</em>\bin\Apache.exe</code> - Apache
+ executable</li>
+
+ <li><code><em>dir</em>\bin\htdigest.exe</code> - Digest auth
+ password file utility</li>
+
+ <li><code><em>dir</em>\bin\htpasswd.exe</code> - Basic auth
+ password file utility</li>
+
+ <li><code><em>dir</em>\bin\logresolve.exe</code> - Log file
+ dns name lookup utility</li>
+
+ <li><code><em>dir</em>\bin\rotatelogs.exe</code> - Log file
+ cycling utility</li>
+
+ <li><code><em>dir</em>\bin\wintty.exe</code> - Console window
+ utility</li>
+
+ <li><code><em>dir</em>\bin\libapr.dll</code> - Apache
+ Portable Runtime shared library</li>
+
+ <li><code><em>dir</em>\bin\libaprutil.dll</code> - Apache
+ Utility Runtime shared library</li>
+
+ <li><code><em>dir</em>\bin\libhttpd.dll</code> - Apache Core
+ library</li>
+
+ <li><code><em>dir</em>\modules\mod_*.so</code> - Loadable
+ Apache modules</li>
+
+ <li><code><em>dir</em>\conf</code> - Configuration
+ directory</li>
+
+ <li><code><em>dir</em>\logs</code> - Empty logging
+ directory</li>
+
+ <li><code><em>dir</em>\include</code> - C language header
+ files</li>
+
+ <li><code><em>dir</em>\lib</code> - Static Link library
+ files</li>
+
+ <li><code><em>dir</em>\libexec</code> - DLL link library
+ files</li>
+ </ul>
+
+ <p><strong>Warning about building Apache from the development
+ tree</strong></p>
+
+ <p>Only the .dsp files are maintained between release builds.
+ The .mak files are NOT regenerated, due to the tremendous waste
+ of reviewer's time. Therefore, you cannot rely on the NMAKE
+ commands above to build revised .dsp project files unless you
+ then export all .mak files yourself from the project. This is
+ unnecessary if you build from within the Microsoft
+ DeveloperStudio environment.</p>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Running Apache for Windows as a Service</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">Running Apache for Windows as a Service</H1>
-
-<P>Apache can be run as a service on Windows NT/2000. (There is also some
- HIGHLY EXPERIMENTAL support for similar behavior on
- <a href="#win95svc">Windows 95/98</a>, introduced with Apache 1.3.13).</P>
-
-<P>Installing Apache as a service should only be done once you can
- successfully run it in a console window. See
- <A HREF="windows.html">Using Apache with Microsoft Windows</A>
- before you attempt to install or run Apache as a service. Changes to the
- httpd.conf file should always be followed by starting Apache as a console
- window. If this succeeds, the service should succeed.</P>
-
-<P><STRONG>NOTE: Prior to version 1.3.13, the configuration was <EM>not
- tested</EM> prior to performing the installation</STRONG>, and a lack of
- service dependencies often caused the console window to succeed, but the
- service would still fail. See <A HREF="#service">below</A> if you are
- having problems running a version of Apache prior to 1.3.13 to resolve the
- issue. If you have this problem with version 1.3.13 or greater, first try
- uninstalling (-u) and re-installing (-i) the Apache service.</P>
-
-<HR>
-
-<P>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, hidden 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 command line with</P>
-
-<PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Running Apache for Windows as a Service</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">Running Apache for Windows as a Service</h1>
+
+ <p>Apache can be run as a service on Windows NT/2000. (There is
+ also some HIGHLY EXPERIMENTAL support for similar behavior on
+ <a href="#win95svc">Windows 95/98</a>, introduced with Apache
+ 1.3.13).</p>
+
+ <p>Installing Apache as a service should only be done once you
+ can successfully run it in a console window. See <a
+ href="windows.html">Using Apache with Microsoft Windows</a>
+ before you attempt to install or run Apache as a service.
+ Changes to the httpd.conf file should always be followed by
+ starting Apache as a console window. If this succeeds, the
+ service should succeed.</p>
+
+ <p><strong>NOTE: Prior to version 1.3.13, the configuration was
+ <em>not tested</em> prior to performing the
+ installation</strong>, and a lack of service dependencies often
+ caused the console window to succeed, but the service would
+ still fail. See <a href="#service">below</a> if you are having
+ problems running a version of Apache prior to 1.3.13 to resolve
+ the issue. If you have this problem with version 1.3.13 or
+ greater, first try uninstalling (-u) and re-installing (-i) the
+ Apache service.</p>
+ <hr />
+
+ <p>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, hidden 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 command line with</p>
+<pre>
NET START APACHE
NET STOP APACHE
-</PRE>
-
-<P>See <A HREF="#signal">Controlling Apache as a Service</A>
- for more information on installing and controlling Apache services.</P>
-
-<P><STRONG>Apache, unlike many other Windows NT/2000 services, logs any
- errors to it's own error.log file in the logs folder within the
- Apache server root folder. You will <EM>not</EM> find Apache error
- details in the Windows NT Event Log.</STRONG></P>
-
-<P>After starting Apache as a service (or if you have trouble starting it)
- you can test it using the same <A HREF="windows.html#cmdline">procedure</a>
- as for running in a console window. Remember to use the command:</P>
-
-<PRE>
+</pre>
+
+ <p>See <a href="#signal">Controlling Apache as a Service</a>
+ for more information on installing and controlling Apache
+ services.</p>
+
+ <p><strong>Apache, unlike many other Windows NT/2000 services,
+ logs any errors to it's own error.log file in the logs folder
+ within the Apache server root folder. You will <em>not</em>
+ find Apache error details in the Windows NT Event
+ Log.</strong></p>
+
+ <p>After starting Apache as a service (or if you have trouble
+ starting it) you can test it using the same <a
+ href="windows.html#cmdline">procedure</a> as for running in a
+ console window. Remember to use the command:</p>
+<pre>
apache -n "service name"
-</PRE>
+</pre>
-<P>to assure you are using the service's configuration.</P>
-
-
-<H2><A NAME="service">Running Apache for Windows as a Service</A></H2>
+ <p>to assure you are using the service's configuration.</p>
-<P><STRONG>Note: The -n option to specify a service name is only available
- with Apache 1.3.7 and later.</STRONG> Earlier versions of Apache only
- support the default service name 'Apache'.</P>
+ <h2><a id="service" name="service">Running Apache for Windows
+ as a Service</a></h2>
-<P>You can install Apache as a Windows NT service as follows:</P>
+ <p><strong>Note: The -n option to specify a service name is
+ only available with Apache 1.3.7 and later.</strong> Earlier
+ versions of Apache only support the default service name
+ 'Apache'.</p>
-<PRE>
+ <p>You can install Apache as a Windows NT service as
+ follows:</p>
+<pre>
apache -i -n "service name"
-</PRE>
-
-<P>To install a service to use a particular configuration, specify the
- configuration file when the service is installed:</P>
+</pre>
-<PRE>
+ <p>To install a service to use a particular configuration,
+ specify the configuration file when the service is
+ installed:</p>
+<pre>
apache -i -n "service name" -f "\my server\conf\my.conf"
-</PRE>
-
-<P>To remove an Apache service, use:</P>
+</pre>
-<PRE>
+ <p>To remove an Apache service, use:</p>
+<pre>
apache -u -n "service name"
-</PRE>
+</pre>
-<P>The default "service name", if one is not specified, is "Apache".</P>
+ <p>The default "service name", if one is not specified, is
+ "Apache".</p>
-<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:</P>
+ <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:</p>
-<P>To test a service's configuration file:</P>
-<PRE>
+ <p>To test a service's configuration file:</p>
+<pre>
apache -n "service name" -t
-</PRE>
+</pre>
-<P>To start a console Apache using a service's configuration file:</P>
-<PRE>
+ <p>To start a console Apache using a service's configuration
+ file:</p>
+<pre>
apache -n "service name"
-</PRE>
+</pre>
-<H2><A NAME="depends">Important Note on service dependencies:</A></H2>
+ <h2><a id="depends" name="depends">Important Note on service
+ dependencies:</a></h2>
-<P>Prior to Apache release 1.3.13, the dependencies required to
- successfully start an installed service were not configured.
- After installing a service using earlier versions of Apache,
- you must follow these steps:
-
-<PRE>
+ <p>Prior to Apache release 1.3.13, the dependencies required to
+ successfully start an installed service were not configured.
+ After installing a service using earlier versions of Apache,
+ you must follow these steps:</p>
+<pre>
Run regedt32
- Select <U>W</U>indow - "HKEY_LOCAL_MACHINE on Local Machine" from the menu
+ Select <u>W</u>indow - "HKEY_LOCAL_MACHINE on Local Machine" from the menu
Double-click to open the SYSTEM, then the CurrentControlSet keys
Scroll down and click on the Apache servicename
- Select <U>E</U>dit - Add <U>V</U>alue... from the menu
+ Select <u>E</u>dit - Add <u>V</u>alue... from the menu
Fill in the Add Value dialog with
- <U>V</U>alue Name: DependOnGroup
- <U>D</U>ata Type: REG_MULTI_SZ
+ <u>V</u>alue Name: DependOnGroup
+ <u>D</u>ata Type: REG_MULTI_SZ
and click OK
Leave the Multi-String Editor dialog empty and click OK
- Select <U>E</U>dit - Add <U>V</U>alue... from the menu
+ Select <u>E</u>dit - Add <u>V</u>alue... from the menu
Fill in the Add Value dialog with
- <U>V</U>alue Name: DependOnService
- <U>D</U>ata Type: REG_MULTI_SZ
+ <u>V</u>alue Name: DependOnService
+ <u>D</u>ata Type: REG_MULTI_SZ
and click OK
Type the following list (one per line) in the Multi-String Editor dialog
Tcpip
Afd
and click OK
-</PRE>
-
-<P>If you are using COM or DCOM components from a third party module, ISAPI,
- or other add-in scripting technologies such as ActiveState Perl, you may
- also need to add the entry Rpcss to the DependOnService list. To avoid
- exposing the TCP port 135 when it is unnecessary, Apache does not create
- that entry upon installation. Follow the directions above to find or
- create the DependOnService value, double click that value if it already
- exists, and add the Rpcss entry to the list.</P>
-
-
-<H2>User Account for Apache Service to Run As (NT/2000)</H2>
-
-<P>When Apache is first installed as a service (e.g. with the -i option)
- it will run as user "System" (the LocalSystem account). There should
- be few issues if all resources for the web server reside on the local
- system, but it has broad security privilages to affect the local machine!</P>
-
-<BLOCKQUOTE>
- LocalSystem is a very privileged account locally, so
- you shouldn't run any shareware applications there.
- However, it has no network privileges and cannot leave
- the machine via any NT-secured mechanism, including
- file system, named pipes, DCOM, or secure RPC.
-</BLOCKQUOTE>
-
-<P><STRONG>NEVER grant network privilages to the SYSTEM account!</STRONG>
- Create a new user account instead, grant the appropriate privilages to
- that user, and use the the 'Log On As:' option. Select the Start Menu ->
- Settings -> Control Panel -> Services -> apache service ... and click
- the "Startup" button to access this setting.</P>
-
-<BLOCKQUOTE>
- A service that runs in the context of the LocalSystem account
- inherits the security context of the SCM. It is not associated with
- any logged-on user account and does not have credentials (domain name,
- user name, and password) to be used for verification.
-</BLOCKQUOTE>
-
-<P>The SYSTEM account has no privilages to the network, so shared pages or
- a shared installation of Apache is invisible to the service. If you intend
- to use <EM>any</EM> network resources, the following steps should help:</P>
-
-<UL>
-<LI>Select Apache from the Control Panel's Service dialog and click Startup.
-<LI>Verify that the service account is correct. You may wish to create an
- account for your Apache services.
-<LI>Retype the password and password confirmation.
-<LI>Go to User Manager for Domains.
-<LI>Click on Policies from the title bar menu, and select User Rights.
-<LI>Select the option for Advanced User Rights.
-<LI>In the drop-down list, verify that the following rights have been
- granted to the selected account:
- <UL>
- <LI>Act as part of the operating system
- <LI>Back up files and directories
- <LI>Log on as a service
- <LI>Restore files and directories
- </UL>
-<LI>Confirm that the selected account is a member of the Users group.
-<LI>Confirm the selected account has access to all document and script
- directories (minimally read and browse access).
-<LI>Confirm the selected account has read/write/delete access to the Apache
- logs directory!
-</UL>
-
-<P>If you allow the account to log in as a user, then you can log in yourself
- and test that the account has the privilages to execute the scripts, read
- the web pages, and that you can start Apache in a console window. If this
- works, and you have followed the steps above, Apache should execute as
- a service with no problems.</P>
-<P><STRONG>Note: error code 2186</STRONG> is a good indication that you need
- to review the 'Log On As' configuration, since the server can't access a
- required network resource.</P>
-
-
-<H2><A NAME="trouble">Troubleshooting Apache for Windows as a Service</A></H2>
-
-<P>When starting Apache as a service you may encounter an error message from
- Windows service manager. For example if you try to start Apache using the Services
- applet in Windows Control Panel you may get the following message;
-<PRE>
+</pre>
+
+ <p>If you are using COM or DCOM components from a third party
+ module, ISAPI, or other add-in scripting technologies such as
+ ActiveState Perl, you may also need to add the entry Rpcss to
+ the DependOnService list. To avoid exposing the TCP port 135
+ when it is unnecessary, Apache does not create that entry upon
+ installation. Follow the directions above to find or create the
+ DependOnService value, double click that value if it already
+ exists, and add the Rpcss entry to the list.</p>
+
+ <h2>User Account for Apache Service to Run As (NT/2000)</h2>
+
+ <p>When Apache is first installed as a service (e.g. with the
+ -i option) it will run as user "System" (the LocalSystem
+ account). There should be few issues if all resources for the
+ web server reside on the local system, but it has broad
+ security privilages to affect the local machine!</p>
+
+ <blockquote>
+ LocalSystem is a very privileged account locally, so you
+ shouldn't run any shareware applications there. However, it
+ has no network privileges and cannot leave the machine via
+ any NT-secured mechanism, including file system, named pipes,
+ DCOM, or secure RPC.
+ </blockquote>
+
+ <p><strong>NEVER grant network privilages to the SYSTEM
+ account!</strong> Create a new user account instead, grant the
+ appropriate privilages to that user, and use the the 'Log On
+ As:' option. Select the Start Menu -> Settings -> Control
+ Panel -> Services -> apache service ... and click the
+ "Startup" button to access this setting.</p>
+
+ <blockquote>
+ A service that runs in the context of the LocalSystem account
+ inherits the security context of the SCM. It is not
+ associated with any logged-on user account and does not have
+ credentials (domain name, user name, and password) to be used
+ for verification.
+ </blockquote>
+
+ <p>The SYSTEM account has no privilages to the network, so
+ shared pages or a shared installation of Apache is invisible to
+ the service. If you intend to use <em>any</em> network
+ resources, the following steps should help:</p>
+
+ <ul>
+ <li>Select Apache from the Control Panel's Service dialog and
+ click Startup.</li>
+
+ <li>Verify that the service account is correct. You may wish
+ to create an account for your Apache services.</li>
+
+ <li>Retype the password and password confirmation.</li>
+
+ <li>Go to User Manager for Domains.</li>
+
+ <li>Click on Policies from the title bar menu, and select
+ User Rights.</li>
+
+ <li>Select the option for Advanced User Rights.</li>
+
+ <li>
+ In the drop-down list, verify that the following rights
+ have been granted to the selected account:
+
+ <ul>
+ <li>Act as part of the operating system</li>
+
+ <li>Back up files and directories</li>
+
+ <li>Log on as a service</li>
+
+ <li>Restore files and directories</li>
+ </ul>
+ </li>
+
+ <li>Confirm that the selected account is a member of the
+ Users group.</li>
+
+ <li>Confirm the selected account has access to all document
+ and script directories (minimally read and browse
+ access).</li>
+
+ <li>Confirm the selected account has read/write/delete access
+ to the Apache logs directory!</li>
+ </ul>
+
+ <p>If you allow the account to log in as a user, then you can
+ log in yourself and test that the account has the privilages to
+ execute the scripts, read the web pages, and that you can start
+ Apache in a console window. If this works, and you have
+ followed the steps above, Apache should execute as a service
+ with no problems.</p>
+
+ <p><strong>Note: error code 2186</strong> is a good indication
+ that you need to review the 'Log On As' configuration, since
+ the server can't access a required network resource.</p>
+
+ <h2><a id="trouble" name="trouble">Troubleshooting Apache for
+ Windows as a Service</a></h2>
+
+ <p>When starting Apache as a service you may encounter an error
+ message from Windows service manager. For example if you try to
+ start Apache using the Services applet in Windows Control Panel
+ you may get the following message;</p>
+<pre>
Could not start the apache service on \\COMPUTER
Error 1067; The process terminated unexpectedly.
-</PRE>
-<P>You will get this error if there is any problem starting Apache. In order to see
- what is causing the problem you should follow the instructions
- for <a href="windows.html#cmdline">Running Apache for Windows from the Command Line</a>.</P>
-
-<P>Also, Apache 1.3.13 now records startup errors in the Application Event Log
- under Windows NT/2000, if Apache is run as a service. Run the Event Viewer
- and select <U>L</U>og ... <U>A</U>pplication to see these events.
-
-<P><STRONG>Check the Application Event Log with the Event Viewer in case of any
- problems, even if no error message pops up to warn you that an error
- occured.</STRONG></P>
-
-<H2><A NAME="cmdline">Running Apache for Windows from the Command Line</A></H2>
-
-For details on controlling Apache service from the command line, please refer to
-<a href="windows.html#cmdline">console command line</a> section.
-
-
-<H2><A NAME="signal">Controlling Apache as a Service</A></H2>
-
-<P>Multiple instances of Apache can be installed and run as services. Signal
- an installed Apache service to start, restart, or shutdown/stop
- as follows:</P>
-
-<PRE>
+</pre>
+
+ <p>You will get this error if there is any problem starting
+ Apache. In order to see what is causing the problem you should
+ follow the instructions for <a
+ href="windows.html#cmdline">Running Apache for Windows from the
+ Command Line</a>.</p>
+
+ <p>Also, Apache 1.3.13 now records startup errors in the
+ Application Event Log under Windows NT/2000, if Apache is run
+ as a service. Run the Event Viewer and select <u>L</u>og ...
+ <u>A</u>pplication to see these events.</p>
+
+ <p><strong>Check the Application Event Log with the Event
+ Viewer in case of any problems, even if no error message pops
+ up to warn you that an error occured.</strong></p>
+
+ <h2><a id="cmdline" name="cmdline">Running Apache for Windows
+ from the Command Line</a></h2>
+ For details on controlling Apache service from the command
+ line, please refer to <a href="windows.html#cmdline">console
+ command line</a> section.
+
+ <h2><a id="signal" name="signal">Controlling Apache as a
+ Service</a></h2>
+
+ <p>Multiple instances of Apache can be installed and run as
+ services. Signal an installed Apache service to start, restart,
+ or shutdown/stop as follows:</p>
+<pre>
apache -n "service name" -k start
apache -n "service name" -k restart
apache -n "service name" -k shutdown
apache -n "service name" -k stop
-</PRE>
-
-<P>For the default "Apache" service, the -n Apache option is still required,
- since the -k commands without the -n option are directed at Apache running
- in a console window. The quotes are only required if the service name
- contains spaces.</P>
-
-<P><STRONG>Note: the -k stop alias for the -k shutdown command was introduced
- in Apache version 1.3.13.</STRONG> Earlier versions of Apache will only
- recognize the -k shutdown option. Prior to 1.3.3, Apache did not recognize
- <EM>any</EM> -k options at all!</P>
-
-<P>In addition, you can use the native NT NET command to
- start and stop Apache services as follows:</P>
-
-<PRE>
+</pre>
+
+ <p>For the default "Apache" service, the -n Apache option is
+ still required, since the -k commands without the -n option are
+ directed at Apache running in a console window. The quotes are
+ only required if the service name contains spaces.</p>
+
+ <p><strong>Note: the -k stop alias for the -k shutdown command
+ was introduced in Apache version 1.3.13.</strong> Earlier
+ versions of Apache will only recognize the -k shutdown option.
+ Prior to 1.3.3, Apache did not recognize <em>any</em> -k
+ options at all!</p>
+
+ <p>In addition, you can use the native NT NET command to start
+ and stop Apache services as follows:</p>
+<pre>
NET START "service name"
NET STOP "service name"
-</PRE>
+</pre>
-<P>Again, quotes are only required if the service name contains spaces.</P>
+ <p>Again, quotes are only required if the service name contains
+ spaces.</p>
-<H2><A NAME="win95svc">HIGHLY EXPERIMENTAL Windows 95/98 Service</A></H2>
+ <h2><a id="win95svc" name="win95svc">HIGHLY EXPERIMENTAL
+ Windows 95/98 Service</a></h2>
-<P><STRONG>Note: The service options for Windows 95 and 98 are only available
- with Apache 1.3.13 and later.</STRONG> Earlier versions of Apache only
- supported Apache in a console window for Windows 95/98.</P>
+ <p><strong>Note: The service options for Windows 95 and 98 are
+ only available with Apache 1.3.13 and later.</strong> Earlier
+ versions of Apache only supported Apache in a console window
+ for Windows 95/98.</p>
-<P>There is some support for Apache on Windows 95/98 to behave in a similar
- manner as a service on Windows NT/2000. It is <EM>highly experimental</EM>,
- if it works (at all) the Apache Sofware Foundation will not attest to it's
- reliability or future support. Proceed at your own risk!</P>
+ <p>There is some support for Apache on Windows 95/98 to behave
+ in a similar manner as a service on Windows NT/2000. It is
+ <em>highly experimental</em>, if it works (at all) the Apache
+ Sofware Foundation will not attest to it's reliability or
+ future support. Proceed at your own risk!</p>
-<P>Once you have confirmed that Apache runs correctly at the
- <a href="windows.html#cmdline">Command Prompt</a> you can install, control
- and uninstall it with the same commands as the Windows NT/2000 version.</P>
+ <p>Once you have confirmed that Apache runs correctly at the <a
+ href="windows.html#cmdline">Command Prompt</a> you can install,
+ control and uninstall it with the same commands as the Windows
+ NT/2000 version.</p>
-<P>There are, however, significant differences that you should note:</P>
+ <p>There are, however, significant differences that you should
+ note:</p>
-<P>Apache will attempt to start and if successful it will run in the
- background. If you run the command</p>
-
-<PRE>
+ <p>Apache will attempt to start and if successful it will run
+ in the background. If you run the command</p>
+<pre>
Apache -n "service name" -k start
-</PRE>
-
- <p>via a shortcut on your desktop, for example, then if the service starts
- successfully a console window will flash up but immediately disappears.
- If Apache detects any errors on startup such as a incorrect entries in the
- httpd.conf file, then the console window will remain visible. This will
- display an error message which will be useful in tracking down the cause of
- the problem.</P>
-
-<P>Windows 95/98 does not support NET START or NET STOP commands so you must
- use Apache's Service Control options at a command prompt. You may wish to
- set up a shortcut for each of these commands so that you can just choose
- it from the start menu or desktop to perform the required action.</P>
-
-<P>Apache and Windows 95/98 offer no support for running the Apache service
- as a specific user with network privilages. In fact, Windows 95/98 offers
- no security on the local machine, either. This is the simple reason that
- the Apache Software Foundation never endorses the use of Windows 95/98 as a
- public httpd server. These facilities exist only to assist the user in
- developing web content and learning the Apache server, and perhaps as a
- intranet server on a secured, private network.</P>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</pre>
+
+ <p>via a shortcut on your desktop, for example, then if the
+ service starts successfully a console window will flash up but
+ immediately disappears. If Apache detects any errors on startup
+ such as a incorrect entries in the httpd.conf file, then the
+ console window will remain visible. This will display an error
+ message which will be useful in tracking down the cause of the
+ problem.</p>
+
+ <p>Windows 95/98 does not support NET START or NET STOP
+ commands so you must use Apache's Service Control options at a
+ command prompt. You may wish to set up a shortcut for each of
+ these commands so that you can just choose it from the start
+ menu or desktop to perform the required action.</p>
+
+ <p>Apache and Windows 95/98 offer no support for running the
+ Apache service as a specific user with network privilages. In
+ fact, Windows 95/98 offers no security on the local machine,
+ either. This is the simple reason that the Apache Software
+ Foundation never endorses the use of Windows 95/98 as a public
+ httpd server. These facilities exist only to assist the user in
+ developing web content and learning the Apache server, and
+ perhaps as a intranet server on a secured, private network.</p>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!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 2.0 under Microsoft Windows. If you find any bugs, or wish
- to contribute in other ways, please use our
- <A HREF="http://www.apache.org/bugs/">bug reporting page.</A></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
- <A HREF="win_compiling.html">Compiling Apache for Microsoft Windows</A>.
-
-<P><STRONG>At this time, support for Windows 95, 98 and ME is incomplete.
- Apache 2.0 is not expected to work on those platforms at this time.</STRONG>
- If you are interested in helping with that effort, please see the
- developer's site for information on <a href="http://dev.apache.org/">how
- to get involved</a>. Support will likely be provided at some point in the
- future, and patches to allow Apache to work on 95, 98 and ME are welcome!</P>
-
-<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="win_service.html">Running Apache for Windows as a Service</A>
- <LI><A HREF="win_service.html#signal">Controlling Apache as a Service</A>
- <LI><A HREF="win_compiling.html">Compiling Apache for Microsoft Windows</A>
-</UL>
-
-<HR>
-
-<H2><A NAME="req">Requirements</A></H2>
-
-<P>Apache 2.0 is designed to run on Windows NT 4.0 and Windows 2000. The
- binary installer will only work with the x86 family of processors, such
- as Intel's. Apache may also run on Windows 95, 98 and ME, but these are
- not tested, and are never recommended for production servers. In all
- cases TCP/IP networking must be installed.</P>
-
-<P>If running on Windows 95, the "Winsock2" upgrade MUST BE INSTALLED.
- "Winsock2" for Windows 95 is available
- <A HREF="http://www.microsoft.com/windows95/downloads/">here</A>.</P>
-
-<P>If running on NT 4.0, installing Service Pack 3 or 6 is recommended, as
- Service Pack 4 created known issues with TCP/IP and WinSock integrity that
- were resolved in later Service Packs.</P>
-
-<H2><A NAME="down">Downloading Apache for Windows</A></H2>
-
-<P>Information on the latest version of Apache can be found on the
- Apache web server at <A HREF="http://httpd.apache.org/">
- http://httpd.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>.msi</CODE> extension. This is a single Microsoft Installer file
- containing Apache, ready to install and run. There is a seperate
- <CODE>.zip</CODE> file containing _only_ the source code, to compile
- Apache yourself with the Microsoft Visual C++ (Visual Studio) tools.</P>
-
-<H2><A NAME="inst">Installing Apache for Windows</A></H2>
-
-<P>Run the Apache <SAMP>.msi</SAMP> file you downloaded above. This will
- ask for:</P>
-
-<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>
-
-<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>
-
-<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.</P>
-
-<H2><A NAME="run">Running Apache for Windows</A></H2>
-
-There are two ways you can run Apache:
-
-<UL>
- <LI>As a <A HREF="win_service.html#service">"service"</A> (available on
- Windows NT/2000, or a pseudo-service on Windows 95, 98 or ME).
- 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 MUST be used by any
- administrator to test before to attempting to run as a service.
-</UL>
-
-<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>
-
-<P>If the Apache console window closes immediately (or unexpectedly),
- run the "Command Prompt" from the Start Menu - Programs list. Change
- to the folder to which you installed Apache, type the command apache,
- and read the error message. Then change to the logs folder, and review
- the error.log file for configuration mistakes. If you accepted the
- defaults when you installed Apache, the commands would be:</P>
-
-<PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>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 2.0 under Microsoft Windows. If you find any bugs, or
+ wish to contribute in other ways, please use our <a
+ href="http://www.apache.org/bugs/">bug reporting page.</a></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 <a href="win_compiling.html">Compiling Apache
+ for Microsoft Windows</a>.</p>
+
+ <p><strong>At this time, support for Windows 95, 98 and ME is
+ incomplete. Apache 2.0 is not expected to work on those
+ platforms at this time.</strong> If you are interested in
+ helping with that effort, please see the developer's site for
+ information on <a href="http://dev.apache.org/">how to get
+ involved</a>. Support will likely be provided at some point in
+ the future, and patches to allow Apache to work on 95, 98 and
+ ME are welcome!</p>
+ <hr />
+
+ <ul>
+ <li><a href="#req">Requirements</a></li>
+
+ <li><a href="#down">Downloading Apache for Windows</a></li>
+
+ <li><a href="#inst">Installing Apache for Windows (binary
+ install)</a></li>
+
+ <li><a href="#run">Running Apache for Windows</a></li>
+
+ <li><a href="#use">Using Apache for Windows</a></li>
+
+ <li><a href="#cmdline">Running Apache for Windows from the
+ Command Line</a></li>
+
+ <li><a href="win_service.html">Running Apache for Windows as
+ a Service</a></li>
+
+ <li><a href="win_service.html#signal">Controlling Apache as a
+ Service</a></li>
+
+ <li><a href="win_compiling.html">Compiling Apache for
+ Microsoft Windows</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="req" name="req">Requirements</a></h2>
+
+ <p>Apache 2.0 is designed to run on Windows NT 4.0 and Windows
+ 2000. The binary installer will only work with the x86 family
+ of processors, such as Intel's. Apache may also run on Windows
+ 95, 98 and ME, but these are not tested, and are never
+ recommended for production servers. In all cases TCP/IP
+ networking must be installed.</p>
+
+ <p>If running on Windows 95, the "Winsock2" upgrade MUST BE
+ INSTALLED. "Winsock2" for Windows 95 is available <a
+ href="http://www.microsoft.com/windows95/downloads/">here</a>.</p>
+
+ <p>If running on NT 4.0, installing Service Pack 3 or 6 is
+ recommended, as Service Pack 4 created known issues with TCP/IP
+ and WinSock integrity that were resolved in later Service
+ Packs.</p>
+
+ <h2><a id="down" 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://httpd.apache.org/">http://httpd.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>.msi</code> extension. This is a single Microsoft
+ Installer file containing Apache, ready to install and run.
+ There is a seperate <code>.zip</code> file containing _only_
+ the source code, to compile Apache yourself with the Microsoft
+ Visual C++ (Visual Studio) tools.</p>
+
+ <h2><a id="inst" name="inst">Installing Apache for
+ Windows</a></h2>
+
+ <p>Run the Apache <samp>.msi</samp> file you downloaded above.
+ This will ask for:</p>
+
+ <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>
+
+ <li>the start menu name (default is "Apache Web Server")</li>
+
+ <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.</li>
+ </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>
+
+ <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>
+
+ <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.</p>
+
+ <h2><a id="run" name="run">Running Apache for Windows</a></h2>
+ There are two ways you can run Apache:
+
+ <ul>
+ <li>As a <a href="win_service.html#service">"service"</a>
+ (available on Windows NT/2000, or a pseudo-service on Windows
+ 95, 98 or ME). 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>
+
+ <li>From a <a href="#cmdline">console window</a>. This MUST
+ be used by any administrator to test before to attempting to
+ run as a service.</li>
+ </ul>
+
+ <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>
+
+ <p>If the Apache console window closes immediately (or
+ unexpectedly), run the "Command Prompt" from the Start Menu -
+ Programs list. Change to the folder to which you installed
+ Apache, type the command apache, and read the error message.
+ Then change to the logs folder, and review the error.log file
+ for configuration mistakes. If you accepted the defaults when
+ you installed Apache, the commands would be:</p>
+<pre>
c:
cd "\program files\apache group\apache"
apache
- <SAMP>Wait for Apache to exit, or press Ctrl+C</SAMP>
+ <samp>Wait for Apache to exit, or press Ctrl+C</samp>
cd logs
more <error.log
-</PRE>
-
-<P><STRONG>Complete the steps above before you proceed to attempt to
- start Apache as a Window NT/2000 service!</STRONG></P>
-
-<P>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:</P>
-
-<PRE>
+</pre>
+
+ <p><strong>Complete the steps above before you proceed to
+ attempt to start Apache as a Window NT/2000
+ service!</strong></p>
+
+ <p>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:</p>
+<pre>
NET START APACHE
NET STOP APACHE
-</PRE>
-
-<P>See <A HREF="#signalsrv">Signalling Service Apache when Running</A>
- for more information on installing and controlling Apache services.</P>
-
-<P><STRONG>Apache, unlike many other Windows NT/2000 services, logs any
- errors to it's own error.log file in the logs folder within the
- Apache server root folder. You will <EM>not</EM> find Apache error
- details in the Windows NT Event Log.</STRONG></P>
-
-<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:</P>
-
-<PRE>
+</pre>
+
+ <p>See <a href="#signalsrv">Signalling Service Apache when
+ Running</a> for more information on installing and controlling
+ Apache services.</p>
+
+ <p><strong>Apache, unlike many other Windows NT/2000 services,
+ logs any errors to it's own error.log file in the logs folder
+ within the Apache server root folder. You will <em>not</em>
+ find Apache error details in the Windows NT Event
+ Log.</strong></p>
+
+ <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:</p>
+<pre>
http://localhost/
-</PRE>
-
-<P>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:</P>
-
-<PRE>
+</pre>
+
+ <p>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:</p>
+<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.
- Again, if you change the configuration of the Windows NT/2000
- service for Apache, first attempt to start it from the command
- line to assure that the service starts with no errors.</P>
-
-<P>Because Apache <em>CANNOT</em> share the same port with another
- TCPIP application, you may need to stop or uninstall certain
- services first. These include (but are not limited to) other
- web servers, and firewall products such as BlackIce. If you can
- only start Apache with these services disabled, reconfigure either
- Apache or the other product so that they do not listen on the
- same TCPIP ports.</P>
-
-<H2><A NAME="use">Configuring Apache for Windows</A></H2>
-
-<P>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>
-
-<P>The main differences in Apache for Windows are:</P>
-
-<UL>
- <LI><P>Because Apache for Windows is multithreaded, it does not use a
- separate process for each request, as Apache does with
- Unix. 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/mpm_common.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.
- <STRONG>
- Warning: The server configuration file is reread when the
- new child process is started. If you have modified httpd.conf,
- the new child may not start or you may receive unexpected results.
- </STRONG>
- <P><A HREF="../mod/mpm_common.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>
+</pre>
+
+ <p>Once your basic installation is working, you should
+ configure it properly by editing the files in the
+ <samp>conf</samp> directory. Again, if you change the
+ configuration of the Windows NT/2000 service for Apache, first
+ attempt to start it from the command line to assure that the
+ service starts with no errors.</p>
+
+ <p>Because Apache <em>CANNOT</em> share the same port with
+ another TCPIP application, you may need to stop or uninstall
+ certain services first. These include (but are not limited to)
+ other web servers, and firewall products such as BlackIce. If
+ you can only start Apache with these services disabled,
+ reconfigure either Apache or the other product so that they do
+ not listen on the same TCPIP ports.</p>
+
+ <h2><a id="use" name="use">Configuring Apache for
+ Windows</a></h2>
+
+ <p>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>
+
+ <p>The main differences in Apache for Windows are:</p>
+
+ <ul>
+ <li>
+ <p>Because Apache for Windows is multithreaded, it does not
+ use a separate process for each request, as Apache does
+ with Unix. 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>
+
+ <p>So the "process"-management directives are
+ different:</p>
+
+ <p><a
+ href="../mod/mpm_common.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.
+ <strong>Warning: The server configuration file is reread
+ when the new child process is started. If you have modified
+ httpd.conf, the new child may not start or you may receive
+ unexpected results.</strong></p>
+
+ <p><a
+ href="../mod/mpm_common.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>
+
+ <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>
+
+ <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/mod_status.so
-</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> Note that Apache <em>CANNOT</em> load ISAPI
- Filters.
- <LI>When running CGI scripts, the method Apache uses to find the
- interpreter for the script is configurable using the
- <a href="../mod/core.html#scriptinterpretersource"
- >ScriptInterpreterSource</a> directive.
- <LI>Since it is often difficult to manage files with names like
- <code>.htaccess</code> under windows, you may find it useful
- to change the name of this configuration file using the
- <a href="../mod/core.html#accessfilename">AccessFilename</a>
- directive.
-
-
-</UL>
-
-<H2><A NAME="service">Running Apache for Windows as a Service</A></H2>
-
-<P><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>
-
-<P>You can install Apache as a Windows NT service as follows:</p>
-
-<PRE>
+</pre>
+
+ <p>Information on <a
+ href="../mod/mod_so.html#creating">creating loadable
+ modules</a> is also available.</p>
+ </li>
+
+ <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> Note that Apache <em>CANNOT</em> load ISAPI
+ Filters.</p>
+ </li>
+
+ <li>When running CGI scripts, the method Apache uses to find
+ the interpreter for the script is configurable using the <a
+ href="../mod/core.html#scriptinterpretersource">ScriptInterpreterSource</a>
+ directive.</li>
+
+ <li>Since it is often difficult to manage files with names
+ like <code>.htaccess</code> under windows, you may find it
+ useful to change the name of this configuration file using
+ the <a
+ href="../mod/core.html#accessfilename">AccessFilename</a>
+ directive.</li>
+ </ul>
+
+ <h2><a id="service" name="service">Running Apache for Windows
+ as a Service</a></h2>
+
+ <p><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>
+
+ <p>You can install Apache as a Windows NT service as
+ follows:</p>
+<pre>
apache -k install -n "service name"
-</PRE>
-
- <p>To install a service to use a particular configuration, specify the
- configuration file when the service is installed:</p>
+</pre>
-<PRE>
+ <p>To install a service to use a particular configuration,
+ specify the configuration file when the service is
+ installed:</p>
+<pre>
apache -k install -n "service name" -f "\my server\conf\my.conf"
-</PRE>
+</pre>
- <p>To remove an Apache service, use</p>
-
-<PRE>
+ <p>To remove an Apache service, use</p>
+<pre>
apache -k uninstall -n "service name"
-</PRE>
-
- <p>The default "service name", if one is not specified, is "Apache".</P>
+</pre>
-<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:</P>
+ <p>The default "service name", if one is not specified, is
+ "Apache".</p>
-<P>To test a service's configuration file:</P>
+ <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:</p>
-<PRE>
+ <p>To test a service's configuration file:</p>
+<pre>
apache -n "service name" -t
-</PRE>
-
-<P>To start a console Apache using a service's configuration file:</P>
+</pre>
-<PRE>
+ <p>To start a console Apache using a service's configuration
+ file:</p>
+<pre>
apache -n "service name"
-</PRE>
+</pre>
-<P><STRONG>Important Note on service dependencies:</STRONG></P>
+ <p><strong>Important Note on service dependencies:</strong></p>
-<P>Prior to Apache release 1.3.13, the dependencies required to
- successfully start an installed service were not configured.
- After installing a service using earlier versions of Apache,
- you must follow these steps:
-
-<PRE>
+ <p>Prior to Apache release 1.3.13, the dependencies required to
+ successfully start an installed service were not configured.
+ After installing a service using earlier versions of Apache,
+ you must follow these steps:</p>
+<pre>
Run regedt32
- Select <U>W</U>indow - "HKEY_LOCAL_MACHINE on Local Machine" from the menu
+ Select <u>W</u>indow - "HKEY_LOCAL_MACHINE on Local Machine" from the menu
Double-click to open the SYSTEM, then the CurrentControlSet keys
Scroll down and click on the Apache servicename
- Select <U>E</U>dit - Add <U>V</U>alue... from the menu
+ Select <u>E</u>dit - Add <u>V</u>alue... from the menu
Fill in the Add Value dialog with
- <U>V</U>alue Name: DependOnGroup
- <U>D</U>ata Type: REG_MULTI_SZ
+ <u>V</u>alue Name: DependOnGroup
+ <u>D</u>ata Type: REG_MULTI_SZ
and click OK
Leave the Multi-String Editor dialog empty and click OK
- Select <U>E</U>dit - Add <U>V</U>alue... from the menu
+ Select <u>E</u>dit - Add <u>V</u>alue... from the menu
Fill in the Add Value dialog with
- <U>V</U>alue Name: DependOnService
- <U>D</U>ata Type: REG_MULTI_SZ
+ <u>V</u>alue Name: DependOnService
+ <u>D</u>ata Type: REG_MULTI_SZ
and click OK
Type the following list (one per line) in the Multi-String Editor dialog
Tcpip
Afd
and click OK
-</PRE>
-
-<P>If you are using COM or DCOM components from a third party module, ISAPI,
- or other add-in scripting technologies such as ActiveState Perl, you may
- also need to add the entry Rpcss to the DependOnService list. To avoid
- exposing the TCP port 135 when it is unnecessary, Apache does not create
- that entry upon installation. Follow the directions above to find or
- create the DependOnService value, double click that value if it already
- exists, and add the Rpcss entry to the list.</P>
-
-<H2><A NAME="cmdline">Running Apache for Windows from the Command Line</A></H2>
-
-<P>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>
-
-<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:</p>
-
-<UL>
- <LI>-f specifies a path to a particular configuration file
-</UL>
+</pre>
+
+ <p>If you are using COM or DCOM components from a third party
+ module, ISAPI, or other add-in scripting technologies such as
+ ActiveState Perl, you may also need to add the entry Rpcss to
+ the DependOnService list. To avoid exposing the TCP port 135
+ when it is unnecessary, Apache does not create that entry upon
+ installation. Follow the directions above to find or create the
+ DependOnService value, double click that value if it already
+ exists, and add the Rpcss entry to the list.</p>
+
+ <h2><a id="cmdline" name="cmdline">Running Apache for Windows
+ from the Command Line</a></h2>
+
+ <p>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>
+
+ <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:</p>
+
+ <ul>
+ <li>-f specifies a path to a particular configuration
+ file</li>
+ </ul>
+<pre>
+ apache -f "c:\my server\conf\my.conf"
+ apache -f test\test.conf
+</pre>
+
+ <ul>
+ <li>-n specifies the configuration file of an installed
+ Apache service (Apache 1.3.7 and later)</li>
+ </ul>
+<pre>
+ apache -n "service name"
+</pre>
-<PRE> apache -f "c:\my server\conf\my.conf"
- apache -f test\test.conf</PRE>
+ <p>In these cases, the proper ServerRoot should be set in the
+ configuration file.</p>
-<UL>
- <LI>-n specifies the configuration file of an installed Apache service (Apache 1.3.7 and later)
-</UL>
+ <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 its ServerRoot by trying the following, in
+ this order:</p>
-<PRE> apache -n "service name"</PRE>
+ <ul>
+ <li>A ServerRoot directive via a -C switch.</li>
- <p>In these cases, the proper ServerRoot should be set in the configuration file.</P>
+ <li>The -d switch on the command line.</li>
-<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 its ServerRoot by trying the following, in this order:</P>
+ <li>Current working directory</li>
-<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>
+ <li>A registry entry, created if you did a binary
+ install.</li>
-<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>
+ <li>The server root compiled into the server.</li>
+ </ul>
-<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>
+ <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>
-<P>During a binary installation, a version-specific registry key is created
- in the Windows registry:
+ <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>
-<PRE>
+ <p>During a binary installation, a version-specific registry
+ key is created in the Windows registry:</p>
+<pre>
HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\1.3.7
HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\2.0a3
-</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>
-
-<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 its
- configuration files.</P>
-
-<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:</p>
-
-<PRE>
+</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>
+
+ <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 its
+ configuration files.</p>
+
+ <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>
+
+ <p>To run Apache from the command line as a console
+ application, use the following command:</p>
+<pre>
apache
-</PRE>
+</pre>
- <p>Apache will execute, and will remain running until it is stopped by pressing
- control-C.</P>
+ <p>Apache will execute, and will remain running until it is
+ stopped by pressing control-C.</p>
-<H2><A NAME="signalsrv">Signalling Service Apache when running</A></H2>
+ <h2><a id="signalsrv" name="signalsrv">Signalling Service
+ Apache when running</a></h2>
-<P>On Windows NT, multiple instances of Apache can be run as services.
- Signal an Apache service to start, restart, or shutdown as follows:</P>
-
-<PRE>
+ <p>On Windows NT, multiple instances of Apache can be run as
+ services. Signal an Apache service to start, restart, or
+ shutdown as follows:</p>
+<pre>
apache -n "service name" -k start
apache -n "service name" -k restart
apache -n "service name" -k shutdown
-</PRE>
-
-<P>In addition, you can use the native NT NET command to
- start and stop Apache services as follows:</P>
+</pre>
-<PRE>
+ <p>In addition, you can use the native NT NET command to start
+ and stop Apache services as follows:</p>
+<pre>
NET START "service name"
NET STOP "service name"
-</PRE>
-
-<H2><A NAME="signal">Signalling Console Apache when running</A></H2>
+</pre>
-<P>On Windows 95, Apache runs as a console application. You can tell a
- running Apache to stop by opening another console window and typing:</P>
+ <h2><a id="signal" name="signal">Signalling Console Apache when
+ running</a></h2>
-<PRE>
+ <p>On Windows 95, Apache runs as a console application. You can
+ tell a running Apache to stop by opening another console window
+ and typing:</p>
+<pre>
apache -k shutdown
-</PRE>
+</pre>
-<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>
+ <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>
-<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</P>
-
-<PRE>
+ <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</p>
+<pre>
apache -k restart
-</PRE>
-
-<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.</P>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+</pre>
+
+ <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.</p>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head><title>Manual Page: ab - Apache HTTP Server</title></head>
-<body bgcolor="#ffffff" text="#000000" link="#0000ff"
-vlink="#000080" alink="#ff0000">
-<!--#include virtual="header.html" -->
-<h1 align="center">Manual Page: ab</h1>
-<!-- This document was autogenerated from the man page -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Manual Page: ab - Apache HTTP Server</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#0000ff"
+ vlink="#000080" alink="#ff0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="center">Manual Page: ab</h1>
+ <!-- This document was autogenerated from the man page -->
<pre>
<strong>NAME</strong>
ab - Apache HTTP server benchmarking tool
<strong>SYNOPSIS</strong>
- <strong>ab </strong>[ -<strong>k </strong>] [ -<strong>n </strong><em>requests </em>] [ -<strong>t </strong><em>timelimit </em>] [ -<strong>c </strong><em>concurrency</em>
- ] [ -<strong>p </strong><em>POST file </em>] [ -<strong>A </strong><em>Authentication username</em>:<em>password </em>] [
- -<strong>P </strong><em>Proxy Authentication username</em>:<em>password </em>] [ -<strong>H </strong><em>Custom</em>
- <em>header </em>] [ -<strong>C </strong><em>Cookie name</em>=<em>value </em>] [ -<strong>T </strong><em>content</em>-<em>type </em>] [ -<strong>v</strong>
- <em>verbosity </em>] ] [ -<strong>w </strong><em>output HTML </em>] ] [ -<strong>x </strong><<em>table</em>> <em>attributes </em>]
- ] [ -<strong>y </strong><<em>tr</em>> <em>attributes </em>] ] [ -<strong>z </strong><<em>td</em>> <em>attributes </em>]
+ <strong>ab</strong> [ -<strong>k</strong> ] [ -<strong>n</strong> <em>requests</em> ] [ -<strong>t</strong> <em>timelimit</em> ] [ -<strong>c</strong> <em>concurrency</em>
+ ] [ -<strong>p</strong> <em>POST file</em> ] [ -<strong>A</strong> <em>Authentication username</em>:<em>password</em> ] [
+ -<strong>P</strong> <em>Proxy Authentication username</em>:<em>password</em> ] [ -<strong>H</strong> <em>Custom</em>
+ <em>header</em> ] [ -<strong>C</strong> <em>Cookie name</em>=<em>value</em> ] [ -<strong>T</strong> <em>content</em>-<em>type</em> ] [ -<strong>v</strong>
+ <em>verbosity</em> ] ] [ -<strong>w</strong> <em>output HTML</em> ] ] [ -<strong>x</strong> <<em>table</em>> <em>attributes</em> ]
+ ] [ -<strong>y</strong> <<em>tr</em>> <em>attributes</em> ] ] [ -<strong>z</strong> <<em>td</em>> <em>attributes</em> ]
[<em>http</em>://]<em>hostname</em>[:<em>port</em>]/<em>path</em>
- <strong>ab </strong>[ -<strong>V </strong>] [ -<strong>h </strong>]
+ <strong>ab</strong> [ -<strong>V</strong> ] [ -<strong>h</strong> ]
<strong>DESCRIPTION</strong>
- <strong>ab </strong>is a tool for benchmarking your Apache HyperText Transfer
+ <strong>ab</strong> is a tool for benchmarking your Apache HyperText Transfer
Protocol (HTTP) server. It is designed to give you an
impression of how your current Apache installation performs.
This especially shows you how many requests per second your
Apache installation is capable of serving.
<strong>OPTIONS</strong>
- -<strong>k </strong>Enable the HTTP KeepAlive feature, i.e., perform
+ -<strong>k </strong> Enable the HTTP KeepAlive feature, i.e., perform
multiple requests within one HTTP session.
Default is no KeepAlive.
- -<strong>n </strong><em>requests </em>Number of requests to perform for the benchmark-
+ -<strong>n</strong> <em>requests</em> Number of requests to perform for the benchmark-
ing session. The default is to just perform a
single request which usually leads to non-
representative benchmarking results.
- -<strong>t </strong><em>timelimit</em>
+ -<strong>t</strong> <em>timelimit</em>
Maximum number of seconds to spend for bench-
- marking. This implies a -<strong>n 50000 </strong>internally. Use
+ marking. This implies a -<strong>n 50000</strong> internally. Use
this to benchmark the server within a fixed
total amount of time. Per default there is no
timelimit.
- -<strong>c </strong><em>concurrency</em>
+ -<strong>c</strong> <em>concurrency</em>
Number of multiple requests to perform at a
time. Default is one request at a time.
- -<strong>p </strong><em>POST file</em>
+ -<strong>p</strong> <em>POST file</em>
File containing data to POST.
- -<strong>A </strong><em>Authentication username</em>:<em>password</em>
+ -<strong>A</strong> <em>Authentication username</em>:<em>password</em>
Supply BASIC Authentication credentials to the
server. The username and password are separated
by a single ':' and sent on the wire uuencoded.
server needs it; (i.e., has sent an 401 authen-
tication needed).
- -<strong>p </strong><em>Proxy</em>-<em>Authentication username</em>:<em>password</em>
+ -<strong>p</strong> <em>Proxy</em>-<em>Authentication username</em>:<em>password</em>
Supply BASIC Authentication credentials to a
proxy en-route. The username and password are
separated by a single ':' and sent on the wire
whether the proxy needs it; (i.e., has sent an
407 proxy authentication needed).
- -<strong>C </strong><em>Cookie name</em>=<em>value</em>
+ -<strong>C</strong> <em>Cookie name</em>=<em>value</em>
Add a 'Cookie:' line to the request. The argu-
ment is typically in the form of a 'name=value'
pair. This field is repeatable.
- -<strong>p </strong><em>Header string</em>
+ -<strong>p</strong> <em>Header string</em>
Append extra headers to the request. The argu-
ment is typically in the form of a valid header
line, containing a colon-separated field-value
pair. (i.e., 'Accept-Encoding: zip/zop;8bit').
- -<strong>T </strong><em>content</em>-<em>type</em>
+ -<strong>T</strong> <em>content</em>-<em>type</em>
Content-type header to use for POST data.
- -<strong>v </strong>Set verbosity level - 4 and above prints infor-
+ -<strong>v </strong> Set verbosity level - 4 and above prints infor-
mation on headers, 3 and above prints response
codes (404, 200, etc.), 2 and above prints warn-
ings and info.
- -<strong>w </strong>Print out results in HTML tables. Default table
+ -<strong>w </strong> Print out results in HTML tables. Default table
is two columns wide, with a white background.
- -<strong>x </strong><em>attributes</em>
+ -<strong>x</strong> <em>attributes</em>
String to use as attributes for <table>. Attri-
- butes are inserted <table <strong>here </strong>>
+ butes are inserted <table <strong>here</strong> >
- -<strong>y </strong><em>attributes</em>
+ -<strong>y</strong> <em>attributes</em>
String to use as attributes for <tr>.
- -<strong>z </strong><em>attributes</em>
+ -<strong>z</strong> <em>attributes</em>
String to use as attributes for <td>.
- -<strong>V </strong>Display version number and exit.
+ -<strong>V </strong> Display version number and exit.
- -<strong>h </strong>Display usage information.
+ -<strong>h </strong> Display usage information.
<strong>BUGS</strong>
There are various statically declared buffers of fixed
It does not implement HTTP/1.x fully; only accepts some
'expected' forms of responses. The rather heavy use of
- <strong>strstr(3) </strong>shows up top in profile, which might indicate a
- performance problem; i.e., you would measure the <strong>ab </strong>perfor-
+ <strong>strstr(3)</strong> shows up top in profile, which might indicate a
+ performance problem; i.e., you would measure the <strong>ab</strong> perfor-
mance rather than the server's.
<strong>SEE ALSO</strong>
<strong>httpd(8)</strong>
</pre>
-<!--#include virtual="footer.html" -->
-</body></html>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head><title>Manual Page: apachectl - Apache HTTP Server</title></head>
-<body bgcolor="#ffffff" text="#000000" link="#0000ff"
-vlink="#000080" alink="#ff0000">
-<!--#include virtual="header.html" -->
-<h1 align="center">Manual Page: apachectl</h1>
-<!-- This document was autogenerated from the man page -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Manual Page: apachectl - Apache HTTP Server</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#0000ff"
+ vlink="#000080" alink="#ff0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="center">Manual Page: apachectl</h1>
+ <!-- This document was autogenerated from the man page -->
<pre>
<strong>NAME</strong>
apachectl - Apache HTTP server control interface
<strong>SYNOPSIS</strong>
- <strong>apachectl </strong><em>command </em>[...]
+ <strong>apachectl</strong> <em>command</em> [...]
<strong>DESCRIPTION</strong>
- <strong>apachectl </strong>is a front end to the Apache HyperText Transfer
+ <strong>apachectl</strong> is a front end to the Apache HyperText Transfer
Protocol (HTTP) server. It is designed to help the adminis-
- trator control the functioning of the Apache <strong>httpd </strong>daemon.
+ trator control the functioning of the Apache <strong>httpd</strong> daemon.
- <strong>NOTE: </strong>If your Apache installation uses non-standard paths,
- you will need to edit the <strong>apachectl </strong>script to set the
- appropriate paths to your PID file and your <strong>httpd </strong>binary.
+ <strong>NOTE:</strong> If your Apache installation uses non-standard paths,
+ you will need to edit the <strong>apachectl</strong> script to set the
+ appropriate paths to your PID file and your <strong>httpd</strong> binary.
See the comments in the script for details.
- The <strong>apachectl </strong>script returns a 0 exit value on success, and
+ The <strong>apachectl</strong> script returns a 0 exit value on success, and
>0 if an error occurs. For more details, view the comments
in the script.
<strong>http://httpd.apache.org/</strong>
<strong>OPTIONS</strong>
- The <em>command </em>can be any one or more of the following options:
+ The <em>command</em> can be any one or more of the following options:
- <strong>start </strong>Start the Apache daemon. Gives an error if it
+ <strong>start </strong> Start the Apache daemon. Gives an error if it
is already running.
- <strong>stop </strong>Stops the Apache daemon.
+ <strong>stop </strong> Stops the Apache daemon.
- <strong>restart </strong>Restarts the Apache daemon by sending it a
+ <strong>restart </strong> Restarts the Apache daemon by sending it a
SIGHUP. If the daemon is not running, it is
started. This command automatically checks the
- configuration files via <strong>configtest </strong>before ini-
+ configuration files via <strong>configtest</strong> before ini-
tiating the restart to make sure Apache doesn't
die.
- <strong>fullstatus </strong>Displays a full status report from <strong>mod_status.</strong>
+ <strong>fullstatus</strong> Displays a full status report from <strong>mod_status.</strong>
For this to work, you need to have mod_status
enabled on your server and a text-based browser
- such as <em>lynx </em>available on your system. The URL
+ such as <em>lynx</em> available on your system. The URL
used to access the status report can be set by
- editing the <strong>STATUSURL </strong>variable in the script.
+ editing the <strong>STATUSURL</strong> variable in the script.
- <strong>status </strong>Displays a brief status report. Similar to the
+ <strong>status </strong> Displays a brief status report. Similar to the
fullstatus option, except that the list of
requests currently being served is omitted.
- <strong>graceful </strong>Gracefully restarts the Apache daemon by sending
+ <strong>graceful</strong> Gracefully restarts the Apache daemon by sending
it a SIGUSR1. If the daemon is not running, it
is started. This differs from a normal restart
in that currently open connections are not
delay may be necessary to ensure that the old
log files are closed before processing them.
This command automatically checks the configura-
- tion files via <strong>configtest </strong>before initiating the
+ tion files via <strong>configtest</strong> before initiating the
restart to make sure Apache doesn't die. <i>On
certain platforms that do not allow USR1 to be
used for a graceful restart, an alternative
graceful will send the right signal for your
platform.</i>
- <strong>configtest </strong>Run a configuration file syntax test. It parses
+ <strong>configtest</strong> Run a configuration file syntax test. It parses
the configuration files and either reports <strong>Syn-</strong>
- <strong>tax Ok </strong>or detailed information about the partic-
+ <strong>tax Ok</strong> or detailed information about the partic-
ular syntax error.
- <strong>help </strong>Displays a short help message.
+ <strong>help </strong> Displays a short help message.
<strong>SEE ALSO</strong>
<strong>httpd(8)</strong>
</pre>
-<!--#include virtual="footer.html" -->
-</body></html>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head><title>Manual Page: apxs - Apache HTTP Server</title></head>
-<body bgcolor="#ffffff" text="#000000" link="#0000ff"
-vlink="#000080" alink="#ff0000">
-<!--#include virtual="header.html" -->
-<h1 align="center">Manual Page: apxs</h1>
-<!-- This document was autogenerated from the man page -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Manual Page: apxs - Apache HTTP Server</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#0000ff"
+ vlink="#000080" alink="#ff0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="center">Manual Page: apxs</h1>
+ <!-- This document was autogenerated from the man page -->
<pre>
<strong>NAME</strong>
apxs - APache eXtenSion tool
<strong>SYNOPSIS</strong>
- <strong>apxs </strong>-<strong>g </strong>[ -<strong>S </strong><em>name</em>=<em>value </em>] -<strong>n </strong><em>modname</em>
+ <strong>apxs</strong> -<strong>g</strong> [ -<strong>S</strong> <em>name</em>=<em>value</em> ] -<strong>n</strong> <em>modname</em>
- <strong>apxs </strong>-<strong>q </strong>[ -<strong>S </strong><em>name</em>=<em>value </em>] <em>query </em>...
+ <strong>apxs</strong> -<strong>q</strong> [ -<strong>S</strong> <em>name</em>=<em>value</em> ] <em>query</em> ...
- <strong>apxs </strong>-<strong>c </strong>[ -<strong>S </strong><em>name</em>=<em>value </em>] [ -<strong>o </strong><em>dsofile </em>] [ -<strong>I </strong><em>incdir </em>] [ -<strong>D</strong>
- <em>name</em>=<em>value </em>] [ -<strong>L </strong><em>libdir </em>] [ -<strong>l </strong><em>libname </em>] [ -<strong>Wc,</strong><em>compiler</em>-
- <em>flags </em>] [ -<strong>Wl,</strong><em>linker</em>-<em>flags </em>] <em>files </em>...
+ <strong>apxs</strong> -<strong>c</strong> [ -<strong>S</strong> <em>name</em>=<em>value</em> ] [ -<strong>o</strong> <em>dsofile</em> ] [ -<strong>I</strong> <em>incdir</em> ] [ -<strong>D</strong>
+ <em>name</em>=<em>value</em> ] [ -<strong>L</strong> <em>libdir</em> ] [ -<strong>l</strong> <em>libname</em> ] [ -<strong>Wc,</strong><em>compiler</em>-
+ <em>flags</em> ] [ -<strong>Wl,</strong><em>linker</em>-<em>flags</em> ] <em>files</em> ...
- <strong>apxs </strong>-<strong>i </strong>[ -<strong>S </strong><em>name</em>=<em>value </em>] [ -<strong>n </strong><em>modname </em>] [ -<strong>a </strong>] [ -<strong>A </strong>] <em>dso-</em>
- <em>file </em>...
+ <strong>apxs</strong> -<strong>i</strong> [ -<strong>S</strong> <em>name</em>=<em>value</em> ] [ -<strong>n</strong> <em>modname</em> ] [ -<strong>a</strong> ] [ -<strong>A</strong> ] <em>dso-</em>
+ <em>file</em> ...
- <strong>apxs </strong>-<strong>e </strong>[ -<strong>S </strong><em>name</em>=<em>value </em>] [ -<strong>n </strong><em>modname </em>] [ -<strong>a </strong>] [ -<strong>A </strong>] <em>dso-</em>
- <em>file </em>...
+ <strong>apxs</strong> -<strong>e</strong> [ -<strong>S</strong> <em>name</em>=<em>value</em> ] [ -<strong>n</strong> <em>modname</em> ] [ -<strong>a</strong> ] [ -<strong>A</strong> ] <em>dso-</em>
+ <em>file</em> ...
<strong>DESCRIPTION</strong>
- <strong>apxs </strong>is a tool for building and installing extension modules
+ <strong>apxs</strong> is a tool for building and installing extension modules
for the Apache HyperText Transfer Protocol (HTTP) server.
This is achieved by building a dynamic shared object (DSO)
- from one or more source or object <em>files </em>which then can be
+ from one or more source or object <em>files</em> which then can be
loaded into the Apache server under runtime via the <strong>LoadMo-</strong>
- <strong>dule </strong>directive from <strong>mod_so.</strong>
+ <strong>dule</strong> directive from <strong>mod_so.</strong>
So to use this extension mechanism your platform has to sup-
- port the DSO feature and your Apache <strong>httpd </strong>binary has to be
- built with the <strong>mod_so </strong>module. The <strong>apxs </strong>tool automatically
+ port the DSO feature and your Apache <strong>httpd</strong> binary has to be
+ built with the <strong>mod_so</strong> module. The <strong>apxs</strong> tool automatically
complains if this is not the case. You can check this your-
self by manually running the command
$ httpd -l
- The module <strong>mod_so </strong>should be part of the displayed list. If
+ The module <strong>mod_so</strong> should be part of the displayed list. If
these requirements are fulfilled you can easily extend your
Apache server's functionality by installing your own modules
- with the DSO mechanism by the help of this <strong>apxs </strong>tool:
+ with the DSO mechanism by the help of this <strong>apxs</strong> tool:
$ apxs -i -a -c mod_foo.c
gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
/path/to/apache/sbin/apachectl restart: httpd started
$ _
- The arguments <em>files </em>can be any C source file (.c), a object
- file (.o) or even a library archive (.a). The <strong>apxs </strong>tool
+ The arguments <em>files</em> can be any C source file (.c), a object
+ file (.o) or even a library archive (.a). The <strong>apxs</strong> tool
automatically recognizes these extensions and automatically
used the C source files for compilation while just using the
object and archive files for the linking phase. But when
for a dynamically loaded shared object. For instance with
GCC you always just have to use <strong>-fpic</strong>. For other C com-
pilers consult its manual page or at watch for the flags
- <strong>apxs </strong>uses to compile the object files.
+ <strong>apxs</strong> uses to compile the object files.
For more details about DSO support in Apache read the docu-
- mentation of <strong>mod_so </strong>or perhaps even read the
- <strong>src/modules/standard/mod_so.c </strong>source file.
+ mentation of <strong>mod_so</strong> or perhaps even read the
+ <strong>src/modules/standard/mod_so.c</strong> source file.
<strong>OPTIONS</strong>
Common options:
- -<strong>n </strong><em>modname </em>This explicitly sets the module name for the -<strong>i</strong>
- (install) and -<strong>g </strong>(template generation) option.
+ -<strong>n</strong> <em>modname</em> This explicitly sets the module name for the -<strong>i</strong>
+ (install) and -<strong>g</strong> (template generation) option.
Use this to explicitly specify the module name.
- For option -<strong>g </strong>this is required, for option -<strong>i</strong>
- the <strong>apxs </strong>tool tries to determine the name from
+ For option -<strong>g</strong> this is required, for option -<strong>i</strong>
+ the <strong>apxs</strong> tool tries to determine the name from
the source or (as a fallback) at least by guess-
ing it from the filename.
Query options:
- -<strong>q </strong>Performs a query for <strong>apxs</strong>'s knowledge about cer-
- tain settings. The <em>query </em>parameters can be one
+ -<strong>q </strong> Performs a query for <strong>apxs</strong>'s knowledge about cer-
+ tain settings. The <em>query</em> parameters can be one
or more of the following strings:
CC TARGET
CFLAGS SBINDIR
Configuration options:
- -<strong>S </strong><em>name</em>=<em>value</em>
+ -<strong>S</strong> <em>name</em>=<em>value</em>
This option changes the apxs settings described
above.
Template Generation options:
- -<strong>g </strong>This generates a subdirectory <em>name </em>(see option
+ -<strong>g </strong> This generates a subdirectory <em>name</em> (see option
-<strong>n</strong>) and there two files: A sample module source
- file named <strong>mod_</strong><em>name</em>.<em>c </em>which can be used as a
+ file named <strong>mod_</strong><em>name</em>.<em>c</em> which can be used as a
template for creating your own modules or as a
quick start for playing with the APXS mechanism.
- And a corresponding <strong>Makefile </strong>for even easier
+ And a corresponding <strong>Makefile</strong> for even easier
build and installing of this module.
DSO compilation options:
- -<strong>c </strong>This indicates the compilation operation. It
+ -<strong>c </strong> This indicates the compilation operation. It
first compiles the C source files (.c) of <em>files</em>
into corresponding object files (.o) and then
- builds a dynamically shared object in <em>dsofile </em>by
+ builds a dynamically shared object in <em>dsofile</em> by
linking these object files plus the remaining
- object files (.o and .a) of <em>files </em>If no -<strong>o</strong>
+ object files (.o and .a) of <em>files</em> If no -<strong>o</strong>
option is specified the output file is guessed
- from the first filename in <em>files </em>and thus usu-
+ from the first filename in <em>files</em> and thus usu-
ally defaults to <strong>mod_</strong><em>name</em>.<em>so</em>
- -<strong>o </strong><em>dsofile </em>Explicitly specifies the filename of the created
+ -<strong>o</strong> <em>dsofile</em> Explicitly specifies the filename of the created
dynamically shared object. If not specified and
- the name cannot be guessed from the <em>files </em>list,
- the fallback name <strong>mod_unknown.so </strong>is used.
+ the name cannot be guessed from the <em>files</em> list,
+ the fallback name <strong>mod_unknown.so</strong> is used.
- -<strong>D </strong><em>name</em>=<em>value</em>
+ -<strong>D</strong> <em>name</em>=<em>value</em>
This option is directly passed through to the
compilation command(s). Use this to add your
own defines to the build process.
- -<strong>I </strong><em>incdir </em>This option is directly passed through to the
+ -<strong>I</strong> <em>incdir</em> This option is directly passed through to the
compilation command(s). Use this to add your
own include directories to search to the build
process.
- -<strong>L </strong><em>libdir </em>This option is directly passed through to the
+ -<strong>L</strong> <em>libdir</em> This option is directly passed through to the
linker command. Use this to add your own
library directories to search to the build pro-
cess.
- -<strong>l </strong><em>libname </em>This option is directly passed through to the
+ -<strong>l</strong> <em>libname</em> This option is directly passed through to the
linker command. Use this to add your own
libraries to search to the build process.
-<strong>Wc,</strong><em>compiler</em>-<em>flags</em>
- This option passes <em>compiler</em>-<em>flags </em>as additional
+ This option passes <em>compiler</em>-<em>flags</em> as additional
flags to the compiler command. Use this to add
local compiler-specific options.
-<strong>Wl,</strong><em>linker</em>-<em>flags</em>
- This option passes <em>linker</em>-<em>flags </em>as additional
+ This option passes <em>linker</em>-<em>flags</em> as additional
flags to the linker command. Use this to add
local linker-specific options.
DSO installation and configuration options:
- -<strong>i </strong>This indicates the installation operation and
+ -<strong>i </strong> This indicates the installation operation and
installs one or more dynamically shared objects
- into the server's <em>modules </em>directory.
+ into the server's <em>modules</em> directory.
- -<strong>a </strong>This activates the module by automatically
- adding a corresponding <strong>LoadModule </strong>line to
- Apache's <strong>httpd.conf </strong>configuration file, or by
+ -<strong>a </strong> This activates the module by automatically
+ adding a corresponding <strong>LoadModule</strong> line to
+ Apache's <strong>httpd.conf</strong> configuration file, or by
enabling it if it already exists.
- -<strong>A </strong>Same as option -<strong>a </strong>but the created <strong>LoadModule</strong>
+ -<strong>A </strong> Same as option -<strong>a</strong> but the created <strong>LoadModule</strong>
directive is prefixed with a hash sign (#), i.e.
the module is just prepared for later activation
but initially disabled.
- -<strong>e </strong>This indicates the editing operation, which can
- be used with the -<strong>a </strong>and -<strong>A </strong>options similarly to
- the -<strong>i </strong>operation to edit Apache's <strong>httpd.conf</strong>
+ -<strong>e </strong> This indicates the editing operation, which can
+ be used with the -<strong>a</strong> and -<strong>A</strong> options similarly to
+ the -<strong>i</strong> operation to edit Apache's <strong>httpd.conf</strong>
configuration file without attempting to install
the module.
$ _
Then you have to update the Apache configuration by making
- sure a <strong>LoadModule </strong>directive is present to load this shared
- object. To simplify this step <strong>apxs </strong>provides an automatic way
+ sure a <strong>LoadModule</strong> directive is present to load this shared
+ object. To simplify this step <strong>apxs</strong> provides an automatic way
to install the shared object in its "modules" directory and
- updating the <strong>httpd.conf </strong>file accordingly. This can be
+ updating the <strong>httpd.conf</strong> file accordingly. This can be
achieved by running:
$ apxs -i -a mod_foo.c
/path/to/apache/sbin/apachectl restart: httpd started
$ _
- You can even use <strong>apxs </strong>to compile complex modules outside the
+ You can even use <strong>apxs</strong> to compile complex modules outside the
Apache source tree, like PHP3:
$ cd php3
ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a
$ _
- because <strong>apxs </strong>automatically recognized C source files and
+ because <strong>apxs</strong> automatically recognized C source files and
object files. Only C source files are compiled while
remaining object files are used for the linking phase.
<strong>apachectl(1), httpd(8).</strong>
</pre>
-<!--#include virtual="footer.html" -->
-</body></html>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head><title>Manual Page: dbmmanage - Apache HTTP Server</title></head>
-<body bgcolor="#ffffff" text="#000000" link="#0000ff"
-vlink="#000080" alink="#ff0000">
-<!--#include virtual="header.html" -->
-<h1 align="center">Manual Page: dbmmanage</h1>
-<!-- This document was autogenerated from the man page -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Manual Page: dbmmanage - Apache HTTP Server</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#0000ff"
+ vlink="#000080" alink="#ff0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="center">Manual Page: dbmmanage</h1>
+ <!-- This document was autogenerated from the man page -->
<pre>
<strong>NAME</strong>
dbmmanage - Create and update user authentication files in
DBM format
<strong>SYNOPSIS</strong>
- <strong>dbmmanage </strong><em>filename </em>[ <em>command </em>] [ <em>username </em>[ <em>encpasswd </em>] ]
+ <strong>dbmmanage</strong> <em>filename</em> [ <em>command</em> ] [ <em>username</em> [ <em>encpasswd</em> ] ]
<strong>DESCRIPTION</strong>
- <strong>dbmmanage </strong>is used to create and update the DBM format files
+ <strong>dbmmanage</strong> is used to create and update the DBM format files
used to store usernames and password for basic authentica-
tion of HTTP users. Resources available from the <strong>httpd</strong>
Apache web server can be restricted to just the users listed
- in the files created by <strong>dbmmanage. </strong>This program can only be
+ in the files created by <strong>dbmmanage.</strong> This program can only be
used when the usernames are stored in a DBM file. To use a
flat-file database see <strong>htpasswd</strong>.
This manual page only lists the command line arguments. For
details of the directives necessary to configure user
- authentication in <strong>httpd </strong>see the Apache manual, which is part
+ authentication in <strong>httpd</strong> see the Apache manual, which is part
of the Apache distribution or can be found at
http://www.apache.org/.
<em>command</em>
This selects the operation to perform:
- <strong>add </strong>Adds an entry for <em>username </em>to <em>filename </em>using the
+ <strong>add </strong> Adds an entry for <em>username</em> to <em>filename</em> using the
encrypted password <em>encpassword</em>.
- <strong>adduser </strong>Asks for a password and then adds an entry for
- <em>username </em>to <em>filename </em>.
+ <strong>adduser </strong> Asks for a password and then adds an entry for
+ <em>username</em> to <em>filename</em> .
- <strong>check </strong>Asks for a password and then checks if <em>username</em>
- is in <em>filename </em>and if it's password matches the
+ <strong>check </strong> Asks for a password and then checks if <em>username</em>
+ is in <em>filename</em> and if it's password matches the
specified one.
- <strong>delete </strong>Deletes the <em>username </em>entry from <em>filename</em>.
+ <strong>delete </strong> Deletes the <em>username</em> entry from <em>filename</em>.
- <strong>import </strong>Reads username:password entries (one per line)
+ <strong>import </strong> Reads username:password entries (one per line)
from STDIN and adds them to <em>filename</em>. The pass-
words already has to be crypted.
- <strong>update </strong>Same as the "adduser" command, except that it
- makes sure <em>username </em>already exists in <em>filename</em>.
+ <strong>update </strong> Same as the "adduser" command, except that it
+ makes sure <em>username</em> already exists in <em>filename</em>.
- <strong>view </strong>Just displays the complete contents of the DBM
+ <strong>view </strong> Just displays the complete contents of the DBM
file.
- <em>username </em>The user for which the update operation is per-
+ <em>username</em> The user for which the update operation is per-
formed.
<strong>BUGS</strong>
The three primary examples are NDBM, the GNU project's GDBM,
and Berkeley DB 2. Unfortunately, all these libraries use
different file formats, and you must make sure that the file
- format used by <em>filename </em>is the same format that <strong>dbmmanage</strong>
- expects to see. <strong>dbmmanage </strong>currently has no way of determin-
+ format used by <em>filename</em> is the same format that <strong>dbmmanage</strong>
+ expects to see. <strong>dbmmanage</strong> currently has no way of determin-
ing what type of DBM file it is looking at. If used against
the wrong format, will simply return nothing, or may create
a different DBM file with a different name, or at worst, it
may corrupt the DBM file if you were attempting to write to
it.
- <strong>dbmmanage </strong>has a list of DBM format preferences, defined by
- the <strong>@AnyDBM::ISA </strong>array near the beginning of the program.
+ <strong>dbmmanage</strong> has a list of DBM format preferences, defined by
+ the <strong>@AnyDBM::ISA</strong> array near the beginning of the program.
Since we prefer the Berkeley DB 2 file format, the order in
- which <strong>dbmmanage </strong>will look for system libraries is Berkeley
+ which <strong>dbmmanage</strong> will look for system libraries is Berkeley
DB 2, then NDBM, and then GDBM. The first library found
- will be the library <strong>dbmmanage </strong>will attempt to use for all
+ will be the library <strong>dbmmanage</strong> will attempt to use for all
DBM file transactions. This ordering is slightly different
- than the standard <strong>@AnyDBM::ISA </strong>ordering in perl, as well as
+ than the standard <strong>@AnyDBM::ISA</strong> ordering in perl, as well as
the ordering used by the simple dbmopen() call in Perl, so
if you use any other utilities to manage your DBM files,
they must also follow this preference ordering. Similar
care must be taken if using programs in other languages,
like C, to access these files.
- Apache's <strong>mod_auth_db.c </strong>module corresponds to Berkeley DB 2
- library, while <strong>mod_auth_dbm.c </strong>corresponds to the NDBM
- library. Also, one can usually use the <strong>file </strong>program sup-
+ Apache's <strong>mod_auth_db.c</strong> module corresponds to Berkeley DB 2
+ library, while <strong>mod_auth_dbm.c</strong> corresponds to the NDBM
+ library. Also, one can usually use the <strong>file</strong> program sup-
plied with most Unix systems to see what format a DBM file
is in.
<strong>httpd(8)</strong>
</pre>
-<!--#include virtual="footer.html" -->
-</body></html>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<HR>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<H3 ALIGN="CENTER">
- Apache HTTP Server Version 2.0
-</H3>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title></title>
+ </head>
+
+ <body>
+ <hr />
+
+ <h3 align="CENTER">Apache HTTP Server Version 2.0</h3>
+ <a href="./"><img src="../images/index.gif" alt="Index" /></a>
+ <a href="../"><img src="../images/home.gif" alt="Home" /></a>
+ </body>
+</html>
-<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A>
-<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A>
-<DIV ALIGN="CENTER">
- <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]">
- <H3>
- Apache HTTP Server Version 2.0
- </H3>
-</DIV>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title></title>
+ </head>
+
+ <body>
+ <div align="CENTER">
+ <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" />
+
+ <h3>Apache HTTP Server Version 2.0</h3>
+ </div>
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head><title>Manual Page: htdigest - Apache HTTP Server</title></head>
-<body bgcolor="#ffffff" text="#000000" link="#0000ff"
-vlink="#000080" alink="#ff0000">
-<!--#include virtual="header.html" -->
-<h1 align="center">Manual Page: htdigest</h1>
-<!-- This document was autogenerated from the man page -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Manual Page: htdigest - Apache HTTP Server</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#0000ff"
+ vlink="#000080" alink="#ff0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="center">Manual Page: htdigest</h1>
+ <!-- This document was autogenerated from the man page -->
<pre>
<strong>NAME</strong>
htdigest - Create and update user authentication files
<strong>SYNOPSIS</strong>
- <strong>htdigest </strong>[ -<strong>c </strong>] <em>passwdfile realm username</em>
+ <strong>htdigest</strong> [ -<strong>c</strong> ] <em>passwdfile realm username</em>
<strong>DESCRIPTION</strong>
- <strong>htdigest </strong>is used to create and update the flat-files used to
+ <strong>htdigest</strong> is used to create and update the flat-files used to
store usernames, realm and password for digest authentica-
tion of HTTP users. Resources available from the <strong>httpd</strong>
Apache web server can be restricted to just the users listed
This manual page only lists the command line arguments. For
details of the directives necessary to configure digest
- authentication in <strong>httpd </strong>see the Apache manual, which is part
+ authentication in <strong>httpd</strong> see the Apache manual, which is part
of the Apache distribution or can be found at
http://www.apache.org/.
<strong>OPTIONS</strong>
- -c Create the <em>passwdfile</em>. If <em>passwdfile </em>already exists, it
+ -c Create the <em>passwdfile</em>. If <em>passwdfile</em> already exists, it
is deleted first.
<em>passwdfile</em>
<em>username</em>
The user name to create or update in <strong>passwdfile</strong>. If
- <em>username </em>does not exist is this file, an entry is
+ <em>username</em> does not exist is this file, an entry is
added. If it does exist, the password is changed.
<strong>SEE ALSO</strong>
<strong>httpd(8)</strong>
</pre>
-<!--#include virtual="footer.html" -->
-</body></html>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head><title>Manual Page: htpasswd - Apache HTTP Server</title></head>
-<body bgcolor="#ffffff" text="#000000" link="#0000ff"
-vlink="#000080" alink="#ff0000">
-<!--#include virtual="header.html" -->
-<h1 align="center">Manual Page: htpasswd</h1>
-<!-- This document was autogenerated from the man page -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Manual Page: htpasswd - Apache HTTP Server</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#0000ff"
+ vlink="#000080" alink="#ff0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="center">Manual Page: htpasswd</h1>
+ <!-- This document was autogenerated from the man page -->
<pre>
<strong>NAME</strong>
htpasswd - Create and update user authentication files
<strong>SYNOPSIS</strong>
- <strong>htpasswd </strong>[ -<strong>c </strong>] [ -<strong>m </strong>] <em>passwdfile username</em>
- <strong>htpasswd </strong>-<strong>b </strong>[ -<strong>c </strong>] [ -<strong>m </strong>| -<strong>d </strong>| -<strong>p </strong>| -<strong>s </strong>] <em>passwdfile username</em>
+ <strong>htpasswd</strong> [ -<strong>c</strong> ] [ -<strong>m</strong> ] <em>passwdfile username</em>
+ <strong>htpasswd</strong> -<strong>b</strong> [ -<strong>c</strong> ] [ -<strong>m</strong> | -<strong>d</strong> | -<strong>p</strong> | -<strong>s</strong> ] <em>passwdfile username</em>
<em>password</em>
- <strong>htpasswd </strong>-<strong>n </strong>[ -<strong>m </strong>| -<strong>d </strong>| -<strong>s </strong>| -<strong>p </strong>] <em>username</em>
- <strong>htpasswd </strong>-<strong>nb </strong>[ -<strong>m </strong>| -<strong>d </strong>| -<strong>s </strong>| -<strong>p </strong>] <em>username password</em>
+ <strong>htpasswd</strong> -<strong>n</strong> [ -<strong>m</strong> | -<strong>d</strong> | -<strong>s</strong> | -<strong>p</strong> ] <em>username</em>
+ <strong>htpasswd</strong> -<strong>nb</strong> [ -<strong>m</strong> | -<strong>d</strong> | -<strong>s</strong> | -<strong>p</strong> ] <em>username password</em>
<strong>DESCRIPTION</strong>
- <strong>htpasswd </strong>is used to create and update the flat-files used to
+ <strong>htpasswd</strong> is used to create and update the flat-files used to
store usernames and password for basic authentication of
- HTTP users. If <strong>htpasswd </strong>cannot access a file, such as not
+ HTTP users. If <strong>htpasswd</strong> cannot access a file, such as not
being able to write to the output file or not being able to
read the file in order to update it, it returns an error
status and makes no changes.
- Resources available from the <strong>httpd </strong>Apache web server can be
+ Resources available from the <strong>httpd</strong> Apache web server can be
restricted to just the users listed in the files created by
- <strong>htpasswd. </strong>This program can only manage usernames and pass-
+ <strong>htpasswd.</strong> This program can only manage usernames and pass-
words stored in a flat-file. It can encrypt and display
password information for use in other types of data stores,
though. To use a DBM database see <strong>dbmmanage</strong>.
- <strong>htpasswd </strong>encrypts passwords using either a version of MD5
+ <strong>htpasswd</strong> encrypts passwords using either a version of MD5
modified for Apache, or the system's <em>crypt</em>() routine. Files
- managed by <strong>htpasswd </strong>may contain both types of passwords;
+ managed by <strong>htpasswd</strong> may contain both types of passwords;
some user records may have MD5-encrypted passwords while
others in the same file may have passwords encrypted with
<em>crypt</em>().
This manual page only lists the command line arguments. For
details of the directives necessary to configure user
- authentication in <strong>httpd </strong>see the Apache manual, which is part
+ authentication in <strong>httpd</strong> see the Apache manual, which is part
of the Apache distribution or can be found at
<URL:http://www.apache.org/>.
<strong>be used with extreme care, since the password is</strong>
<strong>clearly visible on the command line.</strong>
- -c Create the <em>passwdfile</em>. If <em>passwdfile </em>already exists, it
+ -c Create the <em>passwdfile</em>. If <em>passwdfile</em> already exists, it
is rewritten and truncated. This option cannot be com-
- bined with the <strong>-n </strong>option.
+ bined with the <strong>-n</strong> option.
-n Display the results on standard output rather than
updating a file. This is useful for generating pass-
word records acceptable to Apache for inclusion in
non-text data stores. This option changes the syntax
- of the command line, since the <em>passwdfile </em>argument
+ of the command line, since the <em>passwdfile</em> argument
(usually the first one) is omitted. It cannot be com-
- bined with the <strong>-c </strong>option.
+ bined with the <strong>-c</strong> option.
-m Use MD5 encryption for passwords. On Windows and TPF,
this is the default.
-d Use crypt() encryption for passwords. The default on
all platforms but Windows and TPF. Though possibly sup-
- ported by <strong>htpasswd </strong>on all platforms, it is not sup-
- ported by the <strong>httpd </strong>server on Windows and TPF.
+ ported by <strong>htpasswd</strong> on all platforms, it is not sup-
+ ported by the <strong>httpd</strong> server on Windows and TPF.
-s Use SHA encryption for passwords. Facilitates migration
from/to Netscape servers using the LDAP Directory
Interchange Format (ldif).
- -p Use plaintext passwords. Though <strong>htpasswd </strong>will support
- creation on all platforms, the <strong>httpd </strong>daemon will only
+ -p Use plaintext passwords. Though <strong>htpasswd</strong> will support
+ creation on all platforms, the <strong>httpd</strong> daemon will only
accept plain text passwords on Windows and TPF.
<em>passwdfile</em>
<em>username</em>
The username to create or update in <strong>passwdfile</strong>. If
- <em>username </em>does not exist in this file, an entry is
+ <em>username</em> does not exist in this file, an entry is
added. If it does exist, the password is changed.
<em>password</em>
The plaintext password to be encrypted and stored in
- the file. Only used with the -<em>b </em>flag.
+ the file. Only used with the -<em>b</em> flag.
<strong>EXIT STATUS</strong>
- <strong>htpasswd </strong>returns a zero status ("true") if the username and
+ <strong>htpasswd</strong> returns a zero status ("true") if the username and
password have been successfully added or updated in the
- <em>passwdfile</em>. <strong>htpasswd </strong>returns 1 if it encounters some prob-
+ <em>passwdfile</em>. <strong>htpasswd</strong> returns 1 if it encounters some prob-
lem accessing files, 2 if there was a syntax problem with
the command line, 3 if the password was entered interac-
tively and the verification entry didn't match, 4 if its
operation was interrupted, 5 if a value is too long (user-
name, filename, password, or final computed record), and 6
if the username contains illegal characters (see the <strong>RES-</strong>
- <strong>TRICTIONS </strong>section).
+ <strong>TRICTIONS</strong> section).
<strong>EXAMPLES</strong>
<strong>htpasswd /usr/local/etc/apache/.htpasswd-users jsmith</strong>
system, the password will be encrypted using the modi-
fied Apache MD5 algorithm; otherwise, the system's
<em>crypt</em>() routine will be used. If the file does not
- exist, <strong>htpasswd </strong>will do nothing except return an error.
+ exist, <strong>htpasswd</strong> will do nothing except return an error.
<strong>htpasswd -c /home/doe/public_html/.htpasswd jane</strong>
Creates a new file and stores a record in it for user
<em>jane</em>. The user is prompted for the password. If the
file exists and cannot be read, or cannot be written,
- it is not altered and <strong>htpasswd </strong>will display a message
+ it is not altered and <strong>htpasswd</strong> will display a message
and return an error status.
<strong>htpasswd -mb /usr/web/.htpasswd-all jones Pwd4Steve</strong>
file.
<strong>SECURITY CONSIDERATIONS</strong>
- Web password files such as those managed by <strong>htpasswd </strong>should
- <strong>not </strong>be within the Web server's URI space -- that is, they
+ Web password files such as those managed by <strong>htpasswd</strong> should
+ <strong>not</strong> be within the Web server's URI space -- that is, they
should not be fetchable with a browser.
- The use of the -<em>b </em>option is discouraged, since when it is
+ The use of the -<em>b</em> option is discouraged, since when it is
used the unencrypted password appears on the command line.
<strong>RESTRICTIONS</strong>
On the Windows and MPE platforms, passwords encrypted with
- <strong>htpasswd </strong>are limited to no more than 255 characters in
+ <strong>htpasswd</strong> are limited to no more than 255 characters in
length. Longer passwords will be truncated to 255 charac-
ters.
- The MD5 algorithm used by <strong>htpasswd </strong>is specific to the Apache
+ The MD5 algorithm used by <strong>htpasswd</strong> is specific to the Apache
software; passwords encrypted using it will not be usable
with other Web servers.
character ':'.
<strong>SEE ALSO</strong>
- <strong>httpd(8) </strong>and the scripts in support/SHA1 which come with the
+ <strong>httpd(8)</strong> and the scripts in support/SHA1 which come with the
distribution.
</pre>
-<!--#include virtual="footer.html" -->
-</body></html>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head><title>Manual Page: httpd - Apache HTTP Server</title></head>
-<body bgcolor="#ffffff" text="#000000" link="#0000ff"
-vlink="#000080" alink="#ff0000">
-<!--#include virtual="header.html" -->
-<h1 align="center">Manual Page: httpd</h1>
-<!-- This document was autogenerated from the man page -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Manual Page: httpd - Apache HTTP Server</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#0000ff"
+ vlink="#000080" alink="#ff0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="center">Manual Page: httpd</h1>
+ <!-- This document was autogenerated from the man page -->
<pre>
<strong>NAME</strong>
httpd - Apache hypertext transfer protocol server
<strong>SYNOPSIS</strong>
- <strong>httpd </strong>[ -<strong>R </strong><em>libexecdir </em>] [ -<strong>d </strong><em>serverroot </em>] [ -<strong>f </strong><em>config </em>] [ -<strong>C</strong>
- <em>directive </em>] [ -<strong>c </strong><em>directive </em>] [ -<strong>D </strong><em>parameter </em>]
+ <strong>httpd</strong> [ -<strong>R</strong> <em>libexecdir</em> ] [ -<strong>d</strong> <em>serverroot</em> ] [ -<strong>f</strong> <em>config</em> ] [ -<strong>C</strong>
+ <em>directive</em> ] [ -<strong>c</strong> <em>directive</em> ] [ -<strong>D</strong> <em>parameter</em> ]
- <strong>httpd </strong>[ -<strong>h </strong>] [ -<strong>l </strong>] [ -<strong>L </strong>] [ -<strong>v </strong>] [ -<strong>V </strong>] [ -<strong>t </strong>] [ -<strong>T </strong>]
+ <strong>httpd</strong> [ -<strong>h</strong> ] [ -<strong>l</strong> ] [ -<strong>L</strong> ] [ -<strong>v</strong> ] [ -<strong>V</strong> ] [ -<strong>t</strong> ] [ -<strong>T</strong> ]
<strong>DESCRIPTION</strong>
- <strong>httpd </strong>is the Apache HyperText Transfer Protocol (HTTP)
+ <strong>httpd</strong> is the Apache HyperText Transfer Protocol (HTTP)
server program. It is designed to be run as a standalone
daemon process. When used like this it will create a pool of
child processes to handle requests. To stop it, send a TERM
file.
This manual page only lists the command line arguments. For
- details of the directives necessary to configure <strong>httpd </strong>see
+ details of the directives necessary to configure <strong>httpd</strong> see
the Apache manual, which is part of the Apache distribution
or can be found at http://httpd.apache.org/. Paths in this
manual may not reflect those compiled into <strong>httpd.</strong>
<strong>OPTIONS</strong>
- -<strong>R </strong><em>libexecdir</em>
+ -<strong>R</strong> <em>libexecdir</em>
This option is only available if Apache was
- built with the <em>SHARED</em>_<em>CORE </em>rule enabled which
+ built with the <em>SHARED</em>_<em>CORE</em> rule enabled which
forces the Apache core code to be placed into a
dynamic shared object (DSO) file. This file is
searched in a hardcoded path under ServerRoot
per default. Use this option if you want to
override it.
- -<strong>d </strong><em>serverroot</em>
+ -<strong>d</strong> <em>serverroot</em>
Set the initial value for the ServerRoot direc-
tive to <em>serverroot</em>. This can be overridden by
the ServerRoot command in the configuration
file. The default is <strong>/usr/local/apache</strong>.
- -<strong>f </strong><em>config </em>Execute the commands in the file <em>config </em>on
- startup. If <em>config </em>does not begin with a /, then
+ -<strong>f</strong> <em>config</em> Execute the commands in the file <em>config</em> on
+ startup. If <em>config</em> does not begin with a /, then
it is taken to be a path relative to the Server-
Root. The default is <strong>conf/httpd.conf</strong>.
- -<strong>C </strong><em>directive</em>
- Process the configuration <em>directive </em>before read-
+ -<strong>C</strong> <em>directive</em>
+ Process the configuration <em>directive</em> before read-
ing config files.
- -<strong>c </strong><em>directive</em>
- Process the configuration <em>directive </em>after
+ -<strong>c</strong> <em>directive</em>
+ Process the configuration <em>directive</em> after
reading config files.
- -<strong>D </strong><em>parameter</em>
- Sets a configuration <em>parameter </em>which can be used
+ -<strong>D</strong> <em>parameter</em>
+ Sets a configuration <em>parameter</em> which can be used
with <IfDefine>...</IfDefine> sections in the
configuration files to conditionally skip or
process commands.
- -<strong>h </strong>Output a short summary of available command line
+ -<strong>h </strong> Output a short summary of available command line
options.
- -<strong>l </strong>Output a list of modules compiled into the
+ -<strong>l </strong> Output a list of modules compiled into the
server.
- -<strong>L </strong>Output a list of directives together with
+ -<strong>L </strong> Output a list of directives together with
expected arguments and places where the direc-
tive is valid.
- -<strong>S </strong>Show the settings as parsed from the config file
+ -<strong>S </strong> Show the settings as parsed from the config file
(currently only shows the virtualhost settings).
- -<strong>t </strong>Run syntax tests for configuration files only.
+ -<strong>t </strong> Run syntax tests for configuration files only.
The program immediately exits after these syntax
parsing with either a return code of 0 (Syntax
OK) or return code not equal to 0 (Syntax
- Error). If -<strong>D </strong><em>DUMP</em>_<em>VHOSTS </em>is also set, details
+ Error). If -<strong>D</strong> <em>DUMP</em>_<em>VHOSTS</em> is also set, details
of the virtual host configuration will be
printed.
- -<strong>T </strong>Same as option -<strong>t </strong>but does not check the config-
+ -<strong>T </strong> Same as option -<strong>t</strong> but does not check the config-
ured document roots.
- -<strong>v </strong>Print the version of <strong>httpd </strong>, and then exit.
+ -<strong>v </strong> Print the version of <strong>httpd</strong> , and then exit.
- -<strong>V </strong>Print the version and build parameters of <strong>httpd</strong>
+ -<strong>V </strong> Print the version and build parameters of <strong>httpd</strong>
, and then exit.
<strong>FILES</strong>
<strong>/usr/local/apache/logs/httpd.pid</strong>
</pre>
-<!--#include virtual="footer.html" -->
-</body></html>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
- <HEAD>
- <TITLE>Apache HTTP Server and Supporting Programs</TITLE>
- </HEAD>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
- <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
- <BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
- >
- <!--#include virtual="header.html" -->
- <H1 ALIGN="CENTER">Server and Supporting Programs</H1>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
-<p>This page documents all the executable programs included with the
-Apache HTTP Server.</p>
+ <title>Apache HTTP Server and Supporting Programs</title>
+ </head>
+ <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<dl>
+ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
+ vlink="#000080" alink="#FF0000">
+ <!--#include virtual="header.html" -->
-<dt><a href="httpd.html">httpd</a></dt>
-<dd>Apache hypertext transfer protocol server</dd>
+ <h1 align="CENTER">Server and Supporting Programs</h1>
-<dt><a href="apachectl.html">apachectl</a></dt>
-<dd>Apache HTTP server control interface</dd>
+ <p>This page documents all the executable programs included
+ with the Apache HTTP Server.</p>
-<dt><a href="ab.html">ab</a></dt>
-<dd>Apache HTTP server benchmarking tool</dd>
+ <dl>
+ <dt><a href="httpd.html">httpd</a></dt>
-<dt><a href="apxs.html">apxs</a></dt>
-<dd>APache eXtenSion tool</dd>
+ <dd>Apache hypertext transfer protocol server</dd>
-<dt><a href="dbmmanage.html">dbmmanage</a></dt>
-<dd>Create and update user authentication files in DBM format for basic
-authentication</dd>
+ <dt><a href="apachectl.html">apachectl</a></dt>
-<dt><a href="htdigest.html">htdigest</a></dt>
-<dd>Create and update user authentication files for digest authentication</dd>
+ <dd>Apache HTTP server control interface</dd>
-<dt><a href="htpasswd.html">htpasswd</a></dt>
-<dd>Create and update user authentication files for basic authentication</dd>
+ <dt><a href="ab.html">ab</a></dt>
-<dt><a href="logresolve.html">logresolve</a></dt>
-<dd>Resolve hostnames for IP-addresses in Apache logfiles</dd>
+ <dd>Apache HTTP server benchmarking tool</dd>
-<dt><a href="rotatelogs.html">rotatelogs</a></dt>
-<dd>Rotate Apache logs without having to kill the server</dd>
+ <dt><a href="apxs.html">apxs</a></dt>
-<dt><a href="suexec.html">suexec</a></dt>
-<dd>Switch User For Exec</dd>
+ <dd>APache eXtenSion tool</dd>
-<dt><a href="other.html">Other Programs</dt>
+ <dt><a href="dbmmanage.html">dbmmanage</a></dt>
-</dl>
+ <dd>Create and update user authentication files in DBM format
+ for basic authentication</dd>
+
+ <dt><a href="htdigest.html">htdigest</a></dt>
+
+ <dd>Create and update user authentication files for digest
+ authentication</dd>
+
+ <dt><a href="htpasswd.html">htpasswd</a></dt>
+
+ <dd>Create and update user authentication files for basic
+ authentication</dd>
+
+ <dt><a href="logresolve.html">logresolve</a></dt>
+
+ <dd>Resolve hostnames for IP-addresses in Apache
+ logfiles</dd>
+
+ <dt><a href="rotatelogs.html">rotatelogs</a></dt>
+
+ <dd>Rotate Apache logs without having to kill the server</dd>
+
+ <dt><a href="suexec.html">suexec</a></dt>
+
+ <dd>Switch User For Exec</dd>
+
+ <dt><a href="other.html">Other Programs</a></dt>
+ </dl>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
- <!--#include virtual="footer.html" -->
- </BODY>
-</HTML>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head><title>Manual Page: logresolve - Apache HTTP Server</title></head>
-<body bgcolor="#ffffff" text="#000000" link="#0000ff"
-vlink="#000080" alink="#ff0000">
-<!--#include virtual="header.html" -->
-<h1 align="center">Manual Page: logresolve</h1>
-<!-- This document was autogenerated from the man page -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Manual Page: logresolve - Apache HTTP Server</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#0000ff"
+ vlink="#000080" alink="#ff0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="center">Manual Page: logresolve</h1>
+ <!-- This document was autogenerated from the man page -->
<pre>
<strong>NAME</strong>
logresolve - resolve hostnames for IP-addresses in Apache
logfiles
<strong>SYNOPSIS</strong>
- <strong>logresolve </strong>[ -<strong>s </strong><em>filename </em>] [ -<strong>c </strong>] < <em>access</em>_<em>log </em>>
+ <strong>logresolve</strong> [ -<strong>s</strong> <em>filename</em> ] [ -<strong>c</strong> ] < <em>access</em>_<em>log</em> >
<em>access</em>_<em>log</em>.<em>new</em>
<strong>DESCRIPTION</strong>
- <strong>logresolve </strong>is a post-processing program to resolve IP-
+ <strong>logresolve</strong> is a post-processing program to resolve IP-
addresses in Apache's access logfiles. To minimize impact
on your nameserver, logresolve has its very own internal
hash-table cache. This means that each IP number will only
be looked up the first time it is found in the log file.
<strong>OPTIONS</strong>
- -<strong>s </strong><em>filename </em>Specifies a filename to record statistics.
+ -<strong>s</strong> <em>filename</em> Specifies a filename to record statistics.
- -<strong>c </strong>This causes <strong>logresolve </strong>to apply some DNS checks:
+ -<strong>c </strong> This causes <strong>logresolve</strong> to apply some DNS checks:
after finding the hostname from the IP address,
it looks up the IP addresses for the hostname
and checks that one of these matches the origi-
<strong>httpd(8)</strong>
</pre>
-<!--#include virtual="footer.html" -->
-</body></html>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
- <HEAD>
- <TITLE>Other Programs - Apache HTTP Server</TITLE>
- </HEAD>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
- <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
- <BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
- >
- <!--#include virtual="header.html" -->
- <H1 ALIGN="CENTER">Other Programs</H1>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
-<p>The following programs are simple support programs included with
-the Apache HTTP Server which do not have their own manual pages.</p>
+ <title>Other Programs - Apache HTTP 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" -->
-<h2><a name="log_server_status">log_server_status</a></h2>
+ <h1 align="CENTER">Other Programs</h1>
-<p>This Perl script is designed to be run at a frequent interval by something
-like cron. It connects to the server and downloads the status
-information. It reformats the information to a single line and logs
-it to a file. Adjust the variables at the top of the script
-to specify the location of the resulting logfile.</p>
+ <p>The following programs are simple support programs included
+ with the Apache HTTP Server which do not have their own manual
+ pages.</p>
-<h2><a name="split-logfile">split-logfile</a></h2>
+ <h2><a id="log_server_status"
+ name="log_server_status">log_server_status</a></h2>
-<p>This Perl script will take a combined Web server access
-log file and break its contents into separate files.
-It assumes that the first field of each line is the
-virtual host identity (put there by "%v"), and that
-the logfiles should be named that+".log" in the current
-directory.</p>
+ <p>This Perl script is designed to be run at a frequent
+ interval by something like cron. It connects to the server and
+ downloads the status information. It reformats the information
+ to a single line and logs it to a file. Adjust the variables at
+ the top of the script to specify the location of the resulting
+ logfile.</p>
-<p>The combined log file is read from stdin. Records read
-will be appended to any existing log files.</p>
+ <h2><a id="split-logfile"
+ name="split-logfile">split-logfile</a></h2>
+ <p>This Perl script will take a combined Web server access log
+ file and break its contents into separate files. It assumes
+ that the first field of each line is the virtual host identity
+ (put there by "%v"), and that the logfiles should be named
+ that+".log" in the current directory.</p>
+ <p>The combined log file is read from stdin. Records read will
+ be appended to any existing log files.</p>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-</dl>
-
- <!--#include virtual="footer.html" -->
- </BODY>
-</HTML>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head><title>Manual Page: rotatelogs - Apache HTTP Server</title></head>
-<body bgcolor="#ffffff" text="#000000" link="#0000ff"
-vlink="#000080" alink="#ff0000">
-<!--#include virtual="header.html" -->
-<h1 align="center">Manual Page: rotatelogs</h1>
-<!-- This document was autogenerated from the man page -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Manual Page: rotatelogs - Apache HTTP Server</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#0000ff"
+ vlink="#000080" alink="#ff0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="center">Manual Page: rotatelogs</h1>
+ <!-- This document was autogenerated from the man page -->
<pre>
<strong>NAME</strong>
rotatelogs - rotate Apache logs without having to kill the
server
<strong>SYNOPSIS</strong>
- <strong>rotatelogs </strong><em>logfile rotationtime</em>
+ <strong>rotatelogs</strong> <em>logfile rotationtime</em>
<strong>DESCRIPTION</strong>
- <strong>rotatelogs </strong>is a simple program for use in conjunction with
+ <strong>rotatelogs</strong> is a simple program for use in conjunction with
Apache's piped logfile feature which can be used like this:
TransferLog "|rotatelogs /path/to/logs/access_log 86400"
<strong>httpd(8)</strong>
</pre>
-<!--#include virtual="footer.html" -->
-</body></html>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head><title>Manual Page: suexec - Apache HTTP Server</title></head>
-<body bgcolor="#ffffff" text="#000000" link="#0000ff"
-vlink="#000080" alink="#ff0000">
-<!--#include virtual="header.html" -->
-<h1 align="center">Manual Page: suexec</h1>
-<!-- This document was autogenerated from the man page -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Manual Page: suexec - Apache HTTP Server</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#0000ff"
+ vlink="#000080" alink="#ff0000">
+ <!--#include virtual="header.html" -->
+
+ <h1 align="center">Manual Page: suexec</h1>
+ <!-- This document was autogenerated from the man page -->
<pre>
<strong>NAME</strong>
suexec - Switch User For Exec
nally by Apache only.
<strong>DESCRIPTION</strong>
- <strong>suexec </strong>is the "wrapper" support program for the suEXEC
+ <strong>suexec</strong> is the "wrapper" support program for the suEXEC
behaviour for Apache. It is run from within Apache automat-
ically to switch the user when an external program has to be
run under a different user. For more information about
<strong>httpd(8)</strong>
</pre>
-<!--#include virtual="footer.html" -->
-</body></html>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!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. The IP address can also
-be the wildcard <CODE>*</CODE>.
-
-<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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>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>
+
+ <p>If you just want to <cite>make it work</cite> without
+ understanding how, here are <a href="examples.html">some
+ examples</a>.</p>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <p>Unlike the main_server, vhost ports <em>do not</em> affect
+ what ports Apache listens for connections on.</p>
+
+ <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>
+
+ <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. The IP
+ address can also be the wildcard <code>*</code>.</p>
+
+ <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>
+
+ <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>
+
+ <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):</p>
+<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
+ # 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
+ # 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>
+ # server C | # server D
+ ... | ...
+ </VirtualHost> | </VirtualHost>
<VirtualHost 111.22.33.55> |
- # server D | NameVirtualHost 111.22.33.44
- ... | NameVirtualHost 111.22.33.55
- </VirtualHost> |
+ # 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 IP address is not found in the hash table then the match
-against the port number may also result in an entry corresponding to a
-<CODE>NameVirtualHost *</CODE>, which is subsequently handled like
-other name-based vhosts.
-
-<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.
- This also applies to <CODE>NameVirtualHost *</CODE> vhosts.
- <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>
+</pre>
+
+ <p>(To aid the readability of your configuration you should
+ prefer the left variant.)</p>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <p>For every vhost various default values are set. In
+ particular:</p>
+
+ <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>
+
+ <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>
+
+ <li>The per-server configs for each module from the
+ main_server are merged into the vhost server.</li>
+ </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>
+
+ <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>
+
+ <p>Any vhost that includes the magic <samp>_default_</samp>
+ wildcard is given the same <code>ServerName</code> as the
+ main_server.</p>
+
+ <h3>Virtual Host Matching</h3>
+
+ <p>The server determines which vhost to use for a request as
+ follows:</p>
+
+ <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>
+
+ <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>
+
+ <p>If the IP address is not found in the hash table then the
+ match against the port number may also result in an entry
+ corresponding to a <code>NameVirtualHost *</code>, which is
+ subsequently handled like other name-based vhosts.</p>
+
+ <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.</p>
+
+ <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.</p>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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).</p>
+
+ <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.</p>
+
+ <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.</li>
+
+ <li><code>ServerAlias</code> and <code>ServerPath</code>
+ checks are never performed for an IP-based vhost.</li>
+
+ <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.</li>
+
+ <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.</li>
+
+ <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.)</li>
+
+ <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.</li>
+
+ <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. This also applies to
+ <code>NameVirtualHost *</code> vhosts.</li>
+
+ <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).</li>
+
+ <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.</li>
+
+ <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.</li>
+
+ <li><code>ServerName</code> should always be set for each
+ vhost. Otherwise A DNS lookup is required for each
+ vhost.</li>
+ </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:</p>
+
+ <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.)</li>
+
+ <li>Group corresponding <code>NameVirtualHost</code> and
+ <code>VirtualHost</code> definitions in your configuration to
+ ensure better readability.</li>
+
+ <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").</li>
+ </ul>
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
+
-<!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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache Server 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>
+
+ <p>Although Apache attempts to increase the limit as required,
+ this may not work if:</p>
+
+ <ol>
+ <li>Your system does not provide the setrlimit() system
+ call.</li>
+
+ <li>The setrlimit(RLIMIT_NOFILE) call does not function on
+ your system (such as Solaris 2.3)</li>
+
+ <li>The number of file descriptors required exceeds the hard
+ limit.</li>
+
+ <li>Your system imposes other limits on file descriptors,
+ such as a limit on stdio streams only using file descriptors
+ below 256. (Solaris 2)</li>
+ </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>
+
+ <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>
+ </li>
+ </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>
-<!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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache Server 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>
+
+ <p>Although Apache attempts to increase the limit as required,
+ this may not work if:</p>
+
+ <ol>
+ <li>Your system does not provide the setrlimit() system
+ call.</li>
+
+ <li>The setrlimit(RLIMIT_NOFILE) call does not function on
+ your system (such as Solaris 2.3)</li>
+
+ <li>The number of file descriptors required exceeds the hard
+ limit.</li>
+
+ <li>Your system imposes other limits on file descriptors,
+ such as a limit on stdio streams only using file descriptors
+ below 256. (Solaris 2)</li>
+ </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>
+
+ <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>
+ </li>
+ </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>
-<HR>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<H3 ALIGN="CENTER">
- Apache HTTP Server Version 2.0
-</H3>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title></title>
+ </head>
+
+ <body>
+ <hr />
+
+ <h3 align="CENTER">Apache HTTP Server Version 2.0</h3>
+ <a href="./"><img src="../images/index.gif" alt="Index" /></a>
+ <a href="../"><img src="../images/home.gif" alt="Home" /></a>
+ </body>
+</html>
-<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A>
-<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A>
-<DIV ALIGN="CENTER">
- <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]">
- <H3>
- Apache HTTP Server Version 2.0
- </H3>
-</DIV>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title></title>
+ </head>
+
+ <body>
+ <div align="CENTER">
+ <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" />
+
+ <h3>Apache HTTP Server Version 2.0</h3>
+ </div>
+ </body>
+</html>
+
-<!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="name-based.html">Name-based Virtual Hosts</A>
-<LI><A HREF="ip-based.html">IP-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</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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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="name-based.html">Name-based Virtual
+ Hosts</a></li>
+
+ <li><a href="ip-based.html">IP-based Virtual Hosts</a></li>
+
+ <li><a href="examples.html">Virtual Host examples for common
+ setups</a></li>
+
+ <li><a href="details.html">In-Depth Discussion of Virtual
+ Host Matching</a></li>
+
+ <li><a href="fd-limits.html">File Descriptor Limits</a></li>
+
+ <li><a href="mass.html">Dynamically Configured Mass Virtual
+ Hosting</a></li>
+ </ul>
+
+ <h2>Configuration directives</h2>
+
+ <ul>
+ <li><a
+ href="../mod/core.html#virtualhost"><VirtualHost></a></li>
+
+ <li><a
+ href="../mod/core.html#namevirtualhost">NameVirtualHost</a></li>
+
+ <li><a href="../mod/core.html#servername">ServerName</a></li>
+
+ <li><a
+ href="../mod/core.html#serveralias">ServerAlias</a></li>
+
+ <li><a href="../mod/core.html#serverpath">ServerPath</a></li>
+ </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" -->
+ </p>
+ </body>
+</html>
+
-<!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="name-based.html">Name-based Virtual Hosts</A>
-<LI><A HREF="ip-based.html">IP-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</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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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="name-based.html">Name-based Virtual
+ Hosts</a></li>
+
+ <li><a href="ip-based.html">IP-based Virtual Hosts</a></li>
+
+ <li><a href="examples.html">Virtual Host examples for common
+ setups</a></li>
+
+ <li><a href="details.html">In-Depth Discussion of Virtual
+ Host Matching</a></li>
+
+ <li><a href="fd-limits.html">File Descriptor Limits</a></li>
+
+ <li><a href="mass.html">Dynamically Configured Mass Virtual
+ Hosting</a></li>
+ </ul>
+
+ <h2>Configuration directives</h2>
+
+ <ul>
+ <li><a
+ href="../mod/core.html#virtualhost"><VirtualHost></a></li>
+
+ <li><a
+ href="../mod/core.html#namevirtualhost">NameVirtualHost</a></li>
+
+ <li><a href="../mod/core.html#servername">ServerName</a></li>
+
+ <li><a
+ href="../mod/core.html#serveralias">ServerAlias</a></li>
+
+ <li><a href="../mod/core.html#serverpath">ServerPath</a></li>
+ </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" -->
+ </p>
+ </body>
+</html>
+
-<!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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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:</p>
+
+ <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>
+
+ <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.)</li>
+ </ul>
+ Use a single daemon when:
+
+ <ul>
+ <li>Sharing of the httpd configuration between virtual hosts
+ is acceptable.</li>
+
+ <li>The machine services a large number of requests, and so
+ the performance loss in running separate daemons may be
+ significant.</li>
+ </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>
+</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
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 directives that control
-process creation and a few other directives. To find out if a
-directive can be used in the VirtualHost directive, check the
-<A HREF="../mod/directive-dict.html#Context">Context</A> using the
-<A HREF="../mod/directives.html">directive index</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>
+</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
+ directives that control process creation and a few other
+ directives. To find out if a directive can be used in the
+ VirtualHost directive, check the <a
+ href="../mod/directive-dict.html#Context">Context</a> using the
+ <a href="../mod/directives.html">directive index</a>.</p>
+
+ <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>
+
+ <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>
-<!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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>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.
+
+ -->
+ </p>
+
+ <h2><a id="contents" name="contents">Contents:</a></h2>
+
+ <ul>
+ <li><a href="#motivation">Motivation</a></li>
+
+ <li><a href="#overview">Overview</a></li>
+
+ <li><a href="#simple">Simple dynamic virtual hosts</a></li>
+
+ <li><a href="#homepages">A virtually hosted homepages
+ system</a></li>
+
+ <li><a href="#combinations">Using more than one virtual
+ hosting system on the same server</a></li>
+
+ <li><a href="#ipbased">More efficient IP-based virtual
+ hosting</a></li>
+
+ <li><a href="#oldversion">Using older versions of
+ Apache</a></li>
+
+ <li><a href="#simple.rewrite">Simple dynamic virtual hosts
+ using <code>mod_rewrite</code></a></li>
+
+ <li><a href="#homepages.rewrite">A homepages system using
+ <code>mod_rewrite</code></a></li>
+
+ <li><a href="#xtra-conf">Using a separate virtual host
+ configuration file</a></li>
+ </ul>
+ <hr />
+
+ <h2><a id="motivation" 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:</p>
+<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
+ 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
+ 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
+ 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). In a normal
-configuration 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 (either
-<CODE>mod_vhost_alias</CODE> or <CODE>mod_rewrite</CODE>) which has
-a different way of doing the mapping. Neither of these modules is
-responsible for setting the <CODE>DOCUMENT_ROOT</CODE> environment
-variable so if any CGIs or SSI documents make use of it they will
-get a misleading value.</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>
+</pre>
+ <br />
+ <br />
+
+
+ <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:</p>
+
+ <ol>
+ <li>Your configuration file is smaller so Apache starts
+ faster and uses less memory.</li>
+
+ <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.</li>
+ </ol>
+ <br />
+ <br />
+
+
+ <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 id="overview" 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). In a normal
+ configuration 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 (either <code>mod_vhost_alias</code> or
+ <code>mod_rewrite</code>) which has a different way of doing
+ the mapping. Neither of these modules is responsible for
+ setting the <code>DOCUMENT_ROOT</code> environment variable so
+ if any CGIs or SSI documents make use of it they will get a
+ misleading value.</p>
+ <hr />
+
+ <h2><a id="simple" 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
# 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>
+</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 id="homepages" 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
# 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>
+</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 id="combinations" 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
+ Options FollowSymLinks
+ AllowOverride All
</Directory>
<Directory /www/homepages>
- Options FollowSymLinks
- AllowOverride None
+ Options FollowSymLinks
+ AllowOverride None
</Directory>
<VirtualHost 111.22.33.44>
- ServerName www.commercial.isp.com
+ ServerName www.commercial.isp.com
- CustomLog logs/access_log.commercial vcommon
+ CustomLog logs/access_log.commercial vcommon
- VirtualDocumentRoot /www/commercial/%0/docs
- VirtualScriptAlias /www/commercial/%0/cgi-bin
+ VirtualDocumentRoot /www/commercial/%0/docs
+ VirtualScriptAlias /www/commercial/%0/cgi-bin
</VirtualHost>
<VirtualHost 111.22.33.45>
- ServerName www.homepages.isp.com
+ ServerName www.homepages.isp.com
- CustomLog logs/access_log.homepages vcommon
+ CustomLog logs/access_log.homepages vcommon
- VirtualDocumentRoot /www/homepages/%0/docs
- ScriptAlias /cgi-bin/ /www/std-cgi/
+ 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>
+</pre>
+ <hr />
+
+ <h2><a id="ipbased" 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 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>
+</pre>
+ <hr />
+
+ <h2><a id="oldversion" 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 id="simple.rewrite" 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
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
+ # 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
RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi]
# that's it!
-</PRE>
-
+</pre>
+ <hr />
-<HR><H2><A NAME="homepages.rewrite">A homepages system
-using <CODE>mod_rewrite</CODE></A></H2>
+ <h2><a id="homepages.rewrite" 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>
+ <p>This does the same thing as <a href="#homepages">the second
+ example</a>.</p>
+<pre>
RewriteEngine on
RewriteMap lowercase int:tolower
# define the global CGI directory
ScriptAlias /cgi-bin/ /www/std-cgi/
-</PRE>
-
+</pre>
+ <hr />
-<HR><H2><A NAME="xtra-conf">Using a separate virtual host configuration file</A></H2>
+ <h2><a id="xtra-conf" 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>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>
+ <p>The <code>vhost.map</code> file contains something like
+ this:</p>
+<pre>
www.customer-1.com /www/customers/1
www.customer-2.com /www/customers/2
# ...
www.customer-N.com /www/customers/N
-</PRE>
-</P>
+</pre>
+ <br />
+ <br />
+
-<P>The <CODE>http.conf</CODE> contains this:
-<PRE>
+ <p>The <code>http.conf</code> contains this:</p>
+<pre>
RewriteEngine on
RewriteMap lowercase int:tolower
RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$
RewriteCond ${vhost:%1} ^(/.*)$
RewriteRule ^/(.*)$ %1/cgi-bin/$1
-</PRE>
-</P>
+</pre>
+ <br />
+ <br />
+ <!--#include virtual="footer.html" -->
+ </body>
+</html>
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
-<!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>Early versions of HTTP (like many other protocols, e.g. FTP)
-required a different IP address for each virtual host on the server.
-On some platforms this can limit the number of virtual hosts you can
-run, and because there are concerns about the availability of IP
-addresses it is strongly discouraged by the registraries (ARIN, RIPE,
-and APNIC).</P>
-
-<P>The <CODE>HTTP/1.1</CODE> protocol, and a common extension to
-<CODE>HTTP/1.0</CODE>, includes 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 old IP-address-per-hostname method.</P>
-
-<P>The benefits of using the name-based virtual hosts is a practically
-unlimited number of servers, ease of configuration and use, and it
-requires no additional hardware or software. The main disadvantage is
-that the client must support this part of the protocol. Almost all
-browsers do, but there are still tiny numbers of very old browsers in
-use which do not. This can cause problems, although a possible
-solution is addressed below.</P>
-
-<H2>Using name-based virtual hosts</H2>
-
-<P>Using name-based 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, or the wildcard <CODE>*</CODE> to
-indicate that the server only does name-based virtual hosting (no
-IP-based virtual hosting).</P>
-
-<P>For example, suppose that both <SAMP>www.domain.tld</SAMP> and
-<SAMP>www.otherdomain.tld</SAMP> point at the IP address of your
-server. 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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>Early versions of HTTP (like many other protocols, e.g. FTP)
+ required a different IP address for each virtual host on the
+ server. On some platforms this can limit the number of virtual
+ hosts you can run, and because there are concerns about the
+ availability of IP addresses it is strongly discouraged by the
+ registraries (ARIN, RIPE, and APNIC).</p>
+
+ <p>The <code>HTTP/1.1</code> protocol, and a common extension
+ to <code>HTTP/1.0</code>, includes 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 old
+ IP-address-per-hostname method.</p>
+
+ <p>The benefits of using the name-based virtual hosts is a
+ practically unlimited number of servers, ease of configuration
+ and use, and it requires no additional hardware or software.
+ The main disadvantage is that the client must support this part
+ of the protocol. Almost all browsers do, but there are still
+ tiny numbers of very old browsers in use which do not. This can
+ cause problems, although a possible solution is addressed
+ below.</p>
+
+ <h2>Using name-based virtual hosts</h2>
+
+ <p>Using name-based 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, or the wildcard
+ <code>*</code> to indicate that the server only does name-based
+ virtual hosting (no IP-based virtual hosting).</p>
+
+ <p>For example, suppose that both <samp>www.domain.tld</samp>
+ and <samp>www.otherdomain.tld</samp> point at the IP address of
+ your server. 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 *
<VirtualHost *>
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 right IP address.
-
-<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 specify a wildcard then the "main server" isn't used at all.
-If you start to use virtual hosts you should stop using 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>
+</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 right IP
+ address.</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 specify a wildcard then the "main server" isn't used at
+ all. If you start to use virtual hosts you should stop using
+ 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>
+
+ <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>
+</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:</p>
+<pre>
NameVirtualHost 111.22.33.44
<VirtualHost 111.22.33.44>
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>
+</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>
+
-<!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>Early versions of HTTP (like many other protocols, e.g. FTP)
-required a different IP address for each virtual host on the server.
-On some platforms this can limit the number of virtual hosts you can
-run, and because there are concerns about the availability of IP
-addresses it is strongly discouraged by the registraries (ARIN, RIPE,
-and APNIC).</P>
-
-<P>The <CODE>HTTP/1.1</CODE> protocol, and a common extension to
-<CODE>HTTP/1.0</CODE>, includes 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 old IP-address-per-hostname method.</P>
-
-<P>The benefits of using the name-based virtual hosts is a practically
-unlimited number of servers, ease of configuration and use, and it
-requires no additional hardware or software. The main disadvantage is
-that the client must support this part of the protocol. Almost all
-browsers do, but there are still tiny numbers of very old browsers in
-use which do not. This can cause problems, although a possible
-solution is addressed below.</P>
-
-<H2>Using name-based virtual hosts</H2>
-
-<P>Using name-based 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, or the wildcard <CODE>*</CODE> to
-indicate that the server only does name-based virtual hosting (no
-IP-based virtual hosting).</P>
-
-<P>For example, suppose that both <SAMP>www.domain.tld</SAMP> and
-<SAMP>www.otherdomain.tld</SAMP> point at the IP address of your
-server. 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>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta name="generator" content="HTML Tidy, see www.w3.org" />
+
+ <title>Apache 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>Early versions of HTTP (like many other protocols, e.g. FTP)
+ required a different IP address for each virtual host on the
+ server. On some platforms this can limit the number of virtual
+ hosts you can run, and because there are concerns about the
+ availability of IP addresses it is strongly discouraged by the
+ registraries (ARIN, RIPE, and APNIC).</p>
+
+ <p>The <code>HTTP/1.1</code> protocol, and a common extension
+ to <code>HTTP/1.0</code>, includes 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 old
+ IP-address-per-hostname method.</p>
+
+ <p>The benefits of using the name-based virtual hosts is a
+ practically unlimited number of servers, ease of configuration
+ and use, and it requires no additional hardware or software.
+ The main disadvantage is that the client must support this part
+ of the protocol. Almost all browsers do, but there are still
+ tiny numbers of very old browsers in use which do not. This can
+ cause problems, although a possible solution is addressed
+ below.</p>
+
+ <h2>Using name-based virtual hosts</h2>
+
+ <p>Using name-based 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, or the wildcard
+ <code>*</code> to indicate that the server only does name-based
+ virtual hosting (no IP-based virtual hosting).</p>
+
+ <p>For example, suppose that both <samp>www.domain.tld</samp>
+ and <samp>www.otherdomain.tld</samp> point at the IP address of
+ your server. 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 *
<VirtualHost *>
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 right IP address.
-
-<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 specify a wildcard then the "main server" isn't used at all.
-If you start to use virtual hosts you should stop using 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>
+</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 right IP
+ address.</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 specify a wildcard then the "main server" isn't used at
+ all. If you start to use virtual hosts you should stop using
+ 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>
+
+ <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>
+</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:</p>
+<pre>
NameVirtualHost 111.22.33.44
<VirtualHost 111.22.33.44>
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>
+</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>
+
projects / apache / commitdiff