<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>
<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>
<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,
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
<name>ErrorLog</name>
<description>Location where the server will log errors</description>
<syntax> ErrorLog <var>file-path</var>|syslog[:<var>facility</var>]</syntax>
-<default>ErrorLog logs/error_log (Unix) ErrorLog logs/error.log (Windows)</default>
+<default>ErrorLog logs/error_log (Unix) ErrorLog logs/error.log (Windows and OS/2)</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
</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>,
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
</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">
</usage>
</directivesynopsis>
+<directivesynopsis>
+<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>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>The <directive>Mutex</directive> directive is typically used in
+ the following exceptional situations:</p>
+
+ <ul>
+ <li>change the mutex mechanism when the default mechanism selected
+ by <glossary>APR</glossary> has a functional or performance
+ problem</li>
+
+ <li>change the directory used by file-based mutexes when the
+ default directory does not support locking</li>
+ </ul>
+
+ <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>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>
+ 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
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>
projects / apache / blobdiff