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 second argument to change the settings for all mutexes; specify
a mutex name (see table below) as the second 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 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.
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.
Warning
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
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 and Linux are notable exceptions as they provide a mechanism which
usually allows the mutex to be recovered after a child process
terminates abnormally while holding a mutex.
If your system is POSIX compliant or if it 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 available 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, and unless the
OmitPID keyword is specified, the process id of the httpd
parent process will be appended to make the file name 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.
The following table documents the names of mutexes used by httpd
and bundled modules.
mpm-accept |
prefork and worker MPMs |
incoming connections, to avoid the thundering herd problem;
for more information, refer to the
performance tuning
documentation |
authdigest-client |
mod_auth_digest |
client list in shared memory |
authdigest-opaque |
mod_auth_digest |
counter in shared memory |
ldap-cache |
mod_ldap |
LDAP result cache |
rewrite-map |
mod_rewrite |
communication with external mapping programs, to avoid
intermixed I/O from multiple requests |
ssl-cache |
mod_ssl |
SSL session cache |
ssl-stapling |
mod_ssl |
OCSP stapling response cache |
watchdog-callback |
mod_watchdog |
callback function of a particular client module |
The OmitPID keyword suppresses the addition of the httpd
parent process id from the lock file name.
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 sysvsem default
Mutex fcntl:/var/httpd/locks mpm-accept
