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