Document trust-x-forwarded-for

diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml
index c758a77..a7405d9 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.121 2016/05/03 13:22:13 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.122 2016/05/22 12:41:50 fabiankeil Exp $
 
  Copyright (C) 2001-2016 Privoxy Developers https://www.privoxy.org/
  See LICENSE.
@@ -97,7 +97,7 @@
  Sample Configuration File for Privoxy &p-version;
 </title>
 <para>
- $Id: p-config.sgml,v 2.121 2016/05/03 13:22:13 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.122 2016/05/22 12:41:50 fabiankeil Exp $
 </para>
 <para>
 Copyright (C) 2001-2016 Privoxy Developers https://www.privoxy.org/
@@ -3506,11 +3506,85 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
 </variablelist>
 </sect3>
 
+<!--  ~  End section  ~  -->
+
+<sect3 renderas="sect4" id="trust-x-forwarded-for"><title>trust-x-forwarded-for</title>
+<variablelist>
+ <varlistentry>
+  <term>Specifies:</term>
+  <listitem>
+   <para>
+    Whether or not Privoxy should use IP addresses specified with the X-Forwarded-For header
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Type of value:</term>
+  <listitem>
+   <para>
+    <replaceable>0 or one</replaceable>
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Default value:</term>
+  <listitem>
+   <para>0</para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <warning>
+   <para>
+    This is an experimental feature. The syntax is likely to change
+    in future versions.
+   </para>
+   </warning>
+   <para>
+    If clients reach Privoxy through another proxy, for example a load
+    balancer, Privoxy can't tell the client's IP address from the connection.
+    If multiple clients use the same proxy, they will share the same
+    client tag settings which is usually not desired.
+   </para>
+   <para>
+    This option lets Privoxy use the X-Forwarded-For header value as
+    client IP address. If the proxy sets the header, multiple clients
+    using the same proxy do not share the same client tag settings.
+   </para>
+   <para>
+    This option should only be enabled if Privoxy can only be reached
+    through a proxy and if the proxy can be trusted to set the header
+    correctly. It is recommended that ACL are used to make sure only
+    trusted systems can reach Privoxy.
+   </para>
+   <para>
+    If access to Privoxy isn't limited to trusted systems, this option
+    would allow malicious clients to change the client tags for other
+    clients or increase Privoxy's memory requirements by registering
+    lots of client tag settings for clients that don't exist.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Examples:</term>
+  <listitem>
+   <para>
+    <screen>
+      # Allow systems that can reach Privoxy to provide the client
+      # IP address with a X-Forwarded-For header.
+      trust-x-forwarded-for 1
+    </screen>
+   </para>
+  </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
 </sect2>
 
 <!--  ~  End section  ~  -->
 
-
 <!--   ~~~~~       New section      ~~~~~     -->
 
 <sect2 id="windows-gui">