Documentation changes relevant to new graceful-stop command line argument

for httpd and apachectl, and the the "GracefulShutdownTimeout" directive.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@240271 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/docs/manual/mod/mpm_common.xml b/docs/manual/mod/mpm_common.xml
index 1aefd752df4c70473af19f9c0b0a95dc9f02f1a4..17daf039c45db357bd3a5a0f70013a8629ff8f8c 100644 (file)
--- a/docs/manual/mod/mpm_common.xml
+++ b/docs/manual/mod/mpm_common.xml
@@ -156,6 +156,26 @@ after a crash</description>
 </usage>
 </directivesynopsis>
 
+<directivesynopsis>
+<name>GracefulShutdownTimeout</name>
+<description>Specify a timeout after which a gracefully shutdown server
+will exit.</description>
+<syntax>GracefulShutDownTimeout <var>seconds</var></syntax>
+<default>GracefulShutDownTimeout 0</default>
+<contextlist><context>server config</context></contextlist>
+<modulelist><module>prefork</module></modulelist>
+<compatibility>Available in version 2.4 and later</compatibility>
+
+<usage>
+    <p>The <directive>GracefulShutdownTimeout</directive> specifies
+    how many seconds after receiving a "graceful-stop" signal, a 
+    server should continue to run, handling the existing connections.</p>
+
+    <p>Setting this value to zero means that the server will wait
+    indefinitely until all remaining requests have been fully served.</p>
+</usage>
+</directivesynopsis>
+
 <directivesynopsis>
 <name>Group</name>
 <description>Group under which the server will answer

diff --git a/docs/manual/programs/apachectl.xml b/docs/manual/programs/apachectl.xml
index 8307ea73e3622563fb0815b256b6eac0127d1abb..2270620f217a691da3dbecdd2c9cecce3fb12bc7 100644 (file)
--- a/docs/manual/programs/apachectl.xml
+++ b/docs/manual/programs/apachectl.xml
@@ -125,6 +125,13 @@ files as in <code>configtest</code> before initiating the
 restart to make sure Apache doesn't die.  This is equivalent to
 <code>apachectl -k graceful</code>.</dd>
 
+<dt><code>graceful-stop</code></dt>
+
+<dd>Gracefully stops the Apache <program>httpd</program> daemon.  
+This differs from a normal stop in that currently open connections are not 
+aborted.  A side effect is that old log files will not be closed immediately. 
+This is equivalent to <code>apachectl -k graceful-stop</code>.</dd>
+
 <dt><code>configtest</code></dt>
 
 <dd>Run a configuration file syntax test. It parses the configuration

diff --git a/docs/manual/programs/httpd.xml b/docs/manual/programs/httpd.xml
index 4710eaf19b9df4c96aed7073cb50db9ec816e935..1c5234efec9244ff2f9b1e96e82c08090ea434aa 100644 (file)
--- a/docs/manual/programs/httpd.xml
+++ b/docs/manual/programs/httpd.xml
@@ -51,7 +51,8 @@
      [ -<strong>C</strong> <var>directive</var> ] [ -<strong>c</strong>
      <var>directive</var> ] [ -<strong>D</strong> <var>parameter</var> ]
      [ -<strong>e</strong> <var>level</var> ] [ -<strong>E</strong>
-     <var>file</var> ] [ <strong>-k</strong> start|restart|graceful|stop ]
+     <var>file</var> ] 
+     [ <strong>-k</strong> start|restart|graceful|stop|graceful-stop ]
      [ -<strong>R</strong> <var>directory</var> ] [ -<strong>h</strong> ]
      [ -<strong>l</strong> ] [ -<strong>L</strong> ] [ -<strong>S</strong> ]
      [ -<strong>t</strong> ] [ -<strong>v</strong> ] [ -<strong>V</strong> ]
@@ -84,7 +85,7 @@ path relative to the <directive
 module="core">ServerRoot</directive>. The default is
 <code>conf/httpd.conf</code>.</dd>
 
-<dt><code>-k <code>start|restart|graceful|stop</code></code></dt>
+<dt><code>-k <code>start|restart|graceful|stop|graceful-stop</code></code></dt>
 
 <dd>Signals <code>httpd</code> to start, restart, or stop.  See <a
 href="../stopping.html">Stopping Apache</a> for more information.</dd>

diff --git a/docs/manual/stopping.xml b/docs/manual/stopping.xml
index cc2057e307f770c7aa32613933af1ec21dc32acf..d3798f65d89c8f28a38799b0c82bc5fbbd09e35e 100644 (file)
--- a/docs/manual/stopping.xml
+++ b/docs/manual/stopping.xml
@@ -61,7 +61,7 @@
 
     <p>The second method of signaling the <program>httpd</program> processes
     is to use the <code>-k</code> command line options: <code>stop</code>,
-    <code>restart</code>, and <code>graceful</code>,
+    <code>restart</code>, <code>graceful</code> and <code>graceful-stop</code>,
     as described below.  These are arguments to the <program>
     httpd</program> binary, but we recommend that
     you send them using the <program>apachectl</program> control script, which
@@ -181,6 +181,31 @@ restart then your parent will not restart, it will exit with an
 error. See above for a method of avoiding this.</note>
 </section>
 
+<section id="gracefulstop"><title>Graceful Stop</title>
+
+<dl><dt>Signal: WINCH</dt>
+<dd><code>apachectl -k graceful-stop</code></dd>
+</dl>
+
+    <p>The <code>WINCH</code> or <code>graceful-stop</code> signal causes
+    the parent process to <em>advise</em> the children to exit after
+    their current request (or to exit immediately if they're not
+    serving anything). The parent will then remove it's <directive 
+    module="mpm_common">PidFile</directive> and cease listening on
+    all ports. The parent will continue to run, and monitor children
+    which are handling requests. Once all children have finalised
+    and exited or the timeout specified by the <directive 
+    module="mpm_common">GracefulShutdownTimeout</directive> has been
+    reached, the parent will also exit.</p>
+    
+    <p>A <code>TERM</code> signal will immediately terminate the 
+    parent process and all children when in the "graceful" state. However
+    as the <directive module="mpm_common">PidFile</directive> will
+    have been removed, you will not be able to use 
+    <code>apachectl</code> or <code>httpd</code> to send this signal,</p>
+</section>
+
+
 <section id="race"><title>Appendix: signals and race conditions</title>
 
     <p>Prior to Apache 1.2b9 there were several <em>race