1 <?xml version='1.0' encoding='UTF-8' ?>
2 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
5 <relativepath href="."/>
7 <title>Stopping and Restarting</title>
10 <p>This document covers stopping and restarting Apache on
11 Unix-like systems. Windows users should see <a
12 href="platform/windows.html#signal">Signalling Apache when
16 <section id="introduction"><title>Introduction</title>
18 <p>You will notice many <code>httpd</code> executables running on
19 your system, but you should not send signals to any of them except
20 the parent, whose pid is in the <directive
21 module="mpm_common">PidFile</directive>. That is to say you shouldn't ever
22 need to send signals to any process except the parent. There are
23 three signals that you can send the parent: <code>TERM</code>,
24 <code>HUP</code>, and <code>USR1</code>, which will be described
27 <p>To send a signal to the parent you should issue a command
30 <example>kill -TERM `cat /usr/local/apache/logs/httpd.pid`</example>
32 <p>You can read about its progress by issuing:</p>
34 <example>tail -f /usr/local/apache/logs/error_log</example>
36 <p>Modify those examples to match your <directive
37 module="core">ServerRoot</directive> and <directive
38 module="mpm_common">PidFile</directive> settings.</p>
40 <p>A shell script called <a
41 href="programs/apachectl.html">apachectl</a> is provided which
42 automates the processing of signalling Apache. For details
43 about this script, see the documentation on <a
44 href="invoking.html">starting Apache</a>.</p>
47 <section id="term"><title>Stop Now</title>
49 <dl><dt>Signal: TERM</dt>
50 <dd><code>apachectl stop</code></dd>
53 <p>Sending the <code>TERM</code> signal to the parent causes it
54 to immediately attempt to kill off all of its children. It may
55 take it several seconds to complete killing off its children.
56 Then the parent itself exits. Any requests in progress are
57 terminated, and no further requests are served.</p>
60 <section id="graceful"><title>Graceful Restart</title>
62 <dl><dt>Signal: USR1</dt>
63 <dd><code>apachectl graceful</code></dd>
66 <p>The <code>USR1</code> signal causes the parent process to
67 <em>advise</em> the children to exit after their current
68 request (or to exit immediately if they're not serving
69 anything). The parent re-reads its configuration files and
70 re-opens its log files. As each child dies off the parent
71 replaces it with a child from the new <em>generation</em> of
72 the configuration, which begins serving new requests
75 <note>On certain platforms that do not allow USR1 to be used for a
76 graceful restart, an alternative signal may be used (such as
77 WINCH). The command <code>apachectl graceful</code> will send the
78 right signal for your platform.</note>
80 <p>This code is designed to always respect the process control
81 directive of the MPMs, so the number of processes and threads
82 available to serve clients will be maintained at the appropriate
83 values throughout the restart process. Furthermore, it respects
84 <directive module="mpm_common">StartServers</directive> in the
85 following manner: if after one second at least <directive
86 module="mpm_common">StartServers</directive> new children have not
87 been created, then create enough to pick up the slack. Hence the
88 code tries to maintain both the number of children appropriate for
89 the current load on the server, and respect your wishes with the
90 StartServers parameter.</p>
92 <p>Users of the <module>mod_status</module>
93 will notice that the server statistics are <strong>not</strong>
94 set to zero when a <code>USR1</code> is sent. The code was
95 written to both minimize the time in which the server is unable
96 to serve new requests (they will be queued up by the operating
97 system, so they're not lost in any event) and to respect your
98 tuning parameters. In order to do this it has to keep the
99 <em>scoreboard</em> used to keep track of all children across
102 <p>The status module will also use a <code>G</code> to indicate
103 those children which are still serving requests started before
104 the graceful restart was given.</p>
106 <p>At present there is no way for a log rotation script using
107 <code>USR1</code> to know for certain that all children writing
108 the pre-restart log have finished. We suggest that you use a
109 suitable delay after sending the <code>USR1</code> signal
110 before you do anything with the old log. For example if most of
111 your hits take less than 10 minutes to complete for users on
112 low bandwidth links then you could wait 15 minutes before doing
113 anything with the old log.</p>
115 <note>If your configuration file has errors
116 in it when you issue a restart then your parent will not
117 restart, it will exit with an error. In the case of graceful
118 restarts it will also leave children running when it exits.
119 (These are the children which are "gracefully exiting" by
120 handling their last request.) This will cause problems if you
121 attempt to restart the server -- it will not be able to bind to
122 its listening ports. Before doing a restart, you can check the
123 syntax of the configuration files with the <code>-t</code>
124 command line argument (see <a
125 href="programs/httpd.html">httpd</a>). This still will not
126 guarantee that the server will restart correctly. To check the
127 semantics of the configuration files as well as the syntax, you
128 can try starting httpd as a non-root user. If there are no
129 errors it will attempt to open its sockets and logs and fail
130 because it's not root (or because the currently running httpd
131 already has those ports bound). If it fails for any other
132 reason then it's probably a config file error and the error
133 should be fixed before issuing the graceful restart.</note>
136 <section id="hup"><title>Restart Now</title>
138 <dl><dt>Signal: HUP</dt>
139 <dd><code>apachectl restart</code></dd>
142 <p>Sending the <code>HUP</code> signal to the parent causes it
143 to kill off its children like in <code>TERM</code> but the
144 parent doesn't exit. It re-reads its configuration files, and
145 re-opens any log files. Then it spawns a new set of children
146 and continues serving hits.</p>
148 <p>Users of <module>mod_status</module>
149 will notice that the server statistics are set to zero when a
150 <code>HUP</code> is sent.</p>
152 <note>If your configuration file has errors in it when you issue a
153 restart then your parent will not restart, it will exit with an
154 error. See above for a method of avoiding this.</note>
157 <section id="race"><title>Appendix: signals and race conditions</title>
159 <p>Prior to Apache 1.2b9 there were several <em>race
160 conditions</em> involving the restart and die signals (a simple
161 description of race condition is: a time-sensitive problem, as
162 in if something happens at just the wrong time it won't behave
163 as expected). For those architectures that have the "right"
164 feature set we have eliminated as many as we can. But it should
165 be noted that there still do exist race conditions on certain
168 <p>Architectures that use an on disk <directive
169 module="mpm_common">ScoreBoardFile</directive> have the potential
170 to corrupt their scoreboards. This can result in the "bind:
171 Address already in use" (after <code>HUP</code>) or "long lost
172 child came home!" (after <code>USR1</code>). The former is a fatal
173 error, while the latter just causes the server to lose a
174 scoreboard slot. So it might be advisable to use graceful
175 restarts, with an occasional hard restart. These problems are very
176 difficult to work around, but fortunately most architectures do
177 not require a scoreboard file. See the <directive
178 module="mpm_common">ScoreBoardFile</directive> documentation for a
179 architecture uses it.</p>
181 <p>All architectures have a small race condition in each child
182 involving the second and subsequent requests on a persistent
183 HTTP connection (KeepAlive). It may exit after reading the
184 request line but before reading any of the request headers.
185 There is a fix that was discovered too late to make 1.2. In
186 theory this isn't an issue because the KeepAlive client has to
187 expect these events because of network latencies and server
188 timeouts. In practice it doesn't seem to affect anything either
189 -- in a test case the server was restarted twenty times per
190 second and clients successfully browsed the site without
191 getting broken images or empty documents. </p>