<li><img alt="" src="../images/down.gif" /> <a href="#allowoverride">AllowOverride</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#allowoverridelist">AllowOverrideList</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cgimapextension">CGIMapExtension</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#cgipassauth">CGIPassAuth</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#contentdigest">ContentDigest</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#defaultruntimedir">DefaultRuntimeDir</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#defaulttype">DefaultType</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#virtualhost"><VirtualHost></a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AcceptFilter" id="AcceptFilter">AcceptFilter</a> <a name="acceptfilter" id="acceptfilter">Directive</a></h2>
<table class="directive">
cause all CGI script files with a <code>.foo</code> extension to
be passed to the FOO interpreter.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="CGIPassAuth" id="CGIPassAuth">CGIPassAuth</a> <a name="cgipassauth" id="cgipassauth">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables passing HTTP authorization headers to scripts as CGI
+variables</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CGIPassAuth On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CGIPassAuth Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.4.13 and later</td></tr>
+</table>
+ <p><code class="directive">CGIPassAuth</code> allows scripts access to HTTP
+ authorization headers such as <code>Authorization</code>, which is
+ required for scripts that implement HTTP Basic authentication.
+ Normally these HTTP headers are hidden from scripts, as it allows
+ scripts to see user ids and passwords used to access the server when
+ HTTP Basic authentication is enabled in the web server. This directive
+ should be used when scripts are allowed to implement HTTP Basic
+ authentication.</p>
+
+ <p>This directive can be used instead of the compile-time setting
+ <code>SECURITY_HOLE_PASS_AUTHORIZATION</code> which has been available
+ in previous versions of Apache HTTP Server.</p>
+
+ <p>The setting is respected by any modules which use
+ <code>ap_add_common_vars()</code>, such as <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>,
+ <code class="module"><a href="../mod/mod_cgid.html">mod_cgid</a></code>, <code class="module"><a href="../mod/mod_proxy_fcgi.html">mod_proxy_fcgi</a></code>,
+ <code class="module"><a href="../mod/mod_proxy_scgi.html">mod_proxy_scgi</a></code>, and so on. Notably, it affects
+ modules which don't handle the request in the usual sense but
+ still use this API; examples of this are <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
+ and <code class="module"><a href="../mod/mod_ext_filter.html">mod_ext_filter</a></code>. Third-party modules that don't
+ use <code>ap_add_common_vars()</code> may choose to respect the setting
+ as well.</p>
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ContentDigest" id="ContentDigest">ContentDigest</a> <a name="contentdigest" id="contentdigest">Directive</a></h2>
different sections are combined when a request is received</li>
</ul>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../de/mod/core.html" hreflang="de" rel="alternate" title="Deutsch"> de </a> |
<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.de.xsl"?>
-<!-- English Revision: 344972:1673805 (outdated) -->
+<!-- English Revision: 344972:1673860 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<!-- English Revision: 1040494:1673805 (outdated) -->
+<!-- English Revision: 1040494:1673860 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision: 1670326:1673805 (outdated) -->
+<!-- English Revision: 1670326:1673860 (outdated) -->
<!-- French translation : Lucien GENTIS -->
<!-- Reviewed by : Vincent Deffontaines -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
-<!-- English Revision: 669847:1673805 (outdated) -->
+<!-- English Revision: 669847:1673860 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.tr.xsl"?>
-<!-- English Revision: 1647230:1673805 (outdated) -->
+<!-- English Revision: 1647230:1673860 (outdated) -->
<!-- =====================================================
Translated by: Nilgün Belma Bugüner <nilgun belgeler.gen.tr>
Reviewed by: Orhan Berent <berent belgeler.gen.tr>
<li><a href="mod_cache.html#cachestoreprivate">CacheStorePrivate</a></li>
<li><a href="mod_cgid.html#cgidscripttimeout">CGIDScriptTimeout</a></li>
<li><a href="core.html#cgimapextension">CGIMapExtension</a></li>
+<li><a href="core.html#cgipassauth">CGIPassAuth</a></li>
<li><a href="mod_charset_lite.html#charsetdefault">CharsetDefault</a></li>
<li><a href="mod_charset_lite.html#charsetoptions">CharsetOptions</a></li>
<li><a href="mod_charset_lite.html#charsetsourceenc">CharsetSourceEnc</a></li>
script's arguments when building the <code class="program"><a href="../programs/httpd.html">httpd</a></code>.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#how-it-works">How it Works</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#requirements">Requirements</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#asyncrequestworkerfactor">AsyncRequestWorkerFactor</a></li>
<li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li>
<li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#threadstacksize">ThreadStackSize</a></li>
<li><img alt="" src="../images/right.gif" /> <a href="mod_unixd.html#user">User</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#how-it-works">How it Works</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#requirements">Requirements</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><a href="worker.html">The worker MPM</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AsyncRequestWorkerFactor" id="AsyncRequestWorkerFactor">AsyncRequestWorkerFactor</a> <a name="asyncrequestworkerfactor" id="asyncrequestworkerfactor">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limit concurrent connections per process</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AsyncRequestWorkerFactor <var>factor</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>2</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>MPM</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>event</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.13 and later</td></tr>
-</table>
- <p>The event MPM handles some connections in an asynchronous way, where
- request worker threads are only allocated for short periods of time as
- needed, and other connections with one request worker thread reserved per
- connection. This can lead to situations where all workers are tied up and
- no worker thread is available to handle new work on established async
- connections.</p>
-
- <p>To mitigate this problem, the event MPM does two things: Firstly, it
- limits the number of connections accepted per process, depending on the
- number of idle request workers. Secondly, if all workers are busy, it will
- close connections in keep-alive state even if the keep-alive timeout has
- not expired. This allows the respective clients to reconnect to a
- different process which may still have worker threads available.</p>
-
- <p>This directive can be used to fine-tune the per-process connection
- limit. A process will only accept new connections if the current number of
- connections (not counting connections in the "closing" state) is lower
- than:</p>
-
- <p class="indent"><strong>
- <code class="directive"><a href="../mod/mpm_common.html#threadsperchild">ThreadsPerChild</a></code> +
- (<code class="directive">AsyncRequestWorkerFactor</code> *
- <var>number of idle workers</var>)
- </strong></p>
-
- <p>This means the absolute maximum numbers of concurrent connections is:</p>
-
- <p class="indent"><strong>
- (<code class="directive">AsyncRequestWorkerFactor</code> + 1) *
- <code class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code>
- </strong></p>
-
- <p><code class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code> was called
- <code class="directive">MaxClients</code> prior to version 2.3.13. The above value
- shows that the old name did not accurately describe its meaning for the event MPM.</p>
-
- <p><code class="directive">AsyncRequestWorkerFactor</code> can take non-integer
- arguments, e.g "1.5".</p>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="how-it-works" id="how-it-works">How it Works</a></h2>
<p>This MPM tries to fix the 'keep alive problem' in HTTP. After a client
with support for EPoll.</li>
</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AsyncRequestWorkerFactor" id="AsyncRequestWorkerFactor">AsyncRequestWorkerFactor</a> <a name="asyncrequestworkerfactor" id="asyncrequestworkerfactor">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limit concurrent connections per process</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AsyncRequestWorkerFactor <var>factor</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>2</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>MPM</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>event</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.13 and later</td></tr>
+</table>
+ <p>The event MPM handles some connections in an asynchronous way, where
+ request worker threads are only allocated for short periods of time as
+ needed, and other connections with one request worker thread reserved per
+ connection. This can lead to situations where all workers are tied up and
+ no worker thread is available to handle new work on established async
+ connections.</p>
+
+ <p>To mitigate this problem, the event MPM does two things: Firstly, it
+ limits the number of connections accepted per process, depending on the
+ number of idle request workers. Secondly, if all workers are busy, it will
+ close connections in keep-alive state even if the keep-alive timeout has
+ not expired. This allows the respective clients to reconnect to a
+ different process which may still have worker threads available.</p>
+
+ <p>This directive can be used to fine-tune the per-process connection
+ limit. A process will only accept new connections if the current number of
+ connections (not counting connections in the "closing" state) is lower
+ than:</p>
+
+ <p class="indent"><strong>
+ <code class="directive"><a href="../mod/mpm_common.html#threadsperchild">ThreadsPerChild</a></code> +
+ (<code class="directive">AsyncRequestWorkerFactor</code> *
+ <var>number of idle workers</var>)
+ </strong></p>
+
+ <p>This means the absolute maximum numbers of concurrent connections is:</p>
+
+ <p class="indent"><strong>
+ (<code class="directive">AsyncRequestWorkerFactor</code> + 1) *
+ <code class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code>
+ </strong></p>
+
+ <p><code class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code> was called
+ <code class="directive">MaxClients</code> prior to version 2.3.13. The above value
+ shows that the old name did not accurately describe its meaning for the event MPM.</p>
+
+ <p><code class="directive">AsyncRequestWorkerFactor</code> can take non-integer
+ arguments, e.g "1.5".</p>
+
+
</div>
</div>
<div class="bottomlang">
<li><code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code></li>
<li><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="Allow" id="Allow">Allow</a> <a name="allow" id="allow">Directive</a></h2>
<table class="directive">
<li><code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code></li>
</ul>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_access_compat.html" title="English"> en </a> |
<li><a href="../howto/cgi.html">Dynamic Content with CGI</a></li>
<li><a href="../handler.html">Apache httpd's Handler Use</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="Action" id="Action">Action</a> <a name="action" id="action">Directive</a></h2>
<table class="directive">
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../de/mod/mod_actions.html" hreflang="de" rel="alternate" title="Deutsch"> de </a> |
<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#order">Order of Processing</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#alias">Alias</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#aliasmatch">AliasMatch</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#scriptalias">ScriptAlias</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#scriptaliasmatch">ScriptAliasMatch</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#order">Order of Processing</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code></li>
<li><a href="../urlmapping.html">Mapping URLs to the filesystem</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="order" id="order">Order of Processing</a></h2>
+
+ <p>Aliases and Redirects occurring in different contexts are processed
+ like other directives according to standard <a href="../sections.html#mergin">merging rules</a>. But when multiple
+ Aliases or Redirects occur in the same context (for example, in the
+ same <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code>
+ section) they are processed in a particular order.</p>
+
+ <p>First, all Redirects are processed before Aliases are processed,
+ and therefore a request that matches a <code class="directive"><a href="#redirect">Redirect</a></code> or <code class="directive"><a href="#redirectmatch">RedirectMatch</a></code> will never have Aliases
+ applied. Second, the Aliases and Redirects are processed in the order
+ they appear in the configuration files, with the first match taking
+ precedence.</p>
+
+ <p>For this reason, when two or more of these directives apply to the
+ same sub-path, you must list the most specific path first in order for
+ all the directives to have an effect. For example, the following
+ configuration will work as expected:</p>
+
+ <pre class="prettyprint lang-config">Alias "/foo/bar" "/baz"
+Alias "/foo" "/gaq"</pre>
+
+
+ <p>But if the above two directives were reversed in order, the
+ <code>/foo</code> <code class="directive"><a href="#alias">Alias</a></code>
+ would always match before the <code>/foo/bar</code> <code class="directive"><a href="#alias">Alias</a></code>, so the latter directive would be
+ ignored.</p>
+
+ <p>When the <code class="directive"><a href="#alias">Alias</a></code>,
+ <code class="directive"><a href="#scriptalias">ScriptAlias</a></code> and
+ <code class="directive"><a href="#redirect">Redirect</a></code> directives are used
+ within a <code class="directive"><a href="../mod/core.html#location"><Location></a></code>
+ or <code class="directive"><a href="../mod/core.html#locationmatch"><LocationMatch></a></code>
+ section, these directives will take precedence over any globally
+ defined <code class="directive"><a href="#alias">Alias</a></code>,
+ <code class="directive"><a href="#scriptalias">ScriptAlias</a></code> and
+ <code class="directive"><a href="#redirect">Redirect</a></code> directives.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="Alias" id="Alias">Alias</a> <a name="alias" id="alias">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maps URLs to filesystem locations</td></tr>
details.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="order" id="order">Order of Processing</a></h2>
-
- <p>Aliases and Redirects occurring in different contexts are processed
- like other directives according to standard <a href="../sections.html#mergin">merging rules</a>. But when multiple
- Aliases or Redirects occur in the same context (for example, in the
- same <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code>
- section) they are processed in a particular order.</p>
-
- <p>First, all Redirects are processed before Aliases are processed,
- and therefore a request that matches a <code class="directive"><a href="#redirect">Redirect</a></code> or <code class="directive"><a href="#redirectmatch">RedirectMatch</a></code> will never have Aliases
- applied. Second, the Aliases and Redirects are processed in the order
- they appear in the configuration files, with the first match taking
- precedence.</p>
-
- <p>For this reason, when two or more of these directives apply to the
- same sub-path, you must list the most specific path first in order for
- all the directives to have an effect. For example, the following
- configuration will work as expected:</p>
-
- <pre class="prettyprint lang-config">Alias "/foo/bar" "/baz"
-Alias "/foo" "/gaq"</pre>
-
-
- <p>But if the above two directives were reversed in order, the
- <code>/foo</code> <code class="directive"><a href="#alias">Alias</a></code>
- would always match before the <code>/foo/bar</code> <code class="directive"><a href="#alias">Alias</a></code>, so the latter directive would be
- ignored.</p>
-
- <p>When the <code class="directive"><a href="#alias">Alias</a></code>,
- <code class="directive"><a href="#scriptalias">ScriptAlias</a></code> and
- <code class="directive"><a href="#redirect">Redirect</a></code> directives are used
- within a <code class="directive"><a href="../mod/core.html#location"><Location></a></code>
- or <code class="directive"><a href="../mod/core.html#locationmatch"><LocationMatch></a></code>
- section, these directives will take precedence over any globally
- defined <code class="directive"><a href="#alias">Alias</a></code>,
- <code class="directive"><a href="#scriptalias">ScriptAlias</a></code> and
- <code class="directive"><a href="#redirect">Redirect</a></code> directives.</p>
-
</div>
</div>
<div class="bottomlang">
<li><img alt="" src="../images/down.gif" /> <a href="#allowmethods">AllowMethods</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AllowMethods" id="AllowMethods">AllowMethods</a> <a name="allowmethods" id="allowmethods">Directive</a></h2>
<table class="directive">
<code class="directive"><a href="../mod/core.html#limitexcept">LimitExcept</a></code>.</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_allowmethods.html" title="English"> en </a> |
<p>For historical reasons, this module will also process any
file with the mime type <code>httpd/send-as-is</code>.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code></li>
<li><code class="module"><a href="../mod/mod_cern_meta.html">mod_cern_meta</a></code></li>
<li><code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code></li>
<li><a href="../howto/auth.html">Authentication howto</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthBasicAuthoritative" id="AuthBasicAuthoritative">AuthBasicAuthoritative</a> <a name="authbasicauthoritative" id="authbasicauthoritative">Directive</a></h2>
<table class="directive">
</div>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_auth_basic.html" title="English"> en </a> |
whole connection using <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is a much better
alternative.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#using">Using Digest Authentication</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#authdigestalgorithm">AuthDigestAlgorithm</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authdigestdomain">AuthDigestDomain</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authdigestqop">AuthDigestQop</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authdigestshmemsize">AuthDigestShmemSize</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#using">Using Digest Authentication</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/mod_authn_core.html#authname">AuthName</a></code></li>
<li><code class="directive"><a href="../mod/mod_authn_core.html#authtype">AuthType</a></code></li>
<li><a href="../howto/auth.html">Authentication howto</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="using" id="using">Using Digest Authentication</a></h2>
+
+ <p>To use MD5 Digest authentication, simply
+ change the normal <code>AuthType Basic</code> and
+ <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code>
+ to <code>AuthType Digest</code> and
+ <code class="directive"><a href="#authdigestprovider">AuthDigestProvider</a></code>,
+ when setting up authentication, then add a
+ <code class="directive"><a href="#authdigestdomain">AuthDigestDomain</a></code> directive containing at least the root
+ URI(s) for this protection space.</p>
+
+ <p>Appropriate user (text) files can be created using the
+ <code class="program"><a href="../programs/htdigest.html">htdigest</a></code> tool.</p>
+
+ <div class="example"><h3>Example:</h3><pre class="prettyprint lang-config"><Location "/private/">
+ AuthType Digest
+ AuthName "private area"
+ AuthDigestDomain "/private/" "http://mirror.my.dom/private2/"
+
+ AuthDigestProvider file
+ AuthUserFile "/web/auth/.digest_pw"
+ Require valid-user
+</Location></pre>
+</div>
+
+ <div class="note"><h3>Note</h3>
+ <p>Digest authentication was intended to be more secure than basic
+ authentication, but no longer fulfills that design goal. A
+ man-in-the-middle attacker can trivially force the browser to downgrade
+ to basic authentication. And even a passive eavesdropper can brute-force
+ the password using today's graphics hardware, because the hashing
+ algorithm used by digest authentication is too fast. Another problem is
+ that the storage of the passwords on the server is insecure. The contents
+ of a stolen htdigest file can be used directly for digest authentication.
+ Therefore using <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> to encrypt the whole connection is
+ strongly recommended.</p>
+ <p><code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code> only works properly on platforms
+ where APR supports shared memory.</p>
+ </div>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthDigestAlgorithm" id="AuthDigestAlgorithm">AuthDigestAlgorithm</a> <a name="authdigestalgorithm" id="authdigestalgorithm">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Selects the algorithm used to calculate the challenge and
AuthDigestShmemSize 1M</pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="using" id="using">Using Digest Authentication</a></h2>
-
- <p>To use MD5 Digest authentication, simply
- change the normal <code>AuthType Basic</code> and
- <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code>
- to <code>AuthType Digest</code> and
- <code class="directive"><a href="#authdigestprovider">AuthDigestProvider</a></code>,
- when setting up authentication, then add a
- <code class="directive"><a href="#authdigestdomain">AuthDigestDomain</a></code> directive containing at least the root
- URI(s) for this protection space.</p>
-
- <p>Appropriate user (text) files can be created using the
- <code class="program"><a href="../programs/htdigest.html">htdigest</a></code> tool.</p>
-
- <div class="example"><h3>Example:</h3><pre class="prettyprint lang-config"><Location "/private/">
- AuthType Digest
- AuthName "private area"
- AuthDigestDomain "/private/" "http://mirror.my.dom/private2/"
-
- AuthDigestProvider file
- AuthUserFile "/web/auth/.digest_pw"
- Require valid-user
-</Location></pre>
-</div>
-
- <div class="note"><h3>Note</h3>
- <p>Digest authentication was intended to be more secure than basic
- authentication, but no longer fulfills that design goal. A
- man-in-the-middle attacker can trivially force the browser to downgrade
- to basic authentication. And even a passive eavesdropper can brute-force
- the password using today's graphics hardware, because the hashing
- algorithm used by digest authentication is too fast. Another problem is
- that the storage of the passwords on the server is insecure. The contents
- of a stolen htdigest file can be used directly for digest authentication.
- Therefore using <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> to encrypt the whole connection is
- strongly recommended.</p>
- <p><code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code> only works properly on platforms
- where APR supports shared memory.</p>
- </div>
</div>
</div>
<div class="bottomlang">
</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#basicconfig">Basic Configuration</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#standalone">Standalone Login</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#inline">Inline Login</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#inlinepreservebody">Inline Login with Body Preservation</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#loggingout">Logging Out</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#urlencoding">Usernames and Passwords</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#authformauthoritative">AuthFormAuthoritative</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authformbody">AuthFormBody</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authformsize">AuthFormSize</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authformusername">AuthFormUsername</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#basicconfig">Basic Configuration</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#standalone">Standalone Login</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#inline">Inline Login</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#inlinepreservebody">Inline Login with Body Preservation</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#loggingout">Logging Out</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#urlencoding">Usernames and Passwords</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_session.html">mod_session</a></code></li>
<li><code class="directive"><a href="../mod/mod_authn_core.html#authname">AuthName</a></code></li>
<li><a href="../howto/auth.html">Authentication howto</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="basicconfig" id="basicconfig">Basic Configuration</a></h2>
+
+ <p>To protect a particular URL with <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>, you need to
+ decide where you will store your <var>session</var>, and you will need to
+ decide what method you will use to authenticate. In this simple example, the
+ login details will be stored in a session based on
+ <code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code>, and authentication will be attempted against
+ a file using <code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code>. If authentication is unsuccessful,
+ the user will be redirected to the form login page.</p>
+
+ <div class="example"><h3>Basic example</h3><pre class="prettyprint lang-config">AuthFormProvider file
+AuthUserFile "conf/passwd"
+AuthType form
+AuthName realm
+AuthFormLoginRequiredLocation "http://example.com/login.html"
+Session On
+SessionCookieName session path=/
+SessionCryptoPassphrase secret</pre>
+</div>
+
+ <p>The directive <code class="directive"><a href="../mod/mod_authn_core.html#authtype">AuthType</a></code> will enable
+ the <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> authentication when set to the value <var>form</var>.
+ The directives <code class="directive"><a href="#authformprovider">AuthFormProvider</a></code> and
+ <code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code> specify that usernames
+ and passwords should be checked against the chosen file.</p>
+
+ <p>The directives <code class="directive"><a href="../mod/mod_session.html#session">Session</a></code>,
+ <code class="directive"><a href="../mod/mod_session_cookie.html#sessioncookiename">SessionCookieName</a></code> and
+ <code class="directive"><a href="../mod/mod_session_crypto.html#sessioncryptopassphrase">SessionCryptoPassphrase</a></code> create an
+ encrypted session stored within an HTTP cookie on the browser. For more information
+ on the different options for configuring a session, read the documentation for
+ <code class="module"><a href="../mod/mod_session.html">mod_session</a></code>.</p>
+
+ <p>In the simple example above, a URL has been protected by
+ <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>, but the user has yet to be given an opportunity to
+ enter their username and password. Options for doing so include providing a
+ dedicated standalone login page for this purpose, or for providing the login
+ page inline.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="standalone" id="standalone">Standalone Login</a></h2>
+
+ <p>The login form can be hosted as a standalone page, or can be provided inline on
+ the same page.</p>
+
+ <p>When configuring the login as a standalone page, unsuccessful authentication
+ attempts should be redirected to a login form created by the website for this purpose,
+ using the <code class="directive"><a href="#authformloginrequiredlocation">AuthFormLoginRequiredLocation</a></code>
+ directive. Typically this login page will contain an HTML form, asking the user to
+ provide their usename and password.</p>
+
+ <div class="example"><h3>Example login form</h3><pre class="prettyprint lang-html"><form method="POST" action="/dologin.html">
+ Username: <input type="text" name="httpd_username" value="" />
+ Password: <input type="password" name="httpd_password" value="" />
+ <input type="submit" name="login" value="Login" />
+</form></pre>
+</div>
+
+ <p>The part that does the actual login is handled by the <var>form-login-handler</var>.
+ The action of the form should point at this handler, which is configured within
+ Apache httpd as follows:</p>
+
+ <div class="example"><h3>Form login handler example</h3><pre class="prettyprint lang-config"><Location "/dologin.html">
+ SetHandler form-login-handler
+ AuthFormLoginRequiredLocation "http://example.com/login.html"
+ AuthFormLoginSuccessLocation "http://example.com/success.html"
+ AuthFormProvider file
+ AuthUserFile "conf/passwd"
+ AuthType form
+ AuthName realm
+ Session On
+ SessionCookieName session path=/
+ SessionCryptoPassphrase secret
+</Location></pre>
+</div>
+
+ <p>The URLs specified by the
+ <code class="directive"><a href="#authformloginrequiredlocation">AuthFormLoginRequiredLocation</a></code> directive will typically
+ point to a page explaining to the user that their login attempt was unsuccessful, and they
+ should try again. The <code class="directive"><a href="#authformloginsuccesslocation">AuthFormLoginSuccessLocation</a></code>
+ directive specifies the URL the user should be redirected to upon successful login.</p>
+
+ <p>Alternatively, the URL to redirect the user to on success can be embedded within the login
+ form, as in the example below. As a result, the same <var>form-login-handler</var> can be
+ reused for different areas of a website.</p>
+
+ <div class="example"><h3>Example login form with location</h3><pre class="prettyprint lang-html"><form method="POST" action="/dologin.html">
+ Username: <input type="text" name="httpd_username" value="" />
+ Password: <input type="password" name="httpd_password" value="" />
+ <input type="submit" name="login" value="Login" />
+ <input type="hidden" name="httpd_location" value="http://example.com/success.html" />
+</form></pre>
+</div>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="inline" id="inline">Inline Login</a></h2>
+
+ <div class="warning"><h3>Warning</h3>
+ <p>A risk exists that under certain circumstances, the login form configured
+ using inline login may be submitted more than once, revealing login credentials to
+ the application running underneath. The administrator must ensure that the underlying
+ application is properly secured to prevent abuse. If in doubt, use the
+ standalone login configuration.</p>
+ </div>
+
+ <p>As an alternative to having a dedicated login page for a website, it is possible to
+ configure <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> to authenticate users inline, without being
+ redirected to another page. This allows the state of the current page to be preserved
+ during the login attempt. This can be useful in a situation where a time limited
+ session is in force, and the session times out in the middle of the user request. The
+ user can be re-authenticated in place, and they can continue where they left off.</p>
+
+ <p>If a non-authenticated user attempts to access a page protected by
+ <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> that isn't configured with a
+ <code class="directive"><a href="#authformloginrequiredlocation">AuthFormLoginRequiredLocation</a></code> directive,
+ a <var>HTTP_UNAUTHORIZED</var> status code is returned to the browser indicating to the user
+ that they are not authorized to view the page.</p>
+
+ <p>To configure inline authentication, the administrator overrides the error document
+ returned by the <var>HTTP_UNAUTHORIZED</var> status code with a custom error document
+ containing the login form, as follows:</p>
+
+ <div class="example"><h3>Basic inline example</h3><pre class="prettyprint lang-config">AuthFormProvider file
+ErrorDocument 401 "/login.shtml"
+AuthUserFile "conf/passwd"
+AuthType form
+AuthName realm
+AuthFormLoginRequiredLocation "http://example.com/login.html"
+Session On
+SessionCookieName session path=/
+SessionCryptoPassphrase secret</pre>
+</div>
+
+ <p>The error document page should contain a login form with an empty action property,
+ as per the example below. This has the effect of submitting the form to
+ the original protected URL, without the page having to know what that
+ URL is.</p>
+
+ <div class="example"><h3>Example inline login form</h3><pre class="prettyprint lang-html"><form method="POST" <strong>action=""</strong>>
+ Username: <input type="text" name="httpd_username" value="" />
+ Password: <input type="password" name="httpd_password" value="" />
+ <input type="submit" name="login" value="Login" />
+</form></pre>
+</div>
+
+ <p>When the end user has filled in their login details, the form will make
+ an HTTP POST request to the original password protected URL.
+ <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> will intercept this POST request, and if
+ HTML fields are found present for the username and password, the user
+ will be logged in, and the original password protected URL will be returned
+ to the user as a GET request.</p>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="inlinepreservebody" id="inlinepreservebody">Inline Login with Body Preservation</a></h2>
+
+ <p>A limitation of the inline login technique described above is that should an
+ HTML form POST have resulted in the request to authenticate or
+ reauthenticate, the
+ contents of the original form posted by the browser will be lost. Depending on
+ the function of the website, this could present significant inconvenience for the
+ end user.</p>
+
+ <p><code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> addresses this by allowing the method and body
+ of the original request to be embedded in the login form. If authentication
+ is successful, the original method and body will be retried by Apache httpd, preserving
+ the state of the original request.</p>
+
+ <p>To enable body preservation, add three additional fields to the login form as
+ per the example below.</p>
+
+ <div class="example"><h3>Example with body preservation</h3><pre class="prettyprint lang-html"><form method="POST" action="">
+ Username: <input type="text" name="httpd_username" value="" />
+ Password: <input type="password" name="httpd_password" value="" />
+ <input type="submit" name="login" value="Login" />
+ <br /> <strong><input type="hidden" name="httpd_method" value="POST" />
+ <input type="hidden" name="httpd_mimetype" value="application/x-www-form-urlencoded" />
+ <input type="hidden" name="httpd_body" value="name1=value1&name2=value2" /></strong><br />
+</form></pre>
+</div>
+
+ <p>How the method, mimetype and body of the original request are embedded within the
+ login form will depend on the platform and technology being used within the website.
+ </p>
+
+ <p>One option is to use the <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> module along with the
+ <code class="directive"><a href="../mod/mod_request.html#keptbodysize">KeptBodySize</a></code> directive, along with a suitable
+ CGI script to embed the variables in the form.</p>
+
+ <p>Another option is to render the login form using a CGI script or other dynamic
+ technology.</p>
+
+ <div class="example"><h3>CGI example</h3><pre class="prettyprint lang-config"> AuthFormProvider file
+ ErrorDocument 401 "/cgi-bin/login.cgi"
+ ...</pre>
+</div>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="loggingout" id="loggingout">Logging Out</a></h2>
+
+ <p>To enable a user to log out of a particular session, configure a page to
+ be handled by the <var>form-logout-handler</var>. Any attempt to access this
+ URL will cause the username and password to be removed from the current
+ session, effectively logging the user out.</p>
+
+ <p>By setting the
+ <code class="directive"><a href="#authformlogoutlocation">AuthFormLogoutLocation</a></code> directive,
+ a URL can be specified that the browser will be redirected to on successful
+ logout. This URL might explain to the user that they have been logged out, and
+ give the user the option to log in again.</p>
+
+ <div class="example"><h3>Basic logout example</h3><pre class="prettyprint lang-config">SetHandler form-logout-handler
+AuthName realm
+AuthFormLogoutLocation "http://example.com/loggedout.html"
+Session On
+SessionCookieName session path=/
+SessionCryptoPassphrase secret</pre>
+</div>
+
+ <p>Note that logging a user out does not delete the session; it merely removes
+ the username and password from the session. If this results in an empty session,
+ the net effect will be the removal of that session, but this is not
+ guaranteed. If you want to guarantee the removal of a session, set the
+ <code class="directive"><a href="../mod/mod_session.html#sessionmaxage">SessionMaxAge</a></code> directive to a small
+ value, like 1 (setting the directive to zero would mean no session age limit).
+ </p>
+
+ <div class="example"><h3>Basic session expiry example</h3><pre class="prettyprint lang-config">SetHandler form-logout-handler
+AuthFormLogoutLocation "http://example.com/loggedout.html"
+Session On
+SessionMaxAge 1
+SessionCookieName session path=/
+SessionCryptoPassphrase secret</pre>
+</div>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="urlencoding" id="urlencoding">Usernames and Passwords</a></h2>
+ <p>Note that form submission involves URLEncoding the form data:
+ in this case the username and password. You should therefore
+ pick usernames and passwords that avoid characters that are
+ URLencoded in form submission, or you may get unexpected results.</p>
+ </div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthFormAuthoritative" id="AuthFormAuthoritative">AuthFormAuthoritative</a> <a name="authformauthoritative" id="authformauthoritative">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets whether authorization and authentication are passed to
in.</p>
</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="basicconfig" id="basicconfig">Basic Configuration</a></h2>
-
- <p>To protect a particular URL with <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>, you need to
- decide where you will store your <var>session</var>, and you will need to
- decide what method you will use to authenticate. In this simple example, the
- login details will be stored in a session based on
- <code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code>, and authentication will be attempted against
- a file using <code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code>. If authentication is unsuccessful,
- the user will be redirected to the form login page.</p>
-
- <div class="example"><h3>Basic example</h3><pre class="prettyprint lang-config">AuthFormProvider file
-AuthUserFile "conf/passwd"
-AuthType form
-AuthName realm
-AuthFormLoginRequiredLocation "http://example.com/login.html"
-Session On
-SessionCookieName session path=/
-SessionCryptoPassphrase secret</pre>
-</div>
-
- <p>The directive <code class="directive"><a href="../mod/mod_authn_core.html#authtype">AuthType</a></code> will enable
- the <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> authentication when set to the value <var>form</var>.
- The directives <code class="directive"><a href="#authformprovider">AuthFormProvider</a></code> and
- <code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code> specify that usernames
- and passwords should be checked against the chosen file.</p>
-
- <p>The directives <code class="directive"><a href="../mod/mod_session.html#session">Session</a></code>,
- <code class="directive"><a href="../mod/mod_session_cookie.html#sessioncookiename">SessionCookieName</a></code> and
- <code class="directive"><a href="../mod/mod_session_crypto.html#sessioncryptopassphrase">SessionCryptoPassphrase</a></code> create an
- encrypted session stored within an HTTP cookie on the browser. For more information
- on the different options for configuring a session, read the documentation for
- <code class="module"><a href="../mod/mod_session.html">mod_session</a></code>.</p>
-
- <p>In the simple example above, a URL has been protected by
- <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>, but the user has yet to be given an opportunity to
- enter their username and password. Options for doing so include providing a
- dedicated standalone login page for this purpose, or for providing the login
- page inline.</p>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="standalone" id="standalone">Standalone Login</a></h2>
-
- <p>The login form can be hosted as a standalone page, or can be provided inline on
- the same page.</p>
-
- <p>When configuring the login as a standalone page, unsuccessful authentication
- attempts should be redirected to a login form created by the website for this purpose,
- using the <code class="directive"><a href="#authformloginrequiredlocation">AuthFormLoginRequiredLocation</a></code>
- directive. Typically this login page will contain an HTML form, asking the user to
- provide their usename and password.</p>
-
- <div class="example"><h3>Example login form</h3><pre class="prettyprint lang-html"><form method="POST" action="/dologin.html">
- Username: <input type="text" name="httpd_username" value="" />
- Password: <input type="password" name="httpd_password" value="" />
- <input type="submit" name="login" value="Login" />
-</form></pre>
-</div>
-
- <p>The part that does the actual login is handled by the <var>form-login-handler</var>.
- The action of the form should point at this handler, which is configured within
- Apache httpd as follows:</p>
-
- <div class="example"><h3>Form login handler example</h3><pre class="prettyprint lang-config"><Location "/dologin.html">
- SetHandler form-login-handler
- AuthFormLoginRequiredLocation "http://example.com/login.html"
- AuthFormLoginSuccessLocation "http://example.com/success.html"
- AuthFormProvider file
- AuthUserFile "conf/passwd"
- AuthType form
- AuthName realm
- Session On
- SessionCookieName session path=/
- SessionCryptoPassphrase secret
-</Location></pre>
-</div>
-
- <p>The URLs specified by the
- <code class="directive"><a href="#authformloginrequiredlocation">AuthFormLoginRequiredLocation</a></code> directive will typically
- point to a page explaining to the user that their login attempt was unsuccessful, and they
- should try again. The <code class="directive"><a href="#authformloginsuccesslocation">AuthFormLoginSuccessLocation</a></code>
- directive specifies the URL the user should be redirected to upon successful login.</p>
-
- <p>Alternatively, the URL to redirect the user to on success can be embedded within the login
- form, as in the example below. As a result, the same <var>form-login-handler</var> can be
- reused for different areas of a website.</p>
-
- <div class="example"><h3>Example login form with location</h3><pre class="prettyprint lang-html"><form method="POST" action="/dologin.html">
- Username: <input type="text" name="httpd_username" value="" />
- Password: <input type="password" name="httpd_password" value="" />
- <input type="submit" name="login" value="Login" />
- <input type="hidden" name="httpd_location" value="http://example.com/success.html" />
-</form></pre>
-</div>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="inline" id="inline">Inline Login</a></h2>
-
- <div class="warning"><h3>Warning</h3>
- <p>A risk exists that under certain circumstances, the login form configured
- using inline login may be submitted more than once, revealing login credentials to
- the application running underneath. The administrator must ensure that the underlying
- application is properly secured to prevent abuse. If in doubt, use the
- standalone login configuration.</p>
- </div>
-
- <p>As an alternative to having a dedicated login page for a website, it is possible to
- configure <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> to authenticate users inline, without being
- redirected to another page. This allows the state of the current page to be preserved
- during the login attempt. This can be useful in a situation where a time limited
- session is in force, and the session times out in the middle of the user request. The
- user can be re-authenticated in place, and they can continue where they left off.</p>
-
- <p>If a non-authenticated user attempts to access a page protected by
- <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> that isn't configured with a
- <code class="directive"><a href="#authformloginrequiredlocation">AuthFormLoginRequiredLocation</a></code> directive,
- a <var>HTTP_UNAUTHORIZED</var> status code is returned to the browser indicating to the user
- that they are not authorized to view the page.</p>
-
- <p>To configure inline authentication, the administrator overrides the error document
- returned by the <var>HTTP_UNAUTHORIZED</var> status code with a custom error document
- containing the login form, as follows:</p>
-
- <div class="example"><h3>Basic inline example</h3><pre class="prettyprint lang-config">AuthFormProvider file
-ErrorDocument 401 "/login.shtml"
-AuthUserFile "conf/passwd"
-AuthType form
-AuthName realm
-AuthFormLoginRequiredLocation "http://example.com/login.html"
-Session On
-SessionCookieName session path=/
-SessionCryptoPassphrase secret</pre>
-</div>
-
- <p>The error document page should contain a login form with an empty action property,
- as per the example below. This has the effect of submitting the form to
- the original protected URL, without the page having to know what that
- URL is.</p>
-
- <div class="example"><h3>Example inline login form</h3><pre class="prettyprint lang-html"><form method="POST" <strong>action=""</strong>>
- Username: <input type="text" name="httpd_username" value="" />
- Password: <input type="password" name="httpd_password" value="" />
- <input type="submit" name="login" value="Login" />
-</form></pre>
-</div>
-
- <p>When the end user has filled in their login details, the form will make
- an HTTP POST request to the original password protected URL.
- <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> will intercept this POST request, and if
- HTML fields are found present for the username and password, the user
- will be logged in, and the original password protected URL will be returned
- to the user as a GET request.</p>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="inlinepreservebody" id="inlinepreservebody">Inline Login with Body Preservation</a></h2>
-
- <p>A limitation of the inline login technique described above is that should an
- HTML form POST have resulted in the request to authenticate or
- reauthenticate, the
- contents of the original form posted by the browser will be lost. Depending on
- the function of the website, this could present significant inconvenience for the
- end user.</p>
-
- <p><code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> addresses this by allowing the method and body
- of the original request to be embedded in the login form. If authentication
- is successful, the original method and body will be retried by Apache httpd, preserving
- the state of the original request.</p>
-
- <p>To enable body preservation, add three additional fields to the login form as
- per the example below.</p>
-
- <div class="example"><h3>Example with body preservation</h3><pre class="prettyprint lang-html"><form method="POST" action="">
- Username: <input type="text" name="httpd_username" value="" />
- Password: <input type="password" name="httpd_password" value="" />
- <input type="submit" name="login" value="Login" />
- <br /> <strong><input type="hidden" name="httpd_method" value="POST" />
- <input type="hidden" name="httpd_mimetype" value="application/x-www-form-urlencoded" />
- <input type="hidden" name="httpd_body" value="name1=value1&name2=value2" /></strong><br />
-</form></pre>
-</div>
-
- <p>How the method, mimetype and body of the original request are embedded within the
- login form will depend on the platform and technology being used within the website.
- </p>
-
- <p>One option is to use the <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> module along with the
- <code class="directive"><a href="../mod/mod_request.html#keptbodysize">KeptBodySize</a></code> directive, along with a suitable
- CGI script to embed the variables in the form.</p>
-
- <p>Another option is to render the login form using a CGI script or other dynamic
- technology.</p>
-
- <div class="example"><h3>CGI example</h3><pre class="prettyprint lang-config"> AuthFormProvider file
- ErrorDocument 401 "/cgi-bin/login.cgi"
- ...</pre>
-</div>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="loggingout" id="loggingout">Logging Out</a></h2>
-
- <p>To enable a user to log out of a particular session, configure a page to
- be handled by the <var>form-logout-handler</var>. Any attempt to access this
- URL will cause the username and password to be removed from the current
- session, effectively logging the user out.</p>
-
- <p>By setting the
- <code class="directive"><a href="#authformlogoutlocation">AuthFormLogoutLocation</a></code> directive,
- a URL can be specified that the browser will be redirected to on successful
- logout. This URL might explain to the user that they have been logged out, and
- give the user the option to log in again.</p>
-
- <div class="example"><h3>Basic logout example</h3><pre class="prettyprint lang-config">SetHandler form-logout-handler
-AuthName realm
-AuthFormLogoutLocation "http://example.com/loggedout.html"
-Session On
-SessionCookieName session path=/
-SessionCryptoPassphrase secret</pre>
-</div>
-
- <p>Note that logging a user out does not delete the session; it merely removes
- the username and password from the session. If this results in an empty session,
- the net effect will be the removal of that session, but this is not
- guaranteed. If you want to guarantee the removal of a session, set the
- <code class="directive"><a href="../mod/mod_session.html#sessionmaxage">SessionMaxAge</a></code> directive to a small
- value, like 1 (setting the directive to zero would mean no session age limit).
- </p>
-
- <div class="example"><h3>Basic session expiry example</h3><pre class="prettyprint lang-config">SetHandler form-logout-handler
-AuthFormLogoutLocation "http://example.com/loggedout.html"
-Session On
-SessionMaxAge 1
-SessionCookieName session path=/
-SessionCryptoPassphrase secret</pre>
-</div>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="urlencoding" id="urlencoding">Usernames and Passwords</a></h2>
- <p>Note that form submission involves URLEncoding the form data:
- in this case the username and password. You should therefore
- pick usernames and passwords that avoid characters that are
- URLencoded in form submission, or you may get unexpected results.</p>
- </div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_auth_form.html" title="English"> en </a> |
via the <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code>
directive with the <code>anon</code> value.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#example">Example</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#anonymous">Anonymous</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#anonymous_logemail">Anonymous_LogEmail</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#anonymous_nouserid">Anonymous_NoUserID</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#anonymous_verifyemail">Anonymous_VerifyEmail</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#example">Example</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="example" id="example">Example</a></h2>
+ <p>The example below is combined with "normal" htpasswd-file based
+ authentication and allows users in additionally as 'guests' with the
+ following properties:</p>
+
+ <ul>
+ <li>It insists that the user enters a userID.
+ (<code class="directive"><a href="#anonymous_nouserid">Anonymous_NoUserID</a></code>)</li>
+
+ <li>It insists that the user enters a password.
+ (<code class="directive"><a href="#anonymous_mustgiveemail">Anonymous_MustGiveEmail</a></code>)</li>
+
+ <li>The password entered must be a valid email address, <em>i.e.</em>
+ contain at least one '@' and a '.'.
+ (<code class="directive"><a href="#anonymous_verifyemail">Anonymous_VerifyEmail</a></code>)</li>
+
+ <li>The userID must be one of <code>anonymous guest www test
+ welcome</code> and comparison is <strong>not</strong> case
+ sensitive. (<code class="directive"><a href="#anonymous">Anonymous</a></code>)</li>
+
+ <li>And the Email addresses entered in the passwd field are
+ logged to the error log file.
+ (<code class="directive"><a href="#anonymous_logemail">Anonymous_LogEmail</a></code>)</li>
+ </ul>
+
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"><Directory "/var/www/html/private">
+ AuthName "Use 'anonymous' & Email address for guest entry"
+ AuthType Basic
+ AuthBasicProvider file anon
+ AuthUserFile "/path/to/your/.htpasswd"
+
+ Anonymous_NoUserID off
+ Anonymous_MustGiveEmail on
+ Anonymous_VerifyEmail on
+ Anonymous_LogEmail on
+ Anonymous anonymous guest www test welcome
+
+ Require valid-user
+</Directory></pre>
+</div>
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="Anonymous" id="Anonymous">Anonymous</a> <a name="anonymous" id="anonymous">Directive</a></h2>
<table class="directive">
at least one '@' and a '.' to encourage users to enter valid email
addresses (see the above <code class="directive"><a href="#anonymous_logemail">Anonymous_LogEmail</a></code>).</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="example" id="example">Example</a></h2>
- <p>The example below is combined with "normal" htpasswd-file based
- authentication and allows users in additionally as 'guests' with the
- following properties:</p>
-
- <ul>
- <li>It insists that the user enters a userID.
- (<code class="directive"><a href="#anonymous_nouserid">Anonymous_NoUserID</a></code>)</li>
-
- <li>It insists that the user enters a password.
- (<code class="directive"><a href="#anonymous_mustgiveemail">Anonymous_MustGiveEmail</a></code>)</li>
-
- <li>The password entered must be a valid email address, <em>i.e.</em>
- contain at least one '@' and a '.'.
- (<code class="directive"><a href="#anonymous_verifyemail">Anonymous_VerifyEmail</a></code>)</li>
-
- <li>The userID must be one of <code>anonymous guest www test
- welcome</code> and comparison is <strong>not</strong> case
- sensitive. (<code class="directive"><a href="#anonymous">Anonymous</a></code>)</li>
-
- <li>And the Email addresses entered in the passwd field are
- logged to the error log file.
- (<code class="directive"><a href="#anonymous_logemail">Anonymous_LogEmail</a></code>)</li>
- </ul>
-
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"><Directory "/var/www/html/private">
- AuthName "Use 'anonymous' & Email address for guest entry"
- AuthType Basic
- AuthBasicProvider file anon
- AuthUserFile "/path/to/your/.htpasswd"
-
- Anonymous_NoUserID off
- Anonymous_MustGiveEmail on
- Anonymous_VerifyEmail on
- Anonymous_LogEmail on
- Anonymous anonymous guest www test welcome
-
- Require valid-user
-</Directory></pre>
-</div>
</div>
</div>
<div class="bottomlang">
<code class="module"><a href="../mod/mod_authn_core.html">mod_authn_core</a></code> provides directives that are
common to all authentication providers.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#authnalias">Creating Authentication Provider Aliases</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#authname">AuthName</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authnprovideralias"><AuthnProviderAlias></a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authtype">AuthType</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#authnalias">Creating Authentication Provider Aliases</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="authnalias" id="authnalias">Creating Authentication Provider Aliases</a></h2>
+
+ <p>Extended authentication providers can be created
+ within the configuration file and assigned an alias name. The alias
+ providers can then be referenced through the directives
+ <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> or
+ <code class="directive"><a href="../mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code> in
+ the same way as a base authentication provider. Besides the ability
+ to create and alias an extended provider, it also allows the same
+ extended authentication provider to be reference by multiple
+ locations.</p>
+
+ <h3><a name="example" id="example">Examples</a></h3>
+
+ <p>This example checks for passwords in two different text
+ files.</p>
+
+ <div class="example"><h3>Checking multiple text password files</h3><pre class="prettyprint lang-config"># Check here first
+<AuthnProviderAlias file file1>
+ AuthUserFile "/www/conf/passwords1"
+</AuthnProviderAlias>
+
+# Then check here
+<AuthnProviderAlias file file2>
+ AuthUserFile "/www/conf/passwords2"
+</AuthnProviderAlias>
+
+<Directory "/var/web/pages/secure">
+ AuthBasicProvider file1 file2
+
+ AuthType Basic
+ AuthName "Protected Area"
+ Require valid-user
+</Directory></pre>
+</div>
+
+ <p>The example below creates two different ldap authentication
+ provider aliases based on the ldap provider. This allows
+ a single authenticated location to be serviced by multiple ldap
+ hosts:</p>
+
+ <div class="example"><h3>Checking multiple LDAP servers</h3><pre class="prettyprint lang-config"><AuthnProviderAlias ldap ldap-alias1>
+ AuthLDAPBindDN cn=youruser,o=ctx
+ AuthLDAPBindPassword yourpassword
+ AuthLDAPURL ldap://ldap.host/o=ctx
+</AuthnProviderAlias>
+<AuthnProviderAlias ldap ldap-other-alias>
+ AuthLDAPBindDN cn=yourotheruser,o=dev
+ AuthLDAPBindPassword yourotherpassword
+ AuthLDAPURL ldap://other.ldap.host/o=dev?cn
+</AuthnProviderAlias>
+
+Alias "/secure" "/webpages/secure"
+<Directory "/webpages/secure">
+ Order deny,allow
+ Allow from all
+
+ AuthBasicProvider ldap-other-alias ldap-alias1
+
+ AuthType Basic
+ AuthName "LDAP Protected Place"
+ Require valid-user
+ # Note that Require ldap-* would not work here, since the
+ # AuthnProviderAlias does not provide the config to authorization providers
+ # that are implemented in the same module as the authentication provider.
+</Directory></pre>
+</div>
+
+
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthName" id="AuthName">AuthName</a> <a name="authname" id="authname">Directive</a></h2>
<table class="directive">
<li><a href="../howto/auth.html">Authentication, Authorization,
and Access Control</a></li>
</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="authnalias" id="authnalias">Creating Authentication Provider Aliases</a></h2>
-
- <p>Extended authentication providers can be created
- within the configuration file and assigned an alias name. The alias
- providers can then be referenced through the directives
- <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> or
- <code class="directive"><a href="../mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code> in
- the same way as a base authentication provider. Besides the ability
- to create and alias an extended provider, it also allows the same
- extended authentication provider to be reference by multiple
- locations.</p>
-
- <h3><a name="example" id="example">Examples</a></h3>
-
- <p>This example checks for passwords in two different text
- files.</p>
-
- <div class="example"><h3>Checking multiple text password files</h3><pre class="prettyprint lang-config"># Check here first
-<AuthnProviderAlias file file1>
- AuthUserFile "/www/conf/passwords1"
-</AuthnProviderAlias>
-
-# Then check here
-<AuthnProviderAlias file file2>
- AuthUserFile "/www/conf/passwords2"
-</AuthnProviderAlias>
-
-<Directory "/var/web/pages/secure">
- AuthBasicProvider file1 file2
-
- AuthType Basic
- AuthName "Protected Area"
- Require valid-user
-</Directory></pre>
-</div>
-
- <p>The example below creates two different ldap authentication
- provider aliases based on the ldap provider. This allows
- a single authenticated location to be serviced by multiple ldap
- hosts:</p>
-
- <div class="example"><h3>Checking multiple LDAP servers</h3><pre class="prettyprint lang-config"><AuthnProviderAlias ldap ldap-alias1>
- AuthLDAPBindDN cn=youruser,o=ctx
- AuthLDAPBindPassword yourpassword
- AuthLDAPURL ldap://ldap.host/o=ctx
-</AuthnProviderAlias>
-<AuthnProviderAlias ldap ldap-other-alias>
- AuthLDAPBindDN cn=yourotheruser,o=dev
- AuthLDAPBindPassword yourotherpassword
- AuthLDAPURL ldap://other.ldap.host/o=dev?cn
-</AuthnProviderAlias>
-
-Alias "/secure" "/webpages/secure"
-<Directory "/webpages/secure">
- Order deny,allow
- Allow from all
-
- AuthBasicProvider ldap-other-alias ldap-alias1
-
- AuthType Basic
- AuthName "LDAP Protected Place"
- Require valid-user
- # Note that Require ldap-* would not work here, since the
- # AuthnProviderAlias does not provide the config to authorization providers
- # that are implemented in the same module as the authentication provider.
-</Directory></pre>
-</div>
-
-
</div>
</div>
<div class="bottomlang">
<code class="directive"><a href="../mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code>
with the <code>dbd</code> value.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#authdbduserpwquery">AuthDBDUserPWQuery</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#authdbduserrealmquery">AuthDBDUserRealmQuery</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#socache">Performance and Cacheing</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#example">Configuration Example</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#exposed">Exposing Login Information</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#authdbduserpwquery">AuthDBDUserPWQuery</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#authdbduserrealmquery">AuthDBDUserRealmQuery</a></li>
+</ul>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/mod_authn_core.html#authname">AuthName</a></code></li>
<li><code class="directive"><a href="../mod/mod_authn_core.html#authtype">AuthType</a></code></li>
<li><a href="../misc/password_encryptions.html">Password Formats</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthDBDUserPWQuery" id="AuthDBDUserPWQuery">AuthDBDUserPWQuery</a> <a name="authdbduserpwquery" id="authdbduserpwquery">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SQL query to look up a password for a user</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDBDUserPWQuery <var>query</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authn_dbd</td></tr>
-</table>
- <p>The <code class="directive">AuthDBDUserPWQuery</code> specifies an
- SQL query to look up a password for a specified user. The user's ID
- will be passed as a single string parameter when the SQL query is
- executed. It may be referenced within the query statement using
- a <code>%s</code> format specifier.</p>
- <pre class="prettyprint lang-config">AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"</pre>
-
- <p>The first column value of the first row returned by the query
- statement should be a string containing the encrypted password.
- Subsequent rows will be ignored. If no rows are returned, the user
- will not be authenticated through <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>.</p>
- <p>If httpd was built against <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a> version 1.3.0
- or higher, any additional column values in the first row returned by
- the query statement will be stored as environment variables with
- names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
- </p>
- <p>The encrypted password format depends on which authentication
- frontend (e.g. <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code> or
- <code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code>) is being used. See <a href="../misc/password_encryptions.html">Password Formats</a> for
- more information.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthDBDUserRealmQuery" id="AuthDBDUserRealmQuery">AuthDBDUserRealmQuery</a> <a name="authdbduserrealmquery" id="authdbduserrealmquery">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SQL query to look up a password hash for a user and realm.
-</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDBDUserRealmQuery <var>query</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authn_dbd</td></tr>
-</table>
- <p>The <code class="directive">AuthDBDUserRealmQuery</code> specifies an
- SQL query to look up a password for a specified user and realm in a
- digest authentication process.
- The user's ID and the realm, in that order, will be passed as string
- parameters when the SQL query is executed. They may be referenced
- within the query statement using <code>%s</code> format specifiers.</p>
- <pre class="prettyprint lang-config">AuthDBDUserRealmQuery "SELECT password FROM authn WHERE user = %s AND realm = %s"</pre>
-
- <p>The first column value of the first row returned by the query
- statement should be a string containing the encrypted password.
- Subsequent rows will be ignored. If no rows are returned, the user
- will not be authenticated through <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>.</p>
- <p>If httpd was built against <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a> version 1.3.0
- or higher, any additional column values in the first row returned by
- the query statement will be stored as environment variables with
- names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
- </p>
- <p>The encrypted password format depends on which authentication
- frontend (e.g. <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code> or
- <code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code>) is being used. See <a href="../misc/password_encryptions.html">Password Formats</a> for
- more information.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="socache" id="socache">Performance and Cacheing</a></h2>
<p>This has the potential to dramatically simplify the coding and
configuration required in some web applications.
</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthDBDUserPWQuery" id="AuthDBDUserPWQuery">AuthDBDUserPWQuery</a> <a name="authdbduserpwquery" id="authdbduserpwquery">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SQL query to look up a password for a user</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDBDUserPWQuery <var>query</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authn_dbd</td></tr>
+</table>
+ <p>The <code class="directive">AuthDBDUserPWQuery</code> specifies an
+ SQL query to look up a password for a specified user. The user's ID
+ will be passed as a single string parameter when the SQL query is
+ executed. It may be referenced within the query statement using
+ a <code>%s</code> format specifier.</p>
+ <pre class="prettyprint lang-config">AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"</pre>
+
+ <p>The first column value of the first row returned by the query
+ statement should be a string containing the encrypted password.
+ Subsequent rows will be ignored. If no rows are returned, the user
+ will not be authenticated through <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>.</p>
+ <p>If httpd was built against <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a> version 1.3.0
+ or higher, any additional column values in the first row returned by
+ the query statement will be stored as environment variables with
+ names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
+ </p>
+ <p>The encrypted password format depends on which authentication
+ frontend (e.g. <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code> or
+ <code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code>) is being used. See <a href="../misc/password_encryptions.html">Password Formats</a> for
+ more information.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthDBDUserRealmQuery" id="AuthDBDUserRealmQuery">AuthDBDUserRealmQuery</a> <a name="authdbduserrealmquery" id="authdbduserrealmquery">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SQL query to look up a password hash for a user and realm.
+</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDBDUserRealmQuery <var>query</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authn_dbd</td></tr>
+</table>
+ <p>The <code class="directive">AuthDBDUserRealmQuery</code> specifies an
+ SQL query to look up a password for a specified user and realm in a
+ digest authentication process.
+ The user's ID and the realm, in that order, will be passed as string
+ parameters when the SQL query is executed. They may be referenced
+ within the query statement using <code>%s</code> format specifiers.</p>
+ <pre class="prettyprint lang-config">AuthDBDUserRealmQuery "SELECT password FROM authn WHERE user = %s AND realm = %s"</pre>
+
+ <p>The first column value of the first row returned by the query
+ statement should be a string containing the encrypted password.
+ Subsequent rows will be ignored. If no rows are returned, the user
+ will not be authenticated through <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>.</p>
+ <p>If httpd was built against <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a> version 1.3.0
+ or higher, any additional column values in the first row returned by
+ the query statement will be stored as environment variables with
+ names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
+ </p>
+ <p>The encrypted password format depends on which authentication
+ frontend (e.g. <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code> or
+ <code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code>) is being used. See <a href="../misc/password_encryptions.html">Password Formats</a> for
+ more information.</p>
+
</div>
</div>
<div class="bottomlang">
<li><code class="program"><a href="../programs/htdbm.html">htdbm</a></code></li>
<li><a href="../misc/password_encryptions.html">Password Formats</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthDBMType" id="AuthDBMType">AuthDBMType</a> <a name="authdbmtype" id="authdbmtype">Directive</a></h2>
<table class="directive">
<code class="program"><a href="../programs/htdbm.html">htdbm</a></code>.</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_authn_dbm.html" title="English"> en </a> |
<li><code class="program"><a href="../programs/htdigest.html">htdigest</a></code></li>
<li><a href="../misc/password_encryptions.html">Password Formats</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthUserFile" id="AuthUserFile">AuthUserFile</a> <a name="authuserfile" id="authuserfile">Directive</a></h2>
<table class="directive">
</div>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_authn_file.html" title="English"> en </a> |
<p>Maintains a cache of authentication credentials, so that a new backend
lookup is not required for every authenticated request.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#intro">Authentication Cacheing</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#dev">Cacheing with custom modules</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#authncachecontext">AuthnCacheContext</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authncacheenable">AuthnCacheEnable</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authncachesocache">AuthnCacheSOCache</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authncachetimeout">AuthnCacheTimeout</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#intro">Authentication Cacheing</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#dev">Cacheing with custom modules</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="intro" id="intro">Authentication Cacheing</a></h2>
+ <p>Some users of more heavyweight authentication such as SQL database
+ lookups (<code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>) have reported it putting an
+ unacceptable load on their authentication provider. A typical case
+ in point is where an HTML page contains hundreds of objects
+ (images, scripts, stylesheets, media, etc), and a request to the page
+ generates hundreds of effectively-immediate requests for authenticated
+ additional contents.</p>
+ <p>mod_authn_socache provides a solution to this problem by
+ maintaining a cache of authentication credentials.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="usage" id="usage">Usage</a></h2>
+ <p>The authentication cache should be used where authentication
+ lookups impose a significant load on the server, or a backend or
+ network. Authentication by file (<code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code>)
+ or dbm (<code class="module"><a href="../mod/mod_authn_dbm.html">mod_authn_dbm</a></code>) are unlikely to benefit,
+ as these are fast and lightweight in their own right (though in some
+ cases, such as a network-mounted file, cacheing may be worthwhile).
+ Other providers such as SQL or LDAP based authentication are more
+ likely to benefit, particularly where there is an observed
+ performance issue. Amongst the standard modules, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> manages its own cache, so only
+ <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code> will usually benefit from this cache.</p>
+ <p>The basic rules to cache for a provider are:</p>
+ <ol><li>Include the provider you're cacheing for in an
+ <code class="directive">AuthnCacheProvideFor</code> directive.</li>
+ <li>List <var>socache</var> ahead of the provider you're
+ cacheing for in your <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> or <code class="directive"><a href="../mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code> directive.</li>
+ </ol>
+ <p>A simple usage example to accelerate <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>
+ using dbm as a cache engine:</p>
+ <pre class="prettyprint lang-config">#AuthnCacheSOCache is optional. If specified, it is server-wide
+AuthnCacheSOCache dbm
+<Directory "/usr/www/myhost/private">
+ AuthType Basic
+ AuthName "Cached Authentication Example"
+ AuthBasicProvider socache dbd
+ AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
+ AuthnCacheProvideFor dbd
+ Require valid-user
+ #Optional
+ AuthnCacheContext dbd-authn-example
+</Directory></pre>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="dev" id="dev">Cacheing with custom modules</a></h2>
+ <p>Module developers should note that their modules must be enabled
+ for cacheing with mod_authn_socache. A single optional API function
+ <var>ap_authn_cache_store</var> is provided to cache credentials
+ a provider has just looked up or generated. Usage examples are
+ available in <a href="http://svn.eu.apache.org/viewvc?view=revision&revision=957072">r957072</a>, in which three authn providers are enabled for cacheing.</p>
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthnCacheContext" id="AuthnCacheContext">AuthnCacheContext</a> <a name="authncachecontext" id="authncachecontext">Directive</a></h2>
<table class="directive">
your timeout.</p>
</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="intro" id="intro">Authentication Cacheing</a></h2>
- <p>Some users of more heavyweight authentication such as SQL database
- lookups (<code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>) have reported it putting an
- unacceptable load on their authentication provider. A typical case
- in point is where an HTML page contains hundreds of objects
- (images, scripts, stylesheets, media, etc), and a request to the page
- generates hundreds of effectively-immediate requests for authenticated
- additional contents.</p>
- <p>mod_authn_socache provides a solution to this problem by
- maintaining a cache of authentication credentials.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="usage" id="usage">Usage</a></h2>
- <p>The authentication cache should be used where authentication
- lookups impose a significant load on the server, or a backend or
- network. Authentication by file (<code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code>)
- or dbm (<code class="module"><a href="../mod/mod_authn_dbm.html">mod_authn_dbm</a></code>) are unlikely to benefit,
- as these are fast and lightweight in their own right (though in some
- cases, such as a network-mounted file, cacheing may be worthwhile).
- Other providers such as SQL or LDAP based authentication are more
- likely to benefit, particularly where there is an observed
- performance issue. Amongst the standard modules, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> manages its own cache, so only
- <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code> will usually benefit from this cache.</p>
- <p>The basic rules to cache for a provider are:</p>
- <ol><li>Include the provider you're cacheing for in an
- <code class="directive">AuthnCacheProvideFor</code> directive.</li>
- <li>List <var>socache</var> ahead of the provider you're
- cacheing for in your <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> or <code class="directive"><a href="../mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code> directive.</li>
- </ol>
- <p>A simple usage example to accelerate <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>
- using dbm as a cache engine:</p>
- <pre class="prettyprint lang-config">#AuthnCacheSOCache is optional. If specified, it is server-wide
-AuthnCacheSOCache dbm
-<Directory "/usr/www/myhost/private">
- AuthType Basic
- AuthName "Cached Authentication Example"
- AuthBasicProvider socache dbd
- AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
- AuthnCacheProvideFor dbd
- Require valid-user
- #Optional
- AuthnCacheContext dbd-authn-example
-</Directory></pre>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="dev" id="dev">Cacheing with custom modules</a></h2>
- <p>Module developers should note that their modules must be enabled
- for cacheing with mod_authn_socache. A single optional API function
- <var>ap_authn_cache_store</var> is provided to cache credentials
- a provider has just looked up or generated. Usage examples are
- available in <a href="http://svn.eu.apache.org/viewvc?view=revision&revision=957072">r957072</a>, in which three authn providers are enabled for cacheing.</p>
-</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_authn_socache.html" title="English"> en </a> |
such as for Basic authentication, or can authenticate using arbitrary
mechanisms.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#authnzfcgicheckauthnprovider">AuthnzFcgiCheckAuthnProvider</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#authnzfcgidefineprovider">AuthnzFcgiDefineProvider</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#invocations">Invocation modes</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#examples">Additional examples</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#limitations">Limitations</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#authnzfcgicheckauthnprovider">AuthnzFcgiCheckAuthnProvider</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#authnzfcgidefineprovider">AuthnzFcgiDefineProvider</a></li>
+</ul>
+<h3>See also</h3>
<ul class="seealso">
<li><a href="../howto/auth.html">Authentication, Authorization,
and Access Control</a></li>
<li><code class="module"><a href="../mod/mod_proxy_fcgi.html">mod_proxy_fcgi</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthnzFcgiCheckAuthnProvider" id="AuthnzFcgiCheckAuthnProvider">AuthnzFcgiCheckAuthnProvider</a> <a name="authnzfcgicheckauthnprovider" id="authnzfcgicheckauthnprovider">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables a FastCGI application to handle the check_authn
-authentication hook.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthnzFcgiCheckAuthnProvider <em>provider-name</em>|<code>None</code>
-<em>option</em> ...</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_fcgi</td></tr>
-</table>
- <p>This directive is used to enable a FastCGI authorizer to
- handle a specific processing phase of authentication or
- authorization.</p>
-
- <p>Some capabilities of FastCGI authorizers require enablement
- using this directive instead of
- <code class="directive">AuthBasicProvider</code>:</p>
-
- <ul>
- <li>Non-Basic authentication; generally, determining the user
- id of the client and returning it from the authorizer; see the
- <code>UserExpr</code> option below</li>
- <li>Selecting a custom response code; for a non-200 response
- from the authorizer, the code from the authorizer will be the
- status of the response</li>
- <li>Setting the body of a non-200 response; if the authorizer
- provides a response body with a non-200 response, that body
- will be returned to the client; up to 8192 bytes of text are
- supported</li>
- </ul>
-
- <dl>
- <dt><em>provider-name</em></dt>
- <dd>This is the name of a provider defined with <code class="directive">
- AuthnzFcgiDefineProvider</code>.</dd>
-
- <dt><code>None</code></dt>
- <dd>Specify <code>None</code> to disable a provider enabled
- with this directive in an outer scope, such as in a parent
- directory.</dd>
-
- <dt><em>option</em></dt>
- <dd>The following options are supported:
-
- <dl>
- <dt>Authoritative On|Off (default On)</dt>
- <dd>This controls whether or not other modules are allowed
- to run when this module has a FastCGI authorizer configured
- and it fails the request.</dd>
-
- <dt>DefaultUser <em>userid</em></dt>
- <dd>When the authorizer returns success and <code>UserExpr</code>
- is configured and evaluates to an empty string (e.g., authorizer
- didn't return a variable), this value will be used as the user
- id. This is typically used when the authorizer has a concept of
- guest, or unauthenticated, users and guest users are mapped to
- some specific user id for logging and other purposes.</dd>
-
- <dt>RequireBasicAuth On|Off (default Off)</dt>
- <dd>This controls whether or not Basic auth is required
- before passing the request to the authorizer. If required,
- the authorizer won't be invoked without a user id and
- password; 401 will be returned for a request without that.</dd>
-
- <dt>UserExpr <em>expr</em> (no default)</dt>
- <dd>When Basic authentication isn't provided by the client
- and the authorizer determines the user, this expression,
- evaluated after calling the authorizer, determines the
- user. The expression follows <a href="../expr.html">
- ap_expr syntax</a> and must resolve to a string. A typical
- use is to reference a <code>Variable-<em>XXX</em></code>
- setting returned by the authorizer using an option like
- <code>UserExpr "%{reqenv:<em>XXX</em>}"</code>. If
- this option is specified and the user id can't be retrieved
- using the expression after a successful authentication, the
- request will be rejected with a 500 error.</dd>
-
- </dl>
- </dd>
- </dl>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthnzFcgiDefineProvider" id="AuthnzFcgiDefineProvider">AuthnzFcgiDefineProvider</a> <a name="authnzfcgidefineprovider" id="authnzfcgidefineprovider">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a FastCGI application as a provider for
-authentication and/or authorization</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthnzFcgiDefineProvider <em>type</em> <em>provider-name</em>
-<em>backend-address</em></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_fcgi</td></tr>
-</table>
- <p>This directive is used to define a FastCGI application as
- a provider for a particular phase of authentication or
- authorization.</p>
-
- <dl>
- <dt><em>type</em></dt>
- <dd>This must be set to <em>authn</em> for authentication,
- <em>authz</em> for authorization, or <em>authnz</em> for
- a generic FastCGI authorizer which performs both checks.</dd>
-
- <dt><em>provider-name</em></dt>
- <dd>This is used to assign a name to the provider which is
- used in other directives such as
- <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code>
- and
- <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>.</dd>
-
- <dt><em>backend-address</em></dt>
- <dd>This specifies the address of the application, in the form
- <em>fcgi://hostname:port/</em>. The application process(es)
- must be managed independently, such as with
- <code class="program"><a href="../programs/fcgistarter.html">fcgistarter</a></code>.</dd>
- </dl>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="invocations" id="invocations">Invocation modes</a></h2>
<pre class="prettyprint lang-config">LogLevel info authnz_fcgi:trace8</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthnzFcgiCheckAuthnProvider" id="AuthnzFcgiCheckAuthnProvider">AuthnzFcgiCheckAuthnProvider</a> <a name="authnzfcgicheckauthnprovider" id="authnzfcgicheckauthnprovider">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables a FastCGI application to handle the check_authn
+authentication hook.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthnzFcgiCheckAuthnProvider <em>provider-name</em>|<code>None</code>
+<em>option</em> ...</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_fcgi</td></tr>
+</table>
+ <p>This directive is used to enable a FastCGI authorizer to
+ handle a specific processing phase of authentication or
+ authorization.</p>
+
+ <p>Some capabilities of FastCGI authorizers require enablement
+ using this directive instead of
+ <code class="directive">AuthBasicProvider</code>:</p>
+
+ <ul>
+ <li>Non-Basic authentication; generally, determining the user
+ id of the client and returning it from the authorizer; see the
+ <code>UserExpr</code> option below</li>
+ <li>Selecting a custom response code; for a non-200 response
+ from the authorizer, the code from the authorizer will be the
+ status of the response</li>
+ <li>Setting the body of a non-200 response; if the authorizer
+ provides a response body with a non-200 response, that body
+ will be returned to the client; up to 8192 bytes of text are
+ supported</li>
+ </ul>
+
+ <dl>
+ <dt><em>provider-name</em></dt>
+ <dd>This is the name of a provider defined with <code class="directive">
+ AuthnzFcgiDefineProvider</code>.</dd>
+
+ <dt><code>None</code></dt>
+ <dd>Specify <code>None</code> to disable a provider enabled
+ with this directive in an outer scope, such as in a parent
+ directory.</dd>
+
+ <dt><em>option</em></dt>
+ <dd>The following options are supported:
+
+ <dl>
+ <dt>Authoritative On|Off (default On)</dt>
+ <dd>This controls whether or not other modules are allowed
+ to run when this module has a FastCGI authorizer configured
+ and it fails the request.</dd>
+
+ <dt>DefaultUser <em>userid</em></dt>
+ <dd>When the authorizer returns success and <code>UserExpr</code>
+ is configured and evaluates to an empty string (e.g., authorizer
+ didn't return a variable), this value will be used as the user
+ id. This is typically used when the authorizer has a concept of
+ guest, or unauthenticated, users and guest users are mapped to
+ some specific user id for logging and other purposes.</dd>
+
+ <dt>RequireBasicAuth On|Off (default Off)</dt>
+ <dd>This controls whether or not Basic auth is required
+ before passing the request to the authorizer. If required,
+ the authorizer won't be invoked without a user id and
+ password; 401 will be returned for a request without that.</dd>
+
+ <dt>UserExpr <em>expr</em> (no default)</dt>
+ <dd>When Basic authentication isn't provided by the client
+ and the authorizer determines the user, this expression,
+ evaluated after calling the authorizer, determines the
+ user. The expression follows <a href="../expr.html">
+ ap_expr syntax</a> and must resolve to a string. A typical
+ use is to reference a <code>Variable-<em>XXX</em></code>
+ setting returned by the authorizer using an option like
+ <code>UserExpr "%{reqenv:<em>XXX</em>}"</code>. If
+ this option is specified and the user id can't be retrieved
+ using the expression after a successful authentication, the
+ request will be rejected with a 500 error.</dd>
+
+ </dl>
+ </dd>
+ </dl>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthnzFcgiDefineProvider" id="AuthnzFcgiDefineProvider">AuthnzFcgiDefineProvider</a> <a name="authnzfcgidefineprovider" id="authnzfcgidefineprovider">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a FastCGI application as a provider for
+authentication and/or authorization</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthnzFcgiDefineProvider <em>type</em> <em>provider-name</em>
+<em>backend-address</em></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_fcgi</td></tr>
+</table>
+ <p>This directive is used to define a FastCGI application as
+ a provider for a particular phase of authentication or
+ authorization.</p>
+
+ <dl>
+ <dt><em>type</em></dt>
+ <dd>This must be set to <em>authn</em> for authentication,
+ <em>authz</em> for authorization, or <em>authnz</em> for
+ a generic FastCGI authorizer which performs both checks.</dd>
+
+ <dt><em>provider-name</em></dt>
+ <dd>This is used to assign a name to the provider which is
+ used in other directives such as
+ <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code>
+ and
+ <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>.</dd>
+
+ <dt><em>backend-address</em></dt>
+ <dd>This specifies the address of the application, in the form
+ <em>fcgi://hostname:port/</em>. The application process(es)
+ must be managed independently, such as with
+ <code class="program"><a href="../programs/fcgistarter.html">fcgistarter</a></code>.</dd>
+ </dl>
+
</div>
</div>
<div class="bottomlang">
via the <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code>
directive with the <code>ldap</code> value.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#contents">Contents</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#operation">Operation</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#usingtls">Using TLS</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#usingssl">Using SSL</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#exposed">Exposing Login Information</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#activedirectory">Using Active Directory</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#frontpage">Using Microsoft
+ FrontPage with mod_authnz_ldap</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#authldapauthorizeprefix">AuthLDAPAuthorizePrefix</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authldapbindauthoritative">AuthLDAPBindAuthoritative</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authldapsubgroupclass">AuthLDAPSubGroupClass</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authldapurl">AuthLDAPUrl</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#contents">Contents</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#operation">Operation</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#usingtls">Using TLS</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#usingssl">Using SSL</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#exposed">Exposing Login Information</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#activedirectory">Using Active Directory</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#frontpage">Using Microsoft
- FrontPage with mod_authnz_ldap</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code></li>
<li><code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code></li>
<li><code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPAuthorizePrefix" id="AuthLDAPAuthorizePrefix">AuthLDAPAuthorizePrefix</a> <a name="authldapauthorizeprefix" id="authldapauthorizeprefix">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the prefix for environment variables set during
-authorization</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPAuthorizePrefix <em>prefix</em></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPAuthorizePrefix AUTHORIZE_</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.6 and later</td></tr>
-</table>
- <p>This directive allows you to override the prefix used for environment
- variables set during LDAP authorization. If <em>AUTHENTICATE_</em> is
- specified, consumers of these environment variables see the same information
- whether LDAP has performed authentication, authorization, or both.</p>
+<div class="section">
+<h2><a name="contents" id="contents">Contents</a></h2>
- <div class="note"><h3>Note</h3>
- No authorization variables are set when a user is authorized on the basis of
- <code>Require valid-user</code>.
- </div>
+ <ul>
+ <li>
+ <a href="#operation">Operation</a>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPBindAuthoritative" id="AuthLDAPBindAuthoritative">AuthLDAPBindAuthoritative</a> <a name="authldapbindauthoritative" id="authldapbindauthoritative">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines if other authentication providers are used when a user can be mapped to a DN but the server cannot successfully bind with the user's credentials.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPBindAuthoritative<em>off|on</em></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPBindAuthoritative on</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-</table>
- <p>By default, subsequent authentication providers are only queried if a
- user cannot be mapped to a DN, but not if the user can be mapped to a DN and their
- password cannot be verified with an LDAP bind.
- If <code class="directive"><a href="#authldapbindauthoritative">AuthLDAPBindAuthoritative</a></code>
- is set to <em>off</em>, other configured authentication modules will have
- a chance to validate the user if the LDAP bind (with the current user's credentials)
- fails for any reason.</p>
- <p> This allows users present in both LDAP and
- <code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code> to authenticate
- when the LDAP server is available but the user's account is locked or password
- is otherwise unusable.</p>
+ <ul>
+ <li><a href="#authenphase">The Authentication
+ Phase</a></li>
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code></li>
-<li><code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPBindDN" id="AuthLDAPBindDN">AuthLDAPBindDN</a> <a name="authldapbinddn" id="authldapbinddn">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Optional DN to use in binding to the LDAP server</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPBindDN <em>distinguished-name</em></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-</table>
- <p>An optional DN used to bind to the server when searching for
- entries. If not provided, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will use
- an anonymous bind.</p>
+ <li><a href="#authorphase">The Authorization
+ Phase</a></li>
+ </ul>
+ </li>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPBindPassword" id="AuthLDAPBindPassword">AuthLDAPBindPassword</a> <a name="authldapbindpassword" id="authldapbindpassword">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Password used in conjuction with the bind DN</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPBindPassword <em>password</em></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><em>exec:</em> was added in 2.4.5.</td></tr>
-</table>
- <p>A bind password to use in conjunction with the bind DN. Note
- that the bind password is probably sensitive data, and should be
- properly protected. You should only use the <code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code> and <code class="directive"><a href="#authldapbindpassword">AuthLDAPBindPassword</a></code> if you
- absolutely need them to search the directory.</p>
+ <li>
+ <a href="#requiredirectives">The Require Directives</a>
- <p>If the value begins with exec: the resulting command will be
- executed and the first line returned to standard output by the
- program will be used as the password.</p>
-<pre class="prettyprint lang-config">#Password used as-is
-AuthLDAPBindPassword secret
+ <ul>
+ <li><a href="#requser">Require ldap-user</a></li>
+ <li><a href="#reqgroup">Require ldap-group</a></li>
+ <li><a href="#reqdn">Require ldap-dn</a></li>
+ <li><a href="#reqattribute">Require ldap-attribute</a></li>
+ <li><a href="#reqfilter">Require ldap-filter</a></li>
+ </ul>
+ </li>
-#Run /path/to/program to get my password
-AuthLDAPBindPassword exec:/path/to/program
+ <li><a href="#examples">Examples</a></li>
+ <li><a href="#usingtls">Using TLS</a></li>
+ <li><a href="#usingssl">Using SSL</a></li>
+ <li><a href="#exposed">Exposing Login Information</a></li>
+ <li><a href="#activedirectory">Using Active Directory</a></li>
+ <li>
+ <a href="#frontpage">Using Microsoft FrontPage with
+ <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code></a>
-#Run /path/to/otherProgram and provide arguments
-AuthLDAPBindPassword "exec:/path/to/otherProgram argument1"</pre>
+ <ul>
+ <li><a href="#howitworks">How It Works</a></li>
+ <li><a href="#fpcaveats">Caveats</a></li>
+ </ul>
+ </li>
+ </ul>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="operation" id="operation">Operation</a></h2>
+ <p>There are two phases in granting access to a user. The first
+ phase is authentication, in which the <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code>
+ authentication provider verifies that the user's credentials are valid.
+ This is also called the <em>search/bind</em> phase. The second phase is
+ authorization, in which <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> determines
+ if the authenticated user is allowed access to the resource in
+ question. This is also known as the <em>compare</em>
+ phase.</p>
+ <p><code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> registers both an authn_ldap authentication
+ provider and an authz_ldap authorization handler. The authn_ldap
+ authentication provider can be enabled through the
+ <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> directive
+ using the <code>ldap</code> value. The authz_ldap handler extends the
+ <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive's authorization types
+ by adding <code>ldap-user</code>, <code>ldap-dn</code> and <code>ldap-group</code>
+ values.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPCharsetConfig" id="AuthLDAPCharsetConfig">AuthLDAPCharsetConfig</a> <a name="authldapcharsetconfig" id="authldapcharsetconfig">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Language to charset conversion configuration file</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPCharsetConfig <em>file-path</em></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-</table>
- <p>The <code class="directive">AuthLDAPCharsetConfig</code> directive sets the location
- of the language to charset conversion configuration file. <var>File-path</var> is relative
- to the <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>. This file specifies
- the list of language extensions to character sets.
- Most administrators use the provided <code>charset.conv</code>
- file, which associates common language extensions to character sets.</p>
+<h3><a name="authenphase" id="authenphase">The Authentication
+ Phase</a></h3>
- <p>The file contains lines in the following format:</p>
+ <p>During the authentication phase, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code>
+ searches for an entry in the directory that matches the username
+ that the HTTP client passes. If a single unique match is found,
+ then <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> attempts to bind to the
+ directory server using the DN of the entry plus the password
+ provided by the HTTP client. Because it does a search, then a
+ bind, it is often referred to as the search/bind phase. Here are
+ the steps taken during the search/bind phase.</p>
- <div class="example"><p><code>
- <var>Language-Extension</var> <var>charset</var> [<var>Language-String</var>] ...
- </code></p></div>
+ <ol>
+ <li>Generate a search filter by combining the attribute and
+ filter provided in the <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> directive with
+ the username passed by the HTTP client.</li>
- <p>The case of the extension does not matter. Blank lines, and lines
- beginning with a hash character (<code>#</code>) are ignored.</p>
+ <li>Search the directory using the generated filter. If the
+ search does not return exactly one entry, deny or decline
+ access.</li>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPCompareAsUser" id="AuthLDAPCompareAsUser">AuthLDAPCompareAsUser</a> <a name="authldapcompareasuser" id="authldapcompareasuser">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the authenticated user's credentials to perform authorization comparisons</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPCompareAsUser on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPCompareAsUser off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.6 and later</td></tr>
-</table>
- <p>When set, and <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> has authenticated the
- user, LDAP comparisons for authorization use the queried distinguished name (DN)
- and HTTP basic authentication password of the authenticated user instead of
- the servers configured credentials.</p>
+ <li>Fetch the distinguished name of the entry retrieved from
+ the search and attempt to bind to the LDAP server using that
+ DN and the password passed by the HTTP client. If the bind is
+ unsuccessful, deny or decline access.</li>
+ </ol>
- <p> The <em>ldap-attribute</em>, <em>ldap-user</em>, and <em>ldap-group</em> (single-level only)
- authorization checks use comparisons.</p>
+ <p>The following directives are used during the search/bind
+ phase</p>
- <p>This directive only has effect on the comparisons performed during
- nested group processing when <code class="directive"><a href="#authldapsearchasuser">
- AuthLDAPSearchAsUser</a></code> is also enabled.</p>
+ <table>
+
+ <tr>
+ <td><code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code></td>
- <p> This directive should only be used when your LDAP server doesn't
- accept anonymous comparisons and you cannot use a dedicated
- <code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code>.
- </p>
+ <td>Specifies the LDAP server, the
+ base DN, the attribute to use in the search, as well as the
+ extra search filter to use.</td>
+ </tr>
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="#authldapinitialbindasuser">AuthLDAPInitialBindAsUser</a></code></li>
-<li><code class="directive"><a href="#authldapsearchasuser">AuthLDAPSearchAsUser</a></code></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPCompareDNOnServer" id="AuthLDAPCompareDNOnServer">AuthLDAPCompareDNOnServer</a> <a name="authldapcomparednonserver" id="authldapcomparednonserver">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the LDAP server to compare the DNs</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPCompareDNOnServer on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPCompareDNOnServer on</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-</table>
- <p>When set, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will use the LDAP
- server to compare the DNs. This is the only foolproof way to
- compare DNs. <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will search the
- directory for the DN specified with the <a href="#reqdn"><code>Require dn</code></a> directive, then,
- retrieve the DN and compare it with the DN retrieved from the user
- entry. If this directive is not set,
- <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> simply does a string comparison. It
- is possible to get false negatives with this approach, but it is
- much faster. Note the <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> cache can speed up
- DN comparison in most situations.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPDereferenceAliases" id="AuthLDAPDereferenceAliases">AuthLDAPDereferenceAliases</a> <a name="authldapdereferencealiases" id="authldapdereferencealiases">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>When will the module de-reference aliases</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPDereferenceAliases never|searching|finding|always</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPDereferenceAliases always</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-</table>
- <p>This directive specifies when <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will
- de-reference aliases during LDAP operations. The default is
- <code>always</code>.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPGroupAttribute" id="AuthLDAPGroupAttribute">AuthLDAPGroupAttribute</a> <a name="authldapgroupattribute" id="authldapgroupattribute">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>LDAP attributes used to identify the user members of
-groups.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPGroupAttribute <em>attribute</em></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPGroupAttribute member uniquemember</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-</table>
- <p>This directive specifies which LDAP attributes are used to
- check for user members within groups. Multiple attributes can be used
- by specifying this directive multiple times. If not specified,
- then <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> uses the <code>member</code> and
- <code>uniquemember</code> attributes.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPGroupAttributeIsDN" id="AuthLDAPGroupAttributeIsDN">AuthLDAPGroupAttributeIsDN</a> <a name="authldapgroupattributeisdn" id="authldapgroupattributeisdn">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the DN of the client username when checking for
-group membership</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPGroupAttributeIsDN on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPGroupAttributeIsDN on</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-</table>
- <p>When set <code>on</code>, this directive says to use the
- distinguished name of the client username when checking for group
- membership. Otherwise, the username will be used. For example,
- assume that the client sent the username <code>bjenson</code>,
- which corresponds to the LDAP DN <code>cn=Babs Jenson,
- o=Example</code>. If this directive is set,
- <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will check if the group has
- <code>cn=Babs Jenson, o=Example</code> as a member. If this
- directive is not set, then <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will
- check if the group has <code>bjenson</code> as a member.</p>
+ <tr>
+ <td><code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code></td>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPInitialBindAsUser" id="AuthLDAPInitialBindAsUser">AuthLDAPInitialBindAsUser</a> <a name="authldapinitialbindasuser" id="authldapinitialbindasuser">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines if the server does the initial DN lookup using the basic authentication users'
-own username, instead of anonymously or with hard-coded credentials for the server</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPInitialBindAsUser <em>off|on</em></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPInitialBindAsUser off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.6 and later</td></tr>
-</table>
- <p>By default, the server either anonymously, or with a dedicated user and
- password, converts the basic authentication username into an LDAP
- distinguished name (DN). This directive forces the server to use the verbatim username
- and password provided by the incoming user to perform the initial DN
- search.</p>
+ <td>An optional DN to bind with
+ during the search phase.</td>
+ </tr>
- <p> If the verbatim username can't directly bind, but needs some
- cosmetic transformation, see <code class="directive"><a href="#authldapinitialbindpattern">
- AuthLDAPInitialBindPattern</a></code>.</p>
+ <tr>
+ <td><code class="directive"><a href="#authldapbindpassword">AuthLDAPBindPassword</a></code></td>
- <p> This directive should only be used when your LDAP server doesn't
- accept anonymous searches and you cannot use a dedicated
- <code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code>.
- </p>
+ <td>An optional password to bind
+ with during the search phase.</td>
+ </tr>
+ </table>
- <div class="note"><h3>Not available with authorization-only</h3>
- This directive can only be used if this module authenticates the user, and
- has no effect when this module is used exclusively for authorization.
- </div>
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="#authldapinitialbindpattern">AuthLDAPInitialBindPattern</a></code></li>
-<li><code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code></li>
-<li><code class="directive"><a href="#authldapcompareasuser">AuthLDAPCompareAsUser</a></code></li>
-<li><code class="directive"><a href="#authldapsearchasuser">AuthLDAPSearchAsUser</a></code></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPInitialBindPattern" id="AuthLDAPInitialBindPattern">AuthLDAPInitialBindPattern</a> <a name="authldapinitialbindpattern" id="authldapinitialbindpattern">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the transformation of the basic authentication username to be used when binding to the LDAP server
-to perform a DN lookup</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPInitialBindPattern<em><var>regex</var> <var>substitution</var></em></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPInitialBindPattern (.*) $1 (remote username used verbatim)</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.6 and later</td></tr>
-</table>
- <p>If <code class="directive"><a href="#authldapinitialbindasuser">AuthLDAPInitialBindAsUser</a></code> is set to
- <em>ON</em>, the basic authentication username will be transformed according to the
- regular expression and substituion arguments.</p>
+<h3><a name="authorphase" id="authorphase">The Authorization Phase</a></h3>
- <p> The regular expression argument is compared against the current basic authentication username.
- The substitution argument may contain backreferences, but has no other variable interpolation.</p>
+ <p>During the authorization phase, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code>
+ attempts to determine if the user is authorized to access the
+ resource. Many of these checks require
+ <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> to do a compare operation on the
+ LDAP server. This is why this phase is often referred to as the
+ compare phase. <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> accepts the
+ following <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>
+ directives to determine if the credentials are acceptable:</p>
- <p> This directive should only be used when your LDAP server doesn't
- accept anonymous searches and you cannot use a dedicated
- <code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code>.
- </p>
+ <ul>
+ <li>Grant access if there is a <a href="#reqgroup"><code>Require ldap-user</code></a> directive, and the
+ username in the directive matches the username passed by the
+ client.</li>
- <pre class="prettyprint lang-config">AuthLDAPInitialBindPattern (.+) $1@example.com</pre>
+ <li>Grant access if there is a <a href="#reqdn"><code>Require
+ ldap-dn</code></a> directive, and the DN in the directive matches
+ the DN fetched from the LDAP directory.</li>
- <pre class="prettyprint lang-config">AuthLDAPInitialBindPattern (.+) cn=$1,dc=example,dc=com</pre>
+ <li>Grant access if there is a <a href="#reqgroup"><code>Require ldap-group</code></a> directive, and
+ the DN fetched from the LDAP directory (or the username
+ passed by the client) occurs in the LDAP group or, potentially, in
+ one of its sub-groups.</li>
+ <li>Grant access if there is a <a href="#reqattribute">
+ <code>Require ldap-attribute</code></a>
+ directive, and the attribute fetched from the LDAP directory
+ matches the given value.</li>
- <div class="note"><h3>Not available with authorization-only</h3>
- This directive can only be used if this module authenticates the user, and
- has no effect when this module is used exclusively for authorization.
- </div>
- <div class="note"><h3>debugging</h3>
- The substituted DN is recorded in the environment variable
- <em>LDAP_BINDASUSER</em>. If the regular expression does not match the input,
- the verbatim username is used.
- </div>
+ <li>Grant access if there is a <a href="#reqfilter">
+ <code>Require ldap-filter</code></a>
+ directive, and the search filter successfully finds a single user
+ object that matches the dn of the authenticated user.</li>
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="#authldapinitialbindasuser">AuthLDAPInitialBindAsUser</a></code></li>
-<li><code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPMaxSubGroupDepth" id="AuthLDAPMaxSubGroupDepth">AuthLDAPMaxSubGroupDepth</a> <a name="authldapmaxsubgroupdepth" id="authldapmaxsubgroupdepth">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the maximum sub-group nesting depth that will be
-evaluated before the user search is discontinued.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPMaxSubGroupDepth <var>Number</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPMaxSubGroupDepth 10</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.0 and later</td></tr>
-</table>
- <p>When this directive is set to a non-zero value <code>X</code>
- combined with use of the <code>Require ldap-group someGroupDN</code>
- directive, the provided user credentials will be searched for
- as a member of the <code>someGroupDN</code> directory object or of
- any group member of the current group up to the maximum nesting
- level <code>X</code> specified by this directive.</p>
- <p>See the <a href="#reqgroup"><code>Require ldap-group</code></a>
- section for a more detailed example.</p>
+ <li>otherwise, deny or decline access</li>
+ </ul>
- <div class="note"><h3>Nested groups performance</h3>
- <p> When <code class="directive">AuthLDAPSubGroupAttribute</code> overlaps with
- <code class="directive">AuthLDAPGroupAttribute</code> (as it does by default and
- as required by common LDAP schemas), uncached searching for subgroups in
- large groups can be very slow. If you use large, non-nested groups, set
- <code class="directive">AuthLDAPMaxSubGroupDepth</code> to zero.</p>
- </div>
+ <p>Other <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> values may also
+ be used which may require loading additional authorization modules.</p>
+ <ul>
+ <li>Grant access to all successfully authenticated users if
+ there is a <a href="#requser"><code>Require valid-user</code></a>
+ directive. (requires <code class="module"><a href="../mod/mod_authz_user.html">mod_authz_user</a></code>)</li>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPRemoteUserAttribute" id="AuthLDAPRemoteUserAttribute">AuthLDAPRemoteUserAttribute</a> <a name="authldapremoteuserattribute" id="authldapremoteuserattribute">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the value of the attribute returned during the user
-query to set the REMOTE_USER environment variable</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPRemoteUserAttribute uid</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-</table>
- <p>If this directive is set, the value of the
- <code>REMOTE_USER</code> environment variable will be set to the
- value of the attribute specified. Make sure that this attribute is
- included in the list of attributes in the AuthLDAPUrl definition,
- otherwise this directive will have no effect. This directive, if
- present, takes precedence over AuthLDAPRemoteUserIsDN. This
- directive is useful should you want people to log into a website
- using an email address, but a backend application expects the
- username as a userid.</p>
+ <li>Grant access if there is a <a href="#reqgroup"><code>Require group</code></a> directive, and
+ <code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> has been loaded with the
+ <code class="directive"><a href="../mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code>
+ directive set.</li>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPRemoteUserIsDN" id="AuthLDAPRemoteUserIsDN">AuthLDAPRemoteUserIsDN</a> <a name="authldapremoteuserisdn" id="authldapremoteuserisdn">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the DN of the client username to set the REMOTE_USER
-environment variable</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPRemoteUserIsDN on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPRemoteUserIsDN off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-</table>
- <p>If this directive is set to on, the value of the
- <code>REMOTE_USER</code> environment variable will be set to the full
- distinguished name of the authenticated user, rather than just
- the username that was passed by the client. It is turned off by
- default.</p>
+ <li>others...</li>
+ </ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPSearchAsUser" id="AuthLDAPSearchAsUser">AuthLDAPSearchAsUser</a> <a name="authldapsearchasuser" id="authldapsearchasuser">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the authenticated user's credentials to perform authorization searches</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPSearchAsUser on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPSearchAsUser off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.6 and later</td></tr>
-</table>
- <p>When set, and <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> has authenticated the
- user, LDAP searches for authorization use the queried distinguished name (DN)
- and HTTP basic authentication password of the authenticated user instead of
- the servers configured credentials.</p>
- <p> The <em>ldap-filter</em> and <em>ldap-dn</em> authorization
- checks use searches.</p>
+ <p><code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> uses the following directives during the
+ compare phase:</p>
- <p>This directive only has effect on the comparisons performed during
- nested group processing when <code class="directive"><a href="#authldapcompareasuser">
- AuthLDAPCompareAsUser</a></code> is also enabled.</p>
+ <table>
+
+ <tr>
+ <td><code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> </td>
- <p> This directive should only be used when your LDAP server doesn't
- accept anonymous searches and you cannot use a dedicated
- <code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code>.
- </p>
+ <td>The attribute specified in the
+ URL is used in compare operations for the <code>Require
+ ldap-user</code> operation.</td>
+ </tr>
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="#authldapinitialbindasuser">AuthLDAPInitialBindAsUser</a></code></li>
-<li><code class="directive"><a href="#authldapcompareasuser">AuthLDAPCompareAsUser</a></code></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPSubGroupAttribute" id="AuthLDAPSubGroupAttribute">AuthLDAPSubGroupAttribute</a> <a name="authldapsubgroupattribute" id="authldapsubgroupattribute">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the attribute labels, one value per
-directive line, used to distinguish the members of the current group that
-are groups.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPSubGroupAttribute <em>attribute</em></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPSubgroupAttribute member uniquemember</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.0 and later</td></tr>
-</table>
- <p>An LDAP group object may contain members that are users and
- members that are groups (called nested or sub groups). The
- <code>AuthLDAPSubGroupAttribute</code> directive identifies the
- labels of group members and the <code>AuthLDAPGroupAttribute</code>
- directive identifies the labels of the user members. Multiple
- attributes can be used by specifying this directive multiple times.
- If not specified, then <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> uses the
- <code>member</code> and <code>uniqueMember</code> attributes.</p>
+ <tr>
+ <td><code class="directive"><a href="#authldapcomparednonserver">AuthLDAPCompareDNOnServer</a></code></td>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPSubGroupClass" id="AuthLDAPSubGroupClass">AuthLDAPSubGroupClass</a> <a name="authldapsubgroupclass" id="authldapsubgroupclass">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies which LDAP objectClass values identify directory
-objects that are groups during sub-group processing.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPSubGroupClass <em>LdapObjectClass</em></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPSubGroupClass groupOfNames groupOfUniqueNames</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.0 and later</td></tr>
-</table>
- <p>An LDAP group object may contain members that are users and
- members that are groups (called nested or sub groups). The
- <code>AuthLDAPSubGroupAttribute</code> directive identifies the
- labels of members that may be sub-groups of the current group
- (as opposed to user members). The <code>AuthLDAPSubGroupClass</code>
- directive specifies the LDAP objectClass values used in verifying that
- these potential sub-groups are in fact group objects. Verified sub-groups
- can then be searched for more user or sub-group members. Multiple
- attributes can be used by specifying this directive multiple times.
- If not specified, then <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> uses the
- <code>groupOfNames</code> and <code>groupOfUniqueNames</code> values.</p>
+ <td>Determines the behavior of the
+ <code>Require ldap-dn</code> directive.</td>
+ </tr>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthLDAPUrl" id="AuthLDAPUrl">AuthLDAPUrl</a> <a name="authldapurl" id="authldapurl">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>URL specifying the LDAP search parameters</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPUrl <em>url [NONE|SSL|TLS|STARTTLS]</em></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
-</table>
- <p>An RFC 2255 URL which specifies the LDAP search parameters
- to use. The syntax of the URL is</p>
-<div class="example"><p><code>ldap://host:port/basedn?attribute?scope?filter</code></p></div>
- <p>If you want to specify more than one LDAP URL that Apache should try in turn, the syntax is:</p>
-<pre class="prettyprint lang-config">AuthLDAPUrl "ldap://ldap1.example.com ldap2.example.com/dc=..."</pre>
+ <tr>
+ <td><code class="directive"><a href="#authldapgroupattribute">AuthLDAPGroupAttribute</a></code></td>
-<p><em><strong>Caveat: </strong>If you specify multiple servers, you need to enclose the entire URL string in quotes;
-otherwise you will get an error: "AuthLDAPURL takes one argument, URL to define LDAP connection.." </em>
-You can of course use search parameters on each of these.</p>
+ <td>Determines the attribute to
+ use for comparisons in the <code>Require ldap-group</code>
+ directive.</td>
+ </tr>
-<dl>
-<dt>ldap</dt>
+ <tr>
+ <td><code class="directive"><a href="#authldapgroupattributeisdn">AuthLDAPGroupAttributeIsDN</a></code></td>
- <dd>For regular ldap, use the
- string <code>ldap</code>. For secure LDAP, use <code>ldaps</code>
- instead. Secure LDAP is only available if Apache was linked
- to an LDAP library with SSL support.</dd>
+ <td>Specifies whether to use the
+ user DN or the username when doing comparisons for the
+ <code>Require ldap-group</code> directive.</td>
+ </tr>
-<dt>host:port</dt>
+ <tr>
+ <td><code class="directive"><a href="#authldapmaxsubgroupdepth">AuthLDAPMaxSubGroupDepth</a></code></td>
- <dd>
- <p>The name/port of the ldap server (defaults to
- <code>localhost:389</code> for <code>ldap</code>, and
- <code>localhost:636</code> for <code>ldaps</code>). To
- specify multiple, redundant LDAP servers, just list all
- servers, separated by spaces. <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code>
- will try connecting to each server in turn, until it makes a
- successful connection. If multiple ldap servers are specified,
- then entire LDAP URL must be encapsulated in double quotes.</p>
+ <td>Determines the maximum depth of sub-groups that will be evaluated
+ during comparisons in the <code>Require ldap-group</code> directive.</td>
+ </tr>
- <p>Once a connection has been made to a server, that
- connection remains active for the life of the
- <code class="program"><a href="../programs/httpd.html">httpd</a></code> process, or until the LDAP server goes
- down.</p>
+ <tr>
+ <td><code class="directive"><a href="#authldapsubgroupattribute">AuthLDAPSubGroupAttribute</a></code></td>
- <p>If the LDAP server goes down and breaks an existing
- connection, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will attempt to
- re-connect, starting with the primary server, and trying
- each redundant server in turn. Note that this is different
- than a true round-robin search.</p>
- </dd>
+ <td>Determines the attribute to use when obtaining sub-group members
+ of the current group during comparisons in the <code>Require ldap-group</code>
+ directive.</td>
+ </tr>
-<dt>basedn</dt>
+ <tr>
+ <td><code class="directive"><a href="#authldapsubgroupclass">AuthLDAPSubGroupClass</a></code></td>
- <dd>The DN of the branch of the
- directory where all searches should start from. At the very
- least, this must be the top of your directory tree, but
- could also specify a subtree in the directory.</dd>
+ <td>Specifies the LDAP objectClass values used to identify if queried directory
+ objects really are group objects (as opposed to user objects) during the
+ <code>Require ldap-group</code> directive's sub-group processing.</td>
+ </tr>
+ </table>
-<dt>attribute</dt>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="requiredirectives" id="requiredirectives">The Require Directives</a></h2>
- <dd>The attribute to search for.
- Although RFC 2255 allows a comma-separated list of
- attributes, only the first attribute will be used, no
- matter how many are provided. If no attributes are
- provided, the default is to use <code>uid</code>. It's a good
- idea to choose an attribute that will be unique across all
- entries in the subtree you will be using. All attributes
- listed will be put into the environment with an AUTHENTICATE_ prefix
- for use by other modules.</dd>
+ <p>Apache's <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>
+ directives are used during the authorization phase to ensure that
+ a user is allowed to access a resource. mod_authnz_ldap extends the
+ authorization types with <code>ldap-user</code>, <code>ldap-dn</code>,
+ <code>ldap-group</code>, <code>ldap-attribute</code> and
+ <code>ldap-filter</code>. Other authorization types may also be
+ used but may require that additional authorization modules be loaded.</p>
-<dt>scope</dt>
+ <p>Since v2.4.8, <a href="../expr.html">expressions</a> are supported
+ within the LDAP require directives.</p>
- <dd>The scope of the search. Can be either <code>one</code> or
- <code>sub</code>. Note that a scope of <code>base</code> is
- also supported by RFC 2255, but is not supported by this
- module. If the scope is not provided, or if <code>base</code> scope
- is specified, the default is to use a scope of
- <code>sub</code>.</dd>
+<h3><a name="requser" id="requser">Require ldap-user</a></h3>
-<dt>filter</dt>
+ <p>The <code>Require ldap-user</code> directive specifies what
+ usernames can access the resource. Once
+ <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> has retrieved a unique DN from the
+ directory, it does an LDAP compare operation using the username
+ specified in the <code>Require ldap-user</code> to see if that username
+ is part of the just-fetched LDAP entry. Multiple users can be
+ granted access by putting multiple usernames on the line,
+ separated with spaces. If a username has a space in it, then it
+ must be surrounded with double quotes. Multiple users can also be
+ granted access by using multiple <code>Require ldap-user</code>
+ directives, with one user per line. For example, with a <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> of
+ <code>ldap://ldap/o=Example?cn</code> (i.e., <code>cn</code> is
+ used for searches), the following Require directives could be used
+ to restrict access:</p>
+<pre class="prettyprint lang-config">Require ldap-user "Barbara Jenson"
+Require ldap-user "Fred User"
+Require ldap-user "Joe Manager"</pre>
- <dd>A valid LDAP search filter. If
- not provided, defaults to <code>(objectClass=*)</code>, which
- will search for all objects in the tree. Filters are
- limited to approximately 8000 characters (the definition of
- <code>MAX_STRING_LEN</code> in the Apache source code). This
- should be more than sufficient for any application. In 2.4.10 and later,
- The word "none" may be used to not use any filter, which may be
- required by some primitive LDAP servers.</dd>
-</dl>
- <p>When doing searches, the attribute, filter and username passed
- by the HTTP client are combined to create a search filter that
- looks like
- <code>(&(<em>filter</em>)(<em>attribute</em>=<em>username</em>))</code>.</p>
+ <p>Because of the way that <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> handles this
+ directive, Barbara Jenson could sign on as <em>Barbara
+ Jenson</em>, <em>Babs Jenson</em> or any other <code>cn</code> that
+ she has in her LDAP entry. Only the single <code>Require
+ ldap-user</code> line is needed to support all values of the attribute
+ in the user's entry.</p>
- <p>For example, consider an URL of
- <code>ldap://ldap.example.com/o=Example?cn?sub?(posixid=*)</code>. When
- a client attempts to connect using a username of <code>Babs
- Jenson</code>, the resulting search filter will be
- <code>(&(posixid=*)(cn=Babs Jenson))</code>.</p>
+ <p>If the <code>uid</code> attribute was used instead of the
+ <code>cn</code> attribute in the URL above, the above three lines
+ could be condensed to</p>
+<pre class="prettyprint lang-config">Require ldap-user bjenson fuser jmanager</pre>
- <p>An optional parameter can be added to allow the LDAP Url to override
- the connection type. This parameter can be one of the following:</p>
-<dl>
- <dt>NONE</dt>
- <dd>Establish an unsecure connection on the default LDAP port. This
- is the same as <code>ldap://</code> on port 389.</dd>
- <dt>SSL</dt>
- <dd>Establish a secure connection on the default secure LDAP port.
- This is the same as <code>ldaps://</code></dd>
- <dt>TLS | STARTTLS</dt>
- <dd>Establish an upgraded secure connection on the default LDAP port.
- This connection will be initiated on port 389 by default and then
- upgraded to a secure connection on the same port.</dd>
-</dl>
- <p>See above for examples of <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> URLs.</p>
+<h3><a name="reqgroup" id="reqgroup">Require ldap-group</a></h3>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="contents" id="contents">Contents</a></h2>
+ <p>This directive specifies an LDAP group whose members are
+ allowed access. It takes the distinguished name of the LDAP
+ group. Note: Do not surround the group name with quotes.
+ For example, assume that the following entry existed in
+ the LDAP directory:</p>
+<div class="example"><pre>dn: cn=Administrators, o=Example
+objectClass: groupOfUniqueNames
+uniqueMember: cn=Barbara Jenson, o=Example
+uniqueMember: cn=Fred User, o=Example</pre></div>
- <ul>
- <li>
- <a href="#operation">Operation</a>
+ <p>The following directive would grant access to both Fred and
+ Barbara:</p>
+<pre class="prettyprint lang-config">Require ldap-group cn=Administrators, o=Example</pre>
- <ul>
- <li><a href="#authenphase">The Authentication
- Phase</a></li>
- <li><a href="#authorphase">The Authorization
- Phase</a></li>
- </ul>
- </li>
+ <p>Members can also be found within sub-groups of a specified LDAP group
+ if <code class="directive"><a href="#authldapmaxsubgroupdepth">AuthLDAPMaxSubGroupDepth</a></code>
+ is set to a value greater than 0. For example, assume the following entries
+ exist in the LDAP directory:</p>
+<div class="example"><pre>dn: cn=Employees, o=Example
+objectClass: groupOfUniqueNames
+uniqueMember: cn=Managers, o=Example
+uniqueMember: cn=Administrators, o=Example
+uniqueMember: cn=Users, o=Example
- <li>
- <a href="#requiredirectives">The Require Directives</a>
+dn: cn=Managers, o=Example
+objectClass: groupOfUniqueNames
+uniqueMember: cn=Bob Ellis, o=Example
+uniqueMember: cn=Tom Jackson, o=Example
- <ul>
- <li><a href="#requser">Require ldap-user</a></li>
- <li><a href="#reqgroup">Require ldap-group</a></li>
- <li><a href="#reqdn">Require ldap-dn</a></li>
- <li><a href="#reqattribute">Require ldap-attribute</a></li>
- <li><a href="#reqfilter">Require ldap-filter</a></li>
- </ul>
- </li>
+dn: cn=Administrators, o=Example
+objectClass: groupOfUniqueNames
+uniqueMember: cn=Barbara Jenson, o=Example
+uniqueMember: cn=Fred User, o=Example
- <li><a href="#examples">Examples</a></li>
- <li><a href="#usingtls">Using TLS</a></li>
- <li><a href="#usingssl">Using SSL</a></li>
- <li><a href="#exposed">Exposing Login Information</a></li>
- <li><a href="#activedirectory">Using Active Directory</a></li>
- <li>
- <a href="#frontpage">Using Microsoft FrontPage with
- <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code></a>
+dn: cn=Users, o=Example
+objectClass: groupOfUniqueNames
+uniqueMember: cn=Allan Jefferson, o=Example
+uniqueMember: cn=Paul Tilley, o=Example
+uniqueMember: cn=Temporary Employees, o=Example
+
+dn: cn=Temporary Employees, o=Example
+objectClass: groupOfUniqueNames
+uniqueMember: cn=Jim Swenson, o=Example
+uniqueMember: cn=Elliot Rhodes, o=Example</pre></div>
+
+ <p>The following directives would allow access for Bob Ellis, Tom Jackson,
+ Barbara Jenson, Fred User, Allan Jefferson, and Paul Tilley but would not
+ allow access for Jim Swenson, or Elliot Rhodes (since they are at a
+ sub-group depth of 2):</p>
+<pre class="prettyprint lang-config">Require ldap-group cn=Employees, o=Example
+AuthLDAPMaxSubGroupDepth 1</pre>
+
+
+ <p>Behavior of this directive is modified by the <code class="directive"><a href="#authldapgroupattribute">AuthLDAPGroupAttribute</a></code>, <code class="directive"><a href="#authldapgroupattributeisdn">AuthLDAPGroupAttributeIsDN</a></code>, <code class="directive"><a href="#authldapmaxsubgroupdepth">AuthLDAPMaxSubGroupDepth</a></code>, <code class="directive"><a href="#authldapsubgroupattribute">AuthLDAPSubGroupAttribute</a></code>, and <code class="directive"><a href="#authldapsubgroupclass">AuthLDAPSubGroupClass</a></code>
+ directives.</p>
+
+
+<h3><a name="reqdn" id="reqdn">Require ldap-dn</a></h3>
- <ul>
- <li><a href="#howitworks">How It Works</a></li>
- <li><a href="#fpcaveats">Caveats</a></li>
- </ul>
- </li>
- </ul>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="operation" id="operation">Operation</a></h2>
+ <p>The <code>Require ldap-dn</code> directive allows the administrator
+ to grant access based on distinguished names. It specifies a DN
+ that must match for access to be granted. If the distinguished
+ name that was retrieved from the directory server matches the
+ distinguished name in the <code>Require ldap-dn</code>, then
+ authorization is granted. Note: do not surround the distinguished
+ name with quotes.</p>
- <p>There are two phases in granting access to a user. The first
- phase is authentication, in which the <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code>
- authentication provider verifies that the user's credentials are valid.
- This is also called the <em>search/bind</em> phase. The second phase is
- authorization, in which <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> determines
- if the authenticated user is allowed access to the resource in
- question. This is also known as the <em>compare</em>
- phase.</p>
+ <p>The following directive would grant access to a specific
+ DN:</p>
+<pre class="prettyprint lang-config">Require ldap-dn cn=Barbara Jenson, o=Example</pre>
- <p><code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> registers both an authn_ldap authentication
- provider and an authz_ldap authorization handler. The authn_ldap
- authentication provider can be enabled through the
- <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> directive
- using the <code>ldap</code> value. The authz_ldap handler extends the
- <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive's authorization types
- by adding <code>ldap-user</code>, <code>ldap-dn</code> and <code>ldap-group</code>
- values.</p>
-<h3><a name="authenphase" id="authenphase">The Authentication
- Phase</a></h3>
+ <p>Behavior of this directive is modified by the <code class="directive"><a href="#authldapcomparednonserver">AuthLDAPCompareDNOnServer</a></code>
+ directive.</p>
- <p>During the authentication phase, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code>
- searches for an entry in the directory that matches the username
- that the HTTP client passes. If a single unique match is found,
- then <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> attempts to bind to the
- directory server using the DN of the entry plus the password
- provided by the HTTP client. Because it does a search, then a
- bind, it is often referred to as the search/bind phase. Here are
- the steps taken during the search/bind phase.</p>
- <ol>
- <li>Generate a search filter by combining the attribute and
- filter provided in the <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> directive with
- the username passed by the HTTP client.</li>
+<h3><a name="reqattribute" id="reqattribute">Require ldap-attribute</a></h3>
- <li>Search the directory using the generated filter. If the
- search does not return exactly one entry, deny or decline
- access.</li>
+ <p>The <code>Require ldap-attribute</code> directive allows the
+ administrator to grant access based on attributes of the authenticated
+ user in the LDAP directory. If the attribute in the directory
+ matches the value given in the configuration, access is granted.</p>
- <li>Fetch the distinguished name of the entry retrieved from
- the search and attempt to bind to the LDAP server using that
- DN and the password passed by the HTTP client. If the bind is
- unsuccessful, deny or decline access.</li>
- </ol>
+ <p>The following directive would grant access to anyone with
+ the attribute employeeType = active</p>
- <p>The following directives are used during the search/bind
- phase</p>
+ <pre class="prettyprint lang-config">Require ldap-attribute employeeType=active</pre>
- <table>
-
- <tr>
- <td><code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code></td>
- <td>Specifies the LDAP server, the
- base DN, the attribute to use in the search, as well as the
- extra search filter to use.</td>
- </tr>
+ <p>Multiple attribute/value pairs can be specified on the same line
+ separated by spaces or they can be specified in multiple
+ <code>Require ldap-attribute</code> directives. The effect of listing
+ multiple attribute/values pairs is an OR operation. Access will be
+ granted if any of the listed attribute values match the value of the
+ corresponding attribute in the user object. If the value of the
+ attribute contains a space, only the value must be within double quotes.</p>
- <tr>
- <td><code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code></td>
+ <p>The following directive would grant access to anyone with
+ the city attribute equal to "San Jose" or status equal to "Active"</p>
- <td>An optional DN to bind with
- during the search phase.</td>
- </tr>
+ <pre class="prettyprint lang-config">Require ldap-attribute city="San Jose" status=active</pre>
- <tr>
- <td><code class="directive"><a href="#authldapbindpassword">AuthLDAPBindPassword</a></code></td>
- <td>An optional password to bind
- with during the search phase.</td>
- </tr>
- </table>
-<h3><a name="authorphase" id="authorphase">The Authorization Phase</a></h3>
+<h3><a name="reqfilter" id="reqfilter">Require ldap-filter</a></h3>
- <p>During the authorization phase, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code>
- attempts to determine if the user is authorized to access the
- resource. Many of these checks require
- <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> to do a compare operation on the
- LDAP server. This is why this phase is often referred to as the
- compare phase. <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> accepts the
- following <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>
- directives to determine if the credentials are acceptable:</p>
+ <p>The <code>Require ldap-filter</code> directive allows the
+ administrator to grant access based on a complex LDAP search filter.
+ If the dn returned by the filter search matches the authenticated user
+ dn, access is granted.</p>
- <ul>
- <li>Grant access if there is a <a href="#reqgroup"><code>Require ldap-user</code></a> directive, and the
- username in the directive matches the username passed by the
- client.</li>
+ <p>The following directive would grant access to anyone having a cell phone
+ and is in the marketing department</p>
- <li>Grant access if there is a <a href="#reqdn"><code>Require
- ldap-dn</code></a> directive, and the DN in the directive matches
- the DN fetched from the LDAP directory.</li>
+ <pre class="prettyprint lang-config">Require ldap-filter &(cell=*)(department=marketing)</pre>
- <li>Grant access if there is a <a href="#reqgroup"><code>Require ldap-group</code></a> directive, and
- the DN fetched from the LDAP directory (or the username
- passed by the client) occurs in the LDAP group or, potentially, in
- one of its sub-groups.</li>
- <li>Grant access if there is a <a href="#reqattribute">
- <code>Require ldap-attribute</code></a>
- directive, and the attribute fetched from the LDAP directory
- matches the given value.</li>
+ <p>The difference between the <code>Require ldap-filter</code> directive and the
+ <code>Require ldap-attribute</code> directive is that <code>ldap-filter</code>
+ performs a search operation on the LDAP directory using the specified search
+ filter rather than a simple attribute comparison. If a simple attribute
+ comparison is all that is required, the comparison operation performed by
+ <code>ldap-attribute</code> will be faster than the search operation
+ used by <code>ldap-filter</code> especially within a large directory.</p>
- <li>Grant access if there is a <a href="#reqfilter">
- <code>Require ldap-filter</code></a>
- directive, and the search filter successfully finds a single user
- object that matches the dn of the authenticated user.</li>
- <li>otherwise, deny or decline access</li>
- </ul>
- <p>Other <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> values may also
- be used which may require loading additional authorization modules.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="examples" id="examples">Examples</a></h2>
<ul>
- <li>Grant access to all successfully authenticated users if
- there is a <a href="#requser"><code>Require valid-user</code></a>
- directive. (requires <code class="module"><a href="../mod/mod_authz_user.html">mod_authz_user</a></code>)</li>
-
- <li>Grant access if there is a <a href="#reqgroup"><code>Require group</code></a> directive, and
- <code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> has been loaded with the
- <code class="directive"><a href="../mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code>
- directive set.</li>
+ <li>
+ Grant access to anyone who exists in the LDAP directory,
+ using their UID for searches.
+<pre class="prettyprint lang-config">AuthLDAPURL "ldap://ldap1.example.com:389/ou=People, o=Example?uid?sub?(objectClass=*)"
+Require valid-user</pre>
- <li>others...</li>
- </ul>
+ </li>
+ <li>
+ The next example is the same as above; but with the fields
+ that have useful defaults omitted. Also, note the use of a
+ redundant LDAP server.
+<pre class="prettyprint lang-config">AuthLDAPURL "ldap://ldap1.example.com ldap2.example.com/ou=People, o=Example"
+Require valid-user</pre>
- <p><code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> uses the following directives during the
- compare phase:</p>
+ </li>
- <table>
-
- <tr>
- <td><code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> </td>
+ <li>
+ The next example is similar to the previous one, but it
+ uses the common name instead of the UID. Note that this
+ could be problematical if multiple people in the directory
+ share the same <code>cn</code>, because a search on <code>cn</code>
+ <strong>must</strong> return exactly one entry. That's why
+ this approach is not recommended: it's a better idea to
+ choose an attribute that is guaranteed unique in your
+ directory, such as <code>uid</code>.
+<pre class="prettyprint lang-config">AuthLDAPURL "ldap://ldap.example.com/ou=People, o=Example?cn"
+Require valid-user</pre>
- <td>The attribute specified in the
- URL is used in compare operations for the <code>Require
- ldap-user</code> operation.</td>
- </tr>
+ </li>
- <tr>
- <td><code class="directive"><a href="#authldapcomparednonserver">AuthLDAPCompareDNOnServer</a></code></td>
+ <li>
+ Grant access to anybody in the Administrators group. The
+ users must authenticate using their UID.
+<pre class="prettyprint lang-config">AuthLDAPURL ldap://ldap.example.com/o=Example?uid
+Require ldap-group cn=Administrators, o=Example</pre>
- <td>Determines the behavior of the
- <code>Require ldap-dn</code> directive.</td>
- </tr>
+ </li>
- <tr>
- <td><code class="directive"><a href="#authldapgroupattribute">AuthLDAPGroupAttribute</a></code></td>
+ <li>
+ Grant access to anybody in the group whose name matches the
+ hostname of the virtual host. In this example an
+ <a href="../expr.html">expression</a> is used to build the filter.
+<pre class="prettyprint lang-config">AuthLDAPURL ldap://ldap.example.com/o=Example?uid
+Require ldap-group cn=%{SERVER_NAME}, o=Example</pre>
- <td>Determines the attribute to
- use for comparisons in the <code>Require ldap-group</code>
- directive.</td>
- </tr>
+ </li>
- <tr>
- <td><code class="directive"><a href="#authldapgroupattributeisdn">AuthLDAPGroupAttributeIsDN</a></code></td>
+ <li>
+ The next example assumes that everyone at Example who
+ carries an alphanumeric pager will have an LDAP attribute
+ of <code>qpagePagerID</code>. The example will grant access
+ only to people (authenticated via their UID) who have
+ alphanumeric pagers:
+<pre class="prettyprint lang-config">AuthLDAPURL ldap://ldap.example.com/o=Example?uid??(qpagePagerID=*)
+Require valid-user</pre>
- <td>Specifies whether to use the
- user DN or the username when doing comparisons for the
- <code>Require ldap-group</code> directive.</td>
- </tr>
+ </li>
- <tr>
- <td><code class="directive"><a href="#authldapmaxsubgroupdepth">AuthLDAPMaxSubGroupDepth</a></code></td>
+ <li>
+ <p>The next example demonstrates the power of using filters
+ to accomplish complicated administrative requirements.
+ Without filters, it would have been necessary to create a
+ new LDAP group and ensure that the group's members remain
+ synchronized with the pager users. This becomes trivial
+ with filters. The goal is to grant access to anyone who has
+ a pager, plus grant access to Joe Manager, who doesn't
+ have a pager, but does need to access the same
+ resource:</p>
+<pre class="prettyprint lang-config">AuthLDAPURL ldap://ldap.example.com/o=Example?uid??(|(qpagePagerID=*)(uid=jmanager))
+Require valid-user</pre>
- <td>Determines the maximum depth of sub-groups that will be evaluated
- during comparisons in the <code>Require ldap-group</code> directive.</td>
- </tr>
- <tr>
- <td><code class="directive"><a href="#authldapsubgroupattribute">AuthLDAPSubGroupAttribute</a></code></td>
+ <p>This last may look confusing at first, so it helps to
+ evaluate what the search filter will look like based on who
+ connects, as shown below. If
+ Fred User connects as <code>fuser</code>, the filter would look
+ like</p>
- <td>Determines the attribute to use when obtaining sub-group members
- of the current group during comparisons in the <code>Require ldap-group</code>
- directive.</td>
- </tr>
+ <div class="example"><p><code>(&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))</code></p></div>
- <tr>
- <td><code class="directive"><a href="#authldapsubgroupclass">AuthLDAPSubGroupClass</a></code></td>
+ <p>The above search will only succeed if <em>fuser</em> has a
+ pager. When Joe Manager connects as <em>jmanager</em>, the
+ filter looks like</p>
- <td>Specifies the LDAP objectClass values used to identify if queried directory
- objects really are group objects (as opposed to user objects) during the
- <code>Require ldap-group</code> directive's sub-group processing.</td>
- </tr>
- </table>
+ <div class="example"><p><code>(&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))</code></p></div>
+ <p>The above search will succeed whether <em>jmanager</em>
+ has a pager or not.</p>
+ </li>
+ </ul>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
-<h2><a name="requiredirectives" id="requiredirectives">The Require Directives</a></h2>
-
- <p>Apache's <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>
- directives are used during the authorization phase to ensure that
- a user is allowed to access a resource. mod_authnz_ldap extends the
- authorization types with <code>ldap-user</code>, <code>ldap-dn</code>,
- <code>ldap-group</code>, <code>ldap-attribute</code> and
- <code>ldap-filter</code>. Other authorization types may also be
- used but may require that additional authorization modules be loaded.</p>
-
- <p>Since v2.4.8, <a href="../expr.html">expressions</a> are supported
- within the LDAP require directives.</p>
+<h2><a name="usingtls" id="usingtls">Using TLS</a></h2>
-<h3><a name="requser" id="requser">Require ldap-user</a></h3>
+ <p>To use TLS, see the <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> directives <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedclientcert">LDAPTrustedClientCert</a></code>, <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedglobalcert">LDAPTrustedGlobalCert</a></code> and <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedmode">LDAPTrustedMode</a></code>.</p>
- <p>The <code>Require ldap-user</code> directive specifies what
- usernames can access the resource. Once
- <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> has retrieved a unique DN from the
- directory, it does an LDAP compare operation using the username
- specified in the <code>Require ldap-user</code> to see if that username
- is part of the just-fetched LDAP entry. Multiple users can be
- granted access by putting multiple usernames on the line,
- separated with spaces. If a username has a space in it, then it
- must be surrounded with double quotes. Multiple users can also be
- granted access by using multiple <code>Require ldap-user</code>
- directives, with one user per line. For example, with a <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> of
- <code>ldap://ldap/o=Example?cn</code> (i.e., <code>cn</code> is
- used for searches), the following Require directives could be used
- to restrict access:</p>
-<pre class="prettyprint lang-config">Require ldap-user "Barbara Jenson"
-Require ldap-user "Fred User"
-Require ldap-user "Joe Manager"</pre>
+ <p>An optional second parameter can be added to the
+ <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> to override
+ the default connection type set by <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedmode">LDAPTrustedMode</a></code>.
+ This will allow the connection established by an <em>ldap://</em> Url
+ to be upgraded to a secure connection on the same port.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="usingssl" id="usingssl">Using SSL</a></h2>
+ <p>To use SSL, see the <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> directives <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedclientcert">LDAPTrustedClientCert</a></code>, <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedglobalcert">LDAPTrustedGlobalCert</a></code> and <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedmode">LDAPTrustedMode</a></code>.</p>
- <p>Because of the way that <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> handles this
- directive, Barbara Jenson could sign on as <em>Barbara
- Jenson</em>, <em>Babs Jenson</em> or any other <code>cn</code> that
- she has in her LDAP entry. Only the single <code>Require
- ldap-user</code> line is needed to support all values of the attribute
- in the user's entry.</p>
+ <p>To specify a secure LDAP server, use <em>ldaps://</em> in the
+ <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code>
+ directive, instead of <em>ldap://</em>.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="exposed" id="exposed">Exposing Login Information</a></h2>
- <p>If the <code>uid</code> attribute was used instead of the
- <code>cn</code> attribute in the URL above, the above three lines
- could be condensed to</p>
-<pre class="prettyprint lang-config">Require ldap-user bjenson fuser jmanager</pre>
+ <p>when this module performs <em>authentication</em>, ldap attributes specified
+ in the <code class="directive"><a href="#authldapurl">authldapurl</a></code>
+ directive are placed in environment variables with the prefix "AUTHENTICATE_".</p>
+ <p>when this module performs <em>authorization</em>, ldap attributes specified
+ in the <code class="directive"><a href="#authldapurl">authldapurl</a></code>
+ directive are placed in environment variables with the prefix "AUTHORIZE_".</p>
+ <p>If the attribute field contains the username, common name
+ and telephone number of a user, a CGI program will have access to
+ this information without the need to make a second independent LDAP
+ query to gather this additional information.</p>
-<h3><a name="reqgroup" id="reqgroup">Require ldap-group</a></h3>
+ <p>This has the potential to dramatically simplify the coding and
+ configuration required in some web applications.</p>
- <p>This directive specifies an LDAP group whose members are
- allowed access. It takes the distinguished name of the LDAP
- group. Note: Do not surround the group name with quotes.
- For example, assume that the following entry existed in
- the LDAP directory:</p>
-<div class="example"><pre>dn: cn=Administrators, o=Example
-objectClass: groupOfUniqueNames
-uniqueMember: cn=Barbara Jenson, o=Example
-uniqueMember: cn=Fred User, o=Example</pre></div>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="activedirectory" id="activedirectory">Using Active Directory</a></h2>
- <p>The following directive would grant access to both Fred and
- Barbara:</p>
-<pre class="prettyprint lang-config">Require ldap-group cn=Administrators, o=Example</pre>
+ <p>An Active Directory installation may support multiple domains at the
+ same time. To distinguish users between domains, an identifier called
+ a User Principle Name (UPN) can be added to a user's entry in the
+ directory. This UPN usually takes the form of the user's account
+ name, followed by the domain components of the particular domain,
+ for example <em>somebody@nz.example.com</em>.</p>
+ <p>You may wish to configure the <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code>
+ module to authenticate users present in any of the domains making up
+ the Active Directory forest. In this way both
+ <em>somebody@nz.example.com</em> and <em>someone@au.example.com</em>
+ can be authenticated using the same query at the same time.</p>
- <p>Members can also be found within sub-groups of a specified LDAP group
- if <code class="directive"><a href="#authldapmaxsubgroupdepth">AuthLDAPMaxSubGroupDepth</a></code>
- is set to a value greater than 0. For example, assume the following entries
- exist in the LDAP directory:</p>
-<div class="example"><pre>dn: cn=Employees, o=Example
-objectClass: groupOfUniqueNames
-uniqueMember: cn=Managers, o=Example
-uniqueMember: cn=Administrators, o=Example
-uniqueMember: cn=Users, o=Example
+ <p>To make this practical, Active Directory supports the concept of
+ a Global Catalog. This Global Catalog is a read only copy of selected
+ attributes of all the Active Directory servers within the Active
+ Directory forest. Querying the Global Catalog allows all the domains
+ to be queried in a single query, without the query spanning servers
+ over potentially slow links.</p>
-dn: cn=Managers, o=Example
-objectClass: groupOfUniqueNames
-uniqueMember: cn=Bob Ellis, o=Example
-uniqueMember: cn=Tom Jackson, o=Example
+ <p>If enabled, the Global Catalog is an independent directory server
+ that runs on port 3268 (3269 for SSL). To search for a user, do a
+ subtree search for the attribute <em>userPrincipalName</em>, with
+ an empty search root, like so:</p>
-dn: cn=Administrators, o=Example
-objectClass: groupOfUniqueNames
-uniqueMember: cn=Barbara Jenson, o=Example
-uniqueMember: cn=Fred User, o=Example
+<pre class="prettyprint lang-config">AuthLDAPBindDN apache@example.com
+AuthLDAPBindPassword password
+AuthLDAPURL ldap://10.0.0.1:3268/?userPrincipalName?sub</pre>
-dn: cn=Users, o=Example
-objectClass: groupOfUniqueNames
-uniqueMember: cn=Allan Jefferson, o=Example
-uniqueMember: cn=Paul Tilley, o=Example
-uniqueMember: cn=Temporary Employees, o=Example
-dn: cn=Temporary Employees, o=Example
-objectClass: groupOfUniqueNames
-uniqueMember: cn=Jim Swenson, o=Example
-uniqueMember: cn=Elliot Rhodes, o=Example</pre></div>
+ <p>Users will need to enter their User Principal Name as a login, in
+ the form <em>somebody@nz.example.com</em>.</p>
- <p>The following directives would allow access for Bob Ellis, Tom Jackson,
- Barbara Jenson, Fred User, Allan Jefferson, and Paul Tilley but would not
- allow access for Jim Swenson, or Elliot Rhodes (since they are at a
- sub-group depth of 2):</p>
-<pre class="prettyprint lang-config">Require ldap-group cn=Employees, o=Example
-AuthLDAPMaxSubGroupDepth 1</pre>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="frontpage" id="frontpage">Using Microsoft
+ FrontPage with mod_authnz_ldap</a></h2>
+ <p>Normally, FrontPage uses FrontPage-web-specific user/group
+ files (i.e., the <code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code> and
+ <code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> modules) to handle all
+ authentication. Unfortunately, it is not possible to just
+ change to LDAP authentication by adding the proper directives,
+ because it will break the <em>Permissions</em> forms in
+ the FrontPage client, which attempt to modify the standard
+ text-based authorization files.</p>
- <p>Behavior of this directive is modified by the <code class="directive"><a href="#authldapgroupattribute">AuthLDAPGroupAttribute</a></code>, <code class="directive"><a href="#authldapgroupattributeisdn">AuthLDAPGroupAttributeIsDN</a></code>, <code class="directive"><a href="#authldapmaxsubgroupdepth">AuthLDAPMaxSubGroupDepth</a></code>, <code class="directive"><a href="#authldapsubgroupattribute">AuthLDAPSubGroupAttribute</a></code>, and <code class="directive"><a href="#authldapsubgroupclass">AuthLDAPSubGroupClass</a></code>
- directives.</p>
+ <p>Once a FrontPage web has been created, adding LDAP
+ authentication to it is a matter of adding the following
+ directives to <em>every</em> <code>.htaccess</code> file
+ that gets created in the web</p>
+<pre class="prettyprint lang-config">AuthLDAPURL "the url"
+AuthGroupFile "mygroupfile"
+Require group "mygroupfile"</pre>
-<h3><a name="reqdn" id="reqdn">Require ldap-dn</a></h3>
+<h3><a name="howitworks" id="howitworks">How It Works</a></h3>
- <p>The <code>Require ldap-dn</code> directive allows the administrator
- to grant access based on distinguished names. It specifies a DN
- that must match for access to be granted. If the distinguished
- name that was retrieved from the directory server matches the
- distinguished name in the <code>Require ldap-dn</code>, then
- authorization is granted. Note: do not surround the distinguished
- name with quotes.</p>
+ <p>FrontPage restricts access to a web by adding the <code>Require
+ valid-user</code> directive to the <code>.htaccess</code>
+ files. The <code>Require valid-user</code> directive will succeed for
+ any user who is valid <em>as far as LDAP is
+ concerned</em>. This means that anybody who has an entry in
+ the LDAP directory is considered a valid user, whereas FrontPage
+ considers only those people in the local user file to be
+ valid. By substituting the ldap-group with group file authorization,
+ Apache is allowed to consult the local user file (which is managed by
+ FrontPage) - instead of LDAP - when handling authorizing the user.</p>
- <p>The following directive would grant access to a specific
- DN:</p>
-<pre class="prettyprint lang-config">Require ldap-dn cn=Barbara Jenson, o=Example</pre>
+ <p>Once directives have been added as specified above,
+ FrontPage users will be able to perform all management
+ operations from the FrontPage client.</p>
- <p>Behavior of this directive is modified by the <code class="directive"><a href="#authldapcomparednonserver">AuthLDAPCompareDNOnServer</a></code>
- directive.</p>
+<h3><a name="fpcaveats" id="fpcaveats">Caveats</a></h3>
+ <ul>
+ <li>When choosing the LDAP URL, the attribute to use for
+ authentication should be something that will also be valid
+ for putting into a <code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code> user file.
+ The user ID is ideal for this.</li>
-<h3><a name="reqattribute" id="reqattribute">Require ldap-attribute</a></h3>
+ <li>When adding users via FrontPage, FrontPage administrators
+ should choose usernames that already exist in the LDAP
+ directory (for obvious reasons). Also, the password that the
+ administrator enters into the form is ignored, since Apache
+ will actually be authenticating against the password in the
+ LDAP database, and not against the password in the local user
+ file. This could cause confusion for web administrators.</li>
- <p>The <code>Require ldap-attribute</code> directive allows the
- administrator to grant access based on attributes of the authenticated
- user in the LDAP directory. If the attribute in the directory
- matches the value given in the configuration, access is granted.</p>
+
+ <li>Apache must be compiled with <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code>,
+ <code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code> and
+ <code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> in order to
+ use FrontPage support. This is because Apache will still use
+ the <code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> group file for determine
+ the extent of a user's access to the FrontPage web.</li>
- <p>The following directive would grant access to anyone with
- the attribute employeeType = active</p>
+ <li>The directives must be put in the <code>.htaccess</code>
+ files. Attempting to put them inside <code class="directive"><a href="../mod/core.html#location"><Location></a></code> or <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> directives won't work. This
+ is because <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> has to be able to grab
+ the <code class="directive"><a href="../mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code>
+ directive that is found in FrontPage <code>.htaccess</code>
+ files so that it knows where to look for the valid user list. If
+ the <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> directives aren't in the same
+ <code>.htaccess</code> file as the FrontPage directives, then
+ the hack won't work, because <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will
+ never get a chance to process the <code>.htaccess</code> file,
+ and won't be able to find the FrontPage-managed user file.</li>
+ </ul>
- <pre class="prettyprint lang-config">Require ldap-attribute employeeType=active</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPAuthorizePrefix" id="AuthLDAPAuthorizePrefix">AuthLDAPAuthorizePrefix</a> <a name="authldapauthorizeprefix" id="authldapauthorizeprefix">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the prefix for environment variables set during
+authorization</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPAuthorizePrefix <em>prefix</em></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPAuthorizePrefix AUTHORIZE_</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.6 and later</td></tr>
+</table>
+ <p>This directive allows you to override the prefix used for environment
+ variables set during LDAP authorization. If <em>AUTHENTICATE_</em> is
+ specified, consumers of these environment variables see the same information
+ whether LDAP has performed authentication, authorization, or both.</p>
+ <div class="note"><h3>Note</h3>
+ No authorization variables are set when a user is authorized on the basis of
+ <code>Require valid-user</code>.
+ </div>
- <p>Multiple attribute/value pairs can be specified on the same line
- separated by spaces or they can be specified in multiple
- <code>Require ldap-attribute</code> directives. The effect of listing
- multiple attribute/values pairs is an OR operation. Access will be
- granted if any of the listed attribute values match the value of the
- corresponding attribute in the user object. If the value of the
- attribute contains a space, only the value must be within double quotes.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPBindAuthoritative" id="AuthLDAPBindAuthoritative">AuthLDAPBindAuthoritative</a> <a name="authldapbindauthoritative" id="authldapbindauthoritative">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines if other authentication providers are used when a user can be mapped to a DN but the server cannot successfully bind with the user's credentials.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPBindAuthoritative<em>off|on</em></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPBindAuthoritative on</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+</table>
+ <p>By default, subsequent authentication providers are only queried if a
+ user cannot be mapped to a DN, but not if the user can be mapped to a DN and their
+ password cannot be verified with an LDAP bind.
+ If <code class="directive"><a href="#authldapbindauthoritative">AuthLDAPBindAuthoritative</a></code>
+ is set to <em>off</em>, other configured authentication modules will have
+ a chance to validate the user if the LDAP bind (with the current user's credentials)
+ fails for any reason.</p>
+ <p> This allows users present in both LDAP and
+ <code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code> to authenticate
+ when the LDAP server is available but the user's account is locked or password
+ is otherwise unusable.</p>
- <p>The following directive would grant access to anyone with
- the city attribute equal to "San Jose" or status equal to "Active"</p>
+<h3>See also</h3>
+<ul>
+<li><code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code></li>
+<li><code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code></li>
+</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPBindDN" id="AuthLDAPBindDN">AuthLDAPBindDN</a> <a name="authldapbinddn" id="authldapbinddn">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Optional DN to use in binding to the LDAP server</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPBindDN <em>distinguished-name</em></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+</table>
+ <p>An optional DN used to bind to the server when searching for
+ entries. If not provided, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will use
+ an anonymous bind.</p>
- <pre class="prettyprint lang-config">Require ldap-attribute city="San Jose" status=active</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPBindPassword" id="AuthLDAPBindPassword">AuthLDAPBindPassword</a> <a name="authldapbindpassword" id="authldapbindpassword">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Password used in conjuction with the bind DN</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPBindPassword <em>password</em></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><em>exec:</em> was added in 2.4.5.</td></tr>
+</table>
+ <p>A bind password to use in conjunction with the bind DN. Note
+ that the bind password is probably sensitive data, and should be
+ properly protected. You should only use the <code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code> and <code class="directive"><a href="#authldapbindpassword">AuthLDAPBindPassword</a></code> if you
+ absolutely need them to search the directory.</p>
+ <p>If the value begins with exec: the resulting command will be
+ executed and the first line returned to standard output by the
+ program will be used as the password.</p>
+<pre class="prettyprint lang-config">#Password used as-is
+AuthLDAPBindPassword secret
+#Run /path/to/program to get my password
+AuthLDAPBindPassword exec:/path/to/program
+#Run /path/to/otherProgram and provide arguments
+AuthLDAPBindPassword "exec:/path/to/otherProgram argument1"</pre>
-<h3><a name="reqfilter" id="reqfilter">Require ldap-filter</a></h3>
- <p>The <code>Require ldap-filter</code> directive allows the
- administrator to grant access based on a complex LDAP search filter.
- If the dn returned by the filter search matches the authenticated user
- dn, access is granted.</p>
- <p>The following directive would grant access to anyone having a cell phone
- and is in the marketing department</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPCharsetConfig" id="AuthLDAPCharsetConfig">AuthLDAPCharsetConfig</a> <a name="authldapcharsetconfig" id="authldapcharsetconfig">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Language to charset conversion configuration file</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPCharsetConfig <em>file-path</em></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+</table>
+ <p>The <code class="directive">AuthLDAPCharsetConfig</code> directive sets the location
+ of the language to charset conversion configuration file. <var>File-path</var> is relative
+ to the <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>. This file specifies
+ the list of language extensions to character sets.
+ Most administrators use the provided <code>charset.conv</code>
+ file, which associates common language extensions to character sets.</p>
- <pre class="prettyprint lang-config">Require ldap-filter &(cell=*)(department=marketing)</pre>
+ <p>The file contains lines in the following format:</p>
+ <div class="example"><p><code>
+ <var>Language-Extension</var> <var>charset</var> [<var>Language-String</var>] ...
+ </code></p></div>
- <p>The difference between the <code>Require ldap-filter</code> directive and the
- <code>Require ldap-attribute</code> directive is that <code>ldap-filter</code>
- performs a search operation on the LDAP directory using the specified search
- filter rather than a simple attribute comparison. If a simple attribute
- comparison is all that is required, the comparison operation performed by
- <code>ldap-attribute</code> will be faster than the search operation
- used by <code>ldap-filter</code> especially within a large directory.</p>
+ <p>The case of the extension does not matter. Blank lines, and lines
+ beginning with a hash character (<code>#</code>) are ignored.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPCompareAsUser" id="AuthLDAPCompareAsUser">AuthLDAPCompareAsUser</a> <a name="authldapcompareasuser" id="authldapcompareasuser">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the authenticated user's credentials to perform authorization comparisons</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPCompareAsUser on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPCompareAsUser off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.6 and later</td></tr>
+</table>
+ <p>When set, and <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> has authenticated the
+ user, LDAP comparisons for authorization use the queried distinguished name (DN)
+ and HTTP basic authentication password of the authenticated user instead of
+ the servers configured credentials.</p>
+ <p> The <em>ldap-attribute</em>, <em>ldap-user</em>, and <em>ldap-group</em> (single-level only)
+ authorization checks use comparisons.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="examples" id="examples">Examples</a></h2>
+ <p>This directive only has effect on the comparisons performed during
+ nested group processing when <code class="directive"><a href="#authldapsearchasuser">
+ AuthLDAPSearchAsUser</a></code> is also enabled.</p>
- <ul>
- <li>
- Grant access to anyone who exists in the LDAP directory,
- using their UID for searches.
-<pre class="prettyprint lang-config">AuthLDAPURL "ldap://ldap1.example.com:389/ou=People, o=Example?uid?sub?(objectClass=*)"
-Require valid-user</pre>
+ <p> This directive should only be used when your LDAP server doesn't
+ accept anonymous comparisons and you cannot use a dedicated
+ <code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code>.
+ </p>
- </li>
+<h3>See also</h3>
+<ul>
+<li><code class="directive"><a href="#authldapinitialbindasuser">AuthLDAPInitialBindAsUser</a></code></li>
+<li><code class="directive"><a href="#authldapsearchasuser">AuthLDAPSearchAsUser</a></code></li>
+</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPCompareDNOnServer" id="AuthLDAPCompareDNOnServer">AuthLDAPCompareDNOnServer</a> <a name="authldapcomparednonserver" id="authldapcomparednonserver">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the LDAP server to compare the DNs</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPCompareDNOnServer on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPCompareDNOnServer on</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+</table>
+ <p>When set, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will use the LDAP
+ server to compare the DNs. This is the only foolproof way to
+ compare DNs. <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will search the
+ directory for the DN specified with the <a href="#reqdn"><code>Require dn</code></a> directive, then,
+ retrieve the DN and compare it with the DN retrieved from the user
+ entry. If this directive is not set,
+ <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> simply does a string comparison. It
+ is possible to get false negatives with this approach, but it is
+ much faster. Note the <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> cache can speed up
+ DN comparison in most situations.</p>
- <li>
- The next example is the same as above; but with the fields
- that have useful defaults omitted. Also, note the use of a
- redundant LDAP server.
-<pre class="prettyprint lang-config">AuthLDAPURL "ldap://ldap1.example.com ldap2.example.com/ou=People, o=Example"
-Require valid-user</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPDereferenceAliases" id="AuthLDAPDereferenceAliases">AuthLDAPDereferenceAliases</a> <a name="authldapdereferencealiases" id="authldapdereferencealiases">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>When will the module de-reference aliases</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPDereferenceAliases never|searching|finding|always</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPDereferenceAliases always</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+</table>
+ <p>This directive specifies when <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will
+ de-reference aliases during LDAP operations. The default is
+ <code>always</code>.</p>
- </li>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPGroupAttribute" id="AuthLDAPGroupAttribute">AuthLDAPGroupAttribute</a> <a name="authldapgroupattribute" id="authldapgroupattribute">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>LDAP attributes used to identify the user members of
+groups.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPGroupAttribute <em>attribute</em></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPGroupAttribute member uniquemember</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+</table>
+ <p>This directive specifies which LDAP attributes are used to
+ check for user members within groups. Multiple attributes can be used
+ by specifying this directive multiple times. If not specified,
+ then <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> uses the <code>member</code> and
+ <code>uniquemember</code> attributes.</p>
- <li>
- The next example is similar to the previous one, but it
- uses the common name instead of the UID. Note that this
- could be problematical if multiple people in the directory
- share the same <code>cn</code>, because a search on <code>cn</code>
- <strong>must</strong> return exactly one entry. That's why
- this approach is not recommended: it's a better idea to
- choose an attribute that is guaranteed unique in your
- directory, such as <code>uid</code>.
-<pre class="prettyprint lang-config">AuthLDAPURL "ldap://ldap.example.com/ou=People, o=Example?cn"
-Require valid-user</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPGroupAttributeIsDN" id="AuthLDAPGroupAttributeIsDN">AuthLDAPGroupAttributeIsDN</a> <a name="authldapgroupattributeisdn" id="authldapgroupattributeisdn">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the DN of the client username when checking for
+group membership</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPGroupAttributeIsDN on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPGroupAttributeIsDN on</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+</table>
+ <p>When set <code>on</code>, this directive says to use the
+ distinguished name of the client username when checking for group
+ membership. Otherwise, the username will be used. For example,
+ assume that the client sent the username <code>bjenson</code>,
+ which corresponds to the LDAP DN <code>cn=Babs Jenson,
+ o=Example</code>. If this directive is set,
+ <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will check if the group has
+ <code>cn=Babs Jenson, o=Example</code> as a member. If this
+ directive is not set, then <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will
+ check if the group has <code>bjenson</code> as a member.</p>
- </li>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPInitialBindAsUser" id="AuthLDAPInitialBindAsUser">AuthLDAPInitialBindAsUser</a> <a name="authldapinitialbindasuser" id="authldapinitialbindasuser">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines if the server does the initial DN lookup using the basic authentication users'
+own username, instead of anonymously or with hard-coded credentials for the server</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPInitialBindAsUser <em>off|on</em></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPInitialBindAsUser off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.6 and later</td></tr>
+</table>
+ <p>By default, the server either anonymously, or with a dedicated user and
+ password, converts the basic authentication username into an LDAP
+ distinguished name (DN). This directive forces the server to use the verbatim username
+ and password provided by the incoming user to perform the initial DN
+ search.</p>
- <li>
- Grant access to anybody in the Administrators group. The
- users must authenticate using their UID.
-<pre class="prettyprint lang-config">AuthLDAPURL ldap://ldap.example.com/o=Example?uid
-Require ldap-group cn=Administrators, o=Example</pre>
+ <p> If the verbatim username can't directly bind, but needs some
+ cosmetic transformation, see <code class="directive"><a href="#authldapinitialbindpattern">
+ AuthLDAPInitialBindPattern</a></code>.</p>
- </li>
+ <p> This directive should only be used when your LDAP server doesn't
+ accept anonymous searches and you cannot use a dedicated
+ <code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code>.
+ </p>
- <li>
- Grant access to anybody in the group whose name matches the
- hostname of the virtual host. In this example an
- <a href="../expr.html">expression</a> is used to build the filter.
-<pre class="prettyprint lang-config">AuthLDAPURL ldap://ldap.example.com/o=Example?uid
-Require ldap-group cn=%{SERVER_NAME}, o=Example</pre>
+ <div class="note"><h3>Not available with authorization-only</h3>
+ This directive can only be used if this module authenticates the user, and
+ has no effect when this module is used exclusively for authorization.
+ </div>
- </li>
+<h3>See also</h3>
+<ul>
+<li><code class="directive"><a href="#authldapinitialbindpattern">AuthLDAPInitialBindPattern</a></code></li>
+<li><code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code></li>
+<li><code class="directive"><a href="#authldapcompareasuser">AuthLDAPCompareAsUser</a></code></li>
+<li><code class="directive"><a href="#authldapsearchasuser">AuthLDAPSearchAsUser</a></code></li>
+</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPInitialBindPattern" id="AuthLDAPInitialBindPattern">AuthLDAPInitialBindPattern</a> <a name="authldapinitialbindpattern" id="authldapinitialbindpattern">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the transformation of the basic authentication username to be used when binding to the LDAP server
+to perform a DN lookup</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPInitialBindPattern<em><var>regex</var> <var>substitution</var></em></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPInitialBindPattern (.*) $1 (remote username used verbatim)</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.6 and later</td></tr>
+</table>
+ <p>If <code class="directive"><a href="#authldapinitialbindasuser">AuthLDAPInitialBindAsUser</a></code> is set to
+ <em>ON</em>, the basic authentication username will be transformed according to the
+ regular expression and substituion arguments.</p>
- <li>
- The next example assumes that everyone at Example who
- carries an alphanumeric pager will have an LDAP attribute
- of <code>qpagePagerID</code>. The example will grant access
- only to people (authenticated via their UID) who have
- alphanumeric pagers:
-<pre class="prettyprint lang-config">AuthLDAPURL ldap://ldap.example.com/o=Example?uid??(qpagePagerID=*)
-Require valid-user</pre>
+ <p> The regular expression argument is compared against the current basic authentication username.
+ The substitution argument may contain backreferences, but has no other variable interpolation.</p>
- </li>
+ <p> This directive should only be used when your LDAP server doesn't
+ accept anonymous searches and you cannot use a dedicated
+ <code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code>.
+ </p>
- <li>
- <p>The next example demonstrates the power of using filters
- to accomplish complicated administrative requirements.
- Without filters, it would have been necessary to create a
- new LDAP group and ensure that the group's members remain
- synchronized with the pager users. This becomes trivial
- with filters. The goal is to grant access to anyone who has
- a pager, plus grant access to Joe Manager, who doesn't
- have a pager, but does need to access the same
- resource:</p>
-<pre class="prettyprint lang-config">AuthLDAPURL ldap://ldap.example.com/o=Example?uid??(|(qpagePagerID=*)(uid=jmanager))
-Require valid-user</pre>
+ <pre class="prettyprint lang-config">AuthLDAPInitialBindPattern (.+) $1@example.com</pre>
+ <pre class="prettyprint lang-config">AuthLDAPInitialBindPattern (.+) cn=$1,dc=example,dc=com</pre>
- <p>This last may look confusing at first, so it helps to
- evaluate what the search filter will look like based on who
- connects, as shown below. If
- Fred User connects as <code>fuser</code>, the filter would look
- like</p>
- <div class="example"><p><code>(&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))</code></p></div>
+ <div class="note"><h3>Not available with authorization-only</h3>
+ This directive can only be used if this module authenticates the user, and
+ has no effect when this module is used exclusively for authorization.
+ </div>
+ <div class="note"><h3>debugging</h3>
+ The substituted DN is recorded in the environment variable
+ <em>LDAP_BINDASUSER</em>. If the regular expression does not match the input,
+ the verbatim username is used.
+ </div>
- <p>The above search will only succeed if <em>fuser</em> has a
- pager. When Joe Manager connects as <em>jmanager</em>, the
- filter looks like</p>
+<h3>See also</h3>
+<ul>
+<li><code class="directive"><a href="#authldapinitialbindasuser">AuthLDAPInitialBindAsUser</a></code></li>
+<li><code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code></li>
+</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPMaxSubGroupDepth" id="AuthLDAPMaxSubGroupDepth">AuthLDAPMaxSubGroupDepth</a> <a name="authldapmaxsubgroupdepth" id="authldapmaxsubgroupdepth">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the maximum sub-group nesting depth that will be
+evaluated before the user search is discontinued.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPMaxSubGroupDepth <var>Number</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPMaxSubGroupDepth 10</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.0 and later</td></tr>
+</table>
+ <p>When this directive is set to a non-zero value <code>X</code>
+ combined with use of the <code>Require ldap-group someGroupDN</code>
+ directive, the provided user credentials will be searched for
+ as a member of the <code>someGroupDN</code> directory object or of
+ any group member of the current group up to the maximum nesting
+ level <code>X</code> specified by this directive.</p>
+ <p>See the <a href="#reqgroup"><code>Require ldap-group</code></a>
+ section for a more detailed example.</p>
- <div class="example"><p><code>(&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))</code></p></div>
+ <div class="note"><h3>Nested groups performance</h3>
+ <p> When <code class="directive">AuthLDAPSubGroupAttribute</code> overlaps with
+ <code class="directive">AuthLDAPGroupAttribute</code> (as it does by default and
+ as required by common LDAP schemas), uncached searching for subgroups in
+ large groups can be very slow. If you use large, non-nested groups, set
+ <code class="directive">AuthLDAPMaxSubGroupDepth</code> to zero.</p>
+ </div>
- <p>The above search will succeed whether <em>jmanager</em>
- has a pager or not.</p>
- </li>
- </ul>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="usingtls" id="usingtls">Using TLS</a></h2>
- <p>To use TLS, see the <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> directives <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedclientcert">LDAPTrustedClientCert</a></code>, <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedglobalcert">LDAPTrustedGlobalCert</a></code> and <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedmode">LDAPTrustedMode</a></code>.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPRemoteUserAttribute" id="AuthLDAPRemoteUserAttribute">AuthLDAPRemoteUserAttribute</a> <a name="authldapremoteuserattribute" id="authldapremoteuserattribute">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the value of the attribute returned during the user
+query to set the REMOTE_USER environment variable</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPRemoteUserAttribute uid</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+</table>
+ <p>If this directive is set, the value of the
+ <code>REMOTE_USER</code> environment variable will be set to the
+ value of the attribute specified. Make sure that this attribute is
+ included in the list of attributes in the AuthLDAPUrl definition,
+ otherwise this directive will have no effect. This directive, if
+ present, takes precedence over AuthLDAPRemoteUserIsDN. This
+ directive is useful should you want people to log into a website
+ using an email address, but a backend application expects the
+ username as a userid.</p>
- <p>An optional second parameter can be added to the
- <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> to override
- the default connection type set by <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedmode">LDAPTrustedMode</a></code>.
- This will allow the connection established by an <em>ldap://</em> Url
- to be upgraded to a secure connection on the same port.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="usingssl" id="usingssl">Using SSL</a></h2>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPRemoteUserIsDN" id="AuthLDAPRemoteUserIsDN">AuthLDAPRemoteUserIsDN</a> <a name="authldapremoteuserisdn" id="authldapremoteuserisdn">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the DN of the client username to set the REMOTE_USER
+environment variable</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPRemoteUserIsDN on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPRemoteUserIsDN off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+</table>
+ <p>If this directive is set to on, the value of the
+ <code>REMOTE_USER</code> environment variable will be set to the full
+ distinguished name of the authenticated user, rather than just
+ the username that was passed by the client. It is turned off by
+ default.</p>
- <p>To use SSL, see the <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> directives <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedclientcert">LDAPTrustedClientCert</a></code>, <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedglobalcert">LDAPTrustedGlobalCert</a></code> and <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedmode">LDAPTrustedMode</a></code>.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPSearchAsUser" id="AuthLDAPSearchAsUser">AuthLDAPSearchAsUser</a> <a name="authldapsearchasuser" id="authldapsearchasuser">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the authenticated user's credentials to perform authorization searches</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPSearchAsUser on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPSearchAsUser off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.6 and later</td></tr>
+</table>
+ <p>When set, and <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> has authenticated the
+ user, LDAP searches for authorization use the queried distinguished name (DN)
+ and HTTP basic authentication password of the authenticated user instead of
+ the servers configured credentials.</p>
- <p>To specify a secure LDAP server, use <em>ldaps://</em> in the
- <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code>
- directive, instead of <em>ldap://</em>.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="exposed" id="exposed">Exposing Login Information</a></h2>
+ <p> The <em>ldap-filter</em> and <em>ldap-dn</em> authorization
+ checks use searches.</p>
- <p>when this module performs <em>authentication</em>, ldap attributes specified
- in the <code class="directive"><a href="#authldapurl">authldapurl</a></code>
- directive are placed in environment variables with the prefix "AUTHENTICATE_".</p>
+ <p>This directive only has effect on the comparisons performed during
+ nested group processing when <code class="directive"><a href="#authldapcompareasuser">
+ AuthLDAPCompareAsUser</a></code> is also enabled.</p>
- <p>when this module performs <em>authorization</em>, ldap attributes specified
- in the <code class="directive"><a href="#authldapurl">authldapurl</a></code>
- directive are placed in environment variables with the prefix "AUTHORIZE_".</p>
+ <p> This directive should only be used when your LDAP server doesn't
+ accept anonymous searches and you cannot use a dedicated
+ <code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code>.
+ </p>
- <p>If the attribute field contains the username, common name
- and telephone number of a user, a CGI program will have access to
- this information without the need to make a second independent LDAP
- query to gather this additional information.</p>
+<h3>See also</h3>
+<ul>
+<li><code class="directive"><a href="#authldapinitialbindasuser">AuthLDAPInitialBindAsUser</a></code></li>
+<li><code class="directive"><a href="#authldapcompareasuser">AuthLDAPCompareAsUser</a></code></li>
+</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPSubGroupAttribute" id="AuthLDAPSubGroupAttribute">AuthLDAPSubGroupAttribute</a> <a name="authldapsubgroupattribute" id="authldapsubgroupattribute">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the attribute labels, one value per
+directive line, used to distinguish the members of the current group that
+are groups.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPSubGroupAttribute <em>attribute</em></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPSubgroupAttribute member uniquemember</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.0 and later</td></tr>
+</table>
+ <p>An LDAP group object may contain members that are users and
+ members that are groups (called nested or sub groups). The
+ <code>AuthLDAPSubGroupAttribute</code> directive identifies the
+ labels of group members and the <code>AuthLDAPGroupAttribute</code>
+ directive identifies the labels of the user members. Multiple
+ attributes can be used by specifying this directive multiple times.
+ If not specified, then <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> uses the
+ <code>member</code> and <code>uniqueMember</code> attributes.</p>
- <p>This has the potential to dramatically simplify the coding and
- configuration required in some web applications.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPSubGroupClass" id="AuthLDAPSubGroupClass">AuthLDAPSubGroupClass</a> <a name="authldapsubgroupclass" id="authldapsubgroupclass">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies which LDAP objectClass values identify directory
+objects that are groups during sub-group processing.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPSubGroupClass <em>LdapObjectClass</em></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPSubGroupClass groupOfNames groupOfUniqueNames</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.0 and later</td></tr>
+</table>
+ <p>An LDAP group object may contain members that are users and
+ members that are groups (called nested or sub groups). The
+ <code>AuthLDAPSubGroupAttribute</code> directive identifies the
+ labels of members that may be sub-groups of the current group
+ (as opposed to user members). The <code>AuthLDAPSubGroupClass</code>
+ directive specifies the LDAP objectClass values used in verifying that
+ these potential sub-groups are in fact group objects. Verified sub-groups
+ can then be searched for more user or sub-group members. Multiple
+ attributes can be used by specifying this directive multiple times.
+ If not specified, then <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> uses the
+ <code>groupOfNames</code> and <code>groupOfUniqueNames</code> values.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="activedirectory" id="activedirectory">Using Active Directory</a></h2>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthLDAPUrl" id="AuthLDAPUrl">AuthLDAPUrl</a> <a name="authldapurl" id="authldapurl">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>URL specifying the LDAP search parameters</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPUrl <em>url [NONE|SSL|TLS|STARTTLS]</em></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authnz_ldap</td></tr>
+</table>
+ <p>An RFC 2255 URL which specifies the LDAP search parameters
+ to use. The syntax of the URL is</p>
+<div class="example"><p><code>ldap://host:port/basedn?attribute?scope?filter</code></p></div>
+ <p>If you want to specify more than one LDAP URL that Apache should try in turn, the syntax is:</p>
+<pre class="prettyprint lang-config">AuthLDAPUrl "ldap://ldap1.example.com ldap2.example.com/dc=..."</pre>
- <p>An Active Directory installation may support multiple domains at the
- same time. To distinguish users between domains, an identifier called
- a User Principle Name (UPN) can be added to a user's entry in the
- directory. This UPN usually takes the form of the user's account
- name, followed by the domain components of the particular domain,
- for example <em>somebody@nz.example.com</em>.</p>
+<p><em><strong>Caveat: </strong>If you specify multiple servers, you need to enclose the entire URL string in quotes;
+otherwise you will get an error: "AuthLDAPURL takes one argument, URL to define LDAP connection.." </em>
+You can of course use search parameters on each of these.</p>
- <p>You may wish to configure the <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code>
- module to authenticate users present in any of the domains making up
- the Active Directory forest. In this way both
- <em>somebody@nz.example.com</em> and <em>someone@au.example.com</em>
- can be authenticated using the same query at the same time.</p>
+<dl>
+<dt>ldap</dt>
- <p>To make this practical, Active Directory supports the concept of
- a Global Catalog. This Global Catalog is a read only copy of selected
- attributes of all the Active Directory servers within the Active
- Directory forest. Querying the Global Catalog allows all the domains
- to be queried in a single query, without the query spanning servers
- over potentially slow links.</p>
+ <dd>For regular ldap, use the
+ string <code>ldap</code>. For secure LDAP, use <code>ldaps</code>
+ instead. Secure LDAP is only available if Apache was linked
+ to an LDAP library with SSL support.</dd>
- <p>If enabled, the Global Catalog is an independent directory server
- that runs on port 3268 (3269 for SSL). To search for a user, do a
- subtree search for the attribute <em>userPrincipalName</em>, with
- an empty search root, like so:</p>
+<dt>host:port</dt>
-<pre class="prettyprint lang-config">AuthLDAPBindDN apache@example.com
-AuthLDAPBindPassword password
-AuthLDAPURL ldap://10.0.0.1:3268/?userPrincipalName?sub</pre>
+ <dd>
+ <p>The name/port of the ldap server (defaults to
+ <code>localhost:389</code> for <code>ldap</code>, and
+ <code>localhost:636</code> for <code>ldaps</code>). To
+ specify multiple, redundant LDAP servers, just list all
+ servers, separated by spaces. <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code>
+ will try connecting to each server in turn, until it makes a
+ successful connection. If multiple ldap servers are specified,
+ then entire LDAP URL must be encapsulated in double quotes.</p>
+ <p>Once a connection has been made to a server, that
+ connection remains active for the life of the
+ <code class="program"><a href="../programs/httpd.html">httpd</a></code> process, or until the LDAP server goes
+ down.</p>
- <p>Users will need to enter their User Principal Name as a login, in
- the form <em>somebody@nz.example.com</em>.</p>
+ <p>If the LDAP server goes down and breaks an existing
+ connection, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will attempt to
+ re-connect, starting with the primary server, and trying
+ each redundant server in turn. Note that this is different
+ than a true round-robin search.</p>
+ </dd>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="frontpage" id="frontpage">Using Microsoft
- FrontPage with mod_authnz_ldap</a></h2>
+<dt>basedn</dt>
- <p>Normally, FrontPage uses FrontPage-web-specific user/group
- files (i.e., the <code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code> and
- <code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> modules) to handle all
- authentication. Unfortunately, it is not possible to just
- change to LDAP authentication by adding the proper directives,
- because it will break the <em>Permissions</em> forms in
- the FrontPage client, which attempt to modify the standard
- text-based authorization files.</p>
+ <dd>The DN of the branch of the
+ directory where all searches should start from. At the very
+ least, this must be the top of your directory tree, but
+ could also specify a subtree in the directory.</dd>
- <p>Once a FrontPage web has been created, adding LDAP
- authentication to it is a matter of adding the following
- directives to <em>every</em> <code>.htaccess</code> file
- that gets created in the web</p>
-<pre class="prettyprint lang-config">AuthLDAPURL "the url"
-AuthGroupFile "mygroupfile"
-Require group "mygroupfile"</pre>
+<dt>attribute</dt>
+ <dd>The attribute to search for.
+ Although RFC 2255 allows a comma-separated list of
+ attributes, only the first attribute will be used, no
+ matter how many are provided. If no attributes are
+ provided, the default is to use <code>uid</code>. It's a good
+ idea to choose an attribute that will be unique across all
+ entries in the subtree you will be using. All attributes
+ listed will be put into the environment with an AUTHENTICATE_ prefix
+ for use by other modules.</dd>
-<h3><a name="howitworks" id="howitworks">How It Works</a></h3>
+<dt>scope</dt>
- <p>FrontPage restricts access to a web by adding the <code>Require
- valid-user</code> directive to the <code>.htaccess</code>
- files. The <code>Require valid-user</code> directive will succeed for
- any user who is valid <em>as far as LDAP is
- concerned</em>. This means that anybody who has an entry in
- the LDAP directory is considered a valid user, whereas FrontPage
- considers only those people in the local user file to be
- valid. By substituting the ldap-group with group file authorization,
- Apache is allowed to consult the local user file (which is managed by
- FrontPage) - instead of LDAP - when handling authorizing the user.</p>
+ <dd>The scope of the search. Can be either <code>one</code> or
+ <code>sub</code>. Note that a scope of <code>base</code> is
+ also supported by RFC 2255, but is not supported by this
+ module. If the scope is not provided, or if <code>base</code> scope
+ is specified, the default is to use a scope of
+ <code>sub</code>.</dd>
- <p>Once directives have been added as specified above,
- FrontPage users will be able to perform all management
- operations from the FrontPage client.</p>
+<dt>filter</dt>
+ <dd>A valid LDAP search filter. If
+ not provided, defaults to <code>(objectClass=*)</code>, which
+ will search for all objects in the tree. Filters are
+ limited to approximately 8000 characters (the definition of
+ <code>MAX_STRING_LEN</code> in the Apache source code). This
+ should be more than sufficient for any application. In 2.4.10 and later,
+ The word "none" may be used to not use any filter, which may be
+ required by some primitive LDAP servers.</dd>
+</dl>
-<h3><a name="fpcaveats" id="fpcaveats">Caveats</a></h3>
+ <p>When doing searches, the attribute, filter and username passed
+ by the HTTP client are combined to create a search filter that
+ looks like
+ <code>(&(<em>filter</em>)(<em>attribute</em>=<em>username</em>))</code>.</p>
- <ul>
- <li>When choosing the LDAP URL, the attribute to use for
- authentication should be something that will also be valid
- for putting into a <code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code> user file.
- The user ID is ideal for this.</li>
+ <p>For example, consider an URL of
+ <code>ldap://ldap.example.com/o=Example?cn?sub?(posixid=*)</code>. When
+ a client attempts to connect using a username of <code>Babs
+ Jenson</code>, the resulting search filter will be
+ <code>(&(posixid=*)(cn=Babs Jenson))</code>.</p>
- <li>When adding users via FrontPage, FrontPage administrators
- should choose usernames that already exist in the LDAP
- directory (for obvious reasons). Also, the password that the
- administrator enters into the form is ignored, since Apache
- will actually be authenticating against the password in the
- LDAP database, and not against the password in the local user
- file. This could cause confusion for web administrators.</li>
+ <p>An optional parameter can be added to allow the LDAP Url to override
+ the connection type. This parameter can be one of the following:</p>
-
- <li>Apache must be compiled with <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code>,
- <code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code> and
- <code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> in order to
- use FrontPage support. This is because Apache will still use
- the <code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> group file for determine
- the extent of a user's access to the FrontPage web.</li>
+<dl>
+ <dt>NONE</dt>
+ <dd>Establish an unsecure connection on the default LDAP port. This
+ is the same as <code>ldap://</code> on port 389.</dd>
+ <dt>SSL</dt>
+ <dd>Establish a secure connection on the default secure LDAP port.
+ This is the same as <code>ldaps://</code></dd>
+ <dt>TLS | STARTTLS</dt>
+ <dd>Establish an upgraded secure connection on the default LDAP port.
+ This connection will be initiated on port 389 by default and then
+ upgraded to a secure connection on the same port.</dd>
+</dl>
- <li>The directives must be put in the <code>.htaccess</code>
- files. Attempting to put them inside <code class="directive"><a href="../mod/core.html#location"><Location></a></code> or <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> directives won't work. This
- is because <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> has to be able to grab
- the <code class="directive"><a href="../mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code>
- directive that is found in FrontPage <code>.htaccess</code>
- files so that it knows where to look for the valid user list. If
- the <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> directives aren't in the same
- <code>.htaccess</code> file as the FrontPage directives, then
- the hack won't work, because <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> will
- never get a chance to process the <code>.htaccess</code> file,
- and won't be able to find the FrontPage-managed user file.</li>
- </ul>
+ <p>See above for examples of <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> URLs.</p>
</div>
</div>
also allows for advanced logic to be applied to the
authorization processing.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#authzalias">Creating Authorization Provider Aliases</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#logic">Authorization Containers</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#authmerging">AuthMerging</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authzprovideralias"><AuthzProviderAlias></a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#requireany"><RequireAny></a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#requirenone"><RequireNone></a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#authzalias">Creating Authorization Provider Aliases</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#logic">Authorization Containers</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="authzalias" id="authzalias">Creating Authorization Provider Aliases</a></h2>
+
+ <p>Extended authorization providers can be created within the configuration
+ file and assigned an alias name. The alias providers can then be referenced
+ through the <code class="directive"><a href="#require">Require</a></code> directive
+ in the same way as a base authorization provider. Besides the ability to
+ create and alias an extended provider, it also allows the same extended
+ authorization provider to be referenced by multiple locations.
+ </p>
+
+ <h3><a name="example" id="example">Example</a></h3>
+ <p>The example below creates two different ldap authorization provider
+ aliases based on the ldap-group authorization provider. This example
+ allows a single authorization location to check group membership within
+ multiple ldap hosts:
+ </p>
+
+ <pre class="prettyprint lang-config"><AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx>
+ AuthLDAPBindDN cn=youruser,o=ctx
+ AuthLDAPBindPassword yourpassword
+ AuthLDAPURL ldap://ldap.host/o=ctx
+</AuthzProviderAlias>
+
+<AuthzProviderAlias ldap-group ldap-group-alias2 cn=my-other-group,o=dev>
+ AuthLDAPBindDN cn=yourotheruser,o=dev
+ AuthLDAPBindPassword yourotherpassword
+ AuthLDAPURL ldap://other.ldap.host/o=dev?cn
+</AuthzProviderAlias>
+
+Alias "/secure" "/webpages/secure"
+<Directory "/webpages/secure">
+ Require all granted
+
+ AuthBasicProvider file
+
+ AuthType Basic
+ AuthName LDAP_Protected_Place
+
+ #implied OR operation
+ Require ldap-group-alias1
+ Require ldap-group-alias2
+</Directory></pre>
+
+
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="logic" id="logic">Authorization Containers</a></h2>
+
+ <p>The authorization container directives
+ <code class="directive"><a href="#requireall"><RequireAll></a></code>,
+ <code class="directive"><a href="#requireany"><RequireAny></a></code>
+ and
+ <code class="directive"><a href="#requirenone"><RequireNone></a></code>
+ may be combined with each other and with the
+ <code class="directive"><a href="#require">Require</a></code>
+ directive to express complex authorization logic.</p>
+
+ <p>The example below expresses the following authorization logic.
+ In order to access the resource, the user must either be the
+ <code>superadmin</code> user, or belong to both the
+ <code>admins</code> group and the <code>Administrators</code> LDAP
+ group and either belong to the <code>sales</code> group or
+ have the LDAP <code>dept</code> attribute <code>sales</code>.
+ Furthermore, in order to access the resource, the user must
+ not belong to either the <code>temps</code> group or the
+ LDAP group <code>Temporary Employees</code>.</p>
+
+ <pre class="prettyprint lang-config"><Directory "/www/mydocs">
+ <RequireAll>
+ <RequireAny>
+ Require user superadmin
+ <RequireAll>
+ Require group admins
+ Require ldap-group cn=Administrators,o=Airius
+ <RequireAny>
+ Require group sales
+ Require ldap-attribute dept="sales"
+ </RequireAny>
+ </RequireAll>
+ </RequireAny>
+ <RequireNone>
+ Require group temps
+ Require ldap-group cn=Temporary Employees,o=Airius
+ </RequireNone>
+ </RequireAll>
+</Directory></pre>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="requiredirectives" id="requiredirectives">The Require Directives</a></h2>
+
+ <p><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> provides some generic authorization
+ providers which can be used with the
+ <code class="directive"><a href="#require">Require</a></code> directive.</p>
+
+ <h3><a name="reqenv" id="reqenv">Require env</a></h3>
+
+ <p>The <code>env</code> provider allows access to the server
+ to be controlled based on the existence of an <a href="../env.html">environment variable</a>. When <code>Require
+ env <var>env-variable</var></code> is specified, then the request is
+ allowed access if the environment variable <var>env-variable</var>
+ 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
+ <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code>. 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>
+
+ <pre class="prettyprint lang-config">SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in
+<Directory "/docroot">
+ Require env let_me_in
+</Directory></pre>
+
+
+ <p>In this case, browsers with a user-agent string beginning
+ with <code>KnockKnock/2.0</code> will be allowed access, and all
+ others will be denied.</p>
+
+ <p>When the server looks up a path via an internal
+ <a class="glossarylink" href="../glossary.html#subrequest" title="see glossary">subrequest</a> such as looking
+ for a <code class="directive"><a href="../mod/mod_dir.html#directoryindex">DirectoryIndex</a></code>
+ or generating a directory listing with <code class="module"><a href="../mod/mod_autoindex.html">mod_autoindex</a></code>,
+ per-request environment variables are <em>not</em> inherited in the
+ subrequest. Additionally,
+ <code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code> directives
+ are not separately evaluated in the subrequest due to the API phases
+ <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code> takes action in.</p>
+
+
+
+ <h3><a name="reqall" id="reqall">Require all</a></h3>
+
+ <p>The <code>all</code> provider mimics the functionality that
+ was previously provided by the 'Allow from all' and 'Deny from all'
+ directives. This provider can take one of two arguments which are
+ 'granted' or 'denied'. The following examples will grant or deny
+ access to all requests.</p>
+
+ <pre class="prettyprint lang-config">Require all granted</pre>
+
+
+ <pre class="prettyprint lang-config">Require all denied</pre>
+
+
+
+
+ <h3><a name="reqmethod" id="reqmethod">Require method</a></h3>
+
+ <p>The <code>method</code> provider allows using the HTTP method in
+ authorization decisions. The GET and HEAD methods are treated as
+ equivalent. The TRACE method is not available to this provider,
+ use <code class="directive"><a href="../mod/core.html#traceenable">TraceEnable</a></code> instead.</p>
+
+ <p>The following example will only allow GET, HEAD, POST, and OPTIONS
+ requests:</p>
+
+ <pre class="prettyprint lang-config">Require method GET POST OPTIONS</pre>
+
+
+ <p>The following example will allow GET, HEAD, POST, and OPTIONS
+ requests without authentication, and require a valid user for all other
+ methods:</p>
+
+ <pre class="prettyprint lang-config"><RequireAny>
+ Require method GET POST OPTIONS
+ Require valid-user
+</RequireAny></pre>
+
+
+
+
+ <h3><a name="reqexpr" id="reqexpr">Require expr</a></h3>
+
+ <p>The <code>expr</code> provider allows basing authorization
+ decisions on arbitrary expressions.</p>
+
+ <pre class="prettyprint lang-config">Require expr "%{TIME_HOUR} -ge 9 && %{TIME_HOUR} -le 17"</pre>
+
+
+ <pre class="prettyprint lang-config"><RequireAll>
+ Require expr "!(%{QUERY_STRING} =~ /secret/)"
+ Require expr "%{REQUEST_URI} in { '/example.cgi', '/other.cgi' }"
+</RequireAll></pre>
+
+
+ <pre class="prettyprint lang-config">Require expr "!(%{QUERY_STRING} =~ /secret/) && %{REQUEST_URI} in { '/example.cgi', '/other.cgi' }"</pre>
+
+
+ <p>The syntax is described in the <a href="../expr.html">ap_expr</a>
+ documentation.</p>
+
+ <p>Normally, the expression is evaluated before authentication. However, if
+ the expression returns false and references the variable
+ <code>%{REMOTE_USER}</code>, authentication will be performed and
+ the expression will be re-evaluated.</p>
+
+
+
+
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthMerging" id="AuthMerging">AuthMerging</a> <a name="authmerging" id="authmerging">Directive</a></h2>
<table class="directive">
<li><a href="../howto/auth.html">Authentication, Authorization,
and Access Control</a></li>
</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="authzalias" id="authzalias">Creating Authorization Provider Aliases</a></h2>
-
- <p>Extended authorization providers can be created within the configuration
- file and assigned an alias name. The alias providers can then be referenced
- through the <code class="directive"><a href="#require">Require</a></code> directive
- in the same way as a base authorization provider. Besides the ability to
- create and alias an extended provider, it also allows the same extended
- authorization provider to be referenced by multiple locations.
- </p>
-
- <h3><a name="example" id="example">Example</a></h3>
- <p>The example below creates two different ldap authorization provider
- aliases based on the ldap-group authorization provider. This example
- allows a single authorization location to check group membership within
- multiple ldap hosts:
- </p>
-
- <pre class="prettyprint lang-config"><AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx>
- AuthLDAPBindDN cn=youruser,o=ctx
- AuthLDAPBindPassword yourpassword
- AuthLDAPURL ldap://ldap.host/o=ctx
-</AuthzProviderAlias>
-
-<AuthzProviderAlias ldap-group ldap-group-alias2 cn=my-other-group,o=dev>
- AuthLDAPBindDN cn=yourotheruser,o=dev
- AuthLDAPBindPassword yourotherpassword
- AuthLDAPURL ldap://other.ldap.host/o=dev?cn
-</AuthzProviderAlias>
-
-Alias "/secure" "/webpages/secure"
-<Directory "/webpages/secure">
- Require all granted
-
- AuthBasicProvider file
-
- AuthType Basic
- AuthName LDAP_Protected_Place
-
- #implied OR operation
- Require ldap-group-alias1
- Require ldap-group-alias2
-</Directory></pre>
-
-
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="logic" id="logic">Authorization Containers</a></h2>
-
- <p>The authorization container directives
- <code class="directive"><a href="#requireall"><RequireAll></a></code>,
- <code class="directive"><a href="#requireany"><RequireAny></a></code>
- and
- <code class="directive"><a href="#requirenone"><RequireNone></a></code>
- may be combined with each other and with the
- <code class="directive"><a href="#require">Require</a></code>
- directive to express complex authorization logic.</p>
-
- <p>The example below expresses the following authorization logic.
- In order to access the resource, the user must either be the
- <code>superadmin</code> user, or belong to both the
- <code>admins</code> group and the <code>Administrators</code> LDAP
- group and either belong to the <code>sales</code> group or
- have the LDAP <code>dept</code> attribute <code>sales</code>.
- Furthermore, in order to access the resource, the user must
- not belong to either the <code>temps</code> group or the
- LDAP group <code>Temporary Employees</code>.</p>
-
- <pre class="prettyprint lang-config"><Directory "/www/mydocs">
- <RequireAll>
- <RequireAny>
- Require user superadmin
- <RequireAll>
- Require group admins
- Require ldap-group cn=Administrators,o=Airius
- <RequireAny>
- Require group sales
- Require ldap-attribute dept="sales"
- </RequireAny>
- </RequireAll>
- </RequireAny>
- <RequireNone>
- Require group temps
- Require ldap-group cn=Temporary Employees,o=Airius
- </RequireNone>
- </RequireAll>
-</Directory></pre>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="requiredirectives" id="requiredirectives">The Require Directives</a></h2>
-
- <p><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> provides some generic authorization
- providers which can be used with the
- <code class="directive"><a href="#require">Require</a></code> directive.</p>
-
- <h3><a name="reqenv" id="reqenv">Require env</a></h3>
-
- <p>The <code>env</code> provider allows access to the server
- to be controlled based on the existence of an <a href="../env.html">environment variable</a>. When <code>Require
- env <var>env-variable</var></code> is specified, then the request is
- allowed access if the environment variable <var>env-variable</var>
- 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
- <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code>. 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>
-
- <pre class="prettyprint lang-config">SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in
-<Directory "/docroot">
- Require env let_me_in
-</Directory></pre>
-
-
- <p>In this case, browsers with a user-agent string beginning
- with <code>KnockKnock/2.0</code> will be allowed access, and all
- others will be denied.</p>
-
- <p>When the server looks up a path via an internal
- <a class="glossarylink" href="../glossary.html#subrequest" title="see glossary">subrequest</a> such as looking
- for a <code class="directive"><a href="../mod/mod_dir.html#directoryindex">DirectoryIndex</a></code>
- or generating a directory listing with <code class="module"><a href="../mod/mod_autoindex.html">mod_autoindex</a></code>,
- per-request environment variables are <em>not</em> inherited in the
- subrequest. Additionally,
- <code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code> directives
- are not separately evaluated in the subrequest due to the API phases
- <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code> takes action in.</p>
-
-
-
- <h3><a name="reqall" id="reqall">Require all</a></h3>
-
- <p>The <code>all</code> provider mimics the functionality that
- was previously provided by the 'Allow from all' and 'Deny from all'
- directives. This provider can take one of two arguments which are
- 'granted' or 'denied'. The following examples will grant or deny
- access to all requests.</p>
-
- <pre class="prettyprint lang-config">Require all granted</pre>
-
-
- <pre class="prettyprint lang-config">Require all denied</pre>
-
-
-
-
- <h3><a name="reqmethod" id="reqmethod">Require method</a></h3>
-
- <p>The <code>method</code> provider allows using the HTTP method in
- authorization decisions. The GET and HEAD methods are treated as
- equivalent. The TRACE method is not available to this provider,
- use <code class="directive"><a href="../mod/core.html#traceenable">TraceEnable</a></code> instead.</p>
-
- <p>The following example will only allow GET, HEAD, POST, and OPTIONS
- requests:</p>
-
- <pre class="prettyprint lang-config">Require method GET POST OPTIONS</pre>
-
-
- <p>The following example will allow GET, HEAD, POST, and OPTIONS
- requests without authentication, and require a valid user for all other
- methods:</p>
-
- <pre class="prettyprint lang-config"><RequireAny>
- Require method GET POST OPTIONS
- Require valid-user
-</RequireAny></pre>
-
-
-
-
- <h3><a name="reqexpr" id="reqexpr">Require expr</a></h3>
-
- <p>The <code>expr</code> provider allows basing authorization
- decisions on arbitrary expressions.</p>
-
- <pre class="prettyprint lang-config">Require expr "%{TIME_HOUR} -ge 9 && %{TIME_HOUR} -le 17"</pre>
-
-
- <pre class="prettyprint lang-config"><RequireAll>
- Require expr "!(%{QUERY_STRING} =~ /secret/)"
- Require expr "%{REQUEST_URI} in { '/example.cgi', '/other.cgi' }"
-</RequireAll></pre>
-
-
- <pre class="prettyprint lang-config">Require expr "!(%{QUERY_STRING} =~ /secret/) && %{REQUEST_URI} in { '/example.cgi', '/other.cgi' }"</pre>
-
-
- <p>The syntax is described in the <a href="../expr.html">ap_expr</a>
- documentation.</p>
-
- <p>Normally, the expression is evaluated before authentication. However, if
- the expression returns false and references the variable
- <code>%{REMOTE_USER}</code>, authentication will be performed and
- the expression will be re-evaluated.</p>
-
-
-
-
</div>
</div>
<div class="bottomlang">
the backend database driver and connection parameters, and
manage the database connections.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#authzdbdlogintoreferer">AuthzDBDLoginToReferer</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#authzdbdquery">AuthzDBDQuery</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#authzdbdredirectquery">AuthzDBDRedirectQuery</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#login">Database Login</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#client">Client Login integration</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#example">Configuration example</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#authzdbdlogintoreferer">AuthzDBDLoginToReferer</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#authzdbdquery">AuthzDBDQuery</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#authzdbdredirectquery">AuthzDBDRedirectQuery</a></li>
+</ul>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code></li>
<li>
<li><code class="directive"><a href="../mod/mod_dbd.html#dbdparams">DBDParams</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthzDBDLoginToReferer" id="AuthzDBDLoginToReferer">AuthzDBDLoginToReferer</a> <a name="authzdbdlogintoreferer" id="authzdbdlogintoreferer">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines whether to redirect the Client to the Referring
-page on successful login or logout if a <code>Referer</code> request
-header is present</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthzDBDLoginToReferer On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthzDBDLoginToReferer Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authz_dbd</td></tr>
-</table>
- <p>In conjunction with <code>Require dbd-login</code> or
- <code>Require dbd-logout</code>, this provides the option to
- redirect the client back to the Referring page (the URL in
- the <code>Referer</code> HTTP request header, if present).
- When there is no <code>Referer</code> header,
- <code>AuthzDBDLoginToReferer On</code> will be ignored.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthzDBDQuery" id="AuthzDBDQuery">AuthzDBDQuery</a> <a name="authzdbdquery" id="authzdbdquery">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify the SQL Query for the required operation</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthzDBDQuery <var>query</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authz_dbd</td></tr>
-</table>
- <p>The <code class="directive">AuthzDBDQuery</code> specifies an SQL
- query to run. The purpose of the query depends on the
- <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive in
- effect.</p>
- <ul>
- <li>When used with a <code>Require dbd-group</code> directive,
- it specifies a query to look up groups for the current user. This is
- the standard functionality of other authorization modules such as
- <code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> and <code class="module"><a href="../mod/mod_authz_dbm.html">mod_authz_dbm</a></code>.
- The first column value of each row returned by the query statement
- should be a string containing a group name. Zero, one, or more rows
- may be returned.
- <pre class="prettyprint lang-config">Require dbd-group
-AuthzDBDQuery "SELECT group FROM groups WHERE user = %s"</pre>
-
- </li>
- <li>When used with a <code>Require dbd-login</code> or
- <code>Require dbd-logout</code> directive, it will never deny access,
- but will instead execute a SQL statement designed to log the user
- in or out. The user must already be authenticated with
- <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>.
- <pre class="prettyprint lang-config">Require dbd-login
-AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"</pre>
-
- </li>
- </ul>
- <p>In all cases, the user's ID will be passed as a single string
- parameter when the SQL query is executed. It may be referenced within
- the query statement using a <code>%s</code> format specifier.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthzDBDRedirectQuery" id="AuthzDBDRedirectQuery">AuthzDBDRedirectQuery</a> <a name="authzdbdredirectquery" id="authzdbdredirectquery">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify a query to look up a login page for the user</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthzDBDRedirectQuery <var>query</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authz_dbd</td></tr>
-</table>
- <p>Specifies an optional SQL query to use after successful login
- (or logout) to redirect the user to a URL, which may be
- specific to the user. The user's ID will be passed as a single string
- parameter when the SQL query is executed. It may be referenced within
- the query statement using a <code>%s</code> format specifier.</p>
- <pre class="prettyprint lang-config">AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s"</pre>
-
- <p>The first column value of the first row returned by the query
- statement should be a string containing a URL to which to redirect
- the client. Subsequent rows will be ignored. If no rows are returned,
- the client will not be redirected.</p>
- <p>Note that <code class="directive">AuthzDBDLoginToReferer</code> takes
- precedence if both are set.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="requiredirectives" id="requiredirectives">The Require Directives</a></h2>
</Files>
</Directory></pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthzDBDLoginToReferer" id="AuthzDBDLoginToReferer">AuthzDBDLoginToReferer</a> <a name="authzdbdlogintoreferer" id="authzdbdlogintoreferer">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines whether to redirect the Client to the Referring
+page on successful login or logout if a <code>Referer</code> request
+header is present</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthzDBDLoginToReferer On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthzDBDLoginToReferer Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authz_dbd</td></tr>
+</table>
+ <p>In conjunction with <code>Require dbd-login</code> or
+ <code>Require dbd-logout</code>, this provides the option to
+ redirect the client back to the Referring page (the URL in
+ the <code>Referer</code> HTTP request header, if present).
+ When there is no <code>Referer</code> header,
+ <code>AuthzDBDLoginToReferer On</code> will be ignored.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthzDBDQuery" id="AuthzDBDQuery">AuthzDBDQuery</a> <a name="authzdbdquery" id="authzdbdquery">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify the SQL Query for the required operation</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthzDBDQuery <var>query</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authz_dbd</td></tr>
+</table>
+ <p>The <code class="directive">AuthzDBDQuery</code> specifies an SQL
+ query to run. The purpose of the query depends on the
+ <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive in
+ effect.</p>
+ <ul>
+ <li>When used with a <code>Require dbd-group</code> directive,
+ it specifies a query to look up groups for the current user. This is
+ the standard functionality of other authorization modules such as
+ <code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> and <code class="module"><a href="../mod/mod_authz_dbm.html">mod_authz_dbm</a></code>.
+ The first column value of each row returned by the query statement
+ should be a string containing a group name. Zero, one, or more rows
+ may be returned.
+ <pre class="prettyprint lang-config">Require dbd-group
+AuthzDBDQuery "SELECT group FROM groups WHERE user = %s"</pre>
+
+ </li>
+ <li>When used with a <code>Require dbd-login</code> or
+ <code>Require dbd-logout</code> directive, it will never deny access,
+ but will instead execute a SQL statement designed to log the user
+ in or out. The user must already be authenticated with
+ <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>.
+ <pre class="prettyprint lang-config">Require dbd-login
+AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"</pre>
+
+ </li>
+ </ul>
+ <p>In all cases, the user's ID will be passed as a single string
+ parameter when the SQL query is executed. It may be referenced within
+ the query statement using a <code>%s</code> format specifier.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthzDBDRedirectQuery" id="AuthzDBDRedirectQuery">AuthzDBDRedirectQuery</a> <a name="authzdbdredirectquery" id="authzdbdredirectquery">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify a query to look up a login page for the user</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthzDBDRedirectQuery <var>query</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authz_dbd</td></tr>
+</table>
+ <p>Specifies an optional SQL query to use after successful login
+ (or logout) to redirect the user to a URL, which may be
+ specific to the user. The user's ID will be passed as a single string
+ parameter when the SQL query is executed. It may be referenced within
+ the query statement using a <code>%s</code> format specifier.</p>
+ <pre class="prettyprint lang-config">AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s"</pre>
+
+ <p>The first column value of the first row returned by the query
+ statement should be a string containing a URL to which to redirect
+ the client. Subsequent rows will be ignored. If no rows are returned,
+ the client will not be redirected.</p>
+ <p>Note that <code class="directive">AuthzDBDLoginToReferer</code> takes
+ precedence if both are set.</p>
+
</div>
</div>
<div class="bottomlang">
of the web site by group membership. Similar functionality is
provided by <code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code>.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Example usage</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#authdbmgroupfile">AuthDBMGroupFile</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authzdbmtype">AuthzDBMType</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#examples">Example usage</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="requiredirectives" id="requiredirectives">The Require Directives</a></h2>
+
+ <p>Apache's <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>
+ directives are used during the authorization phase to ensure that
+ a user is allowed to access a resource. mod_authz_dbm extends the
+ authorization types with <code>dbm-group</code>.</p>
+
+ <p>Since v2.4.8, <a href="../expr.html">expressions</a> are supported
+ within the DBM require directives.</p>
+
+<h3><a name="reqgroup" id="reqgroup">Require dbm-group</a></h3>
+
+ <p>This directive specifies group membership that is required for the
+ user to gain access.</p>
+
+ <pre class="prettyprint lang-config">Require dbm-group admin</pre>
+
+
+
+
+<h3><a name="reqfilegroup" id="reqfilegroup">Require dbm-file-group</a></h3>
+
+ <p>When this directive is specified, the user must be a member of the group
+ assigned to the file being accessed.</p>
+
+ <pre class="prettyprint lang-config">Require dbm-file-group</pre>
+
+
+
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="examples" id="examples">Example usage</a></h2>
+
+<p><em>Note that using mod_authz_dbm requires you to require <code>dbm-group</code>
+instead of <code>group</code>:</em>
+</p>
+<pre class="prettyprint lang-config"><Directory "/foo/bar">
+ AuthType Basic
+ AuthName "Secure Area"
+ AuthBasicProvider dbm
+ AuthDBMUserFile "site/data/users"
+ AuthDBMGroupFile "site/data/users"
+ Require dbm-group admin
+</Directory></pre>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthDBMGroupFile" id="AuthDBMGroupFile">AuthDBMGroupFile</a> <a name="authdbmgroupfile" id="authdbmgroupfile">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of the database file containing the list
<p>It is crucial that whatever program you use to create your group
files is configured to use the same type of database.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="requiredirectives" id="requiredirectives">The Require Directives</a></h2>
-
- <p>Apache's <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>
- directives are used during the authorization phase to ensure that
- a user is allowed to access a resource. mod_authz_dbm extends the
- authorization types with <code>dbm-group</code>.</p>
-
- <p>Since v2.4.8, <a href="../expr.html">expressions</a> are supported
- within the DBM require directives.</p>
-
-<h3><a name="reqgroup" id="reqgroup">Require dbm-group</a></h3>
-
- <p>This directive specifies group membership that is required for the
- user to gain access.</p>
-
- <pre class="prettyprint lang-config">Require dbm-group admin</pre>
-
-
-
-
-<h3><a name="reqfilegroup" id="reqfilegroup">Require dbm-file-group</a></h3>
-
- <p>When this directive is specified, the user must be a member of the group
- assigned to the file being accessed.</p>
-
- <pre class="prettyprint lang-config">Require dbm-file-group</pre>
-
-
-
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="examples" id="examples">Example usage</a></h2>
-
-<p><em>Note that using mod_authz_dbm requires you to require <code>dbm-group</code>
-instead of <code>group</code>:</em>
-</p>
-<pre class="prettyprint lang-config"><Directory "/foo/bar">
- AuthType Basic
- AuthName "Secure Area"
- AuthBasicProvider dbm
- AuthDBMUserFile "site/data/users"
- AuthDBMGroupFile "site/data/users"
- Require dbm-group admin
-</Directory></pre>
-
</div>
</div>
<div class="bottomlang">
of the web site by group membership. Similar functionality is
provided by <code class="module"><a href="../mod/mod_authz_dbm.html">mod_authz_dbm</a></code>.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#authgroupfile">AuthGroupFile</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AuthGroupFile" id="AuthGroupFile">AuthGroupFile</a> <a name="authgroupfile" id="authgroupfile">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of a text file containing the list
-of user groups for authorization</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthGroupFile <var>file-path</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authz_groupfile</td></tr>
-</table>
- <p>The <code class="directive">AuthGroupFile</code> directive sets the
- name of a textual file containing the list of user groups for user
- authorization. <var>File-path</var> is the path to the group
- file. If it is not absolute, it is treated as relative to the <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</p>
-
- <p>Each line of the group file contains a groupname followed by a
- colon, followed by the member usernames separated by spaces.</p>
-
- <div class="example"><h3>Example:</h3><p><code>
- mygroup: bob joe anne
- </code></p></div>
-
- <p>Note that searching large text files is <em>very</em>
- inefficient; <code class="directive"><a href="../mod/mod_authz_dbm.html#authdbmgroupfile">AuthDBMGroupFile</a></code> provides a much better performance.</p>
-
- <div class="warning"><h3>Security</h3>
- <p>Make sure that the <code class="directive">AuthGroupFile</code> is
- stored outside the document tree of the web-server; do <em>not</em>
- put it in the directory that it protects. Otherwise, clients may
- be able to download the <code class="directive">AuthGroupFile</code>.</p>
- </div>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="requiredirectives" id="requiredirectives">The Require Directives</a></h2>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthGroupFile" id="AuthGroupFile">AuthGroupFile</a> <a name="authgroupfile" id="authgroupfile">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of a text file containing the list
+of user groups for authorization</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthGroupFile <var>file-path</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authz_groupfile</td></tr>
+</table>
+ <p>The <code class="directive">AuthGroupFile</code> directive sets the
+ name of a textual file containing the list of user groups for user
+ authorization. <var>File-path</var> is the path to the group
+ file. If it is not absolute, it is treated as relative to the <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</p>
+
+ <p>Each line of the group file contains a groupname followed by a
+ colon, followed by the member usernames separated by spaces.</p>
+
+ <div class="example"><h3>Example:</h3><p><code>
+ mygroup: bob joe anne
+ </code></p></div>
+
+ <p>Note that searching large text files is <em>very</em>
+ inefficient; <code class="directive"><a href="../mod/mod_authz_dbm.html#authdbmgroupfile">AuthDBMGroupFile</a></code> provides a much better performance.</p>
+
+ <div class="warning"><h3>Security</h3>
+ <p>Make sure that the <code class="directive">AuthGroupFile</code> is
+ stored outside the document tree of the web-server; do <em>not</em>
+ put it in the directory that it protects. Otherwise, clients may
+ be able to download the <code class="directive">AuthGroupFile</code>.</p>
+ </div>
+
</div>
</div>
<div class="bottomlang">
leaving other methods unrestricted, by enclosing the directives
in a <code class="directive"><a href="../mod/core.html#limit"><Limit></a></code> section.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<h3>See also</h3>
<ul class="seealso">
<li><a href="../howto/auth.html">Authentication, Authorization,
and Access Control</a></li>
"MultiViews"</a> resources.</p>
</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#examples">Configuration Examples</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
directive. Alternatively <code>Require valid-user</code> can be used to
grant access to all successfully authenticated users.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
before a 1011-byte file (if in ascending order) even though
they both are shown as "1K".</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#query">Autoindex Request Query Arguments</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#addalt">AddAlt</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#addaltbyencoding">AddAltByEncoding</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#indexstylesheet">IndexStyleSheet</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#readmename">ReadmeName</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#query">Autoindex Request Query Arguments</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="query" id="query">Autoindex Request Query Arguments</a></h2>
+
+
+ <p>Various query string arguments are available to give the client
+ some control over the ordering of the directory listing, as well as
+ what files are listed. If you do not wish to give the client this
+ control, the <code><a href="#indexoptions.ignoreclient">IndexOptions
+ IgnoreClient</a></code> option disables that functionality.</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><code>C=N</code> sorts the directory by file name</li>
+
+ <li><code>C=M</code> sorts the directory by last-modified
+ date, then file name</li>
+
+ <li><code>C=S</code> sorts the directory by size, then file
+ name</li>
+
+ <li class="separate"><code>C=D</code> sorts the directory by description, then
+ file name</li>
+
+ <li><code>O=A</code> sorts the listing in Ascending
+ Order</li>
+
+ <li class="separate"><code>O=D</code> sorts the listing in Descending
+ Order</li>
+
+ <li><code>F=0</code> formats the listing as a simple list
+ (not FancyIndexed)</li>
+
+ <li><code>F=1</code> formats the listing as a FancyIndexed
+ list</li>
+
+ <li class="separate"><code>F=2</code> formats the listing as an
+ HTMLTable FancyIndexed list</li>
+
+ <li><code>V=0</code> disables version sorting</li>
+
+ <li class="separate"><code>V=1</code> enables version sorting</li>
+
+ <li><code>P=<var>pattern</var></code> lists only files matching
+ the given <var>pattern</var></li>
+ </ul>
+
+ <p>Note that the 'P'attern query argument is tested
+ <em>after</em> the usual <code class="directive"><a href="#indexignore">IndexIgnore</a></code> directives are processed,
+ and all file names are still subjected to the same criteria as
+ any other autoindex listing. The Query Arguments parser in
+ <code class="module"><a href="../mod/mod_autoindex.html">mod_autoindex</a></code> 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>
+
+ <div class="example"><p><code>
+ <form action="" method="get"><br />
+ <span class="indent">
+ Show me a <select name="F"><br />
+ <span class="indent">
+ <option value="0"> Plain list</option><br />
+ <option value="1" selected="selected"> Fancy list</option><br />
+ <option value="2"> Table list</option><br />
+ </span>
+ </select><br />
+ Sorted by <select name="C"><br />
+ <span class="indent">
+ <option value="N" selected="selected"> Name</option><br />
+ <option value="M"> Date Modified</option><br />
+ <option value="S"> Size</option><br />
+ <option value="D"> Description</option><br />
+ </span>
+ </select><br />
+ <select name="O"><br />
+ <span class="indent">
+ <option value="A" selected="selected"> Ascending</option><br />
+ <option value="D"> Descending</option><br />
+ </span>
+ </select><br />
+ <select name="V"><br />
+ <span class="indent">
+ <option value="0" selected="selected"> in Normal order</option><br />
+ <option value="1"> in Version order</option><br />
+ </span>
+ </select><br />
+ Matching <input type="text" name="P" value="*" /><br />
+ <input type="submit" name="X" value="Go" /><br />
+ </span>
+ </form>
+ </code></p></div>
+
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AddAlt" id="AddAlt">AddAlt</a> <a name="addalt" id="addalt">Directive</a></h2>
<table class="directive">
<p>See also <code class="directive"><a href="#headername">HeaderName</a></code>, where this behavior is described in greater
detail.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="query" id="query">Autoindex Request Query Arguments</a></h2>
-
-
- <p>Various query string arguments are available to give the client
- some control over the ordering of the directory listing, as well as
- what files are listed. If you do not wish to give the client this
- control, the <code><a href="#indexoptions.ignoreclient">IndexOptions
- IgnoreClient</a></code> option disables that functionality.</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><code>C=N</code> sorts the directory by file name</li>
-
- <li><code>C=M</code> sorts the directory by last-modified
- date, then file name</li>
-
- <li><code>C=S</code> sorts the directory by size, then file
- name</li>
-
- <li class="separate"><code>C=D</code> sorts the directory by description, then
- file name</li>
-
- <li><code>O=A</code> sorts the listing in Ascending
- Order</li>
-
- <li class="separate"><code>O=D</code> sorts the listing in Descending
- Order</li>
-
- <li><code>F=0</code> formats the listing as a simple list
- (not FancyIndexed)</li>
-
- <li><code>F=1</code> formats the listing as a FancyIndexed
- list</li>
-
- <li class="separate"><code>F=2</code> formats the listing as an
- HTMLTable FancyIndexed list</li>
-
- <li><code>V=0</code> disables version sorting</li>
-
- <li class="separate"><code>V=1</code> enables version sorting</li>
-
- <li><code>P=<var>pattern</var></code> lists only files matching
- the given <var>pattern</var></li>
- </ul>
-
- <p>Note that the 'P'attern query argument is tested
- <em>after</em> the usual <code class="directive"><a href="#indexignore">IndexIgnore</a></code> directives are processed,
- and all file names are still subjected to the same criteria as
- any other autoindex listing. The Query Arguments parser in
- <code class="module"><a href="../mod/mod_autoindex.html">mod_autoindex</a></code> 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>
-
- <div class="example"><p><code>
- <form action="" method="get"><br />
- <span class="indent">
- Show me a <select name="F"><br />
- <span class="indent">
- <option value="0"> Plain list</option><br />
- <option value="1" selected="selected"> Fancy list</option><br />
- <option value="2"> Table list</option><br />
- </span>
- </select><br />
- Sorted by <select name="C"><br />
- <span class="indent">
- <option value="N" selected="selected"> Name</option><br />
- <option value="M"> Date Modified</option><br />
- <option value="S"> Size</option><br />
- <option value="D"> Description</option><br />
- </span>
- </select><br />
- <select name="O"><br />
- <span class="indent">
- <option value="A" selected="selected"> Ascending</option><br />
- <option value="D"> Descending</option><br />
- </span>
- </select><br />
- <select name="V"><br />
- <span class="indent">
- <option value="0" selected="selected"> in Normal order</option><br />
- <option value="1"> in Version order</option><br />
- </span>
- </select><br />
- Matching <input type="text" name="P" value="*" /><br />
- <input type="submit" name="X" value="Go" /><br />
- </span>
- </form>
- </code></p></div>
-
</div>
</div>
<div class="bottomlang">
<ul class="seealso">
<li><a href="../filter.html">Filters</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="BufferSize" id="BufferSize">BufferSize</a> <a name="buffersize" id="buffersize">Directive</a></h2>
<table class="directive">
The default is 128 kilobytes.</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_buffer.html" title="English"> en </a> |
<p>Further details, discussion, and examples, are provided in the
<a href="../caching.html">Caching Guide</a>.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#related">Related Modules and Directives</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#sampleconf">Sample Configuration</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#thunderingherd">Avoiding the Thundering Herd</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#finecontrol">Fine Control with the CACHE Filter</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#status">Cache Status and Logging</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#cachedefaultexpire">CacheDefaultExpire</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cachedetailheader">CacheDetailHeader</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cachestorenostore">CacheStoreNoStore</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cachestoreprivate">CacheStorePrivate</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#related">Related Modules and Directives</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#sampleconf">Sample Configuration</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#thunderingherd">Avoiding the Thundering Herd</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#finecontrol">Fine Control with the CACHE Filter</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#status">Cache Status and Logging</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><a href="../caching.html">Caching Guide</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="related" id="related">Related Modules and Directives</a></h2>
+ <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="../mod/mod_cache_disk.html">mod_cache_disk</a></code></li><li><code class="module"><a href="../mod/mod_cache_socache.html">mod_cache_socache</a></code></li></ul></td><td><ul><li><code class="directive"><a href="../mod/mod_cache_disk.html#cacheroot">CacheRoot</a></code></li><li><code class="directive"><a href="../mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code></li><li><code class="directive"><a href="../mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code></li><li><code class="directive"><a href="../mod/mod_cache_disk.html#cacheminfilesize">CacheMinFileSize</a></code></li><li><code class="directive"><a href="../mod/mod_cache_disk.html#cachemaxfilesize">CacheMaxFileSize</a></code></li><li><code class="directive"><a href="../mod/mod_cache_socache.html#cachesocache">CacheSocache</a></code></li><li><code class="directive"><a href="../mod/mod_cache_socache.html#cachesocachemaxtime">CacheSocacheMaxTime</a></code></li><li><code class="directive"><a href="../mod/mod_cache_socache.html#cachesocachemintime">CacheSocacheMinTime</a></code></li><li><code class="directive"><a href="../mod/mod_cache_socache.html#cachesocachemaxsize">CacheSocacheMaxSize</a></code></li><li><code class="directive"><a href="../mod/mod_cache_socache.html#cachesocachereadsize">CacheSocacheReadSize</a></code></li><li><code class="directive"><a href="../mod/mod_cache_socache.html#cachesocachereadtime">CacheSocacheReadTime</a></code></li></ul></td></tr></table>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="sampleconf" id="sampleconf">Sample Configuration</a></h2>
+ <div class="example"><h3>Sample httpd.conf</h3><pre class="prettyprint lang-config">#
+# Sample Cache Configuration
+#
+LoadModule cache_module modules/mod_cache.so
+<IfModule mod_cache.c>
+ LoadModule cache_disk_module modules/mod_cache_disk.so
+ <IfModule mod_cache_disk.c>
+ CacheRoot "c:/cacheroot"
+ CacheEnable disk "/"
+ CacheDirLevels 5
+ CacheDirLength 3
+ </IfModule>
+
+ # When acting as a proxy, don't cache the list of security updates
+ CacheDisable "http://security.update.server/update-list/"
+</IfModule></pre>
+</div>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="thunderingherd" id="thunderingherd">Avoiding the Thundering Herd</a></h2>
+ <p>When a cached entry becomes stale, <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code> will submit
+ a conditional request to the backend, which is expected to confirm whether the
+ cached entry is still fresh, and send an updated entity if not.</p>
+ <p>A small but finite amount of time exists between the time the cached entity
+ becomes stale, and the time the stale entity is fully refreshed. On a busy
+ server, a significant number of requests might arrive during this time, and
+ cause a <strong>thundering herd</strong> of requests to strike the backend
+ suddenly and unpredictably.</p>
+ <p>To keep the thundering herd at bay, the <code class="directive">CacheLock</code>
+ directive can be used to define a directory in which locks are created for
+ URLs <strong>in flight</strong>. The lock is used as a <strong>hint</strong>
+ by other requests to either suppress an attempt to cache (someone else has
+ gone to fetch the entity), or to indicate that a stale entry is being refreshed
+ (stale content will be returned in the mean time).
+ </p>
+ <h3>Initial caching of an entry</h3>
+
+ <p>When an entity is cached for the first time, a lock will be created for the
+ entity until the response has been fully cached. During the lifetime of the
+ lock, the cache will suppress the second and subsequent attempt to cache the
+ same entity. While this doesn't hold back the thundering herd, it does stop
+ the cache attempting to cache the same entity multiple times simultaneously.
+ </p>
+
+ <h3>Refreshment of a stale entry</h3>
+
+ <p>When an entity reaches its freshness lifetime and becomes stale, a lock
+ will be created for the entity until the response has either been confirmed as
+ still fresh, or replaced by the backend. During the lifetime of the lock, the
+ second and subsequent incoming request will cause stale data to be returned,
+ and the thundering herd is kept at bay.</p>
+
+ <h3>Locks and Cache-Control: no-cache</h3>
+
+ <p>Locks are used as a <strong>hint only</strong> to enable the cache to be
+ more gentle on backend servers, however the lock can be overridden if necessary.
+ If the client sends a request with a Cache-Control header forcing a reload, any
+ lock that may be present will be ignored, and the client's request will be
+ honored immediately and the cached entry refreshed.</p>
+ <p>As a further safety mechanism, locks have a configurable maximum age.
+ Once this age has been reached, the lock is removed, and a new request is
+ given the opportunity to create a new lock. This maximum age can be set using
+ the <code class="directive">CacheLockMaxAge</code> directive, and defaults to 5
+ seconds.
+ </p>
+
+ <h3>Example configuration</h3>
+
+ <div class="example"><h3>Enabling the cache lock</h3><pre class="prettyprint lang-config">#
+# Enable the cache lock
+#
+<IfModule mod_cache.c>
+ CacheLock on
+ CacheLockPath "/tmp/mod_cache-lock"
+ CacheLockMaxAge 5
+</IfModule></pre>
+</div>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="finecontrol" id="finecontrol">Fine Control with the CACHE Filter</a></h2>
+ <p>Under the default mode of cache operation, the cache runs as a quick handler,
+ short circuiting the majority of server processing and offering the highest
+ cache performance available.</p>
+
+ <p>In this mode, the cache <strong>bolts onto</strong> the front of the server,
+ acting as if a free standing RFC 2616 caching proxy had been placed in front of
+ the server.</p>
+
+ <p>While this mode offers the best performance, the administrator may find that
+ under certain circumstances they may want to perform further processing on the
+ request after the request is cached, such as to inject personalisation into the
+ cached page, or to apply authorisation restrictions to the content. Under these
+ circumstances, an administrator is often forced to place independent reverse
+ proxy servers either behind or in front of the caching server to achieve this.</p>
+
+ <p>To solve this problem the <code class="directive"><a href="#cachequickhandler">CacheQuickHandler
+ </a></code> directive can be set to <strong>off</strong>, and the server will
+ process all phases normally handled by a non-cached request, including the
+ <strong>authentication and authorisation</strong> phases.</p>
+
+ <p>In addition, the administrator may optionally specify the <strong>precise point
+ within the filter chain</strong> where caching is to take place by adding the
+ <strong>CACHE</strong> filter to the output filter chain.</p>
+
+ <p>For example, to cache content before applying compression to the response,
+ place the <strong>CACHE</strong> filter before the <strong>DEFLATE</strong>
+ filter as in the example below:</p>
+
+ <pre class="prettyprint lang-config"># Cache content before optional compression
+CacheQuickHandler off
+AddOutputFilterByType CACHE;DEFLATE text/plain</pre>
+
+
+ <p>Another option is to have content cached before personalisation is applied
+ by <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> (or another content processing filter). In this
+ example templates containing tags understood by
+ <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> are cached before being parsed:</p>
+
+ <pre class="prettyprint lang-config"># Cache content before mod_include and mod_deflate
+CacheQuickHandler off
+AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html</pre>
+
+
+ <p>You may place the <strong>CACHE</strong> filter anywhere you wish within the
+ filter chain. In this example, content is cached after being parsed by
+ <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>, but before being processed by
+ <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code>:</p>
+
+ <pre class="prettyprint lang-config"># Cache content between mod_include and mod_deflate
+CacheQuickHandler off
+AddOutputFilterByType INCLUDES;CACHE;DEFLATE text/html</pre>
+
+
+ <div class="warning"><h3>Warning:</h3>If the location of the
+ <strong>CACHE</strong> filter in the filter chain is changed for any reason,
+ you may need to <strong>flush your cache</strong> to ensure that your data
+ served remains consistent. <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code> is not in a position
+ to enforce this for you.</div>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="status" id="status">Cache Status and Logging</a></h2>
+ <p>Once <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code> has made a decision as to whether or not
+ an entity is to be served from cache, the detailed reason for the decision
+ is written to the subprocess environment within the request under the
+ <strong>cache-status</strong> key. This reason can be logged by the
+ <code class="directive"><a href="../mod/mod_log_config.html#logformat">LogFormat</a></code> directive as
+ follows:</p>
+
+ <pre class="prettyprint lang-config">LogFormat "%{cache-status}e ..."</pre>
+
+
+ <p>Based on the caching decision made, the reason is also written to the
+ subprocess environment under one the following four keys, as appropriate:</p>
+
+ <dl>
+ <dt>cache-hit</dt><dd>The response was served from cache.</dd>
+ <dt>cache-revalidate</dt><dd>The response was stale and was successfully
+ revalidated, then served from cache.</dd>
+ <dt>cache-miss</dt><dd>The response was served from the upstream server.</dd>
+ <dt>cache-invalidate</dt><dd>The cached entity was invalidated by a request
+ method other than GET or HEAD.</dd>
+ </dl>
+
+ <p>This makes it possible to support conditional logging of cached requests
+ as per the following example:</p>
+
+ <pre class="prettyprint lang-config">CustomLog "cached-requests.log" common env=cache-hit
+CustomLog "uncached-requests.log" common env=cache-miss
+CustomLog "revalidated-requests.log" common env=cache-revalidate
+CustomLog "invalidated-requests.log" common env=cache-invalidate</pre>
+
+
+ <p>For module authors, a hook called <var>cache_status</var> is available,
+ allowing modules to respond to the caching outcomes above in customised
+ ways.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CacheDefaultExpire" id="CacheDefaultExpire">CacheDefaultExpire</a> <a name="cachedefaultexpire" id="cachedefaultexpire">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The default duration to cache a document when no expiry date is specified.</td></tr>
<li><code class="directive"><a href="#cachestorenostore">CacheStoreNoStore</a></code></li>
</ul>
</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="related" id="related">Related Modules and Directives</a></h2>
- <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="../mod/mod_cache_disk.html">mod_cache_disk</a></code></li><li><code class="module"><a href="../mod/mod_cache_socache.html">mod_cache_socache</a></code></li></ul></td><td><ul><li><code class="directive"><a href="../mod/mod_cache_disk.html#cacheroot">CacheRoot</a></code></li><li><code class="directive"><a href="../mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code></li><li><code class="directive"><a href="../mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code></li><li><code class="directive"><a href="../mod/mod_cache_disk.html#cacheminfilesize">CacheMinFileSize</a></code></li><li><code class="directive"><a href="../mod/mod_cache_disk.html#cachemaxfilesize">CacheMaxFileSize</a></code></li><li><code class="directive"><a href="../mod/mod_cache_socache.html#cachesocache">CacheSocache</a></code></li><li><code class="directive"><a href="../mod/mod_cache_socache.html#cachesocachemaxtime">CacheSocacheMaxTime</a></code></li><li><code class="directive"><a href="../mod/mod_cache_socache.html#cachesocachemintime">CacheSocacheMinTime</a></code></li><li><code class="directive"><a href="../mod/mod_cache_socache.html#cachesocachemaxsize">CacheSocacheMaxSize</a></code></li><li><code class="directive"><a href="../mod/mod_cache_socache.html#cachesocachereadsize">CacheSocacheReadSize</a></code></li><li><code class="directive"><a href="../mod/mod_cache_socache.html#cachesocachereadtime">CacheSocacheReadTime</a></code></li></ul></td></tr></table>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="sampleconf" id="sampleconf">Sample Configuration</a></h2>
- <div class="example"><h3>Sample httpd.conf</h3><pre class="prettyprint lang-config">#
-# Sample Cache Configuration
-#
-LoadModule cache_module modules/mod_cache.so
-<IfModule mod_cache.c>
- LoadModule cache_disk_module modules/mod_cache_disk.so
- <IfModule mod_cache_disk.c>
- CacheRoot "c:/cacheroot"
- CacheEnable disk "/"
- CacheDirLevels 5
- CacheDirLength 3
- </IfModule>
-
- # When acting as a proxy, don't cache the list of security updates
- CacheDisable "http://security.update.server/update-list/"
-</IfModule></pre>
-</div>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="thunderingherd" id="thunderingherd">Avoiding the Thundering Herd</a></h2>
- <p>When a cached entry becomes stale, <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code> will submit
- a conditional request to the backend, which is expected to confirm whether the
- cached entry is still fresh, and send an updated entity if not.</p>
- <p>A small but finite amount of time exists between the time the cached entity
- becomes stale, and the time the stale entity is fully refreshed. On a busy
- server, a significant number of requests might arrive during this time, and
- cause a <strong>thundering herd</strong> of requests to strike the backend
- suddenly and unpredictably.</p>
- <p>To keep the thundering herd at bay, the <code class="directive">CacheLock</code>
- directive can be used to define a directory in which locks are created for
- URLs <strong>in flight</strong>. The lock is used as a <strong>hint</strong>
- by other requests to either suppress an attempt to cache (someone else has
- gone to fetch the entity), or to indicate that a stale entry is being refreshed
- (stale content will be returned in the mean time).
- </p>
- <h3>Initial caching of an entry</h3>
-
- <p>When an entity is cached for the first time, a lock will be created for the
- entity until the response has been fully cached. During the lifetime of the
- lock, the cache will suppress the second and subsequent attempt to cache the
- same entity. While this doesn't hold back the thundering herd, it does stop
- the cache attempting to cache the same entity multiple times simultaneously.
- </p>
-
- <h3>Refreshment of a stale entry</h3>
-
- <p>When an entity reaches its freshness lifetime and becomes stale, a lock
- will be created for the entity until the response has either been confirmed as
- still fresh, or replaced by the backend. During the lifetime of the lock, the
- second and subsequent incoming request will cause stale data to be returned,
- and the thundering herd is kept at bay.</p>
-
- <h3>Locks and Cache-Control: no-cache</h3>
-
- <p>Locks are used as a <strong>hint only</strong> to enable the cache to be
- more gentle on backend servers, however the lock can be overridden if necessary.
- If the client sends a request with a Cache-Control header forcing a reload, any
- lock that may be present will be ignored, and the client's request will be
- honored immediately and the cached entry refreshed.</p>
- <p>As a further safety mechanism, locks have a configurable maximum age.
- Once this age has been reached, the lock is removed, and a new request is
- given the opportunity to create a new lock. This maximum age can be set using
- the <code class="directive">CacheLockMaxAge</code> directive, and defaults to 5
- seconds.
- </p>
-
- <h3>Example configuration</h3>
-
- <div class="example"><h3>Enabling the cache lock</h3><pre class="prettyprint lang-config">#
-# Enable the cache lock
-#
-<IfModule mod_cache.c>
- CacheLock on
- CacheLockPath "/tmp/mod_cache-lock"
- CacheLockMaxAge 5
-</IfModule></pre>
-</div>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="finecontrol" id="finecontrol">Fine Control with the CACHE Filter</a></h2>
- <p>Under the default mode of cache operation, the cache runs as a quick handler,
- short circuiting the majority of server processing and offering the highest
- cache performance available.</p>
-
- <p>In this mode, the cache <strong>bolts onto</strong> the front of the server,
- acting as if a free standing RFC 2616 caching proxy had been placed in front of
- the server.</p>
-
- <p>While this mode offers the best performance, the administrator may find that
- under certain circumstances they may want to perform further processing on the
- request after the request is cached, such as to inject personalisation into the
- cached page, or to apply authorisation restrictions to the content. Under these
- circumstances, an administrator is often forced to place independent reverse
- proxy servers either behind or in front of the caching server to achieve this.</p>
-
- <p>To solve this problem the <code class="directive"><a href="#cachequickhandler">CacheQuickHandler
- </a></code> directive can be set to <strong>off</strong>, and the server will
- process all phases normally handled by a non-cached request, including the
- <strong>authentication and authorisation</strong> phases.</p>
-
- <p>In addition, the administrator may optionally specify the <strong>precise point
- within the filter chain</strong> where caching is to take place by adding the
- <strong>CACHE</strong> filter to the output filter chain.</p>
-
- <p>For example, to cache content before applying compression to the response,
- place the <strong>CACHE</strong> filter before the <strong>DEFLATE</strong>
- filter as in the example below:</p>
-
- <pre class="prettyprint lang-config"># Cache content before optional compression
-CacheQuickHandler off
-AddOutputFilterByType CACHE;DEFLATE text/plain</pre>
-
-
- <p>Another option is to have content cached before personalisation is applied
- by <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> (or another content processing filter). In this
- example templates containing tags understood by
- <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> are cached before being parsed:</p>
-
- <pre class="prettyprint lang-config"># Cache content before mod_include and mod_deflate
-CacheQuickHandler off
-AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html</pre>
-
-
- <p>You may place the <strong>CACHE</strong> filter anywhere you wish within the
- filter chain. In this example, content is cached after being parsed by
- <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>, but before being processed by
- <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code>:</p>
-
- <pre class="prettyprint lang-config"># Cache content between mod_include and mod_deflate
-CacheQuickHandler off
-AddOutputFilterByType INCLUDES;CACHE;DEFLATE text/html</pre>
-
-
- <div class="warning"><h3>Warning:</h3>If the location of the
- <strong>CACHE</strong> filter in the filter chain is changed for any reason,
- you may need to <strong>flush your cache</strong> to ensure that your data
- served remains consistent. <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code> is not in a position
- to enforce this for you.</div>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="status" id="status">Cache Status and Logging</a></h2>
- <p>Once <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code> has made a decision as to whether or not
- an entity is to be served from cache, the detailed reason for the decision
- is written to the subprocess environment within the request under the
- <strong>cache-status</strong> key. This reason can be logged by the
- <code class="directive"><a href="../mod/mod_log_config.html#logformat">LogFormat</a></code> directive as
- follows:</p>
-
- <pre class="prettyprint lang-config">LogFormat "%{cache-status}e ..."</pre>
-
-
- <p>Based on the caching decision made, the reason is also written to the
- subprocess environment under one the following four keys, as appropriate:</p>
-
- <dl>
- <dt>cache-hit</dt><dd>The response was served from cache.</dd>
- <dt>cache-revalidate</dt><dd>The response was stale and was successfully
- revalidated, then served from cache.</dd>
- <dt>cache-miss</dt><dd>The response was served from the upstream server.</dd>
- <dt>cache-invalidate</dt><dd>The cached entity was invalidated by a request
- method other than GET or HEAD.</dd>
- </dl>
-
- <p>This makes it possible to support conditional logging of cached requests
- as per the following example:</p>
-
- <pre class="prettyprint lang-config">CustomLog "cached-requests.log" common env=cache-hit
-CustomLog "uncached-requests.log" common env=cache-miss
-CustomLog "revalidated-requests.log" common env=cache-revalidate
-CustomLog "invalidated-requests.log" common env=cache-invalidate</pre>
-
-
- <p>For module authors, a hook called <var>cache_status</var> is available,
- allowing modules to respond to the caching outcomes above in customised
- ways.</p>
-</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_cache.html" title="English"> en </a> |
<li><code class="module"><a href="../mod/mod_cache_socache.html">mod_cache_socache</a></code></li>
<li><a href="../caching.html">Caching Guide</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CacheDirLength" id="CacheDirLength">CacheDirLength</a> <a name="cachedirlength" id="cachedirlength">Directive</a></h2>
<table class="directive">
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_cache_disk.html" title="English"> en </a> |
<li><code class="module"><a href="../mod/mod_cache_disk.html">mod_cache_disk</a></code></li>
<li><a href="../caching.html">Caching Guide</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CacheSocache" id="CacheSocache">CacheSocache</a> <a name="cachesocache" id="cachesocache">Directive</a></h2>
<table class="directive">
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_cache_socache.html" title="English"> en </a> |
<li><code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code></li>
<li><code class="module"><a href="../mod/mod_asis.html">mod_asis</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="MetaDir" id="MetaDir">MetaDir</a> <a name="metadir" id="metadir">Directive</a></h2>
<table class="directive">
</div>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_cern_meta.html" title="English"> en </a> |
for any file with the mime-type <code>application/x-httpd-cgi</code>. The
use of the magic mime-type is deprecated.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#env">CGI Environment variables</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#cgi-debug">CGI Debugging</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#scriptlog">ScriptLog</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#scriptlogbuffer">ScriptLogBuffer</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#scriptloglength">ScriptLogLength</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#env">CGI Environment variables</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#cgi-debug">CGI Debugging</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/core.html#acceptpathinfo">AcceptPathInfo</a></code></li>
<li><code class="directive"><a href="../mod/core.html#options">Options</a></code> ExecCGI</li>
<li><a href="http://www.ietf.org/rfc/rfc3875">CGI Specification</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ScriptLog" id="ScriptLog">ScriptLog</a> <a name="scriptlog" id="scriptlog">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Location of the CGI script error logfile</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ScriptLog <var>file-path</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td><code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, <code class="module"><a href="../mod/mod_cgid.html">mod_cgid</a></code></td></tr>
-</table>
- <p>The <code class="directive">ScriptLog</code> directive sets the CGI
- script error logfile. If no <code class="directive">ScriptLog</code> 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 <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.
- </p>
-
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ScriptLog logs/cgi_log</pre>
-</div>
-
- <p>This log will be opened as the user the child processes run
- as, <em>i.e.</em> the user specified in the main <code class="directive"><a href="../mod/mod_unixd.html#user">User</a></code> 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>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ScriptLogBuffer" id="ScriptLogBuffer">ScriptLogBuffer</a> <a name="scriptlogbuffer" id="scriptlogbuffer">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum amount of PUT or POST requests that will be recorded
-in the scriptlog</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ScriptLogBuffer <var>bytes</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ScriptLogBuffer 1024</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td><code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, <code class="module"><a href="../mod/mod_cgid.html">mod_cgid</a></code></td></tr>
-</table>
- <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.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ScriptLogLength" id="ScriptLogLength">ScriptLogLength</a> <a name="scriptloglength" id="scriptloglength">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Size limit of the CGI script logfile</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ScriptLogLength <var>bytes</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ScriptLogLength 10385760</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td><code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, <code class="module"><a href="../mod/mod_cgid.html">mod_cgid</a></code></td></tr>
-</table>
- <p><code class="directive">ScriptLogLength</code> 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>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="env" id="env">CGI Environment variables</a></h2>
<p>The server will set the CGI environment variables as described
<p>(The %stdout and %stderr parts may be missing if the script did
not output anything on standard output or standard error).</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ScriptLog" id="ScriptLog">ScriptLog</a> <a name="scriptlog" id="scriptlog">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Location of the CGI script error logfile</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ScriptLog <var>file-path</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td><code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, <code class="module"><a href="../mod/mod_cgid.html">mod_cgid</a></code></td></tr>
+</table>
+ <p>The <code class="directive">ScriptLog</code> directive sets the CGI
+ script error logfile. If no <code class="directive">ScriptLog</code> 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 <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.
+ </p>
+
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ScriptLog logs/cgi_log</pre>
+</div>
+
+ <p>This log will be opened as the user the child processes run
+ as, <em>i.e.</em> the user specified in the main <code class="directive"><a href="../mod/mod_unixd.html#user">User</a></code> 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>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ScriptLogBuffer" id="ScriptLogBuffer">ScriptLogBuffer</a> <a name="scriptlogbuffer" id="scriptlogbuffer">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum amount of PUT or POST requests that will be recorded
+in the scriptlog</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ScriptLogBuffer <var>bytes</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ScriptLogBuffer 1024</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td><code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, <code class="module"><a href="../mod/mod_cgid.html">mod_cgid</a></code></td></tr>
+</table>
+ <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.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ScriptLogLength" id="ScriptLogLength">ScriptLogLength</a> <a name="scriptloglength" id="scriptloglength">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Size limit of the CGI script logfile</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ScriptLogLength <var>bytes</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ScriptLogLength 10385760</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td><code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, <code class="module"><a href="../mod/mod_cgid.html">mod_cgid</a></code></td></tr>
+</table>
+ <p><code class="directive">ScriptLogLength</code> 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>
+
</div>
</div>
<div class="bottomlang">
<li><a href="../suexec.html">Running CGI programs under different
user IDs</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CGIDScriptTimeout" id="CGIDScriptTimeout">CGIDScriptTimeout</a> <a name="cgidscripttimeout" id="cgidscripttimeout">Directive</a></h2>
<table class="directive">
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_cgid.html" title="English"> en </a> |
mechanisms implemented by Russian Apache and its associated
<code>mod_charset</code>.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#problems">Common Problems</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#charsetdefault">CharsetDefault</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#charsetoptions">CharsetOptions</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#charsetsourceenc">CharsetSourceEnc</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#problems">Common Problems</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="problems" id="problems">Common Problems</a></h2>
+
+ <h3>Invalid character set names</h3>
+
+ <p>The character set name parameters of <code class="directive"><a href="#charsetsourceenc">CharsetSourceEnc</a></code> and
+ <code class="directive"><a href="#charsetdefault">CharsetDefault</a></code>
+ must be acceptable to the translation mechanism used by
+ <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a> on the system where
+ <code class="module"><a href="../mod/mod_charset_lite.html">mod_charset_lite</a></code> 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>
+
+ <div class="example"><p><code>
+ iconv -f charsetsourceenc-value -t charsetdefault-value
+ </code></p></div>
+
+
+ <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>
+
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CharsetDefault" id="CharsetDefault">CharsetDefault</a> <a name="charsetdefault" id="charsetdefault">Directive</a></h2>
<table class="directive">
</div>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="problems" id="problems">Common Problems</a></h2>
-
- <h3>Invalid character set names</h3>
-
- <p>The character set name parameters of <code class="directive"><a href="#charsetsourceenc">CharsetSourceEnc</a></code> and
- <code class="directive"><a href="#charsetdefault">CharsetDefault</a></code>
- must be acceptable to the translation mechanism used by
- <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a> on the system where
- <code class="module"><a href="../mod/mod_charset_lite.html">mod_charset_lite</a></code> 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>
-
- <div class="example"><p><code>
- iconv -f charsetsourceenc-value -t charsetdefault-value
- </code></p></div>
-
-
- <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>
-
</div>
</div>
<div class="bottomlang">
copying, and deleting resources and collections on a remote web
server.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#example">Enabling WebDAV</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#security">Security Issues</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#complex">Complex Configurations</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#dav">Dav</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#davdepthinfinity">DavDepthInfinity</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#davmintimeout">DavMinTimeout</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#example">Enabling WebDAV</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#security">Security Issues</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#complex">Complex Configurations</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/mod_dav_fs.html#davlockdb">DavLockDB</a></code></li>
<li><code class="directive"><a href="../mod/core.html#limitxmlrequestbody">LimitXMLRequestBody</a></code></li>
<li><a href="http://www.webdav.org">WebDAV Resources</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="Dav" id="Dav">Dav</a> <a name="dav" id="dav">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable WebDAV HTTP methods</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Dav On|Off|<var>provider-name</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Dav Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dav</td></tr>
-</table>
- <p>Use the <code class="directive">Dav</code> directive to enable the
- WebDAV HTTP methods for the given container:</p>
-
- <pre class="prettyprint lang-config"><Location "/foo">
- Dav On
-</Location></pre>
-
-
- <p>The value <code>On</code> is actually an alias for the default
- provider <code>filesystem</code> which is served by the <code class="module"><a href="../mod/mod_dav_fs.html">mod_dav_fs</a></code> module. Note, that once you have DAV enabled
- for some location, it <em>cannot</em> be disabled for sublocations.
- For a complete configuration example have a look at the <a href="#example">section above</a>.</p>
-
- <div class="warning">
- Do not enable WebDAV until you have secured your server. Otherwise
- everyone will be able to distribute files on your system.
- </div>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="DavDepthInfinity" id="DavDepthInfinity">DavDepthInfinity</a> <a name="davdepthinfinity" id="davdepthinfinity">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Allow PROPFIND, Depth: Infinity requests</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DavDepthInfinity on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DavDepthInfinity off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dav</td></tr>
-</table>
- <p>Use the <code class="directive">DavDepthInfinity</code> directive to
- allow the processing of <code>PROPFIND</code> 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>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="DavMinTimeout" id="DavMinTimeout">DavMinTimeout</a> <a name="davmintimeout" id="davmintimeout">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Minimum amount of time the server holds a lock on
-a DAV resource</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DavMinTimeout <var>seconds</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DavMinTimeout 0</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dav</td></tr>
-</table>
- <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 class="directive">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 class="directive">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>
-
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"><Location "/MSWord">
- DavMinTimeout 600
-</Location></pre>
-</div>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="example" id="example">Enabling WebDAV</a></h2>
<p>To enable <code class="module"><a href="../mod/mod_dav.html">mod_dav</a></code>, add the following to a
used to access the output of the PHP scripts, and
<code>http://example.com/php-source</code> can be used with a DAV
client to manipulate them.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="Dav" id="Dav">Dav</a> <a name="dav" id="dav">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable WebDAV HTTP methods</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Dav On|Off|<var>provider-name</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Dav Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dav</td></tr>
+</table>
+ <p>Use the <code class="directive">Dav</code> directive to enable the
+ WebDAV HTTP methods for the given container:</p>
+
+ <pre class="prettyprint lang-config"><Location "/foo">
+ Dav On
+</Location></pre>
+
+
+ <p>The value <code>On</code> is actually an alias for the default
+ provider <code>filesystem</code> which is served by the <code class="module"><a href="../mod/mod_dav_fs.html">mod_dav_fs</a></code> module. Note, that once you have DAV enabled
+ for some location, it <em>cannot</em> be disabled for sublocations.
+ For a complete configuration example have a look at the <a href="#example">section above</a>.</p>
+
+ <div class="warning">
+ Do not enable WebDAV until you have secured your server. Otherwise
+ everyone will be able to distribute files on your system.
+ </div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="DavDepthInfinity" id="DavDepthInfinity">DavDepthInfinity</a> <a name="davdepthinfinity" id="davdepthinfinity">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Allow PROPFIND, Depth: Infinity requests</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DavDepthInfinity on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DavDepthInfinity off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dav</td></tr>
+</table>
+ <p>Use the <code class="directive">DavDepthInfinity</code> directive to
+ allow the processing of <code>PROPFIND</code> 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>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="DavMinTimeout" id="DavMinTimeout">DavMinTimeout</a> <a name="davmintimeout" id="davmintimeout">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Minimum amount of time the server holds a lock on
+a DAV resource</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DavMinTimeout <var>seconds</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DavMinTimeout 0</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dav</td></tr>
+</table>
+ <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 class="directive">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 class="directive">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>
+
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"><Location "/MSWord">
+ DavMinTimeout 600
+</Location></pre>
+</div>
+
</div>
</div>
<div class="bottomlang">
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_dav.html">mod_dav</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="DavLockDB" id="DavLockDB">DavLockDB</a> <a name="davlockdb" id="davlockdb">Directive</a></h2>
<table class="directive">
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_dav_fs.html" title="English"> en </a> |
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_dav.html">mod_dav</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="DavGenericLockDB" id="DavGenericLockDB">DavGenericLockDB</a> <a name="davgenericlockdb" id="davgenericlockdb">Directive</a></h2>
<table class="directive">
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_dav_lock.html" title="English"> en </a> |
by its original developer.
</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#pooling">Connection Pooling</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#API">Apache DBD API</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#prepared">SQL Prepared Statements</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#security">SECURITY WARNING</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#dbdexptime">DBDExptime</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#dbdinitsql">DBDInitSQL</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#dbdpreparesql">DBDPrepareSQL</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#dbdriver">DBDriver</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#pooling">Connection Pooling</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#API">Apache DBD API</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#prepared">SQL Prepared Statements</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#security">SECURITY WARNING</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><a href="../misc/password_encryptions.html">Password Formats</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="pooling" id="pooling">Connection Pooling</a></h2>
+ <p>This module manages database connections, in a manner
+ optimised for the platform. On non-threaded platforms,
+ it provides a persistent connection in the manner of
+ classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python).
+ On threaded platform, it provides an altogether more
+ scalable and efficient <em>connection pool</em>, as
+ described in <a href="http://www.apachetutor.org/dev/reslist">this
+ article at ApacheTutor</a>. Note that <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>
+ supersedes the modules presented in that article.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="API" id="API">Apache DBD API</a></h2>
+ <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> exports five functions for other modules
+ to use. The API is as follows:</p>
+
+<pre class="prettyprint lang-c">typedef struct {
+ apr_dbd_t *handle;
+ apr_dbd_driver_t *driver;
+ apr_hash_t *prepared;
+} ap_dbd_t;
+
+/* Export functions to access the database */
+
+/* acquire a connection that MUST be explicitly closed.
+ * Returns NULL on error
+ */
+AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);
+
+/* release a connection acquired with ap_dbd_open */
+AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);
+
+/* acquire a connection that will have the lifetime of a request
+ * and MUST NOT be explicitly closed. Return NULL on error.
+ * This is the preferred function for most applications.
+ */
+AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);
+
+/* acquire a connection that will have the lifetime of a connection
+ * and MUST NOT be explicitly closed. Return NULL on error.
+ */
+AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*);
+
+/* Prepare a statement for use by a client module */
+AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);
+
+/* Also export them as optional functions for modules that prefer it */
+APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
+APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
+APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
+APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
+APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));</pre>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="prepared" id="prepared">SQL Prepared Statements</a></h2>
+ <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> supports SQL prepared statements on behalf
+ of modules that may wish to use them. Each prepared statement
+ must be assigned a name (label), and they are stored in a hash:
+ the <code>prepared</code> field of an <code>ap_dbd_t</code>.
+ Hash entries are of type <code>apr_dbd_prepared_t</code>
+ and can be used in any of the apr_dbd prepared statement
+ SQL query or select commands.</p>
+
+ <p>It is up to dbd user modules to use the prepared statements
+ and document what statements can be specified in httpd.conf,
+ or to provide their own directives and use <code>ap_dbd_prepare</code>.</p>
+
+ <div class="warning"><h3>Caveat</h3>
+ When using prepared statements with a MySQL database, it is preferred to set
+ <code>reconnect</code> to 0 in the connection string as to avoid errors that
+ arise from the MySQL client reconnecting without properly resetting the
+ prepared statements. If set to 1, any broken connections will be attempted
+ fixed, but as mod_dbd is not informed, the prepared statements will be invalidated.
+ </div>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="security" id="security">SECURITY WARNING</a></h2>
+
+ <p>Any web/database application needs to secure itself against SQL
+ injection attacks. In most cases, Apache DBD is safe, because
+ applications use prepared statements, and untrusted inputs are
+ only ever used as data. Of course, if you use it via third-party
+ modules, you should ascertain what precautions they may require.</p>
+ <p>However, the <var>FreeTDS</var> driver is inherently
+ <strong>unsafe</strong>. The underlying library doesn't support
+ prepared statements, so the driver emulates them, and the
+ untrusted input is merged into the SQL statement.</p>
+ <p>It can be made safe by <em>untainting</em> all inputs:
+ a process inspired by Perl's taint checking. Each input
+ is matched against a regexp, and only the match is used,
+ according to the Perl idiom:</p>
+ <div class="example"><pre><code> $untrusted =~ /([a-z]+)/;
+ $trusted = $1;</code></pre></div>
+ <p>To use this, the untainting regexps must be included in the
+ prepared statements configured. The regexp follows immediately
+ after the % in the prepared statement, and is enclosed in
+ curly brackets {}. For example, if your application expects
+ alphanumeric input, you can use:</p>
+ <div class="example"><p><code>
+ <code>"SELECT foo FROM bar WHERE input = %s"</code>
+ </code></p></div>
+ <p>with other drivers, and suffer nothing worse than a failed query.
+ But with FreeTDS you'd need:</p>
+ <div class="example"><p><code>
+ <code>"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"</code>
+ </code></p></div>
+ <p>Now anything that doesn't match the regexp's $1 match is
+ discarded, so the statement is safe.</p>
+ <p>An alternative to this may be the third-party ODBC driver,
+ which offers the security of genuine prepared statements.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="DBDExptime" id="DBDExptime">DBDExptime</a> <a name="dbdexptime" id="dbdexptime">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Keepalive time for idle connections</td></tr>
driver in apr_dbd_mysql.so.</p>
</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="pooling" id="pooling">Connection Pooling</a></h2>
- <p>This module manages database connections, in a manner
- optimised for the platform. On non-threaded platforms,
- it provides a persistent connection in the manner of
- classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python).
- On threaded platform, it provides an altogether more
- scalable and efficient <em>connection pool</em>, as
- described in <a href="http://www.apachetutor.org/dev/reslist">this
- article at ApacheTutor</a>. Note that <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>
- supersedes the modules presented in that article.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="API" id="API">Apache DBD API</a></h2>
- <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> exports five functions for other modules
- to use. The API is as follows:</p>
-
-<pre class="prettyprint lang-c">typedef struct {
- apr_dbd_t *handle;
- apr_dbd_driver_t *driver;
- apr_hash_t *prepared;
-} ap_dbd_t;
-
-/* Export functions to access the database */
-
-/* acquire a connection that MUST be explicitly closed.
- * Returns NULL on error
- */
-AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);
-
-/* release a connection acquired with ap_dbd_open */
-AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);
-
-/* acquire a connection that will have the lifetime of a request
- * and MUST NOT be explicitly closed. Return NULL on error.
- * This is the preferred function for most applications.
- */
-AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);
-
-/* acquire a connection that will have the lifetime of a connection
- * and MUST NOT be explicitly closed. Return NULL on error.
- */
-AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*);
-
-/* Prepare a statement for use by a client module */
-AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);
-
-/* Also export them as optional functions for modules that prefer it */
-APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
-APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
-APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
-APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
-APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));</pre>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="prepared" id="prepared">SQL Prepared Statements</a></h2>
- <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> supports SQL prepared statements on behalf
- of modules that may wish to use them. Each prepared statement
- must be assigned a name (label), and they are stored in a hash:
- the <code>prepared</code> field of an <code>ap_dbd_t</code>.
- Hash entries are of type <code>apr_dbd_prepared_t</code>
- and can be used in any of the apr_dbd prepared statement
- SQL query or select commands.</p>
-
- <p>It is up to dbd user modules to use the prepared statements
- and document what statements can be specified in httpd.conf,
- or to provide their own directives and use <code>ap_dbd_prepare</code>.</p>
-
- <div class="warning"><h3>Caveat</h3>
- When using prepared statements with a MySQL database, it is preferred to set
- <code>reconnect</code> to 0 in the connection string as to avoid errors that
- arise from the MySQL client reconnecting without properly resetting the
- prepared statements. If set to 1, any broken connections will be attempted
- fixed, but as mod_dbd is not informed, the prepared statements will be invalidated.
- </div>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="security" id="security">SECURITY WARNING</a></h2>
-
- <p>Any web/database application needs to secure itself against SQL
- injection attacks. In most cases, Apache DBD is safe, because
- applications use prepared statements, and untrusted inputs are
- only ever used as data. Of course, if you use it via third-party
- modules, you should ascertain what precautions they may require.</p>
- <p>However, the <var>FreeTDS</var> driver is inherently
- <strong>unsafe</strong>. The underlying library doesn't support
- prepared statements, so the driver emulates them, and the
- untrusted input is merged into the SQL statement.</p>
- <p>It can be made safe by <em>untainting</em> all inputs:
- a process inspired by Perl's taint checking. Each input
- is matched against a regexp, and only the match is used,
- according to the Perl idiom:</p>
- <div class="example"><pre><code> $untrusted =~ /([a-z]+)/;
- $trusted = $1;</code></pre></div>
- <p>To use this, the untainting regexps must be included in the
- prepared statements configured. The regexp follows immediately
- after the % in the prepared statement, and is enclosed in
- curly brackets {}. For example, if your application expects
- alphanumeric input, you can use:</p>
- <div class="example"><p><code>
- <code>"SELECT foo FROM bar WHERE input = %s"</code>
- </code></p></div>
- <p>with other drivers, and suffer nothing worse than a failed query.
- But with FreeTDS you'd need:</p>
- <div class="example"><p><code>
- <code>"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"</code>
- </code></p></div>
- <p>Now anything that doesn't match the regexp's $1 match is
- discarded, so the statement is safe.</p>
- <p>An alternative to this may be the third-party ODBC driver,
- which offers the security of genuine prepared statements.</p>
-</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_dbd.html" title="English"> en </a> |
your server to be compressed before being sent to the client over
the network.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#recommended">Sample Configurations</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#enable">Enabling Compression</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#proxies">Dealing with proxy servers</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#precompressed">Serving pre-compressed
+content</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#deflatebuffersize">DeflateBufferSize</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#deflatecompressionlevel">DeflateCompressionLevel</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#deflatememlevel">DeflateMemLevel</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#deflatewindowsize">DeflateWindowSize</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#recommended">Sample Configurations</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#enable">Enabling Compression</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#proxies">Dealing with proxy servers</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#precompressed">Serving pre-compressed
-content</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><a href="../filter.html">Filters</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="recommended" id="recommended">Sample Configurations</a></h2>
+ <div class="warning"><h3>Compression and TLS</h3>
+ <p>Some web applications are vulnerable to an information disclosure
+ attack when a TLS connection carries deflate compressed data. For more
+ information, review the details of the "BREACH" family of attacks.</p>
+ </div>
+ <p>This is a simple configuration that compresses common text-based content types.</p>
+
+ <div class="example"><h3>Compress only a few types</h3><pre class="prettyprint lang-config">AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript</pre>
+</div>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="enable" id="enable">Enabling Compression</a></h2>
+ <div class="warning"><h3>Compression and TLS</h3>
+ <p>Some web applications are vulnerable to an information disclosure
+ attack when a TLS connection carries deflate compressed data. For more
+ information, review the details of the "BREACH" family of attacks.</p>
+ </div>
+
+ <h3><a name="output" id="output">Output Compression</a></h3>
+ <p>Compression is implemented by the <code>DEFLATE</code>
+ <a href="../filter.html">filter</a>. The following directive
+ will enable compression for documents in the container where it
+ is placed:</p>
+
+ <pre class="prettyprint lang-config">SetOutputFilter DEFLATE
+SetEnvIfNoCase Request_URI "\.(?:gif|jpe?g|png)$" no-gzip</pre>
+
+
+ <p>If you want to restrict the compression to particular MIME types
+ in general, you may use the <code class="directive"><a href="../mod/mod_filter.html#addoutputfilterbytype">AddOutputFilterByType</a></code> directive. Here is an example of
+ enabling compression only for the html files of the Apache
+ documentation:</p>
+
+ <pre class="prettyprint lang-config"><Directory "/your-server-root/manual">
+ AddOutputFilterByType DEFLATE text/html
+</Directory></pre>
+
+
+ <div class="note"><h3>Note</h3>
+ The <code>DEFLATE</code> filter is always inserted after RESOURCE
+ filters like PHP or SSI. It never touches internal subrequests.
+ </div>
+ <div class="note"><h3>Note</h3>
+ There is an environment variable <code>force-gzip</code>,
+ set via <code class="directive"><a href="../mod/mod_env.html#setenv">SetEnv</a></code>, which
+ will ignore the accept-encoding setting of your browser and will
+ send compressed output.
+ </div>
+
+
+ <h3><a name="inflate" id="inflate">Output Decompression</a></h3>
+ <p>The <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> module also provides a filter for
+ inflating/uncompressing a gzip compressed response body. In order to activate
+ this feature you have to insert the <code>INFLATE</code> filter into
+ the output filter chain using <code class="directive"><a href="../mod/core.html#setoutputfilter">SetOutputFilter</a></code> or <code class="directive"><a href="../mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code>, for example:</p>
+
+ <pre class="prettyprint lang-config"><Location "/dav-area">
+ ProxyPass "http://example.com/"
+ SetOutputFilter INFLATE
+</Location></pre>
+
+
+ <p>This Example will uncompress gzip'ed output from example.com, so other
+ filters can do further processing with it.
+ </p>
+
+
+ <h3><a name="input" id="input">Input Decompression</a></h3>
+ <p>The <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> module also provides a filter for
+ decompressing a gzip compressed request body . In order to activate
+ this feature you have to insert the <code>DEFLATE</code> filter into
+ the input filter chain using <code class="directive"><a href="../mod/core.html#setinputfilter">SetInputFilter</a></code> or <code class="directive"><a href="../mod/mod_mime.html#addinputfilter">AddInputFilter</a></code>, for example:</p>
+
+ <pre class="prettyprint lang-config"><Location "/dav-area">
+ SetInputFilter DEFLATE
+</Location></pre>
+
+
+ <p>Now if a request contains a <code>Content-Encoding:
+ gzip</code> header, the body will be automatically decompressed.
+ Few browsers have the ability to gzip request bodies. However,
+ some special applications actually do support request
+ compression, for instance some <a href="http://www.webdav.org">WebDAV</a> clients.</p>
+
+ <div class="warning"><h3>Note on Content-Length</h3>
+ <p>If you evaluate the request body yourself, <em>don't trust
+ the <code>Content-Length</code> header!</em>
+ The Content-Length header reflects the length of the
+ incoming data from the client and <em>not</em> the byte count of
+ the decompressed data stream.</p>
+ </div>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="proxies" id="proxies">Dealing with proxy servers</a></h2>
+
+ <p>The <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> module sends a <code>Vary:
+ Accept-Encoding</code> HTTP response header to alert proxies that
+ a cached response should be sent only to clients that send the
+ appropriate <code>Accept-Encoding</code> request header. This
+ prevents compressed content from being sent to a client that will
+ not understand it.</p>
+
+ <p>If you use some special exclusions dependent
+ on, for example, the <code>User-Agent</code> header, you must
+ manually configure an addition to the <code>Vary</code> header
+ to alert proxies of the additional restrictions. For example,
+ in a typical configuration where the addition of the <code>DEFLATE</code>
+ filter depends on the <code>User-Agent</code>, you should add:</p>
+
+ <pre class="prettyprint lang-config">Header append Vary User-Agent</pre>
+
+
+ <p>If your decision about compression depends on other information
+ than request headers (<em>e.g.</em> HTTP version), you have to set the
+ <code>Vary</code> header to the value <code>*</code>. This prevents
+ compliant proxies from caching entirely.</p>
+
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">Header set Vary *</pre>
+</div>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="precompressed" id="precompressed">Serving pre-compressed
+content</a></h2>
+
+ <p>Since <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> re-compresses content each
+ time a request is made, some performance benefit can be derived by
+ pre-compressing the content and telling mod_deflate to serve them
+ without re-compressing them. This may be accomplished using a
+ configuration like the following:</p>
+
+ <pre class="prettyprint lang-config"><IfModule mod_headers.c>
+ # Serve gzip compressed CSS files if they exist
+ # and the client accepts gzip.
+ RewriteCond "%{HTTP:Accept-encoding}" "gzip"
+ RewriteCond "%{REQUEST_FILENAME}\.gz" -s
+ RewriteRule "^(.*)\.css" "$1\.css\.gz" [QSA]
+
+ # Serve gzip compressed JS files if they exist
+ # and the client accepts gzip.
+ RewriteCond "%{HTTP:Accept-encoding}" "gzip"
+ RewriteCond "%{REQUEST_FILENAME}\.gz" -s
+ RewriteRule "^(.*)\.js" "$1\.js\.gz" [QSA]
+
+
+ # Serve correct content types, and prevent mod_deflate double gzip.
+ RewriteRule "\.css\.gz$" "-" [T=text/css,E=no-gzip:1]
+ RewriteRule "\.js\.gz$" "-" [T=text/javascript,E=no-gzip:1]
+
+
+ <FilesMatch "(\.js\.gz|\.css\.gz)$">
+ # Serve correct encoding type.
+ Header append Content-Encoding gzip
+
+ # Force proxies to cache gzipped &
+ # non-gzipped css/js files separately.
+ Header append Vary Accept-Encoding
+ </FilesMatch>
+</IfModule></pre>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="DeflateBufferSize" id="DeflateBufferSize">DeflateBufferSize</a> <a name="deflatebuffersize" id="deflatebuffersize">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fragment size to be compressed at one time by zlib</td></tr>
zlib compression window size (a value between 1 and 15). Generally, the
higher the window size, the higher can the compression ratio be expected.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="recommended" id="recommended">Sample Configurations</a></h2>
- <div class="warning"><h3>Compression and TLS</h3>
- <p>Some web applications are vulnerable to an information disclosure
- attack when a TLS connection carries deflate compressed data. For more
- information, review the details of the "BREACH" family of attacks.</p>
- </div>
- <p>This is a simple configuration that compresses common text-based content types.</p>
-
- <div class="example"><h3>Compress only a few types</h3><pre class="prettyprint lang-config">AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript</pre>
-</div>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="enable" id="enable">Enabling Compression</a></h2>
- <div class="warning"><h3>Compression and TLS</h3>
- <p>Some web applications are vulnerable to an information disclosure
- attack when a TLS connection carries deflate compressed data. For more
- information, review the details of the "BREACH" family of attacks.</p>
- </div>
-
- <h3><a name="output" id="output">Output Compression</a></h3>
- <p>Compression is implemented by the <code>DEFLATE</code>
- <a href="../filter.html">filter</a>. The following directive
- will enable compression for documents in the container where it
- is placed:</p>
-
- <pre class="prettyprint lang-config">SetOutputFilter DEFLATE
-SetEnvIfNoCase Request_URI "\.(?:gif|jpe?g|png)$" no-gzip</pre>
-
-
- <p>If you want to restrict the compression to particular MIME types
- in general, you may use the <code class="directive"><a href="../mod/mod_filter.html#addoutputfilterbytype">AddOutputFilterByType</a></code> directive. Here is an example of
- enabling compression only for the html files of the Apache
- documentation:</p>
-
- <pre class="prettyprint lang-config"><Directory "/your-server-root/manual">
- AddOutputFilterByType DEFLATE text/html
-</Directory></pre>
-
-
- <div class="note"><h3>Note</h3>
- The <code>DEFLATE</code> filter is always inserted after RESOURCE
- filters like PHP or SSI. It never touches internal subrequests.
- </div>
- <div class="note"><h3>Note</h3>
- There is an environment variable <code>force-gzip</code>,
- set via <code class="directive"><a href="../mod/mod_env.html#setenv">SetEnv</a></code>, which
- will ignore the accept-encoding setting of your browser and will
- send compressed output.
- </div>
-
-
- <h3><a name="inflate" id="inflate">Output Decompression</a></h3>
- <p>The <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> module also provides a filter for
- inflating/uncompressing a gzip compressed response body. In order to activate
- this feature you have to insert the <code>INFLATE</code> filter into
- the output filter chain using <code class="directive"><a href="../mod/core.html#setoutputfilter">SetOutputFilter</a></code> or <code class="directive"><a href="../mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code>, for example:</p>
-
- <pre class="prettyprint lang-config"><Location "/dav-area">
- ProxyPass "http://example.com/"
- SetOutputFilter INFLATE
-</Location></pre>
-
-
- <p>This Example will uncompress gzip'ed output from example.com, so other
- filters can do further processing with it.
- </p>
-
-
- <h3><a name="input" id="input">Input Decompression</a></h3>
- <p>The <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> module also provides a filter for
- decompressing a gzip compressed request body . In order to activate
- this feature you have to insert the <code>DEFLATE</code> filter into
- the input filter chain using <code class="directive"><a href="../mod/core.html#setinputfilter">SetInputFilter</a></code> or <code class="directive"><a href="../mod/mod_mime.html#addinputfilter">AddInputFilter</a></code>, for example:</p>
-
- <pre class="prettyprint lang-config"><Location "/dav-area">
- SetInputFilter DEFLATE
-</Location></pre>
-
-
- <p>Now if a request contains a <code>Content-Encoding:
- gzip</code> header, the body will be automatically decompressed.
- Few browsers have the ability to gzip request bodies. However,
- some special applications actually do support request
- compression, for instance some <a href="http://www.webdav.org">WebDAV</a> clients.</p>
-
- <div class="warning"><h3>Note on Content-Length</h3>
- <p>If you evaluate the request body yourself, <em>don't trust
- the <code>Content-Length</code> header!</em>
- The Content-Length header reflects the length of the
- incoming data from the client and <em>not</em> the byte count of
- the decompressed data stream.</p>
- </div>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="proxies" id="proxies">Dealing with proxy servers</a></h2>
-
- <p>The <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> module sends a <code>Vary:
- Accept-Encoding</code> HTTP response header to alert proxies that
- a cached response should be sent only to clients that send the
- appropriate <code>Accept-Encoding</code> request header. This
- prevents compressed content from being sent to a client that will
- not understand it.</p>
-
- <p>If you use some special exclusions dependent
- on, for example, the <code>User-Agent</code> header, you must
- manually configure an addition to the <code>Vary</code> header
- to alert proxies of the additional restrictions. For example,
- in a typical configuration where the addition of the <code>DEFLATE</code>
- filter depends on the <code>User-Agent</code>, you should add:</p>
-
- <pre class="prettyprint lang-config">Header append Vary User-Agent</pre>
-
-
- <p>If your decision about compression depends on other information
- than request headers (<em>e.g.</em> HTTP version), you have to set the
- <code>Vary</code> header to the value <code>*</code>. This prevents
- compliant proxies from caching entirely.</p>
-
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">Header set Vary *</pre>
-</div>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="precompressed" id="precompressed">Serving pre-compressed
-content</a></h2>
-
- <p>Since <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> re-compresses content each
- time a request is made, some performance benefit can be derived by
- pre-compressing the content and telling mod_deflate to serve them
- without re-compressing them. This may be accomplished using a
- configuration like the following:</p>
-
- <pre class="prettyprint lang-config"><IfModule mod_headers.c>
- # Serve gzip compressed CSS files if they exist
- # and the client accepts gzip.
- RewriteCond "%{HTTP:Accept-encoding}" "gzip"
- RewriteCond "%{REQUEST_FILENAME}\.gz" -s
- RewriteRule "^(.*)\.css" "$1\.css\.gz" [QSA]
-
- # Serve gzip compressed JS files if they exist
- # and the client accepts gzip.
- RewriteCond "%{HTTP:Accept-encoding}" "gzip"
- RewriteCond "%{REQUEST_FILENAME}\.gz" -s
- RewriteRule "^(.*)\.js" "$1\.js\.gz" [QSA]
-
-
- # Serve correct content types, and prevent mod_deflate double gzip.
- RewriteRule "\.css\.gz$" "-" [T=text/css,E=no-gzip:1]
- RewriteRule "\.js\.gz$" "-" [T=text/javascript,E=no-gzip:1]
-
-
- <FilesMatch "(\.js\.gz|\.css\.gz)$">
- # Serve correct encoding type.
- Header append Content-Encoding gzip
-
- # Force proxies to cache gzipped &
- # non-gzipped css/js files separately.
- Header append Vary Accept-Encoding
- </FilesMatch>
-</IfModule></pre>
-
-
</div>
</div>
<div class="bottomlang">
<li><img alt="" src="../images/down.gif" /> <a href="#modemstandard">ModemStandard</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ModemStandard" id="ModemStandard">ModemStandard</a> <a name="modemstandard" id="modemstandard">Directive</a></h2>
<table class="directive">
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_dialup.html" title="English"> en </a> |
<li><img alt="" src="../images/down.gif" /> <a href="#fallbackresource">FallbackResource</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="DirectoryCheckHandler" id="DirectoryCheckHandler">DirectoryCheckHandler</a> <a name="directorycheckhandler" id="directorycheckhandler">Directive</a></h2>
<table class="directive">
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_dir.html" title="English"> en </a> |
be expected, this can produce extreme volumes of data,
and should only be used when debugging problems.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#enable">Enabling dumpio Support</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#dumpioinput">DumpIOInput</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#dumpiooutput">DumpIOOutput</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#enable">Enabling dumpio Support</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="enable" id="enable">Enabling dumpio Support</a></h2>
+
+
+ <p>To enable the module, it should be compiled and loaded
+ in to your running Apache configuration. Logging can then
+ be enabled or disabled separately for input and output via
+ the below directives. Additionally, <code class="module"><a href="../mod/mod_dumpio.html">mod_dumpio</a></code>
+ needs to be configured to <code class="directive"><a href="../mod/core.html#loglevel">LogLevel</a></code> <code>trace7</code>:
+ </p>
+ <pre class="prettyprint lang-config">LogLevel dumpio:trace7</pre>
+
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="DumpIOInput" id="DumpIOInput">DumpIOInput</a> <a name="dumpioinput" id="dumpioinput">Directive</a></h2>
<table class="directive">
<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">DumpIOOutput On</pre>
</div>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="enable" id="enable">Enabling dumpio Support</a></h2>
-
-
- <p>To enable the module, it should be compiled and loaded
- in to your running Apache configuration. Logging can then
- be enabled or disabled separately for input and output via
- the below directives. Additionally, <code class="module"><a href="../mod/mod_dumpio.html">mod_dumpio</a></code>
- needs to be configured to <code class="directive"><a href="../mod/core.html#loglevel">LogLevel</a></code> <code>trace7</code>:
- </p>
- <pre class="prettyprint lang-config">LogLevel dumpio:trace7</pre>
-
</div>
</div>
<div class="bottomlang">
<li><img alt="" src="../images/down.gif" /> <a href="#protocolecho">ProtocolEcho</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ProtocolEcho" id="ProtocolEcho">ProtocolEcho</a> <a name="protocolecho" id="protocolecho">Directive</a></h2>
<table class="directive">
</div>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_echo.html" title="English"> en </a> |
<li><a href="../env.html">Environment Variables</a></li>
<li><code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="PassEnv" id="PassEnv">PassEnv</a> <a name="passenv" id="passenv">Directive</a></h2>
<table class="directive">
</div>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_env.html" title="English"> en </a> |
display of some of the tracing the example module did as the
various callbacks were made.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#example">Example</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#compiling">Compiling the example_hooks module</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#using">Using the <code>mod_example_hooks</code> Module</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="Example" id="Example">Example</a> <a name="example" id="example">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Demonstration directive to illustrate the Apache module
-API</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Example</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_example_hooks</td></tr>
-</table>
- <p>The <code class="directive">Example</code> 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-hooks 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 "<code>Example
- directive declared here: YES/NO</code>".</p>
-
-</div>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#example">Example</a></li>
+</ul>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="compiling" id="compiling">Compiling the example_hooks module</a></h2>
to browse to this location and see the brief display mentioned
earlier.</p>
</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="Example" id="Example">Example</a> <a name="example" id="example">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Demonstration directive to illustrate the Apache module
+API</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Example</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_example_hooks</td></tr>
+</table>
+ <p>The <code class="directive">Example</code> 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-hooks 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 "<code>Example
+ directive declared here: YES/NO</code>".</p>
+
+</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_example_hooks.html" title="English"> en </a> |
proxied from an origin server, this module does not change or add
an <code>Expires</code> or <code>Cache-Control</code> header.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#AltSyn">Alternate Interval Syntax</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#expiresactive">ExpiresActive</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#expiresbytype">ExpiresByType</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#expiresdefault">ExpiresDefault</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#AltSyn">Alternate Interval Syntax</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="AltSyn" id="AltSyn">Alternate Interval Syntax</a></h2>
+ <p>The <code class="directive"><a href="#expiresdefault">ExpiresDefault</a></code> and
+ <code class="directive"><a href="#expiresbytype">ExpiresByType</a></code> directives
+ can also be defined in a more readable syntax of the form:</p>
+
+ <pre class="prettyprint lang-config">ExpiresDefault "<var>base</var> [plus <var>num</var> <var>type</var>] [<var>num</var> <var>type</var>] ..."
+ExpiresByType type/encoding "<var>base</var> [plus <var>num</var> <var>type</var>] [<var>num</var> <var>type</var>] ..."</pre>
+
+
+ <p>where <var>base</var> is one of:</p>
+
+ <ul>
+ <li><code>access</code></li>
+
+ <li><code>now</code> (equivalent to
+ '<code>access</code>')</li>
+
+ <li><code>modification</code></li>
+ </ul>
+
+ <p>The <code>plus</code> keyword is optional. <var>num</var>
+ should be an integer value [acceptable to <code>atoi()</code>],
+ and <var>type</var> is one of:</p>
+
+ <ul>
+ <li><code>years</code></li>
+ <li><code>months</code></li>
+ <li><code>weeks</code></li>
+ <li><code>days</code></li>
+ <li><code>hours</code></li>
+ <li><code>minutes</code></li>
+ <li><code>seconds</code></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>
+
+ <pre class="prettyprint lang-config">ExpiresDefault "access plus 1 month"
+ExpiresDefault "access plus 4 weeks"
+ExpiresDefault "access plus 30 days"</pre>
+
+
+ <p>The expiry time can be fine-tuned by adding several
+ '<var>num</var> <var>type</var>' clauses:</p>
+
+ <pre class="prettyprint lang-config">ExpiresByType text/html "access plus 1 month 15 days 2 hours"
+ExpiresByType image/gif "modification plus 5 hours 3 minutes"</pre>
+
+
+ <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>
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ExpiresActive" id="ExpiresActive">ExpiresActive</a> <a name="expiresactive" id="expiresactive">Directive</a></h2>
<table class="directive">
description as well.</p>
</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="AltSyn" id="AltSyn">Alternate Interval Syntax</a></h2>
- <p>The <code class="directive"><a href="#expiresdefault">ExpiresDefault</a></code> and
- <code class="directive"><a href="#expiresbytype">ExpiresByType</a></code> directives
- can also be defined in a more readable syntax of the form:</p>
-
- <pre class="prettyprint lang-config">ExpiresDefault "<var>base</var> [plus <var>num</var> <var>type</var>] [<var>num</var> <var>type</var>] ..."
-ExpiresByType type/encoding "<var>base</var> [plus <var>num</var> <var>type</var>] [<var>num</var> <var>type</var>] ..."</pre>
-
-
- <p>where <var>base</var> is one of:</p>
-
- <ul>
- <li><code>access</code></li>
-
- <li><code>now</code> (equivalent to
- '<code>access</code>')</li>
-
- <li><code>modification</code></li>
- </ul>
-
- <p>The <code>plus</code> keyword is optional. <var>num</var>
- should be an integer value [acceptable to <code>atoi()</code>],
- and <var>type</var> is one of:</p>
-
- <ul>
- <li><code>years</code></li>
- <li><code>months</code></li>
- <li><code>weeks</code></li>
- <li><code>days</code></li>
- <li><code>hours</code></li>
- <li><code>minutes</code></li>
- <li><code>seconds</code></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>
-
- <pre class="prettyprint lang-config">ExpiresDefault "access plus 1 month"
-ExpiresDefault "access plus 4 weeks"
-ExpiresDefault "access plus 30 days"</pre>
-
-
- <p>The expiry time can be fine-tuned by adding several
- '<var>num</var> <var>type</var>' clauses:</p>
-
- <pre class="prettyprint lang-config">ExpiresByType text/html "access plus 1 month 15 days 2 hours"
-ExpiresByType image/gif "modification plus 5 hours 3 minutes"</pre>
-
-
- <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>
-</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_expires.html" title="English"> en </a> |
a prototype environment for filters.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#extfilterdefine">ExtFilterDefine</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#extfilteroptions">ExtFilterOptions</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><a href="../filter.html">Filters</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="examples" id="examples">Examples</a></h2>
+
+ <h3>Generating HTML from some other type of response</h3>
+ <pre class="prettyprint lang-config"># 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
+ExtFilterDefine c-to-html mode=output \
+ intype=text/c outtype=text/html \
+ cmd="/usr/bin/enscript --color -W html -Ec -o - -"
+
+<Directory "/export/home/trawick/apacheinst/htdocs/c">
+ # core directive to cause the new filter to
+ # be run on output
+ SetOutputFilter c-to-html
+
+ # mod_mime directive to set the type of .c
+ # files to text/c
+ AddType text/c .c
+</Directory></pre>
+
+
+
+ <h3>Implementing a content encoding filter</h3>
+ <p>Note: this gzip example is just for the purposes of illustration.
+ Please refer to <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> for a practical
+ implementation.</p>
+
+ <pre class="prettyprint lang-config"># mod_ext_filter directive to define the external filter
+ExtFilterDefine gzip mode=output cmd=/bin/gzip
+
+<Location "/gzipped">
+
+ # core directive to cause the gzip filter to be
+ # run on output
+ SetOutputFilter gzip
+
+ # mod_headers directive to add
+ # "Content-Encoding: gzip" header field
+ Header set Content-Encoding gzip
+</Location></pre>
+
+
+
+ <h3>Slowing down the server</h3>
+ <pre class="prettyprint lang-config"># 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
+ExtFilterDefine slowdown mode=output cmd=/bin/cat \
+ preservescontentlength
+
+<Location "/">
+ # core directive to cause the slowdown filter to
+ # be run several times on output
+ #
+ SetOutputFilter slowdown;slowdown;slowdown
+</Location></pre>
+
+
+
+ <h3>Using sed to replace text in the response</h3>
+ <pre class="prettyprint lang-config"># mod_ext_filter directive to define a filter which
+# replaces text in the response
+#
+ExtFilterDefine fixtext mode=output intype=text/html \
+ cmd="/bin/sed s/verdana/arial/g"
+
+<Location "/">
+ # core directive to cause the fixtext filter to
+ # be run on output
+ SetOutputFilter fixtext
+</Location></pre>
+
+
+<div class="note">
+<p>You can do the same thing using <code class="module"><a href="../mod/mod_substitute.html">mod_substitute</a></code>
+without invoking an external process.</p>
+</div>
+
+
+ <h3>Tracing another filter</h3>
+ <pre class="prettyprint lang-config"># Trace the data read and written by mod_deflate
+# for a particular client (IP 192.168.1.31)
+# experiencing compression problems.
+# This filter will trace what goes into mod_deflate.
+ExtFilterDefine tracebefore \
+ cmd="/bin/tracefilter.pl /tmp/tracebefore" \
+ EnableEnv=trace_this_client
+
+# This filter will trace what goes after mod_deflate.
+# Note that without the ftype parameter, the default
+# filter type of AP_FTYPE_RESOURCE would cause the
+# filter to be placed *before* mod_deflate in the filter
+# chain. Giving it a numeric value slightly higher than
+# AP_FTYPE_CONTENT_SET will ensure that it is placed
+# after mod_deflate.
+ExtFilterDefine traceafter \
+ cmd="/bin/tracefilter.pl /tmp/traceafter" \
+ EnableEnv=trace_this_client ftype=21
+
+<Directory "/usr/local/docs">
+ SetEnvIf Remote_Addr 192.168.1.31 trace_this_client
+ SetOutputFilter tracebefore;deflate;traceafter
+</Directory></pre>
+
+
+ <div class="example"><h3>Here is the filter which traces the data:</h3><pre class="prettyprint lang-perl">#!/usr/local/bin/perl -w
+use strict;
+
+open(SAVE, ">$ARGV[0]")
+ or die "can't open $ARGV[0]: $?";
+
+while (<STDIN>) {
+ print SAVE $_;
+ print $_;
+}
+
+close(SAVE);</pre>
+</div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ExtFilterDefine" id="ExtFilterDefine">ExtFilterDefine</a> <a name="extfilterdefine" id="extfilterdefine">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define an external filter</td></tr>
<p>Messages written to the filter's standard error will be stored
in the Apache error log.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="examples" id="examples">Examples</a></h2>
-
- <h3>Generating HTML from some other type of response</h3>
- <pre class="prettyprint lang-config"># 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
-ExtFilterDefine c-to-html mode=output \
- intype=text/c outtype=text/html \
- cmd="/usr/bin/enscript --color -W html -Ec -o - -"
-
-<Directory "/export/home/trawick/apacheinst/htdocs/c">
- # core directive to cause the new filter to
- # be run on output
- SetOutputFilter c-to-html
-
- # mod_mime directive to set the type of .c
- # files to text/c
- AddType text/c .c
-</Directory></pre>
-
-
-
- <h3>Implementing a content encoding filter</h3>
- <p>Note: this gzip example is just for the purposes of illustration.
- Please refer to <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> for a practical
- implementation.</p>
-
- <pre class="prettyprint lang-config"># mod_ext_filter directive to define the external filter
-ExtFilterDefine gzip mode=output cmd=/bin/gzip
-
-<Location "/gzipped">
-
- # core directive to cause the gzip filter to be
- # run on output
- SetOutputFilter gzip
-
- # mod_headers directive to add
- # "Content-Encoding: gzip" header field
- Header set Content-Encoding gzip
-</Location></pre>
-
-
-
- <h3>Slowing down the server</h3>
- <pre class="prettyprint lang-config"># 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
-ExtFilterDefine slowdown mode=output cmd=/bin/cat \
- preservescontentlength
-
-<Location "/">
- # core directive to cause the slowdown filter to
- # be run several times on output
- #
- SetOutputFilter slowdown;slowdown;slowdown
-</Location></pre>
-
-
-
- <h3>Using sed to replace text in the response</h3>
- <pre class="prettyprint lang-config"># mod_ext_filter directive to define a filter which
-# replaces text in the response
-#
-ExtFilterDefine fixtext mode=output intype=text/html \
- cmd="/bin/sed s/verdana/arial/g"
-
-<Location "/">
- # core directive to cause the fixtext filter to
- # be run on output
- SetOutputFilter fixtext
-</Location></pre>
-
-
-<div class="note">
-<p>You can do the same thing using <code class="module"><a href="../mod/mod_substitute.html">mod_substitute</a></code>
-without invoking an external process.</p>
-</div>
-
-
- <h3>Tracing another filter</h3>
- <pre class="prettyprint lang-config"># Trace the data read and written by mod_deflate
-# for a particular client (IP 192.168.1.31)
-# experiencing compression problems.
-# This filter will trace what goes into mod_deflate.
-ExtFilterDefine tracebefore \
- cmd="/bin/tracefilter.pl /tmp/tracebefore" \
- EnableEnv=trace_this_client
-
-# This filter will trace what goes after mod_deflate.
-# Note that without the ftype parameter, the default
-# filter type of AP_FTYPE_RESOURCE would cause the
-# filter to be placed *before* mod_deflate in the filter
-# chain. Giving it a numeric value slightly higher than
-# AP_FTYPE_CONTENT_SET will ensure that it is placed
-# after mod_deflate.
-ExtFilterDefine traceafter \
- cmd="/bin/tracefilter.pl /tmp/traceafter" \
- EnableEnv=trace_this_client ftype=21
-
-<Directory "/usr/local/docs">
- SetEnvIf Remote_Addr 192.168.1.31 trace_this_client
- SetOutputFilter tracebefore;deflate;traceafter
-</Directory></pre>
-
-
- <div class="example"><h3>Here is the filter which traces the data:</h3><pre class="prettyprint lang-perl">#!/usr/local/bin/perl -w
-use strict;
-
-open(SAVE, ">$ARGV[0]")
- or die "can't open $ARGV[0]: $?";
-
-while (<STDIN>) {
- print SAVE $_;
- print $_;
-}
-
-close(SAVE);</pre>
-</div>
-
</div>
</div>
<div class="bottomlang">
<p>This module is an extension of and borrows heavily from the
<code>mod_mmap_static</code> module in Apache 1.3.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#using">Using mod_file_cache</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#cachefile">CacheFile</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#mmapfile">MMapFile</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#using">Using mod_file_cache</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="CacheFile" id="CacheFile">CacheFile</a> <a name="cachefile" id="cachefile">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Cache a list of file handles at startup time</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheFile <var>file-path</var> [<var>file-path</var>] ...</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_file_cache</td></tr>
-</table>
- <p>The <code class="directive">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 re-cache them.</p>
-
- <p>Be careful with the <var>file-path</var> 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 class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> or
- <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.</p>
-
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">CacheFile /usr/local/apache/htdocs/index.html</pre>
-</div>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="MMapFile" id="MMapFile">MMapFile</a> <a name="mmapfile" id="mmapfile">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Map a list of files into memory at startup time</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MMapFile <var>file-path</var> [<var>file-path</var>] ...</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_file_cache</td></tr>
-</table>
- <p>The <code class="directive">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 <code>HUP</code> or <code>USR1</code> signal should be send to
- the server to re-<code>mmap()</code> them.</p>
-
- <p>Be careful with the <var>file-path</var> 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 class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> or
- <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.</p>
-
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">MMapFile /usr/local/apache/htdocs/index.html</pre>
-</div>
-
-</div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="using" id="using">Using mod_file_cache</a></h2>
| sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf
</code></p></div>
</div>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="CacheFile" id="CacheFile">CacheFile</a> <a name="cachefile" id="cachefile">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Cache a list of file handles at startup time</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheFile <var>file-path</var> [<var>file-path</var>] ...</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_file_cache</td></tr>
+</table>
+ <p>The <code class="directive">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 re-cache them.</p>
+
+ <p>Be careful with the <var>file-path</var> 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 class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> or
+ <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.</p>
+
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">CacheFile /usr/local/apache/htdocs/index.html</pre>
+</div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="MMapFile" id="MMapFile">MMapFile</a> <a name="mmapfile" id="mmapfile">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Map a list of files into memory at startup time</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MMapFile <var>file-path</var> [<var>file-path</var>] ...</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_file_cache</td></tr>
+</table>
+ <p>The <code class="directive">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 <code>HUP</code> or <code>USR1</code> signal should be send to
+ the server to re-<code>mmap()</code> them.</p>
+
+ <p>Be careful with the <var>file-path</var> 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 class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> or
+ <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.</p>
+
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">MMapFile /usr/local/apache/htdocs/index.html</pre>
+</div>
+
</div>
</div>
<div class="bottomlang">
to <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>; no change to existing filter modules is
required (although it may be possible to simplify them).</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#addoutputfilterbytype">AddOutputFilterByType</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#filterchain">FilterChain</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#filterdeclare">FilterDeclare</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#filterprotocol">FilterProtocol</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#filterprovider">FilterProvider</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#filtertrace">FilterTrace</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#smart">Smart Filtering</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#terms">Filter Declarations, Providers and Chains</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#upgrade">Upgrading from Apache HTTP Server 2.2 Configuration</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#protocol">Protocol Handling</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#addoutputfilterbytype">AddOutputFilterByType</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#filterchain">FilterChain</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#filterdeclare">FilterDeclare</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#filterprotocol">FilterProtocol</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#filterprovider">FilterProvider</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#filtertrace">FilterTrace</a></li>
+</ul>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="smart" id="smart">Smart Filtering</a></h2>
+ <p>In the traditional filtering model, filters are inserted unconditionally
+ using <code class="directive"><a href="../mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code> and family.
+ Each filter then needs to determine whether to run, and there is little
+ flexibility available for server admins to allow the chain to be
+ configured dynamically.</p>
+
+ <p><code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> by contrast gives server administrators a
+ great deal of flexibility in configuring the filter chain. In fact,
+ filters can be inserted based on complex boolean
+ <a href="../expr.html">expressions</a> This generalises the limited
+ flexibility offered by <code class="directive">AddOutputFilterByType</code>.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="terms" id="terms">Filter Declarations, Providers and Chains</a></h2>
+ <p class="figure">
+ <img src="../images/mod_filter_old.gif" width="160" height="310" alt="[This image displays the traditional filter model]" /><br />
+ <dfn>Figure 1:</dfn> The traditional filter model</p>
+
+ <p>In the traditional model, output filters are a simple chain
+ from the content generator (handler) to the client. This works well
+ provided the filter chain can be correctly configured, but presents
+ problems when the filters need to be configured dynamically based on
+ the outcome of the handler.</p>
+
+ <p class="figure">
+ <img src="../images/mod_filter_new.gif" width="423" height="331" alt="[This image shows the mod_filter model]" /><br />
+ <dfn>Figure 2:</dfn> The <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> model</p>
+
+ <p><code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> works by introducing indirection into
+ the filter chain. Instead of inserting filters in the chain, we insert
+ a filter harness which in turn dispatches conditionally
+ to a filter provider. Any content filter may be used as a provider
+ to <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>; no change to existing filter modules
+ is required (although it may be possible to simplify them). There can be
+ multiple providers for one filter, but no more than one provider will
+ run for any single request.</p>
+
+ <p>A filter chain comprises any number of instances of the filter
+ harness, each of which may have any number of providers. A special
+ case is that of a single provider with unconditional dispatch: this
+ is equivalent to inserting the provider filter directly into the chain.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="config" id="config">Configuring the Chain</a></h2>
+ <p>There are three stages to configuring a filter chain with
+ <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>. For details of the directives, see below.</p>
+
+ <dl>
+ <dt>Declare Filters</dt>
+ <dd>The <code class="directive"><a href="#filterdeclare">FilterDeclare</a></code> directive
+ declares a filter, assigning it a name and filter type. Required
+ only if the filter is not the default type AP_FTYPE_RESOURCE.</dd>
+
+ <dt>Register Providers</dt>
+ <dd>The <code class="directive"><a href="#filterprovider">FilterProvider</a></code>
+ directive registers a provider with a filter. The filter may have
+ been declared with <code class="directive"><a href="#filterdeclare">FilterDeclare</a></code>; if not, FilterProvider will implicitly
+ declare it with the default type AP_FTYPE_RESOURCE. The provider
+ must have been
+ registered with <code>ap_register_output_filter</code> by some module.
+ The final argument to <code class="directive"><a href="#filterprovider">FilterProvider</a></code> is an expression: the provider will be
+ selected to run for a request if and only if the expression evaluates
+ to true. The expression may evaluate HTTP request or response
+ headers, environment variables, or the Handler used by this request.
+ Unlike earlier versions, mod_filter now supports complex expressions
+ involving multiple criteria with AND / OR logic (&& / ||)
+ and brackets. The details of the expression syntax are described in
+ the <a href="../expr.html">ap_expr documentation</a>.</dd>
+
+ <dt>Configure the Chain</dt>
+ <dd>The above directives build components of a smart filter chain,
+ but do not configure it to run. The <code class="directive"><a href="#filterchain">FilterChain</a></code> directive builds a filter chain from smart
+ filters declared, offering the flexibility to insert filters at the
+ beginning or end of the chain, remove a filter, or clear the chain.</dd>
+</dl>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="errordocs" id="errordocs">Filtering and Response Status</a></h2>
+ <p>mod_filter normally only runs filters on responses with
+ HTTP status 200 (OK). If you want to filter documents with
+ other response statuses, you can set the <var>filter-errordocs</var>
+ environment variable, and it will work on all responses
+ regardless of status. To refine this further, you can use
+ expression conditions with <code class="directive">FilterProvider</code>.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="upgrade" id="upgrade">Upgrading from Apache HTTP Server 2.2 Configuration</a></h2>
+ <p>The <code class="directive"><a href="#filterprovider">FilterProvider</a></code>
+ directive has changed from httpd 2.2: the <var>match</var> and
+ <var>dispatch</var> arguments are replaced with a single but
+ more versatile <var>expression</var>. In general, you can convert
+ a match/dispatch pair to the two sides of an expression, using
+ something like:</p>
+ <div class="example"><p><code>"dispatch = 'match'"</code></p></div>
+ <p>The Request headers, Response headers and Environment variables
+ are now interpreted from syntax <var>%{req:foo}</var>,
+ <var>%{resp:foo}</var> and <var>%{env:foo}</var> respectively.
+ The variables <var>%{HANDLER}</var> and <var>%{CONTENT_TYPE}</var>
+ are also supported.</p>
+ <p>Note that the match no longer support substring matches. They can be
+ replaced by regular expression matches.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="examples" id="examples">Examples</a></h2>
+ <dl>
+ <dt>Server side Includes (SSI)</dt>
+ <dd>A simple case of replacing <code class="directive">AddOutputFilterByType</code>
+ <pre class="prettyprint lang-config">FilterDeclare SSI
+FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|"
+FilterChain SSI</pre>
+
+ </dd>
+
+ <dt>Server side Includes (SSI)</dt>
+ <dd>The same as the above but dispatching on handler (classic
+ SSI behaviour; .shtml files get processed).
+ <pre class="prettyprint lang-config">FilterProvider SSI INCLUDES "%{HANDLER} = 'server-parsed'"
+FilterChain SSI</pre>
+
+ </dd>
+
+ <dt>Emulating mod_gzip with mod_deflate</dt>
+ <dd>Insert INFLATE filter only if "gzip" is NOT in the
+ Accept-Encoding header. This filter runs with ftype CONTENT_SET.
+ <pre class="prettyprint lang-config">FilterDeclare gzip CONTENT_SET
+FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/"
+FilterChain gzip</pre>
+
+ </dd>
+
+ <dt>Image Downsampling</dt>
+ <dd>Suppose we want to downsample all web images, and have filters
+ for GIF, JPEG and PNG.
+ <pre class="prettyprint lang-config">FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'"
+FilterProvider unpack gif_unpack "%{CONTENT_TYPE} = 'image/gif'"
+FilterProvider unpack png_unpack "%{CONTENT_TYPE} = 'image/png'"
+
+FilterProvider downsample downsample_filter "%{CONTENT_TYPE} = m|^image/(jpeg|gif|png)|"
+FilterProtocol downsample "change=yes"
+
+FilterProvider repack jpeg_pack "%{CONTENT_TYPE} = 'image/jpeg'"
+FilterProvider repack gif_pack "%{CONTENT_TYPE} = 'image/gif'"
+FilterProvider repack png_pack "%{CONTENT_TYPE} = 'image/png'"
+<Location "/image-filter">
+ FilterChain unpack downsample repack
+</Location></pre>
+
+ </dd>
+ </dl>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="protocol" id="protocol">Protocol Handling</a></h2>
+ <p>Historically, each filter is responsible for ensuring that whatever
+ changes it makes are correctly represented in the HTTP response headers,
+ and that it does not run when it would make an illegal change. This
+ imposes a burden on filter authors to re-implement some common
+ functionality in every filter:</p>
+
+ <ul>
+ <li>Many filters will change the content, invalidating existing content
+ tags, checksums, hashes, and lengths.</li>
+
+ <li>Filters that require an entire, unbroken response in input need to
+ ensure they don't get byteranges from a backend.</li>
+
+ <li>Filters that transform output in a filter need to ensure they don't
+ violate a <code>Cache-Control: no-transform</code> header from the
+ backend.</li>
+
+ <li>Filters may make responses uncacheable.</li>
+ </ul>
+
+ <p><code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> aims to offer generic handling of these
+ details of filter implementation, reducing the complexity required of
+ content filter modules. This is work-in-progress; the
+ <code class="directive"><a href="#filterprotocol">FilterProtocol</a></code> implements
+ some of this functionality for back-compatibility with Apache 2.0
+ modules. For httpd 2.1 and later, the
+ <code>ap_register_output_filter_protocol</code> and
+ <code>ap_filter_protocol</code> API enables filter modules to
+ declare their own behaviour.</p>
+
+ <p>At the same time, <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> should not interfere
+ with a filter that wants to handle all aspects of the protocol. By
+ default (i.e. in the absence of any <code class="directive"><a href="#filterprotocol">FilterProtocol</a></code> directives), <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>
+ will leave the headers untouched.</p>
+
+ <p>At the time of writing, this feature is largely untested,
+ as modules in common use are designed to work with 2.0.
+ Modules using it should test it carefully.</p>
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AddOutputFilterByType" id="AddOutputFilterByType">AddOutputFilterByType</a> <a name="addoutputfilterbytype" id="addoutputfilterbytype">Directive</a></h2>
<table class="directive">
</dl>
</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="smart" id="smart">Smart Filtering</a></h2>
- <p>In the traditional filtering model, filters are inserted unconditionally
- using <code class="directive"><a href="../mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code> and family.
- Each filter then needs to determine whether to run, and there is little
- flexibility available for server admins to allow the chain to be
- configured dynamically.</p>
-
- <p><code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> by contrast gives server administrators a
- great deal of flexibility in configuring the filter chain. In fact,
- filters can be inserted based on complex boolean
- <a href="../expr.html">expressions</a> This generalises the limited
- flexibility offered by <code class="directive">AddOutputFilterByType</code>.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="terms" id="terms">Filter Declarations, Providers and Chains</a></h2>
- <p class="figure">
- <img src="../images/mod_filter_old.gif" width="160" height="310" alt="[This image displays the traditional filter model]" /><br />
- <dfn>Figure 1:</dfn> The traditional filter model</p>
-
- <p>In the traditional model, output filters are a simple chain
- from the content generator (handler) to the client. This works well
- provided the filter chain can be correctly configured, but presents
- problems when the filters need to be configured dynamically based on
- the outcome of the handler.</p>
-
- <p class="figure">
- <img src="../images/mod_filter_new.gif" width="423" height="331" alt="[This image shows the mod_filter model]" /><br />
- <dfn>Figure 2:</dfn> The <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> model</p>
-
- <p><code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> works by introducing indirection into
- the filter chain. Instead of inserting filters in the chain, we insert
- a filter harness which in turn dispatches conditionally
- to a filter provider. Any content filter may be used as a provider
- to <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>; no change to existing filter modules
- is required (although it may be possible to simplify them). There can be
- multiple providers for one filter, but no more than one provider will
- run for any single request.</p>
-
- <p>A filter chain comprises any number of instances of the filter
- harness, each of which may have any number of providers. A special
- case is that of a single provider with unconditional dispatch: this
- is equivalent to inserting the provider filter directly into the chain.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="config" id="config">Configuring the Chain</a></h2>
- <p>There are three stages to configuring a filter chain with
- <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>. For details of the directives, see below.</p>
-
- <dl>
- <dt>Declare Filters</dt>
- <dd>The <code class="directive"><a href="#filterdeclare">FilterDeclare</a></code> directive
- declares a filter, assigning it a name and filter type. Required
- only if the filter is not the default type AP_FTYPE_RESOURCE.</dd>
-
- <dt>Register Providers</dt>
- <dd>The <code class="directive"><a href="#filterprovider">FilterProvider</a></code>
- directive registers a provider with a filter. The filter may have
- been declared with <code class="directive"><a href="#filterdeclare">FilterDeclare</a></code>; if not, FilterProvider will implicitly
- declare it with the default type AP_FTYPE_RESOURCE. The provider
- must have been
- registered with <code>ap_register_output_filter</code> by some module.
- The final argument to <code class="directive"><a href="#filterprovider">FilterProvider</a></code> is an expression: the provider will be
- selected to run for a request if and only if the expression evaluates
- to true. The expression may evaluate HTTP request or response
- headers, environment variables, or the Handler used by this request.
- Unlike earlier versions, mod_filter now supports complex expressions
- involving multiple criteria with AND / OR logic (&& / ||)
- and brackets. The details of the expression syntax are described in
- the <a href="../expr.html">ap_expr documentation</a>.</dd>
-
- <dt>Configure the Chain</dt>
- <dd>The above directives build components of a smart filter chain,
- but do not configure it to run. The <code class="directive"><a href="#filterchain">FilterChain</a></code> directive builds a filter chain from smart
- filters declared, offering the flexibility to insert filters at the
- beginning or end of the chain, remove a filter, or clear the chain.</dd>
-</dl>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="errordocs" id="errordocs">Filtering and Response Status</a></h2>
- <p>mod_filter normally only runs filters on responses with
- HTTP status 200 (OK). If you want to filter documents with
- other response statuses, you can set the <var>filter-errordocs</var>
- environment variable, and it will work on all responses
- regardless of status. To refine this further, you can use
- expression conditions with <code class="directive">FilterProvider</code>.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="upgrade" id="upgrade">Upgrading from Apache HTTP Server 2.2 Configuration</a></h2>
- <p>The <code class="directive"><a href="#filterprovider">FilterProvider</a></code>
- directive has changed from httpd 2.2: the <var>match</var> and
- <var>dispatch</var> arguments are replaced with a single but
- more versatile <var>expression</var>. In general, you can convert
- a match/dispatch pair to the two sides of an expression, using
- something like:</p>
- <div class="example"><p><code>"dispatch = 'match'"</code></p></div>
- <p>The Request headers, Response headers and Environment variables
- are now interpreted from syntax <var>%{req:foo}</var>,
- <var>%{resp:foo}</var> and <var>%{env:foo}</var> respectively.
- The variables <var>%{HANDLER}</var> and <var>%{CONTENT_TYPE}</var>
- are also supported.</p>
- <p>Note that the match no longer support substring matches. They can be
- replaced by regular expression matches.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="examples" id="examples">Examples</a></h2>
- <dl>
- <dt>Server side Includes (SSI)</dt>
- <dd>A simple case of replacing <code class="directive">AddOutputFilterByType</code>
- <pre class="prettyprint lang-config">FilterDeclare SSI
-FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|"
-FilterChain SSI</pre>
-
- </dd>
-
- <dt>Server side Includes (SSI)</dt>
- <dd>The same as the above but dispatching on handler (classic
- SSI behaviour; .shtml files get processed).
- <pre class="prettyprint lang-config">FilterProvider SSI INCLUDES "%{HANDLER} = 'server-parsed'"
-FilterChain SSI</pre>
-
- </dd>
-
- <dt>Emulating mod_gzip with mod_deflate</dt>
- <dd>Insert INFLATE filter only if "gzip" is NOT in the
- Accept-Encoding header. This filter runs with ftype CONTENT_SET.
- <pre class="prettyprint lang-config">FilterDeclare gzip CONTENT_SET
-FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/"
-FilterChain gzip</pre>
-
- </dd>
-
- <dt>Image Downsampling</dt>
- <dd>Suppose we want to downsample all web images, and have filters
- for GIF, JPEG and PNG.
- <pre class="prettyprint lang-config">FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'"
-FilterProvider unpack gif_unpack "%{CONTENT_TYPE} = 'image/gif'"
-FilterProvider unpack png_unpack "%{CONTENT_TYPE} = 'image/png'"
-
-FilterProvider downsample downsample_filter "%{CONTENT_TYPE} = m|^image/(jpeg|gif|png)|"
-FilterProtocol downsample "change=yes"
-
-FilterProvider repack jpeg_pack "%{CONTENT_TYPE} = 'image/jpeg'"
-FilterProvider repack gif_pack "%{CONTENT_TYPE} = 'image/gif'"
-FilterProvider repack png_pack "%{CONTENT_TYPE} = 'image/png'"
-<Location "/image-filter">
- FilterChain unpack downsample repack
-</Location></pre>
-
- </dd>
- </dl>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="protocol" id="protocol">Protocol Handling</a></h2>
- <p>Historically, each filter is responsible for ensuring that whatever
- changes it makes are correctly represented in the HTTP response headers,
- and that it does not run when it would make an illegal change. This
- imposes a burden on filter authors to re-implement some common
- functionality in every filter:</p>
-
- <ul>
- <li>Many filters will change the content, invalidating existing content
- tags, checksums, hashes, and lengths.</li>
-
- <li>Filters that require an entire, unbroken response in input need to
- ensure they don't get byteranges from a backend.</li>
-
- <li>Filters that transform output in a filter need to ensure they don't
- violate a <code>Cache-Control: no-transform</code> header from the
- backend.</li>
-
- <li>Filters may make responses uncacheable.</li>
- </ul>
-
- <p><code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> aims to offer generic handling of these
- details of filter implementation, reducing the complexity required of
- content filter modules. This is work-in-progress; the
- <code class="directive"><a href="#filterprotocol">FilterProtocol</a></code> implements
- some of this functionality for back-compatibility with Apache 2.0
- modules. For httpd 2.1 and later, the
- <code>ap_register_output_filter_protocol</code> and
- <code>ap_filter_protocol</code> API enables filter modules to
- declare their own behaviour.</p>
-
- <p>At the same time, <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> should not interfere
- with a filter that wants to handle all aspects of the protocol. By
- default (i.e. in the absence of any <code class="directive"><a href="#filterprotocol">FilterProtocol</a></code> directives), <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>
- will leave the headers untouched.</p>
-
- <p>At the time of writing, this feature is largely untested,
- as modules in common use are designed to work with 2.0.
- Modules using it should test it carefully.</p>
-</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_filter.html" title="English"> en </a> |
request and response headers. Headers can be merged, replaced
or removed.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#header">Header</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#requestheader">RequestHeader</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#order">Order of Processing</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#early">Early and Late Processing</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#header">Header</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#requestheader">RequestHeader</a></li>
+</ul>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="order" id="order">Order of Processing</a></h2>
+
+ <p>The directives provided by <code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can
+ occur almost anywhere within the server configuration, and can be
+ limited in scope by enclosing them in <a href="../sections.html">configuration sections</a>.</p>
+
+ <p>Order of processing is important and is affected both by the
+ order in the configuration file and by placement in <a href="../sections.html#mergin">configuration sections</a>. These
+ two directives have a different effect if reversed:</p>
+
+ <pre class="prettyprint lang-config">RequestHeader append MirrorID "mirror 12"
+RequestHeader unset MirrorID</pre>
+
+
+ <p>This way round, the <code>MirrorID</code> header is not set. If
+ reversed, the MirrorID header is set to "mirror 12".</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="early" id="early">Early and Late Processing</a></h2>
+ <p><code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can be applied either early or late
+ in the request. The normal mode is late, when <em>Request</em> Headers are
+ set immediately before running the content generator and <em>Response</em>
+ Headers just as the response is sent down the wire. Always use
+ Late mode in an operational server.</p>
+
+ <p>Early mode is designed as a test/debugging aid for developers.
+ Directives defined using the <code>early</code> keyword are set
+ right at the beginning of processing the request. This means
+ they can be used to simulate different requests and set up test
+ cases, but it also means that headers may be changed at any time
+ by other modules before generating a Response.</p>
+
+ <p>Because early directives are processed before the request path's
+ configuration is traversed, early headers can only be set in a
+ main server or virtual host context. Early directives cannot depend
+ on a request path, so they will fail in contexts such as
+ <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> or
+ <code class="directive"><a href="../mod/core.html#location"><Location></a></code>.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="examples" id="examples">Examples</a></h2>
+
+ <ol>
+ <li>
+ Copy all request headers that begin with "TS" to the
+ response headers:
+
+ <pre class="prettyprint lang-config">Header echo ^TS</pre>
+
+ </li>
+
+ <li>
+ Add a header, <code>MyHeader</code>, 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.
+
+ <pre class="prettyprint lang-config">Header set MyHeader "%D %t"</pre>
+
+
+ <p>results in this header being added to the response:</p>
+
+ <div class="example"><p><code>
+ MyHeader: D=3775428 t=991424704447256
+ </code></p></div>
+ </li>
+
+ <li>
+ Say hello to Joe
+
+ <pre class="prettyprint lang-config">Header set MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."</pre>
+
+
+ <p>results in this header being added to the response:</p>
+
+ <div class="example"><p><code>
+ MyHeader: Hello Joe. It took D=3775428 microseconds for Apache
+ to serve this request.
+ </code></p></div>
+ </li>
+
+ <li>
+ Conditionally send <code>MyHeader</code> on the response if and
+ only if header <code>MyRequestHeader</code> 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
+ <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code> module.
+
+ <pre class="prettyprint lang-config">SetEnvIf MyRequestHeader myvalue HAVE_MyRequestHeader
+Header set MyHeader "%D %t mytext" env=HAVE_MyRequestHeader</pre>
+
+
+ <p>If the header <code>MyRequestHeader: myvalue</code> is present on
+ the HTTP request, the response will contain the following header:</p>
+
+ <div class="example"><p><code>
+ MyHeader: D=3775428 t=991424704447256 mytext
+ </code></p></div>
+ </li>
+
+ <li>
+ Enable DAV to work with Apache running HTTP through SSL hardware
+ (<a href="http://svn.haxx.se/users/archive-2006-03/0549.shtml">problem
+ description</a>) by replacing <var>https:</var> with
+ <var>http:</var> in the <var>Destination</var> header:
+
+ <pre class="prettyprint lang-config">RequestHeader edit Destination ^https: http: early</pre>
+
+ </li>
+
+ <li>
+ Set the same header value under multiple nonexclusive conditions,
+ but do not duplicate the value in the final header.
+ If all of the following conditions applied to a request (i.e.,
+ if the <code>CGI</code>, <code>NO_CACHE</code> and
+ <code>NO_STORE</code> environment variables all existed for the
+ request):
+
+ <pre class="prettyprint lang-config">Header merge Cache-Control no-cache env=CGI
+Header merge Cache-Control no-cache env=NO_CACHE
+Header merge Cache-Control no-store env=NO_STORE</pre>
+
+
+ <p>then the response would contain the following header:</p>
+
+ <div class="example"><p><code>
+ Cache-Control: no-cache, no-store
+ </code></p></div>
+
+ <p>If <code>append</code> was used instead of <code>merge</code>,
+ then the response would contain the following header:</p>
+
+ <div class="example"><p><code>
+ Cache-Control: no-cache, no-cache, no-store
+ </code></p></div>
+ </li>
+ <li>
+ Set a test cookie if and only if the client didn't send us a cookie
+ <pre class="prettyprint lang-config">Header set Set-Cookie testcookie "expr=-z %{req:Cookie}"</pre>
+
+ </li>
+ <li>
+ Append a Caching header for responses with a HTTP status code of 200
+ <pre class="prettyprint lang-config">Header append Cache-Control s-maxage=600 "expr=%{REQUEST_STATUS} == 200"</pre>
+
+ </li>
+
+ </ol>
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="Header" id="Header">Header</a> <a name="header" id="header">Directive</a></h2>
<table class="directive">
input filters to be overridden or modified.</p>
</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="order" id="order">Order of Processing</a></h2>
-
- <p>The directives provided by <code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can
- occur almost anywhere within the server configuration, and can be
- limited in scope by enclosing them in <a href="../sections.html">configuration sections</a>.</p>
-
- <p>Order of processing is important and is affected both by the
- order in the configuration file and by placement in <a href="../sections.html#mergin">configuration sections</a>. These
- two directives have a different effect if reversed:</p>
-
- <pre class="prettyprint lang-config">RequestHeader append MirrorID "mirror 12"
-RequestHeader unset MirrorID</pre>
-
-
- <p>This way round, the <code>MirrorID</code> header is not set. If
- reversed, the MirrorID header is set to "mirror 12".</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="early" id="early">Early and Late Processing</a></h2>
- <p><code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can be applied either early or late
- in the request. The normal mode is late, when <em>Request</em> Headers are
- set immediately before running the content generator and <em>Response</em>
- Headers just as the response is sent down the wire. Always use
- Late mode in an operational server.</p>
-
- <p>Early mode is designed as a test/debugging aid for developers.
- Directives defined using the <code>early</code> keyword are set
- right at the beginning of processing the request. This means
- they can be used to simulate different requests and set up test
- cases, but it also means that headers may be changed at any time
- by other modules before generating a Response.</p>
-
- <p>Because early directives are processed before the request path's
- configuration is traversed, early headers can only be set in a
- main server or virtual host context. Early directives cannot depend
- on a request path, so they will fail in contexts such as
- <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> or
- <code class="directive"><a href="../mod/core.html#location"><Location></a></code>.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="examples" id="examples">Examples</a></h2>
-
- <ol>
- <li>
- Copy all request headers that begin with "TS" to the
- response headers:
-
- <pre class="prettyprint lang-config">Header echo ^TS</pre>
-
- </li>
-
- <li>
- Add a header, <code>MyHeader</code>, 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.
-
- <pre class="prettyprint lang-config">Header set MyHeader "%D %t"</pre>
-
-
- <p>results in this header being added to the response:</p>
-
- <div class="example"><p><code>
- MyHeader: D=3775428 t=991424704447256
- </code></p></div>
- </li>
-
- <li>
- Say hello to Joe
-
- <pre class="prettyprint lang-config">Header set MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."</pre>
-
-
- <p>results in this header being added to the response:</p>
-
- <div class="example"><p><code>
- MyHeader: Hello Joe. It took D=3775428 microseconds for Apache
- to serve this request.
- </code></p></div>
- </li>
-
- <li>
- Conditionally send <code>MyHeader</code> on the response if and
- only if header <code>MyRequestHeader</code> 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
- <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code> module.
-
- <pre class="prettyprint lang-config">SetEnvIf MyRequestHeader myvalue HAVE_MyRequestHeader
-Header set MyHeader "%D %t mytext" env=HAVE_MyRequestHeader</pre>
-
-
- <p>If the header <code>MyRequestHeader: myvalue</code> is present on
- the HTTP request, the response will contain the following header:</p>
-
- <div class="example"><p><code>
- MyHeader: D=3775428 t=991424704447256 mytext
- </code></p></div>
- </li>
-
- <li>
- Enable DAV to work with Apache running HTTP through SSL hardware
- (<a href="http://svn.haxx.se/users/archive-2006-03/0549.shtml">problem
- description</a>) by replacing <var>https:</var> with
- <var>http:</var> in the <var>Destination</var> header:
-
- <pre class="prettyprint lang-config">RequestHeader edit Destination ^https: http: early</pre>
-
- </li>
-
- <li>
- Set the same header value under multiple nonexclusive conditions,
- but do not duplicate the value in the final header.
- If all of the following conditions applied to a request (i.e.,
- if the <code>CGI</code>, <code>NO_CACHE</code> and
- <code>NO_STORE</code> environment variables all existed for the
- request):
-
- <pre class="prettyprint lang-config">Header merge Cache-Control no-cache env=CGI
-Header merge Cache-Control no-cache env=NO_CACHE
-Header merge Cache-Control no-store env=NO_STORE</pre>
-
-
- <p>then the response would contain the following header:</p>
-
- <div class="example"><p><code>
- Cache-Control: no-cache, no-store
- </code></p></div>
-
- <p>If <code>append</code> was used instead of <code>merge</code>,
- then the response would contain the following header:</p>
-
- <div class="example"><p><code>
- Cache-Control: no-cache, no-cache, no-store
- </code></p></div>
- </li>
- <li>
- Set a test cookie if and only if the client didn't send us a cookie
- <pre class="prettyprint lang-config">Header set Set-Cookie testcookie "expr=-z %{req:Cookie}"</pre>
-
- </li>
- <li>
- Append a Caching header for responses with a HTTP status code of 200
- <pre class="prettyprint lang-config">Header append Cache-Control s-maxage=600 "expr=%{REQUEST_STATUS} == 200"</pre>
-
- </li>
-
- </ol>
-</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English"> en </a> |
</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#consuming">Consuming mod_heartbeat Output</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#heartbeataddress">HeartbeatAddress</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#consuming">Consuming mod_heartbeat Output</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="HeartbeatAddress" id="HeartbeatAddress">HeartbeatAddress</a> <a name="heartbeataddress" id="heartbeataddress">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Multicast address for heartbeat packets</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>HeartbeatAddress <var>addr:port</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>disabled</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_heartbeat</td></tr>
-</table>
-<p>The <code class="directive">HeartbeatAddress</code> directive specifies the
-multicast address to which <code class="module"><a href="../mod/mod_heartbeat.html">mod_heartbeat</a></code> will send
-status information. This address will usually correspond to a configured
- <code class="directive"><a href="../mod/mod_heartmonitor.html#heartbeatlisten">HeartbeatListen</a></code> on a
-frontend proxy system.</p>
-<pre class="prettyprint lang-config">HeartbeatAddress 239.0.0.1:27999</pre>
-
-
-</div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="consuming" id="consuming">Consuming mod_heartbeat Output</a></h2>
separated by '&', being added in the future.
</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="HeartbeatAddress" id="HeartbeatAddress">HeartbeatAddress</a> <a name="heartbeataddress" id="heartbeataddress">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Multicast address for heartbeat packets</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>HeartbeatAddress <var>addr:port</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>disabled</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_heartbeat</td></tr>
+</table>
+<p>The <code class="directive">HeartbeatAddress</code> directive specifies the
+multicast address to which <code class="module"><a href="../mod/mod_heartbeat.html">mod_heartbeat</a></code> will send
+status information. This address will usually correspond to a configured
+ <code class="directive"><a href="../mod/mod_heartmonitor.html#heartbeatlisten">HeartbeatListen</a></code> on a
+frontend proxy system.</p>
+<pre class="prettyprint lang-config">HeartbeatAddress 239.0.0.1:27999</pre>
+
+
</div>
</div>
<div class="bottomlang">
<li><img alt="" src="../images/down.gif" /> <a href="#heartbeatstorage">HeartbeatStorage</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="HeartbeatListen" id="HeartbeatListen">HeartbeatListen</a> <a name="heartbeatlisten" id="heartbeatlisten">Directive</a></h2>
<table class="directive">
<code class="module"><a href="../mod/mod_slotmem_shm.html">mod_slotmem_shm</a></code> is not loaded.</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_heartmonitor.html" title="English"> en </a> |
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="IdentityCheck" id="IdentityCheck">IdentityCheck</a> <a name="identitycheck" id="identitycheck">Directive</a></h2>
<table class="directive">
timeout value according to your local network speed.</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_ident.html" title="English"> en </a> |
<p>However, we are trying to phase out "magic MIME types" so we
are deprecating this method.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#imapbase">ImapBase</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#imapdefault">ImapDefault</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#imapmenu">ImapMenu</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#features">New Features</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#imapfile">Imagemap File</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#example">Example Mapfile</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#referencing">Referencing your mapfile</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ImapBase" id="ImapBase">ImapBase</a> <a name="imapbase" id="imapbase">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Default <code>base</code> for imagemap files</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ImapBase map|referer|<var>URL</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ImapBase http://servername/</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Indexes</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_imagemap</td></tr>
-</table>
- <p>The <code class="directive">ImapBase</code> 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://<var>servername</var>/</code>.</p>
-
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code></li>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#imapbase">ImapBase</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#imapdefault">ImapDefault</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#imapmenu">ImapMenu</a></li>
</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ImapDefault" id="ImapDefault">ImapDefault</a> <a name="imapdefault" id="imapdefault">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Default action when an imagemap is called with coordinates
-that are not explicitly mapped</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ImapDefault error|nocontent|map|referer|<var>URL</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ImapDefault nocontent</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Indexes</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_imagemap</td></tr>
-</table>
- <p>The <code class="directive">ImapDefault</code> 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>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ImapMenu" id="ImapMenu">ImapMenu</a> <a name="imapmenu" id="imapmenu">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Action if no coordinates are given when calling
-an imagemap</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ImapMenu none|formatted|semiformatted|unformatted</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ImapMenu formatted</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Indexes</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_imagemap</td></tr>
-</table>
- <p>The <code class="directive">ImapMenu</code> 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>
-
-</div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="features" id="features">New Features</a></h2>
</a>
</code></p></div>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ImapBase" id="ImapBase">ImapBase</a> <a name="imapbase" id="imapbase">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Default <code>base</code> for imagemap files</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ImapBase map|referer|<var>URL</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ImapBase http://servername/</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Indexes</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_imagemap</td></tr>
+</table>
+ <p>The <code class="directive">ImapBase</code> 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://<var>servername</var>/</code>.</p>
+
+<h3>See also</h3>
+<ul>
+<li><code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code></li>
+</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ImapDefault" id="ImapDefault">ImapDefault</a> <a name="imapdefault" id="imapdefault">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Default action when an imagemap is called with coordinates
+that are not explicitly mapped</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ImapDefault error|nocontent|map|referer|<var>URL</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ImapDefault nocontent</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Indexes</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_imagemap</td></tr>
+</table>
+ <p>The <code class="directive">ImapDefault</code> 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>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ImapMenu" id="ImapMenu">ImapMenu</a> <a name="imapmenu" id="imapmenu">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Action if no coordinates are given when calling
+an imagemap</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ImapMenu none|formatted|semiformatted|unformatted</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ImapMenu formatted</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Indexes</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_imagemap</td></tr>
+</table>
+ <p>The <code class="directive">ImapMenu</code> 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>
+
</div>
</div>
<div class="bottomlang">
inclusion of other files or programs, as well as the setting and
printing of environment variables.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#enabling">Enabling Server-Side Includes</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#pathinfo">PATH_INFO with Server Side Includes</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#elements">Available Elements</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#includevars">Include Variables</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#substitution">Variable Substitution</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#flowctrl">Flow Control Elements</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#legacyexpr">Legacy expression syntax</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#ssiendtag">SSIEndTag</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ssierrormsg">SSIErrorMsg</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ssiundefinedecho">SSIUndefinedEcho</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#xbithack">XBitHack</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#enabling">Enabling Server-Side Includes</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#pathinfo">PATH_INFO with Server Side Includes</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#elements">Available Elements</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#includevars">Include Variables</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#substitution">Variable Substitution</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#flowctrl">Flow Control Elements</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#legacyexpr">Legacy expression syntax</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/core.html#options">Options</a></code></li>
<li><code class="directive"><a href="../mod/core.html#acceptpathinfo">AcceptPathInfo</a></code></li>
<li><a href="../howto/ssi.html">SSI Tutorial</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SSIEndTag" id="SSIEndTag">SSIEndTag</a> <a name="ssiendtag" id="ssiendtag">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String that ends an include element</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIEndTag <var>tag</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIEndTag "-->"</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
-</table>
- <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
- looks for to mark the end of an include element.</p>
-
- <pre class="prettyprint lang-config">SSIEndTag "%>"</pre>
+<div class="section">
+<h2><a name="enabling" id="enabling">Enabling Server-Side Includes</a></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>
+ <pre class="prettyprint lang-config">AddType text/html .shtml
+AddOutputFilter INCLUDES .shtml</pre>
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="#ssistarttag">SSIStartTag</a></code></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SSIErrorMsg" id="SSIErrorMsg">SSIErrorMsg</a> <a name="ssierrormsg" id="ssierrormsg">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Error message displayed when there is an SSI
-error</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIErrorMsg <var>message</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIErrorMsg "[an error occurred while processing this
-directive]"</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
-</table>
- <p>The <code class="directive">SSIErrorMsg</code> directive changes the error
- message displayed when <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> encounters an
- error. For production servers you may consider changing the default
- error message to <code>"<!-- Error -->"</code> so that
- the message is not presented to the user.</p>
- <p>This directive has the same effect as the <code><!--#config
- errmsg=<var>message</var> --></code> element.</p>
+ <p>The following directive must be given for the directories
+ containing the shtml files (typically in a
+ <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section,
+ but this directive is also valid in <code>.htaccess</code> files if
+ <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> <code>Options</code>
+ is set):</p>
- <pre class="prettyprint lang-config">SSIErrorMsg "<!-- Error -->"</pre>
+ <pre class="prettyprint lang-config">Options +Includes</pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SSIETag" id="SSIETag">SSIETag</a> <a name="ssietag" id="ssietag">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls whether ETags are generated by the server.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIETag on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIETag off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.2.15 and later.</td></tr>
-</table>
- <p>Under normal circumstances, a file filtered by <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
- may contain elements that are either dynamically generated, or that may
- have changed independently of the original file. As a result, by default
- the server is asked not to generate an <code>ETag</code> header for the
- response by adding <code>no-etag</code> to the request notes.</p>
+ <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>The <code class="directive">SSIETag</code> directive suppresses this
- behaviour, and allows the server to generate an <code>ETag</code> header.
- This can be used to enable caching of the output. Note that a backend server
- or dynamic content generator may generate an ETag of its own, ignoring
- <code>no-etag</code>, and this ETag will be passed by
- <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> regardless of the value of this setting.
- <code class="directive">SSIETag</code> can take on the following values:</p>
+ <p>For more information, see our <a href="../howto/ssi.html">Tutorial on Server Side Includes</a>.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="pathinfo" id="pathinfo">PATH_INFO with Server Side Includes</a></h2>
+
- <dl>
+ <p>Files processed for server-side includes no longer accept
+ requests with <code>PATH_INFO</code> (trailing pathname information)
+ by default. You can use the <code class="directive"><a href="../mod/core.html#acceptpathinfo">AcceptPathInfo</a></code> directive to
+ configure the server to accept requests with <code>PATH_INFO</code>.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="elements" id="elements">Available Elements</a></h2>
+ <p>The document is parsed as an HTML document, with special
+ commands embedded as SGML comments. A command has the syntax: </p>
- <dt><code>off</code></dt>
- <dd><code>no-etag</code> will be added to the request notes, and the server
- is asked not to generate an ETag. Where a server ignores the value of
- <code>no-etag</code> and generates an ETag anyway, the ETag will be
- respected.</dd>
+ <div class="example"><p><code>
+ <!--#<var>element</var> <var>attribute</var>=<var>value</var>
+ <var>attribute</var>=<var>value</var> ... -->
+ </code></p></div>
- <dt><code>on</code></dt>
- <dd>Existing ETags will be respected, and ETags generated by the server will
- be passed on in the response.</dd>
+ <p>The value will often be enclosed in double quotes, but single
+ quotes (<code>'</code>) and backticks (<code>`</code>) are also
+ possible. Many commands only allow a single attribute-value pair.
+ Note that the comment terminator (<code>--></code>) should be
+ preceded by whitespace to ensure that it isn't considered part of
+ an SSI token. Note that the leading <code><!--#</code> is <em>one</em>
+ token and may not contain any whitespaces.</p>
- </dl>
+ <p>The allowed elements are listed in the following table:</p>
+ <table class="bordered">
+ <tr><th>Element</th><th>Description</th></tr>
+ <tr><td><code><a href="#element.config">config</a></code></td>
+ <td>configure output formats</td></tr>
+ <tr><td><code><a href="#element.echo">echo</a></code></td>
+ <td>print variables</td></tr>
+ <tr><td><code><a href="#element.exec">exec</a></code></td>
+ <td>execute external programs</td></tr>
+ <tr><td><code><a href="#element.fsize">fsize</a></code></td>
+ <td>print size of a file</td></tr>
+ <tr><td><code><a href="#element.flastmod">flastmod</a></code></td>
+ <td>print last modification time of a file</td></tr>
+ <tr><td><code><a href="#element.include">include</a></code></td>
+ <td>include a file</td></tr>
+ <tr><td><code><a href="#element.printenv">printenv</a></code></td>
+ <td>print all available variables</td></tr>
+ <tr><td><code><a href="#element.set">set</a></code></td>
+ <td>set a value of a variable</td></tr>
+ </table>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SSILastModified" id="SSILastModified">SSILastModified</a> <a name="ssilastmodified" id="ssilastmodified">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls whether <code>Last-Modified</code> headers are generated by the
-server.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSILastModified on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSILastModified off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.2.15 and later.</td></tr>
-</table>
- <p>Under normal circumstances, a file filtered by <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
- may contain elements that are either dynamically generated, or that may
- have changed independently of the original file. As a result, by default
- the <code>Last-Modified</code> header is stripped from the response.</p>
+ <p>SSI elements may be defined by modules other than
+ <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>. In fact, the <code><a href="#element.exec">exec</a></code> element is provided by
+ <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, and will only be available if this
+ module is loaded.</p>
- <p>The <code class="directive">SSILastModified</code> directive overrides this
- behaviour, and allows the <code>Last-Modified</code> header to be respected
- if already present, or set if the header is not already present. This can
- be used to enable caching of the output. <code class="directive">SSILastModified</code>
- can take on the following values:</p>
+ <h3><a name="element.config" id="element.config">The config Element</a></h3>
+ <p>This command controls various aspects of the parsing. The
+ valid attributes are:</p>
<dl>
+ <dt><code>echomsg</code> (<em>Apache 2.1 and later</em>)</dt>
+ <dd>
+ <p>The value is a message that is sent back to the
+ client if the <code><a href="#element.echo">echo</a></code> element
+ attempts to echo an undefined variable. This overrides any <code class="directive"><a href="#ssiundefinedecho">SSIUndefinedEcho</a></code> directives.</p>
- <dt><code>off</code></dt>
- <dd>The <code>Last-Modified</code> header will be stripped from responses,
- unless the <code class="directive"><a href="#xbithack">XBitHack</a></code> directive
- is set to <code>full</code> as described below.</dd>
+ <div class="example"><p><code>
+ <!--#config echomsg="[Value Undefined]" -->
+ </code></p></div>
+ </dd>
- <dt><code>on</code></dt>
- <dd>The <code>Last-Modified</code> header will be respected if already
- present in a response, and added to the response if the response is a
- file and the header is missing. The
- <code class="directive"><a href="#ssilastmodified">SSILastModified</a></code> directive
- takes precedence over <code class="directive"><a href="#xbithack">XBitHack</a></code>.</dd>
+ <dt><code>errmsg</code></dt>
+ <dd><p>The value is a message that is sent back to the
+ client if an error occurs while parsing the
+ document. This overrides any <code class="directive"><a href="#ssierrormsg">SSIErrorMsg</a></code> directives.</p>
+
+ <div class="example"><p><code>
+ <!--#config errmsg="[Oops, something broke.]" -->
+ </code></p></div>
+ </dd>
- </dl>
+ <dt><code>sizefmt</code></dt>
+ <dd><p>The value sets the format to be used when 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, for example a size of 1024 bytes
+ will be printed as "1K".</p>
+ <div class="example"><p><code>
+ <!--#config sizefmt="abbrev" -->
+ </code></p></div>
+ </dd>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SSILegacyExprParser" id="SSILegacyExprParser">SSILegacyExprParser</a> <a name="ssilegacyexprparser" id="ssilegacyexprparser">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable compatibility mode for conditional expressions.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSILegacyExprParser on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSILegacyExprParser off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.13 and later.</td></tr>
-</table>
- <p>As of version 2.3.13, <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> has switched to the
- new <a href="../expr.html">ap_expr</a> syntax for conditional expressions
- in <code>#if</code> flow control elements. This directive allows to
- switch to the <a href="#legacyexpr">old syntax</a> which is compatible
- with Apache HTTPD version 2.2.x and earlier.
- </p>
+ <dt><code>timefmt</code></dt>
+ <dd><p>The value is a string to be used by the
+ <code>strftime(3)</code> library routine when printing
+ dates.</p>
+
+ <div class="example"><p><code>
+ <!--#config timefmt=""%R, %B %d, %Y"" -->
+ </code></p></div>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SSIStartTag" id="SSIStartTag">SSIStartTag</a> <a name="ssistarttag" id="ssistarttag">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String that starts an include element</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIStartTag <var>tag</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIStartTag "<!--#"</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
-</table>
- <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
- looks for to mark an include element to process.</p>
+ </dd>
+
+ </dl>
+
- <p>You may want to use this option if you have 2 servers parsing the
- output of a file each processing different commands (possibly at
- different times).</p>
+ <h3><a name="element.echo" id="element.echo">The echo Element</a></h3>
+ <p>This command prints one of the <a href="#includevars">include
+ variables</a> defined below. If the variable is unset, the result is
+ determined by the <code class="directive"><a href="#ssiundefinedecho">SSIUndefinedEcho</a></code> directive. Any dates printed are
+ subject to the currently configured <code>timefmt</code>.</p>
- <pre class="prettyprint lang-config"> SSIStartTag "<%"<br />
- SSIEndTag "%>"</pre>
+ <p>Attributes:</p>
+ <dl>
+ <dt><code>var</code></dt>
+ <dd>The value is the name of the variable to print.</dd>
- <p>The example given above, which also specifies a matching
- <code class="directive"><a href="#ssiendtag">SSIEndTag</a></code>, will
- allow you to use SSI directives as shown in the example
- below:</p>
+ <dt><code>decoding</code></dt>
+ <dd><p>Specifies whether Apache should strip an encoding from
+ the variable before processing the variable further. The default
+ is <code>none</code>, where no decoding will be done. If set to
+ <code>url</code>, then URL decoding (also known as %-encoding;
+ this is appropriate for use within URLs in links, etc.) will be
+ performed. If set to <code>urlencoded</code>,
+ application/x-www-form-urlencoded compatible encoding (found in
+ query strings) will be stripped. If set to <code>base64</code>,
+ base64 will be decoded, and if set to <code>entity</code>, HTML
+ entity encoding will be stripped. Decoding is done prior to any
+ further encoding on the variable. Multiple encodings can be
+ stripped by specifying more than one comma separated encoding.
+ The decoding setting will remain in effect until the next decoding
+ attribute is encountered, or the element ends.</p>
- <div class="example"><h3>SSI directives with alternate start and end tags</h3><p><code>
- <%printenv %>
- </code></p></div>
+ <p>The <code>decoding</code> attribute must <em>precede</em> the
+ corresponding <code>var</code> attribute to be effective.</p>
+ </dd>
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="#ssiendtag">SSIEndTag</a></code></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SSITimeFormat" id="SSITimeFormat">SSITimeFormat</a> <a name="ssitimeformat" id="ssitimeformat">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the format in which date strings are
-displayed</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSITimeFormat <var>formatstring</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
-</table>
-<p>This directive changes the format in which date strings are displayed
- when echoing <code>DATE</code> environment variables. The
- <var>formatstring</var> is as in <code>strftime(3)</code> from the
- C standard library.</p>
+ <dt><code>encoding</code></dt>
+ <dd><p>Specifies how Apache should encode special characters
+ contained in the variable before outputting them. If set
+ to <code>none</code>, no encoding will be done. If set to
+ <code>url</code>, then URL encoding (also known as %-encoding;
+ this is appropriate for use within URLs in links, etc.) will be
+ performed. If set to <code>urlencoded</code>,
+ application/x-www-form-urlencoded compatible encoding will be
+ performed instead, and should be used with query strings. If set
+ to <code>base64</code>, base64 encoding will be performed. At
+ the start of an <code>echo</code> element, the default is set to
+ <code>entity</code>, resulting in entity encoding (which is
+ appropriate in the context of a block-level HTML element,
+ <em>e.g.</em> 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.</p>
- <p>This directive has the same effect as the <code><!--#config
- timefmt=<var>formatstring</var> --></code> element.</p>
+ <p>The <code>encoding</code> attribute must <em>precede</em> the
+ corresponding <code>var</code> attribute to be effective.</p>
- <pre class="prettyprint lang-config">SSITimeFormat "%R, %B %d, %Y"</pre>
+ <div class="warning">
+ In order to avoid cross-site scripting issues, you should
+ <em>always</em> encode user supplied data.
+ </div>
+ <div class="example"><h3>Example</h3><p><code>
+ <!--#echo encoding="entity" var="QUERY_STRING" -->
+ </code></p></div>
+ </dd>
+ </dl>
+
- <p>The above directive would cause times to be displayed in the
- format "22:26, June 14, 2002".</p>
+ <h3><a name="element.exec" id="element.exec">The exec Element</a></h3>
+ <p>The <code>exec</code> command executes a given shell command or
+ CGI script. It requires <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code> to be present
+ in the server. If <code class="directive"><a href="../mod/core.html#options">Options</a></code>
+ <code>IncludesNOEXEC</code> is set, this command is completely
+ disabled. The valid attributes are:</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SSIUndefinedEcho" id="SSIUndefinedEcho">SSIUndefinedEcho</a> <a name="ssiundefinedecho" id="ssiundefinedecho">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String displayed when an unset variable is echoed</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIUndefinedEcho <var>string</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIUndefinedEcho "(none)"</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
-</table>
- <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
- displays when a variable is not set and "echoed".</p>
+ <dl>
+ <dt><code>cgi</code></dt>
+ <dd><p>The value specifies a (%-encoded) URL-path to
+ the CGI script. If the path does not begin with a slash (/),
+ 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 <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
+ or <code class="directive"><a href="../mod/core.html#options">Options</a></code>
+ <code>ExecCGI</code>).</p>
- <pre class="prettyprint lang-config">SSIUndefinedEcho "<!-- undef -->"</pre>
+ <p>The CGI script is given the <code>PATH_INFO</code> and query
+ string (<code>QUERY_STRING</code>) of the original request from the
+ client; these <em>cannot</em> 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>
+ <div class="example"><h3>Example</h3><p><code>
+ <!--#exec cgi="/cgi-bin/example.cgi" -->
+ </code></p></div>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="XBitHack" id="XBitHack">XBitHack</a> <a name="xbithack" id="xbithack">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Parse SSI directives in files with the execute bit
-set</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>XBitHack on|off|full</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>XBitHack off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
-</table>
- <p>The <code class="directive">XBitHack</code> directive controls the parsing
- of ordinary html documents. This directive only affects files associated
- with the <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> <code>text/html</code>. <code class="directive">XBitHack</code> can take on the following values:</p>
+ <p>If the script returns a <code>Location:</code> header instead of
+ output, then this will be translated into an HTML anchor.</p>
- <dl>
- <dt><code>off</code></dt>
- <dd>No special treatment of executable files.</dd>
+ <p>The <code><a href="#includevirtual">include virtual</a></code>
+ element should be used in preference to <code>exec cgi</code>. In
+ particular, if you need to pass additional arguments to a CGI program,
+ using the query string, this cannot be done with <code>exec
+ cgi</code>, but can be done with <code>include virtual</code>, as
+ shown here:</p>
- <dt><code>on</code></dt>
- <dd>Any <code>text/html</code> file that has the user-execute bit
- set will be treated as a server-parsed html document.</dd>
+ <div class="example"><p><code>
+ <!--#include virtual="/cgi-bin/example.cgi?argument=value" -->
+ </code></p></div>
+ </dd>
- <dt><code>full</code></dt>
- <dd>As for <code>on</code> but also test the group-execute bit.
- If it is set, then set the <code>Last-modified</code> 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.
+ <dt><code>cmd</code></dt>
+ <dd><p>The server will execute the given string using
+ <code>/bin/sh</code>. The <a href="#includevars">include variables</a> are available to the command, in addition
+ to the usual set of CGI variables.</p>
- <div class="note"><h3>Note</h3>
- <p>You would not want to use the full option, unless you assure the
- group-execute bit is unset for every SSI script which might <code>#include</code> a CGI or otherwise produces different output on
- each hit (or could potentially change on subsequent requests).</p>
+ <p>The use of <code><a href="#includevirtual">#include virtual</a></code> is almost always prefered to using
+ either <code>#exec cgi</code> or <code>#exec cmd</code>. The former
+ (<code>#include virtual</code>) uses the standard Apache sub-request
+ mechanism to include files or scripts. It is much better tested and
+ maintained.</p>
- <p>The <code class="directive"><a href="#ssilastmodified">SSILastModified</a></code>
- directive takes precedence over the
- <code class="directive"><a href="#xbithack">XBitHack</a></code> directive when
- <code class="directive"><a href="#ssilastmodified">SSILastModified</a></code> is set to
- <code>on</code>.</p>
- </div>
+ <p>In addition, on some platforms, like Win32, and on unix when
+ using <a href="../suexec.html">suexec</a>, you cannot pass arguments
+ to a command in an <code>exec</code> directive, or otherwise include
+ spaces in the command. Thus, while the following will work under a
+ non-suexec configuration on unix, it will not produce the desired
+ result under Win32, or when running suexec:</p>
+ <div class="example"><p><code>
+ <!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->
+ </code></p></div>
</dd>
- </dl>
-
+ </dl>
+
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="enabling" id="enabling">Enabling Server-Side Includes</a></h2>
-
+ <h3><a name="element.fsize" id="element.fsize">The fsize Element</a></h3>
+ <p>This command prints the size of the specified file, subject
+ to the <code>sizefmt</code> format specification. Attributes:</p>
- <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>
+ <dl>
+ <dt><code>file</code></dt>
+ <dd>The value is a path relative to the directory
+ containing the current document being parsed.
- <pre class="prettyprint lang-config">AddType text/html .shtml
-AddOutputFilter INCLUDES .shtml</pre>
+ <div class="example"><p><code>
+ This file is <!--#fsize file="mod_include.html" --> bytes.
+ </code></p></div>
+ The value of <code>file</code> cannot start with a slash
+ (<code>/</code>), nor can it contain <code>../</code> so as to
+ refer to a file above the current directory or outside of the
+ document root. Attempting to so will result in the error message:
+ <code>The given path was above the root path</code>.
+ </dd>
- <p>The following directive must be given for the directories
- containing the shtml files (typically in a
- <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section,
- but this directive is also valid in <code>.htaccess</code> files if
- <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> <code>Options</code>
- is set):</p>
-
- <pre class="prettyprint lang-config">Options +Includes</pre>
-
-
- <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>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="pathinfo" id="pathinfo">PATH_INFO with Server Side Includes</a></h2>
-
-
- <p>Files processed for server-side includes no longer accept
- requests with <code>PATH_INFO</code> (trailing pathname information)
- by default. You can use the <code class="directive"><a href="../mod/core.html#acceptpathinfo">AcceptPathInfo</a></code> directive to
- configure the server to accept requests with <code>PATH_INFO</code>.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="elements" id="elements">Available Elements</a></h2>
- <p>The document is parsed as an HTML document, with special
- commands embedded as SGML comments. A command has the syntax: </p>
+ <dt><code>virtual</code></dt>
+ <dd>The value is a (%-encoded) URL-path. If it does not begin with
+ a slash (/) then it is taken to be relative to the current document.
+ Note, that this does <em>not</em> print the size of any CGI output,
+ but the size of the CGI script itself.</dd>
+ </dl>
<div class="example"><p><code>
- <!--#<var>element</var> <var>attribute</var>=<var>value</var>
- <var>attribute</var>=<var>value</var> ... -->
+ This file is <!--#fsize virtual="/docs/mod/mod_include.html" --> bytes.
</code></p></div>
- <p>The value will often be enclosed in double quotes, but single
- quotes (<code>'</code>) and backticks (<code>`</code>) are also
- possible. Many commands only allow a single attribute-value pair.
- Note that the comment terminator (<code>--></code>) should be
- preceded by whitespace to ensure that it isn't considered part of
- an SSI token. Note that the leading <code><!--#</code> is <em>one</em>
- token and may not contain any whitespaces.</p>
-
- <p>The allowed elements are listed in the following table:</p>
+ <p>Note that in many cases these two are exactly the same thing.
+ However, the <code>file</code> attribute doesn't respect URL-space
+ aliases.</p>
+
- <table class="bordered">
- <tr><th>Element</th><th>Description</th></tr>
- <tr><td><code><a href="#element.config">config</a></code></td>
- <td>configure output formats</td></tr>
- <tr><td><code><a href="#element.echo">echo</a></code></td>
- <td>print variables</td></tr>
- <tr><td><code><a href="#element.exec">exec</a></code></td>
- <td>execute external programs</td></tr>
- <tr><td><code><a href="#element.fsize">fsize</a></code></td>
- <td>print size of a file</td></tr>
- <tr><td><code><a href="#element.flastmod">flastmod</a></code></td>
- <td>print last modification time of a file</td></tr>
- <tr><td><code><a href="#element.include">include</a></code></td>
- <td>include a file</td></tr>
- <tr><td><code><a href="#element.printenv">printenv</a></code></td>
- <td>print all available variables</td></tr>
- <tr><td><code><a href="#element.set">set</a></code></td>
- <td>set a value of a variable</td></tr>
- </table>
+ <h3><a name="element.flastmod" id="element.flastmod">The flastmod Element</a></h3>
+ <p>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><a href="#element.fsize">fsize</a></code> command.</p>
+
- <p>SSI elements may be defined by modules other than
- <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>. In fact, the <code><a href="#element.exec">exec</a></code> element is provided by
- <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, and will only be available if this
- module is loaded.</p>
+ <h3><a name="element.include" id="element.include">The include Element</a></h3>
+ <p>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
+ <a href="core.html#options">Options</a>
+ <code>IncludesNOEXEC</code> set, then only documents with a text
+ <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> (<code>text/plain</code>,
+ <code>text/html</code> etc.) will be included. Otherwise CGI
+ scripts are invoked as normal using the complete URL given in
+ the command, including any query string.</p>
- <h3><a name="element.config" id="element.config">The config Element</a></h3>
- <p>This command controls various aspects of the parsing. The
- valid attributes are:</p>
+ <p>An attribute defines the location of the document, and may
+ appear more than once in an include element; an inclusion is
+ done for each attribute given to the include command in turn.
+ The valid attributes are:</p>
<dl>
- <dt><code>echomsg</code> (<em>Apache 2.1 and later</em>)</dt>
- <dd>
- <p>The value is a message that is sent back to the
- client if the <code><a href="#element.echo">echo</a></code> element
- attempts to echo an undefined variable. This overrides any <code class="directive"><a href="#ssiundefinedecho">SSIUndefinedEcho</a></code> directives.</p>
+ <dt><code>file</code></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.
+ Therefore, you cannot include files that are outside of the
+ document root, or above the current document in the directory
+ structure. The <code>virtual</code> attribute should always be
+ used in preference to this one.</dd>
- <div class="example"><p><code>
- <!--#config echomsg="[Value Undefined]" -->
- </code></p></div>
- </dd>
+ <dt><code><a id="includevirtual" name="includevirtual">virtual</a></code></dt>
+ <dd><p>The value is a (%-encoded) URL-path. 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.</p>
+
+ <p>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.</p>
+
+ <p>If the specified URL is a CGI program, the program will be
+ executed and its output inserted in place of the directive in the
+ parsed file. You may include a query string in a CGI url:</p>
- <dt><code>errmsg</code></dt>
- <dd><p>The value is a message that is sent back to the
- client if an error occurs while parsing the
- document. This overrides any <code class="directive"><a href="#ssierrormsg">SSIErrorMsg</a></code> directives.</p>
-
<div class="example"><p><code>
- <!--#config errmsg="[Oops, something broke.]" -->
+ <!--#include virtual="/cgi-bin/example.cgi?argument=value" -->
</code></p></div>
+
+ <p><code>include virtual</code> should be used in preference
+ to <code>exec cgi</code> to include the output of CGI programs
+ into an HTML document.</p>
+
+ <p>If the <code class="directive"><a href="../mod/mod_request.html#keptbodysize">KeptBodySize</a></code>
+ directive is correctly configured and valid for this included
+ file, attempts to POST requests to the enclosing HTML document
+ will be passed through to subrequests as POST requests as well.
+ Without the directive, all subrequests are processed as GET
+ requests.</p>
+
</dd>
- <dt><code>sizefmt</code></dt>
- <dd><p>The value sets the format to be used when 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, for example a size of 1024 bytes
- will be printed as "1K".</p>
+ <dt><code>onerror</code></dt>
+ <dd><p>The value is a (%-encoded) URL-path which is shown should a
+ previous attempt to include a file or virtual attribute failed.
+ To be effective, this attribute must be specified after the
+ file or virtual attributes being covered. If the attempt to
+ include the onerror path fails, or if onerror is not specified, the
+ default error message will be included.</p>
<div class="example"><p><code>
- <!--#config sizefmt="abbrev" -->
+ # Simple example<br />
+ <!--#include virtual="/not-exist.html" onerror="/error.html" -->
</code></p></div>
- </dd>
- <dt><code>timefmt</code></dt>
- <dd><p>The value is a string to be used by the
- <code>strftime(3)</code> library routine when printing
- dates.</p>
-
<div class="example"><p><code>
- <!--#config timefmt=""%R, %B %d, %Y"" -->
+ # Dedicated onerror paths<br />
+ <!--#include virtual="/path-a.html" onerror="/error-a.html" virtual="/path-b.html" onerror="/error-b.html" -->
</code></p></div>
</dd>
-
</dl>
- <h3><a name="element.echo" id="element.echo">The echo Element</a></h3>
- <p>This command prints one of the <a href="#includevars">include
- variables</a> defined below. If the variable is unset, the result is
- determined by the <code class="directive"><a href="#ssiundefinedecho">SSIUndefinedEcho</a></code> directive. Any dates printed are
- subject to the currently configured <code>timefmt</code>.</p>
+ <h3><a name="element.printenv" id="element.printenv">The printenv Element</a></h3>
+ <p>This prints out a plain text listing of all existing variables and
+ their values. Special characters are entity encoded (see the <code><a href="#element.echo">echo</a></code> element for details)
+ before being output. There are no attributes.</p>
- <p>Attributes:</p>
+ <div class="example"><h3>Example</h3><p><code>
+ <pre>
+ <!--#printenv -->
+ </pre>
+ </code></p></div>
+
+
+ <h3><a name="element.set" id="element.set">The set Element</a></h3>
+ <p>This sets the value of a variable. Attributes:</p>
<dl>
<dt><code>var</code></dt>
- <dd>The value is the name of the variable to print.</dd>
+ <dd>The name of the variable to set.</dd>
+
+ <dt><code>value</code></dt>
+ <dd>The value to give a variable.</dd>
<dt><code>decoding</code></dt>
<dd><p>Specifies whether Apache should strip an encoding from
the variable before processing the variable further. The default
is <code>none</code>, where no decoding will be done. If set to
- <code>url</code>, then URL decoding (also known as %-encoding;
- this is appropriate for use within URLs in links, etc.) will be
- performed. If set to <code>urlencoded</code>,
- application/x-www-form-urlencoded compatible encoding (found in
- query strings) will be stripped. If set to <code>base64</code>,
- base64 will be decoded, and if set to <code>entity</code>, HTML
- entity encoding will be stripped. Decoding is done prior to any
- further encoding on the variable. Multiple encodings can be
- stripped by specifying more than one comma separated encoding.
- The decoding setting will remain in effect until the next decoding
- attribute is encountered, or the element ends.</p>
-
- <p>The <code>decoding</code> attribute must <em>precede</em> the
- corresponding <code>var</code> attribute to be effective.</p>
+ <code>url</code>, <code>urlencoded</code>, <code>base64</code>
+ or <code>entity</code>, URL decoding,
+ application/x-www-form-urlencoded decoding, base64 decoding or HTML
+ entity decoding will be performed respectively. More than one
+ decoding can be specified by separating with commas. The decoding
+ setting will remain in effect until the next decoding attribute
+ is encountered, or the element ends. The <code>decoding</code>
+ attribute must <em>precede</em> the corresponding
+ <code>var</code> attribute to be effective.</p>
</dd>
<dt><code>encoding</code></dt>
<dd><p>Specifies how Apache should encode special characters
- contained in the variable before outputting them. If set
- to <code>none</code>, no encoding will be done. If set to
- <code>url</code>, then URL encoding (also known as %-encoding;
- this is appropriate for use within URLs in links, etc.) will be
- performed. If set to <code>urlencoded</code>,
- application/x-www-form-urlencoded compatible encoding will be
- performed instead, and should be used with query strings. If set
- to <code>base64</code>, base64 encoding will be performed. At
- the start of an <code>echo</code> element, the default is set to
- <code>entity</code>, resulting in entity encoding (which is
- appropriate in the context of a block-level HTML element,
- <em>e.g.</em> 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.</p>
-
- <p>The <code>encoding</code> attribute must <em>precede</em> the
- corresponding <code>var</code> attribute to be effective.</p>
-
- <div class="warning">
- In order to avoid cross-site scripting issues, you should
- <em>always</em> encode user supplied data.
- </div>
-
- <div class="example"><h3>Example</h3><p><code>
- <!--#echo encoding="entity" var="QUERY_STRING" -->
- </code></p></div>
- </dd>
- </dl>
-
-
- <h3><a name="element.exec" id="element.exec">The exec Element</a></h3>
- <p>The <code>exec</code> command executes a given shell command or
- CGI script. It requires <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code> to be present
- in the server. If <code class="directive"><a href="../mod/core.html#options">Options</a></code>
- <code>IncludesNOEXEC</code> is set, this command is completely
- disabled. The valid attributes are:</p>
-
- <dl>
- <dt><code>cgi</code></dt>
- <dd><p>The value specifies a (%-encoded) URL-path to
- the CGI script. If the path does not begin with a slash (/),
- 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 <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
- or <code class="directive"><a href="../mod/core.html#options">Options</a></code>
- <code>ExecCGI</code>).</p>
-
- <p>The CGI script is given the <code>PATH_INFO</code> and query
- string (<code>QUERY_STRING</code>) of the original request from the
- client; these <em>cannot</em> 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>
-
- <div class="example"><h3>Example</h3><p><code>
- <!--#exec cgi="/cgi-bin/example.cgi" -->
- </code></p></div>
-
- <p>If the script returns a <code>Location:</code> header instead of
- output, then this will be translated into an HTML anchor.</p>
-
- <p>The <code><a href="#includevirtual">include virtual</a></code>
- element should be used in preference to <code>exec cgi</code>. In
- particular, if you need to pass additional arguments to a CGI program,
- using the query string, this cannot be done with <code>exec
- cgi</code>, but can be done with <code>include virtual</code>, as
- shown here:</p>
-
- <div class="example"><p><code>
- <!--#include virtual="/cgi-bin/example.cgi?argument=value" -->
- </code></p></div>
- </dd>
-
- <dt><code>cmd</code></dt>
- <dd><p>The server will execute the given string using
- <code>/bin/sh</code>. The <a href="#includevars">include variables</a> are available to the command, in addition
- to the usual set of CGI variables.</p>
-
- <p>The use of <code><a href="#includevirtual">#include virtual</a></code> is almost always prefered to using
- either <code>#exec cgi</code> or <code>#exec cmd</code>. The former
- (<code>#include virtual</code>) uses the standard Apache sub-request
- mechanism to include files or scripts. It is much better tested and
- maintained.</p>
-
- <p>In addition, on some platforms, like Win32, and on unix when
- using <a href="../suexec.html">suexec</a>, you cannot pass arguments
- to a command in an <code>exec</code> directive, or otherwise include
- spaces in the command. Thus, while the following will work under a
- non-suexec configuration on unix, it will not produce the desired
- result under Win32, or when running suexec:</p>
-
- <div class="example"><p><code>
- <!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->
- </code></p></div>
- </dd>
- </dl>
-
-
- <h3><a name="element.fsize" id="element.fsize">The fsize Element</a></h3>
- <p>This command prints the size of the specified file, subject
- to the <code>sizefmt</code> format specification. Attributes:</p>
-
- <dl>
- <dt><code>file</code></dt>
- <dd>The value is a path relative to the directory
- containing the current document being parsed.
-
- <div class="example"><p><code>
- This file is <!--#fsize file="mod_include.html" --> bytes.
- </code></p></div>
-
- The value of <code>file</code> cannot start with a slash
- (<code>/</code>), nor can it contain <code>../</code> so as to
- refer to a file above the current directory or outside of the
- document root. Attempting to so will result in the error message:
- <code>The given path was above the root path</code>.
- </dd>
-
- <dt><code>virtual</code></dt>
- <dd>The value is a (%-encoded) URL-path. If it does not begin with
- a slash (/) then it is taken to be relative to the current document.
- Note, that this does <em>not</em> print the size of any CGI output,
- but the size of the CGI script itself.</dd>
- </dl>
-
- <div class="example"><p><code>
- This file is <!--#fsize virtual="/docs/mod/mod_include.html" --> bytes.
- </code></p></div>
-
- <p>Note that in many cases these two are exactly the same thing.
- However, the <code>file</code> attribute doesn't respect URL-space
- aliases.</p>
-
-
- <h3><a name="element.flastmod" id="element.flastmod">The flastmod Element</a></h3>
- <p>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><a href="#element.fsize">fsize</a></code> command.</p>
-
-
- <h3><a name="element.include" id="element.include">The include Element</a></h3>
- <p>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
- <a href="core.html#options">Options</a>
- <code>IncludesNOEXEC</code> set, then only documents with a text
- <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> (<code>text/plain</code>,
- <code>text/html</code> etc.) will be included. Otherwise CGI
- scripts are invoked as normal using the complete URL given in
- the command, including any query string.</p>
-
- <p>An attribute defines the location of the document, and may
- appear more than once in an include element; an inclusion is
- done for each attribute given to the include command in turn.
- The valid attributes are:</p>
-
- <dl>
- <dt><code>file</code></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.
- Therefore, you cannot include files that are outside of the
- document root, or above the current document in the directory
- structure. The <code>virtual</code> attribute should always be
- used in preference to this one.</dd>
-
- <dt><code><a id="includevirtual" name="includevirtual">virtual</a></code></dt>
- <dd><p>The value is a (%-encoded) URL-path. 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.</p>
-
- <p>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.</p>
-
- <p>If the specified URL is a CGI program, the program will be
- executed and its output inserted in place of the directive in the
- parsed file. You may include a query string in a CGI url:</p>
-
- <div class="example"><p><code>
- <!--#include virtual="/cgi-bin/example.cgi?argument=value" -->
- </code></p></div>
-
- <p><code>include virtual</code> should be used in preference
- to <code>exec cgi</code> to include the output of CGI programs
- into an HTML document.</p>
-
- <p>If the <code class="directive"><a href="../mod/mod_request.html#keptbodysize">KeptBodySize</a></code>
- directive is correctly configured and valid for this included
- file, attempts to POST requests to the enclosing HTML document
- will be passed through to subrequests as POST requests as well.
- Without the directive, all subrequests are processed as GET
- requests.</p>
-
- </dd>
-
- <dt><code>onerror</code></dt>
- <dd><p>The value is a (%-encoded) URL-path which is shown should a
- previous attempt to include a file or virtual attribute failed.
- To be effective, this attribute must be specified after the
- file or virtual attributes being covered. If the attempt to
- include the onerror path fails, or if onerror is not specified, the
- default error message will be included.</p>
-
- <div class="example"><p><code>
- # Simple example<br />
- <!--#include virtual="/not-exist.html" onerror="/error.html" -->
- </code></p></div>
-
- <div class="example"><p><code>
- # Dedicated onerror paths<br />
- <!--#include virtual="/path-a.html" onerror="/error-a.html" virtual="/path-b.html" onerror="/error-b.html" -->
- </code></p></div>
-
- </dd>
- </dl>
-
-
- <h3><a name="element.printenv" id="element.printenv">The printenv Element</a></h3>
- <p>This prints out a plain text listing of all existing variables and
- their values. Special characters are entity encoded (see the <code><a href="#element.echo">echo</a></code> element for details)
- before being output. There are no attributes.</p>
-
- <div class="example"><h3>Example</h3><p><code>
- <pre>
- <!--#printenv -->
- </pre>
- </code></p></div>
-
-
- <h3><a name="element.set" id="element.set">The set Element</a></h3>
- <p>This sets the value of a variable. Attributes:</p>
-
- <dl>
- <dt><code>var</code></dt>
- <dd>The name of the variable to set.</dd>
-
- <dt><code>value</code></dt>
- <dd>The value to give a variable.</dd>
-
- <dt><code>decoding</code></dt>
- <dd><p>Specifies whether Apache should strip an encoding from
- the variable before processing the variable further. The default
- is <code>none</code>, where no decoding will be done. If set to
- <code>url</code>, <code>urlencoded</code>, <code>base64</code>
- or <code>entity</code>, URL decoding,
- application/x-www-form-urlencoded decoding, base64 decoding or HTML
- entity decoding will be performed respectively. More than one
- decoding can be specified by separating with commas. The decoding
- setting will remain in effect until the next decoding attribute
- is encountered, or the element ends. The <code>decoding</code>
- attribute must <em>precede</em> the corresponding
- <code>var</code> attribute to be effective.</p>
- </dd>
-
- <dt><code>encoding</code></dt>
- <dd><p>Specifies how Apache should encode special characters
- contained in the variable before setting them. The default is
- <code>none</code>, where no encoding will be done. If set to
- <code>url</code>, <code>urlencoding</code>, <code>base64</code>
- or <code>entity</code>, URL encoding,
- application/x-www-form-urlencoded encoding, base64 encoding or
- HTML entity encoding will be performed respectively. More than
- one encoding can be specified by separating with commas. The
- encoding setting will remain in effect until the next encoding
- attribute is encountered, or the element ends. The
- <code>encoding</code> attribute must <em>precede</em> the
- corresponding <code>var</code> attribute to be effective.
- Encodings are applied after all decodings have been
- stripped.</p>
- </dd>
- </dl>
+ contained in the variable before setting them. The default is
+ <code>none</code>, where no encoding will be done. If set to
+ <code>url</code>, <code>urlencoding</code>, <code>base64</code>
+ or <code>entity</code>, URL encoding,
+ application/x-www-form-urlencoded encoding, base64 encoding or
+ HTML entity encoding will be performed respectively. More than
+ one encoding can be specified by separating with commas. The
+ encoding setting will remain in effect until the next encoding
+ attribute is encountered, or the element ends. The
+ <code>encoding</code> attribute must <em>precede</em> the
+ corresponding <code>var</code> attribute to be effective.
+ Encodings are applied after all decodings have been
+ stripped.</p>
+ </dd>
+ </dl>
<div class="example"><h3>Example</h3><p><code>
<!--#set var="category" value="help" -->
be escaped. This is regardless of their meaning to the regex engine.</p>
</div>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SSIEndTag" id="SSIEndTag">SSIEndTag</a> <a name="ssiendtag" id="ssiendtag">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String that ends an include element</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIEndTag <var>tag</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIEndTag "-->"</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
+</table>
+ <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
+ looks for to mark the end of an include element.</p>
+
+ <pre class="prettyprint lang-config">SSIEndTag "%>"</pre>
+
+
+
+<h3>See also</h3>
+<ul>
+<li><code class="directive"><a href="#ssistarttag">SSIStartTag</a></code></li>
+</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SSIErrorMsg" id="SSIErrorMsg">SSIErrorMsg</a> <a name="ssierrormsg" id="ssierrormsg">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Error message displayed when there is an SSI
+error</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIErrorMsg <var>message</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIErrorMsg "[an error occurred while processing this
+directive]"</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
+</table>
+ <p>The <code class="directive">SSIErrorMsg</code> directive changes the error
+ message displayed when <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> encounters an
+ error. For production servers you may consider changing the default
+ error message to <code>"<!-- Error -->"</code> so that
+ the message is not presented to the user.</p>
+
+ <p>This directive has the same effect as the <code><!--#config
+ errmsg=<var>message</var> --></code> element.</p>
+
+ <pre class="prettyprint lang-config">SSIErrorMsg "<!-- Error -->"</pre>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SSIETag" id="SSIETag">SSIETag</a> <a name="ssietag" id="ssietag">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls whether ETags are generated by the server.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIETag on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIETag off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.2.15 and later.</td></tr>
+</table>
+ <p>Under normal circumstances, a file filtered by <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
+ may contain elements that are either dynamically generated, or that may
+ have changed independently of the original file. As a result, by default
+ the server is asked not to generate an <code>ETag</code> header for the
+ response by adding <code>no-etag</code> to the request notes.</p>
+
+ <p>The <code class="directive">SSIETag</code> directive suppresses this
+ behaviour, and allows the server to generate an <code>ETag</code> header.
+ This can be used to enable caching of the output. Note that a backend server
+ or dynamic content generator may generate an ETag of its own, ignoring
+ <code>no-etag</code>, and this ETag will be passed by
+ <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> regardless of the value of this setting.
+ <code class="directive">SSIETag</code> can take on the following values:</p>
+
+ <dl>
+
+ <dt><code>off</code></dt>
+ <dd><code>no-etag</code> will be added to the request notes, and the server
+ is asked not to generate an ETag. Where a server ignores the value of
+ <code>no-etag</code> and generates an ETag anyway, the ETag will be
+ respected.</dd>
+
+ <dt><code>on</code></dt>
+ <dd>Existing ETags will be respected, and ETags generated by the server will
+ be passed on in the response.</dd>
+
+ </dl>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SSILastModified" id="SSILastModified">SSILastModified</a> <a name="ssilastmodified" id="ssilastmodified">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls whether <code>Last-Modified</code> headers are generated by the
+server.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSILastModified on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSILastModified off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.2.15 and later.</td></tr>
+</table>
+ <p>Under normal circumstances, a file filtered by <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
+ may contain elements that are either dynamically generated, or that may
+ have changed independently of the original file. As a result, by default
+ the <code>Last-Modified</code> header is stripped from the response.</p>
+
+ <p>The <code class="directive">SSILastModified</code> directive overrides this
+ behaviour, and allows the <code>Last-Modified</code> header to be respected
+ if already present, or set if the header is not already present. This can
+ be used to enable caching of the output. <code class="directive">SSILastModified</code>
+ can take on the following values:</p>
+
+ <dl>
+
+ <dt><code>off</code></dt>
+ <dd>The <code>Last-Modified</code> header will be stripped from responses,
+ unless the <code class="directive"><a href="#xbithack">XBitHack</a></code> directive
+ is set to <code>full</code> as described below.</dd>
+
+ <dt><code>on</code></dt>
+ <dd>The <code>Last-Modified</code> header will be respected if already
+ present in a response, and added to the response if the response is a
+ file and the header is missing. The
+ <code class="directive"><a href="#ssilastmodified">SSILastModified</a></code> directive
+ takes precedence over <code class="directive"><a href="#xbithack">XBitHack</a></code>.</dd>
+
+ </dl>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SSILegacyExprParser" id="SSILegacyExprParser">SSILegacyExprParser</a> <a name="ssilegacyexprparser" id="ssilegacyexprparser">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable compatibility mode for conditional expressions.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSILegacyExprParser on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSILegacyExprParser off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.13 and later.</td></tr>
+</table>
+ <p>As of version 2.3.13, <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> has switched to the
+ new <a href="../expr.html">ap_expr</a> syntax for conditional expressions
+ in <code>#if</code> flow control elements. This directive allows to
+ switch to the <a href="#legacyexpr">old syntax</a> which is compatible
+ with Apache HTTPD version 2.2.x and earlier.
+ </p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SSIStartTag" id="SSIStartTag">SSIStartTag</a> <a name="ssistarttag" id="ssistarttag">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String that starts an include element</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIStartTag <var>tag</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIStartTag "<!--#"</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
+</table>
+ <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
+ looks for to mark an include element to process.</p>
+
+ <p>You may want to use this option if you have 2 servers parsing the
+ output of a file each processing different commands (possibly at
+ different times).</p>
+
+ <pre class="prettyprint lang-config"> SSIStartTag "<%"<br />
+ SSIEndTag "%>"</pre>
+
+
+ <p>The example given above, which also specifies a matching
+ <code class="directive"><a href="#ssiendtag">SSIEndTag</a></code>, will
+ allow you to use SSI directives as shown in the example
+ below:</p>
+
+ <div class="example"><h3>SSI directives with alternate start and end tags</h3><p><code>
+ <%printenv %>
+ </code></p></div>
+
+<h3>See also</h3>
+<ul>
+<li><code class="directive"><a href="#ssiendtag">SSIEndTag</a></code></li>
+</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SSITimeFormat" id="SSITimeFormat">SSITimeFormat</a> <a name="ssitimeformat" id="ssitimeformat">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the format in which date strings are
+displayed</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSITimeFormat <var>formatstring</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
+</table>
+<p>This directive changes the format in which date strings are displayed
+ when echoing <code>DATE</code> environment variables. The
+ <var>formatstring</var> is as in <code>strftime(3)</code> from the
+ C standard library.</p>
+
+ <p>This directive has the same effect as the <code><!--#config
+ timefmt=<var>formatstring</var> --></code> element.</p>
+
+ <pre class="prettyprint lang-config">SSITimeFormat "%R, %B %d, %Y"</pre>
+
+
+ <p>The above directive would cause times to be displayed in the
+ format "22:26, June 14, 2002".</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SSIUndefinedEcho" id="SSIUndefinedEcho">SSIUndefinedEcho</a> <a name="ssiundefinedecho" id="ssiundefinedecho">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String displayed when an unset variable is echoed</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIUndefinedEcho <var>string</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIUndefinedEcho "(none)"</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
+</table>
+ <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
+ displays when a variable is not set and "echoed".</p>
+
+ <pre class="prettyprint lang-config">SSIUndefinedEcho "<!-- undef -->"</pre>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="XBitHack" id="XBitHack">XBitHack</a> <a name="xbithack" id="xbithack">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Parse SSI directives in files with the execute bit
+set</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>XBitHack on|off|full</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>XBitHack off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
+</table>
+ <p>The <code class="directive">XBitHack</code> directive controls the parsing
+ of ordinary html documents. This directive only affects files associated
+ with the <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> <code>text/html</code>. <code class="directive">XBitHack</code> can take on the following values:</p>
+
+ <dl>
+ <dt><code>off</code></dt>
+ <dd>No special treatment of executable files.</dd>
+
+ <dt><code>on</code></dt>
+ <dd>Any <code>text/html</code> file that has the user-execute bit
+ set will be treated as a server-parsed html document.</dd>
+
+ <dt><code>full</code></dt>
+ <dd>As for <code>on</code> but also test the group-execute bit.
+ If it is set, then set the <code>Last-modified</code> 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.
+
+ <div class="note"><h3>Note</h3>
+ <p>You would not want to use the full option, unless you assure the
+ group-execute bit is unset for every SSI script which might <code>#include</code> a CGI or otherwise produces different output on
+ each hit (or could potentially change on subsequent requests).</p>
+
+ <p>The <code class="directive"><a href="#ssilastmodified">SSILastModified</a></code>
+ directive takes precedence over the
+ <code class="directive"><a href="#xbithack">XBitHack</a></code> directive when
+ <code class="directive"><a href="#ssilastmodified">SSILastModified</a></code> is set to
+ <code>on</code>.</p>
+ </div>
+
+ </dd>
+ </dl>
+
+
</div>
</div>
<div class="bottomlang">
<p>Once configured, the server information is obtained by
accessing <code>http://your.host.example.com/server-info</code></p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#addmoduleinfo">AddModuleInfo</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#security">Security Issues</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#queries">Selecting the information shown</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#startup">Dumping the configuration on startup</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#limitations">Known Limitations</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AddModuleInfo" id="AddModuleInfo">AddModuleInfo</a> <a name="addmoduleinfo" id="addmoduleinfo">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adds additional information to the module
-information displayed by the server-info handler</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AddModuleInfo <var>module-name</var> <var>string</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_info</td></tr>
-</table>
- <p>This allows the content of <var>string</var> to be shown as
- HTML interpreted, <strong>Additional Information</strong> for
- the module <var>module-name</var>. Example:</p>
-
- <pre class="prettyprint lang-config">AddModuleInfo mod_deflate.c 'See <a \
- href="http://httpd.apache.org/docs/2.4/mod/mod_deflate.html">\
- http://httpd.apache.org/docs/2.4/mod/mod_deflate.html</a>'</pre>
-
-
-</div>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#addmoduleinfo">AddModuleInfo</a></li>
+</ul>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="security" id="security">Security Issues</a></h2>
<li>Directives generated by third party modules such as <a href="http://perl.apache.org">mod_perl</a>
might not be listed.</li>
</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AddModuleInfo" id="AddModuleInfo">AddModuleInfo</a> <a name="addmoduleinfo" id="addmoduleinfo">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adds additional information to the module
+information displayed by the server-info handler</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AddModuleInfo <var>module-name</var> <var>string</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_info</td></tr>
+</table>
+ <p>This allows the content of <var>string</var> to be shown as
+ HTML interpreted, <strong>Additional Information</strong> for
+ the module <var>module-name</var>. Example:</p>
+
+ <pre class="prettyprint lang-config">AddModuleInfo mod_deflate.c 'See <a \
+ href="http://httpd.apache.org/docs/2.4/mod/mod_deflate.html">\
+ http://httpd.apache.org/docs/2.4/mod/mod_deflate.html</a>'</pre>
+
+
</div>
</div>
<div class="bottomlang">
extension. <strong>Please <em>do not</em> post such problems to
Apache's lists or bug reporting pages.</strong></p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#notes">Additional Notes</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#journal">Programmer's Journal</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#isapiappendlogtoerrors">ISAPIAppendLogToErrors</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#isapiappendlogtoquery">ISAPIAppendLogToQuery</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#isapilognotsupported">ISAPILogNotSupported</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#isapireadaheadbuffer">ISAPIReadAheadBuffer</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#notes">Additional Notes</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#journal">Programmer's Journal</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ISAPIAppendLogToErrors" id="ISAPIAppendLogToErrors">ISAPIAppendLogToErrors</a> <a name="isapiappendlogtoerrors" id="isapiappendlogtoerrors">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from
-ISAPI extensions to the error log</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPIAppendLogToErrors on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPIAppendLogToErrors off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
-</table>
- <p>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from ISAPI
- extensions to the server error log.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ISAPIAppendLogToQuery" id="ISAPIAppendLogToQuery">ISAPIAppendLogToQuery</a> <a name="isapiappendlogtoquery" id="isapiappendlogtoquery">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from
-ISAPI extensions to the query field</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPIAppendLogToQuery on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPIAppendLogToQuery on</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
-</table>
- <p>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from ISAPI
- extensions to the query field (appended to the <code class="directive"><a href="../mod/mod_log_config.html#customlog">CustomLog</a></code> <code>%q</code>
- component).</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ISAPICacheFile" id="ISAPICacheFile">ISAPICacheFile</a> <a name="isapicachefile" id="isapicachefile">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>ISAPI .dll files to be loaded at startup</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPICacheFile <var>file-path</var> [<var>file-path</var>]
-...</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
-</table>
- <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. If the path name is not absolute, it will be treated
- relative to <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ISAPIFakeAsync" id="ISAPIFakeAsync">ISAPIFakeAsync</a> <a name="isapifakeasync" id="isapifakeasync">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fake asynchronous support for ISAPI callbacks</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPIFakeAsync on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPIFakeAsync off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
-</table>
- <p>While set to on, asynchronous support for ISAPI callbacks is
- simulated.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ISAPILogNotSupported" id="ISAPILogNotSupported">ISAPILogNotSupported</a> <a name="isapilognotsupported" id="isapilognotsupported">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Log unsupported feature requests from ISAPI
-extensions</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPILogNotSupported on|off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPILogNotSupported off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
-</table>
- <p>Logs all requests for unsupported features from ISAPI
- extensions in the server error log. This may help administrators
- to track down problems. Once set to on and all desired ISAPI modules
- are functioning, it should be set back to off.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ISAPIReadAheadBuffer" id="ISAPIReadAheadBuffer">ISAPIReadAheadBuffer</a> <a name="isapireadaheadbuffer" id="isapireadaheadbuffer">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Size of the Read Ahead Buffer sent to ISAPI
-extensions</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPIReadAheadBuffer <var>size</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPIReadAheadBuffer 49152</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
-</table>
- <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 <code>ReadClient</code> callback; some
- ISAPI extensions may not support the <code>ReadClient</code> function.
- Refer questions to the ISAPI extension's author.</p>
-
-</div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="usage" id="usage">Usage</a></h2>
<code>TransmitFile</code> semantics. Apache httpd also supports preloading
ISAPI .dlls for performance.</p>
</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ISAPIAppendLogToErrors" id="ISAPIAppendLogToErrors">ISAPIAppendLogToErrors</a> <a name="isapiappendlogtoerrors" id="isapiappendlogtoerrors">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from
+ISAPI extensions to the error log</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPIAppendLogToErrors on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPIAppendLogToErrors off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
+</table>
+ <p>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from ISAPI
+ extensions to the server error log.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ISAPIAppendLogToQuery" id="ISAPIAppendLogToQuery">ISAPIAppendLogToQuery</a> <a name="isapiappendlogtoquery" id="isapiappendlogtoquery">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from
+ISAPI extensions to the query field</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPIAppendLogToQuery on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPIAppendLogToQuery on</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
+</table>
+ <p>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from ISAPI
+ extensions to the query field (appended to the <code class="directive"><a href="../mod/mod_log_config.html#customlog">CustomLog</a></code> <code>%q</code>
+ component).</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ISAPICacheFile" id="ISAPICacheFile">ISAPICacheFile</a> <a name="isapicachefile" id="isapicachefile">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>ISAPI .dll files to be loaded at startup</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPICacheFile <var>file-path</var> [<var>file-path</var>]
+...</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
+</table>
+ <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. If the path name is not absolute, it will be treated
+ relative to <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ISAPIFakeAsync" id="ISAPIFakeAsync">ISAPIFakeAsync</a> <a name="isapifakeasync" id="isapifakeasync">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fake asynchronous support for ISAPI callbacks</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPIFakeAsync on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPIFakeAsync off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
+</table>
+ <p>While set to on, asynchronous support for ISAPI callbacks is
+ simulated.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ISAPILogNotSupported" id="ISAPILogNotSupported">ISAPILogNotSupported</a> <a name="isapilognotsupported" id="isapilognotsupported">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Log unsupported feature requests from ISAPI
+extensions</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPILogNotSupported on|off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPILogNotSupported off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
+</table>
+ <p>Logs all requests for unsupported features from ISAPI
+ extensions in the server error log. This may help administrators
+ to track down problems. Once set to on and all desired ISAPI modules
+ are functioning, it should be set back to off.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ISAPIReadAheadBuffer" id="ISAPIReadAheadBuffer">ISAPIReadAheadBuffer</a> <a name="isapireadaheadbuffer" id="isapireadaheadbuffer">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Size of the Read Ahead Buffer sent to ISAPI
+extensions</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPIReadAheadBuffer <var>size</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPIReadAheadBuffer 49152</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
+</table>
+ <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 <code>ReadClient</code> callback; some
+ ISAPI extensions may not support the <code>ReadClient</code> function.
+ Refer questions to the ISAPI extension's author.</p>
+
+</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_isapi.html" title="English"> en </a> |
It requires the services of <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>, and
provides the <code>bybusyness</code> load balancing method.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#busyness">Pending Request Counting Algorithm</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
<li><code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code></li>
It requires the services of <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>, and
provides the <code>byrequests</code> load balancing method..</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#requests">Request Counting Algorithm</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
<li><code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code></li>
It requires the services of <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>, and
provides the <code>bytraffic</code> load balancing method..</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#traffic">Weighted Traffic Counting Algorithm</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
<li><code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code></li>
<li><code class="module"><a href="../mod/mod_heartbeat.html">mod_heartbeat</a></code></li>
<li><code class="module"><a href="../mod/mod_heartmonitor.html">mod_heartmonitor</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="HeartbeatStorage" id="HeartbeatStorage">HeartbeatStorage</a> <a name="heartbeatstorage" id="heartbeatstorage">Directive</a></h2>
<table class="directive">
<code class="module"><a href="../mod/mod_slotmem_shm.html">mod_slotmem_shm</a></code> is not loaded.</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_lbmethod_heartbeat.html" title="English"> en </a> |
website for details.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#exampleconfig">Example Configuration</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#pool">LDAP Connection Pool</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#cache">LDAP Cache</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#usingssltls">Using SSL/TLS</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#settingcerts">SSL/TLS Certificates</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#ldapcacheentries">LDAPCacheEntries</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ldapcachettl">LDAPCacheTTL</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ldaptrustedmode">LDAPTrustedMode</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ldapverifyservercert">LDAPVerifyServerCert</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#exampleconfig">Example Configuration</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#pool">LDAP Connection Pool</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#cache">LDAP Cache</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#usingssltls">Using SSL/TLS</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#settingcerts">SSL/TLS Certificates</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPCacheEntries" id="LDAPCacheEntries">LDAPCacheEntries</a> <a name="ldapcacheentries" id="ldapcacheentries">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum number of entries in the primary LDAP cache</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPCacheEntries <var>number</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPCacheEntries 1024</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>Specifies the maximum size of the primary LDAP cache. This
- cache contains successful search/binds. Set it to 0 to turn off
- search/bind caching. The default size is 1024 cached
- searches.</p>
+<div class="section">
+<h2><a name="exampleconfig" id="exampleconfig">Example Configuration</a></h2>
+ <p>The following is an example configuration that uses
+ <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> to increase the performance of HTTP Basic
+ authentication provided by <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code>.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPCacheTTL" id="LDAPCacheTTL">LDAPCacheTTL</a> <a name="ldapcachettl" id="ldapcachettl">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Time that cached items remain valid</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPCacheTTL <var>seconds</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPCacheTTL 600</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>Specifies the time (in seconds) that an item in the
- search/bind cache remains valid. The default is 600 seconds (10
- minutes).</p>
+ <pre class="prettyprint lang-config"># Enable the LDAP connection pool and shared
+# memory cache. Enable the LDAP cache status
+# handler. Requires that mod_ldap and mod_authnz_ldap
+# be loaded. Change the "yourdomain.example.com" to
+# match your domain.
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPConnectionPoolTTL" id="LDAPConnectionPoolTTL">LDAPConnectionPoolTTL</a> <a name="ldapconnectionpoolttl" id="ldapconnectionpoolttl">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Discard backend connections that have been sitting in the connection pool too long</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPConnectionPoolTTL <var>n</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPConnectionPoolTTL -1</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Apache HTTP Server 2.3.12 and later</td></tr>
-</table>
- <p>Specifies the maximum age, in seconds, that a pooled LDAP connection can remain idle
- and still be available for use. Connections are cleaned up when they are next needed,
- not asynchronously.</p>
+LDAPSharedCacheSize 500000
+LDAPCacheEntries 1024
+LDAPCacheTTL 600
+LDAPOpCacheEntries 1024
+LDAPOpCacheTTL 600
- <p>A setting of 0 causes connections to never be saved in the backend
- connection pool. The default value of -1, and any other negative value,
- allows connections of any age to be reused.</p>
+<Location "/ldap-status">
+ SetHandler ldap-status
- <p>For performance reasons, the reference time used by this directive is
- based on when the LDAP connection is returned to the pool, not the time
- of the last successful I/O with the LDAP server. </p>
+ Require host yourdomain.example.com
- <p>Since 2.4.10, new measures are in place to avoid the reference time
- from being inflated by cache hits or slow requests. First, the reference
- time is not updated if no backend LDAP conncetions were needed. Second,
- the reference time uses the time the HTTP request was received instead
- of the time the request is completed.</p>
-
- <div class="note"><p>This timeout defaults to units of seconds, but accepts
- suffixes for milliseconds (ms), minutes (min), and hours (h).
- </p></div>
+ Satisfy any
+ AuthType Basic
+ AuthName "LDAP Protected"
+ AuthBasicProvider ldap
+ AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=com?uid?one"
+ Require valid-user
+</Location></pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPConnectionTimeout" id="LDAPConnectionTimeout">LDAPConnectionTimeout</a> <a name="ldapconnectiontimeout" id="ldapconnectiontimeout">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the socket connection timeout in seconds</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPConnectionTimeout <var>seconds</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>This directive configures the LDAP_OPT_NETWORK_TIMEOUT (or LDAP_OPT_CONNECT_TIMEOUT)
- option in the underlying LDAP client library, when available. This value
- typically controls how long the LDAP client library will wait for the TCP
- connection to the LDAP server to complete.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="pool" id="pool">LDAP Connection Pool</a></h2>
- <p> If a connection is not successful with the timeout period, either an error will be
- returned or the LDAP client library will attempt to connect to a secondary LDAP
- server if one is specified (via a space-separated list of hostnames in the
- <code class="directive"><a href="../mod/mod_authnz_ldap.html#authldapurl">AuthLDAPURL</a></code>).</p>
+ <p>LDAP connections are pooled from request to request. This
+ allows the LDAP server to remain connected and bound ready for
+ the next request, without the need to unbind/connect/rebind.
+ The performance advantages are similar to the effect of HTTP
+ keepalives.</p>
- <p>The default is 10 seconds, if the LDAP client library linked with the
- server supports the LDAP_OPT_NETWORK_TIMEOUT option.</p>
+ <p>On a busy server it is possible that many requests will try
+ and access the same LDAP server connection simultaneously.
+ Where an LDAP connection is in use, Apache will create a new
+ connection alongside the original one. This ensures that the
+ connection pool does not become a bottleneck.</p>
- <div class="note">LDAPConnectionTimeout is only available when the LDAP client library linked
- with the server supports the LDAP_OPT_NETWORK_TIMEOUT
- (or LDAP_OPT_CONNECT_TIMEOUT) option, and the ultimate behavior is
- dictated entirely by the LDAP client library.
- </div>
+ <p>There is no need to manually enable connection pooling in
+ the Apache configuration. Any module using this module for
+ access to LDAP services will share the connection pool.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPLibraryDebug" id="LDAPLibraryDebug">LDAPLibraryDebug</a> <a name="ldaplibrarydebug" id="ldaplibrarydebug">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable debugging in the LDAP SDK</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPLibraryDebug <var>7</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>disabled</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>Turns on SDK-specific LDAP debug options that generally cause the LDAP
- SDK to log verbose trace information to the main Apache error log.
- The trace messages from the LDAP SDK provide gory details that
- can be useful during debugging of connectivity problems with backend LDAP servers</p>
+ <p>LDAP connections can keep track of the ldap client
+ credentials used when binding to an LDAP server. These
+ credentials can be provided to LDAP servers that do not
+ allow anonymous binds during referral chasing. To control
+ this feature, see the
+ <code class="directive"><a href="#ldapreferrals">LDAPReferrals</a></code> and
+ <code class="directive"><a href="#ldapreferralhoplimit">LDAPReferralHopLimit</a></code>
+ directives. By default, this feature is enabled.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="cache" id="cache">LDAP Cache</a></h2>
- <p>This option is only configurable when Apache HTTP Server is linked with
- an LDAP SDK that implements <code>LDAP_OPT_DEBUG</code> or
- <code>LDAP_OPT_DEBUG_LEVEL</code>, such as OpenLDAP (a value of 7 is verbose)
- or Tivoli Directory Server (a value of 65535 is verbose).</p>
+ <p>For improved performance, <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> uses an aggressive
+ caching strategy to minimize the number of times that the LDAP
+ server must be contacted. Caching can easily double or triple
+ the throughput of Apache when it is serving pages protected
+ with mod_authnz_ldap. In addition, the load on the LDAP server
+ will be significantly decreased.</p>
- <div class="warning">
- <p>The logged information will likely contain plaintext credentials being used or
- validated by LDAP authentication, so care should be taken in protecting and purging
- the error log when this directive is used.</p>
- </div>
+ <p><code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> supports two types of LDAP caching during
+ the search/bind phase with a <em>search/bind cache</em> and
+ during the compare phase with two <em>operation
+ caches</em>. Each LDAP URL that is used by the server has
+ its own set of these three caches.</p>
+ <h3><a name="search-bind" id="search-bind">The Search/Bind Cache</a></h3>
+ <p>The process of doing a search and then a bind is the
+ most time-consuming aspect of LDAP operation, especially if
+ the directory is large. The search/bind cache is used to
+ cache all searches that resulted in successful binds.
+ Negative results (<em>i.e.</em>, unsuccessful searches, or searches
+ that did not result in a successful bind) are not cached.
+ The rationale behind this decision is that connections with
+ invalid credentials are only a tiny percentage of the total
+ number of connections, so by not caching invalid
+ credentials, the size of the cache is reduced.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPOpCacheEntries" id="LDAPOpCacheEntries">LDAPOpCacheEntries</a> <a name="ldapopcacheentries" id="ldapopcacheentries">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of entries used to cache LDAP compare
-operations</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPOpCacheEntries <var>number</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPOpCacheEntries 1024</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>This specifies the number of entries <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code>
- will use to cache LDAP compare operations. The default is 1024
- entries. Setting it to 0 disables operation caching.</p>
+ <p><code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> stores the username, the DN
+ retrieved, the password used to bind, and the time of the bind
+ in the cache. Whenever a new connection is initiated with the
+ same username, <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> compares the password
+ of the new connection with the password in the cache. If the
+ passwords match, and if the cached entry is not too old,
+ <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> bypasses the search/bind phase.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPOpCacheTTL" id="LDAPOpCacheTTL">LDAPOpCacheTTL</a> <a name="ldapopcachettl" id="ldapopcachettl">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Time that entries in the operation cache remain
-valid</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPOpCacheTTL <var>seconds</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPOpCacheTTL 600</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>Specifies the time (in seconds) that entries in the
- operation cache remain valid. The default is 600 seconds.</p>
+ <p>The search and bind cache is controlled with the <code class="directive"><a href="#ldapcacheentries">LDAPCacheEntries</a></code> and <code class="directive"><a href="#ldapcachettl">LDAPCacheTTL</a></code> directives.</p>
+
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPReferralHopLimit" id="LDAPReferralHopLimit">LDAPReferralHopLimit</a> <a name="ldapreferralhoplimit" id="ldapreferralhoplimit">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The maximum number of referral hops to chase before terminating an LDAP query.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPReferralHopLimit <var>number</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SDK dependent, typically between 5 and 10</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>This directive, if enabled by the <code class="directive">LDAPReferrals</code> directive,
- limits the number of referral hops that are followed before terminating an
- LDAP query.</p>
-
-<div class="warning">
-<p> Support for this tunable is uncommon in LDAP SDKs.</p>
-</div>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPReferrals" id="LDAPReferrals">LDAPReferrals</a> <a name="ldapreferrals" id="ldapreferrals">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable referral chasing during queries to the LDAP server.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPReferrals <var>On|Off|default</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPReferrals On</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The <var>default</var> parameter is available in Apache 2.4.7 and later</td></tr>
-</table>
- <p>Some LDAP servers divide their directory among multiple domains and use referrals
- to direct a client when a domain boundary is crossed. This is similar to a HTTP redirect.
- LDAP client libraries may or may not chase referrals by default. This directive
- explicitly configures the referral chasing in the underlying SDK.</p>
-
-
- <p><code class="directive">LDAPReferrals</code> takes the following values:</p>
- <dl>
- <dt>"on"</dt>
- <dd> <p> When set to "on", the underlying SDK's referral chasing state
- is enabled, <code class="directive">LDAPReferralHopLimit</code> is used to
- override the SDK's hop limit, and an LDAP rebind callback is
- registered.</p></dd>
- <dt>"off"</dt>
- <dd> <p> When set to "off", the underlying SDK's referral chasing state
- is disabled completely.</p></dd>
- <dt>"default"</dt>
- <dd> <p> When set to "default", the underlying SDK's referral chasing state
- is not changed, <code class="directive">LDAPReferralHopLimit</code> is not
- used to overide the SDK's hop limit, and no LDAP rebind callback is
- registered.</p></dd>
- </dl>
-
- <p>The directive <code class="directive">LDAPReferralHopLimit</code> works in conjunction with
- this directive to limit the number of referral hops to follow before terminating the LDAP query.
- When referral processing is enabled by a value of "On", client credentials will be provided,
- via a rebind callback, for any LDAP server requiring them.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPRetries" id="LDAPRetries">LDAPRetries</a> <a name="ldapretries" id="ldapretries">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the number of LDAP server retries.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPRetries <var>number-of-retries</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPRetries 3</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>The server will retry failed LDAP requests up to
- <code class="directive">LDAPRetries</code> times. Setting this
- directive to 0 disables retries.</p>
- <p>LDAP errors such as timeouts and refused connections are retryable.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPRetryDelay" id="LDAPRetryDelay">LDAPRetryDelay</a> <a name="ldapretrydelay" id="ldapretrydelay">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the delay between LDAP server retries.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPRetryDelay <var>seconds</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPRetryDelay 0</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>If <code class="directive">LDAPRetryDelay</code> is set to a non-zero
- value, the server will delay retrying an LDAP request for the
- specified amount of time. Setting this directive to 0 will
- result in any retry to occur without delay.</p>
-
- <p>LDAP errors such as timeouts and refused connections are retryable.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPSharedCacheFile" id="LDAPSharedCacheFile">LDAPSharedCacheFile</a> <a name="ldapsharedcachefile" id="ldapsharedcachefile">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the shared memory cache file</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPSharedCacheFile <var>directory-path/filename</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>Specifies the directory path and file name of the shared memory
- cache file. If not set, anonymous shared memory will be used if the
- platform supports it.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPSharedCacheSize" id="LDAPSharedCacheSize">LDAPSharedCacheSize</a> <a name="ldapsharedcachesize" id="ldapsharedcachesize">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Size in bytes of the shared-memory cache</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPSharedCacheSize <var>bytes</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPSharedCacheSize 500000</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>Specifies the number of bytes to allocate for the shared
- memory cache. The default is 500kb. If set to 0, shared memory
- caching will not be used and every HTTPD process will create its
- own cache.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPTimeout" id="LDAPTimeout">LDAPTimeout</a> <a name="ldaptimeout" id="ldaptimeout">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the timeout for LDAP search and bind operations, in seconds</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPTimeout <var>seconds</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPTimeout 60</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Apache HTTP Server 2.3.5 and later</td></tr>
-</table>
- <p>This directive configures the timeout for bind and search operations, as well as
- the LDAP_OPT_TIMEOUT option in the underlying LDAP client library, when available.</p>
-
- <p> If the timeout expires, httpd will retry in case an existing connection has
- been silently dropped by a firewall. However, performance will be much better if
- the firewall is configured to send TCP RST packets instead of silently dropping
- packets.</p>
-
- <div class="note">
- <p>Timeouts for ldap compare operations requires an SDK with LDAP_OPT_TIMEOUT, such as OpenLDAP >= 2.4.4.</p>
- </div>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPTrustedClientCert" id="LDAPTrustedClientCert">LDAPTrustedClientCert</a> <a name="ldaptrustedclientcert" id="ldaptrustedclientcert">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the file containing or nickname referring to a per
-connection client certificate. Not all LDAP toolkits support per
-connection client certificates.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPTrustedClientCert <var>type</var> <var>directory-path/filename/nickname</var> <var>[password]</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>It specifies the directory path, file name or nickname of a
- per connection client certificate used when establishing an SSL
- or TLS connection to an LDAP server. Different locations or
- directories may have their own independent client certificate
- settings. Some LDAP toolkits (notably Novell)
- do not support per connection client certificates, and will throw an
- error on LDAP server connection if you try to use this directive
- (Use the LDAPTrustedGlobalCert directive instead for Novell client
- certificates - See the SSL/TLS certificate guide above for details).
- The type specifies the kind of certificate parameter being
- set, depending on the LDAP toolkit being used. Supported types are:</p>
- <ul>
- <li>CA_DER - binary DER encoded CA certificate</li>
- <li>CA_BASE64 - PEM encoded CA certificate</li>
- <li>CERT_DER - binary DER encoded client certificate</li>
- <li>CERT_BASE64 - PEM encoded client certificate</li>
- <li>CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)</li>
- <li>KEY_DER - binary DER encoded private key</li>
- <li>KEY_BASE64 - PEM encoded private key</li>
- </ul>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPTrustedGlobalCert" id="LDAPTrustedGlobalCert">LDAPTrustedGlobalCert</a> <a name="ldaptrustedglobalcert" id="ldaptrustedglobalcert">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the file or database containing global trusted
-Certificate Authority or global client certificates</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPTrustedGlobalCert <var>type</var> <var>directory-path/filename</var> <var>[password]</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>It specifies the directory path and file name of the trusted CA
- certificates and/or system wide client certificates <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code>
- should use when establishing an SSL or TLS connection to an LDAP
- server. Note that all certificate information specified using this directive
- is applied globally to the entire server installation. Some LDAP toolkits
- (notably Novell) require all client certificates to be set globally using
- this directive. Most other toolkits require clients certificates to be set
- per Directory or per Location using LDAPTrustedClientCert. If you get this
- wrong, an error may be logged when an attempt is made to contact the LDAP
- server, or the connection may silently fail (See the SSL/TLS certificate
- guide above for details).
- The type specifies the kind of certificate parameter being
- set, depending on the LDAP toolkit being used. Supported types are:</p>
- <ul>
- <li>CA_DER - binary DER encoded CA certificate</li>
- <li>CA_BASE64 - PEM encoded CA certificate</li>
- <li>CA_CERT7_DB - Netscape cert7.db CA certificate database file</li>
- <li>CA_SECMOD - Netscape secmod database file</li>
- <li>CERT_DER - binary DER encoded client certificate</li>
- <li>CERT_BASE64 - PEM encoded client certificate</li>
- <li>CERT_KEY3_DB - Netscape key3.db client certificate database file</li>
- <li>CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)</li>
- <li>CERT_PFX - PKCS#12 encoded client certificate (Novell SDK)</li>
- <li>KEY_DER - binary DER encoded private key</li>
- <li>KEY_BASE64 - PEM encoded private key</li>
- <li>KEY_PFX - PKCS#12 encoded private key (Novell SDK)</li>
- </ul>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPTrustedMode" id="LDAPTrustedMode">LDAPTrustedMode</a> <a name="ldaptrustedmode" id="ldaptrustedmode">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the SSL/TLS mode to be used when connecting to an LDAP server.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPTrustedMode <var>type</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>The following modes are supported:</p>
- <ul>
- <li>NONE - no encryption</li>
- <li>SSL - ldaps:// encryption on default port 636</li>
- <li>TLS - STARTTLS encryption on default port 389</li>
- </ul>
-
- <p>Not all LDAP toolkits support all the above modes. An error message
- will be logged at runtime if a mode is not supported, and the
- connection to the LDAP server will fail.
- </p>
-
- <p>If an ldaps:// URL is specified, the mode becomes SSL and the setting
- of LDAPTrustedMode is ignored.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LDAPVerifyServerCert" id="LDAPVerifyServerCert">LDAPVerifyServerCert</a> <a name="ldapverifyservercert" id="ldapverifyservercert">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Force server certificate verification</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPVerifyServerCert <var>On|Off</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPVerifyServerCert On</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
-</table>
- <p>Specifies whether to force the verification of a
- server certificate when establishing an SSL connection to the
- LDAP server.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="exampleconfig" id="exampleconfig">Example Configuration</a></h2>
- <p>The following is an example configuration that uses
- <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> to increase the performance of HTTP Basic
- authentication provided by <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code>.</p>
-
- <pre class="prettyprint lang-config"># Enable the LDAP connection pool and shared
-# memory cache. Enable the LDAP cache status
-# handler. Requires that mod_ldap and mod_authnz_ldap
-# be loaded. Change the "yourdomain.example.com" to
-# match your domain.
-
-LDAPSharedCacheSize 500000
-LDAPCacheEntries 1024
-LDAPCacheTTL 600
-LDAPOpCacheEntries 1024
-LDAPOpCacheTTL 600
-
-<Location "/ldap-status">
- SetHandler ldap-status
-
- Require host yourdomain.example.com
-
- Satisfy any
- AuthType Basic
- AuthName "LDAP Protected"
- AuthBasicProvider ldap
- AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=com?uid?one"
- Require valid-user
-</Location></pre>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="pool" id="pool">LDAP Connection Pool</a></h2>
-
- <p>LDAP connections are pooled from request to request. This
- allows the LDAP server to remain connected and bound ready for
- the next request, without the need to unbind/connect/rebind.
- The performance advantages are similar to the effect of HTTP
- keepalives.</p>
-
- <p>On a busy server it is possible that many requests will try
- and access the same LDAP server connection simultaneously.
- Where an LDAP connection is in use, Apache will create a new
- connection alongside the original one. This ensures that the
- connection pool does not become a bottleneck.</p>
-
- <p>There is no need to manually enable connection pooling in
- the Apache configuration. Any module using this module for
- access to LDAP services will share the connection pool.</p>
-
- <p>LDAP connections can keep track of the ldap client
- credentials used when binding to an LDAP server. These
- credentials can be provided to LDAP servers that do not
- allow anonymous binds during referral chasing. To control
- this feature, see the
- <code class="directive"><a href="#ldapreferrals">LDAPReferrals</a></code> and
- <code class="directive"><a href="#ldapreferralhoplimit">LDAPReferralHopLimit</a></code>
- directives. By default, this feature is enabled.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="cache" id="cache">LDAP Cache</a></h2>
-
- <p>For improved performance, <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> uses an aggressive
- caching strategy to minimize the number of times that the LDAP
- server must be contacted. Caching can easily double or triple
- the throughput of Apache when it is serving pages protected
- with mod_authnz_ldap. In addition, the load on the LDAP server
- will be significantly decreased.</p>
-
- <p><code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> supports two types of LDAP caching during
- the search/bind phase with a <em>search/bind cache</em> and
- during the compare phase with two <em>operation
- caches</em>. Each LDAP URL that is used by the server has
- its own set of these three caches.</p>
-
- <h3><a name="search-bind" id="search-bind">The Search/Bind Cache</a></h3>
- <p>The process of doing a search and then a bind is the
- most time-consuming aspect of LDAP operation, especially if
- the directory is large. The search/bind cache is used to
- cache all searches that resulted in successful binds.
- Negative results (<em>i.e.</em>, unsuccessful searches, or searches
- that did not result in a successful bind) are not cached.
- The rationale behind this decision is that connections with
- invalid credentials are only a tiny percentage of the total
- number of connections, so by not caching invalid
- credentials, the size of the cache is reduced.</p>
-
- <p><code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> stores the username, the DN
- retrieved, the password used to bind, and the time of the bind
- in the cache. Whenever a new connection is initiated with the
- same username, <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> compares the password
- of the new connection with the password in the cache. If the
- passwords match, and if the cached entry is not too old,
- <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> bypasses the search/bind phase.</p>
-
- <p>The search and bind cache is controlled with the <code class="directive"><a href="#ldapcacheentries">LDAPCacheEntries</a></code> and <code class="directive"><a href="#ldapcachettl">LDAPCacheTTL</a></code> directives.</p>
-
-
- <h3><a name="opcaches" id="opcaches">Operation Caches</a></h3>
- <p>During attribute and distinguished name comparison
- functions, <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> uses two operation caches
- to cache the compare operations. The first compare cache is
- used to cache the results of compares done to test for LDAP
- group membership. The second compare cache is used to cache
- the results of comparisons done between distinguished
- names.</p>
+ <h3><a name="opcaches" id="opcaches">Operation Caches</a></h3>
+ <p>During attribute and distinguished name comparison
+ functions, <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> uses two operation caches
+ to cache the compare operations. The first compare cache is
+ used to cache the results of compares done to test for LDAP
+ group membership. The second compare cache is used to cache
+ the results of comparisons done between distinguished
+ names.</p>
<p>Note that, when group membership is being checked, any sub-group
comparison results are cached to speed future sub-group comparisons.</p>
to the certificate "nickname". An optional password may be
specified to unlock the certificate's private key.</p>
- <p>The SDK supports SSL only. An attempt to use STARTTLS will cause
- an error when an attempt is made to contact the LDAP server at
- runtime.</p>
+ <p>The SDK supports SSL only. An attempt to use STARTTLS will cause
+ an error when an attempt is made to contact the LDAP server at
+ runtime.</p>
+
+ <pre class="prettyprint lang-config"># Specify a Netscape CA certificate file
+LDAPTrustedGlobalCert CA_CERT7_DB "/certs/cert7.db"
+# Specify an optional key3.db file for client certificate support
+LDAPTrustedGlobalCert CERT_KEY3_DB "/certs/key3.db"
+# Specify the secmod file if required
+LDAPTrustedGlobalCert CA_SECMOD "/certs/secmod"
+<Location "/ldap-status">
+ SetHandler ldap-status
+
+ Require host yourdomain.example.com
+
+ Satisfy any
+ AuthType Basic
+ AuthName "LDAP Protected"
+ AuthBasicProvider ldap
+ LDAPTrustedClientCert CERT_NICKNAME <nickname> [password]
+ AuthLDAPURL "ldaps://127.0.0.1/dc=example,dc=com?uid?one"
+ Require valid-user
+</Location></pre>
+
+
+
+
+ <h3><a name="settingcerts-novell" id="settingcerts-novell">Novell SDK</a></h3>
+
+ <p>One or more CA certificates must be specified for the Novell
+ SDK to work correctly. These certificates can be specified as
+ binary DER or Base64 (PEM) encoded files.</p>
+
+ <p>Note: Client certificates are specified globally rather than per
+ connection, and so must be specified with the LDAPTrustedGlobalCert
+ directive as below. Trying to set client certificates via the
+ LDAPTrustedClientCert directive will cause an error to be logged
+ when an attempt is made to connect to the LDAP server..</p>
+
+ <p>The SDK supports both SSL and STARTTLS, set using the
+ LDAPTrustedMode parameter. If an ldaps:// URL is specified,
+ SSL mode is forced, override this directive.</p>
+
+ <pre class="prettyprint lang-config"># Specify two CA certificate files
+LDAPTrustedGlobalCert CA_DER "/certs/cacert1.der"
+LDAPTrustedGlobalCert CA_BASE64 "/certs/cacert2.pem"
+# Specify a client certificate file and key
+LDAPTrustedGlobalCert CERT_BASE64 "/certs/cert1.pem"
+LDAPTrustedGlobalCert KEY_BASE64 "/certs/key1.pem" [password]
+# Do not use this directive, as it will throw an error
+#LDAPTrustedClientCert CERT_BASE64 "/certs/cert1.pem"</pre>
+
+
+
+
+ <h3><a name="settingcerts-openldap" id="settingcerts-openldap">OpenLDAP SDK</a></h3>
+
+ <p>One or more CA certificates must be specified for the OpenLDAP
+ SDK to work correctly. These certificates can be specified as
+ binary DER or Base64 (PEM) encoded files.</p>
+
+ <p>Both CA and client certificates may be specified globally
+ (LDAPTrustedGlobalCert) or per-connection (LDAPTrustedClientCert).
+ When any settings are specified per-connection, the global
+ settings are superceded.</p>
- <pre class="prettyprint lang-config"># Specify a Netscape CA certificate file
-LDAPTrustedGlobalCert CA_CERT7_DB "/certs/cert7.db"
-# Specify an optional key3.db file for client certificate support
-LDAPTrustedGlobalCert CERT_KEY3_DB "/certs/key3.db"
-# Specify the secmod file if required
-LDAPTrustedGlobalCert CA_SECMOD "/certs/secmod"
+ <p>The documentation for the SDK claims to support both SSL and
+ STARTTLS, however STARTTLS does not seem to work on all versions
+ of the SDK. The SSL/TLS mode can be set using the
+ LDAPTrustedMode parameter. If an ldaps:// URL is specified,
+ SSL mode is forced. The OpenLDAP documentation notes that SSL
+ (ldaps://) support has been deprecated to be replaced with TLS,
+ although the SSL functionality still works.</p>
+
+ <pre class="prettyprint lang-config"># Specify two CA certificate files
+LDAPTrustedGlobalCert CA_DER "/certs/cacert1.der"
+LDAPTrustedGlobalCert CA_BASE64 "/certs/cacert2.pem"
<Location "/ldap-status">
SetHandler ldap-status
Require host yourdomain.example.com
+ LDAPTrustedClientCert CERT_BASE64 "/certs/cert1.pem"
+ LDAPTrustedClientCert KEY_BASE64 "/certs/key1.pem"
+ # CA certs respecified due to per-directory client certs
+ LDAPTrustedClientCert CA_DER "/certs/cacert1.der"
+ LDAPTrustedClientCert CA_BASE64 "/certs/cacert2.pem"
Satisfy any
AuthType Basic
AuthName "LDAP Protected"
AuthBasicProvider ldap
- LDAPTrustedClientCert CERT_NICKNAME <nickname> [password]
AuthLDAPURL "ldaps://127.0.0.1/dc=example,dc=com?uid?one"
Require valid-user
</Location></pre>
- <h3><a name="settingcerts-novell" id="settingcerts-novell">Novell SDK</a></h3>
+ <h3><a name="settingcerts-solaris" id="settingcerts-solaris">Solaris SDK</a></h3>
- <p>One or more CA certificates must be specified for the Novell
- SDK to work correctly. These certificates can be specified as
- binary DER or Base64 (PEM) encoded files.</p>
+ <p>SSL/TLS for the native Solaris LDAP libraries is not yet
+ supported. If required, install and use the OpenLDAP libraries
+ instead.</p>
- <p>Note: Client certificates are specified globally rather than per
- connection, and so must be specified with the LDAPTrustedGlobalCert
- directive as below. Trying to set client certificates via the
- LDAPTrustedClientCert directive will cause an error to be logged
- when an attempt is made to connect to the LDAP server..</p>
+
- <p>The SDK supports both SSL and STARTTLS, set using the
- LDAPTrustedMode parameter. If an ldaps:// URL is specified,
- SSL mode is forced, override this directive.</p>
+ <h3><a name="settingcerts-microsoft" id="settingcerts-microsoft">Microsoft SDK</a></h3>
- <pre class="prettyprint lang-config"># Specify two CA certificate files
-LDAPTrustedGlobalCert CA_DER "/certs/cacert1.der"
-LDAPTrustedGlobalCert CA_BASE64 "/certs/cacert2.pem"
-# Specify a client certificate file and key
-LDAPTrustedGlobalCert CERT_BASE64 "/certs/cert1.pem"
-LDAPTrustedGlobalCert KEY_BASE64 "/certs/key1.pem" [password]
-# Do not use this directive, as it will throw an error
-#LDAPTrustedClientCert CERT_BASE64 "/certs/cert1.pem"</pre>
+ <p>SSL/TLS certificate configuration for the native Microsoft
+ LDAP libraries is done inside the system registry, and no
+ configuration directives are required.</p>
+
+ <p>Both SSL and TLS are supported by using the ldaps:// URL
+ format, or by using the LDAPTrustedMode directive accordingly.</p>
+
+ <p>Note: The status of support for client certificates is not yet known
+ for this toolkit.</p>
+
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPCacheEntries" id="LDAPCacheEntries">LDAPCacheEntries</a> <a name="ldapcacheentries" id="ldapcacheentries">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum number of entries in the primary LDAP cache</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPCacheEntries <var>number</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPCacheEntries 1024</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>Specifies the maximum size of the primary LDAP cache. This
+ cache contains successful search/binds. Set it to 0 to turn off
+ search/bind caching. The default size is 1024 cached
+ searches.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPCacheTTL" id="LDAPCacheTTL">LDAPCacheTTL</a> <a name="ldapcachettl" id="ldapcachettl">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Time that cached items remain valid</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPCacheTTL <var>seconds</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPCacheTTL 600</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>Specifies the time (in seconds) that an item in the
+ search/bind cache remains valid. The default is 600 seconds (10
+ minutes).</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPConnectionPoolTTL" id="LDAPConnectionPoolTTL">LDAPConnectionPoolTTL</a> <a name="ldapconnectionpoolttl" id="ldapconnectionpoolttl">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Discard backend connections that have been sitting in the connection pool too long</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPConnectionPoolTTL <var>n</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPConnectionPoolTTL -1</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Apache HTTP Server 2.3.12 and later</td></tr>
+</table>
+ <p>Specifies the maximum age, in seconds, that a pooled LDAP connection can remain idle
+ and still be available for use. Connections are cleaned up when they are next needed,
+ not asynchronously.</p>
+
+ <p>A setting of 0 causes connections to never be saved in the backend
+ connection pool. The default value of -1, and any other negative value,
+ allows connections of any age to be reused.</p>
+
+ <p>For performance reasons, the reference time used by this directive is
+ based on when the LDAP connection is returned to the pool, not the time
+ of the last successful I/O with the LDAP server. </p>
+
+ <p>Since 2.4.10, new measures are in place to avoid the reference time
+ from being inflated by cache hits or slow requests. First, the reference
+ time is not updated if no backend LDAP conncetions were needed. Second,
+ the reference time uses the time the HTTP request was received instead
+ of the time the request is completed.</p>
+
+ <div class="note"><p>This timeout defaults to units of seconds, but accepts
+ suffixes for milliseconds (ms), minutes (min), and hours (h).
+ </p></div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPConnectionTimeout" id="LDAPConnectionTimeout">LDAPConnectionTimeout</a> <a name="ldapconnectiontimeout" id="ldapconnectiontimeout">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the socket connection timeout in seconds</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPConnectionTimeout <var>seconds</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>This directive configures the LDAP_OPT_NETWORK_TIMEOUT (or LDAP_OPT_CONNECT_TIMEOUT)
+ option in the underlying LDAP client library, when available. This value
+ typically controls how long the LDAP client library will wait for the TCP
+ connection to the LDAP server to complete.</p>
+
+ <p> If a connection is not successful with the timeout period, either an error will be
+ returned or the LDAP client library will attempt to connect to a secondary LDAP
+ server if one is specified (via a space-separated list of hostnames in the
+ <code class="directive"><a href="../mod/mod_authnz_ldap.html#authldapurl">AuthLDAPURL</a></code>).</p>
+
+ <p>The default is 10 seconds, if the LDAP client library linked with the
+ server supports the LDAP_OPT_NETWORK_TIMEOUT option.</p>
+
+ <div class="note">LDAPConnectionTimeout is only available when the LDAP client library linked
+ with the server supports the LDAP_OPT_NETWORK_TIMEOUT
+ (or LDAP_OPT_CONNECT_TIMEOUT) option, and the ultimate behavior is
+ dictated entirely by the LDAP client library.
+ </div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPLibraryDebug" id="LDAPLibraryDebug">LDAPLibraryDebug</a> <a name="ldaplibrarydebug" id="ldaplibrarydebug">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable debugging in the LDAP SDK</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPLibraryDebug <var>7</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>disabled</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>Turns on SDK-specific LDAP debug options that generally cause the LDAP
+ SDK to log verbose trace information to the main Apache error log.
+ The trace messages from the LDAP SDK provide gory details that
+ can be useful during debugging of connectivity problems with backend LDAP servers</p>
+
+ <p>This option is only configurable when Apache HTTP Server is linked with
+ an LDAP SDK that implements <code>LDAP_OPT_DEBUG</code> or
+ <code>LDAP_OPT_DEBUG_LEVEL</code>, such as OpenLDAP (a value of 7 is verbose)
+ or Tivoli Directory Server (a value of 65535 is verbose).</p>
+
+ <div class="warning">
+ <p>The logged information will likely contain plaintext credentials being used or
+ validated by LDAP authentication, so care should be taken in protecting and purging
+ the error log when this directive is used.</p>
+ </div>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPOpCacheEntries" id="LDAPOpCacheEntries">LDAPOpCacheEntries</a> <a name="ldapopcacheentries" id="ldapopcacheentries">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of entries used to cache LDAP compare
+operations</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPOpCacheEntries <var>number</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPOpCacheEntries 1024</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>This specifies the number of entries <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code>
+ will use to cache LDAP compare operations. The default is 1024
+ entries. Setting it to 0 disables operation caching.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPOpCacheTTL" id="LDAPOpCacheTTL">LDAPOpCacheTTL</a> <a name="ldapopcachettl" id="ldapopcachettl">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Time that entries in the operation cache remain
+valid</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPOpCacheTTL <var>seconds</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPOpCacheTTL 600</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>Specifies the time (in seconds) that entries in the
+ operation cache remain valid. The default is 600 seconds.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPReferralHopLimit" id="LDAPReferralHopLimit">LDAPReferralHopLimit</a> <a name="ldapreferralhoplimit" id="ldapreferralhoplimit">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The maximum number of referral hops to chase before terminating an LDAP query.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPReferralHopLimit <var>number</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SDK dependent, typically between 5 and 10</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>This directive, if enabled by the <code class="directive">LDAPReferrals</code> directive,
+ limits the number of referral hops that are followed before terminating an
+ LDAP query.</p>
+
+<div class="warning">
+<p> Support for this tunable is uncommon in LDAP SDKs.</p>
+</div>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPReferrals" id="LDAPReferrals">LDAPReferrals</a> <a name="ldapreferrals" id="ldapreferrals">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable referral chasing during queries to the LDAP server.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPReferrals <var>On|Off|default</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPReferrals On</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The <var>default</var> parameter is available in Apache 2.4.7 and later</td></tr>
+</table>
+ <p>Some LDAP servers divide their directory among multiple domains and use referrals
+ to direct a client when a domain boundary is crossed. This is similar to a HTTP redirect.
+ LDAP client libraries may or may not chase referrals by default. This directive
+ explicitly configures the referral chasing in the underlying SDK.</p>
-
- <h3><a name="settingcerts-openldap" id="settingcerts-openldap">OpenLDAP SDK</a></h3>
+ <p><code class="directive">LDAPReferrals</code> takes the following values:</p>
+ <dl>
+ <dt>"on"</dt>
+ <dd> <p> When set to "on", the underlying SDK's referral chasing state
+ is enabled, <code class="directive">LDAPReferralHopLimit</code> is used to
+ override the SDK's hop limit, and an LDAP rebind callback is
+ registered.</p></dd>
+ <dt>"off"</dt>
+ <dd> <p> When set to "off", the underlying SDK's referral chasing state
+ is disabled completely.</p></dd>
+ <dt>"default"</dt>
+ <dd> <p> When set to "default", the underlying SDK's referral chasing state
+ is not changed, <code class="directive">LDAPReferralHopLimit</code> is not
+ used to overide the SDK's hop limit, and no LDAP rebind callback is
+ registered.</p></dd>
+ </dl>
- <p>One or more CA certificates must be specified for the OpenLDAP
- SDK to work correctly. These certificates can be specified as
- binary DER or Base64 (PEM) encoded files.</p>
+ <p>The directive <code class="directive">LDAPReferralHopLimit</code> works in conjunction with
+ this directive to limit the number of referral hops to follow before terminating the LDAP query.
+ When referral processing is enabled by a value of "On", client credentials will be provided,
+ via a rebind callback, for any LDAP server requiring them.</p>
- <p>Both CA and client certificates may be specified globally
- (LDAPTrustedGlobalCert) or per-connection (LDAPTrustedClientCert).
- When any settings are specified per-connection, the global
- settings are superceded.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPRetries" id="LDAPRetries">LDAPRetries</a> <a name="ldapretries" id="ldapretries">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the number of LDAP server retries.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPRetries <var>number-of-retries</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPRetries 3</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>The server will retry failed LDAP requests up to
+ <code class="directive">LDAPRetries</code> times. Setting this
+ directive to 0 disables retries.</p>
+ <p>LDAP errors such as timeouts and refused connections are retryable.</p>
- <p>The documentation for the SDK claims to support both SSL and
- STARTTLS, however STARTTLS does not seem to work on all versions
- of the SDK. The SSL/TLS mode can be set using the
- LDAPTrustedMode parameter. If an ldaps:// URL is specified,
- SSL mode is forced. The OpenLDAP documentation notes that SSL
- (ldaps://) support has been deprecated to be replaced with TLS,
- although the SSL functionality still works.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPRetryDelay" id="LDAPRetryDelay">LDAPRetryDelay</a> <a name="ldapretrydelay" id="ldapretrydelay">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the delay between LDAP server retries.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPRetryDelay <var>seconds</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPRetryDelay 0</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>If <code class="directive">LDAPRetryDelay</code> is set to a non-zero
+ value, the server will delay retrying an LDAP request for the
+ specified amount of time. Setting this directive to 0 will
+ result in any retry to occur without delay.</p>
- <pre class="prettyprint lang-config"># Specify two CA certificate files
-LDAPTrustedGlobalCert CA_DER "/certs/cacert1.der"
-LDAPTrustedGlobalCert CA_BASE64 "/certs/cacert2.pem"
-<Location "/ldap-status">
- SetHandler ldap-status
+ <p>LDAP errors such as timeouts and refused connections are retryable.</p>
- Require host yourdomain.example.com
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPSharedCacheFile" id="LDAPSharedCacheFile">LDAPSharedCacheFile</a> <a name="ldapsharedcachefile" id="ldapsharedcachefile">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the shared memory cache file</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPSharedCacheFile <var>directory-path/filename</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>Specifies the directory path and file name of the shared memory
+ cache file. If not set, anonymous shared memory will be used if the
+ platform supports it.</p>
- LDAPTrustedClientCert CERT_BASE64 "/certs/cert1.pem"
- LDAPTrustedClientCert KEY_BASE64 "/certs/key1.pem"
- # CA certs respecified due to per-directory client certs
- LDAPTrustedClientCert CA_DER "/certs/cacert1.der"
- LDAPTrustedClientCert CA_BASE64 "/certs/cacert2.pem"
- Satisfy any
- AuthType Basic
- AuthName "LDAP Protected"
- AuthBasicProvider ldap
- AuthLDAPURL "ldaps://127.0.0.1/dc=example,dc=com?uid?one"
- Require valid-user
-</Location></pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPSharedCacheSize" id="LDAPSharedCacheSize">LDAPSharedCacheSize</a> <a name="ldapsharedcachesize" id="ldapsharedcachesize">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Size in bytes of the shared-memory cache</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPSharedCacheSize <var>bytes</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPSharedCacheSize 500000</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>Specifies the number of bytes to allocate for the shared
+ memory cache. The default is 500kb. If set to 0, shared memory
+ caching will not be used and every HTTPD process will create its
+ own cache.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPTimeout" id="LDAPTimeout">LDAPTimeout</a> <a name="ldaptimeout" id="ldaptimeout">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the timeout for LDAP search and bind operations, in seconds</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPTimeout <var>seconds</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPTimeout 60</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Apache HTTP Server 2.3.5 and later</td></tr>
+</table>
+ <p>This directive configures the timeout for bind and search operations, as well as
+ the LDAP_OPT_TIMEOUT option in the underlying LDAP client library, when available.</p>
-
+ <p> If the timeout expires, httpd will retry in case an existing connection has
+ been silently dropped by a firewall. However, performance will be much better if
+ the firewall is configured to send TCP RST packets instead of silently dropping
+ packets.</p>
- <h3><a name="settingcerts-solaris" id="settingcerts-solaris">Solaris SDK</a></h3>
+ <div class="note">
+ <p>Timeouts for ldap compare operations requires an SDK with LDAP_OPT_TIMEOUT, such as OpenLDAP >= 2.4.4.</p>
+ </div>
- <p>SSL/TLS for the native Solaris LDAP libraries is not yet
- supported. If required, install and use the OpenLDAP libraries
- instead.</p>
-
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPTrustedClientCert" id="LDAPTrustedClientCert">LDAPTrustedClientCert</a> <a name="ldaptrustedclientcert" id="ldaptrustedclientcert">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the file containing or nickname referring to a per
+connection client certificate. Not all LDAP toolkits support per
+connection client certificates.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPTrustedClientCert <var>type</var> <var>directory-path/filename/nickname</var> <var>[password]</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>It specifies the directory path, file name or nickname of a
+ per connection client certificate used when establishing an SSL
+ or TLS connection to an LDAP server. Different locations or
+ directories may have their own independent client certificate
+ settings. Some LDAP toolkits (notably Novell)
+ do not support per connection client certificates, and will throw an
+ error on LDAP server connection if you try to use this directive
+ (Use the LDAPTrustedGlobalCert directive instead for Novell client
+ certificates - See the SSL/TLS certificate guide above for details).
+ The type specifies the kind of certificate parameter being
+ set, depending on the LDAP toolkit being used. Supported types are:</p>
+ <ul>
+ <li>CA_DER - binary DER encoded CA certificate</li>
+ <li>CA_BASE64 - PEM encoded CA certificate</li>
+ <li>CERT_DER - binary DER encoded client certificate</li>
+ <li>CERT_BASE64 - PEM encoded client certificate</li>
+ <li>CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)</li>
+ <li>KEY_DER - binary DER encoded private key</li>
+ <li>KEY_BASE64 - PEM encoded private key</li>
+ </ul>
- <h3><a name="settingcerts-microsoft" id="settingcerts-microsoft">Microsoft SDK</a></h3>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPTrustedGlobalCert" id="LDAPTrustedGlobalCert">LDAPTrustedGlobalCert</a> <a name="ldaptrustedglobalcert" id="ldaptrustedglobalcert">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the file or database containing global trusted
+Certificate Authority or global client certificates</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPTrustedGlobalCert <var>type</var> <var>directory-path/filename</var> <var>[password]</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>It specifies the directory path and file name of the trusted CA
+ certificates and/or system wide client certificates <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code>
+ should use when establishing an SSL or TLS connection to an LDAP
+ server. Note that all certificate information specified using this directive
+ is applied globally to the entire server installation. Some LDAP toolkits
+ (notably Novell) require all client certificates to be set globally using
+ this directive. Most other toolkits require clients certificates to be set
+ per Directory or per Location using LDAPTrustedClientCert. If you get this
+ wrong, an error may be logged when an attempt is made to contact the LDAP
+ server, or the connection may silently fail (See the SSL/TLS certificate
+ guide above for details).
+ The type specifies the kind of certificate parameter being
+ set, depending on the LDAP toolkit being used. Supported types are:</p>
+ <ul>
+ <li>CA_DER - binary DER encoded CA certificate</li>
+ <li>CA_BASE64 - PEM encoded CA certificate</li>
+ <li>CA_CERT7_DB - Netscape cert7.db CA certificate database file</li>
+ <li>CA_SECMOD - Netscape secmod database file</li>
+ <li>CERT_DER - binary DER encoded client certificate</li>
+ <li>CERT_BASE64 - PEM encoded client certificate</li>
+ <li>CERT_KEY3_DB - Netscape key3.db client certificate database file</li>
+ <li>CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)</li>
+ <li>CERT_PFX - PKCS#12 encoded client certificate (Novell SDK)</li>
+ <li>KEY_DER - binary DER encoded private key</li>
+ <li>KEY_BASE64 - PEM encoded private key</li>
+ <li>KEY_PFX - PKCS#12 encoded private key (Novell SDK)</li>
+ </ul>
- <p>SSL/TLS certificate configuration for the native Microsoft
- LDAP libraries is done inside the system registry, and no
- configuration directives are required.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPTrustedMode" id="LDAPTrustedMode">LDAPTrustedMode</a> <a name="ldaptrustedmode" id="ldaptrustedmode">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specifies the SSL/TLS mode to be used when connecting to an LDAP server.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPTrustedMode <var>type</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>The following modes are supported:</p>
+ <ul>
+ <li>NONE - no encryption</li>
+ <li>SSL - ldaps:// encryption on default port 636</li>
+ <li>TLS - STARTTLS encryption on default port 389</li>
+ </ul>
- <p>Both SSL and TLS are supported by using the ldaps:// URL
- format, or by using the LDAPTrustedMode directive accordingly.</p>
+ <p>Not all LDAP toolkits support all the above modes. An error message
+ will be logged at runtime if a mode is not supported, and the
+ connection to the LDAP server will fail.
+ </p>
- <p>Note: The status of support for client certificates is not yet known
- for this toolkit.</p>
+ <p>If an ldaps:// URL is specified, the mode becomes SSL and the setting
+ of LDAPTrustedMode is ignored.</p>
-
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LDAPVerifyServerCert" id="LDAPVerifyServerCert">LDAPVerifyServerCert</a> <a name="ldapverifyservercert" id="ldapverifyservercert">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Force server certificate verification</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LDAPVerifyServerCert <var>On|Off</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LDAPVerifyServerCert On</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ldap</td></tr>
+</table>
+ <p>Specifies whether to force the verification of a
+ server certificate when establishing an SSL connection to the
+ LDAP server.</p>
</div>
</div>
step. The <code class="directive">TransferLog</code> and <code class="directive">CustomLog</code> directives can be used multiple times in each
server to cause each request to be logged to multiple files.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#formats">Custom Log Formats</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#security">Security Considerations</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#bufferedlogs">BufferedLogs</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#customlog">CustomLog</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#logformat">LogFormat</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#transferlog">TransferLog</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#formats">Custom Log Formats</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#security">Security Considerations</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><a href="../logs.html">Apache Log Files</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="BufferedLogs" id="BufferedLogs">BufferedLogs</a> <a name="bufferedlogs" id="bufferedlogs">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Buffer log entries in memory before writing to disk</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BufferedLogs On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BufferedLogs Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_log_config</td></tr>
-</table>
- <p>The <code class="directive">BufferedLogs</code> directive causes
- <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code> to store several log entries in
- memory and write them together to disk, rather than writing them
- after each request. On some systems, this may result in more
- efficient disk access and hence higher performance. It may be
- set only once for the entire server; it cannot be configured
- per virtual-host.</p>
-
- <div class="note">This directive should be used with caution as a crash might
- cause loss of logging data.</div>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="CustomLog" id="CustomLog">CustomLog</a> <a name="customlog" id="customlog">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets filename and format of log file</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CustomLog <var>file</var>|<var>pipe</var>
-<var>format</var>|<var>nickname</var>
-[env=[!]<var>environment-variable</var>|
-expr=<var>expression</var>]</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_log_config</td></tr>
-</table>
- <p>The <code class="directive">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 one of the following two
- types of values:</p>
-
- <dl>
- <dt><var>file</var></dt>
- <dd>A filename, relative to the <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</dd>
-
- <dt><var>pipe</var></dt>
- <dd>The pipe character "<code>|</code>", followed by the path
- to a program to receive the log information on its standard
- input. See the notes on <a href="../logs.html#piped">piped logs</a>
- for more information.
-
- <div class="warning"><h3>Security:</h3>
- <p>If a program is used, then it will be run as the user who
- started <code class="program"><a href="../programs/httpd.html">httpd</a></code>. This will be root if the server was
- started by root; be sure that the program is secure.</p>
- </div>
- <div class="warning"><h3>Note</h3>
- <p>When entering a file path on non-Unix platforms, care should be taken
- to make sure that only forward slashed are used even though the platform
- may allow the use of back slashes. In general it is a good idea to always
- use forward slashes throughout the configuration files.</p>
- </div></dd>
- </dl>
-
- <p>The second argument specifies what will be written to the
- log file. It can specify either a <var>nickname</var> defined by
- a previous <code class="directive"><a href="#logformat">LogFormat</a></code>
- directive, or it can be an explicit <var>format</var> 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 class="prettyprint lang-config"># CustomLog with format nickname
-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"</pre>
-
-
- <p>The third argument is optional and controls whether or
- not to log a particular request. The condition can be the
- presence or absence (in the case of a '<code>env=!<var>name</var></code>'
- clause) of a particular variable in the server
- <a href="../env.html">environment</a>. Alternatively, the condition
- can be expressed as arbitrary boolean <a href="../expr.html">expression</a>. If the condition is not satisfied, the request
- will not be logged. References to HTTP headers in the expression
- will not cause the header names to be added to the Vary header.</p>
-
- <p>Environment variables can be set on a per-request
- basis using the <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code>
- and/or <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> modules. For
- example, if you want to record requests for all GIF
- images on your server in a separate logfile but not in your main
- log, you can use:</p>
-
- <pre class="prettyprint lang-config">SetEnvIf Request_URI \.gif$ gif-image
-CustomLog "gif-requests.log" common env=gif-image
-CustomLog "nongif-requests.log" common env=!gif-image</pre>
-
-
- <p>Or, to reproduce the behavior of the old RefererIgnore
- directive, you might use the following:</p>
-
- <pre class="prettyprint lang-config">SetEnvIf Referer example\.com localreferer
-CustomLog "referer.log" referer env=!localreferer</pre>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LogFormat" id="LogFormat">LogFormat</a> <a name="logformat" id="logformat">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Describes a format for use in a log file</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LogFormat <var>format</var>|<var>nickname</var>
-[<var>nickname</var>]</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LogFormat "%h %l %u %t \"%r\" %>s %b"</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_log_config</td></tr>
-</table>
- <p>This directive specifies the format of the access log
- file.</p>
-
- <p>The <code class="directive">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 <code class="directive">TransferLog</code>
- directives. The single argument can specify an explicit
- <var>format</var> as discussed in the <a href="#formats">custom log
- formats</a> section above. Alternatively, it can use a
- <var>nickname</var> to refer to a log format defined in a
- previous <code class="directive">LogFormat</code> directive as described
- below.</p>
-
- <p>The second form of the <code class="directive">LogFormat</code>
- directive associates an explicit <var>format</var> with a
- <var>nickname</var>. This <var>nickname</var> can then be used in
- subsequent <code class="directive">LogFormat</code> or
- <code class="directive"><a href="#customlog">CustomLog</a></code> directives
- rather than repeating the entire format string. A
- <code class="directive">LogFormat</code> directive that 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
- <code class="directive"><a href="#transferlog">TransferLog</a></code> directives.
- In addition, <code class="directive">LogFormat</code> cannot use one nickname
- to define another nickname. Note that the nickname should not contain
- percent signs (<code>%</code>).</p>
-
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common</pre>
-</div>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="TransferLog" id="TransferLog">TransferLog</a> <a name="transferlog" id="transferlog">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify location of a log file</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>TransferLog <var>file</var>|<var>pipe</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_log_config</td></tr>
-</table>
- <p>This directive has exactly the same arguments and effect as
- the <code class="directive"><a href="#customlog">CustomLog</a></code>
- 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
- <code class="directive"><a href="#logformat">LogFormat</a></code> directive
- which does not define a nickname. Common Log Format is used if no
- other format has been specified.</p>
-
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
-TransferLog logs/access_log</pre>
-</div>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="formats" id="formats">Custom Log Formats</a></h2>
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>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="BufferedLogs" id="BufferedLogs">BufferedLogs</a> <a name="bufferedlogs" id="bufferedlogs">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Buffer log entries in memory before writing to disk</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BufferedLogs On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BufferedLogs Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_log_config</td></tr>
+</table>
+ <p>The <code class="directive">BufferedLogs</code> directive causes
+ <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code> to store several log entries in
+ memory and write them together to disk, rather than writing them
+ after each request. On some systems, this may result in more
+ efficient disk access and hence higher performance. It may be
+ set only once for the entire server; it cannot be configured
+ per virtual-host.</p>
+
+ <div class="note">This directive should be used with caution as a crash might
+ cause loss of logging data.</div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="CustomLog" id="CustomLog">CustomLog</a> <a name="customlog" id="customlog">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets filename and format of log file</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CustomLog <var>file</var>|<var>pipe</var>
+<var>format</var>|<var>nickname</var>
+[env=[!]<var>environment-variable</var>|
+expr=<var>expression</var>]</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_log_config</td></tr>
+</table>
+ <p>The <code class="directive">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 one of the following two
+ types of values:</p>
+
+ <dl>
+ <dt><var>file</var></dt>
+ <dd>A filename, relative to the <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</dd>
+
+ <dt><var>pipe</var></dt>
+ <dd>The pipe character "<code>|</code>", followed by the path
+ to a program to receive the log information on its standard
+ input. See the notes on <a href="../logs.html#piped">piped logs</a>
+ for more information.
+
+ <div class="warning"><h3>Security:</h3>
+ <p>If a program is used, then it will be run as the user who
+ started <code class="program"><a href="../programs/httpd.html">httpd</a></code>. This will be root if the server was
+ started by root; be sure that the program is secure.</p>
+ </div>
+ <div class="warning"><h3>Note</h3>
+ <p>When entering a file path on non-Unix platforms, care should be taken
+ to make sure that only forward slashed are used even though the platform
+ may allow the use of back slashes. In general it is a good idea to always
+ use forward slashes throughout the configuration files.</p>
+ </div></dd>
+ </dl>
+
+ <p>The second argument specifies what will be written to the
+ log file. It can specify either a <var>nickname</var> defined by
+ a previous <code class="directive"><a href="#logformat">LogFormat</a></code>
+ directive, or it can be an explicit <var>format</var> 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 class="prettyprint lang-config"># CustomLog with format nickname
+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"</pre>
+
+
+ <p>The third argument is optional and controls whether or
+ not to log a particular request. The condition can be the
+ presence or absence (in the case of a '<code>env=!<var>name</var></code>'
+ clause) of a particular variable in the server
+ <a href="../env.html">environment</a>. Alternatively, the condition
+ can be expressed as arbitrary boolean <a href="../expr.html">expression</a>. If the condition is not satisfied, the request
+ will not be logged. References to HTTP headers in the expression
+ will not cause the header names to be added to the Vary header.</p>
+
+ <p>Environment variables can be set on a per-request
+ basis using the <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code>
+ and/or <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> modules. For
+ example, if you want to record requests for all GIF
+ images on your server in a separate logfile but not in your main
+ log, you can use:</p>
+
+ <pre class="prettyprint lang-config">SetEnvIf Request_URI \.gif$ gif-image
+CustomLog "gif-requests.log" common env=gif-image
+CustomLog "nongif-requests.log" common env=!gif-image</pre>
+
+
+ <p>Or, to reproduce the behavior of the old RefererIgnore
+ directive, you might use the following:</p>
+
+ <pre class="prettyprint lang-config">SetEnvIf Referer example\.com localreferer
+CustomLog "referer.log" referer env=!localreferer</pre>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LogFormat" id="LogFormat">LogFormat</a> <a name="logformat" id="logformat">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Describes a format for use in a log file</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LogFormat <var>format</var>|<var>nickname</var>
+[<var>nickname</var>]</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LogFormat "%h %l %u %t \"%r\" %>s %b"</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_log_config</td></tr>
+</table>
+ <p>This directive specifies the format of the access log
+ file.</p>
+
+ <p>The <code class="directive">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 <code class="directive">TransferLog</code>
+ directives. The single argument can specify an explicit
+ <var>format</var> as discussed in the <a href="#formats">custom log
+ formats</a> section above. Alternatively, it can use a
+ <var>nickname</var> to refer to a log format defined in a
+ previous <code class="directive">LogFormat</code> directive as described
+ below.</p>
+
+ <p>The second form of the <code class="directive">LogFormat</code>
+ directive associates an explicit <var>format</var> with a
+ <var>nickname</var>. This <var>nickname</var> can then be used in
+ subsequent <code class="directive">LogFormat</code> or
+ <code class="directive"><a href="#customlog">CustomLog</a></code> directives
+ rather than repeating the entire format string. A
+ <code class="directive">LogFormat</code> directive that 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
+ <code class="directive"><a href="#transferlog">TransferLog</a></code> directives.
+ In addition, <code class="directive">LogFormat</code> cannot use one nickname
+ to define another nickname. Note that the nickname should not contain
+ percent signs (<code>%</code>).</p>
+
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common</pre>
+</div>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="TransferLog" id="TransferLog">TransferLog</a> <a name="transferlog" id="transferlog">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify location of a log file</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>TransferLog <var>file</var>|<var>pipe</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_log_config</td></tr>
+</table>
+ <p>This directive has exactly the same arguments and effect as
+ the <code class="directive"><a href="#customlog">CustomLog</a></code>
+ 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
+ <code class="directive"><a href="#logformat">LogFormat</a></code> directive
+ which does not define a nickname. Common Log Format is used if no
+ other format has been specified.</p>
+
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
+TransferLog logs/access_log</pre>
+</div>
+
</div>
</div>
<div class="bottomlang">
<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_log_debug.c</td></tr>
<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.14 and later</td></tr></table>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#logmessage">LogMessage</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="examples" id="examples">Examples</a></h2>
+
+ <ol>
+ <li>
+ Log message after request to /foo/* is processed:
+
+ <pre class="prettyprint lang-config"><Location "/foo/">
+ LogMessage "/foo/ has been requested"
+</Location></pre>
+
+ </li>
+
+ <li>
+ Log message if request to /foo/* is processed in a sub-request:
+ <pre class="prettyprint lang-config"><Location "/foo/">
+ LogMessage "subrequest to /foo/" hook=type_checker expr=%{IS_SUBREQ}
+</Location></pre>
+
+
+ The default log_transaction hook is not executed for sub-requests,
+ therefore we have to use a different hook.
+ </li>
+
+
+ <li>
+ Log message if an IPv6 client causes a request timeout:
+ <pre class="prettyprint lang-config">LogMessage "IPv6 timeout from %{REMOTE_ADDR}" "expr=-T %{IPV6} && %{REQUEST_STATUS} = 408"</pre>
+
+ Note the placing of the double quotes for the <code>expr=</code> argument.
+ </li>
+
+ <li>
+ Log the value of the "X-Foo" request environment variable in each
+ stage of the request:
+ <pre class="prettyprint lang-config"><Location "/">
+ LogMessage "%{reqenv:X-Foo}" hook=all
+</Location></pre>
+
+ Together with microsecond time stamps in the error log,
+ <code>hook=all</code> also lets you determine the times spent
+ in the different parts of the request processing.
+ </li>
+
+ </ol>
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="LogMessage" id="LogMessage">LogMessage</a> <a name="logmessage" id="logmessage">Directive</a></h2>
<table class="directive">
headers will not cause the header names to be added to the Vary header.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="examples" id="examples">Examples</a></h2>
-
- <ol>
- <li>
- Log message after request to /foo/* is processed:
-
- <pre class="prettyprint lang-config"><Location "/foo/">
- LogMessage "/foo/ has been requested"
-</Location></pre>
-
- </li>
-
- <li>
- Log message if request to /foo/* is processed in a sub-request:
- <pre class="prettyprint lang-config"><Location "/foo/">
- LogMessage "subrequest to /foo/" hook=type_checker expr=%{IS_SUBREQ}
-</Location></pre>
-
-
- The default log_transaction hook is not executed for sub-requests,
- therefore we have to use a different hook.
- </li>
-
-
- <li>
- Log message if an IPv6 client causes a request timeout:
- <pre class="prettyprint lang-config">LogMessage "IPv6 timeout from %{REMOTE_ADDR}" "expr=-T %{IPV6} && %{REQUEST_STATUS} = 408"</pre>
-
- Note the placing of the double quotes for the <code>expr=</code> argument.
- </li>
-
- <li>
- Log the value of the "X-Foo" request environment variable in each
- stage of the request:
- <pre class="prettyprint lang-config"><Location "/">
- LogMessage "%{reqenv:X-Foo}" hook=all
-</Location></pre>
-
- Together with microsecond time stamps in the error log,
- <code>hook=all</code> also lets you determine the times spent
- in the different parts of the request processing.
- </li>
-
- </ol>
</div>
</div>
<div class="bottomlang">
distribution's support directory, may be helpful in evaluating the
forensic log output.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#forensiclog">ForensicLog</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#formats">Forensic Log Format</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#security">Security Considerations</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#forensiclog">ForensicLog</a></li>
+</ul>
+<h3>See also</h3>
<ul class="seealso">
<li><a href="../logs.html">Apache Log Files</a></li>
<li><code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ForensicLog" id="ForensicLog">ForensicLog</a> <a name="forensiclog" id="forensiclog">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets filename of the forensic log</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ForensicLog <var>filename</var>|<var>pipe</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_log_forensic</td></tr>
-</table>
- <p>The <code class="directive">ForensicLog</code> directive is used to
- log requests to the server for forensic analysis. Each log entry
- is assigned a unique ID which can be associated with the request
- using the normal <code class="directive"><a href="../mod/mod_log_config.html#customlog">CustomLog</a></code>
- directive. <code class="module"><a href="../mod/mod_log_forensic.html">mod_log_forensic</a></code> creates a token called
- <code>forensic-id</code>, which can be added to the transfer log
- using the <code>%{forensic-id}n</code> format string.</p>
-
- <p>The argument, which specifies the location to which
- the logs will be written, can take one of the following two
- types of values:</p>
-
- <dl>
- <dt><var>filename</var></dt>
- <dd>A filename, relative to the <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</dd>
-
- <dt><var>pipe</var></dt>
- <dd>The pipe character "<code>|</code>", followed by the path
- to a program to receive the log information on its standard
- input. The program name can be specified relative to the <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code> directive.
-
- <div class="warning"><h3>Security:</h3>
- <p>If a program is used, then it will be run as the user who
- started <code class="program"><a href="../programs/httpd.html">httpd</a></code>. This will be root if the server was
- started by root; be sure that the program is secure or switches to a
- less privileged user.</p>
- </div>
-
- <div class="note"><h3>Note</h3>
- <p>When entering a file path on non-Unix platforms, care should be taken
- to make sure that only forward slashes are used even though the platform
- may allow the use of back slashes. In general it is a good idea to always
- use forward slashes throughout the configuration files.</p>
- </div></dd>
- </dl>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="formats" id="formats">Forensic Log Format</a></h2>
<p>Each request is logged two times. The first time is <em>before</em> it's
they should not be readable by anyone except the user that starts the
server.</p>
</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ForensicLog" id="ForensicLog">ForensicLog</a> <a name="forensiclog" id="forensiclog">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets filename of the forensic log</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ForensicLog <var>filename</var>|<var>pipe</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_log_forensic</td></tr>
+</table>
+ <p>The <code class="directive">ForensicLog</code> directive is used to
+ log requests to the server for forensic analysis. Each log entry
+ is assigned a unique ID which can be associated with the request
+ using the normal <code class="directive"><a href="../mod/mod_log_config.html#customlog">CustomLog</a></code>
+ directive. <code class="module"><a href="../mod/mod_log_forensic.html">mod_log_forensic</a></code> creates a token called
+ <code>forensic-id</code>, which can be added to the transfer log
+ using the <code>%{forensic-id}n</code> format string.</p>
+
+ <p>The argument, which specifies the location to which
+ the logs will be written, can take one of the following two
+ types of values:</p>
+
+ <dl>
+ <dt><var>filename</var></dt>
+ <dd>A filename, relative to the <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</dd>
+
+ <dt><var>pipe</var></dt>
+ <dd>The pipe character "<code>|</code>", followed by the path
+ to a program to receive the log information on its standard
+ input. The program name can be specified relative to the <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code> directive.
+
+ <div class="warning"><h3>Security:</h3>
+ <p>If a program is used, then it will be run as the user who
+ started <code class="program"><a href="../programs/httpd.html">httpd</a></code>. This will be root if the server was
+ started by root; be sure that the program is secure or switches to a
+ less privileged user.</p>
+ </div>
+
+ <div class="note"><h3>Note</h3>
+ <p>When entering a file path on non-Unix platforms, care should be taken
+ to make sure that only forward slashes are used even though the platform
+ may allow the use of back slashes. In general it is a good idea to always
+ use forward slashes throughout the configuration files.</p>
+ </div></dd>
+ </dl>
+
+</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_log_forensic.html" title="English"> en </a> |
with the request that triggered the renegotiation.</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#formats">Custom Log Formats</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code></li>
<li><a href="../logs.html">Apache Log Files</a></li>
</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#basicconf">Basic Configuration</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#writinghandlers">Writing Handlers</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#writingauthzproviders">Writing Authorization Providers</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#writinghooks">Writing Hooks</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#datastructures">Data Structures</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#functions">Built in functions</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging Functions</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#apache2">apache2 Package</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#modifying_buckets">Modifying contents with Lua filters</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#databases">Database connectivity</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#luaauthzprovider">LuaAuthzProvider</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luacodecache">LuaCodeCache</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luaroot">LuaRoot</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luascope">LuaScope</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#basicconf">Basic Configuration</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#writinghandlers">Writing Handlers</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#writingauthzproviders">Writing Authorization Providers</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#writinghooks">Writing Hooks</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#datastructures">Data Structures</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#functions">Built in functions</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging Functions</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#apache2">apache2 Package</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#modifying_buckets">Modifying contents with Lua filters</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#databases">Database connectivity</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaAuthzProvider" id="LuaAuthzProvider">LuaAuthzProvider</a> <a name="luaauthzprovider" id="luaauthzprovider">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Plug an authorization provider function into <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code>
-</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.3 and later</td></tr>
-</table>
-<p>After a lua function has been registered as authorization provider, it can be used
-with the <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive:</p>
+<div class="section">
+<h2><a name="basicconf" id="basicconf">Basic Configuration</a></h2>
-<pre class="prettyprint lang-config">LuaRoot "/usr/local/apache2/lua"
-LuaAuthzProvider foo authz.lua authz_check_foo
-<Location "/">
- Require foo johndoe
-</Location></pre>
+<p>The basic module loading directive is</p>
-<pre class="prettyprint lang-lua">require "apache2"
-function authz_check_foo(r, who)
- if r.user ~= who then return apache2.AUTHZ_DENIED
- return apache2.AUTHZ_GRANTED
-end</pre>
+<pre class="prettyprint lang-config">LoadModule lua_module modules/mod_lua.so</pre>
+<p>
+<code>mod_lua</code> provides a handler named <code>lua-script</code>,
+which can be used with a <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code> or
+<code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> directive:</p>
+<pre class="prettyprint lang-config"><Files "*.lua">
+ SetHandler lua-script
+</Files></pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaCodeCache" id="LuaCodeCache">LuaCodeCache</a> <a name="luacodecache" id="luacodecache">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the compiled code cache.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaCodeCache stat|forever|never</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaCodeCache stat</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-</table><p>
- Specify the behavior of the in-memory code cache. The default
- is stat, which stats the top level script (not any included
- ones) each time that file is needed, and reloads it if the
- modified time indicates it is newer than the one it has
- already loaded. The other values cause it to keep the file
- cached forever (don't stat and replace) or to never cache the
- file.</p>
- <p>In general stat or forever is good for production, and stat or never
- for development.</p>
+<p>
+This will cause <code>mod_lua</code> to handle requests for files
+ending in <code>.lua</code> by invoking that file's
+<code>handle</code> function.
+</p>
- <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">LuaCodeCache stat
-LuaCodeCache forever
-LuaCodeCache never</pre>
-</div>
+<p>For more flexibility, see <code class="directive">LuaMapHandler</code>.
+</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="writinghandlers" id="writinghandlers">Writing Handlers</a></h2>
+<p> In the Apache HTTP Server API, the handler is a specific kind of hook
+responsible for generating the response. Examples of modules that include a
+handler are <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>,
+and <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaHookAccessChecker" id="LuaHookAccessChecker">LuaHookAccessChecker</a> <a name="luahookaccesschecker" id="luahookaccesschecker">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the access_checker phase of request processing</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is supported in 2.3.15 and later</td></tr>
-</table>
-<p>Add your hook to the access_checker phase. An access checker
-hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>
- <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
- control when this script runs relative to other modules.</p></div>
+<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
+just evaluating a script body CGI style. A handler function looks
+something like this:</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaHookAuthChecker" id="LuaHookAuthChecker">LuaHookAuthChecker</a> <a name="luahookauthchecker" id="luahookauthchecker">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the auth_checker phase of request processing</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is supported in 2.3.15 and later</td></tr>
-</table>
-<p>Invoke a lua function in the auth_checker phase of processing
-a request. This can be used to implement arbitrary authentication
-and authorization checking. A very simple example:
-</p>
-<pre class="prettyprint lang-lua">require 'apache2'
--- fake authcheck hook
--- If request has no auth info, set the response header and
--- return a 401 to ask the browser for basic auth info.
--- If request has auth info, don't actually look at it, just
--- pretend we got userid 'foo' and validated it.
--- Then check if the userid is 'foo' and accept the request.
-function authcheck_hook(r)
+<pre class="prettyprint lang-lua">
+<strong>example.lua</strong><br />
+-- example handler
- -- look for auth info
- auth = r.headers_in['Authorization']
- if auth ~= nil then
- -- fake the user
- r.user = 'foo'
- end
+require "string"
- if r.user == nil then
- r:debug("authcheck: user is nil, returning 401")
- r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
- return 401
- elseif r.user == "foo" then
- r:debug('user foo: OK')
- else
- r:debug("authcheck: user='" .. r.user .. "'")
- r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
- return 401
- end
- return apache2.OK
-end</pre>
+--[[
+ This is the default method name for Lua handlers, see the optional
+ function-name in the LuaMapHandler directive to choose a different
+ entry point.
+--]]
+function handle(r)
+ r.content_type = "text/plain"
- <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
- control when this script runs relative to other modules.</p></div>
+ if r.method == 'GET' then
+ r:puts("Hello Lua World!\n")
+ for k, v in pairs( r:parseargs() ) do
+ r:puts( string.format("%s: %s\n", k, v) )
+ end
+ elseif r.method == 'POST' then
+ r:puts("Hello Lua World!\n")
+ for k, v in pairs( r:parsebody() ) do
+ r:puts( string.format("%s: %s\n", k, v) )
+ end
+ elseif r.method == 'PUT' then
+-- use our own Error contents
+ r:puts("Unsupported HTTP method " .. r.method)
+ r.status = 405
+ return apache2.ok
+ else
+-- use the ErrorDocument
+ return 501
+ end
+ return apache2.OK
+end</pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaHookCheckUserID" id="LuaHookCheckUserID">LuaHookCheckUserID</a> <a name="luahookcheckuserid" id="luahookcheckuserid">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the check_user_id phase of request processing</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is supported in 2.3.15 and later</td></tr>
-</table><p>...</p>
- <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
- control when this script runs relative to other modules.</p></div>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaHookFixups" id="LuaHookFixups">LuaHookFixups</a> <a name="luahookfixups" id="luahookfixups">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the fixups phase of a request
-processing</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookFixups /path/to/lua/script.lua hook_function_name</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-</table>
<p>
- Just like LuaHookTranslateName, but executed at the fixups phase
+This handler function just prints out the uri or form encoded
+arguments to a plaintext page.
</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaHookInsertFilter" id="LuaHookInsertFilter">LuaHookInsertFilter</a> <a name="luahookinsertfilter" id="luahookinsertfilter">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the insert_filter phase of request processing</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-</table><p>Not Yet Implemented</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaHookLog" id="LuaHookLog">LuaHookLog</a> <a name="luahooklog" id="luahooklog">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the access log phase of a request
-processing</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookLog /path/to/lua/script.lua log_function_name</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-</table>
<p>
- This simple logging hook allows you to run a function when httpd enters the
- logging phase of a request. With it, you can append data to your own logs,
- manipulate data before the regular log is written, or prevent a log entry
- from being created. To prevent the usual logging from happening, simply return
- <code>apache2.DONE</code> in your logging handler, otherwise return
- <code>apache2.OK</code> to tell httpd to log as normal.
+This means (and in fact encourages) that you can have multiple
+handlers (or hooks, or filters) in the same script.
</p>
-<p>Example:</p>
-<pre class="prettyprint lang-config">LuaHookLog "/path/to/script.lua" logger</pre>
-<pre class="prettyprint lang-lua">-- /path/to/script.lua --
-function logger(r)
- -- flip a coin:
- -- If 1, then we write to our own Lua log and tell httpd not to log
- -- in the main log.
- -- If 2, then we just sanitize the output a bit and tell httpd to
- -- log the sanitized bits.
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="writingauthzproviders" id="writingauthzproviders">Writing Authorization Providers</a></h2>
- if math.random(1,2) == 1 then
- -- Log stuff ourselves and don't log in the regular log
- local f = io.open("/foo/secret.log", "a")
- if f then
- f:write("Something secret happened at " .. r.uri .. "\n")
- f:close()
- end
- return apache2.DONE -- Tell httpd not to use the regular logging functions
- else
- r.uri = r.uri:gsub("somesecretstuff", "") -- sanitize the URI
- return apache2.OK -- tell httpd to log it.
- end
-end</pre>
+<p><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> provides a high-level interface to
+authorization that is much easier to use than using into the relevant
+hooks directly. The first argument to the
+<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive gives
+the name of the responsible authorization provider. For any
+<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> line,
+<code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> will call the authorization provider
+of the given name, passing the rest of the line as parameters. The
+provider will then check authorization and pass the result as return
+value.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaHookMapToStorage" id="LuaHookMapToStorage">LuaHookMapToStorage</a> <a name="luahookmaptostorage" id="luahookmaptostorage">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the map_to_storage phase of request processing</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-</table>
- <p>Like <code class="directive">LuaHookTranslateName</code> but executed at the
- map-to-storage phase of a request. Modules like mod_cache run at this phase,
- which makes for an interesting example on what to do here:</p>
- <pre class="prettyprint lang-config">LuaHookMapToStorage "/path/to/lua/script.lua" check_cache</pre>
+<p>The authz provider is normally called before authentication. If it needs to
+know the authenticated user name (or if the user will be authenticated at
+all), the provider must return <code>apache2.AUTHZ_DENIED_NO_USER</code>.
+This will cause authentication to proceed and the authz provider to be
+called a second time.</p>
- <pre class="prettyprint lang-lua">require"apache2"
-cached_files = {}
+<p>The following authz provider function takes two arguments, one ip
+address and one user name. It will allow access from the given ip address
+without authentication, or if the authenticated user matches the second
+argument:</p>
-function read_file(filename)
- local input = io.open(filename, "r")
- if input then
- local data = input:read("*a")
- cached_files[filename] = data
- file = cached_files[filename]
- input:close()
- end
- return cached_files[filename]
-end
+<pre class="prettyprint lang-lua">
+<strong>authz_provider.lua</strong><br />
-function check_cache(r)
- if r.filename:match("%.png$") then -- Only match PNG files
- local file = cached_files[r.filename] -- Check cache entries
- if not file then
- file = read_file(r.filename) -- Read file into cache
- end
- if file then -- If file exists, write it out
- r.status = 200
- r:write(file)
- r:info(("Sent %s to client from cache"):format(r.filename))
- return apache2.DONE -- skip default handler for PNG files
- end
+require 'apache2'
+
+function authz_check_foo(r, ip, user)
+ if r.useragent_ip == ip then
+ return apache2.AUTHZ_GRANTED
+ elseif r.user == nil then
+ return apache2.AUTHZ_DENIED_NO_USER
+ elseif r.user == user then
+ return apache2.AUTHZ_GRANTED
+ else
+ return apache2.AUTHZ_DENIED
end
- return apache2.DECLINED -- If we had nothing to do, let others serve this.
end</pre>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaHookTranslateName" id="LuaHookTranslateName">LuaHookTranslateName</a> <a name="luahooktranslatename" id="luahooktranslatename">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the translate name phase of request processing</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is supported in 2.3.15 and later</td></tr>
-</table><p>
- Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
- request processing. The hook function receives a single
- argument, the request_rec, and should return a status code,
- which is either an HTTP error code, or the constants defined
- in the apache2 module: apache2.OK, apache2.DECLINED, or
- apache2.DONE. </p>
+<p>The following configuration registers this function as provider
+<code>foo</code> and configures it for URL <code>/</code>:</p>
+<pre class="prettyprint lang-config">LuaAuthzProvider foo authz_provider.lua authz_check_foo
+<Location "/">
+ Require foo 10.1.2.3 john_doe
+</Location></pre>
- <p>For those new to hooks, basically each hook will be invoked
- until one of them returns apache2.OK. If your hook doesn't
- want to do the translation it should just return
- apache2.DECLINED. If the request should stop processing, then
- return apache2.DONE.</p>
- <p>Example:</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="writinghooks" id="writinghooks">Writing Hooks</a></h2>
-<pre class="prettyprint lang-config"># httpd.conf
-LuaHookTranslateName "/scripts/conf/hooks.lua" silly_mapper</pre>
+<p>Hook functions are how modules (and Lua scripts) participate in the
+processing of requests. Each type of hook exposed by the server exists for
+a specific purpose, such as mapping requests to the file system,
+performing access control, or setting mime types:</p>
+
+<table class="bordered"><tr class="header">
+ <th>Hook phase</th>
+ <th>mod_lua directive</th>
+ <th>Description</th>
+ </tr>
+<tr>
+ <td>Quick handler</td>
+ <td><code class="directive"><a href="#luaquickhandler">LuaQuickHandler</a></code></td>
+ <td>This is the first hook that will be called after a request has
+ been mapped to a host or virtual host</td>
+ </tr>
+<tr class="odd">
+ <td>Translate name</td>
+ <td><code class="directive"><a href="#luahooktranslatename">LuaHookTranslateName</a></code></td>
+ <td>This phase translates the requested URI into a filename on the
+ system. Modules such as <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and
+ <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> operate in this phase.</td>
+ </tr>
+<tr>
+ <td>Map to storage</td>
+ <td><code class="directive"><a href="#luahookmaptostorage">LuaHookMapToStorage</a></code></td>
+ <td>This phase maps files to their physical, cached or external/proxied storage.
+ It can be used by proxy or caching modules</td>
+ </tr>
+<tr class="odd">
+ <td>Check Access</td>
+ <td><code class="directive"><a href="#luahookaccesschecker">LuaHookAccessChecker</a></code></td>
+ <td>This phase checks whether a client has access to a resource. This
+ phase is run before the user is authenticated, so beware.
+ </td>
+ </tr>
+<tr>
+ <td>Check User ID</td>
+ <td><code class="directive"><a href="#luahookcheckuserid">LuaHookCheckUserID</a></code></td>
+ <td>This phase it used to check the negotiated user ID</td>
+ </tr>
+<tr class="odd">
+ <td>Check Authorization</td>
+ <td><code class="directive"><a href="#luahookauthchecker">LuaHookAuthChecker</a></code> or
+ <code class="directive"><a href="#luaauthzprovider">LuaAuthzProvider</a></code></td>
+ <td>This phase authorizes a user based on the negotiated credentials, such as
+ user ID, client certificate etc.
+ </td>
+ </tr>
+<tr>
+ <td>Check Type</td>
+ <td><code class="directive"><a href="#luahooktypechecker">LuaHookTypeChecker</a></code></td>
+ <td>This phase checks the requested file and assigns a content type and
+ a handler to it</td>
+ </tr>
+<tr class="odd">
+ <td>Fixups</td>
+ <td><code class="directive"><a href="#luahookfixups">LuaHookFixups</a></code></td>
+ <td>This is the final "fix anything" phase before the content handlers
+ are run. Any last-minute changes to the request should be made here.</td>
+ </tr>
+<tr>
+ <td>Content handler</td>
+ <td>fx. <code>.lua</code> files or through <code class="directive"><a href="#luamaphandler">LuaMapHandler</a></code></td>
+ <td>This is where the content is handled. Files are read, parsed, some are run,
+ and the result is sent to the client</td>
+ </tr>
+<tr class="odd">
+ <td>Logging</td>
+ <td><code class="directive"><a href="#luahooklog">LuaHookLog</a></code></td>
+ <td>Once a request has been handled, it enters several logging phases,
+ which logs the request in either the error or access log. Mod_lua
+ is able to hook into the start of this and control logging output.</td>
+ </tr>
+</table>
+
+<p>Hook functions are passed the request object as their only argument
+(except for LuaAuthzProvider, which also gets passed the arguments from
+the Require directive).
+They can return any value, depending on the hook, but most commonly
+they'll return OK, DONE, or DECLINED, which you can write in Lua as
+<code>apache2.OK</code>, <code>apache2.DONE</code>, or
+<code>apache2.DECLINED</code>, or else an HTTP status code.</p>
-<pre class="prettyprint lang-lua">-- /scripts/conf/hooks.lua --
-require "apache2"
-function silly_mapper(r)
- if r.uri == "/" then
- r.filename = "/var/www/home.lua"
+<pre class="prettyprint lang-lua">
+<strong>translate_name.lua</strong><br />
+-- example hook that rewrites the URI to a filesystem path.
+
+require 'apache2'
+
+function translate_name(r)
+ if r.uri == "/translate-name" then
+ r.filename = r.document_root .. "/find_me.txt"
return apache2.OK
- else
- return apache2.DECLINED
end
+ -- we don't care about this URL, give another module a chance
+ return apache2.DECLINED
end</pre>
- <div class="note"><h3>Context</h3><p>This directive is not valid in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>, <code class="directive"><a href="../mod/core.html#files"><Files></a></code>, or htaccess
- context.</p></div>
- <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
- control when this script runs relative to other modules.</p></div>
+<pre class="prettyprint lang-lua">
+<strong>translate_name2.lua</strong><br />
+--[[ example hook that rewrites one URI to another URI. It returns a
+ apache2.DECLINED to give other URL mappers a chance to work on the
+ substitution, including the core translate_name hook which maps based
+ on the DocumentRoot.
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaHookTypeChecker" id="LuaHookTypeChecker">LuaHookTypeChecker</a> <a name="luahooktypechecker" id="luahooktypechecker">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the type_checker phase of request processing</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-</table><p>
- This directive provides a hook for the type_checker phase of the request processing.
- This phase is where requests are assigned a content type and a handler, and thus can
- be used to modify the type and handler based on input:
- </p>
- <pre class="prettyprint lang-config">LuaHookTypeChecker "/path/to/lua/script.lua" type_checker</pre>
-
- <pre class="prettyprint lang-lua"> function type_checker(r)
- if r.uri:match("%.to_gif$") then -- match foo.png.to_gif
- r.content_type = "image/gif" -- assign it the image/gif type
- r.handler = "gifWizard" -- tell the gifWizard module to handle this
- r.filename = r.uri:gsub("%.to_gif$", "") -- fix the filename requested
- return apache2.OK
- end
-
- return apache2.DECLINED
- end</pre>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaInherit" id="LuaInherit">LuaInherit</a> <a name="luainherit" id="luainherit">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls how parent configuration sections are merged into children</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaInherit none|parent-first|parent-last</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaInherit parent-first</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.0 and later</td></tr>
-</table><p>By default, if LuaHook* directives are used in overlapping
- Directory or Location configuration sections, the scripts defined in the
- more specific section are run <em>after</em> those defined in the more
- generic section (LuaInherit parent-first). You can reverse this order, or
- make the parent context not apply at all.</p>
-
- <p> In previous 2.3.x releases, the default was effectively to ignore LuaHook*
- directives from parent configuration sections.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaInputFilter" id="LuaInputFilter">LuaInputFilter</a> <a name="luainputfilter" id="luainputfilter">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a Lua function for content input filtering</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaInputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.5 and later</td></tr>
-</table>
-<p>Provides a means of adding a Lua function as an input filter.
-As with output filters, input filters work as coroutines,
-first yielding before buffers are sent, then yielding whenever
-a bucket needs to be passed down the chain, and finally (optionally)
-yielding anything that needs to be appended to the input data. The
-global variable <code>bucket</code> holds the buckets as they are passed
-onto the Lua script:
-</p>
-
-<pre class="prettyprint lang-config">LuaInputFilter myInputFilter "/www/filter.lua" input_filter
-<Files "*.lua">
- SetInputFilter myInputFilter
-</Files></pre>
-
-<pre class="prettyprint lang-lua">--[[
- Example input filter that converts all POST data to uppercase.
-]]--
-function input_filter(r)
- print("luaInputFilter called") -- debug print
- coroutine.yield() -- Yield and wait for buckets
- while bucket do -- For each bucket, do...
- local output = string.upper(bucket) -- Convert all POST data to uppercase
- coroutine.yield(output) -- Send converted data down the chain
- end
- -- No more buckets available.
- coroutine.yield("&filterSignature=1234") -- Append signature at the end
-end</pre>
-
-<p>
-The input filter supports denying/skipping a filter if it is deemed unwanted:
-</p>
-<pre class="prettyprint lang-lua">function input_filter(r)
- if not good then
- return -- Simply deny filtering, passing on the original content instead
- end
- coroutine.yield() -- wait for buckets
- ... -- insert filter stuff here
-end</pre>
-
-<p>
-See "<a href="#modifying_buckets">Modifying contents with Lua
-filters</a>" for more information.
-</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaMapHandler" id="LuaMapHandler">LuaMapHandler</a> <a name="luamaphandler" id="luamaphandler">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Map a path to a lua handler</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-</table>
- <p>This directive matches a uri pattern to invoke a specific
- handler function in a specific file. It uses PCRE regular
- expressions to match the uri, and supports interpolating
- match groups into both the file path and the function name.
- Be careful writing your regular expressions to avoid security
- issues.</p>
- <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">LuaMapHandler "/(\w+)/(\w+)" "/scripts/$1.lua" "handle_$2"</pre>
-</div>
- <p>This would match uri's such as /photos/show?id=9
- to the file /scripts/photos.lua and invoke the
- handler function handle_show on the lua vm after
- loading that file.</p>
-
-<pre class="prettyprint lang-config">LuaMapHandler "/bingo" "/scripts/wombat.lua"</pre>
-
- <p>This would invoke the "handle" function, which
- is the default if no specific function name is
- provided.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaOutputFilter" id="LuaOutputFilter">LuaOutputFilter</a> <a name="luaoutputfilter" id="luaoutputfilter">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a Lua function for content output filtering</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaOutputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.5 and later</td></tr>
-</table>
-<p>Provides a means of adding a Lua function as an output filter.
-As with input filters, output filters work as coroutines,
-first yielding before buffers are sent, then yielding whenever
-a bucket needs to be passed down the chain, and finally (optionally)
-yielding anything that needs to be appended to the input data. The
-global variable <code>bucket</code> holds the buckets as they are passed
-onto the Lua script:
-</p>
-
-<pre class="prettyprint lang-config">LuaOutputFilter myOutputFilter "/www/filter.lua" output_filter
-<Files "*.lua">
- SetOutputFilter myOutputFilter
-</Files></pre>
-
-<pre class="prettyprint lang-lua">--[[
- Example output filter that escapes all HTML entities in the output
-]]--
-function output_filter(r)
- coroutine.yield("(Handled by myOutputFilter)<br/>\n") -- Prepend some data to the output,
- -- yield and wait for buckets.
- while bucket do -- For each bucket, do...
- local output = r:escape_html(bucket) -- Escape all output
- coroutine.yield(output) -- Send converted data down the chain
- end
- -- No more buckets available.
-end</pre>
-
-<p>
-As with the input filter, the output filter supports denying/skipping a filter
-if it is deemed unwanted:
-</p>
-<pre class="prettyprint lang-lua">function output_filter(r)
- if not r.content_type:match("text/html") then
- return -- Simply deny filtering, passing on the original content instead
- end
- coroutine.yield() -- wait for buckets
- ... -- insert filter stuff here
-end</pre>
-
-<div class="note"><h3>Lua filters with <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code></h3>
-<p> When a Lua filter is used as the underlying provider via the
-<code class="directive"><a href="../mod/mod_filter.html#filterprovider">FilterProvider</a></code> directive, filtering
-will only work when the <var>filter-name</var> is identical to the <var>provider-name</var>.
-</p> </div>
-
-<p>
-See "<a href="#modifying_buckets">Modifying contents with Lua filters</a>" for more
-information.
-</p>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaPackageCPath" id="LuaPackageCPath">LuaPackageCPath</a> <a name="luapackagecpath" id="luapackagecpath">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.cpath</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackageCPath /path/to/include/?.soa</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-</table>
- <p>Add a path to lua's shared library search path. Follows the same
- conventions as lua. This just munges the package.cpath in the
- lua vms.</p>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaPackagePath" id="LuaPackagePath">LuaPackagePath</a> <a name="luapackagepath" id="luapackagepath">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.path</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackagePath /path/to/include/?.lua</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-</table><p>Add a path to lua's module search path. Follows the same
- conventions as lua. This just munges the package.path in the
- lua vms.</p>
-
- <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">LuaPackagePath "/scripts/lib/?.lua"
-LuaPackagePath "/scripts/lib/?/init.lua"</pre>
-</div>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaQuickHandler" id="LuaQuickHandler">LuaQuickHandler</a> <a name="luaquickhandler" id="luaquickhandler">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the quick handler of request processing</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaQuickHandler /path/to/script.lua hook_function_name</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-</table>
- <p>
- This phase is run immediately after the request has been mapped to a virtal host,
- and can be used to either do some request processing before the other phases kick
- in, or to serve a request without the need to translate, map to storage et cetera.
- As this phase is run before anything else, directives such as <code class="directive"><a href="../mod/core.html#location"><Location></a></code> or <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> are void in this phase, just as
- URIs have not been properly parsed yet.
- </p>
- <div class="note"><h3>Context</h3><p>This directive is not valid in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>, <code class="directive"><a href="../mod/core.html#files"><Files></a></code>, or htaccess
- context.</p></div>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaRoot" id="LuaRoot">LuaRoot</a> <a name="luaroot" id="luaroot">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify the base path for resolving relative paths for mod_lua directives</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaRoot /path/to/a/directory</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-</table>
- <p>Specify the base path which will be used to evaluate all
- relative paths within mod_lua. If not specified they
- will be resolved relative to the current working directory,
- which may not always work well for a server.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LuaScope" id="LuaScope">LuaScope</a> <a name="luascope" id="luascope">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>One of once, request, conn, thread -- default is once</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaScope once|request|conn|thread|server [min] [max]</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaScope once</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
-</table>
- <p>Specify the life cycle scope of the Lua interpreter which will
- be used by handlers in this "Directory." The default is "once"</p>
-
- <dl>
- <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
-
- <dt>request:</dt> <dd>use the interpreter to handle anything based on
- the same file within this request, which is also
- request scoped.</dd>
-
- <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
-
- <dt>thread:</dt> <dd>Use the interpreter for the lifetime of the thread
- handling the request (only available with threaded MPMs).</dd>
-
- <dt>server:</dt> <dd>This one is different than others because the
- server scope is quite long lived, and multiple threads
- will have the same server_rec. To accommodate this,
- server scoped Lua states are stored in an apr
- resource list. The <code>min</code> and <code>max</code> arguments
- specify the minimum and maximum number of Lua states to keep in the
- pool.</dd>
- </dl>
- <p>
- Generally speaking, the <code>thread</code> and <code>server</code> scopes
- execute roughly 2-3 times faster than the rest, because they don't have to
- spawn new Lua states on every request (especially with the event MPM, as
- even keepalive requests will use a new thread for each request). If you are
- satisfied that your scripts will not have problems reusing a state, then
- the <code>thread</code> or <code>server</code> scopes should be used for
- maximum performance. While the <code>thread</code> scope will provide the
- fastest responses, the <code>server</code> scope will use less memory, as
- states are pooled, allowing f.x. 1000 threads to share only 100 Lua states,
- thus using only 10% of the memory required by the <code>thread</code> scope.
- </p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="basicconf" id="basicconf">Basic Configuration</a></h2>
-
-<p>The basic module loading directive is</p>
-
-<pre class="prettyprint lang-config">LoadModule lua_module modules/mod_lua.so</pre>
-
-
-<p>
-<code>mod_lua</code> provides a handler named <code>lua-script</code>,
-which can be used with a <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code> or
-<code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> directive:</p>
-
-<pre class="prettyprint lang-config"><Files "*.lua">
- SetHandler lua-script
-</Files></pre>
-
-
-<p>
-This will cause <code>mod_lua</code> to handle requests for files
-ending in <code>.lua</code> by invoking that file's
-<code>handle</code> function.
-</p>
-
-<p>For more flexibility, see <code class="directive">LuaMapHandler</code>.
-</p>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="writinghandlers" id="writinghandlers">Writing Handlers</a></h2>
-<p> In the Apache HTTP Server API, the handler is a specific kind of hook
-responsible for generating the response. Examples of modules that include a
-handler are <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>,
-and <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>.</p>
-
-<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
-just evaluating a script body CGI style. A handler function looks
-something like this:</p>
-
-
-<pre class="prettyprint lang-lua">
-<strong>example.lua</strong><br />
--- example handler
-
-require "string"
-
---[[
- This is the default method name for Lua handlers, see the optional
- function-name in the LuaMapHandler directive to choose a different
- entry point.
---]]
-function handle(r)
- r.content_type = "text/plain"
-
- if r.method == 'GET' then
- r:puts("Hello Lua World!\n")
- for k, v in pairs( r:parseargs() ) do
- r:puts( string.format("%s: %s\n", k, v) )
- end
- elseif r.method == 'POST' then
- r:puts("Hello Lua World!\n")
- for k, v in pairs( r:parsebody() ) do
- r:puts( string.format("%s: %s\n", k, v) )
- end
- elseif r.method == 'PUT' then
--- use our own Error contents
- r:puts("Unsupported HTTP method " .. r.method)
- r.status = 405
- return apache2.ok
- else
--- use the ErrorDocument
- return 501
- end
- return apache2.OK
-end</pre>
-
-
-<p>
-This handler function just prints out the uri or form encoded
-arguments to a plaintext page.
-</p>
-
-<p>
-This means (and in fact encourages) that you can have multiple
-handlers (or hooks, or filters) in the same script.
-</p>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="writingauthzproviders" id="writingauthzproviders">Writing Authorization Providers</a></h2>
-
-
-<p><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> provides a high-level interface to
-authorization that is much easier to use than using into the relevant
-hooks directly. The first argument to the
-<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive gives
-the name of the responsible authorization provider. For any
-<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> line,
-<code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> will call the authorization provider
-of the given name, passing the rest of the line as parameters. The
-provider will then check authorization and pass the result as return
-value.</p>
-
-<p>The authz provider is normally called before authentication. If it needs to
-know the authenticated user name (or if the user will be authenticated at
-all), the provider must return <code>apache2.AUTHZ_DENIED_NO_USER</code>.
-This will cause authentication to proceed and the authz provider to be
-called a second time.</p>
-
-<p>The following authz provider function takes two arguments, one ip
-address and one user name. It will allow access from the given ip address
-without authentication, or if the authenticated user matches the second
-argument:</p>
-
-<pre class="prettyprint lang-lua">
-<strong>authz_provider.lua</strong><br />
-
-require 'apache2'
-
-function authz_check_foo(r, ip, user)
- if r.useragent_ip == ip then
- return apache2.AUTHZ_GRANTED
- elseif r.user == nil then
- return apache2.AUTHZ_DENIED_NO_USER
- elseif r.user == user then
- return apache2.AUTHZ_GRANTED
- else
- return apache2.AUTHZ_DENIED
- end
-end</pre>
-
-
-<p>The following configuration registers this function as provider
-<code>foo</code> and configures it for URL <code>/</code>:</p>
-<pre class="prettyprint lang-config">LuaAuthzProvider foo authz_provider.lua authz_check_foo
-<Location "/">
- Require foo 10.1.2.3 john_doe
-</Location></pre>
-
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="writinghooks" id="writinghooks">Writing Hooks</a></h2>
-
-<p>Hook functions are how modules (and Lua scripts) participate in the
-processing of requests. Each type of hook exposed by the server exists for
-a specific purpose, such as mapping requests to the file system,
-performing access control, or setting mime types:</p>
-
-<table class="bordered"><tr class="header">
- <th>Hook phase</th>
- <th>mod_lua directive</th>
- <th>Description</th>
- </tr>
-<tr>
- <td>Quick handler</td>
- <td><code class="directive"><a href="#luaquickhandler">LuaQuickHandler</a></code></td>
- <td>This is the first hook that will be called after a request has
- been mapped to a host or virtual host</td>
- </tr>
-<tr class="odd">
- <td>Translate name</td>
- <td><code class="directive"><a href="#luahooktranslatename">LuaHookTranslateName</a></code></td>
- <td>This phase translates the requested URI into a filename on the
- system. Modules such as <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and
- <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> operate in this phase.</td>
- </tr>
-<tr>
- <td>Map to storage</td>
- <td><code class="directive"><a href="#luahookmaptostorage">LuaHookMapToStorage</a></code></td>
- <td>This phase maps files to their physical, cached or external/proxied storage.
- It can be used by proxy or caching modules</td>
- </tr>
-<tr class="odd">
- <td>Check Access</td>
- <td><code class="directive"><a href="#luahookaccesschecker">LuaHookAccessChecker</a></code></td>
- <td>This phase checks whether a client has access to a resource. This
- phase is run before the user is authenticated, so beware.
- </td>
- </tr>
-<tr>
- <td>Check User ID</td>
- <td><code class="directive"><a href="#luahookcheckuserid">LuaHookCheckUserID</a></code></td>
- <td>This phase it used to check the negotiated user ID</td>
- </tr>
-<tr class="odd">
- <td>Check Authorization</td>
- <td><code class="directive"><a href="#luahookauthchecker">LuaHookAuthChecker</a></code> or
- <code class="directive"><a href="#luaauthzprovider">LuaAuthzProvider</a></code></td>
- <td>This phase authorizes a user based on the negotiated credentials, such as
- user ID, client certificate etc.
- </td>
- </tr>
-<tr>
- <td>Check Type</td>
- <td><code class="directive"><a href="#luahooktypechecker">LuaHookTypeChecker</a></code></td>
- <td>This phase checks the requested file and assigns a content type and
- a handler to it</td>
- </tr>
-<tr class="odd">
- <td>Fixups</td>
- <td><code class="directive"><a href="#luahookfixups">LuaHookFixups</a></code></td>
- <td>This is the final "fix anything" phase before the content handlers
- are run. Any last-minute changes to the request should be made here.</td>
- </tr>
-<tr>
- <td>Content handler</td>
- <td>fx. <code>.lua</code> files or through <code class="directive"><a href="#luamaphandler">LuaMapHandler</a></code></td>
- <td>This is where the content is handled. Files are read, parsed, some are run,
- and the result is sent to the client</td>
- </tr>
-<tr class="odd">
- <td>Logging</td>
- <td><code class="directive"><a href="#luahooklog">LuaHookLog</a></code></td>
- <td>Once a request has been handled, it enters several logging phases,
- which logs the request in either the error or access log. Mod_lua
- is able to hook into the start of this and control logging output.</td>
- </tr>
-</table>
-
-<p>Hook functions are passed the request object as their only argument
-(except for LuaAuthzProvider, which also gets passed the arguments from
-the Require directive).
-They can return any value, depending on the hook, but most commonly
-they'll return OK, DONE, or DECLINED, which you can write in Lua as
-<code>apache2.OK</code>, <code>apache2.DONE</code>, or
-<code>apache2.DECLINED</code>, or else an HTTP status code.</p>
-
-
-<pre class="prettyprint lang-lua">
-<strong>translate_name.lua</strong><br />
--- example hook that rewrites the URI to a filesystem path.
-
-require 'apache2'
-
-function translate_name(r)
- if r.uri == "/translate-name" then
- r.filename = r.document_root .. "/find_me.txt"
- return apache2.OK
- end
- -- we don't care about this URL, give another module a chance
- return apache2.DECLINED
-end</pre>
-
-
-
-<pre class="prettyprint lang-lua">
-<strong>translate_name2.lua</strong><br />
---[[ example hook that rewrites one URI to another URI. It returns a
- apache2.DECLINED to give other URL mappers a chance to work on the
- substitution, including the core translate_name hook which maps based
- on the DocumentRoot.
-
- Note: Use the early/late flags in the directive to make it run before
- or after mod_alias.
---]]
+ Note: Use the early/late flags in the directive to make it run before
+ or after mod_alias.
+--]]
require 'apache2'
end</pre>
-<pre class="prettyprint lang-lua">r:addoutputfilter(name|function) -- add an output filter:
+<pre class="prettyprint lang-lua">r:addoutputfilter(name|function) -- add an output filter:
+
+r:addoutputfilter("fooFilter") -- add the fooFilter to the output stream</pre>
+
+
+<pre class="prettyprint lang-lua">r:sendfile(filename) -- sends an entire file to the client, using sendfile if supported by the current platform:
+
+if use_sendfile_thing then
+ r:sendfile("/var/www/large_file.img")
+end</pre>
+
+
+<pre class="prettyprint lang-lua">r:parseargs() -- returns two tables; one standard key/value table for regular GET data,
+ -- and one for multi-value data (fx. foo=1&foo=2&foo=3):
+
+local GET, GETMULTI = r:parseargs()
+r:puts("Your name is: " .. GET['name'] or "Unknown")</pre>
+
+
+<pre class="prettyprint lang-lua">r:parsebody([sizeLimit]) -- parse the request body as a POST and return two lua tables,
+ -- just like r:parseargs().
+ -- An optional number may be passed to specify the maximum number
+ -- of bytes to parse. Default is 8192 bytes:
+
+local POST, POSTMULTI = r:parsebody(1024*1024)
+r:puts("Your name is: " .. POST['name'] or "Unknown")</pre>
+
+
+<pre class="prettyprint lang-lua">r:puts("hello", " world", "!") -- print to response body, self explanatory</pre>
+
+
+<pre class="prettyprint lang-lua">r:write("a single string") -- print to response body, self explanatory</pre>
+
+
+<pre class="prettyprint lang-lua">r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result</pre>
+
+
+<pre class="prettyprint lang-lua">r:base64_encode(string) -- Encodes a string using the Base64 encoding standard:
+
+local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=</pre>
+
+
+<pre class="prettyprint lang-lua">r:base64_decode(string) -- Decodes a Base64-encoded string:
+
+local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'</pre>
+
+
+<pre class="prettyprint lang-lua">r:md5(string) -- Calculates and returns the MD5 digest of a string (binary safe):
+
+local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339</pre>
+
+
+<pre class="prettyprint lang-lua">r:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe):
+
+local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19</pre>
+
+
+<pre class="prettyprint lang-lua">r:escape(string) -- URL-Escapes a string:
+
+local url = "http://foo.bar/1 2 3 & 4 + 5"
+local escaped = r:escape(url) -- returns 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5'</pre>
+
+
+<pre class="prettyprint lang-lua">r:unescape(string) -- Unescapes an URL-escaped string:
+
+local url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5"
+local unescaped = r:unescape(url) -- returns 'http://foo.bar/1 2 3 & 4 + 5'</pre>
+
+
+<pre class="prettyprint lang-lua">r:construct_url(string) -- Constructs an URL from an URI
+
+local url = r:construct_url(r.uri)</pre>
+
+
+<pre class="prettyprint lang-lua">r.mpm_query(number) -- Queries the server for MPM information using ap_mpm_query:
+
+local mpm = r.mpm_query(14)
+if mpm == 1 then
+ r:puts("This server uses the Event MPM")
+end</pre>
+
+
+<pre class="prettyprint lang-lua">r:expr(string) -- Evaluates an <a href="../expr.html">expr</a> string.
+
+if r:expr("%{HTTP_HOST} =~ /^www/") then
+ r:puts("This host name starts with www")
+end</pre>
+
+
+<pre class="prettyprint lang-lua">r:scoreboard_process(a) -- Queries the server for information about the process at position <code>a</code>:
+
+local process = r:scoreboard_process(1)
+r:puts("Server 1 has PID " .. process.pid)</pre>
+
+
+<pre class="prettyprint lang-lua">r:scoreboard_worker(a, b) -- Queries for information about the worker thread, <code>b</code>, in process <code>a</code>:
+
+local thread = r:scoreboard_worker(1, 1)
+r:puts("Server 1's thread 1 has thread ID " .. thread.tid .. " and is in " .. thread.status .. " status")</pre>
+
+
+
+<pre class="prettyprint lang-lua">r:clock() -- Returns the current time with microsecond precision</pre>
+
+
+<pre class="prettyprint lang-lua">r:requestbody(filename) -- Reads and returns the request body of a request.
+ -- If 'filename' is specified, it instead saves the
+ -- contents to that file:
+
+local input = r:requestbody()
+r:puts("You sent the following request body to me:\n")
+r:puts(input)</pre>
+
+
+<pre class="prettyprint lang-lua">r:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter</pre>
+
+
+<pre class="prettyprint lang-lua">r.module_info(module_name) -- Queries the server for information about a module
+
+local mod = r.module_info("mod_lua.c")
+if mod then
+ for k, v in pairs(mod.commands) do
+ r:puts( ("%s: %s\n"):format(k,v)) -- print out all directives accepted by this module
+ end
+end</pre>
+
+
+<pre class="prettyprint lang-lua">r:loaded_modules() -- Returns a list of modules loaded by httpd:
+
+for k, module in pairs(r:loaded_modules()) do
+ r:puts("I have loaded module " .. module .. "\n")
+end</pre>
+
+
+<pre class="prettyprint lang-lua">r:runtime_dir_relative(filename) -- Compute the name of a run-time file (e.g., shared memory "file")
+ -- relative to the appropriate run-time directory.</pre>
+
+
+<pre class="prettyprint lang-lua">r:server_info() -- Returns a table containing server information, such as
+ -- the name of the httpd executable file, mpm used etc.</pre>
+
+
+<pre class="prettyprint lang-lua">r:set_document_root(file_path) -- Sets the document root for the request to file_path</pre>
+
+
+
+
+<pre class="prettyprint lang-lua">r:set_context_info(prefix, docroot) -- Sets the context prefix and context document root for a request</pre>
+
+
+<pre class="prettyprint lang-lua">r:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependent way</pre>
+
+
+<pre class="prettyprint lang-lua">r:escape_logitem(string) -- Escapes a string for logging</pre>
-r:addoutputfilter("fooFilter") -- add the fooFilter to the output stream</pre>
+<pre class="prettyprint lang-lua">r.strcmp_match(string, pattern) -- Checks if 'string' matches 'pattern' using strcmp_match (globs).
+ -- fx. whether 'www.example.com' matches '*.example.com':
+
+local match = r.strcmp_match("foobar.com", "foo*.com")
+if match then
+ r:puts("foobar.com matches foo*.com")
+end</pre>
-<pre class="prettyprint lang-lua">r:sendfile(filename) -- sends an entire file to the client, using sendfile if supported by the current platform:
-if use_sendfile_thing then
- r:sendfile("/var/www/large_file.img")
-end</pre>
+<pre class="prettyprint lang-lua">r:set_keepalive() -- Sets the keepalive status for a request. Returns true if possible, false otherwise.</pre>
-<pre class="prettyprint lang-lua">r:parseargs() -- returns two tables; one standard key/value table for regular GET data,
- -- and one for multi-value data (fx. foo=1&foo=2&foo=3):
+<pre class="prettyprint lang-lua">r:make_etag() -- Constructs and returns the etag for the current request.</pre>
-local GET, GETMULTI = r:parseargs()
-r:puts("Your name is: " .. GET['name'] or "Unknown")</pre>
+<pre class="prettyprint lang-lua">r:send_interim_response(clear) -- Sends an interim (1xx) response to the client.
+ -- if 'clear' is true, available headers will be sent and cleared.</pre>
-<pre class="prettyprint lang-lua">r:parsebody([sizeLimit]) -- parse the request body as a POST and return two lua tables,
- -- just like r:parseargs().
- -- An optional number may be passed to specify the maximum number
- -- of bytes to parse. Default is 8192 bytes:
-
-local POST, POSTMULTI = r:parsebody(1024*1024)
-r:puts("Your name is: " .. POST['name'] or "Unknown")</pre>
+<pre class="prettyprint lang-lua">r:custom_response(status_code, string) -- Construct and set a custom response for a given status code.
+ -- This works much like the ErrorDocument directive:
+
+r:custom_response(404, "Baleted!")</pre>
-<pre class="prettyprint lang-lua">r:puts("hello", " world", "!") -- print to response body, self explanatory</pre>
+<pre class="prettyprint lang-lua">r.exists_config_define(string) -- Checks whether a configuration definition exists or not:
-<pre class="prettyprint lang-lua">r:write("a single string") -- print to response body, self explanatory</pre>
+if r.exists_config_define("FOO") then
+ r:puts("httpd was probably run with -DFOO, or it was defined in the configuration")
+end</pre>
-<pre class="prettyprint lang-lua">r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result</pre>
+<pre class="prettyprint lang-lua">r:state_query(string) -- Queries the server for state information</pre>
-<pre class="prettyprint lang-lua">r:base64_encode(string) -- Encodes a string using the Base64 encoding standard:
+<pre class="prettyprint lang-lua">r:stat(filename [,wanted]) -- Runs stat() on a file, and returns a table with file information:
-local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=</pre>
+local info = r:stat("/var/www/foo.txt")
+if info then
+ r:puts("This file exists and was last modified at: " .. info.modified)
+end</pre>
-<pre class="prettyprint lang-lua">r:base64_decode(string) -- Decodes a Base64-encoded string:
+<pre class="prettyprint lang-lua">r:regex(string, pattern [,flags]) -- Runs a regular expression match on a string, returning captures if matched:
-local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'</pre>
+local matches = r:regex("foo bar baz", [[foo (\w+) (\S*)]])
+if matches then
+ r:puts("The regex matched, and the last word captured ($2) was: " .. matches[2])
+end
+-- Example ignoring case sensitivity:
+local matches = r:regex("FOO bar BAz", [[(foo) bar]], 1)
-<pre class="prettyprint lang-lua">r:md5(string) -- Calculates and returns the MD5 digest of a string (binary safe):
+-- Flags can be a bitwise combination of:
+-- 0x01: Ignore case
+-- 0x02: Multiline search</pre>
-local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339</pre>
+<pre class="prettyprint lang-lua">r.usleep(number_of_microseconds) -- Puts the script to sleep for a given number of microseconds.</pre>
-<pre class="prettyprint lang-lua">r:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe):
-local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19</pre>
+<pre class="prettyprint lang-lua">r:dbacquire(dbType[, dbParams]) -- Acquires a connection to a database and returns a database class.
+ -- See '<a href="#databases">Database connectivity</a>' for details.</pre>
-<pre class="prettyprint lang-lua">r:escape(string) -- URL-Escapes a string:
+<pre class="prettyprint lang-lua">r:ivm_set("key", value) -- Set an Inter-VM variable to hold a specific value.
+ -- These values persist even though the VM is gone or not being used,
+ -- and so should only be used if MaxConnectionsPerChild is > 0
+ -- Values can be numbers, strings and booleans, and are stored on a
+ -- per process basis (so they won't do much good with a prefork mpm)
+
+r:ivm_get("key") -- Fetches a variable set by ivm_set. Returns the contents of the variable
+ -- if it exists or nil if no such variable exists.
+
+-- An example getter/setter that saves a global variable outside the VM:
+function handle(r)
+ -- First VM to call this will get no value, and will have to create it
+ local foo = r:ivm_get("cached_data")
+ if not foo then
+ foo = do_some_calcs() -- fake some return value
+ r:ivm_set("cached_data", foo) -- set it globally
+ end
+ r:puts("Cached data is: ", foo)
+end</pre>
-local url = "http://foo.bar/1 2 3 & 4 + 5"
-local escaped = r:escape(url) -- returns 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5'</pre>
+<pre class="prettyprint lang-lua">r:htpassword(string [,algorithm [,cost]]) -- Creates a password hash from a string.
+ -- algorithm: 0 = APMD5 (default), 1 = SHA, 2 = BCRYPT, 3 = CRYPT.
+ -- cost: only valid with BCRYPT algorithm (default = 5).</pre>
-<pre class="prettyprint lang-lua">r:unescape(string) -- Unescapes an URL-escaped string:
-local url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5"
-local unescaped = r:unescape(url) -- returns 'http://foo.bar/1 2 3 & 4 + 5'</pre>
+<pre class="prettyprint lang-lua">r:mkdir(dir [,mode]) -- Creates a directory and sets mode to optional mode paramter.</pre>
-<pre class="prettyprint lang-lua">r:construct_url(string) -- Constructs an URL from an URI
+<pre class="prettyprint lang-lua">r:mkrdir(dir [,mode]) -- Creates directories recursive and sets mode to optional mode paramter.</pre>
-local url = r:construct_url(r.uri)</pre>
+<pre class="prettyprint lang-lua">r:rmdir(dir) -- Removes a directory.</pre>
-<pre class="prettyprint lang-lua">r.mpm_query(number) -- Queries the server for MPM information using ap_mpm_query:
-local mpm = r.mpm_query(14)
-if mpm == 1 then
- r:puts("This server uses the Event MPM")
-end</pre>
+<pre class="prettyprint lang-lua">r:touch(file [,mtime]) -- Sets the file modification time to current time or to optional mtime msec value.</pre>
-<pre class="prettyprint lang-lua">r:expr(string) -- Evaluates an <a href="../expr.html">expr</a> string.
+<pre class="prettyprint lang-lua">r:get_direntries(dir) -- Returns a table with all directory entries.
-if r:expr("%{HTTP_HOST} =~ /^www/") then
- r:puts("This host name starts with www")
+function handle(r)
+ local dir = r.context_document_root
+ for _, f in ipairs(r:get_direntries(dir)) do
+ local info = r:stat(dir .. "/" .. f)
+ if info then
+ local mtime = os.date(fmt, info.mtime / 1000000)
+ local ftype = (info.filetype == 2) and "[dir] " or "[file]"
+ r:puts( ("%s %s %10i %s\n"):format(ftype, mtime, info.size, f) )
+ end
+ end
end</pre>
-<pre class="prettyprint lang-lua">r:scoreboard_process(a) -- Queries the server for information about the process at position <code>a</code>:
+<pre class="prettyprint lang-lua">r.date_parse_rfc(string) -- Parses a date/time string and returns seconds since epoche.</pre>
-local process = r:scoreboard_process(1)
-r:puts("Server 1 has PID " .. process.pid)</pre>
+<pre class="prettyprint lang-lua">r:getcookie(key) -- Gets a HTTP cookie</pre>
-<pre class="prettyprint lang-lua">r:scoreboard_worker(a, b) -- Queries for information about the worker thread, <code>b</code>, in process <code>a</code>:
-local thread = r:scoreboard_worker(1, 1)
-r:puts("Server 1's thread 1 has thread ID " .. thread.tid .. " and is in " .. thread.status .. " status")</pre>
+<pre class="prettyprint lang-lua">r:setcookie{
+ key = [key],
+ value = [value],
+ expires = [expiry],
+ secure = [boolean],
+ httponly = [boolean],
+ path = [path],
+ domain = [domain]
+} -- Sets a HTTP cookie, for instance:
+r:setcookie{
+ key = "cookie1",
+ value = "HDHfa9eyffh396rt",
+ expires = os.time() + 86400,
+ secure = true
+}</pre>
-<pre class="prettyprint lang-lua">r:clock() -- Returns the current time with microsecond precision</pre>
+<pre class="prettyprint lang-lua">r:wsupgrade() -- Upgrades a connection to WebSockets if possible (and requested):
+if r:wsupgrade() then -- if we can upgrade:
+ r:wswrite("Welcome to websockets!") -- write something to the client
+ r:wsclose() -- goodbye!
+end</pre>
-<pre class="prettyprint lang-lua">r:requestbody(filename) -- Reads and returns the request body of a request.
- -- If 'filename' is specified, it instead saves the
- -- contents to that file:
-
-local input = r:requestbody()
-r:puts("You sent the following request body to me:\n")
-r:puts(input)</pre>
+<pre class="prettyprint lang-lua">r:wsread() -- Reads a WebSocket frame from a WebSocket upgraded connection (see above):
+
+local line, isFinal = r:wsread() -- isFinal denotes whether this is the final frame.
+ -- If it isn't, then more frames can be read
+r:wswrite("You wrote: " .. line)</pre>
-<pre class="prettyprint lang-lua">r:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter</pre>
+<pre class="prettyprint lang-lua">r:wswrite(line) -- Writes a frame to a WebSocket client:
+r:wswrite("Hello, world!")</pre>
-<pre class="prettyprint lang-lua">r.module_info(module_name) -- Queries the server for information about a module
+<pre class="prettyprint lang-lua">r:wsclose() -- Closes a WebSocket request and terminates it for httpd:
-local mod = r.module_info("mod_lua.c")
-if mod then
- for k, v in pairs(mod.commands) do
- r:puts( ("%s: %s\n"):format(k,v)) -- print out all directives accepted by this module
- end
+if r:wsupgrade() then
+ r:wswrite("Write something: ")
+ local line = r:wsread() or "nothing"
+ r:wswrite("You wrote: " .. line);
+ r:wswrite("Goodbye!")
+ r:wsclose()
end</pre>
-<pre class="prettyprint lang-lua">r:loaded_modules() -- Returns a list of modules loaded by httpd:
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="logging" id="logging">Logging Functions</a></h2>
-for k, module in pairs(r:loaded_modules()) do
- r:puts("I have loaded module " .. module .. "\n")
+<pre class="prettyprint lang-lua"> -- examples of logging messages<br />
+ r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
+ r:debug("This is a debug log message")<br />
+ r:info("This is an info log message")<br />
+ r:notice("This is a notice log message")<br />
+ r:warn("This is a warn log message")<br />
+ r:err("This is an err log message")<br />
+ r:alert("This is an alert log message")<br />
+ r:crit("This is a crit log message")<br />
+ r:emerg("This is an emerg log message")<br />
+</pre>
+
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="apache2" id="apache2">apache2 Package</a></h2>
+<p>A package named <code>apache2</code> is available with (at least) the following contents.</p>
+<dl>
+ <dt>apache2.OK</dt>
+ <dd>internal constant OK. Handlers should return this if they've
+ handled the request.</dd>
+ <dt>apache2.DECLINED</dt>
+ <dd>internal constant DECLINED. Handlers should return this if
+ they are not going to handle the request.</dd>
+ <dt>apache2.DONE</dt>
+ <dd>internal constant DONE.</dd>
+ <dt>apache2.version</dt>
+ <dd>Apache HTTP server version string</dd>
+ <dt>apache2.HTTP_MOVED_TEMPORARILY</dt>
+ <dd>HTTP status code</dd>
+ <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
+ <dd>internal constants used by <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></dd>
+ <dt>apache2.AUTHZ_DENIED, apache2.AUTHZ_GRANTED, apache2.AUTHZ_NEUTRAL, apache2.AUTHZ_GENERAL_ERROR, apache2.AUTHZ_DENIED_NO_USER</dt>
+ <dd>internal constants used by <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code></dd>
+
+</dl>
+<p>(Other HTTP status codes are not yet implemented.)</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="modifying_buckets" id="modifying_buckets">Modifying contents with Lua filters</a></h2>
+
+ <p>
+ Filter functions implemented via <code class="directive"><a href="#luainputfilter">LuaInputFilter</a></code>
+ or <code class="directive"><a href="#luaoutputfilter">LuaOutputFilter</a></code> are designed as
+ three-stage non-blocking functions using coroutines to suspend and resume a
+ function as buckets are sent down the filter chain. The core structure of
+ such a function is:
+ </p>
+ <pre class="prettyprint lang-lua">function filter(r)
+ -- Our first yield is to signal that we are ready to receive buckets.
+ -- Before this yield, we can set up our environment, check for conditions,
+ -- and, if we deem it necessary, decline filtering a request alltogether:
+ if something_bad then
+ return -- This would skip this filter.
+ end
+ -- Regardless of whether we have data to prepend, a yield MUST be called here.
+ -- Note that only output filters can prepend data. Input filters must use the
+ -- final stage to append data to the content.
+ coroutine.yield([optional header to be prepended to the content])
+
+ -- After we have yielded, buckets will be sent to us, one by one, and we can
+ -- do whatever we want with them and then pass on the result.
+ -- Buckets are stored in the global variable 'bucket', so we create a loop
+ -- that checks if 'bucket' is not nil:
+ while bucket ~= nil do
+ local output = mangle(bucket) -- Do some stuff to the content
+ coroutine.yield(output) -- Return our new content to the filter chain
+ end
+
+ -- Once the buckets are gone, 'bucket' is set to nil, which will exit the
+ -- loop and land us here. Anything extra we want to append to the content
+ -- can be done by doing a final yield here. Both input and output filters
+ -- can append data to the content in this phase.
+ coroutine.yield([optional footer to be appended to the content])
end</pre>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="databases" id="databases">Database connectivity</a></h2>
+
+ <p>
+ Mod_lua implements a simple database feature for querying and running commands
+ on the most popular database engines (mySQL, PostgreSQL, FreeTDS, ODBC, SQLite, Oracle)
+ as well as mod_dbd.
+ </p>
+ <p>The example below shows how to acquire a database handle and return information from a table:</p>
+ <pre class="prettyprint lang-lua">function handle(r)
+ -- Acquire a database handle
+ local database, err = r:dbacquire("mysql", "server=localhost,user=someuser,pass=somepass,dbname=mydb")
+ if not err then
+ -- Select some information from it
+ local results, err = database:select(r, "SELECT `name`, `age` FROM `people` WHERE 1")
+ if not err then
+ local rows = results(0) -- fetch all rows synchronously
+ for k, row in pairs(rows) do
+ r:puts( string.format("Name: %s, Age: %s<br/>", row[1], row[2]) )
+ end
+ else
+ r:puts("Database query error: " .. err)
+ end
+ database:close()
+ else
+ r:puts("Could not connect to the database: " .. err)
+ end
+end</pre>
-<pre class="prettyprint lang-lua">r:runtime_dir_relative(filename) -- Compute the name of a run-time file (e.g., shared memory "file")
- -- relative to the appropriate run-time directory.</pre>
-
-
-<pre class="prettyprint lang-lua">r:server_info() -- Returns a table containing server information, such as
- -- the name of the httpd executable file, mpm used etc.</pre>
+ <p>
+ To utilize <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>, specify <code>mod_dbd</code>
+ as the database type, or leave the field blank:
+ </p>
+ <pre class="prettyprint lang-lua">local database = r:dbacquire("mod_dbd")</pre>
+ <h3><a name="database_object" id="database_object">Database object and contained functions</a></h3>
+
+ <p>The database object returned by <code>dbacquire</code> has the following methods:</p>
+ <p><strong>Normal select and query from a database:</strong></p>
+ <pre class="prettyprint lang-lua">-- Run a statement and return the number of rows affected:
+local affected, errmsg = database:query(r, "DELETE FROM `tbl` WHERE 1")
-<pre class="prettyprint lang-lua">r:set_document_root(file_path) -- Sets the document root for the request to file_path</pre>
+-- Run a statement and return a result set that can be used synchronously or async:
+local result, errmsg = database:select(r, "SELECT * FROM `people` WHERE 1")</pre>
+ <p><strong>Using prepared statements (recommended):</strong></p>
+ <pre class="prettyprint lang-lua">-- Create and run a prepared statement:
+local statement, errmsg = database:prepare(r, "DELETE FROM `tbl` WHERE `age` > %u")
+if not errmsg then
+ local result, errmsg = statement:query(20) -- run the statement with age > 20
+end
+-- Fetch a prepared statement from a DBDPrepareSQL directive:
+local statement, errmsg = database:prepared(r, "someTag")
+if not errmsg then
+ local result, errmsg = statement:select("John Doe", 123) -- inject the values "John Doe" and 123 into the statement
+end</pre>
+ <p><strong>Escaping values, closing databases etc:</strong></p>
+ <pre class="prettyprint lang-lua">-- Escape a value for use in a statement:
+local escaped = database:escape(r, [["'|blabla]])
-<pre class="prettyprint lang-lua">r:set_context_info(prefix, docroot) -- Sets the context prefix and context document root for a request</pre>
+-- Close a database connection and free up handles:
+database:close()
+-- Check whether a database connection is up and running:
+local connected = database:active()</pre>
-<pre class="prettyprint lang-lua">r:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependent way</pre>
+
+ <h3><a name="result_sets" id="result_sets">Working with result sets</a></h3>
+
+ <p>The result set returned by <code>db:select</code> or by the prepared statement functions
+ created through <code>db:prepare</code> can be used to
+ fetch rows synchronously or asynchronously, depending on the row number specified:<br />
+ <code>result(0)</code> fetches all rows in a synchronous manner, returning a table of rows.<br />
+ <code>result(-1)</code> fetches the next available row in the set, asynchronously.<br />
+ <code>result(N)</code> fetches row number <code>N</code>, asynchronously:
+ </p>
+ <pre class="prettyprint lang-lua">-- fetch a result set using a regular query:
+local result, err = db:select(r, "SELECT * FROM `tbl` WHERE 1")
+local rows = result(0) -- Fetch ALL rows synchronously
+local row = result(-1) -- Fetch the next available row, asynchronously
+local row = result(1234) -- Fetch row number 1234, asynchronously
+local row = result(-1, true) -- Fetch the next available row, using row names as key indexes.</pre>
-<pre class="prettyprint lang-lua">r:escape_logitem(string) -- Escapes a string for logging</pre>
+ <p>One can construct a function that returns an iterative function to iterate over all rows
+ in a synchronous or asynchronous way, depending on the async argument:
+ </p>
+ <pre class="prettyprint lang-lua">function rows(resultset, async)
+ local a = 0
+ local function getnext()
+ a = a + 1
+ local row = resultset(-1)
+ return row and a or nil, row
+ end
+ if not async then
+ return pairs(resultset(0))
+ else
+ return getnext, self
+ end
+end
+local statement, err = db:prepare(r, "SELECT * FROM `tbl` WHERE `age` > %u")
+if not err then
+ -- fetch rows asynchronously:
+ local result, err = statement:select(20)
+ if not err then
+ for index, row in rows(result, true) do
+ ....
+ end
+ end
-<pre class="prettyprint lang-lua">r.strcmp_match(string, pattern) -- Checks if 'string' matches 'pattern' using strcmp_match (globs).
- -- fx. whether 'www.example.com' matches '*.example.com':
-
-local match = r.strcmp_match("foobar.com", "foo*.com")
-if match then
- r:puts("foobar.com matches foo*.com")
+ -- fetch rows synchronously:
+ local result, err = statement:select(20)
+ if not err then
+ for index, row in rows(result, false) do
+ ....
+ end
+ end
end</pre>
+
+ <h3><a name="closing_databases" id="closing_databases">Closing a database connection</a></h3>
+
-<pre class="prettyprint lang-lua">r:set_keepalive() -- Sets the keepalive status for a request. Returns true if possible, false otherwise.</pre>
-
-
-<pre class="prettyprint lang-lua">r:make_etag() -- Constructs and returns the etag for the current request.</pre>
-
-
-<pre class="prettyprint lang-lua">r:send_interim_response(clear) -- Sends an interim (1xx) response to the client.
- -- if 'clear' is true, available headers will be sent and cleared.</pre>
+ <p>Database handles should be closed using <code>database:close()</code> when they are no longer
+ needed. If you do not close them manually, they will eventually be garbage collected and
+ closed by mod_lua, but you may end up having too many unused connections to the database
+ if you leave the closing up to mod_lua. Essentially, the following two measures are
+ the same:
+ </p>
+ <pre class="prettyprint lang-lua">-- Method 1: Manually close a handle
+local database = r:dbacquire("mod_dbd")
+database:close() -- All done
+-- Method 2: Letting the garbage collector close it
+local database = r:dbacquire("mod_dbd")
+database = nil -- throw away the reference
+collectgarbage() -- close the handle via GC</pre>
-<pre class="prettyprint lang-lua">r:custom_response(status_code, string) -- Construct and set a custom response for a given status code.
- -- This works much like the ErrorDocument directive:
-
-r:custom_response(404, "Baleted!")</pre>
+
+ <h3><a name="database_caveat" id="database_caveat">Precautions when working with databases</a></h3>
+
+ <p>Although the standard <code>query</code> and <code>run</code> functions are freely
+ available, it is recommended that you use prepared statements whenever possible, to
+ both optimize performance (if your db handle lives on for a long time) and to minimize
+ the risk of SQL injection attacks. <code>run</code> and <code>query</code> should only
+ be used when there are no variables inserted into a statement (a static statement).
+ When using dynamic statements, use <code>db:prepare</code> or <code>db:prepared</code>.
+ </p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaAuthzProvider" id="LuaAuthzProvider">LuaAuthzProvider</a> <a name="luaauthzprovider" id="luaauthzprovider">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Plug an authorization provider function into <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code>
+</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.3 and later</td></tr>
+</table>
+<p>After a lua function has been registered as authorization provider, it can be used
+with the <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive:</p>
-<pre class="prettyprint lang-lua">r.exists_config_define(string) -- Checks whether a configuration definition exists or not:
+<pre class="prettyprint lang-config">LuaRoot "/usr/local/apache2/lua"
+LuaAuthzProvider foo authz.lua authz_check_foo
+<Location "/">
+ Require foo johndoe
+</Location></pre>
-if r.exists_config_define("FOO") then
- r:puts("httpd was probably run with -DFOO, or it was defined in the configuration")
+<pre class="prettyprint lang-lua">require "apache2"
+function authz_check_foo(r, who)
+ if r.user ~= who then return apache2.AUTHZ_DENIED
+ return apache2.AUTHZ_GRANTED
end</pre>
-<pre class="prettyprint lang-lua">r:state_query(string) -- Queries the server for state information</pre>
-
-
-<pre class="prettyprint lang-lua">r:stat(filename [,wanted]) -- Runs stat() on a file, and returns a table with file information:
-
-local info = r:stat("/var/www/foo.txt")
-if info then
- r:puts("This file exists and was last modified at: " .. info.modified)
-end</pre>
-
-<pre class="prettyprint lang-lua">r:regex(string, pattern [,flags]) -- Runs a regular expression match on a string, returning captures if matched:
-local matches = r:regex("foo bar baz", [[foo (\w+) (\S*)]])
-if matches then
- r:puts("The regex matched, and the last word captured ($2) was: " .. matches[2])
-end
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaCodeCache" id="LuaCodeCache">LuaCodeCache</a> <a name="luacodecache" id="luacodecache">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the compiled code cache.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaCodeCache stat|forever|never</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaCodeCache stat</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table><p>
+ Specify the behavior of the in-memory code cache. The default
+ is stat, which stats the top level script (not any included
+ ones) each time that file is needed, and reloads it if the
+ modified time indicates it is newer than the one it has
+ already loaded. The other values cause it to keep the file
+ cached forever (don't stat and replace) or to never cache the
+ file.</p>
--- Example ignoring case sensitivity:
-local matches = r:regex("FOO bar BAz", [[(foo) bar]], 1)
+ <p>In general stat or forever is good for production, and stat or never
+ for development.</p>
--- Flags can be a bitwise combination of:
--- 0x01: Ignore case
--- 0x02: Multiline search</pre>
+ <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">LuaCodeCache stat
+LuaCodeCache forever
+LuaCodeCache never</pre>
+</div>
-<pre class="prettyprint lang-lua">r.usleep(number_of_microseconds) -- Puts the script to sleep for a given number of microseconds.</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookAccessChecker" id="LuaHookAccessChecker">LuaHookAccessChecker</a> <a name="luahookaccesschecker" id="luahookaccesschecker">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the access_checker phase of request processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is supported in 2.3.15 and later</td></tr>
+</table>
+<p>Add your hook to the access_checker phase. An access checker
+hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.</p>
+ <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
+ control when this script runs relative to other modules.</p></div>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookAuthChecker" id="LuaHookAuthChecker">LuaHookAuthChecker</a> <a name="luahookauthchecker" id="luahookauthchecker">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the auth_checker phase of request processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is supported in 2.3.15 and later</td></tr>
+</table>
+<p>Invoke a lua function in the auth_checker phase of processing
+a request. This can be used to implement arbitrary authentication
+and authorization checking. A very simple example:
+</p>
+<pre class="prettyprint lang-lua">require 'apache2'
-<pre class="prettyprint lang-lua">r:dbacquire(dbType[, dbParams]) -- Acquires a connection to a database and returns a database class.
- -- See '<a href="#databases">Database connectivity</a>' for details.</pre>
+-- fake authcheck hook
+-- If request has no auth info, set the response header and
+-- return a 401 to ask the browser for basic auth info.
+-- If request has auth info, don't actually look at it, just
+-- pretend we got userid 'foo' and validated it.
+-- Then check if the userid is 'foo' and accept the request.
+function authcheck_hook(r)
+ -- look for auth info
+ auth = r.headers_in['Authorization']
+ if auth ~= nil then
+ -- fake the user
+ r.user = 'foo'
+ end
-<pre class="prettyprint lang-lua">r:ivm_set("key", value) -- Set an Inter-VM variable to hold a specific value.
- -- These values persist even though the VM is gone or not being used,
- -- and so should only be used if MaxConnectionsPerChild is > 0
- -- Values can be numbers, strings and booleans, and are stored on a
- -- per process basis (so they won't do much good with a prefork mpm)
-
-r:ivm_get("key") -- Fetches a variable set by ivm_set. Returns the contents of the variable
- -- if it exists or nil if no such variable exists.
-
--- An example getter/setter that saves a global variable outside the VM:
-function handle(r)
- -- First VM to call this will get no value, and will have to create it
- local foo = r:ivm_get("cached_data")
- if not foo then
- foo = do_some_calcs() -- fake some return value
- r:ivm_set("cached_data", foo) -- set it globally
- end
- r:puts("Cached data is: ", foo)
+ if r.user == nil then
+ r:debug("authcheck: user is nil, returning 401")
+ r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
+ return 401
+ elseif r.user == "foo" then
+ r:debug('user foo: OK')
+ else
+ r:debug("authcheck: user='" .. r.user .. "'")
+ r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
+ return 401
+ end
+ return apache2.OK
end</pre>
+ <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
+ control when this script runs relative to other modules.</p></div>
-<pre class="prettyprint lang-lua">r:htpassword(string [,algorithm [,cost]]) -- Creates a password hash from a string.
- -- algorithm: 0 = APMD5 (default), 1 = SHA, 2 = BCRYPT, 3 = CRYPT.
- -- cost: only valid with BCRYPT algorithm (default = 5).</pre>
-
-
-<pre class="prettyprint lang-lua">r:mkdir(dir [,mode]) -- Creates a directory and sets mode to optional mode paramter.</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookCheckUserID" id="LuaHookCheckUserID">LuaHookCheckUserID</a> <a name="luahookcheckuserid" id="luahookcheckuserid">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the check_user_id phase of request processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is supported in 2.3.15 and later</td></tr>
+</table><p>...</p>
+ <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
+ control when this script runs relative to other modules.</p></div>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookFixups" id="LuaHookFixups">LuaHookFixups</a> <a name="luahookfixups" id="luahookfixups">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the fixups phase of a request
+processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookFixups /path/to/lua/script.lua hook_function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+<p>
+ Just like LuaHookTranslateName, but executed at the fixups phase
+</p>
-<pre class="prettyprint lang-lua">r:mkrdir(dir [,mode]) -- Creates directories recursive and sets mode to optional mode paramter.</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookInsertFilter" id="LuaHookInsertFilter">LuaHookInsertFilter</a> <a name="luahookinsertfilter" id="luahookinsertfilter">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the insert_filter phase of request processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table><p>Not Yet Implemented</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookLog" id="LuaHookLog">LuaHookLog</a> <a name="luahooklog" id="luahooklog">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the access log phase of a request
+processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookLog /path/to/lua/script.lua log_function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+<p>
+ This simple logging hook allows you to run a function when httpd enters the
+ logging phase of a request. With it, you can append data to your own logs,
+ manipulate data before the regular log is written, or prevent a log entry
+ from being created. To prevent the usual logging from happening, simply return
+ <code>apache2.DONE</code> in your logging handler, otherwise return
+ <code>apache2.OK</code> to tell httpd to log as normal.
+</p>
+<p>Example:</p>
+<pre class="prettyprint lang-config">LuaHookLog "/path/to/script.lua" logger</pre>
+<pre class="prettyprint lang-lua">-- /path/to/script.lua --
+function logger(r)
+ -- flip a coin:
+ -- If 1, then we write to our own Lua log and tell httpd not to log
+ -- in the main log.
+ -- If 2, then we just sanitize the output a bit and tell httpd to
+ -- log the sanitized bits.
-<pre class="prettyprint lang-lua">r:rmdir(dir) -- Removes a directory.</pre>
+ if math.random(1,2) == 1 then
+ -- Log stuff ourselves and don't log in the regular log
+ local f = io.open("/foo/secret.log", "a")
+ if f then
+ f:write("Something secret happened at " .. r.uri .. "\n")
+ f:close()
+ end
+ return apache2.DONE -- Tell httpd not to use the regular logging functions
+ else
+ r.uri = r.uri:gsub("somesecretstuff", "") -- sanitize the URI
+ return apache2.OK -- tell httpd to log it.
+ end
+end</pre>
-<pre class="prettyprint lang-lua">r:touch(file [,mtime]) -- Sets the file modification time to current time or to optional mtime msec value.</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookMapToStorage" id="LuaHookMapToStorage">LuaHookMapToStorage</a> <a name="luahookmaptostorage" id="luahookmaptostorage">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the map_to_storage phase of request processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+ <p>Like <code class="directive">LuaHookTranslateName</code> but executed at the
+ map-to-storage phase of a request. Modules like mod_cache run at this phase,
+ which makes for an interesting example on what to do here:</p>
+ <pre class="prettyprint lang-config">LuaHookMapToStorage "/path/to/lua/script.lua" check_cache</pre>
+ <pre class="prettyprint lang-lua">require"apache2"
+cached_files = {}
-<pre class="prettyprint lang-lua">r:get_direntries(dir) -- Returns a table with all directory entries.
+function read_file(filename)
+ local input = io.open(filename, "r")
+ if input then
+ local data = input:read("*a")
+ cached_files[filename] = data
+ file = cached_files[filename]
+ input:close()
+ end
+ return cached_files[filename]
+end
-function handle(r)
- local dir = r.context_document_root
- for _, f in ipairs(r:get_direntries(dir)) do
- local info = r:stat(dir .. "/" .. f)
- if info then
- local mtime = os.date(fmt, info.mtime / 1000000)
- local ftype = (info.filetype == 2) and "[dir] " or "[file]"
- r:puts( ("%s %s %10i %s\n"):format(ftype, mtime, info.size, f) )
+function check_cache(r)
+ if r.filename:match("%.png$") then -- Only match PNG files
+ local file = cached_files[r.filename] -- Check cache entries
+ if not file then
+ file = read_file(r.filename) -- Read file into cache
+ end
+ if file then -- If file exists, write it out
+ r.status = 200
+ r:write(file)
+ r:info(("Sent %s to client from cache"):format(r.filename))
+ return apache2.DONE -- skip default handler for PNG files
+ end
end
- end
+ return apache2.DECLINED -- If we had nothing to do, let others serve this.
end</pre>
-<pre class="prettyprint lang-lua">r.date_parse_rfc(string) -- Parses a date/time string and returns seconds since epoche.</pre>
-
-
-<pre class="prettyprint lang-lua">r:getcookie(key) -- Gets a HTTP cookie</pre>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookTranslateName" id="LuaHookTranslateName">LuaHookTranslateName</a> <a name="luahooktranslatename" id="luahooktranslatename">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the translate name phase of request processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is supported in 2.3.15 and later</td></tr>
+</table><p>
+ Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
+ request processing. The hook function receives a single
+ argument, the request_rec, and should return a status code,
+ which is either an HTTP error code, or the constants defined
+ in the apache2 module: apache2.OK, apache2.DECLINED, or
+ apache2.DONE. </p>
+ <p>For those new to hooks, basically each hook will be invoked
+ until one of them returns apache2.OK. If your hook doesn't
+ want to do the translation it should just return
+ apache2.DECLINED. If the request should stop processing, then
+ return apache2.DONE.</p>
-<pre class="prettyprint lang-lua">r:setcookie{
- key = [key],
- value = [value],
- expires = [expiry],
- secure = [boolean],
- httponly = [boolean],
- path = [path],
- domain = [domain]
-} -- Sets a HTTP cookie, for instance:
+ <p>Example:</p>
-r:setcookie{
- key = "cookie1",
- value = "HDHfa9eyffh396rt",
- expires = os.time() + 86400,
- secure = true
-}</pre>
+<pre class="prettyprint lang-config"># httpd.conf
+LuaHookTranslateName "/scripts/conf/hooks.lua" silly_mapper</pre>
-<pre class="prettyprint lang-lua">r:wsupgrade() -- Upgrades a connection to WebSockets if possible (and requested):
-if r:wsupgrade() then -- if we can upgrade:
- r:wswrite("Welcome to websockets!") -- write something to the client
- r:wsclose() -- goodbye!
+<pre class="prettyprint lang-lua">-- /scripts/conf/hooks.lua --
+require "apache2"
+function silly_mapper(r)
+ if r.uri == "/" then
+ r.filename = "/var/www/home.lua"
+ return apache2.OK
+ else
+ return apache2.DECLINED
+ end
end</pre>
-<pre class="prettyprint lang-lua">r:wsread() -- Reads a WebSocket frame from a WebSocket upgraded connection (see above):
+ <div class="note"><h3>Context</h3><p>This directive is not valid in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>, <code class="directive"><a href="../mod/core.html#files"><Files></a></code>, or htaccess
+ context.</p></div>
-local line, isFinal = r:wsread() -- isFinal denotes whether this is the final frame.
- -- If it isn't, then more frames can be read
-r:wswrite("You wrote: " .. line)</pre>
+ <div class="note"><h3>Ordering</h3><p>The optional arguments "early" or "late"
+ control when this script runs relative to other modules.</p></div>
-<pre class="prettyprint lang-lua">r:wswrite(line) -- Writes a frame to a WebSocket client:
-r:wswrite("Hello, world!")</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaHookTypeChecker" id="LuaHookTypeChecker">LuaHookTypeChecker</a> <a name="luahooktypechecker" id="luahooktypechecker">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the type_checker phase of request processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table><p>
+ This directive provides a hook for the type_checker phase of the request processing.
+ This phase is where requests are assigned a content type and a handler, and thus can
+ be used to modify the type and handler based on input:
+ </p>
+ <pre class="prettyprint lang-config">LuaHookTypeChecker "/path/to/lua/script.lua" type_checker</pre>
+ <pre class="prettyprint lang-lua"> function type_checker(r)
+ if r.uri:match("%.to_gif$") then -- match foo.png.to_gif
+ r.content_type = "image/gif" -- assign it the image/gif type
+ r.handler = "gifWizard" -- tell the gifWizard module to handle this
+ r.filename = r.uri:gsub("%.to_gif$", "") -- fix the filename requested
+ return apache2.OK
+ end
-<pre class="prettyprint lang-lua">r:wsclose() -- Closes a WebSocket request and terminates it for httpd:
+ return apache2.DECLINED
+ end</pre>
-if r:wsupgrade() then
- r:wswrite("Write something: ")
- local line = r:wsread() or "nothing"
- r:wswrite("You wrote: " .. line);
- r:wswrite("Goodbye!")
- r:wsclose()
-end</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaInherit" id="LuaInherit">LuaInherit</a> <a name="luainherit" id="luainherit">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls how parent configuration sections are merged into children</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaInherit none|parent-first|parent-last</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaInherit parent-first</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.0 and later</td></tr>
+</table><p>By default, if LuaHook* directives are used in overlapping
+ Directory or Location configuration sections, the scripts defined in the
+ more specific section are run <em>after</em> those defined in the more
+ generic section (LuaInherit parent-first). You can reverse this order, or
+ make the parent context not apply at all.</p>
+
+ <p> In previous 2.3.x releases, the default was effectively to ignore LuaHook*
+ directives from parent configuration sections.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaInputFilter" id="LuaInputFilter">LuaInputFilter</a> <a name="luainputfilter" id="luainputfilter">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a Lua function for content input filtering</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaInputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.5 and later</td></tr>
+</table>
+<p>Provides a means of adding a Lua function as an input filter.
+As with output filters, input filters work as coroutines,
+first yielding before buffers are sent, then yielding whenever
+a bucket needs to be passed down the chain, and finally (optionally)
+yielding anything that needs to be appended to the input data. The
+global variable <code>bucket</code> holds the buckets as they are passed
+onto the Lua script:
+</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="logging" id="logging">Logging Functions</a></h2>
+<pre class="prettyprint lang-config">LuaInputFilter myInputFilter "/www/filter.lua" input_filter
+<Files "*.lua">
+ SetInputFilter myInputFilter
+</Files></pre>
-<pre class="prettyprint lang-lua"> -- examples of logging messages<br />
- r:trace1("This is a trace log message") -- trace1 through trace8 can be used <br />
- r:debug("This is a debug log message")<br />
- r:info("This is an info log message")<br />
- r:notice("This is a notice log message")<br />
- r:warn("This is a warn log message")<br />
- r:err("This is an err log message")<br />
- r:alert("This is an alert log message")<br />
- r:crit("This is a crit log message")<br />
- r:emerg("This is an emerg log message")<br />
-</pre>
+<pre class="prettyprint lang-lua">--[[
+ Example input filter that converts all POST data to uppercase.
+]]--
+function input_filter(r)
+ print("luaInputFilter called") -- debug print
+ coroutine.yield() -- Yield and wait for buckets
+ while bucket do -- For each bucket, do...
+ local output = string.upper(bucket) -- Convert all POST data to uppercase
+ coroutine.yield(output) -- Send converted data down the chain
+ end
+ -- No more buckets available.
+ coroutine.yield("&filterSignature=1234") -- Append signature at the end
+end</pre>
+<p>
+The input filter supports denying/skipping a filter if it is deemed unwanted:
+</p>
+<pre class="prettyprint lang-lua">function input_filter(r)
+ if not good then
+ return -- Simply deny filtering, passing on the original content instead
+ end
+ coroutine.yield() -- wait for buckets
+ ... -- insert filter stuff here
+end</pre>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="apache2" id="apache2">apache2 Package</a></h2>
-<p>A package named <code>apache2</code> is available with (at least) the following contents.</p>
-<dl>
- <dt>apache2.OK</dt>
- <dd>internal constant OK. Handlers should return this if they've
- handled the request.</dd>
- <dt>apache2.DECLINED</dt>
- <dd>internal constant DECLINED. Handlers should return this if
- they are not going to handle the request.</dd>
- <dt>apache2.DONE</dt>
- <dd>internal constant DONE.</dd>
- <dt>apache2.version</dt>
- <dd>Apache HTTP server version string</dd>
- <dt>apache2.HTTP_MOVED_TEMPORARILY</dt>
- <dd>HTTP status code</dd>
- <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
- <dd>internal constants used by <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></dd>
- <dt>apache2.AUTHZ_DENIED, apache2.AUTHZ_GRANTED, apache2.AUTHZ_NEUTRAL, apache2.AUTHZ_GENERAL_ERROR, apache2.AUTHZ_DENIED_NO_USER</dt>
- <dd>internal constants used by <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code></dd>
+<p>
+See "<a href="#modifying_buckets">Modifying contents with Lua
+filters</a>" for more information.
+</p>
-</dl>
-<p>(Other HTTP status codes are not yet implemented.)</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="modifying_buckets" id="modifying_buckets">Modifying contents with Lua filters</a></h2>
-
- <p>
- Filter functions implemented via <code class="directive"><a href="#luainputfilter">LuaInputFilter</a></code>
- or <code class="directive"><a href="#luaoutputfilter">LuaOutputFilter</a></code> are designed as
- three-stage non-blocking functions using coroutines to suspend and resume a
- function as buckets are sent down the filter chain. The core structure of
- such a function is:
- </p>
- <pre class="prettyprint lang-lua">function filter(r)
- -- Our first yield is to signal that we are ready to receive buckets.
- -- Before this yield, we can set up our environment, check for conditions,
- -- and, if we deem it necessary, decline filtering a request alltogether:
- if something_bad then
- return -- This would skip this filter.
- end
- -- Regardless of whether we have data to prepend, a yield MUST be called here.
- -- Note that only output filters can prepend data. Input filters must use the
- -- final stage to append data to the content.
- coroutine.yield([optional header to be prepended to the content])
-
- -- After we have yielded, buckets will be sent to us, one by one, and we can
- -- do whatever we want with them and then pass on the result.
- -- Buckets are stored in the global variable 'bucket', so we create a loop
- -- that checks if 'bucket' is not nil:
- while bucket ~= nil do
- local output = mangle(bucket) -- Do some stuff to the content
- coroutine.yield(output) -- Return our new content to the filter chain
- end
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaMapHandler" id="LuaMapHandler">LuaMapHandler</a> <a name="luamaphandler" id="luamaphandler">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Map a path to a lua handler</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+ <p>This directive matches a uri pattern to invoke a specific
+ handler function in a specific file. It uses PCRE regular
+ expressions to match the uri, and supports interpolating
+ match groups into both the file path and the function name.
+ Be careful writing your regular expressions to avoid security
+ issues.</p>
+ <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">LuaMapHandler "/(\w+)/(\w+)" "/scripts/$1.lua" "handle_$2"</pre>
+</div>
+ <p>This would match uri's such as /photos/show?id=9
+ to the file /scripts/photos.lua and invoke the
+ handler function handle_show on the lua vm after
+ loading that file.</p>
- -- Once the buckets are gone, 'bucket' is set to nil, which will exit the
- -- loop and land us here. Anything extra we want to append to the content
- -- can be done by doing a final yield here. Both input and output filters
- -- can append data to the content in this phase.
- coroutine.yield([optional footer to be appended to the content])
-end</pre>
+<pre class="prettyprint lang-config">LuaMapHandler "/bingo" "/scripts/wombat.lua"</pre>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="databases" id="databases">Database connectivity</a></h2>
-
- <p>
- Mod_lua implements a simple database feature for querying and running commands
- on the most popular database engines (mySQL, PostgreSQL, FreeTDS, ODBC, SQLite, Oracle)
- as well as mod_dbd.
- </p>
- <p>The example below shows how to acquire a database handle and return information from a table:</p>
- <pre class="prettyprint lang-lua">function handle(r)
- -- Acquire a database handle
- local database, err = r:dbacquire("mysql", "server=localhost,user=someuser,pass=somepass,dbname=mydb")
- if not err then
- -- Select some information from it
- local results, err = database:select(r, "SELECT `name`, `age` FROM `people` WHERE 1")
- if not err then
- local rows = results(0) -- fetch all rows synchronously
- for k, row in pairs(rows) do
- r:puts( string.format("Name: %s, Age: %s<br/>", row[1], row[2]) )
- end
- else
- r:puts("Database query error: " .. err)
- end
- database:close()
- else
- r:puts("Could not connect to the database: " .. err)
+ <p>This would invoke the "handle" function, which
+ is the default if no specific function name is
+ provided.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaOutputFilter" id="LuaOutputFilter">LuaOutputFilter</a> <a name="luaoutputfilter" id="luaoutputfilter">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a Lua function for content output filtering</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaOutputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>2.4.5 and later</td></tr>
+</table>
+<p>Provides a means of adding a Lua function as an output filter.
+As with input filters, output filters work as coroutines,
+first yielding before buffers are sent, then yielding whenever
+a bucket needs to be passed down the chain, and finally (optionally)
+yielding anything that needs to be appended to the input data. The
+global variable <code>bucket</code> holds the buckets as they are passed
+onto the Lua script:
+</p>
+
+<pre class="prettyprint lang-config">LuaOutputFilter myOutputFilter "/www/filter.lua" output_filter
+<Files "*.lua">
+ SetOutputFilter myOutputFilter
+</Files></pre>
+
+<pre class="prettyprint lang-lua">--[[
+ Example output filter that escapes all HTML entities in the output
+]]--
+function output_filter(r)
+ coroutine.yield("(Handled by myOutputFilter)<br/>\n") -- Prepend some data to the output,
+ -- yield and wait for buckets.
+ while bucket do -- For each bucket, do...
+ local output = r:escape_html(bucket) -- Escape all output
+ coroutine.yield(output) -- Send converted data down the chain
end
+ -- No more buckets available.
end</pre>
- <p>
- To utilize <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>, specify <code>mod_dbd</code>
- as the database type, or leave the field blank:
- </p>
- <pre class="prettyprint lang-lua">local database = r:dbacquire("mod_dbd")</pre>
+<p>
+As with the input filter, the output filter supports denying/skipping a filter
+if it is deemed unwanted:
+</p>
+<pre class="prettyprint lang-lua">function output_filter(r)
+ if not r.content_type:match("text/html") then
+ return -- Simply deny filtering, passing on the original content instead
+ end
+ coroutine.yield() -- wait for buckets
+ ... -- insert filter stuff here
+end</pre>
- <h3><a name="database_object" id="database_object">Database object and contained functions</a></h3>
-
- <p>The database object returned by <code>dbacquire</code> has the following methods:</p>
- <p><strong>Normal select and query from a database:</strong></p>
- <pre class="prettyprint lang-lua">-- Run a statement and return the number of rows affected:
-local affected, errmsg = database:query(r, "DELETE FROM `tbl` WHERE 1")
+<div class="note"><h3>Lua filters with <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code></h3>
+<p> When a Lua filter is used as the underlying provider via the
+<code class="directive"><a href="../mod/mod_filter.html#filterprovider">FilterProvider</a></code> directive, filtering
+will only work when the <var>filter-name</var> is identical to the <var>provider-name</var>.
+</p> </div>
--- Run a statement and return a result set that can be used synchronously or async:
-local result, errmsg = database:select(r, "SELECT * FROM `people` WHERE 1")</pre>
+<p>
+See "<a href="#modifying_buckets">Modifying contents with Lua filters</a>" for more
+information.
+</p>
- <p><strong>Using prepared statements (recommended):</strong></p>
- <pre class="prettyprint lang-lua">-- Create and run a prepared statement:
-local statement, errmsg = database:prepare(r, "DELETE FROM `tbl` WHERE `age` > %u")
-if not errmsg then
- local result, errmsg = statement:query(20) -- run the statement with age > 20
-end
--- Fetch a prepared statement from a DBDPrepareSQL directive:
-local statement, errmsg = database:prepared(r, "someTag")
-if not errmsg then
- local result, errmsg = statement:select("John Doe", 123) -- inject the values "John Doe" and 123 into the statement
-end</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaPackageCPath" id="LuaPackageCPath">LuaPackageCPath</a> <a name="luapackagecpath" id="luapackagecpath">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.cpath</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackageCPath /path/to/include/?.soa</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+ <p>Add a path to lua's shared library search path. Follows the same
+ conventions as lua. This just munges the package.cpath in the
+ lua vms.</p>
- <p><strong>Escaping values, closing databases etc:</strong></p>
- <pre class="prettyprint lang-lua">-- Escape a value for use in a statement:
-local escaped = database:escape(r, [["'|blabla]])
--- Close a database connection and free up handles:
-database:close()
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaPackagePath" id="LuaPackagePath">LuaPackagePath</a> <a name="luapackagepath" id="luapackagepath">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a directory to lua's package.path</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaPackagePath /path/to/include/?.lua</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table><p>Add a path to lua's module search path. Follows the same
+ conventions as lua. This just munges the package.path in the
+ lua vms.</p>
--- Check whether a database connection is up and running:
-local connected = database:active()</pre>
+ <div class="example"><h3>Examples:</h3><pre class="prettyprint lang-config">LuaPackagePath "/scripts/lib/?.lua"
+LuaPackagePath "/scripts/lib/?/init.lua"</pre>
+</div>
-
- <h3><a name="result_sets" id="result_sets">Working with result sets</a></h3>
-
- <p>The result set returned by <code>db:select</code> or by the prepared statement functions
- created through <code>db:prepare</code> can be used to
- fetch rows synchronously or asynchronously, depending on the row number specified:<br />
- <code>result(0)</code> fetches all rows in a synchronous manner, returning a table of rows.<br />
- <code>result(-1)</code> fetches the next available row in the set, asynchronously.<br />
- <code>result(N)</code> fetches row number <code>N</code>, asynchronously:
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaQuickHandler" id="LuaQuickHandler">LuaQuickHandler</a> <a name="luaquickhandler" id="luaquickhandler">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Provide a hook for the quick handler of request processing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaQuickHandler /path/to/script.lua hook_function_name</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+ <p>
+ This phase is run immediately after the request has been mapped to a virtal host,
+ and can be used to either do some request processing before the other phases kick
+ in, or to serve a request without the need to translate, map to storage et cetera.
+ As this phase is run before anything else, directives such as <code class="directive"><a href="../mod/core.html#location"><Location></a></code> or <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> are void in this phase, just as
+ URIs have not been properly parsed yet.
</p>
- <pre class="prettyprint lang-lua">-- fetch a result set using a regular query:
-local result, err = db:select(r, "SELECT * FROM `tbl` WHERE 1")
-
-local rows = result(0) -- Fetch ALL rows synchronously
-local row = result(-1) -- Fetch the next available row, asynchronously
-local row = result(1234) -- Fetch row number 1234, asynchronously
-local row = result(-1, true) -- Fetch the next available row, using row names as key indexes.</pre>
+ <div class="note"><h3>Context</h3><p>This directive is not valid in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>, <code class="directive"><a href="../mod/core.html#files"><Files></a></code>, or htaccess
+ context.</p></div>
- <p>One can construct a function that returns an iterative function to iterate over all rows
- in a synchronous or asynchronous way, depending on the async argument:
- </p>
- <pre class="prettyprint lang-lua">function rows(resultset, async)
- local a = 0
- local function getnext()
- a = a + 1
- local row = resultset(-1)
- return row and a or nil, row
- end
- if not async then
- return pairs(resultset(0))
- else
- return getnext, self
- end
-end
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaRoot" id="LuaRoot">LuaRoot</a> <a name="luaroot" id="luaroot">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify the base path for resolving relative paths for mod_lua directives</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaRoot /path/to/a/directory</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+ <p>Specify the base path which will be used to evaluate all
+ relative paths within mod_lua. If not specified they
+ will be resolved relative to the current working directory,
+ which may not always work well for a server.</p>
-local statement, err = db:prepare(r, "SELECT * FROM `tbl` WHERE `age` > %u")
-if not err then
- -- fetch rows asynchronously:
- local result, err = statement:select(20)
- if not err then
- for index, row in rows(result, true) do
- ....
- end
- end
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LuaScope" id="LuaScope">LuaScope</a> <a name="luascope" id="luascope">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>One of once, request, conn, thread -- default is once</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LuaScope once|request|conn|thread|server [min] [max]</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>LuaScope once</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
+</table>
+ <p>Specify the life cycle scope of the Lua interpreter which will
+ be used by handlers in this "Directory." The default is "once"</p>
- -- fetch rows synchronously:
- local result, err = statement:select(20)
- if not err then
- for index, row in rows(result, false) do
- ....
- end
- end
-end</pre>
+ <dl>
+ <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
-
- <h3><a name="closing_databases" id="closing_databases">Closing a database connection</a></h3>
-
+ <dt>request:</dt> <dd>use the interpreter to handle anything based on
+ the same file within this request, which is also
+ request scoped.</dd>
- <p>Database handles should be closed using <code>database:close()</code> when they are no longer
- needed. If you do not close them manually, they will eventually be garbage collected and
- closed by mod_lua, but you may end up having too many unused connections to the database
- if you leave the closing up to mod_lua. Essentially, the following two measures are
- the same:
- </p>
- <pre class="prettyprint lang-lua">-- Method 1: Manually close a handle
-local database = r:dbacquire("mod_dbd")
-database:close() -- All done
+ <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
--- Method 2: Letting the garbage collector close it
-local database = r:dbacquire("mod_dbd")
-database = nil -- throw away the reference
-collectgarbage() -- close the handle via GC</pre>
+ <dt>thread:</dt> <dd>Use the interpreter for the lifetime of the thread
+ handling the request (only available with threaded MPMs).</dd>
-
- <h3><a name="database_caveat" id="database_caveat">Precautions when working with databases</a></h3>
-
- <p>Although the standard <code>query</code> and <code>run</code> functions are freely
- available, it is recommended that you use prepared statements whenever possible, to
- both optimize performance (if your db handle lives on for a long time) and to minimize
- the risk of SQL injection attacks. <code>run</code> and <code>query</code> should only
- be used when there are no variables inserted into a statement (a static statement).
- When using dynamic statements, use <code>db:prepare</code> or <code>db:prepared</code>.
+ <dt>server:</dt> <dd>This one is different than others because the
+ server scope is quite long lived, and multiple threads
+ will have the same server_rec. To accommodate this,
+ server scoped Lua states are stored in an apr
+ resource list. The <code>min</code> and <code>max</code> arguments
+ specify the minimum and maximum number of Lua states to keep in the
+ pool.</dd>
+ </dl>
+ <p>
+ Generally speaking, the <code>thread</code> and <code>server</code> scopes
+ execute roughly 2-3 times faster than the rest, because they don't have to
+ spawn new Lua states on every request (especially with the event MPM, as
+ even keepalive requests will use a new thread for each request). If you are
+ satisfied that your scripts will not have problems reusing a state, then
+ the <code>thread</code> or <code>server</code> scopes should be used for
+ maximum performance. While the <code>thread</code> scope will provide the
+ fastest responses, the <code>server</code> scope will use less memory, as
+ states are pooled, allowing f.x. 1000 threads to share only 100 Lua states,
+ thus using only 10% of the memory required by the <code>thread</code> scope.
</p>
-
</div>
</div>
rest of the configuration file.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#tips">Tips</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#macro"><Macro></a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#undefmacro">UndefMacro</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#use">Use</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#tips">Tips</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="Macro" id="Macro"><Macro></a> <a name="macro" id="macro">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a configuration file macro</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>
-<Macro <var>name</var> [<var>par1</var> .. <var>parN</var>]>
-... </Macro></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
-</table>
- <p>The <code class="directive">Macro</code> directive controls the definition of
- a macro within the server runtime configuration files.
- The first argument is the name of the macro.
- Other arguments are parameters to the macro. It is good practice to prefix
- parameter names with any of '<code>$%@</code>', and not macro names
- with such characters.
- </p>
-
- <pre class="prettyprint lang-config"><Macro LocalAccessPolicy>
- Require ip 10.2.16.0/24
-</Macro>
-
-<Macro RestrictedAccessPolicy $ipnumbers>
- Require ip $ipnumbers
-</Macro></pre>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="UndefMacro" id="UndefMacro">UndefMacro</a> <a name="undefmacro" id="undefmacro">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Undefine a macro</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UndefMacro <var>name</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
-</table>
- <p>The <code class="directive">UndefMacro</code> directive undefines a macro
- which has been defined before hand.</p>
-
- <pre class="prettyprint lang-config">UndefMacro LocalAccessPolicy
-UndefMacro RestrictedAccessPolicy</pre>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="Use" id="Use">Use</a> <a name="use" id="use">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use a macro</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
-</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
-</table>
- <p>The <code class="directive">Use</code> directive controls the use of a macro.
- The specified macro is expanded. It must be given the same number of
- arguments as in the macro definition. The provided values are
- associated to their corresponding initial parameters and are substituted
- before processing.</p>
-
- <pre class="prettyprint lang-config">Use LocalAccessPolicy
-...
-Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"</pre>
-
-
- <p>is equivalent, with the macros defined above, to:</p>
-
- <pre class="prettyprint lang-config">Require ip 10.2.16.0/24
-...
-Require ip 192.54.172.0/24 192.54.148.0/24</pre>
-
-
-</div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="usage" id="usage">Usage</a></h2>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="Macro" id="Macro"><Macro></a> <a name="macro" id="macro">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a configuration file macro</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>
+<Macro <var>name</var> [<var>par1</var> .. <var>parN</var>]>
+... </Macro></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
+</table>
+ <p>The <code class="directive">Macro</code> directive controls the definition of
+ a macro within the server runtime configuration files.
+ The first argument is the name of the macro.
+ Other arguments are parameters to the macro. It is good practice to prefix
+ parameter names with any of '<code>$%@</code>', and not macro names
+ with such characters.
+ </p>
+
+ <pre class="prettyprint lang-config"><Macro LocalAccessPolicy>
+ Require ip 10.2.16.0/24
+</Macro>
+
+<Macro RestrictedAccessPolicy $ipnumbers>
+ Require ip $ipnumbers
+</Macro></pre>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="UndefMacro" id="UndefMacro">UndefMacro</a> <a name="undefmacro" id="undefmacro">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Undefine a macro</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UndefMacro <var>name</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
+</table>
+ <p>The <code class="directive">UndefMacro</code> directive undefines a macro
+ which has been defined before hand.</p>
+
+ <pre class="prettyprint lang-config">UndefMacro LocalAccessPolicy
+UndefMacro RestrictedAccessPolicy</pre>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="Use" id="Use">Use</a> <a name="use" id="use">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use a macro</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
+</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
+</table>
+ <p>The <code class="directive">Use</code> directive controls the use of a macro.
+ The specified macro is expanded. It must be given the same number of
+ arguments as in the macro definition. The provided values are
+ associated to their corresponding initial parameters and are substituted
+ before processing.</p>
+
+ <pre class="prettyprint lang-config">Use LocalAccessPolicy
+...
+Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"</pre>
+
+
+ <p>is equivalent, with the macros defined above, to:</p>
+
+ <pre class="prettyprint lang-config">Require ip 10.2.16.0/24
+...
+Require ip 192.54.172.0/24 192.54.148.0/24</pre>
+
+
</div>
</div>
<div class="bottomlang">
their last modified date) to ensure that all visitors are
receive the corrected content headers.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#multipleext">Files with Multiple Extensions</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#contentencoding">Content encoding</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#charset-lang">Character sets and languages</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#addcharset">AddCharset</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#addencoding">AddEncoding</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#removetype">RemoveType</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#typesconfig">TypesConfig</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#multipleext">Files with Multiple Extensions</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#contentencoding">Content encoding</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#charset-lang">Character sets and languages</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/mod_mime_magic.html#mimemagicfile">MimeMagicFile</a></code></li>
<li><code class="directive"><a href="../mod/core.html#adddefaultcharset">AddDefaultCharset</a></code></li>
<li><code class="directive"><a href="../mod/core.html#setoutputfilter">SetOutputFilter</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="multipleext" id="multipleext">Files with Multiple Extensions</a></h2>
+ <p>Files can have more than one extension; the order of the
+ extensions is <em>normally</em> irrelevant. For example, if the
+ file <code>welcome.html.fr</code> maps onto content type
+ <code>text/html</code> and language French then the file
+ <code>welcome.fr.html</code> will map onto exactly the same
+ information. If more than one extension is given that maps onto
+ the same type of metadata, then the one to the right will
+ be used, except for languages and content encodings. For example,
+ if <code>.gif</code> maps to the <a class="glossarylink" href="../glossary.html#media-type" title="see glossary">media-type</a>
+ <code>image/gif</code> and <code>.html</code> maps to the
+ media-type <code>text/html</code>, then the file
+ <code>welcome.gif.html</code> will be associated with the
+ media-type <code>text/html</code>.</p>
+
+ <p><a href="#charset-lang">Languages</a> and <a href="#contentencoding">content encodings</a> are treated accumulative, because one can assign
+ more than one language or encoding to a particular resource. For example,
+ the file <code>welcome.html.en.de</code> will be delivered with
+ <code>Content-Language: en, de</code> and <code>Content-Type:
+ text/html</code>.</p>
+
+ <p>Care should be taken when a file with multiple extensions
+ gets associated with both a <a class="glossarylink" href="../glossary.html#media-type" title="see glossary">media-type</a>
+ and a handler. This will
+ usually result in the request being handled by the module associated
+ with the handler. For example, if the <code>.imap</code>
+ extension is mapped to the handler <code>imap-file</code> (from
+ <code class="module"><a href="../mod/mod_imagemap.html">mod_imagemap</a></code>) and the <code>.html</code> extension is
+ mapped to the media-type <code>text/html</code>, then the file
+ <code>world.imap.html</code> will be associated with both the
+ <code>imap-file</code> handler and <code>text/html</code> media-type.
+ When it is processed, the <code>imap-file</code> handler will be used,
+ and so it will be treated as a <code class="module"><a href="../mod/mod_imagemap.html">mod_imagemap</a></code> imagemap
+ file.</p>
+
+ <p>If you would prefer only the last dot-separated part of the
+ filename to be mapped to a particular piece of meta-data, then do
+ not use the <code>Add*</code> directives. For example, if you wish
+ to have the file <code>foo.html.cgi</code> processed as a CGI
+ script, but not the file <code>bar.cgi.html</code>, then instead
+ of using <code>AddHandler cgi-script .cgi</code>, use</p>
+
+ <div class="example"><h3>Configure handler based on final extension only</h3><pre class="prettyprint lang-config"><FilesMatch "\.cgi$">
+ SetHandler cgi-script
+</FilesMatch></pre>
+</div>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="contentencoding" id="contentencoding">Content encoding</a></h2>
+ <p>A file of a particular <a class="glossarylink" href="../glossary.html#media-type" title="see glossary">media-type</a> can additionally be encoded a
+ particular way to simplify transmission over the Internet.
+ While this usually will refer to compression, such as
+ <code>gzip</code>, it can also refer to encryption, such a
+ <code>pgp</code> or to an encoding such as UUencoding, which is
+ designed for transmitting a binary file in an ASCII (text)
+ format.</p>
+
+ <p>The <a href="http://www.ietf.org/rfc/rfc2616.txt">HTTP/1.1
+ RFC</a>, section 14.11 puts it this way:</p>
+
+ <blockquote cite="http://www.ietf.org/rfc/rfc2616.txt">
+ <p>The Content-Encoding entity-header field is used as a modifier to
+ the media-type. When present, its value indicates what additional
+ content codings have been applied to the entity-body, and thus what
+ decoding mechanisms must be applied in order to obtain the media-type
+ referenced by the Content-Type header field. Content-Encoding is
+ primarily used to allow a document to be compressed without losing
+ the identity of its underlying media type.</p>
+ </blockquote>
+
+ <p>By using more than one file extension (see <a href="#multipleext">section above about multiple file
+ extensions</a>), you can indicate that a file is of a
+ particular <em>type</em>, and also has a particular
+ <em>encoding</em>. </p>
+
+ <p>For example, you may have a file which is a Microsoft Word
+ document, which is pkzipped to reduce its size. If the
+ <code>.doc</code> extension is associated with the Microsoft
+ Word file type, and the <code>.zip</code> extension is
+ associated with the pkzip file encoding, then the file
+ <code>Resume.doc.zip</code> would be known to be a pkzip'ed Word
+ document.</p>
+
+ <p>Apache sends a <code>Content-encoding</code> header with the
+ resource, in order to tell the client browser about the
+ encoding method.</p>
+
+ <pre class="prettyprint lang-config">Content-encoding: pkzip</pre>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="charset-lang" id="charset-lang">Character sets and languages</a></h2>
+ <p>In addition to file type and the file encoding,
+ another important piece of information is what language a
+ particular document is in, and in what character set the file
+ should be displayed. For example, the document might be written
+ in the Vietnamese alphabet, or in Cyrillic, and should be
+ displayed as such. This information, also, is transmitted in
+ HTTP headers.</p>
+
+ <p>The character set, language, encoding and mime type are all
+ used in the process of content negotiation (See
+ <code class="module"><a href="../mod/mod_negotiation.html">mod_negotiation</a></code>) to determine
+ which document to give to the client, when there are
+ alternative documents in more than one character set, language,
+ encoding or mime type. All filename extensions associations
+ created with <code class="directive"><a href="#addcharset">AddCharset</a></code>,
+ <code class="directive"><a href="#addencoding">AddEncoding</a></code>, <code class="directive"><a href="#addlanguage">AddLanguage</a></code> and <code class="directive"><a href="#addtype">AddType</a></code> directives
+ (and extensions listed in the <code class="directive"><a href="../mod/mod_mime_magic.html#mimemagicfile">MimeMagicFile</a></code>) participate in this select process.
+ Filename extensions that are only associated using the <code class="directive"><a href="#addhandler">AddHandler</a></code>, <code class="directive"><a href="#addinputfilter">AddInputFilter</a></code> or <code class="directive"><a href="#addoutputfilter">AddOutputFilter</a></code> directives may be included or excluded
+ from matching by using the <code class="directive"><a href="#multiviewsmatch">MultiviewsMatch</a></code> directive.</p>
+
+ <h3><a name="charset" id="charset">Charset</a></h3>
+ <p>To convey this further information, Apache optionally sends
+ a <code>Content-Language</code> header, to specify the language
+ that the document is in, and can append additional information
+ onto the <code>Content-Type</code> header to indicate the
+ particular character set that should be used to correctly
+ render the information.</p>
+
+ <div class="example"><p><code>
+Content-Language: en, fr
+Content-Type: text/plain; charset=ISO-8859-1
+ </code></p></div>
+
+ <p>The language specification is the two-letter abbreviation
+ for the language. The <code>charset</code> is the name of the
+ particular character set which should be used.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AddCharset" id="AddCharset">AddCharset</a> <a name="addcharset" id="addcharset">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maps the given filename extensions to the specified content
<ul>
<li><code class="module"><a href="../mod/mod_mime_magic.html">mod_mime_magic</a></code></li>
</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="multipleext" id="multipleext">Files with Multiple Extensions</a></h2>
- <p>Files can have more than one extension; the order of the
- extensions is <em>normally</em> irrelevant. For example, if the
- file <code>welcome.html.fr</code> maps onto content type
- <code>text/html</code> and language French then the file
- <code>welcome.fr.html</code> will map onto exactly the same
- information. If more than one extension is given that maps onto
- the same type of metadata, then the one to the right will
- be used, except for languages and content encodings. For example,
- if <code>.gif</code> maps to the <a class="glossarylink" href="../glossary.html#media-type" title="see glossary">media-type</a>
- <code>image/gif</code> and <code>.html</code> maps to the
- media-type <code>text/html</code>, then the file
- <code>welcome.gif.html</code> will be associated with the
- media-type <code>text/html</code>.</p>
-
- <p><a href="#charset-lang">Languages</a> and <a href="#contentencoding">content encodings</a> are treated accumulative, because one can assign
- more than one language or encoding to a particular resource. For example,
- the file <code>welcome.html.en.de</code> will be delivered with
- <code>Content-Language: en, de</code> and <code>Content-Type:
- text/html</code>.</p>
-
- <p>Care should be taken when a file with multiple extensions
- gets associated with both a <a class="glossarylink" href="../glossary.html#media-type" title="see glossary">media-type</a>
- and a handler. This will
- usually result in the request being handled by the module associated
- with the handler. For example, if the <code>.imap</code>
- extension is mapped to the handler <code>imap-file</code> (from
- <code class="module"><a href="../mod/mod_imagemap.html">mod_imagemap</a></code>) and the <code>.html</code> extension is
- mapped to the media-type <code>text/html</code>, then the file
- <code>world.imap.html</code> will be associated with both the
- <code>imap-file</code> handler and <code>text/html</code> media-type.
- When it is processed, the <code>imap-file</code> handler will be used,
- and so it will be treated as a <code class="module"><a href="../mod/mod_imagemap.html">mod_imagemap</a></code> imagemap
- file.</p>
-
- <p>If you would prefer only the last dot-separated part of the
- filename to be mapped to a particular piece of meta-data, then do
- not use the <code>Add*</code> directives. For example, if you wish
- to have the file <code>foo.html.cgi</code> processed as a CGI
- script, but not the file <code>bar.cgi.html</code>, then instead
- of using <code>AddHandler cgi-script .cgi</code>, use</p>
-
- <div class="example"><h3>Configure handler based on final extension only</h3><pre class="prettyprint lang-config"><FilesMatch "\.cgi$">
- SetHandler cgi-script
-</FilesMatch></pre>
-</div>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="contentencoding" id="contentencoding">Content encoding</a></h2>
- <p>A file of a particular <a class="glossarylink" href="../glossary.html#media-type" title="see glossary">media-type</a> can additionally be encoded a
- particular way to simplify transmission over the Internet.
- While this usually will refer to compression, such as
- <code>gzip</code>, it can also refer to encryption, such a
- <code>pgp</code> or to an encoding such as UUencoding, which is
- designed for transmitting a binary file in an ASCII (text)
- format.</p>
-
- <p>The <a href="http://www.ietf.org/rfc/rfc2616.txt">HTTP/1.1
- RFC</a>, section 14.11 puts it this way:</p>
-
- <blockquote cite="http://www.ietf.org/rfc/rfc2616.txt">
- <p>The Content-Encoding entity-header field is used as a modifier to
- the media-type. When present, its value indicates what additional
- content codings have been applied to the entity-body, and thus what
- decoding mechanisms must be applied in order to obtain the media-type
- referenced by the Content-Type header field. Content-Encoding is
- primarily used to allow a document to be compressed without losing
- the identity of its underlying media type.</p>
- </blockquote>
-
- <p>By using more than one file extension (see <a href="#multipleext">section above about multiple file
- extensions</a>), you can indicate that a file is of a
- particular <em>type</em>, and also has a particular
- <em>encoding</em>. </p>
-
- <p>For example, you may have a file which is a Microsoft Word
- document, which is pkzipped to reduce its size. If the
- <code>.doc</code> extension is associated with the Microsoft
- Word file type, and the <code>.zip</code> extension is
- associated with the pkzip file encoding, then the file
- <code>Resume.doc.zip</code> would be known to be a pkzip'ed Word
- document.</p>
-
- <p>Apache sends a <code>Content-encoding</code> header with the
- resource, in order to tell the client browser about the
- encoding method.</p>
-
- <pre class="prettyprint lang-config">Content-encoding: pkzip</pre>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="charset-lang" id="charset-lang">Character sets and languages</a></h2>
- <p>In addition to file type and the file encoding,
- another important piece of information is what language a
- particular document is in, and in what character set the file
- should be displayed. For example, the document might be written
- in the Vietnamese alphabet, or in Cyrillic, and should be
- displayed as such. This information, also, is transmitted in
- HTTP headers.</p>
-
- <p>The character set, language, encoding and mime type are all
- used in the process of content negotiation (See
- <code class="module"><a href="../mod/mod_negotiation.html">mod_negotiation</a></code>) to determine
- which document to give to the client, when there are
- alternative documents in more than one character set, language,
- encoding or mime type. All filename extensions associations
- created with <code class="directive"><a href="#addcharset">AddCharset</a></code>,
- <code class="directive"><a href="#addencoding">AddEncoding</a></code>, <code class="directive"><a href="#addlanguage">AddLanguage</a></code> and <code class="directive"><a href="#addtype">AddType</a></code> directives
- (and extensions listed in the <code class="directive"><a href="../mod/mod_mime_magic.html#mimemagicfile">MimeMagicFile</a></code>) participate in this select process.
- Filename extensions that are only associated using the <code class="directive"><a href="#addhandler">AddHandler</a></code>, <code class="directive"><a href="#addinputfilter">AddInputFilter</a></code> or <code class="directive"><a href="#addoutputfilter">AddOutputFilter</a></code> directives may be included or excluded
- from matching by using the <code class="directive"><a href="#multiviewsmatch">MultiviewsMatch</a></code> directive.</p>
-
- <h3><a name="charset" id="charset">Charset</a></h3>
- <p>To convey this further information, Apache optionally sends
- a <code>Content-Language</code> header, to specify the language
- that the document is in, and can append additional information
- onto the <code>Content-Type</code> header to indicate the
- particular character set that should be used to correctly
- render the information.</p>
-
- <div class="example"><p><code>
-Content-Language: en, fr
-Content-Type: text/plain; charset=ISO-8859-1
- </code></p></div>
-
- <p>The language specification is the two-letter abbreviation
- for the language. The <code>charset</code> is the name of the
- particular character set which should be used.</p>
-
</div>
</div>
<div class="bottomlang">
what the contents are. This module is active only if the magic
file is specified by the <code class="directive"><a href="#mimemagicfile">MimeMagicFile</a></code> directive.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#mimemagicfile">MimeMagicFile</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#format">Format of the Magic File</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#performance">Performance Issues</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#notes">Notes</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="MimeMagicFile" id="MimeMagicFile">MimeMagicFile</a> <a name="mimemagicfile" id="mimemagicfile">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable MIME-type determination based on file contents
-using the specified magic file</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MimeMagicFile <var>file-path</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_mime_magic</td></tr>
-</table>
- <p>The <code class="directive">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
- <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>. 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>
-
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">MimeMagicFile conf/magic</pre>
-</div>
-
-</div>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#mimemagicfile">MimeMagicFile</a></li>
+</ul>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="format" id="format">Format of the Magic File</a></h2>
used here.</li>
</ul>
</div>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="MimeMagicFile" id="MimeMagicFile">MimeMagicFile</a> <a name="mimemagicfile" id="mimemagicfile">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable MIME-type determination based on file contents
+using the specified magic file</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MimeMagicFile <var>file-path</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_mime_magic</td></tr>
+</table>
+ <p>The <code class="directive">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
+ <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>. 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>
+
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">MimeMagicFile conf/magic</pre>
+</div>
+
</div>
</div>
<div class="bottomlang">
results.</li>
</ul>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#typemaps">Type maps</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#multiviews">Multiviews</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#cachenegotiateddocs">CacheNegotiatedDocs</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#forcelanguagepriority">ForceLanguagePriority</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#languagepriority">LanguagePriority</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#typemaps">Type maps</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#multiviews">Multiviews</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/core.html#options">Options</a></code></li>
<li><code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code></li>
<li><a href="../env.html">Environment Variables</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="CacheNegotiatedDocs" id="CacheNegotiatedDocs">CacheNegotiatedDocs</a> <a name="cachenegotiateddocs" id="cachenegotiateddocs">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Allows content-negotiated documents to be
-cached by proxy servers</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheNegotiatedDocs On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheNegotiatedDocs Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_negotiation</td></tr>
-</table>
- <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>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ForceLanguagePriority" id="ForceLanguagePriority">ForceLanguagePriority</a> <a name="forcelanguagepriority" id="forcelanguagepriority">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Action to take if a single acceptable document is not
-found</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ForceLanguagePriority Prefer</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_negotiation</td></tr>
-</table>
- <p>The <code class="directive">ForceLanguagePriority</code> directive uses
- the given <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> to satisfy
- negotiation where the server could otherwise not return a single
- matching document.</p>
-
- <p><code>ForceLanguagePriority Prefer</code> uses
- <code>LanguagePriority</code> to serve a one valid result, rather
- than returning an HTTP result 300 (MULTIPLE CHOICES) when there
- are several equally valid choices. If the directives below were
- given, and the user's <code>Accept-Language</code> header assigned
- <code>en</code> and <code>de</code> each as quality <code>.500</code>
- (equally acceptable) then the first matching variant, <code>en</code>,
- will be served.</p>
-
- <pre class="prettyprint lang-config">LanguagePriority en fr de
-ForceLanguagePriority Prefer</pre>
-
-
- <p><code>ForceLanguagePriority Fallback</code> uses
- <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> to
- serve a valid result, rather than returning an HTTP result 406
- (NOT ACCEPTABLE). If the directives below were given, and the user's
- <code>Accept-Language</code> only permitted an <code>es</code>
- language response, but such a variant isn't found, then the first
- variant from the <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> list below will be served.</p>
-
- <pre class="prettyprint lang-config">LanguagePriority en fr de
-ForceLanguagePriority Fallback</pre>
-
-
- <p>Both options, <code>Prefer</code> and <code>Fallback</code>, may be
- specified, so either the first matching variant from <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> will be served if
- more than one variant is acceptable, or first available document will
- be served if none of the variants matched the client's acceptable list
- of languages.</p>
-
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="../mod/mod_mime.html#addlanguage">AddLanguage</a></code></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LanguagePriority" id="LanguagePriority">LanguagePriority</a> <a name="languagepriority" id="languagepriority">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The precendence of language variants for cases where
-the client does not express a preference</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LanguagePriority <var>MIME-lang</var> [<var>MIME-lang</var>]
-...</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_negotiation</td></tr>
-</table>
- <p>The <code class="directive">LanguagePriority</code> 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 <var>MIME-lang</var> are in order of decreasing preference.</p>
-
- <pre class="prettyprint lang-config">LanguagePriority en fr de</pre>
-
-
- <p>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 or the <code class="directive"><a href="#forcelanguagepriority">ForceLanguagePriority</a></code> directive
- is not <code>None</code>. In general, the client determines the
- language preference, not the server.</p>
-
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="../mod/mod_mime.html#addlanguage">AddLanguage</a></code></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="typemaps" id="typemaps">Type maps</a></h2>
<p>A type map has a format similar to RFC822 mail headers. It
that do not have content negotiation meta-information assigned
to them when choosing files.</p>
</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="CacheNegotiatedDocs" id="CacheNegotiatedDocs">CacheNegotiatedDocs</a> <a name="cachenegotiateddocs" id="cachenegotiateddocs">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Allows content-negotiated documents to be
+cached by proxy servers</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheNegotiatedDocs On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheNegotiatedDocs Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_negotiation</td></tr>
+</table>
+ <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>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ForceLanguagePriority" id="ForceLanguagePriority">ForceLanguagePriority</a> <a name="forcelanguagepriority" id="forcelanguagepriority">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Action to take if a single acceptable document is not
+found</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ForceLanguagePriority Prefer</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_negotiation</td></tr>
+</table>
+ <p>The <code class="directive">ForceLanguagePriority</code> directive uses
+ the given <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> to satisfy
+ negotiation where the server could otherwise not return a single
+ matching document.</p>
+
+ <p><code>ForceLanguagePriority Prefer</code> uses
+ <code>LanguagePriority</code> to serve a one valid result, rather
+ than returning an HTTP result 300 (MULTIPLE CHOICES) when there
+ are several equally valid choices. If the directives below were
+ given, and the user's <code>Accept-Language</code> header assigned
+ <code>en</code> and <code>de</code> each as quality <code>.500</code>
+ (equally acceptable) then the first matching variant, <code>en</code>,
+ will be served.</p>
+
+ <pre class="prettyprint lang-config">LanguagePriority en fr de
+ForceLanguagePriority Prefer</pre>
+
+
+ <p><code>ForceLanguagePriority Fallback</code> uses
+ <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> to
+ serve a valid result, rather than returning an HTTP result 406
+ (NOT ACCEPTABLE). If the directives below were given, and the user's
+ <code>Accept-Language</code> only permitted an <code>es</code>
+ language response, but such a variant isn't found, then the first
+ variant from the <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> list below will be served.</p>
+
+ <pre class="prettyprint lang-config">LanguagePriority en fr de
+ForceLanguagePriority Fallback</pre>
+
+
+ <p>Both options, <code>Prefer</code> and <code>Fallback</code>, may be
+ specified, so either the first matching variant from <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> will be served if
+ more than one variant is acceptable, or first available document will
+ be served if none of the variants matched the client's acceptable list
+ of languages.</p>
+
+<h3>See also</h3>
+<ul>
+<li><code class="directive"><a href="../mod/mod_mime.html#addlanguage">AddLanguage</a></code></li>
+</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LanguagePriority" id="LanguagePriority">LanguagePriority</a> <a name="languagepriority" id="languagepriority">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The precendence of language variants for cases where
+the client does not express a preference</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LanguagePriority <var>MIME-lang</var> [<var>MIME-lang</var>]
+...</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_negotiation</td></tr>
+</table>
+ <p>The <code class="directive">LanguagePriority</code> 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 <var>MIME-lang</var> are in order of decreasing preference.</p>
+
+ <pre class="prettyprint lang-config">LanguagePriority en fr de</pre>
+
+
+ <p>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 or the <code class="directive"><a href="#forcelanguagepriority">ForceLanguagePriority</a></code> directive
+ is not <code>None</code>. In general, the client determines the
+ language preference, not the server.</p>
+
+<h3>See also</h3>
+<ul>
+<li><code class="directive"><a href="../mod/mod_mime.html#addlanguage">AddLanguage</a></code></li>
+</ul>
+</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_negotiation.html" title="English"> en </a> |
<li><img alt="" src="../images/down.gif" /> <a href="#securelisten">SecureListen</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="NWSSLTrustedCerts" id="NWSSLTrustedCerts">NWSSLTrustedCerts</a> <a name="nwssltrustedcerts" id="nwssltrustedcerts">Directive</a></h2>
<table class="directive">
parameter also enables mutual authentication.</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_nw_ssl.html" title="English"> en </a> |
separation is an issue.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#security">Security Considerations</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#dtraceprivileges">DTracePrivileges</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#privilegesmode">PrivilegesMode</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#vhostsecure">VHostSecure</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#vhostuser">VHostUser</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#security">Security Considerations</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="security" id="security">Security Considerations</a></h2>
+
+<p><code class="module"><a href="../mod/mod_privileges.html">mod_privileges</a></code> introduces new security concerns
+in situations where <strong>untrusted code</strong> may be run
+<strong>within the webserver process</strong>. This applies to
+untrusted modules, and scripts running under modules such as
+mod_php or mod_perl. Scripts running externally (e.g. as CGI
+or in an appserver behind mod_proxy or mod_jk) are NOT affected.</p>
+
+<p>The basic security concerns with mod_privileges are:</p>
+<ul><li>Running as a system user introduces the same security issues
+ as mod_suexec, and near-equivalents such as cgiwrap and suphp.</li>
+<li>A privileges-aware malicious user extension (module or script)
+ could escalate its privileges to anything available to the
+ httpd process in any virtual host. This introduces new risks
+ if (and only if) mod_privileges is compiled with the
+ <var>BIG_SECURITY_HOLE</var> option.</li>
+<li>A privileges-aware malicious user extension (module or script)
+ could escalate privileges to set its user ID to another system
+ user (and/or group).</li>
+</ul>
+
+<p>The <code class="directive">PrivilegesMode</code> directive allows you to
+select either <var>FAST</var> or <var>SECURE</var> mode. You can
+mix modes, using <var>FAST</var> mode for trusted users and
+fully-audited code paths, while imposing SECURE mode where an
+untrusted user has scope to introduce code.</p>
+<p>Before describing the modes, we should also introduce the target
+use cases: Benign vs Hostile. In a benign situation, you want to
+separate users for their convenience, and protect them and the server
+against the risks posed by honest mistakes, but you trust your users
+are not deliberately subverting system security. In a hostile
+situation - e.g. commercial hosting - you may have users deliberately
+attacking the system or each other.</p>
+<dl>
+<dt>FAST mode</dt>
+<dd>In <var>FAST</var> mode, requests are run in-process with the
+selected uid/gid and privileges, so the overhead is negligible.
+This is suitable for benign situations, but is not secure against an
+attacker escalating privileges with an in-process module or script.</dd>
+<dt>SECURE mode</dt>
+<dd>A request in <var>SECURE</var> mode forks a subprocess, which
+then drops privileges. This is a very similar case to running CGI
+with suexec, but for the entire request cycle, and with the benefit
+of fine-grained control of privileges.</dd>
+</dl>
+<p>You can select different <code class="directive">PrivilegesMode</code>s for
+each virtual host, and even in a directory context within a virtual
+host. <var>FAST</var> mode is appropriate where the user(s) are
+trusted and/or have no privilege to load in-process code.
+<var>SECURE</var> mode is appropriate to cases where untrusted code
+might be run in-process. However, even in <var>SECURE</var> mode,
+there is no protection against a malicious user who is able to
+introduce privileges-aware code running <em>before the start of the
+request-processing cycle.</em></p>
+
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="DTracePrivileges" id="DTracePrivileges">DTracePrivileges</a> <a name="dtraceprivileges" id="dtraceprivileges">Directive</a></h2>
<table class="directive">
<li><code class="directive"><a href="../mod/mod_unixd.html#user">User</a></code></li>
<li><code class="directive"><a href="../mod/mod_suexec.html#suexecusergroup">SuexecUserGroup</a></code></li>
</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="security" id="security">Security Considerations</a></h2>
-
-<p><code class="module"><a href="../mod/mod_privileges.html">mod_privileges</a></code> introduces new security concerns
-in situations where <strong>untrusted code</strong> may be run
-<strong>within the webserver process</strong>. This applies to
-untrusted modules, and scripts running under modules such as
-mod_php or mod_perl. Scripts running externally (e.g. as CGI
-or in an appserver behind mod_proxy or mod_jk) are NOT affected.</p>
-
-<p>The basic security concerns with mod_privileges are:</p>
-<ul><li>Running as a system user introduces the same security issues
- as mod_suexec, and near-equivalents such as cgiwrap and suphp.</li>
-<li>A privileges-aware malicious user extension (module or script)
- could escalate its privileges to anything available to the
- httpd process in any virtual host. This introduces new risks
- if (and only if) mod_privileges is compiled with the
- <var>BIG_SECURITY_HOLE</var> option.</li>
-<li>A privileges-aware malicious user extension (module or script)
- could escalate privileges to set its user ID to another system
- user (and/or group).</li>
-</ul>
-
-<p>The <code class="directive">PrivilegesMode</code> directive allows you to
-select either <var>FAST</var> or <var>SECURE</var> mode. You can
-mix modes, using <var>FAST</var> mode for trusted users and
-fully-audited code paths, while imposing SECURE mode where an
-untrusted user has scope to introduce code.</p>
-<p>Before describing the modes, we should also introduce the target
-use cases: Benign vs Hostile. In a benign situation, you want to
-separate users for their convenience, and protect them and the server
-against the risks posed by honest mistakes, but you trust your users
-are not deliberately subverting system security. In a hostile
-situation - e.g. commercial hosting - you may have users deliberately
-attacking the system or each other.</p>
-<dl>
-<dt>FAST mode</dt>
-<dd>In <var>FAST</var> mode, requests are run in-process with the
-selected uid/gid and privileges, so the overhead is negligible.
-This is suitable for benign situations, but is not secure against an
-attacker escalating privileges with an in-process module or script.</dd>
-<dt>SECURE mode</dt>
-<dd>A request in <var>SECURE</var> mode forks a subprocess, which
-then drops privileges. This is a very similar case to running CGI
-with suexec, but for the entire request cycle, and with the benefit
-of fine-grained control of privileges.</dd>
-</dl>
-<p>You can select different <code class="directive">PrivilegesMode</code>s for
-each virtual host, and even in a directory context within a virtual
-host. <var>FAST</var> mode is appropriate where the user(s) are
-trusted and/or have no privilege to load in-process code.
-<var>SECURE</var> mode is appropriate to cases where untrusted code
-might be run in-process. However, even in <var>SECURE</var> mode,
-there is no protection against a malicious user who is able to
-introduce privileges-aware code running <em>before the start of the
-request-processing cycle.</em></p>
-
</div>
</div>
<div class="bottomlang">
<code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>. These additional modules will need
to be loaded and configured to take advantage of these features.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#forwardreverse">Forward Proxies and Reverse
+ Proxies/Gateways</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Basic Examples</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#handler">Access via Handler</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#workers">Workers</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#access">Controlling access to your proxy</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#startup">Slow Startup</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#intranet">Intranet Proxy</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#envsettings">Protocol Adjustments</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#request-bodies">Request Bodies</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#x-headers">Reverse Proxy Request Headers</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#balancergrowth">BalancerGrowth</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#balancerinherit">BalancerInherit</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxytimeout">ProxyTimeout</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxyvia">ProxyVia</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#forwardreverse">Forward Proxies and Reverse
- Proxies/Gateways</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#examples">Basic Examples</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#handler">Access via Handler</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#workers">Workers</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#access">Controlling access to your proxy</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#startup">Slow Startup</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#intranet">Intranet Proxy</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#envsettings">Protocol Adjustments</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#request-bodies">Request Bodies</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#x-headers">Reverse Proxy Request Headers</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code></li>
<li><code class="module"><a href="../mod/mod_proxy_ajp.html">mod_proxy_ajp</a></code></li>
<li><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="BalancerGrowth" id="BalancerGrowth">BalancerGrowth</a> <a name="balancergrowth" id="balancergrowth">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of additional Balancers that can be added Post-configuration</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerGrowth <var>#</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerGrowth 5</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerGrowth is only available in Apache HTTP Server 2.3.13
- and later.</td></tr>
-</table>
- <p>This directive allows for growth potential in the number of
- Balancers available for a virtualhost in addition to the
- number pre-configured. It only takes effect if there is at
- least 1 pre-configured Balancer.</p>
+<div class="section">
+<h2><a name="forwardreverse" id="forwardreverse">Forward Proxies and Reverse
+ Proxies/Gateways</a></h2>
+ <p>Apache HTTP Server can be configured in both a <dfn>forward</dfn> and
+ <dfn>reverse</dfn> proxy (also known as <dfn>gateway</dfn>) mode.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="BalancerInherit" id="BalancerInherit">BalancerInherit</a> <a name="balancerinherit" id="balancerinherit">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Inherit ProxyPassed Balancers/Workers from the main server</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerInherit On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerInherit On</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerInherit is only available in Apache HTTP Server 2.4.5 and later.</td></tr>
-</table>
- <p>This directive will cause the current server/vhost to "inherit" ProxyPass
- Balancers and Workers defined in the main server. This can cause issues and
- inconsistent behavior if using the Balancer Manager and so should be disabled
- if using that feature.</p>
- <p>The setting in the global server defines the default for all vhosts.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="BalancerMember" id="BalancerMember">BalancerMember</a> <a name="balancermember" id="balancermember">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a member to a load balancing group</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerMember [<var>balancerurl</var>] <var>url</var> [<var>key=value [key=value ...]]</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerMember is only available in Apache HTTP Server 2.2
- and later.</td></tr>
-</table>
- <p>This directive adds a member to a load balancing group. It could be used
- within a <code><Proxy <var>balancer://</var>...></code> container
- directive, and can take any of the key value pair parameters available to
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> directives.</p>
- <p>One additional parameter is available only to <code class="directive">BalancerMember</code> directives:
- <var>loadfactor</var>. This is the member load factor - a number between 1
- (default) and 100, which defines the weighted load to be applied to the
- member in question.</p>
- <p>The <var>balancerurl</var> is only needed when not in
- <code><Proxy <var>balancer://</var>...></code>
- container directive. It corresponds to the url of a balancer defined in
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
- <p>The path component of the balancer URL in any
- <code><Proxy <var>balancer://</var>...></code> container directive
- is ignored.</p>
- <p>Trailing slashes should typically be removed from the URL of a
- <code class="directive">BalancerMember</code>.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="BalancerPersist" id="BalancerPersist">BalancerPersist</a> <a name="balancerpersist" id="balancerpersist">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Attempt to persist changes made by the Balancer Manager across restarts.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerPersist On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerPersist Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerPersist is only available in Apache HTTP Server 2.4.4 and later.</td></tr>
-</table>
- <p>This directive will cause the shared memory storage associated
- with the balancers and balancer members to be persisted across
- restarts. This allows these local changes to not be lost during the
- normal restart/graceful state transitions.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="NoProxy" id="NoProxy">NoProxy</a> <a name="noproxy" id="noproxy">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Hosts, domains, or networks that will be connected to
-directly</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>NoProxy <var>host</var> [<var>host</var>] ...</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>This directive is only useful for Apache httpd proxy servers within
- intranets. The <code class="directive">NoProxy</code> directive specifies a
- list of subnets, IP addresses, hosts and/or domains, separated by
- spaces. A request to a host which matches one or more of these is
- always served directly, without forwarding to the configured
- <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> proxy server(s).</p>
+ <p>An ordinary <dfn>forward proxy</dfn> is an intermediate
+ server that sits between the client and the <em>origin
+ server</em>. In order to get content from the origin server,
+ the client sends a request to the proxy naming the origin server
+ as the target and the proxy then requests the content from the
+ origin server and returns it to the client. The client must be
+ specially configured to use the forward proxy to access other
+ sites.</p>
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyRemote "*" "http://firewall.example.com:81"
-NoProxy ".example.com" "192.168.112.0/21"</pre>
-</div>
+ <p>A typical usage of a forward proxy is to provide Internet
+ access to internal clients that are otherwise restricted by a
+ firewall. The forward proxy can also use caching (as provided
+ by <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>) to reduce network usage.</p>
- <p>The <var>host</var> arguments to the <code class="directive">NoProxy</code>
- directive are one of the following type list:</p>
+ <p>The forward proxy is activated using the <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive. Because
+ forward proxies allow clients to access arbitrary sites through
+ your server and to hide their true origin, it is essential that
+ you <a href="#access">secure your server</a> so that only
+ authorized clients can access the proxy before activating a
+ forward proxy.</p>
- <dl>
-
- <dt><var><a name="domain" id="domain">Domain</a></var></dt>
- <dd>
- <p>A <dfn>Domain</dfn> is a partially qualified DNS domain name, preceded
- by a period. It represents a list of hosts which logically belong to the
- same DNS domain or zone (<em>i.e.</em>, the suffixes of the hostnames are
- all ending in <var>Domain</var>).</p>
+ <p>A <dfn>reverse proxy</dfn> (or <dfn>gateway</dfn>), by
+ contrast, appears to the client just like an ordinary web
+ server. No special configuration on the client is necessary.
+ The client makes ordinary requests for content in the name-space
+ of the reverse proxy. The reverse proxy then decides where to
+ send those requests, and returns the content as if it was itself
+ the origin.</p>
- <div class="example"><h3>Examples</h3><p><code>
- .com .example.org.
- </code></p></div>
+ <p>A typical usage of a reverse proxy is to provide Internet
+ users access to a server that is behind a firewall. Reverse
+ proxies can also be used to balance load among several back-end
+ servers, or to provide caching for a slower back-end server.
+ In addition, reverse proxies can be used simply to bring
+ several servers into the same URL space.</p>
- <p>To distinguish <var>Domain</var>s from <var><a href="#hostname">Hostname</a></var>s (both syntactically and semantically; a DNS domain can
- have a DNS A record, too!), <var>Domain</var>s are always written with a
- leading period.</p>
+ <p>A reverse proxy is activated using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive or the
+ <code>[P]</code> flag to the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive. It is
+ <strong>not</strong> necessary to turn <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> on in order to
+ configure a reverse proxy.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="examples" id="examples">Basic Examples</a></h2>
- <div class="note"><h3>Note</h3>
- <p>Domain name comparisons are done without regard to the case, and
- <var>Domain</var>s are always assumed to be anchored in the root of the
- DNS tree, therefore two domains <code>.ExAmple.com</code> and
- <code>.example.com.</code> (note the trailing period) are considered
- equal. Since a domain comparison does not involve a DNS lookup, it is much
- more efficient than subnet comparison.</p>
- </div></dd>
+ <p>The examples below are only a very basic idea to help you
+ get started. Please read the documentation on the individual
+ directives.</p>
-
- <dt><var><a name="subnet" id="subnet">SubNet</a></var></dt>
- <dd>
- <p>A <dfn>SubNet</dfn> is a partially qualified internet address in
- numeric (dotted quad) form, optionally followed by a slash and the netmask,
- specified as the number of significant bits in the <var>SubNet</var>. It is
- used to represent a subnet of hosts which can be reached over a common
- network interface. In the absence of the explicit net mask it is assumed
- that omitted (or zero valued) trailing digits specify the mask. (In this
- case, the netmask can only be multiples of 8 bits wide.) Examples:</p>
+ <p>In addition, if you wish to have caching enabled, consult
+ the documentation from <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>.</p>
- <dl>
- <dt><code>192.168</code> or <code>192.168.0.0</code></dt>
- <dd>the subnet 192.168.0.0 with an implied netmask of 16 valid bits
- (sometimes used in the netmask form <code>255.255.0.0</code>)</dd>
- <dt><code>192.168.112.0/21</code></dt>
- <dd>the subnet <code>192.168.112.0/21</code> with a netmask of 21
- valid bits (also used in the form <code>255.255.248.0</code>)</dd>
- </dl>
+ <div class="example"><h3>Reverse Proxy</h3><pre class="prettyprint lang-config">ProxyPass "/foo" "http://foo.example.com/bar"
+ProxyPassReverse "/foo" "http://foo.example.com/bar"</pre>
+</div>
- <p>As a degenerate case, a <em>SubNet</em> with 32 valid bits is the
- equivalent to an <var><a href="#ipaddr">IPAddr</a></var>, while a <var>SubNet</var> with zero
- valid bits (<em>e.g.</em>, 0.0.0.0/0) is the same as the constant
- <var>_Default_</var>, matching any IP address.</p></dd>
+ <div class="example"><h3>Forward Proxy</h3><pre class="prettyprint lang-config">ProxyRequests On
+ProxyVia On
-
- <dt><var><a name="ipaddr" id="ipaddr">IPAddr</a></var></dt>
- <dd>
- <p>A <dfn>IPAddr</dfn> represents a fully qualified internet address in
- numeric (dotted quad) form. Usually, this address represents a host, but
- there need not necessarily be a DNS domain name connected with the
- address.</p>
- <div class="example"><h3>Example</h3><p><code>
- 192.168.123.7
- </code></p></div>
+<Proxy "*">
+ Require host internal.example.com
+</Proxy></pre>
+</div>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="handler" id="handler">Access via Handler</a></h2>
- <div class="note"><h3>Note</h3>
- <p>An <var>IPAddr</var> does not need to be resolved by the DNS system, so
- it can result in more effective apache performance.</p>
- </div></dd>
+ <p>You can also force a request to be handled as a reverse-proxy
+ request, by creating a suitable Handler pass-through. The example
+ configuration below will pass all requests for PHP scripts to the
+ specified FastCGI server using reverse proxy:
+ </p>
-
- <dt><var><a name="hostname" id="hostname">Hostname</a></var></dt>
- <dd>
- <p>A <dfn>Hostname</dfn> is a fully qualified DNS domain name which can
- be resolved to one or more <var><a href="#ipaddr">IPAddrs</a></var> via the
- DNS domain name service. It represents a logical host (in contrast to
- <var><a href="#domain">Domain</a></var>s, see above) and must be resolvable
- to at least one <var><a href="#ipaddr">IPAddr</a></var> (or often to a list
- of hosts with different <var><a href="#ipaddr">IPAddr</a></var>s).</p>
+ <div class="example"><h3>Reverse Proxy PHP scripts</h3><pre class="prettyprint lang-config"><FilesMatch "\.php$">
+ # Unix sockets require 2.4.7 or later
+ SetHandler "proxy:unix:/path/to/app.sock|fcgi://localhost/"
+</FilesMatch></pre>
+</div>
- <div class="example"><h3>Examples</h3><p><code>
- prep.ai.example.edu<br />
- www.example.org
- </code></p></div>
+ <p>This feature is available in Apache HTTP Server 2.4.10 and later.</p>
- <div class="note"><h3>Note</h3>
- <p>In many situations, it is more effective to specify an <var><a href="#ipaddr">IPAddr</a></var> in place of a <var>Hostname</var> since a
- DNS lookup can be avoided. Name resolution in Apache httpd can take a remarkable
- deal of time when the connection to the name server uses a slow PPP
- link.</p>
- <p><var>Hostname</var> comparisons are done without regard to the case,
- and <var>Hostname</var>s are always assumed to be anchored in the root
- of the DNS tree, therefore two hosts <code>WWW.ExAmple.com</code>
- and <code>www.example.com.</code> (note the trailing period) are
- considered equal.</p>
- </div></dd>
- </dl>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="workers" id="workers">Workers</a></h2>
+ <p>The proxy manages the configuration of origin servers and their
+ communication parameters in objects called <dfn>workers</dfn>.
+ There are two built-in workers, the default forward proxy worker and the
+ default reverse proxy worker. Additional workers can be configured
+ explicitly.</p>
-<h3>See also</h3>
-<ul>
-<li><a href="../dns-caveats.html">DNS Issues</a></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="Proxy" id="Proxy"><Proxy></a> <a name="proxy" id="proxy">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Container for directives applied to proxied resources</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><Proxy <var>wildcard-url</var>> ...</Proxy></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>Directives placed in <code class="directive"><Proxy></code>
- sections apply only to matching proxied content. Shell-style wildcards are
- allowed.</p>
+ <p>The two default workers have a fixed configuration
+ and will be used if no other worker matches the request.
+ They do not use HTTP Keep-Alive or connection pooling.
+ The TCP connections to the origin server will instead be
+ opened and closed for each request.</p>
- <p>For example, the following will allow only hosts in
- <code>yournetwork.example.com</code> to access content via your proxy
- server:</p>
+ <p>Explicitly configured workers are identified by their URL.
+ They are usually created and configured using
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> or
+ <code class="directive"><a href="#proxypassmatch">ProxyPassMatch</a></code> when used
+ for a reverse proxy:</p>
- <pre class="prettyprint lang-config"><Proxy "*">
- Require host yournetwork.example.com
-</Proxy></pre>
+ <pre class="prettyprint lang-config">ProxyPass "/example" "http://backend.example.com" connectiontimeout=5 timeout=30</pre>
- <p>The following example will process all files in the <code>foo</code>
- directory of <code>example.com</code> through the <code>INCLUDES</code>
- filter when they are sent through the proxy server:</p>
+ <p>This will create a worker associated with the origin server URL
+ <code>http://backend.example.com</code> and using the given timeout
+ values. When used in a forward proxy, workers are usually defined
+ via the <code class="directive"><a href="#proxyset">ProxySet</a></code> directive:</p>
- <pre class="prettyprint lang-config"><Proxy "http://example.com/foo/*">
- SetOutputFilter INCLUDES
+ <pre class="prettyprint lang-config">ProxySet "http://backend.example.com" connectiontimeout=5 timeout=30</pre>
+
+
+ <p>or alternatively using <code class="directive"><a href="#proxy">Proxy</a></code>
+ and <code class="directive"><a href="#proxyset">ProxySet</a></code>:</p>
+
+ <pre class="prettyprint lang-config"><Proxy "http://backend.example.com">
+ ProxySet connectiontimeout=5 timeout=30
</Proxy></pre>
- <div class="note"><h3>Differences from the Location configuration section</h3>
- <p>A backend URL matches the configuration section if it begins with the
- the <var>wildcard-url</var> string, even if the last path segment in the
- directive only matches a prefix of the backend URL. For example,
- <Proxy "http://example.com/foo"> matches all of
- http://example.com/foo, http://example.com/foo/bar, and
- http://example.com/foobar. The matching of the final URL differs
- from the behavior of the <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section, which for purposes of this note
- treats the final path component as if it ended in a slash.</p>
- <p>For more control over the matching, see <code class="directive"><ProxyMatch></code>.</p>
- </div>
+ <p>Using explicitly configured workers in the forward mode is
+ not very common, because forward proxies usually communicate with many
+ different origin servers. Creating explicit workers for some of the
+ origin servers can still be useful, if they are used very often.
+ Explicitly configured workers have no concept of forward or reverse
+ proxying by themselves. They encapsulate a common concept of
+ communication with origin servers. A worker created by
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> for use in a
+ reverse proxy will be also used for forward proxy requests whenever
+ the URL to the origin server matches the worker URL and vice versa.</p>
+ <p>The URL identifying a direct worker is the URL of its
+ origin server including any path components given:</p>
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="#proxymatch"><ProxyMatch></a></code></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyAddHeaders" id="ProxyAddHeaders">ProxyAddHeaders</a> <a name="proxyaddheaders" id="proxyaddheaders">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add proxy information in X-Forwarded-* headers</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyAddHeaders Off|On</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyAddHeaders On</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.10 and later</td></tr>
-</table>
- <p>This directive determines whether or not proxy related information should be passed to the
- backend server through X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Server HTTP headers.</p>
- <div class="note"><h3>Effectiveness</h3>
- <p>This option is of use only for HTTP proxying, as handled by <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>.</p>
- </div>
+ <pre class="prettyprint lang-config">ProxyPass "/examples" "http://backend.example.com/examples"
+ProxyPass "/docs" "http://backend.example.com/docs"</pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyBadHeader" id="ProxyBadHeader">ProxyBadHeader</a> <a name="proxybadheader" id="proxybadheader">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines how to handle bad header lines in a
-response</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyBadHeader IsError|Ignore|StartBody</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyBadHeader IsError</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>The <code class="directive">ProxyBadHeader</code> directive determines the
- behaviour of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> if it receives syntactically invalid
- response header lines (<em>i.e.</em> containing no colon) from the origin
- server. The following arguments are possible:</p>
- <dl>
- <dt><code>IsError</code></dt>
- <dd>Abort the request and end up with a 502 (Bad Gateway) response. This is
- the default behaviour.</dd>
+ <p>This example defines two different workers, each using a separate
+ connection pool and configuration.</p>
- <dt><code>Ignore</code></dt>
- <dd>Treat bad header lines as if they weren't sent.</dd>
+ <div class="warning"><h3>Worker Sharing</h3>
+ <p>Worker sharing happens if the worker URLs overlap, which occurs when
+ the URL of some worker is a leading substring of the URL of another
+ worker defined later in the configuration file. In the following example</p>
- <dt><code>StartBody</code></dt>
- <dd>When receiving the first bad header line, finish reading the headers and
- treat the remainder as body. This helps to work around buggy backend servers
- which forget to insert an empty line between the headers and the body.</dd>
- </dl>
+ <pre class="prettyprint lang-config">ProxyPass "/apps" "http://backend.example.com/" timeout=60
+ProxyPass "/examples" "http://backend.example.com/examples" timeout=10</pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyBlock" id="ProxyBlock">ProxyBlock</a> <a name="proxyblock" id="proxyblock">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Words, hosts, or domains that are banned from being
-proxied</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyBlock *|<var>word</var>|<var>host</var>|<var>domain</var>
-[<var>word</var>|<var>host</var>|<var>domain</var>] ...</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>The <code class="directive">ProxyBlock</code> directive specifies a list of
- words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and
- FTP document requests to sites whose names contain matched words,
- hosts or domains are <em>blocked</em> by the proxy server. The proxy
- module will also attempt to determine IP addresses of list items which
- may be hostnames during startup, and cache them for match test as
- well. That may slow down the startup time of the server.</p>
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyBlock "news.example.com" "auctions.example.com" "friends.example.com"</pre>
-</div>
+ <p>the second worker isn't actually created. Instead the first
+ worker is used. The benefit is, that there is only one connection pool,
+ so connections are more often reused. Note that all configuration attributes
+ given explicitly for the later worker will be ignored. This will be logged
+ as a warning. In the above example the resulting timeout value
+ for the URL <code>/examples</code> will be <code>60</code> instead
+ of <code>10</code>!</p>
- <p>Note that <code>example</code> would also be sufficient to match any
- of these sites.</p>
+ <p>If you want to avoid worker sharing, sort your worker definitions
+ by URL length, starting with the longest worker URLs. If you want to maximize
+ worker sharing use the reverse sort order. See also the related warning about
+ ordering <code class="directive"><a href="#proxypass">ProxyPass</a></code> directives.</p>
- <p>Hosts would also be matched if referenced by IP address.</p>
+ </div>
- <p>Note also that</p>
+ <p>Explicitly configured workers come in two flavors:
+ <dfn>direct workers</dfn> and <dfn>(load) balancer workers</dfn>.
+ They support many important configuration attributes which are
+ described below in the <code class="directive"><a href="#proxypass">ProxyPass</a></code>
+ directive. The same attributes can also be set using
+ <code class="directive"><a href="#proxyset">ProxySet</a></code>.</p>
- <pre class="prettyprint lang-config">ProxyBlock "*"</pre>
+ <p>The set of options available for a direct worker
+ depends on the protocol, which is specified in the origin server URL.
+ Available protocols include <code>ajp</code>, <code>fcgi</code>,
+ <code>ftp</code>, <code>http</code> and <code>scgi</code>.</p>
+ <p>Balancer workers are virtual workers that use direct workers known
+ as their members to actually handle the requests. Each balancer can
+ have multiple members. When it handles a request, it chooses a member
+ based on the configured load balancing algorithm.</p>
- <p>blocks connections to all sites.</p>
+ <p>A balancer worker is created if its worker URL uses
+ <code>balancer</code> as the protocol scheme.
+ The balancer URL uniquely identifies the balancer worker.
+ Members are added to a balancer using
+ <code class="directive"><a href="#balancermember">BalancerMember</a></code>.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyDomain" id="ProxyDomain">ProxyDomain</a> <a name="proxydomain" id="proxydomain">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Default domain name for proxied requests</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyDomain <var>Domain</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>This directive is only useful for Apache httpd proxy servers within
- intranets. The <code class="directive">ProxyDomain</code> directive specifies
- the default domain which the apache proxy server will belong to. If a
- request to a host without a domain name is encountered, a redirection
- response to the same host with the configured <var>Domain</var> appended
- will be generated.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="access" id="access">Controlling access to your proxy</a></h2>
+ <p>You can control who can access your proxy via the <code class="directive"><a href="#proxy"><Proxy></a></code> control block as in
+ the following example:</p>
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"> ProxyRemote "*" "http://firewall.example.com:81"<br />
- NoProxy ".example.com" "192.168.112.0/21"<br />
- ProxyDomain ".example.com"</pre>
-</div>
+ <pre class="prettyprint lang-config"><Proxy "*">
+ Require ip 192.168.0
+</Proxy></pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyErrorOverride" id="ProxyErrorOverride">ProxyErrorOverride</a> <a name="proxyerroroverride" id="proxyerroroverride">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Override error pages for proxied content</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyErrorOverride On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyErrorOverride Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>This directive is useful for reverse-proxy setups, where you want to
- have a common look and feel on the error pages seen by the end user.
- This also allows for included files (via
- <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>'s SSI) to get
- the error code and act accordingly (default behavior would display
- the error page of the proxied server, turning this on shows the SSI
- Error message).</p>
- <p>This directive does not affect the processing of informational (1xx),
- normal success (2xx), or redirect (3xx) responses.</p>
+ <p>For more information on access control directives, see
+ <code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code>.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyIOBufferSize" id="ProxyIOBufferSize">ProxyIOBufferSize</a> <a name="proxyiobuffersize" id="proxyiobuffersize">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determine size of internal data throughput buffer</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyIOBufferSize <var>bytes</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyIOBufferSize 8192</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>The <code class="directive">ProxyIOBufferSize</code> directive adjusts the size
- of the internal buffer, which is used as a scratchpad for the data between
- input and output. The size must be at least <code>512</code>.</p>
+ <p>Strictly limiting access is essential if you are using a
+ forward proxy (using the <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive).
+ Otherwise, your server can be used by any client to access
+ arbitrary hosts while hiding his or her true identity. This is
+ dangerous both for your network and for the Internet at large.
+ When using a reverse proxy (using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive with
+ <code>ProxyRequests Off</code>), access control is less
+ critical because clients can only contact the hosts that you
+ have specifically configured.</p>
- <p>In almost every case there's no reason to change that value.</p>
+ <p><strong>See Also</strong> the <a href="mod_proxy_http.html#env">Proxy-Chain-Auth</a> environment variable.</p>
- <p>If used with AJP this directive sets the maximum AJP packet size in
- bytes. Values larger than 65536 are set to 65536. If you change it from
- the default, you must also change the <code>packetSize</code> attribute of
- your AJP connector on the Tomcat side! The attribute
- <code>packetSize</code> is only available in Tomcat <code>5.5.20+</code>
- and <code>6.0.2+</code></p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="startup" id="startup">Slow Startup</a></h2>
+ <p>If you're using the <code class="directive"><a href="#proxyblock">ProxyBlock</a></code> directive, hostnames' IP addresses are looked up
+ and cached during startup for later match test. This may take a few
+ seconds (or more) depending on the speed with which the hostname lookups
+ occur.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="intranet" id="intranet">Intranet Proxy</a></h2>
+ <p>An Apache httpd proxy server situated in an intranet needs to forward
+ external requests through the company's firewall (for this, configure
+ the <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> directive
+ to forward the respective <var>scheme</var> to the firewall proxy).
+ However, when it has to
+ access resources within the intranet, it can bypass the firewall when
+ accessing hosts. The <code class="directive"><a href="#noproxy">NoProxy</a></code>
+ directive is useful for specifying which hosts belong to the intranet and
+ should be accessed directly.</p>
- <p>Normally it is not necessary to change the maximum packet size.
- Problems with the default value have been reported when sending
- certificates or certificate chains.</p>
+ <p>Users within an intranet tend to omit the local domain name from their
+ WWW requests, thus requesting "http://somehost/" instead of
+ <code>http://somehost.example.com/</code>. Some commercial proxy servers
+ let them get away with this and simply serve the request, implying a
+ configured local domain. When the <code class="directive"><a href="#proxydomain">ProxyDomain</a></code> directive is used and the server is <a href="#proxyrequests">configured for proxy service</a>, Apache httpd can return
+ a redirect response and send the client to the correct, fully qualified,
+ server address. This is the preferred method since the user's bookmark
+ files will then contain fully qualified hosts.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="envsettings" id="envsettings">Protocol Adjustments</a></h2>
+ <p>For circumstances where <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> is sending
+ requests to an origin server that doesn't properly implement
+ keepalives or HTTP/1.1, there are two <a href="../env.html">environment variables</a> that can force the
+ request to use HTTP/1.0 with no keepalive. These are set via the
+ <code class="directive"><a href="../mod/mod_env.html#setenv">SetEnv</a></code> directive.</p>
+
+ <p>These are the <code>force-proxy-request-1.0</code> and
+ <code>proxy-nokeepalive</code> notes.</p>
+
+ <pre class="prettyprint lang-config"><Location "/buggyappserver/">
+ ProxyPass "http://buggyappserver:7001/foo/"
+ SetEnv force-proxy-request-1.0 1
+ SetEnv proxy-nokeepalive 1
+</Location></pre>
-</div>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="request-bodies" id="request-bodies">Request Bodies</a></h2>
+
+ <p>Some request methods such as POST include a request body.
+ The HTTP protocol requires that requests which include a body
+ either use chunked transfer encoding or send a
+ <code>Content-Length</code> request header. When passing these
+ requests on to the origin server, <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>
+ will always attempt to send the <code>Content-Length</code>. But
+ if the body is large and the original request used chunked
+ encoding, then chunked encoding may also be used in the upstream
+ request. You can control this selection using <a href="../env.html">environment variables</a>. Setting
+ <code>proxy-sendcl</code> ensures maximum compatibility with
+ upstream servers by always sending the
+ <code>Content-Length</code>, while setting
+ <code>proxy-sendchunked</code> minimizes resource usage by using
+ chunked encoding.</p>
+
+ <p>Under some circumstances, the server must spool request bodies
+ to disk to satisfy the requested handling of request bodies. For
+ example, this spooling will occur if the original body was sent with
+ chunked encoding (and is large), but the administrator has
+ asked for backend requests to be sent with Content-Length or as HTTP/1.0.
+ This spooling can also occur if the request body already has a
+ Content-Length header, but the server is configured to filter incoming
+ request bodies.</p>
+
+ <p><code class="directive"><a href="../mod/core.html#limitrequestbody">LimitRequestBody</a></code> only applies to
+ request bodies that the server will spool to disk</p>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="x-headers" id="x-headers">Reverse Proxy Request Headers</a></h2>
+
+ <p>When acting in a reverse-proxy mode (using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive, for example),
+ <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> adds several request headers in
+ order to pass information to the origin server. These headers
+ are:</p>
+
+ <dl>
+ <dt><code>X-Forwarded-For</code></dt>
+ <dd>The IP address of the client.</dd>
+ <dt><code>X-Forwarded-Host</code></dt>
+ <dd>The original host requested by the client in the <code>Host</code>
+ HTTP request header.</dd>
+ <dt><code>X-Forwarded-Server</code></dt>
+ <dd>The hostname of the proxy server.</dd>
+ </dl>
+
+ <p>Be careful when using these headers on the origin server, since
+ they will contain more than one (comma-separated) value if the
+ original request already contained one of these headers. For
+ example, you can use <code>%{X-Forwarded-For}i</code> in the log
+ format string of the origin server to log the original clients IP
+ address, but you may get more than one address if the request
+ passes through several proxies.</p>
+
+ <p>See also the <code class="directive"><a href="#proxypreservehost">ProxyPreserveHost</a></code> and <code class="directive"><a href="#proxyvia">ProxyVia</a></code> directives, which control
+ other request headers.</p>
+
+ <p>Note: If you need to specify custom request headers to be
+ added to the forwarded request, use the
+ <code class="directive"><a href="../mod/mod_headers.html#requestheader">RequestHeader</a></code>
+ directive.</p>
+
+ </div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyMatch" id="ProxyMatch"><ProxyMatch></a> <a name="proxymatch" id="proxymatch">Directive</a></h2>
+<div class="directive-section"><h2><a name="BalancerGrowth" id="BalancerGrowth">BalancerGrowth</a> <a name="balancergrowth" id="balancergrowth">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Container for directives applied to regular-expression-matched
-proxied resources</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><ProxyMatch <var>regex</var>> ...</ProxyMatch></code></td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of additional Balancers that can be added Post-configuration</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerGrowth <var>#</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerGrowth 5</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerGrowth is only available in Apache HTTP Server 2.3.13
+ and later.</td></tr>
</table>
- <p>The <code class="directive"><ProxyMatch></code> directive is
- identical to the <code class="directive"><a href="#proxy"><Proxy></a></code> directive, except it matches URLs
- using <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expressions</a>.</p>
-
- <p>From 2.4.8 onwards, named groups and backreferences are captured and
- written to the environment with the corresponding name prefixed with
- "MATCH_" and in upper case. This allows elements of URLs to be referenced
- from within <a href="../expr.html">expressions</a> and modules like
- <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. In order to prevent confusion, numbered
- (unnamed) backreferences are ignored. Use named groups instead.</p>
-
-<pre class="prettyprint lang-config"><ProxyMatch "^http://(?<sitename>[^/]+)">
- Require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
-</ProxyMatch></pre>
-
+ <p>This directive allows for growth potential in the number of
+ Balancers available for a virtualhost in addition to the
+ number pre-configured. It only takes effect if there is at
+ least 1 pre-configured Balancer.</p>
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="#proxy"><Proxy></a></code></li>
-</ul>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyMaxForwards" id="ProxyMaxForwards">ProxyMaxForwards</a> <a name="proxymaxforwards" id="proxymaxforwards">Directive</a></h2>
+<div class="directive-section"><h2><a name="BalancerInherit" id="BalancerInherit">BalancerInherit</a> <a name="balancerinherit" id="balancerinherit">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximium number of proxies that a request can be forwarded
-through</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyMaxForwards <var>number</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyMaxForwards -1</code></td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Inherit ProxyPassed Balancers/Workers from the main server</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerInherit On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerInherit On</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Default behaviour changed in 2.2.7</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerInherit is only available in Apache HTTP Server 2.4.5 and later.</td></tr>
</table>
- <p>The <code class="directive">ProxyMaxForwards</code> directive specifies the
- maximum number of proxies through which a request may pass, if there's no
- <code>Max-Forwards</code> header supplied with the request. This may
- be set to prevent infinite proxy loops, or a DoS attack.</p>
-
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyMaxForwards 15</pre>
-</div>
-
- <p>Note that setting <code class="directive">ProxyMaxForwards</code> is a
- violation of the HTTP/1.1 protocol (RFC2616), which forbids a Proxy
- setting <code>Max-Forwards</code> if the Client didn't set it.
- Earlier Apache httpd versions would always set it. A negative
- <code class="directive">ProxyMaxForwards</code> value, including the
- default -1, gives you protocol-compliant behaviour, but may
- leave you open to loops.</p>
-
+ <p>This directive will cause the current server/vhost to "inherit" ProxyPass
+ Balancers and Workers defined in the main server. This can cause issues and
+ inconsistent behavior if using the Balancer Manager and so should be disabled
+ if using that feature.</p>
+ <p>The setting in the global server defines the default for all vhosts.</p>
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyPass" id="ProxyPass">ProxyPass</a> <a name="proxypass" id="proxypass">Directive</a></h2>
+<div class="directive-section"><h2><a name="BalancerMember" id="BalancerMember">BalancerMember</a> <a name="balancermember" id="balancermember">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maps remote servers into the local server URL-space</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPass [<var>path</var>] !|<var>url</var> [<var>key=value</var>
- <var>[key=value</var> ...]] [nocanon] [interpolate] [noquery]</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a member to a load balancing group</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerMember [<var>balancerurl</var>] <var>url</var> [<var>key=value [key=value ...]]</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Unix Domain Socket (UDS) support added in 2.4.7</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerMember is only available in Apache HTTP Server 2.2
+ and later.</td></tr>
</table>
- <p>This directive allows remote servers to be mapped into the
- space of the local server; the local server does not act as a
- proxy in the conventional sense, but appears to be a mirror of the
- remote server. The local server is often called a <dfn>reverse
- proxy</dfn> or <dfn>gateway</dfn>. The <var>path</var> is the name of
- a local virtual path; <var>url</var> is a partial URL for the
- remote server and cannot include a query string.</p>
-
- <div class="note"><strong>Note: </strong>This directive cannot be used within a
- <code><Directory></code> context.</div>
-
- <div class="warning">The <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive should
- usually be set <strong>off</strong> when using
- <code class="directive">ProxyPass</code>.</div>
-
- <p>In 2.4.7 and later, support for using a Unix Domain Socket is available by using a target
- which prepends <code>unix:/path/lis.sock|</code>. For example, to proxy
- HTTP and target the UDS at /home/www/socket you would use
- <code>unix:/home/www.socket|http://localhost/whatever/</code>.</p>
+ <p>This directive adds a member to a load balancing group. It could be used
+ within a <code><Proxy <var>balancer://</var>...></code> container
+ directive, and can take any of the key value pair parameters available to
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> directives.</p>
+ <p>One additional parameter is available only to <code class="directive">BalancerMember</code> directives:
+ <var>loadfactor</var>. This is the member load factor - a number between 1
+ (default) and 100, which defines the weighted load to be applied to the
+ member in question.</p>
+ <p>The <var>balancerurl</var> is only needed when not in
+ <code><Proxy <var>balancer://</var>...></code>
+ container directive. It corresponds to the url of a balancer defined in
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
+ <p>The path component of the balancer URL in any
+ <code><Proxy <var>balancer://</var>...></code> container directive
+ is ignored.</p>
+ <p>Trailing slashes should typically be removed from the URL of a
+ <code class="directive">BalancerMember</code>.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="BalancerPersist" id="BalancerPersist">BalancerPersist</a> <a name="balancerpersist" id="balancerpersist">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Attempt to persist changes made by the Balancer Manager across restarts.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerPersist On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerPersist Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerPersist is only available in Apache HTTP Server 2.4.4 and later.</td></tr>
+</table>
+ <p>This directive will cause the shared memory storage associated
+ with the balancers and balancer members to be persisted across
+ restarts. This allows these local changes to not be lost during the
+ normal restart/graceful state transitions.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="NoProxy" id="NoProxy">NoProxy</a> <a name="noproxy" id="noproxy">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Hosts, domains, or networks that will be connected to
+directly</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>NoProxy <var>host</var> [<var>host</var>] ...</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>This directive is only useful for Apache httpd proxy servers within
+ intranets. The <code class="directive">NoProxy</code> directive specifies a
+ list of subnets, IP addresses, hosts and/or domains, separated by
+ spaces. A request to a host which matches one or more of these is
+ always served directly, without forwarding to the configured
+ <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> proxy server(s).</p>
- <div class="note"><strong>Note:</strong> The path associated with the <code>unix:</code>
- URL is <code class="directive">DefaultRuntimeDir</code> aware.</div>
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyRemote "*" "http://firewall.example.com:81"
+NoProxy ".example.com" "192.168.112.0/21"</pre>
+</div>
- <p>Suppose the local server has address <code>http://example.com/</code>;
- then</p>
+ <p>The <var>host</var> arguments to the <code class="directive">NoProxy</code>
+ directive are one of the following type list:</p>
- <pre class="prettyprint lang-config"><Location "/mirror/foo/">
- ProxyPass "http://backend.example.com/"
-</Location></pre>
+ <dl>
+
+ <dt><var><a name="domain" id="domain">Domain</a></var></dt>
+ <dd>
+ <p>A <dfn>Domain</dfn> is a partially qualified DNS domain name, preceded
+ by a period. It represents a list of hosts which logically belong to the
+ same DNS domain or zone (<em>i.e.</em>, the suffixes of the hostnames are
+ all ending in <var>Domain</var>).</p>
+ <div class="example"><h3>Examples</h3><p><code>
+ .com .example.org.
+ </code></p></div>
- <p>will cause a local request for
- <code>http://example.com/mirror/foo/bar</code> to be internally converted
- into a proxy request to <code>http://backend.example.com/bar</code>.</p>
+ <p>To distinguish <var>Domain</var>s from <var><a href="#hostname">Hostname</a></var>s (both syntactically and semantically; a DNS domain can
+ have a DNS A record, too!), <var>Domain</var>s are always written with a
+ leading period.</p>
- <p>The following alternative syntax is possible, however it can carry a
- performance penalty when present in very large numbers. The advantage of
- the below syntax is that it allows for dynamic control via the
- <a href="mod_proxy_balancer.html#balancer_manager">Balancer Manager</a> interface:</p>
+ <div class="note"><h3>Note</h3>
+ <p>Domain name comparisons are done without regard to the case, and
+ <var>Domain</var>s are always assumed to be anchored in the root of the
+ DNS tree, therefore two domains <code>.ExAmple.com</code> and
+ <code>.example.com.</code> (note the trailing period) are considered
+ equal. Since a domain comparison does not involve a DNS lookup, it is much
+ more efficient than subnet comparison.</p>
+ </div></dd>
- <pre class="prettyprint lang-config">ProxyPass "/mirror/foo/" "http://backend.example.com/"</pre>
+
+ <dt><var><a name="subnet" id="subnet">SubNet</a></var></dt>
+ <dd>
+ <p>A <dfn>SubNet</dfn> is a partially qualified internet address in
+ numeric (dotted quad) form, optionally followed by a slash and the netmask,
+ specified as the number of significant bits in the <var>SubNet</var>. It is
+ used to represent a subnet of hosts which can be reached over a common
+ network interface. In the absence of the explicit net mask it is assumed
+ that omitted (or zero valued) trailing digits specify the mask. (In this
+ case, the netmask can only be multiples of 8 bits wide.) Examples:</p>
+ <dl>
+ <dt><code>192.168</code> or <code>192.168.0.0</code></dt>
+ <dd>the subnet 192.168.0.0 with an implied netmask of 16 valid bits
+ (sometimes used in the netmask form <code>255.255.0.0</code>)</dd>
+ <dt><code>192.168.112.0/21</code></dt>
+ <dd>the subnet <code>192.168.112.0/21</code> with a netmask of 21
+ valid bits (also used in the form <code>255.255.248.0</code>)</dd>
+ </dl>
- <div class="warning">
- <p>If the first argument ends with a trailing <strong>/</strong>, the second
- argument should also end with a trailing <strong>/</strong> and vice
- versa. Otherwise the resulting requests to the backend may miss some
- needed slashes and do not deliver the expected results.
- </p>
- </div>
+ <p>As a degenerate case, a <em>SubNet</em> with 32 valid bits is the
+ equivalent to an <var><a href="#ipaddr">IPAddr</a></var>, while a <var>SubNet</var> with zero
+ valid bits (<em>e.g.</em>, 0.0.0.0/0) is the same as the constant
+ <var>_Default_</var>, matching any IP address.</p></dd>
- <p>The <code>!</code> directive is useful in situations where you don't want
- to reverse-proxy a subdirectory, <em>e.g.</em></p>
+
+ <dt><var><a name="ipaddr" id="ipaddr">IPAddr</a></var></dt>
+ <dd>
+ <p>A <dfn>IPAddr</dfn> represents a fully qualified internet address in
+ numeric (dotted quad) form. Usually, this address represents a host, but
+ there need not necessarily be a DNS domain name connected with the
+ address.</p>
+ <div class="example"><h3>Example</h3><p><code>
+ 192.168.123.7
+ </code></p></div>
- <pre class="prettyprint lang-config"><Location "/mirror/foo/">
- ProxyPass "http://backend.example.com/"
-</Location>
-<Location "/mirror/foo/i">
- ProxyPass "!"
-</Location></pre>
+ <div class="note"><h3>Note</h3>
+ <p>An <var>IPAddr</var> does not need to be resolved by the DNS system, so
+ it can result in more effective apache performance.</p>
+ </div></dd>
+
+ <dt><var><a name="hostname" id="hostname">Hostname</a></var></dt>
+ <dd>
+ <p>A <dfn>Hostname</dfn> is a fully qualified DNS domain name which can
+ be resolved to one or more <var><a href="#ipaddr">IPAddrs</a></var> via the
+ DNS domain name service. It represents a logical host (in contrast to
+ <var><a href="#domain">Domain</a></var>s, see above) and must be resolvable
+ to at least one <var><a href="#ipaddr">IPAddr</a></var> (or often to a list
+ of hosts with different <var><a href="#ipaddr">IPAddr</a></var>s).</p>
- <pre class="prettyprint lang-config">ProxyPass "/mirror/foo/i" "!"
-ProxyPass "/mirror/foo" "http://backend.example.com"</pre>
+ <div class="example"><h3>Examples</h3><p><code>
+ prep.ai.example.edu<br />
+ www.example.org
+ </code></p></div>
+ <div class="note"><h3>Note</h3>
+ <p>In many situations, it is more effective to specify an <var><a href="#ipaddr">IPAddr</a></var> in place of a <var>Hostname</var> since a
+ DNS lookup can be avoided. Name resolution in Apache httpd can take a remarkable
+ deal of time when the connection to the name server uses a slow PPP
+ link.</p>
+ <p><var>Hostname</var> comparisons are done without regard to the case,
+ and <var>Hostname</var>s are always assumed to be anchored in the root
+ of the DNS tree, therefore two hosts <code>WWW.ExAmple.com</code>
+ and <code>www.example.com.</code> (note the trailing period) are
+ considered equal.</p>
+ </div></dd>
+ </dl>
- <p>will proxy all requests to <code>/mirror/foo</code> to
- <code>backend.example.com</code> <em>except</em> requests made to
- <code>/mirror/foo/i</code>.</p>
+<h3>See also</h3>
+<ul>
+<li><a href="../dns-caveats.html">DNS Issues</a></li>
+</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="Proxy" id="Proxy"><Proxy></a> <a name="proxy" id="proxy">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Container for directives applied to proxied resources</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><Proxy <var>wildcard-url</var>> ...</Proxy></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>Directives placed in <code class="directive"><Proxy></code>
+ sections apply only to matching proxied content. Shell-style wildcards are
+ allowed.</p>
- <div class="warning"><h3>Ordering ProxyPass Directives</h3>
- <p>The configured <code class="directive"><a href="#proxypass">ProxyPass</a></code>
- and <code class="directive"><a href="#proxypassmatch">ProxyPassMatch</a></code>
- rules are checked in the order of configuration. The first rule that
- matches wins. So usually you should sort conflicting
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> rules starting with the
- longest URLs first. Otherwise later rules for longer URLS will be hidden
- by any earlier rule which uses a leading substring of the URL. Note that
- there is some relation with worker sharing. In contrast, only one
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive can be placed
- in a <code class="directive"><a href="../mod/core.html#location">Location</a></code> block, and the most
- specific location will take precedence.</p>
+ <p>For example, the following will allow only hosts in
+ <code>yournetwork.example.com</code> to access content via your proxy
+ server:</p>
- <p>For the same reasons exclusions must come <em>before</em> the
- general <code class="directive">ProxyPass</code> directives.</p>
+ <pre class="prettyprint lang-config"><Proxy "*">
+ Require host yournetwork.example.com
+</Proxy></pre>
- </div>
- <p>In Apache HTTP Server 2.1 and later, mod_proxy supports pooled
- connections to a backend server. Connections created on demand
- can be retained in a pool for future use. Limits on the pool size
- and other settings can be coded on
- the <code class="directive">ProxyPass</code> directive
- using <code>key=value</code> parameters, described in the table
- below.</p>
+ <p>The following example will process all files in the <code>foo</code>
+ directory of <code>example.com</code> through the <code>INCLUDES</code>
+ filter when they are sent through the proxy server:</p>
- <p>By default, mod_proxy will allow and retain the maximum number of
- connections that could be used simultaneously by that web server child
- process. Use the <code>max</code> parameter to reduce the number from
- the default. Use the <code>ttl</code> parameter to set an optional
- time to live; connections which have been unused for at least
- <code>ttl</code> seconds will be closed. <code>ttl</code> can be used
- to avoid using a connection which is subject to closing because of the
- backend server's keep-alive timeout.</p>
+ <pre class="prettyprint lang-config"><Proxy "http://example.com/foo/*">
+ SetOutputFilter INCLUDES
+</Proxy></pre>
- <p>The pool of connections is maintained per web server child
- process, and <code>max</code> and other settings are not coordinated
- among all child processes, except when only one child process is allowed
- by configuration or MPM design.</p>
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300</pre>
-</div>
-
- <table class="bordered"><tr><th>BalancerMember parameters</th></tr></table>
- <table>
- <tr><th>Parameter</th>
- <th>Default</th>
- <th>Description</th></tr>
- <tr><td>min</td>
- <td>0</td>
- <td>Minimum number of connection pool entries, unrelated to the
- actual number of connections. This only needs to be modified from the
- default for special circumstances where heap memory associated with the
- backend connections should be preallocated or retained.</td></tr>
- <tr><td>max</td>
- <td>1...n</td>
- <td>Maximum number of connections that will be allowed to the
- backend server. The default for this limit is the number of threads
- per process in the active MPM. In the Prefork MPM, this is always 1,
- while with other MPMs it is controlled by the
- <code class="directive">ThreadsPerChild</code> directive.</td></tr>
- <tr><td>smax</td>
- <td>max</td>
- <td>Retained connection pool entries above this limit are freed
- during certain operations if they have been unused for longer than
- the time to live, controlled by the <code>ttl</code> parameter. If
- the connection pool entry has an associated connection, it will be
- closed. This only needs to be modified from the default for special
- circumstances where connection pool entries and any associated
- connections which have exceeded the time to live need to be freed or
- closed more aggressively.</td></tr>
- <tr><td>acquire</td>
- <td>-</td>
- <td>If set this will be the maximum time to wait for a free
- connection in the connection pool, in milliseconds. If there are no free
- connections in the pool the Apache httpd will return <code>SERVER_BUSY</code>
- status to the client.
- </td></tr>
- <tr><td>connectiontimeout</td>
- <td>timeout</td>
- <td>Connect timeout in seconds.
- The number of seconds Apache httpd waits for the creation of a connection to
- the backend to complete. By adding a postfix of ms the timeout can be
- also set in milliseconds.
- </td></tr>
- <tr><td>disablereuse</td>
- <td>Off</td>
- <td>This parameter should be used when you want to force mod_proxy
- to immediately close a connection to the backend after being used, and
- thus, disable its persistent connection and pool for that backend.
- This helps in various situations where a firewall between Apache
- httpd and
- the backend server (regardless of protocol) tends to silently
- drop connections or when backends themselves may be under round-
- robin DNS. To disable connection pooling reuse,
- set this property value to <code>On</code>.
- </td></tr>
- <tr><td>enablereuse</td>
- <td>On</td>
- <td>This is the inverse of 'disablereuse' above, provided as a
- convenience for scheme handlers that require opt-in for connection
- reuse (such as <code class="module"><a href="../mod/mod_proxy_fcgi.html">mod_proxy_fcgi</a></code>). 2.4.11 and later only.
- </td></tr>
- <tr><td>flushpackets</td>
- <td>off</td>
- <td>Determines whether the proxy module will auto-flush the output
- brigade after each "chunk" of data. 'off' means that it will flush
- only when needed, 'on' means after each chunk is sent and
- 'auto' means poll/wait for a period of time and flush if
- no input has been received for 'flushwait' milliseconds.
- Currently this is in effect only for AJP.
- </td></tr>
- <tr><td>flushwait</td>
- <td>10</td>
- <td>The time to wait for additional input, in milliseconds, before
- flushing the output brigade if 'flushpackets' is 'auto'.
- </td></tr>
- <tr><td>iobuffersize</td>
- <td>8192</td>
- <td>Adjusts the size of the internal scratchpad IO buffer. This allows you
- to override the <code class="directive">ProxyIOBufferSize</code> for a specific worker.
- This must be at least 512 or set to 0 for the system default of 8192.
- </td></tr>
- <tr><td>keepalive</td>
- <td>Off</td>
- <td><p>This parameter should be used when you have a firewall between your
- Apache httpd and the backend server, who tend to drop inactive connections.
- This flag will tell the Operating System to send <code>KEEP_ALIVE</code>
- messages on inactive connections and thus prevent the firewall to drop the connection.
- To enable keepalive set this property value to <code>On</code>. </p>
- <p>The frequency of initial and subsequent TCP keepalive probes
- depends on global OS settings, and may be as high as 2 hours. To be useful,
- the frequency configured in the OS must be smaller than the threshold used
- by the firewall.</p>
- </td></tr>
- <tr><td>lbset</td>
- <td>0</td>
- <td>Sets the load balancer cluster set that the worker is a member
- of. The load balancer will try all members of a lower numbered
- lbset before trying higher numbered ones.
- </td></tr>
- <tr><td>ping</td>
- <td>0</td>
- <td>Ping property tells the webserver to "test" the connection to
- the backend before forwarding the request. For AJP, it causes
- <code class="module"><a href="../mod/mod_proxy_ajp.html">mod_proxy_ajp</a></code>to send a <code>CPING</code>
- request on the ajp13 connection (implemented on Tomcat 3.3.2+, 4.1.28+
- and 5.0.13+). For HTTP, it causes <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>
- to send a <code>100-Continue</code> to the backend (only valid for
- HTTP/1.1 - for non HTTP/1.1 backends, this property has no
- effect). In both cases the parameter is the delay in seconds to wait
- for the reply.
- This feature has been added to avoid problems with hung and
- busy backends.
- This will increase the network traffic during the normal operation
- which could be an issue, but it will lower the
- traffic in case some of the cluster nodes are down or busy.
- By adding a postfix of ms the delay can be also set in
- milliseconds.
- </td></tr>
- <tr><td>receivebuffersize</td>
- <td>0</td>
- <td>Adjusts the size of the explicit (TCP/IP) network buffer size for
- proxied connections. This allows you to override the
- <code class="directive">ProxyReceiveBufferSize</code> for a specific worker.
- This must be at least 512 or set to 0 for the system default.
- </td></tr>
- <tr><td>redirect</td>
- <td>-</td>
- <td>Redirection Route of the worker. This value is usually
- set dynamically to enable safe removal of the node from
- the cluster. If set all requests without session id will be
- redirected to the BalancerMember that has route parameter
- equal as this value.
- </td></tr>
- <tr><td>retry</td>
- <td>60</td>
- <td>Connection pool worker retry timeout in seconds.
- If the connection pool worker to the backend server is in the error state,
- Apache httpd will not forward any requests to that server until the timeout
- expires. This enables to shut down the backend server for maintenance,
- and bring it back online later. A value of 0 means always retry workers
- in an error state with no timeout.
- </td></tr>
- <tr><td>route</td>
- <td>-</td>
- <td>Route of the worker when used inside load balancer.
- The route is a value appended to session id.
- </td></tr>
- <tr><td>status</td>
- <td>-</td>
- <td>Single letter value defining the initial status of
- this worker.
- <table>
- <tr><td>D: Worker is disabled and will not accept any requests.</td></tr>
- <tr><td>S: Worker is administratively stopped.</td></tr>
- <tr><td>I: Worker is in ignore-errors mode, and will always be considered available.</td></tr>
- <tr><td>H: Worker is in hot-standby mode and will only be used if no other
- viable workers are available.</td></tr>
- <tr><td>E: Worker is in an error state.</td></tr>
- <tr><td>N: Worker is in drain mode, and will only accept existing sticky sessions
- destined for itself and ignore all other requests.</td></tr>
- </table>Status
- can be set (which is the default) by prepending with '+' or
- cleared by prepending with '-'.
- Thus, a setting of 'S-E' sets this worker to Stopped and
- clears the in-error flag.
- </td></tr>
- <tr><td>timeout</td>
- <td><code class="directive"><a href="#proxytimeout">ProxyTimeout</a></code></td>
- <td>Connection timeout in seconds.
- The number of seconds Apache httpd waits for data sent by / to the backend.
- </td></tr>
- <tr><td>ttl</td>
- <td>-</td>
- <td>Time to live for inactive connections and associated connection
- pool entries, in seconds. Once reaching this limit, a
- connection will not be used again; it will be closed at some
- later time.
- </td></tr>
-
- </table>
-
- <p>If the Proxy directive scheme starts with the
- <code>balancer://</code> (eg: <code>balancer://cluster</code>,
- any path information is ignored) then a virtual worker that does not really
- communicate with the backend server will be created. Instead it is responsible
- for the management of several "real" workers. In that case the special set of
- parameters can be add to this virtual worker. See <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>
- for more information about how the balancer works.
- </p>
- <table class="bordered"><tr><th>Balancer parameters</th></tr></table>
- <table>
- <tr><th>Parameter</th>
- <th>Default</th>
- <th>Description</th></tr>
- <tr><td>lbmethod</td>
- <td>byrequests</td>
- <td>Balancer load-balance method. Select the load-balancing scheduler
- method to use. Either <code>byrequests</code>, to perform weighted
- request counting, <code>bytraffic</code>, to perform weighted
- traffic byte count balancing, or <code>bybusyness</code>, to perform
- pending request balancing. Default is <code>byrequests</code>.
- </td></tr>
- <tr><td>maxattempts</td>
- <td>One less than the number of workers, or 1 with a single worker.</td>
- <td>Maximum number of failover attempts before giving up.
- </td></tr>
- <tr><td>nofailover</td>
- <td>Off</td>
- <td>If set to <code>On</code> the session will break if the worker is in
- error state or disabled. Set this value to On if backend servers do not
- support session replication.
- </td></tr>
- <tr><td>stickysession</td>
- <td>-</td>
- <td>Balancer sticky session name. The value is usually set to something
- like <code>JSESSIONID</code> or <code>PHPSESSIONID</code>,
- and it depends on the backend application server that support sessions.
- If the backend application server uses different name for cookies
- and url encoded id (like servlet containers) use | to to separate them.
- The first part is for the cookie the second for the path.<br />
- Available in Apache HTTP Server 2.4.4 and later.
- </td></tr>
- <tr><td>stickysessionsep</td>
- <td>"."</td>
- <td>Sets the separation symbol in the session cookie. Some backend application servers
- do not use the '.' as the symbol. For example the Oracle Weblogic server uses
- '!'. The correct symbol can be set using this option. The setting of 'Off'
- signifies that no symbol is used.
- </td></tr>
- <tr><td>scolonpathdelim</td>
- <td>Off</td>
- <td>If set to <code>On</code> the semi-colon character ';' will be
- used as an additional sticky session path delimiter/separator. This
- is mainly used to emulate mod_jk's behavior when dealing with paths such
- as <code>JSESSIONID=6736bcf34;foo=aabfa</code>
- </td></tr>
- <tr><td>timeout</td>
- <td>0</td>
- <td>Balancer timeout in seconds. If set this will be the maximum time
- to wait for a free worker. Default is not to wait.
- </td></tr>
- <tr><td>failonstatus</td>
- <td>-</td>
- <td>A single or comma-separated list of HTTP status codes. If set this will
- force the worker into error state when the backend returns any status code
- in the list. Worker recovery behaves the same as other worker errors.
- </td></tr>
- <tr><td>failontimeout</td>
- <td>Off</td>
- <td>If set, an IO read timeout after a request is sent to the backend will
- force the worker into error state. Worker recovery behaves the same as other
- worker errors.<br />
- Available in Apache HTTP Server 2.4.5 and later.
- </td></tr>
- <tr><td>nonce</td>
- <td><auto></td>
- <td>The protective nonce used in the <code>balancer-manager</code> application page.
- The default is to use an automatically determined UUID-based
- nonce, to provide for further protection for the page. If set,
- then the nonce is set to that value. A setting of <code>None</code>
- disables all nonce checking.
- <div class="note"><h3>Note</h3>
- <p>In addition to the nonce, the <code>balancer-manager</code> page
- should be protected via an ACL.</p>
- </div>
- </td></tr>
- <tr><td>growth</td>
- <td>0</td>
- <td>Number of additional BalancerMembers to allow to be added
- to this balancer in addition to those defined at configuration.
- </td></tr>
- <tr><td>forcerecovery</td>
- <td>On</td>
- <td>Force the immediate recovery of all workers without considering the
- retry parameter of the workers if all workers of a balancer are
- in error state. There might be cases where an already overloaded backend
- can get into deeper trouble if the recovery of all workers is enforced
- without considering the retry parameter of each worker. In this case
- set to <code>Off</code>.<br />
- Available in Apache HTTP Server 2.4.2 and later.
- </td></tr>
-
- </table>
- <p>A sample balancer setup</p>
- <pre class="prettyprint lang-config">ProxyPass "/special-area" "http://special.example.com" smax=5 max=10
-ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofailover=On
-<Proxy "balancer://mycluster">
- BalancerMember "ajp://1.2.3.4:8009"
- BalancerMember "ajp://1.2.3.5:8009" loadfactor=20
- # Less powerful server, don't send as many requests there,
- BalancerMember "ajp://1.2.3.6:8009" loadfactor=5
-</Proxy></pre>
-
-
- <p>Setting up a hot-standby, that will only be used if no other
- members are available</p>
- <pre class="prettyprint lang-config">ProxyPass "/" "balancer://hotcluster/"
-<Proxy "balancer://hotcluster">
- BalancerMember "ajp://1.2.3.4:8009" loadfactor=1
- BalancerMember "ajp://1.2.3.5:8009" loadfactor=2
- # The server below is on hot standby
- BalancerMember "ajp://1.2.3.6:8009" status=+H
- ProxySet lbmethod=bytraffic
-</Proxy></pre>
-
-
- <p>Normally, mod_proxy will canonicalise ProxyPassed URLs.
- But this may be incompatible with some backends, particularly those
- that make use of <var>PATH_INFO</var>. The optional <var>nocanon</var>
- keyword suppresses this, and passes the URL path "raw" to the
- backend. Note that may affect the security of your backend, as it
- removes the normal limited protection against URL-based attacks
- provided by the proxy.</p>
-
- <p>Normally, mod_proxy will include the query string when
- generating the <var>SCRIPT_FILENAME</var> environment variable.
- The optional <var>noquery</var> keyword (available in
- httpd 2.4.1 and later) prevents this.</p>
-
- <p>When used inside a <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section, the first argument is omitted and the local
- directory is obtained from the <code class="directive"><a href="../mod/core.html#location"><Location></a></code>. The same will occur inside a
- <code class="directive"><a href="../mod/core.html#locationmatch"><LocationMatch></a></code> section,
- however ProxyPass does not interpret the regexp as such, so it is necessary
- to use <code class="directive">ProxyPassMatch</code> in this situation instead.</p>
-
- <p>This directive is not supported in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> or <code class="directive"><a href="../mod/core.html#files"><Files></a></code> sections.</p>
-
- <p>If you require a more flexible reverse-proxy configuration, see the
- <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive with the
- <code>[P]</code> flag.</p>
-
- <p>The optional <var>interpolate</var> keyword, in combination with
- <code class="directive">ProxyPassInterpolateEnv</code> causes the ProxyPass
- to interpolate environment variables, using the syntax
- <var>${VARNAME}</var>. Note that many of the standard CGI-derived
- environment variables will not exist when this interpolation happens,
- so you may still have to resort to <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
- for complex rules. Also note that interpolation is not supported
- within the scheme portion of a URL. Dynamic determination of the
- scheme can be accomplished with <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> as in the
- following example.</p>
-
- <pre class="prettyprint lang-config">RewriteEngine On
-
-RewriteCond "%{HTTPS}" =off
-RewriteRule "." "-" [E=protocol:http]
-RewriteCond "%{HTTPS}" =on
-RewriteRule "." "-" [E=protocol:https]
-
-RewriteRule "^/mirror/foo/(.*)" "%{ENV:protocol}://backend.example.com/$1" [P]
-ProxyPassReverse "/mirror/foo/" "http://backend.example.com/"
-ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"</pre>
+ <div class="note"><h3>Differences from the Location configuration section</h3>
+ <p>A backend URL matches the configuration section if it begins with the
+ the <var>wildcard-url</var> string, even if the last path segment in the
+ directive only matches a prefix of the backend URL. For example,
+ <Proxy "http://example.com/foo"> matches all of
+ http://example.com/foo, http://example.com/foo/bar, and
+ http://example.com/foobar. The matching of the final URL differs
+ from the behavior of the <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section, which for purposes of this note
+ treats the final path component as if it ended in a slash.</p>
+ <p>For more control over the matching, see <code class="directive"><ProxyMatch></code>.</p>
+ </div>
+<h3>See also</h3>
+<ul>
+<li><code class="directive"><a href="#proxymatch"><ProxyMatch></a></code></li>
+</ul>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyPassInherit" id="ProxyPassInherit">ProxyPassInherit</a> <a name="proxypassinherit" id="proxypassinherit">Directive</a></h2>
+<div class="directive-section"><h2><a name="ProxyAddHeaders" id="ProxyAddHeaders">ProxyAddHeaders</a> <a name="proxyaddheaders" id="proxyaddheaders">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Inherit ProxyPass directives defined from the main server</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassInherit On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyPassInherit On</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add proxy information in X-Forwarded-* headers</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyAddHeaders Off|On</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyAddHeaders On</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>ProxyPassInherit is only available in Apache HTTP Server 2.4.5 and later.
- and later.</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.10 and later</td></tr>
</table>
- <p>This directive will cause the current server/vhost to "inherit"
- <code class="directive"><a href="#proxypass">ProxyPass</a></code>
- directives defined in the main server. This can cause issues and
- inconsistent behavior if using the Balancer Manager for dynamic changes
- and so should be disabled if using that feature.</p>
- <p>The setting in the global server defines the default for all vhosts.</p>
- <p>Disabling ProxyPassInherit also disables <code class="directive"><a href="#balancerinherit">BalancerInherit</a></code>.</p>
-
+ <p>This directive determines whether or not proxy related information should be passed to the
+ backend server through X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Server HTTP headers.</p>
+ <div class="note"><h3>Effectiveness</h3>
+ <p>This option is of use only for HTTP proxying, as handled by <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>.</p>
+ </div>
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyPassInterpolateEnv" id="ProxyPassInterpolateEnv">ProxyPassInterpolateEnv</a> <a name="proxypassinterpolateenv" id="proxypassinterpolateenv">Directive</a></h2>
+<div class="directive-section"><h2><a name="ProxyBadHeader" id="ProxyBadHeader">ProxyBadHeader</a> <a name="proxybadheader" id="proxybadheader">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable Environment Variable interpolation in Reverse Proxy configurations</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassInterpolateEnv On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyPassInterpolateEnv Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines how to handle bad header lines in a
+response</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyBadHeader IsError|Ignore|StartBody</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyBadHeader IsError</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.2.9 and later</td></tr>
</table>
- <p>This directive, together with the <var>interpolate</var> argument to
- <code class="directive">ProxyPass</code>, <code class="directive">ProxyPassReverse</code>,
- <code class="directive">ProxyPassReverseCookieDomain</code> and
- <code class="directive">ProxyPassReverseCookiePath</code>
- enables reverse proxies to be dynamically
- configured using environment variables, which may be set by
- another module such as <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.
- It affects the <code class="directive">ProxyPass</code>,
- <code class="directive">ProxyPassReverse</code>,
- <code class="directive">ProxyPassReverseCookieDomain</code>, and
- <code class="directive">ProxyPassReverseCookiePath</code> directives,
- and causes them to substitute the value of an environment
- variable <code>varname</code> for the string <code>${varname}</code>
- in configuration directives (if the <var>interpolate</var> option is set).</p>
- <p>Keep this turned off (for server performance) unless you need it!</p>
+ <p>The <code class="directive">ProxyBadHeader</code> directive determines the
+ behaviour of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> if it receives syntactically invalid
+ response header lines (<em>i.e.</em> containing no colon) from the origin
+ server. The following arguments are possible:</p>
+
+ <dl>
+ <dt><code>IsError</code></dt>
+ <dd>Abort the request and end up with a 502 (Bad Gateway) response. This is
+ the default behaviour.</dd>
+
+ <dt><code>Ignore</code></dt>
+ <dd>Treat bad header lines as if they weren't sent.</dd>
+
+ <dt><code>StartBody</code></dt>
+ <dd>When receiving the first bad header line, finish reading the headers and
+ treat the remainder as body. This helps to work around buggy backend servers
+ which forget to insert an empty line between the headers and the body.</dd>
+ </dl>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyPassMatch" id="ProxyPassMatch">ProxyPassMatch</a> <a name="proxypassmatch" id="proxypassmatch">Directive</a></h2>
+<div class="directive-section"><h2><a name="ProxyBlock" id="ProxyBlock">ProxyBlock</a> <a name="proxyblock" id="proxyblock">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maps remote servers into the local server URL-space using regular expressions</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassMatch [<var>regex</var>] !|<var>url</var> [<var>key=value</var>
- <var>[key=value</var> ...]]</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Words, hosts, or domains that are banned from being
+proxied</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyBlock *|<var>word</var>|<var>host</var>|<var>domain</var>
+[<var>word</var>|<var>host</var>|<var>domain</var>] ...</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
</table>
- <p>This directive is equivalent to <code class="directive"><a href="#proxypass">ProxyPass</a></code>,
- but makes use of regular expressions, instead of simple prefix matching. The
- supplied regular expression is matched against the <var>url</var>, and if it
- matches, the server will substitute any parenthesized matches into the given
- string and use it as a new <var>url</var>.</p>
-
- <div class="note"><strong>Note: </strong>This directive cannot be used within a
- <code><Directory></code> context.</div>
-
- <p>Suppose the local server has address <code>http://example.com/</code>;
- then</p>
+ <p>The <code class="directive">ProxyBlock</code> directive specifies a list of
+ words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and
+ FTP document requests to sites whose names contain matched words,
+ hosts or domains are <em>blocked</em> by the proxy server. The proxy
+ module will also attempt to determine IP addresses of list items which
+ may be hostnames during startup, and cache them for match test as
+ well. That may slow down the startup time of the server.</p>
- <pre class="prettyprint lang-config">ProxyPassMatch "^/(.*\.gif)$" "http://backend.example.com/$1"</pre>
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyBlock "news.example.com" "auctions.example.com" "friends.example.com"</pre>
+</div>
+ <p>Note that <code>example</code> would also be sufficient to match any
+ of these sites.</p>
- <p>will cause a local request for
- <code>http://example.com/foo/bar.gif</code> to be internally converted
- into a proxy request to <code>http://backend.example.com/foo/bar.gif</code>.</p>
- <div class="note"><h3>Note</h3>
- <p>The URL argument must be parsable as a URL <em>before</em> regexp
- substitutions (as well as after). This limits the matches you can use.
- For instance, if we had used</p>
- <pre class="prettyprint lang-config">ProxyPassMatch "^(/.*\.gif)$" "http://backend.example.com:8000$1"</pre>
+ <p>Hosts would also be matched if referenced by IP address.</p>
- <p>in our previous example, it would fail with a syntax error
- at server startup. This is a bug (PR 46665 in the ASF bugzilla),
- and the workaround is to reformulate the match:</p>
- <pre class="prettyprint lang-config">ProxyPassMatch "^/(.*\.gif)$" "http://backend.example.com:8000/$1"</pre>
+ <p>Note also that</p>
- </div>
- <p>The <code>!</code> directive is useful in situations where you don't want
- to reverse-proxy a subdirectory.</p>
+ <pre class="prettyprint lang-config">ProxyBlock "*"</pre>
- <p>When used inside a <code class="directive"><a href="../mod/core.html#locationmatch"><LocationMatch></a></code> section, the first argument is omitted and the
- regexp is obtained from the <code class="directive"><a href="../mod/core.html#locationmatch"><LocationMatch></a></code>.</p>
- <p>If you require a more flexible reverse-proxy configuration, see the
- <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive with the
- <code>[P]</code> flag.</p>
+ <p>blocks connections to all sites.</p>
- <div class="note">
- <h3>Default Substitution</h3>
- <p>When the URL parameter doesn't use any backreferences into the regular
- expression, the original URL will be appended to the URL parameter.
- </p>
- </div>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyDomain" id="ProxyDomain">ProxyDomain</a> <a name="proxydomain" id="proxydomain">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Default domain name for proxied requests</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyDomain <var>Domain</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>This directive is only useful for Apache httpd proxy servers within
+ intranets. The <code class="directive">ProxyDomain</code> directive specifies
+ the default domain which the apache proxy server will belong to. If a
+ request to a host without a domain name is encountered, a redirection
+ response to the same host with the configured <var>Domain</var> appended
+ will be generated.</p>
- <div class="warning">
- <h3>Security Warning</h3>
- <p>Take care when constructing the target URL of the rule, considering
- the security impact from allowing the client influence over the set of
- URLs to which your server will act as a proxy. Ensure that the scheme
- and hostname part of the URL is either fixed, or does not allow the
- client undue influence.</p>
- </div>
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"> ProxyRemote "*" "http://firewall.example.com:81"<br />
+ NoProxy ".example.com" "192.168.112.0/21"<br />
+ ProxyDomain ".example.com"</pre>
+</div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyPassReverse" id="ProxyPassReverse">ProxyPassReverse</a> <a name="proxypassreverse" id="proxypassreverse">Directive</a></h2>
+<div class="directive-section"><h2><a name="ProxyErrorOverride" id="ProxyErrorOverride">ProxyErrorOverride</a> <a name="proxyerroroverride" id="proxyerroroverride">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the URL in HTTP response headers sent from a reverse
-proxied server</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverse [<var>path</var>] <var>url</var>
-[<var>interpolate</var>]</code></td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Override error pages for proxied content</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyErrorOverride On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyErrorOverride Off</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
</table>
- <p>This directive lets Apache httpd adjust the URL in the <code>Location</code>,
- <code>Content-Location</code> and <code>URI</code> headers on HTTP
- redirect responses. This is essential when Apache httpd is used as a
- reverse proxy (or gateway) to avoid by-passing the reverse proxy
- because of HTTP redirects on the backend servers which stay behind
- the reverse proxy.</p>
-
- <p>Only the HTTP response headers specifically mentioned above
- will be rewritten. Apache httpd will not rewrite other response
- headers, nor will it by default rewrite URL references inside HTML pages.
- This means that if the proxied content contains absolute URL
- references, they will by-pass the proxy. To rewrite HTML content to
- match the proxy, you must load and enable <code class="module"><a href="../mod/mod_proxy_html.html">mod_proxy_html</a></code>.
- </p>
-
- <p><var>path</var> is the name of a local virtual path. <var>url</var> is a
- partial URL for the remote server - the same way they are used for the
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
-
- <p>For example, suppose the local server has address
- <code>http://example.com/</code>; then</p>
-
- <pre class="prettyprint lang-config">ProxyPass "/mirror/foo/" "http://backend.example.com/"
-ProxyPassReverse "/mirror/foo/" "http://backend.example.com/"
-ProxyPassReverseCookieDomain "backend.example.com" "public.example.com"
-ProxyPassReverseCookiePath "/" "/mirror/foo/"</pre>
+ <p>This directive is useful for reverse-proxy setups, where you want to
+ have a common look and feel on the error pages seen by the end user.
+ This also allows for included files (via
+ <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>'s SSI) to get
+ the error code and act accordingly (default behavior would display
+ the error page of the proxied server, turning this on shows the SSI
+ Error message).</p>
+ <p>This directive does not affect the processing of informational (1xx),
+ normal success (2xx), or redirect (3xx) responses.</p>
- <p>will not only cause a local request for the
- <code>http://example.com/mirror/foo/bar</code> to be internally converted
- into a proxy request to <code>http://backend.example.com/bar</code>
- (the functionality <code>ProxyPass</code> provides here). It also takes care
- of redirects the server <code>backend.example.com</code> sends: when
- <code>http://backend.example.com/bar</code> is redirected by him to
- <code>http://backend.example.com/quux</code> Apache httpd adjusts this to
- <code>http://example.com/mirror/foo/quux</code> before forwarding the HTTP
- redirect response to the client. Note that the hostname used for
- constructing the URL is chosen in respect to the setting of the <code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code> directive.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyIOBufferSize" id="ProxyIOBufferSize">ProxyIOBufferSize</a> <a name="proxyiobuffersize" id="proxyiobuffersize">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determine size of internal data throughput buffer</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyIOBufferSize <var>bytes</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyIOBufferSize 8192</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>The <code class="directive">ProxyIOBufferSize</code> directive adjusts the size
+ of the internal buffer, which is used as a scratchpad for the data between
+ input and output. The size must be at least <code>512</code>.</p>
- <p>Note that this <code class="directive">ProxyPassReverse</code> directive can
- also be used in conjunction with the proxy pass-through feature
- (<code>RewriteRule ... [P]</code>) from <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
- because it doesn't depend on a corresponding <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
+ <p>In almost every case there's no reason to change that value.</p>
- <p>The optional <var>interpolate</var> keyword, used together with
- <code class="directive">ProxyPassInterpolateEnv</code>, enables interpolation
- of environment variables specified using the format <var>${VARNAME}</var>.
- Note that interpolation is not supported within the scheme portion of a
- URL.</p>
+ <p>If used with AJP this directive sets the maximum AJP packet size in
+ bytes. Values larger than 65536 are set to 65536. If you change it from
+ the default, you must also change the <code>packetSize</code> attribute of
+ your AJP connector on the Tomcat side! The attribute
+ <code>packetSize</code> is only available in Tomcat <code>5.5.20+</code>
+ and <code>6.0.2+</code></p>
- <p>When used inside a <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section, the first argument is omitted and the local
- directory is obtained from the <code class="directive"><a href="../mod/core.html#location"><Location></a></code>. The same occurs inside a <code class="directive"><a href="../mod/core.html#locationmatch"><LocationMatch></a></code> section, but will probably not work as
- intended, as ProxyPassReverse will interpret the regexp literally as a
- path; if needed in this situation, specify the ProxyPassReverse outside
- the section, or in a separate <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section.</p>
+ <p>Normally it is not necessary to change the maximum packet size.
+ Problems with the default value have been reported when sending
+ certificates or certificate chains.</p>
- <p>This directive is not supported in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> or <code class="directive"><a href="../mod/core.html#files"><Files></a></code> sections.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyPassReverseCookieDomain" id="ProxyPassReverseCookieDomain">ProxyPassReverseCookieDomain</a> <a name="proxypassreversecookiedomain" id="proxypassreversecookiedomain">Directive</a></h2>
+<div class="directive-section"><h2><a name="ProxyMatch" id="ProxyMatch"><ProxyMatch></a> <a name="proxymatch" id="proxymatch">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the Domain string in Set-Cookie headers from a reverse-
-proxied server</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookieDomain <var>internal-domain</var>
-<var>public-domain</var> [<var>interpolate</var>]</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Container for directives applied to regular-expression-matched
+proxied resources</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><ProxyMatch <var>regex</var>> ...</ProxyMatch></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
</table>
-<p>Usage is basically similar to
-<code class="directive"><a href="#proxypassreverse">ProxyPassReverse</a></code>, but instead of
-rewriting headers that are a URL, this rewrites the <code>domain</code>
-string in <code>Set-Cookie</code> headers.</p>
+ <p>The <code class="directive"><ProxyMatch></code> directive is
+ identical to the <code class="directive"><a href="#proxy"><Proxy></a></code> directive, except it matches URLs
+ using <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expressions</a>.</p>
+
+ <p>From 2.4.8 onwards, named groups and backreferences are captured and
+ written to the environment with the corresponding name prefixed with
+ "MATCH_" and in upper case. This allows elements of URLs to be referenced
+ from within <a href="../expr.html">expressions</a> and modules like
+ <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. In order to prevent confusion, numbered
+ (unnamed) backreferences are ignored. Use named groups instead.</p>
+<pre class="prettyprint lang-config"><ProxyMatch "^http://(?<sitename>[^/]+)">
+ Require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
+</ProxyMatch></pre>
+
+
+<h3>See also</h3>
+<ul>
+<li><code class="directive"><a href="#proxy"><Proxy></a></code></li>
+</ul>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyPassReverseCookiePath" id="ProxyPassReverseCookiePath">ProxyPassReverseCookiePath</a> <a name="proxypassreversecookiepath" id="proxypassreversecookiepath">Directive</a></h2>
+<div class="directive-section"><h2><a name="ProxyMaxForwards" id="ProxyMaxForwards">ProxyMaxForwards</a> <a name="proxymaxforwards" id="proxymaxforwards">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the Path string in Set-Cookie headers from a reverse-
-proxied server</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookiePath <var>internal-path</var>
-<var>public-path</var> [<var>interpolate</var>]</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximium number of proxies that a request can be forwarded
+through</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyMaxForwards <var>number</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyMaxForwards -1</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Default behaviour changed in 2.2.7</td></tr>
</table>
-<p>
-Useful in conjunction with
-<code class="directive"><a href="#proxypassreverse">ProxyPassReverse</a></code>
-in situations where backend URL paths are mapped to public paths on the
-reverse proxy. This directive rewrites the <code>path</code> string in
-<code>Set-Cookie</code> headers. If the beginning of the cookie path matches
-<var>internal-path</var>, the cookie path will be replaced with
-<var>public-path</var>.
-</p><p>
-In the example given with
-<code class="directive"><a href="#proxypassreverse">ProxyPassReverse</a></code>, the directive:
-</p>
- <pre class="prettyprint lang-config">ProxyPassReverseCookiePath "/" "/mirror/foo/"</pre>
+ <p>The <code class="directive">ProxyMaxForwards</code> directive specifies the
+ maximum number of proxies through which a request may pass, if there's no
+ <code>Max-Forwards</code> header supplied with the request. This may
+ be set to prevent infinite proxy loops, or a DoS attack.</p>
-<p>
-will rewrite a cookie with backend path <code>/</code> (or
-<code>/example</code> or, in fact, anything) to <code>/mirror/foo/</code>.
-</p>
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyMaxForwards 15</pre>
+</div>
+
+ <p>Note that setting <code class="directive">ProxyMaxForwards</code> is a
+ violation of the HTTP/1.1 protocol (RFC2616), which forbids a Proxy
+ setting <code>Max-Forwards</code> if the Client didn't set it.
+ Earlier Apache httpd versions would always set it. A negative
+ <code class="directive">ProxyMaxForwards</code> value, including the
+ default -1, gives you protocol-compliant behaviour, but may
+ leave you open to loops.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyPreserveHost" id="ProxyPreserveHost">ProxyPreserveHost</a> <a name="proxypreservehost" id="proxypreservehost">Directive</a></h2>
+<div class="directive-section"><h2><a name="ProxyPass" id="ProxyPass">ProxyPass</a> <a name="proxypass" id="proxypass">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use incoming Host HTTP request header for proxy
-request</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPreserveHost On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyPreserveHost Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maps remote servers into the local server URL-space</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPass [<var>path</var>] !|<var>url</var> [<var>key=value</var>
+ <var>[key=value</var> ...]] [nocanon] [interpolate] [noquery]</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Usable in directory
-context in 2.3.3 and later.</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Unix Domain Socket (UDS) support added in 2.4.7</td></tr>
</table>
- <p>When enabled, this option will pass the Host: line from the incoming
- request to the proxied host, instead of the hostname specified in the
- <code class="directive">ProxyPass</code> line.</p>
+ <p>This directive allows remote servers to be mapped into the
+ space of the local server; the local server does not act as a
+ proxy in the conventional sense, but appears to be a mirror of the
+ remote server. The local server is often called a <dfn>reverse
+ proxy</dfn> or <dfn>gateway</dfn>. The <var>path</var> is the name of
+ a local virtual path; <var>url</var> is a partial URL for the
+ remote server and cannot include a query string.</p>
+
+ <div class="note"><strong>Note: </strong>This directive cannot be used within a
+ <code><Directory></code> context.</div>
+
+ <div class="warning">The <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive should
+ usually be set <strong>off</strong> when using
+ <code class="directive">ProxyPass</code>.</div>
+
+ <p>In 2.4.7 and later, support for using a Unix Domain Socket is available by using a target
+ which prepends <code>unix:/path/lis.sock|</code>. For example, to proxy
+ HTTP and target the UDS at /home/www/socket you would use
+ <code>unix:/home/www.socket|http://localhost/whatever/</code>.</p>
+
+ <div class="note"><strong>Note:</strong> The path associated with the <code>unix:</code>
+ URL is <code class="directive">DefaultRuntimeDir</code> aware.</div>
+
+ <p>Suppose the local server has address <code>http://example.com/</code>;
+ then</p>
+
+ <pre class="prettyprint lang-config"><Location "/mirror/foo/">
+ ProxyPass "http://backend.example.com/"
+</Location></pre>
+
+
+ <p>will cause a local request for
+ <code>http://example.com/mirror/foo/bar</code> to be internally converted
+ into a proxy request to <code>http://backend.example.com/bar</code>.</p>
+
+ <p>The following alternative syntax is possible, however it can carry a
+ performance penalty when present in very large numbers. The advantage of
+ the below syntax is that it allows for dynamic control via the
+ <a href="mod_proxy_balancer.html#balancer_manager">Balancer Manager</a> interface:</p>
+
+ <pre class="prettyprint lang-config">ProxyPass "/mirror/foo/" "http://backend.example.com/"</pre>
+
+
+ <div class="warning">
+ <p>If the first argument ends with a trailing <strong>/</strong>, the second
+ argument should also end with a trailing <strong>/</strong> and vice
+ versa. Otherwise the resulting requests to the backend may miss some
+ needed slashes and do not deliver the expected results.
+ </p>
+ </div>
+
+ <p>The <code>!</code> directive is useful in situations where you don't want
+ to reverse-proxy a subdirectory, <em>e.g.</em></p>
- <p>This option should normally be turned <code>Off</code>. It is mostly
- useful in special configurations like proxied mass name-based virtual
- hosting, where the original Host header needs to be evaluated by the
- backend server.</p>
+ <pre class="prettyprint lang-config"><Location "/mirror/foo/">
+ ProxyPass "http://backend.example.com/"
+</Location>
+<Location "/mirror/foo/i">
+ ProxyPass "!"
+</Location></pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyReceiveBufferSize" id="ProxyReceiveBufferSize">ProxyReceiveBufferSize</a> <a name="proxyreceivebuffersize" id="proxyreceivebuffersize">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Network buffer size for proxied HTTP and FTP
-connections</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyReceiveBufferSize <var>bytes</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyReceiveBufferSize 0</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>The <code class="directive">ProxyReceiveBufferSize</code> directive specifies an
- explicit (TCP/IP) network buffer size for proxied HTTP and FTP connections,
- for increased throughput. It has to be greater than <code>512</code> or set
- to <code>0</code> to indicate that the system's default buffer size should
- be used.</p>
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyReceiveBufferSize 2048</pre>
-</div>
+ <pre class="prettyprint lang-config">ProxyPass "/mirror/foo/i" "!"
+ProxyPass "/mirror/foo" "http://backend.example.com"</pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyRemote" id="ProxyRemote">ProxyRemote</a> <a name="proxyremote" id="proxyremote">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Remote proxy used to handle certain requests</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRemote <var>match</var> <var>remote-server</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>This defines remote proxies to this proxy. <var>match</var> is either the
- name of a URL-scheme that the remote server supports, or a partial URL
- for which the remote server should be used, or <code>*</code> to indicate
- the server should be contacted for all requests. <var>remote-server</var> is
- a partial URL for the remote server. Syntax:</p>
- <div class="example"><p><code>
- <dfn>remote-server</dfn> =
- <var>scheme</var>://<var>hostname</var>[:<var>port</var>]
- </code></p></div>
+ <p>will proxy all requests to <code>/mirror/foo</code> to
+ <code>backend.example.com</code> <em>except</em> requests made to
+ <code>/mirror/foo/i</code>.</p>
- <p><var>scheme</var> is effectively the protocol that should be used to
- communicate with the remote server; only <code>http</code> and <code>https</code>
- are supported by this module. When using <code>https</code>, the requests
- are forwarded through the remote proxy using the HTTP CONNECT method.</p>
+ <div class="warning"><h3>Ordering ProxyPass Directives</h3>
+ <p>The configured <code class="directive"><a href="#proxypass">ProxyPass</a></code>
+ and <code class="directive"><a href="#proxypassmatch">ProxyPassMatch</a></code>
+ rules are checked in the order of configuration. The first rule that
+ matches wins. So usually you should sort conflicting
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> rules starting with the
+ longest URLs first. Otherwise later rules for longer URLS will be hidden
+ by any earlier rule which uses a leading substring of the URL. Note that
+ there is some relation with worker sharing. In contrast, only one
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive can be placed
+ in a <code class="directive"><a href="../mod/core.html#location">Location</a></code> block, and the most
+ specific location will take precedence.</p>
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyRemote "http://goodguys.example.com/" "http://mirrorguys.example.com:8000"
-ProxyRemote "*" "http://cleverproxy.localdomain"
-ProxyRemote "ftp" "http://ftpproxy.mydomain:8080"</pre>
-</div>
+ <p>For the same reasons exclusions must come <em>before</em> the
+ general <code class="directive">ProxyPass</code> directives.</p>
- <p>In the last example, the proxy will forward FTP requests, encapsulated
- as yet another HTTP proxy request, to another proxy which can handle
- them.</p>
+ </div>
- <p>This option also supports reverse proxy configuration - a backend
- webserver can be embedded within a virtualhost URL space even if that
- server is hidden by another forward proxy.</p>
+ <p>In Apache HTTP Server 2.1 and later, mod_proxy supports pooled
+ connections to a backend server. Connections created on demand
+ can be retained in a pool for future use. Limits on the pool size
+ and other settings can be coded on
+ the <code class="directive">ProxyPass</code> directive
+ using <code>key=value</code> parameters, described in the table
+ below.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyRemoteMatch" id="ProxyRemoteMatch">ProxyRemoteMatch</a> <a name="proxyremotematch" id="proxyremotematch">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Remote proxy used to handle requests matched by regular
-expressions</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRemoteMatch <var>regex</var> <var>remote-server</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>The <code class="directive">ProxyRemoteMatch</code> is identical to the
- <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> directive, except the
- first argument is a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
- match against the requested URL.</p>
+ <p>By default, mod_proxy will allow and retain the maximum number of
+ connections that could be used simultaneously by that web server child
+ process. Use the <code>max</code> parameter to reduce the number from
+ the default. Use the <code>ttl</code> parameter to set an optional
+ time to live; connections which have been unused for at least
+ <code>ttl</code> seconds will be closed. <code>ttl</code> can be used
+ to avoid using a connection which is subject to closing because of the
+ backend server's keep-alive timeout.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyRequests" id="ProxyRequests">ProxyRequests</a> <a name="proxyrequests" id="proxyrequests">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables forward (standard) proxy requests</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRequests On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyRequests Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>This allows or prevents Apache httpd from functioning as a forward proxy
- server. (Setting ProxyRequests to <code>Off</code> does not disable use of
- the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.)</p>
+ <p>The pool of connections is maintained per web server child
+ process, and <code>max</code> and other settings are not coordinated
+ among all child processes, except when only one child process is allowed
+ by configuration or MPM design.</p>
- <p>In a typical reverse proxy or gateway configuration, this
- option should be set to
- <code>Off</code>.</p>
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300</pre>
+</div>
- <p>In order to get the functionality of proxying HTTP or FTP sites, you
- need also <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> or <code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code>
- (or both) present in the server.</p>
+ <table class="bordered"><tr><th>BalancerMember parameters</th></tr></table>
+ <table>
+ <tr><th>Parameter</th>
+ <th>Default</th>
+ <th>Description</th></tr>
+ <tr><td>min</td>
+ <td>0</td>
+ <td>Minimum number of connection pool entries, unrelated to the
+ actual number of connections. This only needs to be modified from the
+ default for special circumstances where heap memory associated with the
+ backend connections should be preallocated or retained.</td></tr>
+ <tr><td>max</td>
+ <td>1...n</td>
+ <td>Maximum number of connections that will be allowed to the
+ backend server. The default for this limit is the number of threads
+ per process in the active MPM. In the Prefork MPM, this is always 1,
+ while with other MPMs it is controlled by the
+ <code class="directive">ThreadsPerChild</code> directive.</td></tr>
+ <tr><td>smax</td>
+ <td>max</td>
+ <td>Retained connection pool entries above this limit are freed
+ during certain operations if they have been unused for longer than
+ the time to live, controlled by the <code>ttl</code> parameter. If
+ the connection pool entry has an associated connection, it will be
+ closed. This only needs to be modified from the default for special
+ circumstances where connection pool entries and any associated
+ connections which have exceeded the time to live need to be freed or
+ closed more aggressively.</td></tr>
+ <tr><td>acquire</td>
+ <td>-</td>
+ <td>If set this will be the maximum time to wait for a free
+ connection in the connection pool, in milliseconds. If there are no free
+ connections in the pool the Apache httpd will return <code>SERVER_BUSY</code>
+ status to the client.
+ </td></tr>
+ <tr><td>connectiontimeout</td>
+ <td>timeout</td>
+ <td>Connect timeout in seconds.
+ The number of seconds Apache httpd waits for the creation of a connection to
+ the backend to complete. By adding a postfix of ms the timeout can be
+ also set in milliseconds.
+ </td></tr>
+ <tr><td>disablereuse</td>
+ <td>Off</td>
+ <td>This parameter should be used when you want to force mod_proxy
+ to immediately close a connection to the backend after being used, and
+ thus, disable its persistent connection and pool for that backend.
+ This helps in various situations where a firewall between Apache
+ httpd and
+ the backend server (regardless of protocol) tends to silently
+ drop connections or when backends themselves may be under round-
+ robin DNS. To disable connection pooling reuse,
+ set this property value to <code>On</code>.
+ </td></tr>
+ <tr><td>enablereuse</td>
+ <td>On</td>
+ <td>This is the inverse of 'disablereuse' above, provided as a
+ convenience for scheme handlers that require opt-in for connection
+ reuse (such as <code class="module"><a href="../mod/mod_proxy_fcgi.html">mod_proxy_fcgi</a></code>). 2.4.11 and later only.
+ </td></tr>
+ <tr><td>flushpackets</td>
+ <td>off</td>
+ <td>Determines whether the proxy module will auto-flush the output
+ brigade after each "chunk" of data. 'off' means that it will flush
+ only when needed, 'on' means after each chunk is sent and
+ 'auto' means poll/wait for a period of time and flush if
+ no input has been received for 'flushwait' milliseconds.
+ Currently this is in effect only for AJP.
+ </td></tr>
+ <tr><td>flushwait</td>
+ <td>10</td>
+ <td>The time to wait for additional input, in milliseconds, before
+ flushing the output brigade if 'flushpackets' is 'auto'.
+ </td></tr>
+ <tr><td>iobuffersize</td>
+ <td>8192</td>
+ <td>Adjusts the size of the internal scratchpad IO buffer. This allows you
+ to override the <code class="directive">ProxyIOBufferSize</code> for a specific worker.
+ This must be at least 512 or set to 0 for the system default of 8192.
+ </td></tr>
+ <tr><td>keepalive</td>
+ <td>Off</td>
+ <td><p>This parameter should be used when you have a firewall between your
+ Apache httpd and the backend server, who tend to drop inactive connections.
+ This flag will tell the Operating System to send <code>KEEP_ALIVE</code>
+ messages on inactive connections and thus prevent the firewall to drop the connection.
+ To enable keepalive set this property value to <code>On</code>. </p>
+ <p>The frequency of initial and subsequent TCP keepalive probes
+ depends on global OS settings, and may be as high as 2 hours. To be useful,
+ the frequency configured in the OS must be smaller than the threshold used
+ by the firewall.</p>
+ </td></tr>
+ <tr><td>lbset</td>
+ <td>0</td>
+ <td>Sets the load balancer cluster set that the worker is a member
+ of. The load balancer will try all members of a lower numbered
+ lbset before trying higher numbered ones.
+ </td></tr>
+ <tr><td>ping</td>
+ <td>0</td>
+ <td>Ping property tells the webserver to "test" the connection to
+ the backend before forwarding the request. For AJP, it causes
+ <code class="module"><a href="../mod/mod_proxy_ajp.html">mod_proxy_ajp</a></code>to send a <code>CPING</code>
+ request on the ajp13 connection (implemented on Tomcat 3.3.2+, 4.1.28+
+ and 5.0.13+). For HTTP, it causes <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>
+ to send a <code>100-Continue</code> to the backend (only valid for
+ HTTP/1.1 - for non HTTP/1.1 backends, this property has no
+ effect). In both cases the parameter is the delay in seconds to wait
+ for the reply.
+ This feature has been added to avoid problems with hung and
+ busy backends.
+ This will increase the network traffic during the normal operation
+ which could be an issue, but it will lower the
+ traffic in case some of the cluster nodes are down or busy.
+ By adding a postfix of ms the delay can be also set in
+ milliseconds.
+ </td></tr>
+ <tr><td>receivebuffersize</td>
+ <td>0</td>
+ <td>Adjusts the size of the explicit (TCP/IP) network buffer size for
+ proxied connections. This allows you to override the
+ <code class="directive">ProxyReceiveBufferSize</code> for a specific worker.
+ This must be at least 512 or set to 0 for the system default.
+ </td></tr>
+ <tr><td>redirect</td>
+ <td>-</td>
+ <td>Redirection Route of the worker. This value is usually
+ set dynamically to enable safe removal of the node from
+ the cluster. If set all requests without session id will be
+ redirected to the BalancerMember that has route parameter
+ equal as this value.
+ </td></tr>
+ <tr><td>retry</td>
+ <td>60</td>
+ <td>Connection pool worker retry timeout in seconds.
+ If the connection pool worker to the backend server is in the error state,
+ Apache httpd will not forward any requests to that server until the timeout
+ expires. This enables to shut down the backend server for maintenance,
+ and bring it back online later. A value of 0 means always retry workers
+ in an error state with no timeout.
+ </td></tr>
+ <tr><td>route</td>
+ <td>-</td>
+ <td>Route of the worker when used inside load balancer.
+ The route is a value appended to session id.
+ </td></tr>
+ <tr><td>status</td>
+ <td>-</td>
+ <td>Single letter value defining the initial status of
+ this worker.
+ <table>
+ <tr><td>D: Worker is disabled and will not accept any requests.</td></tr>
+ <tr><td>S: Worker is administratively stopped.</td></tr>
+ <tr><td>I: Worker is in ignore-errors mode, and will always be considered available.</td></tr>
+ <tr><td>H: Worker is in hot-standby mode and will only be used if no other
+ viable workers are available.</td></tr>
+ <tr><td>E: Worker is in an error state.</td></tr>
+ <tr><td>N: Worker is in drain mode, and will only accept existing sticky sessions
+ destined for itself and ignore all other requests.</td></tr>
+ </table>Status
+ can be set (which is the default) by prepending with '+' or
+ cleared by prepending with '-'.
+ Thus, a setting of 'S-E' sets this worker to Stopped and
+ clears the in-error flag.
+ </td></tr>
+ <tr><td>timeout</td>
+ <td><code class="directive"><a href="#proxytimeout">ProxyTimeout</a></code></td>
+ <td>Connection timeout in seconds.
+ The number of seconds Apache httpd waits for data sent by / to the backend.
+ </td></tr>
+ <tr><td>ttl</td>
+ <td>-</td>
+ <td>Time to live for inactive connections and associated connection
+ pool entries, in seconds. Once reaching this limit, a
+ connection will not be used again; it will be closed at some
+ later time.
+ </td></tr>
- <p>In order to get the functionality of (forward) proxying HTTPS sites, you
- need <code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code> enabled in the server.</p>
+ </table>
- <div class="warning"><h3>Warning</h3>
- <p>Do not enable proxying with <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> until you have <a href="#access">secured your server</a>. Open proxy servers are dangerous
- both to your network and to the Internet at large.</p>
+ <p>If the Proxy directive scheme starts with the
+ <code>balancer://</code> (eg: <code>balancer://cluster</code>,
+ any path information is ignored) then a virtual worker that does not really
+ communicate with the backend server will be created. Instead it is responsible
+ for the management of several "real" workers. In that case the special set of
+ parameters can be add to this virtual worker. See <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>
+ for more information about how the balancer works.
+ </p>
+ <table class="bordered"><tr><th>Balancer parameters</th></tr></table>
+ <table>
+ <tr><th>Parameter</th>
+ <th>Default</th>
+ <th>Description</th></tr>
+ <tr><td>lbmethod</td>
+ <td>byrequests</td>
+ <td>Balancer load-balance method. Select the load-balancing scheduler
+ method to use. Either <code>byrequests</code>, to perform weighted
+ request counting, <code>bytraffic</code>, to perform weighted
+ traffic byte count balancing, or <code>bybusyness</code>, to perform
+ pending request balancing. Default is <code>byrequests</code>.
+ </td></tr>
+ <tr><td>maxattempts</td>
+ <td>One less than the number of workers, or 1 with a single worker.</td>
+ <td>Maximum number of failover attempts before giving up.
+ </td></tr>
+ <tr><td>nofailover</td>
+ <td>Off</td>
+ <td>If set to <code>On</code> the session will break if the worker is in
+ error state or disabled. Set this value to On if backend servers do not
+ support session replication.
+ </td></tr>
+ <tr><td>stickysession</td>
+ <td>-</td>
+ <td>Balancer sticky session name. The value is usually set to something
+ like <code>JSESSIONID</code> or <code>PHPSESSIONID</code>,
+ and it depends on the backend application server that support sessions.
+ If the backend application server uses different name for cookies
+ and url encoded id (like servlet containers) use | to to separate them.
+ The first part is for the cookie the second for the path.<br />
+ Available in Apache HTTP Server 2.4.4 and later.
+ </td></tr>
+ <tr><td>stickysessionsep</td>
+ <td>"."</td>
+ <td>Sets the separation symbol in the session cookie. Some backend application servers
+ do not use the '.' as the symbol. For example the Oracle Weblogic server uses
+ '!'. The correct symbol can be set using this option. The setting of 'Off'
+ signifies that no symbol is used.
+ </td></tr>
+ <tr><td>scolonpathdelim</td>
+ <td>Off</td>
+ <td>If set to <code>On</code> the semi-colon character ';' will be
+ used as an additional sticky session path delimiter/separator. This
+ is mainly used to emulate mod_jk's behavior when dealing with paths such
+ as <code>JSESSIONID=6736bcf34;foo=aabfa</code>
+ </td></tr>
+ <tr><td>timeout</td>
+ <td>0</td>
+ <td>Balancer timeout in seconds. If set this will be the maximum time
+ to wait for a free worker. Default is not to wait.
+ </td></tr>
+ <tr><td>failonstatus</td>
+ <td>-</td>
+ <td>A single or comma-separated list of HTTP status codes. If set this will
+ force the worker into error state when the backend returns any status code
+ in the list. Worker recovery behaves the same as other worker errors.
+ </td></tr>
+ <tr><td>failontimeout</td>
+ <td>Off</td>
+ <td>If set, an IO read timeout after a request is sent to the backend will
+ force the worker into error state. Worker recovery behaves the same as other
+ worker errors.<br />
+ Available in Apache HTTP Server 2.4.5 and later.
+ </td></tr>
+ <tr><td>nonce</td>
+ <td><auto></td>
+ <td>The protective nonce used in the <code>balancer-manager</code> application page.
+ The default is to use an automatically determined UUID-based
+ nonce, to provide for further protection for the page. If set,
+ then the nonce is set to that value. A setting of <code>None</code>
+ disables all nonce checking.
+ <div class="note"><h3>Note</h3>
+ <p>In addition to the nonce, the <code>balancer-manager</code> page
+ should be protected via an ACL.</p>
</div>
+ </td></tr>
+ <tr><td>growth</td>
+ <td>0</td>
+ <td>Number of additional BalancerMembers to allow to be added
+ to this balancer in addition to those defined at configuration.
+ </td></tr>
+ <tr><td>forcerecovery</td>
+ <td>On</td>
+ <td>Force the immediate recovery of all workers without considering the
+ retry parameter of the workers if all workers of a balancer are
+ in error state. There might be cases where an already overloaded backend
+ can get into deeper trouble if the recovery of all workers is enforced
+ without considering the retry parameter of each worker. In this case
+ set to <code>Off</code>.<br />
+ Available in Apache HTTP Server 2.4.2 and later.
+ </td></tr>
-<h3>See also</h3>
-<ul>
-<li><a href="#forwardreverse">Forward and Reverse Proxies/Gateways</a></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxySet" id="ProxySet">ProxySet</a> <a name="proxyset" id="proxyset">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set various Proxy balancer or member parameters</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxySet <var>url</var> <var>key=value [key=value ...]</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>ProxySet is only available in Apache HTTP Server 2.2
- and later.</td></tr>
-</table>
- <p>This directive is used as an alternate method of setting any of the
- parameters available to Proxy balancers and workers normally done via the
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive. If used
- within a <code><Proxy <var>balancer url|worker url</var>></code>
- container directive, the <var>url</var> argument is not required. As a side
- effect the respective balancer or worker gets created. This can be useful
- when doing reverse proxying via a
- <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> instead of a
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
+ </table>
+ <p>A sample balancer setup</p>
+ <pre class="prettyprint lang-config">ProxyPass "/special-area" "http://special.example.com" smax=5 max=10
+ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofailover=On
+<Proxy "balancer://mycluster">
+ BalancerMember "ajp://1.2.3.4:8009"
+ BalancerMember "ajp://1.2.3.5:8009" loadfactor=20
+ # Less powerful server, don't send as many requests there,
+ BalancerMember "ajp://1.2.3.6:8009" loadfactor=5
+</Proxy></pre>
- <div class="example"><pre class="prettyprint lang-config"><Proxy "balancer://hotcluster">
- BalancerMember "http://www2.example.com:8080" loadfactor=1
- BalancerMember "http://www3.example.com:8080" loadfactor=2
+
+ <p>Setting up a hot-standby, that will only be used if no other
+ members are available</p>
+ <pre class="prettyprint lang-config">ProxyPass "/" "balancer://hotcluster/"
+<Proxy "balancer://hotcluster">
+ BalancerMember "ajp://1.2.3.4:8009" loadfactor=1
+ BalancerMember "ajp://1.2.3.5:8009" loadfactor=2
+ # The server below is on hot standby
+ BalancerMember "ajp://1.2.3.6:8009" status=+H
ProxySet lbmethod=bytraffic
</Proxy></pre>
-</div>
- <pre class="prettyprint lang-config"><Proxy "http://backend">
- ProxySet keepalive=On
-</Proxy></pre>
+ <p>Normally, mod_proxy will canonicalise ProxyPassed URLs.
+ But this may be incompatible with some backends, particularly those
+ that make use of <var>PATH_INFO</var>. The optional <var>nocanon</var>
+ keyword suppresses this, and passes the URL path "raw" to the
+ backend. Note that may affect the security of your backend, as it
+ removes the normal limited protection against URL-based attacks
+ provided by the proxy.</p>
- <pre class="prettyprint lang-config">ProxySet "balancer://foo" lbmethod=bytraffic timeout=15</pre>
+ <p>Normally, mod_proxy will include the query string when
+ generating the <var>SCRIPT_FILENAME</var> environment variable.
+ The optional <var>noquery</var> keyword (available in
+ httpd 2.4.1 and later) prevents this.</p>
+ <p>When used inside a <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section, the first argument is omitted and the local
+ directory is obtained from the <code class="directive"><a href="../mod/core.html#location"><Location></a></code>. The same will occur inside a
+ <code class="directive"><a href="../mod/core.html#locationmatch"><LocationMatch></a></code> section,
+ however ProxyPass does not interpret the regexp as such, so it is necessary
+ to use <code class="directive">ProxyPassMatch</code> in this situation instead.</p>
- <pre class="prettyprint lang-config">ProxySet "ajp://backend:7001" timeout=15</pre>
+ <p>This directive is not supported in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> or <code class="directive"><a href="../mod/core.html#files"><Files></a></code> sections.</p>
+ <p>If you require a more flexible reverse-proxy configuration, see the
+ <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive with the
+ <code>[P]</code> flag.</p>
- <div class="warning"><h3>Warning</h3>
- <p>Keep in mind that the same parameter key can have a different meaning
- depending whether it is applied to a balancer or a worker as shown by the two
- examples above regarding timeout.</p>
- </div>
+ <p>The optional <var>interpolate</var> keyword, in combination with
+ <code class="directive">ProxyPassInterpolateEnv</code> causes the ProxyPass
+ to interpolate environment variables, using the syntax
+ <var>${VARNAME}</var>. Note that many of the standard CGI-derived
+ environment variables will not exist when this interpolation happens,
+ so you may still have to resort to <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+ for complex rules. Also note that interpolation is not supported
+ within the scheme portion of a URL. Dynamic determination of the
+ scheme can be accomplished with <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> as in the
+ following example.</p>
+
+ <pre class="prettyprint lang-config">RewriteEngine On
+
+RewriteCond "%{HTTPS}" =off
+RewriteRule "." "-" [E=protocol:http]
+RewriteCond "%{HTTPS}" =on
+RewriteRule "." "-" [E=protocol:https]
+RewriteRule "^/mirror/foo/(.*)" "%{ENV:protocol}://backend.example.com/$1" [P]
+ProxyPassReverse "/mirror/foo/" "http://backend.example.com/"
+ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"</pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxySourceAddress" id="ProxySourceAddress">ProxySourceAddress</a> <a name="proxysourceaddress" id="proxysourceaddress">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set local IP address for outgoing proxy connections</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxySourceAddress <var>address</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.9 and later</td></tr>
-</table>
- <p>This directive allows to set a specific local address to bind to when connecting
- to a backend server.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyStatus" id="ProxyStatus">ProxyStatus</a> <a name="proxystatus" id="proxystatus">Directive</a></h2>
+<div class="directive-section"><h2><a name="ProxyPassInherit" id="ProxyPassInherit">ProxyPassInherit</a> <a name="proxypassinherit" id="proxypassinherit">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Show Proxy LoadBalancer status in mod_status</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyStatus Off|On|Full</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyStatus Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Inherit ProxyPass directives defined from the main server</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassInherit On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyPassInherit On</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.2 and later</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>ProxyPassInherit is only available in Apache HTTP Server 2.4.5 and later.
+ and later.</td></tr>
</table>
- <p>This directive determines whether or not proxy
- loadbalancer status data is displayed via the <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>
- server-status page.</p>
- <div class="note"><h3>Note</h3>
- <p><strong>Full</strong> is synonymous with <strong>On</strong></p>
- </div>
-
-
+ <p>This directive will cause the current server/vhost to "inherit"
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code>
+ directives defined in the main server. This can cause issues and
+ inconsistent behavior if using the Balancer Manager for dynamic changes
+ and so should be disabled if using that feature.</p>
+ <p>The setting in the global server defines the default for all vhosts.</p>
+ <p>Disabling ProxyPassInherit also disables <code class="directive"><a href="#balancerinherit">BalancerInherit</a></code>.</p>
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyTimeout" id="ProxyTimeout">ProxyTimeout</a> <a name="proxytimeout" id="proxytimeout">Directive</a></h2>
+<div class="directive-section"><h2><a name="ProxyPassInterpolateEnv" id="ProxyPassInterpolateEnv">ProxyPassInterpolateEnv</a> <a name="proxypassinterpolateenv" id="proxypassinterpolateenv">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Network timeout for proxied requests</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyTimeout <var>seconds</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Value of <code class="directive"><a href="../mod/core.html#timeout">Timeout</a></code></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable Environment Variable interpolation in Reverse Proxy configurations</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassInterpolateEnv On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyPassInterpolateEnv Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.2.9 and later</td></tr>
</table>
- <p>This directive allows a user to specifiy a timeout on proxy requests.
- This is useful when you have a slow/buggy appserver which hangs, and you
- would rather just return a timeout and fail gracefully instead of waiting
- however long it takes the server to return.</p>
+ <p>This directive, together with the <var>interpolate</var> argument to
+ <code class="directive">ProxyPass</code>, <code class="directive">ProxyPassReverse</code>,
+ <code class="directive">ProxyPassReverseCookieDomain</code> and
+ <code class="directive">ProxyPassReverseCookiePath</code>
+ enables reverse proxies to be dynamically
+ configured using environment variables, which may be set by
+ another module such as <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.
+ It affects the <code class="directive">ProxyPass</code>,
+ <code class="directive">ProxyPassReverse</code>,
+ <code class="directive">ProxyPassReverseCookieDomain</code>, and
+ <code class="directive">ProxyPassReverseCookiePath</code> directives,
+ and causes them to substitute the value of an environment
+ variable <code>varname</code> for the string <code>${varname}</code>
+ in configuration directives (if the <var>interpolate</var> option is set).</p>
+ <p>Keep this turned off (for server performance) unless you need it!</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyVia" id="ProxyVia">ProxyVia</a> <a name="proxyvia" id="proxyvia">Directive</a></h2>
+<div class="directive-section"><h2><a name="ProxyPassMatch" id="ProxyPassMatch">ProxyPassMatch</a> <a name="proxypassmatch" id="proxypassmatch">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Information provided in the <code>Via</code> HTTP response
-header for proxied requests</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyVia On|Off|Full|Block</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyVia Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maps remote servers into the local server URL-space using regular expressions</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassMatch [<var>regex</var>] !|<var>url</var> [<var>key=value</var>
+ <var>[key=value</var> ...]]</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
</table>
- <p>This directive controls the use of the <code>Via:</code> HTTP
- header by the proxy. Its intended use is to control the flow of
- proxy requests along a chain of proxy servers. See <a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> (HTTP/1.1), section
- 14.45 for an explanation of <code>Via:</code> header lines.</p>
-
- <ul>
- <li>If set to <code>Off</code>, which is the default, no special processing
- is performed. If a request or reply contains a <code>Via:</code> header,
- it is passed through unchanged.</li>
-
- <li>If set to <code>On</code>, each request and reply will get a
- <code>Via:</code> header line added for the current host.</li>
-
- <li>If set to <code>Full</code>, each generated <code>Via:</code> header
- line will additionally have the Apache httpd server version shown as a
- <code>Via:</code> comment field.</li>
-
- <li>If set to <code>Block</code>, every proxy request will have all its
- <code>Via:</code> header lines removed. No new <code>Via:</code> header will
- be generated.</li>
- </ul>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="forwardreverse" id="forwardreverse">Forward Proxies and Reverse
- Proxies/Gateways</a></h2>
- <p>Apache HTTP Server can be configured in both a <dfn>forward</dfn> and
- <dfn>reverse</dfn> proxy (also known as <dfn>gateway</dfn>) mode.</p>
-
- <p>An ordinary <dfn>forward proxy</dfn> is an intermediate
- server that sits between the client and the <em>origin
- server</em>. In order to get content from the origin server,
- the client sends a request to the proxy naming the origin server
- as the target and the proxy then requests the content from the
- origin server and returns it to the client. The client must be
- specially configured to use the forward proxy to access other
- sites.</p>
-
- <p>A typical usage of a forward proxy is to provide Internet
- access to internal clients that are otherwise restricted by a
- firewall. The forward proxy can also use caching (as provided
- by <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>) to reduce network usage.</p>
-
- <p>The forward proxy is activated using the <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive. Because
- forward proxies allow clients to access arbitrary sites through
- your server and to hide their true origin, it is essential that
- you <a href="#access">secure your server</a> so that only
- authorized clients can access the proxy before activating a
- forward proxy.</p>
+ <p>This directive is equivalent to <code class="directive"><a href="#proxypass">ProxyPass</a></code>,
+ but makes use of regular expressions, instead of simple prefix matching. The
+ supplied regular expression is matched against the <var>url</var>, and if it
+ matches, the server will substitute any parenthesized matches into the given
+ string and use it as a new <var>url</var>.</p>
- <p>A <dfn>reverse proxy</dfn> (or <dfn>gateway</dfn>), by
- contrast, appears to the client just like an ordinary web
- server. No special configuration on the client is necessary.
- The client makes ordinary requests for content in the name-space
- of the reverse proxy. The reverse proxy then decides where to
- send those requests, and returns the content as if it was itself
- the origin.</p>
+ <div class="note"><strong>Note: </strong>This directive cannot be used within a
+ <code><Directory></code> context.</div>
+
+ <p>Suppose the local server has address <code>http://example.com/</code>;
+ then</p>
- <p>A typical usage of a reverse proxy is to provide Internet
- users access to a server that is behind a firewall. Reverse
- proxies can also be used to balance load among several back-end
- servers, or to provide caching for a slower back-end server.
- In addition, reverse proxies can be used simply to bring
- several servers into the same URL space.</p>
+ <pre class="prettyprint lang-config">ProxyPassMatch "^/(.*\.gif)$" "http://backend.example.com/$1"</pre>
- <p>A reverse proxy is activated using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive or the
- <code>[P]</code> flag to the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive. It is
- <strong>not</strong> necessary to turn <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> on in order to
- configure a reverse proxy.</p>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="examples" id="examples">Basic Examples</a></h2>
- <p>The examples below are only a very basic idea to help you
- get started. Please read the documentation on the individual
- directives.</p>
+ <p>will cause a local request for
+ <code>http://example.com/foo/bar.gif</code> to be internally converted
+ into a proxy request to <code>http://backend.example.com/foo/bar.gif</code>.</p>
+ <div class="note"><h3>Note</h3>
+ <p>The URL argument must be parsable as a URL <em>before</em> regexp
+ substitutions (as well as after). This limits the matches you can use.
+ For instance, if we had used</p>
+ <pre class="prettyprint lang-config">ProxyPassMatch "^(/.*\.gif)$" "http://backend.example.com:8000$1"</pre>
- <p>In addition, if you wish to have caching enabled, consult
- the documentation from <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>.</p>
+ <p>in our previous example, it would fail with a syntax error
+ at server startup. This is a bug (PR 46665 in the ASF bugzilla),
+ and the workaround is to reformulate the match:</p>
+ <pre class="prettyprint lang-config">ProxyPassMatch "^/(.*\.gif)$" "http://backend.example.com:8000/$1"</pre>
- <div class="example"><h3>Reverse Proxy</h3><pre class="prettyprint lang-config">ProxyPass "/foo" "http://foo.example.com/bar"
-ProxyPassReverse "/foo" "http://foo.example.com/bar"</pre>
-</div>
+ </div>
+ <p>The <code>!</code> directive is useful in situations where you don't want
+ to reverse-proxy a subdirectory.</p>
- <div class="example"><h3>Forward Proxy</h3><pre class="prettyprint lang-config">ProxyRequests On
-ProxyVia On
+ <p>When used inside a <code class="directive"><a href="../mod/core.html#locationmatch"><LocationMatch></a></code> section, the first argument is omitted and the
+ regexp is obtained from the <code class="directive"><a href="../mod/core.html#locationmatch"><LocationMatch></a></code>.</p>
-<Proxy "*">
- Require host internal.example.com
-</Proxy></pre>
-</div>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="handler" id="handler">Access via Handler</a></h2>
+ <p>If you require a more flexible reverse-proxy configuration, see the
+ <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive with the
+ <code>[P]</code> flag.</p>
- <p>You can also force a request to be handled as a reverse-proxy
- request, by creating a suitable Handler pass-through. The example
- configuration below will pass all requests for PHP scripts to the
- specified FastCGI server using reverse proxy:
+ <div class="note">
+ <h3>Default Substitution</h3>
+ <p>When the URL parameter doesn't use any backreferences into the regular
+ expression, the original URL will be appended to the URL parameter.
</p>
+ </div>
- <div class="example"><h3>Reverse Proxy PHP scripts</h3><pre class="prettyprint lang-config"><FilesMatch "\.php$">
- # Unix sockets require 2.4.7 or later
- SetHandler "proxy:unix:/path/to/app.sock|fcgi://localhost/"
-</FilesMatch></pre>
-</div>
-
- <p>This feature is available in Apache HTTP Server 2.4.10 and later.</p>
+ <div class="warning">
+ <h3>Security Warning</h3>
+ <p>Take care when constructing the target URL of the rule, considering
+ the security impact from allowing the client influence over the set of
+ URLs to which your server will act as a proxy. Ensure that the scheme
+ and hostname part of the URL is either fixed, or does not allow the
+ client undue influence.</p>
+ </div>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="workers" id="workers">Workers</a></h2>
- <p>The proxy manages the configuration of origin servers and their
- communication parameters in objects called <dfn>workers</dfn>.
- There are two built-in workers, the default forward proxy worker and the
- default reverse proxy worker. Additional workers can be configured
- explicitly.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyPassReverse" id="ProxyPassReverse">ProxyPassReverse</a> <a name="proxypassreverse" id="proxypassreverse">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the URL in HTTP response headers sent from a reverse
+proxied server</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverse [<var>path</var>] <var>url</var>
+[<var>interpolate</var>]</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>This directive lets Apache httpd adjust the URL in the <code>Location</code>,
+ <code>Content-Location</code> and <code>URI</code> headers on HTTP
+ redirect responses. This is essential when Apache httpd is used as a
+ reverse proxy (or gateway) to avoid by-passing the reverse proxy
+ because of HTTP redirects on the backend servers which stay behind
+ the reverse proxy.</p>
- <p>The two default workers have a fixed configuration
- and will be used if no other worker matches the request.
- They do not use HTTP Keep-Alive or connection pooling.
- The TCP connections to the origin server will instead be
- opened and closed for each request.</p>
+ <p>Only the HTTP response headers specifically mentioned above
+ will be rewritten. Apache httpd will not rewrite other response
+ headers, nor will it by default rewrite URL references inside HTML pages.
+ This means that if the proxied content contains absolute URL
+ references, they will by-pass the proxy. To rewrite HTML content to
+ match the proxy, you must load and enable <code class="module"><a href="../mod/mod_proxy_html.html">mod_proxy_html</a></code>.
+ </p>
- <p>Explicitly configured workers are identified by their URL.
- They are usually created and configured using
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> or
- <code class="directive"><a href="#proxypassmatch">ProxyPassMatch</a></code> when used
- for a reverse proxy:</p>
+ <p><var>path</var> is the name of a local virtual path. <var>url</var> is a
+ partial URL for the remote server - the same way they are used for the
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
- <pre class="prettyprint lang-config">ProxyPass "/example" "http://backend.example.com" connectiontimeout=5 timeout=30</pre>
+ <p>For example, suppose the local server has address
+ <code>http://example.com/</code>; then</p>
+ <pre class="prettyprint lang-config">ProxyPass "/mirror/foo/" "http://backend.example.com/"
+ProxyPassReverse "/mirror/foo/" "http://backend.example.com/"
+ProxyPassReverseCookieDomain "backend.example.com" "public.example.com"
+ProxyPassReverseCookiePath "/" "/mirror/foo/"</pre>
- <p>This will create a worker associated with the origin server URL
- <code>http://backend.example.com</code> and using the given timeout
- values. When used in a forward proxy, workers are usually defined
- via the <code class="directive"><a href="#proxyset">ProxySet</a></code> directive:</p>
- <pre class="prettyprint lang-config">ProxySet "http://backend.example.com" connectiontimeout=5 timeout=30</pre>
+ <p>will not only cause a local request for the
+ <code>http://example.com/mirror/foo/bar</code> to be internally converted
+ into a proxy request to <code>http://backend.example.com/bar</code>
+ (the functionality <code>ProxyPass</code> provides here). It also takes care
+ of redirects the server <code>backend.example.com</code> sends: when
+ <code>http://backend.example.com/bar</code> is redirected by him to
+ <code>http://backend.example.com/quux</code> Apache httpd adjusts this to
+ <code>http://example.com/mirror/foo/quux</code> before forwarding the HTTP
+ redirect response to the client. Note that the hostname used for
+ constructing the URL is chosen in respect to the setting of the <code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code> directive.</p>
+ <p>Note that this <code class="directive">ProxyPassReverse</code> directive can
+ also be used in conjunction with the proxy pass-through feature
+ (<code>RewriteRule ... [P]</code>) from <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+ because it doesn't depend on a corresponding <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
- <p>or alternatively using <code class="directive"><a href="#proxy">Proxy</a></code>
- and <code class="directive"><a href="#proxyset">ProxySet</a></code>:</p>
+ <p>The optional <var>interpolate</var> keyword, used together with
+ <code class="directive">ProxyPassInterpolateEnv</code>, enables interpolation
+ of environment variables specified using the format <var>${VARNAME}</var>.
+ Note that interpolation is not supported within the scheme portion of a
+ URL.</p>
- <pre class="prettyprint lang-config"><Proxy "http://backend.example.com">
- ProxySet connectiontimeout=5 timeout=30
-</Proxy></pre>
+ <p>When used inside a <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section, the first argument is omitted and the local
+ directory is obtained from the <code class="directive"><a href="../mod/core.html#location"><Location></a></code>. The same occurs inside a <code class="directive"><a href="../mod/core.html#locationmatch"><LocationMatch></a></code> section, but will probably not work as
+ intended, as ProxyPassReverse will interpret the regexp literally as a
+ path; if needed in this situation, specify the ProxyPassReverse outside
+ the section, or in a separate <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section.</p>
+ <p>This directive is not supported in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> or <code class="directive"><a href="../mod/core.html#files"><Files></a></code> sections.</p>
- <p>Using explicitly configured workers in the forward mode is
- not very common, because forward proxies usually communicate with many
- different origin servers. Creating explicit workers for some of the
- origin servers can still be useful, if they are used very often.
- Explicitly configured workers have no concept of forward or reverse
- proxying by themselves. They encapsulate a common concept of
- communication with origin servers. A worker created by
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> for use in a
- reverse proxy will be also used for forward proxy requests whenever
- the URL to the origin server matches the worker URL and vice versa.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyPassReverseCookieDomain" id="ProxyPassReverseCookieDomain">ProxyPassReverseCookieDomain</a> <a name="proxypassreversecookiedomain" id="proxypassreversecookiedomain">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the Domain string in Set-Cookie headers from a reverse-
+proxied server</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookieDomain <var>internal-domain</var>
+<var>public-domain</var> [<var>interpolate</var>]</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+<p>Usage is basically similar to
+<code class="directive"><a href="#proxypassreverse">ProxyPassReverse</a></code>, but instead of
+rewriting headers that are a URL, this rewrites the <code>domain</code>
+string in <code>Set-Cookie</code> headers.</p>
- <p>The URL identifying a direct worker is the URL of its
- origin server including any path components given:</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyPassReverseCookiePath" id="ProxyPassReverseCookiePath">ProxyPassReverseCookiePath</a> <a name="proxypassreversecookiepath" id="proxypassreversecookiepath">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the Path string in Set-Cookie headers from a reverse-
+proxied server</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookiePath <var>internal-path</var>
+<var>public-path</var> [<var>interpolate</var>]</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+<p>
+Useful in conjunction with
+<code class="directive"><a href="#proxypassreverse">ProxyPassReverse</a></code>
+in situations where backend URL paths are mapped to public paths on the
+reverse proxy. This directive rewrites the <code>path</code> string in
+<code>Set-Cookie</code> headers. If the beginning of the cookie path matches
+<var>internal-path</var>, the cookie path will be replaced with
+<var>public-path</var>.
+</p><p>
+In the example given with
+<code class="directive"><a href="#proxypassreverse">ProxyPassReverse</a></code>, the directive:
+</p>
+ <pre class="prettyprint lang-config">ProxyPassReverseCookiePath "/" "/mirror/foo/"</pre>
- <pre class="prettyprint lang-config">ProxyPass "/examples" "http://backend.example.com/examples"
-ProxyPass "/docs" "http://backend.example.com/docs"</pre>
+<p>
+will rewrite a cookie with backend path <code>/</code> (or
+<code>/example</code> or, in fact, anything) to <code>/mirror/foo/</code>.
+</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyPreserveHost" id="ProxyPreserveHost">ProxyPreserveHost</a> <a name="proxypreservehost" id="proxypreservehost">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use incoming Host HTTP request header for proxy
+request</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPreserveHost On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyPreserveHost Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Usable in directory
+context in 2.3.3 and later.</td></tr>
+</table>
+ <p>When enabled, this option will pass the Host: line from the incoming
+ request to the proxied host, instead of the hostname specified in the
+ <code class="directive">ProxyPass</code> line.</p>
+ <p>This option should normally be turned <code>Off</code>. It is mostly
+ useful in special configurations like proxied mass name-based virtual
+ hosting, where the original Host header needs to be evaluated by the
+ backend server.</p>
- <p>This example defines two different workers, each using a separate
- connection pool and configuration.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyReceiveBufferSize" id="ProxyReceiveBufferSize">ProxyReceiveBufferSize</a> <a name="proxyreceivebuffersize" id="proxyreceivebuffersize">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Network buffer size for proxied HTTP and FTP
+connections</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyReceiveBufferSize <var>bytes</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyReceiveBufferSize 0</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>The <code class="directive">ProxyReceiveBufferSize</code> directive specifies an
+ explicit (TCP/IP) network buffer size for proxied HTTP and FTP connections,
+ for increased throughput. It has to be greater than <code>512</code> or set
+ to <code>0</code> to indicate that the system's default buffer size should
+ be used.</p>
- <div class="warning"><h3>Worker Sharing</h3>
- <p>Worker sharing happens if the worker URLs overlap, which occurs when
- the URL of some worker is a leading substring of the URL of another
- worker defined later in the configuration file. In the following example</p>
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyReceiveBufferSize 2048</pre>
+</div>
- <pre class="prettyprint lang-config">ProxyPass "/apps" "http://backend.example.com/" timeout=60
-ProxyPass "/examples" "http://backend.example.com/examples" timeout=10</pre>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyRemote" id="ProxyRemote">ProxyRemote</a> <a name="proxyremote" id="proxyremote">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Remote proxy used to handle certain requests</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRemote <var>match</var> <var>remote-server</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>This defines remote proxies to this proxy. <var>match</var> is either the
+ name of a URL-scheme that the remote server supports, or a partial URL
+ for which the remote server should be used, or <code>*</code> to indicate
+ the server should be contacted for all requests. <var>remote-server</var> is
+ a partial URL for the remote server. Syntax:</p>
+ <div class="example"><p><code>
+ <dfn>remote-server</dfn> =
+ <var>scheme</var>://<var>hostname</var>[:<var>port</var>]
+ </code></p></div>
- <p>the second worker isn't actually created. Instead the first
- worker is used. The benefit is, that there is only one connection pool,
- so connections are more often reused. Note that all configuration attributes
- given explicitly for the later worker will be ignored. This will be logged
- as a warning. In the above example the resulting timeout value
- for the URL <code>/examples</code> will be <code>60</code> instead
- of <code>10</code>!</p>
+ <p><var>scheme</var> is effectively the protocol that should be used to
+ communicate with the remote server; only <code>http</code> and <code>https</code>
+ are supported by this module. When using <code>https</code>, the requests
+ are forwarded through the remote proxy using the HTTP CONNECT method.</p>
- <p>If you want to avoid worker sharing, sort your worker definitions
- by URL length, starting with the longest worker URLs. If you want to maximize
- worker sharing use the reverse sort order. See also the related warning about
- ordering <code class="directive"><a href="#proxypass">ProxyPass</a></code> directives.</p>
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyRemote "http://goodguys.example.com/" "http://mirrorguys.example.com:8000"
+ProxyRemote "*" "http://cleverproxy.localdomain"
+ProxyRemote "ftp" "http://ftpproxy.mydomain:8080"</pre>
+</div>
- </div>
+ <p>In the last example, the proxy will forward FTP requests, encapsulated
+ as yet another HTTP proxy request, to another proxy which can handle
+ them.</p>
- <p>Explicitly configured workers come in two flavors:
- <dfn>direct workers</dfn> and <dfn>(load) balancer workers</dfn>.
- They support many important configuration attributes which are
- described below in the <code class="directive"><a href="#proxypass">ProxyPass</a></code>
- directive. The same attributes can also be set using
- <code class="directive"><a href="#proxyset">ProxySet</a></code>.</p>
+ <p>This option also supports reverse proxy configuration - a backend
+ webserver can be embedded within a virtualhost URL space even if that
+ server is hidden by another forward proxy.</p>
- <p>The set of options available for a direct worker
- depends on the protocol, which is specified in the origin server URL.
- Available protocols include <code>ajp</code>, <code>fcgi</code>,
- <code>ftp</code>, <code>http</code> and <code>scgi</code>.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyRemoteMatch" id="ProxyRemoteMatch">ProxyRemoteMatch</a> <a name="proxyremotematch" id="proxyremotematch">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Remote proxy used to handle requests matched by regular
+expressions</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRemoteMatch <var>regex</var> <var>remote-server</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>The <code class="directive">ProxyRemoteMatch</code> is identical to the
+ <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> directive, except the
+ first argument is a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
+ match against the requested URL.</p>
- <p>Balancer workers are virtual workers that use direct workers known
- as their members to actually handle the requests. Each balancer can
- have multiple members. When it handles a request, it chooses a member
- based on the configured load balancing algorithm.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyRequests" id="ProxyRequests">ProxyRequests</a> <a name="proxyrequests" id="proxyrequests">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables forward (standard) proxy requests</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRequests On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyRequests Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>This allows or prevents Apache httpd from functioning as a forward proxy
+ server. (Setting ProxyRequests to <code>Off</code> does not disable use of
+ the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.)</p>
- <p>A balancer worker is created if its worker URL uses
- <code>balancer</code> as the protocol scheme.
- The balancer URL uniquely identifies the balancer worker.
- Members are added to a balancer using
- <code class="directive"><a href="#balancermember">BalancerMember</a></code>.</p>
+ <p>In a typical reverse proxy or gateway configuration, this
+ option should be set to
+ <code>Off</code>.</p>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="access" id="access">Controlling access to your proxy</a></h2>
- <p>You can control who can access your proxy via the <code class="directive"><a href="#proxy"><Proxy></a></code> control block as in
- the following example:</p>
+ <p>In order to get the functionality of proxying HTTP or FTP sites, you
+ need also <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> or <code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code>
+ (or both) present in the server.</p>
- <pre class="prettyprint lang-config"><Proxy "*">
- Require ip 192.168.0
-</Proxy></pre>
+ <p>In order to get the functionality of (forward) proxying HTTPS sites, you
+ need <code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code> enabled in the server.</p>
+ <div class="warning"><h3>Warning</h3>
+ <p>Do not enable proxying with <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> until you have <a href="#access">secured your server</a>. Open proxy servers are dangerous
+ both to your network and to the Internet at large.</p>
+ </div>
- <p>For more information on access control directives, see
- <code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code>.</p>
+<h3>See also</h3>
+<ul>
+<li><a href="#forwardreverse">Forward and Reverse Proxies/Gateways</a></li>
+</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxySet" id="ProxySet">ProxySet</a> <a name="proxyset" id="proxyset">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set various Proxy balancer or member parameters</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxySet <var>url</var> <var>key=value [key=value ...]</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>ProxySet is only available in Apache HTTP Server 2.2
+ and later.</td></tr>
+</table>
+ <p>This directive is used as an alternate method of setting any of the
+ parameters available to Proxy balancers and workers normally done via the
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive. If used
+ within a <code><Proxy <var>balancer url|worker url</var>></code>
+ container directive, the <var>url</var> argument is not required. As a side
+ effect the respective balancer or worker gets created. This can be useful
+ when doing reverse proxying via a
+ <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> instead of a
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
- <p>Strictly limiting access is essential if you are using a
- forward proxy (using the <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive).
- Otherwise, your server can be used by any client to access
- arbitrary hosts while hiding his or her true identity. This is
- dangerous both for your network and for the Internet at large.
- When using a reverse proxy (using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive with
- <code>ProxyRequests Off</code>), access control is less
- critical because clients can only contact the hosts that you
- have specifically configured.</p>
+ <div class="example"><pre class="prettyprint lang-config"><Proxy "balancer://hotcluster">
+ BalancerMember "http://www2.example.com:8080" loadfactor=1
+ BalancerMember "http://www3.example.com:8080" loadfactor=2
+ ProxySet lbmethod=bytraffic
+</Proxy></pre>
+</div>
- <p><strong>See Also</strong> the <a href="mod_proxy_http.html#env">Proxy-Chain-Auth</a> environment variable.</p>
+ <pre class="prettyprint lang-config"><Proxy "http://backend">
+ ProxySet keepalive=On
+</Proxy></pre>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="startup" id="startup">Slow Startup</a></h2>
- <p>If you're using the <code class="directive"><a href="#proxyblock">ProxyBlock</a></code> directive, hostnames' IP addresses are looked up
- and cached during startup for later match test. This may take a few
- seconds (or more) depending on the speed with which the hostname lookups
- occur.</p>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="intranet" id="intranet">Intranet Proxy</a></h2>
- <p>An Apache httpd proxy server situated in an intranet needs to forward
- external requests through the company's firewall (for this, configure
- the <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> directive
- to forward the respective <var>scheme</var> to the firewall proxy).
- However, when it has to
- access resources within the intranet, it can bypass the firewall when
- accessing hosts. The <code class="directive"><a href="#noproxy">NoProxy</a></code>
- directive is useful for specifying which hosts belong to the intranet and
- should be accessed directly.</p>
- <p>Users within an intranet tend to omit the local domain name from their
- WWW requests, thus requesting "http://somehost/" instead of
- <code>http://somehost.example.com/</code>. Some commercial proxy servers
- let them get away with this and simply serve the request, implying a
- configured local domain. When the <code class="directive"><a href="#proxydomain">ProxyDomain</a></code> directive is used and the server is <a href="#proxyrequests">configured for proxy service</a>, Apache httpd can return
- a redirect response and send the client to the correct, fully qualified,
- server address. This is the preferred method since the user's bookmark
- files will then contain fully qualified hosts.</p>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="envsettings" id="envsettings">Protocol Adjustments</a></h2>
- <p>For circumstances where <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> is sending
- requests to an origin server that doesn't properly implement
- keepalives or HTTP/1.1, there are two <a href="../env.html">environment variables</a> that can force the
- request to use HTTP/1.0 with no keepalive. These are set via the
- <code class="directive"><a href="../mod/mod_env.html#setenv">SetEnv</a></code> directive.</p>
+ <pre class="prettyprint lang-config">ProxySet "balancer://foo" lbmethod=bytraffic timeout=15</pre>
- <p>These are the <code>force-proxy-request-1.0</code> and
- <code>proxy-nokeepalive</code> notes.</p>
- <pre class="prettyprint lang-config"><Location "/buggyappserver/">
- ProxyPass "http://buggyappserver:7001/foo/"
- SetEnv force-proxy-request-1.0 1
- SetEnv proxy-nokeepalive 1
-</Location></pre>
+ <pre class="prettyprint lang-config">ProxySet "ajp://backend:7001" timeout=15</pre>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="request-bodies" id="request-bodies">Request Bodies</a></h2>
+ <div class="warning"><h3>Warning</h3>
+ <p>Keep in mind that the same parameter key can have a different meaning
+ depending whether it is applied to a balancer or a worker as shown by the two
+ examples above regarding timeout.</p>
+ </div>
- <p>Some request methods such as POST include a request body.
- The HTTP protocol requires that requests which include a body
- either use chunked transfer encoding or send a
- <code>Content-Length</code> request header. When passing these
- requests on to the origin server, <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>
- will always attempt to send the <code>Content-Length</code>. But
- if the body is large and the original request used chunked
- encoding, then chunked encoding may also be used in the upstream
- request. You can control this selection using <a href="../env.html">environment variables</a>. Setting
- <code>proxy-sendcl</code> ensures maximum compatibility with
- upstream servers by always sending the
- <code>Content-Length</code>, while setting
- <code>proxy-sendchunked</code> minimizes resource usage by using
- chunked encoding.</p>
- <p>Under some circumstances, the server must spool request bodies
- to disk to satisfy the requested handling of request bodies. For
- example, this spooling will occur if the original body was sent with
- chunked encoding (and is large), but the administrator has
- asked for backend requests to be sent with Content-Length or as HTTP/1.0.
- This spooling can also occur if the request body already has a
- Content-Length header, but the server is configured to filter incoming
- request bodies.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxySourceAddress" id="ProxySourceAddress">ProxySourceAddress</a> <a name="proxysourceaddress" id="proxysourceaddress">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set local IP address for outgoing proxy connections</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxySourceAddress <var>address</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.9 and later</td></tr>
+</table>
+ <p>This directive allows to set a specific local address to bind to when connecting
+ to a backend server.</p>
- <p><code class="directive"><a href="../mod/core.html#limitrequestbody">LimitRequestBody</a></code> only applies to
- request bodies that the server will spool to disk</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyStatus" id="ProxyStatus">ProxyStatus</a> <a name="proxystatus" id="proxystatus">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Show Proxy LoadBalancer status in mod_status</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyStatus Off|On|Full</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyStatus Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.2 and later</td></tr>
+</table>
+ <p>This directive determines whether or not proxy
+ loadbalancer status data is displayed via the <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>
+ server-status page.</p>
+ <div class="note"><h3>Note</h3>
+ <p><strong>Full</strong> is synonymous with <strong>On</strong></p>
+ </div>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="x-headers" id="x-headers">Reverse Proxy Request Headers</a></h2>
- <p>When acting in a reverse-proxy mode (using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive, for example),
- <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> adds several request headers in
- order to pass information to the origin server. These headers
- are:</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyTimeout" id="ProxyTimeout">ProxyTimeout</a> <a name="proxytimeout" id="proxytimeout">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Network timeout for proxied requests</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyTimeout <var>seconds</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Value of <code class="directive"><a href="../mod/core.html#timeout">Timeout</a></code></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>This directive allows a user to specifiy a timeout on proxy requests.
+ This is useful when you have a slow/buggy appserver which hangs, and you
+ would rather just return a timeout and fail gracefully instead of waiting
+ however long it takes the server to return.</p>
- <dl>
- <dt><code>X-Forwarded-For</code></dt>
- <dd>The IP address of the client.</dd>
- <dt><code>X-Forwarded-Host</code></dt>
- <dd>The original host requested by the client in the <code>Host</code>
- HTTP request header.</dd>
- <dt><code>X-Forwarded-Server</code></dt>
- <dd>The hostname of the proxy server.</dd>
- </dl>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyVia" id="ProxyVia">ProxyVia</a> <a name="proxyvia" id="proxyvia">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Information provided in the <code>Via</code> HTTP response
+header for proxied requests</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyVia On|Off|Full|Block</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyVia Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>This directive controls the use of the <code>Via:</code> HTTP
+ header by the proxy. Its intended use is to control the flow of
+ proxy requests along a chain of proxy servers. See <a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> (HTTP/1.1), section
+ 14.45 for an explanation of <code>Via:</code> header lines.</p>
- <p>Be careful when using these headers on the origin server, since
- they will contain more than one (comma-separated) value if the
- original request already contained one of these headers. For
- example, you can use <code>%{X-Forwarded-For}i</code> in the log
- format string of the origin server to log the original clients IP
- address, but you may get more than one address if the request
- passes through several proxies.</p>
+ <ul>
+ <li>If set to <code>Off</code>, which is the default, no special processing
+ is performed. If a request or reply contains a <code>Via:</code> header,
+ it is passed through unchanged.</li>
- <p>See also the <code class="directive"><a href="#proxypreservehost">ProxyPreserveHost</a></code> and <code class="directive"><a href="#proxyvia">ProxyVia</a></code> directives, which control
- other request headers.</p>
+ <li>If set to <code>On</code>, each request and reply will get a
+ <code>Via:</code> header line added for the current host.</li>
- <p>Note: If you need to specify custom request headers to be
- added to the forwarded request, use the
- <code class="directive"><a href="../mod/mod_headers.html#requestheader">RequestHeader</a></code>
- directive.</p>
+ <li>If set to <code>Full</code>, each generated <code>Via:</code> header
+ line will additionally have the Apache httpd server version shown as a
+ <code>Via:</code> comment field.</li>
- </div>
+ <li>If set to <code>Block</code>, every proxy request will have all its
+ <code>Via:</code> header lines removed. No new <code>Via:</code> header will
+ be generated.</li>
+ </ul>
+
+</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_proxy.html" title="English"> en </a> |
large.</p>
</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#env">Environment Variables</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#basppacketstruct">Basic Packet Structure</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#rpacetstruct">Request Packet Structure</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#resppacketstruct">Response Packet Structure</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
<li><a href="../env.html">Environment Variable documentation</a></li>
large.</p>
</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#scheduler">Load balancer scheduler algorithm</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#stickyness">Load balancer stickyness</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#balancer_manager">Enabling Balancer Manager Support</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#stickyness_implementation">Details on load balancer stickyness</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#stickyness_troubleshooting">Troubleshooting load balancer stickyness</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
large.</p>
</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#notes">Request notes</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#allowconnect">AllowCONNECT</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#notes">Request notes</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="notes" id="notes">Request notes</a></h2>
+ <p><code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code> creates the following request notes for
+ logging using the <code>%{VARNAME}n</code> format in
+ <code class="directive"><a href="../mod/mod_log_config.html#logformat">LogFormat</a></code> or
+ <code class="directive"><a href="../mod/core.html#errorlogformat">ErrorLogFormat</a></code>:
+ </p>
+ <dl>
+ <dt>proxy-source-port</dt>
+ <dd>The local port used for the connection to the backend server.</dd>
+ </dl>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AllowCONNECT" id="AllowCONNECT">AllowCONNECT</a> <a name="allowconnect" id="allowconnect">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Ports that are allowed to <code>CONNECT</code> through the
allow connections to the listed ports only.</p>
</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="notes" id="notes">Request notes</a></h2>
- <p><code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code> creates the following request notes for
- logging using the <code>%{VARNAME}n</code> format in
- <code class="directive"><a href="../mod/mod_log_config.html#logformat">LogFormat</a></code> or
- <code class="directive"><a href="../mod/core.html#errorlogformat">ErrorLogFormat</a></code>:
- </p>
- <dl>
- <dt>proxy-source-port</dt>
- <dd>The local port used for the connection to the backend server.</dd>
- </dl>
-</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_proxy_connect.html" title="English"> en </a> |
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ProxyExpressDBMFile" id="ProxyExpressDBMFile">ProxyExpressDBMFile</a> <a name="proxyexpressdbmfile" id="proxyexpressdbmfile">Directive</a></h2>
<table class="directive">
controls whether the module will be active.</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_proxy_express.html" title="English"> en </a> |
large.</p>
</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#env">Environment Variables</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="program"><a href="../programs/fcgistarter.html">fcgistarter</a></code></li>
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
large.</p>
</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#proxyftpdircharset">ProxyFtpDirCharset</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#proxyftpescapewildcards">ProxyFtpEscapeWildcards</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#proxyftplistonwildcard">ProxyFtpListOnWildcard</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#mimetypes">Why doesn't file type <var>xxx</var>
download via FTP?</a></li>
in my browser's URL line?</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#wildcard">Why do I get a file listing when I expected
a file to be downloaded?</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#proxyftpdircharset">ProxyFtpDirCharset</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#proxyftpescapewildcards">ProxyFtpEscapeWildcards</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#proxyftplistonwildcard">ProxyFtpListOnWildcard</a></li>
+</ul>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyFtpDirCharset" id="ProxyFtpDirCharset">ProxyFtpDirCharset</a> <a name="proxyftpdircharset" id="proxyftpdircharset">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define the character set for proxied FTP listings</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyFtpDirCharset <var>character set</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyFtpDirCharset ISO-8859-1</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_ftp</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.2.7 and later. Moved from <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> in Apache 2.3.5.</td></tr>
-</table>
- <p>The <code class="directive">ProxyFtpDirCharset</code> directive defines the
- character set to be set for FTP directory listings in HTML generated by
- <code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code>.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyFtpEscapeWildcards" id="ProxyFtpEscapeWildcards">ProxyFtpEscapeWildcards</a> <a name="proxyftpescapewildcards" id="proxyftpescapewildcards">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether wildcards in requested filenames are escaped when sent to the FTP server</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyFtpEscapeWildcards [on|off]</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>on</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_ftp</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.3 and later</td></tr>
-</table>
- <p>The <code class="directive">ProxyFtpEscapeWildcards</code> directive
- controls whether wildcard characters ("*?[{~") in requested
- filenames are escaped with backslash before sending them to the
- FTP server. That is the default behavior, but many FTP servers
- don't know about the escaping and try to serve the literal filenames
- they were sent, including the backslashes in the names. </p>
- <p>Set to "off" to allow downloading files with wildcards
- in their names from FTP servers that don't understand wildcard
- escaping.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyFtpListOnWildcard" id="ProxyFtpListOnWildcard">ProxyFtpListOnWildcard</a> <a name="proxyftplistonwildcard" id="proxyftplistonwildcard">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether wildcards in requested filenames trigger a file listing</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyFtpListOnWildcard [on|off]</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>on</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_ftp</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.3 and later</td></tr>
-</table>
- <p>The <code class="directive">ProxyFtpListOnWildcard</code> directive
- controls whether wildcard characters ("*?[{~") in requested
- filenames cause <code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code> to return a listing
- of files instead of downloading a file. By default (value on),
- they do. Set to "off" to allow downloading files even if they
- have wildcard characters in their names.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="mimetypes" id="mimetypes">Why doesn't file type <var>xxx</var>
download via FTP?</a></h2>
See the <code class="directive">ProxyFtpListOnWildcard</code> directive.
</p>
</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyFtpDirCharset" id="ProxyFtpDirCharset">ProxyFtpDirCharset</a> <a name="proxyftpdircharset" id="proxyftpdircharset">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define the character set for proxied FTP listings</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyFtpDirCharset <var>character set</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyFtpDirCharset ISO-8859-1</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_ftp</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.2.7 and later. Moved from <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> in Apache 2.3.5.</td></tr>
+</table>
+ <p>The <code class="directive">ProxyFtpDirCharset</code> directive defines the
+ character set to be set for FTP directory listings in HTML generated by
+ <code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code>.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyFtpEscapeWildcards" id="ProxyFtpEscapeWildcards">ProxyFtpEscapeWildcards</a> <a name="proxyftpescapewildcards" id="proxyftpescapewildcards">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether wildcards in requested filenames are escaped when sent to the FTP server</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyFtpEscapeWildcards [on|off]</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>on</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_ftp</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.3 and later</td></tr>
+</table>
+ <p>The <code class="directive">ProxyFtpEscapeWildcards</code> directive
+ controls whether wildcard characters ("*?[{~") in requested
+ filenames are escaped with backslash before sending them to the
+ FTP server. That is the default behavior, but many FTP servers
+ don't know about the escaping and try to serve the literal filenames
+ they were sent, including the backslashes in the names. </p>
+ <p>Set to "off" to allow downloading files with wildcards
+ in their names from FTP servers that don't understand wildcard
+ escaping.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyFtpListOnWildcard" id="ProxyFtpListOnWildcard">ProxyFtpListOnWildcard</a> <a name="proxyftplistonwildcard" id="proxyftplistonwildcard">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether wildcards in requested filenames trigger a file listing</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyFtpListOnWildcard [on|off]</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>on</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_ftp</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.3 and later</td></tr>
+</table>
+ <p>The <code class="directive">ProxyFtpListOnWildcard</code> directive
+ controls whether wildcard characters ("*?[{~") in requested
+ filenames cause <code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code> to return a listing
+ of files instead of downloading a file. By default (value on),
+ they do. Set to "off" to allow downloading files even if they
+ have wildcard characters in their names.</p>
+
+</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_proxy_ftp.html" title="English"> en </a> |
<li><img alt="" src="../images/down.gif" /> <a href="#proxyhtmlurlmap">ProxyHTMLURLMap</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ProxyHTMLBufSize" id="ProxyHTMLBufSize">ProxyHTMLBufSize</a> <a name="proxyhtmlbufsize" id="proxyhtmlbufsize">Directive</a></h2>
<table class="directive">
in mod_proxy_html 3.x for HTTPD 2.0 and 2.2 is also supported.</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_proxy_html.html" title="English"> en </a> |
large.</p>
</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#env">Environment Variables</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#notes">Request notes</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
<li><code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code></li>
large.</p>
</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#env">Environment Variables</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#proxyscgiinternalredirect">ProxySCGIInternalRedirect</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxyscgisendfile">ProxySCGISendfile</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#env">Environment Variables</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
<li><code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="examples" id="examples">Examples</a></h2>
+ <p>Remember, in order to make the following examples work, you have to
+ enable <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> and <code class="module"><a href="../mod/mod_proxy_scgi.html">mod_proxy_scgi</a></code>.</p>
+
+ <div class="example"><h3>Simple gateway</h3><pre class="prettyprint lang-config">ProxyPass /scgi-bin/ scgi://localhost:4000/</pre>
+</div>
+
+ <p>The balanced gateway needs <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code> and
+ at least one load balancer algorithm module, such as
+ <code class="module"><a href="../mod/mod_lbmethod_byrequests.html">mod_lbmethod_byrequests</a></code>, in addition to the proxy
+ modules listed above. <code class="module"><a href="../mod/mod_lbmethod_byrequests.html">mod_lbmethod_byrequests</a></code> is the
+ default, and will be used for this example configuration.</p>
+
+ <div class="example"><h3>Balanced gateway</h3><pre class="prettyprint lang-config">ProxyPass "/scgi-bin/" "balancer://somecluster/"
+<Proxy "balancer://somecluster">
+ BalancerMember "scgi://localhost:4000"
+ BalancerMember "scgi://localhost:4001"
+</Proxy></pre>
+</div>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="env" id="env">Environment Variables</a></h2>
+ <p>In addition to the configuration directives that control the
+ behaviour of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, an <dfn>environment
+ variable</dfn> may also control the SCGI protocol
+ provider:</p>
+ <dl>
+ <dt>proxy-scgi-pathinfo</dt>
+ <dd>By default <code class="module"><a href="../mod/mod_proxy_scgi.html">mod_proxy_scgi</a></code> will neither create
+ nor export the <var>PATH_INFO</var> environment variable. This allows
+ the backend SCGI server to correctly determine <var>SCRIPT_NAME</var>
+ and <var>Script-URI</var> and be compliant with RFC 3875 section 3.3.
+ If instead you need <code class="module"><a href="../mod/mod_proxy_scgi.html">mod_proxy_scgi</a></code> to generate
+ a "best guess" for <var>PATH_INFO</var>, set this env-var. The
+ variable must be set before <code class="directive"><a href="../mod/env.html#setenv">SetEnv</a></code>
+ is effective. <code class="directive"><a href="../mod/setenv.html#setenvif">SetEnvIf</a></code> can be
+ used instead: <code>SetEnvIf Request_URI . proxy-scgi-pathinfo</code>
+ </dd>
+ </dl>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ProxySCGIInternalRedirect" id="ProxySCGIInternalRedirect">ProxySCGIInternalRedirect</a> <a name="proxyscgiinternalredirect" id="proxyscgiinternalredirect">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable or disable internal redirect responses from the
ProxySCGISendfile X-Send-Static</pre>
</div>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="examples" id="examples">Examples</a></h2>
- <p>Remember, in order to make the following examples work, you have to
- enable <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> and <code class="module"><a href="../mod/mod_proxy_scgi.html">mod_proxy_scgi</a></code>.</p>
-
- <div class="example"><h3>Simple gateway</h3><pre class="prettyprint lang-config">ProxyPass /scgi-bin/ scgi://localhost:4000/</pre>
-</div>
-
- <p>The balanced gateway needs <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code> and
- at least one load balancer algorithm module, such as
- <code class="module"><a href="../mod/mod_lbmethod_byrequests.html">mod_lbmethod_byrequests</a></code>, in addition to the proxy
- modules listed above. <code class="module"><a href="../mod/mod_lbmethod_byrequests.html">mod_lbmethod_byrequests</a></code> is the
- default, and will be used for this example configuration.</p>
-
- <div class="example"><h3>Balanced gateway</h3><pre class="prettyprint lang-config">ProxyPass "/scgi-bin/" "balancer://somecluster/"
-<Proxy "balancer://somecluster">
- BalancerMember "scgi://localhost:4000"
- BalancerMember "scgi://localhost:4001"
-</Proxy></pre>
-</div>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="env" id="env">Environment Variables</a></h2>
- <p>In addition to the configuration directives that control the
- behaviour of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, an <dfn>environment
- variable</dfn> may also control the SCGI protocol
- provider:</p>
- <dl>
- <dt>proxy-scgi-pathinfo</dt>
- <dd>By default <code class="module"><a href="../mod/mod_proxy_scgi.html">mod_proxy_scgi</a></code> will neither create
- nor export the <var>PATH_INFO</var> environment variable. This allows
- the backend SCGI server to correctly determine <var>SCRIPT_NAME</var>
- and <var>Script-URI</var> and be compliant with RFC 3875 section 3.3.
- If instead you need <code class="module"><a href="../mod/mod_proxy_scgi.html">mod_proxy_scgi</a></code> to generate
- a "best guess" for <var>PATH_INFO</var>, set this env-var. The
- variable must be set before <code class="directive"><a href="../mod/env.html#setenv">SetEnv</a></code>
- is effective. <code class="directive"><a href="../mod/setenv.html#setenvif">SetEnvIf</a></code> can be
- used instead: <code>SetEnvIf Request_URI . proxy-scgi-pathinfo</code>
- </dd>
- </dl>
</div>
</div>
<div class="bottomlang">
the request into a response. This module can be used to turn an output
filter into an HTTP service.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#reflectorheader">ReflectorHeader</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ReflectorHeader" id="ReflectorHeader">ReflectorHeader</a> <a name="reflectorheader" id="reflectorheader">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Reflect an input header to the output headers</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ReflectorHeader <var>inputheader</var> <var>[outputheader]</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_reflector</td></tr>
-</table>
- <p>This directive controls the reflection of request headers to the response.
- The first argument is the name of the request header to copy. If the optional
- second argument is specified, it will be used as the name of the response
- header, otherwise the original request header name will be used.</p>
-
-</div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="examples" id="examples">Examples</a></h2>
</dd>
</dl>
</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ReflectorHeader" id="ReflectorHeader">ReflectorHeader</a> <a name="reflectorheader" id="reflectorheader">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Reflect an input header to the output headers</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ReflectorHeader <var>inputheader</var> <var>[outputheader]</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_reflector</td></tr>
+</table>
+ <p>This directive controls the reflection of request headers to the response.
+ The first argument is the name of the request header to copy. If the optional
+ second argument is specified, it will be used as the name of the response
+ header, otherwise the original request header name will be used.</p>
+
+</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_reflector.html" title="English"> en </a> |
it is trivial for the remote useragent to impersonate another
useragent.</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#processing">Remote IP Processing</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#remoteipheader">RemoteIPHeader</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#remoteipinternalproxy">RemoteIPInternalProxy</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#remoteiptrustedproxy">RemoteIPTrustedProxy</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#remoteiptrustedproxylist">RemoteIPTrustedProxyList</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#processing">Remote IP Processing</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code></li>
<li><code class="module"><a href="../mod/mod_status.html">mod_status</a></code></li>
<li><code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="processing" id="processing">Remote IP Processing</a></h2>
+
+ <p>Apache by default identifies the useragent with the connection's
+ client_ip value, and the connection remote_host and remote_logname are
+ derived from this value. These fields play a role in authentication,
+ authorization and logging and other purposes by other loadable
+ modules.</p>
+
+ <p>mod_remoteip overrides the client IP of the connection with the
+ advertised useragent IP as provided by a proxy or load balancer, for
+ the duration of the request. A load balancer might establish a long
+ lived keepalive connection with the server, and each request will
+ have the correct useragent IP, even though the underlying client IP
+ address of the load balancer remains unchanged.</p>
+
+ <p>When multiple, comma delimited useragent IP addresses are listed in the
+ header value, they are processed in Right-to-Left order. Processing
+ halts when a given useragent IP address is not trusted to present the
+ preceding IP address. The header field is updated to this remaining
+ list of unconfirmed IP addresses, or if all IP addresses were trusted,
+ this header is removed from the request altogether.</p>
+
+ <p>In overriding the client IP, the module stores the list of intermediate
+ hosts in a remoteip-proxy-ip-list note, which <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>
+ can record using the <code>%{remoteip-proxy-ip-list}n</code> format token.
+ If the administrator needs to store this as an additional header, this
+ same value can also be recording as a header using the directive
+ <code class="directive"><a href="#remoteipproxiesheader">RemoteIPProxiesHeader</a></code>.</p>
+
+ <div class="note"><h3>IPv4-over-IPv6 Mapped Addresses</h3>
+ As with httpd in general, any IPv4-over-IPv6 mapped addresses are recorded
+ in their IPv4 representation.</div>
+
+ <div class="note"><h3>Internal (Private) Addresses</h3>
+ All internal addresses 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8
+ blocks (and IPv6 addresses outside of the public 2000::/3 block) are only
+ evaluated by mod_remoteip when <code class="directive"><a href="#remoteipinternalproxy">RemoteIPInternalProxy</a></code>
+ internal (intranet) proxies are registered.</div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="RemoteIPHeader" id="RemoteIPHeader">RemoteIPHeader</a> <a name="remoteipheader" id="remoteipheader">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare the header field which should be parsed for useragent IP addresses</td></tr>
proxy.isp.example.com #some well known ISP
</code></p></div>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="processing" id="processing">Remote IP Processing</a></h2>
-
- <p>Apache by default identifies the useragent with the connection's
- client_ip value, and the connection remote_host and remote_logname are
- derived from this value. These fields play a role in authentication,
- authorization and logging and other purposes by other loadable
- modules.</p>
-
- <p>mod_remoteip overrides the client IP of the connection with the
- advertised useragent IP as provided by a proxy or load balancer, for
- the duration of the request. A load balancer might establish a long
- lived keepalive connection with the server, and each request will
- have the correct useragent IP, even though the underlying client IP
- address of the load balancer remains unchanged.</p>
-
- <p>When multiple, comma delimited useragent IP addresses are listed in the
- header value, they are processed in Right-to-Left order. Processing
- halts when a given useragent IP address is not trusted to present the
- preceding IP address. The header field is updated to this remaining
- list of unconfirmed IP addresses, or if all IP addresses were trusted,
- this header is removed from the request altogether.</p>
-
- <p>In overriding the client IP, the module stores the list of intermediate
- hosts in a remoteip-proxy-ip-list note, which <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>
- can record using the <code>%{remoteip-proxy-ip-list}n</code> format token.
- If the administrator needs to store this as an additional header, this
- same value can also be recording as a header using the directive
- <code class="directive"><a href="#remoteipproxiesheader">RemoteIPProxiesHeader</a></code>.</p>
-
- <div class="note"><h3>IPv4-over-IPv6 Mapped Addresses</h3>
- As with httpd in general, any IPv4-over-IPv6 mapped addresses are recorded
- in their IPv4 representation.</div>
-
- <div class="note"><h3>Internal (Private) Addresses</h3>
- All internal addresses 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8
- blocks (and IPv6 addresses outside of the public 2000::/3 block) are only
- evaluated by mod_remoteip when <code class="directive"><a href="#remoteipinternalproxy">RemoteIPInternalProxy</a></code>
- internal (intranet) proxies are registered.</div>
-
</div>
</div>
<div class="bottomlang">
<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_reqtimeout.c</td></tr>
<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTPD 2.2.15 and later</td></tr></table>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#requestreadtimeout">RequestReadTimeout</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="examples" id="examples">Examples</a></h2>
+
+ <ol>
+ <li>
+ Allow 10 seconds to receive the request including the headers and
+ 30 seconds for receiving the request body:
+
+ <pre class="prettyprint lang-config">RequestReadTimeout header=10 body=30</pre>
+
+ </li>
+
+ <li>
+ Allow at least 10 seconds to receive the request body.
+ If the client sends data, increase the timeout by 1 second for every
+ 1000 bytes received, with no upper limit for the timeout (except for
+ the limit given indirectly by
+ <code class="directive"><a href="../mod/core.html#limitrequestbody">LimitRequestBody</a></code>):
+
+ <pre class="prettyprint lang-config">RequestReadTimeout body=10,MinRate=1000</pre>
+
+ </li>
+
+ <li>
+ Allow at least 10 seconds to receive the request including the headers.
+ If the client sends data, increase the timeout by 1 second for every
+ 500 bytes received. But do not allow more than 30 seconds for the
+ request including the headers:
+
+ <pre class="prettyprint lang-config">RequestReadTimeout header=10-30,MinRate=500</pre>
+
+ </li>
+
+ <li>
+ Usually, a server should have both header and body timeouts configured.
+ If a common configuration is used for http and https virtual hosts, the
+ timeouts should not be set too low:
+
+ <pre class="prettyprint lang-config">RequestReadTimeout header=20-40,MinRate=500 body=20,MinRate=500</pre>
+
+ </li>
+
+ </ol>
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="RequestReadTimeout" id="RequestReadTimeout">RequestReadTimeout</a> <a name="requestreadtimeout" id="requestreadtimeout">Directive</a></h2>
<table class="directive">
</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="examples" id="examples">Examples</a></h2>
-
- <ol>
- <li>
- Allow 10 seconds to receive the request including the headers and
- 30 seconds for receiving the request body:
-
- <pre class="prettyprint lang-config">RequestReadTimeout header=10 body=30</pre>
-
- </li>
-
- <li>
- Allow at least 10 seconds to receive the request body.
- If the client sends data, increase the timeout by 1 second for every
- 1000 bytes received, with no upper limit for the timeout (except for
- the limit given indirectly by
- <code class="directive"><a href="../mod/core.html#limitrequestbody">LimitRequestBody</a></code>):
-
- <pre class="prettyprint lang-config">RequestReadTimeout body=10,MinRate=1000</pre>
-
- </li>
-
- <li>
- Allow at least 10 seconds to receive the request including the headers.
- If the client sends data, increase the timeout by 1 second for every
- 500 bytes received. But do not allow more than 30 seconds for the
- request including the headers:
-
- <pre class="prettyprint lang-config">RequestReadTimeout header=10-30,MinRate=500</pre>
-
- </li>
-
- <li>
- Usually, a server should have both header and body timeouts configured.
- If a common configuration is used for http and https virtual hosts, the
- timeouts should not be set too low:
-
- <pre class="prettyprint lang-config">RequestReadTimeout header=20-40,MinRate=500 body=20,MinRate=500</pre>
-
- </li>
-
- </ol>
</div>
</div>
<div class="bottomlang">
<li><img alt="" src="../images/down.gif" /> <a href="#keptbodysize">KeptBodySize</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="KeptBodySize" id="KeptBodySize">KeptBodySize</a> <a name="keptbodysize" id="keptbodysize">Directive</a></h2>
<table class="directive">
<li><a href="mod_auth_form.html">mod_auth_form</a> documentation</li>
</ul>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_request.html" title="English"> en </a> |
<p>Further details, discussion, and examples, are provided in the
<a href="../rewrite/">detailed mod_rewrite documentation</a>.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#rewritebase">RewriteBase</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">RewriteCond</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#rewriteoptions">RewriteOptions</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#rewriterule">RewriteRule</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="logging" id="logging">Logging</a></h2>
+
+ <p><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> offers detailed logging of its actions
+ at the <code>trace1</code> to <code>trace8</code> log levels. The
+ log level can be set specifically for <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+ using the <code class="directive"><a href="../mod/core.html#loglevel">LogLevel</a></code> directive: Up to
+ level <code>debug</code>, no actions are logged, while <code>trace8</code>
+ means that practically all actions are logged.</p>
+
+ <div class="note">
+ Using a high trace log level for <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+ will slow down your Apache HTTP Server dramatically! Use a log
+ level higher than <code>trace2</code> only for debugging!
+ </div>
+
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">LogLevel alert rewrite:trace3</pre>
+</div>
+
+ <div class="note"><h3>RewriteLog</h3>
+ <p>Those familiar with earlier versions of
+ <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> will no doubt be looking for the
+ <code>RewriteLog</code> and <code>RewriteLogLevel</code>
+ directives. This functionality has been completely replaced by the
+ new per-module logging configuration mentioned above.
+ </p>
+
+ <p>To get just the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>-specific log
+ messages, pipe the log file through grep:</p>
+ <div class="example"><p><code>
+ tail -f error_log|fgrep '[rewrite:'
+ </code></p></div>
+ </div>
+
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="RewriteBase" id="RewriteBase">RewriteBase</a> <a name="rewritebase" id="rewritebase">Directive</a></h2>
<table class="directive">
</table>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="logging" id="logging">Logging</a></h2>
-
- <p><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> offers detailed logging of its actions
- at the <code>trace1</code> to <code>trace8</code> log levels. The
- log level can be set specifically for <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
- using the <code class="directive"><a href="../mod/core.html#loglevel">LogLevel</a></code> directive: Up to
- level <code>debug</code>, no actions are logged, while <code>trace8</code>
- means that practically all actions are logged.</p>
-
- <div class="note">
- Using a high trace log level for <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
- will slow down your Apache HTTP Server dramatically! Use a log
- level higher than <code>trace2</code> only for debugging!
- </div>
-
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">LogLevel alert rewrite:trace3</pre>
-</div>
-
- <div class="note"><h3>RewriteLog</h3>
- <p>Those familiar with earlier versions of
- <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> will no doubt be looking for the
- <code>RewriteLog</code> and <code>RewriteLogLevel</code>
- directives. This functionality has been completely replaced by the
- new per-module logging configuration mentioned above.
- </p>
-
- <p>To get just the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>-specific log
- messages, pipe the log file through grep:</p>
- <div class="example"><p><code>
- tail -f error_log|fgrep '[rewrite:'
- </code></p></div>
- </div>
-
</div>
</div>
<div class="bottomlang">
the author's blog</a>.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#sampleconf">Sample Configuration</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#sed_commands">Sed Commands</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#inputsed">InputSed</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#outputsed">OutputSed</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#sampleconf">Sample Configuration</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#sed_commands">Sed Commands</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="InputSed" id="InputSed">InputSed</a> <a name="inputsed" id="inputsed">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sed command to filter request data (typically <code>POST</code> data)</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>InputSed <var>sed-command</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_sed</td></tr>
-</table>
- <p>The <code class="directive">InputSed</code> directive specifies the <code>sed</code> command
- to execute on the request data e.g., <code>POST</code> data.
- </p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="OutputSed" id="OutputSed">OutputSed</a> <a name="outputsed" id="outputsed">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sed command for filtering response content</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>OutputSed <var>sed-command</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_sed</td></tr>
-</table>
- <p>The <code class="directive">OutputSed</code> directive specifies the <code>sed</code>
- command to execute on the response.
- </p>
-
-</div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="sampleconf" id="sampleconf">Sample Configuration</a></h2>
<dd>Swap the contents of the hold buffer and the current line.</dd>
</dl>
</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="InputSed" id="InputSed">InputSed</a> <a name="inputsed" id="inputsed">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sed command to filter request data (typically <code>POST</code> data)</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>InputSed <var>sed-command</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_sed</td></tr>
+</table>
+ <p>The <code class="directive">InputSed</code> directive specifies the <code>sed</code> command
+ to execute on the request data e.g., <code>POST</code> data.
+ </p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="OutputSed" id="OutputSed">OutputSed</a> <a name="outputsed" id="outputsed">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sed command for filtering response content</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>OutputSed <var>sed-command</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_sed</td></tr>
+</table>
+ <p>The <code class="directive">OutputSed</code> directive specifies the <code>sed</code>
+ command to execute on the response.
+ </p>
+
+</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_sed.html" title="English"> en </a> |
environment variables and HTTP headers, as appropriate.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#session">Session</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#sessionenv">SessionEnv</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#sessionexclude">SessionExclude</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#sessionheader">SessionHeader</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#sessioninclude">SessionInclude</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#sessionmaxage">SessionMaxAge</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#whatisasession">What is a session?</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#whocanuseasession">Who can use a session?</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cookieprivacy">Cookie Privacy</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authentication">Session Support for Authentication</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#integration">Integrating Sessions with External Applications</a></li>
-</ul><h3>See also</h3>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#session">Session</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#sessionenv">SessionEnv</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#sessionexclude">SessionExclude</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#sessionheader">SessionHeader</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#sessioninclude">SessionInclude</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#sessionmaxage">SessionMaxAge</a></li>
+</ul>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code></li>
<li><code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code></li>
<li><code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="Session" id="Session">Session</a> <a name="session" id="session">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables a session for the current directory or location</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Session On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Session Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
-</table>
- <p>The <code class="directive">Session</code> directive enables a session for the
- directory or location container. Further directives control where the
- session will be stored and how privacy is maintained.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SessionEnv" id="SessionEnv">SessionEnv</a> <a name="sessionenv" id="sessionenv">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Control whether the contents of the session are written to the
-<var>HTTP_SESSION</var> environment variable</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionEnv On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionEnv Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
-</table>
- <p>If set to <var>On</var>, the <code class="directive">SessionEnv</code> directive
- causes the contents of the session to be written to a CGI environment
- variable called <var>HTTP_SESSION</var>.</p>
-
- <p>The string is written in the URL query format, for example:</p>
-
- <div class="example"><p><code>
- <code>key1=foo&key3=bar</code>
- </code></p></div>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SessionExclude" id="SessionExclude">SessionExclude</a> <a name="sessionexclude" id="sessionexclude">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define URL prefixes for which a session is ignored</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionExclude <var>path</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
-</table>
- <p>The <code class="directive">SessionExclude</code> directive allows sessions to
- be disabled relative to URL prefixes only. This can be used to make a
- website more efficient, by targeting a more precise URL space for which
- a session should be maintained. By default, all URLs within the directory
- or location are included in the session. The
- <code class="directive"><a href="#sessionexclude">SessionExclude</a></code> directive takes
- precedence over the
- <code class="directive"><a href="#sessioninclude">SessionInclude</a></code> directive.</p>
-
- <div class="warning"><h3>Warning</h3>
- <p>This directive has a similar purpose to the <var>path</var> attribute
- in HTTP cookies, but should not be confused with this attribute. This
- directive does not set the <var>path</var> attribute, which must be
- configured separately.</p></div>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SessionHeader" id="SessionHeader">SessionHeader</a> <a name="sessionheader" id="sessionheader">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Import session updates from a given HTTP response header</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionHeader <var>header</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
-</table>
- <p>The <code class="directive">SessionHeader</code> directive defines the name of an
- HTTP response header which, if present, will be parsed and written to the
- current session.</p>
-
- <p>The header value is expected to be in the URL query format, for example:</p>
-
- <div class="example"><p><code>
- <code>key1=foo&key2=&key3=bar</code>
- </code></p></div>
-
- <p>Where a key is set to the empty string, that key will be removed from the
- session.</p>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SessionInclude" id="SessionInclude">SessionInclude</a> <a name="sessioninclude" id="sessioninclude">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define URL prefixes for which a session is valid</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionInclude <var>path</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>all URLs</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
-</table>
- <p>The <code class="directive">SessionInclude</code> directive allows sessions to
- be made valid for specific URL prefixes only. This can be used to make a
- website more efficient, by targeting a more precise URL space for which
- a session should be maintained. By default, all URLs within the directory
- or location are included in the session.</p>
-
- <div class="warning"><h3>Warning</h3>
- <p>This directive has a similar purpose to the <var>path</var> attribute
- in HTTP cookies, but should not be confused with this attribute. This
- directive does not set the <var>path</var> attribute, which must be
- configured separately.</p></div>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="SessionMaxAge" id="SessionMaxAge">SessionMaxAge</a> <a name="sessionmaxage" id="sessionmaxage">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a maximum age in seconds for a session</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionMaxAge <var>maxage</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionMaxAge 0</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
-</table>
- <p>The <code class="directive">SessionMaxAge</code> directive defines a time limit
- for which a session will remain valid. When a session is saved, this time
- limit is reset and an existing session can be continued. If a session
- becomes older than this limit without a request to the server to refresh
- the session, the session will time out and be removed. Where a session is
- used to stored user login details, this has the effect of logging the user
- out automatically after the given time.</p>
-
- <p>Setting the maxage to zero disables session expiry.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="whatisasession" id="whatisasession">What is a session?</a></h2>
<p>At the core of the session interface is a table of key and value pairs
</dl>
</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="Session" id="Session">Session</a> <a name="session" id="session">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables a session for the current directory or location</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Session On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Session Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
+</table>
+ <p>The <code class="directive">Session</code> directive enables a session for the
+ directory or location container. Further directives control where the
+ session will be stored and how privacy is maintained.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SessionEnv" id="SessionEnv">SessionEnv</a> <a name="sessionenv" id="sessionenv">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Control whether the contents of the session are written to the
+<var>HTTP_SESSION</var> environment variable</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionEnv On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionEnv Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
+</table>
+ <p>If set to <var>On</var>, the <code class="directive">SessionEnv</code> directive
+ causes the contents of the session to be written to a CGI environment
+ variable called <var>HTTP_SESSION</var>.</p>
+
+ <p>The string is written in the URL query format, for example:</p>
+
+ <div class="example"><p><code>
+ <code>key1=foo&key3=bar</code>
+ </code></p></div>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SessionExclude" id="SessionExclude">SessionExclude</a> <a name="sessionexclude" id="sessionexclude">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define URL prefixes for which a session is ignored</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionExclude <var>path</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
+</table>
+ <p>The <code class="directive">SessionExclude</code> directive allows sessions to
+ be disabled relative to URL prefixes only. This can be used to make a
+ website more efficient, by targeting a more precise URL space for which
+ a session should be maintained. By default, all URLs within the directory
+ or location are included in the session. The
+ <code class="directive"><a href="#sessionexclude">SessionExclude</a></code> directive takes
+ precedence over the
+ <code class="directive"><a href="#sessioninclude">SessionInclude</a></code> directive.</p>
+
+ <div class="warning"><h3>Warning</h3>
+ <p>This directive has a similar purpose to the <var>path</var> attribute
+ in HTTP cookies, but should not be confused with this attribute. This
+ directive does not set the <var>path</var> attribute, which must be
+ configured separately.</p></div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SessionHeader" id="SessionHeader">SessionHeader</a> <a name="sessionheader" id="sessionheader">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Import session updates from a given HTTP response header</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionHeader <var>header</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
+</table>
+ <p>The <code class="directive">SessionHeader</code> directive defines the name of an
+ HTTP response header which, if present, will be parsed and written to the
+ current session.</p>
+
+ <p>The header value is expected to be in the URL query format, for example:</p>
+
+ <div class="example"><p><code>
+ <code>key1=foo&key2=&key3=bar</code>
+ </code></p></div>
+
+ <p>Where a key is set to the empty string, that key will be removed from the
+ session.</p>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SessionInclude" id="SessionInclude">SessionInclude</a> <a name="sessioninclude" id="sessioninclude">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define URL prefixes for which a session is valid</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionInclude <var>path</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>all URLs</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
+</table>
+ <p>The <code class="directive">SessionInclude</code> directive allows sessions to
+ be made valid for specific URL prefixes only. This can be used to make a
+ website more efficient, by targeting a more precise URL space for which
+ a session should be maintained. By default, all URLs within the directory
+ or location are included in the session.</p>
+
+ <div class="warning"><h3>Warning</h3>
+ <p>This directive has a similar purpose to the <var>path</var> attribute
+ in HTTP cookies, but should not be confused with this attribute. This
+ directive does not set the <var>path</var> attribute, which must be
+ configured separately.</p></div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SessionMaxAge" id="SessionMaxAge">SessionMaxAge</a> <a name="sessionmaxage" id="sessionmaxage">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a maximum age in seconds for a session</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionMaxAge <var>maxage</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionMaxAge 0</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
+</table>
+ <p>The <code class="directive">SessionMaxAge</code> directive defines a time limit
+ for which a session will remain valid. When a session is saved, this time
+ limit is reset and an existing session can be continued. If a session
+ becomes older than this limit without a request to the server to refresh
+ the session, the session will time out and be removed. Where a session is
+ used to stored user login details, this has the effect of logging the user
+ out automatically after the given time.</p>
+
+ <p>Setting the maxage to zero disables session expiry.</p>
+
+</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_session.html" title="English"> en </a> |
the <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> module.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#basicexamples">Basic Examples</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#sessioncookiename">SessionCookieName</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sessioncookiename2">SessionCookieName2</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sessioncookieremove">SessionCookieRemove</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#basicexamples">Basic Examples</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_session.html">mod_session</a></code></li>
<li><code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code></li>
<li><code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="basicexamples" id="basicexamples">Basic Examples</a></h2>
+
+ <p>To create a simple session and store it in a cookie called
+ <var>session</var>, configure the session as follows:</p>
+
+ <div class="example"><h3>Browser based session</h3><pre class="prettyprint lang-config">Session On
+SessionCookieName session path=/</pre>
+</div>
+
+ <p>For more examples on how the session can be configured to be read
+ from and written to by a CGI application, see the
+ <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> examples section.</p>
+
+ <p>For documentation on how the session can be used to store username
+ and password details, see the <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> module.</p>
+
+ </div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SessionCookieName" id="SessionCookieName">SessionCookieName</a> <a name="sessioncookiename" id="sessioncookiename">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Name and attributes for the RFC2109 cookie storing the session</td></tr>
</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="basicexamples" id="basicexamples">Basic Examples</a></h2>
-
- <p>To create a simple session and store it in a cookie called
- <var>session</var>, configure the session as follows:</p>
-
- <div class="example"><h3>Browser based session</h3><pre class="prettyprint lang-config">Session On
-SessionCookieName session path=/</pre>
-</div>
-
- <p>For more examples on how the session can be configured to be read
- from and written to by a CGI application, see the
- <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> examples section.</p>
-
- <p>For documentation on how the session can be used to store username
- and password details, see the <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> module.</p>
-
- </div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_session_cookie.html" title="English"> en </a> |
the <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> module.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#basicusage">Basic Usage</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#sessioncryptocipher">SessionCryptoCipher</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sessioncryptodriver">SessionCryptoDriver</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sessioncryptopassphrase">SessionCryptoPassphrase</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sessioncryptopassphrasefile">SessionCryptoPassphraseFile</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#basicusage">Basic Usage</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_session.html">mod_session</a></code></li>
<li><code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code></li>
<li><code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="basicusage" id="basicusage">Basic Usage</a></h2>
+
+ <p>To create a simple encrypted session and store it in a cookie called
+ <var>session</var>, configure the session as follows:</p>
+
+ <div class="example"><h3>Browser based encrypted session</h3><pre class="prettyprint lang-config">Session On
+SessionCookieName session path=/
+SessionCryptoPassphrase secret</pre>
+</div>
+
+ <p>The session will be encrypted with the given key. Different servers can
+ be configured to share sessions by ensuring the same encryption key is used
+ on each server.</p>
+
+ <p>If the encryption key is changed, sessions will be invalidated
+ automatically.</p>
+
+ <p>For documentation on how the session can be used to store username
+ and password details, see the <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> module.</p>
+
+ </div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SessionCryptoCipher" id="SessionCryptoCipher">SessionCryptoCipher</a> <a name="sessioncryptocipher" id="sessioncryptocipher">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The crypto cipher to be used to encrypt the session</td></tr>
</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="basicusage" id="basicusage">Basic Usage</a></h2>
-
- <p>To create a simple encrypted session and store it in a cookie called
- <var>session</var>, configure the session as follows:</p>
-
- <div class="example"><h3>Browser based encrypted session</h3><pre class="prettyprint lang-config">Session On
-SessionCookieName session path=/
-SessionCryptoPassphrase secret</pre>
-</div>
-
- <p>The session will be encrypted with the given key. Different servers can
- be configured to share sessions by ensuring the same encryption key is used
- on each server.</p>
-
- <p>If the encryption key is changed, sessions will be invalidated
- automatically.</p>
-
- <p>For documentation on how the session can be used to store username
- and password details, see the <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> module.</p>
-
- </div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_session_crypto.html" title="English"> en </a> |
the <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> module.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#dbdconfig">DBD Configuration</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#anonymous">Anonymous Sessions</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#peruser">Per User Sessions</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#housekeeping">Database Housekeeping</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#sessiondbdcookiename">SessionDBDCookieName</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sessiondbdcookiename2">SessionDBDCookieName2</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sessiondbdselectlabel">SessionDBDSelectLabel</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sessiondbdupdatelabel">SessionDBDUpdateLabel</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#dbdconfig">DBD Configuration</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#anonymous">Anonymous Sessions</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#peruser">Per User Sessions</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#housekeeping">Database Housekeeping</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_session.html">mod_session</a></code></li>
<li><code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code></li>
<li><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="dbdconfig" id="dbdconfig">DBD Configuration</a></h2>
+
+ <p>Before the <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code> module can be configured to maintain a
+ session, the <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> module must be configured to make the various database queries
+ available to the server.</p>
+
+ <p>There are four queries required to keep a session maintained, to select an existing session,
+ to update an existing session, to insert a new session, and to delete an expired or empty
+ session. These queries are configured as per the example below.</p>
+
+ <div class="example"><h3>Sample DBD configuration</h3><pre class="prettyprint lang-config">DBDriver pgsql
+DBDParams "dbname=apachesession user=apache password=xxxxx host=localhost"
+DBDPrepareSQL "delete from session where key = %s" deletesession
+DBDPrepareSQL "update session set value = %s, expiry = %lld, key = %s where key = %s" updatesession
+DBDPrepareSQL "insert into session (value, expiry, key) values (%s, %lld, %s)" insertsession
+DBDPrepareSQL "select value from session where key = %s and (expiry = 0 or expiry > %lld)" selectsession
+DBDPrepareSQL "delete from session where expiry != 0 and expiry < %lld" cleansession</pre>
+</div>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="anonymous" id="anonymous">Anonymous Sessions</a></h2>
+
+ <p>Anonymous sessions are keyed against a unique UUID, and stored on the
+ browser within an HTTP cookie. This method is similar to that used by most
+ application servers to store session information.</p>
+
+ <p>To create a simple anonymous session and store it in a postgres database
+ table called <var>apachesession</var>, and save the session ID in a cookie
+ called <var>session</var>, configure the session as follows:</p>
+
+ <div class="example"><h3>SQL based anonymous session</h3><pre class="prettyprint lang-config">Session On
+SessionDBDCookieName session path=/</pre>
+</div>
+
+ <p>For more examples on how the session can be configured to be read
+ from and written to by a CGI application, see the
+ <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> examples section.</p>
+
+ <p>For documentation on how the session can be used to store username
+ and password details, see the <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> module.</p>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="peruser" id="peruser">Per User Sessions</a></h2>
+
+ <p>Per user sessions are keyed against the username of a successfully
+ authenticated user. It offers the most privacy, as no external handle
+ to the session exists outside of the authenticated realm.</p>
+
+ <p>Per user sessions work within a correctly configured authenticated
+ environment, be that using basic authentication, digest authentication
+ or SSL client certificates. Due to the limitations of who came first,
+ the chicken or the egg, per user sessions cannot be used to store
+ authentication credentials from a module like
+ <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>.</p>
+
+ <p>To create a simple per user session and store it in a postgres database
+ table called <var>apachesession</var>, and with the session keyed to the
+ userid, configure the session as follows:</p>
+
+ <div class="example"><h3>SQL based per user session</h3><pre class="prettyprint lang-config">Session On
+SessionDBDPerUser On</pre>
+</div>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="housekeeping" id="housekeeping">Database Housekeeping</a></h2>
+ <p>Over the course of time, the database can be expected to start accumulating
+ expired sessions. At this point, the <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code> module
+ is not yet able to handle session expiry automatically.</p>
+
+ <div class="warning"><h3>Warning</h3>
+ <p>The administrator will need to set up an external process via cron to clean
+ out expired sessions.</p>
+ </div>
+
+ </div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SessionDBDCookieName" id="SessionDBDCookieName">SessionDBDCookieName</a> <a name="sessiondbdcookiename" id="sessiondbdcookiename">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Name and attributes for the RFC2109 cookie storing the session ID</td></tr>
</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="dbdconfig" id="dbdconfig">DBD Configuration</a></h2>
-
- <p>Before the <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code> module can be configured to maintain a
- session, the <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> module must be configured to make the various database queries
- available to the server.</p>
-
- <p>There are four queries required to keep a session maintained, to select an existing session,
- to update an existing session, to insert a new session, and to delete an expired or empty
- session. These queries are configured as per the example below.</p>
-
- <div class="example"><h3>Sample DBD configuration</h3><pre class="prettyprint lang-config">DBDriver pgsql
-DBDParams "dbname=apachesession user=apache password=xxxxx host=localhost"
-DBDPrepareSQL "delete from session where key = %s" deletesession
-DBDPrepareSQL "update session set value = %s, expiry = %lld, key = %s where key = %s" updatesession
-DBDPrepareSQL "insert into session (value, expiry, key) values (%s, %lld, %s)" insertsession
-DBDPrepareSQL "select value from session where key = %s and (expiry = 0 or expiry > %lld)" selectsession
-DBDPrepareSQL "delete from session where expiry != 0 and expiry < %lld" cleansession</pre>
-</div>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="anonymous" id="anonymous">Anonymous Sessions</a></h2>
-
- <p>Anonymous sessions are keyed against a unique UUID, and stored on the
- browser within an HTTP cookie. This method is similar to that used by most
- application servers to store session information.</p>
-
- <p>To create a simple anonymous session and store it in a postgres database
- table called <var>apachesession</var>, and save the session ID in a cookie
- called <var>session</var>, configure the session as follows:</p>
-
- <div class="example"><h3>SQL based anonymous session</h3><pre class="prettyprint lang-config">Session On
-SessionDBDCookieName session path=/</pre>
-</div>
-
- <p>For more examples on how the session can be configured to be read
- from and written to by a CGI application, see the
- <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> examples section.</p>
-
- <p>For documentation on how the session can be used to store username
- and password details, see the <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> module.</p>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="peruser" id="peruser">Per User Sessions</a></h2>
-
- <p>Per user sessions are keyed against the username of a successfully
- authenticated user. It offers the most privacy, as no external handle
- to the session exists outside of the authenticated realm.</p>
-
- <p>Per user sessions work within a correctly configured authenticated
- environment, be that using basic authentication, digest authentication
- or SSL client certificates. Due to the limitations of who came first,
- the chicken or the egg, per user sessions cannot be used to store
- authentication credentials from a module like
- <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>.</p>
-
- <p>To create a simple per user session and store it in a postgres database
- table called <var>apachesession</var>, and with the session keyed to the
- userid, configure the session as follows:</p>
-
- <div class="example"><h3>SQL based per user session</h3><pre class="prettyprint lang-config">Session On
-SessionDBDPerUser On</pre>
-</div>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="housekeeping" id="housekeeping">Database Housekeeping</a></h2>
- <p>Over the course of time, the database can be expected to start accumulating
- expired sessions. At this point, the <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code> module
- is not yet able to handle session expiry automatically.</p>
-
- <div class="warning"><h3>Warning</h3>
- <p>The administrator will need to set up an external process via cron to clean
- out expired sessions.</p>
- </div>
-
- </div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_session_dbd.html" title="English"> en </a> |
<ul class="seealso">
<li><a href="../env.html">Environment Variables in Apache HTTP Server</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="BrowserMatch" id="BrowserMatch">BrowserMatch</a> <a name="browsermatch" id="browsermatch">Directive</a></h2>
<table class="directive">
combination.</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_setenvif.html" title="English"> en </a> |
version.</p>
</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#windows">Creating Loadable Modules for Windows</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#loadfile">LoadFile</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#loadmodule">LoadModule</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#windows">Creating Loadable Modules for Windows</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LoadFile" id="LoadFile">LoadFile</a> <a name="loadfile" id="loadfile">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Link in the named object file or library</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LoadFile <em>filename</em> [<em>filename</em>] ...</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_so</td></tr>
-</table>
-
- <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>
-
- <p>For example:</p>
-
- <pre class="prettyprint lang-config">LoadFile libexec/libxmlparse.so</pre>
-
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="LoadModule" id="LoadModule">LoadModule</a> <a name="loadmodule" id="loadmodule">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Links in the object file or library, and adds to the list
-of active modules</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LoadModule <em>module filename</em></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_so</td></tr>
-</table>
- <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>
-
- <pre class="prettyprint lang-config">LoadModule status_module modules/mod_status.so</pre>
-
-
- <p>loads the named module from the modules subdirectory of the
- ServerRoot.</p>
-
-</div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="windows" id="windows">Creating Loadable Modules for Windows</a></h2>
root, and use the <code class="directive">LoadModule</code>
directive to load it.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LoadFile" id="LoadFile">LoadFile</a> <a name="loadfile" id="loadfile">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Link in the named object file or library</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LoadFile <em>filename</em> [<em>filename</em>] ...</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_so</td></tr>
+</table>
+
+ <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>
+
+ <p>For example:</p>
+
+ <pre class="prettyprint lang-config">LoadFile libexec/libxmlparse.so</pre>
+
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="LoadModule" id="LoadModule">LoadModule</a> <a name="loadmodule" id="loadmodule">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Links in the object file or library, and adds to the list
+of active modules</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LoadModule <em>module filename</em></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_so</td></tr>
+</table>
+ <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>
+
+ <pre class="prettyprint lang-config">LoadModule status_module modules/mod_status.so</pre>
+
+
+ <p>loads the named module from the modules subdirectory of the
+ ServerRoot.</p>
+
</div>
</div>
<div class="bottomlang">
<li><img alt="" src="../images/down.gif" /> <a href="#checkspelling">CheckSpelling</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CheckCaseOnly" id="CheckCaseOnly">CheckCaseOnly</a> <a name="checkcaseonly" id="checkcaseonly">Directive</a></h2>
<table class="directive">
</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_speling.html" title="English"> en </a> |
<p>Further details, discussion, and examples are provided in the
<a href="../ssl/">SSL documentation</a>.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#envvars">Environment Variables</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#logformats">Custom Log Formats</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#notes">Request Notes</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#authzproviders">Authorization providers for use with Require</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#sslcacertificatefile">SSLCACertificateFile</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sslcacertificatepath">SSLCACertificatePath</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sslverifyclient">SSLVerifyClient</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sslverifydepth">SSLVerifyDepth</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#envvars">Environment Variables</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#logformats">Custom Log Formats</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#notes">Request Notes</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#authzproviders">Authorization providers for use with Require</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="envvars" id="envvars">Environment Variables</a></h2>
+
+<p>This module can be configured to provide several items of SSL information
+as additional environment variables to the SSI and CGI namespace. This
+information is not provided by default for performance reasons. (See
+<code class="directive">SSLOptions</code> StdEnvVars, below.) The generated variables
+are listed in the table below. For backward compatibility the information can
+be made available under different names, too. Look in the <a href="../ssl/ssl_compat.html">Compatibility</a> chapter for details on the
+compatibility variables.</p>
+
+<table class="bordered">
+
+<tr>
+ <th><a name="table3">Variable Name:</a></th>
+ <th>Value Type:</th>
+ <th>Description:</th>
+</tr>
+<tr><td><code>HTTPS</code></td> <td>flag</td> <td>HTTPS is being used.</td></tr>
+<tr><td><code>SSL_PROTOCOL</code></td> <td>string</td> <td>The SSL protocol version (SSLv3, TLSv1, TLSv1.1, TLSv1.2)</td></tr>
+<tr><td><code>SSL_SESSION_ID</code></td> <td>string</td> <td>The hex-encoded SSL session id</td></tr>
+<tr><td><code>SSL_SESSION_RESUMED</code></td> <td>string</td> <td>Initial or Resumed SSL Session. Note: multiple requests may be served over the same (Initial or Resumed) SSL session if HTTP KeepAlive is in use</td></tr>
+<tr><td><code>SSL_SECURE_RENEG</code></td> <td>string</td> <td><code>true</code> if secure renegotiation is supported, else <code>false</code></td></tr>
+<tr><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The cipher specification name</td></tr>
+<tr><td><code>SSL_CIPHER_EXPORT</code></td> <td>string</td> <td><code>true</code> if cipher is an export cipher</td></tr>
+<tr><td><code>SSL_CIPHER_USEKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (actually used)</td></tr>
+<tr><td><code>SSL_CIPHER_ALGKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (possible)</td></tr>
+<tr><td><code>SSL_COMPRESS_METHOD</code></td> <td>string</td> <td>SSL compression method negotiated</td></tr>
+<tr><td><code>SSL_VERSION_INTERFACE</code></td> <td>string</td> <td>The mod_ssl program version</td></tr>
+<tr><td><code>SSL_VERSION_LIBRARY</code></td> <td>string</td> <td>The OpenSSL program version</td></tr>
+<tr><td><code>SSL_CLIENT_M_VERSION</code></td> <td>string</td> <td>The version of the client certificate</td></tr>
+<tr><td><code>SSL_CLIENT_M_SERIAL</code></td> <td>string</td> <td>The serial of the client certificate</td></tr>
+<tr><td><code>SSL_CLIENT_S_DN</code></td> <td>string</td> <td>Subject DN in client's certificate</td></tr>
+<tr><td><code>SSL_CLIENT_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Subject DN</td></tr>
+<tr><td><code>SSL_CLIENT_I_DN</code></td> <td>string</td> <td>Issuer DN of client's certificate</td></tr>
+<tr><td><code>SSL_CLIENT_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Issuer DN</td></tr>
+<tr><td><code>SSL_CLIENT_V_START</code></td> <td>string</td> <td>Validity of client's certificate (start time)</td></tr>
+<tr><td><code>SSL_CLIENT_V_END</code></td> <td>string</td> <td>Validity of client's certificate (end time)</td></tr>
+<tr><td><code>SSL_CLIENT_V_REMAIN</code></td> <td>string</td> <td>Number of days until client's certificate expires</td></tr>
+<tr><td><code>SSL_CLIENT_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of client's certificate</td></tr>
+<tr><td><code>SSL_CLIENT_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of client's certificate</td></tr>
+<tr><td><code>SSL_CLIENT_CERT</code></td> <td>string</td> <td>PEM-encoded client certificate</td></tr>
+<tr><td><code>SSL_CLIENT_CERT_CHAIN_</code><em>n</em></td> <td>string</td> <td>PEM-encoded certificates in client certificate chain</td></tr>
+<tr><td><code>SSL_CLIENT_CERT_RFC4523_CEA</code></td> <td>string</td> <td>Serial number and issuer of the certificate. The format matches that of the CertificateExactAssertion in RFC4523</td></tr>
+<tr><td><code>SSL_CLIENT_VERIFY</code></td> <td>string</td> <td><code>NONE</code>, <code>SUCCESS</code>, <code>GENEROUS</code> or <code>FAILED:</code><em>reason</em></td></tr>
+<tr><td><code>SSL_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr>
+<tr><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr>
+<tr><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr>
+<tr><td><code>SSL_SERVER_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Subject DN</td></tr>
+<tr><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr>
+<tr><td><code>SSL_SERVER_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Issuer DN</td></tr>
+<tr><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr>
+<tr><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr>
+<tr><td><code>SSL_SERVER_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of server's certificate</td></tr>
+<tr><td><code>SSL_SERVER_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of server's certificate</td></tr>
+<tr><td><code>SSL_SERVER_CERT</code></td> <td>string</td> <td>PEM-encoded server certificate</td></tr>
+<tr><td><code>SSL_SRP_USER</code></td> <td>string</td> <td>SRP username</td></tr>
+<tr><td><code>SSL_SRP_USERINFO</code></td> <td>string</td> <td>SRP user info</td></tr>
+<tr><td><code>SSL_TLS_SNI</code></td> <td>string</td> <td>Contents of the SNI TLS extension (if supplied with ClientHello)</td></tr>
+</table>
+
+<p><em>x509</em> specifies a component of an X.509 DN; one of
+<code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code>. In Apache 2.1 and
+later, <em>x509</em> may also include a numeric <code>_n</code>
+suffix. If the DN in question contains multiple attributes of the
+same name, this suffix is used as a zero-based index to select a
+particular attribute. For example, where the server certificate
+subject DN included two OU attributes, <code>SSL_SERVER_S_DN_OU_0</code>
+and
+<code>SSL_SERVER_S_DN_OU_1</code> could be used to reference each. A
+variable name without a <code>_n</code> suffix is equivalent to that
+name with a <code>_0</code> suffix; the first (or only) attribute.
+When the environment table is populated using
+the <code>StdEnvVars</code> option of
+the <code class="directive"><a href="#ssloptions">SSLOptions</a></code> directive, the
+first (or only) attribute of any DN is added only under a non-suffixed
+name; i.e. no <code>_0</code> suffixed entries are added.</p>
+
+<p>The format of the <em>*_DN</em> variables has changed in Apache HTTPD
+2.3.11. See the <code>LegacyDNStringFormat</code> option for
+<code class="directive"><a href="#ssloptions">SSLOptions</a></code> for details.</p>
+
+<p><code>SSL_CLIENT_V_REMAIN</code> is only available in version 2.1
+and later.</p>
+
+<p>A number of additional environment variables can also be used
+in <code class="directive">SSLRequire</code> expressions, or in custom log
+formats:</p>
+
+<div class="note"><pre>HTTP_USER_AGENT PATH_INFO AUTH_TYPE
+HTTP_REFERER QUERY_STRING SERVER_SOFTWARE
+HTTP_COOKIE REMOTE_HOST API_VERSION
+HTTP_FORWARDED REMOTE_IDENT TIME_YEAR
+HTTP_HOST IS_SUBREQ TIME_MON
+HTTP_PROXY_CONNECTION DOCUMENT_ROOT TIME_DAY
+HTTP_ACCEPT SERVER_ADMIN TIME_HOUR
+THE_REQUEST SERVER_NAME TIME_MIN
+REQUEST_FILENAME SERVER_PORT TIME_SEC
+REQUEST_METHOD SERVER_PROTOCOL TIME_WDAY
+REQUEST_SCHEME REMOTE_ADDR TIME
+REQUEST_URI REMOTE_USER</pre></div>
+
+<p>In these contexts, two special formats can also be used:</p>
+
+<dl>
+ <dt><code>ENV:<em>variablename</em></code></dt>
+ <dd>This will expand to the standard environment
+ variable <em>variablename</em>.</dd>
+
+ <dt><code>HTTP:<em>headername</em></code></dt>
+ <dd>This will expand to the value of the request header with name
+ <em>headername</em>.</dd>
+</dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="logformats" id="logformats">Custom Log Formats</a></h2>
+
+<p>When <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is built into Apache or at least
+loaded (under DSO situation) additional functions exist for the <a href="mod_log_config.html#formats">Custom Log Format</a> of
+<code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>. First there is an
+additional ``<code>%{</code><em>varname</em><code>}x</code>''
+eXtension format function which can be used to expand any variables
+provided by any module, especially those provided by mod_ssl which can
+you find in the above table.</p>
+<p>
+For backward compatibility there is additionally a special
+``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function
+provided. Information about this function is provided in the <a href="../ssl/ssl_compat.html">Compatibility</a> chapter.</p>
+<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">CustomLog "logs/ssl_request_log" "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"</pre>
+</div>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="notes" id="notes">Request Notes</a></h2>
+
+<p><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> sets "notes" for the request which can be
+used in logging with the <code>%{<em>name</em>}n</code> format
+string in <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>.</p>
+
+<p>The notes supported are as follows:</p>
+
+<dl>
+ <dt><code>ssl-access-forbidden</code></dt>
+ <dd>This note is set to the value <code>1</code> if access was
+ denied due to an <code class="directive">SSLRequire</code>
+ or <code class="directive">SSLRequireSSL</code> directive.</dd>
+
+ <dt><code>ssl-secure-reneg</code></dt>
+ <dd>If <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is built against a version of
+ OpenSSL which supports the secure renegotiation extension, this note
+ is set to the value <code>1</code> if SSL is in used for the current
+ connection, and the client also supports the secure renegotiation
+ extension. If the client does not support the secure renegotiation
+ extension, the note is set to the value <code>0</code>.
+ If <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is not built against a version of
+ OpenSSL which supports secure renegotiation, or if SSL is not in use
+ for the current connection, the note is not set.</dd>
+</dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="authzproviders" id="authzproviders">Authorization providers for use with Require</a></h2>
+
+ <p><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> provides a few authentication providers for use
+ with <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code>'s
+ <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive.</p>
+
+ <h3><a name="reqssl" id="reqssl">Require ssl</a></h3>
+
+ <p>The <code>ssl</code> provider denies access if a connection is not
+ encrypted with SSL. This is similar to the
+ <code class="directive">SSLRequireSSL</code> directive.</p>
+
+ <pre class="prettyprint lang-config">Require ssl</pre>
+
+
+
+
+ <h3><a name="reqverifyclient" id="reqverifyclient">Require ssl-verify-client</a></h3>
+
+ <p>The <code>ssl</code> provider allows access if the user is
+ authenticated with a valid client certificate. This is only
+ useful if <code>SSLVerifyClient optional</code> is in effect.</p>
+
+ <p>The following example grants access if the user is authenticated
+ either with a client certificate or by username and password.</p>
+
+ <pre class="prettyprint lang-config"> Require ssl-verify-client<br />
+ Require valid-user</pre>
+
+
+
+
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SSLCACertificateFile" id="SSLCACertificateFile">SSLCACertificateFile</a> <a name="sslcacertificatefile" id="sslcacertificatefile">Directive</a></h2>
<table class="directive">
<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLVerifyDepth 10</pre>
</div>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="envvars" id="envvars">Environment Variables</a></h2>
-
-<p>This module can be configured to provide several items of SSL information
-as additional environment variables to the SSI and CGI namespace. This
-information is not provided by default for performance reasons. (See
-<code class="directive">SSLOptions</code> StdEnvVars, below.) The generated variables
-are listed in the table below. For backward compatibility the information can
-be made available under different names, too. Look in the <a href="../ssl/ssl_compat.html">Compatibility</a> chapter for details on the
-compatibility variables.</p>
-
-<table class="bordered">
-
-<tr>
- <th><a name="table3">Variable Name:</a></th>
- <th>Value Type:</th>
- <th>Description:</th>
-</tr>
-<tr><td><code>HTTPS</code></td> <td>flag</td> <td>HTTPS is being used.</td></tr>
-<tr><td><code>SSL_PROTOCOL</code></td> <td>string</td> <td>The SSL protocol version (SSLv3, TLSv1, TLSv1.1, TLSv1.2)</td></tr>
-<tr><td><code>SSL_SESSION_ID</code></td> <td>string</td> <td>The hex-encoded SSL session id</td></tr>
-<tr><td><code>SSL_SESSION_RESUMED</code></td> <td>string</td> <td>Initial or Resumed SSL Session. Note: multiple requests may be served over the same (Initial or Resumed) SSL session if HTTP KeepAlive is in use</td></tr>
-<tr><td><code>SSL_SECURE_RENEG</code></td> <td>string</td> <td><code>true</code> if secure renegotiation is supported, else <code>false</code></td></tr>
-<tr><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The cipher specification name</td></tr>
-<tr><td><code>SSL_CIPHER_EXPORT</code></td> <td>string</td> <td><code>true</code> if cipher is an export cipher</td></tr>
-<tr><td><code>SSL_CIPHER_USEKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (actually used)</td></tr>
-<tr><td><code>SSL_CIPHER_ALGKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (possible)</td></tr>
-<tr><td><code>SSL_COMPRESS_METHOD</code></td> <td>string</td> <td>SSL compression method negotiated</td></tr>
-<tr><td><code>SSL_VERSION_INTERFACE</code></td> <td>string</td> <td>The mod_ssl program version</td></tr>
-<tr><td><code>SSL_VERSION_LIBRARY</code></td> <td>string</td> <td>The OpenSSL program version</td></tr>
-<tr><td><code>SSL_CLIENT_M_VERSION</code></td> <td>string</td> <td>The version of the client certificate</td></tr>
-<tr><td><code>SSL_CLIENT_M_SERIAL</code></td> <td>string</td> <td>The serial of the client certificate</td></tr>
-<tr><td><code>SSL_CLIENT_S_DN</code></td> <td>string</td> <td>Subject DN in client's certificate</td></tr>
-<tr><td><code>SSL_CLIENT_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Subject DN</td></tr>
-<tr><td><code>SSL_CLIENT_I_DN</code></td> <td>string</td> <td>Issuer DN of client's certificate</td></tr>
-<tr><td><code>SSL_CLIENT_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Issuer DN</td></tr>
-<tr><td><code>SSL_CLIENT_V_START</code></td> <td>string</td> <td>Validity of client's certificate (start time)</td></tr>
-<tr><td><code>SSL_CLIENT_V_END</code></td> <td>string</td> <td>Validity of client's certificate (end time)</td></tr>
-<tr><td><code>SSL_CLIENT_V_REMAIN</code></td> <td>string</td> <td>Number of days until client's certificate expires</td></tr>
-<tr><td><code>SSL_CLIENT_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of client's certificate</td></tr>
-<tr><td><code>SSL_CLIENT_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of client's certificate</td></tr>
-<tr><td><code>SSL_CLIENT_CERT</code></td> <td>string</td> <td>PEM-encoded client certificate</td></tr>
-<tr><td><code>SSL_CLIENT_CERT_CHAIN_</code><em>n</em></td> <td>string</td> <td>PEM-encoded certificates in client certificate chain</td></tr>
-<tr><td><code>SSL_CLIENT_CERT_RFC4523_CEA</code></td> <td>string</td> <td>Serial number and issuer of the certificate. The format matches that of the CertificateExactAssertion in RFC4523</td></tr>
-<tr><td><code>SSL_CLIENT_VERIFY</code></td> <td>string</td> <td><code>NONE</code>, <code>SUCCESS</code>, <code>GENEROUS</code> or <code>FAILED:</code><em>reason</em></td></tr>
-<tr><td><code>SSL_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr>
-<tr><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr>
-<tr><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr>
-<tr><td><code>SSL_SERVER_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Subject DN</td></tr>
-<tr><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr>
-<tr><td><code>SSL_SERVER_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Issuer DN</td></tr>
-<tr><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr>
-<tr><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr>
-<tr><td><code>SSL_SERVER_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of server's certificate</td></tr>
-<tr><td><code>SSL_SERVER_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of server's certificate</td></tr>
-<tr><td><code>SSL_SERVER_CERT</code></td> <td>string</td> <td>PEM-encoded server certificate</td></tr>
-<tr><td><code>SSL_SRP_USER</code></td> <td>string</td> <td>SRP username</td></tr>
-<tr><td><code>SSL_SRP_USERINFO</code></td> <td>string</td> <td>SRP user info</td></tr>
-<tr><td><code>SSL_TLS_SNI</code></td> <td>string</td> <td>Contents of the SNI TLS extension (if supplied with ClientHello)</td></tr>
-</table>
-
-<p><em>x509</em> specifies a component of an X.509 DN; one of
-<code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code>. In Apache 2.1 and
-later, <em>x509</em> may also include a numeric <code>_n</code>
-suffix. If the DN in question contains multiple attributes of the
-same name, this suffix is used as a zero-based index to select a
-particular attribute. For example, where the server certificate
-subject DN included two OU attributes, <code>SSL_SERVER_S_DN_OU_0</code>
-and
-<code>SSL_SERVER_S_DN_OU_1</code> could be used to reference each. A
-variable name without a <code>_n</code> suffix is equivalent to that
-name with a <code>_0</code> suffix; the first (or only) attribute.
-When the environment table is populated using
-the <code>StdEnvVars</code> option of
-the <code class="directive"><a href="#ssloptions">SSLOptions</a></code> directive, the
-first (or only) attribute of any DN is added only under a non-suffixed
-name; i.e. no <code>_0</code> suffixed entries are added.</p>
-
-<p>The format of the <em>*_DN</em> variables has changed in Apache HTTPD
-2.3.11. See the <code>LegacyDNStringFormat</code> option for
-<code class="directive"><a href="#ssloptions">SSLOptions</a></code> for details.</p>
-
-<p><code>SSL_CLIENT_V_REMAIN</code> is only available in version 2.1
-and later.</p>
-
-<p>A number of additional environment variables can also be used
-in <code class="directive">SSLRequire</code> expressions, or in custom log
-formats:</p>
-
-<div class="note"><pre>HTTP_USER_AGENT PATH_INFO AUTH_TYPE
-HTTP_REFERER QUERY_STRING SERVER_SOFTWARE
-HTTP_COOKIE REMOTE_HOST API_VERSION
-HTTP_FORWARDED REMOTE_IDENT TIME_YEAR
-HTTP_HOST IS_SUBREQ TIME_MON
-HTTP_PROXY_CONNECTION DOCUMENT_ROOT TIME_DAY
-HTTP_ACCEPT SERVER_ADMIN TIME_HOUR
-THE_REQUEST SERVER_NAME TIME_MIN
-REQUEST_FILENAME SERVER_PORT TIME_SEC
-REQUEST_METHOD SERVER_PROTOCOL TIME_WDAY
-REQUEST_SCHEME REMOTE_ADDR TIME
-REQUEST_URI REMOTE_USER</pre></div>
-
-<p>In these contexts, two special formats can also be used:</p>
-
-<dl>
- <dt><code>ENV:<em>variablename</em></code></dt>
- <dd>This will expand to the standard environment
- variable <em>variablename</em>.</dd>
-
- <dt><code>HTTP:<em>headername</em></code></dt>
- <dd>This will expand to the value of the request header with name
- <em>headername</em>.</dd>
-</dl>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="logformats" id="logformats">Custom Log Formats</a></h2>
-
-<p>When <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is built into Apache or at least
-loaded (under DSO situation) additional functions exist for the <a href="mod_log_config.html#formats">Custom Log Format</a> of
-<code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>. First there is an
-additional ``<code>%{</code><em>varname</em><code>}x</code>''
-eXtension format function which can be used to expand any variables
-provided by any module, especially those provided by mod_ssl which can
-you find in the above table.</p>
-<p>
-For backward compatibility there is additionally a special
-``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function
-provided. Information about this function is provided in the <a href="../ssl/ssl_compat.html">Compatibility</a> chapter.</p>
-<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">CustomLog "logs/ssl_request_log" "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"</pre>
-</div>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="notes" id="notes">Request Notes</a></h2>
-
-<p><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> sets "notes" for the request which can be
-used in logging with the <code>%{<em>name</em>}n</code> format
-string in <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>.</p>
-
-<p>The notes supported are as follows:</p>
-
-<dl>
- <dt><code>ssl-access-forbidden</code></dt>
- <dd>This note is set to the value <code>1</code> if access was
- denied due to an <code class="directive">SSLRequire</code>
- or <code class="directive">SSLRequireSSL</code> directive.</dd>
-
- <dt><code>ssl-secure-reneg</code></dt>
- <dd>If <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is built against a version of
- OpenSSL which supports the secure renegotiation extension, this note
- is set to the value <code>1</code> if SSL is in used for the current
- connection, and the client also supports the secure renegotiation
- extension. If the client does not support the secure renegotiation
- extension, the note is set to the value <code>0</code>.
- If <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is not built against a version of
- OpenSSL which supports secure renegotiation, or if SSL is not in use
- for the current connection, the note is not set.</dd>
-</dl>
-
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="authzproviders" id="authzproviders">Authorization providers for use with Require</a></h2>
-
- <p><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> provides a few authentication providers for use
- with <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code>'s
- <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive.</p>
-
- <h3><a name="reqssl" id="reqssl">Require ssl</a></h3>
-
- <p>The <code>ssl</code> provider denies access if a connection is not
- encrypted with SSL. This is similar to the
- <code class="directive">SSLRequireSSL</code> directive.</p>
-
- <pre class="prettyprint lang-config">Require ssl</pre>
-
-
-
-
- <h3><a name="reqverifyclient" id="reqverifyclient">Require ssl-verify-client</a></h3>
-
- <p>The <code>ssl</code> provider allows access if the user is
- authenticated with a valid client certificate. This is only
- useful if <code>SSLVerifyClient optional</code> is in effect.</p>
-
- <p>The following example grants access if the user is authenticated
- either with a client certificate or by username and password.</p>
-
- <pre class="prettyprint lang-config"> Require ssl-verify-client<br />
- Require valid-user</pre>
-
-
-
-
</div>
</div>
<div class="bottomlang">
toggle <code class="directive"><a href="../mod/core.html#extendedstatus">ExtendedStatus</a></code> On
by default.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#enable">Enabling Status Support</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#autoupdate">Automatic Updates</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#machinereadable">Machine Readable Status File</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#troubleshoot">Using server-status to troubleshoot</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="enable" id="enable">Enabling Status Support</a></h2>
<li><img alt="" src="../images/down.gif" /> <a href="#substitutemaxlinelength">SubstituteMaxLineLength</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="Substitute" id="Substitute">Substitute</a> <a name="substitute" id="substitute">Directive</a></h2>
<table class="directive">
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_substitute.html" title="English"> en </a> |
<ul class="seealso">
<li><a href="../suexec.html">SuEXEC support</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SuexecUserGroup" id="SuexecUserGroup">SuexecUserGroup</a> <a name="suexecusergroup" id="suexecusergroup">Directive</a></h2>
<table class="directive">
<li><code class="directive"><a href="../mod/mod_unixd.html#suexec">Suexec</a></code></li>
</ul>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_suexec.html" title="English"> en </a> |
useful for various reasons which are beyond the scope of this
document.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#theory">Theory</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+</ul><h3 class="directives">Directives</h3>
+<p>This module provides no
+ directives.</p>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="theory" id="theory">Theory</a></h2>
<ul class="seealso">
<li><a href="../suexec.html">suEXEC support</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ChrootDir" id="ChrootDir">ChrootDir</a> <a name="chrootdir" id="chrootdir">Directive</a></h2>
<table class="directive">
<li><code class="directive"><a href="../mod/mod_suexec.html#suexecusergroup">SuexecUserGroup</a></code></li>
</ul>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_unixd.html" title="English"> en </a> |
<li><a href="../howto/public_html.html">public_html
tutorial</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="UserDir" id="UserDir">UserDir</a> <a name="userdir" id="userdir">Directive</a></h2>
<table class="directive">
</li>
</ul>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_userdir.html" title="English"> en </a> |
<p>Provides tracking of a user through your website via browser
cookies.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#cookiedomain">CookieDomain</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cookieexpires">CookieExpires</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cookiestyle">CookieStyle</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cookietracking">CookieTracking</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="logging" id="logging">Logging</a></h2>
+
+
+ <p><code class="module"><a href="../mod/mod_usertrack.html">mod_usertrack</a></code> sets a cookie which can be logged
+ via <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code> configurable logging formats:</p>
+
+ <pre class="prettyprint lang-config">LogFormat "%{Apache}n %r %t" usertrack
+CustomLog logs/clickstream.log usertrack</pre>
+
+
+</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CookieDomain" id="CookieDomain">CookieDomain</a> <a name="cookiedomain" id="cookiedomain">Directive</a></h2>
<table class="directive">
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="logging" id="logging">Logging</a></h2>
-
-
- <p><code class="module"><a href="../mod/mod_usertrack.html">mod_usertrack</a></code> sets a cookie which can be logged
- via <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code> configurable logging formats:</p>
-
- <pre class="prettyprint lang-config">LogFormat "%{Apache}n %r %t" usertrack
-CustomLog logs/clickstream.log usertrack</pre>
-
-
</div>
</div>
<div class="bottomlang">
<li><img alt="" src="../images/down.gif" /> <a href="#ifversion"><IfVersion></a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="IfVersion" id="IfVersion"><IfVersion></a> <a name="ifversion" id="ifversion">Directive</a></h2>
<table class="directive">
<code>=</code>.</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_version.html" title="English"> en </a> |
</div>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#interpol">Directory Name Interpolation</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#virtualdocumentroot">VirtualDocumentRoot</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#virtualdocumentrootip">VirtualDocumentRootIP</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#virtualscriptalias">VirtualScriptAlias</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#virtualscriptaliasip">VirtualScriptAliasIP</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#interpol">Directory Name Interpolation</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code></li>
<li><a href="../vhosts/mass.html">Dynamically configured mass
virtual hosting</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="VirtualDocumentRoot" id="VirtualDocumentRoot">VirtualDocumentRoot</a> <a name="virtualdocumentroot" id="virtualdocumentroot">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Dynamically configure the location of the document root
-for a given virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>VirtualDocumentRoot <em>interpolated-directory</em>|none</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>VirtualDocumentRoot none</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_vhost_alias</td></tr>
-</table>
-
- <p>The <code class="directive">VirtualDocumentRoot</code> directive allows you to
- determine where Apache HTTP Server 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 <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> directive's argument.
- If <em>interpolated-directory</em> is <code>none</code> then
- <code class="directive">VirtualDocumentRoot</code> is turned off. This directive
- cannot be used in the same context as <code class="directive"><a href="#virtualdocumentrootip">VirtualDocumentRootIP</a></code>.</p>
-
-<div class="warning"><h3>Note</h3>
-<code class="directive">VirtualDocumentRoot</code> will override any <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> directives you may have put in the same
-context or child contexts. Putting a <code class="directive">VirtualDocumentRoot</code>
-in the global server scope will effectively override <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> directives in any virtual hosts defined later
-on, unless you set <code class="directive">VirtualDocumentRoot</code> to <code>None</code>
-in each virtual host.
-</div>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="VirtualDocumentRootIP" id="VirtualDocumentRootIP">VirtualDocumentRootIP</a> <a name="virtualdocumentrootip" id="virtualdocumentrootip">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Dynamically configure the location of the document root
-for a given virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>VirtualDocumentRootIP <em>interpolated-directory</em>|none</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>VirtualDocumentRootIP none</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_vhost_alias</td></tr>
-</table>
-
-<p>The <code class="directive">VirtualDocumentRootIP</code> directive is like the
- <code class="directive"><a href="#virtualdocumentroot">VirtualDocumentRoot</a></code>
- directive, except that it uses the IP address of the server end
- of the connection for directory interpolation instead of the server
- name.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="VirtualScriptAlias" id="VirtualScriptAlias">VirtualScriptAlias</a> <a name="virtualscriptalias" id="virtualscriptalias">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Dynamically configure the location of the CGI directory for
-a given virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>VirtualScriptAlias <em>interpolated-directory</em>|none</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>VirtualScriptAlias none</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_vhost_alias</td></tr>
-</table>
-
- <p>The <code class="directive">VirtualScriptAlias</code> directive allows you to
- determine where Apache httpd will find CGI scripts in a similar
- manner to <code class="directive"><a href="#virtualdocumentroot">VirtualDocumentRoot</a></code> does for other documents. It matches
- requests for URIs starting <code>/cgi-bin/</code>, much like <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
- <code>/cgi-bin/</code> would.</p>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="VirtualScriptAliasIP" id="VirtualScriptAliasIP">VirtualScriptAliasIP</a> <a name="virtualscriptaliasip" id="virtualscriptaliasip">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Dynamically configure the location of the CGI directory for
-a given virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>VirtualScriptAliasIP <em>interpolated-directory</em>|none</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>VirtualScriptAliasIP none</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_vhost_alias</td></tr>
-</table>
-
- <p>The <code class="directive">VirtualScriptAliasIP</code> directive is like the
- <code class="directive"><a href="#virtualscriptalias">VirtualScriptAlias</a></code>
- directive, except that it uses the IP address of the server end
- of the connection for directory interpolation instead of the server
- name.</p>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="interpol" id="interpol">Directory Name Interpolation</a></h2>
<p>The <code class="directive"><a href="../mod/mod_log_config.html#logformat">LogFormat</a></code>
directives <code>%V</code> and <code>%A</code> are useful
in conjunction with this module.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="VirtualDocumentRoot" id="VirtualDocumentRoot">VirtualDocumentRoot</a> <a name="virtualdocumentroot" id="virtualdocumentroot">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Dynamically configure the location of the document root
+for a given virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>VirtualDocumentRoot <em>interpolated-directory</em>|none</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>VirtualDocumentRoot none</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_vhost_alias</td></tr>
+</table>
+
+ <p>The <code class="directive">VirtualDocumentRoot</code> directive allows you to
+ determine where Apache HTTP Server 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 <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> directive's argument.
+ If <em>interpolated-directory</em> is <code>none</code> then
+ <code class="directive">VirtualDocumentRoot</code> is turned off. This directive
+ cannot be used in the same context as <code class="directive"><a href="#virtualdocumentrootip">VirtualDocumentRootIP</a></code>.</p>
+
+<div class="warning"><h3>Note</h3>
+<code class="directive">VirtualDocumentRoot</code> will override any <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> directives you may have put in the same
+context or child contexts. Putting a <code class="directive">VirtualDocumentRoot</code>
+in the global server scope will effectively override <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> directives in any virtual hosts defined later
+on, unless you set <code class="directive">VirtualDocumentRoot</code> to <code>None</code>
+in each virtual host.
+</div>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="VirtualDocumentRootIP" id="VirtualDocumentRootIP">VirtualDocumentRootIP</a> <a name="virtualdocumentrootip" id="virtualdocumentrootip">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Dynamically configure the location of the document root
+for a given virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>VirtualDocumentRootIP <em>interpolated-directory</em>|none</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>VirtualDocumentRootIP none</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_vhost_alias</td></tr>
+</table>
+
+<p>The <code class="directive">VirtualDocumentRootIP</code> directive is like the
+ <code class="directive"><a href="#virtualdocumentroot">VirtualDocumentRoot</a></code>
+ directive, except that it uses the IP address of the server end
+ of the connection for directory interpolation instead of the server
+ name.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="VirtualScriptAlias" id="VirtualScriptAlias">VirtualScriptAlias</a> <a name="virtualscriptalias" id="virtualscriptalias">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Dynamically configure the location of the CGI directory for
+a given virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>VirtualScriptAlias <em>interpolated-directory</em>|none</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>VirtualScriptAlias none</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_vhost_alias</td></tr>
+</table>
+
+ <p>The <code class="directive">VirtualScriptAlias</code> directive allows you to
+ determine where Apache httpd will find CGI scripts in a similar
+ manner to <code class="directive"><a href="#virtualdocumentroot">VirtualDocumentRoot</a></code> does for other documents. It matches
+ requests for URIs starting <code>/cgi-bin/</code>, much like <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
+ <code>/cgi-bin/</code> would.</p>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="VirtualScriptAliasIP" id="VirtualScriptAliasIP">VirtualScriptAliasIP</a> <a name="virtualscriptaliasip" id="virtualscriptaliasip">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Dynamically configure the location of the CGI directory for
+a given virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>VirtualScriptAliasIP <em>interpolated-directory</em>|none</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>VirtualScriptAliasIP none</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_vhost_alias</td></tr>
+</table>
+
+ <p>The <code class="directive">VirtualScriptAliasIP</code> directive is like the
+ <code class="directive"><a href="#virtualscriptalias">VirtualScriptAlias</a></code>
+ directive, except that it uses the IP address of the server end
+ of the connection for directory interpolation instead of the server
+ name.</p>
+
+
</div>
</div>
<div class="bottomlang">
<li><img alt="" src="../images/down.gif" /> <a href="#watchdoginterval">WatchdogInterval</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WatchdogInterval" id="WatchdogInterval">WatchdogInterval</a> <a name="watchdoginterval" id="watchdoginterval">Directive</a></h2>
<table class="directive">
second.</p>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_watchdog.html" title="English"> en </a></p>
after markup processing, and will ensure the correct <var>charset</var>
value is set in the HTTP <var>Content-Type</var> header.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
-<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#xml2encalias">xml2EncAlias</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#xml2encdefault">xml2EncDefault</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#xml2startparse">xml2StartParse</a></li>
-</ul>
-<h3>Topics</h3>
+<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#api">Programming API</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sniffing">Detecting an Encoding</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#output">Output Encoding</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#alias">Unsupported Encodings</a></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="xml2EncAlias" id="xml2EncAlias">xml2EncAlias</a> <a name="xml2encalias" id="xml2encalias">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Recognise Aliases for encoding values</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>xml2EncAlias <var>charset alias [alias ...]</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_xml2enc</td></tr>
-</table>
- <p>This server-wide directive aliases one or more encoding to another
- encoding. This enables encodings not recognised by libxml2 to be handled
- internally by libxml2's encoding support using the translation table for
- a recognised encoding. This serves two purposes: to support character sets
- (or names) not recognised either by libxml2 or iconv, and to skip
- conversion for an encoding where it is known to be unnecessary.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="xml2EncDefault" id="xml2EncDefault">xml2EncDefault</a> <a name="xml2encdefault" id="xml2encdefault">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets a default encoding to assume when absolutely no information
-can be <a href="#sniffing">automatically detected</a></td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>xml2EncDefault <var>name</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_xml2enc</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Version 2.4.0 and later; available as a third-party
-module for earlier versions.</td></tr>
-</table>
- <p>If you are processing data with known encoding but no encoding
- information, you can set this default to help mod_xml2enc process
- the data correctly. For example, to work with the default value
- of Latin1 (<var>iso-8859-1</var> specified in HTTP/1.0, use</p>
- <pre class="prettyprint lang-config">xml2EncDefault iso-8859-1</pre>
-
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="xml2StartParse" id="xml2StartParse">xml2StartParse</a> <a name="xml2startparse" id="xml2startparse">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Advise the parser to skip leading junk.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>xml2StartParse <var>element [element ...]</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_xml2enc</td></tr>
-</table>
- <p>Specify that the markup parser should start at the first instance
- of any of the elements specified. This can be used as a workaround
- where a broken backend inserts leading junk that messes up the parser (<a href="http://bahumbug.wordpress.com/2006/10/12/mod_proxy_html-revisited/">example here</a>).</p>
- <p>It should never be used for XML, nor well-formed HTML.</p>
-
-</div>
+</ul><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#xml2encalias">xml2EncAlias</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#xml2encdefault">xml2EncDefault</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#xml2startparse">xml2StartParse</a></li>
+</ul>
+<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="usage" id="usage">Usage</a></h2>
<p>If you are working with encodings that are not supported by any of
the conversion methods available on your platform, you can still alias
them to a supported encoding using <code class="directive">xml2EncAlias</code>.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="xml2EncAlias" id="xml2EncAlias">xml2EncAlias</a> <a name="xml2encalias" id="xml2encalias">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Recognise Aliases for encoding values</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>xml2EncAlias <var>charset alias [alias ...]</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_xml2enc</td></tr>
+</table>
+ <p>This server-wide directive aliases one or more encoding to another
+ encoding. This enables encodings not recognised by libxml2 to be handled
+ internally by libxml2's encoding support using the translation table for
+ a recognised encoding. This serves two purposes: to support character sets
+ (or names) not recognised either by libxml2 or iconv, and to skip
+ conversion for an encoding where it is known to be unnecessary.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="xml2EncDefault" id="xml2EncDefault">xml2EncDefault</a> <a name="xml2encdefault" id="xml2encdefault">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets a default encoding to assume when absolutely no information
+can be <a href="#sniffing">automatically detected</a></td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>xml2EncDefault <var>name</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_xml2enc</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Version 2.4.0 and later; available as a third-party
+module for earlier versions.</td></tr>
+</table>
+ <p>If you are processing data with known encoding but no encoding
+ information, you can set this default to help mod_xml2enc process
+ the data correctly. For example, to work with the default value
+ of Latin1 (<var>iso-8859-1</var> specified in HTTP/1.0, use</p>
+ <pre class="prettyprint lang-config">xml2EncDefault iso-8859-1</pre>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="xml2StartParse" id="xml2StartParse">xml2StartParse</a> <a name="xml2startparse" id="xml2startparse">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Advise the parser to skip leading junk.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>xml2StartParse <var>element [element ...]</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_xml2enc</td></tr>
+</table>
+ <p>Specify that the markup parser should start at the first instance
+ of any of the elements specified. This can be used as a workaround
+ where a broken backend inserts leading junk that messes up the parser (<a href="http://bahumbug.wordpress.com/2006/10/12/mod_proxy_html-revisited/">example here</a>).</p>
+ <p>It should never be used for XML, nor well-formed HTML.</p>
+
</div>
</div>
<div class="bottomlang">
<li><img alt="" src="../images/down.gif" /> <a href="#threadstacksize">ThreadStackSize</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CoreDumpDirectory" id="CoreDumpDirectory">CoreDumpDirectory</a> <a name="coredumpdirectory" id="coredumpdirectory">Directive</a></h2>
<table class="directive">
causes crashes with some common modules.</div>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../de/mod/mpm_common.html" hreflang="de" rel="alternate" title="Deutsch"> de </a> |
ports Apache httpd uses</a>
</li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="MaxThreads" id="MaxThreads">MaxThreads</a> <a name="maxthreads" id="maxthreads">Directive</a></h2>
<table class="directive">
</code></p></div>
</div>
-
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mpm_netware.html" title="English"> en </a> |
small enough to assure that there is enough physical RAM for all
processes.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#how-it-works">How it Works</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li>
<li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#enableexceptionhook">EnableExceptionHook</a></li>
<li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#startservers">StartServers</a></li>
<li><img alt="" src="../images/right.gif" /> <a href="mod_unixd.html#user">User</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#how-it-works">How it Works</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><a href="../bind.html">Setting which addresses and ports Apache HTTP Server
uses</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="how-it-works" id="how-it-works">How it Works</a></h2>
+ <p>A single control process is responsible for launching child
+ processes which listen for connections and serve them when they
+ arrive. Apache httpd always tries to maintain several <dfn>spare</dfn>
+ 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 class="directive"><a href="../mod/mpm_common.html#startservers">StartServers</a></code>,
+ <code class="directive"><a href="#minspareservers">MinSpareServers</a></code>,
+ <code class="directive"><a href="#maxspareservers">MaxSpareServers</a></code>, and
+ <code class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code> regulate how
+ the parent process creates children to serve requests. In general,
+ Apache httpd 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 class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code>,
+ while sites with limited memory may need to decrease <code class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></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 <code>root</code>
+ under Unix in order to bind to port 80, the child processes are
+ launched by Apache httpd as a less-privileged user. The <code class="directive"><a href="../mod/mod_unixd.html#user">User</a></code> and <code class="directive"><a href="../mod/mod_unixd.html#group">Group</a></code> directives are used to set
+ the privileges of the Apache httpd 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.</p>
+
+ <p><code class="directive"><a href="../mod/mpm_common.html#maxconnectionsperchild">MaxConnectionsPerChild</a></code>
+ controls how frequently the server recycles processes by killing
+ old ones and launching new ones.</p>
+
+ <p>This MPM uses the <code>mpm-accept</code> mutex to serialize
+ access to incoming connections when subject to the thundering herd
+ problem (generally, when there are multiple listening sockets).
+ The implementation aspects of this mutex can be configured with the
+ <code class="directive"><a href="../mod/core.html#mutex">Mutex</a></code> directive. The <a href="../misc/perf-tuning.html">performance hints</a>
+ documentation has additional information about this mutex.</p>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="MaxSpareServers" id="MaxSpareServers">MaxSpareServers</a> <a name="maxspareservers" id="maxspareservers">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum number of idle child server processes</td></tr>
<li><code class="directive"><a href="../mod/mpm_common.html#minsparethreads">MinSpareThreads</a></code></li>
</ul>
</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="how-it-works" id="how-it-works">How it Works</a></h2>
- <p>A single control process is responsible for launching child
- processes which listen for connections and serve them when they
- arrive. Apache httpd always tries to maintain several <dfn>spare</dfn>
- 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 class="directive"><a href="../mod/mpm_common.html#startservers">StartServers</a></code>,
- <code class="directive"><a href="#minspareservers">MinSpareServers</a></code>,
- <code class="directive"><a href="#maxspareservers">MaxSpareServers</a></code>, and
- <code class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code> regulate how
- the parent process creates children to serve requests. In general,
- Apache httpd 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 class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code>,
- while sites with limited memory may need to decrease <code class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></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 <code>root</code>
- under Unix in order to bind to port 80, the child processes are
- launched by Apache httpd as a less-privileged user. The <code class="directive"><a href="../mod/mod_unixd.html#user">User</a></code> and <code class="directive"><a href="../mod/mod_unixd.html#group">Group</a></code> directives are used to set
- the privileges of the Apache httpd 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.</p>
-
- <p><code class="directive"><a href="../mod/mpm_common.html#maxconnectionsperchild">MaxConnectionsPerChild</a></code>
- controls how frequently the server recycles processes by killing
- old ones and launching new ones.</p>
-
- <p>This MPM uses the <code>mpm-accept</code> mutex to serialize
- access to incoming connections when subject to the thundering herd
- problem (generally, when there are multiple listening sockets).
- The implementation aspects of this mutex can be configured with the
- <code class="directive"><a href="../mod/core.html#mutex">Mutex</a></code> directive. The <a href="../misc/perf-tuning.html">performance hints</a>
- documentation has additional information about this mutex.</p>
-</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../de/mod/prefork.html" hreflang="de" rel="alternate" title="Deutsch"> de </a> |
CGI program</td></tr>
<tr class="odd"><td><a href="core.html#cgimapextension">CGIMapExtension <var>cgi-path</var> <var>.extension</var></a></td><td></td><td>dh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Technique for locating the interpreter for CGI
scripts</td></tr>
-<tr><td><a href="mod_charset_lite.html#charsetdefault">CharsetDefault <var>charset</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Charset to translate into</td></tr>
-<tr class="odd"><td><a href="mod_charset_lite.html#charsetoptions">CharsetOptions <var>option</var> [<var>option</var>] ...</a></td><td> ImplicitAdd </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Configures charset translation behavior</td></tr>
-<tr><td><a href="mod_charset_lite.html#charsetsourceenc">CharsetSourceEnc <var>charset</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Source charset of files</td></tr>
-<tr class="odd"><td><a href="mod_speling.html#checkcaseonly">CheckCaseOnly on|off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Limits the action of the speling module to case corrections</td></tr>
-<tr><td><a href="mod_speling.html#checkspelling">CheckSpelling on|off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Enables the spelling
+<tr><td><a href="core.html#cgipassauth">CGIPassAuth On|Off</a></td><td> Off </td><td>dh</td><td>C</td></tr><tr><td class="descr" colspan="4">Enables passing HTTP authorization headers to scripts as CGI
+variables</td></tr>
+<tr class="odd"><td><a href="mod_charset_lite.html#charsetdefault">CharsetDefault <var>charset</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Charset to translate into</td></tr>
+<tr><td><a href="mod_charset_lite.html#charsetoptions">CharsetOptions <var>option</var> [<var>option</var>] ...</a></td><td> ImplicitAdd </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Configures charset translation behavior</td></tr>
+<tr class="odd"><td><a href="mod_charset_lite.html#charsetsourceenc">CharsetSourceEnc <var>charset</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Source charset of files</td></tr>
+<tr><td><a href="mod_speling.html#checkcaseonly">CheckCaseOnly on|off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Limits the action of the speling module to case corrections</td></tr>
+<tr class="odd"><td><a href="mod_speling.html#checkspelling">CheckSpelling on|off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enables the spelling
module</td></tr>
-<tr class="odd"><td><a href="mod_unixd.html#chrootdir">ChrootDir <var>/path/to/directory</var></a></td><td></td><td>s</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Directory for apache to run chroot(8) after startup.</td></tr>
-<tr><td><a href="core.html#contentdigest">ContentDigest On|Off</a></td><td> Off </td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Enables the generation of <code>Content-MD5</code> HTTP Response
+<tr><td><a href="mod_unixd.html#chrootdir">ChrootDir <var>/path/to/directory</var></a></td><td></td><td>s</td><td>B</td></tr><tr><td class="descr" colspan="4">Directory for apache to run chroot(8) after startup.</td></tr>
+<tr class="odd"><td><a href="core.html#contentdigest">ContentDigest On|Off</a></td><td> Off </td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Enables the generation of <code>Content-MD5</code> HTTP Response
headers</td></tr>
-<tr class="odd"><td><a href="mod_usertrack.html#cookiedomain">CookieDomain <em>domain</em></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">The domain to which the tracking cookie applies</td></tr>
-<tr><td><a href="mod_usertrack.html#cookieexpires">CookieExpires <em>expiry-period</em></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Expiry time for the tracking cookie</td></tr>
-<tr class="odd"><td><a href="mod_usertrack.html#cookiename">CookieName <em>token</em></a></td><td> Apache </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Name of the tracking cookie</td></tr>
-<tr><td><a href="mod_usertrack.html#cookiestyle">CookieStyle
- <em>Netscape|Cookie|Cookie2|RFC2109|RFC2965</em></a></td><td> Netscape </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Format of the cookie header field</td></tr>
-<tr class="odd"><td><a href="mod_usertrack.html#cookietracking">CookieTracking on|off</a></td><td> off </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enables tracking cookie</td></tr>
-<tr><td><a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory <var>directory</var></a></td><td></td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Directory where Apache HTTP Server attempts to
+<tr><td><a href="mod_usertrack.html#cookiedomain">CookieDomain <em>domain</em></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">The domain to which the tracking cookie applies</td></tr>
+<tr class="odd"><td><a href="mod_usertrack.html#cookieexpires">CookieExpires <em>expiry-period</em></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Expiry time for the tracking cookie</td></tr>
+<tr><td><a href="mod_usertrack.html#cookiename">CookieName <em>token</em></a></td><td> Apache </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Name of the tracking cookie</td></tr>
+<tr
class="odd"><td><a href="mod_usertrack.html#cookiestyle">CookieStyle
+ <em>Netscape|Cookie|Cookie2|RFC2109|RFC2965</em></a></td><td> Netscape </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Format of the cookie header field</td></tr>
+<tr><td><a href="mod_usertrack.html#cookietracking">CookieTracking on|off</a></td><td> off </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Enables tracking cookie</td></tr>
+<tr class="odd"><td><a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory <var>directory</var></a></td><td></td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Directory where Apache HTTP Server attempts to
switch before dumping core</td></tr>
-<tr
class="odd"><td><a href="mod_log_config.html#customlog">CustomLog <var>file</var>|<var>pipe</var>
+<tr><td><a href="mod_log_config.html#customlog">CustomLog <var>file</var>|<var>pipe</var>
<var>format</var>|<var>nickname</var>
[env=[!]<var>environment-variable</var>|
-expr=<var>expression</var>]</a></td><td></td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sets filename and format of log file</td></tr>
-<tr><td><a href="mod_dav.html#dav" id="D" name="D">Dav On|Off|<var>provider-name</var></a></td><td> Off </td><td>d</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable WebDAV HTTP methods</td></tr>
-<tr class="odd"><td><a href="mod_dav.html#davdepthinfinity">DavDepthInfinity on|off</a></td><td> off </td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Allow PROPFIND, Depth: Infinity requests</td></tr>
-<tr><td><a href="mod_dav_lock.html#davgenericlockdb">DavGenericLockDB <var>file-path</var></a></td><td></td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Location of the DAV lock database</td></tr>
-<tr class="odd"><td><a href="mod_dav_fs.html#davlockdb">DavLockDB <var>file-path</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Location of the DAV lock database</td></tr>
-<tr><td><a href="mod_dav.html#davmintimeout">DavMinTimeout <var>seconds</var></a></td><td> 0 </td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Minimum amount of time the server holds a lock on
+expr=<var>expression</var>]</a></td><td></td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Sets filename and format of log file</td></tr>
+<tr class="odd"><td><a href="mod_dav.html#dav" id="D" name="D">Dav On|Off|<var>provider-name</var></a></td><td> Off </td><td>d</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable WebDAV HTTP methods</td></tr>
+<tr><td><a href="mod_dav.html#davdepthinfinity">DavDepthInfinity on|off</a></td><td> off </td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Allow PROPFIND, Depth: Infinity requests</td></tr>
+<tr class="odd"><td><a href="mod_dav_lock.html#davgenericlockdb">DavGenericLockDB <var>file-path</var></a></td><td></td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Location of the DAV lock database</td></tr>
+<tr><td><a href="mod_dav_fs.html#davlockdb">DavLockDB <var>file-path</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Location of the DAV lock database</td></tr>
+<tr class="odd"><td><a href="mod_dav.html#davmintimeout">DavMinTimeout <var>seconds</var></a></td><td> 0 </td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Minimum amount of time the server holds a lock on
a DAV resource</td></tr>
-<tr class="odd"><td><a href="mod_dbd.html#dbdexptime">DBDExptime <var>time-in-seconds</var></a></td><td> 300 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Keepalive time for idle connections</td></tr>
-<tr><td><a href="mod_dbd.html#dbdinitsql">DBDInitSQL <var>"SQL statement"</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Execute an SQL statement after connecting to a database</td></tr>
-<tr class="odd"><td><a href="mod_dbd.html#dbdkeep">DBDKeep <var>number</var></a></td><td> 2 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum sustained number of connections</td></tr>
-<tr><td><a href="mod_dbd.html#dbdmax">DBDMax <var>number</var></a></td><td> 10 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximum number of connections</td></tr>
-<tr class="odd"><td><a href="mod_dbd.html#dbdmin">DBDMin <var>number</var></a></td><td> 1 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Minimum number of connections</td></tr>
-<tr><td><a href="mod_dbd.html#dbdparams">DBDParams
-<var>param1</var>=<var>value1</var>[,<var>param2</var>=<var>value2</var>]</a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Parameters for database connection</td></tr>
-<tr class="odd"><td><a href="mod_dbd.html#dbdpersist">DBDPersist On|Off</a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Whether to use persistent connections</td></tr>
-<tr><td><a href="mod_dbd.html#dbdpreparesql">DBDPrepareSQL <var>"SQL statement"</var> <var>label</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Define an SQL prepared statement</td></tr>
-<tr class="odd"><td><a href="mod_dbd.html#dbdriver">DBDriver <var>name</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Specify an SQL driver</td></tr>
-<tr><td><a href="mod_autoindex.html#defaulticon">DefaultIcon <var>url-path</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Icon to display for files when no specific icon is
+<tr><td><a href="mod_dbd.html#dbdexptime">DBDExptime <var>time-in-seconds</var></a></td><td> 300 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Keepalive time for idle connections</td></tr>
+<tr class="odd"><td><a href="mod_dbd.html#dbdinitsql">DBDInitSQL <var>"SQL statement"</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Execute an SQL statement after connecting to a database</td></tr>
+<tr><td><a href="mod_dbd.html#dbdkeep">DBDKeep <var>number</var></a></td><td> 2 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximum sustained number of connections</td></tr>
+<tr class="odd"><td><a href="mod_dbd.html#dbdmax">DBDMax <var>number</var></a></td><td> 10 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum number of connections</td></tr>
+<tr><td><a href="mod_dbd.html#dbdmin">DBDMin <var>number</var></a></td><td> 1 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Minimum number of connections</td></tr>
+<tr
class="odd"><td><a href="mod_dbd.html#dbdparams">DBDParams
+<var>param1</var>=<var>value1</var>[,<var>param2</var>=<var>value2</var>]</a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Parameters for database connection</td></tr>
+<tr><td><a href="mod_dbd.html#dbdpersist">DBDPersist On|Off</a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Whether to use persistent connections</td></tr>
+<tr class="odd"><td><a href="mod_dbd.html#dbdpreparesql">DBDPrepareSQL <var>"SQL statement"</var> <var>label</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Define an SQL prepared statement</td></tr>
+<tr><td><a href="mod_dbd.html#dbdriver">DBDriver <var>name</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Specify an SQL driver</td></tr>
+<tr class="odd"><td><a href="mod_autoindex.html#defaulticon">DefaultIcon <var>url-path</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Icon to display for files when no specific icon is
configured</td></tr>
-<tr class="odd"><td><a href="mod_mime.html#defaultlanguage">DefaultLanguage <var>language-tag</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Defines a default language-tag to be sent in the Content-Language
+<tr><td><a href="mod_mime.html#defaultlanguage">DefaultLanguage <var>language-tag</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Defines a default language-tag to be sent in the Content-Language
header field for all resources in the current context that have not been
assigned a language-tag by some other means.</td></tr>
-<tr><td><a href="core.html#defaultruntimedir">DefaultRuntimeDir <var>directory-path</var></a></td><td> DEFAULT_REL_RUNTIME +</td><td>s</td><td>C</td></tr><tr><td class="descr" colspan="4">Base directory for the server run-time files</td></tr>
-<tr class="odd"><td><a href="core.html#defaulttype">DefaultType <var>media-type|none</var></a></td><td> none </td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">This directive has no effect other than to emit warnings
+<tr class="odd"><td><a href="core.html#defaultruntimedir">DefaultRuntimeDir <var>directory-path</var></a></td><td> DEFAULT_REL_RUNTIME +</td><td>s</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Base directory for the server run-time files</td></tr>
+<tr><td><a href="core.html#defaulttype">DefaultType <var>media-type|none</var></a></td><td> none </td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">This directive has no effect other than to emit warnings
if the value is not <code>none</code>. In prior versions, DefaultType
would specify a default media type to assign to response content for
which no other media type configuration could be found.
</td></tr>
-<tr><td><a href="core.html#define">Define <var>parameter-name</var> [<var>parameter-value</var>]</a></td><td></td><td>svd</td><td>C</td></tr><tr><td class="descr" colspan="4">Define a variable</td></tr>
-<tr class="odd"><td><a href="mod_deflate.html#deflatebuffersize">DeflateBufferSize <var>value</var></a></td><td> 8096 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Fragment size to be compressed at one time by zlib</td></tr>
-<tr><td><a href="mod_deflate.html#deflatecompressionlevel">DeflateCompressionLevel <var>value</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">How much compression do we apply to the output</td></tr>
-<tr class="odd"><td><a href="mod_deflate.html#deflatefilternote">DeflateFilterNote [<var>type</var>] <var>notename</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Places the compression ratio in a note for logging</td></tr>
-<tr><td><a href="mod_deflate.html#deflateinflatelimitrequestbody">DeflateInflateLimitRequestBody<var>value</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximum size of inflated request bodies</td></tr>
-<tr class="odd"><td><a href="mod_deflate.html#deflateinflateratioburst">DeflateInflateRatioBurst <var>value</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum number of times the inflation ratio for request bodies
+<tr class="odd"><td><a href="core.html#define">Define <var>parameter-name</var> [<var>parameter-value</var>]</a></td><td></td><td>svd</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Define a variable</td></tr>
+<tr><td><a href="mod_deflate.html#deflatebuffersize">DeflateBufferSize <var>value</var></a></td><td> 8096 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Fragment size to be compressed at one time by zlib</td></tr>
+<tr class="odd"><td><a href="mod_deflate.html#deflatecompressionlevel">DeflateCompressionLevel <var>value</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">How much compression do we apply to the output</td></tr>
+<tr><td><a href="mod_deflate.html#deflatefilternote">DeflateFilterNote [<var>type</var>] <var>notename</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Places the compression ratio in a note for logging</td></tr>
+<tr class="odd"><td><a href="mod_deflate.html#deflateinflatelimitrequestbody">DeflateInflateLimitRequestBody<var>value</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum size of inflated request bodies</td></tr>
+<tr><td><a href="mod_deflate.html#deflateinflateratioburst">DeflateInflateRatioBurst <var>value</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximum number of times the inflation ratio for request bodies
can be crossed</td></tr>
-<tr><td><a href="mod_deflate.html#deflateinflateratiolimit">DeflateInflateRatioLimit <var>value</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximum inflation ratio for request bodies</td></tr>
-<tr class="odd"><td><a href="mod_deflate.html#deflatememlevel">DeflateMemLevel <var>value</var></a></td><td> 9 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">How much memory should be used by zlib for compression</td></tr>
-<tr><td><a href="mod_deflate.html#deflatewindowsize">DeflateWindowSize <var>value</var></a></td><td> 15 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Zlib compression window size</td></tr>
-<tr
class="odd"><td><a href="mod_access_compat.html#deny"> Deny from all|<var>host</var>|env=[!]<var>env-variable</var>
-[<var>host</var>|env=[!]<var>env-variable</var>] ...</a></td><td></td><td>dh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Controls which hosts are denied access to the
+<tr class="odd"><td><a href="mod_deflate.html#deflateinflateratiolimit">DeflateInflateRatioLimit <var>value</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum inflation ratio for request bodies</td></tr>
+<tr><td><a href="mod_deflate.html#deflatememlevel">DeflateMemLevel <var>value</var></a></td><td> 9 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">How much memory should be used by zlib for compression</td></tr>
+<tr class="odd"><td><a href="mod_deflate.html#deflatewindowsize">DeflateWindowSize <var>value</var></a></td><td> 15 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Zlib compression window size</td></tr>
+<tr><td><a href="mod_access_compat.html#deny"> Deny from all|<var>host</var>|env=[!]<var>env-variable</var>
+[<var>host</var>|env=[!]<var>env-variable</var>] ...</a></td><td></td><td>dh</td><td>E</td></tr><tr><td class="descr" colspan="4">Controls which hosts are denied access to the
server</td></tr>
-<tr><td><a href="core.html#directory"><Directory "<var>directory-path</var>">
-... </Directory></a></td><td></td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Enclose a group of directives that apply only to the
+<tr
class="odd"><td><a href="core.html#directory"><Directory "<var>directory-path</var>">
+... </Directory></a></td><td></td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Enclose a group of directives that apply only to the
named file-system directory, sub-directories, and their contents.</td></tr>
-<tr class="odd"><td><a href="mod_dir.html#directorycheckhandler">DirectoryCheckHandler On|Off</a></td><td> Off </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Toggle how this module responds when another handler is configured</td></tr>
-<tr><td><a href="mod_dir.html#directoryindex">DirectoryIndex
- disabled | <var>local-url</var> [<var>local-url</var>] ...</a></td><td> index.html </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">List of resources to look for when the client requests
+<tr><td><a href="mod_dir.html#directorycheckhandler">DirectoryCheckHandler On|Off</a></td><td> Off </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Toggle how this module responds when another handler is configured</td></tr>
+<tr
class="odd"><td><a href="mod_dir.html#directoryindex">DirectoryIndex
+ disabled | <var>local-url</var> [<var>local-url</var>] ...</a></td><td> index.html </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">List of resources to look for when the client requests
a directory</td></tr>
-<tr
class="odd"><td><a href="mod_dir.html#directoryindexredirect">DirectoryIndexRedirect on | off | permanent | temp | seeother |
+<tr><td><a href="mod_dir.html#directoryindexredirect">DirectoryIndexRedirect on | off | permanent | temp | seeother |
<var>3xx-code</var>
-</a></td><td> off </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Configures an external redirect for directory indexes.
+</a></td><td> off </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Configures an external redirect for directory indexes.
</td></tr>
-<tr><td><a href="core.html#directorymatch"><DirectoryMatch <var>regex</var>>
-... </DirectoryMatch></a></td><td></td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Enclose directives that apply to
+<tr
class="odd"><td><a href="core.html#directorymatch"><DirectoryMatch <var>regex</var>>
+... </DirectoryMatch></a></td><td></td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Enclose directives that apply to
the contents of file-system directories matching a regular expression.</td></tr>
-<tr class="odd"><td><a href="mod_dir.html#directoryslash">DirectorySlash On|Off</a></td><td> On </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Toggle trailing slash redirects on or off</td></tr>
-<tr><td><a href="core.html#documentroot">DocumentRoot <var>directory-path</var></a></td><td> "/usr/local/apache/ +</td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Directory that forms the main document tree visible
+<tr><td><a href="mod_dir.html#directoryslash">DirectorySlash On|Off</a></td><td> On </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Toggle trailing slash redirects on or off</td></tr>
+<tr class="odd"><td><a href="core.html#documentroot">DocumentRoot <var>directory-path</var></a></td><td> "/usr/local/apache/ +</td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Directory that forms the main document tree visible
from the web</td></tr>
-<tr class="odd"><td><a href="mod_privileges.html#dtraceprivileges">DTracePrivileges On|Off</a></td><td> Off </td><td>s</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Determines whether the privileges required by dtrace are enabled.</td></tr>
-<tr><td><a href="mod_dumpio.html#dumpioinput">DumpIOInput On|Off</a></td><td> Off </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Dump all input data to the error log</td></tr>
-<tr class="odd"><td><a href="mod_dumpio.html#dumpiooutput">DumpIOOutput On|Off</a></td><td> Off </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Dump all output data to the error log</td></tr>
-<tr><td><a href="core.html#else" id="E" name="E"><Else> ... </Else></a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Contains directives that apply only if the condition of a
+<tr><td><a href="mod_privileges.html#dtraceprivileges">DTracePrivileges On|Off</a></td><td> Off </td><td>s</td><td>X</td></tr><tr><td class="descr" colspan="4">Determines whether the privileges required by dtrace are enabled.</td></tr>
+<tr class="odd"><td><a href="mod_dumpio.html#dumpioinput">DumpIOInput On|Off</a></td><td> Off </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Dump all input data to the error log</td></tr>
+<tr><td><a href="mod_dumpio.html#dumpiooutput">DumpIOOutput On|Off</a></td><td> Off </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Dump all output data to the error log</td></tr>
+<tr class="odd"><td><a href="core.html#else" id="E" name="E"><Else> ... </Else></a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Contains directives that apply only if the condition of a
previous <code class="directive"><a href="../mod/core.html#if"><If></a></code> or
<code class="directive"><a href="../mod/core.html#elseif"><ElseIf></a></code> section is not
satisfied by a request at runtime</td></tr>
-<tr class="odd"><td><a href="core.html#elseif"><ElseIf <var>expression</var>> ... </ElseIf></a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Contains directives that apply only if a condition is satisfied
+<tr><td><a href="core.html#elseif"><ElseIf <var>expression</var>> ... </ElseIf></a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Contains directives that apply only if a condition is satisfied
by a request at runtime while the condition of a previous
<code class="directive"><a href="../mod/core.html#if"><If></a></code> or
<code class="directive"><ElseIf></code> section is not
satisfied</td></tr>
-<tr><td><a href="mpm_common.html#enableexceptionhook">EnableExceptionHook On|Off</a></td><td> Off </td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Enables a hook that runs exception handlers
+<tr class="odd"><td><a href="mpm_common.html#enableexceptionhook">EnableExceptionHook On|Off</a></td><td> Off </td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Enables a hook that runs exception handlers
after a crash</td></tr>
-<tr class="odd"><td><a href="core.html#enablemmap">EnableMMAP On|Off</a></td><td> On </td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Use memory-mapping to read files during delivery</td></tr>
-<tr><td><a href="core.html#enablesendfile">EnableSendfile On|Off</a></td><td> Off </td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Use the kernel sendfile support to deliver files to the client</td></tr>
-<tr class="odd"><td><a href="core.html#error">Error <var>message</var></a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Abort configuration parsing with a custom error message</td></tr>
-<tr><td><a href="core.html#errordocument">ErrorDocument <var>error-code</var> <var>document</var></a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">What the server will return to the client
+<tr><td><a href="core.html#enablemmap">EnableMMAP On|Off</a></td><td> On </td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Use memory-mapping to read files during delivery</td></tr>
+<tr class="odd"><td><a href="core.html#enablesendfile">EnableSendfile On|Off</a></td><td> Off </td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Use the kernel sendfile support to deliver files to the client</td></tr>
+<tr><td><a href="core.html#error">Error <var>message</var></a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Abort configuration parsing with a custom error message</td></tr>
+<tr class="odd"><td><a href="core.html#errordocument">ErrorDocument <var>error-code</var> <var>document</var></a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">What the server will return to the client
in case of an error</td></tr>
-<tr class="odd"><td><a href="core.html#errorlog"> ErrorLog <var>file-path</var>|syslog[:<var>facility</var>]</a></td><td> logs/error_log (Uni +</td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Location where the server will log errors</td></tr>
-<tr><td><a href="core.html#errorlogformat"> ErrorLogFormat [connection|request] <var>format</var></a></td><td></td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Format specification for error log entries</td></tr>
-<tr class="odd"><td><a href="mod_example_hooks.html#example">Example</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Demonstration directive to illustrate the Apache module
+<tr><td><a href="core.html#errorlog"> ErrorLog <var>file-path</var>|syslog[:<var>facility</var>]</a></td><td> logs/error_log (Uni +</td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Location where the server will log errors</td></tr>
+<tr class="odd"><td><a href="core.html#errorlogformat"> ErrorLogFormat [connection|request] <var>format</var></a></td><td></td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Format specification for error log entries</td></tr>
+<tr><td><a href="mod_example_hooks.html#example">Example</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Demonstration directive to illustrate the Apache module
API</td></tr>
-<tr><td><a href="mod_expires.html#expiresactive">ExpiresActive On|Off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Enables generation of <code>Expires</code>
+<tr class="odd"><td><a href="mod_expires.html#expiresactive">ExpiresActive On|Off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enables generation of <code>Expires</code>
headers</td></tr>
-<tr
class="odd"><td><a href="mod_expires.html#expiresbytype">ExpiresByType <var>MIME-type</var>
-<var><code>seconds</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Value of the <code>Expires</code> header configured
+<tr><td><a href="mod_expires.html#expiresbytype">ExpiresByType <var>MIME-type</var>
+<var><code>seconds</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Value of the <code>Expires</code> header configured
by MIME type</td></tr>
-<tr><td><a href="mod_expires.html#expiresdefault">ExpiresDefault <var><code>seconds</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Default algorithm for calculating expiration time</td></tr>
-<tr class="odd"><td><a href="core.html#extendedstatus">ExtendedStatus On|Off</a></td><td> Off[*] </td><td>s</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Keep track of extended status information for each
+<tr class="odd"><td><a href="mod_expires.html#expiresdefault">ExpiresDefault <var><code>seconds</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Default algorithm for calculating expiration time</td></tr>
+<tr><td><a href="core.html#extendedstatus">ExtendedStatus On|Off</a></td><td> Off[*] </td><td>s</td><td>C</td></tr><tr><td class="descr" colspan="4">Keep track of extended status information for each
request</td></tr>
-<tr><td><a href="mod_ext_filter.html#extfilterdefine">ExtFilterDefine <var>filtername</var> <var>parameters</var></a></td><td></td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Define an external filter</td></tr>
-<tr
class="odd"><td><a href="mod_ext_filter.html#extfilteroptions">ExtFilterOptions <var>option</var> [<var>option</var>] ...</a></td><td> NoLogStderr </td><td>d</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Configure <code class="module"><a href="../mod/mod_ext_filter.html">mod_ext_filter</a></code> options</td></tr>
-<tr><td><a href="mod_dir.html#fallbackresource" id="F" name="F">FallbackResource disabled | <var>local-url</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Define a default URL for requests that don't map to a file</td></tr>
-<tr class="odd"><td><a href="core.html#fileetag">FileETag <var>component</var> ...</a></td><td> MTime Size </td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">File attributes used to create the ETag
+<tr class="odd"><td><a href="mod_ext_filter.html#extfilterdefine">ExtFilterDefine <var>filtername</var> <var>parameters</var></a></td><td></td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Define an external filter</td></tr>
+<tr
><td><a href="mod_ext_filter.html#extfilteroptions">ExtFilterOptions <var>option</var> [<var>option</var>] ...</a></td><td> NoLogStderr </td><td>d</td><td>E</td></tr><tr><td class="descr" colspan="4">Configure <code class="module"><a href="../mod/mod_ext_filter.html">mod_ext_filter</a></code> options</td></tr>
+<tr class="odd"><td><a href="mod_dir.html#fallbackresource" id="F" name="F">FallbackResource disabled | <var>local-url</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Define a default URL for requests that don't map to a file</td></tr>
+<tr><td><a href="core.html#fileetag">FileETag <var>component</var> ...</a></td><td> MTime Size </td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">File attributes used to create the ETag
HTTP response header for static files</td></tr>
-<tr><td><a href="core.html#files"><Files "<var>filename</var>"> ... </Files></a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Contains directives that apply to matched
+<tr class="odd"><td><a href="core.html#files"><Files "<var>filename</var>"> ... </Files></a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Contains directives that apply to matched
filenames</td></tr>
-<tr class="odd"><td><a href="core.html#filesmatch"><FilesMatch <var>regex</var>> ... </FilesMatch></a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Contains directives that apply to regular-expression matched
+<tr><td><a href="core.html#filesmatch"><FilesMatch <var>regex</var>> ... </FilesMatch></a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Contains directives that apply to regular-expression matched
filenames</td></tr>
-<tr><td><a href="mod_filter.html#filterchain">FilterChain [+=-@!]<var>filter-name</var> <var>...</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Configure the filter chain</td></tr>
-<tr class="odd"><td><a href="mod_filter.html#filterdeclare">FilterDeclare <var>filter-name</var> <var>[type]</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Declare a smart filter</td></tr>
-<tr><td><a href="mod_filter.html#filterprotocol">FilterProtocol <var>filter-name</var> [<var>provider-name</var>]
- <var>proto-flags</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Deal with correct HTTP protocol handling</td></tr>
-<tr
class="odd"><td><a href="mod_filter.html#filterprovider">FilterProvider <var>filter-name</var> <var>provider-name</var>
- <var>expression</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Register a content filter</td></tr>
-<tr><td><a href="mod_filter.html#filtertrace">FilterTrace <var>filter-name</var> <var>level</var></a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Get debug/diagnostic information from
+<tr class="odd"><td><a href="mod_filter.html#filterchain">FilterChain [+=-@!]<var>filter-name</var> <var>...</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Configure the filter chain</td></tr>
+<tr><td><a href="mod_filter.html#filterdeclare">FilterDeclare <var>filter-name</var> <var>[type]</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Declare a smart filter</td></tr>
+<tr
class="odd"><td><a href="mod_filter.html#filterprotocol">FilterProtocol <var>filter-name</var> [<var>provider-name</var>]
+ <var>proto-flags</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Deal with correct HTTP protocol handling</td></tr>
+<tr><td><a href="mod_filter.html#filterprovider">FilterProvider <var>filter-name</var> <var>provider-name</var>
+ <var>expression</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Register a content filter</td></tr>
+<tr class="odd"><td><a href="mod_filter.html#filtertrace">FilterTrace <var>filter-name</var> <var>level</var></a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Get debug/diagnostic information from
<code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code></td></tr>
-<tr class="odd"><td><a href="mod_negotiation.html#forcelanguagepriority">ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</a></td><td> Prefer </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Action to take if a single acceptable document is not
+<tr><td><a href="mod_negotiation.html#forcelanguagepriority">ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</a></td><td> Prefer </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Action to take if a single acceptable document is not
found</td></tr>
-<tr><td><a href="core.html#forcetype">ForceType <var>media-type</var>|None</a></td><td></td><td>dh</td><td>C</td></tr><tr><td class="descr" colspan="4">Forces all matching files to be served with the specified
+<tr class="odd"><td><a href="core.html#forcetype">ForceType <var>media-type</var>|None</a></td><td></td><td>dh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Forces all matching files to be served with the specified
media type in the HTTP Content-Type header field</td></tr>
-<tr class="odd"><td><a href="mod_log_forensic.html#forensiclog">ForensicLog <var>filename</var>|<var>pipe</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Sets filename of the forensic log</td></tr>
-<tr><td><a href="core.html#gprofdir" id="G" name="G">GprofDir <var>/tmp/gprof/</var>|<var>/tmp/gprof/</var>%</a></td><td></td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Directory to write gmon.out profiling data to. </td></tr>
-<tr class="odd"><td><a href="mpm_common.html#gracefulshutdowntimeout">GracefulShutdownTimeout <var>seconds</var></a></td><td> 0 </td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Specify a timeout after which a gracefully shutdown server
+<tr><td><a href="mod_log_forensic.html#forensiclog">ForensicLog <var>filename</var>|<var>pipe</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Sets filename of the forensic log</td></tr>
+<tr class="odd"><td><a href="core.html#gprofdir" id="G" name="G">GprofDir <var>/tmp/gprof/</var>|<var>/tmp/gprof/</var>%</a></td><td></td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Directory to write gmon.out profiling data to. </td></tr>
+<tr><td><a href="mpm_common.html#gracefulshutdowntimeout">GracefulShutdownTimeout <var>seconds</var></a></td><td> 0 </td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Specify a timeout after which a gracefully shutdown server
will exit.</td></tr>
-<tr><td><a href="mod_unixd.html#group">Group <var>unix-group</var></a></td><td> #-1 </td><td>s</td><td>B</td></tr><tr><td class="descr" colspan="4">Group under which the server will answer
+<tr class="odd"><td><a href="mod_unixd.html#group">Group <var>unix-group</var></a></td><td> #-1 </td><td>s</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Group under which the server will answer
requests</td></tr>
-<tr
class="odd"><td><a href="mod_headers.html#header" id="H" name="H">Header [<var>condition</var>] add|append|echo|edit|edit*|merge|set|setifempty|unset|note
+<tr><td><a href="mod_headers.html#header" id="H" name="H">Header [<var>condition</var>] add|append|echo|edit|edit*|merge|set|setifempty|unset|note
<var>header</var> [[expr=]<var>value</var> [<var>replacement</var>]
[early|env=[!]<var>varname</var>|expr=<var>expression</var>]]
-</a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Configure HTTP response headers</td></tr>
-<tr><td><a href="mod_autoindex.html#headername">HeaderName <var>filename</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Name of the file that will be inserted at the top
+</a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Configure HTTP response headers</td></tr>
+<tr class="odd"><td><a href="mod_autoindex.html#headername">HeaderName <var>filename</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Name of the file that will be inserted at the top
of the index listing</td></tr>
-<tr class="odd"><td><a href="mod_heartbeat.html#heartbeataddress">HeartbeatAddress <var>addr:port</var></a></td><td></td><td>s</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Multicast address for heartbeat packets</td></tr>
-<tr><td><a href="mod_heartmonitor.html#heartbeatlisten">HeartbeatListen<var>addr:port</var></a></td><td></td><td>s</td><td>X</td></tr><tr><td class="descr" colspan="4">multicast address to listen for incoming heartbeat requests </td></tr>
-<tr class="odd"><td><a href="mod_heartmonitor.html#heartbeatmaxservers">HeartbeatMaxServers <var>number-of-servers</var></a></td><td> 10 </td><td>s</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Specifies the maximum number of servers that will be sending
+<tr><td><a href="mod_heartbeat.html#heartbeataddress">HeartbeatAddress <var>addr:port</var></a></td><td></td><td>s</td><td>X</td></tr><tr><td class="descr" colspan="4">Multicast address for heartbeat packets</td></tr>
+<tr class="odd"><td><a href="mod_heartmonitor.html#heartbeatlisten">HeartbeatListen<var>addr:port</var></a></td><td></td><td>s</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">multicast address to listen for incoming heartbeat requests </td></tr>
+<tr><td><a href="mod_heartmonitor.html#heartbeatmaxservers">HeartbeatMaxServers <var>number-of-servers</var></a></td><td> 10 </td><td>s</td><td>X</td></tr><tr><td class="descr" colspan="4">Specifies the maximum number of servers that will be sending
heartbeat requests to this server</td></tr>
-<tr><td><a href="mod_heartmonitor.html#heartbeatstorage">HeartbeatStorage <var>file-path</var></a></td><td> logs/hb.dat </td><td>s</td><td>X</td></tr><tr><td class="descr" colspan="4">Path to store heartbeat data</td></tr>
-<tr class="odd"><td><a href="mod_lbmethod_heartbeat.html#heartbeatstorage">HeartbeatStorage <var>file-path</var></a></td><td> logs/hb.dat </td><td>s</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Path to read heartbeat data</td></tr>
-<tr><td><a href="core.html#hostnamelookups">HostnameLookups On|Off|Double</a></td><td> Off </td><td>svd</td><td>C</td></tr><tr><td class="descr" colspan="4">Enables DNS lookups on client IP addresses</td></tr>
-<tr class="odd"><td><a href="mod_ident.html#identitycheck" id="I" name="I">IdentityCheck On|Off</a></td><td> Off </td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enables logging of the RFC 1413 identity of the remote
+<tr class="odd"><td><a href="mod_heartmonitor.html#heartbeatstorage">HeartbeatStorage <var>file-path</var></a></td><td> logs/hb.dat </td><td>s</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Path to store heartbeat data</td></tr>
+<tr><td><a href="mod_lbmethod_heartbeat.html#heartbeatstorage">HeartbeatStorage <var>file-path</var></a></td><td> logs/hb.dat </td><td>s</td><td>X</td></tr><tr><td class="descr" colspan="4">Path to read heartbeat data</td></tr>
+<tr class="odd"><td><a href="core.html#hostnamelookups">HostnameLookups On|Off|Double</a></td><td> Off </td><td>svd</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Enables DNS lookups on client IP addresses</td></tr>
+<tr><td><a href="mod_ident.html#identitycheck" id="I" name="I">IdentityCheck On|Off</a></td><td> Off </td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Enables logging of the RFC 1413 identity of the remote
user</td></tr>
-<tr><td><a href="mod_ident.html#identitychecktimeout">IdentityCheckTimeout <var>seconds</var></a></td><td> 30 </td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Determines the timeout duration for ident requests</td></tr>
-<tr class="odd"><td><a href="core.html#if"><If <var>expression</var>> ... </If></a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Contains directives that apply only if a condition is
+<tr class="odd"><td><a href="mod_ident.html#identitychecktimeout">IdentityCheckTimeout <var>seconds</var></a></td><td> 30 </td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Determines the timeout duration for ident requests</td></tr>
+<tr><td><a href="core.html#if"><If <var>expression</var>> ... </If></a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Contains directives that apply only if a condition is
satisfied by a request at runtime</td></tr>
-<tr><td><a href="core.html#ifdefine"><IfDefine [!]<var>parameter-name</var>> ...
- </IfDefine></a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Encloses directives that will be processed only
+<tr
class="odd"><td><a href="core.html#ifdefine"><IfDefine [!]<var>parameter-name</var>> ...
+ </IfDefine></a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Encloses directives that will be processed only
if a test is true at startup</td></tr>
-<tr
class="odd"><td><a href="core.html#ifmodule"><IfModule [!]<var>module-file</var>|<var>module-identifier</var>> ...
- </IfModule></a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Encloses directives that are processed conditional on the
+<tr><td><a href="core.html#ifmodule"><IfModule [!]<var>module-file</var>|<var>module-identifier</var>> ...
+ </IfModule></a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Encloses directives that are processed conditional on the
presence or absence of a specific module</td></tr>
-<tr><td><a href="mod_version.html#ifversion"><IfVersion [[!]<var>operator</var>] <var>version</var>> ...
-</IfVersion></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">contains version dependent configuration</td></tr>
-<tr class="odd"><td><a href="mod_imagemap.html#imapbase">ImapBase map|referer|<var>URL</var></a></td><td> http://servername/ </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Default <code>base</code> for imagemap files</td></tr>
-<tr><td><a href="mod_imagemap.html#imapdefault">ImapDefault error|nocontent|map|referer|<var>URL</var></a></td><td> nocontent </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Default action when an imagemap is called with coordinates
+<tr
class="odd"><td><a href="mod_version.html#ifversion"><IfVersion [[!]<var>operator</var>] <var>version</var>> ...
+</IfVersion></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">contains version dependent configuration</td></tr>
+<tr><td><a href="mod_imagemap.html#imapbase">ImapBase map|referer|<var>URL</var></a></td><td> http://servername/ </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Default <code>base</code> for imagemap files</td></tr>
+<tr class="odd"><td><a href="mod_imagemap.html#imapdefault">ImapDefault error|nocontent|map|referer|<var>URL</var></a></td><td> nocontent </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Default action when an imagemap is called with coordinates
that are not explicitly mapped</td></tr>
-<tr class="odd"><td><a href="mod_imagemap.html#imapmenu">ImapMenu none|formatted|semiformatted|unformatted</a></td><td> formatted </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Action if no coordinates are given when calling
+<tr><td><a href="mod_imagemap.html#imapmenu">ImapMenu none|formatted|semiformatted|unformatted</a></td><td> formatted </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Action if no coordinates are given when calling
an imagemap</td></tr>
-<tr><td><a href="core.html#include">Include <var>file-path</var>|<var>directory-path</var>|<var>wildcard</var></a></td><td></td><td>svd</td><td>C</td></tr><tr><td class="descr" colspan="4">Includes other configuration files from within
+<tr class="odd"><td><a href="core.html#include">Include <var>file-path</var>|<var>directory-path</var>|<var>wildcard</var></a></td><td></td><td>svd</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Includes other configuration files from within
the server configuration files</td></tr>
-<tr class="odd"><td><a href="core.html#includeoptional">IncludeOptional <var>file-path</var>|<var>directory-path</var>|<var>wildcard</var></a></td><td></td><td>svd</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Includes other configuration files from within
+<tr><td><a href="core.html#includeoptional">IncludeOptional <var>file-path</var>|<var>directory-path</var>|<var>wildcard</var></a></td><td></td><td>svd</td><td>C</td></tr><tr><td class="descr" colspan="4">Includes other configuration files from within
the server configuration files</td></tr>
-<tr><td><a href="mod_autoindex.html#indexheadinsert">IndexHeadInsert <var>"markup ..."</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Inserts text in the HEAD section of an index page.</td></tr>
-<tr class="odd"><td><a href="mod_autoindex.html#indexignore">IndexIgnore <var>file</var> [<var>file</var>] ...</a></td><td> "." </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Adds to the list of files to hide when listing
+<tr class="odd"><td><a href="mod_autoindex.html#indexheadinsert">IndexHeadInsert <var>"markup ..."</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Inserts text in the HEAD section of an index page.</td></tr>
+<tr><td><a href="mod_autoindex.html#indexignore">IndexIgnore <var>file</var> [<var>file</var>] ...</a></td><td> "." </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Adds to the list of files to hide when listing
a directory</td></tr>
-<tr><td><a href="mod_autoindex.html#indexignorereset">IndexIgnoreReset ON|OFF</a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Empties the list of files to hide when listing
+<tr class="odd"><td><a href="mod_autoindex.html#indexignorereset">IndexIgnoreReset ON|OFF</a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Empties the list of files to hide when listing
a directory</td></tr>
-<tr
class="odd"><td><a href="mod_autoindex.html#indexoptions">IndexOptions [+|-]<var>option</var> [[+|-]<var>option</var>]
-...</a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Various configuration settings for directory
+<tr><td><a href="mod_autoindex.html#indexoptions">IndexOptions [+|-]<var>option</var> [[+|-]<var>option</var>]
+...</a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Various configuration settings for directory
indexing</td></tr>
-<tr><td><a href="mod_autoindex.html#indexorderdefault">IndexOrderDefault Ascending|Descending
-Name|Date|Size|Description</a></td><td> Ascending Name </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Sets the default ordering of the directory index</td></tr>
-<tr class="odd"><td><a href="mod_autoindex.html#indexstylesheet">IndexStyleSheet <var>url-path</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Adds a CSS stylesheet to the directory index</td></tr>
-<tr><td><a href="mod_sed.html#inputsed">InputSed <var>sed-command</var></a></td><td></td><td>dh</td><td>X</td></tr><tr><td class="descr" colspan="4">Sed command to filter request data (typically <code>POST</code> data)</td></tr>
-<tr class="odd"><td><a href="mod_isapi.html#isapiappendlogtoerrors">ISAPIAppendLogToErrors on|off</a></td><td> off </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from
+<tr
class="odd"><td><a href="mod_autoindex.html#indexorderdefault">IndexOrderDefault Ascending|Descending
+Name|Date|Size|Description</a></td><td> Ascending Name </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sets the default ordering of the directory index</td></tr>
+<tr><td><a href="mod_autoindex.html#indexstylesheet">IndexStyleSheet <var>url-path</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Adds a CSS stylesheet to the directory index</td></tr>
+<tr class="odd"><td><a href="mod_sed.html#inputsed">InputSed <var>sed-command</var></a></td><td></td><td>dh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Sed command to filter request data (typically <code>POST</code> data)</td></tr>
+<tr><td><a href="mod_isapi.html#isapiappendlogtoerrors">ISAPIAppendLogToErrors on|off</a></td><td> off </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from
ISAPI extensions to the error log</td></tr>
-<tr><td><a href="mod_isapi.html#isapiappendlogtoquery">ISAPIAppendLogToQuery on|off</a></td><td> on </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from
+<tr class="odd"><td><a href="mod_isapi.html#isapiappendlogtoquery">ISAPIAppendLogToQuery on|off</a></td><td> on </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from
ISAPI extensions to the query field</td></tr>
-<tr
class="odd"><td><a href="mod_isapi.html#isapicachefile">ISAPICacheFile <var>file-path</var> [<var>file-path</var>]
-...</a></td><td></td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">ISAPI .dll files to be loaded at startup</td></tr>
-<tr><td><a href="mod_isapi.html#isapifakeasync">ISAPIFakeAsync on|off</a></td><td> off </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Fake asynchronous support for ISAPI callbacks</td></tr>
-<tr class="odd"><td><a href="mod_isapi.html#isapilognotsupported">ISAPILogNotSupported on|off</a></td><td> off </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Log unsupported feature requests from ISAPI
+<tr><td><a href="mod_isapi.html#isapicachefile">ISAPICacheFile <var>file-path</var> [<var>file-path</var>]
+...</a></td><td></td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">ISAPI .dll files to be loaded at startup</td></tr>
+<tr class="odd"><td><a href="mod_isapi.html#isapifakeasync">ISAPIFakeAsync on|off</a></td><td> off </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Fake asynchronous support for ISAPI callbacks</td></tr>
+<tr><td><a href="mod_isapi.html#isapilognotsupported">ISAPILogNotSupported on|off</a></td><td> off </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Log unsupported feature requests from ISAPI
extensions</td></tr>
-<tr><td><a href="mod_isapi.html#isapireadaheadbuffer">ISAPIReadAheadBuffer <var>size</var></a></td><td> 49152 </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Size of the Read Ahead Buffer sent to ISAPI
+<tr class="odd"><td><a href="mod_isapi.html#isapireadaheadbuffer">ISAPIReadAheadBuffer <var>size</var></a></td><td> 49152 </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Size of the Read Ahead Buffer sent to ISAPI
extensions</td></tr>
-<tr class="odd"><td><a href="core.html#keepalive" id="K" name="K">KeepAlive On|Off</a></td><td> On </td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Enables HTTP persistent connections</td></tr>
-<tr><td><a href="core.html#keepalivetimeout">KeepAliveTimeout <var>num</var>[ms]</a></td><td> 5 </td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Amount of time the server will wait for subsequent
+<tr><td><a href="core.html#keepalive" id="K" name="K">KeepAlive On|Off</a></td><td> On </td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Enables HTTP persistent connections</td></tr>
+<tr class="odd"><td><a href="core.html#keepalivetimeout">KeepAliveTimeout <var>num</var>[ms]</a></td><td> 5 </td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Amount of time the server will wait for subsequent
requests on a persistent connection</td></tr>
-<tr class="odd"><td><a href="mod_request.html#keptbodysize">KeptBodySize <var>maximum size in bytes</var></a></td><td> 0 </td><td>d</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Keep the request body instead of discarding it up to
+<tr><td><a href="mod_request.html#keptbodysize">KeptBodySize <var>maximum size in bytes</var></a></td><td> 0 </td><td>d</td><td>B</td></tr><tr><td class="descr" colspan="4">Keep the request body instead of discarding it up to
the specified maximum size, for potential use by filters such as
mod_include.</td></tr>
-<tr><td><a href="mod_negotiation.html#languagepriority" id="L" name="L">LanguagePriority <var>MIME-lang</var> [<var>MIME-lang</var>]
-...</a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">The precendence of language variants for cases where
+<tr
class="odd"><td><a href="mod_negotiation.html#languagepriority" id="L" name="L">LanguagePriority <var>MIME-lang</var> [<var>MIME-lang</var>]
+...</a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">The precendence of language variants for cases where
the client does not express a preference</td></tr>
-<tr class="odd"><td><a href="mod_ldap.html#ldapcacheentries">LDAPCacheEntries <var>number</var></a></td><td> 1024 </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum number of entries in the primary LDAP cache</td></tr>
-<tr><td><a href="mod_ldap.html#ldapcachettl">LDAPCacheTTL <var>seconds</var></a></td><td> 600 </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Time that cached items remain valid</td></tr>
-<tr class="odd"><td><a href="mod_ldap.html#ldapconnectionpoolttl">LDAPConnectionPoolTTL <var>n</var></a></td><td> -1 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Discard backend connections that have been sitting in the connection pool too long</td></tr>
-<tr><td><a href="mod_ldap.html#ldapconnectiontimeout">LDAPConnectionTimeout <var>seconds</var></a></td><td></td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Specifies the socket connection timeout in seconds</td></tr>
-<tr class="odd"><td><a href="mod_ldap.html#ldaplibrarydebug">LDAPLibraryDebug <var>7</var></a></td><td></td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable debugging in the LDAP SDK</td></tr>
-<tr><td><a href="mod_ldap.html#ldapopcacheentries">LDAPOpCacheEntries <var>number</var></a></td><td> 1024 </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Number of entries used to cache LDAP compare
+<tr><td><a href="mod_ldap.html#ldapcacheentries">LDAPCacheEntries <var>number</var></a></td><td> 1024 </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximum number of entries in the primary LDAP cache</td></tr>
+<tr class="odd"><td><a href="mod_ldap.html#ldapcachettl">LDAPCacheTTL <var>seconds</var></a></td><td> 600 </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Time that cached items remain valid</td></tr>
+<tr><td><a href="mod_ldap.html#ldapconnectionpoolttl">LDAPConnectionPoolTTL <var>n</var></a></td><td> -1 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Discard backend connections that have been sitting in the connection pool too long</td></tr>
+<tr class="odd"><td><a href="mod_ldap.html#ldapconnectiontimeout">LDAPConnectionTimeout <var>seconds</var></a></td><td></td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Specifies the socket connection timeout in seconds</td></tr>
+<tr><td><a href="mod_ldap.html#ldaplibrarydebug">LDAPLibraryDebug <var>7</var></a></td><td></td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable debugging in the LDAP SDK</td></tr>
+<tr class="odd"><td><a href="mod_ldap.html#ldapopcacheentries">LDAPOpCacheEntries <var>number</var></a></td><td> 1024 </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Number of entries used to cache LDAP compare
operations</td></tr>
-<tr class="odd"><td><a href="mod_ldap.html#ldapopcachettl">LDAPOpCacheTTL <var>seconds</var></a></td><td> 600 </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Time that entries in the operation cache remain
+<tr><td><a href="mod_ldap.html#ldapopcachettl">LDAPOpCacheTTL <var>seconds</var></a></td><td> 600 </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Time that entries in the operation cache remain
valid</td></tr>
-<tr><td><a href="mod_ldap.html#ldapreferralhoplimit">LDAPReferralHopLimit <var>number</var></a></td><td></td><td>dh</td><td>E</td></tr><tr><td class="descr" colspan="4">The maximum number of referral hops to chase before terminating an LDAP query.</td></tr>
-<tr class="odd"><td><a href="mod_ldap.html#ldapreferrals">LDAPReferrals <var>On|Off|default</var></a></td><td> On </td><td>dh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable referral chasing during queries to the LDAP server.</td></tr>
-<tr><td><a href="mod_ldap.html#ldapretries">LDAPRetries <var>number-of-retries</var></a></td><td> 3 </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Configures the number of LDAP server retries.</td></tr>
-<tr class="odd"><td><a href="mod_ldap.html#ldapretrydelay">LDAPRetryDelay <var>seconds</var></a></td><td> 0 </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Configures the delay between LDAP server retries.</td></tr>
-<tr><td><a href="mod_ldap.html#ldapsharedcachefile">LDAPSharedCacheFile <var>directory-path/filename</var></a></td><td></td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Sets the shared memory cache file</td></tr>
-<tr class="odd"><td><a href="mod_ldap.html#ldapsharedcachesize">LDAPSharedCacheSize <var>bytes</var></a></td><td> 500000 </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Size in bytes of the shared-memory cache</td></tr>
-<tr><td><a href="mod_ldap.html#ldaptimeout">LDAPTimeout <var>seconds</var></a></td><td> 60 </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Specifies the timeout for LDAP search and bind operations, in seconds</td></tr>
-<tr class="odd"><td><a href="mod_ldap.html#ldaptrustedclientcert">LDAPTrustedClientCert <var>type</var> <var>directory-path/filename/nickname</var> <var>[password]</var></a></td><td></td><td>dh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Sets the file containing or nickname referring to a per
+<tr class="odd"><td><a href="mod_ldap.html#ldapreferralhoplimit">LDAPReferralHopLimit <var>number</var></a></td><td></td><td>dh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">The maximum number of referral hops to chase before terminating an LDAP query.</td></tr>
+<tr><td><a href="mod_ldap.html#ldapreferrals">LDAPReferrals <var>On|Off|default</var></a></td><td> On </td><td>dh</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable referral chasing during queries to the LDAP server.</td></tr>
+<tr class="odd"><td><a href="mod_ldap.html#ldapretries">LDAPRetries <var>number-of-retries</var></a></td><td> 3 </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Configures the number of LDAP server retries.</td></tr>
+<tr><td><a href="mod_ldap.html#ldapretrydelay">LDAPRetryDelay <var>seconds</var></a></td><td> 0 </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Configures the delay between LDAP server retries.</td></tr>
+<tr class="odd"><td><a href="mod_ldap.html#ldapsharedcachefile">LDAPSharedCacheFile <var>directory-path/filename</var></a></td><td></td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Sets the shared memory cache file</td></tr>
+<tr><td><a href="mod_ldap.html#ldapsharedcachesize">LDAPSharedCacheSize <var>bytes</var></a></td><td> 500000 </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Size in bytes of the shared-memory cache</td></tr>
+<tr class="odd"><td><a href="mod_ldap.html#ldaptimeout">LDAPTimeout <var>seconds</var></a></td><td> 60 </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Specifies the timeout for LDAP search and bind operations, in seconds</td></tr>
+<tr><td><a href="mod_ldap.html#ldaptrustedclientcert">LDAPTrustedClientCert <var>type</var> <var>directory-path/filename/nickname</var> <var>[password]</var></a></td><td></td><td>dh</td><td>E</td></tr><tr><td class="descr" colspan="4">Sets the file containing or nickname referring to a per
connection client certificate. Not all LDAP toolkits support per
connection client certificates.</td></tr>
-<tr><td><a href="mod_ldap.html#ldaptrustedglobalcert">LDAPTrustedGlobalCert <var>type</var> <var>directory-path/filename</var> <var>[password]</var></a></td><td></td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Sets the file or database containing global trusted
+<tr class="odd"><td><a href="mod_ldap.html#ldaptrustedglobalcert">LDAPTrustedGlobalCert <var>type</var> <var>directory-path/filename</var> <var>[password]</var></a></td><td></td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Sets the file or database containing global trusted
Certificate Authority or global client certificates</td></tr>
-<tr class="odd"><td><a href="mod_ldap.html#ldaptrustedmode">LDAPTrustedMode <var>type</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Specifies the SSL/TLS mode to be used when connecting to an LDAP server.</td></tr>
-<tr><td><a href="mod_ldap.html#ldapverifyservercert">LDAPVerifyServerCert <var>On|Off</var></a></td><td> On </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Force server certificate verification</td></tr>
-<tr
class="odd"><td><a href="core.html#limit"><Limit <var>method</var> [<var>method</var>] ... > ...
- </Limit></a></td><td></td><td>dh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Restrict enclosed access controls to only certain HTTP
+<tr><td><a href="mod_ldap.html#ldaptrustedmode">LDAPTrustedMode <var>type</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Specifies the SSL/TLS mode to be used when connecting to an LDAP server.</td></tr>
+<tr class="odd"><td><a href="mod_ldap.html#ldapverifyservercert">LDAPVerifyServerCert <var>On|Off</var></a></td><td> On </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Force server certificate verification</td></tr>
+<tr><td><a href="core.html#limit"><Limit <var>method</var> [<var>method</var>] ... > ...
+ </Limit></a></td><td></td><td>dh</td><td>C</td></tr><tr><td class="descr" colspan="4">Restrict enclosed access controls to only certain HTTP
methods</td></tr>
-<tr><td><a href="core.html#limitexcept"><LimitExcept <var>method</var> [<var>method</var>] ... > ...
- </LimitExcept></a></td><td></td><td>dh</td><td>C</td></tr><tr><td class="descr" colspan="4">Restrict access controls to all HTTP methods
+<tr
class="odd"><td><a href="core.html#limitexcept"><LimitExcept <var>method</var> [<var>method</var>] ... > ...
+ </LimitExcept></a></td><td></td><td>dh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Restrict access controls to all HTTP methods
except the named ones</td></tr>
-<tr class="odd"><td><a href="core.html#limitinternalrecursion">LimitInternalRecursion <var>number</var> [<var>number</var>]</a></td><td> 10 </td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Determine maximum number of internal redirects and nested
+<tr><td><a href="core.html#limitinternalrecursion">LimitInternalRecursion <var>number</var> [<var>number</var>]</a></td><td> 10 </td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Determine maximum number of internal redirects and nested
subrequests</td></tr>
-<tr><td><a href="core.html#limitrequestbody">LimitRequestBody <var>bytes</var></a></td><td> 0 </td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Restricts the total size of the HTTP request body sent
+<tr class="odd"><td><a href="core.html#limitrequestbody">LimitRequestBody <var>bytes</var></a></td><td> 0 </td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Restricts the total size of the HTTP request body sent
from the client</td></tr>
-<tr class="odd"><td><a href="core.html#limitrequestfields">LimitRequestFields <var>number</var></a></td><td> 100 </td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Limits the number of HTTP request header fields that
+<tr><td><a href="core.html#limitrequestfields">LimitRequestFields <var>number</var></a></td><td> 100 </td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Limits the number of HTTP request header fields that
will be accepted from the client</td></tr>
-<tr><td><a href="core.html#limitrequestfieldsize">LimitRequestFieldSize <var>bytes</var></a></td><td> 8190 </td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Limits the size of the HTTP request header allowed from the
+<tr class="odd"><td><a href="core.html#limitrequestfieldsize">LimitRequestFieldSize <var>bytes</var></a></td><td> 8190 </td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Limits the size of the HTTP request header allowed from the
client</td></tr>
-<tr class="odd"><td><a href="core.html#limitrequestline">LimitRequestLine <var>bytes</var></a></td><td> 8190 </td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Limit the size of the HTTP request line that will be accepted
+<tr><td><a href="core.html#limitrequestline">LimitRequestLine <var>bytes</var></a></td><td> 8190 </td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Limit the size of the HTTP request line that will be accepted
from the client</td></tr>
-<tr><td><a href="core.html#limitxmlrequestbody">LimitXMLRequestBody <var>bytes</var></a></td><td> 1000000 </td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Limits the size of an XML-based request body</td></tr>
-<tr class="odd"><td><a href="mpm_common.html#listen">Listen [<var>IP-address</var>:]<var>portnumber</var> [<var>protocol</var>]</a></td><td></td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">IP addresses and ports that the server
+<tr class="odd"><td><a href="core.html#limitxmlrequestbody">LimitXMLRequestBody <var>bytes</var></a></td><td> 1000000 </td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Limits the size of an XML-based request body</td></tr>
+<tr><td><a href="mpm_common.html#listen">Listen [<var>IP-address</var>:]<var>portnumber</var> [<var>protocol</var>]</a></td><td></td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">IP addresses and ports that the server
listens to</td></tr>
-<tr><td><a href="mpm_common.html#listenbacklog">ListenBacklog <var>backlog</var></a></td><td></td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Maximum length of the queue of pending connections</td></tr>
-<tr class="odd"><td><a href="mod_so.html#loadfile">LoadFile <em>filename</em> [<em>filename</em>] ...</a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Link in the named object file or library</td></tr>
-<tr><td><a href="mod_so.html#loadmodule">LoadModule <em>module filename</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Links in the object file or library, and adds to the list
+<tr class="odd"><td><a href="mpm_common.html#listenbacklog">ListenBacklog <var>backlog</var></a></td><td></td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum length of the queue of pending connections</td></tr>
+<tr><td><a href="mod_so.html#loadfile">LoadFile <em>filename</em> [<em>filename</em>] ...</a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Link in the named object file or library</td></tr>
+<tr class="odd"><td><a href="mod_so.html#loadmodule">LoadModule <em>module filename</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Links in the object file or library, and adds to the list
of active modules</td></tr>
-<tr
class="odd"><td><a href="core.html#location"><Location
- "<var>URL-path</var>|<var>URL</var>"> ... </Location></a></td><td></td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Applies the enclosed directives only to matching
+<tr><td><a href="core.html#location"><Location
+ "<var>URL-path</var>|<var>URL</var>"> ... </Location></a></td><td></td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Applies the enclosed directives only to matching
URLs</td></tr>
-<tr><td><a href="core.html#locationmatch"><LocationMatch
- <var>regex</var>> ... </LocationMatch></a></td><td></td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Applies the enclosed directives only to regular-expression
+<tr
class="odd"><td><a href="core.html#locationmatch"><LocationMatch
+ <var>regex</var>> ... </LocationMatch></a></td><td></td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Applies the enclosed directives only to regular-expression
matching URLs</td></tr>
-<tr
class="odd"><td><a href="mod_log_config.html#logformat">LogFormat <var>format</var>|<var>nickname</var>
-[<var>nickname</var>]</a></td><td> "%h %l %u %t \"%r\" +</td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Describes a format for use in a log file</td></tr>
-<tr><td><a href="core.html#loglevel">LogLevel [<var>module</var>:]<var>level</var>
+<tr><td><a href="mod_log_config.html#logformat">LogFormat <var>format</var>|<var>nickname</var>
+[<var>nickname</var>]</a></td><td> "%h %l %u %t \"%r\" +</td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Describes a format for use in a log file</td></tr>
+<tr
class="odd"><td><a href="core.html#loglevel">LogLevel [<var>module</var>:]<var>level</var>
[<var>module</var>:<var>level</var>] ...
-</a></td><td> warn </td><td>svd</td><td>C</td></tr><tr><td class="descr" colspan="4">Controls the verbosity of the ErrorLog</td></tr>
-<tr
class="odd"><td><a href="mod_log_debug.html#logmessage">LogMessage <var>message</var>
+</a></td><td> warn </td><td>svd</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Controls the verbosity of the ErrorLog</td></tr>
+<tr><td><a href="mod_log_debug.html#logmessage">LogMessage <var>message</var>
[hook=<var>hook</var>] [expr=<var>expression</var>]
-</a></td><td></td><td>d</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Log user-defined message to error log
+</a></td><td></td><td>d</td><td>X</td></tr><tr><td class="descr" colspan="4">Log user-defined message to error log
</td></tr>
-<tr
><td><a href="mod_lua.html#luaauthzprovider">LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</a></td><td></td><td>s</td><td>X</td></tr><tr><td class="descr" colspan="4">Plug an authorization provider function into <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code>
+<tr
class="odd"><td><a href="mod_lua.html#luaauthzprovider">LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</a></td><td></td><td>s</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Plug an authorization provider function into <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code>
</td></tr>
-<tr class="odd"><td><a href="mod_lua.html#luacodecache">LuaCodeCache stat|forever|never</a></td><td> stat </td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Configure the compiled code cache.</td></tr>
-<tr><td><a href="mod_lua.html#luahookaccesschecker">LuaHookAccessChecker /path/to/lua/script.lua hook_function_name [early|late]</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Provide a hook for the access_checker phase of request processing</td></tr>
-<tr class="odd"><td><a href="mod_lua.html#luahookauthchecker">LuaHookAuthChecker /path/to/lua/script.lua hook_function_name [early|late]</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Provide a hook for the auth_checker phase of request processing</td></tr>
-<tr><td><a href="mod_lua.html#luahookcheckuserid">LuaHookCheckUserID /path/to/lua/script.lua hook_function_name [early|late]</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Provide a hook for the check_user_id phase of request processing</td></tr>
-<tr class="odd"><td><a href="mod_lua.html#luahookfixups">LuaHookFixups /path/to/lua/script.lua hook_function_name</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Provide a hook for the fixups phase of a request
+<tr><td><a href="mod_lua.html#luacodecache">LuaCodeCache stat|forever|never</a></td><td> stat </td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Configure the compiled code cache.</td></tr>
+<tr class="odd"><td><a href="mod_lua.html#luahookaccesschecker">LuaHookAccessChecker /path/to/lua/script.lua hook_function_name [early|late]</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Provide a hook for the access_checker phase of request processing</td></tr>
+<tr><td><a href="mod_lua.html#luahookauthchecker">LuaHookAuthChecker /path/to/lua/script.lua hook_function_name [early|late]</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Provide a hook for the auth_checker phase of request processing</td></tr>
+<tr class="odd"><td><a href="mod_lua.html#luahookcheckuserid">LuaHookCheckUserID /path/to/lua/script.lua hook_function_name [early|late]</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Provide a hook for the check_user_id phase of request processing</td></tr>
+<tr><td><a href="mod_lua.html#luahookfixups">LuaHookFixups /path/to/lua/script.lua hook_function_name</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Provide a hook for the fixups phase of a request
processing</td></tr>
-<tr><td><a href="mod_lua.html#luahookinsertfilter">LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Provide a hook for the insert_filter phase of request processing</td></tr>
-<tr class="odd"><td><a href="mod_lua.html#luahooklog">LuaHookLog /path/to/lua/script.lua log_function_name</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Provide a hook for the access log phase of a request
+<tr class="odd"><td><a href="mod_lua.html#luahookinsertfilter">LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Provide a hook for the insert_filter phase of request processing</td></tr>
+<tr><td><a href="mod_lua.html#luahooklog">LuaHookLog /path/to/lua/script.lua log_function_name</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Provide a hook for the access log phase of a request
processing</td></tr>
-<tr><td><a href="mod_lua.html#luahookmaptostorage">LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Provide a hook for the map_to_storage phase of request processing</td></tr>
-<tr class="odd"><td><a href="mod_lua.html#luahooktranslatename">LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]</a></td><td></td><td>sv</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Provide a hook for the translate name phase of request processing</td></tr>
-<tr><td><a href="mod_lua.html#luahooktypechecker">LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Provide a hook for the type_checker phase of request processing</td></tr>
-<tr class="odd"><td><a href="mod_lua.html#luainherit">LuaInherit none|parent-first|parent-last</a></td><td> parent-first </td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Controls how parent configuration sections are merged into children</td></tr>
-<tr><td><a href="mod_lua.html#luainputfilter">LuaInputFilter filter_name /path/to/lua/script.lua function_name</a></td><td></td><td>s</td><td>X</td></tr><tr><td class="descr" colspan="4">Provide a Lua function for content input filtering</td></tr>
-<tr class="odd"><td><a href="mod_lua.html#luamaphandler">LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Map a path to a lua handler</td></tr>
-<tr><td><a href="mod_lua.html#luaoutputfilter">LuaOutputFilter filter_name /path/to/lua/script.lua function_name</a></td><td></td><td>s</td><td>X</td></tr><tr><td class="descr" colspan="4">Provide a Lua function for content output filtering</td></tr>
-<tr class="odd"><td><a href="mod_lua.html#luapackagecpath">LuaPackageCPath /path/to/include/?.soa</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Add a directory to lua's package.cpath</td></tr>
-<tr><td><a href="mod_lua.html#luapackagepath">LuaPackagePath /path/to/include/?.lua</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Add a directory to lua's package.path</td></tr>
-<tr class="odd"><td><a href="mod_lua.html#luaquickhandler">LuaQuickHandler /path/to/script.lua hook_function_name</a></td><td></td><td>sv</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Provide a hook for the quick handler of request processing</td></tr>
-<tr><td><a href="mod_lua.html#luaroot">LuaRoot /path/to/a/directory</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Specify the base path for resolving relative paths for mod_lua directives</td></tr>
-<tr class="odd"><td><a href="mod_lua.html#luascope">LuaScope once|request|conn|thread|server [min] [max]</a></td><td> once </td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">One of once, request, conn, thread -- default is once</td></tr>
-<tr><td><a href="mod_macro.html#macro" id="M" name="M">
+<tr class="odd"><td><a href="mod_lua.html#luahookmaptostorage">LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Provide a hook for the map_to_storage phase of request processing</td></tr>
+<tr><td><a href="mod_lua.html#luahooktranslatename">LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]</a></td><td></td><td>sv</td><td>X</td></tr><tr><td class="descr" colspan="4">Provide a hook for the translate name phase of request processing</td></tr>
+<tr class="odd"><td><a href="mod_lua.html#luahooktypechecker">LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Provide a hook for the type_checker phase of request processing</td></tr>
+<tr><td><a href="mod_lua.html#luainherit">LuaInherit none|parent-first|parent-last</a></td><td> parent-first </td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Controls how parent configuration sections are merged into children</td></tr>
+<tr class="odd"><td><a href="mod_lua.html#luainputfilter">LuaInputFilter filter_name /path/to/lua/script.lua function_name</a></td><td></td><td>s</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Provide a Lua function for content input filtering</td></tr>
+<tr><td><a href="mod_lua.html#luamaphandler">LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Map a path to a lua handler</td></tr>
+<tr class="odd"><td><a href="mod_lua.html#luaoutputfilter">LuaOutputFilter filter_name /path/to/lua/script.lua function_name</a></td><td></td><td>s</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Provide a Lua function for content output filtering</td></tr>
+<tr><td><a href="mod_lua.html#luapackagecpath">LuaPackageCPath /path/to/include/?.soa</a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">Add a directory to lua's package.cpath</td></tr>
+<tr class="odd"><td><a href="mod_lua.html#luapackagepath">LuaPackagePath /path/to/include/?.lua</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Add a directory to lua's package.path</td></tr>
+<tr><td><a href="mod_lua.html#luaquickhandler">LuaQuickHandler /path/to/script.lua hook_function_name</a></td><td></td><td>sv</td><td>X</td></tr><tr><td class="descr" colspan="4">Provide a hook for the quick handler of request processing</td></tr>
+<tr class="odd"><td><a href="mod_lua.html#luaroot">LuaRoot /path/to/a/directory</a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Specify the base path for resolving relative paths for mod_lua directives</td></tr>
+<tr><td><a href="mod_lua.html#luascope">LuaScope once|request|conn|thread|server [min] [max]</a></td><td> once </td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">One of once, request, conn, thread -- default is once</td></tr>
+<tr
class="odd"><td><a href="mod_macro.html#macro" id="M" name="M">
<Macro <var>name</var> [<var>par1</var> .. <var>parN</var>]>
-... </Macro></a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Define a configuration file macro</td></tr>
-<tr class="odd"><td><a href="mpm_common.html#maxconnectionsperchild">MaxConnectionsPerChild <var>number</var></a></td><td> 0 </td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Limit on the number of connections that an individual child server
+... </Macro></a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Define a configuration file macro</td></tr>
+<tr><td><a href="mpm_common.html#maxconnectionsperchild">MaxConnectionsPerChild <var>number</var></a></td><td> 0 </td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Limit on the number of connections that an individual child server
will handle during its life</td></tr>
-<tr><td><a href="core.html#maxkeepaliverequests">MaxKeepAliveRequests <var>number</var></a></td><td> 100 </td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Number of requests allowed on a persistent
+<tr class="odd"><td><a href="core.html#maxkeepaliverequests">MaxKeepAliveRequests <var>number</var></a></td><td> 100 </td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Number of requests allowed on a persistent
connection</td></tr>
-<tr class="odd"><td><a href="mpm_common.html#maxmemfree">MaxMemFree <var>KBytes</var></a></td><td> 2048 </td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum amount of memory that the main allocator is allowed
+<tr><td><a href="mpm_common.html#maxmemfree">MaxMemFree <var>KBytes</var></a></td><td> 2048 </td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Maximum amount of memory that the main allocator is allowed
to hold without calling <code>free()</code></td></tr>
-<tr><td><a href="core.html#maxrangeoverlaps">MaxRangeOverlaps default | unlimited | none | <var>number-of-ranges</var></a></td><td> 20 </td><td>svd</td><td>C</td></tr><tr><td class="descr" colspan="4">Number of overlapping ranges (eg: <code>100-200,150-300</code>) allowed before returning the complete
+<tr class="odd"><td><a href="core.html#maxrangeoverlaps">MaxRangeOverlaps default | unlimited | none | <var>number-of-ranges</var></a></td><td> 20 </td><td>svd</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Number of overlapping ranges (eg: <code>100-200,150-300</code>) allowed before returning the complete
resource </td></tr>
-<tr class="odd"><td><a href="core.html#maxrangereversals">MaxRangeReversals default | unlimited | none | <var>number-of-ranges</var></a></td><td> 20 </td><td>svd</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Number of range reversals (eg: <code>100-200,50-70</code>) allowed before returning the complete
+<tr><td><a href="core.html#maxrangereversals">MaxRangeReversals default | unlimited | none | <var>number-of-ranges</var></a></td><td> 20 </td><td>svd</td><td>C</td></tr><tr><td class="descr" colspan="4">Number of range reversals (eg: <code>100-200,50-70</code>) allowed before returning the complete
resource </td></tr>
-<tr><td><a href="core.html#maxranges">MaxRanges default | unlimited | none | <var>number-of-ranges</var></a></td><td> 200 </td><td>svd</td><td>C</td></tr><tr><td class="descr" colspan="4">Number of ranges allowed before returning the complete
+<tr class="odd"><td><a href="core.html#maxranges">MaxRanges default | unlimited | none | <var>number-of-ranges</var></a></td><td> 200 </td><td>svd</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Number of ranges allowed before returning the complete
resource </td></tr>
-<tr class="odd"><td><a href="mpm_common.html#maxrequestworkers">MaxRequestWorkers <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum number of connections that will be processed
+<tr><td><a href="mpm_common.html#maxrequestworkers">MaxRequestWorkers <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Maximum number of connections that will be processed
simultaneously</td></tr>
-<tr><td><a href="prefork.html#maxspareservers">MaxSpareServers <var>number</var></a></td><td> 10 </td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Maximum number of idle child server processes</td></tr>
-<tr class="odd"><td><a href="mpm_common.html#maxsparethreads">MaxSpareThreads <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum number of idle threads</td></tr>
-<tr><td><a href="mpm_netware.html#maxthreads">MaxThreads <var>number</var></a></td><td> 2048 </td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Set the maximum number of worker threads</td></tr>
-<tr class="odd"><td><a href="core.html#mergetrailers">MergeTrailers [on|off]</a></td><td> off </td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Determins whether trailers are merged into headers</td></tr>
-<tr><td><a href="mod_cern_meta.html#metadir">MetaDir <var>directory</var></a></td><td> .web </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Name of the directory to find CERN-style meta information
+<tr class="odd"><td><a href="prefork.html#maxspareservers">MaxSpareServers <var>number</var></a></td><td> 10 </td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum number of idle child server processes</td></tr>
+<tr><td><a href="mpm_common.html#maxsparethreads">MaxSpareThreads <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Maximum number of idle threads</td></tr>
+<tr class="odd"><td><a href="mpm_netware.html#maxthreads">MaxThreads <var>number</var></a></td><td> 2048 </td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Set the maximum number of worker threads</td></tr>
+<tr><td><a href="core.html#mergetrailers">MergeTrailers [on|off]</a></td><td> off </td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Determins whether trailers are merged into headers</td></tr>
+<tr class="odd"><td><a href="mod_cern_meta.html#metadir">MetaDir <var>directory</var></a></td><td> .web </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Name of the directory to find CERN-style meta information
files</td></tr>
-<tr class="odd"><td><a href="mod_cern_meta.html#metafiles">MetaFiles on|off</a></td><td> off </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Activates CERN meta-file processing</td></tr>
-<tr><td><a href="mod_cern_meta.html#metasuffix">MetaSuffix <var>suffix</var></a></td><td> .meta </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">File name suffix for the file containing CERN-style
+<tr><td><a href="mod_cern_meta.html#metafiles">MetaFiles on|off</a></td><td> off </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Activates CERN meta-file processing</td></tr>
+<tr class="odd"><td><a href="mod_cern_meta.html#metasuffix">MetaSuffix <var>suffix</var></a></td><td> .meta </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">File name suffix for the file containing CERN-style
meta information</td></tr>
-<tr class="odd"><td><a href="mod_mime_magic.html#mimemagicfile">MimeMagicFile <var>file-path</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable MIME-type determination based on file contents
+<tr><td><a href="mod_mime_magic.html#mimemagicfile">MimeMagicFile <var>file-path</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable MIME-type determination based on file contents
using the specified magic file</td></tr>
-<tr><td><a href="prefork.html#minspareservers">MinSpareServers <var>number</var></a></td><td> 5 </td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Minimum number of idle child server processes</td></tr>
-<tr class="odd"><td><a href="mpm_common.html#minsparethreads">MinSpareThreads <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Minimum number of idle threads available to handle request
+<tr class="odd"><td><a href="prefork.html#minspareservers">MinSpareServers <var>number</var></a></td><td> 5 </td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Minimum number of idle child server processes</td></tr>
+<tr><td><a href="mpm_common.html#minsparethreads">MinSpareThreads <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Minimum number of idle threads available to handle request
spikes</td></tr>
-<tr><td><a href="mod_file_cache.html#mmapfile">MMapFile <var>file-path</var> [<var>file-path</var>] ...</a></td><td></td><td>s</td><td>X</td></tr><tr><td class="descr" colspan="4">Map a list of files into memory at startup time</td></tr>
-<tr class="odd"><td><a href="mod_dialup.html#modemstandard">ModemStandard V.21|V.26bis|V.32|V.92</a></td><td></td><td>d</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Modem standard to simulate</td></tr>
-<tr
><td><a href="mod_mime.html#modmimeusepathinfo">ModMimeUsePathInfo On|Off</a></td><td> Off </td><td>d</td><td>B</td></tr><tr><td class="descr" colspan="4">Tells <code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code> to treat <code>path_info</code>
+<tr class="odd"><td><a href="mod_file_cache.html#mmapfile">MMapFile <var>file-path</var> [<var>file-path</var>] ...</a></td><td></td><td>s</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Map a list of files into memory at startup time</td></tr>
+<tr><td><a href="mod_dialup.html#modemstandard">ModemStandard V.21|V.26bis|V.32|V.92</a></td><td></td><td>d</td><td>X</td></tr><tr><td class="descr" colspan="4">Modem standard to simulate</td></tr>
+<tr
class="odd"><td><a href="mod_mime.html#modmimeusepathinfo">ModMimeUsePathInfo On|Off</a></td><td> Off </td><td>d</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Tells <code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code> to treat <code>path_info</code>
components as part of the filename</td></tr>
-<tr
class="odd"><td><a href="mod_mime.html#multiviewsmatch">MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers
-[Handlers|Filters]</a></td><td> NegotiatedOnly </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">The types of files that will be included when searching for
+<tr><td><a href="mod_mime.html#multiviewsmatch">MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers
+[Handlers|Filters]</a></td><td> NegotiatedOnly </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">The types of files that will be included when searching for
a matching file with MultiViews</td></tr>
-<tr><td><a href="core.html#mutex">Mutex <var>mechanism</var> [default|<var>mutex-name</var>] ... [OmitPID]</a></td><td> default </td><td>s</td><td>C</td></tr><tr><td class="descr" colspan="4">Configures mutex mechanism and lock file directory for all
+<tr class="odd"><td><a href="core.html#mutex">Mutex <var>mechanism</var> [default|<var>mutex-name</var>] ... [OmitPID]</a></td><td> default </td><td>s</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Configures mutex mechanism and lock file directory for all
or specified mutexes</td></tr>
-<tr class="odd"><td><a href="core.html#namevirtualhost" id="N" name="N">NameVirtualHost <var>addr</var>[:<var>port</var>]</a></td><td></td><td>s</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">DEPRECATED: Designates an IP address for name-virtual
+<tr><td><a href="core.html#namevirtualhost" id="N" name="N">NameVirtualHost <var>addr</var>[:<var>port</var>]</a></td><td></td><td>s</td><td>C</td></tr><tr><td class="descr" colspan="4">DEPRECATED: Designates an IP address for name-virtual
hosting</td></tr>
-<tr><td><a href="mod_proxy.html#noproxy">NoProxy <var>host</var> [<var>host</var>] ...</a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Hosts, domains, or networks that will be connected to
+<tr class="odd"><td><a href="mod_proxy.html#noproxy">NoProxy <var>host</var> [<var>host</var>] ...</a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Hosts, domains, or networks that will be connected to
directly</td></tr>
-<tr class="odd"><td><a href="mod_nw_ssl.html#nwssltrustedcerts">NWSSLTrustedCerts <var>filename</var> [<var>filename</var>] ...</a></td><td></td><td>s</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">List of additional client certificates</td></tr>
-<tr><td><a href="mod_nw_ssl.html#nwsslupgradeable">NWSSLUpgradeable [<var>IP-address</var>:]<var>portnumber</var></a></td><td></td><td>s</td><td>B</td></tr><tr><td class="descr" colspan="4">Allows a connection to be upgraded to an SSL connection upon request</td></tr>
-<tr
class="odd"><td><a href="core.html#options" id="O" name="O">Options
- [+|-]<var>option</var> [[+|-]<var>option</var>] ...</a></td><td> FollowSymlinks </td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Configures what features are available in a particular
+<tr><td><a href="mod_nw_ssl.html#nwssltrustedcerts">NWSSLTrustedCerts <var>filename</var> [<var>filename</var>] ...</a></td><td></td><td>s</td><td>B</td></tr><tr><td class="descr" colspan="4">List of additional client certificates</td></tr>
+<tr class="odd"><td><a href="mod_nw_ssl.html#nwsslupgradeable">NWSSLUpgradeable [<var>IP-address</var>:]<var>portnumber</var></a></td><td></td><td>s</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Allows a connection to be upgraded to an SSL connection upon request</td></tr>
+<tr><td><a href="core.html#options" id="O" name="O">Options
+ [+|-]<var>option</var> [[+|-]<var>option</var>] ...</a></td><td> FollowSymlinks </td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Configures what features are available in a particular
directory</td></tr>
-<tr><td><a href="mod_access_compat.html#order"> Order <var>ordering</var></a></td><td> Deny,Allow </td><td>dh</td><td>E</td></tr><tr><td class="descr" colspan="4">Controls the default access state and the order in which
+<tr class="odd"><td><a href="mod_access_compat.html#order"> Order <var>ordering</var></a></td><td> Deny,Allow </td><td>dh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Controls the default access state and the order in which
<code class="directive">Allow</code> and <code class="directive">Deny</code> are
evaluated.</td></tr>
-<tr class="odd"><td><a href="mod_sed.html#outputsed">OutputSed <var>sed-command</var></a></td><td></td><td>dh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Sed command for filtering response content</td></tr>
-<tr><td><a href="mod_env.html#passenv" id="P" name="P">PassEnv <var>env-variable</var> [<var>env-variable</var>]
-...</a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Passes environment variables from the shell</td></tr>
-<tr class="odd"><td><a href="mpm_common.html#pidfile">PidFile <var>filename</var></a></td><td> logs/httpd.pid </td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">File where the server records the process ID
+<tr><td><a href="mod_sed.html#outputsed">OutputSed <var>sed-command</var></a></td><td></td><td>dh</td><td>X</td></tr><tr><td class="descr" colspan="4">Sed command for filtering response content</td></tr>
+<tr
class="odd"><td><a href="mod_env.html#passenv" id="P" name="P">PassEnv <var>env-variable</var> [<var>env-variable</var>]
+...</a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Passes environment variables from the shell</td></tr>
+<tr><td><a href="mpm_common.html#pidfile">PidFile <var>filename</var></a></td><td> logs/httpd.pid </td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">File where the server records the process ID
of the daemon</td></tr>
-<tr><td><a href="mod_privileges.html#privilegesmode">PrivilegesMode FAST|SECURE|SELECTIVE</a></td><td> FAST </td><td>svd</td><td>X</td></tr><tr><td class="descr" colspan="4">Trade off processing speed and efficiency vs security against
+<tr class="odd"><td><a href="mod_privileges.html#privilegesmode">PrivilegesMode FAST|SECURE|SELECTIVE</a></td><td> FAST </td><td>svd</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Trade off processing speed and efficiency vs security against
malicious privileges-aware code.</td></tr>
-<tr class="odd"><td><a href="core.html#protocol">Protocol <var>protocol</var></a></td><td></td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Protocol for a listening socket</td></tr>
-<tr><td><a href="mod_echo.html#protocolecho">ProtocolEcho On|Off</a></td><td> Off </td><td>sv</td><td>X</td></tr><tr><td class="descr" colspan="4">Turn the echo server on or off</td></tr>
-<tr class="odd"><td><a href="mod_proxy.html#proxy"><Proxy <var>wildcard-url</var>> ...</Proxy></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Container for directives applied to proxied resources</td></tr>
-<tr><td><a href="mod_proxy.html#proxyaddheaders">ProxyAddHeaders Off|On</a></td><td> On </td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Add proxy information in X-Forwarded-* headers</td></tr>
-<tr class="odd"><td><a href="mod_proxy.html#proxybadheader">ProxyBadHeader IsError|Ignore|StartBody</a></td><td> IsError </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Determines how to handle bad header lines in a
+<tr><td><a href="core.html#protocol">Protocol <var>protocol</var></a></td><td></td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Protocol for a listening socket</td></tr>
+<tr class="odd"><td><a href="mod_echo.html#protocolecho">ProtocolEcho On|Off</a></td><td> Off </td><td>sv</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Turn the echo server on or off</td></tr>
+<tr><td><a href="mod_proxy.html#proxy"><Proxy <var>wildcard-url</var>> ...</Proxy></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Container for directives applied to proxied resources</td></tr>
+<tr class="odd"><td><a href="mod_proxy.html#proxyaddheaders">ProxyAddHeaders Off|On</a></td><td> On </td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Add proxy information in X-Forwarded-* headers</td></tr>
+<tr><td><a href="mod_proxy.html#proxybadheader">ProxyBadHeader IsError|Ignore|StartBody</a></td><td> IsError </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Determines how to handle bad header lines in a
response</td></tr>
-<tr><td><a href="mod_proxy.html#proxyblock">ProxyBlock *|<var>word</var>|<var>host</var>|<var>domain</var>
-[<var>word</var>|<var>host</var>|<var>domain</var>] ...</a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Words, hosts, or domains that are banned from being
+<tr
class="odd"><td><a href="mod_proxy.html#proxyblock">ProxyBlock *|<var>word</var>|<var>host</var>|<var>domain</var>
+[<var>word</var>|<var>host</var>|<var>domain</var>] ...</a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Words, hosts, or domains that are banned from being
proxied</td></tr>
-<tr class="odd"><td><a href="mod_proxy.html#proxydomain">ProxyDomain <var>Domain</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Default domain name for proxied requests</td></tr>
-<tr><td><a href="mod_proxy.html#proxyerroroverride">ProxyErrorOverride On|Off</a></td><td> Off </td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Override error pages for proxied content</td></tr>
-<tr class="odd"><td><a href="mod_proxy_express.html#proxyexpressdbmfile">ProxyExpressDBMFile <pathname></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Pathname to DBM file.</td></tr>
-<tr><td><a href="mod_proxy_express.html#proxyexpressdbmtype">ProxyExpressDBMFile <type></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">DBM type of file.</td></tr>
-<tr class="odd"><td><a href="mod_proxy_express.html#proxyexpressenable">ProxyExpressEnable [on|off]</a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable the module functionality.</td></tr>
-<tr><td><a href="mod_proxy_ftp.html#proxyftpdircharset">ProxyFtpDirCharset <var>character set</var></a></td><td> ISO-8859-1 </td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Define the character set for proxied FTP listings</td></tr>
-<tr class="odd"><td><a href="mod_proxy_ftp.html#proxyftpescapewildcards">ProxyFtpEscapeWildcards [on|off]</a></td><td></td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Whether wildcards in requested filenames are escaped when sent to the FTP server</td></tr>
-<tr><td><a href="mod_proxy_ftp.html#proxyftplistonwildcard">ProxyFtpListOnWildcard [on|off]</a></td><td></td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Whether wildcards in requested filenames trigger a file listing</td></tr>
-<tr class="odd"><td><a href="mod_proxy_html.html#proxyhtmlbufsize">ProxyHTMLBufSize <var>bytes</var></a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sets the buffer size increment for buffering inline scripts and
+<tr><td><a href="mod_proxy.html#proxydomain">ProxyDomain <var>Domain</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Default domain name for proxied requests</td></tr>
+<tr class="odd"><td><a href="mod_proxy.html#proxyerroroverride">ProxyErrorOverride On|Off</a></td><td> Off </td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Override error pages for proxied content</td></tr>
+<tr><td><a href="mod_proxy_express.html#proxyexpressdbmfile">ProxyExpressDBMFile <pathname></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Pathname to DBM file.</td></tr>
+<tr class="odd"><td><a href="mod_proxy_express.html#proxyexpressdbmtype">ProxyExpressDBMFile <type></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">DBM type of file.</td></tr>
+<tr><td><a href="mod_proxy_express.html#proxyexpressenable">ProxyExpressEnable [on|off]</a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable the module functionality.</td></tr>
+<tr class="odd"><td><a href="mod_proxy_ftp.html#proxyftpdircharset">ProxyFtpDirCharset <var>character set</var></a></td><td> ISO-8859-1 </td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Define the character set for proxied FTP listings</td></tr>
+<tr><td><a href="mod_proxy_ftp.html#proxyftpescapewildcards">ProxyFtpEscapeWildcards [on|off]</a></td><td></td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Whether wildcards in requested filenames are escaped when sent to the FTP server</td></tr>
+<tr class="odd"><td><a href="mod_proxy_ftp.html#proxyftplistonwildcard">ProxyFtpListOnWildcard [on|off]</a></td><td></td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Whether wildcards in requested filenames trigger a file listing</td></tr>
+<tr><td><a href="mod_proxy_html.html#proxyhtmlbufsize">ProxyHTMLBufSize <var>bytes</var></a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Sets the buffer size increment for buffering inline scripts and
stylesheets.</td></tr>
-<tr><td><a href="mod_proxy_html.html#proxyhtmlcharsetout">ProxyHTMLCharsetOut <var>Charset | *</var></a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Specify a charset for mod_proxy_html output.</td></tr>
-<tr
class="odd"><td><a href="mod_proxy_html.html#proxyhtmldoctype">ProxyHTMLDocType <var>HTML|XHTML [Legacy]</var><br /><strong>OR</strong>
-<br />ProxyHTMLDocType <var>fpi [SGML|XML]</var></a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sets an HTML or XHTML document type declaration.</td></tr>
-<tr><td><a href="mod_proxy_html.html#proxyhtmlenable">ProxyHTMLEnable <var>On|Off</var></a></td><td> Off </td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Turns the proxy_html filter on or off.</td></tr>
-<tr class="odd"><td><a href="mod_proxy_html.html#proxyhtmlevents">ProxyHTMLEvents <var>attribute [attribute ...]</var></a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Specify attributes to treat as scripting events.</td></tr>
-<tr><td><a href="mod_proxy_html.html#proxyhtmlextended">ProxyHTMLExtended <var>On|Off</var></a></td><td> Off </td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Determines whether to fix links in inline scripts, stylesheets,
+<tr class="odd"><td><a href="mod_proxy_html.html#proxyhtmlcharsetout">ProxyHTMLCharsetOut <var>Charset | *</var></a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Specify a charset for mod_proxy_html output.</td></tr>
+<tr><td><a href="mod_proxy_html.html#proxyhtmldoctype">ProxyHTMLDocType <var>HTML|XHTML [Legacy]</var><br /><strong>OR</strong>
+<br />ProxyHTMLDocType <var>fpi [SGML|XML]</var></a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Sets an HTML or XHTML document type declaration.</td></tr>
+<tr class="odd"><td><a href="mod_proxy_html.html#proxyhtmlenable">ProxyHTMLEnable <var>On|Off</var></a></td><td> Off </td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Turns the proxy_html filter on or off.</td></tr>
+<tr><td><a href="mod_proxy_html.html#proxyhtmlevents">ProxyHTMLEvents <var>attribute [attribute ...]</var></a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Specify attributes to treat as scripting events.</td></tr>
+<tr class="odd"><td><a href="mod_proxy_html.html#proxyhtmlextended">ProxyHTMLExtended <var>On|Off</var></a></td><td> Off </td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Determines whether to fix links in inline scripts, stylesheets,
and scripting events.</td></tr>
-<tr class="odd"><td><a href="mod_proxy_html.html#proxyhtmlfixups">ProxyHTMLFixups <var>[lowercase] [dospath] [reset]</var></a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Fixes for simple HTML errors.</td></tr>
-<tr><td><a href="mod_proxy_html.html#proxyhtmlinterp">ProxyHTMLInterp <var>On|Off</var></a></td><td> Off </td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Enables per-request interpolation of
+<tr><td><a href="mod_proxy_html.html#proxyhtmlfixups">ProxyHTMLFixups <var>[lowercase] [dospath] [reset]</var></a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Fixes for simple HTML errors.</td></tr>
+<tr class="odd"><td><a href="mod_proxy_html.html#proxyhtmlinterp">ProxyHTMLInterp <var>On|Off</var></a></td><td> Off </td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Enables per-request interpolation of
<code class="directive">ProxyHTMLURLMap</code> rules.</td></tr>
-<tr class="odd"><td><a href="mod_proxy_html.html#proxyhtmllinks">ProxyHTMLLinks <var>element attribute [attribute2 ...]</var></a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Specify HTML elements that have URL attributes to be rewritten.</td></tr>
-<tr><td><a href="mod_proxy_html.html#proxyhtmlmeta">ProxyHTMLMeta <var>On|Off</var></a></td><td> Off </td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Turns on or off extra pre-parsing of metadata in HTML
+<tr><td><a href="mod_proxy_html.html#proxyhtmllinks">ProxyHTMLLinks <var>element attribute [attribute2 ...]</var></a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Specify HTML elements that have URL attributes to be rewritten.</td></tr>
+<tr class="odd"><td><a href="mod_proxy_html.html#proxyhtmlmeta">ProxyHTMLMeta <var>On|Off</var></a></td><td> Off </td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Turns on or off extra pre-parsing of metadata in HTML
<code><head></code> sections.</td></tr>
-<tr class="odd"><td><a href="mod_proxy_html.html#proxyhtmlstripcomments">ProxyHTMLStripComments <var>On|Off</var></a></td><td> Off </td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Determines whether to strip HTML comments.</td></tr>
-<tr><td><a href="mod_proxy_html.html#proxyhtmlurlmap">ProxyHTMLURLMap <var>from-pattern to-pattern [flags] [cond]</var></a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Defines a rule to rewrite HTML links</td></tr>
-<tr class="odd"><td><a href="mod_proxy.html#proxyiobuffersize">ProxyIOBufferSize <var>bytes</var></a></td><td> 8192 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Determine size of internal data throughput buffer</td></tr>
-<tr><td><a href="mod_proxy.html#proxymatch"><ProxyMatch <var>regex</var>> ...</ProxyMatch></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Container for directives applied to regular-expression-matched
+<tr><td><a href="mod_proxy_html.html#proxyhtmlstripcomments">ProxyHTMLStripComments <var>On|Off</var></a></td><td> Off </td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Determines whether to strip HTML comments.</td></tr>
+<tr class="odd"><td><a href="mod_proxy_html.html#proxyhtmlurlmap">ProxyHTMLURLMap <var>from-pattern to-pattern [flags] [cond]</var></a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Defines a rule to rewrite HTML links</td></tr>
+<tr><td><a href="mod_proxy.html#proxyiobuffersize">ProxyIOBufferSize <var>bytes</var></a></td><td> 8192 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Determine size of internal data throughput buffer</td></tr>
+<tr class="odd"><td><a href="mod_proxy.html#proxymatch"><ProxyMatch <var>regex</var>> ...</ProxyMatch></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Container for directives applied to regular-expression-matched
proxied resources</td></tr>
-<tr class="odd"><td><a href="mod_proxy.html#proxymaxforwards">ProxyMaxForwards <var>number</var></a></td><td> -1 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximium number of proxies that a request can be forwarded
+<tr><td><a href="mod_proxy.html#proxymaxforwards">ProxyMaxForwards <var>number</var></a></td><td> -1 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximium number of proxies that a request can be forwarded
through</td></tr>
-<tr><td><a href="mod_proxy.html#proxypass">ProxyPass [<var>path</var>] !|<var>url</var> [<var>key=value</var>
- <var>[key=value</var> ...]] [nocanon] [interpolate] [noquery]</a></td><td></td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Maps remote servers into the local server URL-space</td></tr>
-<tr class="odd"><td><a href="mod_proxy.html#proxypassinherit">ProxyPassInherit On|Off</a></td><td> On </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Inherit ProxyPass directives defined from the main server</td></tr>
-<tr><td><a href="mod_proxy.html#proxypassinterpolateenv">ProxyPassInterpolateEnv On|Off</a></td><td> Off </td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable Environment Variable interpolation in Reverse Proxy configurations</td></tr>
-<tr
class="odd"><td><a href="mod_proxy.html#proxypassmatch">ProxyPassMatch [<var>regex</var>] !|<var>url</var> [<var>key=value</var>
- <var>[key=value</var> ...]]</a></td><td></td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maps remote servers into the local server URL-space using regular expressions</td></tr>
-<tr><td><a href="mod_proxy.html#proxypassreverse">ProxyPassReverse [<var>path</var>] <var>url</var>
-[<var>interpolate</var>]</a></td><td></td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Adjusts the URL in HTTP response headers sent from a reverse
+<tr
class="odd"><td><a href="mod_proxy.html#proxypass">ProxyPass [<var>path</var>] !|<var>url</var> [<var>key=value</var>
+ <var>[key=value</var> ...]] [nocanon] [interpolate] [noquery]</a></td><td></td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maps remote servers into the local server URL-space</td></tr>
+<tr><td><a href="mod_proxy.html#proxypassinherit">ProxyPassInherit On|Off</a></td><td> On </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Inherit ProxyPass directives defined from the main server</td></tr>
+<tr class="odd"><td><a href="mod_proxy.html#proxypassinterpolateenv">ProxyPassInterpolateEnv On|Off</a></td><td> Off </td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable Environment Variable interpolation in Reverse Proxy configurations</td></tr>
+<tr><td><a href="mod_proxy.html#proxypassmatch">ProxyPassMatch [<var>regex</var>] !|<var>url</var> [<var>key=value</var>
+ <var>[key=value</var> ...]]</a></td><td></td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Maps remote servers into the local server URL-space using regular expressions</td></tr>
+<tr
class="odd"><td><a href="mod_proxy.html#proxypassreverse">ProxyPassReverse [<var>path</var>] <var>url</var>
+[<var>interpolate</var>]</a></td><td></td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Adjusts the URL in HTTP response headers sent from a reverse
proxied server</td></tr>
-<tr
class="odd"><td><a href="mod_proxy.html#proxypassreversecookiedomain">ProxyPassReverseCookieDomain <var>internal-domain</var>
-<var>public-domain</var> [<var>interpolate</var>]</a></td><td></td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Adjusts the Domain string in Set-Cookie headers from a reverse-
+<tr><td><a href="mod_proxy.html#proxypassreversecookiedomain">ProxyPassReverseCookieDomain <var>internal-domain</var>
+<var>public-domain</var> [<var>interpolate</var>]</a></td><td></td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Adjusts the Domain string in Set-Cookie headers from a reverse-
proxied server</td></tr>
-<tr><td><a href="mod_proxy.html#proxypassreversecookiepath">ProxyPassReverseCookiePath <var>internal-path</var>
-<var>public-path</var> [<var>interpolate</var>]</a></td><td></td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Adjusts the Path string in Set-Cookie headers from a reverse-
+<tr
class="odd"><td><a href="mod_proxy.html#proxypassreversecookiepath">ProxyPassReverseCookiePath <var>internal-path</var>
+<var>public-path</var> [<var>interpolate</var>]</a></td><td></td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Adjusts the Path string in Set-Cookie headers from a reverse-
proxied server</td></tr>
-<tr class="odd"><td><a href="mod_proxy.html#proxypreservehost">ProxyPreserveHost On|Off</a></td><td> Off </td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Use incoming Host HTTP request header for proxy
+<tr><td><a href="mod_proxy.html#proxypreservehost">ProxyPreserveHost On|Off</a></td><td> Off </td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Use incoming Host HTTP request header for proxy
request</td></tr>
-<tr><td><a href="mod_proxy.html#proxyreceivebuffersize">ProxyReceiveBufferSize <var>bytes</var></a></td><td> 0 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Network buffer size for proxied HTTP and FTP
+<tr class="odd"><td><a href="mod_proxy.html#proxyreceivebuffersize">ProxyReceiveBufferSize <var>bytes</var></a></td><td> 0 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Network buffer size for proxied HTTP and FTP
connections</td></tr>
-<tr class="odd"><td><a href="mod_proxy.html#proxyremote">ProxyRemote <var>match</var> <var>remote-server</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Remote proxy used to handle certain requests</td></tr>
-<tr><td><a href="mod_proxy.html#proxyremotematch">ProxyRemoteMatch <var>regex</var> <var>remote-server</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Remote proxy used to handle requests matched by regular
+<tr><td><a href="mod_proxy.html#proxyremote">ProxyRemote <var>match</var> <var>remote-server</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Remote proxy used to handle certain requests</td></tr>
+<tr class="odd"><td><a href="mod_proxy.html#proxyremotematch">ProxyRemoteMatch <var>regex</var> <var>remote-server</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Remote proxy used to handle requests matched by regular
expressions</td></tr>
-<tr class="odd"><td><a href="mod_proxy.html#proxyrequests">ProxyRequests On|Off</a></td><td> Off </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enables forward (standard) proxy requests</td></tr>
-<tr><td><a href="mod_proxy_scgi.html#proxyscgiinternalredirect">ProxySCGIInternalRedirect On|Off</a></td><td> On </td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable or disable internal redirect responses from the
+<tr><td><a href="mod_proxy.html#proxyrequests">ProxyRequests On|Off</a></td><td> Off </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Enables forward (standard) proxy requests</td></tr>
+<tr class="odd"><td><a href="mod_proxy_scgi.html#proxyscgiinternalredirect">ProxySCGIInternalRedirect On|Off</a></td><td> On </td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable or disable internal redirect responses from the
backend</td></tr>
-<tr class="odd"><td><a href="mod_proxy_scgi.html#proxyscgisendfile">ProxySCGISendfile On|Off|<var>Headername</var></a></td><td> Off </td><td>svd</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable evaluation of <var>X-Sendfile</var> pseudo response
+<tr><td><a href="mod_proxy_scgi.html#proxyscgisendfile">ProxySCGISendfile On|Off|<var>Headername</var></a></td><td> Off </td><td>svd</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable evaluation of <var>X-Sendfile</var> pseudo response
header</td></tr>
-<tr><td><a href="mod_proxy.html#proxyset">ProxySet <var>url</var> <var>key=value [key=value ...]</var></a></td><td></td><td>d</td><td>E</td></tr><tr><td class="descr" colspan="4">Set various Proxy balancer or member parameters</td></tr>
-<tr class="odd"><td><a href="mod_proxy.html#proxysourceaddress">ProxySourceAddress <var>address</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Set local IP address for outgoing proxy connections</td></tr>
-<tr><td><a href="mod_proxy.html#proxystatus">ProxyStatus Off|On|Full</a></td><td> Off </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Show Proxy LoadBalancer status in mod_status</td></tr>
-<tr class="odd"><td><a href="mod_proxy.html#proxytimeout">ProxyTimeout <var>seconds</var></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Network timeout for proxied requests</td></tr>
-<tr><td><a href="mod_proxy.html#proxyvia">ProxyVia On|Off|Full|Block</a></td><td> Off </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Information provided in the <code>Via</code> HTTP response
+<tr class="odd"><td><a href="mod_proxy.html#proxyset">ProxySet <var>url</var> <var>key=value [key=value ...]</var></a></td><td></td><td>d</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Set various Proxy balancer or member parameters</td></tr>
+<tr><td><a href="mod_proxy.html#proxysourceaddress">ProxySourceAddress <var>address</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Set local IP address for outgoing proxy connections</td></tr>
+<tr class="odd"><td><a href="mod_proxy.html#proxystatus">ProxyStatus Off|On|Full</a></td><td> Off </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Show Proxy LoadBalancer status in mod_status</td></tr>
+<tr><td><a href="mod_proxy.html#proxytimeout">ProxyTimeout <var>seconds</var></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Network timeout for proxied requests</td></tr>
+<tr class="odd"><td><a href="mod_proxy.html#proxyvia">ProxyVia On|Off|Full|Block</a></td><td> Off </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Information provided in the <code>Via</code> HTTP response
header for proxied requests</td></tr>
-<tr class="odd"><td><a href="mod_autoindex.html#readmename" id="R" name="R">ReadmeName <var>filename</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Name of the file that will be inserted at the end
+<tr><td><a href="mod_autoindex.html#readmename" id="R" name="R">ReadmeName <var>filename</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Name of the file that will be inserted at the end
of the index listing</td></tr>
-<tr><td><a href="mpm_common.html#receivebuffersize">ReceiveBufferSize <var>bytes</var></a></td><td> 0 </td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">TCP receive buffer size</td></tr>
-<tr
class="odd"><td><a href="mod_alias.html#redirect">Redirect [<var>status</var>] [<var>URL-path</var>]
-<var>URL</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sends an external redirect asking the client to fetch
+<tr class="odd"><td><a href="mpm_common.html#receivebuffersize">ReceiveBufferSize <var>bytes</var></a></td><td> 0 </td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">TCP receive buffer size</td></tr>
+<tr><td><a href="mod_alias.html#redirect">Redirect [<var>status</var>] [<var>URL-path</var>]
+<var>URL</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Sends an external redirect asking the client to fetch
a different URL</td></tr>
-<tr><td><a href="mod_alias.html#redirectmatch">RedirectMatch [<var>status</var>] <var>regex</var>
-<var>URL</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Sends an external redirect based on a regular expression match
+<tr
class="odd"><td><a href="mod_alias.html#redirectmatch">RedirectMatch [<var>status</var>] <var>regex</var>
+<var>URL</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sends an external redirect based on a regular expression match
of the current URL</td></tr>
-<tr class="odd"><td><a href="mod_alias.html#redirectpermanent">RedirectPermanent <var>URL-path</var> <var>URL</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sends an external permanent redirect asking the client to fetch
+<tr><td><a href="mod_alias.html#redirectpermanent">RedirectPermanent <var>URL-path</var> <var>URL</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Sends an external permanent redirect asking the client to fetch
a different URL</td></tr>
-<tr><td><a href="mod_alias.html#redirecttemp">RedirectTemp <var>URL-path</var> <var>URL</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Sends an external temporary redirect asking the client to fetch
+<tr class="odd"><td><a href="mod_alias.html#redirecttemp">RedirectTemp <var>URL-path</var> <var>URL</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sends an external temporary redirect asking the client to fetch
a different URL</td></tr>
-<tr class="odd"><td><a href="mod_reflector.html#reflectorheader">ReflectorHeader <var>inputheader</var> <var>[outputheader]</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Reflect an input header to the output headers</td></tr>
-<tr><td><a href="mod_remoteip.html#remoteipheader">RemoteIPHeader <var>header-field</var></a></td><td></td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Declare the header field which should be parsed for useragent IP addresses</td></tr>
-<tr class="odd"><td><a href="mod_remoteip.html#remoteipinternalproxy">RemoteIPInternalProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</a></td><td></td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
-<tr><td><a href="mod_remoteip.html#remoteipinternalproxylist">RemoteIPInternalProxyList <var>filename</var></a></td><td></td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
-<tr class="odd"><td><a href="mod_remoteip.html#remoteipproxiesheader">RemoteIPProxiesHeader <var>HeaderFieldName</var></a></td><td></td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Declare the header field which will record all intermediate IP addresses</td></tr>
-<tr><td><a href="mod_remoteip.html#remoteiptrustedproxy">RemoteIPTrustedProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</a></td><td></td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
-<tr class="odd"><td><a href="mod_remoteip.html#remoteiptrustedproxylist">RemoteIPTrustedProxyList <var>filename</var></a></td><td></td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
-<tr><td><a href="mod_mime.html#removecharset">RemoveCharset <var>extension</var> [<var>extension</var>]
-...</a></td><td></td><td>vdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Removes any character set associations for a set of file
+<tr><td><a href="mod_reflector.html#reflectorheader">ReflectorHeader <var>inputheader</var> <var>[outputheader]</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Reflect an input header to the output headers</td></tr>
+<tr class="odd"><td><a href="mod_remoteip.html#remoteipheader">RemoteIPHeader <var>header-field</var></a></td><td></td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Declare the header field which should be parsed for useragent IP addresses</td></tr>
+<tr><td><a href="mod_remoteip.html#remoteipinternalproxy">RemoteIPInternalProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</a></td><td></td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
+<tr class="odd"><td><a href="mod_remoteip.html#remoteipinternalproxylist">RemoteIPInternalProxyList <var>filename</var></a></td><td></td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
+<tr><td><a href="mod_remoteip.html#remoteipproxiesheader">RemoteIPProxiesHeader <var>HeaderFieldName</var></a></td><td></td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Declare the header field which will record all intermediate IP addresses</td></tr>
+<tr class="odd"><td><a href="mod_remoteip.html#remoteiptrustedproxy">RemoteIPTrustedProxy <var>proxy-ip</var>|<var>proxy-ip/subnet</var>|<var>hostname</var> ...</a></td><td></td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
+<tr><td><a href="mod_remoteip.html#remoteiptrustedproxylist">RemoteIPTrustedProxyList <var>filename</var></a></td><td></td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Declare client intranet IP addresses trusted to present the RemoteIPHeader value</td></tr>
+<tr
class="odd"><td><a href="mod_mime.html#removecharset">RemoveCharset <var>extension</var> [<var>extension</var>]
+...</a></td><td></td><td>vdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Removes any character set associations for a set of file
extensions</td></tr>
-<tr
class="odd"><td><a href="mod_mime.html#removeencoding">RemoveEncoding <var>extension</var> [<var>extension</var>]
-...</a></td><td></td><td>vdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Removes any content encoding associations for a set of file
+<tr><td><a href="mod_mime.html#removeencoding">RemoveEncoding <var>extension</var> [<var>extension</var>]
+...</a></td><td></td><td>vdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Removes any content encoding associations for a set of file
extensions</td></tr>
-<tr><td><a href="mod_mime.html#removehandler">RemoveHandler <var>extension</var> [<var>extension</var>]
-...</a></td><td></td><td>vdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Removes any handler associations for a set of file
+<tr
class="odd"><td><a href="mod_mime.html#removehandler">RemoveHandler <var>extension</var> [<var>extension</var>]
+...</a></td><td></td><td>vdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Removes any handler associations for a set of file
extensions</td></tr>
-<tr
class="odd"><td><a href="mod_mime.html#removeinputfilter">RemoveInputFilter <var>extension</var> [<var>extension</var>]
-...</a></td><td></td><td>vdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Removes any input filter associations for a set of file
+<tr><td><a href="mod_mime.html#removeinputfilter">RemoveInputFilter <var>extension</var> [<var>extension</var>]
+...</a></td><td></td><td>vdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Removes any input filter associations for a set of file
extensions</td></tr>
-<tr><td><a href="mod_mime.html#removelanguage">RemoveLanguage <var>extension</var> [<var>extension</var>]
-...</a></td><td></td><td>vdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Removes any language associations for a set of file
+<tr
class="odd"><td><a href="mod_mime.html#removelanguage">RemoveLanguage <var>extension</var> [<var>extension</var>]
+...</a></td><td></td><td>vdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Removes any language associations for a set of file
extensions</td></tr>
-<tr
class="odd"><td><a href="mod_mime.html#removeoutputfilter">RemoveOutputFilter <var>extension</var> [<var>extension</var>]
-...</a></td><td></td><td>vdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Removes any output filter associations for a set of file
+<tr><td><a href="mod_mime.html#removeoutputfilter">RemoveOutputFilter <var>extension</var> [<var>extension</var>]
+...</a></td><td></td><td>vdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Removes any output filter associations for a set of file
extensions</td></tr>
-<tr><td><a href="mod_mime.html#removetype">RemoveType <var>extension</var> [<var>extension</var>]
-...</a></td><td></td><td>vdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Removes any content type associations for a set of file
+<tr
class="odd"><td><a href="mod_mime.html#removetype">RemoveType <var>extension</var> [<var>extension</var>]
+...</a></td><td></td><td>vdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Removes any content type associations for a set of file
extensions</td></tr>
-<tr
class="odd"><td><a href="mod_headers.html#requestheader">RequestHeader add|append|edit|edit*|merge|set|setifempty|unset
+<tr><td><a href="mod_headers.html#requestheader">RequestHeader add|append|edit|edit*|merge|set|setifempty|unset
<var>header</var> [[expr=]<var>value</var> [<var>replacement</var>]
[early|env=[!]<var>varname</var>|expr=<var>expression</var>]]
-</a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Configure HTTP request headers</td></tr>
-<tr><td><a href="mod_reqtimeout.html#requestreadtimeout">RequestReadTimeout
+</a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Configure HTTP request headers</td></tr>
+<tr
class="odd"><td><a href="mod_reqtimeout.html#requestreadtimeout">RequestReadTimeout
[header=<var>timeout</var>[-<var>maxtimeout</var>][,MinRate=<var>rate</var>]
[body=<var>timeout</var>[-<var>maxtimeout</var>][,MinRate=<var>rate</var>]
-</a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Set timeout values for receiving request headers and body from client.
+</a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Set timeout values for receiving request headers and body from client.
</td></tr>
-<tr
class="odd"><td><a href="mod_authz_core.html#require">Require [not] <var>entity-name</var>
- [<var>entity-name</var>] ...</a></td><td></td><td>dh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Tests whether an authenticated user is authorized by
+<tr><td><a href="mod_authz_core.html#require">Require [not] <var>entity-name</var>
+ [<var>entity-name</var>] ...</a></td><td></td><td>dh</td><td>B</td></tr><tr><td class="descr" colspan="4">Tests whether an authenticated user is authorized by
an authorization provider.</td></tr>
-<tr><td><a href="mod_authz_core.html#requireall"><RequireAll> ... </RequireAll></a></td><td></td><td>dh</td><td>B</td></tr><tr><td class="descr" colspan="4">Enclose a group of authorization directives of which none
+<tr class="odd"><td><a href="mod_authz_core.html#requireall"><RequireAll> ... </RequireAll></a></td><td></td><td>dh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Enclose a group of authorization directives of which none
must fail and at least one must succeed for the enclosing directive to
succeed.</td></tr>
-<tr class="odd"><td><a href="mod_authz_core.html#requireany"><RequireAny> ... </RequireAny></a></td><td></td><td>dh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Enclose a group of authorization directives of which one
+<tr><td><a href="mod_authz_core.html#requireany"><RequireAny> ... </RequireAny></a></td><td></td><td>dh</td><td>B</td></tr><tr><td class="descr" colspan="4">Enclose a group of authorization directives of which one
must succeed for the enclosing directive to succeed.</td></tr>
-<tr><td><a href="mod_authz_core.html#requirenone"><RequireNone> ... </RequireNone></a></td><td></td><td>dh</td><td>B</td></tr><tr><td class="descr" colspan="4">Enclose a group of authorization directives of which none
+<tr class="odd"><td><a href="mod_authz_core.html#requirenone"><RequireNone> ... </RequireNone></a></td><td></td><td>dh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Enclose a group of authorization directives of which none
must succeed for the enclosing directive to not fail.</td></tr>
-<tr class="odd"><td><a href="mod_rewrite.html#rewritebase">RewriteBase <em>URL-path</em></a></td><td></td><td>dh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Sets the base URL for per-directory rewrites</td></tr>
-<tr><td><a href="mod_rewrite.html#rewritecond"> RewriteCond
- <em>TestString</em> <em>CondPattern</em></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Defines a condition under which rewriting will take place
+<tr><td><a href="mod_rewrite.html#rewritebase">RewriteBase <em>URL-path</em></a></td><td></td><td>dh</td><td>E</td></tr><tr><td class="descr" colspan="4">Sets the base URL for per-directory rewrites</td></tr>
+<tr
class="odd"><td><a href="mod_rewrite.html#rewritecond"> RewriteCond
+ <em>TestString</em> <em>CondPattern</em></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Defines a condition under which rewriting will take place
</td></tr>
-<tr class="odd"><td><a href="mod_rewrite.html#rewriteengine">RewriteEngine on|off</a></td><td> off </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enables or disables runtime rewriting engine</td></tr>
-<tr><td><a href="mod_rewrite.html#rewritemap">RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
-</a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Defines a mapping function for key-lookup</td></tr>
-<tr class="odd"><td><a href="mod_rewrite.html#rewriteoptions">RewriteOptions <var>Options</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Sets some special options for the rewrite engine</td></tr>
-<tr><td><a href="mod_rewrite.html#rewriterule">RewriteRule
- <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Defines rules for the rewriting engine</td></tr>
-<tr class="odd"><td><a href="core.html#rlimitcpu">RLimitCPU <var>seconds</var>|max [<var>seconds</var>|max]</a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Limits the CPU consumption of processes launched
+<tr><td><a href="mod_rewrite.html#rewriteengine">RewriteEngine on|off</a></td><td> off </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Enables or disables runtime rewriting engine</td></tr>
+<tr
class="odd"><td><a href="mod_rewrite.html#rewritemap">RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
+</a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Defines a mapping function for key-lookup</td></tr>
+<tr><td><a href="mod_rewrite.html#rewriteoptions">RewriteOptions <var>Options</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Sets some special options for the rewrite engine</td></tr>
+<tr
class="odd"><td><a href="mod_rewrite.html#rewriterule">RewriteRule
+ <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Defines rules for the rewriting engine</td></tr>
+<tr><td><a href="core.html#rlimitcpu">RLimitCPU <var>seconds</var>|max [<var>seconds</var>|max]</a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Limits the CPU consumption of processes launched
by Apache httpd children</td></tr>
-<tr><td><a href="core.html#rlimitmem">RLimitMEM <var>bytes</var>|max [<var>bytes</var>|max]</a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Limits the memory consumption of processes launched
+<tr class="odd"><td><a href="core.html#rlimitmem">RLimitMEM <var>bytes</var>|max [<var>bytes</var>|max]</a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Limits the memory consumption of processes launched
by Apache httpd children</td></tr>
-<tr class="odd"><td><a href="core.html#rlimitnproc">RLimitNPROC <var>number</var>|max [<var>number</var>|max]</a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Limits the number of processes that can be launched by
+<tr><td><a href="core.html#rlimitnproc">RLimitNPROC <var>number</var>|max [<var>number</var>|max]</a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Limits the number of processes that can be launched by
processes launched by Apache httpd children</td></tr>
-<tr><td><a href="mod_access_compat.html#satisfy" id="S" name="S">Satisfy Any|All</a></td><td> All </td><td>dh</td><td>E</td></tr><tr><td class="descr" colspan="4">Interaction between host-level access control and
+<tr class="odd"><td><a href="mod_access_compat.html#satisfy" id="S" name="S">Satisfy Any|All</a></td><td> All </td><td>dh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Interaction between host-level access control and
user authentication</td></tr>
-<tr class="odd"><td><a href="mpm_common.html#scoreboardfile">ScoreBoardFile <var>file-path</var></a></td><td> logs/apache_runtime +</td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Location of the file used to store coordination data for
+<tr><td><a href="mpm_common.html#scoreboardfile">ScoreBoardFile <var>file-path</var></a></td><td> logs/apache_runtime +</td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Location of the file used to store coordination data for
the child processes</td></tr>
-<tr><td><a href="mod_actions.html#script">Script <var>method</var> <var>cgi-script</var></a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Activates a CGI script for a particular request
+<tr class="odd"><td><a href="mod_actions.html#script">Script <var>method</var> <var>cgi-script</var></a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Activates a CGI script for a particular request
method.</td></tr>
-<tr
class="odd"><td><a href="mod_alias.html#scriptalias">ScriptAlias [<var>URL-path</var>]
-<var>file-path</var>|<var>directory-path</var></a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Maps a URL to a filesystem location and designates the
+<tr><td><a href="mod_alias.html#scriptalias">ScriptAlias [<var>URL-path</var>]
+<var>file-path</var>|<var>directory-path</var></a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Maps a URL to a filesystem location and designates the
target as a CGI script</td></tr>
-<tr><td><a href="mod_alias.html#scriptaliasmatch">ScriptAliasMatch <var>regex</var>
-<var>file-path</var>|<var>directory-path</var></a></td><td></td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Maps a URL to a filesystem location using a regular expression
+<tr
class="odd"><td><a href="mod_alias.html#scriptaliasmatch">ScriptAliasMatch <var>regex</var>
+<var>file-path</var>|<var>directory-path</var></a></td><td></td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Maps a URL to a filesystem location using a regular expression
and designates the target as a CGI script</td></tr>
-<tr class="odd"><td><a href="core.html#scriptinterpretersource">ScriptInterpreterSource Registry|Registry-Strict|Script</a></td><td> Script </td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Technique for locating the interpreter for CGI
+<tr><td><a href="core.html#scriptinterpretersource">ScriptInterpreterSource Registry|Registry-Strict|Script</a></td><td> Script </td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Technique for locating the interpreter for CGI
scripts</td></tr>
-<tr><td><a href="mod_cgi.html#scriptlog">ScriptLog <var>file-path</var></a></td><td></td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Location of the CGI script error logfile</td></tr>
-<tr class="odd"><td><a href="mod_cgi.html#scriptlogbuffer">ScriptLogBuffer <var>bytes</var></a></td><td> 1024 </td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum amount of PUT or POST requests that will be recorded
+<tr class="odd"><td><a href="mod_cgi.html#scriptlog">ScriptLog <var>file-path</var></a></td><td></td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Location of the CGI script error logfile</td></tr>
+<tr><td><a href="mod_cgi.html#scriptlogbuffer">ScriptLogBuffer <var>bytes</var></a></td><td> 1024 </td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Maximum amount of PUT or POST requests that will be recorded
in the scriptlog</td></tr>
-<tr><td><a href="mod_cgi.html#scriptloglength">ScriptLogLength <var>bytes</var></a></td><td> 10385760 </td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Size limit of the CGI script logfile</td></tr>
-<tr class="odd"><td><a href="mod_cgid.html#scriptsock">ScriptSock <var>file-path</var></a></td><td> cgisock </td><td>s</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">The filename prefix of the socket to use for communication with
+<tr class="odd"><td><a href="mod_cgi.html#scriptloglength">ScriptLogLength <var>bytes</var></a></td><td> 10385760 </td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Size limit of the CGI script logfile</td></tr>
+<tr><td><a href="mod_cgid.html#scriptsock">ScriptSock <var>file-path</var></a></td><td> cgisock </td><td>s</td><td>B</td></tr><tr><td class="descr" colspan="4">The filename prefix of the socket to use for communication with
the cgi daemon</td></tr>
-<tr><td><a href="mod_nw_ssl.html#securelisten">SecureListen [<var>IP-address</var>:]<var>portnumber</var>
-<var>Certificate-Name</var> [MUTUAL]</a></td><td></td><td>s</td><td>B</td></tr><tr><td class="descr" colspan="4">Enables SSL encryption for the specified port</td></tr>
-<tr class="odd"><td><a href="core.html#seerequesttail">SeeRequestTail On|Off</a></td><td> Off </td><td>s</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Determine if mod_status displays the first 63 characters
+<tr
class="odd"><td><a href="mod_nw_ssl.html#securelisten">SecureListen [<var>IP-address</var>:]<var>portnumber</var>
+<var>Certificate-Name</var> [MUTUAL]</a></td><td></td><td>s</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Enables SSL encryption for the specified port</td></tr>
+<tr><td><a href="core.html#seerequesttail">SeeRequestTail On|Off</a></td><td> Off </td><td>s</td><td>C</td></tr><tr><td class="descr" colspan="4">Determine if mod_status displays the first 63 characters
of a request or the last 63, assuming the request itself is greater than
63 chars.</td></tr>
-<tr><td><a href="mpm_common.html#sendbuffersize">SendBufferSize <var>bytes</var></a></td><td> 0 </td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">TCP buffer size</td></tr>
-<tr class="odd"><td><a href="core.html#serveradmin">ServerAdmin <var>email-address</var>|<var>URL</var></a></td><td></td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Email address that the server includes in error
+<tr class="odd"><td><a href="mpm_common.html#sendbuffersize">SendBufferSize <var>bytes</var></a></td><td> 0 </td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">TCP buffer size</td></tr>
+<tr><td><a href="core.html#serveradmin">ServerAdmin <var>email-address</var>|<var>URL</var></a></td><td></td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Email address that the server includes in error
messages sent to the client</td></tr>
-<tr><td><a href="core.html#serveralias">ServerAlias <var>hostname</var> [<var>hostname</var>] ...</a></td><td></td><td>v</td><td>C</td></tr><tr><td class="descr" colspan="4">Alternate names for a host used when matching requests
+<tr class="odd"><td><a href="core.html#serveralias">ServerAlias <var>hostname</var> [<var>hostname</var>] ...</a></td><td></td><td>v</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Alternate names for a host used when matching requests
to name-virtual hosts</td></tr>
-<tr class="odd"><td><a href="mpm_common.html#serverlimit">ServerLimit <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Upper limit on configurable number of processes</td></tr>
-<tr><td><a href="core.html#servername">ServerName [<var>scheme</var>://]<var>fully-qualified-domain-name</var>[:<var>port</var>]</a></td><td></td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Hostname and port that the server uses to identify
+<tr><td><a href="mpm_common.html#serverlimit">ServerLimit <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Upper limit on configurable number of processes</td></tr>
+<tr class="odd"><td><a href="core.html#servername">ServerName [<var>scheme</var>://]<var>fully-qualified-domain-name</var>[:<var>port</var>]</a></td><td></td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Hostname and port that the server uses to identify
itself</td></tr>
-<tr class="odd"><td><a href="core.html#serverpath">ServerPath <var>URL-path</var></a></td><td></td><td>v</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Legacy URL pathname for a name-based virtual host that
+<tr><td><a href="core.html#serverpath">ServerPath <var>URL-path</var></a></td><td></td><td>v</td><td>C</td></tr><tr><td class="descr" colspan="4">Legacy URL pathname for a name-based virtual host that
is accessed by an incompatible browser</td></tr>
-<tr><td><a href="core.html#serverroot">ServerRoot <var>directory-path</var></a></td><td> /usr/local/apache </td><td>s</td><td>C</td></tr><tr><td class="descr" colspan="4">Base directory for the server installation</td></tr>
-<tr class="odd"><td><a href="core.html#serversignature">ServerSignature On|Off|EMail</a></td><td> Off </td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Configures the footer on server-generated documents</td></tr>
-<tr><td><a href="core.html#servertokens">ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full</a></td><td> Full </td><td>s</td><td>C</td></tr><tr><td class="descr" colspan="4">Configures the <code>Server</code> HTTP response
+<tr class="odd"><td><a href="core.html#serverroot">ServerRoot <var>directory-path</var></a></td><td> /usr/local/apache </td><td>s</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Base directory for the server installation</td></tr>
+<tr><td><a href="core.html#serversignature">ServerSignature On|Off|EMail</a></td><td> Off </td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Configures the footer on server-generated documents</td></tr>
+<tr class="odd"><td><a href="core.html#servertokens">ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full</a></td><td> Full </td><td>s</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Configures the <code>Server</code> HTTP response
header</td></tr>
-<tr class="odd"><td><a href="mod_session.html#session">Session On|Off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enables a session for the current directory or location</td></tr>
-<tr><td><a href="mod_session_cookie.html#sessioncookiename">SessionCookieName <var>name</var> <var>attributes</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Name and attributes for the RFC2109 cookie storing the session</td></tr>
-<tr class="odd"><td><a href="mod_session_cookie.html#sessioncookiename2">SessionCookieName2 <var>name</var> <var>attributes</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Name and attributes for the RFC2965 cookie storing the session</td></tr>
-<tr><td><a href="mod_session_cookie.html#sessioncookieremove">SessionCookieRemove On|Off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Control for whether session cookies should be removed from incoming HTTP headers</td></tr>
-<tr class="odd"><td><a href="mod_session_crypto.html#sessioncryptocipher">SessionCryptoCipher <var>name</var></a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">The crypto cipher to be used to encrypt the session</td></tr>
-<tr><td><a href="mod_session_crypto.html#sessioncryptodriver">SessionCryptoDriver <var>name</var> <var>[param[=value]]</var></a></td><td></td><td>s</td><td>X</td></tr><tr><td class="descr" colspan="4">The crypto driver to be used to encrypt the session</td></tr>
-<tr class="odd"><td><a href="mod_session_crypto.html#sessioncryptopassphrase">SessionCryptoPassphrase <var>secret</var> [ <var>secret</var> ... ] </a></td><td></td><td>svdh</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">The key used to encrypt the session</td></tr>
-<tr><td><a href="mod_session_crypto.html#sessioncryptopassphrasefile">SessionCryptoPassphraseFile <var>filename</var></a></td><td></td><td>svd</td><td>X</td></tr><tr><td class="descr" colspan="4">File containing keys used to encrypt the session</td></tr>
-<tr class="odd"><td><a href="mod_session_dbd.html#sessiondbdcookiename">SessionDBDCookieName <var>name</var> <var>attributes</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Name and attributes for the RFC2109 cookie storing the session ID</td></tr>
-<tr><td><a href="mod_session_dbd.html#sessiondbdcookiename2">SessionDBDCookieName2 <var>name</var> <var>attributes</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Name and attributes for the RFC2965 cookie storing the session ID</td></tr>
-<tr class="odd"><td><a href="mod_session_dbd.html#sessiondbdcookieremove">SessionDBDCookieRemove On|Off</a></td><td> On </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Control for whether session ID cookies should be removed from incoming HTTP headers</td></tr>
-<tr><td><a href="mod_session_dbd.html#sessiondbddeletelabel">SessionDBDDeleteLabel <var>label</var></a></td><td> deletesession </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">The SQL query to use to remove sessions from the database</td></tr>
-<tr class="odd"><td><a href="mod_session_dbd.html#sessiondbdinsertlabel">SessionDBDInsertLabel <var>label</var></a></td><td> insertsession </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">The SQL query to use to insert sessions into the database</td></tr>
-<tr><td><a href="mod_session_dbd.html#sessiondbdperuser">SessionDBDPerUser On|Off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable a per user session</td></tr>
-<tr class="odd"><td><a href="mod_session_dbd.html#sessiondbdselectlabel">SessionDBDSelectLabel <var>label</var></a></td><td> selectsession </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">The SQL query to use to select sessions from the database</td></tr>
-<tr><td><a href="mod_session_dbd.html#sessiondbdupdatelabel">SessionDBDUpdateLabel <var>label</var></a></td><td> updatesession </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">The SQL query to use to update existing sessions in the database</td></tr>
-<tr class="odd"><td><a href="mod_session.html#sessionenv">SessionEnv On|Off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Control whether the contents of the session are written to the
+<tr><td><a href="mod_session.html#session">Session On|Off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Enables a session for the current directory or location</td></tr>
+<tr class="odd"><td><a href="mod_session_cookie.html#sessioncookiename">SessionCookieName <var>name</var> <var>attributes</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Name and attributes for the RFC2109 cookie storing the session</td></tr>
+<tr><td><a href="mod_session_cookie.html#sessioncookiename2">SessionCookieName2 <var>name</var> <var>attributes</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Name and attributes for the RFC2965 cookie storing the session</td></tr>
+<tr class="odd"><td><a href="mod_session_cookie.html#sessioncookieremove">SessionCookieRemove On|Off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Control for whether session cookies should be removed from incoming HTTP headers</td></tr>
+<tr><td><a href="mod_session_crypto.html#sessioncryptocipher">SessionCryptoCipher <var>name</var></a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">The crypto cipher to be used to encrypt the session</td></tr>
+<tr class="odd"><td><a href="mod_session_crypto.html#sessioncryptodriver">SessionCryptoDriver <var>name</var> <var>[param[=value]]</var></a></td><td></td><td>s</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">The crypto driver to be used to encrypt the session</td></tr>
+<tr><td><a href="mod_session_crypto.html#sessioncryptopassphrase">SessionCryptoPassphrase <var>secret</var> [ <var>secret</var> ... ] </a></td><td></td><td>svdh</td><td>X</td></tr><tr><td class="descr" colspan="4">The key used to encrypt the session</td></tr>
+<tr class="odd"><td><a href="mod_session_crypto.html#sessioncryptopassphrasefile">SessionCryptoPassphraseFile <var>filename</var></a></td><td></td><td>svd</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">File containing keys used to encrypt the session</td></tr>
+<tr><td><a href="mod_session_dbd.html#sessiondbdcookiename">SessionDBDCookieName <var>name</var> <var>attributes</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Name and attributes for the RFC2109 cookie storing the session ID</td></tr>
+<tr class="odd"><td><a href="mod_session_dbd.html#sessiondbdcookiename2">SessionDBDCookieName2 <var>name</var> <var>attributes</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Name and attributes for the RFC2965 cookie storing the session ID</td></tr>
+<tr><td><a href="mod_session_dbd.html#sessiondbdcookieremove">SessionDBDCookieRemove On|Off</a></td><td> On </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Control for whether session ID cookies should be removed from incoming HTTP headers</td></tr>
+<tr class="odd"><td><a href="mod_session_dbd.html#sessiondbddeletelabel">SessionDBDDeleteLabel <var>label</var></a></td><td> deletesession </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">The SQL query to use to remove sessions from the database</td></tr>
+<tr><td><a href="mod_session_dbd.html#sessiondbdinsertlabel">SessionDBDInsertLabel <var>label</var></a></td><td> insertsession </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">The SQL query to use to insert sessions into the database</td></tr>
+<tr class="odd"><td><a href="mod_session_dbd.html#sessiondbdperuser">SessionDBDPerUser On|Off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable a per user session</td></tr>
+<tr><td><a href="mod_session_dbd.html#sessiondbdselectlabel">SessionDBDSelectLabel <var>label</var></a></td><td> selectsession </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">The SQL query to use to select sessions from the database</td></tr>
+<tr class="odd"><td><a href="mod_session_dbd.html#sessiondbdupdatelabel">SessionDBDUpdateLabel <var>label</var></a></td><td> updatesession </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">The SQL query to use to update existing sessions in the database</td></tr>
+<tr><td><a href="mod_session.html#sessionenv">SessionEnv On|Off</a></td><td> Off </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Control whether the contents of the session are written to the
<var>HTTP_SESSION</var> environment variable</td></tr>
-<tr><td><a href="mod_session.html#sessionexclude">SessionExclude <var>path</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Define URL prefixes for which a session is ignored</td></tr>
-<tr class="odd"><td><a href="mod_session.html#sessionheader">SessionHeader <var>header</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Import session updates from a given HTTP response header</td></tr>
-<tr><td><a href="mod_session.html#sessioninclude">SessionInclude <var>path</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Define URL prefixes for which a session is valid</td></tr>
-<tr class="odd"><td><a href="mod_session.html#sessionmaxage">SessionMaxAge <var>maxage</var></a></td><td> 0 </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Define a maximum age in seconds for a session</td></tr>
-<tr><td><a href="mod_env.html#setenv">SetEnv <var>env-variable</var> [<var>value</var>]</a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Sets environment variables</td></tr>
-<tr
class="odd"><td><a href="mod_setenvif.html#setenvif">SetEnvIf <em>attribute
+<tr class="odd"><td><a href="mod_session.html#sessionexclude">SessionExclude <var>path</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Define URL prefixes for which a session is ignored</td></tr>
+<tr><td><a href="mod_session.html#sessionheader">SessionHeader <var>header</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Import session updates from a given HTTP response header</td></tr>
+<tr class="odd"><td><a href="mod_session.html#sessioninclude">SessionInclude <var>path</var></a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Define URL prefixes for which a session is valid</td></tr>
+<tr><td><a href="mod_session.html#sessionmaxage">SessionMaxAge <var>maxage</var></a></td><td> 0 </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Define a maximum age in seconds for a session</td></tr>
+<tr class="odd"><td><a href="mod_env.html#setenv">SetEnv <var>env-variable</var> [<var>value</var>]</a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sets environment variables</td></tr>
+<tr><td><a href="mod_setenvif.html#setenvif">SetEnvIf <em>attribute
regex [!]env-variable</em>[=<em>value</em>]
- [[!]<em>env-variable</em>[=<em>value</em>]] ...</a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sets environment variables based on attributes of the request
+ [[!]<em>env-variable</em>[=<em>value</em>]] ...</a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Sets environment variables based on attributes of the request
</td></tr>
-<tr><td><a href="mod_setenvif.html#setenvifexpr">SetEnvIfExpr <em>expr
+<tr
class="odd"><td><a href="mod_setenvif.html#setenvifexpr">SetEnvIfExpr <em>expr
[!]env-variable</em>[=<em>value</em>]
- [[!]<em>env-variable</em>[=<em>value</em>]] ...</a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Sets environment variables based on an ap_expr expression</td></tr>
-<tr
class="odd"><td><a href="mod_setenvif.html#setenvifnocase">SetEnvIfNoCase <em>attribute regex
+ [[!]<em>env-variable</em>[=<em>value</em>]] ...</a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sets environment variables based on an ap_expr expression</td></tr>
+<tr><td><a href="mod_setenvif.html#setenvifnocase">SetEnvIfNoCase <em>attribute regex
[!]env-variable</em>[=<em>value</em>]
- [[!]<em>env-variable</em>[=<em>value</em>]] ...</a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sets environment variables based on attributes of the request
+ [[!]<em>env-variable</em>[=<em>value</em>]] ...</a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Sets environment variables based on attributes of the request
without respect to case</td></tr>
-<tr><td><a href="core.html#sethandler">SetHandler <var>handler-name</var>|None</a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Forces all matching files to be processed by a
+<tr class="odd"><td><a href="core.html#sethandler">SetHandler <var>handler-name</var>|None</a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Forces all matching files to be processed by a
handler</td></tr>
-<tr class="odd"><td><a href="core.html#setinputfilter">SetInputFilter <var>filter</var>[;<var>filter</var>...]</a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Sets the filters that will process client requests and POST
+<tr><td><a href="core.html#setinputfilter">SetInputFilter <var>filter</var>[;<var>filter</var>...]</a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Sets the filters that will process client requests and POST
input</td></tr>
-<tr><td><a href="core.html#setoutputfilter">SetOutputFilter <var>filter</var>[;<var>filter</var>...]</a></td><td></td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">Sets the filters that will process responses from the
+<tr class="odd"><td><a href="core.html#setoutputfilter">SetOutputFilter <var>filter</var>[;<var>filter</var>...]</a></td><td></td><td>svdh</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Sets the filters that will process responses from the
server</td></tr>
-<tr class="odd"><td><a href="mod_include.html#ssiendtag">SSIEndTag <var>tag</var></a></td><td> "-->" </td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">String that ends an include element</td></tr>
-<tr><td><a href="mod_include.html#ssierrormsg">SSIErrorMsg <var>message</var></a></td><td> "[an error occurred +</td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Error message displayed when there is an SSI
+<tr><td><a href="mod_include.html#ssiendtag">SSIEndTag <var>tag</var></a></td><td> "-->" </td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">String that ends an include element</td></tr>
+<tr class="odd"><td><a href="mod_include.html#ssierrormsg">SSIErrorMsg <var>message</var></a></td><td> "[an error occurred +</td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Error message displayed when there is an SSI
error</td></tr>
-<tr class="odd"><td><a href="mod_include.html#ssietag">SSIETag on|off</a></td><td> off </td><td>dh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Controls whether ETags are generated by the server.</td></tr>
-<tr><td><a href="mod_include.html#ssilastmodified">SSILastModified on|off</a></td><td> off </td><td>dh</td><td>B</td></tr><tr><td class="descr" colspan="4">Controls whether <code>Last-Modified</code> headers are generated by the
+<tr><td><a href="mod_include.html#ssietag">SSIETag on|off</a></td><td> off </td><td>dh</td><td>B</td></tr><tr><td class="descr" colspan="4">Controls whether ETags are generated by the server.</td></tr>
+<tr class="odd"><td><a href="mod_include.html#ssilastmodified">SSILastModified on|off</a></td><td> off </td><td>dh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Controls whether <code>Last-Modified</code> headers are generated by the
server.</td></tr>
-<tr class="odd"><td><a href="mod_include.html#ssilegacyexprparser">SSILegacyExprParser on|off</a></td><td> off </td><td>dh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Enable compatibility mode for conditional expressions.</td></tr>
-<tr><td><a href="mod_include.html#ssistarttag">SSIStartTag <var>tag</var></a></td><td> "<!--#" </td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">String that starts an include element</td></tr>
-<tr class="odd"><td><a href="mod_include.html#ssitimeformat">SSITimeFormat <var>formatstring</var></a></td><td> "%A, %d-%b-%Y %H:%M +</td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Configures the format in which date strings are
+<tr><td><a href="mod_include.html#ssilegacyexprparser">SSILegacyExprParser on|off</a></td><td> off </td><td>dh</td><td>B</td></tr><tr><td class="descr" colspan="4">Enable compatibility mode for conditional expressions.</td></tr>
+<tr class="odd"><td><a href="mod_include.html#ssistarttag">SSIStartTag <var>tag</var></a></td><td> "<!--#" </td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">String that starts an include element</td></tr>
+<tr><td><a href="mod_include.html#ssitimeformat">SSITimeFormat <var>formatstring</var></a></td><td> "%A, %d-%b-%Y %H:%M +</td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Configures the format in which date strings are
displayed</td></tr>
-<tr><td><a href="mod_include.html#ssiundefinedecho">SSIUndefinedEcho <var>string</var></a></td><td> "(none)" </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">String displayed when an unset variable is echoed</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslcacertificatefile">SSLCACertificateFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">File of concatenated PEM-encoded CA Certificates
+<tr class="odd"><td><a href="mod_include.html#ssiundefinedecho">SSIUndefinedEcho <var>string</var></a></td><td> "(none)" </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">String displayed when an unset variable is echoed</td></tr>
+<tr><td><a href="mod_ssl.html#sslcacertificatefile">SSLCACertificateFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">File of concatenated PEM-encoded CA Certificates
for Client Auth</td></tr>
-<tr><td><a href="mod_ssl.html#sslcacertificatepath">SSLCACertificatePath <em>directory-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Directory of PEM-encoded CA Certificates for
+<tr class="odd"><td><a href="mod_ssl.html#sslcacertificatepath">SSLCACertificatePath <em>directory-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Directory of PEM-encoded CA Certificates for
Client Auth</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslcadnrequestfile">SSLCADNRequestFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">File of concatenated PEM-encoded CA Certificates
+<tr><td><a href="mod_ssl.html#sslcadnrequestfile">SSLCADNRequestFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">File of concatenated PEM-encoded CA Certificates
for defining acceptable CA names</td></tr>
-<tr><td><a href="mod_ssl.html#sslcadnrequestpath">SSLCADNRequestPath <em>directory-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Directory of PEM-encoded CA Certificates for
+<tr class="odd"><td><a href="mod_ssl.html#sslcadnrequestpath">SSLCADNRequestPath <em>directory-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Directory of PEM-encoded CA Certificates for
defining acceptable CA names</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslcarevocationcheck">SSLCARevocationCheck chain|leaf|none</a></td><td> none </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable CRL-based revocation checking</td></tr>
-<tr><td><a href="mod_ssl.html#sslcarevocationfile">SSLCARevocationFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">File of concatenated PEM-encoded CA CRLs for
+<tr><td><a href="mod_ssl.html#sslcarevocationcheck">SSLCARevocationCheck chain|leaf|none</a></td><td> none </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable CRL-based revocation checking</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslcarevocationfile">SSLCARevocationFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">File of concatenated PEM-encoded CA CRLs for
Client Auth</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslcarevocationpath">SSLCARevocationPath <em>directory-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Directory of PEM-encoded CA CRLs for
+<tr><td><a href="mod_ssl.html#sslcarevocationpath">SSLCARevocationPath <em>directory-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Directory of PEM-encoded CA CRLs for
Client Auth</td></tr>
-<tr><td><a href="mod_ssl.html#sslcertificatechainfile">SSLCertificateChainFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">File of PEM-encoded Server CA Certificates</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslcertificatefile">SSLCertificateFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Server PEM-encoded X.509 certificate data file</td></tr>
-<tr><td><a href="mod_ssl.html#sslcertificatekeyfile">SSLCertificateKeyFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Server PEM-encoded private key file</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslciphersuite">SSLCipherSuite <em>cipher-spec</em></a></td><td> DEFAULT (depends on +</td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Cipher Suite available for negotiation in SSL
+<tr class="odd"><td><a href="mod_ssl.html#sslcertificatechainfile">SSLCertificateChainFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">File of PEM-encoded Server CA Certificates</td></tr>
+<tr><td><a href="mod_ssl.html#sslcertificatefile">SSLCertificateFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Server PEM-encoded X.509 certificate data file</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslcertificatekeyfile">SSLCertificateKeyFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Server PEM-encoded private key file</td></tr>
+<tr><td><a href="mod_ssl.html#sslciphersuite">SSLCipherSuite <em>cipher-spec</em></a></td><td> DEFAULT (depends on +</td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Cipher Suite available for negotiation in SSL
handshake</td></tr>
-<tr><td><a href="mod_ssl.html#sslcompression">SSLCompression on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable compression on the SSL level</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslcryptodevice">SSLCryptoDevice <em>engine</em></a></td><td> builtin </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable use of a cryptographic hardware accelerator</td></tr>
-<tr><td><a href="mod_ssl.html#sslengine">SSLEngine on|off|optional</a></td><td> off </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">SSL Engine Operation Switch</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslfips">SSLFIPS on|off</a></td><td> off </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">SSL FIPS mode Switch</td></tr>
-<tr><td><a href="mod_ssl.html#sslhonorcipherorder">SSLHonorCipherOrder on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Option to prefer the server's cipher preference order</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslinsecurerenegotiation">SSLInsecureRenegotiation on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Option to enable support for insecure renegotiation</td></tr>
-<tr><td><a href="mod_ssl.html#sslocspdefaultresponder">SSLOCSDefaultResponder <em>uri</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Set the default responder URI for OCSP validation</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslocspenable">SSLOCSPEnable on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable OCSP validation of the client certificate chain</td></tr>
-<tr><td><a href="mod_ssl.html#sslocspoverrideresponder">SSLOCSPOverrideResponder on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Force use of the default responder URI for OCSP validation</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslocsprespondertimeout">SSLOCSPResponderTimeout <em>seconds</em></a></td><td> 10 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Timeout for OCSP queries</td></tr>
-<tr><td><a href="mod_ssl.html#sslocspresponsemaxage">SSLOCSPResponseMaxAge <em>seconds</em></a></td><td> -1 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximum allowable age for OCSP responses</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslocspresponsetimeskew">SSLOCSPResponseTimeSkew <em>seconds</em></a></td><td> 300 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum allowable time skew for OCSP response validation</td></tr>
-<tr><td><a href="mod_ssl.html#sslocspuserequestnonce">SSLOCSPUseRequestNonce on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Use a nonce within OCSP queries</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslopensslconfcmd">SSLOpenSSLConfCmd <em>command-name</em> <em>command-value</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Configure OpenSSL parameters through its <em>SSL_CONF</em> API</td></tr>
-<tr><td><a href="mod_ssl.html#ssloptions">SSLOptions [+|-]<em>option</em> ...</a></td><td></td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Configure various SSL engine run-time options</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslpassphrasedialog">SSLPassPhraseDialog <em>type</em></a></td><td> builtin </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Type of pass phrase dialog for encrypted private
+<tr class="odd"><td><a href="mod_ssl.html#sslcompression">SSLCompression on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable compression on the SSL level</td></tr>
+<tr><td><a href="mod_ssl.html#sslcryptodevice">SSLCryptoDevice <em>engine</em></a></td><td> builtin </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable use of a cryptographic hardware accelerator</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslengine">SSLEngine on|off|optional</a></td><td> off </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">SSL Engine Operation Switch</td></tr>
+<tr><td><a href="mod_ssl.html#sslfips">SSLFIPS on|off</a></td><td> off </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">SSL FIPS mode Switch</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslhonorcipherorder">SSLHonorCipherOrder on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Option to prefer the server's cipher preference order</td></tr>
+<tr><td><a href="mod_ssl.html#sslinsecurerenegotiation">SSLInsecureRenegotiation on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Option to enable support for insecure renegotiation</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslocspdefaultresponder">SSLOCSDefaultResponder <em>uri</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Set the default responder URI for OCSP validation</td></tr>
+<tr><td><a href="mod_ssl.html#sslocspenable">SSLOCSPEnable on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable OCSP validation of the client certificate chain</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslocspoverrideresponder">SSLOCSPOverrideResponder on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Force use of the default responder URI for OCSP validation</td></tr>
+<tr><td><a href="mod_ssl.html#sslocsprespondertimeout">SSLOCSPResponderTimeout <em>seconds</em></a></td><td> 10 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Timeout for OCSP queries</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslocspresponsemaxage">SSLOCSPResponseMaxAge <em>seconds</em></a></td><td> -1 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum allowable age for OCSP responses</td></tr>
+<tr><td><a href="mod_ssl.html#sslocspresponsetimeskew">SSLOCSPResponseTimeSkew <em>seconds</em></a></td><td> 300 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximum allowable time skew for OCSP response validation</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslocspuserequestnonce">SSLOCSPUseRequestNonce on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Use a nonce within OCSP queries</td></tr>
+<tr><td><a href="mod_ssl.html#sslopensslconfcmd">SSLOpenSSLConfCmd <em>command-name</em> <em>command-value</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Configure OpenSSL parameters through its <em>SSL_CONF</em> API</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#ssloptions">SSLOptions [+|-]<em>option</em> ...</a></td><td></td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Configure various SSL engine run-time options</td></tr>
+<tr><td><a href="mod_ssl.html#sslpassphrasedialog">SSLPassPhraseDialog <em>type</em></a></td><td> builtin </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Type of pass phrase dialog for encrypted private
keys</td></tr>
-<tr><td><a href="mod_ssl.html#sslprotocol">SSLProtocol [+|-]<em>protocol</em> ...</a></td><td> all </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Configure usable SSL/TLS protocol versions</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslproxycacertificatefile">SSLProxyCACertificateFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">File of concatenated PEM-encoded CA Certificates
+<tr class="odd"><td><a href="mod_ssl.html#sslprotocol">SSLProtocol [+|-]<em>protocol</em> ...</a></td><td> all </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Configure usable SSL/TLS protocol versions</td></tr>
+<tr><td><a href="mod_ssl.html#sslproxycacertificatefile">SSLProxyCACertificateFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">File of concatenated PEM-encoded CA Certificates
for Remote Server Auth</td></tr>
-<tr><td><a href="mod_ssl.html#sslproxycacertificatepath">SSLProxyCACertificatePath <em>directory-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Directory of PEM-encoded CA Certificates for
+<tr class="odd"><td><a href="mod_ssl.html#sslproxycacertificatepath">SSLProxyCACertificatePath <em>directory-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Directory of PEM-encoded CA Certificates for
Remote Server Auth</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslproxycarevocationcheck">SSLProxyCARevocationCheck chain|leaf|none</a></td><td> none </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable CRL-based revocation checking for Remote Server Auth</td></tr>
-<tr><td><a href="mod_ssl.html#sslproxycarevocationfile">SSLProxyCARevocationFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">File of concatenated PEM-encoded CA CRLs for
+<tr><td><a href="mod_ssl.html#sslproxycarevocationcheck">SSLProxyCARevocationCheck chain|leaf|none</a></td><td> none </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable CRL-based revocation checking for Remote Server Auth</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslproxycarevocationfile">SSLProxyCARevocationFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">File of concatenated PEM-encoded CA CRLs for
Remote Server Auth</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslproxycarevocationpath">SSLProxyCARevocationPath <em>directory-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Directory of PEM-encoded CA CRLs for
+<tr><td><a href="mod_ssl.html#sslproxycarevocationpath">SSLProxyCARevocationPath <em>directory-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Directory of PEM-encoded CA CRLs for
Remote Server Auth</td></tr>
-<tr><td><a href="mod_ssl.html#sslproxycheckpeercn">SSLProxyCheckPeerCN on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Whether to check the remote server certificate's CN field
+<tr class="odd"><td><a href="mod_ssl.html#sslproxycheckpeercn">SSLProxyCheckPeerCN on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Whether to check the remote server certificate's CN field
</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslproxycheckpeerexpire">SSLProxyCheckPeerExpire on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Whether to check if remote server certificate is expired
+<tr><td><a href="mod_ssl.html#sslproxycheckpeerexpire">SSLProxyCheckPeerExpire on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Whether to check if remote server certificate is expired
</td></tr>
-<tr><td><a href="mod_ssl.html#sslproxycheckpeername">SSLProxyCheckPeerName on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Configure host name checking for remote server certificates
+<tr class="odd"><td><a href="mod_ssl.html#sslproxycheckpeername">SSLProxyCheckPeerName on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Configure host name checking for remote server certificates
</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslproxyciphersuite">SSLProxyCipherSuite <em>cipher-spec</em></a></td><td> ALL:!ADH:RC4+RSA:+H +</td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Cipher Suite available for negotiation in SSL
+<tr><td><a href="mod_ssl.html#sslproxyciphersuite">SSLProxyCipherSuite <em>cipher-spec</em></a></td><td> ALL:!ADH:RC4+RSA:+H +</td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Cipher Suite available for negotiation in SSL
proxy handshake</td></tr>
-<tr><td><a href="mod_ssl.html#sslproxyengine">SSLProxyEngine on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">SSL Proxy Engine Operation Switch</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslproxymachinecertificatechainfile">SSLProxyMachineCertificateChainFile <em>filename</em></a></td><td></td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">File of concatenated PEM-encoded CA certificates to be used by the proxy for choosing a certificate</td></tr>
-<tr><td><a href="mod_ssl.html#sslproxymachinecertificatefile">SSLProxyMachineCertificateFile <em>filename</em></a></td><td></td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">File of concatenated PEM-encoded client certificates and keys to be used by the proxy</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslproxymachinecertificatepath">SSLProxyMachineCertificatePath <em>directory</em></a></td><td></td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Directory of PEM-encoded client certificates and keys to be used by the proxy</td></tr>
-<tr><td><a href="mod_ssl.html#sslproxyprotocol">SSLProxyProtocol [+|-]<em>protocol</em> ...</a></td><td> all </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Configure usable SSL protocol flavors for proxy usage</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslproxyverify">SSLProxyVerify <em>level</em></a></td><td> none </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Type of remote server Certificate verification</td></tr>
-<tr><td><a href="mod_ssl.html#sslproxyverifydepth">SSLProxyVerifyDepth <em>number</em></a></td><td> 1 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximum depth of CA Certificates in Remote Server
+<tr class="odd"><td><a href="mod_ssl.html#sslproxyengine">SSLProxyEngine on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">SSL Proxy Engine Operation Switch</td></tr>
+<tr><td><a href="mod_ssl.html#sslproxymachinecertificatechainfile">SSLProxyMachineCertificateChainFile <em>filename</em></a></td><td></td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">File of concatenated PEM-encoded CA certificates to be used by the proxy for choosing a certificate</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslproxymachinecertificatefile">SSLProxyMachineCertificateFile <em>filename</em></a></td><td></td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">File of concatenated PEM-encoded client certificates and keys to be used by the proxy</td></tr>
+<tr><td><a href="mod_ssl.html#sslproxymachinecertificatepath">SSLProxyMachineCertificatePath <em>directory</em></a></td><td></td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Directory of PEM-encoded client certificates and keys to be used by the proxy</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslproxyprotocol">SSLProxyProtocol [+|-]<em>protocol</em> ...</a></td><td> all </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Configure usable SSL protocol flavors for proxy usage</td></tr>
+<tr><td><a href="mod_ssl.html#sslproxyverify">SSLProxyVerify <em>level</em></a></td><td> none </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Type of remote server Certificate verification</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslproxyverifydepth">SSLProxyVerifyDepth <em>number</em></a></td><td> 1 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum depth of CA Certificates in Remote Server
Certificate verification</td></tr>
-<tr
class="odd"><td><a href="mod_ssl.html#sslrandomseed">SSLRandomSeed <em>context</em> <em>source</em>
-[<em>bytes</em>]</a></td><td></td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Pseudo Random Number Generator (PRNG) seeding
+<tr><td><a href="mod_ssl.html#sslrandomseed">SSLRandomSeed <em>context</em> <em>source</em>
+[<em>bytes</em>]</a></td><td></td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Pseudo Random Number Generator (PRNG) seeding
source</td></tr>
-<tr><td><a href="mod_ssl.html#sslrenegbuffersize">SSLRenegBufferSize <var>bytes</var></a></td><td> 131072 </td><td>dh</td><td>E</td></tr><tr><td class="descr" colspan="4">Set the size for the SSL renegotiation buffer</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslrequire">SSLRequire <em>expression</em></a></td><td></td><td>dh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Allow access only when an arbitrarily complex
+<tr class="odd"><td><a href="mod_ssl.html#sslrenegbuffersize">SSLRenegBufferSize <var>bytes</var></a></td><td> 131072 </td><td>dh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Set the size for the SSL renegotiation buffer</td></tr>
+<tr><td><a href="mod_ssl.html#sslrequire">SSLRequire <em>expression</em></a></td><td></td><td>dh</td><td>E</td></tr><tr><td class="descr" colspan="4">Allow access only when an arbitrarily complex
boolean expression is true</td></tr>
-<tr><td><a href="mod_ssl.html#sslrequiressl">SSLRequireSSL</a></td><td></td><td>dh</td><td>E</td></tr><tr><td class="descr" colspan="4">Deny access when SSL is not used for the
+<tr class="odd"><td><a href="mod_ssl.html#sslrequiressl">SSLRequireSSL</a></td><td></td><td>dh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Deny access when SSL is not used for the
HTTP request</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslsessioncache">SSLSessionCache <em>type</em></a></td><td> none </td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Type of the global/inter-process SSL Session
+<tr><td><a href="mod_ssl.html#sslsessioncache">SSLSessionCache <em>type</em></a></td><td> none </td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Type of the global/inter-process SSL Session
Cache</td></tr>
-<tr><td><a href="mod_ssl.html#sslsessioncachetimeout">SSLSessionCacheTimeout <em>seconds</em></a></td><td> 300 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Number of seconds before an SSL session expires
+<tr class="odd"><td><a href="mod_ssl.html#sslsessioncachetimeout">SSLSessionCacheTimeout <em>seconds</em></a></td><td> 300 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Number of seconds before an SSL session expires
in the Session Cache</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslsessionticketkeyfile">SSLSessionTicketKeyFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Persistent encryption/decryption key for TLS session tickets</td></tr>
-<tr><td><a href="mod_ssl.html#sslsessiontickets">SSLSessionTickets on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable or disable use of TLS session tickets</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslsrpunknownuserseed">SSLSRPUnknownUserSeed <em>secret-string</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">SRP unknown user seed</td></tr>
-<tr><td><a href="mod_ssl.html#sslsrpverifierfile">SSLSRPVerifierFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Path to SRP verifier file</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslstaplingcache">SSLStaplingCache <em>type</em></a></td><td></td><td>s</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Configures the OCSP stapling cache</td></tr>
-<tr><td><a href="mod_ssl.html#sslstaplingerrorcachetimeout">SSLStaplingErrorCacheTimeout <em>seconds</em></a></td><td> 600 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Number of seconds before expiring invalid responses in the OCSP stapling cache</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslstaplingfaketrylater">SSLStaplingFakeTryLater on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Synthesize "tryLater" responses for failed OCSP stapling queries</td></tr>
-<tr><td><a href="mod_ssl.html#sslstaplingforceurl">SSLStaplingForceURL <em>uri</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Override the OCSP responder URI specified in the certificate's AIA extension</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslstaplingrespondertimeout">SSLStaplingResponderTimeout <em>seconds</em></a></td><td> 10 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Timeout for OCSP stapling queries</td></tr>
-<tr><td><a href="mod_ssl.html#sslstaplingresponsemaxage">SSLStaplingResponseMaxAge <em>seconds</em></a></td><td> -1 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximum allowable age for OCSP stapling responses</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslstaplingresponsetimeskew">SSLStaplingResponseTimeSkew <em>seconds</em></a></td><td> 300 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum allowable time skew for OCSP stapling response validation</td></tr>
-<tr><td><a href="mod_ssl.html#sslstaplingreturnrespondererrors">SSLStaplingReturnResponderErrors on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Pass stapling related OCSP errors on to client</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslstaplingstandardcachetimeout">SSLStaplingStandardCacheTimeout <em>seconds</em></a></td><td> 3600 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Number of seconds before expiring responses in the OCSP stapling cache</td></tr>
-<tr><td><a href="mod_ssl.html#sslstrictsnivhostcheck">SSLStrictSNIVHostCheck on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Whether to allow non-SNI clients to access a name-based virtual
+<tr><td><a href="mod_ssl.html#sslsessionticketkeyfile">SSLSessionTicketKeyFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Persistent encryption/decryption key for TLS session tickets</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslsessiontickets">SSLSessionTickets on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable or disable use of TLS session tickets</td></tr>
+<tr><td><a href="mod_ssl.html#sslsrpunknownuserseed">SSLSRPUnknownUserSeed <em>secret-string</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">SRP unknown user seed</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslsrpverifierfile">SSLSRPVerifierFile <em>file-path</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Path to SRP verifier file</td></tr>
+<tr><td><a href="mod_ssl.html#sslstaplingcache">SSLStaplingCache <em>type</em></a></td><td></td><td>s</td><td>E</td></tr><tr><td class="descr" colspan="4">Configures the OCSP stapling cache</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslstaplingerrorcachetimeout">SSLStaplingErrorCacheTimeout <em>seconds</em></a></td><td> 600 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Number of seconds before expiring invalid responses in the OCSP stapling cache</td></tr>
+<tr><td><a href="mod_ssl.html#sslstaplingfaketrylater">SSLStaplingFakeTryLater on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Synthesize "tryLater" responses for failed OCSP stapling queries</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslstaplingforceurl">SSLStaplingForceURL <em>uri</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Override the OCSP responder URI specified in the certificate's AIA extension</td></tr>
+<tr><td><a href="mod_ssl.html#sslstaplingrespondertimeout">SSLStaplingResponderTimeout <em>seconds</em></a></td><td> 10 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Timeout for OCSP stapling queries</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslstaplingresponsemaxage">SSLStaplingResponseMaxAge <em>seconds</em></a></td><td> -1 </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum allowable age for OCSP stapling responses</td></tr>
+<tr><td><a href="mod_ssl.html#sslstaplingresponsetimeskew">SSLStaplingResponseTimeSkew <em>seconds</em></a></td><td> 300 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximum allowable time skew for OCSP stapling response validation</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslstaplingreturnrespondererrors">SSLStaplingReturnResponderErrors on|off</a></td><td> on </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Pass stapling related OCSP errors on to client</td></tr>
+<tr><td><a href="mod_ssl.html#sslstaplingstandardcachetimeout">SSLStaplingStandardCacheTimeout <em>seconds</em></a></td><td> 3600 </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Number of seconds before expiring responses in the OCSP stapling cache</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslstrictsnivhostcheck">SSLStrictSNIVHostCheck on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Whether to allow non-SNI clients to access a name-based virtual
host.
</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslusername">SSLUserName <em>varname</em></a></td><td></td><td>sdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Variable name to determine user name</td></tr>
-<tr><td><a href="mod_ssl.html#sslusestapling">SSLUseStapling on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Enable stapling of OCSP responses in the TLS handshake</td></tr>
-<tr class="odd"><td><a href="mod_ssl.html#sslverifyclient">SSLVerifyClient <em>level</em></a></td><td> none </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Type of Client Certificate verification</td></tr>
-<tr><td><a href="mod_ssl.html#sslverifydepth">SSLVerifyDepth <em>number</em></a></td><td> 1 </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Maximum depth of CA Certificates in Client
+<tr><td><a href="mod_ssl.html#sslusername">SSLUserName <em>varname</em></a></td><td></td><td>sdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Variable name to determine user name</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslusestapling">SSLUseStapling on|off</a></td><td> off </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Enable stapling of OCSP responses in the TLS handshake</td></tr>
+<tr><td><a href="mod_ssl.html#sslverifyclient">SSLVerifyClient <em>level</em></a></td><td> none </td><td>svdh</td><td>E</td></tr><tr><td class="descr" colspan="4">Type of Client Certificate verification</td></tr>
+<tr class="odd"><td><a href="mod_ssl.html#sslverifydepth">SSLVerifyDepth <em>number</em></a></td><td> 1 </td><td>svdh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Maximum depth of CA Certificates in Client
Certificate verification</td></tr>
-<tr class="odd"><td><a href="mpm_common.html#startservers">StartServers <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Number of child server processes created at startup</td></tr>
-<tr><td><a href="mpm_common.html#startthreads">StartThreads <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Number of threads created on startup</td></tr>
-<tr class="odd"><td><a href="mod_substitute.html#substitute">Substitute <var>s/pattern/substitution/[infq]</var></a></td><td></td><td>dh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Pattern to filter the response content</td></tr>
-<tr><td><a href="mod_substitute.html#substitutemaxlinelength">SubstituteMaxLineLength <var>bytes</var>(b|B|k|K|m|M|g|G)</a></td><td> 1m </td><td>dh</td><td>E</td></tr><tr><td class="descr" colspan="4">Set the maximum line size</td></tr>
-<tr class="odd"><td><a href="mod_unixd.html#suexec">Suexec On|Off</a></td><td></td><td>s</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Enable or disable the suEXEC feature</td></tr>
-<tr><td><a href="mod_suexec.html#suexecusergroup">SuexecUserGroup <em>User Group</em></a></td><td></td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">User and group for CGI programs to run as</td></tr>
-<tr class="odd"><td><a href="mpm_common.html#threadlimit" id="T" name="T">ThreadLimit <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Sets the upper limit on the configurable number of threads
+<tr><td><a href="mpm_common.html#startservers">StartServers <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Number of child server processes created at startup</td></tr>
+<tr class="odd"><td><a href="mpm_common.html#startthreads">StartThreads <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Number of threads created on startup</td></tr>
+<tr><td><a href="mod_substitute.html#substitute">Substitute <var>s/pattern/substitution/[infq]</var></a></td><td></td><td>dh</td><td>E</td></tr><tr><td class="descr" colspan="4">Pattern to filter the response content</td></tr>
+<tr class="odd"><td><a href="mod_substitute.html#substitutemaxlinelength">SubstituteMaxLineLength <var>bytes</var>(b|B|k|K|m|M|g|G)</a></td><td> 1m </td><td>dh</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Set the maximum line size</td></tr>
+<tr><td><a href="mod_unixd.html#suexec">Suexec On|Off</a></td><td></td><td>s</td><td>B</td></tr><tr><td class="descr" colspan="4">Enable or disable the suEXEC feature</td></tr>
+<tr class="odd"><td><a href="mod_suexec.html#suexecusergroup">SuexecUserGroup <em>User Group</em></a></td><td></td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">User and group for CGI programs to run as</td></tr>
+<tr><td><a href="mpm_common.html#threadlimit" id="T" name="T">ThreadLimit <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Sets the upper limit on the configurable number of threads
per child process</td></tr>
-<tr><td><a href="mpm_common.html#threadsperchild">ThreadsPerChild <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">Number of threads created by each child process</td></tr>
-<tr class="odd"><td><a href="mpm_common.html#threadstacksize">ThreadStackSize <var>size</var></a></td><td></td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">The size in bytes of the stack used by threads handling
+<tr class="odd"><td><a href="mpm_common.html#threadsperchild">ThreadsPerChild <var>number</var></a></td><td></td><td>s</td><td>M</td></tr><tr class="odd"><td class="descr" colspan="4">Number of threads created by each child process</td></tr>
+<tr><td><a href="mpm_common.html#threadstacksize">ThreadStackSize <var>size</var></a></td><td></td><td>s</td><td>M</td></tr><tr><td class="descr" colspan="4">The size in bytes of the stack used by threads handling
client connections</td></tr>
-<tr><td><a href="core.html#timeout">TimeOut <var>seconds</var></a></td><td> 60 </td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Amount of time the server will wait for
+<tr class="odd"><td><a href="core.html#timeout">TimeOut <var>seconds</var></a></td><td> 60 </td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Amount of time the server will wait for
certain events before failing a request</td></tr>
-<tr class="odd"><td><a href="core.html#traceenable">TraceEnable <var>[on|off|extended]</var></a></td><td> on </td><td>sv</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Determines the behavior on <code>TRACE</code> requests</td></tr>
-<tr><td><a href="mod_log_config.html#transferlog">TransferLog <var>file</var>|<var>pipe</var></a></td><td></td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Specify location of a log file</td></tr>
-<tr class="odd"><td><a href="mod_mime.html#typesconfig">TypesConfig <var>file-path</var></a></td><td> conf/mime.types </td><td>s</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">The location of the <code>mime.types</code> file</td></tr>
-<tr><td><a href="core.html#undefine" id="U" name="U">UnDefine <var>parameter-name</var></a></td><td></td><td>s</td><td>C</td></tr><tr><td class="descr" colspan="4">Undefine the existence of a variable</td></tr>
-<tr class="odd"><td><a href="mod_macro.html#undefmacro">UndefMacro <var>name</var></a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Undefine a macro</td></tr>
-<tr><td><a href="mod_env.html#unsetenv">UnsetEnv <var>env-variable</var> [<var>env-variable</var>]
-...</a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Removes variables from the environment</td></tr>
-<tr
class="odd"><td><a href="mod_macro.html#use">Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
-</a></td><td></td><td>svd</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Use a macro</td></tr>
-<tr><td><a href="core.html#usecanonicalname">UseCanonicalName On|Off|DNS</a></td><td> Off </td><td>svd</td><td>C</td></tr><tr><td class="descr" colspan="4">Configures how the server determines its own name and
+<tr><td><a href="core.html#traceenable">TraceEnable <var>[on|off|extended]</var></a></td><td> on </td><td>sv</td><td>C</td></tr><tr><td class="descr" colspan="4">Determines the behavior on <code>TRACE</code> requests</td></tr>
+<tr class="odd"><td><a href="mod_log_config.html#transferlog">TransferLog <var>file</var>|<var>pipe</var></a></td><td></td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Specify location of a log file</td></tr>
+<tr><td><a href="mod_mime.html#typesconfig">TypesConfig <var>file-path</var></a></td><td> conf/mime.types </td><td>s</td><td>B</td></tr><tr><td class="descr" colspan="4">The location of the <code>mime.types</code> file</td></tr>
+<tr class="odd"><td><a href="core.html#undefine" id="U" name="U">UnDefine <var>parameter-name</var></a></td><td></td><td>s</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Undefine the existence of a variable</td></tr>
+<tr><td><a href="mod_macro.html#undefmacro">UndefMacro <var>name</var></a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Undefine a macro</td></tr>
+<tr
class="odd"><td><a href="mod_env.html#unsetenv">UnsetEnv <var>env-variable</var> [<var>env-variable</var>]
+...</a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Removes variables from the environment</td></tr>
+<tr><td><a href="mod_macro.html#use">Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
+</a></td><td></td><td>svd</td><td>B</td></tr><tr><td class="descr" colspan="4">Use a macro</td></tr>
+<tr class="odd"><td><a href="core.html#usecanonicalname">UseCanonicalName On|Off|DNS</a></td><td> Off </td><td>svd</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Configures how the server determines its own name and
port</td></tr>
-<tr class="odd"><td><a href="core.html#usecanonicalphysicalport">UseCanonicalPhysicalPort On|Off</a></td><td> Off </td><td>svd</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Configures how the server determines its own port</td></tr>
-<tr><td><a href="mod_unixd.html#user">User <var>unix-userid</var></a></td><td> #-1 </td><td>s</td><td>B</td></tr><tr><td class="descr" colspan="4">The userid under which the server will answer
+<tr><td><a href="core.html#usecanonicalphysicalport">UseCanonicalPhysicalPort On|Off</a></td><td> Off </td><td>svd</td><td>C</td></tr><tr><td class="descr" colspan="4">Configures how the server determines its own port</td></tr>
+<tr class="odd"><td><a href="mod_unixd.html#user">User <var>unix-userid</var></a></td><td> #-1 </td><td>s</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">The userid under which the server will answer
requests</td></tr>
-<tr
class="odd"><td><a href="mod_userdir.html#userdir">UserDir <em>directory-filename</em> [<em>directory-filename</em>] ...
-</a></td><td></td><td>sv</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Location of the user-specific directories</td></tr>
-<tr><td><a href="mod_privileges.html#vhostcgimode" id="V" name="V">VHostCGIMode On|Off|Secure</a></td><td> On </td><td>v</td><td>X</td></tr><tr><td class="descr" colspan="4">Determines whether the virtualhost can run
+<tr><td><a href="mod_userdir.html#userdir">UserDir <em>directory-filename</em> [<em>directory-filename</em>] ...
+</a></td><td></td><td>sv</td><td>B</td></tr><tr><td class="descr" colspan="4">Location of the user-specific directories</td></tr>
+<tr class="odd"><td><a href="mod_privileges.html#vhostcgimode" id="V" name="V">VHostCGIMode On|Off|Secure</a></td><td> On </td><td>v</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Determines whether the virtualhost can run
subprocesses, and the privileges available to subprocesses.</td></tr>
-<tr class="odd"><td><a href="mod_privileges.html#vhostcgiprivs">VHostPrivs [+-]?<var>privilege-name</var> [[+-]?privilege-name] ...</a></td><td></td><td>v</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Assign arbitrary privileges to subprocesses created
+<tr><td><a href="mod_privileges.html#vhostcgiprivs">VHostPrivs [+-]?<var>privilege-name</var> [[+-]?privilege-name] ...</a></td><td></td><td>v</td><td>X</td></tr><tr><td class="descr" colspan="4">Assign arbitrary privileges to subprocesses created
by a virtual host.</td></tr>
-<tr><td><a href="mod_privileges.html#vhostgroup">VHostGroup <var>unix-groupid</var></a></td><td></td><td>v</td><td>X</td></tr><tr><td class="descr" colspan="4">Sets the Group ID under which a virtual host runs.</td></tr>
-<tr class="odd"><td><a href="mod_privileges.html#vhostprivs">VHostPrivs [+-]?<var>privilege-name</var> [[+-]?privilege-name] ...</a></td><td></td><td>v</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Assign arbitrary privileges to a virtual host.</td></tr>
-<tr><td><a href="mod_privileges.html#vhostsecure">VHostSecure On|Off</a></td><td> On </td><td>v</td><td>X</td></tr><tr><td class="descr" colspan="4">Determines whether the server runs with enhanced security
+<tr class="odd"><td><a href="mod_privileges.html#vhostgroup">VHostGroup <var>unix-groupid</var></a></td><td></td><td>v</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Sets the Group ID under which a virtual host runs.</td></tr>
+<tr><td><a href="mod_privileges.html#vhostprivs">VHostPrivs [+-]?<var>privilege-name</var> [[+-]?privilege-name] ...</a></td><td></td><td>v</td><td>X</td></tr><tr><td class="descr" colspan="4">Assign arbitrary privileges to a virtual host.</td></tr>
+<tr class="odd"><td><a href="mod_privileges.html#vhostsecure">VHostSecure On|Off</a></td><td> On </td><td>v</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Determines whether the server runs with enhanced security
for the virtualhost.</td></tr>
-<tr class="odd"><td><a href="mod_privileges.html#vhostuser">VHostUser <var>unix-userid</var></a></td><td></td><td>v</td><td>X</td></tr><tr class="odd"><td class="descr" colspan="4">Sets the User ID under which a virtual host runs.</td></tr>
-<tr><td><a href="mod_vhost_alias.html#virtualdocumentroot">VirtualDocumentRoot <em>interpolated-directory</em>|none</a></td><td> none </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Dynamically configure the location of the document root
+<tr><td><a href="mod_privileges.html#vhostuser">VHostUser <var>unix-userid</var></a></td><td></td><td>v</td><td>X</td></tr><tr><td class="descr" colspan="4">Sets the User ID under which a virtual host runs.</td></tr>
+<tr class="odd"><td><a href="mod_vhost_alias.html#virtualdocumentroot">VirtualDocumentRoot <em>interpolated-directory</em>|none</a></td><td> none </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Dynamically configure the location of the document root
for a given virtual host</td></tr>
-<tr class="odd"><td><a href="mod_vhost_alias.html#virtualdocumentrootip">VirtualDocumentRootIP <em>interpolated-directory</em>|none</a></td><td> none </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Dynamically configure the location of the document root
+<tr><td><a href="mod_vhost_alias.html#virtualdocumentrootip">VirtualDocumentRootIP <em>interpolated-directory</em>|none</a></td><td> none </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Dynamically configure the location of the document root
for a given virtual host</td></tr>
-<tr><td><a href="core.html#virtualhost"><VirtualHost
+<tr
class="odd"><td><a href="core.html#virtualhost"><VirtualHost
<var>addr</var>[:<var>port</var>] [<var>addr</var>[:<var>port</var>]]
- ...> ... </VirtualHost></a></td><td></td><td>s</td><td>C</td></tr><tr><td class="descr" colspan="4">Contains directives that apply only to a specific
+ ...> ... </VirtualHost></a></td><td></td><td>s</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Contains directives that apply only to a specific
hostname or IP address</td></tr>
-<tr class="odd"><td><a href="mod_vhost_alias.html#virtualscriptalias">VirtualScriptAlias <em>interpolated-directory</em>|none</a></td><td> none </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Dynamically configure the location of the CGI directory for
+<tr><td><a href="mod_vhost_alias.html#virtualscriptalias">VirtualScriptAlias <em>interpolated-directory</em>|none</a></td><td> none </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Dynamically configure the location of the CGI directory for
a given virtual host</td></tr>
-<tr><td><a href="mod_vhost_alias.html#virtualscriptaliasip">VirtualScriptAliasIP <em>interpolated-directory</em>|none</a></td><td> none </td><td>sv</td><td>E</td></tr><tr><td class="descr" colspan="4">Dynamically configure the location of the CGI directory for
+<tr class="odd"><td><a href="mod_vhost_alias.html#virtualscriptaliasip">VirtualScriptAliasIP <em>interpolated-directory</em>|none</a></td><td> none </td><td>sv</td><td>E</td></tr><tr class="odd"><td class="descr" colspan="4">Dynamically configure the location of the CGI directory for
a given virtual host</td></tr>
-<tr class="odd"><td><a href="mod_watchdog.html#watchdoginterval" id="W" name="W">WatchdogInterval <var>number-of-seconds</var></a></td><td> 1 </td><td>s</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Watchdog interval in seconds</td></tr>
-<tr><td><a href="mod_include.html#xbithack" id="X" name="X">XBitHack on|off|full</a></td><td> off </td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Parse SSI directives in files with the execute bit
+<tr><td><a href="mod_watchdog.html#watchdoginterval" id="W" name="W">WatchdogInterval <var>number-of-seconds</var></a></td><td> 1 </td><td>s</td><td>B</td></tr><tr><td class="descr" colspan="4">Watchdog interval in seconds</td></tr>
+<tr class="odd"><td><a href="mod_include.html#xbithack" id="X" name="X">XBitHack on|off|full</a></td><td> off </td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Parse SSI directives in files with the execute bit
set</td></tr>
-<tr class="odd"><td><a href="mod_xml2enc.html#xml2encalias">xml2EncAlias <var>charset alias [alias ...]</var></a></td><td></td><td>s</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Recognise Aliases for encoding values</td></tr>
-<tr><td><a href="mod_xml2enc.html#xml2encdefault">xml2EncDefault <var>name</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Sets a default encoding to assume when absolutely no information
+<tr><td><a href="mod_xml2enc.html#xml2encalias">xml2EncAlias <var>charset alias [alias ...]</var></a></td><td></td><td>s</td><td>B</td></tr><tr><td class="descr" colspan="4">Recognise Aliases for encoding values</td></tr>
+<tr class="odd"><td><a href="mod_xml2enc.html#xml2encdefault">xml2EncDefault <var>name</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Sets a default encoding to assume when absolutely no information
can be <a href="#sniffing">automatically detected</a></td></tr>
-<tr class="odd"><td><a href="mod_xml2enc.html#xml2startparse">xml2StartParse <var>element [element ...]</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr class="odd"><td class="descr" colspan="4">Advise the parser to skip leading junk.</td></tr>
+<tr><td><a href="mod_xml2enc.html#xml2startparse">xml2StartParse <var>element [element ...]</var></a></td><td></td><td>svdh</td><td>B</td></tr><tr><td class="descr" colspan="4">Advise the parser to skip leading junk.</td></tr>
</table></div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../de/mod/quickreference.html" hreflang="de" rel="alternate" title="Deutsch"> de </a> |
controls the maximum total number of threads that may be
launched.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#how-it-works">How it Works</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li>
<li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#enableexceptionhook">EnableExceptionHook</a></li>
<li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#threadstacksize">ThreadStackSize</a></li>
<li><img alt="" src="../images/right.gif" /> <a href="mod_unixd.html#user">User</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#how-it-works">How it Works</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><a href="../bind.html">Setting which addresses and ports Apache HTTP Server uses</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
projects / apache / commitdiff