stopping.html.en revision b9d4dbc11f13f990bf18b912f4716474d384cf98
2454dfa32c93c20a8522c6ed42fe057baaac9f9aStephan Bosch<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<HTML>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<HEAD>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<TITLE>Stopping and Restarting Apache</TITLE>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch</HEAD>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<BODY>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<!--#include virtual="header.html" -->
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<h1>Stopping and Restarting Apache</h1>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<p>You will notice many <code>httpd</code> executables running on your system,
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschbut you should not send signals to any of them except the parent, whose
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschpid is in the <a href="mod/core.html#pidfile">PidFile</a>. That is to
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschsay you shouldn't ever need to send signals to any process except the
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschparent. There are three signals that you can send the parent:
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<code>TERM</code>, <code>HUP</code>, and <code>USR1</code>, which will
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschbe described in a moment.
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<p>To send a signal to the parent you should issue a command such as:
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<blockquote><pre>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch kill -TERM `cat /usr/local/etc/httpd/logs/httpd.pid`
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch</pre></blockquote>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan BoschYou can read about its progress by issuing:
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<blockquote><pre>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch tail -f /usr/local/etc/httpd/logs/error_log
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch</pre></blockquote>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan BoschModify those examples to match your
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<a href="mod/core.html#serverroot">ServerRoot</a> and
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<a href="mod/core.html#pidfile">PidFile</a> settings.
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<h3>TERM Signal: stop now</h3>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<p>Sending the <code>TERM</code> signal to the parent causes it to
47fee1a942e4797548b1232354f6676b8ff809f4Stephan Boschimmediately attempt to kill off all of its children. It may take it
47fee1a942e4797548b1232354f6676b8ff809f4Stephan Boschseveral seconds to complete killing off its children. Then the
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschparent itself exits. Any requests in progress are terminated, and no
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschfurther requests are served.
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<h3>HUP Signal: restart now</h3>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<p>Sending the <code>HUP</code> signal to the parent causes it to kill off
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschits children like in <code>TERM</code> but the parent doesn't exit. It
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschre-reads its configuration files, and re-opens any log files.
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan BoschThen it spawns a new set of children and continues
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschserving hits.
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
f9d2a1f21ad65262bc630f0834d7eead06a1bac3Timo Sirainen<p>Users of the
f9d2a1f21ad65262bc630f0834d7eead06a1bac3Timo Sirainen<a href="mod/mod_status.html">status module</a>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschwill notice that the server statistics are
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschset to zero when a <code>HUP</code> is sent.
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
15d19d6e4daf460d8d2c82b981e23996dbdf7ba5Timo Sirainen<p><b>Note:</b> If your configuration file has errors in it when you issue a
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschrestart then your parent will not restart, it will exit with an error.
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan BoschSee below for a method of avoiding this.
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<h3>USR1 Signal: graceful restart</h3>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<p><b>Note:</b> prior to release 1.2b9 this code is quite unstable and
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschshouldn't be used at all.
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<p>The <code>USR1</code> signal causes the parent process to <i>advise</i>
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschthe children to exit after their current request (or to exit immediately
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschif they're not serving anything). The parent re-reads its configuration
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschfiles and re-opens its log files. As each child dies off the parent
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschreplaces it with a child from the new <i>generation</i> of the
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Boschconfiguration, which begins serving new requests immediately.
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<p>This code is designed to always respect the
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<a href="mod/core.html#maxclients">MaxClients</a>,
3fcb3d2d1f3583025ff62bae95ec706920f398b1Stephan Bosch<a href="mod/core.html#minspareservers">MinSpareServers</a>,
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Boschand <a href="mod/core.html#maxspareservers">MaxSpareServers</a> settings.
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan BoschFurthermore, it respects <a href="mod/core.html#startservers">StartServers</a>
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Boschin the following manner: if after one second at least StartServers new
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Boschchildren have not been created, then create enough to pick up the slack.
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan BoschThis is to say that the code tries to maintain both the number of children
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Boschappropriate for the current load on the server, and respect your wishes
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Boschwith the StartServers parameter.
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Bosch
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Bosch<p>Users of the
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Bosch<a href="mod/mod_status.html">status module</a>
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Boschwill notice that the server statistics
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Boschare <b>not</b> set to zero when a <code>USR1</code> is sent. The code
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Boschwas written to both minimize the time in which the server is unable to serve
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Boschnew requests (they will be queued up by the operating system, so they're
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Boschnot lost in any event) and to respect your tuning parameters. In order
e1a4ea6ad3e799ef8df7395e765c0ae9218e6c5dStephan Boschto do this it has to keep the <i>scoreboard</i> used to keep track
of all children across generations.
<p>The status module will also use a <code>G</code> to indicate those
children which are still serving requests started before the graceful
restart was given.
<p>At present there is no way for a log rotation script using
<code>USR1</code> to know for certain that all children writing the
pre-restart log have finished. We suggest that you use a suitable delay
after sending the <code>USR1</code> signal before you do anything with the
old log. For example if most of your hits take less than 10 minutes to
complete for users on low bandwidth links then you could wait 15 minutes
before doing anything with the old log.
<p><b>Note:</b> 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. At present the only work
around is to check the syntax of your files before doing a restart. The
easiest way is to just run httpd 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 httpd 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.
<h3>Appendix: signals and race conditions</h3>
<p>Prior to Apache 1.2b9 there were several <i>race conditions</i>
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>Architectures that use an on disk
<a href="mod/core.html#scoreboardfile">ScoreBoardFile</a>
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 ScoreBoardFile documentation for a method to determine if your
architecture uses it.
<p><code>NEXT</code> and <code>MACHTEN</code> (68k only) have small race
conditions
which can cause a restart/die signal to be lost, but should not cause the
server to do anything otherwise problematic.
<!-- they don't have sigaction, or we're not using it -djg -->
<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.
<!--#include virtual="footer.html" -->
</BODY>
</HTML>