From 48a542e69c8855b2d69a217297e90aed33800ce2 Mon Sep 17 00:00:00 2001 From: Jeff Trawick Date: Tue, 24 Nov 2009 14:54:03 +0000 Subject: [PATCH] document the new Mutex directive, pulling in any existing special considerations described in the documentation of the old LockFile, AcceptMutex, RewriteLock, and SSLMutex directives git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@883712 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/core.xml | 204 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml index 710c160f57..cf7e3672bd 100644 --- a/docs/manual/mod/core.xml +++ b/docs/manual/mod/core.xml @@ -2228,6 +2228,210 @@ connection + +Mutex +Configures mutex mechanism and lock file directory for all +or specified mutexes +Mutex default|mutex-name mechanism +Mutex default default +server config +Available in Apache 2.3.4 and later + + +

The Mutex directive sets the mechanism, + and optionally the lock file location, that httpd and modules use + to serialize access to resources. Specify default 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.

+ +

The Mutex directive is typically used in + the following exceptional situations:

+ +
    +
  • change the mutex mechanism when the default mechanism selected + by APR has a functional or performance + problem
    • + +
  • change the directory used by file-based mutexes when the + default directory does not support locking
    • +
+ + Supported modules +

This directive only configures mutexes which have been registered + with the core server using the ap_mutex_register() API. + All modules bundled with httpd support the Mutex + 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.

+ + +

The following table documents the names of mutexes used by httpd + and bundled modules.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mutex nameModule(s)Protected resource
mpm-acceptprefork and worker MPMsincoming connections, to avoid the thundering herd problem; + for more information, refer to the + performance tuning + documentation
authdigest-clientmod_auth_digestclient list in shared memory
authdigest-opaquemod_auth_digestcounter in shared memory
ldap-cachemod_ldapLDAP result cache
rewrite-mapmod_rewritecommunication with external mapping programs, to avoid + intermixed I/O from multiple requests
ssl-cachemod_sslSSL session cache
ssl-staplingmod_sslOCSP stapling response cache
watchdog-callbackmod_watchdogcallback function of a particular client module
+ +

The following mutex mechanisms are available:

+
    +
  • default | yes +

    This selects the default locking implementation, as determined by + APR. The default locking implementation can + be displayed by running httpd with the + -V option.

    • + +
  • none | no +

    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.

    • + +
  • posixsem +

    This is a mutex variant based on a Posix semaphore.

    • + +
  • sysvsem +

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

    + + Warning +

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

    +     +
    • + +
  • sem +

    This selects the "best" available semaphore implementation, choosing + between Posix and SystemV IPC semaphores, in that order.

    • + +
  • pthread +

    This is a mutex variant based on cross-process Posix thread + mutexes.

    + + Warning +

    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.

    +

    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.

    +

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

    +     +
    • + +
  • fcntl:/path/to/mutex +

    This is a mutex variant where a physical (lock-)file and the + fcntl() function are used as the mutex.

    + + Warning +

    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 fcntl() + is not thread-aware, such as on Solaris.

    +     +
    • + +
  • flock:/path/to/mutex +

    This is similar to the fcntl:/path/to/mutex method + with the exception that the flock() function is used to + provide file locking.

    • + +
  • file:/path/to/mutex +

    This selects the "best" available file locking implementation, + choosing between fcntl and flock, in that + order.

    • +
+ +

Most mechanisms are only available on selected platforms, where the + underlying platform and APR support it. Mechanisms + which aren't avaiable on all platforms are posixsem, + sysvsem, sem, pthread, fcntl, + flock, and file.

+ +

With the file-based mechanisms fcntl and flock, + 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 + ServerRoot. Always use a local disk + filesystem for /path/to/mutex 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, with the process + id of the httpd parent process appended to to make it unique, avoiding + conflicts when multiple httpd instances share a lock file directory. For + example, if the mutex name is mpm-accept and the lock file + directory is /var/httpd/locks, the lock file name for the + httpd instance with parent process id 12345 would be + /var/httpd/locks/mpm-accept.12345.

+ + Security +

It is best to avoid putting mutex files 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.

+ + +

In the following example, the mutex mechanism for the MPM accept + mutex will be changed from the compiled-in default to fcntl, + with the associated lock file created in directory + /var/httpd/locks. The mutex mechanism for all other mutexes + will be changed from the compiled-in default to sysvsem.

+ + + Mutex default sysvsem
+ Mutex mpm-accept fcntl:/var/httpd/locks + + + + NameVirtualHost Designates an IP address for name-virtual -- 2.40.0