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