svn commit: r263857 - /httpd/httpd/trunk/docs/manual/stopping.xml

[co...@apache.org]

Author: colm
Date: Sun Aug 28 03:48:09 2005
New Revision: 263857

URL: http://svn.apache.org/viewcvs?rev=263857&view=rev
Log:

Add a note on the possible pit-falls that lie ahead when running multiple
instances of httpd at the same time.


Modified:
    httpd/httpd/trunk/docs/manual/stopping.xml

Modified: httpd/httpd/trunk/docs/manual/stopping.xml
URL: http://svn.apache.org/viewcvs/httpd/httpd/trunk/docs/manual/stopping.xml?rev=263857&r1=263856&r2=263857&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/stopping.xml (original)
+++ httpd/httpd/trunk/docs/manual/stopping.xml Sun Aug 28 03:48:09 2005
@@ -203,6 +203,25 @@
     as the <directive module="mpm_common">PidFile</directive> will
     have been removed, you will not be able to use 
     <code>apachectl</code> or <code>httpd</code> to send this signal,</p>
+
+    <note><p>The <code>graceful-stop</code> signal allows you to run multiple
+    identically configured instances of <program>httpd</program> at the 
+    same time. This is a powerful feature when performing graceful 
+    upgrades of Apache, however it can also cause deadlocks and race 
+    conditions with some configurations.</p> 
+
+    <p>Care has been taken to ensure that on-disk files
+    such as the <directive module="core">Lockfile</directive> and <directive 
+    module="mod_cgid">ScriptSock</directive> files contain the server
+    PID, and should co-exist without problem. However, if a configuration
+    directive, third-party module or persistent CGI utilises any other on-disk 
+    lock or  state files; care should be taken to ensure that multiple running 
+    instances of <program>httpd</program> do not clobber each others files.</p> 
+
+    <p>You should also be wary of other potential race conditions, such as
+    using <program>rotatelogs</program> style piped logging. Multiple running
+    instances of <program>rotatelogs</program> attempting to rotate the same
+    logfiles at the same time may destroy each other's logfiles.</p></note>
 </section>