Bump copyright

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

diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml
index e4416f7..e545a3a 100644 (file)
--- a/doc/source/p-config.sgml
+++ b/doc/source/p-config.sgml
@@ -3,9 +3,9 @@
 
  Purpose     :  Used with other docs and files only.
 
 
  Purpose     :  Used with other docs and files only.
 

- $Id: p-config.sgml,v 2.78 2011/08/18 11:42:50 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.105 2014/06/02 06:20:51 fabiankeil Exp $

 
 

- Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2014 Privoxy Developers http://www.privoxy.org/

  See LICENSE.
 
  ========================================================================
  See LICENSE.
 
  ========================================================================


@@ -94,13 +94,13 @@
 <sect1 id="config">
 <title>
  @@TITLE<!-- between the @@ is stripped by Makefile -->@@
 <sect1 id="config">
 <title>
  @@TITLE<!-- between the @@ is stripped by Makefile -->@@

- Sample Configuration File for Privoxy v&p-version;
+ Sample Configuration File for Privoxy &p-version;

 </title>
 <para>
 </title>
 <para>

- $Id: p-config.sgml,v 2.78 2011/08/18 11:42:50 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.105 2014/06/02 06:20:51 fabiankeil Exp $

 </para>
 <para>
 </para>
 <para>

-Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/
+Copyright (C) 2001-2014 Privoxy Developers http://www.privoxy.org/

 </para>
 
 <para>
 </para>
 
 <para>


@@ -117,7 +117,8 @@ Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/
       3. DEBUGGING                                              #
       4. ACCESS CONTROL AND SECURITY                            #
       5. FORWARDING                                             #
       3. DEBUGGING                                              #
       4. ACCESS CONTROL AND SECURITY                            #
       5. FORWARDING                                             #

-      6. WINDOWS GUI OPTIONS                                    #
+      6. MISCELLANEOUS                                          #
+      7. WINDOWS GUI OPTIONS                                    #

                                                                 #
 #################################################################
  </literallayout>
                                                                 #
 #################################################################
  </literallayout>


@@ -533,16 +534,6 @@ II. FORMAT OF THE CONFIGURATION FILE
    <para>
     No trailing <quote><literal>/</literal></quote>, please.
    </para>
    <para>
     No trailing <quote><literal>/</literal></quote>, please.
    </para>

-  <!--
-   This is really outdated and not likely to happen. HB 09/20/06
-   <para>
-    When development goes modular and multi-user, the blocker, filter, and
-    per-user config will be stored in subdirectories of <quote>confdir</quote>.
-    For now, the configuration directory structure is flat, except for
-    <filename>confdir/templates</filename>, where the HTML templates for CGI
-    output reside (e.g. <application>Privoxy's</application> 404 error page).
-   </para>
-  -->

   </listitem>
  </varlistentry>
 </variablelist>
   </listitem>
  </varlistentry>
 </variablelist>


@@ -597,6 +588,55 @@ II. FORMAT OF THE CONFIGURATION FILE
 </sect3>
 
 
 </sect3>
 
 

+<!--   ~~~~~       New section      ~~~~~     -->
+<sect3 renderas="sect4" id="temporary-directory"><title>temporary-directory</title>
+
+<variablelist>
+ <varlistentry>
+  <term>Specifies:</term>
+  <listitem>
+   <para>A directory where Privoxy can create temporary files.</para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Type of value:</term>
+  <listitem>
+   <para>Path name</para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Default value:</term>
+  <listitem>
+   <para>unset</para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Effect if unset:</term>
+  <listitem>
+   <para>No temporary files are created, external filters don't work.</para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    To execute <literal><ulink url="actions-file.html#EXTERNAL-FILTER">external filters</ulink></literal>,
+    <application>Privoxy</application> has to create temporary files.
+    This directive specifies the directory the temporary files should
+    be written to.
+   </para>
+   <para>
+    It should be a directory only <application>Privoxy</application>
+    (and trusted users) can access.
+   </para>
+  </listitem>
+ </varlistentry>
+</variablelist>
+
+<![%config-file;[<literallayout>@@#temporary-directory .</literallayout>]]>
+</sect3>
+
+

 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 renderas="sect4" id="logdir"><title>logdir</title>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 renderas="sect4" id="logdir"><title>logdir</title>
 


@@ -856,8 +896,7 @@ actionsfile
    <para>
     Your logfile will grow indefinitely, and you will probably want to
     periodically remove it.  On Unix systems, you can do this with a cron job
    <para>
     Your logfile will grow indefinitely, and you will probably want to
     periodically remove it.  On Unix systems, you can do this with a cron job

-    (see <quote>man cron</quote>). For Red Hat based Linux distributions, a
-    <command>logrotate</command> script has been included.
+    (see <quote>man cron</quote>).

    </para>
    <para>
     Any log files must be writable by whatever user <application>Privoxy</application>
    </para>
    <para>
     Any log files must be writable by whatever user <application>Privoxy</application>


@@ -1020,6 +1059,7 @@ actionsfile
   debug  4096 # Startup banner and warnings.
   debug  8192 # Non-fatal errors
   debug 32768 # log all data read from the network
   debug  4096 # Startup banner and warnings.
   debug  8192 # Non-fatal errors
   debug 32768 # log all data read from the network

+  debug 65536 # Log the applying actions

 </programlisting>
    </para>
    <para>
 </programlisting>
    </para>
    <para>


@@ -1083,13 +1123,13 @@ actionsfile
  <varlistentry>
   <term>Type of value:</term>
   <listitem>
  <varlistentry>
   <term>Type of value:</term>
   <listitem>

-   <para><emphasis>None</emphasis></para>
+   <para><emphasis>1 or 0</emphasis></para>

   </listitem>
  </varlistentry>
  <varlistentry>
   <term>Default value:</term>
   <listitem>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term>Default value:</term>
   <listitem>

-   <para><emphasis>Unset</emphasis></para>
+   <para><emphasis>0</emphasis></para>

   </listitem>
  </varlistentry>
  <varlistentry>
   </listitem>
  </varlistentry>
  <varlistentry>


@@ -1112,7 +1152,7 @@ actionsfile
  </varlistentry>
 </variablelist>
 
  </varlistentry>
 </variablelist>
 

-<![%config-file;[<literallayout>@@#single-threaded</literallayout>]]>
+<![%config-file;[<literallayout>@@#single-threaded 1</literallayout>]]>

 </sect3>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 </sect3>
 
 <!--   ~~~~~       New section      ~~~~~     -->


@@ -1278,10 +1318,10 @@ actionsfile
     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
     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.
+    patches if your <application>Privoxy</application> version behaves differently.

    </para>
    <para>
    </para>
    <para>

-    If you configure <application>Privoxy</application>to be reachable from the
+    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>
     network, consider using <link linkend="acls">access control lists</link>
     (ACL's, see below), and/or a firewall.
    </para>


@@ -1291,12 +1331,6 @@ actionsfile
     linkend="enable-edit-actions">enable-edit-actions</link></literal> and
     <literal><link linkend="enable-remote-toggle">enable-remote-toggle</link></literal>
    </para>
     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>
   </listitem>
  </varlistentry>
  <varlistentry>


@@ -1371,18 +1405,6 @@ actionsfile
     <quote>toggled off</quote> mode, i.e. mostly behave like a normal,
     content-neutral proxy with both ad blocking and content filtering
     disabled. See <literal>enable-remote-toggle</literal> below.
     <quote>toggled off</quote> mode, i.e. mostly behave like a normal,
     content-neutral proxy with both ad blocking and content filtering
     disabled. See <literal>enable-remote-toggle</literal> below.

-<!--
-    This is not really useful
-    anymore, since toggling is much easier via <ulink
-    url="http://config.privoxy.org/toggle">the web interface</ulink> than via
-    editing the <filename>conf</filename> file.
-
-    Remote toggling is now disabled by default. fk 2007-11-07)
--->
-   </para>
-   <para>
-    The windows version will only display the toggle icon in the system tray
-    if this option is present.

    </para>
   </listitem>
  </varlistentry>
    </para>
   </listitem>
  </varlistentry>


@@ -1888,6 +1910,67 @@ ACLs: permit-access and deny-access</title>
 <![%config-file;[<literallayout>@@buffer-limit 4096</literallayout>]]>
 </sect3>
 
 <![%config-file;[<literallayout>@@buffer-limit 4096</literallayout>]]>
 </sect3>
 

+<!--   ~~~~~       New section      ~~~~~     -->
+<sect3 renderas="sect4" id="enable-proxy-authentication-forwarding"><title>enable-proxy-authentication-forwarding</title>
+<variablelist>
+ <varlistentry>
+  <term>Specifies:</term>
+  <listitem>
+   <para>
+    Whether or not proxy authentication through &my-app; should work.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Type of value:</term>
+  <listitem>
+   <para>0 or 1</para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Default value:</term>
+  <listitem>
+   <para>0</para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Effect if unset:</term>
+  <listitem>
+   <para>
+    Proxy authentication headers are removed.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    Privoxy itself does not support proxy authentication, but can
+    allow clients to authenticate against Privoxy's parent proxy.
+   </para>
+   <para>
+    By default Privoxy (3.0.21 and later) don't do that and remove
+    Proxy-Authorization headers in requests and Proxy-Authenticate
+    headers in responses to make it harder for malicious sites to
+    trick inexperienced users into providing login information.
+   </para>
+   <para>
+    If this option is enabled the headers are forwarded.
+   </para>
+   <para>
+    Enabling this option is <emphasis>not recommended</emphasis> if there is
+    no parent proxy that requires authentication or if the local network between
+    Privoxy and the parent proxy isn't trustworthy. If proxy authentication is
+    only required for some requests, it is recommended to use a client header filter
+    to remove the authentication headers for requests where they aren't needed.
+   </para>
+  </listitem>
+ </varlistentry>
+</variablelist>
+
+<![%config-file;[<literallayout>@@enable-proxy-authentication-forwarding 0</literallayout>]]>
+</sect3>
+

 </sect2>
 
 <!--  ~  End section  ~  -->
 </sect2>
 
 <!--  ~  End section  ~  -->


@@ -2034,7 +2117,7 @@ ACLs: permit-access and deny-access</title>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 renderas="sect4" id="socks"><title>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 renderas="sect4" id="socks"><title>

-forward-socks4, forward-socks4a and forward-socks5</title>
+forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>

 <anchor id="forward-socks4">
 <anchor id="forward-socks4a">
 
 <anchor id="forward-socks4">
 <anchor id="forward-socks4a">
 


@@ -2097,6 +2180,12 @@ forward-socks4, forward-socks4a and forward-socks5</title>
    <para>
     With <literal>forward-socks5</literal> the DNS resolution will happen on the remote server as well.
    </para>
    <para>
     With <literal>forward-socks5</literal> the DNS resolution will happen on the remote server as well.
    </para>

+   <para>
+    <literal>forward-socks5t</literal> works like vanilla <literal>forward-socks5</literal> but
+    lets &my-app; additionally use Tor-specific SOCKS extensions. Currently the only supported
+    SOCKS extension is optimistic data which can reduce the latency for the first request made
+    on a newly created connection.
+   </para>

    <para>
     <replaceable class="parameter">socks_proxy</replaceable> and
     <replaceable class="parameter">http_parent</replaceable> can be a
    <para>
     <replaceable class="parameter">socks_proxy</replaceable> and
     <replaceable class="parameter">http_parent</replaceable> can be a


@@ -2145,7 +2234,7 @@ forward-socks4, forward-socks4a and forward-socks5</title>
    </para>
    <para>
     <screen>
    </para>
    <para>
     <screen>

-  forward-socks5   /               127.0.0.1:9050 .
+  forward-socks5t   /               127.0.0.1:9050 .

 </screen>
    </para>
 
 </screen>
    </para>
 


@@ -2386,6 +2475,9 @@ forward-socks4, forward-socks4a and forward-socks5</title>
     option and configure your packet filter to redirect outgoing
     HTTP connections into <application>Privoxy</application>.
    </para>
     option and configure your packet filter to redirect outgoing
     HTTP connections into <application>Privoxy</application>.
    </para>

+   <para>
+    Note that intercepting encrypted connections (HTTPS) isn't supported.
+   </para>

    <para>
     Make sure that <application>Privoxy's</application> own requests
     aren't redirected as well. Additionally take care that
    <para>
     Make sure that <application>Privoxy's</application> own requests
     aren't redirected as well. Additionally take care that


@@ -2600,7 +2692,7 @@ forward-socks4, forward-socks4a and forward-socks5</title>
     Several users have reported this as a Privoxy bug, so the
     default value has been reduced. Consider increasing it to
     300 seconds or even more if you think your browser can handle
     Several users have reported this as a Privoxy bug, so the
     default value has been reduced. Consider increasing it to
     300 seconds or even more if you think your browser can handle

-    it. If your browser appears to be hanging it can't.
+    it. If your browser appears to be hanging, it probably can't.

    </para>
   </listitem>
  </varlistentry>
    </para>
   </listitem>
  </varlistentry>


@@ -2617,6 +2709,75 @@ forward-socks4, forward-socks4a and forward-socks5</title>
 </sect3>
 
 
 </sect3>
 
 

+<sect3 renderas="sect4" id="tolerate-pipelining"><title>tolerate-pipelining</title>
+<variablelist>
+ <varlistentry>
+  <term>Specifies:</term>
+  <listitem>
+   <para>
+    Whether or not pipelined requests should be served.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Type of value:</term>
+  <listitem>
+   <para>
+    <replaceable>0 or 1.</replaceable>
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Default value:</term>
+  <listitem>
+   <para>None</para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Effect if unset:</term>
+  <listitem>
+   <para>
+    If Privoxy receives more than one request at once, it terminates the
+    client connection after serving the first one.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    &my-app; currently doesn't pipeline outgoing requests,
+    thus allowing pipelining on the client connection is not
+    guaranteed to improve the performance.
+   </para>
+   <para>
+    By default &my-app; tries to discourage clients from pipelining
+    by discarding aggressively pipelined requests, which forces the
+    client to resend them through a new connection.
+   </para>
+   <para>
+    This option lets &my-app; tolerate pipelining. Whether or not
+    that improves performance mainly depends on the client configuration.
+   </para>
+   <para>
+    If you are seeing problems with pages not properly loading,
+    disabling this option could work around the problem.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Examples:</term>
+  <listitem>
+   <para>
+    tolerate-pipelining 1
+   </para>
+  </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@tolerate-pipelining 1</literallayout>]]>
+</sect3>
+
+

 <sect3 renderas="sect4" id="default-server-timeout"><title>default-server-timeout</title>
 <variablelist>
  <varlistentry>
 <sect3 renderas="sect4" id="default-server-timeout"><title>default-server-timeout</title>
 <variablelist>
  <varlistentry>


@@ -2874,7 +3035,7 @@ forward-socks4, forward-socks4a and forward-socks5</title>
  <varlistentry>
   <term>Default value:</term>
   <listitem>
  <varlistentry>
   <term>Default value:</term>
   <listitem>

-   <para>None</para>
+   <para>128</para>

   </listitem>
  </varlistentry>
  <varlistentry>
   </listitem>
  </varlistentry>
  <varlistentry>


@@ -2919,6 +3080,13 @@ forward-socks4, forward-socks4a and forward-socks5</title>
     Obviously using this option only makes sense if you choose a limit
     below the one enforced by the operating system.
    </para>
     Obviously using this option only makes sense if you choose a limit
     below the one enforced by the operating system.
    </para>

+   <para>
+    One most POSIX-compliant systems &my-app; can't properly deal with
+    more than FD_SETSIZE file descriptors at the same time and has to reject
+    connections if the limit is reached. This will likely change in a
+    future version, but currently this limit can't be increased without
+    recompiling &my-app; with a different FD_SETSIZE limit.
+   </para>

   </listitem>
  </varlistentry>
  <varlistentry>
   </listitem>
  </varlistentry>
  <varlistentry>


@@ -3126,6 +3294,72 @@ forward-socks4, forward-socks4a and forward-socks5</title>
 </sect3>
 
 
 </sect3>
 
 

+<sect3 renderas="sect4" id="client-header-order"><title>client-header-order</title>
+<variablelist>
+ <varlistentry>
+  <term>Specifies:</term>
+  <listitem>
+   <para>
+    The order in which client headers are sorted before forwarding them.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Type of value:</term>
+  <listitem>
+   <para>
+    <replaceable>Client header names delimited by spaces or tabs</replaceable>
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Default value:</term>
+  <listitem>
+   <para>None</para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+     By default &my-app; leaves the client headers in the order they
+     were sent by the client. Headers are modified in-place, new headers
+     are added at the end of the already existing headers.
+   </para>
+   <para>
+     The header order can be used to fingerprint client requests
+     independently of other headers like the User-Agent.
+   </para>
+   <para>
+     This directive allows to sort the headers differently to better
+     mimic a different User-Agent. Client headers will be emitted
+     in the order given, headers whose name isn't explicitly specified
+     are added at the end.
+   </para>
+   <para>
+     Note that sorting headers in an uncommon way will make fingerprinting
+     actually easier. Encrypted headers are not affected by this directive.
+   </para>
+  </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#client-header-order Host \
+ User-Agent \
+ Accept \
+ Accept-Language \
+ Accept-Encoding \
+ Proxy-Connection \
+ Referer \
+ Cookie \
+ DNT \
+ If-Modified-Since \
+ Cache-Control \
+ Content-Length \
+ Content-Type
+</literallayout>]]>
+</sect3>
+
+

 </sect2>
 
 <!--  ~  End section  ~  -->
 </sect2>
 
 <!--  ~  End section  ~  -->


@@ -3165,8 +3399,9 @@ forward-socks4, forward-socks4a and forward-socks5</title>
 <![%config-file;[<para>@@</para>]]> <!-- for spacing -->
 <para>
  If <quote>log-messages</quote> is set to 1,
 <![%config-file;[<para>@@</para>]]> <!-- for spacing -->
 <para>
  If <quote>log-messages</quote> is set to 1,

- <application>Privoxy</application> will log messages to the console
- window:
+ <application>Privoxy</application> copies log messages to the console
+ window.
+ The log detail depends on the <link linkend="debug">debug</link> directive.

 </para>
 
 <![%config-file;[<literallayout>@@#log-messages   1</literallayout>]]>
 </para>
 
 <![%config-file;[<literallayout>@@#log-messages   1</literallayout>]]>