On Windows from Apache httpd 2.3.3 and later.</compatibility>
<usage>
- <p>This directive enables operating system specific optimizations for a
- listening socket by the Protocol type. The basic premise is for the
- kernel to not send a socket to the server process until either data
- is received or an entire HTTP Request is buffered. Only
- <a href="http://www.freebsd.org/cgi/man.cgi?query=accept_filter&sektion=9">
- FreeBSD's Accept Filters</a>, Linux's more primitive
+ <p>This directive enables operating system specific optimizations for a
+ listening socket by the <directive>Protocol</directive>type.
+ The basic premise is for the kernel to not send a socket to the server
+ process until either data is received or an entire HTTP Request is buffered.
+
Only <a href="http://www.freebsd.org/cgi/man.cgi?query=accept_filter&sektion=9">
+ FreeBSD's Accept Filters</a>, Linux's more primitive
<code>TCP_DEFER_ACCEPT</code>, and Windows' optimized AcceptEx()
are currently supported.</p>
- <p>Using <code>none</code> for an argument will disable any accept filters
+ <p>Using <code>none</code> for an argument will disable any accept filters
for that protocol. This is useful for protocols that require a server
send data first, such as <code>ftp:</code> or <code>nntp</code>:</p>
<example>AcceptFilter nntp none</example>
+ <p>The default protocol names are <code>https</code> for port 443
+ and <code>http</code> for all other ports. To specify another protocol
+ is being used with a listening port, add the <var>protocol</var>
+ argument to the <directive module="mpm_common">Listen</directive>
+ directive.</p>
+
<p>The default values on FreeBSD are:</p>
<example>
AcceptFilter http httpready <br/>
AcceptFilter https dataready
</example>
-
+
<p>The <code>httpready</code> accept filter buffers entire HTTP requests at
- the kernel level. Once an entire request is received, the kernel then
- sends it to the server. See the
+ the kernel level. Once an entire request is received, the kernel then
+ sends it to the server. See the
<a href="http://www.freebsd.org/cgi/man.cgi?query=accf_http&sektion=9">
- accf_http(9)</a> man page for more details. Since HTTPS requests are
+ accf_http(9)</a> man page for more details. Since HTTPS requests are
encrypted only the <a href="http://www.freebsd.org/cgi/man.cgi?query=accf_data&sektion=9">
accf_data(9)</a> filter is used.</p>
</example>
<p>Linux's <code>TCP_DEFER_ACCEPT</code> does not support buffering http
- requests. Any value besides <code>none</code> will enable
+ requests. Any value besides <code>none</code> will enable
<code>TCP_DEFER_ACCEPT</code> on that listener. For more details
- see the Linux
+ see the Linux
<a href="http://homepages.cwi.nl/~aeb/linux/man2html/man7/tcp.7.html">
tcp(7)</a> man page.</p>
the <code>connect</code> option does not wait for the initial data
transmission.</p>
- <p>On Windows, <code>none</code> uses accept() rather than than AcceptEx()
+ <p>On Windows, <code>none</code> uses accept() rather than AcceptEx()
and will not recycle sockets between connections. This is useful for
network adapters with broken driver support, as well as some virtual
network providers such as vpn drivers, or spam, virus or spyware
- filters.</p>
+ filters.</p>
</usage>
+<seealso><directive>Protocol</directive></seealso>
</directivesynopsis>
<directivesynopsis>
<code>.htaccess</code> files</description>
<syntax>AllowOverride All|None|<var>directive-type</var>
[<var>directive-type</var>] ...</syntax>
-<default>AllowOverride All</default>
+<default>AllowOverride None (2.3.9 and later), AllowOverride All (2.3.8 and earlier)</default>
<contextlist><context>directory</context></contextlist>
<usage>
server error.</p>
<note><p>For security and performance reasons, do not set
- <code>AllowOverride</code> to anything other than <code>None</code>
+ <code>AllowOverride</code> to anything other than <code>None</code>
in your <code><Directory /></code> block. Instead, find (or
create) the <code><Directory></code> block that refers to the
directory where you're actually planning to place a
<directivesynopsis type="section">
<name>Directory</name>
<description>Enclose a group of directives that apply only to the
-named file-system directory and sub-directories</description>
+named file-system directory, sub-directories, and their contents.</description>
<syntax><Directory <var>directory-path</var>>
... </Directory></syntax>
<contextlist><context>server config</context><context>virtual host</context>
<usage>
<p><directive type="section">Directory</directive> and
<code></Directory></code> are used to enclose a group of
- directives that will apply only to the named directory and
- sub-directories of that directory. Any directive that is allowed
+ directives that will apply only to the named directory,
+ sub-directories of that directory, and the files within the respective
+ directories. Any directive that is allowed
in a directory context may be used. <var>Directory-path</var> is
either the full path to a directory, or a wild-card string using
Unix shell-style matching. In a wild-card string, <code>?</code> matches
<directivesynopsis type="section">
<name>DirectoryMatch</name>
<description>Enclose directives that apply to
-file-system directories matching a regular expression and their
-subdirectories</description>
+the contents of file-system directories matching a regular expression.</description>
<syntax><DirectoryMatch <var>regex</var>>
... </DirectoryMatch></syntax>
<contextlist><context>server config</context><context>virtual host</context>
<usage>
<p><directive type="section">DirectoryMatch</directive> and
<code></DirectoryMatch></code> are used to enclose a group
- of directives which will apply only to the named directory and
- sub-directories of that directory, the same as <directive
- module="core" type="section">Directory</directive>. However, it
- takes as an argument a <glossary ref="regex">regular
- expression</glossary>. For example:</p>
+ of directives which will apply only to the named directory (and the files within),
+ the same as <directive module="core" type="section">Directory</directive>.
+ However, it takes as an argument a
+ <glossary ref="regex">regular expression</glossary>. For example:</p>
<example>
<DirectoryMatch "^/www/(.+/)?[0-9]{3}">
<p>would match directories in <code>/www/</code> that consisted of three
numbers.</p>
+
+ <note><title>Compatability</title>
+ Prior to 2.3.9, this directive implicitly applied to sub-directories
+ (like <directive module="core" type="section">Directory</directive>) and
+ could not match the end of line symbol ($). In 2.3.9 and later,
+ only directories that match the expression are affected by the enclosed
+ directives.
+ </note>
+
+ <note><title>Trailing Slash</title>
+ This directive applies to requests for directories that may or may
+ not end in a trailing slash, so expressions that are anchored to the
+ end of line ($) must be written with care.
+ </note>
</usage>
<seealso><directive type="section" module="core">Directory</directive> for
a description of how regular expressions are mixed in with normal
</example>
<p>then an access to
- <code>http://www.my.host.com/index.html</code> refers to
- <code>/usr/web/index.html</code>. If the <var>directory-path</var> is
- not absolute then it is assumed to be relative to the <directive
+ <code>http://my.example.com/index.html</code> refers to
+ <code>/usr/web/index.html</code>. If the <var>directory-path</var> is
+ not absolute then it is assumed to be relative to the <directive
module="core">ServerRoot</directive>.</p>
<p>The <directive>DocumentRoot</directive> should be specified without
<name>EnableSendfile</name>
<description>Use the kernel sendfile support to deliver files to the client</description>
<syntax>EnableSendfile On|Off</syntax>
-<default>EnableSendfile On</default>
+<default>EnableSendfile Off</default>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context>
</contextlist>
<override>FileInfo</override>
-<compatibility>Available in version 2.0.44 and later</compatibility>
+<compatibility>Available in version 2.0.44 and later. Default changed to Off in
+version 2.3.9.</compatibility>
<usage>
<p>This directive controls whether <program>httpd</program> may use the
<li>On Linux on Itanium, sendfile may be unable to handle files
over 2GB in size.</li>
<li>With a network-mounted <directive
- module="core">DocumentRoot</directive> (e.g., NFS or SMB),
+ module="core">DocumentRoot</directive> (e.g., NFS, SMB, CIFS, FUSE),
the kernel may be unable to serve the network file through
its own cache.</li>
</ul>
- <p>For server configurations that are vulnerable to these problems,
- you should disable this feature by specifying:</p>
+ <p>For server configurations that are not vulnerable to these problems,
+ you may enable this feature by specifying:</p>
<example>
- EnableSendfile Off
+ EnableSendfile On
</example>
- <p>For NFS or SMB mounted files, this feature may be disabled explicitly
+ <p>For network mounted files, this feature may be disabled explicitly
for the offending files by specifying:</p>
<example>
</example>
<p>Please note that the per-directory and .htaccess configuration
of <directive>EnableSendfile</directive> is not supported by
- <module>mod_disk_cache</module>.
+ <module>mod_cache_disk</module>.
Only global definition of <directive>EnableSendfile</directive>
is taken into account by the module.
</p>
</usage>
</directivesynopsis>
+<directivesynopsis>
+<name>Error</name>
+<description>Abort configuration parsing with a custom error message</description>
+<syntax>Error <var>message</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+<context>directory</context><context>.htaccess</context>
+</contextlist>
+<compatibility>2.3.9 and later</compatibility>
+
+<usage>
+ <p>If an error can be detected within the configuration, this
+ directive can be used to generate a custom error message, and halt
+ configuration parsing. The typical use is for reporting required
+ modules which are missing from the configuration.</p>
+
+ <example><title>Example</title>
+ # ensure that mod_include is loaded<br />
+ <IfModule !include_module><br />
+ Error mod_include is required by mod_foo. Load it with LoadModule.<br />
+ </IfModule><br />
+ <br />
+ # ensure that exactly one of SSL,NOSSL is defined<br />
+ <IfDefine SSL><br />
+ <IfDefine NOSSL><br />
+ Error Both SSL and NOSSL are defined. Define only one of them.<br />
+ </IfDefine><br />
+ </IfDefine><br />
+ <IfDefine !SSL><br />
+ <IfDefine !NOSSL><br />
+ Error Either SSL or NOSSL must be defined.<br />
+ </IfDefine><br />
+ </IfDefine><br />
+ </example>
+
+</usage>
+</directivesynopsis>
+
<directivesynopsis>
<name>ErrorDocument</name>
<description>What the server will return to the client
<context>directory</context><context>.htaccess</context>
</contextlist>
<override>FileInfo</override>
-<compatibility>Quoting syntax for text messages is different in Apache HTTP Server
-2.0</compatibility>
<usage>
<p>In the event of a problem or error, Apache httpd can be configured
will be immediately halted and the internal error message returned.
This is necessary to guard against security problems caused by
bad requests.</p>
-
+
<p>If you are using mod_proxy, you may wish to enable
<directive module="mod_proxy">ProxyErrorOverride</directive> so that you can provide
custom error messages on behalf of your Origin servers. If you don't enable ProxyErrorOverride,
<usage>
<p>The <directive>ErrorLog</directive> directive sets the name of
the file to which the server will log any errors it encounters. If
- the <var>file-path</var> is not absolute then it is assumed to be
+ the <var>file-path</var> is not absolute then it is assumed to be
relative to the <directive module="core">ServerRoot</directive>.</p>
<example><title>Example</title>
syslog facility <code>local7</code>, but you can override this by
using the <code>syslog:<var>facility</var></code> syntax where
<var>facility</var> can be one of the names usually documented in
- syslog(1).</p>
+ syslog(1). The facility is effectively global, and if it is changed
+ in individual virtual hosts, the final facility specified affects the
+ entire server.</p>
<example><title>Example</title>
ErrorLog syslog:user
anyone other than the user that starts the server.</p>
<note type="warning"><title>Note</title>
<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
+ 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>
</note>
</usage>
<seealso><a href="../logs.html">Apache HTTP Server Log Files</a></seealso>
</directivesynopsis>
+<directivesynopsis>
+<name>ErrorLogFormat</name>
+<description>Format specification for error log entries</description>
+<syntax> ErrorLog [connection|request] <var>format</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
+<compatibility>Available in Apache httpd 2.3.9 and later</compatibility>
+
+<usage>
+ <p><directive>ErrorLogFormat</directive> allows to specify what
+ supplementary information is logged in the error log in addition to the
+ actual log message.</p>
+
+ <example><title>Simple example</title>
+ ErrorLogFormat "[%t] [%l] [pid %P] %F: %E: [client %a] %M"
+ </example>
+
+ <p>Specifying <code>connection</code> or <code>request</code> as first
+ paramter allows to specify additional formats, causing additional
+ information to be logged when the first message is logged for a specific
+ connection or request, respectivly. This additional information is only
+ logged once per connection/request. If a connection or request is processed
+ without causing any log message, the additional information is not logged
+ either.</p>
+
+ <p>It can happen that some format string items do not produce output. For
+ example, the Referer header is only present if the log message is
+ associated to a request and the log message happens at a time when the
+ Referer header has already been read from the client. If no output is
+ produced, the default behaviour is to delete everything from the preceeding
+ space character to the next space character. This means the log line is
+ implicitly divided into fields on non-whitespace to whitespace transitions.
+ If a format string item does not produce output, the whole field is
+ ommitted. For example, if the remote address <code>%a</code> in the log
+ format <code>[%t] [%l] [%a] %M </code> is not available, the surrounding
+ brackets are not logged either. Space characters can be escaped with a
+ backslash to prevent them from delimiting a field. The combination '% '
+ (percent space) is a zero-witdh field delimiter that does not produce any
+ output.</p>
+
+ <p>The above behaviour can be changed by adding modifiers to the format
+ string item. A <code>-</code> (minus) modifier causes a minus to be logged if the
+ respective item does not produce any output. In once-per-connection/request
+ formats, it is also possible to use the <code>+</code> (plus) modifier. If an
+ item with the plus modifier does not produce any output, the whole line is
+ ommitted.</p>
+
+ <p>A number as modifier can be used to assign a log severity level to a
+ format item. The item will only be logged if the severity of the log
+ message is not higher than the specified log severity level. The number can
+ range from 1 (alert) over 4 (warn) and 7 (debug) to 15 (trace8).</p>
+
+ <p>Some format string items accept additional parameters in braces.</p>
+
+ <table border="1" style="zebra">
+ <columnspec><column width=".2"/><column width=".8"/></columnspec>
+
+ <tr><th>Format String</th> <th>Description</th></tr>
+
+ <tr><td><code>%%</code></td>
+ <td>The percent sign</td></tr>
+
+ <tr><td><code>%...a</code></td>
+ <td>Remote IP-address and port</td></tr>
+
+ <tr><td><code>%...A</code></td>
+ <td>Local IP-address and port</td></tr>
+
+ <tr><td><code>%...{name}e</code></td>
+ <td>Request environment variable <code>name</code></td></tr>
+
+ <tr><td><code>%...E</code></td>
+ <td>APR/OS error status code and string</td></tr>
+
+ <tr><td><code>%...F</code></td>
+ <td>Source file name and line number of the log call</td></tr>
+
+ <tr><td><code>%...{name}i</code></td>
+ <td>Request header <code>name</code></td></tr>
+
+ <tr><td><code>%...k</code></td>
+ <td>Number of keep-alive requests on this connection</td></tr>
+
+ <tr><td><code>%...l</code></td>
+ <td>Loglevel of the message</td></tr>
+
+ <tr><td><code>%...L</code></td>
+ <td>Log ID of the request</td></tr>
+
+ <tr><td><code>%...{c}L</code></td>
+ <td>Log ID of the connection</td></tr>
+
+ <tr><td><code>%...{C}L</code></td>
+ <td>Log ID of the connection if used in connection scope, empty otherwise</td></tr>
+
+ <tr><td><code>%...m</code></td>
+ <td>Name of the module logging the message</td></tr>
+
+ <tr><td><code>%M</code></td>
+ <td>The actual log message</td></tr>
+
+ <tr><td><code>%...{name}n</code></td>
+ <td>Request note <code>name</code></td></tr>
+
+ <tr><td><code>%...P</code></td>
+ <td>Process ID of current process</td></tr>
+
+ <tr><td><code>%...T</code></td>
+ <td>Thread ID of current thread</td></tr>
+
+ <tr><td><code>%...t</code></td>
+ <td>The current time</td></tr>
+
+ <tr><td><code>%...{u}t</code></td>
+ <td>The current time including micro-seconds</td></tr>
+
+ <tr><td><code>%...{cu}t</code></td>
+ <td>The current time in compact ISO 8601 format, including
+ micro-seconds</td></tr>
+
+ <tr><td><code>%...v</code></td>
+ <td>The canonical <directive module="core">ServerName</directive>
+ of the current server.</td></tr>
+
+ <tr><td><code>%...V</code></td>
+ <td>The server name of the server serving the request according to the
+ <directive module="core" >UseCanonicalName</directive>
+ setting.</td></tr>
+
+ <tr><td><code>\ </code> (backslash space)</td>
+ <td>Non-field delimiting space</td></tr>
+
+ <tr><td><code>% </code> (percent space)</td>
+ <td>Field delimiter (no output)</td></tr>
+ </table>
+
+ <p>The log ID format <code>%L</code> produces a unique id for a connection
+ or request. This can be used to correlate which log lines belong to the
+ same connection or request, which request happens on which connection.
+ A <code>%L</code> format string is also available in
+ <module>mod_log_config</module>, to allow to correlate access log entries
+ with error log lines. If <module>mod_unique_id</module> is loaded, its
+ unique id will be used as log ID for requests.</p>
+
+ <example><title>Example (somewhat similar to default format)</title>
+ ErrorLogFormat "[%{u}t] [%-m:%l] [pid %P] %7F: %E: [client\ %a]
+ %M% ,\ referer\ %{Referer}i"
+ </example>
+
+ <example><title>Example (similar to the 2.2.x format)</title>
+ ErrorLogFormat "[%t] [%l] %7F: %E: [client\ %a]
+ %M% ,\ referer\ %{Referer}i"
+ </example>
+
+ <example><title>Advanced example with request/connection log IDs</title>
+ ErrorLogFormat "[%{uc}t] [%-m:%-l] [R:%L] [C:%{C}L] %7F: %E: %M"<br/>
+ ErrorLogFormat request "[%{uc}t] [R:%L] Request %k on C:%{c}L pid:%P tid:%T"<br/>
+ ErrorLogFormat request "[%{uc}t] [R:%L] UA:'%+{User-Agent}i'"<br/>
+ ErrorLogFormat request "[%{uc}t] [R:%L] Referer:'%+{Referer}i'"<br/>
+ ErrorLogFormat connection "[%{uc}t] [C:%{c}L] local\ %a remote\ %A"<br/>
+ </example>
+
+</usage>
+<seealso><directive module="core">ErrorLog</directive></seealso>
+<seealso><directive module="core">LogLevel</directive></seealso>
+<seealso><a href="../logs.html">Apache HTTP Server Log Files</a></seealso>
+</directivesynopsis>
+
<directivesynopsis>
<name>ExtendedStatus</name>
-<description>Keep track of extended status information for each
+<description>Keep track of extended status information for each
request</description>
<syntax>ExtendedStatus On|Off</syntax>
<default>ExtendedStatus Off[*]</default>
<usage>
<p>This option tracks additional data per worker about the
- currently executing request, and a utilization summary; you
- can see these variables during runtime by configuring
+ currently executing request, and a utilization summary; you
+ can see these variables during runtime by configuring
<module>mod_status</module>. Note that other modules may
rely on this scoreboard.</p>
during a graceful restart.</p>
<note>
- <p>Note that loading <module>mod_status</module> will change
+ <p>Note that loading <module>mod_status</module> will change
the default behavior to ExtendedStatus On, while other
third party modules may do the same. Such modules rely on
collecting detailed information about the state of all workers.
changed via <directive>FileETag</directive>.
</note>
<note><title>Server Side Includes</title>
- An ETag is not generated for responses parsed by <module>mod_include</module>,
- since the response entity can change without a change of the INode, MTime, or Size
+ An ETag is not generated for responses parsed by <module>mod_include</module>,
+ since the response entity can change without a change of the INode, MTime, or Size
of the static file with embedded SSI directives.
</note>
<p>The <var>filename</var> argument should include a filename, or
a wild-card string, where <code>?</code> matches any single character,
and <code>*</code> matches any sequences of characters.
- <glossary ref="regex">Regular expressions</glossary>
+ <glossary ref="regex">Regular expressions</glossary>
can also be used, with the addition of the
<code>~</code> character. For example:</p>
<p>The <directive type="section">FilesMatch</directive> directive
limits the scope of the enclosed directives by filename, just as the
<directive module="core" type="section">Files</directive> directive
- does. However, it accepts a <glossary ref="regex">regular
+ does. However, it accepts a <glossary ref="regex">regular
expression</glossary>. For example:</p>
<example>
</indent>
</Location>
</example>
+
+ <p>This directive primarily overrides the content types generated for
+ static files served out of the filesystem. For resources other than
+ static files, where the generator of the response typically specifies
+ a Content-Type, this directive has no effect.</p>
+
+</usage>
+</directivesynopsis>
+<directivesynopsis>
+<name>GprofDir</name>
+<description>Directory to write gmon.out profiling data to. </description>
+<syntax>GprofDir <var>/tmp/gprof/</var>|<var>/tmp/gprof/</var>%</syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
+
+<usage>
+ <p>When the server has been compiled with gprof profiling suppport,
+ <directive>GprofDir</directive> causes <code>gmon.out</code> files to
+ be written to the specified directory when the process exits. If the
+ argument ends with a percent symbol ('%'), subdirectories are created
+ for each process id.</p>
+
+ <p>This directive currently only works with the <module>prefork</module>
+ MPM.</p>
</usage>
</directivesynopsis>
<p>You may compare the value of any variable in the request headers
($req), response headers ($resp) or environment ($env) in your
expression.</p>
+
+ <p>Apart from <code>=</code>, <code>If</code> can use the <code>IN</code>
+ operator to compare if the expression is in a given range:</p>
+
+ <example>
+ <If %{REQUEST_METHOD} IN GET,HEAD,OPTIONS>
+ </example>
+
</usage>
+<seealso><a href="../expr.html">Expressions in Apache HTTP Server</a>,
+for a complete reference and more examples.</seealso>
<seealso><a href="../sections.html">How <Directory>, <Location>,
<Files> sections work</a> for an explanation of how these
different sections are combined when a request is received.
</IfDefine><br />
<IfDefine !MemCache><br />
<indent>
- LoadModule disk_cache_module modules/mod_disk_cache.so<br />
+ LoadModule cache_disk_module modules/mod_cache_disk.so<br />
</indent>
</IfDefine>
</indent>
<directive module="core">Include</directive> directive will fail with an
error saying the file or directory cannot be found.</p>
- <p>The file path specified may be an absolute path, or may be relative
+ <p>The file path specified may be an absolute path, or may be relative
to the <directive module="core">ServerRoot</directive> directory.</p>
<p>Examples:</p>
path. In the following example, the server will fail to load if no
directories match conf/vhosts/*, but will load successfully if no
files match *.conf.</p>
-
+
<example>
Include conf/vhosts/*/vhost.conf<br />
Include conf/vhosts/*/*.conf
<example>
Include strict conf/vhosts/*/*.conf
</example>
-
+
<p>In this example, the server load successfully if either conf/vhosts/*
matches no directories, or if *.conf matches no files:</p>
<seealso><program>apachectl</program></seealso>
</directivesynopsis>
-
+
<directivesynopsis>
<name>KeepAlive</name>
<description>Enables HTTP persistent connections</description>
<p>When a client uses a Keep-Alive connection it will be counted
as a single "request" for the <directive module="mpm_common"
- >MaxRequestsPerChild</directive> directive, regardless
+ >MaxConnectionsPerChild</directive> directive, regardless
of how many requests are sent using the connection.</p>
</usage>
<default>KeepAliveTimeout 5</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
-<compatibility>Specifying a value in milliseconds is available in
+<compatibility>Specifying a value in milliseconds is available in
Apache httpd 2.3.2 and later</compatibility>
<usage>
may cause performance problems in heavily loaded servers. The
higher the timeout, the more server processes will be kept
occupied waiting on connections with idle clients.</p>
-
+
<p>In a name-based virtual host context, the value of the first
defined virtual host (the default host) in a set of <directive
module="core">NameVirtualHost</directive> will be used.
<LimitExcept GET>
<indent>
Require valid-user
- </indent>
+ </indent>
</LimitExcept><br />
<Limit POST>
<indent>
Require group editors
- </indent>
+ </indent>
</Limit>
</example>
</usage>
<usage>
<p>This directive specifies the number of <var>bytes</var> from 0
(meaning unlimited) to 2147483647 (2GB) that are allowed in a
- request body.</p>
+ request body. See the note below for the limited applicability
+ to proxy requests.</p>
<p>The <directive>LimitRequestBody</directive> directive allows
the user to set a limit on the allowed size of an HTTP request
LimitRequestBody 102400
</example>
+ <note><p>For a full description of how this directive is interpreted by
+ proxy requests, see the <module>mod_proxy</module> documentation.</p>
+ </note>
+
</usage>
</directivesynopsis>
will be accepted from the client</description>
<syntax>LimitRequestFields <var>number</var></syntax>
<default>LimitRequestFields 100</default>
-<contextlist><context>server config</context></contextlist>
+<contextlist><context>server config</context><context>virtual host</context></contextlist>
<usage>
<p><var>Number</var> is an integer from 0 (meaning unlimited) to
LimitRequestFields 50
</example>
+ <note type="warning"><title>Warning</title>
+ <p> When name-based virtual hosting is used, the value for this
+ directive is taken from the default (first-listed) virtual host for the
+ <directive>NameVirtualHost</directive> the connection was mapped to.</p>
+ </note>
+
</usage>
</directivesynopsis>
client</description>
<syntax>LimitRequestFieldSize <var>bytes</var></syntax>
<default>LimitRequestFieldSize 8190</default>
-<contextlist><context>server config</context></contextlist>
+<contextlist><context>server config</context><context>virtual host</context></contextlist>
<usage>
<p>This directive specifies the number of <var>bytes</var>
that will be allowed in an HTTP request header.</p>
<p>The <directive>LimitRequestFieldSize</directive> directive
- allows the server administrator to reduce or increase the limit
+ allows the server administrator to reduce or increase the limit
on the allowed size of an HTTP request header field. A server
- needs this value to be large enough to hold any one header field
- from a normal client request. The size of a normal request header
- field will vary greatly among different client implementations,
+ needs this value to be large enough to hold any one header field
+ from a normal client request. The size of a normal request header
+ field will vary greatly among different client implementations,
often depending upon the extent to which a user has configured
their browser to support detailed content negotiation. SPNEGO
authentication headers can be up to 12392 bytes.</p>
<note>Under normal conditions, the value should not be changed from
the default.</note>
+ <note type="warning"><title>Warning</title>
+ <p> When name-based virtual hosting is used, the value for this
+ directive is taken from the default (first-listed) virtual host for the
+ <directive>NameVirtualHost</directive> the connection was mapped to.</p>
+ </note>
+
</usage>
</directivesynopsis>
from the client</description>
<syntax>LimitRequestLine <var>bytes</var></syntax>
<default>LimitRequestLine 8190</default>
-<contextlist><context>server config</context></contextlist>
+<contextlist><context>server config</context><context>virtual host</context></contextlist>
<usage>
- <p>This directive sets the number of <var>bytes</var> that will be
+ <p>This directive sets the number of <var>bytes</var> that will be
allowed on the HTTP request-line.</p>
<p>The <directive>LimitRequestLine</directive> directive allows
<note>Under normal conditions, the value should not be changed from
the default.</note>
+
+ <note type="warning"><title>Warning</title>
+ <p> When name-based virtual hosting is used, the value for this
+ directive is taken from the default (first-listed) virtual host for the
+ <directive>NameVirtualHost</directive> the connection was mapped to.</p>
+ </note>
+
</usage>
</directivesynopsis>
locations. Since several different URLs may map to the same
filesystem location, such access controls may by circumvented.</p>
- <note><title>When to use <directive
+ <p>The enclosed directives will be applied to the request if the path component
+ of the URL meets <em>any</em> of the following criteria:
+ </p>
+ <ul>
+ <li>The specified location matches exactly the path component of the URL.
+ </li>
+ <li>The specified location, which ends in a forward slash, is a prefix
+ of the path component of the URL (treated as a context root).
+ </li>
+ <li>The specified location, with the addition of a trailing slash, is a
+ prefix of the path component of the URL (also treated as a context root).
+ </li>
+ </ul>
+ <p>
+ In the example below, where no trailing slash is used, requests to
+ /private1, /private1/ and /private1/file.txt will have the enclosed
+ directives applied, but /private1other would not.
+ </p>
+ <example>
+ <Location /private1>
+ ...
+ </example>
+ <p>
+ In the example below, where a trailing slash is used, requests to
+ /private2/ and /private2/file.txt will have the enclosed
+ directives applied, but /private2 and /private2other would not.
+ </p>
+ <example>
+ <Location /private2<em>/</em>>
+ ...
+ </example>
+
+ <note><title>When to use <directive
type="section">Location</directive></title>
<p>Use <directive type="section">Location</directive> to apply
content that lives in the filesystem, use <directive
type="section" module="core">Directory</directive> and <directive
type="section" module="core">Files</directive>. An exception is
- <code><Location /></code>, which is an easy way to
+ <code><Location /></code>, which is an easy way to
apply a configuration to the entire server.</p>
</note>
characters. Neither wildcard character matches a / in the URL-path.</p>
<p><glossary ref="regex">Regular expressions</glossary>
- can also be used, with the addition of the <code>~</code>
+ can also be used, with the addition of the <code>~</code>
character. For example:</p>
<example>
<Location /status><br />
<indent>
SetHandler server-status<br />
- Order Deny,Allow<br />
- Deny from all<br />
- Allow from .example.com<br />
+ Require host example.com<br />
</indent>
</Location>
</example>
<li><code>default | yes</code>
<p>This selects the default locking implementation, as determined by
<glossary>APR</glossary>. The default locking implementation can
- be displayed by running <program>httpd</program> with the
+ be displayed by running <program>httpd</program> with the
<code>-V</code> option.</p></li>
<li><code>none | no</code>
<p>This is a mutex variant based on a SystemV IPC semaphore.</p>
<note type="warning"><title>Warning</title>
- <p>It is possible to "leak" SysV semaphores if processes crash
+ <p>It is possible to "leak" SysV semaphores if processes crash
before the semaphore is removed.</p>
</note>
</li>
<li><code>fcntl:/path/to/mutex</code>
- <p>This is a mutex variant where a physical (lock-)file and the
+ <p>This is a mutex variant where a physical (lock-)file and the
<code>fcntl()</code> function are used as the mutex.</p>
<note type="warning"><title>Warning</title>
order.</p></li>
</ul>
- <p>Most mechanisms are only available on selected platforms, where the
+ <p>Most mechanisms are only available on selected platforms, where the
underlying platform and <glossary>APR</glossary> support it. Mechanisms
which aren't available on all platforms are <em>posixsem</em>,
- <em>sysvsem</em>, <em>sem</em>, <em>pthread</em>, <em>fcntl</em>,
+ <em>sysvsem</em>, <em>sem</em>, <em>pthread</em>, <em>fcntl</em>,
<em>flock</em>, and <em>file</em>.</p>
<p>With the file-based mechanisms <em>fcntl</em> and <em>flock</em>,
filesystem for <code>/path/to/mutex</code> and never a directory residing
on a NFS- or AFS-filesystem. The basename of the file will be the mutex
type, an optional instance string provided by the module, and unless the
- <code>OmitPID</code> keyword is specified, the process id of the httpd
+ <code>OmitPID</code> keyword is specified, the process id of the httpd
parent process will be appended to to make the file name unique, avoiding
conflicts when multiple httpd instances share a lock file directory. For
example, if the mutex name is <code>mpm-accept</code> and the lock file
directory is <code>/var/httpd/locks</code>, the lock file name for the
- httpd instance with parent process id 12345 would be
+ httpd instance with parent process id 12345 would be
<code>/var/httpd/locks/mpm-accept.12345</code>.</p>
<note type="warning"><title>Security</title>
<usage>
-<p>A single <directive>NameVirtualHost</directive> directive
-identifies a set of identical virtual hosts on which the server will
-further select from on the basis of the <em>hostname</em>
+<p>A single <directive>NameVirtualHost</directive> directive
+identifies a set of identical virtual hosts on which the server will
+further select from on the basis of the <em>hostname</em>
requested by the client. The <directive>NameVirtualHost</directive>
-directive is a required directive if you want to configure
+directive is a required directive if you want to configure
<a href="../vhosts/">name-based virtual hosts</a>.</p>
<p>This directive, and the corresponding <directive >VirtualHost</directive>,
-<em>must</em> be qualified with a port number if the server supports both HTTP
+<em>must</em> be qualified with a port number if the server supports both HTTP
and HTTPS connections.</p>
<p>Although <var>addr</var> can be a hostname, it is recommended
NameVirtualHost matches only virtualhosts that also have a literal wildcard
as their argument.</p>
-<p>In cases where a firewall or other proxy receives the requests and
+<p>In cases where a firewall or other proxy receives the requests and
forwards them on a different IP address to the server, you must specify the
IP address of the physical interface on the machine which will be
servicing the requests. </p>
-<p> In the example below, requests received on interface 192.0.2.1 and port 80
+<p> In the example below, requests received on interface 192.0.2.1 and port 80
will only select among the first two virtual hosts. Requests received on
port 80 on any other interface will only select among the third and fourth
-virtual hosts. In the common case where the interface isn't important
-to the mapping, only the "*:80" NameVirtualHost and VirtualHost directives
+virtual hosts. In the common case where the interface isn't important
+to the mapping, only the "*:80" NameVirtualHost and VirtualHost directives
are necessary.</p>
<example>
directory</description>
<syntax>Options
[+|-]<var>option</var> [[+|-]<var>option</var>] ...</syntax>
-<default>Options All</default>
+<default>Options FollowSymlinks</default>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context>
</contextlist>
<override>Options</override>
+<compatibility>The default was changed from All to FollowSymlinks in 2.3.11</compatibility>
<usage>
<p>The <directive>Options</directive> directive controls which
<dl>
<dt><code>All</code></dt>
- <dd>All options except for <code>MultiViews</code>. This is the default
- setting.</dd>
+ <dd>All options except for <code>MultiViews</code>.</dd>
<dt><code>ExecCGI</code></dt>
<dt><code>FollowSymLinks</code></dt>
<dd>
-
- The server will follow symbolic links in this directory.
+ The server will follow symbolic links in this directory. This is
+ the default setting.
<note>
<p>Even though the server follows the symlink it does <em>not</em>
change the pathname used to match against <directive type="section"
<dd>
<a href="../content-negotiation.html">Content negotiated</a>
"MultiViews" are allowed using
- <module>mod_negotiation</module>.</dd>
+ <module>mod_negotiation</module>.
+ <note><title>Note</title> <p>This option gets ignored if set
+ anywhere other than <directive module="core" type="section"
+ >Directory</directive>, as <module>mod_negotiation</module>
+ needs real resources to compare against and evaluate from.</p></note>
+ </dd>
<dt><code>SymLinksIfOwnerMatch</code></dt>
</note>
<p>The default in the absence of any other settings is
- <code>All</code>.</p>
+ <code>FollowSymlinks</code>.</p>
</usage>
</directivesynopsis>
+<directivesynopsis>
+<name>Protocol</name>
+<description>Protocol for a listening socket</description>
+<syntax>Protocol <var>protocol</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context></contextlist>
+<compatibility>Available in Apache 2.1.5 and later.
+On Windows from Apache 2.3.3 and later.</compatibility>
+
+<usage>
+ <p>This directive specifies the protocol used for a specific listening socket.
+ The protocol is used to determine which module should handle a request, and
+ to apply protocol specific optimizations with the <directive>AcceptFilter</directive>
+ directive.</p>
+
+ <p>You only need to set the protocol if you are running on non-standard ports, otherwise <code>http</code> is assumed for port 80 and <code>https</code> for port 443.</p>
+
+ <p>For example, if you are running <code>https</code> on a non-standard port, specify the protocol explicitly:</p>
+
+ <example>
+ Protocol https
+ </example>
+
+ <p>You can also specify the protocol using the <directive module="mpm_common">Listen</directive> directive.</p>
+</usage>
+<seealso><directive>AcceptFilter</directive></seealso>
+<seealso><directive module="mpm_common">Listen</directive></seealso>
+</directivesynopsis>
+
+
<directivesynopsis>
<name>RLimitCPU</name>
<description>Limits the CPU consumption of processes launched
<usage>
<p>mod_status with <code>ExtendedStatus On</code>
- displays the actual request being handled.
+ displays the actual request being handled.
For historical purposes, only 63 characters of the request
are actually stored for display purposes. This directive
controls whether the 1st 63 characters are stored (the previous
<example>
<VirtualHost *:80><br />
- ServerName server.domain.com<br />
- ServerAlias server server2.domain.com server2<br />
+ ServerName server.example.com<br />
+ ServerAlias server server2.example.com server2<br />
ServerAlias *.example.com<br />
UseCanonicalName Off<br />
# ...<br />
<p>The <directive>ServerName</directive> directive sets the
request scheme, hostname and
port that the server uses to identify itself. This is used when
- creating redirection URLs. For example, if the name of the
+ creating redirection URLs.</p>
+
+ <p>Additionally, <directive>ServerName</directive> is used (possibly
+ in conjunction with <directive>ServerAlias</directive>) to uniquely
+ identify a virtual host, when using <a
+ href="../vhosts/name-based.html">name-based virtual hosts</a>.</p>
+
+ <p>For example, if the name of the
machine hosting the web server is <code>simple.example.com</code>,
but the machine also has the DNS alias <code>www.example.com</code>
and you wish the web server to be so identified, the following
directive should be used:</p>
<example>
- ServerName www.example.com:80
+ ServerName www.example.com
</example>
<p>The <directive>ServerName</directive> directive
section specifies what hostname must appear in the request's
<code>Host:</code> header to match this virtual host.</p>
-
<p>Sometimes, the server runs behind a device that processes SSL,
such as a reverse proxy, load balancer or SSL offload
appliance. When this is the case, specify the
<code>https://</code> scheme and the port number to which the
clients connect in the <directive>ServerName</directive> directive
to make sure that the server generates the correct
- self-referential URLs.
+ self-referential URLs.
</p>
<p>See the description of the
specified port, or to the port number given in the client's request.
</p>
+ <note type="warning">
+ <p>Failure to set <directive>ServerName</directive> to a name that
+ your server can resolve to an IP address will result in a startup
+ warning. <code>httpd</code> will then use whatever hostname it can
+ determine, using the system's <code>hostname</code> command. This
+ will almost never be the hostname you actually want.</p>
+ <example>
+ httpd: Could not reliably determine the server's fully qualified domain name, using rocinante.local for ServerName
+ </example>
+ </note>
+
</usage>
<seealso><a href="../dns-caveats.html">Issues Regarding DNS and
subdirectories <code>conf/</code> and <code>logs/</code>. Relative
paths in other configuration directives (such as <directive
module="core">Include</directive> or <directive
- module="mod_so">LoadModule</directive>, for example) are taken as
+ module="mod_so">LoadModule</directive>, for example) are taken as
relative to this directory.</p>
<example><title>Example</title>
<p>After version 2.0.44, this directive also controls the
information presented by the <directive
module="core">ServerSignature</directive> directive.</p>
-
+
<note>Setting <directive>ServerTokens</directive> to less than
<code>minimal</code> is not recommended because it makes it more
difficult to debug interoperational problems. Also note that
<directivesynopsis>
<name>TraceEnable</name>
-<description>Determines the behaviour on <code>TRACE</code>
-requests</description>
+<description>Determines the behaviour on <code>TRACE</code> requests</description>
<syntax>TraceEnable <var>[on|off|extended]</var></syntax>
<default>TraceEnable on</default>
<contextlist><context>server config</context></contextlist>
allowed) error to the client.</p>
<p>Finally, for testing and diagnostic purposes only, request
- bodies may be allowed using the non-compliant <code>TraceEnable
+ bodies may be allowed using the non-compliant <code>TraceEnable
extended</code> directive. The core (as an origin server) will
restrict the request body to 64k (plus 8k for chunk headers if
<code>Transfer-Encoding: chunked</code> is used). The core will
type a shortname, and a URL which is a directory, such as
<code>http://www/splat</code>, <em>without the trailing
slash</em> then Apache httpd will redirect them to
- <code>http://www.domain.com/splat/</code>. If you have
+ <code>http://www.example.com/splat/</code>. If you have
authentication enabled, this will cause the user to have to
authenticate twice (once for <code>www</code> and once again
- for <code>www.
domain.com</code> -- see <a
+ for <code>www.
example.com</code> -- see <a
href="http://httpd.apache.org/docs/misc/FAQ.html#prompted-twice">the
FAQ on this subject for more information</a>). But if
<directive>UseCanonicalName</directive> is set <code>Off</code>, then
<li>Port provided in <code>Servername</code></li>
<li>Default port</li>
</ul>
-
+
<p>With <code>UseCanonicalPhysicalPort Off</code>, the
physical ports are removed from the ordering.</p>
</note>
projects / apache / blobdiff