Skip to content

Commit aef4ec1

Browse files
colmmacccolmmacc
committed
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
1 parent c69524d commit aef4ec1

4 files changed

Lines changed: 56 additions & 3 deletions

File tree

‎docs/manual/mod/mpm_common.xml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,26 @@ after a crash</description>
156156
</usage>
157157
</directivesynopsis>
158158

159+
<directivesynopsis>
160+
<name>GracefulShutdownTimeout</name>
161+
<description>Specify a timeout after which a gracefully shutdown server
162+
will exit.</description>
163+
<syntax>GracefulShutDownTimeout <var>seconds</var></syntax>
164+
<default>GracefulShutDownTimeout 0</default>
165+
<contextlist><context>server config</context></contextlist>
166+
<modulelist><module>prefork</module></modulelist>
167+
<compatibility>Available in version 2.4 and later</compatibility>
168+
169+
<usage>
170+
<p>The <directive>GracefulShutdownTimeout</directive> specifies
171+
how many seconds after receiving a "graceful-stop" signal, a
172+
server should continue to run, handling the existing connections.</p>
173+
174+
<p>Setting this value to zero means that the server will wait
175+
indefinitely until all remaining requests have been fully served.</p>
176+
</usage>
177+
</directivesynopsis>
178+
159179
<directivesynopsis>
160180
<name>Group</name>
161181
<description>Group under which the server will answer

‎docs/manual/programs/apachectl.xml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,13 @@ files as in <code>configtest</code> before initiating the
125125
restart to make sure Apache doesn't die. This is equivalent to
126126
<code>apachectl -k graceful</code>.</dd>
127127

128+
<dt><code>graceful-stop</code></dt>
129+
130+
<dd>Gracefully stops the Apache <program>httpd</program> daemon.
131+
This differs from a normal stop in that currently open connections are not
132+
aborted. A side effect is that old log files will not be closed immediately.
133+
This is equivalent to <code>apachectl -k graceful-stop</code>.</dd>
134+
128135
<dt><code>configtest</code></dt>
129136

130137
<dd>Run a configuration file syntax test. It parses the configuration

‎docs/manual/programs/httpd.xml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,8 @@
5151
[ -<strong>C</strong> <var>directive</var> ] [ -<strong>c</strong>
5252
<var>directive</var> ] [ -<strong>D</strong> <var>parameter</var> ]
5353
[ -<strong>e</strong> <var>level</var> ] [ -<strong>E</strong>
54-
<var>file</var> ] [ <strong>-k</strong> start|restart|graceful|stop ]
54+
<var>file</var> ]
55+
[ <strong>-k</strong> start|restart|graceful|stop|graceful-stop ]
5556
[ -<strong>R</strong> <var>directory</var> ] [ -<strong>h</strong> ]
5657
[ -<strong>l</strong> ] [ -<strong>L</strong> ] [ -<strong>S</strong> ]
5758
[ -<strong>t</strong> ] [ -<strong>v</strong> ] [ -<strong>V</strong> ]
@@ -84,7 +85,7 @@ path relative to the <directive
8485
module="core">ServerRoot</directive>. The default is
8586
<code>conf/httpd.conf</code>.</dd>
8687

87-
<dt><code>-k <code>start|restart|graceful|stop</code></code></dt>
88+
<dt><code>-k <code>start|restart|graceful|stop|graceful-stop</code></code></dt>
8889

8990
<dd>Signals <code>httpd</code> to start, restart, or stop. See <a
9091
href="../stopping.html">Stopping Apache</a> for more information.</dd>

‎docs/manual/stopping.xml‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@
6161

6262
<p>The second method of signaling the <program>httpd</program> processes
6363
is to use the <code>-k</code> command line options: <code>stop</code>,
64-
<code>restart</code>, and <code>graceful</code>,
64+
<code>restart</code>, <code>graceful</code> and <code>graceful-stop</code>,
6565
as described below. These are arguments to the <program>
6666
httpd</program> binary, but we recommend that
6767
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
181181
error. See above for a method of avoiding this.</note>
182182
</section>
183183

184+
<section id="gracefulstop"><title>Graceful Stop</title>
185+
186+
<dl><dt>Signal: WINCH</dt>
187+
<dd><code>apachectl -k graceful-stop</code></dd>
188+
</dl>
189+
190+
<p>The <code>WINCH</code> or <code>graceful-stop</code> signal causes
191+
the parent process to <em>advise</em> the children to exit after
192+
their current request (or to exit immediately if they're not
193+
serving anything). The parent will then remove it's <directive
194+
module="mpm_common">PidFile</directive> 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 <directive
198+
module="mpm_common">GracefulShutdownTimeout</directive> has been
199+
reached, the parent will also exit.</p>
200+
201+
<p>A <code>TERM</code> signal will immediately terminate the
202+
parent process and all children when in the "graceful" state. However
203+
as the <directive module="mpm_common">PidFile</directive> will
204+
have been removed, you will not be able to use
205+
<code>apachectl</code> or <code>httpd</code> to send this signal,</p>
206+
</section>
207+
208+
184209
<section id="race"><title>Appendix: signals and race conditions</title>
185210

186211
<p>Prior to Apache 1.2b9 there were several <em>race

0 commit comments

Comments
 (0)