stopping.html revision 57d0156f7bbd9ea3a72342cf9912aba61d118702
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <meta name="generator" content="HTML Tidy, see www.w3.org" />
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <title>Stopping and Restarting the Server</title>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <!--#include virtual="header.html" -->
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <h1 align="CENTER">Stopping and Restarting the Server</h1>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>This document covers stopping and restarting Apache on
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek Unix-like systems. Windows users should see <a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek href="platform/windows.html#signal">Signalling Apache when
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>You will notice many <code>httpd</code> executables running
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek on your system, but you should not send signals to any of them
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek except the parent, whose pid is in the <a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek href="mod/core.html#pidfile">PidFile</a>. That is to say you
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek shouldn't ever need to send signals to any process except the
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek parent. There are three signals that you can send the parent:
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <code>TERM</code>, <code>HUP</code>, and <code>USR1</code>,
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek which will be described in a moment.</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>To send a signal to the parent you should issue a command
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek such as:</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <blockquote>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek kill -TERM `cat /usr/local/apache/logs/httpd.pid`
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek </blockquote>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek You can read about its progress by issuing:
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <blockquote>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek </blockquote>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek Modify those examples to match your <a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek href="mod/core.html#serverroot">ServerRoot</a> and <a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek href="mod/core.html#pidfile">PidFile</a> settings.
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek href="programs/apachectl.html">apachectl</a> is provided which
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek automates the processing of signalling Apache. For details
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek about this script, see the documentation on <a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>Sending the <code>TERM</code> signal to the parent causes it
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek to immediately attempt to kill off all of its children. It may
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek take it several seconds to complete killing off its children.
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek Then the parent itself exits. Any requests in progress are
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek terminated, and no further requests are served.</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>The <code>USR1</code> signal causes the parent process to
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <em>advise</em> the children to exit after their current
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek request (or to exit immediately if they're not serving
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek anything). The parent re-reads its configuration files and
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek re-opens its log files. As each child dies off the parent
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek replaces it with a child from the new <em>generation</em> of
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek the configuration, which begins serving new requests
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek immediately.</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <i>On certain platforms that do not allow USR1 to be used for a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek graceful restart, an alternative signal may be used (such as
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek WINCH). apachectl graceful will send the right signal for your
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek platform.</i>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>This code is designed to always respect the <a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek href="mod/mpm_common.html#maxclients">MaxClients</a>, <a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek href="mod/prefork.html#minspareservers">MinSpareServers</a>,
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek href="mod/prefork.html#maxspareservers">MaxSpareServers</a>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek settings. Furthermore, it respects <a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek href="mod/mpm_common.html#startservers">StartServers</a> in the
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek following manner: if after one second at least StartServers new
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek children have not been created, then create enough to pick up
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek the slack. This is to say that the code tries to maintain both
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek the number of children appropriate for the current load on the
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek server, and respect your wishes with the StartServers
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek parameter.</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>Users of the <a href="mod/mod_status.html">status module</a>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek will notice that the server statistics are <strong>not</strong>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek set to zero when a <code>USR1</code> is sent. The code was
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek written to both minimize the time in which the server is unable
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek to serve new requests (they will be queued up by the operating
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek system, so they're not lost in any event) and to respect your
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek tuning parameters. In order to do this it has to keep the
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <em>scoreboard</em> used to keep track of all children across
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek generations.</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>The status module will also use a <code>G</code> to indicate
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek those children which are still serving requests started before
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek the graceful restart was given.</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>At present there is no way for a log rotation script using
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <code>USR1</code> to know for certain that all children writing
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek the pre-restart log have finished. We suggest that you use a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek suitable delay after sending the <code>USR1</code> signal
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek before you do anything with the old log. For example if most of
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek your hits take less than 10 minutes to complete for users on
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek low bandwidth links then you could wait 15 minutes before doing
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek anything with the old log.</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p><strong>Note:</strong> If your configuration file has errors
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek in it when you issue a restart then your parent will not
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek restart, it will exit with an error. In the case of graceful
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek restarts it will also leave children running when it exits.
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek (These are the children which are "gracefully exiting" by
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek handling their last request.) This will cause problems if you
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek attempt to restart the server -- it will not be able to bind to
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek its listening ports. Before doing a restart, you can check the
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek syntax of the configuration files with the <code>-t</code>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek command line argument (see <a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek href="programs/httpd.html">httpd</a>). This still will not
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek guarantee that the server will restart correctly. To check the
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek semantics of the configuration files as well as the syntax, you
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek can try starting httpd as a non-root user. If there are no
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek errors it will attempt to open its sockets and logs and fail
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek because it's not root (or because the currently running httpd
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek already has those ports bound). If it fails for any other
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek reason then it's probably a config file error and the error
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek should be fixed before issuing the graceful restart.</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>Sending the <code>HUP</code> signal to the parent causes it
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek to kill off its children like in <code>TERM</code> but the
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek parent doesn't exit. It re-reads its configuration files, and
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek re-opens any log files. Then it spawns a new set of children
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek and continues serving hits.</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>Users of the <a href="mod/mod_status.html">status module</a>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek will notice that the server statistics are set to zero when a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p><strong>Note:</strong> If your configuration file has errors
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek in it when you issue a restart then your parent will not
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek restart, it will exit with an error. See below for a method of
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek avoiding this.</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>Prior to Apache 1.2b9 there were several <em>race
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek conditions</em> involving the restart and die signals (a simple
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek description of race condition is: a time-sensitive problem, as
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek in if something happens at just the wrong time it won't behave
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek as expected). For those architectures that have the "right"
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek feature set we have eliminated as many as we can. But it should
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek be noted that there still do exist race conditions on certain
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek architectures.</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek href="mod/core.html#scoreboardfile">ScoreBoardFile</a> have the
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek potential to corrupt their scoreboards. This can result in the
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek "bind: Address already in use" (after <code>HUP</code>) or
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek "long lost child came home!" (after <code>USR1</code>). The
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek former is a fatal error, while the latter just causes the
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek server to lose a scoreboard slot. So it might be advisable to
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek use graceful restarts, with an occasional hard restart. These
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek problems are very difficult to work around, but fortunately
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek most architectures do not require a scoreboard file. See the <a
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek href="mod/core.html#scoreboardfile">ScoreBoardFile</a>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek documentation for a architecture uses it.</p>
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p><code>NEXT</code> and <code>MACHTEN</code> (68k only) have
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek small race conditions which can cause a restart/die signal to
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek be lost, but should not cause the server to do anything
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek otherwise problematic.
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <!-- they don't have sigaction, or we're not using it -djg -->
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek <p>All architectures have a small race condition in each child
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek involving the second and subsequent requests on a persistent
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek HTTP connection (KeepAlive). It may exit after reading the
bc58e1cfee742178f95922d964349d6c262f6df7Jakub Hrozek request line but before reading any of the request headers.
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek There is a fix that was discovered too late to make 1.2. In
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek theory this isn't an issue because the KeepAlive client has to
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek expect these events because of network latencies and server
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek timeouts. In practice it doesn't seem to affect anything either
8df69bbc58c2f4d3f0b34be9756d9ddf24b1db6dJakub Hrozek -- in a test case the server was restarted twenty times per
9797aa5907191cef5db8279e20ec75fd0abbe980Jakub Hrozek second and clients successfully browsed the site without
10c07e188323a2f9824b5e34379f3b1a9b37759eJakub Hrozek getting broken images or empty documents.
10c07e188323a2f9824b5e34379f3b1a9b37759eJakub Hrozek <!--#include virtual="footer.html" -->