Purpose : Used with other docs and files only.
- Copyright (C) 2001-2021 Privoxy Developers https://www.privoxy.org/
+ Copyright (C) 2001-2023 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
Sample Configuration File for Privoxy &p-version;
</title>
<para>
-Copyright (C) 2001-2021 Privoxy Developers https://www.privoxy.org/
+Copyright (C) 2001-2023 Privoxy Developers https://www.privoxy.org/
</para>
<literallayout>
4. ACCESS CONTROL AND SECURITY #
5. FORWARDING #
6. MISCELLANEOUS #
- 7. HTTPS INSPECTION (EXPERIMENTAL) #
+ 7. HTTPS INSPECTION #
8. WINDOWS GUI OPTIONS #
#
##################################################################
<para>
Unix, in local filesystem (may not work with all browsers):
</para>
- <screen> user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/</screen>
+ <screen>user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/</screen>
<para>
Windows, in local filesystem, <emphasis>must</emphasis> use forward slash notation:
</para>
- <screen> user-manual file:/c:/some-dir/privoxy-&p-version;/user-manual/</screen>
+ <screen>user-manual file:/c:/some-dir/privoxy-&p-version;/user-manual/</screen>
<para>
Windows, UNC notation (with forward slashes):
</para>
- <screen> user-manual file://///some-server/some-path/privoxy-&p-version;/user-manual/</screen>
+ <screen>user-manual file://///some-server/some-path/privoxy-&p-version;/user-manual/</screen>
-->
<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>
- <screen> user-manual /usr/share/doc/privoxy/user-manual</screen>
+ <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>
- <screen> user-manual http://example.com/privoxy/user-manual/</screen>
+ <screen>user-manual http://example.com/privoxy/user-manual/</screen>
<![%user-man;[
<!-- this gets hammered in conversion to config. Text repeated below. -->
<warning>
<term>Notes:</term>
<listitem>
<para>
- The value of this option only matters if the experimental trust mechanism has been
+ The value of this option only matters if the trust mechanism has been
activated. (See <link linkend="trustfile"><emphasis>trustfile</emphasis></link> below.)
</para>
<para>
fk 2007-11-07
-->
<![%config-file;[<literallayout>@@actionsfile user.action # User customizations</literallayout>]]>
-<![%config-file;[<literallayout>@@#regression-tests.action # Tests for privoxy-regression-test</literallayout>]]>
+<![%config-file;[<literallayout>@@#actionsfile regression-tests.action # Tests for privoxy-regression-test</literallayout>]]>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
The available debug levels are:
</para>
<programlisting>
- debug 1 # Log the destination for each request. See also debug 1024.
- debug 2 # show each connection status
- debug 4 # show tagging-related messages
- debug 8 # show header parsing
- debug 16 # log all data written to the network
- debug 32 # debug force feature
- debug 64 # debug regular expression filters
- debug 128 # debug redirects
- debug 256 # debug GIF de-animation
- debug 512 # Common Log Format
- debug 1024 # Log the destination for requests &my-app; didn't let through, and the reason why.
- debug 2048 # CGI user interface
- debug 4096 # Startup banner and warnings.
- debug 8192 # Non-fatal errors
- debug 32768 # log all data read from the network
- debug 65536 # Log the applying actions
+debug 1 # Log the destination for each request. See also debug 1024.
+debug 2 # show each connection status
+debug 4 # show tagging-related messages
+debug 8 # show header parsing
+debug 16 # log all data written to the network
+debug 32 # debug force feature
+debug 64 # debug regular expression filters
+debug 128 # debug redirects
+debug 256 # debug GIF de-animation
+debug 512 # Common Log Format
+debug 1024 # Log the destination for requests &my-app; didn't let through, and the reason why.
+debug 2048 # CGI user interface
+debug 4096 # Startup banner and warnings.
+debug 8192 # Non-fatal errors
+debug 32768 # log all data read from the network
+debug 65536 # Log the applying actions
</programlisting>
<para>
To select multiple debug levels, you can either add them or use
as it happens. <emphasis>1, 1024, 4096 and 8192 are recommended</emphasis>
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).
+ They can produce a lot of output (especially 16).
</para>
<para>
If you are used to the more verbose settings, simply enable the debug lines
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@#debug 1 # Log the destination for each request &my-app; let through.</literallayout>]]>
+<![%config-file;[<literallayout>@@#debug 1 # Log the destination for each request. See also debug 1024.</literallayout>]]>
+<![%config-file;[<literallayout>@@#debug 2 # show each connection status</literallayout>]]>
+<![%config-file;[<literallayout>@@#debug 4 # show tagging-related messages</literallayout>]]>
+<![%config-file;[<literallayout>@@#debug 8 # show header parsing</literallayout>]]>
+<![%config-file;[<literallayout>@@#debug 128 # debug redirects</literallayout>]]>
+<![%config-file;[<literallayout>@@#debug 256 # debug GIF de-animation</literallayout>]]>
+<![%config-file;[<literallayout>@@#debug 512 # Common Log Format</literallayout>]]>
<![%config-file;[<literallayout>@@#debug 1024 # Log the destination for requests &my-app; didn't let through, and the reason why.</literallayout>]]>
<![%config-file;[<literallayout>@@#debug 4096 # Startup banner and warnings</literallayout>]]>
<![%config-file;[<literallayout>@@#debug 8192 # Non-fatal errors</literallayout>]]>
+<![%config-file;[<literallayout>@@#debug 65536 # Log applying actions</literallayout>]]>
</sect3>
(ACL's, see below), and/or a firewall.
</para>
<para>
- If you open <application>Privoxy</application> to untrusted users, you will
- also want to make sure that the following actions are disabled: <literal><link
+ If you open <application>Privoxy</application> to untrusted users, you should
+ also make sure that the following actions are disabled: <literal><link
linkend="enable-edit-actions">enable-edit-actions</link></literal> and
<literal><link linkend="enable-remote-toggle">enable-remote-toggle</link></literal>
</para>
You want it to serve requests from inside only:
</para>
<programlisting>
- listen-address 192.168.0.1:8118
+listen-address 192.168.0.1:8118
</programlisting>
<para>
Suppose you are running <application>Privoxy</application> on an
of the loopback device:
</para>
<programlisting>
- listen-address [::1]:8118
+listen-address [::1]:8118
</programlisting>
</listitem>
</varlistentry>
<emphasis>all</emphasis> destination addresses are OK:
</para>
<screen>
- permit-access localhost
+permit-access localhost
</screen>
<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>
<screen>
- permit-access www.privoxy.org/24 www.example.com/32
+permit-access www.privoxy.org/24 www.example.com/32
</screen>
<para>
Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
www.dirty-stuff.example.com:
</para>
<screen>
- permit-access 192.168.45.64/26
- deny-access 192.168.45.73 www.dirty-stuff.example.com
+permit-access 192.168.45.64/26
+deny-access 192.168.45.73 www.dirty-stuff.example.com
</screen>
<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>
<programlisting>
- permit-access 192.0.2.0/24
+permit-access 192.0.2.0/24
</programlisting>
<para>
This is equivalent to the following line even if listening on an
IPv4 address (not supported on all platforms):
</para>
<programlisting>
- permit-access [::ffff:192.0.2.0]/120
+permit-access [::ffff:192.0.2.0]/120
</programlisting>
</listitem>
</varlistentry>
Everything goes to an example parent proxy, except SSL on port 443 (which it doesn't handle):
</para>
<screen>
- forward / parent-proxy.example.org:8080
- forward :443 .
+forward / parent-proxy.example.org:8080
+forward :443 .
</screen>
<para>
Everything goes to our example ISP's caching proxy, except for requests
to that ISP's sites:
</para>
<screen>
- forward / caching-proxy.isp.example.net:8000
- forward .isp.example.net .
+forward / caching-proxy.isp.example.net:8000
+forward .isp.example.net .
</screen>
<para>
Parent proxy specified by an IPv6 address:
</para>
<programlisting>
- forward / [2001:DB8::1]:8000
+forward / [2001:DB8::1]:8000
</programlisting>
<para>
Suppose your parent proxy doesn't support IPv6:
</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]:*> .
+forward / parent-proxy.example.org:8000
+forward ipv6-server.example.org .
+forward <[2-3][0-9a-f][0-9a-f][0-9a-f]:*> .
</programlisting>
</listitem>
</varlistentry>
the Internet.
</para>
<screen>
- forward-socks4a / socks-gw.example.com:1080 www-cache.isp.example.net:8080
- forward .example.com .
+forward-socks4a / socks-gw.example.com:1080 www-cache.isp.example.net:8080
+forward .example.com .
</screen>
<para>
A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
</para>
<screen>
- forward-socks4 / socks-gw.example.com:1080 .
+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 .
+forward-socks5 / user:pass@socks-gw.example.com:1080 .
</screen>
<para>
something like:
</para>
<screen>
- forward-socks5t / 127.0.0.1:9050 .
+forward-socks5t / 127.0.0.1:9050 .
</screen>
<para>
Note that if you got Tor through one of the bundles, you may
therefore might want to make some exceptions:
</para>
<screen>
- forward 192.168.*.*/ .
- forward 10.*.*.*/ .
- forward 127.*.*.*/ .
+forward 192.168.*.*/ .
+forward 10.*.*.*/ .
+forward 127.*.*.*/ .
</screen>
<para>
Unencrypted connections to systems in these address ranges will
this:
</para>
<screen>
- forward localhost/ .
+forward localhost/ .
</screen>
</listitem>
host-a:
</para>
- <screen>
- forward / .
- forward .isp-b.example.net host-b:8118
+<screen>
+forward / .
+forward .isp-b.example.net host-b:8118
</screen>
<para>
host-b:
</para>
- <screen>
- forward / .
- forward .isp-a.example.org host-a:8118
+<screen>
+forward / .
+forward .isp-a.example.org host-a:8118
</screen>
<para>
run on the same box, your <application>squid</application> configuration could then look like this:
</para>
- <screen>
- # Define Privoxy as parent proxy (without ICP)
- cache_peer 127.0.0.1 parent 8118 7 no-query
+<screen>
+# Define Privoxy as parent proxy (without ICP)
+cache_peer 127.0.0.1 parent 8118 7 no-query
- # Define ACL for protocol FTP
- acl ftp proto FTP
+# Define ACL for protocol FTP
+acl ftp proto FTP
- # Do not forward FTP requests to Privoxy
- always_direct allow ftp
+# Do not forward FTP requests to Privoxy
+always_direct allow ftp
- # Forward all the rest to Privoxy
- never_direct allow all</screen>
+# Forward all the rest to Privoxy
+never_direct allow all
+</screen>
<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>
- <screen>
- forward / .
- forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010</screen>
+<screen>
+forward / .
+forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010
+</screen>
</sect3>
]]>
There are also a few privacy implications you should be aware of.
</para>
<para>
- If this option is effective, outgoing connections are shared between
+ If this option is enabled, outgoing connections are shared between
clients (if there are more than one) and closing the browser that initiated
- the outgoing connection does no longer affect the connection between &my-app;
+ the outgoing connection does not affect the connection between &my-app;
and the server unless the client's request hasn't been completed yet.
</para>
<para>
If you aren't using an occasionally slow proxy like Tor, reducing
it to a few seconds should be fine.
</para>
+ <warning>
+ <para>
+ When a TLS library is being used to read or write data from a socket with
+ <literal><ulink url="actions-file.html#HTTPS-INSPECTION">https-inspection</ulink></literal>
+ enabled the socket-timeout currently isn't applied and the timeout
+ used depends on the library (which may not even use a timeout).
+ </para>
+ </warning>
</listitem>
</varlistentry>
<varlistentry>
</listitem>
</varlistentry>
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Notes:</term>
<listitem>
<para>
Connections are served until a resource limit is reached.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
<para>
&my-app; creates one thread (or process) for every incoming client
connection that isn't rejected based on the access control settings.
</para>
<para>
One most POSIX-compliant systems &my-app; can't properly deal with
- more than FD_SETSIZE file descriptors at the same time and has to reject
- connections if the limit is reached. This will likely change in a
- future version, but currently this limit can't be increased without
- recompiling &my-app; with a different FD_SETSIZE limit.
+ more than FD_SETSIZE file descriptors if &my-app; has been configured
+ to use select() and has to reject connections if the limit is reached.
+ When using select() this limit therefore can't be increased without
+ recompiling &my-app; with a different FD_SETSIZE limit unless &my-app;
+ is running on Windows with _WIN32 defined.
+ </para>
+ <para>
+ When &my-app; has been configured to use poll() the FD_SETSIZE limit
+ does not apply.
</para>
</listitem>
</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
+# 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>
Cookie \
DNT \
Connection \
+ Pragma \
Upgrade-Insecure-Requests \
If-Modified-Since \
Cache-Control \
<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
- client-specific-tag overrule-redirects Overrule redirect sections
- client-specific-tag allow-cookies Do not crunch cookies in either direction
- client-specific-tag change-tor-socks-port Change forward-socks5 settings to use a different Tor socks port (and circuits)
- client-specific-tag no-https-inspection Disable HTTPS inspection
- client-specific-tag no-tls-verification Don't verify certificates when http-inspection is enabled
+ # 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
+ client-specific-tag overrule-redirects Overrule redirect sections
+ client-specific-tag allow-cookies Do not crunch cookies in either direction
+ client-specific-tag change-tor-socks-port Change forward-socks5 settings to use a different Tor socks port (and circuits)
+ client-specific-tag no-https-inspection Disable HTTPS inspection
+ client-specific-tag no-tls-verification Don't verify certificates when http-inspection is enabled
</screen>
</listitem>
</varlistentry>
<term>Example:</term>
<listitem>
<screen>
- # Increase the time to life for temporarily enabled tags to 3 minutes
- client-tag-lifetime 180
+ # Increase the time to life for temporarily enabled tags to 3 minutes
+ client-tag-lifetime 180
</screen>
</listitem>
</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
+ # 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>
<term>Example:</term>
<listitem>
<screen>
- # Increase the receive buffer size
- receive-buffer-size 32768
+ # Increase the receive buffer size
+ receive-buffer-size 32768
</screen>
</listitem>
</varlistentry>
<sect2 id="https-inspection-directives">
-<title>HTTPS Inspection (Experimental)</title>
+<title>HTTPS Inspection</title>
<para>
HTTPS inspection allows to filter encrypted requests and responses.
<varlistentry>
<term>Default value:</term>
<listitem>
- <para><emphasis>Empty string</emphasis></para>
+ <para><emphasis>./CA</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
The <ulink url="#CA-CERT-FILE">ca-cert-file section</ulink> contains
a command to generate it.
</para>
+ <para>
+ The CA key is used by &my-app; to sign generated certificates.
+ </para>
<para>
Access to the key should be limited to Privoxy.
</para>
that is used when Privoxy generates certificates for intercepted
requests.
</para>
+ <warning>
<para>
Note that the password is shown on the CGI page so don't
reuse an important one.
</para>
+ <para>
+ If disclosure of the password is a compliance issue consider blocking
+ the relevant CGI requests after enabling the <link linkend="enforce-blocks">enforce-blocks</link>
+ and <link linkend="allow-cgi-request-crunching">allow-cgi-request-crunching</link>.
+ </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:\
+ # 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-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>
<screen>
- # Explicitly set a couple of ciphers with names used by OpenSSL
+ # 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:\
ECDH-ECDSA-AES128-GCM-SHA256:\
ECDHE-RSA-AES256-GCM-SHA384:\
AES128-SHA
- </screen>
+</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>
+ # 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>
projects / privoxy.git / blobdiff