2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
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
14 http://www.apache.org/licenses/LICENSE-2.0
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.
23 <modulesynopsis metafile="mpm_common.xml.meta">
25 <name>mpm_common</name>
26 <description>A collection of directives that are implemented by
27 more than one multi-processing module (MPM)</description>
31 <name>CoreDumpDirectory</name>
32 <description>Directory where Apache HTTP Server attempts to
33 switch before dumping core</description>
34 <syntax>CoreDumpDirectory <var>directory</var></syntax>
35 <default>See usage for the default setting</default>
36 <contextlist><context>server config</context></contextlist>
37 <modulelist><module>event</module><module>worker</module>
38 <module>prefork</module></modulelist>
41 <p>This controls the directory to which Apache httpd attempts to
42 switch before dumping core. If your operating system is configured to
43 create core files in the working directory of the crashing process,
44 <directive>CoreDumpDirectory</directive> is necessary to change working
45 directory from the default <directive module="core">ServerRoot</directive>
46 directory, which should not be writable by the user the server runs as.</p>
48 <p>If you want a core dump for debugging, you can use this directive to
49 place it in a different location. This directive has no effect if your
50 operating system is not configured to write core files to the working directory
51 of the crashing processes.</p>
53 <note><title>Core Dumps on Linux</title>
54 <p>If Apache httpd starts as root and switches to another user, the
55 Linux kernel <em>disables</em> core dumps even if the directory is
56 writable for the process. Apache httpd (2.0.46 and later) reenables core dumps
57 on Linux 2.4 and beyond, but only if you explicitly configure a <directive
58 >CoreDumpDirectory</directive>.</p>
62 <title>Core Dumps on BSD</title>
63 <p>To enable core-dumping of suid-executables on BSD-systems (such
64 as FreeBSD), set <code>kern.sugid_coredump</code> to 1.
68 <note><title>Specific signals</title>
69 <p><directive>CoreDumpDirectory</directive> processing only occurs for
70 a select set of fatal signals: SIGFPE, SIGILL, SIGABORT,
71 SIGSEGV, and SIGBUS.</p>
72 <p>On some operating systems, SIGQUIT also results in a core dump but
73 does not go through <directive>CoreDumpDirectory</directive> or
74 <directive>EnableExceptionHook</directive> processing, so the core
75 location is dictated entirely by the operating system.</p>
82 <name>EnableExceptionHook</name>
83 <description>Enables a hook that runs exception handlers
84 after a crash</description>
85 <syntax>EnableExceptionHook On|Off</syntax>
86 <default>EnableExceptionHook Off</default>
87 <contextlist><context>server config</context></contextlist>
89 <module>event</module><module>worker</module>
90 <module>prefork</module></modulelist>
93 <p>For safety reasons this directive is only available if the server was
94 configured with the <code>--enable-exception-hook</code> option. It
95 enables a hook that allows external modules to plug in and do something
96 after a child crashed.</p>
98 <p>There are already two modules, <code>mod_whatkilledus</code> and
99 <code>mod_backtrace</code> that make use of this hook. Please have a
100 look at Jeff Trawick's <a
101 href="http://people.apache.org/~trawick/exception_hook.html"
102 >EnableExceptionHook site</a> for more information about these.</p>
107 <name>GracefulShutdownTimeout</name>
108 <description>Specify a timeout after which a gracefully shutdown server
109 will exit.</description>
110 <syntax>GracefulShutdownTimeout <var>seconds</var></syntax>
111 <default>GracefulShutdownTimeout 0</default>
112 <contextlist><context>server config</context></contextlist>
113 <modulelist><module>event</module><module>worker</module>
114 <module>prefork</module></modulelist>
117 <p>The <directive>GracefulShutdownTimeout</directive> specifies
118 how many seconds after receiving a "graceful-stop" signal, a
119 server should continue to run, handling the existing connections.</p>
121 <p>Setting this value to zero means that the server will wait
122 indefinitely until all remaining requests have been fully served.</p>
128 <description>File where the server records the process ID
129 of the daemon</description>
130 <syntax>PidFile <var>filename</var></syntax>
131 <default>PidFile httpd.pid</default>
132 <contextlist><context>server config</context></contextlist>
133 <modulelist><module>event</module><module>worker</module>
134 <module>prefork</module><module>mpm_winnt</module>
135 <module>mpmt_os2</module>
139 <p>The <directive>PidFile</directive> directive sets the file to
140 which the server records the process id of the daemon. If the
141 filename is not absolute then it is assumed to be relative to the
142 <directive module="core">DefaultRuntimeDir</directive>.</p>
144 <example><title>Example</title>
145 <highlight language="config">
146 PidFile /var/run/apache.pid
150 <p>It is often useful to be able to send the server a signal,
151 so that it closes and then re-opens its <directive
152 module="core">ErrorLog</directive> and <directive
153 module="mod_log_config">TransferLog</directive>, and
154 re-reads its configuration files. This is done by sending a
155 SIGHUP (kill -1) signal to the process id listed in the
156 <directive>PidFile</directive>.</p>
158 <p>The <directive>PidFile</directive> is subject to the same
159 warnings about log file placement and <a
160 href="../misc/security_tips.html#serverroot">security</a>.</p>
162 <note><title>Note</title>
163 <p>As of Apache HTTP Server 2, we recommended that you only use the <program>
164 apachectl</program> script, or the init script that your OS provides,
165 for (re-)starting or stopping the server.</p>
172 <description>IP addresses and ports that the server
173 listens to</description>
174 <syntax>Listen [<var>IP-address</var>:]<var>portnumber</var> [<var>protocol</var>]</syntax>
175 <contextlist><context>server config</context></contextlist>
176 <modulelist><module>event</module><module>worker</module>
177 <module>prefork</module><module>mpm_winnt</module>
178 <module>mpm_netware</module><module>mpmt_os2</module>
182 <p>The <directive>Listen</directive> directive instructs Apache httpd to
183 listen to only specific IP addresses or ports; by default it
184 responds to requests on all IP interfaces. <directive>Listen</directive>
185 is now a required directive. If it is not in the config file, the
186 server will fail to start. This is a change from previous versions
189 <p>The <directive>Listen</directive> directive tells the server to
190 accept incoming requests on the specified port or address-and-port
191 combination. If only a port number is specified, the server listens to
192 the given port on all interfaces. If an IP address is given as well
193 as a port, the server will listen on the given port and
196 <p>Multiple <directive>Listen</directive> directives may be used to
197 specify a number of addresses and ports to listen to. The server will
198 respond to requests from any of the listed addresses and ports.</p>
200 <p>For example, to make the server accept connections on both
201 port 80 and port 8000, use:</p>
203 <highlight language="config">
208 <p>To make the server accept connections on two specified
209 interfaces and port numbers, use </p>
211 <highlight language="config">
212 Listen 192.170.2.1:80
213 Listen 192.170.2.5:8000
216 <p>IPv6 addresses must be surrounded in square brackets, as in the
217 following example:</p>
219 <highlight language="config">
220 Listen [2001:db8::a00:20ff:fea7:ccea]:80
223 <p>The optional <var>protocol</var> argument is not required for most
224 configurations. If not specified, <code>https</code> is the default for
225 port 443 and <code>http</code> the default for all other ports. The
226 protocol is used to determine which module should handle a request, and
227 to apply protocol specific optimizations with the
228 <directive module="core">AcceptFilter</directive> directive.</p>
230 <p>You only need to set the protocol if you are running on non-standard
231 ports. For example, running an <code>https</code> site on port 8443:</p>
233 <highlight language="config">
234 Listen 192.170.2.1:8443 https
237 <note><title>Error condition</title>
238 Multiple <directive>Listen</directive> directives for the same ip
239 address and port will result in an <code>Address already in use</code>
244 <seealso><a href="../dns-caveats.html">DNS Issues</a></seealso>
245 <seealso><a href="../bind.html">Setting which addresses and ports Apache HTTP Server
248 href="http://wiki.apache.org/httpd/CouldNotBindToAddress">Further
249 discussion of the <code>Address already in use</code> error message,
250 including other causes.</a></seealso>
254 <name>ListenCoresBucketsRatio</name>
255 <description>Ratio between the number of CPU cores (online) and the number of
256 listeners' buckets</description>
257 <syntax>ListenCoresBucketsRatio <var>ratio</var></syntax>
258 <default>ListenCoresBucketsRatio 0 (disabled)</default>
259 <contextlist><context>server config</context></contextlist>
260 <modulelist><module>event</module><module>worker</module>
261 <module>prefork</module>
263 <compatibility>Available in Apache HTTP Server 2.4.17, with a kernel supporting
264 the socket option <code>SO_REUSEPORT</code> and distributing new connections
265 evenly accross listening processes' (or threads') sockets using it (eg. Linux
266 3.9 and later, but not the current implementations of <code>SO_REUSEPORT</code>
267 in *BSDs.</compatibility>
270 <p>A <var>ratio</var> between the number of (online) CPU cores and the
271 number of listeners' buckets can be used to make Apache HTTP Server create
272 <code>num_cpu_cores / ratio</code> listening buckets, each containing its
273 own <directive>Listen</directive>-ing socket(s) on the same port(s), and
274 then make each child handle a single bucket (with round-robin distribution
275 of the buckets at children creation time).</p>
277 <p><directive>ListenCoresBucketsRatio</directive> can improve the
278 scalability when accepting new connections is/becomes the bottleneck.
279 On systems with a large number of CPU cores, enabling this feature has
280 been tested to show significant performances improvement and shorter
283 <p>There must be at least twice the number of CPU cores than the
284 configured <var>ratio</var> for this to be active. The recommended
285 <var>ratio</var> is <code>8</code>, hence at least <code>16</code>
286 cores should be available at runtime when this value is used.</p>
291 <name>ListenBackLog</name>
292 <description>Maximum length of the queue of pending connections</description>
293 <syntax>ListenBacklog <var>backlog</var></syntax>
294 <default>ListenBacklog 511</default>
295 <contextlist><context>server config</context></contextlist>
296 <modulelist><module>event</module><module>worker</module>
297 <module>prefork</module><module>mpm_winnt</module>
298 <module>mpm_netware</module><module>mpmt_os2</module>
302 <p>The maximum length of the queue of pending connections.
303 Generally no tuning is needed or desired, however on some
304 systems it is desirable to increase this when under a TCP SYN
305 flood attack. See the backlog parameter to the
306 <code>listen(2)</code> system call.</p>
308 <p>This will often be limited to a smaller number by the
309 operating system. This varies from OS to OS. Also note that
310 many OSes do not use exactly what is specified as the backlog,
311 but use a number based on (but normally larger than) what is
317 <name>MaxRequestWorkers</name>
318 <description>Maximum number of connections that will be processed
319 simultaneously</description>
320 <syntax>MaxRequestWorkers <var>number</var></syntax>
321 <default>See usage for details</default>
322 <contextlist><context>server config</context></contextlist>
323 <modulelist><module>event</module><module>worker</module>
324 <module>prefork</module>
328 <p>The <directive>MaxRequestWorkers</directive> directive sets the limit
329 on the number of simultaneous requests that will be served. Any
330 connection attempts over the <directive>MaxRequestWorkers</directive>
331 limit will normally be queued, up to a number based on the
332 <directive module="mpm_common">ListenBacklog</directive>
333 directive. Once a child process is freed at the end of a different
334 request, the connection will then be serviced.</p>
336 <p>For non-threaded servers (<em>i.e.</em>, <module>prefork</module>),
337 <directive>MaxRequestWorkers</directive> translates into the maximum
338 number of child processes that will be launched to serve requests.
339 The default value is <code>256</code>; to increase it, you must also raise
340 <directive module="mpm_common">ServerLimit</directive>.</p>
342 <p>For threaded and hybrid servers (<em>e.g.</em> <module>event</module>
343 or <module>worker</module>) <directive>MaxRequestWorkers</directive> restricts
344 the total number of threads that will be available to serve clients.
345 For hybrid MPMs the default value is <code>16</code> (<directive
346 module="mpm_common">ServerLimit</directive>) multiplied by the value of
347 <code>25</code> (<directive module="mpm_common"
348 >ThreadsPerChild</directive>). Therefore, to increase <directive
349 >MaxRequestWorkers</directive> to a value that requires more than 16 processes,
350 you must also raise <directive module="mpm_common"
351 >ServerLimit</directive>.</p>
353 <p><directive>MaxRequestWorkers</directive> was called
354 <directive>MaxClients</directive> before version 2.3.13. The old name is still
360 <name>MaxMemFree</name>
361 <description>Maximum amount of memory that the main allocator is allowed
362 to hold without calling <code>free()</code></description>
363 <syntax>MaxMemFree <var>KBytes</var></syntax>
364 <default>MaxMemFree 2048</default>
365 <contextlist><context>server config</context></contextlist>
366 <modulelist><module>event</module><module>worker</module>
367 <module>prefork</module><module>mpm_winnt</module>
368 <module>mpm_netware</module>
372 <p>The <directive>MaxMemFree</directive> directive sets the
373 maximum number of free Kbytes that every allocator is allowed
374 to hold without calling <code>free()</code>. In threaded MPMs, every
375 thread has its own allocator. When set
376 to zero, the threshold will be set to unlimited.</p>
381 <name>MaxConnectionsPerChild</name>
382 <description>Limit on the number of connections that an individual child server
383 will handle during its life</description>
384 <syntax>MaxConnectionsPerChild <var>number</var></syntax>
385 <default>MaxConnectionsPerChild 0</default>
386 <contextlist><context>server config</context></contextlist>
387 <modulelist><module>event</module><module>worker</module>
388 <module>prefork</module><module>mpm_winnt</module>
389 <module>mpm_netware</module><module>mpmt_os2</module>
391 <compatibility>Available Apache HTTP Server 2.3.9 and later. The old name
392 <code>MaxRequestsPerChild</code> is still supported.</compatibility>
395 <p>The <directive>MaxConnectionsPerChild</directive> directive sets
396 the limit on the number of connections that an individual child
397 server process will handle. After
398 <directive>MaxConnectionsPerChild</directive> connections, the child
399 process will die. If <directive>MaxConnectionsPerChild</directive> is
400 <code>0</code>, then the process will never expire.</p>
402 <p>Setting <directive>MaxConnectionsPerChild</directive> to a
403 non-zero value limits the amount of memory that process can consume
404 by (accidental) memory leakage.</p>
409 <name>MaxSpareThreads</name>
410 <description>Maximum number of idle threads</description>
411 <syntax>MaxSpareThreads <var>number</var></syntax>
412 <default>See usage for details</default>
413 <contextlist><context>server config</context></contextlist>
414 <modulelist><module>event</module><module>worker</module>
415 <module>mpm_netware</module><module>mpmt_os2</module>
419 <p>Maximum number of idle threads. Different MPMs deal with this
420 directive differently.</p>
422 <p>For <module>worker</module> and <module>event</module>, the default is
423 <code>MaxSpareThreads 250</code>. These MPMs deal with idle threads
424 on a server-wide basis. If there are too many idle threads in the
425 server then child processes are killed until the number of idle
426 threads is less than this number.</p>
428 <p>For <module>mpm_netware</module> the default is
429 <code>MaxSpareThreads 100</code>. Since this MPM runs a
430 single-process, the spare thread count is also server-wide.</p>
432 <p><module>mpmt_os2</module> works
433 similar to <module>mpm_netware</module>. For
434 <module>mpmt_os2</module> the default value is <code>10</code>.</p>
436 <note><title>Restrictions</title>
437 <p>The range of the <directive>MaxSpareThreads</directive> value
438 is restricted. Apache httpd will correct the given value automatically
439 according to the following rules:</p>
441 <li><module>mpm_netware</module> wants the value to be greater than
442 <directive module="mpm_common">MinSpareThreads</directive>.</li>
444 <li>For <module>worker</module> and <module>event</module>, the value
445 must be greater or equal to the sum of <directive module="mpm_common">
446 MinSpareThreads</directive> and <directive module="mpm_common">
447 ThreadsPerChild</directive>.</li>
451 <seealso><directive module="mpm_common">MinSpareThreads</directive></seealso>
452 <seealso><directive module="mpm_common">StartServers</directive></seealso>
453 <seealso><directive module="prefork">MaxSpareServers</directive></seealso>
457 <name>MinSpareThreads</name>
458 <description>Minimum number of idle threads available to handle request
460 <syntax>MinSpareThreads <var>number</var></syntax>
461 <default>See usage for details</default>
462 <contextlist><context>server config</context></contextlist>
463 <modulelist><module>event</module><module>worker</module>
464 <module>mpm_netware</module><module>mpmt_os2</module>
468 <p>Minimum number of idle threads to handle request spikes.
469 Different MPMs deal with this directive differently.</p>
471 <p><module>worker</module> and <module>event</module> use a default of
472 <code>MinSpareThreads 75</code> and deal with idle threads on a server-wide
473 basis. If there aren't enough idle threads in the server then child
474 processes are created until the number of idle threads is greater
475 than <var>number</var>.</p>
477 <p><module>mpm_netware</module> uses a default of
478 <code>MinSpareThreads 10</code> and, since it is a single-process
479 MPM, tracks this on a server-wide bases.</p>
481 <p><module>mpmt_os2</module> works
482 similar to <module>mpm_netware</module>. For
483 <module>mpmt_os2</module> the default value is <code>5</code>.</p>
485 <seealso><directive module="mpm_common">MaxSpareThreads</directive></seealso>
486 <seealso><directive module="mpm_common">StartServers</directive></seealso>
487 <seealso><directive module="prefork">MinSpareServers</directive></seealso>
491 <name>ScoreBoardFile</name>
492 <description>Location of the file used to store coordination data for
493 the child processes</description>
494 <syntax>ScoreBoardFile <var>file-path</var></syntax>
495 <default>ScoreBoardFile apache_runtime_status</default>
496 <contextlist><context>server config</context></contextlist>
497 <modulelist><module>event</module><module>worker</module>
498 <module>prefork</module><module>mpm_winnt</module>
502 <p>Apache HTTP Server uses a scoreboard to communicate between its parent
503 and child processes. Some architectures require a file to facilitate
504 this communication. If the file is left unspecified, Apache httpd first
505 attempts to create the scoreboard entirely in memory (using anonymous
506 shared memory) and, failing that, will attempt to create the file on
507 disk (using file-based shared memory). Specifying this directive causes
508 Apache httpd to always create the file on the disk.</p>
510 <p>If <var>file-path</var> is not an absolute path, the location specified
511 will be relative to the value of
512 <directive module="core">DefaultRuntimeDir</directive>.</p>
514 <example><title>Example</title>
515 <highlight language="config">
516 ScoreBoardFile /var/run/apache_runtime_status
520 <p>File-based shared memory is useful for third-party applications
521 that require direct access to the scoreboard.</p>
523 <p>If you use a <directive>ScoreBoardFile</directive> then
524 you may see improved speed by placing it on a RAM disk. But be
525 careful that you heed the same warnings about log file placement
526 and <a href="../misc/security_tips.html">security</a>.</p>
528 <seealso><a href="../stopping.html">Stopping and Restarting
529 Apache HTTP Server</a></seealso>
533 <name>ReceiveBufferSize</name>
534 <description>TCP receive buffer size</description>
535 <syntax>ReceiveBufferSize <var>bytes</var></syntax>
536 <default>ReceiveBufferSize 0</default>
537 <contextlist><context>server config</context></contextlist>
538 <modulelist><module>event</module><module>worker</module>
539 <module>prefork</module><module>mpm_winnt</module>
540 <module>mpm_netware</module><module>mpmt_os2</module>
544 <p>The server will set the TCP receive buffer size to the number of
547 <p>If set to the value of <code>0</code>, the server will use the
553 <name>SendBufferSize</name>
554 <description>TCP buffer size</description>
555 <syntax>SendBufferSize <var>bytes</var></syntax>
556 <default>SendBufferSize 0</default>
557 <contextlist><context>server config</context></contextlist>
558 <modulelist><module>event</module><module>worker</module>
559 <module>prefork</module><module>mpm_winnt</module>
560 <module>mpm_netware</module><module>mpmt_os2</module>
564 <p>Sets the server's TCP send buffer size to the number of bytes
565 specified. It is often useful to set this past the OS's standard
566 default value on high speed, high latency connections
567 (<em>i.e.</em>, 100ms or so, such as transcontinental fast pipes).</p>
569 <p>If set to the value of <code>0</code>, the server will use the
570 default value provided by your OS.</p>
572 <p>Further configuration of your operating system may be required to elicit
573 better performance on high speed, high latency connections.</p>
575 <note> <p> On some operating systems, changes in TCP behavior resulting
576 from a larger <directive>SendBufferSize</directive> may not be seen unless
577 <directive module="core">EnableSendfile</directive> is set to OFF. This
578 interaction applies only to static files.</p> </note>
584 <name>ServerLimit</name>
585 <description>Upper limit on configurable number of processes</description>
586 <syntax>ServerLimit <var>number</var></syntax>
587 <default>See usage for details</default>
588 <contextlist><context>server config</context></contextlist>
589 <modulelist><module>event</module><module>worker</module>
590 <module>prefork</module>
594 <p>For the <module>prefork</module> MPM, this directive sets the
595 maximum configured value for <directive
596 module="mpm_common">MaxRequestWorkers</directive> for the lifetime of the
597 Apache httpd process. For the <module>worker</module> and <module>event
598 </module> MPMs, this directive in combination with <directive
599 module="mpm_common">ThreadLimit</directive> sets
600 the maximum configured value for <directive
601 module="mpm_common">MaxRequestWorkers</directive> for the lifetime of the
602 Apache httpd process. Any attempts to change this directive during a
603 restart will be ignored, but <directive
604 module="mpm_common">MaxRequestWorkers</directive> can be modified during
607 <p>Special care must be taken when using this directive. If
608 <directive>ServerLimit</directive> is set to a value much higher
609 than necessary, extra, unused shared memory will be allocated. If
610 both <directive>ServerLimit</directive> and <directive
611 module="mpm_common">MaxRequestWorkers</directive> are set to values
612 higher than the system can handle, Apache httpd may not start or the
613 system may become unstable.</p>
615 <p>With the <module>prefork</module> MPM, use this directive only
616 if you need to set <directive
617 module="mpm_common">MaxRequestWorkers</directive> higher than 256 (default).
618 Do not set the value of this directive any higher than what you
619 might want to set <directive
620 module="mpm_common">MaxRequestWorkers</directive> to.</p>
622 <p>With <module>worker</module> and <module>event</module>, use this
623 directive only if your <directive module="mpm_common">MaxRequestWorkers
624 </directive> and <directive module="mpm_common">ThreadsPerChild</directive>
625 settings require more than 16 server processes (default). Do not set
626 the value of this directive any higher than the number of server
627 processes required by what you may want for <directive
628 module="mpm_common">MaxRequestWorkers </directive> and <directive
629 module="mpm_common">ThreadsPerChild</directive>.</p>
631 <note><title>Note</title>
632 <p>There is a hard limit of <code>ServerLimit 20000</code> compiled
633 into the server (for the <module>prefork</module> MPM 200000). This is
634 intended to avoid nasty effects caused by typos. To increase it
635 even further past this limit, you will need to modify the value of
636 MAX_SERVER_LIMIT in the mpm source file and rebuild the server.</p>
639 <seealso><a href="../stopping.html">Stopping and Restarting Apache HTTP Server</a></seealso>
643 <name>StartServers</name>
644 <description>Number of child server processes created at startup</description>
645 <syntax>StartServers <var>number</var></syntax>
646 <default>See usage for details</default>
647 <contextlist><context>server config</context></contextlist>
648 <modulelist><module>event</module><module>worker</module>
649 <module>prefork</module><module>mpmt_os2</module>
653 <p>The <directive>StartServers</directive> directive sets the
654 number of child server processes created on startup. As the number
655 of processes is dynamically controlled depending on the load, (see
656 <directive module="mpm_common">MinSpareThreads</directive>,
657 <directive module="mpm_common">MaxSpareThreads</directive>,
658 <directive module="prefork">MinSpareServers</directive>, <directive
659 module="prefork">MaxSpareServers</directive>)
660 there is usually little reason to adjust this parameter.</p>
662 <p>The default value differs from MPM to MPM. <module>worker</module> and
663 <module>event</module> default to <code>StartServers 3</code>; <module>
664 prefork</module> defaults to <code>5</code>; <module>mpmt_os2</module>
665 defaults to <code>2</code>.</p>
670 <name>StartThreads</name>
671 <description>Number of threads created on startup</description>
672 <syntax>StartThreads <var>number</var></syntax>
673 <default>See usage for details</default>
674 <contextlist><context>server config</context></contextlist>
675 <modulelist><module>mpm_netware</module></modulelist>
678 <p>Number of threads created on startup. As the
679 number of threads is dynamically controlled depending on the
681 <directive module="mpm_common">MinSpareThreads</directive>,
682 <directive module="mpm_common">MaxSpareThreads</directive>,
683 <directive module="prefork">MinSpareServers</directive>, <directive
684 module="prefork">MaxSpareServers</directive>)
685 there is usually little reason to adjust this
688 <p>For <module>mpm_netware</module> the default is
689 <code>StartThreads 50</code> and, since there is only a single
690 process, this is the total number of threads created at startup to
696 <name>ThreadLimit</name>
697 <description>Sets the upper limit on the configurable number of threads
698 per child process</description>
699 <syntax>ThreadLimit <var>number</var></syntax>
700 <default>See usage for details</default>
701 <contextlist><context>server config</context></contextlist>
702 <modulelist><module>event</module><module>worker</module>
703 <module>mpm_winnt</module>
707 <p>This directive sets the maximum configured value for <directive
708 module="mpm_common">ThreadsPerChild</directive> for the lifetime
709 of the Apache httpd process. Any attempts to change this directive
710 during a restart will be ignored, but <directive
711 module="mpm_common">ThreadsPerChild</directive> can be modified
712 during a restart up to the value of this directive.</p>
714 <p>Special care must be taken when using this directive. If
715 <directive>ThreadLimit</directive> is set to a value much higher
716 than <directive module="mpm_common">ThreadsPerChild</directive>,
717 extra unused shared memory will be allocated. If both
718 <directive>ThreadLimit</directive> and <directive
719 module="mpm_common">ThreadsPerChild</directive> are set to values
720 higher than the system can handle, Apache httpd may not start or the
721 system may become unstable. Do not set the value of this directive
722 any higher than your greatest predicted setting of <directive
723 module="mpm_common">ThreadsPerChild</directive> for the
724 current run of Apache httpd.</p>
726 <p>The default value for <directive>ThreadLimit</directive> is
727 <code>1920</code> when used with <module>mpm_winnt</module> and
728 <code>64</code> when used with the others.</p>
730 <note><title>Note</title>
731 <p>There is a hard limit of <code>ThreadLimit 20000</code> (or
732 <code>ThreadLimit 100000</code> with <module>event</module>,
733 <code>ThreadLimit 15000</code> with <module>mpm_winnt</module>)
734 compiled into the server. This is intended to avoid nasty effects
735 caused by typos. To increase it even further past this limit, you
736 will need to modify the value of MAX_THREAD_LIMIT in the mpm
737 source file and rebuild the server.</p>
743 <name>ThreadsPerChild</name>
744 <description>Number of threads created by each child process</description>
745 <syntax>ThreadsPerChild <var>number</var></syntax>
746 <default>See usage for details</default>
747 <contextlist><context>server config</context></contextlist>
748 <modulelist><module>event</module><module>worker</module>
749 <module>mpm_winnt</module>
753 <p>This directive sets the number of threads created by each
754 child process. The child creates these threads at startup and
755 never creates more. If using an MPM like <module>mpm_winnt</module>,
756 where there is only one child process, this number should be high
757 enough to handle the entire load of the server. If using an MPM
758 like <module>worker</module>, where there are multiple child processes,
759 the <em>total</em> number of threads should be high enough to handle
760 the common load on the server.</p>
762 <p>The default value for <directive>ThreadsPerChild</directive> is
763 <code>64</code> when used with <module>mpm_winnt</module> and
764 <code>25</code> when used with the others.</p>
769 <name>ThreadStackSize</name>
770 <description>The size in bytes of the stack used by threads handling
771 client connections</description>
772 <syntax>ThreadStackSize <var>size</var></syntax>
773 <default>65536 on NetWare; varies on other operating systems</default>
774 <contextlist><context>server config</context></contextlist>
775 <modulelist><module>event</module><module>worker</module>
776 <module>mpm_winnt</module><module>mpm_netware</module>
777 <module>mpmt_os2</module>
781 <p>The <directive>ThreadStackSize</directive> directive sets the
782 size of the stack (for autodata) of threads which handle client
783 connections and call modules to help process those connections.
784 In most cases the operating system default for stack size is
785 reasonable, but there are some conditions where it may need to be
789 <li>On platforms with a relatively small default thread stack size
790 (e.g., HP-UX), Apache httpd may crash when using some third-party modules
791 which use a relatively large amount of autodata storage. Those
792 same modules may have worked fine on other platforms where the
793 default thread stack size is larger. This type of crash is
794 resolved by setting <directive>ThreadStackSize</directive> to a
795 value higher than the operating system default. This type of
796 adjustment is necessary only if the provider of the third-party
797 module specifies that it is required, or if diagnosis of an Apache httpd
798 crash indicates that the thread stack size was too small.</li>
800 <li>On platforms where the default thread stack size is
801 significantly larger than necessary for the web server
802 configuration, a higher number of threads per child process
803 will be achievable if <directive>ThreadStackSize</directive> is
804 set to a value lower than the operating system default. This type
805 of adjustment should only be made in a test environment which allows
806 the full set of web server processing can be exercised, as there
807 may be infrequent requests which require more stack to process.
808 The minimum required stack size strongly depends on the modules
809 used, but any change in the web server configuration can invalidate
810 the current <directive>ThreadStackSize</directive> setting.</li>
812 <li>On Linux, this directive can only be used to increase the default
813 stack size, as the underlying system call uses the value as a
814 <em>minimum</em> stack size. The (often large) soft limit for
815 <code>ulimit -s</code> (8MB if unlimited) is used as the default stack
819 <note>It is recommended to not reduce <directive>ThreadStackSize</directive>
820 unless a high number of threads per child process is needed. On some
821 platforms (including Linux), a setting of 128000 is already too low and
822 causes crashes with some common modules.</note>