<!-- $LastChangedRevision$ -->
<!--
- Copyright 2002-2006 The Apache Software Foundation or its licensors, as
- applicable.
-
- Licensed 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
+ 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
<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><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
+ <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
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:
+ 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="#graceful">USR1</a></code>, which
+ <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
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 module="mpm_common">StartServers</directive>
+ <directive module="mpm_common">StartServers</directive>
parameter.</p>
<p>Users of <module>mod_status</module>
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 <program>httpd</program>). 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 <program>httpd</program> as a non-root user. If there
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.</note>
+ 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="gracefulstop"><title>Graceful Stop</title>
<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
+ 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
+ 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
+
+ <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>
+ 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 Apache, 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 the <directive module="core">Lockfile</directive> and <directive
- module="mod_cgid">ScriptSock</directive> files contain the server
- PID, and should co-exist 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 others files.</p>
+ 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
logfiles at the same time may destroy each other's logfiles.</p></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 simply put,
- a race condition is a time-sensitive problem - if something happens
- at just the wrong time or things happen in the wrong order,
- undesired behaviour will result. If the same thing happens at the right
- time, all will be well). For those architectures that have the "right"
- feature set we have eliminated as many as we can. But it should
- be noted that race conditions do still exist on certain
- architectures.</p>
-
- <p>Architectures that use an on-disk <directive
- module="mpm_common">ScoreBoardFile</directive> can potentially have
- their scoreboards corrupted. 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 may 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
- architecture which 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>
-
</manualpage>
projects / apache / blobdiff