stopping.html revision 581d30ba070dbab2ae9db00315908259540f499d
3802a3d3d7af51ddff31943d5514382f01265770Lennart Poettering<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<TITLE>Stopping and Restarting Apache</TITLE>
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek BGCOLOR="#FFFFFF"
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek<!--#include virtual="header.html" -->
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek<H1 ALIGN="CENTER">Stopping and Restarting Apache</H1>
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek<P>This document covers stopping and restarting Apache on Unix
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekonly. Windows users should see <A HREF="platform/windows.html#signal">Signalling
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<P>You will notice many <CODE>httpd</CODE> executables running on your system,
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekbut you should not send signals to any of them except the parent, whose
dfdebb1b925332352966804303b2516a6506a429Zbigniew Jędrzejewski-Szmekpid is in the <A HREF="mod/core.html#pidfile">PidFile</A>. That is to
dfdebb1b925332352966804303b2516a6506a429Zbigniew Jędrzejewski-Szmeksay you shouldn't ever need to send signals to any process except the
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekparent. There are three signals that you can send the parent:
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<CODE>TERM</CODE>, <CODE>HUP</CODE>, and <CODE>USR1</CODE>, which will
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekbe described in a moment.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<P>To send a signal to the parent you should issue a command such as:
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek kill -TERM `cat /usr/local/apache/logs/httpd.pid`
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-SzmekYou can read about its progress by issuing:
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek tail -f /usr/local/apache/logs/error_log
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-SzmekModify those examples to match your
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<A HREF="mod/core.html#serverroot">ServerRoot</A> and
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<A HREF="mod/core.html#pidfile">PidFile</A> settings.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<P>As of Apache 1.3 we provide a script <CODE>src/support/apachectl</CODE>
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekwhich can be used to start, stop, and restart Apache. It may need a
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmeklittle customization for your system, see the comments at the top of
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<P>Sending the <CODE>TERM</CODE> signal to the parent causes it to
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekimmediately attempt to kill off all of its children. It may take it
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekseveral seconds to complete killing off its children. Then the
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekparent itself exits. Any requests in progress are terminated, and no
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekfurther requests are served.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<P>Sending the <CODE>HUP</CODE> signal to the parent causes it to kill off
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekits children like in <CODE>TERM</CODE> but the parent doesn't exit. It
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekre-reads its configuration files, and re-opens any log files.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-SzmekThen it spawns a new set of children and continues
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<A HREF="mod/mod_status.html">status module</A>
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekwill notice that the server statistics are
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekset to zero when a <CODE>HUP</CODE> is sent.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<P><STRONG>Note:</STRONG> If your configuration file has errors in it when
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekrestart then your parent will not restart, it will exit with an error.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-SzmekSee below for a method of avoiding this.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<H3>USR1 Signal: graceful restart</H3>
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<P><STRONG>Note:</STRONG> prior to release 1.2b9 this code is quite unstable
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekand shouldn't be used at all.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<P>The <CODE>USR1</CODE> signal causes the parent process to <EM>advise</EM>
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekthe children to exit after their current request (or to exit immediately
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekif they're not serving anything). The parent re-reads its configuration
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekfiles and re-opens its log files. As each child dies off the parent
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekreplaces it with a child from the new <EM>generation</EM> of the
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekconfiguration, which begins serving new requests immediately.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<P>This code is designed to always respect the
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<A HREF="mod/core.html#maxclients">MaxClients</A>,
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<A HREF="mod/core.html#minspareservers">MinSpareServers</A>,
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekand <A HREF="mod/core.html#maxspareservers">MaxSpareServers</A> settings.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-SzmekFurthermore, it respects <A HREF="mod/core.html#startservers">StartServers</A>
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekin the following manner: if after one second at least StartServers new
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekchildren have not been created, then create enough to pick up the slack.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-SzmekThis is to say that the code tries to maintain both the number of children
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekappropriate for the current load on the server, and respect your wishes
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekwith the StartServers parameter.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<A HREF="mod/mod_status.html">status module</A>
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekwill notice that the server statistics
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekare <STRONG>not</STRONG> set to zero when a <CODE>USR1</CODE> is sent. The
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekwas written to both minimize the time in which the server is unable to serve
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmeknew requests (they will be queued up by the operating system, so they're
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmeknot lost in any event) and to respect your tuning parameters. In order
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekto do this it has to keep the <EM>scoreboard</EM> used to keep track
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekof all children across generations.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<P>The status module will also use a <CODE>G</CODE> to indicate those
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekchildren which are still serving requests started before the graceful
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekrestart was given.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<P>At present there is no way for a log rotation script using
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<CODE>USR1</CODE> to know for certain that all children writing the
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekpre-restart log have finished. We suggest that you use a suitable delay
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekafter sending the <CODE>USR1</CODE> signal before you do anything with the
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekold log. For example if most of your hits take less than 10 minutes to
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekcomplete for users on low bandwidth links then you could wait 15 minutes
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekbefore doing anything with the old log.
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmek<P><STRONG>Note:</STRONG> If your configuration file has errors in it when
708c143c7cd2bbd748ac0fa993496ff44e72701cZbigniew Jędrzejewski-Szmekrestart then your parent will not restart, it will exit with an error.
dfdebb1b925332352966804303b2516a6506a429Zbigniew Jędrzejewski-SzmekIn the case of graceful
1f70b0876a9388f38422c12fa0c73761559d9425Lennart Poetteringrestarts it will also leave children running when it exits. (These are
1f70b0876a9388f38422c12fa0c73761559d9425Lennart Poetteringthe children which are "gracefully exiting" by handling their last request.)
1f70b0876a9388f38422c12fa0c73761559d9425Lennart PoetteringThis will cause problems if you attempt to restart the server -- it will
1f70b0876a9388f38422c12fa0c73761559d9425Lennart Poetteringnot be able to bind to its listening ports. Before doing a restart, you
1f70b0876a9388f38422c12fa0c73761559d9425Lennart Poetteringcan check the syntax of the configuration files with the <CODE>-t</CODE>
1f70b0876a9388f38422c12fa0c73761559d9425Lennart Poetteringcommand line argument (see <A HREF="invoking.html">Starting
1f70b0876a9388f38422c12fa0c73761559d9425Lennart PoetteringApache</A>). This still will not guarantee that the server will restart
1f70b0876a9388f38422c12fa0c73761559d9425Lennart Poetteringcorrectly. To check the semantics of the configuration files as well
1f70b0876a9388f38422c12fa0c73761559d9425Lennart Poetteringas the syntax, you can try starting httpd as a non-root user. If
1f70b0876a9388f38422c12fa0c73761559d9425Lennart Poetteringthere are no errors it will attempt to open its sockets and logs and
d9130355ee0530117518ff24354bdd552d030238Lennart Poetteringfail because it's not root (or because the currently running httpd
d9130355ee0530117518ff24354bdd552d030238Lennart Poetteringalready has those ports bound). If it fails for any other reason then
d9130355ee0530117518ff24354bdd552d030238Lennart Poetteringit's probably a config file error and the error should be fixed before
d9130355ee0530117518ff24354bdd552d030238Lennart Poetteringissuing the graceful restart.
d9130355ee0530117518ff24354bdd552d030238Lennart Poettering<H3>Appendix: signals and race conditions</H3>
d9130355ee0530117518ff24354bdd552d030238Lennart Poettering<P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM>
781fa93815fafd02b5287ef5781b92ef7b99973bLennart Poetteringinvolving the restart and die signals (a simple description of race
781fa93815fafd02b5287ef5781b92ef7b99973bLennart Poetteringcondition is: a time-sensitive problem, as in if something happens at just
781fa93815fafd02b5287ef5781b92ef7b99973bLennart Poetteringthe wrong time it won't behave as expected). For those architectures that
781fa93815fafd02b5287ef5781b92ef7b99973bLennart Poetteringhave the "right" feature set we have eliminated as many as we can.
38051578360c211e88ef4082ce5746adb52a500eLennart PoetteringBut it should be noted that there still do exist race conditions on
38051578360c211e88ef4082ce5746adb52a500eLennart Poetteringcertain architectures.
38051578360c211e88ef4082ce5746adb52a500eLennart Poettering<P>Architectures that use an on disk
38051578360c211e88ef4082ce5746adb52a500eLennart Poettering<A HREF="mod/core.html#scoreboardfile">ScoreBoardFile</A>
781fa93815fafd02b5287ef5781b92ef7b99973bLennart Poetteringhave the potential to corrupt their scoreboards. This can result in
781fa93815fafd02b5287ef5781b92ef7b99973bLennart Poetteringthe "bind: Address already in use" (after <CODE>HUP</CODE>) or
781fa93815fafd02b5287ef5781b92ef7b99973bLennart Poettering"long lost child came home!" (after <CODE>USR1</CODE>). The former is
1fc5560911a7e9e8cf2993e17e1f0a001e148809Lennart Poetteringa fatal error, while the latter just causes the server to lose a scoreboard
1fc5560911a7e9e8cf2993e17e1f0a001e148809Lennart Poetteringslot. So it might be advisable to use graceful restarts, with
1fc5560911a7e9e8cf2993e17e1f0a001e148809Lennart Poetteringan occasional hard restart. These problems are very difficult to work
1fc5560911a7e9e8cf2993e17e1f0a001e148809Lennart Poetteringaround, but fortunately most architectures do not require a scoreboard file.
1fc5560911a7e9e8cf2993e17e1f0a001e148809Lennart PoetteringSee the ScoreBoardFile documentation for a method to determine if your
1fc5560911a7e9e8cf2993e17e1f0a001e148809Lennart Poetteringarchitecture uses it.
1fc5560911a7e9e8cf2993e17e1f0a001e148809Lennart Poettering<P><CODE>NEXT</CODE> and <CODE>MACHTEN</CODE> (68k only) have small race
1fc5560911a7e9e8cf2993e17e1f0a001e148809Lennart Poetteringwhich can cause a restart/die signal to be lost, but should not cause the
38051578360c211e88ef4082ce5746adb52a500eLennart Poetteringserver to do anything otherwise problematic.
38051578360c211e88ef4082ce5746adb52a500eLennart Poettering<!-- they don't have sigaction, or we're not using it -djg -->
38051578360c211e88ef4082ce5746adb52a500eLennart Poettering<P>All architectures have a small race condition in each child involving
38051578360c211e88ef4082ce5746adb52a500eLennart Poetteringthe second and subsequent requests on a persistent HTTP connection
38051578360c211e88ef4082ce5746adb52a500eLennart Poettering(KeepAlive). It may exit after reading the request line but before
38051578360c211e88ef4082ce5746adb52a500eLennart Poetteringreading any of the request headers. There is a fix that was discovered
38051578360c211e88ef4082ce5746adb52a500eLennart Poetteringtoo late to make 1.2. In theory this isn't an issue because the KeepAlive
38051578360c211e88ef4082ce5746adb52a500eLennart Poetteringclient has to expect these events because of network latencies and
38051578360c211e88ef4082ce5746adb52a500eLennart Poetteringserver timeouts. In practice it doesn't seem to affect anything either
38051578360c211e88ef4082ce5746adb52a500eLennart Poettering-- in a test case the server was restarted twenty times per second and
38051578360c211e88ef4082ce5746adb52a500eLennart Poetteringclients successfully browsed the site without getting broken images or
38051578360c211e88ef4082ce5746adb52a500eLennart Poetteringempty documents.
38051578360c211e88ef4082ce5746adb52a500eLennart Poettering<!--#include virtual="footer.html" -->