perchild.xml revision 68cd30d6fb171881925dff9669d04affea29d2b7
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<!-- $Revision: 1.16 $ -->
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd Copyright 2002-2004 The Apache Software Foundation
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd Licensed under the Apache License, Version 2.0 (the "License");
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd you may not use this file except in compliance with the License.
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd You may obtain a copy of the License at
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd Unless required by applicable law or agreed to in writing, software
27e52281f1522522b170cafc76b08b58aa70ccaand distributed under the License is distributed on an "AS IS" BASIS,
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd See the License for the specific language governing permissions and
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd limitations under the License.
ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd<description>Multi-Processing Module allowing for daemon processes serving
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjungrequests to be assigned a variety of different userids</description>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd This module is not functional. Development of this module is not
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd complete and is not currently active. Do not use
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <module>perchild</module> unless you are a programmer willing to
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd help fix it.
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>This Multi-Processing Module (MPM) implements a hybrid
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd multi-process, multi-threaded web server. A fixed number of
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd processes create threads to handle requests. Fluctuations in
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd load are handled by increasing or decreasing the number of
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd threads in each process.</p>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<seealso><a href="/bind.html">Setting which addresses and ports Apache
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>A single control process launches the number of child processes
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd indicated by the <directive module="perchild">NumServers</directive>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd directive at server startup. Each child process creates threads as
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd specified in the <directive module="mpm_common">StartThreads</directive> directive.
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd The individual threads then
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd listen for connections and serve them when they arrive.</p>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>Apache always tries to maintain a pool of <dfn>spare</dfn> or
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd idle server threads, which stand ready to serve incoming
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd requests. In this way, clients do not need to wait for new
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd threads to be created. For each child process, Apache assesses
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd the number of idle threads and creates or destroys threads to
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd keep this number within the boundaries specified by
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <directive module="mpm_common">MinSpareThreads</directive>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd and <directive module="mpm_common">MaxSpareThreads</directive>.
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd Since this process is very self-regulating, it is rarely
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd necessary to modify these directives from their default values.
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd The maximum number of clients that may be served simultaneously
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd is determined by multiplying the number of server processes
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd that will be created (<directive
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd number of threads created in each process
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd (<directive module="mpm_common">MaxThreadsPerChild</directive>).</p>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>While the parent process is usually started as root under
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd Unix in order to bind to port 80, the child processes and
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd threads are launched by Apache as a less-privileged user. The
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <directive module="mpm_common">User</directive> and <directive
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd module="mpm_common">Group</directive> directives are used to
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd set the privileges of the Apache child processes. The child
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd processes must be able to read all the content that will be
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd served, but should have as few privileges beyond that as
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd possible. In addition, unless <a
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd href="/suexec.html">suexec</a> is used, these directives also
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd set the privileges which will be inherited by CGI scripts.</p>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p><directive module="mpm_common">MaxRequestsPerChild</directive>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd controls how frequently the
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd server recycles processes by killing old ones and launching new
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <section id="user-ids"><title>Working with different user-IDs</title>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>The <module>perchild</module> MPM adds the extra ability to
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd specify that particular processes should serve requests under
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd different user-IDs. These user-IDs can then be associated with
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd specific virtual hosts. You have to use one <directive
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd module="perchild">ChildPerUserID</directive> directive for
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd every user/group combination you want to be run. Then you can tie
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd particular virtual hosts to that user and group IDs.</p>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>The following example runs 7 child processes. Two of them are run
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd under <code>user1</code>/<code>group1</code>. The next four are run
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd under <code>user2</code>/<code>group2</code> and the remaining
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd >User</directive> and <directive module="mpm_common">Group</directive>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd of the main server:</p>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd NumServers 7<br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd ChildPerUserID user1 group1 2<br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd ChildPerUserID user2 group2 4
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd </example>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>Using unbalanced numbers of processes as above is useful, if the
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd particular virtual hosts produce different load. The assignment to
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd the virtual hosts is easily done as in the example below. In
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd conclusion with the example above the following assumes, that
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <code>server2</code> has to serve about twice of the hits of
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd NameVirtualHost *<br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <VirtualHost *><br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd ServerName fallbackhost<br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd # no assignment; use fallback<br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd </VirtualHost><br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <VirtualHost *><br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd ServerName server1<br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd AssignUserID user1 group1<br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd </VirtualHost><br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <VirtualHost *><br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd ServerName server2<br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd AssignUserID user2 group2<br />
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd </VirtualHost>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd </example>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd </section>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>AcceptMutex</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>EnableExceptionHook</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>Group</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>PidFile</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>Listen</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>ListenBacklog</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>LockFile</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>MaxRequestsPerChild</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>MaxSpareThreads</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>MinSpareThreads</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>ScoreBoardFile</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>SendBufferSize</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>ServerLimit</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>StartThreads</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>ThreadLimit</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>ThreadStackSize</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis location="mpm_common"><name>User</name>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<description>Tie a virtual host to a user and group ID</description>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<syntax>AssignUserID <var>user-id</var> <var>group-id</var></syntax>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<contextlist><context>virtual host</context></contextlist>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>Tie a virtual host to a specific user/group combination. Requests
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd addressed to the virtual host where this directive appears will be
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd served by a process running with the specified user and group ID.</p>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>The user and group ID has to be assigned to a number of children
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd in the global server config using the <directive module="perchild"
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd >ChildPerUserID</directive> directive. See the section above for a
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<description>Specify user ID and group ID for a number of child
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bndprocesses</description>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<syntax>ChildPerUserID <var>user-id</var> <var>group-id</var>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<contextlist><context>server config</context></contextlist>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>Specify a user ID and group ID for a number of child processes.
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd The third argument, <var>num-children</var>, is the number of child
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd processes to start with the specified user and group. It does
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <em>not</em> represent a specific child number. In order to use this
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd directive, the server must be run initially as <code>root</code>.
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd If you start the server as a non-root user, it will fail to change
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd to the lesser privileged user.</p>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>If the total number of child processes, found by totaling all of the
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd third arguments to all <directive>ChildPerUserID</directive> directives
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd in the config file, is less than <directive module="perchild"
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd >NumServers</directive>, then all remaining children will inherit the
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <directive module="mpm_common">User</directive> and <directive
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd module="mpm_common">Group</directive> settings from the main server.
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd See the section above for a <a href="#user-ids">configuration
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>Don't set <var>user-id</var> (or <var>group-id</var>) to
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <code>root</code> unless you know exactly what you are doing, and
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd what the dangers are.</p>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<description>Maximum number of threads per child process</description>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<contextlist><context>server config</context></contextlist>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <p>This directive sets the maximum number of threads that will be
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd created in each child process. To increase this value beyond its
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd default, it is necessary to change the value of the <directive
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd module="mpm_common">ThreadLimit</directive> directive and stop and
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd re-start the server.</p>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd</directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<directivesynopsis>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<description>Total number of children alive at the same time</description>
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd<contextlist><context>server config</context></contextlist>
ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd <p>The <directive>NumServers</directive> directive determines the number
ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd of children alive at the same time. This number should be large enough to
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung handle the requests for the entire site. To increase this value beyond the
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd value of <code>8</code>, it is necessary to change the value of the
9c1260efa52c82c2a58e5b5f20cd6902563d95f5rbowen <directive module="mpm_common">ServerLimit</directive> directive and stop
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd and re-start the server. See the section above for a <a href="#user-ids"