<directive module="mpm_common">Listen</directive>
directives.</p>
- <p>The directive <directive
- module="mpm_common">AcceptMutex</directive> can be used to
- change the selected mutex implementation at run-time.</p>
-
- <dl>
- <dt><code>AcceptMutex flock</code></dt>
-
- <dd>
- <p>This method uses the <code>flock(2)</code> system call to
- lock a lock file (located by the <directive module="mpm_common"
- >LockFile</directive> directive).</p>
- </dd>
-
- <dt><code>AcceptMutex fcntl</code></dt>
-
- <dd>
- <p>This method uses the <code>fcntl(2)</code> system call to
- lock a lock file (located by the <directive module="mpm_common"
- >LockFile</directive> directive).</p>
- </dd>
-
- <dt><code>AcceptMutex sysvsem</code></dt>
-
- <dd>
- <p>(1.3 or later) This method uses SysV-style semaphores to
- implement the mutex. Unfortunately SysV-style semaphores have
- some bad side-effects. One is that it's possible Apache will
- die without cleaning up the semaphore (see the
- <code>ipcs(8)</code> man page). The other is that 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>
- </dd>
-
- <dt><code>AcceptMutex pthread</code></dt>
-
- <dd>
- <p>(1.3 or later) This method uses POSIX mutexes and should
- work on any architecture implementing the full POSIX threads
- specification, however appears to only work on Solaris (2.5
- or later), and even then only in certain configurations. If
- you experiment with this you should watch out for your server
- hanging and not responding. Static content only servers may
- work just fine.</p>
- </dd>
-
- <dt><code>AcceptMutex posixsem</code></dt>
-
- <dd>
- <p>(2.0 or later) This method uses POSIX semaphores. 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>
- </dd>
-
- </dl>
-
- <p>If your system has another method of serialization which
- isn't in the above list then it may be worthwhile adding code
- for it to APR.</p>
+ <p>The <directive module="core">Mutex</directive> directive can
+ be used to change the mutex implementation of the
+ <code>mpm-accept</code> mutex at run-time. Special considerations
+ for different mutex implementations are documented with that
+ directive.</p>
<p>Another solution that has been considered but never
implemented is to partially serialize the loop -- that is, let
module documentation for more information.</p></li>
<li><code>posixsem</code>
- <p>This is a mutex variant based on a Posix semaphore.</p></li>
+ <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>
<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>
</ul>
</section>
-<directivesynopsis location="mpm_common"><name>AcceptMutex</name>
-</directivesynopsis>
<directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
</directivesynopsis>
<directivesynopsis location="mpm_common"><name>EnableExceptionHook</name>
</directivesynopsis>
<directivesynopsis location="mpm_common"><name>SendBufferSize</name>
</directivesynopsis>
-<directivesynopsis location="mpm_common"><name>LockFile</name>
-</directivesynopsis>
<directivesynopsis location="mpm_common"><name>MaxClients</name>
</directivesynopsis>
<directivesynopsis location="mpm_common"><name>MaxMemFree</name>
</directivesynopsis>
-<directivesynopsis>
-<name>RewriteLock</name>
-<description>Sets the name of the lock file used for <directive
-module="mod_rewrite">RewriteMap</directive>
-synchronization</description>
-<syntax>RewriteLock <em>file-path</em></syntax>
-<contextlist><context>server config</context></contextlist>
-
-<usage>
- <p>This directive sets the filename for a synchronization
- lockfile which mod_rewrite needs to communicate with <directive
- module="mod_rewrite">RewriteMap</directive>
- <em>programs</em>. Set this lockfile to a local path (not on a
- NFS-mounted device) when you want to use a rewriting
- map-program. It is not required for other types of rewriting
- maps.</p>
-</usage>
-
-</directivesynopsis>
-
<directivesynopsis>
<name>RewriteMap</name>
<description>Defines a mapping function for key-lookup</description>
``<code>NULL</code>'' if it fails (<em>i.e.</em>, there
is no corresponding value for the given key).</p>
+ <p>This feature utilizes the <code>rewrite-map</code> mutex,
+ which is required for reliable communication with the program.
+ The mutex mechanism and lock file can be configured with the
+ <directive module="core">Mutex</directive> directive.</p>
+
<p>External rewriting programs are not started if they're defined in a
context that does not have <directive>RewriteEngine</directive> set to
<code>on</code></p>.
<li>A common mistake is to use buffered I/O on
<code>stdout</code>. Avoid this, as it will cause a deadloop!
``<code>$|=1</code>'' is used above, to prevent this.</li>
-
- <li>The <directive
- module="mod_rewrite">RewriteLock</directive> directive can
- be used to define a lockfile which mod_rewrite can use to synchronize
- communication with the mapping program. By default no such
- synchronization takes place.</li>
</ol>
</li>
<li>
more than one multi-processing module (MPM)</description>
<status>MPM</status>
-<directivesynopsis>
-<name>AcceptMutex</name>
-<description>Method that Apache uses to serialize multiple children
-accepting requests on network sockets</description>
-<syntax>AcceptMutex Default|<var>method</var></syntax>
-<default>AcceptMutex Default</default>
-<contextlist><context>server config</context></contextlist>
-<modulelist><module>prefork</module><module>worker</module>
-</modulelist>
-
-<usage>
- <p>The <directive>AcceptMutex</directive> directives sets the
- method (and lockfile location if appropriate) that Apache uses to
- serialize multiple children accepting
- requests on network sockets. Prior to Apache 2.0, the method was
- selectable only at compile time. The optimal method to use is
- highly architecture and platform dependent. For further details,
- see the <a href="../misc/perf-tuning.html">performance tuning</a>
- documentation.</p>
-
- <p>If this directive is set to <code>Default</code>, then the
- compile-time selected default will be used. Other possible
- methods are listed below. Note that not all methods are
- available on all platforms. If a method is specified which is
- not available, a message will be written to the error log
- listing the available methods.</p>
-
- <dl>
- <dt><code>flock<<var>:/path/to/lockfile</var>></code></dt>
- <dd>uses the <code>flock(2)</code> system call to lock the
- file defined by the optional <var>/path/to/lockfile</var>
- parameter. One can also use the <directive module="mpm_common"
- >LockFile</directive> directive to specify the lockfile,
- although this is deprecated.</dd>
-
- <dt><code>fcntl<<var>:/path/to/lockfile</var>></code></dt>
- <dd>uses the <code>fcntl(2)</code> system call to lock the
- file defined by the optional <var>/path/to/lockfile</var>
- parameter. One can also use the <directive module="mpm_common"
- >LockFile</directive> directive to specify the lockfile,
- although this is deprecated.</dd>
-
- <dt><code>file<<var>:/path/to/lockfile</var>></code></dt>
- <dd>This directive tells Apache to pick the "best" file locking
- implementation available to it, choosing between <code>fcntl</code> and
- <code>flock</code>, in that order. It is only available when the underlying
- platform and <glossary>APR</glossary> supports at least one of the 2.</dd>
-
- <dt><code>posixsem</code></dt>
- <dd>uses POSIX compatible semaphores to implement the mutex.</dd>
-
- <dt><code>sysvsem</code></dt>
- <dd>uses SySV-style semaphores to implement the mutex.</dd>
-
- <dt><code>sem</code></dt>
- <dd>This directive tells Apache to pick the "best" semaphore
- implementation available to it, choosing between Posix and SystemV IPC,
- in that order. It is only available when the underlying platform and
- <glossary>APR</glossary> supports at least one of the 2.</dd>
-
- <dt><code>pthread</code></dt>
- <dd>uses POSIX mutexes as implemented by the POSIX Threads
- (PThreads) specification.</dd>
-
- </dl>
-
- <p>If you want to find out the compile time chosen default
- for your system, you may set your <directive module="core"
- >LogLevel</directive> to <code>debug</code>. Then the default <directive
- >AcceptMutex</directive> will be written into the <directive
- module="core">ErrorLog</directive>.</p>
-
- <note type="warning"><title>Warning</title>
- <p>On most systems, when the <code>pthread</code> option
- is selected, if a child process terminates abnormally
- while holding the <code>AcceptCntl</code> mutex the
- server will 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, used by Apache, 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>
-</usage>
-</directivesynopsis>
-
<directivesynopsis>
<name>CoreDumpDirectory</name>
<description>Directory where Apache attempts to
</usage>
</directivesynopsis>
-<directivesynopsis>
-<name>LockFile</name>
-<description>Location of the accept serialization lock file <em>(deprecated)</em></description>
-<syntax>LockFile <var>filename</var></syntax>
-<default>LockFile logs/accept.lock</default>
-<contextlist><context>server config</context></contextlist>
-<modulelist>
-<module>prefork</module><module>worker</module>
-</modulelist>
-
-<usage>
- <p>The <directive>LockFile</directive> directive sets the path to
- the lockfile used when Apache is used with an <directive
- module="mpm_common">AcceptMutex</directive> value of either
- <code>fcntl</code> or <code>flock</code>. This directive should
- normally be left at its default value. The main reason for changing
- it is if the <code>logs</code> directory is NFS mounted, since
- <strong>the lockfile must be stored on a local disk</strong>. The PID
- of the main server process is automatically appended to the
- filename.</p>
-
- <note type="warning"><title>Security</title>
- <p>It is best to <em>avoid</em> putting this file 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>
- <note type="warning"><title>Deprecated</title>
- <p>This directive is deprecated. It is strongly suggested that
- you use <directive module="mpm_common">AcceptMutex</directive> to
- specify both the mutex locking implementation as well as
- the lockfile location.</p>
- </note>
-
-</usage>
-<seealso><directive module="mpm_common">AcceptMutex</directive></seealso>
-</directivesynopsis>
-
<directivesynopsis>
<name>MaxClients</name>
<description>Maximum number of connections that will be processed
<p><directive module="mpm_common">MaxRequestsPerChild</directive>
controls how frequently the server recycles processes by killing
old ones and launching new ones.</p>
+
+ <p>This MPM uses the <code>mpm-accept</code> mutex to serialize
+ access to incoming connections when subject to the thundering herd
+ problem (generally, when there are multiple listening sockets).
+ The implementation aspects of this mutex can be configured with the
+ <directive module="core">Mutex</directive> directive. The <a
+ href="../misc/perf-tuning.html">performance hints</a>
+ documentation has additional information about this mutex.</p>
</section>
<directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
</directivesynopsis>
<directivesynopsis location="mpm_common"><name>ListenBacklog</name>
</directivesynopsis>
-<directivesynopsis location="mpm_common"><name>LockFile</name>
-</directivesynopsis>
<directivesynopsis location="mpm_common"><name>MaxClients</name>
</directivesynopsis>
<directivesynopsis location="mpm_common"><name>MaxMemFree</name>
</directivesynopsis>
<directivesynopsis location="mod_unixd"><name>Group</name>
</directivesynopsis>
-<directivesynopsis location="mpm_common"><name>AcceptMutex</name>
-</directivesynopsis>
<directivesynopsis>
<name>MaxSpareServers</name>
<p><directive module="mpm_common">MaxRequestsPerChild</directive>
controls how frequently the server recycles processes by killing
old ones and launching new ones.</p>
+
+ <p>This MPM uses the <code>mpm-accept</code> mutex to serialize
+ access to incoming connections when subject to the thundering herd
+ problem (generally, when there are multiple listening sockets).
+ The implementation aspects of this mutex can be configured with the
+ <directive module="core">Mutex</directive> directive. The <a
+ href="../misc/perf-tuning.html">performance hints</a>
+ documentation has additional information about this mutex.</p>
</section>
-<directivesynopsis location="mpm_common"><name>AcceptMutex</name>
-</directivesynopsis>
<directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
</directivesynopsis>
<directivesynopsis location="mpm_common"><name>EnableExceptionHook</name>
</directivesynopsis>
<directivesynopsis location="mpm_common"><name>ListenBacklog</name>
</directivesynopsis>
-<directivesynopsis location="mpm_common"><name>LockFile</name>
-</directivesynopsis>
<directivesynopsis location="mpm_common"><name>MaxClients</name>
</directivesynopsis>
<directivesynopsis location="mpm_common"><name>MaxMemFree</name>
<directive module="mpm_common">CoreDumpDirectory</directive>
<directive module="core">DocumentRoot</directive>
<directive module="core">ErrorLog</directive>
- <directive module="mpm_common">LockFile</directive>
+ <directive module="core">Mutex</directive>
<directive module="mpm_common">PidFile</directive>
<directive module="mpm_common">ScoreBoardFile</directive>
<directive module="core">ServerRoot</directive>
<p>The <directive module="mpm_common">ThreadStackSize</directive>
directive is used with some platforms to control the stack size.</p>
</section>
+
+ <section id="implementation">
+ <title>Implementation Choices</title>
+
+ <related>
+ <directivelist>
+ <directive module="core">Mutex</directive>
+ </directivelist>
+ </related>
+
+ <p>The <directive>Mutex</directive> directive can be used to change
+ the underlying implementation used for mutexes, in order to relieve
+ functional or performance problems with <glossary>APR</glossary>'s
+ default choice.</p>
+ </section>
+
</manualpage>
upgrades of Apache, however it can also cause deadlocks and race
conditions with some configurations.</p>
- <p>Care has been taken to ensure that on-disk files
- such as the <directive module="core">Lockfile</directive> and <directive
- module="mod_cgid">ScriptSock</directive> files contain the server
+ <p>Care has been taken to ensure that on-disk files such as lock files
+ (<directive module="core">Mutex</directive>) and Unix socket files
+ (<directive module="mod_cgid">ScriptSock</directive>) contain the server
PID, and should coexist without problem. However, if a configuration
directive, third-party module or persistent CGI utilises any other on-disk
lock or state files, care should be taken to ensure that multiple running
projects / apache / commitdiff