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