Improve the listen-address documentation

[privoxy.git] / doc / source / p-config.sgml

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>