X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fp-config.sgml;h=042400ef0c0e848f13ea141a086f2d9fee799b32;hb=e994f44d9c5a0c61bf6b824720be67476d4487ed;hp=e9e8310f94d0e7cd9bc7b854a4901cdd39ea0ba5;hpb=53704ce1e734b0cbcf86ee262c8e38c0c3b2651c;p=privoxy.git
diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml
index e9e8310f..042400ef 100644
--- a/doc/source/p-config.sgml
+++ b/doc/source/p-config.sgml
@@ -3,7 +3,7 @@
Purpose : Used with other docs and files only.
- Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/
+ Copyright (C) 2001-2021 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
@@ -90,7 +90,7 @@
Sample Configuration File for Privoxy &p-version;
-Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/
+Copyright (C) 2001-2021 Privoxy Developers https://www.privoxy.org/
@@ -241,22 +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/
+ 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/
+ 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/
+ 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:
@@ -267,7 +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/
@@ -738,6 +738,7 @@ actionsfile
fk 2007-11-07
-->
@@actionsfile user.action # User customizations]]>
+@@#actionsfile regression-tests.action # Tests for privoxy-regression-test]]>
@@ -1016,22 +1017,22 @@ actionsfile
The available debug levels are:
- 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 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
To select multiple debug levels, you can either add them or use
@@ -1042,7 +1043,7 @@ actionsfile
as it happens. 1, 1024, 4096 and 8192 are recommended
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).
If you are used to the more verbose settings, simply enable the debug lines
@@ -1066,7 +1067,7 @@ actionsfile
-@@#debug 1 # Log the destination for each request &my-app; let through.]]>
+@@#debug 1 # Log the destination for each request. See also debug 1024.]]>
@@#debug 1024 # Log the destination for requests &my-app; didn't let through, and the reason why.]]>
@@#debug 4096 # Startup banner and warnings]]>
@@#debug 8192 # Non-fatal errors]]>
@@ -1269,7 +1270,7 @@ actionsfile
They can only be used if Privoxy has
been compiled with IPv6 support. If you aren't sure if your version
supports it, have a look at
- http://config.privoxy.org/show-status.
+ http://config.privoxy.org/show-status.
Some operating systems will prefer IPv6 to IPv4 addresses even if the
@@ -1294,8 +1295,8 @@ actionsfile
(ACL's, see below), and/or a firewall.
- If you open Privoxy to untrusted users, you will
- also want to make sure that the following actions are disabled: Privoxy to untrusted users, you should
+ also make sure that the following actions are disabled: enable-edit-actions and
enable-remote-toggle
@@ -1311,7 +1312,7 @@ actionsfile
You want it to serve requests from inside only:
- listen-address 192.168.0.1:8118
+listen-address 192.168.0.1:8118
Suppose you are running Privoxy on an
@@ -1319,7 +1320,7 @@ actionsfile
of the loopback device:
- listen-address [::1]:8118
+listen-address [::1]:8118
@@ -1768,14 +1769,14 @@ ACLs: permit-access and deny-access
all destination addresses are OK:
- permit-access localhost
+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
+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,
@@ -1783,22 +1784,22 @@ ACLs: permit-access and deny-access
www.dirty-stuff.example.com:
- 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
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
+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
+permit-access [::ffff:192.0.2.0]/120
@@ -2179,30 +2180,30 @@ 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 .
+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 .
+forward / caching-proxy.isp.example.net:8000
+forward .isp.example.net .
Parent proxy specified by an IPv6 address:
- forward / [2001:DB8::1]:8000
+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]:*> .
+forward / parent-proxy.example.org:8000
+forward ipv6-server.example.org .
+forward <[2-3][0-9a-f][0-9a-f][0-9a-f]:*> .
@@ -2310,21 +2311,21 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
the Internet.
- 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 .
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 .
+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 .
+forward-socks5 / user:pass@socks-gw.example.com:1080 .
@@ -2332,7 +2333,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
something like:
- forward-socks5t / 127.0.0.1:9050 .
+forward-socks5t / 127.0.0.1:9050 .
Note that if you got Tor through one of the bundles, you may
@@ -2346,9 +2347,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
therefore might want to make some exceptions:
- forward 192.168.*.*/ .
- forward 10.*.*.*/ .
- forward 127.*.*.*/ .
+forward 192.168.*.*/ .
+forward 10.*.*.*/ .
+forward 127.*.*.*/ .
Unencrypted connections to systems in these address ranges will
@@ -2363,7 +2364,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
this:
- forward localhost/ .
+forward localhost/ .
@@ -2392,18 +2393,18 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
host-a:
-
- forward / .
- forward .isp-b.example.net host-b:8118
+
+forward / .
+forward .isp-b.example.net host-b:8118
host-b:
-
- forward / .
- forward .isp-a.example.org host-a:8118
+
+forward / .
+forward .isp-a.example.org host-a:8118
@@ -2423,18 +2424,19 @@ 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
+
+# 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
+# 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.
@@ -2447,9 +2449,10 @@ 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
+
+forward / .
+forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010
+
]]>
@@ -3005,9 +3008,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
There are also a few privacy implications you should be aware of.
- 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.
@@ -3095,6 +3098,14 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
If you aren't using an occasionally slow proxy like Tor, reducing
it to a few seconds should be fine.
+
+
+ When a TLS library is being used to read or write data from a socket with
+ https-inspection
+ enabled the socket-timeout currently isn't applied and the timeout
+ used depends on the library (which may not even use a timeout).
+
+
@@ -3135,16 +3146,11 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Effect if unset:
+ Notes:
Connections are served until a resource limit is reached.
-
-
-
- Notes:
-
&my-app; creates one thread (or process) for every incoming client
connection that isn't rejected based on the access control settings.
@@ -3178,10 +3184,15 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
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.
+
+
+ When &my-app; has been configured to use poll() the FD_SETSIZE limit
+ does not apply.
@@ -3518,18 +3529,18 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
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
+# 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
@@ -3582,7 +3593,10 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Note that sorting headers in an uncommon way will make fingerprinting
- actually easier. Encrypted headers are not affected by this directive.
+ actually easier.
+ Encrypted headers are not affected by this directive unless
+ https-inspection
+ is enabled.
@@ -3596,9 +3610,13 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Referer \
Cookie \
DNT \
+ Connection \
+ Pragma \
+ Upgrade-Insecure-Requests \
If-Modified-Since \
Cache-Control \
Content-Length \
+ Origin \
Content-Type
]]>
@@ -3632,12 +3650,6 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
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
@@ -3671,7 +3683,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
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.
+ be phrased in away that the user understands the effect of the tag.
@@ -3679,10 +3691,15 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
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
+ # 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
@@ -3718,12 +3735,6 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
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
@@ -3742,8 +3753,8 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Example:
- # 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
@@ -3779,12 +3790,6 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
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.
@@ -3814,9 +3819,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Example:
- # 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
@@ -3887,8 +3892,8 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Example:
- # Increase the receive buffer size
- receive-buffer-size 32768
+ # Increase the receive buffer size
+ receive-buffer-size 32768
@@ -3904,9 +3909,11 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
HTTPS Inspection (Experimental)
- HTTPS inspection allows to filter encrypted requests.
+ HTTPS inspection allows to filter encrypted requests and responses.
This is only supported when Privoxy
has been built with FEATURE_HTTPS_INSPECTION.
+ If you aren't sure if your version supports it, have a look at
+ http://config.privoxy.org/show-status.
@@ -4024,7 +4031,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
The file can be generated with:
- openssl req -new -x509 -extensions v3_ca -keyout cakey.pem -out cacert.crt -days 3650
+ openssl req -new -x509 -extensions v3_ca -keyout cakey.pem -out cacert.crt -days 3650
@@ -4080,9 +4087,15 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
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.
+ This directive specifies the name of the CA key file in ".pem" format.
+ The ca-cert-file section contains
+ a command to generate it.
+
+
+ The CA key is used by &my-app; to sign generated certificates.
+
+
+ Access to the key should be limited to Privoxy.
@@ -4304,8 +4317,8 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Examples:
- # 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:\
@@ -4336,9 +4349,9 @@ 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
+ # 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:\
@@ -4357,11 +4370,11 @@ 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
-
+ # Use keywords instead of explicitly naming the ciphers (Does not work with MbedTLS)
+cipher-list ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
+
@@ -4412,7 +4425,9 @@ AES128-SHA
An example file can be downloaded from
- https://curl.haxx.se/ca/cacert.pem.
+ https://curl.se/ca/cacert.pem.
+ If you want to create the file yourself, please see:
+ https://curl.se/docs/caextract.html.