stopping.xml revision c68aa7f213d409d464eaa6b963afb28678548f4f
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
33bdcae1f7a1a65e351dda2a766a0cf28b1e695dnd<!-- $LastChangedRevision$ -->
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb Licensed to the Apache Software Foundation (ASF) under one or more
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb contributor license agreements. See the NOTICE file distributed with
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb this work for additional information regarding copyright ownership.
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb The ASF licenses this file to You under the Apache License, Version 2.0
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb (the "License"); you may not use this file except in compliance with
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb the License. You may obtain a copy of the License at
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb Unless required by applicable law or agreed to in writing, software
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb distributed under the License is distributed on an "AS IS" BASIS,
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb See the License for the specific language governing permissions and
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb limitations under the License.
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb <p>This document covers stopping and restarting Apache HTTPD on
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb Unix-like systems. Windows NT, 2000 and XP users should see
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb <a href="platform/windows.html#winsvc">Running httpd as a
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb href="platform/windows.html#wincons">Running httpd as a
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb Console Application</a> for information on how to control
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb httpd on those platforms.</p>
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb <p>In order to stop or restart the Apache HTTP Server, you must send a signal to
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb the running <program>httpd</program> processes. There are two ways to
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb send the signals. First, you can use the unix <code>kill</code>
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb command to directly send signals to the processes. You will
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb notice many <program>httpd</program> executables running on your system,
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb but you should not send signals to any of them except the parent,
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb whose pid is in the <directive
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb module="mpm_common">PidFile</directive>. That is to say you
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb shouldn't ever need to send signals to any process except the
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb parent. There are four signals that you can send the parent:
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb will be described in a moment.</p>
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb <p>To send a signal to the parent you should issue a command
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb such as:</p>
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb<example>kill -TERM `cat /usr/local/apache2/logs/httpd.pid`</example>
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb <p>The second method of signaling the <program>httpd</program> processes
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb is to use the <code>-k</code> command line options: <code>stop</code>,
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb <code>restart</code>, <code>graceful</code> and <code>graceful-stop</code>,
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb as described below. These are arguments to the <program>
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb httpd</program> binary, but we recommend that
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb you send them using the <program>apachectl</program> control script, which
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb <p>After you have signaled <program>httpd</program>, you can read about
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb its progress by issuing:</p>
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb<example>tail -f /usr/local/apache2/logs/error_log</example>
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb <p>Sending the <code>TERM</code> or <code>stop</code> signal to
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb the parent causes it to immediately attempt to kill off all of its
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb children. It may take it several seconds to complete killing off
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb its children. Then the parent itself exits. Any requests in
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb progress are terminated, and no further requests are served.</p>
d4abb06ac220bb280ae996b6d21bbd257db51bb1jerenkrantz <p>The <code>USR1</code> or <code>graceful</code> signal causes
d4abb06ac220bb280ae996b6d21bbd257db51bb1jerenkrantz the parent process to <em>advise</em> the children to exit after
d4abb06ac220bb280ae996b6d21bbd257db51bb1jerenkrantz their current request (or to exit immediately if they're not
d4abb06ac220bb280ae996b6d21bbd257db51bb1jerenkrantz serving anything). The parent re-reads its configuration files and
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb re-opens its log files. As each child dies off the parent replaces
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb configuration, which begins serving new requests immediately.</p>
a2a0abd88b19e042a3eb2a9fa1702c25ad51303dwrowe <p>This code is designed to always respect the process control
4f9c22c4f27571d54197be9674e1fc0d528192aestriker directive of the MPMs, so the number of processes and threads
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb available to serve clients will be maintained at the appropriate
4f9c22c4f27571d54197be9674e1fc0d528192aestriker values throughout the restart process. Furthermore, it respects
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb <directive module="mpm_common">StartServers</directive> in the
4f9c22c4f27571d54197be9674e1fc0d528192aestriker following manner: if after one second at least <directive
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb module="mpm_common">StartServers</directive> new children have not
4f9c22c4f27571d54197be9674e1fc0d528192aestriker been created, then create enough to pick up the slack. Hence the
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb code tries to maintain both the number of children appropriate for
4f9c22c4f27571d54197be9674e1fc0d528192aestriker the current load on the server, and respect your wishes with the
4f9c22c4f27571d54197be9674e1fc0d528192aestriker parameter.</p>
4f9c22c4f27571d54197be9674e1fc0d528192aestriker will notice that the server statistics are <strong>not</strong>
b38846b15c8891c6dec44dcc4f96ca40721bf663rbb set to zero when a <code>USR1</code> is sent. The code was
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe written to both minimize the time in which the server is unable
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe to serve new requests (they will be queued up by the operating
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe system, so they're not lost in any event) and to respect your
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe tuning parameters. In order to do this it has to keep the
2d399cd7535887fceaa9f8f116eb98ce68ddd602trawick <em>scoreboard</em> used to keep track of all children across
c2cf53a40a9814eb91db2cdf820f97d943f21628coar generations.</p>
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe <p>The status module will also use a <code>G</code> to indicate
731344ed8f3677d1661c261ca5fcdd2ee3dbc74ccoar those children which are still serving requests started before
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe the graceful restart was given.</p>
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe <p>At present there is no way for a log rotation script using
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe <code>USR1</code> to know for certain that all children writing
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe the pre-restart log have finished. We suggest that you use a
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe suitable delay after sending the <code>USR1</code> signal
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe before you do anything with the old log. For example if most of
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe your hits take less than 10 minutes to complete for users on
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe low bandwidth links then you could wait 15 minutes before doing
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe anything with the old log.</p>
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe <p>When you issue a restart, a syntax check is first run, to
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe ensure that there are no errors in the configuration files.
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe If your configuration file has errors in it, you will get an
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe error message about that syntax error, and the server will refuse to
8419e6f8bff1a3617933f3ba760d2bdec7442f44coar restart. This avoids the situation where the server halts and then
8419e6f8bff1a3617933f3ba760d2bdec7442f44coar cannot restart, leaving you with a non-functioning server.</p>
8419e6f8bff1a3617933f3ba760d2bdec7442f44coar <p>This still will not
8419e6f8bff1a3617933f3ba760d2bdec7442f44coar guarantee that the server will restart correctly. To check the
8419e6f8bff1a3617933f3ba760d2bdec7442f44coar semantics of the configuration files as well as the syntax, you
8419e6f8bff1a3617933f3ba760d2bdec7442f44coar can try starting <program>httpd</program> as a non-root user. If there
8419e6f8bff1a3617933f3ba760d2bdec7442f44coar are no errors it will attempt to open its sockets and logs and fail
d4abb06ac220bb280ae996b6d21bbd257db51bb1jerenkrantz because it's not root (or because the currently running
2a6e98ba4ffa30ded5d8831664c5cb2a170a56b6coar <program>httpd</program> already has those ports bound). If it fails
8419e6f8bff1a3617933f3ba760d2bdec7442f44coar for any other reason then it's probably a config file error and the error
8419e6f8bff1a3617933f3ba760d2bdec7442f44coar should be fixed before issuing the graceful restart.</p></note>
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe <p>Sending the <code>HUP</code> or <code>restart</code> signal to
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe the parent causes it to kill off its children like in
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe <code>TERM</code>, but the parent doesn't exit. It re-reads its
4f9c22c4f27571d54197be9674e1fc0d528192aestriker configuration files, and re-opens any log files. Then it spawns a
4f9c22c4f27571d54197be9674e1fc0d528192aestriker new set of children and continues serving hits.</p>
731344ed8f3677d1661c261ca5fcdd2ee3dbc74ccoar will notice that the server statistics are set to zero when a
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe<note>As with a graceful restart, a syntax check is run before the
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowerestart is attempted. If your configuration file has errors in it, the
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowerestart will not be attempted, and you will receive notification of the
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowesyntax error(s).</note>
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe<section id="gracefulstop"><title>Graceful Stop</title>
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe <p>The <code>WINCH</code> or <code>graceful-stop</code> signal causes
4775dfc34c90fada8c7c4d6a57ed8a3114d55c2dtrawick the parent process to <em>advise</em> the children to exit after
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe their current request (or to exit immediately if they're not
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe serving anything). The parent will then remove its <directive
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe module="mpm_common">PidFile</directive> and cease listening on
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe all ports. The parent will continue to run, and monitor children
731344ed8f3677d1661c261ca5fcdd2ee3dbc74ccoar which are handling requests. Once all children have finalised
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe and exited or the timeout specified by the <directive
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe module="mpm_common">GracefulShutdownTimeout</directive> has been
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe reached, the parent will also exit. If the timeout is reached,
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe any remaining children will be sent the <code>TERM</code> signal
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe to force them to exit.</p>
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe <p>A <code>TERM</code> signal will immediately terminate the
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe parent process and all children when in the "graceful" state. However
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe as the <directive module="mpm_common">PidFile</directive> will
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe have been removed, you will not be able to use
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe <code>apachectl</code> or <code>httpd</code> to send this signal.</p>
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe <note><p>The <code>graceful-stop</code> signal allows you to run multiple
83a8dc5a596a8a1b9d14f063268287d123b9ed7ewrowe identically configured instances of <program>httpd</program> at the
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe same time. This is a powerful feature when performing graceful
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe upgrades of httpd, however it can also cause deadlocks and race
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe conditions with some configurations.</p>
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe <p>Care has been taken to ensure that on-disk files such as lock files
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe (<directive module="core">Mutex</directive>) and Unix socket files
4f9c22c4f27571d54197be9674e1fc0d528192aestriker (<directive module="mod_cgid">ScriptSock</directive>) contain the server
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe PID, and should coexist without problem. However, if a configuration
4f9c22c4f27571d54197be9674e1fc0d528192aestriker directive, third-party module or persistent CGI utilises any other on-disk
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe lock or state files, care should be taken to ensure that multiple running
4f9c22c4f27571d54197be9674e1fc0d528192aestriker instances of <program>httpd</program> do not clobber each others files.</p>
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe <p>You should also be wary of other potential race conditions, such as
731344ed8f3677d1661c261ca5fcdd2ee3dbc74ccoar using <program>rotatelogs</program> style piped logging. Multiple running
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe instances of <program>rotatelogs</program> attempting to rotate the same
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe logfiles at the same time may destroy each other's logfiles.</p></note>
fa06de8a28a737e8fbaad76d7f3ff67aaa5e4a09wrowe</manualpage>