stopping.html revision 16a48a1188079f43d01158f2bda4727e946f5fed
842ae4bd224140319ae7feec1872b93dfd491143fielding<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
b0fb330a8581c8bfab5e523084f9f39264a52b12gstein<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
b0fb330a8581c8bfab5e523084f9f39264a52b12gstein BGCOLOR="#FFFFFF"
71da3cca78eea6010f89b139ecadb79e6d213c4fnd TEXT="#000000"
71da3cca78eea6010f89b139ecadb79e6d213c4fnd LINK="#0000FF"
71da3cca78eea6010f89b139ecadb79e6d213c4fnd VLINK="#000080"
71da3cca78eea6010f89b139ecadb79e6d213c4fnd ALINK="#FF0000"
b0fb330a8581c8bfab5e523084f9f39264a52b12gstein<!--#include virtual="header.html" -->
f4c310fd2555c6faca1f980f00b161eadb089023gstein<H1 ALIGN="CENTER">Stopping and Restarting the Server</H1>
b0fb330a8581c8bfab5e523084f9f39264a52b12gstein<P>This document covers stopping and restarting Apache on Unix-like
f4c310fd2555c6faca1f980f00b161eadb089023gsteinsystems. Windows users should see <A
f4c310fd2555c6faca1f980f00b161eadb089023gsteinHREF="platform/windows.html#signal">Signalling Apache when
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P>You will notice many <CODE>httpd</CODE> executables running on your system,
f4c310fd2555c6faca1f980f00b161eadb089023gsteinbut you should not send signals to any of them except the parent, whose
f4c310fd2555c6faca1f980f00b161eadb089023gsteinpid is in the <A HREF="mod/core.html#pidfile">PidFile</A>. That is to
f4c310fd2555c6faca1f980f00b161eadb089023gsteinsay you shouldn't ever need to send signals to any process except the
f4c310fd2555c6faca1f980f00b161eadb089023gsteinparent. There are three signals that you can send the parent:
f4c310fd2555c6faca1f980f00b161eadb089023gstein<CODE>TERM</CODE>, <CODE>HUP</CODE>, and <CODE>USR1</CODE>, which will
f4c310fd2555c6faca1f980f00b161eadb089023gsteinbe described in a moment.
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P>To send a signal to the parent you should issue a command such as:
f4c310fd2555c6faca1f980f00b161eadb089023gsteinYou can read about its progress by issuing:
f4c310fd2555c6faca1f980f00b161eadb089023gsteinModify those examples to match your
f4c310fd2555c6faca1f980f00b161eadb089023gstein<p>A shell script called <code>apachectl</code> is provided
f4c310fd2555c6faca1f980f00b161eadb089023gsteinwhich automates the processing of signalling Apache.
f4c310fd2555c6faca1f980f00b161eadb089023gsteinFor details about this script, see the documentation
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P>Sending the <CODE>TERM</CODE> signal to the parent causes it to
f4c310fd2555c6faca1f980f00b161eadb089023gsteinimmediately attempt to kill off all of its children. It may take it
f4c310fd2555c6faca1f980f00b161eadb089023gsteinseveral seconds to complete killing off its children. Then the
f4c310fd2555c6faca1f980f00b161eadb089023gsteinparent itself exits. Any requests in progress are terminated, and no
f4c310fd2555c6faca1f980f00b161eadb089023gsteinfurther requests are served.
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P>The <CODE>WINCH</CODE> signal causes the parent process to <EM>advise</EM>
f4c310fd2555c6faca1f980f00b161eadb089023gsteinthe children to exit after their current request (or to exit immediately
f4c310fd2555c6faca1f980f00b161eadb089023gsteinif they're not serving anything). The parent re-reads its configuration
f4c310fd2555c6faca1f980f00b161eadb089023gsteinfiles and re-opens its log files. As each child dies off the parent
f4c310fd2555c6faca1f980f00b161eadb089023gsteinreplaces it with a child from the new <EM>generation</EM> of the
f4c310fd2555c6faca1f980f00b161eadb089023gsteinconfiguration, which begins serving new requests immediately.</p>
f4c310fd2555c6faca1f980f00b161eadb089023gsteinHREF="mod/mpm_common.html#maxclients">MaxClients</A>, <A
f4c310fd2555c6faca1f980f00b161eadb089023gsteinHREF="mod/prefork.html#minspareservers">MinSpareServers</A>, and <A
f4c310fd2555c6faca1f980f00b161eadb089023gsteinHREF="mod/prefork.html#maxspareservers">MaxSpareServers</A>
f4c310fd2555c6faca1f980f00b161eadb089023gsteinsettings. Furthermore, it respects <A
f4c310fd2555c6faca1f980f00b161eadb089023gsteinHREF="mod/mpm_common.html#startservers">StartServers</A> in the
f4c310fd2555c6faca1f980f00b161eadb089023gsteinfollowing manner: if after one second at least StartServers new
f4c310fd2555c6faca1f980f00b161eadb089023gsteinchildren have not been created, then create enough to pick up the
f4c310fd2555c6faca1f980f00b161eadb089023gsteinslack. This is to say that the code tries to maintain both the number
f4c310fd2555c6faca1f980f00b161eadb089023gsteinof children appropriate for the current load on the server, and
f4c310fd2555c6faca1f980f00b161eadb089023gsteinrespect your wishes with the StartServers parameter.</p>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P>Users of the
f4c310fd2555c6faca1f980f00b161eadb089023gsteinwill notice that the server statistics
f4c310fd2555c6faca1f980f00b161eadb089023gsteinare <STRONG>not</STRONG> set to zero when a <CODE>USR1</CODE> is sent. The
f4c310fd2555c6faca1f980f00b161eadb089023gsteinwas written to both minimize the time in which the server is unable to serve
f4c310fd2555c6faca1f980f00b161eadb089023gsteinnew requests (they will be queued up by the operating system, so they're
f4c310fd2555c6faca1f980f00b161eadb089023gsteinnot lost in any event) and to respect your tuning parameters. In order
f4c310fd2555c6faca1f980f00b161eadb089023gsteinto do this it has to keep the <EM>scoreboard</EM> used to keep track
f4c310fd2555c6faca1f980f00b161eadb089023gsteinof all children across generations.
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P>The status module will also use a <CODE>G</CODE> to indicate those
f4c310fd2555c6faca1f980f00b161eadb089023gsteinchildren which are still serving requests started before the graceful
f4c310fd2555c6faca1f980f00b161eadb089023gsteinrestart was given.
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P>At present there is no way for a log rotation script using
f4c310fd2555c6faca1f980f00b161eadb089023gstein<CODE>WINCH</CODE> to know for certain that all children writing the
f4c310fd2555c6faca1f980f00b161eadb089023gsteinpre-restart log have finished. We suggest that you use a suitable delay
f4c310fd2555c6faca1f980f00b161eadb089023gsteinafter sending the <CODE>WINCH</CODE> signal before you do anything with the
f4c310fd2555c6faca1f980f00b161eadb089023gsteinold log. For example if most of your hits take less than 10 minutes to
f4c310fd2555c6faca1f980f00b161eadb089023gsteincomplete for users on low bandwidth links then you could wait 15 minutes
f4c310fd2555c6faca1f980f00b161eadb089023gsteinbefore doing anything with the old log.
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P><STRONG>Note:</STRONG> If your configuration file has errors in it
f4c310fd2555c6faca1f980f00b161eadb089023gsteinwhen you issue a restart then your parent will not restart, it will
f4c310fd2555c6faca1f980f00b161eadb089023gsteinexit with an error. In the case of graceful restarts it will also
f4c310fd2555c6faca1f980f00b161eadb089023gsteinleave children running when it exits. (These are the children which
f4c310fd2555c6faca1f980f00b161eadb089023gsteinare "gracefully exiting" by handling their last request.) This will
f4c310fd2555c6faca1f980f00b161eadb089023gsteincause problems if you attempt to restart the server -- it will not be
f4c310fd2555c6faca1f980f00b161eadb089023gsteinable to bind to its listening ports. Before doing a restart, you can
f4c310fd2555c6faca1f980f00b161eadb089023gsteincheck the syntax of the configuration files with the <CODE>-t</CODE>
f4c310fd2555c6faca1f980f00b161eadb089023gsteincommand line argument (see <A HREF="invoking.html">Starting
f4c310fd2555c6faca1f980f00b161eadb089023gsteinApache</A>). This still will not guarantee that the server will
f4c310fd2555c6faca1f980f00b161eadb089023gsteinrestart correctly. To check the semantics of the configuration files
f4c310fd2555c6faca1f980f00b161eadb089023gsteinas well as the syntax, you can try starting httpd as a non-root user.
f4c310fd2555c6faca1f980f00b161eadb089023gsteinIf there are no errors it will attempt to open its sockets and logs
f4c310fd2555c6faca1f980f00b161eadb089023gsteinand fail because it's not root (or because the currently running httpd
f4c310fd2555c6faca1f980f00b161eadb089023gsteinalready has those ports bound). If it fails for any other reason then
f4c310fd2555c6faca1f980f00b161eadb089023gsteinit's probably a config file error and the error should be fixed before
f4c310fd2555c6faca1f980f00b161eadb089023gsteinissuing the graceful restart.
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P>Sending the <CODE>HUP</CODE> signal to the parent causes it to kill off
f4c310fd2555c6faca1f980f00b161eadb089023gsteinits children like in <CODE>TERM</CODE> but the parent doesn't exit. It
f4c310fd2555c6faca1f980f00b161eadb089023gsteinre-reads its configuration files, and re-opens any log files.
f4c310fd2555c6faca1f980f00b161eadb089023gsteinThen it spawns a new set of children and continues
f4c310fd2555c6faca1f980f00b161eadb089023gsteinserving hits.
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P>Users of the
f4c310fd2555c6faca1f980f00b161eadb089023gsteinwill notice that the server statistics are
cccd31fa4a72fe23cc3249c06db181b274a55a69gstein<P><STRONG>Note:</STRONG> If your configuration file has errors in it when
96056e0b952146325e0e4fb1ac7dd77e3ee752d6trawickrestart then your parent will not restart, it will exit with an error.
96056e0b952146325e0e4fb1ac7dd77e3ee752d6trawickSee below for a method of avoiding this.
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM>
f4c310fd2555c6faca1f980f00b161eadb089023gsteininvolving the restart and die signals (a simple description of race
f4c310fd2555c6faca1f980f00b161eadb089023gsteincondition is: a time-sensitive problem, as in if something happens at just
f4c310fd2555c6faca1f980f00b161eadb089023gsteinthe wrong time it won't behave as expected). For those architectures that
956f4b1551215610a57f3b52822dbac6f41a8aa9gsteinhave the "right" feature set we have eliminated as many as we can.
f4c310fd2555c6faca1f980f00b161eadb089023gsteinBut it should be noted that there still do exist race conditions on
f4c310fd2555c6faca1f980f00b161eadb089023gsteincertain architectures.
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P>Architectures that use an on disk
f4c310fd2555c6faca1f980f00b161eadb089023gstein<A HREF="mod/core.html#scoreboardfile">ScoreBoardFile</A>
f4c310fd2555c6faca1f980f00b161eadb089023gsteinhave the potential to corrupt their scoreboards. This can result in
f4c310fd2555c6faca1f980f00b161eadb089023gsteinthe "bind: Address already in use" (after <CODE>HUP</CODE>) or
f4c310fd2555c6faca1f980f00b161eadb089023gstein"long lost child came home!" (after <CODE>USR1</CODE>). The former is
f4c310fd2555c6faca1f980f00b161eadb089023gsteina fatal error, while the latter just causes the server to lose a scoreboard
6f15570e3adc0faf87bf55f70857028276fc9e32wroweslot. So it might be advisable to use graceful restarts, with
f4c310fd2555c6faca1f980f00b161eadb089023gsteinan occasional hard restart. These problems are very difficult to work
6f15570e3adc0faf87bf55f70857028276fc9e32wrowearound, but fortunately most architectures do not require a scoreboard file.
f4c310fd2555c6faca1f980f00b161eadb089023gsteinSee the ScoreBoardFile documentation for a method to determine if your
f4c310fd2555c6faca1f980f00b161eadb089023gsteinarchitecture uses it.
6f15570e3adc0faf87bf55f70857028276fc9e32wrowe<P><CODE>NEXT</CODE> and <CODE>MACHTEN</CODE> (68k only) have small race
6f15570e3adc0faf87bf55f70857028276fc9e32wrowewhich can cause a restart/die signal to be lost, but should not cause the
f4c310fd2555c6faca1f980f00b161eadb089023gsteinserver to do anything otherwise problematic.
6f15570e3adc0faf87bf55f70857028276fc9e32wrowe<!-- they don't have sigaction, or we're not using it -djg -->
f4c310fd2555c6faca1f980f00b161eadb089023gstein<P>All architectures have a small race condition in each child involving
6f15570e3adc0faf87bf55f70857028276fc9e32wrowethe second and subsequent requests on a persistent HTTP connection
6f15570e3adc0faf87bf55f70857028276fc9e32wrowe(KeepAlive). It may exit after reading the request line but before
f4c310fd2555c6faca1f980f00b161eadb089023gsteinreading any of the request headers. There is a fix that was discovered
6f15570e3adc0faf87bf55f70857028276fc9e32wrowetoo late to make 1.2. In theory this isn't an issue because the KeepAlive
f4c310fd2555c6faca1f980f00b161eadb089023gsteinclient has to expect these events because of network latencies and
6f15570e3adc0faf87bf55f70857028276fc9e32wroweserver timeouts. In practice it doesn't seem to affect anything either
f4c310fd2555c6faca1f980f00b161eadb089023gstein-- in a test case the server was restarted twenty times per second and
f4c310fd2555c6faca1f980f00b161eadb089023gsteinclients successfully browsed the site without getting broken images or
f4c310fd2555c6faca1f980f00b161eadb089023gsteinempty documents.
f4c310fd2555c6faca1f980f00b161eadb089023gstein<!--#include virtual="footer.html" -->