From: Joe Orton <jorton@apache.org>
Date: Thu, 23 Nov 2017 08:57:18 +0000 (+0000)
Subject: Document special cases where changing Listen across a restart will
X-Git-Tag: 2.5.0-alpha2-ci-test-only~3130
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=98ab6806467fd70a2d909f34f4c294302c1820fa;p=thirdparty%2Fapache%2Fhttpd.git

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 33bfd2d1a97..0bd24555522 100644
--- 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