stopping.html.en revision bf3d9f591e5af24fdcaa9029094dc045878d1d1a
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki BGCOLOR="#FFFFFF"
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki TEXT="#000000"
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki LINK="#0000FF"
498e8a909bc308283d3713bb348246fe51de059cyoshiki VLINK="#000080"
498e8a909bc308283d3713bb348246fe51de059cyoshiki ALINK="#FF0000"
498e8a909bc308283d3713bb348246fe51de059cyoshiki<!--#include virtual="header.html" -->
498e8a909bc308283d3713bb348246fe51de059cyoshiki<h1 ALIGN="CENTER">Stopping and Restarting Apache</h1>
498e8a909bc308283d3713bb348246fe51de059cyoshiki<p>You will notice many <code>httpd</code> executables running on your system,
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikibut you should not send signals to any of them except the parent, whose
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikipid is in the <a href="mod/core.html#pidfile">PidFile</a>. That is to
498e8a909bc308283d3713bb348246fe51de059cyoshikisay you shouldn't ever need to send signals to any process except the
498e8a909bc308283d3713bb348246fe51de059cyoshikiparent. There are three signals that you can send the parent:
498e8a909bc308283d3713bb348246fe51de059cyoshiki<code>TERM</code>, <code>HUP</code>, and <code>USR1</code>, which will
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikibe described in a moment.
498e8a909bc308283d3713bb348246fe51de059cyoshiki<p>To send a signal to the parent you should issue a command such as:
498e8a909bc308283d3713bb348246fe51de059cyoshiki kill -TERM `cat /usr/local/etc/httpd/logs/httpd.pid`
498e8a909bc308283d3713bb348246fe51de059cyoshikiYou can read about its progress by issuing:
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiModify those examples to match your
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<a href="mod/core.html#serverroot">ServerRoot</a> and
498e8a909bc308283d3713bb348246fe51de059cyoshiki<a href="mod/core.html#pidfile">PidFile</a> settings.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<p>Sending the <code>TERM</code> signal to the parent causes it to
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiimmediately attempt to kill off all of its children. It may take it
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiseveral seconds to complete killing off its children. Then the
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiparent itself exits. Any requests in progress are terminated, and no
498e8a909bc308283d3713bb348246fe51de059cyoshikifurther requests are served.
498e8a909bc308283d3713bb348246fe51de059cyoshiki<p>Sending the <code>HUP</code> signal to the parent causes it to kill off
498e8a909bc308283d3713bb348246fe51de059cyoshikiits children like in <code>TERM</code> but the parent doesn't exit. It
498e8a909bc308283d3713bb348246fe51de059cyoshikire-reads its configuration files, and re-opens any log files.
498e8a909bc308283d3713bb348246fe51de059cyoshikiThen it spawns a new set of children and continues
498e8a909bc308283d3713bb348246fe51de059cyoshikiserving hits.
498e8a909bc308283d3713bb348246fe51de059cyoshiki<p>Users of the
498e8a909bc308283d3713bb348246fe51de059cyoshikiwill notice that the server statistics are
498e8a909bc308283d3713bb348246fe51de059cyoshiki<p><b>Note:</b> If your configuration file has errors in it when you issue a
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikirestart then your parent will not restart, it will exit with an error.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiSee below for a method of avoiding this.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<p><b>Note:</b> prior to release 1.2b9 this code is quite unstable and
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikishouldn't be used at all.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<p>The <code>USR1</code> signal causes the parent process to <i>advise</i>
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikithe children to exit after their current request (or to exit immediately
498e8a909bc308283d3713bb348246fe51de059cyoshikiif they're not serving anything). The parent re-reads its configuration
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikifiles and re-opens its log files. As each child dies off the parent
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikireplaces it with a child from the new <i>generation</i> of the
498e8a909bc308283d3713bb348246fe51de059cyoshikiconfiguration, which begins serving new requests immediately.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<p>This code is designed to always respect the
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<a href="mod/core.html#minspareservers">MinSpareServers</a>,
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiand <a href="mod/core.html#maxspareservers">MaxSpareServers</a> settings.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiFurthermore, it respects <a href="mod/core.html#startservers">StartServers</a>
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiin the following manner: if after one second at least StartServers new
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikichildren have not been created, then create enough to pick up the slack.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiThis is to say that the code tries to maintain both the number of children
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiappropriate for the current load on the server, and respect your wishes
498e8a909bc308283d3713bb348246fe51de059cyoshikiwith the StartServers parameter.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<p>Users of the
498e8a909bc308283d3713bb348246fe51de059cyoshikiwill notice that the server statistics
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiare <b>not</b> set to zero when a <code>USR1</code> is sent. The code
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiwas written to both minimize the time in which the server is unable to serve
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikinew requests (they will be queued up by the operating system, so they're
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikinot lost in any event) and to respect your tuning parameters. In order
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikito do this it has to keep the <i>scoreboard</i> used to keep track
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiof all children across generations.
498e8a909bc308283d3713bb348246fe51de059cyoshiki<p>The status module will also use a <code>G</code> to indicate those
498e8a909bc308283d3713bb348246fe51de059cyoshikichildren which are still serving requests started before the graceful
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikirestart was given.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<p>At present there is no way for a log rotation script using
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<code>USR1</code> to know for certain that all children writing the
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikipre-restart log have finished. We suggest that you use a suitable delay
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiafter sending the <code>USR1</code> signal before you do anything with the
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiold log. For example if most of your hits take less than 10 minutes to
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikicomplete for users on low bandwidth links then you could wait 15 minutes
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikibefore doing anything with the old log.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<p><b>Note:</b> If your configuration file has errors in it when you issue a
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikirestart then your parent will not restart, it will exit with an error.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiIn the case of graceful
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikirestarts it will also leave children running when it exits. (These are
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikithe children which are "gracefully exiting" by handling their last request.)
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiThis will cause problems if you attempt to restart the server -- it will
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikinot be able to bind to its listening ports. At present the only work
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiaround is to check the syntax of your files before doing a restart. The
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikieasiest way is to just run httpd as a non-root user. If there are no
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikierrors it will attempt to open its sockets and logs and fail because it's
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikinot root (or because the currently running httpd already has those ports
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikibound). If it fails for any other reason then it's probably a config file
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikierror and the error should be fixed before issuing the graceful restart.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<p>Prior to Apache 1.2b9 there were several <i>race conditions</i>
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiinvolving the restart and die signals (a simple description of race
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikicondition is: a time-sensitive problem, as in if something happens at just
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikithe wrong time it won't behave as expected). For those architectures that
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikihave the "right" feature set we have eliminated as many as we can.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiBut it should be noted that there still do exist race conditions on
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikicertain architectures.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<p>Architectures that use an on disk
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<a href="mod/core.html#scoreboardfile">ScoreBoardFile</a>
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikihave the potential to corrupt their scoreboards. This can result in
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikithe "bind: Address already in use" (after <code>HUP</code>) or
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki"long lost child came home!" (after <code>USR1</code>). The former is
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikia fatal error, while the latter just causes the server to lose a scoreboard
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikislot. So it might be advisable to use graceful restarts, with
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikian occasional hard restart. These problems are very difficult to work
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiaround, but fortunately most architectures do not require a scoreboard file.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiSee the ScoreBoardFile documentation for a method to determine if your
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiarchitecture uses it.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<p><code>NEXT</code> and <code>MACHTEN</code> (68k only) have small race
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiwhich can cause a restart/die signal to be lost, but should not cause the
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiserver to do anything otherwise problematic.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<!-- they don't have sigaction, or we're not using it -djg -->
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<p>All architectures have a small race condition in each child involving
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikithe second and subsequent requests on a persistent HTTP connection
498e8a909bc308283d3713bb348246fe51de059cyoshiki(KeepAlive). It may exit after reading the request line but before
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikireading any of the request headers. There is a fix that was discovered
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikitoo late to make 1.2. In theory this isn't an issue because the KeepAlive
498e8a909bc308283d3713bb348246fe51de059cyoshikiclient has to expect these events because of network latencies and
498e8a909bc308283d3713bb348246fe51de059cyoshikiserver timeouts. In practice it doesn't seem to affect anything either
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki-- in a test case the server was restarted twenty times per second and
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiclients successfully browsed the site without getting broken images or
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshikiempty documents.
0d419faf71b4d392a596273bd6cc6db401bf6ab7yoshiki<!--#include virtual="footer.html" -->