home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F278402_perchild.xml < prev    next >
Extensible Markup Language  |  2004-04-17  |  12KB  |  270 lines
  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.6.2.7 $ -->
  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.         <VirtualHost *><br />
  123.         <indent>
  124.           ServerName fallbackhost<br />
  125.           # no assignment; use fallback<br />
  126.         </indent>
  127.         </VirtualHost><br />
  128.         <br />
  129.         <VirtualHost *><br />
  130.         <indent>
  131.           ServerName server1<br />
  132.           AssignUserID user1 group1<br />
  133.         </indent>
  134.         </VirtualHost><br />
  135.         <br />
  136.         <VirtualHost *><br />
  137.         <indent>
  138.           ServerName server2<br />
  139.           AssignUserID user2 group2<br />
  140.         </indent>
  141.         </VirtualHost>
  142.       </example>
  143.     </section>
  144. </section>
  145.  
  146. <directivesynopsis location="mpm_common"><name>AcceptMutex</name>
  147. </directivesynopsis>
  148. <directivesynopsis location="mpm_common"><name>BS2000Account</name>
  149. </directivesynopsis>
  150. <directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
  151. </directivesynopsis>
  152. <directivesynopsis location="mpm_common"><name>EnableExceptionHook</name>
  153. </directivesynopsis>
  154. <directivesynopsis location="mpm_common"><name>Group</name>
  155. </directivesynopsis>
  156. <directivesynopsis location="mpm_common"><name>PidFile</name>
  157. </directivesynopsis>
  158. <directivesynopsis location="mpm_common"><name>Listen</name>
  159. </directivesynopsis>
  160. <directivesynopsis location="mpm_common"><name>ListenBacklog</name>
  161. </directivesynopsis>
  162. <directivesynopsis location="mpm_common"><name>LockFile</name>
  163. </directivesynopsis>
  164. <directivesynopsis location="mpm_common"><name>MaxRequestsPerChild</name>
  165. </directivesynopsis>
  166. <directivesynopsis location="mpm_common"><name>MaxSpareThreads</name>
  167. </directivesynopsis>
  168. <directivesynopsis location="mpm_common"><name>MinSpareThreads</name>
  169. </directivesynopsis>
  170. <directivesynopsis location="mpm_common"><name>ScoreBoardFile</name>
  171. </directivesynopsis>
  172. <directivesynopsis location="mpm_common"><name>SendBufferSize</name>
  173. </directivesynopsis>
  174. <directivesynopsis location="mpm_common"><name>ServerLimit</name>
  175. </directivesynopsis>
  176. <directivesynopsis location="mpm_common"><name>StartThreads</name>
  177. </directivesynopsis>
  178. <directivesynopsis location="mpm_common"><name>ThreadLimit</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>
  270.