granicus.if.org Git - apache/blob - docs/manual/mod/perchild.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4
   5 <!--
   6  Copyright 2002-2004 The Apache Software Foundation
   7
   8  Licensed under the Apache License, Version 2.0 (the "License");
   9  you may not use this file except in compliance with the License.
  10  You may obtain a copy of the License at
  11
  12      http://www.apache.org/licenses/LICENSE-2.0
  13
  14  Unless required by applicable law or agreed to in writing, software
  15  distributed under the License is distributed on an "AS IS" BASIS,
  16  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  See the License for the specific language governing permissions and
  18  limitations under the License.
  19 -->
  20
  21 <modulesynopsis metafile="perchild.xml.meta">
  22
  23 <name>perchild</name>
  24 <description>Multi-Processing Module allowing for daemon processes serving
  25 requests to be assigned a variety of different userids</description>
  26 <status>MPM</status>
  27 <sourcefile>perchild.c</sourcefile>
  28 <identifier>mpm_perchild_module</identifier>
  29
  30 <summary>
  31     <note type="warning">
  32       This MPM does not currently work on most platforms.  Work is ongoing
  33       to make it functional.
  34     </note>
  35
  36     <p>This Multi-Processing Module (MPM) implements a hybrid
  37     multi-process, multi-threaded web server. A fixed number of
  38     processes create threads to handle requests. Fluctuations in
  39     load are handled by increasing or decreasing the number of
  40     threads in each process.</p>
  41 </summary>
  42 <seealso><a href="../bind.html">Setting which addresses and ports Apache
  43 uses</a></seealso>
  44
  45 <section id="how-it-works"><title>How it works</title>
  46     <p>A single control process launches the number of child processes
  47     indicated by the <directive module="perchild">NumServers</directive>
  48     directive at server startup. Each child process creates threads as
  49     specified in the <directive module="mpm_common">StartThreads</directive> directive.
  50     The individual threads then
  51     listen for connections and serve them when they arrive.</p>
  52
  53     <p>Apache always tries to maintain a pool of <dfn>spare</dfn> or
  54     idle server threads, which stand ready to serve incoming
  55     requests. In this way, clients do not need to wait for new
  56     threads to be created. For each child process, Apache assesses
  57     the number of idle threads and creates or destroys threads to
  58     keep this number within the boundaries specified by
  59     <directive module="mpm_common">MinSpareThreads</directive>
  60     and <directive module="mpm_common">MaxSpareThreads</directive>.
  61     Since this process is very self-regulating, it is rarely
  62     necessary to modify these directives from their default values.
  63     The maximum number of clients that may be served simultaneously
  64     is determined by multiplying the number of server processes
  65     that will be created (<directive
  66     module="perchild">NumServers</directive>) by the maximum
  67     number of threads created in each process
  68     (<directive module="mpm_common">MaxThreadsPerChild</directive>).</p>
  69
  70     <p>While the parent process is usually started as root under
  71     Unix in order to bind to port 80, the child processes and
  72     threads are launched by Apache as a less-privileged user. The
  73     <directive module="mpm_common">User</directive> and <directive
  74     module="mpm_common">Group</directive> directives are used to
  75     set the privileges of the Apache child processes. The child
  76     processes must be able to read all the content that will be
  77     served, but should have as few privileges beyond that as
  78     possible. In addition, unless <a
  79     href="../suexec.html">suexec</a> is used, these directives also
  80     set the privileges which will be inherited by CGI scripts.</p>
  81
  82     <p><directive module="mpm_common">MaxRequestsPerChild</directive>
  83     controls how frequently the
  84     server recycles processes by killing old ones and launching new
  85     ones.</p>
  86
  87     <section id="user-ids"><title>Working with different user-IDs</title>
  88       <p>The <module>perchild</module> MPM adds the extra ability to
  89       specify that particular processes should serve requests under
  90       different user-IDs. These user-IDs can then be associated with
  91       specific virtual hosts. You have to use one <directive
  92       module="perchild">ChildPerUserID</directive> directive for
  93       every user/group combination you want to be run. Then you can tie
  94       particular virtual hosts to that user and group IDs.</p>
  95
  96       <p>The following example runs 7 child processes. Two of them are run
  97       under <code>user1</code>/<code>group1</code>. The next four are run
  98       under <code>user2</code>/<code>group2</code> and the remaining
  99       process uses the <directive module="mpm_common"
 100       >User</directive> and <directive module="mpm_common">Group</directive>
 101       of the main server:</p>
 102
 103       <example><title>Global config</title>
 104         NumServers 7<br />
 105         ChildPerUserID user1 group1 2<br />
 106         ChildPerUserID user2 group2 4
 107       </example>
 108
 109       <p>Using unbalanced numbers of processes as above is useful, if the
 110       particular virtual hosts produce different load. The assignment to
 111       the virtual hosts is easily done as in the example below. In
 112       conclusion with the example above the following assumes, that
 113       <code>server2</code> has to serve about twice of the hits of
 114       <code>server1</code>.</p>
 115
 116       <example><title>Example</title>
 117         NameVirtualHost *<br />
 118         <br />
 119         &lt;VirtualHost *&gt;<br />
 120         <indent>
 121           ServerName fallbackhost<br />
 122           # no assignment; use fallback<br />
 123         </indent>
 124         &lt;/VirtualHost&gt;<br />
 125         <br />
 126         &lt;VirtualHost *&gt;<br />
 127         <indent>
 128           ServerName server1<br />
 129           AssignUserID user1 group1<br />
 130         </indent>
 131         &lt;/VirtualHost&gt;<br />
 132         <br />
 133         &lt;VirtualHost *&gt;<br />
 134         <indent>
 135           ServerName server2<br />
 136           AssignUserID user2 group2<br />
 137         </indent>
 138         &lt;/VirtualHost&gt;
 139       </example>
 140     </section>
 141 </section>
 142
 143 <directivesynopsis location="mpm_common"><name>AcceptMutex</name>
 144 </directivesynopsis>
 145 <directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
 146 </directivesynopsis>
 147 <directivesynopsis location="mpm_common"><name>Group</name>
 148 </directivesynopsis>
 149 <directivesynopsis location="mpm_common"><name>PidFile</name>
 150 </directivesynopsis>
 151 <directivesynopsis location="mpm_common"><name>Listen</name>
 152 </directivesynopsis>
 153 <directivesynopsis location="mpm_common"><name>ListenBacklog</name>
 154 </directivesynopsis>
 155 <directivesynopsis location="mpm_common"><name>LockFile</name>
 156 </directivesynopsis>
 157 <directivesynopsis location="mpm_common"><name>MaxRequestsPerChild</name>
 158 </directivesynopsis>
 159 <directivesynopsis location="mpm_common"><name>MaxSpareThreads</name>
 160 </directivesynopsis>
 161 <directivesynopsis location="mpm_common"><name>MinSpareThreads</name>
 162 </directivesynopsis>
 163 <directivesynopsis location="mpm_common"><name>ScoreBoardFile</name>
 164 </directivesynopsis>
 165 <directivesynopsis location="mpm_common"><name>SendBufferSize</name>
 166 </directivesynopsis>
 167 <directivesynopsis location="mpm_common"><name>ServerLimit</name>
 168 </directivesynopsis>
 169 <directivesynopsis location="mpm_common"><name>StartThreads</name>
 170 </directivesynopsis>
 171 <directivesynopsis location="mpm_common"><name>ThreadLimit</name>
 172 </directivesynopsis>
 173 <directivesynopsis location="mpm_common"><name>User</name>
 174 </directivesynopsis>
 175
 176 <directivesynopsis>
 177 <name>AssignUserID</name>
 178 <description>Tie a virtual host to a user and group ID</description>
 179 <syntax>AssignUserID <var>user-id</var> <var>group-id</var></syntax>
 180 <contextlist><context>virtual host</context></contextlist>
 181
 182 <usage>
 183     <p>Tie a virtual host to a specific user/group combination. Requests
 184     addressed to the virtual host where this directive appears will be
 185     served by a process running with the specified user and group ID.</p>
 186
 187     <p>The user and group ID has to be assigned to a number of children
 188     in the global server config using the <directive module="perchild"
 189     >ChildPerUserID</directive> directive. See the section above for a
 190     <a href="#user-ids">configuration example</a>.</p>
 191 </usage>
 192 </directivesynopsis>
 193
 194 <directivesynopsis>
 195 <name>ChildPerUserID</name>
 196 <description>Specify user ID and group ID for a number of child
 197 processes</description>
 198 <syntax>ChildPerUserID <var>user-id</var> <var>group-id</var>
 199 <var>num-children</var></syntax>
 200 <contextlist><context>server config</context></contextlist>
 201
 202 <usage>
 203     <p>Specify a user ID and group ID for a number of child processes.
 204     The third argument, <var>num-children</var>, is the number of child
 205     processes to start with the specified user and group. It does
 206     <em>not</em> represent a specific child number. In order to use this
 207     directive, the server must be run initially as <code>root</code>.
 208     If you start the server as a non-root user, it will fail to change
 209     to the lesser privileged user.</p>
 210
 211     <p>If the total number of child processes, found by totaling all of the
 212     third arguments to all <directive>ChildPerUserID</directive> directives
 213     in the config file, is less than <directive module="perchild"
 214     >NumServers</directive>, then all remaining children will inherit the
 215     <directive module="mpm_common">User</directive> and <directive
 216     module="mpm_common">Group</directive> settings from the main server.
 217     See the section above for a <a href="#user-ids">configuration
 218     example</a>.</p>
 219
 220     <note type="warning"><title>Security</title>
 221       <p>Don't set <var>user-id</var> (or <var>group-id</var>) to
 222       <code>root</code> unless you know exactly what you are doing, and
 223       what the dangers are.</p>
 224     </note>
 225 </usage>
 226 </directivesynopsis>
 227
 228 <directivesynopsis>
 229 <name>MaxThreadsPerChild</name>
 230 <description>Maximum number of threads per child process</description>
 231 <syntax>MaxThreadsPerChild <var>number</var></syntax>
 232 <default>MaxThreadsPerChild 64</default>
 233 <contextlist><context>server config</context></contextlist>
 234
 235 <usage>
 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 <directive
 239     module="mpm_common">ThreadLimit</directive> directive and stop and
 240     re-start the server.</p>
 241 </usage>
 242 </directivesynopsis>
 243
 244 <directivesynopsis>
 245 <name>NumServers</name>
 246 <description>Total number of children alive at the same time</description>
 247 <syntax>NumServers <var>number</var></syntax>
 248 <default>NumServers 2</default>
 249 <contextlist><context>server config</context></contextlist>
 250
 251 <usage>
 252     <p>The <directive>NumServers</directive> 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     <directive module="mpm_common">ServerLimit</directive> directive and stop
 257     and re-start the server. See the section above for a <a href="#user-ids"
 258     >configuration example</a>.</p>
 259 </usage>
 260 </directivesynopsis>
 261
 262 </modulesynopsis>