Commit 1868e2bb authored by Joshua Slive's avatar Joshua Slive
Browse files

A few small changes to bring this up to 2.0. 

This doc could use a major rewrite.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@87487 13f79535-47bb-0310-9956-ffa450edef68
parent f4ac1706

docs/manual/stopping.html

+68 −60
Original line number Diff line number Diff line 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<HTML>

<HEAD>

<TITLE>Stopping and Restarting Apache</TITLE>

<TITLE>Stopping and Restarting the Server</TITLE>

</HEAD>



<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
@@ -13,11 +13,12 @@ 
 ALINK="#FF0000"

>

<!--#include virtual="header.html" -->

<H1 ALIGN="CENTER">Stopping and Restarting Apache</H1>

<H1 ALIGN="CENTER">Stopping and Restarting the Server</H1>



<P>This document covers stopping and restarting Apache on Unix

only. Windows users should see <A HREF="platform/windows.html#signal">Signalling

Apache when running</A>.</P>

<P>This document covers stopping and restarting Apache on Unix-like

systems. Windows users should see <A

HREF="platform/windows.html#signal">Signalling Apache when

running</A>.</P>



<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
@@ -42,12 +43,15 @@ 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.

<p>A shell script called <code>apachectl</code> is provided

which automates the processing of signalling Apache.

For details about this script, see the documentation

on <a href="invoking.html">starting Apache</a>.</p>



<H3>TERM Signal: stop now</H3>

<H3>Stop Now</h3>



<p><strong>Signal:</strong> TERM<br>

<code>apachectl stop</code></p>



<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
@@ -55,46 +59,29 @@ 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>

<H3>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><strong>Signal:</strong> WINCH<br>

<code>apachectl graceful</code></p>



<P>The <CODE>USR1</CODE> signal causes the parent process to <EM>advise</EM>

<P>The <CODE>WINCH</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.

configuration, which begins serving new requests immediately.</p>



<P>This code is designed to always respect the <A

HREF="mod/mpm_common.html#maxclients">MaxClients</A>, <A

HREF="mod/prefork.html#minspareservers">MinSpareServers</A>, and <A

HREF="mod/prefork.html#maxspareservers">MaxSpareServers</A>

settings.  Furthermore, it respects <A

HREF="mod/mpm_common.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>



<P>Users of the

<A HREF="mod/mod_status.html">status module</A>
@@ -112,33 +99,54 @@ 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

<CODE>WINCH</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

after sending the <CODE>WINCH</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.  Before doing a restart, you

can check the syntax of the configuration files with the <CODE>-t</CODE>

<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.  Before doing a restart, you can

check the syntax of the configuration files with the <CODE>-t</CODE>

command line argument (see <A HREF="invoking.html">Starting

Apache</A>). 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

Apache</A>). 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.





<H3>Restart Now</H3>



<p><strong>Signal:</strong> HUP<br>

<code>apachectl restart</code></p>



<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>Appendix: signals and race conditions</H3>



<P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM>

docs/manual/stopping.html.en

+68 −60
Original line number Diff line number Diff line 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<HTML>

<HEAD>

<TITLE>Stopping and Restarting Apache</TITLE>

<TITLE>Stopping and Restarting the Server</TITLE>

</HEAD>



<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
@@ -13,11 +13,12 @@ 
 ALINK="#FF0000"

>

<!--#include virtual="header.html" -->

<H1 ALIGN="CENTER">Stopping and Restarting Apache</H1>

<H1 ALIGN="CENTER">Stopping and Restarting the Server</H1>



<P>This document covers stopping and restarting Apache on Unix

only. Windows users should see <A HREF="platform/windows.html#signal">Signalling

Apache when running</A>.</P>

<P>This document covers stopping and restarting Apache on Unix-like

systems. Windows users should see <A

HREF="platform/windows.html#signal">Signalling Apache when

running</A>.</P>



<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
@@ -42,12 +43,15 @@ 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.

<p>A shell script called <code>apachectl</code> is provided

which automates the processing of signalling Apache.

For details about this script, see the documentation

on <a href="invoking.html">starting Apache</a>.</p>



<H3>TERM Signal: stop now</H3>

<H3>Stop Now</h3>



<p><strong>Signal:</strong> TERM<br>

<code>apachectl stop</code></p>



<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
@@ -55,46 +59,29 @@ 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>

<H3>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><strong>Signal:</strong> WINCH<br>

<code>apachectl graceful</code></p>



<P>The <CODE>USR1</CODE> signal causes the parent process to <EM>advise</EM>

<P>The <CODE>WINCH</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.

configuration, which begins serving new requests immediately.</p>



<P>This code is designed to always respect the <A

HREF="mod/mpm_common.html#maxclients">MaxClients</A>, <A

HREF="mod/prefork.html#minspareservers">MinSpareServers</A>, and <A

HREF="mod/prefork.html#maxspareservers">MaxSpareServers</A>

settings.  Furthermore, it respects <A

HREF="mod/mpm_common.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>



<P>Users of the

<A HREF="mod/mod_status.html">status module</A>
@@ -112,33 +99,54 @@ 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

<CODE>WINCH</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

after sending the <CODE>WINCH</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.  Before doing a restart, you

can check the syntax of the configuration files with the <CODE>-t</CODE>

<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.  Before doing a restart, you can

check the syntax of the configuration files with the <CODE>-t</CODE>

command line argument (see <A HREF="invoking.html">Starting

Apache</A>). 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

Apache</A>). 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.





<H3>Restart Now</H3>



<p><strong>Signal:</strong> HUP<br>

<code>apachectl restart</code></p>



<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>Appendix: signals and race conditions</H3>



<P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM>