stopping.html revision c0bd8a46007487ae47eb8c422ee2171260ec017a
c25356d5978632df6203437e1953bcb29e0c736fTimo Sirainen<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
a8fe899601735459641edae975c0fa08be8482e2Timo Sirainen<!--#include virtual="header.html" -->
2615df45a8027948a474abe5e817b34b0499c171Timo Sirainen<p>You will notice many <code>httpd</code> executables running on your system,
2615df45a8027948a474abe5e817b34b0499c171Timo Sirainenbut you should not send signals to any of them except the parent, whose
2615df45a8027948a474abe5e817b34b0499c171Timo Sirainenpid is in the <a href="mod/core.html#pidfile">PidFile</a>. That is to
29543188462c9348f365ec29115d777ffe4769d3Timo Sirainensay you shouldn't ever need to send signals to any process except the
29543188462c9348f365ec29115d777ffe4769d3Timo Sirainenparent. There are three signals that you can send the parent:
2615df45a8027948a474abe5e817b34b0499c171Timo Sirainen<code>TERM</code>, <code>HUP</code>, and <code>USR1</code>, which will
fa780a18c41881036af582f7a3473d6399e9d34dTimo Sirainenbe described in a moment.
37847ec8eaec9ad55c9df10ae109efe7b37ac573Timo Sirainen<p>To send a signal to the parent you should issue a command such as:
bdb026e2dc8a7c77585ed5ba489f0056df8074d4Timo Sirainen kill -TERM `cat /usr/local/etc/httpd/logs/httpd.pid`
dca6d617a23e3f93af3b8df59acb46478179fe55Timo SirainenYou can read about its progress by issuing:
8854395cdd21ca521b37ce669f3acb8445792b20Timo SirainenModify those examples to match your
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainen<a href="mod/core.html#serverroot">ServerRoot</a> and
dca6d617a23e3f93af3b8df59acb46478179fe55Timo Sirainen<a href="mod/core.html#pidfile">PidFile</a> settings.
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainen<p>Sending the <code>TERM</code> signal to the parent causes it to
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainenimmediately attempt to kill off all of its children. It may take it
917498e6f84969d2b93410c1e479735abe8e0ed7Timo Sirainenseveral seconds to complete killing off its children. Then the
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainenparent itself exits. Any requests in progress are terminated, and no
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainenfurther requests are served.
c0a87e5f3316a57e6f915882fa1951d0fbb74a61Timo Sirainen<p>Sending the <code>HUP</code> signal to the parent causes it to kill off
c0a87e5f3316a57e6f915882fa1951d0fbb74a61Timo Sirainenits children like in <code>TERM</code> but the parent doesn't exit. It
c0a87e5f3316a57e6f915882fa1951d0fbb74a61Timo Sirainenre-reads its configuration files, and re-opens any log files.
c0a87e5f3316a57e6f915882fa1951d0fbb74a61Timo SirainenThen it spawns a new set of children and continues
9fc97c8aa8190df87624d214bcc5d0b5362bec93Timo Sirainen<p>Users of the
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainen<a href="mod/mod_status.html">status module</a>
c040ee67d0ac0fb7375bb543965bf67dcae6affaTimo Sirainenwill notice that the server statistics are
d92f33f13830ba23d814342bf3ea8db721a15bb1Timo Sirainen<p><b>Note:</b> prior to release 1.2b9 this code is quite unstable and
d92f33f13830ba23d814342bf3ea8db721a15bb1Timo Sirainenshouldn't be used at all.
61e84692827b6a64912343f515c984853021483aTimo Sirainen<p>The <code>USR1</code> signal causes the parent process to <i>advise</i>
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainenthe children to exit after their current request (or to exit immediately
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainenif they're not serving anything). The parent re-reads its configuration
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainenfiles and re-opens its log files. As each child dies off the parent
dca6d617a23e3f93af3b8df59acb46478179fe55Timo Sirainenreplaces it with a child from the new <i>generation</i> of the
dca6d617a23e3f93af3b8df59acb46478179fe55Timo Sirainenconfiguration, which begins serving new requests immediately.
dca6d617a23e3f93af3b8df59acb46478179fe55Timo Sirainen<p>This code is designed to always respect the
dca6d617a23e3f93af3b8df59acb46478179fe55Timo Sirainen<a href="mod/core.html#maxclients">MaxClients</a>,
61b0637759146621cbb7edcbd0b03a71cfd66dfeTimo Sirainen<a href="mod/core.html#minspareservers">MinSpareServers</a>,
dca6d617a23e3f93af3b8df59acb46478179fe55Timo Sirainenand <a href="mod/core.html#maxspareservers">MaxSpareServers</a> settings.
b039dabf4c53f72454e795930e7643b6e0e625f9Timo SirainenFurthermore, it respects <a href="mod/core.html#startservers">StartServers</a>
4ba962c3e78f140facdcfb1e093c4c46de75ae24Timo Sirainenin the following manner: if after one second at least StartServers new
4ba962c3e78f140facdcfb1e093c4c46de75ae24Timo Sirainenchildren have not been created, then create enough to pick up the slack.
4ba962c3e78f140facdcfb1e093c4c46de75ae24Timo SirainenThis is to say that the code tries to maintain both the number of children
4ba962c3e78f140facdcfb1e093c4c46de75ae24Timo Sirainenappropriate for the current load on the server, and respect your wishes
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainenwith the StartServers parameter.
b039dabf4c53f72454e795930e7643b6e0e625f9Timo Sirainen<p>Users of the
2f30b72d49fbff0c4096125c139e4bdfef45669cTimo Sirainen<a href="mod/mod_status.html">status module</a>
0b25846ba794ce19536a24d4065beaf2a0bd9464Timo Sirainenwill notice that the server statistics
91b203fd2132510a47a4b34252c0ae0efd688a19Timo Sirainenare <b>not</b> set to zero when a <code>USR1</code> is sent. The code
71e88fae3be360e9a93b3398e743f99a6f05d2edTimo Sirainenwas written to both minimize the time in which the server is unable to serve
8854395cdd21ca521b37ce669f3acb8445792b20Timo Sirainennew requests (they will be queued up by the operating system, so they're
8854395cdd21ca521b37ce669f3acb8445792b20Timo Sirainennot lost in any event) and to respect your tuning parameters. In order
8854395cdd21ca521b37ce669f3acb8445792b20Timo Sirainento do this it has to keep the <i>scoreboard</i> used to keep track
8854395cdd21ca521b37ce669f3acb8445792b20Timo Sirainenof all children across generations.
8854395cdd21ca521b37ce669f3acb8445792b20Timo Sirainen<p>The status module will also use a <code>G</code> to indicate those
8854395cdd21ca521b37ce669f3acb8445792b20Timo Sirainenchildren which are still serving requests started before the graceful
8854395cdd21ca521b37ce669f3acb8445792b20Timo Sirainenrestart was given.
58a89627905e3590381cdd5eb931b9537c4b4ea6Timo Sirainen<p>At present there is no way for a log rotation script using
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainen<code>USR1</code> to know for certain that all children writing the
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainenpre-restart log have finished. We suggest that you use a suitable delay
8e371a3ce32bd64288786855b8ce0cb63f19f7d1Timo Sirainenafter sending the <code>USR1</code> signal before you do anything with the
8e371a3ce32bd64288786855b8ce0cb63f19f7d1Timo Sirainenold log. For example if most of your hits take less than 10 minutes to
8e371a3ce32bd64288786855b8ce0cb63f19f7d1Timo Sirainencomplete for users on low bandwidth links then you could wait 15 minutes
8e371a3ce32bd64288786855b8ce0cb63f19f7d1Timo Sirainenbefore doing anything with the old log.
8e371a3ce32bd64288786855b8ce0cb63f19f7d1Timo Sirainen<p>Prior to Apache 1.2b9 there were several <i>race conditions</i>
8e371a3ce32bd64288786855b8ce0cb63f19f7d1Timo Siraineninvolving the restart and die signals (a simple description of race
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainencondition is: a time-sensitive problem, as in if something happens at just
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainenthe wrong time it won't behave as expected). For those architectures that
bbd0a870f8639767e4e4011d2aedadac08d5c66fTimo Sirainenhave the "right" feature set we have eliminated as many as we can.
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo SirainenBut it should be noted that there still do exist race conditions on
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainencertain architectures.
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainenhref="mod/core.html#scoreboardfile">ScoreBoardFile</a> have the potential
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainento lose track of a child during graceful restart (you'll see an <a
c58906589cafc32df4c04ffbef933baadd3f2276Timo Sirainenhref="mod/core.html#errorlog">ErrorLog</a> message saying something about
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainena <i>long lost child</i>). The ScoreBoardFile directive explains how
a64adf62fa33f2463a86f990217b0c9078531a40Timo Sirainento figure out if your server uses a file, and possibly how to avoid it.
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo SirainenThere is also the potential that the scoreboard will be corrupted during
a27e065f1a1f91c7fbdf7c2ea1c387441af0cbb3Timo Sirainenany signalling, but this only has bad effects on graceful restart.
76b91bac787101e6b0075122ab6478dd98c8a884Timo Sirainen<p><code>NEXT</code> and <code>MACHTEN</code> have small race conditions
5694eeb99b69dea8033ca77ad69743c6b4871370Timo Sirainenwhich can cause a restart/die signal to be lost, but should not cause the
b13f738e8eb3f24dc2abf2c804f954b4d864ac6fTimo Sirainenserver to do anything otherwise problematic.
b13f738e8eb3f24dc2abf2c804f954b4d864ac6fTimo Sirainen<!-- they don't have sigaction, or we're not using it -djg -->
37847ec8eaec9ad55c9df10ae109efe7b37ac573Timo Sirainen<p>All architectures have a small race condition in each child involving
3fe67ec75ccae1230bb9eb9f16affc48377f6441Timo Sirainenthe second and subsequent requests on a persistent HTTP connection
37847ec8eaec9ad55c9df10ae109efe7b37ac573Timo Sirainen(KeepAlive). It may exit after reading the request line but before
bd4e36a8cd7257cca7d1434c49a1e343ed7c5100Timo Sirainenreading any of the request headers. There is a fix that was discovered
678d0463849ba777106eb7875f27db07a5d8e3dfTimo Sirainentoo late to make 1.2. In theory this isn't an issue because the KeepAlive
bd4e36a8cd7257cca7d1434c49a1e343ed7c5100Timo Sirainenclient has to expect these events because of network latencies and
bd4e36a8cd7257cca7d1434c49a1e343ed7c5100Timo Sirainenserver timeouts. In practice it doesn't seem to affect anything either
8ca217bf3aa23c7922d0d4aa44fcd2320416d61cMartti Rannanjärvi-- in a test case the server was restarted twenty times per second and
8ca217bf3aa23c7922d0d4aa44fcd2320416d61cMartti Rannanjärviclients successfully browsed the site without getting broken images or
8ca217bf3aa23c7922d0d4aa44fcd2320416d61cMartti Rannanjärviempty documents.
ff7056842f14fd3b30a2d327dfab165b9d15dd30Timo Sirainen<!--#include virtual="footer.html" -->