<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 2.1.5 and later.
+On Windows from Apache 2.3.3 and later.</compatibility>
<usage>
<p>This directive enables operating system specific optimizations for a
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>
+ 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 values on FreeBSD are:</p>
<example>
</example>
<p>The <code>httpready</code> accept filter buffers entire HTTP requests at
- the kernel level. Once an entire request is recieved, the kernel then
+ 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
<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 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>
</directivesynopsis>
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>
<directivesynopsis>
<name>AddOutputFilterByType</name>
-<description>assigns an output filter to a particular MIME-type</description>
+<description>assigns an output filter to a particular media-type</description>
<syntax>AddOutputFilterByType <var>filter</var>[;<var>filter</var>...]
-<var>MIME-type</var> [<var>MIME-type</var>] ...</syntax>
+<var>media-type</var> [<var>media-type</var>] ...</syntax>
<contextlist><context>server config</context>
<context>virtual host</context><context>directory</context>
<context>.htaccess</context></contextlist>
<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
+ response <glossary>media-type</glossary>. Because of certain
problems discussed below, this directive is deprecated. The same
functionality is available using <module>mod_filter</module>.</p>
<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
+ filters are applied if the <glossary>media-type</glossary> could not
+ be determined. 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>
- <p>The by-type output filters are never applied on proxy requests.</p>
</note>
</usage>
module="mod_authn_dbm">AuthDBMGroupFile</directive>,
<directive module="mod_authn_dbm">AuthDBMUserFile</directive>,
<directive module="mod_authz_groupfile">AuthGroupFile</directive>,
- <directive module="core">AuthName</directive>,
- <directive module="core">AuthType</directive>, <directive
+ <directive module="mod_authn_core">AuthName</directive>,
+ <directive module="mod_authn_core">AuthType</directive>, <directive
module="mod_authn_file">AuthUserFile</directive>, <directive
- module="core">Require</directive>, <em>etc.</em>).</dd>
+ module="mod_authz_core">Require</directive>, <em>etc.</em>).</dd>
<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>
<usage>
<p>This directive enables the generation of
<code>Content-MD5</code> headers as defined in RFC1864
- respectively RFC2068.</p>
+ respectively RFC2616.</p>
<p>MD5 is an algorithm for computing a "message digest"
(sometimes called "fingerprint") of arbitrary-length data, with
<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</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 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 must inform the client of the content-type of the
- document, so in the event of an unknown type it uses the
- <code>DefaultType</code>. For example:</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
+ DefaultType None
</example>
- <p>would be appropriate for a directory which contained many GIF
- images with filenames missing the <code>.gif</code> extension.</p>
+ <p><code>DefaultType None</code> 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>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>
+
+<directivesynopsis>
+<name>Define</name>
+<description>Define the existence of a variable</description>
+<syntax>Define <var>parameter-name</var></syntax>
+<contextlist><context>server config</context></contextlist>
+
+<usage>
+ <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>
</usage>
</directivesynopsis>
<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,
</indent>
</Directory>
</example>
+ <p>Please note that the per-directory and .htaccess configuration
+ of <directive>EnableSendfile</directive> is not supported by
+ <module>mod_disk_cache</module>.
+ Only global definition of <directive>EnableSendfile</directive>
+ is taken into account by the module.
+ </p>
</usage>
</directivesynopsis>
will be immediately halted and the internal error message returned.
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 will not generate custom error documents for proxied content.</p>
</usage>
<seealso><a href="../custom-error.html">documentation of
the setting for that subdirectory (which will be inherited by
any sub-subdirectories that don't override it) will be equivalent to
<code>FileETag MTime Size</code>.</p>
+ <note type="warning"><title>Warning</title>
+ Do not change the default for directories or locations that have WebDAV
+ enabled and use <module>mod_dav_fs</module> as a storage provider.
+ <module>mod_dav_fs</module> uses <code>INode MTime Size</code>
+ as a fixed format for <code>ETag</code> comparisons on conditional requests.
+ These conditional requests will break if the <code>ETag</code> format is
+ changed via <directive>FileETag</directive>.
+ </note>
</usage>
</directivesynopsis>
<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>
<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>
</usage>
</directivesynopsis>
+<directivesynopsis type="section">
+<name>If</name>
+<description>Contains directives that apply only if a condition is
+satisfied by a request at runtime</description>
+<syntax><If <var>expression</var>> ... </If></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+<context>directory</context><context>.htaccess</context>
+</contextlist>
+<override>All</override>
+
+<usage>
+ <p>The <directive type="section">If</directive> directive
+ evaluates an expression at runtime, and applies the enclosed
+ directives if and only if the expression evaluates to true.
+ For example:</p>
+
+ <example>
+ <If "$req{Host} = ''">
+ </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>
+</usage>
+
+<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.
+ <directive type="section">If</directive> has the same precedence
+ and usage as <directive type="section">Files</directive></seealso>
+</directivesynopsis>
+
<directivesynopsis type="section">
<name>IfDefine</name>
<description>Encloses directives that will be processed only
the test, and only processes the directives if
<var>parameter-name</var> is <strong>not</strong> defined.</p>
- <p>The <var>parameter-name</var> argument is a define as given on
- the <program>httpd</program> command line via <code>-D<var>parameter-</var>
- </code>, at the time the server was started.</p>
+ <p>The <var>parameter-name</var> argument is a define as given on the
+ <program>httpd</program> command line via <code>-D<var>parameter</var>
+ </code> at the time the server was started or by the <directive
+ module="core">Define</directive> directive.</p>
<p><directive type="section">IfDefine</directive> sections are
nest-able, which can be used to implement simple
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 disk_cache_module modules/mod_disk_cache.so<br />
+ </indent>
+ </IfDefine>
+ </indent>
+ </IfDefine>
</indent>
</IfDefine>
</example>
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
+ 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.</p>
+ 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>The file path specified may be an absolute path, or may be relative
to the <directive module="core">ServerRoot</directive> directory.</p>
Include conf/ssl.conf<br />
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>
-
- <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
- </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"
+ >MaxRequestsPerChild</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 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
+ 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.</p>
+ 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
</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>
<p>The URL may use wildcards. In a wild-card string, <code>?</code> matches
any single character, and <code>*</code> matches any sequences of
- characters. Neither wilcard character matches a / in the URL-path.</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 />
SetHandler server-status<br />
Order Deny,Allow<br />
Deny from all<br />
- Allow from .foo.com<br />
+ Allow from .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>
<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 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>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>Optionally you can specify a port number on which the
- name-based virtual hosts should be used, e.g.</p>
+ <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>
- <p>IPv6 addresses must be enclosed in square brackets, as shown
- in the following example:</p>
+<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>
- 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>
+ <p>IPv6 addresses must be enclosed in square brackets, as shown
+ in the following example:</p>
<example>
- NameVirtualHost *
+ NameVirtualHost [2001:db8::a00:20ff:fea7:ccea]:8080
</example>
<note><title>Argument to <directive type="section">VirtualHost</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>
<p>Note also, that this option <strong>gets ignored</strong> if set
inside a <directive type="section" module="core">Location</directive>
section.</p>
+ <p>Omitting this option should not be considered a security restriction,
+ since symlink testing is subject to race conditions that make it
+ circumventable.</p>
</note></dd>
<dt><code>Includes</code></dt>
target file or directory is owned by the same user id as the
link.
- <note><title>Note</title> This option gets ignored if
+ <note><title>Note</title> <p>This option gets ignored if
set inside a <directive module="core"
- type="section">Location</directive> section.</note>
+ type="section">Location</directive> section.</p>
+ <p>This option should not be considered a security restriction,
+ since symlink testing is subject to race conditions that make it
+ circumventable.</p></note>
</dd>
</dl>
<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 />
+ <VirtualHost *:80><br />
ServerName server.domain.com<br />
ServerAlias server server2.domain.com server2<br />
+ ServerAlias *.example.com<br />
# ...<br />
</VirtualHost>
</example>
<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.
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>
<contextlist><context>server config</context><context>virtual host</context></contextlist>
<usage>
- <p>The <directive>TimeOut</directive> directive currently defines
- the amount of time Apache will wait for three things:</p>
+ <p>The <directive>TimeOut</directive> directive defines the length
+ of time Apache will wait for I/O in various circumstances:</p>
<ol>
- <li>The total amount of time it takes to receive a GET
- request.</li>
+ <li>When reading data from the client, the length of time to
+ wait for a TCP packet to arrive if the read buffer is
+ empty.</li>
+
+ <li>When writing data to the client, the length of time to wait
+ for an acknowledgement of a packet if the send buffer is
+ full.</li>
- <li>The amount of time between receipt of TCP packets on a
- POST or PUT request.</li>
+ <li>In <module>mod_cgi</module>, the length of time to wait for
+ output from a CGI script.</li>
- <li>The amount of time between ACKs on transmissions of TCP
- packets in responses.</li>
+ <li>In <module>mod_ext_filter</module>, the length of time to
+ wait for output from a filtering process.</li>
+
+ <li>In <module>mod_proxy</module>, the default timeout value if
+ <directive module="mod_proxy">ProxyTimeout</directive> is not
+ configured.</li>
</ol>
- <p>We plan on making these separately configurable at some point
- down the road. The timer used to default to 1200 before 1.2,
- but has been lowered to 300 which is still far more than
- necessary in most situations. It is not set any lower by
- default because there may still be odd places in the code where
- the timer is not reset when a packet is sent. </p>
</usage>
</directivesynopsis>
<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>
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
to match all ports on that address. (This is recommended when used
with <code>_default_</code>.)</p>
+ <p>A <directive module="core">ServerName</directive> should be
+ specified inside each <directive
+ type="section">VirtualHost</directive> block. If it is absent, the
+ <directive module="core">ServerName</directive> from the "main"
+ server configuration will be inherited.</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