Commit aef4ec15 authored by Colm MacCarthaigh's avatar Colm MacCarthaigh
Browse files 

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
parent c69524da

docs/manual/mod/mpm_common.xml

+20 −0
Original line number Diff line number Diff line
@@ -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

docs/manual/programs/apachectl.xml

+7 −0
Original line number Diff line number Diff line
@@ -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

docs/manual/programs/httpd.xml

+3 −2
Original line number Diff line number Diff line
@@ -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>

docs/manual/stopping.xml

+26 −1
Original line number Diff line number Diff line
@@ -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