| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <HTML> |
| <HEAD> |
| <TITLE>Stopping and Restarting Apache</TITLE> |
| </HEAD> |
| |
| <!-- Background white, links blue (unvisited), navy (visited), red (active) --> |
| <BODY |
| BGCOLOR="#FFFFFF" |
| TEXT="#000000" |
| LINK="#0000FF" |
| VLINK="#000080" |
| ALINK="#FF0000" |
| > |
| <!--#include virtual="header.html" --> |
| <H1 ALIGN="CENTER">Stopping and Restarting Apache</H1> |
| |
| <P>You will notice many <CODE>httpd</CODE> executables running on your system, |
| but you should not send signals to any of them except the parent, whose |
| pid is in the <A HREF="mod/core.html#pidfile">PidFile</A>. 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: |
| <CODE>TERM</CODE>, <CODE>HUP</CODE>, and <CODE>USR1</CODE>, which will |
| be described in a moment. |
| |
| <P>To send a signal to the parent you should issue a command such as: |
| <BLOCKQUOTE><PRE> |
| kill -TERM `cat /usr/local/apache/logs/httpd.pid` |
| </PRE></BLOCKQUOTE> |
| |
| You can read about its progress by issuing: |
| |
| <BLOCKQUOTE><PRE> |
| tail -f /usr/local/apache/logs/error_log |
| </PRE></BLOCKQUOTE> |
| |
| Modify those examples to match your |
| <A HREF="mod/core.html#serverroot">ServerRoot</A> and |
| <A HREF="mod/core.html#pidfile">PidFile</A> settings. |
| |
| <P>As of Apache 1.3 we provide a script <CODE>src/support/apachectl</CODE> |
| which can be used to start, stop, and restart Apache. It may need a |
| little customization for your system, see the comments at the top of |
| the script. |
| |
| <H3>TERM Signal: stop now</H3> |
| |
| <P>Sending the <CODE>TERM</CODE> 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. |
| |
| <H3>HUP Signal: restart now</H3> |
| |
| <P>Sending the <CODE>HUP</CODE> signal to the parent causes it to kill off |
| its children like in <CODE>TERM</CODE> 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. |
| |
| <P>Users of the |
| <A HREF="mod/mod_status.html">status module</A> |
| will notice that the server statistics are |
| set to zero when a <CODE>HUP</CODE> is sent. |
| |
| <P><STRONG>Note:</STRONG> 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 below for a method of avoiding this. |
| |
| <H3>USR1 Signal: graceful restart</H3> |
| |
| <P><STRONG>Note:</STRONG> prior to release 1.2b9 this code is quite unstable |
| and shouldn't be used at all. |
| |
| <P>The <CODE>USR1</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 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 <EM>generation</EM> of the |
| configuration, which begins serving new requests immediately. |
| |
| <P>This code is designed to always respect the |
| <A HREF="mod/core.html#maxclients">MaxClients</A>, |
| <A HREF="mod/core.html#minspareservers">MinSpareServers</A>, |
| and <A HREF="mod/core.html#maxspareservers">MaxSpareServers</A> settings. |
| Furthermore, it respects <A HREF="mod/core.html#startservers">StartServers</A> |
| 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. |
| This is to say that 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. |
| |
| <P>Users of the |
| <A HREF="mod/mod_status.html">status module</A> |
| will notice that the server statistics |
| are <STRONG>not</STRONG> set to zero when a <CODE>USR1</CODE> 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 <EM>scoreboard</EM> used to keep track |
| of all children across generations. |
| |
| <P>The status module will also use a <CODE>G</CODE> to indicate those |
| children which are still serving requests started before the graceful |
| restart was given. |
| |
| <P>At present there is no way for a log rotation script using |
| <CODE>USR1</CODE> 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 <CODE>USR1</CODE> 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. |
| |
| <P><STRONG>Note:</STRONG> 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. At present the only work |
| around is to check the syntax of your files before doing a restart. The |
| easiest way is to just run 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. |
| |
| <H3>Appendix: signals and race conditions</H3> |
| |
| <P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM> |
| involving the restart and die signals (a simple description of race |
| condition is: a time-sensitive problem, as in if something happens at just |
| the wrong time it won't behave as expected). For those architectures that |
| have the "right" feature set we have eliminated as many as we can. |
| But it should be noted that there still do exist race conditions on |
| certain architectures. |
| |
| <P>Architectures that use an on disk |
| <A HREF="mod/core.html#scoreboardfile">ScoreBoardFile</A> |
| have the potential to corrupt their scoreboards. This can result in |
| the "bind: Address already in use" (after <CODE>HUP</CODE>) or |
| "long lost child came home!" (after <CODE>USR1</CODE>). The former is |
| a fatal error, while the latter just causes the server to lose a scoreboard |
| slot. So it might 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 a method to determine if your |
| architecture uses it. |
| |
| <P><CODE>NEXT</CODE> and <CODE>MACHTEN</CODE> (68k only) have small race |
| conditions |
| which can cause a restart/die signal to be lost, but should not cause the |
| server to do anything otherwise problematic. |
| <!-- they don't have sigaction, or we're not using it -djg --> |
| |
| <P>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. |
| |
| <!--#include virtual="footer.html" --> |
| </BODY> |
| </HTML> |