09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<?xml version="1.0"?>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<modulesynopsis metafile="worker.xml.meta">

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<name>worker</name>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<description>Multi-Processing Module implementing a hybrid

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding multi-threaded multi-process web server</description>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<status>MPM</status>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<sourcefile>worker.c</sourcefile>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<identifier>mpm_worker_module</identifier>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<summary>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>This Multi-Processing Module (MPM) implements a hybrid

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding multi-process multi-threaded server. By using threads to serve

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding requests, it is able to serve a large number of requests with

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding fewer system resources than a process-based server. However, it

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding retains much of the stability of a process-based server by

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding keeping multiple processes available, each with many threads.</p>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>The most important directives used to control this MPM are

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <directive module="mpm_common">ThreadsPerChild</directive>, which

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding controls the number of threads deployed by each child process and

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <directive module="mpm_common">MaxClients</directive>, which

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding controls the maximum total number of threads that may be

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding launched.</p>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding</summary>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<seealso><a href="/bind.html">Setting which addresses and ports Apache

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldinguses</a></seealso>

ec59f4e92f66631ee3266c0d416a01ac92bdf06cstoddard

ec59f4e92f66631ee3266c0d416a01ac92bdf06cstoddard<section id="how-it-works"><title>How it Works</title>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>A single control process (the parent) is responsible for launching

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding child processes. Each child process creates a fixed number of server

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding threads as specified in the <directive

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding module="mpm_common">ThreadsPerChild</directive> directive, as well

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding as a listener thread which listens for connections and passes them

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding to a server thread for processing when they arrive.</p>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>Apache always tries to maintain a pool of <dfn>spare</dfn> or

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding idle server threads, which stand ready to serve incoming

4cff088e460b3832142e59c63b357f8cf4d77fa8ake requests. In this way, clients do not need to wait for a new

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding threads or processes to be created before their requests can be

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding served. The number of processes that will initially launched is

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding set by the <directive module="mpm_common">StartServers</directive>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding directive. During operation, Apache assesses the total number

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding of idle threads in all processes, and forks or kills processes to

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding keep this number within the boundaries specified by <directive

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding module="mpm_common">MinSpareThreads</directive> and <directive

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding module="mpm_common">MaxSpareThreads</directive>. Since this

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding process is very self-regulating, it is rarely necessary to modify

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding these directives from their default values. The maximum number of

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding clients that may be served simultaneously (i.e., the maximum total

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding number of threads in all processes) is determined by the

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <directive module="mpm_common">MaxClients</directive> directive.

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding The maximum number of active child processes is determined by

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding the <directive module="mpm_common">MaxClients</directive>

ec59f4e92f66631ee3266c0d416a01ac92bdf06cstoddard directive divided by the <directive module="mpm_common">

ec59f4e92f66631ee3266c0d416a01ac92bdf06cstoddard ThreadsPerChild</directive> directive.</p>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>Two directives set hard limits on the number of active child

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding processes and the number of server threads in a child process,

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding and can only be changed by fully stopping the server and then

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding starting it again. <directive module="mpm_common">ServerLimit

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding </directive> is a hard limit on the number of active child

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding processes, and must be greater than or equal to the

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <directive module="mpm_common">MaxClients</directive>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding directive divided by the <directive module="mpm_common">

4cff088e460b3832142e59c63b357f8cf4d77fa8ake ThreadsPerChild</directive> directive.

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <directive module="mpm_common">ThreadLimit</directive> is a hard

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding limit of the number of server threads, and must be greater than

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding or equal to the <directive

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding module="mpm_common">ThreadsPerChild</directive> directive.</p>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>In addition to the set of active child processes, there may

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding be additional child processes which are terminating, but where at

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding least one server thread is still handling an existing client

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding connection. Up to <directive

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding module="mpm_common">MaxClients</directive> terminating processes

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding may be present, though the actual number can be expected to be

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding much smaller. This behavior can be avoided by disabling the

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding termination of individual child processes, which is achieved using

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding the following:</p>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <ul>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <li>set the value of <directive module="mpm_common">

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding MaxRequestsPerChild</directive> to zero</li>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <li>set the value of <directive module="mpm_common">

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding MaxSpareThreads</directive> to the same value as

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <directive module="mpm_common">MaxClients</directive></li>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding </ul>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>A typical configuration of the process-thread controls in

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding the <module>worker</module> MPM could look as follows:</p>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <example>

09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding ServerLimit 16<br />

StartServers 2<br />

MaxClients 150<br />

MinSpareThreads 25<br />

MaxSpareThreads 75<br />

ThreadsPerChild 25

</example>

<p>While the parent process is usually started as <code>root</code>

under Unix in order to bind to port 80, the child processes and threads

are launched by Apache as a less-privileged user. The <directive

module="mod_unixd">User</directive> and <directive

module="mod_unixd">Group</directive> 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 <program>suexec</program> is used,

these directives also set the privileges which will be inherited

by CGI scripts.</p>

<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>EnableExceptionHook</name>

</directivesynopsis>

<directivesynopsis location="mod_unixd"><name>Group</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>PidFile</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>Listen</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ListenBacklog</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>MaxClients</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>MaxMemFree</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>MaxRequestsPerChild</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>MaxSpareThreads</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>MinSpareThreads</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ScoreBoardFile</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ReceiveBufferSize</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>SendBufferSize</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ServerLimit</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>StartServers</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ThreadLimit</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ThreadsPerChild</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ThreadStackSize</name>

</directivesynopsis>

<directivesynopsis location="mod_unixd"><name>User</name>

</directivesynopsis>

</modulesynopsis>