X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fp-config.sgml;h=e9e8310f94d0e7cd9bc7b854a4901cdd39ea0ba5;hb=4a39c88bb798b039e2db687ec49b85af1c67f233;hp=380ae510ace91acc5b2b38daa77b3a6587aa42e9;hpb=08ca69772a966f4315f5c8fd43dfd34c3def1965;p=privoxy.git
diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml
index 380ae510..e9e8310f 100644
--- a/doc/source/p-config.sgml
+++ b/doc/source/p-config.sgml
@@ -1,11 +1,9 @@
+
+##################################################################
+ #
+ 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
+ ===============
+
This file holds Privoxy's main configuration. Privoxy detects
@@ -229,7 +219,7 @@ II. FORMAT OF THE CONFIGURATION FILE
Effect if unset:
- http://www.privoxy.org/version/user-manual/
+ https://www.privoxy.org/version/user-manual/
will be used, where version is the Privoxy version.
@@ -251,30 +241,22 @@ II. FORMAT OF THE CONFIGURATION FILE
Unix, in local filesystem (may not work with all browsers):
- user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/
-
Windows, in local filesystem, must use forward slash notation:
- user-manual file:/c:/some-dir/privoxy-&p-version;/user-manual/
-
Windows, UNC notation (with forward slashes):
- user-manual file://///some-server/some-path/privoxy-&p-version;/user-manual/
-
-->
The best all purpose solution is simply to put the full local
PATH to where the User Manual is
located:
-
- user-manual /usr/share/doc/privoxy/user-manual
-
+ user-manual /usr/share/doc/privoxy/user-manual
The User Manual is then available to anyone with access to
Privoxy, by following the built-in URL:
@@ -285,9 +267,7 @@ II. FORMAT OF THE CONFIGURATION FILE
If the documentation is not on the local system, it can be accessed
from a remote server, as:
-
- user-manual http://example.com/privoxy/user-manual/
-
+ user-manual http://example.com/privoxy/user-manual/
@@ -316,7 +296,7 @@ II. FORMAT OF THE CONFIGURATION FILE
-@@#user-manual http://www.privoxy.org/user-manual/]]>
+@@#user-manual https://www.privoxy.org/user-manual/]]>
@@ -743,13 +723,6 @@ actionsfile
Actions files contain all the per site and per URL configuration for
ad blocking, cookie management, privacy considerations, etc.
- There is no point in using Privoxy without at
- least one actions file.
-
-
- Note that since Privoxy 3.0.7, the complete filename, including the .action
- extension has to be specified. The syntax change was necessary to be consistent
- with the other file options and to allow previously forbidden characters.
@@ -886,22 +859,22 @@ actionsfile
Depending on the debug options below, the logfile may be a privacy risk
if third parties can get access to it. As most users will never look
- at it, Privoxy 3.0.7 and later only log fatal
- errors by default.
+ at it, Privoxy only logs fatal errors by default.
For most troubleshooting purposes, you will have to change that,
please refer to the debugging section for details.
-
- Your logfile will grow indefinitely, and you will probably want to
- periodically remove it. On Unix systems, you can do this with a cron job
- (see man cron).
-
Any log files must be writable by whatever user Privoxy
is being run as (on Unix, default user id is privoxy).
+
+ To prevent the logfile from growing indefinitely, it is recommended to
+ periodically rotate or shorten it. Many operating systems support log
+ rotation out of the box, some require additional software to do it.
+ For details, please refer to the documentation for your operating system.
+
@@ -1042,9 +1015,8 @@ actionsfile
The available debug levels are:
-
- 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
@@ -1061,7 +1033,6 @@ actionsfile
debug 32768 # log all data read from the network
debug 65536 # Log the applying actions
-
To select multiple debug levels, you can either add them or use
multiple debug lines.
@@ -1072,12 +1043,6 @@ actionsfile
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).
-
-
-
- &my-app; used to ship with the debug levels recommended above enabled by
- default, but due to privacy concerns 3.0.7 and later are configured to
- only log fatal errors.
If you are used to the more verbose settings, simply enable the debug lines
@@ -1295,6 +1260,9 @@ actionsfile
If the specified address isn't available on the system, or if the
hostname can't be resolved, Privoxy
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
IPv6 addresses containing colons have to be quoted by brackets.
@@ -1342,21 +1310,17 @@ actionsfile
(192.168.0.0) and has another outside connection with a different address.
You want it to serve requests from inside only:
-
listen-address 192.168.0.1:8118
-
Suppose you are running Privoxy on an
IPv6-capable machine and you want it to listen on the IPv6 address
of the loopback device:
-
listen-address [::1]:8118
-
@@ -1666,7 +1630,7 @@ actionsfile
- Examples:
+ Example:
enforce-blocks 1
@@ -1713,7 +1677,7 @@ ACLs: permit-access and deny-access
If your system implements
RFC 3493, then
src_addr and dst_addr can be IPv6 addresses delimeted by
+ class="parameter">dst_addr can be IPv6 addresses delimited by
brackets, port can be a number
or a service name, and
src_masklen and
@@ -1803,49 +1767,39 @@ ACLs: permit-access and deny-access
is OK. The absence of a dst_addr implies that
all destination addresses are OK:
-
permit-access localhost
-
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):
-
permit-access www.privoxy.org/24 www.example.com/32
-
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:
-
permit-access 192.168.45.64/26
deny-access 192.168.45.73 www.dirty-stuff.example.com
-
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):
-
permit-access 192.0.2.0/24
-
This is equivalent to the following line even if listening on an
IPv4 address (not supported on all platforms):
-
permit-access [::ffff:192.0.2.0]/120
-
@@ -1971,6 +1925,155 @@ ACLs: permit-access and deny-access
@@enable-proxy-authentication-forwarding 0]]>
+
+trusted-cgi-referer
+
+
+ Specifies:
+
+
+ A trusted website or webpage whose links can be followed to reach sensitive CGI pages
+
+
+
+
+ Type of value:
+
+ URL or URL prefix
+
+
+
+ Default value:
+
+ Unset
+
+
+
+ Effect if unset:
+
+
+ No external pages are considered trusted referers.
+
+
+
+
+ Notes:
+
+
+ Before &my-app; accepts configuration changes through CGI pages like
+ client-tags or the
+ remote toggle, it checks
+ the Referer header to see if the request comes from a trusted source.
+
+
+ By default only the webinterface domains
+ config.privoxy.org
+ and
+ p.p
+ 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.
+
+
+ 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.
+
+
+ The trusted-cgi-referer 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.
+
+
+ If the trusted source is supposed to access the CGI pages via
+ JavaScript the cors-allowed-origin
+ option can be used.
+
+
+
+ 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.
+
+
+
+
+
+
+@@#trusted-cgi-referer http://www.example.org/local-privoxy-control-page]]>
+
+
+
+
+cors-allowed-origin
+
+
+ Specifies:
+
+
+ A trusted website which can access &my-app;'s CGI pages through JavaScript.
+
+
+
+
+ Type of value:
+
+ URL
+
+
+
+ Default value:
+
+ Unset
+
+
+
+ Effect if unset:
+
+
+ No external sites get access via cross-origin resource sharing.
+
+
+
+
+ Notes:
+
+
+ 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
+ trusted-cgi-referer
+ directive.
+
+
+ Cross-origin resource sharing (CORS) is a mechanism to allow
+ cross-origin requests.
+
+
+ The cors-allowed-origin 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
+ trusted-cgi-referer
+ directive.
+
+
+
+ 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.
+
+
+
+
+
+
+@@#cors-allowed-origin http://www.example.org/]]>
+
+
@@ -2075,40 +2178,32 @@ ACLs: permit-access and deny-access
Everything goes to an example parent proxy, except SSL on port 443 (which it doesn't handle):
-
forward / parent-proxy.example.org:8080
forward :443 .
-
Everything goes to our example ISP's caching proxy, except for requests
to that ISP's sites:
-
forward / caching-proxy.isp.example.net:8000
forward .isp.example.net .
-
Parent proxy specified by an IPv6 address:
-
forward / [2001:DB8::1]:8000
-
Suppose your parent proxy doesn't support IPv6:
-
forward / parent-proxy.example.org:8000
forward ipv6-server.example.org .
forward <[2-3][0-9a-f][0-9a-f][0-9a-f]:*> .
-
@@ -2135,7 +2230,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
target_pattern
- socks_proxy[:port]
+ [user:pass@]socks_proxy[:port]
http_parent[:port]
@@ -2148,7 +2243,8 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
(http_parent
may be . to denote no HTTP forwarding), and the optional
port parameters are TCP ports,
- i.e. integer values from 1 to 65535
+ i.e. integer values from 1 to 65535. user and
+ pass can be used for SOCKS5 authentication if required.
@@ -2213,43 +2309,47 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
the Internet.
-
forward-socks4a / socks-gw.example.com:1080 www-cache.isp.example.net:8080
forward .example.com .
-
A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
-
forward-socks4 / socks-gw.example.com:1080 .
+
+
+ To connect SOCKS5 proxy which requires username/password authentication:
+
+ forward-socks5 / user:pass@socks-gw.example.com:1080 .
+
To chain Privoxy and Tor, both running on the same system, you would use
something like:
-
forward-socks5t / 127.0.0.1:9050 .
+
+ Note that if you got Tor through one of the bundles, you may
+ have to change the port from 9050 to 9150 (or even another one).
+ For details, please check the documentation on the
+ Tor website.
-
-
+
The public Tor network can't be used to
reach your local network, if you need to access local servers you
therefore might want to make some exceptions:
-
forward 192.168.*.*/ .
- forward 10.*.*.*/ .
- forward 127.*.*.*/ .
+ forward 10.*.*.*/ .
+ forward 127.*.*.*/ .
-
Unencrypted connections to systems in these address ranges will
be as (un)secure as the local network is, but the alternative is that you
@@ -2262,11 +2362,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
using their names, you will need additional exceptions that look like
this:
-
forward localhost/ .
-
@@ -2294,23 +2392,19 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
host-a:
-
forward / .
forward .isp-b.example.net host-b:8118
-
host-b:
-
forward / .
forward .isp-a.example.org host-a:8118
-
Now, your users can set their browser's proxy to use either
@@ -2329,7 +2423,6 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
run on the same box, your squid configuration could then look like this:
-
# Define Privoxy as parent proxy (without ICP)
cache_peer 127.0.0.1 parent 8118 7 no-query
@@ -2342,7 +2435,6 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
# Forward all the rest to Privoxy
never_direct allow all
-
You would then need to change your browser's proxy settings to squid's address and port.
@@ -2355,11 +2447,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
say, on antivir.example.com, port 8010:
-
forward / .
forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010
-
]]>
@@ -2418,7 +2508,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
forwarded-connect-retries 1
@@ -2486,10 +2576,16 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Privoxy's listening port is reachable
by the outside or an attacker has access to the pages you visit.
+
+ 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.
+
- Examples:
+ Example:
accept-intercepted-requests 1
@@ -2547,7 +2643,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
allow-cgi-request-crunching 1
@@ -2614,7 +2710,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
split-large-forms 1
@@ -2697,7 +2793,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
keep-alive-timeout 300
@@ -2766,7 +2862,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
tolerate-pipelining 1
@@ -2847,7 +2943,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
default-server-timeout 60
@@ -2855,7 +2951,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
-@@#default-server-timeout 60]]>
+@@#default-server-timeout 5]]>
@@ -2946,7 +3042,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
connection-sharing 1
@@ -3002,7 +3098,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
socket-timeout 300
@@ -3090,7 +3186,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
max-client-connections 256
@@ -3102,15 +3198,13 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
-handle-as-empty-doc-returns-ok
+listen-backlogSpecifies:
- The status code Privoxy returns for pages blocked with
-
- +handle-as-empty-document.
+ Connection queue length requested from the operating system.
@@ -3118,61 +3212,78 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Type of value:
- 0 or 1
+ Number.Default value:
- 0
+ 128Effect if unset:
- Privoxy returns a status 403(forbidden) for all blocked pages.
+ A connection queue length of 128 is requested from the operating system.
- Effect if set:
+ Notes:
- 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.
+
+
+ Increasing the queue length allows Privoxy to accept more
+ incoming connections that arrive roughly at the same time.
+
+
+ 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.
+
+
+ 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.
+
+
+ On some platforms you can use "netstat -Lan -p tcp" to see the effective
+ queue length.
+
+
+ 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.
- Notes:
+ Example:
- This directive was added as a work-around for Firefox bug 492459:
-
- Websites are no longer rendered if SSL requests for JavaScripts are blocked by a proxy.
-
- (https://bugzilla.mozilla.org/show_bug.cgi?id=492459),
- 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
-@@#handle-as-empty-doc-returns-ok 1]]>
+@@#listen-backlog -1]]>
-enable-compression
+enable-accept-filterSpecifies:
- Whether or not buffered content is compressed before delivery.
+ Whether or not Privoxy should use an accept filter
@@ -3194,50 +3305,58 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Effect if unset:
- Privoxy does not compress buffered content.
+ No accept filter is enabled.
- Effect if set:
+ Notes:
- 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.
-
-
-
- Notes:
-
- 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.
- 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).
- Privoxy will not compress buffered content below a certain length.
+ Currently accept filters are only supported on FreeBSD-based
+ systems. Check the
+ accf_http(9)
+ man page
+ to learn how to enable the support in the operating system.
+
+
+
+
+ Example:
+
+
+ enable-accept-filter 1
-@@#enable-compression 1]]>
+@@#enable-accept-filter 1]]>
-compression-level
+handle-as-empty-doc-returns-okSpecifies:
- The compression level that is passed to the zlib library when compressing buffered content.
+ The status code Privoxy returns for pages blocked with
+
+ +handle-as-empty-document.
@@ -3245,7 +3364,132 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Type of value:
- Positive number ranging from 0 to 9.
+ 0 or 1
+
+
+
+
+ Default value:
+
+ 0
+
+
+
+ Effect if unset:
+
+
+ Privoxy returns a status 403(forbidden) for all blocked pages.
+
+
+
+
+ Effect if set:
+
+
+ Privoxy returns a status 200(OK) for pages blocked with +handle-as-empty-document
+ and a status 403(Forbidden) for all other blocked pages.
+
+
+
+
+ Notes:
+
+
+ This directive was added as a work-around for Firefox bug 492459:
+ Websites are no longer rendered if SSL requests for JavaScripts are blocked by a proxy.
+ (
+ https://bugzilla.mozilla.org/show_bug.cgi?id=492459),
+ 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.
+
+
+
+
+@@#handle-as-empty-doc-returns-ok 1]]>
+
+
+
+enable-compression
+
+
+ Specifies:
+
+
+ Whether or not buffered content is compressed before delivery.
+
+
+
+
+ Type of value:
+
+
+ 0 or 1
+
+
+
+
+ Default value:
+
+ 0
+
+
+
+ Effect if unset:
+
+
+ Privoxy does not compress buffered content.
+
+
+
+
+ Effect if set:
+
+
+ Privoxy compresses buffered content before delivering it to the client,
+ provided the client supports it.
+
+
+
+
+ Notes:
+
+
+ This directive is only supported if Privoxy has been compiled with
+ FEATURE_COMPRESSION, which should not to be confused with FEATURE_ZLIB.
+
+
+ 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.
+
+
+ Privoxy will not compress buffered content below a certain length.
+
+
+
+
+@@#enable-compression 1]]>
+
+
+
+compression-level
+
+
+ Specifies:
+
+
+ The compression level that is passed to the zlib library when compressing buffered content.
+
+
+
+
+ Type of value:
+
+
+ Positive number ranging from 0 to 9.
@@ -3259,48 +3503,674 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Notes:
- 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.
+ 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.
+
+
+ If compression is disabled, the compression level is irrelevant.
+
+
+
+
+ Examples:
+
+
+ # 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
+
+
+
+
+@@#compression-level 1]]>
+
+
+
+client-header-order
+
+
+ Specifies:
+
+
+ The order in which client headers are sorted before forwarding them.
+
+
+
+
+ Type of value:
+
+
+ Client header names delimited by spaces or tabs
+
+
+
+
+ Default value:
+
+ None
+
+
+
+ Notes:
+
+
+ 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.
+
+
+ The header order can be used to fingerprint client requests
+ independently of other headers like the User-Agent.
+
+
+ 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.
+
+
+ Note that sorting headers in an uncommon way will make fingerprinting
+ actually easier. Encrypted headers are not affected by this directive.
+
+
+
+
+@@#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
+]]>
+
+
+
+client-specific-tag
+
+
+ Specifies:
+
+
+ The name of a tag that will always be set for clients that
+ requested it through the webinterface.
+
+
+
+
+ Type of value:
+
+
+ Tag name followed by a description that will be shown in the webinterface
+
+
+
+
+ Default value:
+
+ None
+
+
+
+ Notes:
+
+
+
+ This is an experimental feature. The syntax is likely to change
+ in future versions.
+
+
+
+ Client-specific tags allow Privoxy admins to create different
+ profiles and let the users chose which one they want without
+ impacting other users.
+
+
+ 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
+ enable-remote-toggle feature
+ 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.
+
+
+ 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
+ CLIENT-TAG 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!
+
+
+ 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.
+
+
+ Clients can request tags to be set by using the CGI interface http://config.privoxy.org/client-tags.
+ 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.
+
+
+
+
+ Examples:
+
+
+ # 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-tag-lifetime
+
+
+ Specifies:
+
+
+ How long a temporarily enabled tag remains enabled.
+
+
+
+
+ Type of value:
+
+
+ Time in seconds.
+
+
+
+
+ Default value:
+
+ 60
+
+
+
+ Notes:
+
+
+
+ This is an experimental feature. The syntax is likely to change
+ in future versions.
+
+
+
+ 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.
+
+
+ The CGI interface http://config.privoxy.org/client-tags
+ therefore provides a "enable this tag temporarily" option.
+ If it is used, the tag will be set until the client-tag-lifetime
+ is over.
+
+
+
+
+ Example:
+
+
+ # Increase the time to life for temporarily enabled tags to 3 minutes
+ client-tag-lifetime 180
+
+
+
+
+
+
+
+
+trust-x-forwarded-for
+
+
+ Specifies:
+
+
+ Whether or not Privoxy should use IP addresses specified with the X-Forwarded-For header
+
+
+
+
+ Type of value:
+
+
+ 0 or one
+
+
+
+
+ Default value:
+
+ 0
+
+
+
+ Notes:
+
+
+
+ This is an experimental feature. The syntax is likely to change
+ in future versions.
+
+
+
+ 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.
+
+
+ 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.
+
+
+ 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.
+
+
+ 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.
+
+
+
+
+ Example:
+
+
+ # Allow systems that can reach Privoxy to provide the client
+ # IP address with a X-Forwarded-For header.
+ trust-x-forwarded-for 1
+
+
+
+
+
+
+
+
+
+
+receive-buffer-size
+
+
+ Specifies:
+
+
+ The size of the buffer Privoxy uses to receive data from the server.
+
+
+
+
+ Type of value:
+
+
+ Size in bytes
+
+
+
+
+ Default value:
+
+ 5000
+
+
+
+ Notes:
+
+
+ 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.
+
+
+ This is mostly relevant for fast network connections and
+ large downloads that don't require filtering.
+
+
+ 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.
+
+
+ A dtrace command like:
+ sudo dtrace -n 'syscall::read:return /execname == "privoxy"/ { @[execname] = llquantize(arg0, 10, 0, 5, 20); @m = max(arg0)}'
+ can be used to properly tune the receive-buffer-size.
+ On systems without dtrace, strace or truss may be used as
+ less convenient alternatives.
+
+
+ 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.
+
+
+
+
+ Example:
+
+
+ # Increase the receive buffer size
+ receive-buffer-size 32768
+
+
+
+
+
+
+
+
+
+
+
+
+HTTPS Inspection (Experimental)
+
+
+ HTTPS inspection allows to filter encrypted requests.
+ This is only supported when Privoxy
+ has been built with FEATURE_HTTPS_INSPECTION.
+
+
+
+
+ca-directory
+
+
+ Specifies:
+
+
+ Directory with the CA key, the CA certificate and the trusted CAs file.
+
+
+
+
+ Type of value:
+
+
+ Text
+
+
+
+
+ Default value:
+
+ Empty string
+
+
+
+ Effect if unset:
+
+
+ Default value is used.
+
+
+
+
+ Notes:
+
+
+ This directive specifies the directory where the
+ CA key, the CA certificate and the trusted CAs file
+ are located.
+
+
+ The permissions should only let &my-app; and the &my-app;
+ admin access the directory.
+
+
+
+
+ Example:
+
+
+ ca-directory /usr/local/etc/privoxy/CA
+
+
+
+
+@@#ca-directory /usr/local/etc/privoxy/CA]]>
+
+
+
+
+
+
+ca-cert-file
+
+
+ Specifies:
+
+
+ The CA certificate file in ".crt" format.
+
+
+
+
+ Type of value:
+
+
+ Text
+
+
+
+
+ Default value:
+
+ cacert.crt
+
+
+
+ Effect if unset:
+
+
+ Default value is used.
+
+
+
+
+ Notes:
+
+
+ This directive specifies the name of the CA certificate file
+ in ".crt" format.
+
+
+ The file is used by &my-app; to generate website certificates
+ when https inspection is enabled with the
+ https-inspection
+ action.
+
+
+ &my-app; clients should import the certificate so that they
+ can validate the generated certificates.
+
+
+ The file can be generated with:
+ openssl req -new -x509 -extensions v3_ca -keyout cakey.pem -out cacert.crt -days 3650
+
+
+
+
+ Example:
+
+
+ ca-cert-file root.crt
+
+
+
+
+@@#ca-cert-file cacert.crt]]>
+
+
+
+
+
+
+ca-key-file
+
+
+ Specifies:
+
+
+ The CA key file in ".pem" format.
+
+
+
+
+ Type of value:
+
+
+ Text
+
+
+
+
+ Default value:
+
+ cacert.pem
+
+
+
+ Effect if unset:
+
+
+ Default value is used.
+
+
+
+
+ Notes:
+
+
+ This directive specifies the name of the CA key file
+ in ".pem" format. See the ca-cert-file
+ for a command to generate it.
+
+
+
+ Example:
+
- If compression is disabled, the compression level is irrelevant.
+ ca-key-file cakey.pem
+
+
+
+
+@@#ca-key-file cakey.pem]]>
+
+
+
+
+
+
+ca-password
+
+
+ Specifies:
+
+
+ The password for the CA keyfile.
- Examples:
+ Type of value:
-
- # 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
-
+ Text
+
+
+
+
+ Default value:
+
+ Empty string
+
+
+
+ Effect if unset:
+
+
+ Default value is used.
+
+
+
+
+ Notes:
+
+
+ This directive specifies the password for the CA keyfile
+ that is used when Privoxy generates certificates for intercepted
+ requests.
+
+
+ Note that the password is shown on the CGI page so don't
+ reuse an important one.
+
+
+
+
+ Example:
+
+
+ ca-password blafasel
-@@#compression-level 1]]>
+@@#ca-password swordfish]]>
+
+
+
-client-header-order
+certificate-directorySpecifies:
- The order in which client headers are sorted before forwarding them.
+ Directory to save generated keys and certificates.
@@ -3308,62 +4178,259 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Type of value:
- Client header names delimited by spaces or tabs
+ Text
Default value:
- None
+ ./certs
+
+
+
+ Effect if unset:
+
+
+ Default value is used.
+ Notes:
- 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 directory where generated
+ TLS/SSL keys and certificates are saved when https inspection
+ is enabled with the
+ https-inspection
+ action.
- The header order can be used to fingerprint client requests
- independently of other headers like the User-Agent.
+ The keys and certificates currently have to be deleted manually
+ when changing the ca-cert-file
+ and the ca-cert-key.
- 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.
+ The permissions should only let &my-app; and the &my-app;
+ admin access the directory.
+
+
+ &my-app; currently does not garbage-collect obsolete keys
+ and certificates and does not keep track of how may keys
+ and certificates exist.
+
+
+ &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.
+
+
+
+
+
+ Example:
+
- Note that sorting headers in an uncommon way will make fingerprinting
- actually easier. Encrypted headers are not affected by this directive.
+ certificate-directory /usr/local/var/privoxy/certs
-@@#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
-]]>
+@@#certificate-directory /usr/local/var/privoxy/certs]]>
+
+
+
-
+cipher-list
+
+
+ Specifies:
+
+
+ A list of ciphers to use in TLS handshakes
+
+
+
+
+ Type of value:
+
+
+ Text
+
+
+
+
+ Default value:
+
+ None
+
+
+
+ Effect if unset:
+
+
+ A default value is inherited from the TLS library.
+
+
+
+
+ Notes:
+
+
+ This directive allows to specify a non-default list of ciphers to use
+ in TLS handshakes with clients and servers.
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+
+
+ Examples:
+
+
+ # 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
+
+
+ # 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
+
+
+ # Use keywords instead of explicitly naming the ciphers (Does not work with MbedTLS)
+ cipher-list ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
+
+
+
+
+
+
+
+
+
+
+trusted-cas-file
+
+
+ Specifies:
+
+
+ The trusted CAs file in ".pem" format.
+
+
+
+
+ Type of value:
+
+
+ File name relative to ca-directory
+
+
+
+
+ Default value:
+
+ trustedCAs.pem
+
+
+
+ Effect if unset:
+
+
+ Default value is used.
+
+
+
+
+ Notes:
+
+
+ This directive specifies the trusted CAs file that is used when validating
+ certificates for intercepted TLS/SSL requests.
+
+
+ An example file can be downloaded from
+ https://curl.haxx.se/ca/cacert.pem.
+
+
+
+
+ Example:
+
+
+ trusted-cas-file trusted_cas_file.pem
+
+
+
+
+@@#trusted-cas-file trustedCAs.pem]]>
+
+
@@ -3384,15 +4451,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#activity-animation 1]]>
-
- activity-animation 1
-
-
-
-
+
]]>
@@ -3406,15 +4467,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#log-messages 1]]>
-
- log-messages 1
-
-
-
-
+
]]>
@@ -3432,15 +4487,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#log-buffer-size 1]]>
-
- log-buffer-size 1
-
-
-
-
+
]]>
@@ -3452,15 +4501,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#log-max-lines 200]]>
-
- log-max-lines 200
-
-
-
-
+
]]>
@@ -3473,15 +4516,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#log-highlight-messages 1]]>
-
- log-highlight-messages 1
-
-
-
-
+
]]>
@@ -3492,15 +4529,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#log-font-name Comic Sans MS]]>
-
- log-font-name Comic Sans MS
-
-
-
-
+
]]>
@@ -3511,15 +4542,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#log-font-size 8]]>
-
- log-font-size 8
-
-
-
-
+
]]>
@@ -3532,15 +4557,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#show-on-task-bar 0]]>
-
- show-on-task-bar 0
-
-
-
-
+
]]>
@@ -3553,15 +4572,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#close-button-minimizes 1]]>
-
- close-button-minimizes 1
-
-
-
-
+
]]>
@@ -3575,15 +4588,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#hide-console]]>
-
-
#hide-console
-
-
-
-
+
]]>