<description>Configures optimizations for a Protocol's Listener Sockets</description>
<syntax>AcceptFilter <var>protocol</var> <var>accept_filter</var></syntax>
<contextlist><context>server config</context></contextlist>
-<compatibility>Available in Apache 2.1.5 and later</compatibility>
+<compatibility>Available in Apache httpd 2.1.5 and later.
+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> and Linux's more primitive
- <code>TCP_DEFER_ACCEPT</code> are currently supported.</p>
+ <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
+ 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>
- <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>nntp</code>:</p>
- <example>AcceptFilter nntp none</example>
+ <p>The default values on Windows are:</p>
+ <example>
+ AcceptFilter http data <br/>
+ AcceptFilter https data
+ </example>
+
+ <p>Window's mpm_winnt interprets the AcceptFilter to toggle the AcceptEx()
+ API, and does not support http protocol buffering. There are two values
+ which utilize the Windows AcceptEx() API and will recycle network
+ sockets between connections. <code>data</code> waits until data has
+ been transmitted as documented above, and the initial data buffer and
+ network endpoint addresses are all retrieved from the single AcceptEx()
+ invocation. <code>connect</code> will use the AcceptEx() API, also
+ retrieve the network endpoint addresses, but like <code>none</code>
+ the <code>connect</code> option does not wait for the initial data
+ transmission.</p>
+
+ <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>
</usage>
+<seealso><directive>Protocol</directive></seealso>
</directivesynopsis>
<directivesynopsis>
<context>virtual host</context><context>directory</context>
<context>.htaccess</context></contextlist>
<override>FileInfo</override>
-<compatibility>Available in Apache 2.0.30 and later</compatibility>
+<compatibility>Available in Apache httpd 2.0.30 and later</compatibility>
<usage>
a default charset of <code>iso-8859-1</code>. Any other value is assumed
to be the <var>charset</var> to be used, which should be one of the
<a href="http://www.iana.org/assignments/character-sets">IANA registered
- charset values</a> for use in MIME media types.
+ charset values</a> for use in Internet media types (MIME types).
For example:</p>
<example>
<seealso><directive module="mod_mime">AddCharset</directive></seealso>
</directivesynopsis>
-<directivesynopsis>
-<name>AddOutputFilterByType</name>
-<description>assigns an output filter to a particular MIME-type</description>
-<syntax>AddOutputFilterByType <var>filter</var>[;<var>filter</var>...]
-<var>MIME-type</var> [<var>MIME-type</var>] ...</syntax>
-<contextlist><context>server config</context>
-<context>virtual host</context><context>directory</context>
-<context>.htaccess</context></contextlist>
-<override>FileInfo</override>
-<compatibility>Available in Apache 2.0.33 and later; deprecated in Apache 2.1 and later</compatibility>
-
-<usage>
- <p>This directive activates a particular output <a
- href="../filter.html">filter</a> for a request depending on the
- response <glossary>MIME-type</glossary>. Because of certain
- problems discussed below, this directive is deprecated. The same
- functionality is available using <module>mod_filter</module>.</p>
-
- <p>The following example uses the <code>DEFLATE</code> filter, which
- is provided by <module>mod_deflate</module>. It will compress all
- output (either static or dynamic) which is labeled as
- <code>text/html</code> or <code>text/plain</code> before it is sent
- to the client.</p>
-
- <example>
- AddOutputFilterByType DEFLATE text/html text/plain
- </example>
-
- <p>If you want the content to be processed by more than one filter, their
- names have to be separated by semicolons. It's also possible to use one
- <directive>AddOutputFilterByType</directive> directive for each of
- these filters.</p>
-
- <p>The configuration below causes all script output labeled as
- <code>text/html</code> to be processed at first by the
- <code>INCLUDES</code> filter and then by the <code>DEFLATE</code>
- filter.</p>
-
- <example>
- <Location /cgi-bin/><br />
- <indent>
- Options Includes<br />
- AddOutputFilterByType INCLUDES;DEFLATE text/html<br />
- </indent>
- </Location>
- </example>
-
- <note type="warning"><title>Note</title>
- <p>Enabling filters with <directive>AddOutputFilterByType</directive>
- may fail partially or completely in some cases. For example, no
- filters are applied if the <glossary>MIME-type</glossary> could not be determined and falls
- back to the <directive module="core">DefaultType</directive> setting,
- even if the <directive module="core">DefaultType</directive> is the
- same.</p>
-
- <p>However, if you want to make sure, that the filters will be
- applied, assign the content type to a resource explicitly, for
- example with <directive module="mod_mime">AddType</directive> or
- <directive module="core">ForceType</directive>. Setting the
- content type within a (non-nph) CGI script is also safe.</p>
-
- </note>
-</usage>
-
-<seealso><directive module="mod_mime">AddOutputFilter</directive></seealso>
-<seealso><directive module="core">SetOutputFilter</directive></seealso>
-<seealso><a href="../filter.html">filters</a></seealso>
-</directivesynopsis>
-
<directivesynopsis>
<name>AllowEncodedSlashes</name>
<description>Determines whether encoded path separators in URLs are allowed to
<default>AllowEncodedSlashes Off</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
-<compatibility>Available in Apache 2.0.46 and later</compatibility>
+<compatibility>Available in Apache httpd 2.0.46 and later</compatibility>
<usage>
<p>The <directive>AllowEncodedSlashes</directive> directive allows URLs
<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>
<dt>FileInfo</dt>
<dd>
- Allow use of the directives controlling document types (<directive
- module="core">DefaultType</directive>, <directive
- module="core">ErrorDocument</directive>, <directive
- module="core">ForceType</directive>, <directive
- module="mod_negotiation">LanguagePriority</directive>,
- <directive module="core">SetHandler</directive>, <directive
- module="core">SetInputFilter</directive>, <directive
- module="core">SetOutputFilter</directive>, and
- <module>mod_mime</module> Add* and Remove*
- directives, <em>etc.</em>), document meta data (<directive
+ Allow use of the directives controlling document types
+ (<directive module="core">ErrorDocument</directive>,
+ <directive module="core">ForceType</directive>,
+ <directive module="mod_negotiation">LanguagePriority</directive>,
+ <directive module="core">SetHandler</directive>,
+ <directive module="core">SetInputFilter</directive>,
+ <directive module="core">SetOutputFilter</directive>, and
+ <module>mod_mime</module> Add* and Remove* directives),
+ document meta data (<directive
module="mod_headers">Header</directive>, <directive
module="mod_headers">RequestHeader</directive>, <directive
module="mod_setenvif">SetEnvIf</directive>, <directive
<p>In the example above all directives that are neither in the group
<code>AuthConfig</code> nor <code>Indexes</code> cause an internal
server error.</p>
+
+ <note><p>For security and performance reasons, do not set
+ <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
+ <code>.htaccess</code> file.</p>
+ </note>
</usage>
<seealso><directive module="core">AccessFileName</directive></seealso>
<compatibility>NetWare only</compatibility>
<usage>
- <p>This directive is used to control how Apache finds the
+ <p>This directive is used to control how Apache httpd finds the
interpreter used to run CGI scripts. For example, setting
<code>CGIMapExtension sys:\foo.nlm .foo</code> will
cause all CGI script files with a <code>.foo</code> extension to
<directivesynopsis>
<name>DefaultType</name>
-<description>MIME content-type that will be sent if the
-server cannot determine a type in any other way</description>
-<syntax>DefaultType <var>MIME-type|none</var></syntax>
-<default>DefaultType text/plain</default>
+<description>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.
+</description>
+<syntax>DefaultType <var>media-type|none</var></syntax>
+<default>DefaultType none</default>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context>
</contextlist>
<override>FileInfo</override>
+<compatibility>The argument <code>none</code> is available in Apache httpd 2.2.7 and later. All other choices are DISABLED for 2.3.x and later.</compatibility>
<usage>
- <p>There will be times when the server is asked to provide a
- document whose type cannot be determined by its <glossary
- ref="mime-type">MIME types</glossary> mappings.</p>
-
- <p>The server SHOULD inform the client of the content-type of the
- document. If the server is unable to determine this by normal
- means, it will set it to the configured
- <code>DefaultType</code>. For example:</p>
+ <p>This directive has been disabled. For backwards compatibility
+ of configuration files, it may be specified with the value
+ <code>none</code>, meaning no default media type. For example:</p>
- <example>
- DefaultType image/gif
- </example>
-
- <p>would be appropriate for a directory which contained many GIF
- images with filenames missing the <code>.gif</code> extension.</p>
-
- <p>In cases where it can neither be determined by the server nor
- the administrator (e.g. a proxy), it is preferable to omit the MIME
- type altogether rather than provide information that may be false.
- This can be accomplished using</p>
<example>
DefaultType None
</example>
- <p>DefaultType None is only available in httpd-2.2.7 and later.</p>
- <p>Note that unlike <directive
- module="core">ForceType</directive>, this directive only
- provides the default mime-type. All other mime-type definitions,
- including filename extensions, that might identify the media type
- will override this default.</p>
+ <p><code>DefaultType None</code> is only available in
+ httpd-2.2.7 and later.</p>
+
+ <p>Use the mime.types configuration file and the
+ <directive module="mod_mime">AddType</directive> to configure media
+ type assignments via file extensions, or the
+ <directive module="core">ForceType</directive> directive to configure
+ the media type for specific resources. Otherwise, the server will
+ send the response without a Content-Type header field and the
+ recipient may attempt to guess the media type.</p>
</usage>
</directivesynopsis>
<contextlist><context>server config</context></contextlist>
<usage>
- <p>Equivalent to passing the <code>-D</code> argument to <a
- href="../programs/httpd.html">httpd</a>.</p>
+ <p>Equivalent to passing the <code>-D</code> argument to <program
+ >httpd</program>.</p>
<p>This directive can be used to toggle the use of <directive module="core"
type="section">IfDefine</directive> sections without needing to alter
<code>-D</code> arguments in any startup scripts.</p>
<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
<note>
<p>Be careful with the <var>directory-path</var> arguments:
- They have to literally match the filesystem path which Apache uses
+ They have to literally match the filesystem path which Apache httpd uses
to access the files. Directives applied to a particular
<code><Directory></code> will not apply to files accessed from
that same directory via a different path, such as via different symbolic
the corresponding <directive type="section">Directory</directive> will
be applied.</p>
- <p><strong>Note that the default Apache access for
+ <p><strong>Note that the default access for
<code><Directory /></code> is <code>Allow from All</code>.
- This means that Apache will serve any file mapped from an URL. It is
+ This means that Apache httpd will serve any file mapped from an URL. It is
recommended that you change this with a block such
as</strong></p>
<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
memory-mapping if it needs to read the contents of a file during
delivery. By default, when the handling of a request requires
access to the data within a file -- for example, when delivering a
- server-parsed file using <module>mod_include</module> -- Apache
+ server-parsed file using <module>mod_include</module> -- Apache httpd
memory-maps the file if the OS supports it.</p>
<p>This memory-mapping sometimes yields a performance improvement.
<ul>
<li>On some multiprocessor systems, memory-mapping can reduce the
performance of the <program>httpd</program>.</li>
- <li>With an NFS-mounted <directive module="core">DocumentRoot</directive>,
- the <program>httpd</program> may crash due to a segmentation fault if a file
- is deleted or truncated while the <program>httpd</program> has it
- memory-mapped.</li>
+ <li>Deleting or truncating a file while <program>httpd</program>
+ has it memory-mapped can cause <program>httpd</program> to
+ crash with a segmentation fault.
+ </li>
</ul>
<p>For server configurations that are vulnerable to these problems,
<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
sendfile support from the kernel to transmit file contents to the client.
By default, when the handling of a request requires no access
to the data within a file -- for example, when delivering a
- static file -- Apache uses sendfile to deliver the file contents
+ static file -- Apache httpd uses sendfile to deliver the file contents
without ever reading the file if the OS supports it.</p>
<p>This sendfile mechanism avoids separate read and send operations,
<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>
</indent>
</Directory>
</example>
+ <p>Please note that the per-directory and .htaccess configuration
+ of <directive>EnableSendfile</directive> is not supported by
+ <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>
<context>directory</context><context>.htaccess</context>
</contextlist>
<override>FileInfo</override>
-<compatibility>Quoting syntax for text messages is different in Apache
-2.0</compatibility>
<usage>
- <p>In the event of a problem or error, Apache can be configured
+ <p>In the event of a problem or error, Apache httpd can be configured
to do one of four things,</p>
<ol>
<p>The first option is the default, while options 2-4 are
configured using the <directive>ErrorDocument</directive>
directive, which is followed by the HTTP response code and a URL
- or a message. Apache will sometimes offer additional information
+ or a message. Apache httpd will sometimes offer additional information
regarding the problem/error.</p>
<p>URLs can begin with a slash (/) for local web-paths (relative
</example>
<p>Additionally, the special value <code>default</code> can be used
- to specify Apache's simple hardcoded message. While not required
+ to specify Apache httpd's simple hardcoded message. While not required
under normal circumstances, <code>default</code> will restore
- Apache's simple hardcoded message for configurations that would
+ Apache httpd's simple hardcoded message for configurations that would
otherwise inherit an existing <directive>ErrorDocument</directive>.</p>
<example>
<p>Note that when you specify an <directive>ErrorDocument</directive>
that points to a remote URL (ie. anything with a method such as
- <code>http</code> in front of it), Apache will send a redirect to the
+ <code>http</code> in front of it), Apache HTTP Server will send a redirect to the
client to tell it where to find the document, even if the
document ends up being on the same server. This has several
implications, the most important being that the client will not
This is necessary to guard against security problems caused by
bad requests.</p>
- <p>Prior to version 2.0, messages were indicated by prefixing
- them with a single unmatched double quote character.</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,
+ Apache httpd will not generate custom error documents for proxied content.</p>
</usage>
<seealso><a href="../custom-error.html">documentation of
<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>
</example>
<p>If the <var>file-path</var>
- begins with a pipe (|) then it is assumed to be a command to spawn
- to handle the error log.</p>
+ begins with a pipe character "<code>|</code>" then it is assumed to be a
+ command to spawn to handle the error log.</p>
<example><title>Example</title>
ErrorLog "|/usr/local/bin/httpd_errors"
</example>
+ <p>See the notes on <a href="../logs.html#piped">piped logs</a> for
+ more information.</p>
+
<p>Using <code>syslog</code> instead of a filename enables logging
via syslogd(8) if the system supports it. The default is to use
syslog facility <code>local7</code>, but you can override this by
using the <code>syslog:<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><directive module="core">LogLevel</directive></seealso>
-<seealso><a href="../logs.html">Apache Log Files</a></seealso>
+<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
+request</description>
+<syntax>ExtendedStatus On|Off</syntax>
+<default>ExtendedStatus Off[*]</default>
+<contextlist><context>server config</context></contextlist>
+
+<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
+ <module>mod_status</module>. Note that other modules may
+ rely on this scoreboard.</p>
+
+ <p>This setting applies to the entire server, and cannot be
+ enabled or disabled on a virtualhost-by-virtualhost basis.
+ The collection of extended status information can slow down
+ the server. Also note that this setting cannot be changed
+ during a graceful restart.</p>
+
+ <note>
+ <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.
+ The default is changed by <module>mod_status</module> beginning
+ with version 2.3.6; the previous default was always Off.</p>
+ </note>
+
+</usage>
+
</directivesynopsis>
<directivesynopsis>
<name>FileETag</name>
<description>File attributes used to create the ETag
-HTTP response header</description>
+HTTP response header for static files</description>
<syntax>FileETag <var>component</var> ...</syntax>
<default>FileETag INode MTime Size</default>
<contextlist><context>server config</context><context>virtual host</context>
<p>
The <directive>FileETag</directive> directive configures the file
attributes that are used to create the <code>ETag</code> (entity
- tag) response header field when the document is based on a file.
+ tag) response header field when the document is based on a static file.
(The <code>ETag</code> value is used in cache management to save
- network bandwidth.) In Apache 1.3.22 and earlier, the
- <code>ETag</code> value was <em>always</em> formed
- from the file's inode, size, and last-modified time (mtime). The
+ network bandwidth.) The
<directive>FileETag</directive> directive allows you to choose
which of these -- if any -- should be used. The recognized keywords are:
</p>
These conditional requests will break if the <code>ETag</code> format is
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
+ of the static file with embedded SSI directives.
+ </note>
+
</usage>
</directivesynopsis>
<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>
<directivesynopsis>
<name>ForceType</name>
<description>Forces all matching files to be served with the specified
-MIME content-type</description>
-<syntax>ForceType <var>MIME-type</var>|None</syntax>
+media type in the HTTP Content-Type header field</description>
+<syntax>ForceType <var>media-type</var>|None</syntax>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>FileInfo</override>
-<compatibility>Moved to the core in Apache 2.0</compatibility>
+<compatibility>Moved to the core in Apache httpd 2.0</compatibility>
<usage>
<p>When placed into an <code>.htaccess</code> file or a
<directive type="section" module="core">Files</directive>
section, this directive forces all matching files to be served
with the content type identification given by
- <var>MIME-type</var>. For example, if you had a directory full of
+ <var>media-type</var>. For example, if you had a directory full of
GIF files, but did not want to label them all with <code>.gif</code>,
you might want to use:</p>
ForceType image/gif
</example>
- <p>Note that unlike <directive module="core">DefaultType</directive>,
- this directive overrides all mime-type associations, including
- filename extensions, that might identify the media type.</p>
+ <p>Note that this directive overrides other indirect media type
+ associations defined in mime.types or via the
+ <directive module="mod_mime">AddType</directive>.</p>
- <p>You can override any <directive>ForceType</directive> setting
+ <p>You can also override more general
+ <directive>ForceType</directive> settings
by using the value of <code>None</code>:</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>
</example>
<p>would match HTTP/1.0 requests without a <var>Host:</var> header.</p>
+
+ <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.
multiple-parameter tests. Example:</p>
<example>
- httpd -DReverseProxy ...<br />
+ httpd -DReverseProxy -DUseCache -DMemCache ...<br />
<br />
# httpd.conf<br />
<IfDefine ReverseProxy><br />
<indent>
- LoadModule rewrite_module modules/mod_rewrite.so<br />
- LoadModule proxy_module modules/libproxy.so<br />
+ LoadModule proxy_module modules/mod_proxy.so<br />
+ LoadModule proxy_http_module modules/mod_proxy_http.so<br />
+ <IfDefine UseCache><br />
+ <indent>
+ LoadModule cache_module modules/mod_cache.so<br />
+ <IfDefine MemCache><br />
+ <indent>
+ LoadModule mem_cache_module modules/mod_mem_cache.so<br />
+ </indent>
+ </IfDefine><br />
+ <IfDefine !MemCache><br />
+ <indent>
+ LoadModule cache_disk_module modules/mod_cache_disk.so<br />
+ </indent>
+ </IfDefine>
+ </indent>
+ </IfDefine>
</indent>
</IfDefine>
</example>
<p>In the former case, the directives between the start and end
markers are only processed if the module named <var>module</var>
- is included in Apache -- either compiled in or
+ is included in Apache httpd -- either compiled in or
dynamically loaded using <directive module="mod_so"
>LoadModule</directive>. The second format reverses the test,
and only processes the directives if <var>module</var> is
<name>Include</name>
<description>Includes other configuration files from within
the server configuration files</description>
-<syntax>Include <var>file-path</var>|<var>directory-path</var></syntax>
+<syntax>Include [<var>optional</var>|<var>strict</var>] <var>file-path</var>|<var>directory-path</var>|<var>wildcard</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context>
</contextlist>
-<compatibility>Wildcard matching available in 2.0.41 and later</compatibility>
+<compatibility>Wildcard matching available in 2.0.41 and later, directory
+wildcard matching available in 2.3.6 and later</compatibility>
<usage>
<p>This directive allows inclusion of other configuration files
from within the server configuration files.</p>
- <p>Shell-style (<code>fnmatch()</code>) wildcard characters can be used to
- include several files at once, in alphabetical order. In
- addition, if <directive>Include</directive> points to a directory,
- rather than a file, Apache will read all files in that directory
- and any subdirectory. But including entire directories is not
- recommended, because it is easy to accidentally leave temporary
- files in a directory that can cause <program>httpd</program> to
- fail.</p>
+ <p>Shell-style (<code>fnmatch()</code>) wildcard characters can be used
+ in the filename or directory parts of the path to include several files
+ at once, in alphabetical order. In addition, if
+ <directive>Include</directive> points to a directory, rather than a file,
+ Apache httpd will read all files in that directory and any subdirectory.
+ However, including entire directories is not recommended, because it is
+ easy to accidentally leave temporary files in a directory that can cause
+ <program>httpd</program> to fail. Instead, we encourage you to use the
+ wildcard syntax shown below, to include files that match a particular
+ pattern, such as *.conf, for example.</p>
+
+ <p>When a wildcard is specified for a <strong>file</strong> component of
+ the path, and no file matches the wildcard, the
+ <directive module="core">Include</directive>
+ directive will be <strong>silently ignored</strong>. When a wildcard is
+ specified for a <strong>directory</strong> component of the path, and
+ no directory matches the wildcard, the
+ <directive module="core">Include</directive> directive will
+ <strong>fail with an error</strong> saying the directory cannot be found.
+ </p>
+
+ <p>For further control over the behaviour of the server when no files or
+ directories match, prefix the path with the modifiers <var>optional</var>
+ or <var>strict</var>. If <var>optional</var> is specified, any wildcard
+ file or directory that does not match will be silently ignored. If
+ <var>strict</var> is specified, any wildcard file or directory that does
+ not match at least one file will cause server startup to fail.</p>
+
+ <p>When a directory or file component of the path is
+ specified exactly, and that directory or file does not exist,
+ <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>
Include conf/vhosts/*.conf
</example>
- <p>Running <code>apachectl configtest</code> will give you a list
- of the files that are being processed during the configuration
- check:</p>
+ <p>Wildcards may be included in the directory or file portion of the
+ 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>
+
+ <p>In this example, the server will fail to load if either
+ conf/vhosts/* matches no directories, or if *.conf matches no files:</p>
+
+ <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>
<example>
- root@host# apachectl configtest<br />
- Processing config file: /usr/local/apache2/conf/ssl.conf<br />
- Processing config file: /usr/local/apache2/conf/vhosts/vhost1.conf<br />
- Processing config file: /usr/local/apache2/conf/vhosts/vhost2.conf<br />
- Syntax OK
+ Include optional conf/vhosts/*/*.conf
</example>
+
</usage>
<seealso><program>apachectl</program></seealso>
length over persistent connections.</p>
<p>When a client uses a Keep-Alive connection it will be counted
- as a single "request" for the MaxRequestsPerChild directive, regardless
+ as a single "request" for the <directive module="mpm_common"
+ >MaxConnectionsPerChild</directive> directive, regardless
of how many requests are sent using the connection.</p>
</usage>
<name>KeepAliveTimeout</name>
<description>Amount of time the server will wait for subsequent
requests on a persistent connection</description>
-<syntax>KeepAliveTimeout <var>seconds</var></syntax>
+<syntax>KeepAliveTimeout <var>num</var>[ms]</syntax>
<default>KeepAliveTimeout 5</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
+<compatibility>Specifying a value in milliseconds is available in
+Apache httpd 2.3.2 and later</compatibility>
<usage>
- <p>The number of seconds Apache will wait for a subsequent
- request before closing the connection. Once a request has been
+ <p>The number of seconds Apache httpd will wait for a subsequent
+ request before closing the connection. By adding a postfix of ms the
+ timeout can be also set in milliseconds. Once a request has been
received, the timeout value specified by the
<directive module="core">Timeout</directive> directive applies.</p>
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.
+ The other values will be ignored.</p>
</usage>
</directivesynopsis>
methods</description>
<syntax><Limit <var>method</var> [<var>method</var>] ... > ...
</Limit></syntax>
-<contextlist><context>server config</context><context>virtual host</context>
-<context>directory</context><context>.htaccess</context>
+<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
-<override>All</override>
+<override>AuthConfig, Limit</override>
<usage>
<p>Access controls are normally effective for
<code>LOCK</code>, and <code>UNLOCK</code>. <strong>The method name is
case-sensitive.</strong> If <code>GET</code> is used it will also
restrict <code>HEAD</code> requests. The <code>TRACE</code> method
- cannot be limited (see <directive type="section" module="core"
+ cannot be limited (see <directive module="core"
>TraceEnable</directive>).</p>
<note type="warning">A <directive type="section"
module="core">LimitExcept</directive> section should always be
- used in preference to a <directive type="section"
- module="core">Limit</directive> section when restricting access,
- since a <directive type="section"
+ used in preference to a <directive type="section">Limit</directive>
+ section when restricting access, since a <directive type="section"
module="core">LimitExcept</directive> section provides protection
against arbitrary methods.</note>
+ <p>The <directive type="section">Limit</directive> and
+ <directive type="section" module="core">LimitExcept</directive>
+ directives may be nested. In this case, each successive level of
+ <directive type="section">Limit</directive> or <directive
+ type="section" module="core">LimitExcept</directive> directives must
+ further restrict the set of methods to which access controls apply.</p>
+
+ <note type="warning">When using
+ <directive type="section">Limit</directive> or
+ <directive type="section">LimitExcept</directive> directives with
+ the <directive module="mod_authz_core">Require</directive> directive,
+ note that the first <directive module="mod_authz_core">Require</directive>
+ to succeed authorizes the request, regardless of the presence of other
+ <directive module="mod_authz_core">Require</directive> directives.</note>
+
+ <p>For example, given the following configuration, all users will
+ be authorized for <code>POST</code> requests, and the
+ <code>Require group editors</code> directive will be ignored
+ in all cases:</p>
+
+ <example>
+ <LimitExcept GET>
+ <indent>
+ Require valid-user
+ </indent>
+ </LimitExcept><br />
+ <Limit POST>
+ <indent>
+ Require group editors
+ </indent>
+ </Limit>
+ </example>
</usage>
</directivesynopsis>
except the named ones</description>
<syntax><LimitExcept <var>method</var> [<var>method</var>] ... > ...
</LimitExcept></syntax>
-<contextlist><context>server config</context><context>virtual host</context>
-<context>directory</context><context>.htaccess</context>
+<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
-<override>All</override>
+<override>AuthConfig, Limit</override>
<usage>
<p><directive type="section">LimitExcept</directive> and
<default>LimitInternalRecursion 10</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
-<compatibility>Available in Apache 2.0.47 and later</compatibility>
+<compatibility>Available in Apache httpd 2.0.47 and later</compatibility>
<usage>
<p>An internal redirect happens, for example, when using the <directive
module="mod_actions">Action</directive> directive, which internally
- redirects the original request to a CGI script. A subrequest is Apache's
+ redirects the original request to a CGI script. A subrequest is Apache httpd's
mechanism to find out what would happen for some URI if it were requested.
For example, <module>mod_dir</module> uses subrequests to look for the
files listed in the <directive module="mod_dir">DirectoryIndex</directive>
<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>
<p>For all origin (non-proxy) requests, the URL to be matched is a
- URL-path of the form <code>/path/</code>. No scheme, hostname,
- port, or query string may be included. For proxy requests, the
+ URL-path of the form <code>/path/</code>. <em>No scheme, hostname,
+ port, or query string may be included.</em> For proxy requests, the
URL to be matched is of the form
<code>scheme://servername/path</code>, and you must include the
prefix.</p>
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> character. For example:</p>
+ can also be used, with the addition of the <code>~</code>
+ character. For example:</p>
<example>
<Location ~ "/(extra|special)/data">
or <code>/special/data</code>. The directive <directive
type="section" module="core">LocationMatch</directive> behaves
identical to the regex version of <directive
- type="section">Location</directive>.</p>
+ type="section">Location</directive>, and is preferred, for the
+ simple reason that <code>~</code> is hard to distinguish from
+ <code>-</code> in many fonts.</p>
<p>The <directive type="section">Location</directive>
functionality is especially useful when combined with the
<directive module="core">SetHandler</directive>
directive. For example, to enable status requests, but allow them
- only from browsers at <code>foo.com</code>, you might use:</p>
+ only from browsers at <code>example.com</code>, you might use:</p>
<example>
<Location /status><br />
<indent>
SetHandler server-status<br />
- Order Deny,Allow<br />
- Deny from all<br />
- Allow from .foo.com<br />
+ Require host example.com<br />
</indent>
</Location>
</example>
</usage>
<seealso><a href="../sections.html">How <Directory>, <Location>
and <Files> sections work</a> for an explanation of how these
- different sections are combined when a request is received</seealso>
+ different sections are combined when a request is received.</seealso>
+<seealso><directive module="core">LocationMatch</directive></seealso>
</directivesynopsis>
<directivesynopsis type="section">
<directivesynopsis>
<name>LogLevel</name>
<description>Controls the verbosity of the ErrorLog</description>
-<syntax>LogLevel <var>level</var></syntax>
+<syntax>LogLevel [<var>module</var>:]<var>level</var>
+ [<var>module</var>:<var>level</var>] ...
+</syntax>
<default>LogLevel warn</default>
<contextlist><context>server config</context><context>virtual host</context>
+<context>directory</context>
</contextlist>
+<compatibility>Per-module and per-directory configuration is available in
+ Apache HTTP Server 2.3.6 and later</compatibility>
<usage>
<p><directive>LogLevel</directive> adjusts the verbosity of the
<td>"Opening config file ..."</td>
</tr>
+ <tr>
+ <td><code>trace1</code> </td>
+
+ <td>Trace messages</td>
+
+ <td>"proxy: FTP: control connection complete"</td>
+ </tr>
+ <tr>
+ <td><code>trace2</code> </td>
+
+ <td>Trace messages</td>
+
+ <td>"proxy: CONNECT: sending the CONNECT request to the remote proxy"</td>
+ </tr>
+ <tr>
+ <td><code>trace3</code> </td>
+
+ <td>Trace messages</td>
+
+ <td>"openssl: Handshake: start"</td>
+ </tr>
+ <tr>
+ <td><code>trace4</code> </td>
+
+ <td>Trace messages</td>
+
+ <td>"read from buffered SSL brigade, mode 0, 17 bytes"</td>
+ </tr>
+ <tr>
+ <td><code>trace5</code> </td>
+
+ <td>Trace messages</td>
+
+ <td>"map lookup FAILED: map=rewritemap key=keyname"</td>
+ </tr>
+ <tr>
+ <td><code>trace6</code> </td>
+
+ <td>Trace messages</td>
+
+ <td>"cache lookup FAILED, forcing new map lookup"</td>
+ </tr>
+ <tr>
+ <td><code>trace7</code> </td>
+
+ <td>Trace messages, dumping large amounts of data</td>
+
+ <td>"| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |"</td>
+ </tr>
+ <tr>
+ <td><code>trace8</code> </td>
+
+ <td>Trace messages, dumping large amounts of data</td>
+
+ <td>"| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |"</td>
+ </tr>
</table>
<p>When a particular level is specified, messages from all
logged. However, this doesn't apply when logging is done
using <code>syslog</code>.</p>
</note>
+
+ <p>Specifying a level without a module name will reset the level
+ for all modules to that level. Specifying a level with a module
+ name will set the level for that module only. It is possible to
+ use the module source file name, the module identifier, or the
+ module identifier with the trailing <code>_module</code> omitted
+ as module specification. This means the following three specifications
+ are equivalent:</p>
+
+ <example>
+ LogLevel info ssl:warn<br />
+ LogLevel info mod_ssl.c:warn<br />
+ LogLevel info ssl_module:warn<br />
+ </example>
+
+ <p>It is also possible to change the level per directory:</p>
+
+ <example>
+ LogLevel info<br />
+ <Directory /usr/local/apache/htdocs/app><br />
+ LogLevel debug<br />
+ </Files>
+ </example>
+
+ <note>
+ Per directory loglevel configuration only affects messages that are
+ logged after the request has been parsed and that are associated with
+ the request. Log messages which are associated with the connection or
+ the server are not affected.
+ </note>
</usage>
</directivesynopsis>
</directivesynopsis>
<directivesynopsis>
-<name>NameVirtualHost</name>
-<description>Designates an IP address for name-virtual
-hosting</description>
-<syntax>NameVirtualHost <var>addr</var>[:<var>port</var>]</syntax>
+<name>Mutex</name>
+<description>Configures mutex mechanism and lock file directory for all
+or specified mutexes</description>
+<syntax>Mutex <var>mechanism</var> [default|<var>mutex-name</var>] ... [OmitPID]</syntax>
+<default>Mutex default</default>
<contextlist><context>server config</context></contextlist>
+<compatibility>Available in Apache HTTP Server 2.3.4 and later</compatibility>
<usage>
- <p>The <directive>NameVirtualHost</directive> directive is a
- required directive if you want to configure <a
- href="../vhosts/">name-based virtual hosts</a>.</p>
+ <p>The <directive>Mutex</directive> directive sets the mechanism,
+ and optionally the lock file location, that httpd and modules use
+ to serialize access to resources. Specify <code>default</code> as
+ the first argument to change the settings for all mutexes; specify
+ a mutex name (see table below) as the first argument to override
+ defaults only for that mutex.</p>
- <p>Although <var>addr</var> can be hostname it is recommended
- that you always use an IP address, e.g.</p>
+ <p>The <directive>Mutex</directive> directive is typically used in
+ the following exceptional situations:</p>
- <example>
- NameVirtualHost 111.22.33.44
- </example>
+ <ul>
+ <li>change the mutex mechanism when the default mechanism selected
+ by <glossary>APR</glossary> has a functional or performance
+ problem</li>
- <p>With the <directive>NameVirtualHost</directive> directive you
- specify the IP address on which the server will receive requests
- for the name-based virtual hosts. This will usually be the address
- to which your name-based virtual host names resolve. 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. If you have multiple name-based hosts on
- multiple addresses, repeat the directive for each address.</p>
+ <li>change the directory used by file-based mutexes when the
+ default directory does not support locking</li>
+ </ul>
- <note><title>Note</title>
- <p>Note, that the "main server" and any <code>_default_</code> servers
- will <strong>never</strong> be served for a request to a
- <directive>NameVirtualHost</directive> IP address (unless for some
- reason you specify <directive>NameVirtualHost</directive> but then
- don't define any <directive>VirtualHost</directive>s for that
- address).</p>
+ <note><title>Supported modules</title>
+ <p>This directive only configures mutexes which have been registered
+ with the core server using the <code>ap_mutex_register()</code> API.
+ All modules bundled with httpd support the <directive>Mutex</directive>
+ directive, but third-party modules may not. Consult the documentation
+ of the third-party module, which must indicate the mutex name(s) which
+ can be configured if this directive is supported.</p>
</note>
- <p>Optionally you can specify a port number on which the
- name-based virtual hosts should be used, e.g.</p>
+ <p>The following mutex <em>mechanisms</em> are available:</p>
+ <ul>
+ <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
+ <code>-V</code> option.</p></li>
+
+ <li><code>none | no</code>
+ <p>This effectively disables the mutex, and is only allowed for a
+ mutex if the module indicates that it is a valid choice. Consult the
+ module documentation for more information.</p></li>
+
+ <li><code>posixsem</code>
+ <p>This is a mutex variant based on a Posix semaphore.</p>
+
+ <note type="warning"><title>Warning</title>
+ <p>The semaphore ownership is not recovered if a thread in the process
+ holding the mutex segfaults, resulting in a hang of the web server.</p>
+ </note>
+ </li>
+
+ <li><code>sysvsem</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
+ before the semaphore is removed.</p>
+ </note>
+
+ <note type="warning"><title>Security</title>
+ <p>The semaphore API allows for a denial of service attack by any
+ CGIs running under the same uid as the webserver (<em>i.e.</em>,
+ all CGIs, unless you use something like <program>suexec</program>
+ or <code>cgiwrapper</code>).</p>
+ </note>
+ </li>
+
+ <li><code>sem</code>
+ <p>This selects the "best" available semaphore implementation, choosing
+ between Posix and SystemV IPC semaphores, in that order.</p></li>
+
+ <li><code>pthread</code>
+ <p>This is a mutex variant based on cross-process Posix thread
+ mutexes.</p>
+
+ <note type="warning"><title>Warning</title>
+ <p>On most systems, if a child process terminates abnormally while
+ holding a mutex that uses this implementation, the server will deadlock
+ and stop responding to requests. When this occurs, the server will
+ require a manual restart to recover.</p>
+ <p>Solaris is a notable exception as it provides a mechanism which
+ usually allows the mutex to be recovered after a child process
+ terminates abnormally while holding a mutex.</p>
+ <p>If your system implements the
+ <code>pthread_mutexattr_setrobust_np()</code> function, you may be able
+ to use the <code>pthread</code> option safely.</p>
+ </note>
+ </li>
+
+ <li><code>fcntl:/path/to/mutex</code>
+ <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>
+ <p>When multiple mutexes based on this mechanism are used within
+ multi-threaded, multi-process environments, deadlock errors (EDEADLK)
+ can be reported for valid mutex operations if <code>fcntl()</code>
+ is not thread-aware, such as on Solaris.</p>
+ </note>
+ </li>
+
+ <li><code>flock:/path/to/mutex</code>
+ <p>This is similar to the <code>fcntl:/path/to/mutex</code> method
+ with the exception that the <code>flock()</code> function is used to
+ provide file locking.</p></li>
+
+ <li><code>file:/path/to/mutex</code>
+ <p>This selects the "best" available file locking implementation,
+ choosing between <code>fcntl</code> and <code>flock</code>, in that
+ order.</p></li>
+ </ul>
+
+ <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>flock</em>, and <em>file</em>.</p>
+
+ <p>With the file-based mechanisms <em>fcntl</em> and <em>flock</em>,
+ the path, if provided, is a directory where the lock file will be created.
+ The default directory is httpd's run-time file directory relative to
+ <directive module="core">ServerRoot</directive>. Always use a local disk
+ 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
+ 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
+ <code>/var/httpd/locks/mpm-accept.12345</code>.</p>
+
+ <note type="warning"><title>Security</title>
+ <p>It is best to <em>avoid</em> putting mutex files in a world-writable
+ directory such as <code>/var/tmp</code> because someone could create
+ a denial of service attack and prevent the server from starting by
+ creating a lockfile with the same name as the one the server will try
+ to create.</p>
+ </note>
+
+ <p>The following table documents the names of mutexes used by httpd
+ and bundled modules.</p>
+
+ <table border="1" style="zebra">
+ <tr>
+ <th>Mutex name</th>
+ <th>Module(s)</th>
+ <th>Protected resource</th>
+ </tr>
+ <tr>
+ <td><code>mpm-accept</code></td>
+ <td><module>prefork</module> and <module>worker</module> MPMs</td>
+ <td>incoming connections, to avoid the thundering herd problem;
+ for more information, refer to the
+ <a href="../misc/perf-tuning.html">performance tuning</a>
+ documentation</td>
+ </tr>
+ <tr>
+ <td><code>authdigest-client</code></td>
+ <td><module>mod_auth_digest</module></td>
+ <td>client list in shared memory</td>
+ </tr>
+ <tr>
+ <td><code>authdigest-opaque</code></td>
+ <td><module>mod_auth_digest</module></td>
+ <td>counter in shared memory</td>
+ </tr>
+ <tr>
+ <td><code>ldap-cache</code></td>
+ <td><module>mod_ldap</module></td>
+ <td>LDAP result cache</td>
+ </tr>
+ <tr>
+ <td><code>rewrite-map</code></td>
+ <td><module>mod_rewrite</module></td>
+ <td>communication with external mapping programs, to avoid
+ intermixed I/O from multiple requests</td>
+ </tr>
+ <tr>
+ <td><code>ssl-cache</code></td>
+ <td><module>mod_ssl</module></td>
+ <td>SSL session cache</td>
+ </tr>
+ <tr>
+ <td><code>ssl-stapling</code></td>
+ <td><module>mod_ssl</module></td>
+ <td>OCSP stapling response cache</td>
+ </tr>
+ <tr>
+ <td><code>watchdog-callback</code></td>
+ <td><module>mod_watchdog</module></td>
+ <td>callback function of a particular client module</td>
+ </tr>
+ </table>
+
+ <p>The <code>OmitPID</code> keyword suppresses the addition of the httpd
+ parent process id from the lock file name.</p>
+
+ <p>In the following example, the mutex mechanism for the MPM accept
+ mutex will be changed from the compiled-in default to <code>fcntl</code>,
+ with the associated lock file created in directory
+ <code>/var/httpd/locks</code>. The mutex mechanism for all other mutexes
+ will be changed from the compiled-in default to <code>sysvsem</code>.</p>
<example>
- NameVirtualHost 111.22.33.44:8080
+ Mutex default sysvsem<br />
+ Mutex mpm-accept fcntl:/var/httpd/locks
+ </example>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>NameVirtualHost</name>
+<description>Designates an IP address for name-virtual
+hosting</description>
+<syntax>NameVirtualHost <var>addr</var>[:<var>port</var>]</syntax>
+<contextlist><context>server config</context></contextlist>
+
+<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>
+requested by the client. The <directive>NameVirtualHost</directive>
+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
+and HTTPS connections.</p>
+
+<p>Although <var>addr</var> can be a hostname, it is recommended
+that you always use an IP address or a wildcard. A wildcard
+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
+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
+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
+are necessary.</p>
+
+ <example>
+ NameVirtualHost 192.0.2.1:80<br />
+ NameVirtualHost *:80<br /><br />
+
+ <VirtualHost 192.0.2.1:80><br />
+ ServerName namebased-a.example.com<br />
+ </VirtualHost><br />
+ <br />
+ <VirtualHost 192.0.2.1:80><br />
+ Servername namebased-b.example.com<br />
+ </VirtualHost><br />
+ <br />
+ <VirtualHost *:80><br />
+ ServerName namebased-c.example.com <br />
+ </VirtualHost><br />
+ <br />
+ <VirtualHost *:80><br />
+ ServerName namebased-d.example.com <br />
+ </VirtualHost><br />
+ <br />
+
</example>
+ <p>If no matching virtual host is found, then the first listed
+ virtual host that matches the IP address and port will be used.</p>
+
+
<p>IPv6 addresses must be enclosed in square brackets, as shown
in the following example:</p>
NameVirtualHost [2001:db8::a00:20ff:fea7:ccea]:8080
</example>
- <p>To receive requests on all interfaces, you can use an argument of
- <code>*</code></p>
-
- <example>
- NameVirtualHost *
- </example>
-
<note><title>Argument to <directive type="section">VirtualHost</directive>
directive</title>
<p>Note that the argument to the <directive
>NameVirtualHost</directive> directive.</p>
<example>
- NameVirtualHost 1.2.3.4<br />
- <VirtualHost 1.2.3.4><br />
+ NameVirtualHost 192.0.2.2:80<br />
+ <VirtualHost 192.0.2.2:80><br />
# ...<br />
</VirtualHost><br />
</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
-by Apache children</description>
+by Apache httpd children</description>
<syntax>RLimitCPU <var>seconds</var>|max [<var>seconds</var>|max]</syntax>
<default>Unset; uses operating system defaults</default>
<contextlist><context>server config</context><context>virtual host</context>
the server is running as <code>root</code>, or in the initial startup
phase.</p>
- <p>This applies to processes forked off from Apache children
- servicing requests, not the Apache children themselves. This
+ <p>This applies to processes forked off from Apache httpd children
+ servicing requests, not the Apache httpd children themselves. This
includes CGI scripts and SSI exec commands, but not any
- processes forked off from the Apache parent such as piped
+ processes forked off from the Apache httpd parent such as piped
logs.</p>
<p>CPU resource limits are expressed in seconds per
<directivesynopsis>
<name>RLimitMEM</name>
<description>Limits the memory consumption of processes launched
-by Apache children</description>
+by Apache httpd children</description>
<syntax>RLimitMEM <var>bytes</var>|max [<var>bytes</var>|max]</syntax>
<default>Unset; uses operating system defaults</default>
<contextlist><context>server config</context><context>virtual host</context>
the server is running as <code>root</code>, or in the initial startup
phase.</p>
- <p>This applies to processes forked off from Apache children
- servicing requests, not the Apache children themselves. This
+ <p>This applies to processes forked off from Apache httpd children
+ servicing requests, not the Apache httpd children themselves. This
includes CGI scripts and SSI exec commands, but not any
- processes forked off from the Apache parent such as piped
+ processes forked off from the Apache httpd parent such as piped
logs.</p>
<p>Memory resource limits are expressed in bytes per
<directivesynopsis>
<name>RLimitNPROC</name>
<description>Limits the number of processes that can be launched by
-processes launched by Apache children</description>
+processes launched by Apache httpd children</description>
<syntax>RLimitNPROC <var>number</var>|max [<var>number</var>|max]</syntax>
<default>Unset; uses operating system defaults</default>
<contextlist><context>server config</context><context>virtual host</context>
the server is running as <code>root</code>, or in the initial startup
phase.</p>
- <p>This applies to processes forked off from Apache children
- servicing requests, not the Apache children themselves. This
+ <p>This applies to processes forked off from Apache httpd children
+ servicing requests, not the Apache httpd children themselves. This
includes CGI scripts and SSI exec commands, but not any
- processes forked off from the Apache parent such as piped
+ processes forked off from the Apache httpd parent such as piped
logs.</p>
<p>Process limits control the number of processes per user.</p>
<context>directory</context><context>.htaccess</context></contextlist>
<override>FileInfo</override>
<compatibility>Win32 only;
-option <code>Registry-Strict</code> is available in Apache 2.0 and
+option <code>Registry-Strict</code> is available in Apache HTTP Server 2.0 and
later</compatibility>
<usage>
- <p>This directive is used to control how Apache finds the
+ <p>This directive is used to control how Apache httpd finds the
interpreter used to run CGI scripts. The default setting is
- <code>Script</code>. This causes Apache to use the interpreter pointed to
+ <code>Script</code>. This causes Apache httpd to use the interpreter pointed to
by the shebang line (first line, starting with <code>#!</code>) in the
script. On Win32 systems this line usually looks like:</p>
search key. The command defined by the registry subkey
<code>Shell\ExecCGI\Command</code> or, if it does not exist, by the subkey
<code>Shell\Open\Command</code> is used to open the script file. If the
- registry keys cannot be found, Apache falls back to the behavior of the
+ registry keys cannot be found, Apache httpd falls back to the behavior of the
<code>Script</code> option.</p>
<note type="warning"><title>Security</title>
<p>Be careful when using <code>ScriptInterpreterSource
Registry</code> with <directive
module="mod_alias">ScriptAlias</directive>'ed directories, because
- Apache will try to execute <strong>every</strong> file within this
+ Apache httpd will try to execute <strong>every</strong> file within this
directory. The <code>Registry</code> setting may cause undesired
program calls on files which are typically not executed. For
example, the default open command on <code>.htm</code> files on
so.</p>
</note>
- <p>The option <code>Registry-Strict</code> which is new in Apache
+ <p>The option <code>Registry-Strict</code> which is new in Apache HTTP Server
2.0 does the same thing as <code>Registry</code> but uses only the
subkey <code>Shell\ExecCGI\Command</code>. The
<code>ExecCGI</code> key is not a common one. It must be
</usage>
</directivesynopsis>
+<directivesynopsis>
+<name>SeeRequestTail</name>
+<description>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.</description>
+<syntax>SeeRequestTail On|Off</syntax>
+<default>SeeRequestTail Off</default>
+<contextlist><context>server config</context></contextlist>
+<compatibility>Available in Apache httpd 2.2.7 and later.</compatibility>
+
+<usage>
+ <p>mod_status with <code>ExtendedStatus On</code>
+ 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
+ behavior and the default) or if the last 63 characters are. This
+ is only applicable, of course, if the length of the request is
+ 64 characters or greater.</p>
+
+ <p>If Apache httpd is handling <code
+ >GET /disk1/storage/apache/htdocs/images/imagestore1/food/apples.jpg HTTP/1.1</code
+ > mod_status displays as follows:
+ </p>
+
+ <table border="1">
+ <tr>
+ <th>Off (default)</th>
+ <td>GET /disk1/storage/apache/htdocs/images/imagestore1/food/apples</td>
+ </tr>
+ <tr>
+ <th>On</th>
+ <td>orage/apache/htdocs/images/imagestore1/food/apples.jpg HTTP/1.1</td>
+ </tr>
+ </table>
+
+</usage>
+</directivesynopsis>
+
<directivesynopsis>
<name>ServerAdmin</name>
<description>Email address that the server includes in error
<usage>
<p>The <directive>ServerAlias</directive> directive sets the
alternate names for a host, for use with <a
- href="../vhosts/name-based.html">name-based virtual hosts</a>. The
+ href="../vhosts/name-based.html">name-based virtual hosts</a>. The
<directive>ServerAlias</directive> may include wildcards, if appropriate.</p>
<example>
- <VirtualHost *><br />
- ServerName server.domain.com<br />
- ServerAlias server server2.domain.com server2<br />
+ <VirtualHost *:80><br />
+ ServerName server.example.com<br />
+ ServerAlias server server2.example.com server2<br />
+ ServerAlias *.example.com<br />
+ UseCanonicalName Off<br />
# ...<br />
</VirtualHost>
</example>
</usage>
-<seealso><a href="../vhosts/">Apache Virtual Host documentation</a></seealso>
+<seealso><directive module="core">UseCanonicalName</directive></seealso>
+<seealso><a href="../vhosts/">Apache HTTP Server Virtual Host documentation</a></seealso>
</directivesynopsis>
<directivesynopsis>
<syntax>ServerName [<var>scheme</var>://]<var>fully-qualified-domain-name</var>[:<var>port</var>]</syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
-<compatibility>In version 2.0, this
- directive supersedes the functionality of the <directive>Port</directive>
- directive from version 1.3.</compatibility>
<usage>
<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
+ may appear anywhere within the definition of a server. However,
+ each appearance overrides the previous appearance (within that
+ server).</p>
+
<p>If no <directive>ServerName</directive> is specified, then the
server attempts to deduce the hostname by performing a reverse
lookup on the IP address. If no port is specified in the
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
<directive module="core">UseCanonicalName</directive> and
- <directive module="core">UseCanonicalPhysicalPort</directive>directives for
+ <directive module="core">UseCanonicalPhysicalPort</directive> directives for
settings which determine whether self-referential URLs (e.g., by the
<module>mod_dir</module> module) will refer to 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
- Apache</a></seealso>
-<seealso><a href="../vhosts/">Apache virtual host
+ Apache HTTP Server</a></seealso>
+<seealso><a href="../vhosts/">Apache HTTP Server virtual host
documentation</a></seealso>
<seealso><directive module="core">UseCanonicalName</directive></seealso>
<seealso><directive module="core">UseCanonicalPhysicalPort</directive></seealso>
URL pathname for a host, for use with <a
href="../vhosts/">name-based virtual hosts</a>.</p>
</usage>
-<seealso><a href="../vhosts/">Apache Virtual Host documentation</a></seealso>
+<seealso><a href="../vhosts/">Apache HTTP Server Virtual Host documentation</a></seealso>
</directivesynopsis>
<directivesynopsis>
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>
information about compiled-in modules.</p>
<dl>
+ <dt><code>ServerTokens Full</code> (or not specified)</dt>
+
+ <dd>Server sends (<em>e.g.</em>): <code>Server: Apache/2.4.1
+ (Unix) PHP/4.2.2 MyMod/1.2</code></dd>
+
<dt><code>ServerTokens Prod[uctOnly]</code></dt>
<dd>Server sends (<em>e.g.</em>): <code>Server:
<dt><code>ServerTokens Minor</code></dt>
<dd>Server sends (<em>e.g.</em>): <code>Server:
- Apache/2.0</code></dd>
+ Apache/2.4</code></dd>
<dt><code>ServerTokens Min[imal]</code></dt>
<dd>Server sends (<em>e.g.</em>): <code>Server:
- Apache/2.0.41</code></dd>
+ Apache/2.4.1</code></dd>
<dt><code>ServerTokens OS</code></dt>
- <dd>Server sends (<em>e.g.</em>): <code>Server: Apache/2.0.41
+ <dd>Server sends (<em>e.g.</em>): <code>Server: Apache/2.4.1
(Unix)</code></dd>
- <dt><code>ServerTokens Full</code> (or not specified)</dt>
-
- <dd>Server sends (<em>e.g.</em>): <code>Server: Apache/2.0.41
- (Unix) PHP/4.2.2 MyMod/1.2</code></dd>
</dl>
<p>This setting applies to the entire server, and cannot be
<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
+ disabling the Server: header does nothing at all to make your
+ server more secure; the idea of "security through obscurity"
+ is a myth and leads to a false sense of safety.</note>
+
</usage>
<seealso><directive module="core">ServerSignature</directive></seealso>
</directivesynopsis>
<context>directory</context><context>.htaccess</context>
</contextlist>
<override>FileInfo</override>
-<compatibility>Moved into the core in Apache 2.0</compatibility>
+<compatibility>Moved into the core in Apache httpd 2.0</compatibility>
<usage>
<p>When placed into an <code>.htaccess</code> file or a
<usage>
<p>The <directive>TimeOut</directive> directive defines the length
- of time Apache will wait for I/O in various circumstances:</p>
+ of time Apache httpd will wait for I/O in various circumstances:</p>
<ol>
<li>When reading data from the client, the length of time to
<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>
-<compatibility>Available in Apache 1.3.34, 2.0.55 and later</compatibility>
+<compatibility>Available in Apache HTTP Server 1.3.34, 2.0.55 and later</compatibility>
<usage>
<p>This directive overrides the behavior of <code>TRACE</code> for both
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
</usage>
</directivesynopsis>
+<directivesynopsis>
+<name>UnDefine</name>
+<description>Undefine the existence of a variable</description>
+<syntax>UnDefine <var>parameter-name</var></syntax>
+<contextlist><context>server config</context></contextlist>
+
+<usage>
+ <p>Undoes the effect of a <directive module="core">Define</directive> or
+ of passing a <code>-D</code> argument to <program>httpd</program>.</p>
+ <p>This directive can be used to toggle the use of <directive module="core"
+ type="section">IfDefine</directive> sections without needing to alter
+ <code>-D</code> arguments in any startup scripts.</p>
+</usage>
+</directivesynopsis>
+
<directivesynopsis>
<name>UseCanonicalName</name>
<description>Configures how the server determines its own name and
<context>directory</context></contextlist>
<usage>
- <p>In many situations Apache must construct a <em>self-referential</em>
+ <p>In many situations Apache httpd must construct a <em>self-referential</em>
URL -- that is, a URL that refers back to the same server. With
- <code>UseCanonicalName On</code> Apache will use the hostname and port
+ <code>UseCanonicalName On</code> Apache httpd will use the hostname and port
specified in the <directive module="core">ServerName</directive>
directive to construct the canonical name for the server. This name
is used in all self-referential URLs, and for the values of
<code>SERVER_NAME</code> and <code>SERVER_PORT</code> in CGIs.</p>
- <p>With <code>UseCanonicalName Off</code> Apache will form
+ <p>With <code>UseCanonicalName Off</code> Apache httpd will form
self-referential URLs using the hostname and port supplied by
the client if any are supplied (otherwise it will use the
canonical name, as defined above). These values are the same
that are used to implement <a
- href="../vhosts/name-based.html">name based virtual hosts</a>,
+ href="../vhosts/name-based.html">name-based virtual hosts</a>,
and are available with the same clients. The CGI variables
<code>SERVER_NAME</code> and <code>SERVER_PORT</code> will be
constructed from the client supplied values as well.</p>
names such as <code>www</code>. You'll notice that if the users
type a shortname, and a URL which is a directory, such as
<code>http://www/splat</code>, <em>without the trailing
- slash</em> then Apache will redirect them to
- <code>http://www.domain.com/splat/</code>. If you have
+ slash</em> then Apache httpd will redirect them to
+ <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
- Apache will redirect to <code>http://www/splat/</code>.</p>
+ Apache httpd will redirect to <code>http://www/splat/</code>.</p>
<p>There is a third option, <code>UseCanonicalName DNS</code>,
which is intended for use with mass IP-based virtual hosting to
support ancient clients that do not provide a
- <code>Host:</code> header. With this option Apache does a
+ <code>Host:</code> header. With this option Apache httpd does a
reverse DNS lookup on the server IP address that the client
connected to in order to work out self-referential URLs.</p>
<context>directory</context></contextlist>
<usage>
- <p>In many situations Apache must construct a <em>self-referential</em>
+ <p>In many situations Apache httpd must construct a <em>self-referential</em>
URL -- that is, a URL that refers back to the same server. With
- <code>UseCanonicalPhysicalPort On</code> Apache will, when
+ <code>UseCanonicalPhysicalPort On</code> Apache httpd will, when
constructing the canonical port for the server to honor
the <directive module="core">UseCanonicalName</directive> directive,
provide the actual physical port number being used by this request
as a potential port. With <code>UseCanonicalPhysicalPort Off</code>
- Apache will not ever use the actual physical port number, instead
+ Apache httpd will not ever use the actual physical port number, instead
relying on all configured information to construct a valid port number.</p>
<note><title>Note</title>
<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>
<example><title>Example</title>
<VirtualHost 10.1.2.3><br />
<indent>
- ServerAdmin webmaster@host.foo.com<br />
- DocumentRoot /www/docs/host.foo.com<br />
- ServerName host.foo.com<br />
- ErrorLog logs/host.foo.com-error_log<br />
- TransferLog logs/host.foo.com-access_log<br />
+ ServerAdmin webmaster@host.example.com<br />
+ DocumentRoot /www/docs/host.example.com<br />
+ ServerName host.example.com<br />
+ ErrorLog logs/host.example.com-error_log<br />
+ TransferLog logs/host.example.com-access_log<br />
</indent>
</VirtualHost>
</example>
<note><title>Note</title>
<p>The use of <directive type="section">VirtualHost</directive> does
- <strong>not</strong> affect what addresses Apache listens on. You
- may need to ensure that Apache is listening on the correct addresses
+ <strong>not</strong> affect what addresses Apache httpd listens on. You
+ may need to ensure that Apache httpd is listening on the correct addresses
using <directive module="mpm_common">Listen</directive>.</p>
</note>
not explicitly listed in another virtual host. In the absence
of any <code>_default_</code> virtual host the "main" server config,
consisting of all those definitions outside any VirtualHost
- section, is used when no IP-match occurs. (But note that any IP
- address that matches a <directive
- module="core">NameVirtualHost</directive> directive will use neither
- the "main" server config nor the <code>_default_</code> virtual host.
- See the <a href="../vhosts/name-based.html">name-based virtual hosting</a>
- documentation for further details.)</p>
+ section, is used when no IP-match occurs.</p>
<p>You can specify a <code>:port</code> to change the port that is
matched. If unspecified then it defaults to the same port as the
<directive module="core">ServerName</directive> from the "main"
server configuration will be inherited.</p>
+ <p>If no matching virtual host is found, then the first listed
+ virtual host that matches the IP address will be used. As a
+ consequence, the first listed virtual host is the default virtual
+ host.</p>
+
<note type="warning"><title>Security</title>
<p>See the <a href="../misc/security_tips.html">security tips</a>
document for details on why your security could be compromised if the
than the user that starts the server.</p>
</note>
</usage>
-<seealso><a href="../vhosts/">Apache Virtual Host documentation</a></seealso>
+<seealso><a href="../vhosts/">Apache HTTP Server Virtual Host documentation</a></seealso>
<seealso><a href="../dns-caveats.html">Issues Regarding DNS and
- Apache</a></seealso>
+ Apache HTTP Server</a></seealso>
<seealso><a href="../bind.html">Setting
- which addresses and ports Apache uses</a></seealso>
+ which addresses and ports Apache HTTP Server uses</a></seealso>
<seealso><a href="../sections.html">How <Directory>, <Location>
and <Files> sections work</a> for an explanation of how these
different sections are combined when a request is received</seealso>
projects / apache / blobdiff