Improve the listen-address documentation

Explicitly mention that hostnames can be used instead of
IP addresses, that only the first address returned will
be used and what happens if the address is invalid.

Requested by Cálestyo in #3302213.

diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml
index ce36f36..b05dc3a 100644 (file)
--- a/doc/source/p-config.sgml
+++ b/doc/source/p-config.sgml
@@ -3,7 +3,7 @@
 
  Purpose     :  Used with other docs and files only.
 
- $Id: p-config.sgml,v 2.69 2011/03/27 14:14:13 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.70 2011/04/19 13:14:10 fabiankeil Exp $
 
  Copyright (C) 2001-2010 Privoxy Developers http://www.privoxy.org/
  See LICENSE.
@@ -97,7 +97,7 @@
  Sample Configuration File for Privoxy v&p-version;
 </title>
 <para>
- $Id: p-config.sgml,v 2.69 2011/03/27 14:14:13 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.70 2011/04/19 13:14:10 fabiankeil Exp $
 </para>
 <para>
 Copyright (C) 2001-2010 Privoxy Developers http://www.privoxy.org/
@@ -1194,7 +1194,7 @@ actionsfile
   <term>Specifies:</term>
   <listitem>
    <para>
-    The IP address and TCP port on which <application>Privoxy</application> will
+    The address and TCP port on which <application>Privoxy</application> will
     listen for client requests.
    </para>
   </listitem>
@@ -1203,6 +1203,7 @@ actionsfile
   <term>Type of value:</term>
   <listitem>
    <para>[<replaceable class="parameter">IP-Address</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
+   <para>[<replaceable class="parameter">Hostname</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
   </listitem>
  </varlistentry>
 
@@ -1233,15 +1234,39 @@ actionsfile
     serve requests from other machines (e.g. on your local network) as well, you
     will need to override the default.
    </para>
+   <para>
+    If a hostname is used instead of an IP address, <application>Privoxy</application>
+    will try to resolve it to an IP address and if there are multiple, use the first
+    one returned.
+   </para>
+   <para>
+    If the address for the hostname isn't already known on the system
+    (for example because it's in /etc/hostname), this may result in DNS
+    traffic.
+   </para>
+   <para>
+    If the specified address isn't available on the system, or if the
+    hostname can't be resolved, <application>Privoxy</application>
+    will fail to start.
+   </para>
    <para>
     IPv6 addresses containing colons have to be quoted by brackets.
+    They can only be used if <application>Privoxy</application> has
+    been compiled with IPv6 support. If you aren't sure if your version
+    supports it, have a look at
+    <literal>http://config.privoxy.org/show-status</literal>.
+   </para>
+   <para>
+    If you leave out the address, <application>Privoxy</application> will bind to all
+    IPv4 interfaces (addresses) on your machine and may become reachable from the
+    Internet and/or the local network. Be aware that some GNU/Linux distributions
+    modify that behaviour without updating the documentation. Check for non-standard
+    patches if your <application>Privoxy</application>version behaves differently.
    </para>
    <para>
-    If you leave out the IP address, <application>Privoxy</application> will
-    bind to all IPv4 interfaces (addresses) on your machine and may become reachable
-    from the Internet. In that case, consider using <link
-    linkend="acls">access control lists</link> (ACL's, see below), and/or
-    a firewall.
+    If you configure <application>Privoxy</application>to be reachable from the
+    network, consider using <link linkend="acls">access control lists</link>
+    (ACL's, see below), and/or a firewall.
    </para>
    <para>
     If you open <application>Privoxy</application> to untrusted users, you will
@@ -1249,6 +1274,12 @@ actionsfile
     linkend="enable-edit-actions">enable-edit-actions</link></literal> and
     <literal><link linkend="enable-remote-toggle">enable-remote-toggle</link></literal>
    </para>
+   <para>
+    With the exception noted above, listening on multiple addresses is currently
+    not supported by <application>Privoxy</application> directly.
+    It can be done on most operating systems by letting a packet filter
+    redirect request for certain addresses to Privoxy, though.
+   </para>
   </listitem>
  </varlistentry>
  <varlistentry>