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.3</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/">Documentation</a> &gt; <a href="./">Version 2.3</a></div><div id="page-content"><div id="preamble"><h1>Stopping and Restarting</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="./de/stopping.html" hreflang="de" rel="alternate" title="Deutsch">&nbsp;de&nbsp;</a> |
  22 <a href="./en/stopping.html" title="English">&nbsp;en&nbsp;</a> |
  23 <a href="./es/stopping.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
  24 <a href="./fr/stopping.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
  25 <a href="./ja/stopping.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
  26 <a href="./ko/stopping.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
  27 <a href="./tr/stopping.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  28 </div>
  29
  30     <p>This document covers stopping and restarting Apache on
  31     Unix-like systems. Windows NT, 2000 and XP users should see
  32     <a href="platform/windows.html#winsvc">Running Apache as a
  33     Service</a> and Windows 9x and ME users should see <a href="platform/windows.html#wincons">Running Apache as a
  34     Console Application</a> for information on how to control
  35     Apache on those platforms.</p>
  36 </div>
  37 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#introduction">Introduction</a></li>
  38 <li><img alt="" src="./images/down.gif" /> <a href="#term">Stop Now</a></li>
  39 <li><img alt="" src="./images/down.gif" /> <a href="#graceful">Graceful Restart</a></li>
  40 <li><img alt="" src="./images/down.gif" /> <a href="#hup">Restart Now</a></li>
  41 <li><img alt="" src="./images/down.gif" /> <a href="#gracefulstop">Graceful Stop</a></li>
  42 </ul><h3>See also</h3><ul class="seealso"><li><code class="program"><a href="./programs/httpd.html">httpd</a></code></li><li><code class="program"><a href="./programs/apachectl.html">apachectl</a></code></li><li><a href="invoking.html">Starting</a></li></ul></div>
  43 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  44 <div class="section">
  45 <h2><a name="introduction" id="introduction">Introduction</a></h2>
  46
  47     <p>In order to stop or restart Apache, you must send a signal to
  48     the running <code class="program"><a href="./programs/httpd.html">httpd</a></code> processes.  There are two ways to
  49     send the signals.  First, you can use the unix <code>kill</code>
  50     command to directly send signals to the processes. You will
  51     notice many <code class="program"><a href="./programs/httpd.html">httpd</a></code> executables running on your system,
  52     but you should not send signals to any of them except the parent,
  53     whose pid is in the <code class="directive"><a href="./mod/mpm_common.html#pidfile">PidFile</a></code>. That is to say you
  54     shouldn't ever need to send signals to any process except the
  55     parent. There are four signals that you can send the parent:
  56     <code><a href="#term">TERM</a></code>,
  57     <code><a href="#graceful">USR1</a></code>,
  58     <code><a href="#hup">HUP</a></code>, and
  59     <code><a href="#gracefulstop">WINCH</a></code>, which
  60     will be described in a moment.</p>
  61
  62     <p>To send a signal to the parent you should issue a command
  63     such as:</p>
  64
  65 <div class="example"><p><code>kill -TERM `cat /usr/local/apache2/logs/httpd.pid`</code></p></div>
  66
  67     <p>The second method of signaling the <code class="program"><a href="./programs/httpd.html">httpd</a></code> processes
  68     is to use the <code>-k</code> command line options: <code>stop</code>,
  69     <code>restart</code>, <code>graceful</code> and <code>graceful-stop</code>,
  70     as described below.  These are arguments to the <code class="program"><a href="./programs/httpd.html">httpd</a></code> binary, but we recommend that
  71     you send them using the <code class="program"><a href="./programs/apachectl.html">apachectl</a></code> control script, which
  72     will pass them through to <code class="program"><a href="./programs/httpd.html">httpd</a></code>.</p>
  73
  74     <p>After you have signaled <code class="program"><a href="./programs/httpd.html">httpd</a></code>, you can read about
  75     its progress by issuing:</p>
  76
  77 <div class="example"><p><code>tail -f /usr/local/apache2/logs/error_log</code></p></div>
  78
  79     <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>
  80 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  81 <div class="section">
  82 <h2><a name="term" id="term">Stop Now</a></h2>
  83
  84 <dl><dt>Signal: TERM</dt>
  85 <dd><code>apachectl -k stop</code></dd>
  86 </dl>
  87
  88     <p>Sending the <code>TERM</code> or <code>stop</code> signal to
  89     the parent causes it to immediately attempt to kill off all of its
  90     children. It may take it several seconds to complete killing off
  91     its children.  Then the parent itself exits. Any requests in
  92     progress are terminated, and no further requests are served.</p>
  93 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  94 <div class="section">
  95 <h2><a name="graceful" id="graceful">Graceful Restart</a></h2>
  96
  97 <dl><dt>Signal: USR1</dt>
  98 <dd><code>apachectl -k graceful</code></dd>
  99 </dl>
 100
 101     <p>The <code>USR1</code> or <code>graceful</code> signal causes
 102     the parent process to <em>advise</em> the children to exit after
 103     their current request (or to exit immediately if they're not
 104     serving anything). The parent re-reads its configuration files and
 105     re-opens its log files. As each child dies off the parent replaces
 106     it with a child from the new <em>generation</em> of the
 107     configuration, which begins serving new requests immediately.</p>
 108
 109     <p>This code is designed to always respect the process control
 110     directive of the MPMs, so the number of processes and threads
 111     available to serve clients will be maintained at the appropriate
 112     values throughout the restart process.  Furthermore, it respects
 113     <code class="directive"><a href="./mod/mpm_common.html#startservers">StartServers</a></code> in the
 114     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
 115     been created, then create enough to pick up the slack. Hence the
 116     code tries to maintain both the number of children appropriate for
 117     the current load on the server, and respect your wishes with the
 118     <code class="directive"><a href="./mod/mpm_common.html#startservers">StartServers</a></code>
 119     parameter.</p>
 120
 121     <p>Users of <code class="module"><a href="./mod/mod_status.html">mod_status</a></code>
 122     will notice that the server statistics are <strong>not</strong>
 123     set to zero when a <code>USR1</code> is sent. The code was
 124     written to both minimize the time in which the server is unable
 125     to serve new requests (they will be queued up by the operating
 126     system, so they're not lost in any event) and to respect your
 127     tuning parameters. In order to do this it has to keep the
 128     <em>scoreboard</em> used to keep track of all children across
 129     generations.</p>
 130
 131     <p>The status module will also use a <code>G</code> to indicate
 132     those children which are still serving requests started before
 133     the graceful restart was given.</p>
 134
 135     <p>At present there is no way for a log rotation script using
 136     <code>USR1</code> to know for certain that all children writing
 137     the pre-restart log have finished. We suggest that you use a
 138     suitable delay after sending the <code>USR1</code> signal
 139     before you do anything with the old log. For example if most of
 140     your hits take less than 10 minutes to complete for users on
 141     low bandwidth links then you could wait 15 minutes before doing
 142     anything with the old log.</p>
 143
 144     <div class="note">
 145     <p>When you issue a restart, a syntax check is first run, to
 146     ensure that there are no errors in the configuration files.
 147     If your configuration file has errors in it, you will get an
 148     error message about that syntax error, and the server will refuse to
 149     restart. This avoids the situation where the server halts and then
 150     cannot restart, leaving you with a non-functioning server.</p>
 151
 152     <p>This still will not
 153     guarantee that the server will restart correctly. To check the
 154     semantics of the configuration files as well as the syntax, you
 155     can try starting <code class="program"><a href="./programs/httpd.html">httpd</a></code> as a non-root user. If there
 156     are no errors it will attempt to open its sockets and logs and fail
 157     because it's not root (or because the currently running
 158     <code class="program"><a href="./programs/httpd.html">httpd</a></code> already has those ports bound). If it fails
 159     for any other reason then it's probably a config file error and the error
 160     should be fixed before issuing the graceful restart.</p></div>
 161 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 162 <div class="section">
 163 <h2><a name="hup" id="hup">Restart Now</a></h2>
 164
 165 <dl><dt>Signal: HUP</dt>
 166 <dd><code>apachectl -k restart</code></dd>
 167 </dl>
 168
 169     <p>Sending the <code>HUP</code> or <code>restart</code> signal to
 170     the parent causes it to kill off its children like in
 171     <code>TERM</code>, but the parent doesn't exit. It re-reads its
 172     configuration files, and re-opens any log files. Then it spawns a
 173     new set of children and continues serving hits.</p>
 174
 175     <p>Users of <code class="module"><a href="./mod/mod_status.html">mod_status</a></code>
 176     will notice that the server statistics are set to zero when a
 177     <code>HUP</code> is sent.</p>
 178
 179 <div class="note">As with a graceful restart, a syntax check is run before the
 180 restart is attempted. If your configuration file has errors in it, the
 181 restart will not be attempted, and you will receive notification of the
 182 syntax error(s).</div>
 183 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 184 <div class="section">
 185 <h2><a name="gracefulstop" id="gracefulstop">Graceful Stop</a></h2>
 186
 187 <dl><dt>Signal: WINCH</dt>
 188 <dd><code>apachectl -k graceful-stop</code></dd>
 189 </dl>
 190
 191     <p>The <code>WINCH</code> or <code>graceful-stop</code> signal causes
 192     the parent process to <em>advise</em> the children to exit after
 193     their current request (or to exit immediately if they're not
 194     serving anything). The parent will then remove its <code class="directive"><a href="./mod/mpm_common.html#pidfile">PidFile</a></code> and cease listening on
 195     all ports. The parent will continue to run, and monitor children
 196     which are handling requests. Once all children have finalised
 197     and exited or the timeout specified by the <code class="directive"><a href="./mod/mpm_common.html#gracefulshutdowntimeout">GracefulShutdownTimeout</a></code> has been
 198     reached, the parent will also exit.  If the timeout is reached,
 199     any remaining children will be sent the <code>TERM</code> signal
 200     to force them to exit.</p>
 201
 202     <p>A <code>TERM</code> signal will immediately terminate the
 203     parent process and all children when in the "graceful" state. However
 204     as the <code class="directive"><a href="./mod/mpm_common.html#pidfile">PidFile</a></code> will
 205     have been removed, you will not be able to use
 206     <code>apachectl</code> or <code>httpd</code> to send this signal.</p>
 207
 208     <div class="note"><p>The <code>graceful-stop</code> signal allows you to run multiple
 209     identically configured instances of <code class="program"><a href="./programs/httpd.html">httpd</a></code> at the
 210     same time. This is a powerful feature when performing graceful
 211     upgrades of Apache, however it can also cause deadlocks and race
 212     conditions with some configurations.</p>
 213
 214     <p>Care has been taken to ensure that on-disk files
 215     such as the <code class="directive"><a href="./mod/core.html#lockfile">Lockfile</a></code> and <code class="directive"><a href="./mod/mod_cgid.html#scriptsock">ScriptSock</a></code> files contain the server
 216     PID, and should coexist without problem. However, if a configuration
 217     directive, third-party module or persistent CGI utilises any other on-disk
 218     lock or  state files, care should be taken to ensure that multiple running
 219     instances of <code class="program"><a href="./programs/httpd.html">httpd</a></code> do not clobber each others files.</p>
 220
 221     <p>You should also be wary of other potential race conditions, such as
 222     using <code class="program"><a href="./programs/rotatelogs.html">rotatelogs</a></code> style piped logging. Multiple running
 223     instances of <code class="program"><a href="./programs/rotatelogs.html">rotatelogs</a></code> attempting to rotate the same
 224     logfiles at the same time may destroy each other's logfiles.</p></div>
 225 </div></div>
 226 <div class="bottomlang">
 227 <p><span>Available Languages: </span><a href="./de/stopping.html" hreflang="de" rel="alternate" title="Deutsch">&nbsp;de&nbsp;</a> |
 228 <a href="./en/stopping.html" title="English">&nbsp;en&nbsp;</a> |
 229 <a href="./es/stopping.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
 230 <a href="./fr/stopping.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
 231 <a href="./ja/stopping.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
 232 <a href="./ko/stopping.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
 233 <a href="./tr/stopping.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
 234 </div><div id="footer">
 235 <p class="apache">Copyright 2008 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 236 <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>
 237 </body></html>