From: Jeff Trawick Date: Tue, 24 Nov 2009 21:08:37 +0000 (+0000) Subject: move a couple of special warnings for SysV sems and Posix sems out of the X-Git-Tag: 2.3.4~5 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=6565e2228baed86c40bb38d60cccd815588c4f8a;p=apache move a couple of special warnings for SysV sems and Posix sems out of the performance tuning guide and into the common Mutex documentation; remove the other (duplicate) information from that guide and instead point to the Mutex directive mpm_common: axe docs for old accept mutex directives worker and prefork: axe links to old accept mutex directives, mention the use of the accept mutex and how it can be configured event: axe links to old mutex directives where were already N/A mod_rewrite: axe old RewriteLock directive, mention use of the rewrite map mutex for RewriteMap programs and how it can be configured fix other miscellaneous LockFile or AcceptMutex references git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@883878 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/misc/perf-tuning.xml b/docs/manual/misc/perf-tuning.xml index 6526a4b122..ac0fa15a3c 100644 --- a/docs/manual/misc/perf-tuning.xml +++ b/docs/manual/misc/perf-tuning.xml @@ -705,67 +705,11 @@ Listen directives.

-

The directive AcceptMutex can be used to - change the selected mutex implementation at run-time.

- -
-
AcceptMutex flock
- -
-

This method uses the flock(2) system call to - lock a lock file (located by the LockFile directive).

-
- -
AcceptMutex fcntl
- -
-

This method uses the fcntl(2) system call to - lock a lock file (located by the LockFile directive).

-
- -
AcceptMutex sysvsem
- -
-

(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 - ipcs(8) 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 - (i.e., all CGIs, unless you use something like - suexec or cgiwrapper).

-
- -
AcceptMutex pthread
- -
-

(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.

-
- -
AcceptMutex posixsem
- -
-

(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.

-
- -
- -

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.

+

The Mutex directive can + be used to change the mutex implementation of the + mpm-accept mutex at run-time. Special considerations + for different mutex implementations are documented with that + directive.

Another solution that has been considered but never implemented is to partially serialize the loop -- that is, let diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml index cf7e3672bd..daf9f71ac4 100644 --- a/docs/manual/mod/core.xml +++ b/docs/manual/mod/core.xml @@ -2335,7 +2335,13 @@ or specified mutexes module documentation for more information.

  • posixsem -

    This is a mutex variant based on a Posix semaphore.

    • +

    This is a mutex variant based on a Posix semaphore.

    + + Warning +

    The semaphore ownership is not recovered if a thread in the process + holding the mutex segfaults, resulting in a hang of the web server.

    +     +
  • sysvsem

    This is a mutex variant based on a SystemV IPC semaphore.

    @@ -2344,6 +2350,13 @@ or specified mutexes

    It is possible to "leak" SysV semaphores if processes crash before the semaphore is removed.

    + + Security +

    The semaphore API allows for a denial of service attack by any + CGIs running under the same uid as the webserver (i.e., + all CGIs, unless you use something like suexec + or cgiwrapper).

    +
  • sem diff --git a/docs/manual/mod/event.xml b/docs/manual/mod/event.xml index 9439e1899d..55f31b266b 100644 --- a/docs/manual/mod/event.xml +++ b/docs/manual/mod/event.xml @@ -94,8 +94,6 @@ of consuming threads only for connections with active processing -AcceptMutex - CoreDumpDirectory EnableExceptionHook @@ -108,8 +106,6 @@ of consuming threads only for connections with active processing SendBufferSize -LockFile - MaxClients MaxMemFree diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml index 363429ddb2..9151086b97 100644 --- a/docs/manual/mod/mod_rewrite.xml +++ b/docs/manual/mod/mod_rewrite.xml @@ -202,26 +202,6 @@ RewriteLogLevel 3 - -RewriteLock -Sets the name of the lock file used for RewriteMap -synchronization -RewriteLock file-path -server config - - -

    This directive sets the filename for a synchronization - lockfile which mod_rewrite needs to communicate with RewriteMap - programs. 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.

    -     - -     - RewriteMap Defines a mapping function for key-lookup @@ -417,6 +397,11 @@ $ httxt2dbm -i mapfile.txt -o mapfile.map ``NULL'' if it fails (i.e., there is no corresponding value for the given key).

    +

    This feature utilizes the rewrite-map mutex, + which is required for reliable communication with the program. + The mutex mechanism and lock file can be configured with the + Mutex directive.

    +

    External rewriting programs are not started if they're defined in a context that does not have RewriteEngine set to on

    . @@ -445,12 +430,6 @@ while (<STDIN>) {
  • A common mistake is to use buffered I/O on stdout. Avoid this, as it will cause a deadloop! ``$|=1'' is used above, to prevent this.
    • - -
  • The RewriteLock 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.
  • diff --git a/docs/manual/mod/mpm_common.xml b/docs/manual/mod/mpm_common.xml index 66306c13c2..d59018e51f 100644 --- a/docs/manual/mod/mpm_common.xml +++ b/docs/manual/mod/mpm_common.xml @@ -27,96 +27,6 @@ more than one multi-processing module (MPM) MPM - -AcceptMutex -Method that Apache uses to serialize multiple children -accepting requests on network sockets -AcceptMutex Default|method -AcceptMutex Default -server config -preforkworker - - - -

    The AcceptMutex 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 performance tuning - documentation.

    - -

    If this directive is set to Default, 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.

    - -
    -
    flock<:/path/to/lockfile>
    -
    uses the flock(2) system call to lock the - file defined by the optional /path/to/lockfile - parameter. One can also use the LockFile directive to specify the lockfile, - although this is deprecated.
    - -
    fcntl<:/path/to/lockfile>
    -
    uses the fcntl(2) system call to lock the - file defined by the optional /path/to/lockfile - parameter. One can also use the LockFile directive to specify the lockfile, - although this is deprecated.
    - -
    file<:/path/to/lockfile>
    -
    This directive tells Apache to pick the "best" file locking - implementation available to it, choosing between fcntl and - flock, in that order. It is only available when the underlying - platform and APR supports at least one of the 2.
    - -
    posixsem
    -
    uses POSIX compatible semaphores to implement the mutex.
    - -
    sysvsem
    -
    uses SySV-style semaphores to implement the mutex.
    - -
    sem
    -
    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 - APR supports at least one of the 2.
    - -
    pthread
    -
    uses POSIX mutexes as implemented by the POSIX Threads - (PThreads) specification.
    - -
    - -

    If you want to find out the compile time chosen default - for your system, you may set your LogLevel to debug. Then the default AcceptMutex will be written into the ErrorLog.

    - - Warning -

    On most systems, when the pthread option - is selected, if a child process terminates abnormally - while holding the AcceptCntl mutex the - server will stop responding to requests. When this - occurs, the server will require a manual restart to - recover.

    -

    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.

    -

    If your system implements the - pthread_mutexattr_setrobust_np() function, - you may be able to use the pthread option safely.

    -     -     -     - CoreDumpDirectory Directory where Apache attempts to @@ -354,45 +264,6 @@ The protocol argument was added in 2.1.5 - -LockFile -Location of the accept serialization lock file (deprecated) -LockFile filename -LockFile logs/accept.lock -server config - -preforkworker - - - -

    The LockFile directive sets the path to - the lockfile used when Apache is used with an AcceptMutex value of either - fcntl or flock. This directive should - normally be left at its default value. The main reason for changing - it is if the logs directory is NFS mounted, since - the lockfile must be stored on a local disk. The PID - of the main server process is automatically appended to the - filename.

    - - Security -

    It is best to avoid putting this file in a world writable - directory such as /var/tmp 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.

    -     - Deprecated -

    This directive is deprecated. It is strongly suggested that - you use AcceptMutex to - specify both the mutex locking implementation as well as - the lockfile location.

    -     - -     -AcceptMutex -     - MaxClients Maximum number of connections that will be processed diff --git a/docs/manual/mod/prefork.xml b/docs/manual/mod/prefork.xml index c5288611dd..d47dd7a0cf 100644 --- a/docs/manual/mod/prefork.xml +++ b/docs/manual/mod/prefork.xml @@ -83,6 +83,14 @@ uses

    MaxRequestsPerChild controls how frequently the server recycles processes by killing old ones and launching new ones.

    + +

    This MPM uses the mpm-accept 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 + Mutex directive. The performance hints + documentation has additional information about this mutex.

    CoreDumpDirectory @@ -95,8 +103,6 @@ uses ListenBacklog -LockFile - MaxClients MaxMemFree @@ -117,8 +123,6 @@ uses Group -AcceptMutex - MaxSpareServers diff --git a/docs/manual/mod/worker.xml b/docs/manual/mod/worker.xml index 1490cb2d11..98b709327b 100644 --- a/docs/manual/mod/worker.xml +++ b/docs/manual/mod/worker.xml @@ -135,10 +135,16 @@ uses

    MaxRequestsPerChild controls how frequently the server recycles processes by killing old ones and launching new ones.

    + +

    This MPM uses the mpm-accept 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 + Mutex directive. The performance hints + documentation has additional information about this mutex.

    -AcceptMutex - CoreDumpDirectory EnableExceptionHook @@ -151,8 +157,6 @@ uses ListenBacklog -LockFile - MaxClients MaxMemFree diff --git a/docs/manual/server-wide.xml b/docs/manual/server-wide.xml index 15e511e4b0..161bb41871 100644 --- a/docs/manual/server-wide.xml +++ b/docs/manual/server-wide.xml @@ -70,7 +70,7 @@ the basic operations of the server.

    CoreDumpDirectory DocumentRoot ErrorLog - LockFile + Mutex PidFile ScoreBoardFile ServerRoot @@ -117,4 +117,20 @@ the basic operations of the server.

    The ThreadStackSize directive is used with some platforms to control the stack size.

    + +
    + Implementation Choices + + + + Mutex + + + +

    The Mutex directive can be used to change + the underlying implementation used for mutexes, in order to relieve + functional or performance problems with APR's + default choice.

    +
    + diff --git a/docs/manual/stopping.xml b/docs/manual/stopping.xml index 5c49c7684e..ef5826e43c 100644 --- a/docs/manual/stopping.xml +++ b/docs/manual/stopping.xml @@ -214,9 +214,9 @@ syntax error(s). upgrades of Apache, however it can also cause deadlocks and race conditions with some configurations.

    -

    Care has been taken to ensure that on-disk files - such as the Lockfile and ScriptSock files contain the server +

    Care has been taken to ensure that on-disk files such as lock files + (Mutex) and Unix socket files + (ScriptSock) 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