e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding Licensed to the Apache Software Foundation (ASF) under one or more
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding contributor license agreements. See the NOTICE file distributed with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding this work for additional information regarding copyright ownership.
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding The ASF licenses this file to You under the Apache License, Version 2.0
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding (the "License"); you may not use this file except in compliance with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding the License. You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<description>Multi-Processing Module implementing a hybrid
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive multi-threaded multi-process web server</description>
52f786c4400efff1823bbdb062b80718079fc9e4jwoolley <p>This Multi-Processing Module (MPM) implements a hybrid
57758b7ebacbd303cb1c004dd67dd8e5cc1055dbslive multi-process multi-threaded server. By using threads to serve
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive requests, it is able to serve a large number of requests with
57758b7ebacbd303cb1c004dd67dd8e5cc1055dbslive fewer system resources than a process-based server. However, it
7852e17fb37b2a02ccdcab107f2c7f5fd41fd201nd retains much of the stability of a process-based server by
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive keeping multiple processes available, each with many threads.</p>
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive <p>The most important directives used to control this MPM are
f8396ed8364b56ec8adeaa49cac35a929758a29eslive <directive module="mpm_common">ThreadsPerChild</directive>, which
f8396ed8364b56ec8adeaa49cac35a929758a29eslive controls the number of threads deployed by each child process and
3fa816e4832a1c70600bdfd6fc5ef60e9f1c18bbsf <directive module="mpm_common">MaxRequestWorkers</directive>, which
f8396ed8364b56ec8adeaa49cac35a929758a29eslive controls the maximum total number of threads that may be
f8396ed8364b56ec8adeaa49cac35a929758a29eslive launched.</p>
654d8eb036bedc99e90e11910ee02d3421417697rbowen<seealso><a href="/bind.html">Setting which addresses and ports Apache HTTP Server uses</a></seealso>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>A single control process (the parent) is responsible for launching
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick child processes. Each child process creates a fixed number of server
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim threads as specified in the <directive
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick module="mpm_common">ThreadsPerChild</directive> directive, as well
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick as a listener thread which listens for connections and passes them
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick to a server thread for processing when they arrive.</p>
654d8eb036bedc99e90e11910ee02d3421417697rbowen <p>Apache HTTP Server always tries to maintain a pool of <dfn>spare</dfn> or
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive idle server threads, which stand ready to serve incoming
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive requests. In this way, clients do not need to wait for a new
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive threads or processes to be created before their requests can be
9b875a4dfeaf682cae2f428f245743175b0b359bigalic served. The number of processes that will initially launch is
1f5962de2a7436453ab6197268f483f400af0406slive set by the <directive module="mpm_common">StartServers</directive>
654d8eb036bedc99e90e11910ee02d3421417697rbowen directive. During operation, the server assesses the total number
1f5962de2a7436453ab6197268f483f400af0406slive of idle threads in all processes, and forks or kills processes to
1f5962de2a7436453ab6197268f483f400af0406slive keep this number within the boundaries specified by <directive
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive module="mpm_common">MinSpareThreads</directive> and <directive
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive module="mpm_common">MaxSpareThreads</directive>. Since this
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive process is very self-regulating, it is rarely necessary to modify
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive these directives from their default values. The maximum number of
1f5962de2a7436453ab6197268f483f400af0406slive clients that may be served simultaneously (i.e., the maximum total
1f5962de2a7436453ab6197268f483f400af0406slive number of threads in all processes) is determined by the
3fa816e4832a1c70600bdfd6fc5ef60e9f1c18bbsf <directive module="mpm_common">MaxRequestWorkers</directive> directive.
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick The maximum number of active child processes is determined by
3fa816e4832a1c70600bdfd6fc5ef60e9f1c18bbsf the <directive module="mpm_common">MaxRequestWorkers</directive>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick directive divided by the <directive module="mpm_common">
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <p>Two directives set hard limits on the number of active child
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick processes and the number of server threads in a child process,
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim and can only be changed by fully stopping the server and then
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick starting it again. <directive module="mpm_common">ServerLimit
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim </directive> is a hard limit on the number of active child
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim processes, and must be greater than or equal to the
3fa816e4832a1c70600bdfd6fc5ef60e9f1c18bbsf <directive module="mpm_common">MaxRequestWorkers</directive>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick directive divided by the <directive module="mpm_common">
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim ThreadsPerChild</directive> directive.
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <directive module="mpm_common">ThreadLimit</directive> is a hard
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick limit of the number of server threads, and must be greater than
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim or equal to the <directive
4bd465052c4a0c8d41e573ee7a90c312d980355fchrisd module="mpm_common">ThreadsPerChild</directive> directive.</p>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>In addition to the set of active child processes, there may
57758b7ebacbd303cb1c004dd67dd8e5cc1055dbslive be additional child processes which are terminating, but where at
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick least one server thread is still handling an existing client
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim connection. Up to <directive
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim module="mpm_common">MaxRequestWorkers</directive> terminating processes
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim may be present, though the actual number can be expected to be
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim much smaller. This behavior can be avoided by disabling the
57758b7ebacbd303cb1c004dd67dd8e5cc1055dbslive termination of individual child processes, which is achieved using
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick the following:</p>
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <li>set the value of <directive module="mpm_common">
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick <li>set the value of <directive module="mpm_common">
8a6d5edcb07aeccca7afba02a17dd6904d6b206ctrawick MaxSpareThreads</directive> to the same value as
3fa816e4832a1c70600bdfd6fc5ef60e9f1c18bbsf <directive module="mpm_common">MaxRequestWorkers</directive></li>
1f5962de2a7436453ab6197268f483f400af0406slive <p>A typical configuration of the process-thread controls in
1f5962de2a7436453ab6197268f483f400af0406slive the <module>worker</module> MPM could look as follows:</p>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedoohServerLimit 16
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedoohStartServers 2
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedoohMaxRequestWorkers 150
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedoohMinSpareThreads 25
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedoohMaxSpareThreads 75
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedoohThreadsPerChild 25
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
e8d485701957d5c6de870111c112e168a894d49and <p>While the parent process is usually started as <code>root</code>
e8d485701957d5c6de870111c112e168a894d49and under Unix in order to bind to port 80, the child processes and threads
654d8eb036bedc99e90e11910ee02d3421417697rbowen are launched by the server as a less-privileged user. The <directive
4c894c7d7c34890a8984b6cc1bcf6c19f15c4c0aniq module="mod_unixd">Group</directive> directives are used to set
654d8eb036bedc99e90e11910ee02d3421417697rbowen the privileges of the Apache HTTP Server child processes. The child processes
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive must be able to read all the content that will be served, but
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive should have as few privileges beyond that as possible. In
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive these directives also set the privileges which will be inherited
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive by CGI scripts.</p>
be192cefa381d5bae6868034687471754cb43175sf <p><directive module="mpm_common">MaxConnectionsPerChild</directive>
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive controls how frequently the server recycles processes by killing
6f0a2db084bb825acdd2edb2fc98f3fb9c879ef3slive old ones and launching new ones.</p>
bf0e7f6393e91c0a7c15cb0d889a4238c973dc2etrawick <p>This MPM uses the <code>mpm-accept</code> mutex to serialize
bf0e7f6393e91c0a7c15cb0d889a4238c973dc2etrawick access to incoming connections when subject to the thundering herd
bf0e7f6393e91c0a7c15cb0d889a4238c973dc2etrawick problem (generally, when there are multiple listening sockets).
bf0e7f6393e91c0a7c15cb0d889a4238c973dc2etrawick The implementation aspects of this mutex can be configured with the
bf0e7f6393e91c0a7c15cb0d889a4238c973dc2etrawick <directive module="core">Mutex</directive> directive. The <a
bf0e7f6393e91c0a7c15cb0d889a4238c973dc2etrawick documentation has additional information about this mutex.</p>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
e0bc3354c7c500594dae31ba0ae09818c7fd77c0nd<directivesynopsis location="mpm_common"><name>EnableExceptionHook</name>
e0bc3354c7c500594dae31ba0ae09818c7fd77c0nd</directivesynopsis>
4c894c7d7c34890a8984b6cc1bcf6c19f15c4c0aniq<directivesynopsis location="mod_unixd"><name>Group</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<directivesynopsis location="mpm_common"><name>PidFile</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<directivesynopsis location="mpm_common"><name>Listen</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<directivesynopsis location="mpm_common"><name>ListenBacklog</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
3fa816e4832a1c70600bdfd6fc5ef60e9f1c18bbsf<directivesynopsis location="mpm_common"><name>MaxRequestWorkers</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
aec7c8cf914c36561c73aee001924daa6ce7a21btrawick<directivesynopsis location="mpm_common"><name>MaxMemFree</name>
aec7c8cf914c36561c73aee001924daa6ce7a21btrawick</directivesynopsis>
be192cefa381d5bae6868034687471754cb43175sf<directivesynopsis location="mpm_common"><name>MaxConnectionsPerChild</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<directivesynopsis location="mpm_common"><name>MaxSpareThreads</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<directivesynopsis location="mpm_common"><name>MinSpareThreads</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<directivesynopsis location="mpm_common"><name>ScoreBoardFile</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
cc934828f4a719743a3387516f6fa71dd2cc88ffstas<directivesynopsis location="mpm_common"><name>ReceiveBufferSize</name>
cc934828f4a719743a3387516f6fa71dd2cc88ffstas</directivesynopsis>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<directivesynopsis location="mpm_common"><name>SendBufferSize</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<directivesynopsis location="mpm_common"><name>ServerLimit</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<directivesynopsis location="mpm_common"><name>StartServers</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<directivesynopsis location="mpm_common"><name>ThreadLimit</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive<directivesynopsis location="mpm_common"><name>ThreadsPerChild</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
87ffb6e33f3cbef3b9bb406cc2d27039fa336eaatrawick<directivesynopsis location="mpm_common"><name>ThreadStackSize</name>
e6469ad7a7dacf318f7ecf393b448b83ad1fdb37slive</directivesynopsis>
4c894c7d7c34890a8984b6cc1bcf6c19f15c4c0aniq<directivesynopsis location="mod_unixd"><name>User</name>
5598203bfab66b6f93b9d64e49bec79eaaa9f8dftrawick</directivesynopsis>
52f786c4400efff1823bbdb062b80718079fc9e4jwoolley</modulesynopsis>