stopping.html revision 25503838e438bb909e3ff880125732c7ed5e64ad
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes BGCOLOR="#FFFFFF"
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes TEXT="#000000"
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes LINK="#0000FF"
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes VLINK="#000080"
0662ed52e814f8f08ef0e09956413a792584eddffuankg ALINK="#FF0000"
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<!--#include virtual="header.html" -->
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<H1 ALIGN="CENTER">Stopping and Restarting Apache</H1>
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P>You will notice many <CODE>httpd</CODE> executables running on your system,
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesbut you should not send signals to any of them except the parent, whose
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholespid is in the <A HREF="mod/core.html#pidfile">PidFile</A>. That is to
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholessay you shouldn't ever need to send signals to any process except the
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesparent. There are three signals that you can send the parent:
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<CODE>TERM</CODE>, <CODE>HUP</CODE>, and <CODE>USR1</CODE>, which will
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesbe described in a moment.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P>To send a signal to the parent you should issue a command such as:
16b55a35cff91315d261d1baa776138af465c4e4fuankgYou can read about its progress by issuing:
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesModify those examples to match your
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<A HREF="mod/core.html#serverroot">ServerRoot</A> and
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<A HREF="mod/core.html#pidfile">PidFile</A> settings.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P>Sending the <CODE>TERM</CODE> signal to the parent causes it to
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesimmediately attempt to kill off all of its children. It may take it
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesseveral seconds to complete killing off its children. Then the
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesparent itself exits. Any requests in progress are terminated, and no
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesfurther requests are served.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P>Sending the <CODE>HUP</CODE> signal to the parent causes it to kill off
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesits children like in <CODE>TERM</CODE> but the parent doesn't exit. It
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesre-reads its configuration files, and re-opens any log files.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesThen it spawns a new set of children and continues
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesserving hits.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P>Users of the
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholeswill notice that the server statistics are
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P><STRONG>Note:</STRONG> If your configuration file has errors in it when you issue a
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesrestart then your parent will not restart, it will exit with an error.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesSee below for a method of avoiding this.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P><STRONG>Note:</STRONG> prior to release 1.2b9 this code is quite unstable and
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesshouldn't be used at all.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P>The <CODE>USR1</CODE> signal causes the parent process to <EM>advise</EM>
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesthe children to exit after their current request (or to exit immediately
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesif they're not serving anything). The parent re-reads its configuration
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesfiles and re-opens its log files. As each child dies off the parent
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesreplaces it with a child from the new <EM>generation</EM> of the
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesconfiguration, which begins serving new requests immediately.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P>This code is designed to always respect the
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<A HREF="mod/core.html#minspareservers">MinSpareServers</A>,
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgand <A HREF="mod/core.html#maxspareservers">MaxSpareServers</A> settings.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesFurthermore, it respects <A HREF="mod/core.html#startservers">StartServers</A>
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesin the following manner: if after one second at least StartServers new
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholeschildren have not been created, then create enough to pick up the slack.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesThis is to say that the code tries to maintain both the number of children
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesappropriate for the current load on the server, and respect your wishes
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholeswith the StartServers parameter.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P>Users of the
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholeswill notice that the server statistics
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesare <STRONG>not</STRONG> set to zero when a <CODE>USR1</CODE> is sent. The code
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholeswas written to both minimize the time in which the server is unable to serve
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesnew requests (they will be queued up by the operating system, so they're
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesnot lost in any event) and to respect your tuning parameters. In order
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesto do this it has to keep the <EM>scoreboard</EM> used to keep track
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesof all children across generations.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P>The status module will also use a <CODE>G</CODE> to indicate those
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholeschildren which are still serving requests started before the graceful
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesrestart was given.
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg<P>At present there is no way for a log rotation script using
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<CODE>USR1</CODE> to know for certain that all children writing the
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholespre-restart log have finished. We suggest that you use a suitable delay
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgafter sending the <CODE>USR1</CODE> signal before you do anything with the
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesold log. For example if most of your hits take less than 10 minutes to
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholescomplete for users on low bandwidth links then you could wait 15 minutes
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesbefore doing anything with the old log.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P><STRONG>Note:</STRONG> If your configuration file has errors in it when you issue a
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesrestart then your parent will not restart, it will exit with an error.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesIn the case of graceful
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesrestarts it will also leave children running when it exits. (These are
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesthe children which are "gracefully exiting" by handling their last request.)
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesThis will cause problems if you attempt to restart the server -- it will
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesnot be able to bind to its listening ports. At present the only work
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgaround is to check the syntax of your files before doing a restart. The
0662ed52e814f8f08ef0e09956413a792584eddffuankgeasiest way is to just run httpd as a non-root user. If there are no
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholeserrors it will attempt to open its sockets and logs and fail because it's
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgnot root (or because the currently running httpd already has those ports
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesbound). If it fails for any other reason then it's probably a config file
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholeserror and the error should be fixed before issuing the graceful restart.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM>
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesinvolving the restart and die signals (a simple description of race
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholescondition is: a time-sensitive problem, as in if something happens at just
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesthe wrong time it won't behave as expected). For those architectures that
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholeshave the "right" feature set we have eliminated as many as we can.
0662ed52e814f8f08ef0e09956413a792584eddffuankgBut it should be noted that there still do exist race conditions on
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholescertain architectures.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P>Architectures that use an on disk
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<A HREF="mod/core.html#scoreboardfile">ScoreBoardFile</A>
0662ed52e814f8f08ef0e09956413a792584eddffuankghave the potential to corrupt their scoreboards. This can result in
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesthe "bind: Address already in use" (after <CODE>HUP</CODE>) or
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes"long lost child came home!" (after <CODE>USR1</CODE>). The former is
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesa fatal error, while the latter just causes the server to lose a scoreboard
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesslot. So it might be advisable to use graceful restarts, with
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesan occasional hard restart. These problems are very difficult to work
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesaround, but fortunately most architectures do not require a scoreboard file.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesSee the ScoreBoardFile documentation for a method to determine if your
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesarchitecture uses it.
0662ed52e814f8f08ef0e09956413a792584eddffuankg<P><CODE>NEXT</CODE> and <CODE>MACHTEN</CODE> (68k only) have small race
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholeswhich can cause a restart/die signal to be lost, but should not cause the
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgserver to do anything otherwise problematic.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<!-- they don't have sigaction, or we're not using it -djg -->
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<P>All architectures have a small race condition in each child involving
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgthe second and subsequent requests on a persistent HTTP connection
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes(KeepAlive). It may exit after reading the request line but before
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesreading any of the request headers. There is a fix that was discovered
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholestoo late to make 1.2. In theory this isn't an issue because the KeepAlive
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesclient has to expect these events because of network latencies and
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesserver timeouts. In practice it doesn't seem to affect anything either
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes-- in a test case the server was restarted twenty times per second and
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesclients successfully browsed the site without getting broken images or
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholesempty documents.
d3fc1a9aec53a772142e2909441b213f3ae8102abnicholes<!--#include virtual="footer.html" -->