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