granicus.if.org Git - apache/blob - docs/manual/mpm.xml

   1 <?xml version='1.0' encoding='UTF-8' ?>
   2 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <manualpage metafile="mpm.xml.meta">
  24
  25   <title>Multi-Processing Modules (MPMs)</title>
  26
  27 <summary>
  28 <p>This document describes what a Multi-Processing Module is and
  29 how they are used by the Apache HTTP Server.</p>
  30 </summary>
  31
  32 <section id="introduction"><title>Introduction</title>
  33
  34     <p>The Apache HTTP Server is designed to be a powerful and
  35     flexible web server that can work on a very wide variety of
  36     platforms in a range of different environments. Different
  37     platforms and different environments often require different
  38     features, or may have different ways of implementing the same
  39     feature most efficiently. Apache httpd has always accommodated a wide
  40     variety of environments through its modular design. This design
  41     allows the webmaster to choose which features will be included
  42     in the server by selecting which modules to load either at
  43     compile-time or at run-time.</p>
  44
  45     <p>Apache HTTP Server 2.0 extends this modular design to the most basic
  46     functions of a web server. The server ships with a selection of
  47     Multi-Processing Modules (MPMs) which are responsible for
  48     binding to network ports on the machine, accepting requests,
  49     and dispatching children to handle the requests.</p>
  50
  51     <p>Extending the modular design to this level of the server
  52     allows two important benefits:</p>
  53
  54     <ul>
  55       <li>Apache httpd can more cleanly and efficiently support a wide
  56       variety of operating systems. In particular, the Windows
  57       version of the server is now much more efficient, since
  58       <module>mpm_winnt</module> can use native
  59       networking features in place of the POSIX layer used in
  60       Apache httpd 1.3. This benefit also extends to other operating
  61       systems that implement specialized MPMs.</li>
  62
  63       <li>The server can be better customized for the needs of the
  64       particular site. For example, sites that need a great deal of
  65       scalability can choose to use a threaded MPM like
  66       <module>worker</module> or <module>event</module>, while sites requiring
  67       stability or compatibility with older software can use a
  68       <module>prefork</module>.</li>
  69     </ul>
  70
  71     <p>At the user level, MPMs appear much like other Apache httpd
  72     modules. The main difference is that one and only one MPM must
  73     be loaded into the server at any time. The list of available
  74     MPMs appears on the <a href="mod/">module index page</a>.</p>
  75
  76 </section>
  77
  78 <section id="defaults"><title>MPM Defaults</title>
  79
  80 <p>The following table lists the default MPMs for various operating
  81 systems.  This will be the MPM selected if you do not make another
  82 choice at compile-time.</p>
  83
  84 <table border="1" style="zebra">
  85 <columnspec><column width=".2"/><column width=".2"/></columnspec>
  86 <tr><td>Netware</td><td><module>mpm_netware</module></td></tr>
  87 <tr><td>OS/2</td><td><module>mpmt_os2</module></td></tr>
  88 <tr><td>Unix</td><td><module>prefork</module>, <module>worker</module>, or
  89     <module>event</module>, depending on platform capabilities</td></tr>
  90 <tr><td>Windows</td><td><module>mpm_winnt</module></td></tr>
  91 </table>
  92
  93 <note><p>Here, 'Unix' is used to mean Unix-like operating systems, such as
  94 Linux, BSD, Solaris, Mac OS X, etc.</p></note>
  95
  96 <p>In the case of Unix, the decision as to which MPM is installed is
  97 based on two questions:</p>
  98 <p>1. Does the system support threads?</p>
  99 <p>2. Does the system support thread-safe polling (Specifically, the
 100 kqueue and epoll functions)?</p>
 101
 102 <p>If the answer to both questions is 'yes', the default MPM is
 103 <module>event</module>.</p>
 104
 105 <p>If The answer to #1 is 'yes', but the answer to #2 is 'no', the
 106 default will be <module>worker</module>.</p>
 107
 108 <p>If the answer to both questions is 'no', then the default MPM will be
 109 <module>prefork</module>.</p>
 110
 111 <p>In practical terms, this means that the default will almost always be
 112 <module>event</module>, as all modern operating systems support these
 113 two features.</p>
 114
 115 </section>
 116
 117 <section id="static"><title>Building an MPM as a static module</title>
 118
 119     <p>MPMs can be built as static modules on all platforms.  A single MPM
 120     is chosen at build time and linked into the server.  The server must
 121     be rebuilt in order to change the MPM.</p>
 122
 123     <p>To override the default MPM choice, use the
 124     <code>--with-mpm=<em>NAME</em></code> option of the
 125     <program>configure</program> script. <em>NAME</em> is the name of the
 126     desired MPM.</p>
 127
 128     <p>Once the server has been compiled, it is possible to determine which MPM
 129     was chosen by using <code>./httpd -l</code>. This command will list every
 130     module that is compiled into the server, including the MPM.</p>
 131
 132 </section>
 133
 134 <section id="dynamic"><title>Building an MPM as a DSO module</title>
 135
 136     <p>On Unix and similar platforms, MPMs can be built as DSO modules and
 137     dynamically loaded into the server in the same manner as other DSO
 138     modules.  Building MPMs as DSO modules allows the MPM to be changed by
 139     updating the <directive module="mod_so">LoadModule</directive> directive
 140     for the MPM instead of by rebuilding the server.</p>
 141
 142     <highlight language="config">
 143     LoadModule mpm_prefork_module modules/mod_mpm_prefork.so
 144     </highlight>
 145
 146     <p>Attempting to <directive module="mod_so">LoadModule</directive>
 147     more than one MPM will result in a startup failure with the
 148     following error.</p>
 149
 150     <example>AH00534: httpd: Configuration error: More than one MPM
 151     loaded.</example>
 152
 153     <p>This feature is enabled using the
 154     <code>--enable-mpms-shared</code> option of the <program>configure</program>
 155     script.
 156     With argument <code><em>all</em></code>, all possible MPMs for the platform
 157     will be installed.  Alternately, a list of MPMs can be specified as the
 158     argument.</p>
 159
 160     <p>The default MPM, either selected automatically or specified with the
 161     <code>--with-mpm</code> option of the <program>configure</program>
 162     script, will be loaded in the generated server configuration file.  Edit the
 163     <directive module="mod_so">LoadModule</directive> directive to select a
 164     different MPM.</p>
 165
 166 </section>
 167
 168 </manualpage>