stopping.html revision 35e192dc8923c9513aabb426c5f595730ea41f48
f79d43bbe70a01454049b77d6f15f6369744959eStéphane Graber<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano BGCOLOR="#FFFFFF"
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano TEXT="#000000"
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano LINK="#0000FF"
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano VLINK="#000080"
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano ALINK="#FF0000"
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<!--#include virtual="header.html" -->
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<H1 ALIGN="CENTER">Stopping and Restarting the Server</H1>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<P>This document covers stopping and restarting Apache on Unix-like
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanosystems. Windows users should see <A
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoHREF="platform/windows.html#signal">Signalling Apache when
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<P>You will notice many <CODE>httpd</CODE> executables running on your system,
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanobut you should not send signals to any of them except the parent, whose
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanopid is in the <A HREF="mod/core.html#pidfile">PidFile</A>. That is to
7f95145833bb24f54e037f73ecc37444d6635697Dwight Engensay you shouldn't ever need to send signals to any process except the
99e4008cad9e959b683c6f48411fcf15a92be3b5Michel Normandparent. There are three signals that you can send the parent:
99e4008cad9e959b683c6f48411fcf15a92be3b5Michel Normand<CODE>TERM</CODE>, <CODE>HUP</CODE>, and <CODE>USR1</CODE>, which will
99e4008cad9e959b683c6f48411fcf15a92be3b5Michel Normandbe described in a moment.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<P>To send a signal to the parent you should issue a command such as:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoYou can read about its progress by issuing:
d5cf438682963ac84c3617941032ba623d4ac9b2Michel NormandModify those examples to match your
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<A HREF="mod/core.html#serverroot">ServerRoot</A> and
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<A HREF="mod/core.html#pidfile">PidFile</A> settings.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanohref="programs/apachectl.html">apachectl</a> is provided which
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoautomates the processing of signalling Apache. For details about this
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoscript, see the documentation on <a href="invoking.html">starting
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<P>Sending the <CODE>TERM</CODE> signal to the parent causes it to
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoimmediately attempt to kill off all of its children. It may take it
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoseveral seconds to complete killing off its children. Then the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoparent itself exits. Any requests in progress are terminated, and no
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcanofurther requests are served.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<P>The <CODE>WINCH</CODE> signal causes the parent process to <EM>advise</EM>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanothe children to exit after their current request (or to exit immediately
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoif they're not serving anything). The parent re-reads its configuration
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanofiles and re-opens its log files. As each child dies off the parent
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoreplaces it with a child from the new <EM>generation</EM> of the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoconfiguration, which begins serving new requests immediately.</p>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoHREF="mod/mpm_common.html#maxclients">MaxClients</A>, <A
70bb1a9ca75543597766cfd644b53db5cc772d3fLars WikbergHREF="mod/prefork.html#minspareservers">MinSpareServers</A>, and <A
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoHREF="mod/prefork.html#maxspareservers">MaxSpareServers</A>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanosettings. Furthermore, it respects <A
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoHREF="mod/mpm_common.html#startservers">StartServers</A> in the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanofollowing manner: if after one second at least StartServers new
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanochildren have not been created, then create enough to pick up the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoslack. This is to say that the code tries to maintain both the number
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoof children appropriate for the current load on the server, and
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanorespect your wishes with the StartServers parameter.</p>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<P>Users of the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanowill notice that the server statistics
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoare <STRONG>not</STRONG> set to zero when a <CODE>USR1</CODE> is sent. The
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanowas written to both minimize the time in which the server is unable to serve
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanonew requests (they will be queued up by the operating system, so they're
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanonot lost in any event) and to respect your tuning parameters. In order
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normandto do this it has to keep the <EM>scoreboard</EM> used to keep track
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoof all children across generations.
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano<P>The status module will also use a <CODE>G</CODE> to indicate those
bb787bc51f0a272f6574fe359f0749302e67c550Matthias Bruggerchildren which are still serving requests started before the graceful
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanorestart was given.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<P>At present there is no way for a log rotation script using
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<CODE>WINCH</CODE> to know for certain that all children writing the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanopre-restart log have finished. We suggest that you use a suitable delay
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoafter sending the <CODE>WINCH</CODE> signal before you do anything with the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoold log. For example if most of your hits take less than 10 minutes to
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedicomplete for users on low bandwidth links then you could wait 15 minutes
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanobefore doing anything with the old log.
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi<P><STRONG>Note:</STRONG> If your configuration file has errors in it
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchediwhen you issue a restart then your parent will not restart, it will
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchediexit with an error. In the case of graceful restarts it will also
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoleave children running when it exits. (These are the children which
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchediare "gracefully exiting" by handling their last request.) This will
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedicause problems if you attempt to restart the server -- it will not be
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchediable to bind to its listening ports. Before doing a restart, you can
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedicheck the syntax of the configuration files with the <CODE>-t</CODE>
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedicommand line argument (see <A HREF="invoking.html">Starting
0478642a4349846ab8e76e318909886e795df92dFilippo GiunchediApache</A>). This still will not guarantee that the server will
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedirestart correctly. To check the semantics of the configuration files
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedias well as the syntax, you can try starting httpd as a non-root user.
0478642a4349846ab8e76e318909886e795df92dFilippo GiunchediIf there are no errors it will attempt to open its sockets and logs
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcanoand fail because it's not root (or because the currently running httpd
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcanoalready has those ports bound). If it fails for any other reason then
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcanoit's probably a config file error and the error should be fixed before
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcanoissuing the graceful restart.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<P>Sending the <CODE>HUP</CODE> signal to the parent causes it to kill off
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoits children like in <CODE>TERM</CODE> but the parent doesn't exit. It
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanore-reads its configuration files, and re-opens any log files.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoThen it spawns a new set of children and continues
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano<P>Users of the
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcanowill notice that the server statistics are
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<P><STRONG>Note:</STRONG> If your configuration file has errors in it when
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcanorestart then your parent will not restart, it will exit with an error.
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel LezcanoSee below for a method of avoiding this.
0dcbd62472d5062ff9df89e130176c517e42aec9Stéphane Graber<H3>Appendix: signals and race conditions</H3>
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano<P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM>
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcanoinvolving the restart and die signals (a simple description of race
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanocondition is: a time-sensitive problem, as in if something happens at just
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanothe wrong time it won't behave as expected). For those architectures that
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanohave the "right" feature set we have eliminated as many as we can.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoBut it should be noted that there still do exist race conditions on
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanocertain architectures.
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand<P>Architectures that use an on disk
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand<A HREF="mod/core.html#scoreboardfile">ScoreBoardFile</A>
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normandhave the potential to corrupt their scoreboards. This can result in
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normandthe "bind: Address already in use" (after <CODE>HUP</CODE>) or
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand"long lost child came home!" (after <CODE>USR1</CODE>). The former is
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normanda fatal error, while the latter just causes the server to lose a scoreboard
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoslot. So it might be advisable to use graceful restarts, with
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoan occasional hard restart. These problems are very difficult to work
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoaround, but fortunately most architectures do not require a scoreboard file.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoSee the ScoreBoardFile documentation for a method to determine if your
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoarchitecture uses it.
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano<P><CODE>NEXT</CODE> and <CODE>MACHTEN</CODE> (68k only) have small race
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcanowhich can cause a restart/die signal to be lost, but should not cause the
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcanoserver to do anything otherwise problematic.
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano<!-- they don't have sigaction, or we're not using it -djg -->
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano<P>All architectures have a small race condition in each child involving
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcanothe second and subsequent requests on a persistent HTTP connection
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano(KeepAlive). It may exit after reading the request line but before
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoreading any of the request headers. There is a fix that was discovered
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanotoo late to make 1.2. In theory this isn't an issue because the KeepAlive
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoclient has to expect these events because of network latencies and
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoserver timeouts. In practice it doesn't seem to affect anything either
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano-- in a test case the server was restarted twenty times per second and
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoclients successfully browsed the site without getting broken images or
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoempty documents.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<!--#include virtual="footer.html" -->