rubbos/app/httpd-2.0.64/docs/manual/mod/perchild.html.en

   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
   7       -->
   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>
  13 <body>
  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="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.0</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache MPM perchild</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/perchild.html" title="English">&nbsp;en&nbsp;</a></p>
  25 </div>
  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>
  31 <h3>Summary</h3>
  32
  33     <div class="warning">
  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
  37       help fix it.
  38     </div>
  39
  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>
  45 </div>
  46 <div id="quickview"><h3 class="directives">Directives</h3>
  47 <ul id="toc">
  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>
  71 </ul>
  72 <h3>Topics</h3>
  73 <ul id="topics">
  74 <li><img alt="" src="../images/down.gif" /> <a href="#how-it-works">How it works</a></li>
  75 </ul><h3>See also</h3>
  76 <ul class="seealso">
  77 <li><a href="../bind.html">Setting which addresses and ports Apache
  78 uses</a></li>
  79 </ul></div>
  80 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  81 <div class="section">
  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>
  89
  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>
 105
 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
 115     by CGI scripts.</p>
 116
 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
 120     ones.</p>
 121
 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>
 129
 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>
 135
 136       <div class="example"><h3>Global config</h3><p><code>
 137         NumServers 7<br />
 138         ChildPerUserID user1 group1 2<br />
 139         ChildPerUserID user2 group2 4
 140       </code></p></div>
 141
 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>
 148
 149       <div class="example"><h3>Example</h3><p><code>
 150         NameVirtualHost *<br />
 151         <br />
 152         &lt;VirtualHost *&gt;<br />
 153         <span class="indent">
 154           ServerName fallbackhost<br />
 155           # no assignment; use fallback<br />
 156         </span>
 157         &lt;/VirtualHost&gt;<br />
 158         <br />
 159         &lt;VirtualHost *&gt;<br />
 160         <span class="indent">
 161           ServerName server1<br />
 162           AssignUserID user1 group1<br />
 163         </span>
 164         &lt;/VirtualHost&gt;<br />
 165         <br />
 166         &lt;VirtualHost *&gt;<br />
 167         <span class="indent">
 168           ServerName server2<br />
 169           AssignUserID user2 group2<br />
 170         </span>
 171         &lt;/VirtualHost&gt;
 172       </code></p></div>
 173
 174 </div>
 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>
 183 </table>
 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>
 187
 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>
 191
 192 </div>
 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
 197 processes</td></tr>
 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>
 203 </table>
 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>
 211
 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
 217     example</a>.</p>
 218
 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>
 223     </div>
 224
 225 </div>
 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>
 235 </table>
 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>
 240
 241 </div>
 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>
 251 </table>
 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>
 258
 259 </div>
 260 </div>
 261 <div class="bottomlang">
 262 <p><span>Available Languages: </span><a href="../en/mod/perchild.html" title="English">&nbsp;en&nbsp;</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>
 266 </body></html>