1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>perchild - Apache HTTP Server</title>
9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
14 <div id="page-header">
15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
16 <p class="apache">Apache HTTP Server Version 2.0</p>
17 <img alt="" src="../images/feather.gif" /></div>
18 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
20 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Modules</a></div>
21 <div id="page-content">
22 <div id="preamble"><h1>Apache MPM perchild</h1>
24 <p><span>Available Languages: </span><a href="../en/mod/perchild.html" title="English"> en </a></p>
26 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Multi-Processing Module allowing for daemon processes serving
27 requests to be assigned a variety of different userids</td></tr>
28 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>MPM</td></tr>
29 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>mpm_perchild_module</td></tr>
30 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>perchild.c</td></tr></table>
34 This module is not functional. Development of this module is not
35 complete and is not currently active. Do not use
36 <code class="module"><a href="../mod/perchild.html">perchild</a></code> unless you are a programmer willing to
40 <p>This Multi-Processing Module (MPM) implements a hybrid
41 multi-process, multi-threaded web server. A fixed number of
42 processes create threads to handle requests. Fluctuations in
43 load are handled by increasing or decreasing the number of
44 threads in each process.</p>
46 <div id="quickview"><h3 class="directives">Directives</h3>
48 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#acceptmutex">AcceptMutex</a></li>
49 <li><img alt="" src="../images/down.gif" /> <a href="#assignuserid">AssignUserID</a></li>
50 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#bs2000account">BS2000Account</a></li>
51 <li><img alt="" src="../images/down.gif" /> <a href="#childperuserid">ChildPerUserID</a></li>
52 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li>
53 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#enableexceptionhook">EnableExceptionHook</a></li>
54 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#group">Group</a></li>
55 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#listen">Listen</a></li>
56 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#listenbacklog">ListenBacklog</a></li>
57 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#lockfile">LockFile</a></li>
58 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li>
59 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#maxsparethreads">MaxSpareThreads</a></li>
60 <li><img alt="" src="../images/down.gif" /> <a href="#maxthreadsperchild">MaxThreadsPerChild</a></li>
61 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#minsparethreads">MinSpareThreads</a></li>
62 <li><img alt="" src="../images/down.gif" /> <a href="#numservers">NumServers</a></li>
63 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#pidfile">PidFile</a></li>
64 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#receivebuffersize">ReceiveBufferSize</a></li>
65 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li>
66 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#sendbuffersize">SendBufferSize</a></li>
67 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#serverlimit">ServerLimit</a></li>
68 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#startthreads">StartThreads</a></li>
69 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#threadlimit">ThreadLimit</a></li>
70 <li><img alt="" src="../images/right.gif" /> <a href="mpm_common.html#user">User</a></li>
74 <li><img alt="" src="../images/down.gif" /> <a href="#how-it-works">How it works</a></li>
75 </ul><h3>See also</h3>
77 <li><a href="../bind.html">Setting which addresses and ports Apache
80 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
82 <h2><a name="how-it-works" id="how-it-works">How it works</a></h2>
83 <p>A single control process launches the number of child processes
84 indicated by the <code class="directive"><a href="#numservers">NumServers</a></code>
85 directive at server startup. Each child process creates threads as
86 specified in the <code class="directive"><a href="../mod/mpm_common.html#startthreads">StartThreads</a></code> directive.
87 The individual threads then
88 listen for connections and serve them when they arrive.</p>
90 <p>Apache always tries to maintain a pool of <dfn>spare</dfn> or
91 idle server threads, which stand ready to serve incoming
92 requests. In this way, clients do not need to wait for new
93 threads to be created. For each child process, Apache assesses
94 the number of idle threads and creates or destroys threads to
95 keep this number within the boundaries specified by
96 <code class="directive"><a href="../mod/mpm_common.html#minsparethreads">MinSpareThreads</a></code>
97 and <code class="directive"><a href="../mod/mpm_common.html#maxsparethreads">MaxSpareThreads</a></code>.
98 Since this process is very self-regulating, it is rarely
99 necessary to modify these directives from their default values.
100 The maximum number of clients that may be served simultaneously
101 is determined by multiplying the number of server processes
102 that will be created (<code class="directive"><a href="#numservers">NumServers</a></code>) by the maximum
103 number of threads created in each process
104 (<code class="directive"><a href="../mod/mpm_common.html#maxthreadsperchild">MaxThreadsPerChild</a></code>).</p>
106 <p>While the parent process is usually started as root under
107 Unix in order to bind to port 80, the child processes and
108 threads are launched by Apache as a less-privileged user. The
109 <code class="directive"><a href="../mod/mpm_common.html#user">User</a></code> and <code class="directive"><a href="../mod/mpm_common.html#group">Group</a></code> directives are used to
110 set the privileges of the Apache child processes. The child
111 processes must be able to read all the content that will be
112 served, but should have as few privileges beyond that as
113 possible. In addition, unless <code class="program"><a href="../programs/suexec.html">suexec</a></code> is used,
114 these directives also set the privileges which will be inherited
117 <p><code class="directive"><a href="../mod/mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></code>
118 controls how frequently the
119 server recycles processes by killing old ones and launching new
122 <h3><a name="user-ids" id="user-ids">Working with different user-IDs</a></h3>
123 <p>The <code class="module"><a href="../mod/perchild.html">perchild</a></code> MPM adds the extra ability to
124 specify that particular processes should serve requests under
125 different user-IDs. These user-IDs can then be associated with
126 specific virtual hosts. You have to use one <code class="directive"><a href="#childperuserid">ChildPerUserID</a></code> directive for
127 every user/group combination you want to be run. Then you can tie
128 particular virtual hosts to that user and group IDs.</p>
130 <p>The following example runs 7 child processes. Two of them are run
131 under <code>user1</code>/<code>group1</code>. The next four are run
132 under <code>user2</code>/<code>group2</code> and the remaining
133 process uses the <code class="directive"><a href="../mod/mpm_common.html#user">User</a></code> and <code class="directive"><a href="../mod/mpm_common.html#group">Group</a></code>
134 of the main server:</p>
136 <div class="example"><h3>Global config</h3><p><code>
138 ChildPerUserID user1 group1 2<br />
139 ChildPerUserID user2 group2 4
142 <p>Using unbalanced numbers of processes as above is useful, if the
143 particular virtual hosts produce different load. The assignment to
144 the virtual hosts is easily done as in the example below. In
145 conclusion with the example above the following assumes, that
146 <code>server2</code> has to serve about twice of the hits of
147 <code>server1</code>.</p>
149 <div class="example"><h3>Example</h3><p><code>
150 NameVirtualHost *<br />
152 <VirtualHost *><br />
153 <span class="indent">
154 ServerName fallbackhost<br />
155 # no assignment; use fallback<br />
157 </VirtualHost><br />
159 <VirtualHost *><br />
160 <span class="indent">
161 ServerName server1<br />
162 AssignUserID user1 group1<br />
164 </VirtualHost><br />
166 <VirtualHost *><br />
167 <span class="indent">
168 ServerName server2<br />
169 AssignUserID user2 group2<br />
175 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
176 <div class="directive-section"><h2><a name="AssignUserID" id="AssignUserID">AssignUserID</a> <a name="assignuserid" id="assignuserid">Directive</a></h2>
177 <table class="directive">
178 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Tie a virtual host to a user and group ID</td></tr>
179 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AssignUserID <var>user-id</var> <var>group-id</var></code></td></tr>
180 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>virtual host</td></tr>
181 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>MPM</td></tr>
182 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>perchild</td></tr>
184 <p>Tie a virtual host to a specific user/group combination. Requests
185 addressed to the virtual host where this directive appears will be
186 served by a process running with the specified user and group ID.</p>
188 <p>The user and group ID has to be assigned to a number of children
189 in the global server config using the <code class="directive"><a href="#childperuserid">ChildPerUserID</a></code> directive. See the section above for a
190 <a href="#user-ids">configuration example</a>.</p>
193 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
194 <div class="directive-section"><h2><a name="ChildPerUserID" id="ChildPerUserID">ChildPerUserID</a> <a name="childperuserid" id="childperuserid">Directive</a></h2>
195 <table class="directive">
196 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify user ID and group ID for a number of child
198 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ChildPerUserID <var>user-id</var> <var>group-id</var>
199 <var>num-children</var></code></td></tr>
200 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
201 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>MPM</td></tr>
202 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>perchild</td></tr>
204 <p>Specify a user ID and group ID for a number of child processes.
205 The third argument, <var>num-children</var>, is the number of child
206 processes to start with the specified user and group. It does
207 <em>not</em> represent a specific child number. In order to use this
208 directive, the server must be run initially as <code>root</code>.
209 If you start the server as a non-root user, it will fail to change
210 to the lesser privileged user.</p>
212 <p>If the total number of child processes, found by totaling all of the
213 third arguments to all <code class="directive">ChildPerUserID</code> directives
214 in the config file, is less than <code class="directive"><a href="#numservers">NumServers</a></code>, then all remaining children will inherit the
215 <code class="directive"><a href="../mod/mpm_common.html#user">User</a></code> and <code class="directive"><a href="../mod/mpm_common.html#group">Group</a></code> settings from the main server.
216 See the section above for a <a href="#user-ids">configuration
219 <div class="warning"><h3>Security</h3>
220 <p>Don't set <var>user-id</var> (or <var>group-id</var>) to
221 <code>root</code> unless you know exactly what you are doing, and
222 what the dangers are.</p>
226 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
227 <div class="directive-section"><h2><a name="MaxThreadsPerChild" id="MaxThreadsPerChild">MaxThreadsPerChild</a> <a name="maxthreadsperchild" id="maxthreadsperchild">Directive</a></h2>
228 <table class="directive">
229 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum number of threads per child process</td></tr>
230 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MaxThreadsPerChild <var>number</var></code></td></tr>
231 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>MaxThreadsPerChild 64</code></td></tr>
232 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
233 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>MPM</td></tr>
234 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>perchild</td></tr>
236 <p>This directive sets the maximum number of threads that will be
237 created in each child process. To increase this value beyond its
238 default, it is necessary to change the value of the <code class="directive"><a href="../mod/mpm_common.html#threadlimit">ThreadLimit</a></code> directive and stop and
239 re-start the server.</p>
242 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
243 <div class="directive-section"><h2><a name="NumServers" id="NumServers">NumServers</a> <a name="numservers" id="numservers">Directive</a></h2>
244 <table class="directive">
245 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Total number of children alive at the same time</td></tr>
246 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>NumServers <var>number</var></code></td></tr>
247 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>NumServers 2</code></td></tr>
248 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
249 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>MPM</td></tr>
250 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>perchild</td></tr>
252 <p>The <code class="directive">NumServers</code> directive determines the number
253 of children alive at the same time. This number should be large enough to
254 handle the requests for the entire site. To increase this value beyond the
255 value of <code>8</code>, it is necessary to change the value of the
256 <code class="directive"><a href="../mod/mpm_common.html#serverlimit">ServerLimit</a></code> directive and stop
257 and re-start the server. See the section above for a <a href="#user-ids">configuration example</a>.</p>
261 <div class="bottomlang">
262 <p><span>Available Languages: </span><a href="../en/mod/perchild.html" title="English"> en </a></p>
263 </div><div id="footer">
264 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
265 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>