From 329ccfb69ab19e6496481234d9a8e84c4cece7b8 Mon Sep 17 00:00:00 2001
From: Joe Orton <jorton@apache.org>
Date: Fri, 23 Mar 2018 08:35:49 +0000
Subject: [PATCH] Merge r1816110 from trunk:

Document special cases where changing Listen across a restart will
fail.

PR: 61666



git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1827552 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/bind.xml | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/docs/manual/bind.xml b/docs/manual/bind.xml
index 888ef9387e..c9e5bdc325 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
-- 
2.40.0