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.xsl"?>
   4 <modulesynopsis>
   5
   6 <name>perchild</name>
   7 <description>Multi-Processing Module allowing for daemon processes
   8     serving requests to be assigned a variety of different
   9     userids</description>
  10 <status>MPM</status>
  11 <sourcefile>perchild.c</sourcefile>
  12 <identifier>mpm_perchild_module</identifier>
  13
  14 <summary>
  15 <note type="warning">
  16 This MPM does not currently work on most platforms.  Work is ongoing to
  17 make it functional.
  18 </note>
  19
  20     <p>This Multi-Processing Module (MPM) implements a hybrid
  21     multi-process, multi-threaded web server. A fixed number of
  22     processes create threads to handle requests. Fluctuations in
  23     load are handled by increasing or decreasing the number of
  24     threads in each process.</p>
  25
  26     <p>A single control process launches the number of child processes
  27     indicated by the <directive
  28     module="mpm_common">NumServers</directive> directive at server
  29     startup. Each child process creates threads as specified in the
  30     <code>StartThreads</code> directive. The individual threads then
  31     listen for connections and serve them when they arrive.</p>
  32
  33     <p>Apache always tries to maintain a pool of <em>spare</em> or
  34     idle server threads, which stand ready to serve incoming
  35     requests. In this way, clients do not need to wait for new
  36     threads to be created. For each child process, Apache assesses
  37     the number of idle threads and creates or destroys threads to
  38     keep this number within the boundaries specified by
  39     <code>MinSpareThreads</code> and <code>MaxSpareThreads</code>.
  40     Since this process is very self-regulating, it is rarely
  41     necessary to modify these directives from their default values.
  42     The maximum number of clients that may be served simultaneously
  43     is determined by multiplying the number of server processes
  44     that will be created (<code>NumServers</code>) by the maximum
  45     number of threads created in each process
  46     (<code>MaxThreadsPerChild</code>).</p>
  47
  48     <p>While the parent process is usually started as root under
  49     Unix in order to bind to port 80, the child processes and
  50     threads are launched by Apache as a less-privileged user. The
  51     <code>User</code> and <code>Group</code> directives are used to
  52     set the privileges of the Apache child processes. The child
  53     processes must be able to read all the content that will be
  54     served, but should have as few privileges beyond that as
  55     possible. In addition, unless <a
  56     href="../suexec.html">suexec</a> is used, these directives also
  57     set the privileges which will be inherited by CGI scripts.</p>
  58
  59     <p><code>MaxRequestsPerChild</code> controls how frequently the
  60     server recycles processes by killing old ones and launching new
  61     ones.</p>
  62
  63     <p>See also: <a href="../bind.html">Setting which addresses and
  64     ports Apache uses</a>.</p>
  65
  66     <p>In addition it adds the extra ability to specify that
  67     specific processes should serve requests under different
  68     userids. These processes can then be associated with specific
  69     virtual hosts.</p>
  70     <!-- XXX: This desperately needs more explanation. -->
  71 </summary>
  72
  73 <directivesynopsis location="mpm_common">
  74 <name>CoreDumpDirectory</name>
  75 </directivesynopsis>
  76 <directivesynopsis location="mpm_common">
  77 <name>Group</name>
  78 </directivesynopsis>
  79 <directivesynopsis location="mpm_common">
  80 <name>PidFile</name>
  81 </directivesynopsis>
  82 <directivesynopsis location="mpm_common">
  83 <name>Listen</name>
  84 </directivesynopsis>
  85 <directivesynopsis location="mpm_common">
  86 <name>ListenBacklog</name>
  87 </directivesynopsis>
  88 <directivesynopsis location="mpm_common">
  89 <name>LockFile</name>
  90 </directivesynopsis>
  91 <directivesynopsis location="mpm_common">
  92 <name>MaxRequestsPerChild</name>
  93 </directivesynopsis>
  94 <directivesynopsis location="mpm_common">
  95 <name>MaxSpareThreads</name>
  96 </directivesynopsis>
  97 <directivesynopsis location="mpm_common">
  98 <name>MaxThreadsPerChild</name>
  99 </directivesynopsis>
 100 <directivesynopsis location="mpm_common">
 101 <name>MinSpareThreads</name>
 102 </directivesynopsis>
 103 <directivesynopsis location="mpm_common">
 104 <name>NumServers</name>
 105 </directivesynopsis>
 106 <directivesynopsis location="mpm_common">
 107 <name>ScoreBoardFile</name>
 108 </directivesynopsis>
 109 <directivesynopsis location="mpm_common">
 110 <name>SendBufferSize</name>
 111 </directivesynopsis>
 112 <directivesynopsis location="mpm_common">
 113 <name>StartThreads</name>
 114 </directivesynopsis>
 115 <directivesynopsis location="mpm_common">
 116 <name>User</name>
 117 </directivesynopsis>
 118
 119 <directivesynopsis>
 120 <name>AssignUserId</name>
 121 <syntax>AssignUserID <em>user_id</em> <em>group_id</em></syntax>
 122 <contextlist><context>virtual host</context></contextlist>
 123
 124 <usage>
 125     <p>Tie a virtual host to a specific child process. Requests addressed to
 126 the virtual host where this directive appears will be served by the process
 127 running with the specified user and group id.</p>
 128 </usage>
 129 </directivesynopsis>
 130
 131 <directivesynopsis>
 132 <name>ChildPerUserId</name>
 133 <syntax>ChildPerUserID <em>user_id</em>
 134 <em>group_id</em> <em>child_id</em></syntax>
 135 <contextlist><context>server config</context></contextlist>
 136
 137 <usage>
 138     <p>Specify a user id and group id for a specific child process. The number of
 139 children if set by the <a href="mpm_common.html#numservers">NumServers</a>
 140 directive. For example, the default value for <a
 141 href="mpm_common.html#numservers">NumServers</a> is 5 and that means
 142 children ids 1,2,3,4 and 5 are available for assigment. If a child does not
 143 have an associated ChildPerUserID, it inherits the <a
 144 href="mpm_common.html#user">User</a> and <a
 145 href="mpm_common.html#group">Group</a> settings from the main server </p>
 146 </usage>
 147 </directivesynopsis>
 148
 149 </modulesynopsis>
 150