stopping.html revision 20ed258be862d40023bc04cb4666e418f1853115
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey BGCOLOR="#FFFFFF"
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey TEXT="#000000"
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey LINK="#0000FF"
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey VLINK="#000080"
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey ALINK="#FF0000"
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<!--#include virtual="header.html" -->
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<H1 ALIGN="CENTER">Stopping and Restarting Apache</H1>
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P>You will notice many <CODE>httpd</CODE> executables running on your system,
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseybut you should not send signals to any of them except the parent, whose
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseypid is in the <A HREF="mod/core.html#pidfile">PidFile</A>. That is to
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseysay you shouldn't ever need to send signals to any process except the
8367f835047e57c70a508975d020905f0173f51aTom Rumseyparent. There are three signals that you can send the parent:
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<CODE>TERM</CODE>, <CODE>HUP</CODE>, and <CODE>USR1</CODE>, which will
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseybe described in a moment.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P>To send a signal to the parent you should issue a command such as:
8367f835047e57c70a508975d020905f0173f51aTom Rumsey kill -TERM `cat /usr/local/apache/logs/httpd.pid`
efafbd2aa55b834f714882683fa864a0ac9e64aaTom RumseyYou can read about its progress by issuing:
efafbd2aa55b834f714882683fa864a0ac9e64aaTom RumseyModify those examples to match your
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<A HREF="mod/core.html#serverroot">ServerRoot</A> and
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<A HREF="mod/core.html#pidfile">PidFile</A> settings.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<p>As of Apache 1.3 we provide a script <code>src/support/apachectl</code>
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseywhich can be used to start, stop, and restart Apache. It may need a
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseylittle customization for your system, see the comments at the top of
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P>Sending the <CODE>TERM</CODE> signal to the parent causes it to
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyimmediately attempt to kill off all of its children. It may take it
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyseveral seconds to complete killing off its children. Then the
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyparent itself exits. Any requests in progress are terminated, and no
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyfurther requests are served.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P>Sending the <CODE>HUP</CODE> signal to the parent causes it to kill off
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyits children like in <CODE>TERM</CODE> but the parent doesn't exit. It
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyre-reads its configuration files, and re-opens any log files.
8367f835047e57c70a508975d020905f0173f51aTom RumseyThen it spawns a new set of children and continues
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyserving hits.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P>Users of the
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseywill notice that the server statistics are
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P><STRONG>Note:</STRONG> If your configuration file has errors in it when you issue a
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyrestart then your parent will not restart, it will exit with an error.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom RumseySee below for a method of avoiding this.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P><STRONG>Note:</STRONG> prior to release 1.2b9 this code is quite unstable and
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyshouldn't be used at all.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P>The <CODE>USR1</CODE> signal causes the parent process to <EM>advise</EM>
8367f835047e57c70a508975d020905f0173f51aTom Rumseythe children to exit after their current request (or to exit immediately
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyif they're not serving anything). The parent re-reads its configuration
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyfiles and re-opens its log files. As each child dies off the parent
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyreplaces it with a child from the new <EM>generation</EM> of the
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyconfiguration, which begins serving new requests immediately.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P>This code is designed to always respect the
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<A HREF="mod/core.html#maxclients">MaxClients</A>,
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<A HREF="mod/core.html#minspareservers">MinSpareServers</A>,
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyand <A HREF="mod/core.html#maxspareservers">MaxSpareServers</A> settings.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom RumseyFurthermore, it respects <A HREF="mod/core.html#startservers">StartServers</A>
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyin the following manner: if after one second at least StartServers new
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseychildren have not been created, then create enough to pick up the slack.
8367f835047e57c70a508975d020905f0173f51aTom RumseyThis is to say that the code tries to maintain both the number of children
c00a5587d32883c0f366fd6c47c3e674dad9dba7Tom Rumseyappropriate for the current load on the server, and respect your wishes
8367f835047e57c70a508975d020905f0173f51aTom Rumseywith the StartServers parameter.
c00a5587d32883c0f366fd6c47c3e674dad9dba7Tom Rumsey<P>Users of the
8367f835047e57c70a508975d020905f0173f51aTom Rumseywill notice that the server statistics
c00a5587d32883c0f366fd6c47c3e674dad9dba7Tom Rumseyare <STRONG>not</STRONG> set to zero when a <CODE>USR1</CODE> is sent. The code
c00a5587d32883c0f366fd6c47c3e674dad9dba7Tom Rumseywas written to both minimize the time in which the server is unable to serve
c00a5587d32883c0f366fd6c47c3e674dad9dba7Tom Rumseynew requests (they will be queued up by the operating system, so they're
c00a5587d32883c0f366fd6c47c3e674dad9dba7Tom Rumseynot lost in any event) and to respect your tuning parameters. In order
8367f835047e57c70a508975d020905f0173f51aTom Rumseyto do this it has to keep the <EM>scoreboard</EM> used to keep track
8367f835047e57c70a508975d020905f0173f51aTom Rumseyof all children across generations.
8367f835047e57c70a508975d020905f0173f51aTom Rumsey<P>The status module will also use a <CODE>G</CODE> to indicate those
8367f835047e57c70a508975d020905f0173f51aTom Rumseychildren which are still serving requests started before the graceful
8367f835047e57c70a508975d020905f0173f51aTom Rumseyrestart was given.
8367f835047e57c70a508975d020905f0173f51aTom Rumsey<P>At present there is no way for a log rotation script using
8367f835047e57c70a508975d020905f0173f51aTom Rumsey<CODE>USR1</CODE> to know for certain that all children writing the
8367f835047e57c70a508975d020905f0173f51aTom Rumseypre-restart log have finished. We suggest that you use a suitable delay
8367f835047e57c70a508975d020905f0173f51aTom Rumseyafter sending the <CODE>USR1</CODE> signal before you do anything with the
8367f835047e57c70a508975d020905f0173f51aTom Rumseyold log. For example if most of your hits take less than 10 minutes to
8367f835047e57c70a508975d020905f0173f51aTom Rumseycomplete for users on low bandwidth links then you could wait 15 minutes
8367f835047e57c70a508975d020905f0173f51aTom Rumseybefore doing anything with the old log.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P><STRONG>Note:</STRONG> If your configuration file has errors in it when you issue a
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyrestart then your parent will not restart, it will exit with an error.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom RumseyIn the case of graceful
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyrestarts it will also leave children running when it exits. (These are
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseythe children which are "gracefully exiting" by handling their last request.)
efafbd2aa55b834f714882683fa864a0ac9e64aaTom RumseyThis will cause problems if you attempt to restart the server -- it will
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseynot be able to bind to its listening ports. At present the only work
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyaround is to check the syntax of your files before doing a restart. The
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyeasiest way is to just run httpd as a non-root user. If there are no
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyerrors it will attempt to open its sockets and logs and fail because it's
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseynot root (or because the currently running httpd already has those ports
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseybound). If it fails for any other reason then it's probably a config file
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyerror and the error should be fixed before issuing the graceful restart.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM>
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyinvolving the restart and die signals (a simple description of race
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseycondition is: a time-sensitive problem, as in if something happens at just
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseythe wrong time it won't behave as expected). For those architectures that
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyhave the "right" feature set we have eliminated as many as we can.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom RumseyBut it should be noted that there still do exist race conditions on
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseycertain architectures.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P>Architectures that use an on disk
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<A HREF="mod/core.html#scoreboardfile">ScoreBoardFile</A>
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyhave the potential to corrupt their scoreboards. This can result in
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseythe "bind: Address already in use" (after <CODE>HUP</CODE>) or
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey"long lost child came home!" (after <CODE>USR1</CODE>). The former is
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseya fatal error, while the latter just causes the server to lose a scoreboard
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyslot. So it might be advisable to use graceful restarts, with
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyan occasional hard restart. These problems are very difficult to work
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyaround, but fortunately most architectures do not require a scoreboard file.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom RumseySee the ScoreBoardFile documentation for a method to determine if your
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyarchitecture uses it.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P><CODE>NEXT</CODE> and <CODE>MACHTEN</CODE> (68k only) have small race
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseywhich can cause a restart/die signal to be lost, but should not cause the
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyserver to do anything otherwise problematic.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<!-- they don't have sigaction, or we're not using it -djg -->
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<P>All architectures have a small race condition in each child involving
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseythe second and subsequent requests on a persistent HTTP connection
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey(KeepAlive). It may exit after reading the request line but before
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyreading any of the request headers. There is a fix that was discovered
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseytoo late to make 1.2. In theory this isn't an issue because the KeepAlive
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyclient has to expect these events because of network latencies and
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyserver timeouts. In practice it doesn't seem to affect anything either
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey-- in a test case the server was restarted twenty times per second and
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyclients successfully browsed the site without getting broken images or
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumseyempty documents.
efafbd2aa55b834f714882683fa864a0ac9e64aaTom Rumsey<!--#include virtual="footer.html" -->