From 98ab6806467fd70a2d909f34f4c294302c1820fa Mon Sep 17 00:00:00 2001
From: Joe Orton <jorton@apache.org>
Date: Thu, 23 Nov 2017 08:57:18 +0000
Subject: [PATCH] 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
---
 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 33bfd2d1a9..0bd2455552 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