Purpose : Used with other docs and files only.
- $Id: p-config.sgml,v 2.97 2013/03/01 17:39:27 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.
========================================================================
Sample Configuration File for Privoxy &p-version;
</title>
<para>
- $Id: p-config.sgml,v 2.97 2013/03/01 17:39:27 fabiankeil Exp $
+ $Id: p-config.sgml,v 2.127 2017/06/26 12:14:38 fabiankeil Exp $
</para>
<para>
-Copyright (C) 2001-2013 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>).
- </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 ~~~~~ -->
<![%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 ~ -->
</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>
</sect3>
+<sect3 renderas="sect4" id="listen-backlog"><title>listen-backlog</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Connection queue length requested from the operating system.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>Number.</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>128</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ A connection queue length of 128 is requested from the operating system.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ 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>Examples:</term>
+ <listitem>
+ <para>
+ listen-backlog 4096
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#listen-backlog -1</literallayout>]]>
+</sect3>
+
+
+<sect3 renderas="sect4" id="enable-accept-filter"><title>enable-accept-filter</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether or not Privoxy should use an accept filter
+ </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>
+ No accept filter is enabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ 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>Examples:</term>
+ <listitem>
+ <para>
+ enable-accept-filter 1
+ </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>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>
</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 ~~~~~ -->