Document special cases where changing Listen across a restart will

fail.

PR: 61666

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

diff --git a/docs/manual/bind.xml b/docs/manual/bind.xml
index 33bfd2d1a972a1bfc4a5efff705de15b79265272..0bd24555522c17661568189e94eb32777534882c 100644 (file)
--- a/docs/manual/bind.xml
+++ b/docs/manual/bind.xml
@@ -113,7 +113,41 @@ Listen 192.0.2.5:8000
 
   </section>
 
-  <section id="ipv6">
+  <section id="reload">
+    <title>Changing Listen configuration on restart</title>
+
+    <p>When httpd is restarted, special consideration must be made for
+    changes to <directive module="mpm_common">Listen</directive> directives.  During a restart, httpd keeps ports
+    bound (as in the original configuration) to avoid generating
+    "Connection refused" errors for any new attempts to connect to the
+    server. If changes are made to the set of <directive module="mpm_common">Listen</directive> directives used
+    which conflict with the old configuration, configuration will fail
+    and the server will terminate.</p>
+
+    <p>For example, changing from configuration:</p>
+    
+    <example>
+    <highlight language="config">
+      Listen 127.0.0.1:80
+    </highlight>
+    </example>
+
+    <p>to the following may fail, because binding to port 80 across
+    all addresses conflicts with binding to port 80 on just
+    127.0.0.1.</p>
+    
+    <example>
+    <highlight language="config">
+      Listen 80
+    </highlight>
+    </example>
+
+    <p>To have such configuration changes take effect, it is necessary
+    to stop and then start the server.</p>
+    
+  </section>
+
+    <section id="ipv6">
     <title>Special IPv6 Considerations</title>
 
     <p>A growing number of platforms implement IPv6, and