Purpose : Used with other docs and files only.
- $Id: p-config.sgml,v 2.83 2012/07/27 17:41:10 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.127 2017/06/26 12:14:38 fabiankeil Exp $
- Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2017 Privoxy Developers https://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.83 2012/07/27 17:41:10 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.127 2017/06/26 12:14:38 fabiankeil Exp $
</para>
<para>
-Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/
+Copyright (C) 2001-2017 Privoxy Developers https://www.privoxy.org/
</para>
<para>
<literallayout>
-#################################################################
- #
- Table of Contents #
- #
- I. INTRODUCTION #
- II. FORMAT OF THE CONFIGURATION FILE #
- #
- 1. LOCAL SET-UP DOCUMENTATION #
- 2. CONFIGURATION AND LOG FILE LOCATIONS #
- 3. DEBUGGING #
- 4. ACCESS CONTROL AND SECURITY #
- 5. FORWARDING #
- 6. WINDOWS GUI OPTIONS #
- #
-#################################################################
+##################################################################
+ #
+ Table of Contents #
+ #
+ I. INTRODUCTION #
+ II. FORMAT OF THE CONFIGURATION FILE #
+ #
+ 1. LOCAL SET-UP DOCUMENTATION #
+ 2. CONFIGURATION AND LOG FILE LOCATIONS #
+ 3. DEBUGGING #
+ 4. ACCESS CONTROL AND SECURITY #
+ 5. FORWARDING #
+ 6. MISCELLANEOUS #
+ 7. WINDOWS GUI OPTIONS #
+ #
+##################################################################
</literallayout>
</para>
<term>Effect if unset:</term>
<listitem>
<para>
- <ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/<replaceable class="parameter">version</replaceable>/user-manual/</ulink>
+ <ulink url="https://www.privoxy.org/user-manual/">https://www.privoxy.org/<replaceable class="parameter">version</replaceable>/user-manual/</ulink>
will be used, where <replaceable class="parameter">version</replaceable> is the <application>Privoxy</application> version.
</para>
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#user-manual http://www.privoxy.org/user-manual/</literallayout>]]>
+<![%config-file;[<literallayout>@@#user-manual https://www.privoxy.org/user-manual/</literallayout>]]>
</sect3>
<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>
so that you will notice when things go wrong. The other levels are
probably only of interest if you are hunting down a specific problem.
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
<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>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="trusted-cgi-referer"><title>trusted-cgi-referer</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ A trusted website or webpage whose links can be followed to reach sensitive CGI pages
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>URL or URL prefix</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>Unset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No external pages are considered trusted referers.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Before &my-app; accepts configuration changes through CGI pages like
+ <link linkend="client-specific-tag">client-tags</link> or the
+ <link linkend="enable-remote-toggle">remote toggle</link>, it checks
+ the Referer header to see if the request comes from a trusted source.
+ </para>
+ <para>
+ By default only the webinterface domains
+ <ulink url="http://config.privoxy.org/">config.privoxy.org</ulink>
+ and
+ <ulink url="http://p.p/">p.p</ulink>
+ are considered trustworthy.
+ Requests originating from other domains are rejected to prevent
+ third-parties from modifiying Privoxy's state by e.g. embedding
+ images that result in CGI requests.
+ </para>
+ <para>
+ In some environments it may be desirable to embed links to CGI pages
+ on external pages, for example on an Intranet homepage the Privoxy admin
+ controls.
+ </para>
+ <para>
+ The <quote>trusted-cgi-referer</quote> option can be used to add that page,
+ or the whole domain, as trusted source so the resulting requests aren't
+ rejected.
+ Requests are accepted if the specified trusted-cgi-refer is the prefix
+ of the Referer.
+ </para>
+ <warning>
+ <para>
+ Declaring pages the admin doesn't control trustworthy may allow
+ malicious third parties to modify Privoxy's internal state against
+ the user's wishes and without the user's knowledge.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<![%config-file;[<literallayout>@@trusted-cgi-referer http://www.example.org/local-privoxy-control-page</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
<application>Privoxy's</application> listening port is reachable
by the outside or an attacker has access to the pages you visit.
</para>
+ <para>
+ If you are running Privoxy as intercepting proxy without being
+ able to intercept all client requests you may want to adjust
+ the CGI templates to make sure they don't reference content from
+ config.privoxy.org.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
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>
</sect3>
-<sect3 renderas="sect4" id="handle-as-empty-doc-returns-ok"><title>handle-as-empty-doc-returns-ok</title>
+<sect3 renderas="sect4" id="listen-backlog"><title>listen-backlog</title>
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
- The status code Privoxy returns for pages blocked with
- <!-- URL will only end up in the user manual so the relative link should work. -->
- <literal><ulink url="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT">+handle-as-empty-document</ulink></literal>.
+ Connection queue length requested from the operating system.
</para>
</listitem>
</varlistentry>
<term>Type of value:</term>
<listitem>
<para>
- <replaceable>0 or 1</replaceable>
+ <replaceable>Number.</replaceable>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para>0</para>
+ <para>128</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
<para>
- Privoxy returns a status 403(forbidden) for all blocked pages.
+ A connection queue length of 128 is requested from the operating system.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Effect if set:</term>
+ <term>Notes:</term>
<listitem>
<para>
- Privoxy returns a status 200(OK) for pages blocked with +handle-as-empty-document
- and a status 403(Forbidden) for all other blocked pages.
+ Under high load incoming connection may queue up before Privoxy
+ gets around to serve them. The queue length is limitted by the
+ operating system. Once the queue is full, additional connections
+ are dropped before Privoxy can accept and serve them.
+ </para>
+ <para>
+ Increasing the queue length allows Privoxy to accept more
+ incomming connections that arrive roughly at the same time.
+ </para>
+ <para>
+ Note that Privoxy can only request a certain queue length,
+ whether or not the requested length is actually used depends
+ on the operating system which may use a different length instead.
+ </para>
+ <para>
+ On many operating systems a limit of -1 can be specified to
+ instruct the operating system to use the maximum queue length
+ allowed. Check the listen man page to see if your platform allows this.
+ </para>
+ <para>
+ On some platforms you can use "netstat -Lan -p tcp" to see the effective
+ queue length.
+ </para>
+ <para>
+ Effectively using a value above 128 usually requires changing
+ the system configuration as well. On FreeBSD-based system the
+ limit is controlled by the kern.ipc.soacceptqueue sysctl.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Notes:</term>
+ <term>Examples:</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>
- (<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.
+ listen-backlog 4096
</para>
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#handle-as-empty-doc-returns-ok 1</literallayout>]]>
+<![%config-file;[<literallayout>@@#listen-backlog -1</literallayout>]]>
</sect3>
-<sect3 renderas="sect4" id="enable-compression"><title>enable-compression</title>
+<sect3 renderas="sect4" id="enable-accept-filter"><title>enable-accept-filter</title>
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
- Whether or not buffered content is compressed before delivery.
+ Whether or not Privoxy should use an accept filter
</para>
</listitem>
</varlistentry>
<term>Effect if unset:</term>
<listitem>
<para>
- Privoxy does not compress buffered content.
+ No accept filter is enabled.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Effect if set:</term>
+ <term>Notes:</term>
<listitem>
<para>
- Privoxy compresses buffered content before delivering it to the client,
- provided the client supports it.
+ Accept filters reduce the number of context switches by not
+ passing sockets for new connections to Privoxy until a complete
+ HTTP request is available.
+ </para>
+ <para>
+ As a result, Privoxy can process the whole request right away
+ without having to wait for additional data first.
+ </para>
+ <para>
+ For this option to work, Privoxy has to be compiled with
+ FEATURE_ACCEPT_FILTER and the operating system has to support
+ it (which may require loading a kernel module).
+ </para>
+ <para>
+ Currently accept filters are only supported on FreeBSD-based
+ systems. Check the
+ <ulink url="https://www.freebsd.org/cgi/man.cgi?query=accf_http">accf_http(9)
+ man page</ulink>
+ to learn how to enable the support in the operating system.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Notes:</term>
+ <term>Examples:</term>
<listitem>
<para>
- This directive is only supported if Privoxy has been compiled with
- FEATURE_COMPRESSION, which should not to be confused with FEATURE_ZLIB.
+ enable-accept-filter 1
</para>
- <para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#enable-accept-filter 1</literallayout>]]>
+</sect3>
+
+
+<sect3 renderas="sect4" id="handle-as-empty-doc-returns-ok"><title>handle-as-empty-doc-returns-ok</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The status code Privoxy returns for pages blocked with
+ <!-- URL will only end up in the user manual so the relative link should work. -->
+ <literal><ulink url="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT">+handle-as-empty-document</ulink></literal>.
+ </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>0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Privoxy returns a status 403(forbidden) for all blocked pages.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if set:</term>
+ <listitem>
+ <para>
+ Privoxy returns a status 200(OK) for pages blocked with +handle-as-empty-document
+ and a status 403(Forbidden) for all other blocked pages.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ 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>),
+ 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>
+</variablelist>
+<![%config-file;[<literallayout>@@#handle-as-empty-doc-returns-ok 1</literallayout>]]>
+</sect3>
+
+
+<sect3 renderas="sect4" id="enable-compression"><title>enable-compression</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether or not buffered content is compressed before delivery.
+ </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>0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Privoxy does not compress buffered content.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if set:</term>
+ <listitem>
+ <para>
+ Privoxy compresses buffered content before delivering it to the client,
+ provided the client supports it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This directive is only supported if Privoxy has been compiled with
+ FEATURE_COMPRESSION, which should not to be confused with FEATURE_ZLIB.
+ </para>
+ <para>
Compressing buffered content is mainly useful if Privoxy and the
client are running on different systems. If they are running on the
same system, enabling compression is likely to slow things down.
</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>
-</sect2>
+<sect3 renderas="sect4" id="client-specific-tag"><title>client-specific-tag</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The name of a tag that will always be set for clients that
+ requested it through the webinterface.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>Tag name followed by a description that will be shown in the webinterface</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>None</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>
+ Client-specific tags allow Privoxy admins to create different
+ profiles and let the users chose which one they want without
+ impacting other users.
+ </para>
+ <para>
+ One use case is allowing users to circumvent certain blocks
+ without having to allow them to circumvent all blocks.
+ This is not possible with the
+ <link linkend="enable-remote-toggle">enable-remote-toggle feature</link>
+ because it would bluntly disable all blocks for all users and also affect
+ other actions like filters.
+ It also is set globally which renders it useless in most multi-user setups.
+ </para>
+ <para>
+ After a client-specific tag has been defined with the client-specific-tag
+ directive, action sections can be activated based on the tag by using a
+ <ulink url="actions-file.html#CLIENT-TAG-PATTERN">CLIENT-TAG</ulink> pattern.
+ The CLIENT-TAG pattern is evaluated at the same priority
+ as URL patterns, as a result the last matching pattern wins.
+ Tags that are created based on client or server headers are evaluated
+ later on and can overrule CLIENT-TAG and URL patterns!
+ </para>
+ <para>
+ The tag is set for all requests that come from clients that requested
+ it to be set.
+ Note that "clients" are differentiated by IP address,
+ if the IP address changes the tag has to be requested again.
+ </para>
+ <para>
+ Clients can request tags to be set by using the CGI interface <ulink
+ url="http://config.privoxy.org/client-tags">http://config.privoxy.org/client-tags</ulink>.
+ The specific tag description is only used on the web page and should
+ be phrased in away that the user understand the effect of the tag.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ <screen>
+ # Define a couple of tags, the described effect requires action sections
+ # that are enabled based on CLIENT-TAG patterns.
+ client-specific-tag circumvent-blocks Overrule blocks but do not affect other actions
+ disable-content-filters Disable content-filters but do not affect other actions
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+<sect3 renderas="sect4" id="client-tag-lifetime"><title>client-tag-lifetime</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ How long a temporarily enabled tag remains enabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>Time in seconds.</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>60</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>
+ In case of some tags users may not want to enable them permanently,
+ but only for a short amount of time, for example to circumvent a block
+ that is the result of an overly-broad URL pattern.
+ </para>
+ <para>
+ The CGI interface <ulink
+ url="http://config.privoxy.org/client-tags">http://config.privoxy.org/client-tags</ulink>
+ therefore provides a "enable this tag temporarily" option.
+ If it is used, the tag will be set until the client-tag-lifetime
+ is over.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ <screen>
+ # Increase the time to life for temporarily enabled tags to 3 minutes
+ client-tag-lifetime 180
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</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>
<!-- ~ End section ~ -->
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="receive-buffer-size"><title>receive-buffer-size</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The size of the buffer Privoxy uses to receive data from the server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>Size in bytes</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>5000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Increasing the receive-buffer-size increases Privoxy's memory usage but
+ can lower the number of context switches and thereby reduce the
+ cpu usage and potentially increase the throughput.
+ </para>
+ <para>
+ This is mostly relevant for fast network connections and
+ large downloads that don't require filtering.
+ </para>
+ <para>
+ Reducing the buffer size reduces the amount of memory Privoxy
+ needs to handle the request but increases the number of systemcalls
+ and may reduce the throughput.
+ </para>
+ <para>
+ A dtrace command like:
+ <quote>sudo dtrace -n 'syscall::read:return /execname == "privoxy"/ { @[execname] = llquantize(arg0, 10, 0, 5, 20); @m = max(arg0)}'</quote>
+ can be used to properly tune the receive-buffer-size.
+ On systems without dtrace, strace or truss may be used as
+ less convenient alternatives.
+ </para>
+ <para>
+ If the buffer is too large it will increase Privoxy's memory
+ footprint without any benefit. As the memory is (currently)
+ cleared before using it, a buffer that is too large can
+ actually reduce the throughput.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ <screen>
+ # Increase the receive buffer size
+ receive-buffer-size 32768
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+</sect2>
<!-- ~~~~~ New section ~~~~~ -->
<![%config-file;[<para>@@</para>]]> <!-- for spacing -->
<para>
If <quote>log-messages</quote> is set to 1,
- <application>Privoxy</application> copy log messages to the console
+ <application>Privoxy</application> copies log messages to the console
window.
The log detail depends on the <link linkend="debug">debug</link> directive.
</para>
projects / privoxy.git / blobdiff