stopping.html revision 324dc6114db013ab41b5257dc24425e6a12b8719
af062818b47340eef15700d2f0211576ba3506eevboxsync<!--#include virtual="header.html" -->
af062818b47340eef15700d2f0211576ba3506eevboxsync<p>You will notice many <code>httpd</code> executables running on your system,
af062818b47340eef15700d2f0211576ba3506eevboxsyncbut you should not send signals to any of them except the parent, whose
af062818b47340eef15700d2f0211576ba3506eevboxsyncpid is in the <a href="mod/core.html#pidfile">PidFile</a>. That is to
af062818b47340eef15700d2f0211576ba3506eevboxsyncsay you shouldn't ever need to send signals to any process except the
af062818b47340eef15700d2f0211576ba3506eevboxsyncparent. There are three signals that you can send the parent:
af062818b47340eef15700d2f0211576ba3506eevboxsync<code>TERM</code>, <code>HUP</code>, and <code>USR1</code>, which will
af062818b47340eef15700d2f0211576ba3506eevboxsyncbe described in a moment.
af062818b47340eef15700d2f0211576ba3506eevboxsync<p>To send a signal to the parent you should issue a command such as:
af062818b47340eef15700d2f0211576ba3506eevboxsync kill -TERM `cat /usr/local/etc/httpd/logs/httpd.pid`
af062818b47340eef15700d2f0211576ba3506eevboxsyncYou can read about its progress by issuing:
af062818b47340eef15700d2f0211576ba3506eevboxsyncModify those examples to match your
af062818b47340eef15700d2f0211576ba3506eevboxsync<a href="mod/core.html#serverroot">ServerRoot</a> and
af062818b47340eef15700d2f0211576ba3506eevboxsync<a href="mod/core.html#pidfile">PidFile</a> settings.
af062818b47340eef15700d2f0211576ba3506eevboxsync<p>Sending the <code>TERM</code> signal to the parent causes it to
af062818b47340eef15700d2f0211576ba3506eevboxsyncimmediately attempt to kill off all of its children. It may take it
af062818b47340eef15700d2f0211576ba3506eevboxsyncseveral seconds to complete killing off its children. Then the
af062818b47340eef15700d2f0211576ba3506eevboxsyncparent itself exits. Any requests in progress are terminated, and no
af062818b47340eef15700d2f0211576ba3506eevboxsyncfurther requests are served.
af062818b47340eef15700d2f0211576ba3506eevboxsync<p>Sending the <code>HUP</code> signal to the parent causes it to kill off
af062818b47340eef15700d2f0211576ba3506eevboxsyncits children like in <code>TERM</code> but the parent doesn't exit. It
af062818b47340eef15700d2f0211576ba3506eevboxsyncre-reads its configuration files, and re-opens any log files.
af062818b47340eef15700d2f0211576ba3506eevboxsyncThen it spawns a new set of children and continues
af062818b47340eef15700d2f0211576ba3506eevboxsyncserving hits.
af062818b47340eef15700d2f0211576ba3506eevboxsync<p>Users of the
af062818b47340eef15700d2f0211576ba3506eevboxsyncwill notice that the server statistics are
af062818b47340eef15700d2f0211576ba3506eevboxsync<p><b>Note:</b> prior to release 1.2b9 this code is quite unstable and
af062818b47340eef15700d2f0211576ba3506eevboxsyncshouldn't be used at all.
af062818b47340eef15700d2f0211576ba3506eevboxsync<p><b>Note:</b> Architectures that use an on disk <a
af062818b47340eef15700d2f0211576ba3506eevboxsynchref="mod/core.html#scoreboardfile">ScoreBoardFile</a> are not supported
af062818b47340eef15700d2f0211576ba3506eevboxsyncon graceful restarts. See the ScoreBoardFile documentation for a method
af062818b47340eef15700d2f0211576ba3506eevboxsyncto determine if your architecture uses a file.
af062818b47340eef15700d2f0211576ba3506eevboxsync<p>The <code>USR1</code> signal causes the parent process to <i>advise</i>
af062818b47340eef15700d2f0211576ba3506eevboxsyncthe children to exit after their current request (or to exit immediately
af062818b47340eef15700d2f0211576ba3506eevboxsyncif they're not serving anything). The parent re-reads its configuration
af062818b47340eef15700d2f0211576ba3506eevboxsyncfiles and re-opens its log files. As each child dies off the parent
af062818b47340eef15700d2f0211576ba3506eevboxsyncreplaces it with a child from the new <i>generation</i> of the
af062818b47340eef15700d2f0211576ba3506eevboxsyncconfiguration, which begins serving new requests immediately.
af062818b47340eef15700d2f0211576ba3506eevboxsync<p>This code is designed to always respect the
af062818b47340eef15700d2f0211576ba3506eevboxsync<a href="mod/core.html#minspareservers">MinSpareServers</a>,
af062818b47340eef15700d2f0211576ba3506eevboxsyncand <a href="mod/core.html#maxspareservers">MaxSpareServers</a> settings.
af062818b47340eef15700d2f0211576ba3506eevboxsyncFurthermore, it respects <a href="mod/core.html#startservers">StartServers</a>
af062818b47340eef15700d2f0211576ba3506eevboxsyncin the following manner: if after one second at least StartServers new
af062818b47340eef15700d2f0211576ba3506eevboxsyncchildren have not been created, then create enough to pick up the slack.
af062818b47340eef15700d2f0211576ba3506eevboxsyncThis is to say that the code tries to maintain both the number of children
af062818b47340eef15700d2f0211576ba3506eevboxsyncappropriate for the current load on the server, and respect your wishes
af062818b47340eef15700d2f0211576ba3506eevboxsyncwith the StartServers parameter.
af062818b47340eef15700d2f0211576ba3506eevboxsync<p>Users of the
af062818b47340eef15700d2f0211576ba3506eevboxsyncwill notice that the server statistics
af062818b47340eef15700d2f0211576ba3506eevboxsyncare <b>not</b> set to zero when a <code>USR1</code> is sent. The code
af062818b47340eef15700d2f0211576ba3506eevboxsyncwas written to both minimize the time in which the server is unable to serve
af062818b47340eef15700d2f0211576ba3506eevboxsyncnew requests (they will be queued up by the operating system, so they're
af062818b47340eef15700d2f0211576ba3506eevboxsyncnot lost in any event) and to respect your tuning parameters. In order
af062818b47340eef15700d2f0211576ba3506eevboxsyncto do this it has to keep the <i>scoreboard</i> used to keep track
af062818b47340eef15700d2f0211576ba3506eevboxsyncof all children across generations.
af062818b47340eef15700d2f0211576ba3506eevboxsync<p>The status module will also use a <code>G</code> to indicate those
af062818b47340eef15700d2f0211576ba3506eevboxsyncchildren which are still serving requests started before the graceful
af062818b47340eef15700d2f0211576ba3506eevboxsyncrestart was given.
af062818b47340eef15700d2f0211576ba3506eevboxsync<p>At present there is no way for a log rotation script using
af062818b47340eef15700d2f0211576ba3506eevboxsync<code>USR1</code> to know for certain that all children writing the
af062818b47340eef15700d2f0211576ba3506eevboxsyncpre-restart log have finished. We suggest that you use a suitable delay
af062818b47340eef15700d2f0211576ba3506eevboxsyncafter sending the <code>USR1</code> signal before you do anything with the
af062818b47340eef15700d2f0211576ba3506eevboxsyncold log. For example if most of your hits take less than 10 minutes to
af062818b47340eef15700d2f0211576ba3506eevboxsynccomplete for users on low bandwidth links then you could wait 15 minutes
af062818b47340eef15700d2f0211576ba3506eevboxsyncbefore doing anything with the old log.
af062818b47340eef15700d2f0211576ba3506eevboxsync<p>Prior to Apache 1.2b9 there were several <i>race conditions</i>
af062818b47340eef15700d2f0211576ba3506eevboxsyncinvolving the restart and die signals (a simple description of race
af062818b47340eef15700d2f0211576ba3506eevboxsynccondition is: a time-sensitive problem, as in if something happens at just
af062818b47340eef15700d2f0211576ba3506eevboxsyncthe wrong time it won't behave as expected). For those architectures that
af062818b47340eef15700d2f0211576ba3506eevboxsynchave the "right" feature set we have eliminated as many as we can.
af062818b47340eef15700d2f0211576ba3506eevboxsyncBut it should be noted that there still do exist race conditions on
af062818b47340eef15700d2f0211576ba3506eevboxsynccertain architectures.
af062818b47340eef15700d2f0211576ba3506eevboxsynchref="mod/core.html#scoreboardfile">ScoreBoardFile</a> have the potential
af062818b47340eef15700d2f0211576ba3506eevboxsyncto corrupt their scoreboards whenever a signal is received (by the
af062818b47340eef15700d2f0211576ba3506eevboxsyncparent or children). It is
af062818b47340eef15700d2f0211576ba3506eevboxsyncpossible for the server to forget about some children when this happens.
af062818b47340eef15700d2f0211576ba3506eevboxsyncSee the ScoreBoardFile documentation for a method to determine if your
af062818b47340eef15700d2f0211576ba3506eevboxsyncarchitecture uses it.
af062818b47340eef15700d2f0211576ba3506eevboxsync<p><code>NEXT</code> and <code>MACHTEN</code> have small race conditions
af062818b47340eef15700d2f0211576ba3506eevboxsyncwhich can cause a restart/die signal to be lost, but should not cause the
af062818b47340eef15700d2f0211576ba3506eevboxsyncserver to do anything otherwise problematic.
af062818b47340eef15700d2f0211576ba3506eevboxsync<!-- they don't have sigaction, or we're not using it -djg -->
af062818b47340eef15700d2f0211576ba3506eevboxsync<p>All architectures have a small race condition in each child involving
af062818b47340eef15700d2f0211576ba3506eevboxsyncthe second and subsequent requests on a persistent HTTP connection
af062818b47340eef15700d2f0211576ba3506eevboxsync(KeepAlive). It may exit after reading the request line but before
af062818b47340eef15700d2f0211576ba3506eevboxsyncreading any of the request headers. There is a fix that was discovered
af062818b47340eef15700d2f0211576ba3506eevboxsynctoo late to make 1.2. In theory this isn't an issue because the KeepAlive
af062818b47340eef15700d2f0211576ba3506eevboxsyncclient has to expect these events because of network latencies and
af062818b47340eef15700d2f0211576ba3506eevboxsyncserver timeouts. In practice it doesn't seem to affect anything either
af062818b47340eef15700d2f0211576ba3506eevboxsync-- in a test case the server was restarted twenty times per second and
af062818b47340eef15700d2f0211576ba3506eevboxsyncclients successfully browsed the site without getting broken images or
af062818b47340eef15700d2f0211576ba3506eevboxsyncempty documents.
af062818b47340eef15700d2f0211576ba3506eevboxsync<!--#include virtual="footer.html" -->