stopping.html revision fd44e70dca166566d67733c5b4e44ea4763374b6
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<TITLE>Stopping and Restarting the Server</TITLE>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper BGCOLOR="#FFFFFF"
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper TEXT="#000000"
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper LINK="#0000FF"
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper VLINK="#000080"
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper ALINK="#FF0000"
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<!--#include virtual="header.html" -->
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<H1 ALIGN="CENTER">Stopping and Restarting the Server</H1>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>This document covers stopping and restarting Apache on Unix-like
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepersystems. Windows users should see <A
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de ReeperHREF="platform/windows.html#signal">Signalling Apache when
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>You will notice many <CODE>httpd</CODE> executables running on your system,
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperbut you should not send signals to any of them except the parent, whose
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperpid is in the <A HREF="mod/core.html#pidfile">PidFile</A>. That is to
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepersay you shouldn't ever need to send signals to any process except the
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperparent. There are three signals that you can send the parent:
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<CODE>TERM</CODE>, <CODE>HUP</CODE>, and <CODE>USR1</CODE>, which will
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperbe described in a moment.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>To send a signal to the parent you should issue a command such as:
5c39d8f041417518a02ce2c941d96c2d33b2a364Mark de Reeper kill -TERM `cat /usr/local/apache/logs/httpd.pid`
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de ReeperYou can read about its progress by issuing:
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de ReeperModify those examples to match your
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<A HREF="mod/core.html#serverroot">ServerRoot</A> and
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<A HREF="mod/core.html#pidfile">PidFile</A> settings.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperhref="programs/apachectl.html">apachectl</a> is provided which
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperautomates the processing of signalling Apache. For details about this
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperscript, see the documentation on <a href="invoking.html">starting
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>Sending the <CODE>TERM</CODE> signal to the parent causes it to
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperimmediately attempt to kill off all of its children. It may take it
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperseveral seconds to complete killing off its children. Then the
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperparent itself exits. Any requests in progress are terminated, and no
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperfurther requests are served.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>The <CODE>USR1</CODE> signal causes the parent process to <EM>advise</EM>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperthe children to exit after their current request (or to exit immediately
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperif they're not serving anything). The parent re-reads its configuration
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperfiles and re-opens its log files. As each child dies off the parent
d38436884ea9bb358fbc6af6e5fa63b407e99436Mark de Reeperreplaces it with a child from the new <EM>generation</EM> of the
d38436884ea9bb358fbc6af6e5fa63b407e99436Mark de Reeperconfiguration, which begins serving new requests immediately.</p>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<I>On certain platforms that do not allow USR1 to be used for a graceful
d38436884ea9bb358fbc6af6e5fa63b407e99436Mark de Reeperrestart, an alternative signal may be used (such as WINCH). apachectl
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepergraceful will send the right signal for your platform.</I>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>This code is designed to always respect the <A
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de ReeperHREF="mod/mpm_common.html#maxclients">MaxClients</A>, <A
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de ReeperHREF="mod/prefork.html#minspareservers">MinSpareServers</A>, and <A
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de ReeperHREF="mod/prefork.html#maxspareservers">MaxSpareServers</A>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepersettings. Furthermore, it respects <A
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de ReeperHREF="mod/mpm_common.html#startservers">StartServers</A> in the
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperfollowing manner: if after one second at least StartServers new
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperchildren have not been created, then create enough to pick up the
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperslack. This is to say that the code tries to maintain both the number
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperof children appropriate for the current load on the server, and
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperrespect your wishes with the StartServers parameter.</p>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>Users of the
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<A HREF="mod/mod_status.html">status module</A>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperwill notice that the server statistics
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperare <STRONG>not</STRONG> set to zero when a <CODE>USR1</CODE> is sent. The
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperwas written to both minimize the time in which the server is unable to serve
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepernew requests (they will be queued up by the operating system, so they're
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepernot lost in any event) and to respect your tuning parameters. In order
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperto do this it has to keep the <EM>scoreboard</EM> used to keep track
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperof all children across generations.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>The status module will also use a <CODE>G</CODE> to indicate those
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperchildren which are still serving requests started before the graceful
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperrestart was given.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>At present there is no way for a log rotation script using
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<CODE>USR1</CODE> to know for certain that all children writing the
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperpre-restart log have finished. We suggest that you use a suitable delay
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperafter sending the <CODE>USR1</CODE> signal before you do anything with the
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperold log. For example if most of your hits take less than 10 minutes to
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepercomplete for users on low bandwidth links then you could wait 15 minutes
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperbefore doing anything with the old log.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P><STRONG>Note:</STRONG> If your configuration file has errors in it
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperwhen you issue a restart then your parent will not restart, it will
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperexit with an error. In the case of graceful restarts it will also
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperleave children running when it exits. (These are the children which
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperare "gracefully exiting" by handling their last request.) This will
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepercause problems if you attempt to restart the server -- it will not be
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperable to bind to its listening ports. Before doing a restart, you can
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepercheck the syntax of the configuration files with the <CODE>-t</CODE>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepercommand line argument (see <A
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de ReeperHREF="programs/httpd.html">httpd</A>). This still will not guarantee
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperthat the server will restart correctly. To check the semantics of the
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperconfiguration files as well as the syntax, you can try starting httpd
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperas a non-root user. If there are no errors it will attempt to open
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperits sockets and logs and fail because it's not root (or because the
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepercurrently running httpd already has those ports bound). If it fails
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperfor any other reason then it's probably a config file error and the
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepererror should be fixed before issuing the graceful restart.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>Sending the <CODE>HUP</CODE> signal to the parent causes it to kill off
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperits children like in <CODE>TERM</CODE> but the parent doesn't exit. It
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperre-reads its configuration files, and re-opens any log files.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de ReeperThen it spawns a new set of children and continues
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>Users of the
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<A HREF="mod/mod_status.html">status module</A>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperwill notice that the server statistics are
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P><STRONG>Note:</STRONG> If your configuration file has errors in it when
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperrestart then your parent will not restart, it will exit with an error.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de ReeperSee below for a method of avoiding this.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<H3>Appendix: signals and race conditions</H3>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperinvolving the restart and die signals (a simple description of race
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepercondition is: a time-sensitive problem, as in if something happens at just
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperthe wrong time it won't behave as expected). For those architectures that
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperhave the "right" feature set we have eliminated as many as we can.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de ReeperBut it should be noted that there still do exist race conditions on
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepercertain architectures.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>Architectures that use an on disk
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<A HREF="mod/core.html#scoreboardfile">ScoreBoardFile</A>
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperhave the potential to corrupt their scoreboards. This can result in
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperthe "bind: Address already in use" (after <CODE>HUP</CODE>) or
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper"long lost child came home!" (after <CODE>USR1</CODE>). The former is
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepera fatal error, while the latter just causes the server to lose a scoreboard
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperslot. So it might be advisable to use graceful restarts, with
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperan occasional hard restart. These problems are very difficult to work
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperaround, but fortunately most architectures do not require a scoreboard file.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de ReeperSee the <a HREF=
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper"mod/core.html#scoreboardfile">ScoreBoardFile</a> documentation for a
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperarchitecture uses it.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P><CODE>NEXT</CODE> and <CODE>MACHTEN</CODE> (68k only) have small race
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperwhich can cause a restart/die signal to be lost, but should not cause the
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperserver to do anything otherwise problematic.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<!-- they don't have sigaction, or we're not using it -djg -->
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<P>All architectures have a small race condition in each child involving
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperthe second and subsequent requests on a persistent HTTP connection
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper(KeepAlive). It may exit after reading the request line but before
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperreading any of the request headers. There is a fix that was discovered
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reepertoo late to make 1.2. In theory this isn't an issue because the KeepAlive
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperclient has to expect these events because of network latencies and
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperserver timeouts. In practice it doesn't seem to affect anything either
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper-- in a test case the server was restarted twenty times per second and
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperclients successfully browsed the site without getting broken images or
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeperempty documents.
6406210b71fd4a97800f32f3613eea9b6a6a12ceMark de Reeper<!--#include virtual="footer.html" -->