granicus.if.org Git - apache/blob - docs/manual/stopping.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>Stopping and Restarting - Apache HTTP Server</title>
   9 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
  15 <p class="apache">Apache HTTP Server Version 2.1</p>
  16 <img alt="" src="./images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="./images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="./">Version 2.1</a></div><div id="page-content"><div id="preamble"><h1>Stopping and Restarting</h1>
  20     <p>This document covers stopping and restarting Apache on
  21     Unix-like systems. Windows NT, 2000 and XP users should see
  22     <a href="platform/windows.html#winsvc">Running Apache as a
  23     Service</a> and Windows 9x and ME users should see <a href="platform/windows.html#wincons">Running Apache as a
  24     Console Application</a> for information on how to control
  25     Apache on those platforms.</p>
  26 </div>
  27 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#introduction">Introduction</a></li>
  28 <li><img alt="" src="./images/down.gif" /> <a href="#term">Stop Now</a></li>
  29 <li><img alt="" src="./images/down.gif" /> <a href="#graceful">Graceful Restart</a></li>
  30 <li><img alt="" src="./images/down.gif" /> <a href="#hup">Restart Now</a></li>
  31 <li><img alt="" src="./images/down.gif" /> <a href="#race">Appendix: signals and race conditions</a></li>
  32 </ul><h3>See also</h3><ul class="seealso"><li><a href="programs/httpd.html">httpd</a></li><li><a href="programs/apachectl.html">apachectl</a></li></ul></div>
  33 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  34 <div class="section">
  35 <h2><a name="introduction" id="introduction">Introduction</a></h2>
  36
  37     <p>In order to stop or restart Apache, you must send a signal to
  38     the running <code>httpd</code> processes.  There are two ways to
  39     send the signals.  First, you can use the unix <code>kill</code>
  40     command to directly send signals to the processes. You will
  41     notice many <code>httpd</code> executables running on your system,
  42     but you should not send signals to any of them except the parent,
  43     whose pid is in the <code class="directive"><a href="./mod/mpm_common.html#pidfile">PidFile</a></code>. That is to say you
  44     shouldn't ever need to send signals to any process except the
  45     parent. There are three signals that you can send the parent:
  46     <a href="#term"><code>TERM</code></a>,
  47     <a href="#hup"><code>HUP</code></a>, and
  48     <a href="#graceful"><code>USR1</code></a>, which
  49     will be described in a moment.</p>
  50
  51     <p>To send a signal to the parent you should issue a command
  52     such as:</p>
  53
  54 <div class="example"><p><code>kill -TERM `cat /usr/local/apache2/logs/httpd.pid`</code></p></div>
  55
  56     <p>The second method of signaling the <code>httpd</code> processes
  57     is to use the <code>-k</code> command line options: <code>stop</code>,
  58     <code>restart</code>, and <code>graceful</code>,
  59     as described below.  These are arguments to the <a href="programs/httpd.html">httpd</a> binary, but we recommend that
  60     you send them using the <a href="programs/apachectl.html">apachectl</a> control script, which
  61     will pass them through to <code>httpd</code>.</p>
  62
  63     <p>After you have signaled <code>httpd</code>, you can read about
  64     its progress by issuing:</p>
  65
  66 <div class="example"><p><code>tail -f /usr/local/apache2/logs/error_log</code></p></div>
  67
  68     <p>Modify those examples to match your <code class="directive"><a href="./mod/core.html#serverroot">ServerRoot</a></code> and <code class="directive"><a href="./mod/mpm_common.html#pidfile">PidFile</a></code> settings.</p>
  69 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  70 <div class="section">
  71 <h2><a name="term" id="term">Stop Now</a></h2>
  72
  73 <dl><dt>Signal: TERM</dt>
  74 <dd><code>apachectl -k stop</code></dd>
  75 </dl>
  76
  77     <p>Sending the <code>TERM</code> or <code>stop</code> signal to
  78     the parent causes it to immediately attempt to kill off all of its
  79     children. It may take it several seconds to complete killing off
  80     its children.  Then the parent itself exits. Any requests in
  81     progress are terminated, and no further requests are served.</p>
  82 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  83 <div class="section">
  84 <h2><a name="graceful" id="graceful">Graceful Restart</a></h2>
  85
  86 <dl><dt>Signal: USR1</dt>
  87 <dd><code>apachectl -k graceful</code></dd>
  88 </dl>
  89
  90     <p>The <code>USR1</code> or <code>graceful</code> signal causes
  91     the parent process to <em>advise</em> the children to exit after
  92     their current request (or to exit immediately if they're not
  93     serving anything). The parent re-reads its configuration files and
  94     re-opens its log files. As each child dies off the parent replaces
  95     it with a child from the new <em>generation</em> of the
  96     configuration, which begins serving new requests immediately.</p>
  97
  98     <div class="note">On certain platforms that do not allow <code>USR1</code> to
  99     be used for a graceful restart, an alternative signal may be used (such
 100     as <code>WINCH</code>). The command <code>apachectl graceful</code>
 101     will send the right signal for your platform.</div>
 102
 103     <p>This code is designed to always respect the process control
 104     directive of the MPMs, so the number of processes and threads
 105     available to serve clients will be maintained at the appropriate
 106     values throughout the restart process.  Furthermore, it respects
 107     <code class="directive"><a href="./mod/mpm_common.html#startservers">StartServers</a></code> in the
 108     following manner: if after one second at least <code class="directive"><a href="./mod/mpm_common.html#startservers">StartServers</a></code> new children have not
 109     been created, then create enough to pick up the slack. Hence the
 110     code tries to maintain both the number of children appropriate for
 111     the current load on the server, and respect your wishes with the
 112     <code class="directive">StartServers</code> parameter.</p>
 113
 114     <p>Users of the <code class="module"><a href="./mod/mod_status.html">mod_status</a></code>
 115     will notice that the server statistics are <strong>not</strong>
 116     set to zero when a <code>USR1</code> is sent. The code was
 117     written to both minimize the time in which the server is unable
 118     to serve new requests (they will be queued up by the operating
 119     system, so they're not lost in any event) and to respect your
 120     tuning parameters. In order to do this it has to keep the
 121     <em>scoreboard</em> used to keep track of all children across
 122     generations.</p>
 123
 124     <p>The status module will also use a <code>G</code> to indicate
 125     those children which are still serving requests started before
 126     the graceful restart was given.</p>
 127
 128     <p>At present there is no way for a log rotation script using
 129     <code>USR1</code> to know for certain that all children writing
 130     the pre-restart log have finished. We suggest that you use a
 131     suitable delay after sending the <code>USR1</code> signal
 132     before you do anything with the old log. For example if most of
 133     your hits take less than 10 minutes to complete for users on
 134     low bandwidth links then you could wait 15 minutes before doing
 135     anything with the old log.</p>
 136
 137     <div class="note">If your configuration file has errors
 138     in it when you issue a restart then your parent will not
 139     restart, it will exit with an error. In the case of graceful
 140     restarts it will also leave children running when it exits.
 141     (These are the children which are "gracefully exiting" by
 142     handling their last request.) This will cause problems if you
 143     attempt to restart the server -- it will not be able to bind to
 144     its listening ports. Before doing a restart, you can check the
 145     syntax of the configuration files with the <code>-t</code>
 146     command line argument (see <a href="programs/httpd.html">httpd</a>). This still will not
 147     guarantee that the server will restart correctly. To check the
 148     semantics of the configuration files as well as the syntax, you
 149     can try starting <code>httpd</code> as a non-root user. If there are no
 150     errors it will attempt to open its sockets and logs and fail
 151     because it's not root (or because the currently running <code>httpd</code>
 152     already has those ports bound). If it fails for any other
 153     reason then it's probably a config file error and the error
 154     should be fixed before issuing the graceful restart.</div>
 155 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 156 <div class="section">
 157 <h2><a name="hup" id="hup">Restart Now</a></h2>
 158
 159 <dl><dt>Signal: HUP</dt>
 160 <dd><code>apachectl -k restart</code></dd>
 161 </dl>
 162
 163     <p>Sending the <code>HUP</code> or <code>restart</code> signal to
 164     the parent causes it to kill off its children like in
 165     <code>TERM</code>, but the parent doesn't exit. It re-reads its
 166     configuration files, and re-opens any log files. Then it spawns a
 167     new set of children and continues serving hits.</p>
 168
 169     <p>Users of <code class="module"><a href="./mod/mod_status.html">mod_status</a></code>
 170     will notice that the server statistics are set to zero when a
 171     <code>HUP</code> is sent.</p>
 172
 173 <div class="note">If your configuration file has errors in it when you issue a
 174 restart then your parent will not restart, it will exit with an
 175 error. See above for a method of avoiding this.</div>
 176 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 177 <div class="section">
 178 <h2><a name="race" id="race">Appendix: signals and race conditions</a></h2>
 179
 180     <p>Prior to Apache 1.2b9 there were several <em>race
 181     conditions</em> involving the restart and die signals (a simple
 182     description of race condition is: a time-sensitive problem, as
 183     in if something happens at just the wrong time it won't behave
 184     as expected). For those architectures that have the "right"
 185     feature set we have eliminated as many as we can. But it should
 186     be noted that there still do exist race conditions on certain
 187     architectures.</p>
 188
 189     <p>Architectures that use an on disk <code class="directive"><a href="./mod/mpm_common.html#scoreboardfile">ScoreBoardFile</a></code> have the potential
 190     to corrupt their scoreboards. This can result in the "bind:
 191     Address already in use" (after <code>HUP</code>) or "long lost
 192     child came home!" (after <code>USR1</code>). The former is a fatal
 193     error, while the latter just causes the server to lose a
 194     scoreboard slot. So it might be advisable to use graceful
 195     restarts, with an occasional hard restart. These problems are very
 196     difficult to work around, but fortunately most architectures do
 197     not require a scoreboard file. See the <code class="directive"><a href="./mod/mpm_common.html#scoreboardfile">ScoreBoardFile</a></code> documentation for a
 198     architecture uses it.</p>
 199
 200     <p>All architectures have a small race condition in each child
 201     involving the second and subsequent requests on a persistent
 202     HTTP connection (KeepAlive). It may exit after reading the
 203     request line but before reading any of the request headers.
 204     There is a fix that was discovered too late to make 1.2. In
 205     theory this isn't an issue because the KeepAlive client has to
 206     expect these events because of network latencies and server
 207     timeouts. In practice it doesn't seem to affect anything either
 208     -- in a test case the server was restarted twenty times per
 209     second and clients successfully browsed the site without
 210     getting broken images or empty documents. </p>
 211 </div></div>
 212 <div id="footer">
 213 <p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
 214 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div>
 215 </body></html>