Purpose : Used with other docs and files only.
- $Id: p-config.sgml,v 2.82 2012/07/27 17:36:06 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.111 2014/11/14 11:31:24 fabiankeil Exp $
- Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2014 Privoxy Developers http://www.privoxy.org/
See LICENSE.
========================================================================
<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>
- $Id: p-config.sgml,v 2.82 2012/07/27 17:36:06 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.111 2014/11/14 11:31:24 fabiankeil Exp $
</para>
<para>
-Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/
+Copyright (C) 2001-2014 Privoxy Developers http://www.privoxy.org/
</para>
<para>
3. DEBUGGING #
4. ACCESS CONTROL AND SECURITY #
5. FORWARDING #
- 6. WINDOWS GUI OPTIONS #
+ 6. MISCELLANEOUS #
+ 7. WINDOWS GUI OPTIONS #
#
#################################################################
</literallayout>
<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>
</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>
<para>
Actions files contain all the per site and per URL configuration for
ad blocking, cookie management, privacy considerations, etc.
- There is no point in using <application>Privoxy</application> without at
- least one actions file.
- </para>
- <para>
- Note that since Privoxy 3.0.7, the complete filename, including the <quote>.action</quote>
- extension has to be specified. The syntax change was necessary to be consistent
- with the other file options and to allow previously forbidden characters.
</para>
</listitem>
</varlistentry>
<para>
Depending on the debug options below, the logfile may be a privacy risk
if third parties can get access to it. As most users will never look
- at it, <application>Privoxy</application> 3.0.7 and later only log fatal
- errors by default.
+ at it, <application>Privoxy</application> only logs fatal errors by default.
</para>
<para>
For most troubleshooting purposes, you will have to change that,
please refer to the debugging section for details.
</para>
- <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.
- </para>
<para>
Any log files must be writable by whatever user <application>Privoxy</application>
is being run as (on Unix, default user id is <quote>privoxy</quote>).
</para>
+ <para>
+ To prevent the logfile from growing indefinitely, it is recommended to
+ periodically rotate or shorten it. Many operating systems support log
+ rotation out of the box, some require additional software to do it.
+ For details, please refer to the documentation for your operating system.
+ </para>
</listitem>
</varlistentry>
</variablelist>
They can produce a hell of an output (especially 16).
<!-- LOL -->
</para>
- <para>
- &my-app; used to ship with the debug levels recommended above enabled by
- default, but due to privacy concerns 3.0.7 and later are configured to
- only log fatal errors.
- </para>
<para>
If you are used to the more verbose settings, simply enable the debug lines
below again.
<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>
- <para><emphasis>Unset</emphasis></para>
+ <para><emphasis>0</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#single-threaded</literallayout>]]>
+<![%config-file;[<literallayout>@@#single-threaded 1</literallayout>]]>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
<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>
<![%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 ~ -->
<!-- ~~~~~ 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">
<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>
<para>
<screen>
- forward-socks5 / 127.0.0.1:9050 .
+ forward-socks5t / 127.0.0.1:9050 .
</screen>
</para>
-
- <para>
+ <para>
+ Note that if you got Tor through one of the bundles, you may
+ have to change the port from 9050 to 9150 (or even another one).
+ For details, please check the documentation on the
+ <ulink url="https://torproject.org/">Tor website</ulink>.
+ </para>
+ <para>
The public <application>Tor</application> network can't be used to
reach your local network, if you need to access local servers you
therefore might want to make some exceptions:
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
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>
</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>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para>None</para>
+ <para>128</para>
</listitem>
</varlistentry>
<varlistentry>
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>
<term>Notes:</term>
<listitem>
<para>
- This is a work-around for Firefox bug 492459:
- <quote>
- Websites are no longer rendered if SSL requests for JavaScripts are blocked by a proxy.
- </quote>
+ This directive was added as a work-around for Firefox bug 492459:
+ <quote>Websites are no longer rendered if SSL requests for JavaScripts are blocked by a proxy.</quote>
(<ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=492459"
- >https://bugzilla.mozilla.org/show_bug.cgi?id=492459</ulink>)
- As the bug has been fixed for quite some time this option should no longer
- be needed and will be removed in a future release. Please speak up if you
- have a reason why the option should be kept around.
+ >https://bugzilla.mozilla.org/show_bug.cgi?id=492459</ulink>),
+ the bug has been fixed for quite some time, but this directive is also useful
+ to make it harder for websites to detect whether or not resources are being
+ blocked.
</para>
</listitem>
</varlistentry>
</varlistentry>
</variablelist>
<![%config-file;[<literallayout>@@#client-header-order Host \
-# User-Agent \
-# Accept \
-# Accept-Language \
-# Accept-Encoding \
-# Proxy-Connection,\
-# Referer,Cookie \
-# If-Modified-Since \
-# Cache-Control \
-# Content-Length \
-# Content-Type
+ User-Agent \
+ Accept \
+ Accept-Language \
+ Accept-Encoding \
+ Proxy-Connection \
+ Referer \
+ Cookie \
+ DNT \
+ If-Modified-Since \
+ Cache-Control \
+ Content-Length \
+ Content-Type
</literallayout>]]>
</sect3>
<![%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>]]>