Clarify local-address documentation

The 'local-address' setting accepts both IPv4 and IPv6 addresses,
and also accepts port numbers. This patch documents all of those
behaviors.

Signed-off-by: Kevin P. Fleming <kevin@km6g.us>

diff --git a/docs/settings.rst b/docs/settings.rst
index 8de9398fbc311e22e5a5bab4630c67eb732a7b9c..b36aa714e6da5afd2178f81dcfb002fd98c23501 100644 (file)
--- a/docs/settings.rst
+++ b/docs/settings.rst
@@ -770,12 +770,12 @@ available in non-static distributions.
 ``local-address``
 -----------------
 .. versionchanged:: 4.3.0
-  now also takes your IPv6 addresses
+  now also accepts IPv6 addresses
 
 .. versionchanged:: 4.3.0
-  Before 4.3.0, this setting only supported IPv4.
+  Before 4.3.0, this setting only supported IPv4 addresses.
 
--  IPv4 Addresses, separated by commas or whitespace
+-  IPv4/IPv6 Addresses, with optional port numbers, separated by commas or whitespace
 -  Default: ``0.0.0.0, ::``
 
 Local IP addresses to which we bind. It is highly advised to bind to
@@ -784,6 +784,18 @@ big problems if you have multiple IP addresses. Unix does not provide a
 way of figuring out what IP address a packet was sent to when binding to
 any.
 
+Each address specified can include a port number; if no port is included
+then the :ref:`setting-local-port` port will be used for that address. If a
+port number is specified, it must be separated from the address with a ':';
+for an IPv6 address the address must be enclosed in square brackets.
+
+Examples:
+
+``local-address=127.0.0.1 ::1``
+``local-address=0.0.0.0:5353``
+``local-address=[::]:8053``
+``local-address=127.0.0.1:53, [::1]:5353``
+
 .. _setting-local-address-nonexist-fail:
 
 ``local-address-nonexist-fail``
@@ -834,7 +846,8 @@ addresses do not exist on this server.
 -  Integer
 -  Default: 53
 
-The port on which we listen. Only one port possible.
+Local port to bind to.
+If an address in :ref:`setting-local-address` does not have an explicit port, this port is used.
 
 .. _setting-log-dns-details:
 

diff --git a/pdns/recursordist/docs/manpages/pdns_recursor.1.rst b/pdns/recursordist/docs/manpages/pdns_recursor.1.rst
index 689d09cc8e5ee4d2530f8b40407f0c7fc39c6014..8baf8d349dc0785758d9b7f631f7bd0b3426a8f2 100644 (file)
--- a/pdns/recursordist/docs/manpages/pdns_recursor.1.rst
+++ b/pdns/recursordist/docs/manpages/pdns_recursor.1.rst
@@ -76,6 +76,8 @@ at `<https://doc.powerdns.com/>`
     Load root hints from this *filename*
 --local-address=<address>
     Listen on *address*, separated by spaces or commas.
+    Addresses specified can include port numbers; any which do not
+    incude port numbers will listen on *--local-port*.
 --local-port=<port>
     Listen on *port*.
 --log-common-errors

diff --git a/pdns/recursordist/docs/settings.rst b/pdns/recursordist/docs/settings.rst
index eacaacd142bf41ce34eb61b4ed906d1415b94049..f97f914ab7325a31af445389dbaad72562bb6440 100644 (file)
--- a/pdns/recursordist/docs/settings.rst
+++ b/pdns/recursordist/docs/settings.rst
@@ -715,14 +715,26 @@ Indication of how many queries will be averaged to get the average latency repor
 
 ``local-address``
 -----------------
--  IP addresses, comma separated
--  Default: 127.0.0.1
-
-Local IPv4 or IPv6 addresses to bind to.
-Addresses can also contain port numbers, for IPv4 specify like this: ``192.0.2.4:5300``, for IPv6: ``[::1]:5300``.
-
-**Warning**: When binding to wildcard addresses, UNIX semantics mean that answers may not be sent from the address a query was received on.
-It is highly recommended to bind to explicit addresses.
+-  IPv4/IPv6 Addresses, with optional port numbers, separated by commas or whitespace
+-  Default: ``0.0.0.0, ::``
+
+Local IP addresses to which we bind. It is highly advised to bind to
+specific interfaces and not use the default 'bind to any'. This causes
+big problems if you have multiple IP addresses. Unix does not provide a
+way of figuring out what IP address a packet was sent to when binding to
+any.
+
+Each address specified can include a port number; if no port is included
+then the :ref:`setting-local-port` port will be used for that address. If a
+port number is specified, it must be separated from the address with a ':';
+for an IPv6 address the address must be enclosed in square brackets.
+
+Examples:
+
+``local-address=127.0.0.1 ::1``
+``local-address=0.0.0.0:5353``
+``local-address=[::]:8053``
+``local-address=127.0.0.1:53, [::1]:5353``
 
 .. _setting-local-port: