<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+<!-- $LastChangedRevision$ -->
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
<manualpage metafile="stopping.xml.meta">
- <title>Stopping and Restarting</title>
+ <title>Stopping and Restarting Apache HTTP Server</title>
<summary>
- <p>This document covers stopping and restarting Apache on
+ <p>This document covers stopping and restarting Apache HTTP Server on
Unix-like systems. Windows NT, 2000 and XP users should see
- <a href="platform/windows.html#winsvc">Running Apache as a
+ <a href="platform/windows.html#winsvc">Running httpd as a
Service</a> and Windows 9x and ME users should see <a
- href="platform/windows.html#wincons">Running Apache as a
+ href="platform/windows.html#wincons">Running httpd as a
Console Application</a> for information on how to control
- Apache on those platforms.</p>
+ httpd on those platforms.</p>
</summary>
-<seealso><a href="programs/httpd.html">httpd</a></seealso>
-<seealso><a href="programs/apachectl.html">apachectl</a></seealso>
+<seealso><program>httpd</program></seealso>
+<seealso><program>apachectl</program></seealso>
+<seealso><a href="invoking.html">Starting</a></seealso>
<section id="introduction"><title>Introduction</title>
- <p>In order to stop or restart Apache, you must send a signal to
- the running <code>httpd</code> processes. There are two ways to
+ <p>In order to stop or restart the Apache HTTP Server, you must send a signal to
+ the running <program>httpd</program> processes. There are two ways to
send the signals. First, you can use the unix <code>kill</code>
command to directly send signals to the processes. You will
- notice many <code>httpd</code> executables running on your system,
+ notice many <program>httpd</program> executables running on your system,
but you should not send signals to any of them except the parent,
whose pid is in the <directive
module="mpm_common">PidFile</directive>. That is to say you
shouldn't ever need to send signals to any process except the
- parent. There are three signals that you can send the parent:
- <a href="#term"><code>TERM</code></a>,
- <a href="#hup"><code>HUP</code></a>, and
- <a href="#graceful"><code>USR1</code></a>, which
+ parent. There are four signals that you can send the parent:
+ <code><a href="#term">TERM</a></code>,
+ <code><a href="#graceful">USR1</a></code>,
+ <code><a href="#hup">HUP</a></code>, and
+ <code><a href="#gracefulstop">WINCH</a></code>, which
will be described in a moment.</p>
<p>To send a signal to the parent you should issue a command
<example>kill -TERM `cat /usr/local/apache2/logs/httpd.pid`</example>
- <p>The second method of signaling the <code>httpd</code> processes
+ <p>The second method of signaling the <program>httpd</program> processes
is to use the <code>-k</code> command line options: <code>stop</code>,
- <code>restart</code>, and <code>graceful</code>,
- as described below. These are arguments to the <a
- href="programs/httpd.html">httpd</a> binary, but we recommend that
- you send them using the <a
- href="programs/apachectl.html">apachectl</a> control script, which
- will pass them through to <code>httpd</code>.</p>
-
- <p>After you have signaled <code>httpd</code>, you can read about
+ <code>restart</code>, <code>graceful</code> and <code>graceful-stop</code>,
+ as described below. These are arguments to the <program>
+ httpd</program> binary, but we recommend that
+ you send them using the <program>apachectl</program> control script, which
+ will pass them through to <program>httpd</program>.</p>
+
+ <p>After you have signaled <program>httpd</program>, you can read about
its progress by issuing:</p>
<example>tail -f /usr/local/apache2/logs/error_log</example>
it with a child from the new <em>generation</em> of the
configuration, which begins serving new requests immediately.</p>
- <note>On certain platforms that do not allow <code>USR1</code> to
- be used for a graceful restart, an alternative signal may be used (such
- as <code>WINCH</code>). The command <code>apachectl graceful</code>
- will send the right signal for your platform.</note>
-
<p>This code is designed to always respect the process control
directive of the MPMs, so the number of processes and threads
available to serve clients will be maintained at the appropriate
been created, then create enough to pick up the slack. Hence the
code tries to maintain both the number of children appropriate for
the current load on the server, and respect your wishes with the
- <directive>StartServers</directive> parameter.</p>
+ <directive module="mpm_common">StartServers</directive>
+ parameter.</p>
- <p>Users of the <module>mod_status</module>
+ <p>Users of <module>mod_status</module>
will notice that the server statistics are <strong>not</strong>
set to zero when a <code>USR1</code> is sent. The code was
written to both minimize the time in which the server is unable
low bandwidth links then you could wait 15 minutes before doing
anything with the old log.</p>
- <note>If your configuration file has errors
- in it when you issue a restart then your parent will not
- restart, it will exit with an error. In the case of graceful
- restarts it will also leave children running when it exits.
- (These are the children which are "gracefully exiting" by
- handling their last request.) This will cause problems if you
- attempt to restart the server -- it will not be able to bind to
- its listening ports. Before doing a restart, you can check the
- syntax of the configuration files with the <code>-t</code>
- command line argument (see <a
- href="programs/httpd.html">httpd</a>). This still will not
+ <note>
+ <p>When you issue a restart, a syntax check is first run, to
+ ensure that there are no errors in the configuration files.
+ If your configuration file has errors in it, you will get an
+ error message about that syntax error, and the server will refuse to
+ restart. This avoids the situation where the server halts and then
+ cannot restart, leaving you with a non-functioning server.</p>
+
+ <p>This still will not
guarantee that the server will restart correctly. To check the
semantics of the configuration files as well as the syntax, you
- can try starting <code>httpd</code> as a non-root user. If there are no
- errors it will attempt to open its sockets and logs and fail
- because it's not root (or because the currently running <code>httpd</code>
- already has those ports bound). If it fails for any other
- reason then it's probably a config file error and the error
- should be fixed before issuing the graceful restart.</note>
+ can try starting <program>httpd</program> as a non-root user. If there
+ are no errors it will attempt to open its sockets and logs and fail
+ because it's not root (or because the currently running
+ <program>httpd</program> already has those ports bound). If it fails
+ for any other reason then it's probably a config file error and the error
+ should be fixed before issuing the graceful restart.</p></note>
</section>
<section id="hup"><title>Restart Now</title>
will notice that the server statistics are set to zero when a
<code>HUP</code> is sent.</p>
-<note>If your configuration file has errors in it when you issue a
-restart then your parent will not restart, it will exit with an
-error. See above for a method of avoiding this.</note>
+<note>As with a graceful restart, a syntax check is run before the
+restart is attempted. If your configuration file has errors in it, the
+restart will not be attempted, and you will receive notification of the
+syntax error(s).</note>
</section>
-<section id="race"><title>Appendix: signals and race conditions</title>
-
- <p>Prior to Apache 1.2b9 there were several <em>race
- conditions</em> involving the restart and die signals (a simple
- description of race condition is: a time-sensitive problem, as
- in if something happens at just the wrong time it won't behave
- as expected). For those architectures that have the "right"
- feature set we have eliminated as many as we can. But it should
- be noted that there still do exist race conditions on certain
- architectures.</p>
-
- <p>Architectures that use an on disk <directive
- module="mpm_common">ScoreBoardFile</directive> have the potential
- to corrupt their scoreboards. This can result in the "bind:
- Address already in use" (after <code>HUP</code>) or "long lost
- child came home!" (after <code>USR1</code>). The former is a fatal
- error, while the latter just causes the server to lose a
- scoreboard slot. So it might be advisable to use graceful
- restarts, with an occasional hard restart. These problems are very
- difficult to work around, but fortunately most architectures do
- not require a scoreboard file. See the <directive
- module="mpm_common">ScoreBoardFile</directive> documentation for a
- architecture uses it.</p>
-
- <p>All architectures have a small race condition in each child
- involving the second and subsequent requests on a persistent
- HTTP connection (KeepAlive). It may exit after reading the
- request line but before reading any of the request headers.
- There is a fix that was discovered too late to make 1.2. In
- theory this isn't an issue because the KeepAlive client has to
- expect these events because of network latencies and server
- timeouts. In practice it doesn't seem to affect anything either
- -- in a test case the server was restarted twenty times per
- second and clients successfully browsed the site without
- getting broken images or empty documents. </p>
+<section id="gracefulstop"><title>Graceful Stop</title>
+
+<dl><dt>Signal: WINCH</dt>
+<dd><code>apachectl -k graceful-stop</code></dd>
+</dl>
+
+ <p>The <code>WINCH</code> or <code>graceful-stop</code> signal causes
+ the parent process to <em>advise</em> the children to exit after
+ their current request (or to exit immediately if they're not
+ serving anything). The parent will then remove its <directive
+ module="mpm_common">PidFile</directive> and cease listening on
+ all ports. The parent will continue to run, and monitor children
+ which are handling requests. Once all children have finalised
+ and exited or the timeout specified by the <directive
+ module="mpm_common">GracefulShutdownTimeout</directive> has been
+ reached, the parent will also exit. If the timeout is reached,
+ any remaining children will be sent the <code>TERM</code> signal
+ to force them to exit.</p>
+
+ <p>A <code>TERM</code> signal will immediately terminate the
+ parent process and all children when in the "graceful" state. However
+ as the <directive module="mpm_common">PidFile</directive> will
+ have been removed, you will not be able to use
+ <code>apachectl</code> or <code>httpd</code> to send this signal.</p>
+
+ <note><p>The <code>graceful-stop</code> signal allows you to run multiple
+ identically configured instances of <program>httpd</program> at the
+ same time. This is a powerful feature when performing graceful
+ upgrades of httpd, however it can also cause deadlocks and race
+ conditions with some configurations.</p>
+
+ <p>Care has been taken to ensure that on-disk files such as lock files
+ (<directive module="core">Mutex</directive>) and Unix socket files
+ (<directive module="mod_cgid">ScriptSock</directive>) contain the server
+ PID, and should coexist without problem. However, if a configuration
+ directive, third-party module or persistent CGI utilises any other on-disk
+ lock or state files, care should be taken to ensure that multiple running
+ instances of <program>httpd</program> do not clobber each other's files.</p>
+
+ <p>You should also be wary of other potential race conditions, such as
+ using <program>rotatelogs</program> style piped logging. Multiple running
+ instances of <program>rotatelogs</program> attempting to rotate the same
+ logfiles at the same time may destroy each other's logfiles.</p></note>
</section>
</manualpage>
projects / apache / blobdiff