Stopping and Restarting

Available Languages: de | + en | + es | + ja | + ko | + ru | + tr

+ +

This document covers stopping and restarting Apache on + Unix-like systems. Windows NT, 2000 and XP users should see + Running Apache as a + Service and Windows 9x and ME users should see Running Apache as a + Console Application for information on how to control + Apache on those platforms.

Introduction
Stop Now
Graceful Restart
Restart Now
Appendix: signals and race conditions

Introduction

+ +

In order to stop or restart Apache, you must send a signal to + the running httpd processes. There are two ways to + send the signals. First, you can use the unix kill + command to directly send signals to the processes. You will + notice many httpd executables running on your system, + but you should not send signals to any of them except the parent, + whose pid is in the PidFile. That is to say you + shouldn't ever need to send signals to any process except the + parent. There are three signals that you can send the parent: + TERM, + HUP, and + USR1, which + will be described in a moment.

+ +

To send a signal to the parent you should issue a command + such as:

+ +

kill -TERM `cat /usr/local/apache2/logs/httpd.pid`

+ +

The second method of signaling the httpd processes + is to use the -k command line options: stop, + restart, and graceful, + as described below. These are arguments to the httpd binary, but we recommend that + you send them using the apachectl control script, which + will pass them through to httpd.

+ +

After you have signaled httpd, you can read about + its progress by issuing:

+ +

tail -f /usr/local/apache2/logs/error_log

+ +

Modify those examples to match your ServerRoot and PidFile settings.

Stop Now

+ +

Signal: TERM: apachectl -k stop

+ +

Sending the TERM or stop signal to + the parent causes it to immediately attempt to kill off all of its + children. It may take it several seconds to complete killing off + its children. Then the parent itself exits. Any requests in + progress are terminated, and no further requests are served.

Graceful Restart

+ +

Signal: USR1: apachectl -k graceful

+ +

The USR1 or graceful signal causes + the parent process to advise the children to exit after + their current request (or to exit immediately if they're not + serving anything). The parent re-reads its configuration files and + re-opens its log files. As each child dies off the parent replaces + it with a child from the new generation of the + configuration, which begins serving new requests immediately.

+ +

On certain platforms that do not allow USR1 to + be used for a graceful restart, an alternative signal may be used (such + as WINCH). The command apachectl graceful + will send the right signal for your platform.

+ +

This code is designed to always respect the process control + directive of the MPMs, so the number of processes and threads + available to serve clients will be maintained at the appropriate + values throughout the restart process. Furthermore, it respects + StartServers in the + following manner: if after one second at least StartServers new children have not + been created, then create enough to pick up the slack. Hence the + code tries to maintain both the number of children appropriate for + the current load on the server, and respect your wishes with the + StartServers + parameter.

+ +

Users of mod_status + will notice that the server statistics are not + set to zero when a USR1 is sent. The code was + written to both minimize the time in which the server is unable + to serve new requests (they will be queued up by the operating + system, so they're not lost in any event) and to respect your + tuning parameters. In order to do this it has to keep the + scoreboard used to keep track of all children across + generations.

+ +

The status module will also use a G to indicate + those children which are still serving requests started before + the graceful restart was given.

+ +

At present there is no way for a log rotation script using + USR1 to know for certain that all children writing + the pre-restart log have finished. We suggest that you use a + suitable delay after sending the USR1 signal + before you do anything with the old log. For example if most of + your hits take less than 10 minutes to complete for users on + low bandwidth links then you could wait 15 minutes before doing + anything with the old log.

+ +

If your configuration file has errors + in it when you issue a restart then your parent will not + restart, it will exit with an error. In the case of graceful + restarts it will also leave children running when it exits. + (These are the children which are "gracefully exiting" by + handling their last request.) This will cause problems if you + attempt to restart the server -- it will not be able to bind to + its listening ports. Before doing a restart, you can check the + syntax of the configuration files with the -t + command line argument (see httpd). This still will not + guarantee that the server will restart correctly. To check the + semantics of the configuration files as well as the syntax, you + can try starting httpd as a non-root user. If there + are no errors it will attempt to open its sockets and logs and fail + because it's not root (or because the currently running + httpd already has those ports bound). If it fails + for any other reason then it's probably a config file error and the error + should be fixed before issuing the graceful restart.

Restart Now

+ +

Signal: HUP: apachectl -k restart

+ +

Sending the HUP or restart signal to + the parent causes it to kill off its children like in + TERM, but the parent doesn't exit. It re-reads its + configuration files, and re-opens any log files. Then it spawns a + new set of children and continues serving hits.

+ +

Users of mod_status + will notice that the server statistics are set to zero when a + HUP is sent.

+ +

If your configuration file has errors in it when you issue a +restart then your parent will not restart, it will exit with an +error. See above for a method of avoiding this.

Appendix: signals and race conditions

+ +

Prior to Apache 1.2b9 there were several race + conditions involving the restart and die signals (a simply put, + a race condition is a time-sensitive problem - if something happens + at just the wrong time or things happen in the wrong order, + undesired behaviour will result. If the same thing happens at the right + time, all will be well). For those architectures that have the "right" + feature set we have eliminated as many as we can. But it should + be noted that race conditions do still exist on certain + architectures.

+ +

Architectures that use an on-disk ScoreBoardFile can potentially have + their scoreboards corrupted. This can result in the "bind: + Address already in use" (after HUP) or "long lost + child came home!" (after USR1). The former is a fatal + error, while the latter just causes the server to lose a + scoreboard slot. So it may be advisable to use graceful + restarts, with an occasional hard restart. These problems are very + difficult to work around, but fortunately most architectures do + not require a scoreboard file. See the ScoreBoardFile documentation for + architecture which uses it.

+ +

All architectures have a small race condition in each child + involving the second and subsequent requests on a persistent + HTTP connection (KeepAlive). It may exit after reading the + request line but before reading any of the request headers. + There is a fix that was discovered too late to make 1.2. In + theory this isn't an issue because the KeepAlive client has to + expect these events because of network latencies and server + timeouts. In practice it doesn't seem to affect anything either + -- in a test case the server was restarted twenty times per + second and clients successfully browsed the site without + getting broken images or empty documents.