Purpose : Used with other docs and files only.
- Copyright (C) 2001-2019 Privoxy Developers https://www.privoxy.org/
+ Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
Sample Configuration File for Privoxy &p-version;
</title>
<para>
-Copyright (C) 2001-2019 Privoxy Developers https://www.privoxy.org/
+Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/
</para>
<literallayout>
4. ACCESS CONTROL AND SECURITY #
5. FORWARDING #
6. MISCELLANEOUS #
- 7. WINDOWS GUI OPTIONS #
+ 7. HTTPS INSPECTION (EXPERIMENTAL) #
+ 8. WINDOWS GUI OPTIONS #
#
##################################################################
The available debug levels are:
</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
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.
</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
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
forwarded-connect-retries 1
</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
<listitem>
<para>
Under high load incoming connection may queue up before Privoxy
- gets around to serve them. The queue length is limitted by the
+ 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
- incomming connections that arrive roughly at the same time.
+ incoming connections that arrive roughly at the same time.
</para>
<para>
Note that Privoxy can only request a certain queue length,
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
listen-backlog 4096
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<para>
enable-accept-filter 1
# 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
+ client-specific-tag disable-content-filters Disable content-filters but do not affect other actions
</screen>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<screen>
# Increase the time to life for temporarily enabled tags to 3 minutes
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<screen>
# Allow systems that can reach Privoxy to provide the client
</listitem>
</varlistentry>
<varlistentry>
- <term>Examples:</term>
+ <term>Example:</term>
<listitem>
<screen>
# Increase the receive buffer size
</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:
+ <command>openssl req -new -x509 -extensions v3_ca -keyout cakey.pem -out cacert.crt -days 3650</command>
+ </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>Default value:</term>
+ <listitem>
+ <para><emphasis>cacert.pem</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 key file in ".pem" format.
+ The <ulink url="#CA-CERT-FILE">ca-cert-file section</ulink> contains
+ 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>@@#ca-key-file cakey.pem</literallayout>]]>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="ca-password"><title>ca-password</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The password for the CA keyfile.
+ </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 password for the CA keyfile
+ that is used when Privoxy generates certificates for intercepted
+ requests.
+ </para>
+ <para>
+ 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>
+ Directory to save generated keys and certificates.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ 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>@@#certificate-directory /usr/local/var/privoxy/certs</literallayout>]]>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="cipher-list"><title>cipher-list</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ A list of ciphers to use in TLS handshakes
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ Text
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <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>
+ <para>
+ 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 explicitly 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>
+ The trusted CAs file in ".pem" format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ 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>
+ Default value is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This directive specifies the trusted CAs file that is used when validating
+ certificates for intercepted TLS/SSL requests.
+ </para>
+ <para>
+ 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>Example:</term>
+ <listitem>
+ <para>
+ trusted-cas-file trusted_cas_file.pem
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#trusted-cas-file trustedCAs.pem</literallayout>]]>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+</sect2>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="windows-gui">