stopping.html revision b9d4dbc11f13f990bf18b912f4716474d384cf98
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<!--#include virtual="header.html" -->
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<p>You will notice many <code>httpd</code> executables running on your system,
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterbut you should not send signals to any of them except the parent, whose
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterpid is in the <a href="mod/core.html#pidfile">PidFile</a>. That is to
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fostersay you shouldn't ever need to send signals to any process except the
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterparent. There are three signals that you can send the parent:
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<code>TERM</code>, <code>HUP</code>, and <code>USR1</code>, which will
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterbe described in a moment.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<p>To send a signal to the parent you should issue a command such as:
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster kill -TERM `cat /usr/local/etc/httpd/logs/httpd.pid`
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan FosterYou can read about its progress by issuing:
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan FosterModify those examples to match your
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<a href="mod/core.html#serverroot">ServerRoot</a> and
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<a href="mod/core.html#pidfile">PidFile</a> settings.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<p>Sending the <code>TERM</code> signal to the parent causes it to
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenimmediately attempt to kill off all of its children. It may take it
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterseveral seconds to complete killing off its children. Then the
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterparent itself exits. Any requests in progress are terminated, and no
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterfurther requests are served.
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Madden<p>Sending the <code>HUP</code> signal to the parent causes it to kill off
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterits children like in <code>TERM</code> but the parent doesn't exit. It
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenre-reads its configuration files, and re-opens any log files.
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil MaddenThen it spawns a new set of children and continues
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenserving hits.
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Madden<p>Users of the
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenwill notice that the server statistics are
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<p><b>Note:</b> If your configuration file has errors in it when you issue a
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenrestart then your parent will not restart, it will exit with an error.
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil MaddenSee below for a method of avoiding this.
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Madden<p><b>Note:</b> prior to release 1.2b9 this code is quite unstable and
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenshouldn't be used at all.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<p>The <code>USR1</code> signal causes the parent process to <i>advise</i>
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterthe children to exit after their current request (or to exit immediately
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenif they're not serving anything). The parent re-reads its configuration
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenfiles and re-opens its log files. As each child dies off the parent
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenreplaces it with a child from the new <i>generation</i> of the
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenconfiguration, which begins serving new requests immediately.
8589dad18873c72c72a41284cf70a88eb0c56f79Mark de Reeper<p>This code is designed to always respect the
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Madden<a href="mod/core.html#maxclients">MaxClients</a>,
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Madden<a href="mod/core.html#minspareservers">MinSpareServers</a>,
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenand <a href="mod/core.html#maxspareservers">MaxSpareServers</a> settings.
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil MaddenFurthermore, it respects <a href="mod/core.html#startservers">StartServers</a>
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenin the following manner: if after one second at least StartServers new
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenchildren have not been created, then create enough to pick up the slack.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan FosterThis is to say that the code tries to maintain both the number of children
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterappropriate for the current load on the server, and respect your wishes
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterwith the StartServers parameter.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<p>Users of the
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterwill notice that the server statistics
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterare <b>not</b> set to zero when a <code>USR1</code> is sent. The code
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterwas written to both minimize the time in which the server is unable to serve
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosternew requests (they will be queued up by the operating system, so they're
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosternot lost in any event) and to respect your tuning parameters. In order
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterto do this it has to keep the <i>scoreboard</i> used to keep track
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterof all children across generations.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<p>The status module will also use a <code>G</code> to indicate those
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterchildren which are still serving requests started before the graceful
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterrestart was given.
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Madden<p>At present there is no way for a log rotation script using
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<code>USR1</code> to know for certain that all children writing the
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterpre-restart log have finished. We suggest that you use a suitable delay
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenafter sending the <code>USR1</code> signal before you do anything with the
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterold log. For example if most of your hits take less than 10 minutes to
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fostercomplete for users on low bandwidth links then you could wait 15 minutes
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenbefore doing anything with the old log.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<p><b>Note:</b> If your configuration file has errors in it when you issue a
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterrestart then your parent will not restart, it will exit with an error.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan FosterIn the case of graceful
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterrestarts it will also leave children running when it exits. (These are
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenthe children which are "gracefully exiting" by handling their last request.)
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan FosterThis will cause problems if you attempt to restart the server -- it will
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosternot be able to bind to its listening ports. At present the only work
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenaround is to check the syntax of your files before doing a restart. The
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fostereasiest way is to just run httpd as a non-root user. If there are no
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fostererrors it will attempt to open its sockets and logs and fail because it's
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosternot root (or because the currently running httpd already has those ports
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterbound). If it fails for any other reason then it's probably a config file
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fostererror and the error should be fixed before issuing the graceful restart.
8589dad18873c72c72a41284cf70a88eb0c56f79Mark de Reeper<h3>Appendix: signals and race conditions</h3>
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<p>Prior to Apache 1.2b9 there were several <i>race conditions</i>
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterinvolving the restart and die signals (a simple description of race
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fostercondition is: a time-sensitive problem, as in if something happens at just
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterthe wrong time it won't behave as expected). For those architectures that
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterhave the "right" feature set we have eliminated as many as we can.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan FosterBut it should be noted that there still do exist race conditions on
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddencertain architectures.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<p>Architectures that use an on disk
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Madden<a href="mod/core.html#scoreboardfile">ScoreBoardFile</a>
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterhave the potential to corrupt their scoreboards. This can result in
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterthe "bind: Address already in use" (after <code>HUP</code>) or
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Madden"long lost child came home!" (after <code>USR1</code>). The former is
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fostera fatal error, while the latter just causes the server to lose a scoreboard
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterslot. So it might be advisable to use graceful restarts, with
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenan occasional hard restart. These problems are very difficult to work
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenaround, but fortunately most architectures do not require a scoreboard file.
8589dad18873c72c72a41284cf70a88eb0c56f79Mark de ReeperSee the ScoreBoardFile documentation for a method to determine if your
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterarchitecture uses it.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<p><code>NEXT</code> and <code>MACHTEN</code> (68k only) have small race
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterwhich can cause a restart/die signal to be lost, but should not cause the
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterserver to do anything otherwise problematic.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<!-- they don't have sigaction, or we're not using it -djg -->
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<p>All architectures have a small race condition in each child involving
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Fosterthe second and subsequent requests on a persistent HTTP connection
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Madden(KeepAlive). It may exit after reading the request line but before
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenreading any of the request headers. There is a fix that was discovered
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddentoo late to make 1.2. In theory this isn't an issue because the KeepAlive
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenclient has to expect these events because of network latencies and
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenserver timeouts. In practice it doesn't seem to affect anything either
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster-- in a test case the server was restarted twenty times per second and
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenclients successfully browsed the site without getting broken images or
a0e65fdaa1ba8bc5e1029449a643b62da3687defNeil Maddenempty documents.
4a2f0f0be43dfd4c1b490cbf3cc48b6ba6084b1cAllan Foster<!--#include virtual="footer.html" -->