<!--
- File : $Source: /cvsroot/ijbswa/current/doc/source/p-config.sgml,v $
+ File : doc/source/p-config.sgml
Purpose : Used with other docs and files only.
- $Id: p-config.sgml,v 2.114 2016/02/26 12:32:56 fabiankeil Exp $
-
- Copyright (C) 2001-2016 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
example:
</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>confdir /etc/privoxy</emphasis></literallayout>
- </msgtext>
- </literal>
-</para>
+<literallayout>
+ <emphasis>confdir /etc/privoxy</emphasis>
+</literallayout>
<para>
Assigns the value <literal>/etc/privoxy</literal> to the option
Sample Configuration File for Privoxy &p-version;
</title>
<para>
- $Id: p-config.sgml,v 2.114 2016/02/26 12:32:56 fabiankeil Exp $
-</para>
-<para>
-Copyright (C) 2001-2016 Privoxy Developers http://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. MISCELLANEOUS #
- 7. WINDOWS GUI OPTIONS #
- #
-#################################################################
- </literallayout>
+Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/
</para>
-<literallayout>I. INTRODUCTION
- =============== <!-- fuck this madness --></literallayout>
+<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. MISCELLANEOUS #
+ 7. HTTPS INSPECTION (EXPERIMENTAL) #
+ 8. WINDOWS GUI OPTIONS #
+ #
+##################################################################
+
+
+I. INTRODUCTION
+ ===============
+</literallayout>
<para>
This file holds Privoxy's main configuration. Privoxy detects
<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>
<para>
Unix, in local filesystem (may not work with all browsers):
</para>
- <para>
<screen> user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/</screen>
- </para>
<para>
Windows, in local filesystem, <emphasis>must</emphasis> use forward slash notation:
</para>
- <para>
<screen> user-manual file:/c:/some-dir/privoxy-&p-version;/user-manual/</screen>
- </para>
<para>
Windows, UNC notation (with forward slashes):
</para>
- <para>
<screen> user-manual file://///some-server/some-path/privoxy-&p-version;/user-manual/</screen>
- </para>
-->
<para>
The best all purpose solution is simply to put the full local
<literal>PATH</literal> to where the <citetitle>User Manual</citetitle> is
located:
</para>
- <para>
- <screen> user-manual /usr/share/doc/privoxy/user-manual</screen>
- </para>
+ <screen> user-manual /usr/share/doc/privoxy/user-manual</screen>
<para>
The User Manual is then available to anyone with access to
<application>Privoxy</application>, by following the built-in URL:
If the documentation is not on the local system, it can be accessed
from a remote server, as:
</para>
- <para>
- <screen> user-manual http://example.com/privoxy/user-manual/</screen>
- </para>
+ <screen> user-manual http://example.com/privoxy/user-manual/</screen>
<![%user-man;[
<!-- this gets hammered in conversion to config. Text repeated below. -->
<warning>
</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>
The available debug levels are:
</para>
- <para>
<programlisting>
- debug 1 # Log the destination for each request &my-app; let through. See also debug 1024.
+ debug 1 # Log the destination for each request. See also debug 1024.
debug 2 # show each connection status
debug 4 # show I/O status
debug 8 # show header parsing
debug 32768 # log all data read from the network
debug 65536 # Log the applying actions
</programlisting>
- </para>
<para>
To select multiple debug levels, you can either add them or use
multiple <literal>debug</literal> lines.
If the specified address isn't available on the system, or if the
hostname can't be resolved, <application>Privoxy</application>
will fail to start.
+ On GNU/Linux, and other platforms that can listen on not yet assigned IP
+ addresses, Privoxy will start and will listen on the specified
+ address whenever the IP address is assigned to the system
</para>
<para>
IPv6 addresses containing colons have to be quoted by brackets.
(192.168.0.0) and has another outside connection with a different address.
You want it to serve requests from inside only:
</para>
- <para>
<programlisting>
listen-address 192.168.0.1:8118
</programlisting>
- </para>
<para>
Suppose you are running <application>Privoxy</application> on an
IPv6-capable machine and you want it to listen on the IPv6 address
of the loopback device:
</para>
- <para>
<programlisting>
listen-address [::1]:8118
</programlisting>
- </para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
enforce-blocks 1
If your system implements
<ulink url="http://tools.ietf.org/html/rfc3493">RFC 3493</ulink>, then
<replaceable class="parameter">src_addr</replaceable> and <replaceable
- class="parameter">dst_addr</replaceable> can be IPv6 addresses delimeted by
+ class="parameter">dst_addr</replaceable> can be IPv6 addresses delimited by
brackets, <replaceable class="parameter">port</replaceable> can be a number
or a service name, and
<replaceable class="parameter">src_masklen</replaceable> and
is OK. The absence of a <replaceable class="parameter">dst_addr</replaceable> implies that
<emphasis>all</emphasis> destination addresses are OK:
</para>
- <para>
<screen>
permit-access localhost
</screen>
- </para>
<para>
Allow any host on the same class C subnet as www.privoxy.org access to
nothing but www.example.com (or other domains hosted on the same system):
</para>
- <para>
<screen>
permit-access www.privoxy.org/24 www.example.com/32
</screen>
- </para>
<para>
Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
with the exception that 192.168.45.73 may not access the IP address behind
www.dirty-stuff.example.com:
</para>
- <para>
<screen>
permit-access 192.168.45.64/26
deny-access 192.168.45.73 www.dirty-stuff.example.com
</screen>
- </para>
<para>
Allow access from the IPv4 network 192.0.2.0/24 even if listening on
an IPv6 wild card address (not supported on all platforms):
</para>
- <para>
<programlisting>
permit-access 192.0.2.0/24
</programlisting>
- </para>
<para>
This is equivalent to the following line even if listening on an
IPv4 address (not supported on all platforms):
</para>
- <para>
<programlisting>
permit-access [::ffff:192.0.2.0]/120
</programlisting>
- </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>
+ <para>
+ If the trusted source is supposed to access the CGI pages via
+ JavaScript the <link linkend="cors-allowed-origin">cors-allowed-origin</link>
+ option can be used.
+ </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>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="cors-allowed-origin"><title>cors-allowed-origin</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ A trusted website which can access &my-app;'s CGI pages through JavaScript.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>URL</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>Unset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No external sites get access via cross-origin resource sharing.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Modern browsers by default prevent cross-origin requests made
+ via JavaScript to &my-app;'s CGI interface even if &my-app;
+ would trust the referer because it's white listed via the
+ <link linkend="trusted-cgi-referer">trusted-cgi-referer</link>
+ directive.
+ </para>
+ <para>
+ <ulink url="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing"
+ >Cross-origin resource sharing (CORS)</ulink> is a mechanism to allow
+ cross-origin requests.
+ </para>
+ <para>
+ The <quote>cors-allowed-origin</quote> option can be used to specify
+ a domain that is allowed to make requests to Privoxy CGI interface
+ via JavaScript. It is used in combination with the
+ <link linkend="trusted-cgi-referer">trusted-cgi-referer</link>
+ directive.
+ </para>
+ <warning>
+ <para>
+ Declaring domains 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>@@#cors-allowed-origin http://www.example.org/</literallayout>]]>
+</sect3>
+
</sect2>
<!-- ~ End section ~ -->
<para>
Everything goes to an example parent proxy, except SSL on port 443 (which it doesn't handle):
</para>
- <para>
<screen>
forward / parent-proxy.example.org:8080
forward :443 .
</screen>
- </para>
<para>
Everything goes to our example ISP's caching proxy, except for requests
to that ISP's sites:
</para>
- <para>
<screen>
forward / caching-proxy.isp.example.net:8000
forward .isp.example.net .
</screen>
- </para>
<para>
Parent proxy specified by an IPv6 address:
</para>
- <para>
<programlisting>
forward / [2001:DB8::1]:8000
</programlisting>
- </para>
<para>
Suppose your parent proxy doesn't support IPv6:
</para>
- <para>
<programlisting>
forward / parent-proxy.example.org:8000
forward ipv6-server.example.org .
forward <[2-3][0-9a-f][0-9a-f][0-9a-f]:*> .
</programlisting>
- </para>
</listitem>
</varlistentry>
</variablelist>
<listitem>
<para>
<replaceable class="parameter">target_pattern</replaceable>
- <replaceable class="parameter">socks_proxy</replaceable>[:<replaceable class="parameter">port</replaceable>]
+ [<replaceable class="parameter">user</replaceable>:<replaceable class="parameter">pass</replaceable>@]<replaceable class="parameter">socks_proxy</replaceable>[:<replaceable class="parameter">port</replaceable>]
<replaceable class="parameter">http_parent</replaceable>[:<replaceable class="parameter">port</replaceable>]
</para>
<para>
(<replaceable class="parameter">http_parent</replaceable>
may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
<replaceable class="parameter">port</replaceable> parameters are TCP ports,
- i.e. integer values from 1 to 65535
+ i.e. integer values from 1 to 65535. <replaceable class="parameter">user</replaceable> and
+ <replaceable class="parameter">pass</replaceable> can be used for SOCKS5 authentication if required.
</para>
</listitem>
</varlistentry>
their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
the Internet.
</para>
- <para>
<screen>
forward-socks4a / socks-gw.example.com:1080 www-cache.isp.example.net:8080
forward .example.com .
</screen>
- </para>
<para>
A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
</para>
- <para>
<screen>
forward-socks4 / socks-gw.example.com:1080 .
</screen>
+
+ <para>
+ To connect SOCKS5 proxy which requires username/password authentication:
</para>
+ <screen>
+ forward-socks5 / user:pass@socks-gw.example.com:1080 .
+</screen>
<para>
To chain Privoxy and Tor, both running on the same system, you would use
something like:
</para>
- <para>
<screen>
forward-socks5t / 127.0.0.1:9050 .
</screen>
- </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).
reach your local network, if you need to access local servers you
therefore might want to make some exceptions:
</para>
- <para>
<screen>
forward 192.168.*.*/ .
- forward 10.*.*.*/ .
- forward 127.*.*.*/ .
+ forward 10.*.*.*/ .
+ forward 127.*.*.*/ .
</screen>
- </para>
<para>
Unencrypted connections to systems in these address ranges will
be as (un)secure as the local network is, but the alternative is that you
using their names, you will need additional exceptions that look like
this:
</para>
- <para>
<screen>
forward localhost/ .
</screen>
- </para>
</listitem>
</varlistentry>
host-a:
</para>
-<para>
<screen>
forward / .
forward .isp-b.example.net host-b:8118
</screen>
-</para>
<para>
host-b:
</para>
-<para>
<screen>
forward / .
forward .isp-a.example.org host-a:8118
</screen>
-</para>
<para>
Now, your users can set their browser's proxy to use either
run on the same box, your <application>squid</application> configuration could then look like this:
</para>
-<para>
<screen>
# Define Privoxy as parent proxy (without ICP)
cache_peer 127.0.0.1 parent 8118 7 no-query
# Forward all the rest to Privoxy
never_direct allow all</screen>
-</para>
<para>
You would then need to change your browser's proxy settings to <application>squid</application>'s address and port.
say, on <literal>antivir.example.com</literal>, port 8010:
</para>
-<para>
<screen>
forward / .
forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010</screen>
-</para>
</sect3>
]]>
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
forwarded-connect-retries 1
<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>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
accept-intercepted-requests 1
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
allow-cgi-request-crunching 1
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
split-large-forms 1
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
keep-alive-timeout 300
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
tolerate-pipelining 1
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
default-server-timeout 60
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#default-server-timeout 60</literallayout>]]>
+<![%config-file;[<literallayout>@@#default-server-timeout 5</literallayout>]]>
</sect3>
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
connection-sharing 1
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
socket-timeout 300
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
max-client-connections 256
</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 limited 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
+ incoming 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>Example:</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.
+ 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>
- </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.
+ As a result, Privoxy can process the whole request right away
+ without having to wait for additional data first.
</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.
- If you didn't measure otherwise, you should assume that it does
- and keep this option disabled.
+ 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>
- Privoxy will not compress buffered content below a certain length.
+ 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>Example:</term>
+ <listitem>
+ <para>
+ enable-accept-filter 1
</para>
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#enable-compression 1</literallayout>]]>
+<![%config-file;[<literallayout>@@#enable-accept-filter 1</literallayout>]]>
</sect3>
-<sect3 renderas="sect4" id="compression-level"><title>compression-level</title>
+<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 compression level that is passed to the zlib library when compressing buffered content.
+ 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>
<term>Type of value:</term>
<listitem>
<para>
- <replaceable>Positive number ranging from 0 to 9.</replaceable>
+ <replaceable>0 or 1</replaceable>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para>1</para>
+ <para>0</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Notes:</term>
+ <term>Effect if unset:</term>
<listitem>
<para>
- Compressing the data more takes usually longer than compressing
- it less or not compressing it at all. Which level is best depends
+ 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.
+ If you didn't measure otherwise, you should assume that it does
+ and keep this option disabled.
+ </para>
+ <para>
+ Privoxy will not compress buffered content below a certain length.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#enable-compression 1</literallayout>]]>
+</sect3>
+
+
+<sect3 renderas="sect4" id="compression-level"><title>compression-level</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The compression level that is passed to the zlib library when compressing buffered content.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable>Positive number ranging from 0 to 9.</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Compressing the data more takes usually longer than compressing
+ it less or not compressing it at all. Which level is best depends
on the connection between Privoxy and the client. If you can't
be bothered to benchmark it for yourself, you should stick with
the default and keep compression disabled.
</para>
<para>
- If compression is disabled, the compression level is irrelevant.
+ If compression is disabled, the compression level is irrelevant.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <screen>
+ # Best speed (compared to the other levels)
+ compression-level 1
+
+ # Best compression
+ compression-level 9
+
+ # No compression. Only useful for testing as the added header
+ # slightly increases the amount of data that has to be sent.
+ # If your benchmark shows that using this compression level
+ # is superior to using no compression at all, the benchmark
+ # is likely to be flawed.
+ compression-level 0
+</screen>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#compression-level 1</literallayout>]]>
+</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>
+
+
+<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>
+ <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
+ client-specific-tag disable-content-filters Disable content-filters but do not affect other actions
+</screen>
+ </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>Example:</term>
+ <listitem>
+ <screen>
+ # Increase the time to life for temporarily enabled tags to 3 minutes
+ client-tag-lifetime 180
+</screen>
+ </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>Example:</term>
+ <listitem>
+ <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>
+ </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>Example:</term>
+ <listitem>
+ <screen>
+ # Increase the receive buffer size
+ receive-buffer-size 32768
+</screen>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+</sect2>
+
+
+<sect2 id="https-inspection-directives">
+<title>HTTPS Inspection (Experimental)</title>
+
+<para>
+ HTTPS inspection allows to filter encrypted requests.
+ This is only supported when <application>Privoxy</application>
+ has been built with FEATURE_HTTPS_INSPECTION.
+</para>
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="ca-directory"><title>ca-directory</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Directory with the CA key, the CA certificate and the trusted CAs file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ Text
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Empty string</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Default value is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This directive specifies the directory where the
+ CA key, the CA certificate and the trusted CAs file
+ are located.
+ </para>
+ <para>
+ The permissions should only let &my-app; and the &my-app;
+ admin access the directory.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Example:</term>
+ <listitem>
+ <para>
+ ca-directory /usr/local/etc/privoxy/CA
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#ca-directory /usr/local/etc/privoxy/CA</literallayout>]]>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="ca-cert-file"><title>ca-cert-file</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The CA certificate file in ".crt" format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ Text
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>cacert.crt</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Default value is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This directive specifies the name of the CA certificate file
+ in ".crt" format.
+ </para>
+ <para>
+ The file is used by &my-app; to generate website certificates
+ when https inspection is enabled with the
+ <literal><ulink url="actions-file.html#HTTPS-INSPECTION">https-inspection</ulink></literal>
+ action.
+ </para>
+ <para>
+ &my-app; clients should import the certificate so that they
+ can validate the generated certificates.
+ </para>
+ <para>
+ The file can be generated with:
+ openssl req -new -x509 -extensions v3_ca -keyout cakey.pem -out cacert.crt -days 3650
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Example:</term>
+ <listitem>
+ <para>
+ ca-cert-file root.crt
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#ca-cert-file cacert.crt</literallayout>]]>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="ca-key-file"><title>ca-key-file</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The CA key file in ".pem" format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ Text
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>cacert.pem</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
<listitem>
<para>
- <screen>
- # Best speed (compared to the other levels)
- compression-level 1
- # Best compression
- compression-level 9
- # No compression. Only useful for testing as the added header
- # slightly increases the amount of data that has to be sent.
- # If your benchmark shows that using this compression level
- # is superior to using no compression at all, the benchmark
- # is likely to be flawed.
- compression-level 0
- </screen>
+ Default value is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This directive specifies the name of the CA key file
+ in ".pem" format. See the <ulink url="#CA-CERT-FILE">ca-cert-file</ulink>
+ for a command to generate it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Example:</term>
+ <listitem>
+ <para>
+ ca-key-file cakey.pem
</para>
</listitem>
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#compression-level 1</literallayout>]]>
+<![%config-file;[<literallayout>@@#ca-key-file cakey.pem</literallayout>]]>
</sect3>
+<!-- ~ End section ~ -->
-<sect3 renderas="sect4" id="client-header-order"><title>client-header-order</title>
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="ca-password"><title>ca-password</title>
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
- The order in which client headers are sorted before forwarding them.
+ The password for the CA keyfile.
</para>
</listitem>
</varlistentry>
<term>Type of value:</term>
<listitem>
<para>
- <replaceable>Client header names delimited by spaces or tabs</replaceable>
+ Text
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para>None</para>
+ <para><emphasis>Empty string</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Default value is used.
+ </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.
+ This directive specifies the password for the CA keyfile
+ that is used when Privoxy generates certificates for intercepted
+ requests.
</para>
<para>
- The header order can be used to fingerprint client requests
- independently of other headers like the User-Agent.
+ Note that the password is shown on the CGI page so don't
+ reuse an important one.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Example:</term>
+ <listitem>
+ <para>
+ ca-password blafasel
</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#ca-password swordfish</literallayout>]]>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="certificate-directory"><title>certificate-directory</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
<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.
+ Directory to save generated keys and certificates.
</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
<para>
- Note that sorting headers in an uncommon way will make fingerprinting
- actually easier. Encrypted headers are not affected by this directive.
+ Text
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>./certs</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Default value is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This directive specifies the directory where generated
+ TLS/SSL keys and certificates are saved when https inspection
+ is enabled with the
+ <literal><ulink url="actions-file.html#HTTPS-INSPECTION">https-inspection</ulink></literal>
+ action.
+ </para>
+ <para>
+ The keys and certificates currently have to be deleted manually
+ when changing the <ulink url="#CA-CERT-FILE">ca-cert-file</ulink>
+ and the <ulink url="#CA-CERT-KEY">ca-cert-key</ulink>.
+ </para>
+ <para>
+ The permissions should only let &my-app; and the &my-app;
+ admin access the directory.
+ </para>
+ <warning>
+ <para>
+ &my-app; currently does not garbage-collect obsolete keys
+ and certificates and does not keep track of how may keys
+ and certificates exist.
+ </para>
+ <para>
+ &my-app; admins should monitor the size of the directory
+ and/or make sure there is sufficient space available.
+ A cron job to limit the number of keys and certificates
+ to a certain number may be worth considering.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Example:</term>
+ <listitem>
+ <para>
+ certificate-directory /usr/local/var/privoxy/certs
</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>]]>
+<![%config-file;[<literallayout>@@#certificate-directory /usr/local/var/privoxy/certs</literallayout>]]>
</sect3>
+<!-- ~ End section ~ -->
-<sect3 renderas="sect4" id="client-specific-tag"><title>client-specific-tag</title>
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="cipher-list"><title>cipher-list</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.
+ A list of ciphers to use in TLS handshakes
</para>
</listitem>
</varlistentry>
<term>Type of value:</term>
<listitem>
<para>
- <replaceable>Tag name followed by a description that will be shown in the webinterface</replaceable>
+ Text
</para>
</listitem>
</varlistentry>
<para>None</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ A default value is inherited from the TLS library.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
- <warning>
<para>
- This is an experimental feature. The syntax is likely to change
- in future versions.
+ This directive allows to specify a non-default list of ciphers to use
+ in TLS handshakes with clients and servers.
+ </para>
+ <para>
+ Ciphers are separated by colons. Which ciphers are supported
+ depends on the TLS library. When using OpenSSL, unsupported ciphers
+ are skipped. When using MbedTLS they are rejected.
</para>
+ <warning>
+ <para>
+ Specifying an unusual cipher list makes fingerprinting easier.
+ Note that the default list provided by the TLS library may
+ be unusual when compared to the one used by modern browsers
+ as well.
+ </para>
</warning>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <screen>
+ # Explicitly set a couple of ciphers with names used by MbedTLS
+ cipher-list cipher-list TLS-ECDHE-RSA-WITH-CHACHA20-POLY1305-SHA256:\
+TLS-ECDHE-ECDSA-WITH-CHACHA20-POLY1305-SHA256:\
+TLS-DHE-RSA-WITH-CHACHA20-POLY1305-SHA256:\
+TLS-ECDHE-ECDSA-WITH-AES-128-GCM-SHA256:\
+TLS-ECDHE-ECDSA-WITH-AES-256-GCM-SHA384:\
+TLS-ECDHE-ECDSA-WITH-AES-256-CCM:\
+TLS-ECDHE-ECDSA-WITH-AES-256-CCM-8:\
+TLS-ECDHE-ECDSA-WITH-AES-128-CCM:\
+TLS-ECDHE-ECDSA-WITH-AES-128-CCM-8:\
+TLS-ECDHE-ECDSA-WITH-CAMELLIA-128-GCM-SHA256:\
+TLS-ECDHE-ECDSA-WITH-CAMELLIA-256-GCM-SHA384:\
+TLS-ECDHE-RSA-WITH-AES-128-GCM-SHA256:\
+TLS-ECDHE-RSA-WITH-AES-256-GCM-SHA384:\
+TLS-ECDHE-RSA-WITH-CAMELLIA-128-GCM-SHA256:\
+TLS-ECDHE-RSA-WITH-CAMELLIA-256-GCM-SHA384:\
+TLS-DHE-RSA-WITH-AES-256-GCM-SHA384:\
+TLS-DHE-RSA-WITH-AES-128-GCM-SHA256:\
+TLS-DHE-RSA-WITH-AES-256-CCM:\
+TLS-DHE-RSA-WITH-AES-256-CCM-8:\
+TLS-DHE-RSA-WITH-AES-128-CCM:\
+TLS-DHE-RSA-WITH-AES-128-CCM-8:\
+TLS-DHE-RSA-WITH-CAMELLIA-128-GCM-SHA256:\
+TLS-DHE-RSA-WITH-CAMELLIA-256-GCM-SHA384:\
+TLS-ECDH-RSA-WITH-AES-128-GCM-SHA256:\
+TLS-ECDH-RSA-WITH-AES-256-GCM-SHA384:\
+TLS-ECDH-RSA-WITH-CAMELLIA-128-GCM-SHA256:\
+TLS-ECDH-RSA-WITH-CAMELLIA-256-GCM-SHA384:\
+TLS-ECDH-ECDSA-WITH-AES-128-GCM-SHA256:\
+TLS-ECDH-ECDSA-WITH-AES-256-GCM-SHA384:\
+TLS-ECDH-ECDSA-WITH-CAMELLIA-128-GCM-SHA256:\
+TLS-ECDH-ECDSA-WITH-CAMELLIA-256-GCM-SHA384
+ </screen>
+ <screen>
+ # Explicitly set a couple of ciphers with names used by OpenSSL
+cipher-list ECDHE-RSA-AES256-GCM-SHA384:\
+ECDHE-ECDSA-AES256-GCM-SHA384:\
+DH-DSS-AES256-GCM-SHA384:\
+DHE-DSS-AES256-GCM-SHA384:\
+DH-RSA-AES256-GCM-SHA384:\
+DHE-RSA-AES256-GCM-SHA384:\
+ECDH-RSA-AES256-GCM-SHA384:\
+ECDH-ECDSA-AES256-GCM-SHA384:\
+ECDHE-RSA-AES128-GCM-SHA256:\
+ECDHE-ECDSA-AES128-GCM-SHA256:\
+DH-DSS-AES128-GCM-SHA256:\
+DHE-DSS-AES128-GCM-SHA256:\
+DH-RSA-AES128-GCM-SHA256:\
+DHE-RSA-AES128-GCM-SHA256:\
+ECDH-RSA-AES128-GCM-SHA256:\
+ECDH-ECDSA-AES128-GCM-SHA256:\
+ECDHE-RSA-AES256-GCM-SHA384:\
+AES128-SHA
+ </screen>
+ <screen>
+ # Use keywords instead of explicity naming the ciphers (Does not work with MbedTLS)
+ cipher-list ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
+ </screen>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="trusted-cas-file"><title>trusted-cas-file</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
<para>
- Client-specific tags allow Privoxy admins to create different
- profiles and let the users chose which one they want without
- impacting other users.
+ The trusted CAs file in ".pem" format.
</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
<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.
+ File name relative to ca-directory
</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>trustedCAs.pem</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
<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="#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!
+ Default value is used.
</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
<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.
+ This directive specifies the trusted CAs file that is used when validating
+ certificates for intercepted TLS/SSL requests.
</para>
<para>
- Clients can request tags to be set by using the CGI interface <ulink
- url="http://config.privoxy.org/show-client-tags">http://config.privoxy.org/show-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.
+ An example file can be downloaded from
+ <ulink url="https://curl.haxx.se/ca/cacert.pem">https://curl.haxx.se/ca/cacert.pem</ulink>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</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>
+ trusted-cas-file trusted_cas_file.pem
</para>
</listitem>
</varlistentry>
</variablelist>
+<![%config-file;[<literallayout>@@#trusted-cas-file trustedCAs.pem</literallayout>]]>
</sect3>
-</sect2>
-
<!-- ~ End section ~ -->
+</sect2>
<!-- ~~~~~ New section ~~~~~ -->
<![%config-file;[<literallayout>@@#activity-animation 1</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>activity-animation 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="log-messages">
<![%config-file;[<literallayout>@@#log-messages 1</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>log-messages 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="log-buffer-size">
<![%config-file;[<literallayout>@@#log-buffer-size 1</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>log-buffer-size 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="log-max-lines">
<![%config-file;[<literallayout>@@#log-max-lines 200</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>log-max-lines 200</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="log-highlight-messages">
<![%config-file;[<literallayout>@@#log-highlight-messages 1</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>log-highlight-messages 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="log-font-name">
<![%config-file;[<literallayout>@@#log-font-name Comic Sans MS</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>log-font-name Comic Sans MS</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="log-font-size">
<![%config-file;[<literallayout>@@#log-font-size 8</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>log-font-size 8</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="show-on-task-bar">
<![%config-file;[<literallayout>@@#show-on-task-bar 0</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>show-on-task-bar 0</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="close-button-minimizes">
<![%config-file;[<literallayout>@@#close-button-minimizes 1</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>close-button-minimizes 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="hide-console">
<![%config-file;[<literallayout>@@#hide-console</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
#<emphasis>hide-console</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
</sect2>
projects / privoxy.git / blobdiff