From ab0d82ccf23fb3904c8d52eeea7a6a885f69df71 Mon Sep 17 00:00:00 2001
From: Colm MacCarthaigh <colm@apache.org>
Date: Fri, 26 Aug 2005 16:11:45 +0000
Subject: [PATCH] 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
---
 docs/manual/mod/mpm_common.xml     | 20 ++++++++++++++++++++
 docs/manual/programs/apachectl.xml |  7 +++++++
 docs/manual/programs/httpd.xml     |  5 +++--
 docs/manual/stopping.xml           | 27 ++++++++++++++++++++++++++-
 4 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/docs/manual/mod/mpm_common.xml b/docs/manual/mod/mpm_common.xml
index 1aefd752df..17daf039c4 100644
--- 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 8307ea73e3..2270620f21 100644
--- 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 4710eaf19b..1c5234efec 100644
--- 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 cc2057e307..d3798f65d8 100644
--- 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
-- 
2.40.0