From 5fe0caf22ae8c6201cf06ff414b1bdd35d1af07e Mon Sep 17 00:00:00 2001 From: Joshua Slive Date: Tue, 26 Feb 2002 19:00:40 +0000 Subject: [PATCH] Start converting the mpm documentation. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@93579 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mpm_common.xml | 613 +++++++++++++++++++++++++++++++++ docs/manual/mod/prefork.xml | 207 +++++++++++ 2 files changed, 820 insertions(+) create mode 100644 docs/manual/mod/mpm_common.xml create mode 100644 docs/manual/mod/prefork.xml diff --git a/docs/manual/mod/mpm_common.xml b/docs/manual/mod/mpm_common.xml new file mode 100644 index 0000000000..3e3e4b7a5f --- /dev/null +++ b/docs/manual/mod/mpm_common.xml @@ -0,0 +1,613 @@ + + + + +mpm_common +A collection of directives that are implemented by +more than one multi-processing module (MPM) +MPM + + +CoreDumpDirectory +Sets the directory where Apache attempts to +switch before dumping core +CoreDumpDirectory directory +CoreDumpDirectory ServerRoot +server config +workerperchild +preforkmpm_winnt + + + + +

This controls the directory to which Apache attempts to + switch before dumping core. The default is in the + ServerRoot directory, however + since this should not be writable by the user the server runs + as, core dumps won't normally get written. If you want a core + dump for debugging, you can use this directive to place it in a + different location.

+ + + + +Group +Sets the group under which the server will answer +requests +Group unix-group +Group #-1 +server configvirtual host + +workerperchild +prefork + + +

The Group directive sets the group under + which the server will answer requests. In order to use this + directive, the stand-alone server must be run initially as root. + Unix-group is one of:

+ +
+
A group name
+ +
Refers to the given group by name.
+ +
# followed by a group number.
+ +
Refers to a group by its number.
+
+

It is recommended that you set up a new group specifically for + running the server. Some admins use user nobody, + but this is not always possible or desirable.

+ +

Note: if you start the server as a non-root user, it will + fail to change to the specified group, and will instead + continue to run as the group of the original user.

+ +

Special note: Use of this directive in <VirtualHost< is + no longer supported. To implement the suEXEC wrapper with Apache 2.0, use the + SuexecUserGroup + directive. SECURITY: See User for a discussion of the + security considerations.

+ + + + +PidFile +Sets the file where the server records the process ID +of the daemon +PidFile filename +PidFile logs/httpd.pid +server config +workerperchilde +preforkmpm_winnt + + + +

The PidFile directive sets the file to + which the server records the process id of the daemon. If the + filename does not begin with a slash (/) then it is assumed to be + relative to the ServerRoot.

+ +

It is often useful to be able to send the server a signal, + so that it closes and then reopens its ErrorLog and TransferLog, and + re-reads its configuration files. This is done by sending a + SIGHUP (kill -1) signal to the process id listed in the + PidFile.

+ +

The PidFile is subject to the same warnings about log file + placement and security.

+ + + + +Listen +Sets the IP addresses and ports that the server +listens to +Listen [IP-address:]portnumber +server config +workerperchild +preforkmpm_winnt + + + +

The Listen directive instructs Apache to + listen to only specific IP addresses or ports; by default it + responds to requests on all IP interfaces. The Listen directive is + now a required directive. If it is not in the config file, the + server will fail to start. This is a change from previous versions + of Apache.

+ +

The Listen directive tells the server to accept incoming + requests on the specified port or address-and-port combination. + If only a port number is specified, the server listens to the + given port on all interfaces. If an IP address is given as well + as a port, the server will listen on the given port and + interface.

+ +

Multiple Listen directives may be used to specify a number + of addresses and ports to listen to. The server will respond to + requests from any of the listed addresses and ports.

+ +

For example, to make the server accept connections on both + port 80 and port 8000, use:

+ + Listen 80
+ Listen 8000 + + To make the server accept connections on two specified + interfaces and port numbers, use + + Listen 192.170.2.1:80
+ Listen 192.170.2.5:8000 + + IPv6 addresses must be surrounded in square brackets, as in the + following example: + + Listen [fe80::a00:20ff:fea7:ccea]:80 + + + +DNS Issues +Setting + which addresses and ports Apache uses + + + +ListenBackLog +Maximum length of the queue of pending connections +ListenBacklog backlog +ListenBacklog 511 +server config +workerperchild +preforkmpm_winnt + + + +

The maximum length of the queue of pending connections. + Generally no tuning is needed or desired, however on some + systems it is desirable to increase this when under a TCP SYN + flood attack. See the backlog parameter to the + listen(2) system call.

+ +

This will often be limited to a smaller number by the + operating system. This varies from OS to OS. Also note that + many OSes do not use exactly what is specified as the backlog, + but use a number based on (but normally larger than) what is + set.

+ + + + +LockFile +Location of the accept serialization lock file +LockFile filename +LockFile logs/accept.lock +server config +workerperchild +prefork + + +

The LockFile directive sets the path to + the lockfile used when Apache is compiled with either + USE_FCNTL_SERIALIZED_ACCEPT or USE_FLOCK_SERIALIZED_ACCEPT. 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.

+ + + + +MaxClients +Maximum number of child processes that will be created +to serve requests +MaxClients number +>MaxClients + 8 (with threads) MaxClients 256 +server config +workerprefork + + + +

The MaxClients directive sets the limit + on the number of child processes that will be created to serve + requests. When the server is built without threading, no more than + this number of clients can be served simultaneously. To configure + more than 256 clients with the prefork MPM, you must use the + ServerLimit directive. + To configure more than 1024 clients with the worker MPM, you must + use the ServerLimit and + ThreadLimit directives.

+ +

Any connection attempts over the + MaxClients limit will normally be queued, + up to a number based on the ListenBacklog directive. Once a child + process is freed at the end of a different request, the connection + will then be serviced.

+ +

When the server is compiled with threading, then the maximum + number of simultaneous requests that can be served is obtained + from the value of this directive multiplied by + ThreadsPerChild.

+ + + + +MaxRequestPerChild +Limit on the number of requests that an individual child server +will handle during its life +MaxRequestsPerChild number +MaxRequestsPerChild 10000 +server config +workerperchild +preforkmpm_winnt + + + +

The MaxRequestsPerChild directive sets + the limit on the number of requests that an individual child + server process will handle. After + MaxRequestsPerChild requests, the child + process will die. If MaxRequestsPerChild is + 0, then the process will never expire.

+ +

Setting MaxRequestsPerChild to a + non-zero limit has two beneficial effects:

+ +
    +
  • it limits the amount of memory that process can consume + by (accidental) memory leakage;
    • + +
  • by giving processes a finite lifetime, it helps reduce + the number of processes when the server load reduces.
    • +
+ +

NOTE: For KeepAlive requests, only + the first request is counted towards this limit. In effect, it + changes the behavior to limit the number of + connections per child.

+ + + + +MaxSpareThreads +Maximum number of idle threads +MaxSpareThreads number +MaxSpareThreads 10 (Perchild) or 500 (worker) +server config +workerperchild + + + +

Maximum number of idle threads. Different MPMs deal with this + directive differently. perchild monitors the + number of idle threads on a per-child basis. If there are too many + idle threads in that child, the server will begin to kill threads + within that child.

+ +

worker deals with idle threads on a + server-wide basis. If there are too many idle threads in the + server then child processes are killed until the number of idle + threads is less than this number.

+ + +MinSpareThreads +StartServers + + + +MaxThreadsPerChild +Maximum number of threads per child process +MaxThreadsPerChild number +MaxThreadsPerChild 64 +server config +workerperchild + + + +

Maximum number of threads per child. For MPMs with a + variable number of threads per child, this directive sets the + maximum number of threads that will be created in each child + process. To increase this value beyond its default, it is + necessary to change the value of the compile-time define + HARD_THREAD_LIMIT and recompile the server.

+ + + + +MinSpareThreads +Minimum number of idle threads available to handle request +spikes +MinSpareServers number +MinSpareThreads 5 (Perchild) or 250 (worker) +server config +workerperchild + + + +

Minimum number of idle threads to handle request spikes. + Different MPMs deal with this directive + differently. perchild monitors the number of idle + threads on a per-child basis. If there aren't enough idle threads + in that child, the server will begin to create new threads within + that child.

+ +

worker deals with idle threads on a + server-wide basis. If there aren't enough idle threads in the + server then child processes are created until the number of idle + threads is greater than number.

+ +MaxSpareThreads +StartServers + + + +NumServers +Total number of children alive at the same time +NumServers number +NumServers 2 +server config +perchild + + +

Number of children alive at the same time. MPMs that use + this directive do not dynamically create new child processes so + this number should be large enough to handle the requests for + the entire site.

+ + + + +ScoreBoardFile +Location of the file used to store coordination data for +the child processes +ScoreBoardFile file-path +ScoreBoardFile logs/apache_status +server config +workerperchild +prefork + + +

The ScoreBoardFile directive is required + on some architectures to place a file that the server will use to + communicate between its children and the parent. The easiest way + to find out if your architecture requires a scoreboard file is to + run Apache and see if it creates the file named by the + directive. If your architecture requires it then you must ensure + that this file is not used at the same time by more than one + invocation of Apache.

+ +

If you have to use a ScoreBoardFile then + you may see improved speed by placing it on a RAM disk. But be + careful that you heed the same warnings about log file placement + and security.

+ +Stopping and Restarting Apache + + + +SendBufferSize +TCP buffer size +SendBufferSize bytes +server config +workerperchild +preforkmpm_winnt + + + +

The server will set the TCP buffer size to the number of bytes + specified. Very useful to increase past standard OS defaults on + high speed high latency (i.e., 100ms or so, such as + transcontinental fast pipes).

+ + + + +ServerLimit +Upper limit on configurable number of processes +ServerLimit number +ServerLimit 256 (prefork), ServerLimit 16 (worker) +server config +workerprefork + + + +

For the prefork MPM, this directive sets the + maximum configured value for MaxClients for the lifetime of the + Apache process. For the worker MPM, this directive in combination + with ThreadLimit sets + the maximum configured value for MaxClients for the lifetime of the + Apache process. Any attempts to change this directive during a + restart will be ignored, but MaxClients can be modified during + a restart.

+ +

Special care must be taken when using this directive. If + ServerLimit is set to a value much higher + than necessary, extra, unused shared memory will be allocated. If + both ServerLimit and MaxClients are set to values + higher than the system can handle, Apache may not start or the + system may become unstable.

+ +

With the prefork MPM, use this directive only + if you need to set MaxClients higher higher than 256. + Do not set the value of this directive any higher than what you + might want to set MaxClients to.

+ +

With the worker MPM, use this directive only + if your MaxClients and + ThreadsPerChild + settings require more than 16 server processes. Do not set the + value of this directive any higher than the number of server + processes required by what you may want for MaxClients and ThreadsPerChild.

+ + + + +StartServers +Number of child server processes created at startup +StartServers number +StartServers 5 +server config +worker + + +

The StartServers directive sets the + number of child server processes created on startup. As the number + of processes is dynamically controlled depending on the load, + there is usually little reason to adjust this parameter.

+ +MinSpareThreads +MaxSpareThreads + + + +StartThreads +Nubmer of threads each child creates on startup +StartThreads number +StartThreads 5 +server config +perchild + + +

Number of threads each child creates on startup. As the + number of threads is dynamically controlled depending on the + load, there is usually little reason to adjust this + parameter.

+ + + + +ThreadLimit +Sets the upper limit on the configurable number of threads +per child process +ThreadLimit number +ThreadLimit 64 +server config +worker + + +

This directive sets the maximum configured value for ThreadsPerChild for the lifetime + of the Apache process. Any attempts to change this directive + during a restart will be ignored, but ThreadsPerChild can be modified + during a restart up to the value of this directive.

+ +

Special care must be taken when using this directive. If + ThreadLimit is set to a value much higher + than ThreadsPerChild, + extra unused shared memory will be allocated. If both + ThreadLimit and ThreadsPerChild are set to values + higher than the system can handle, Apache may not start or the + system may become unstable.

+ +

Use this directive only if you need to set ThreadsPerChild higher than 64. Do + not set the value of this directive any higher than what you might + want to set ThreadsPerChild to.

+ + + + +ThreadsPerChild +Number of threads created by each child process +ThreadsPerChild number +ThreadsPerChild 50 +server config +workermpm_winnt + + + +

This directive sets the number of threads created by each + child process. The child creates these threads at startup and + never creates more. if using an MPM like mpmt_winnt, where + there is only one child process, this number should be high + enough to handle the entire load of the server. If using an MPM + like worker, where there are multiple child processes, the + total number of threads should be high enough to handle the + common load on the server.

+ + + + +User +The userid under which the server will answer +requests +User unix-userid +User #-1 +server configvirtual host + +workerperchild +prefork + + +

The User directive sets the userid as + which the server will answer requests. In order to use this + directive, the standalone server must be run initially as + root. Unix-userid is one of:

+ +
+
A username
+ +
Refers to the given user by name.
+ +
# followed by a user number.
+ +
Refers to a user by their number.
+
+ +

The user should have no privileges which result in it being + able to access files which are not intended to be visible to the + outside world, and similarly, the user should not be able to + execute code which is not meant for httpd requests. It is + recommended that you set up a new user and group specifically for + running the server. Some admins use user nobody, but + this is not always possible or desirable. For example + mod_proxy's cache, when enabled, must be + accessible to this user (see CacheRoot).

+ +

Notes: If you start the server as a non-root user, it will + fail to change to the lesser privileged user, and will instead + continue to run as that original user. If you do start the + server as root, then it is normal for the parent process to + remain running as root.

+ +

Special note: Use of this directive in VirtualHost is no longer supported. To + configure your server for suexec use + SuexecUserGroup.

+ +Security

Don't set User +(or Group) to +root unless you know exactly what you are doing, and what +the dangers are.

 + + + + \ No newline at end of file diff --git a/docs/manual/mod/prefork.xml b/docs/manual/mod/prefork.xml new file mode 100644 index 0000000000..1dd788813b --- /dev/null +++ b/docs/manual/mod/prefork.xml @@ -0,0 +1,207 @@ + + + +prefork +Implements a non-threaded, pre-forking web server +MPM +prefork.c +mpm_prefork_module + + +

This Multi-Processing Module (MPM) implements a + non-threaded, pre-forking web server which handles request in a + manner very similar to the default behavior of Apache 1.3 on + Unix.

+ +

A single control process is responsible for launching child + processes which listen for connections and serve them when they + arrive. Apache always tries to maintain several spare + or idle server processes, which stand ready to serve incoming + requests. In this way, clients do not need to wait for a new + child processes to be forked before their requests can be + served.

+ +

The StartServers, + MinSpareServers, + MaxSpareServers, and + MaxClients regulate how + the parent process creates children to serve requests. In general, + Apache is very self-regulating, so most sites do not need to + adjust these directives from their default values. Sites which + need to serve more than 256 simultaneous requests may need to + increase MaxClients, + while sites with limited memory may need to decrease MaxClients to keep the server from + thrashing (swapping memory to disk and back). More information + about tuning process creation is provided in the performance hints + documentation.

+ +

While the parent process is usually started as root under Unix + in order to bind to port 80, the child processes are launched by + Apache as a less-privileged user. The User and Group directives are used to set + the privileges of the Apache child processes. The child processes + must be able to read all the content that will be served, but + should have as few privileges beyond that as possible. In + addition, unless suexec is used, + these directives also set the privileges which will be inherited + by CGI scripts.

+ +

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

+ +Setting which addresses and + ports Apache uses + + +CoreDumpDirectory + + + +PidFile + + + +Listen + + + +ListenBacklog + + + +LockFile + + + +MaxRequestsPerChild + + + +MaxSpareServers + + + +MinSpareServers + + + +ScoreBoardFile + + + +SendBufferSize + + + +ServerLimit + + + +StartServers + + + +User + + + +AcceptMutex +Method that Apache uses to serialize multiple children +accepting requests on network sockets +AcceptMutex default|method +AcceptMutex default +server config + + +

The AcceptMutex directives sets the + method 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
+ +
uses the flock(2) system call to lock the + file defined by the LockFile directive.
+ +
fcntl
+ +
uses the fnctl(2) system call to lock the + file defined by the LockFile directive.
+ +
sysvsem
+ +
uses SySV-style semaphores to implement the mutex.
+ +
pthread
+ +
uses POSIX mutexes as implemented by the POSIX Threads + (PThreads) specification.
+
+ + + + +MaxSpareServers +Maximum number of idle child server processes +MaxSpareServers number
 +MaxSpareServers 10 +server config + + +

The MaxSpareServers directive sets the + desired maximum number of idle child server processes. An + idle process is one which is not handling a request. If there are + more than MaxSpareServers idle, then the parent process will kill + off the excess processes.

+ +

Tuning of this parameter should only be necessary on very + busy sites. Setting this parameter to a large number is almost + always a bad idea.

+ +MinSpareServers +StartServers + + + +MinSpareServers +Minimum number of idle child server processes +MinSpareServers number +MinSpareServers 5 +server config + + +

The MinSpareServers directive sets the + desired minimum number of idle child server processes. An + idle process is one which is not handling a request. If there are + fewer than MinSpareServers idle, then the parent process creates + new children at a maximum rate of 1 per second.

+ +

Tuning of this parameter should only be necessary on very + busy sites. Setting this parameter to a large number is almost + always a bad idea.

+ +

This directive has no effect on Microsoft Windows.

+ +MaxSpareServers +StartServers + + + + -- 2.50.1