Document the problem of config file errors.

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

2 files changed, 36 insertions, 0 deletions

diff --git a/docs/manual/stopping.html b/docs/manual/stopping.html
index e333deb851..7e6e835a8a 100644
--- a/docs/manual/stopping.html
+++ b/docs/manual/stopping.html
@@ -52,6 +52,10 @@ serving hits.
 will notice that the server statistics are
 set to zero when a <code>HUP</code> is sent.
 
+<p><b>Note:</b> 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><b>Note:</b> prior to release 1.2b9 this code is quite unstable and
@@ -97,6 +101,20 @@ 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><b>Note:</b> 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 <i>race conditions</i>
diff --git a/docs/manual/stopping.html.en b/docs/manual/stopping.html.en
index e333deb851..7e6e835a8a 100644
--- a/docs/manual/stopping.html.en
+++ b/docs/manual/stopping.html.en
@@ -52,6 +52,10 @@ serving hits.
 will notice that the server statistics are
 set to zero when a <code>HUP</code> is sent.
 
+<p><b>Note:</b> 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><b>Note:</b> prior to release 1.2b9 this code is quite unstable and
@@ -97,6 +101,20 @@ 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><b>Note:</b> 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 <i>race conditions</i>