X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fp-config.sgml;h=b5c8500f64415dbd7a808b5581b3e445690a52ef;hp=ba974539df0f024aa0f5ff820acf2c48fbdb9e14;hb=f2be4cfb0e98db4cf6fcf33f3f1efadabe399887;hpb=3f47e92cd5ade006b4911f98d0f24e61048075e6
diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml
index ba974539..b5c8500f 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-2018 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-2018 Privoxy Developers https://www.privoxy.org/
+Copyright (C) 2001-2021 Privoxy Developers https://www.privoxy.org/
@@ -107,7 +107,8 @@ Copyright (C) 2001-2018 Privoxy Developers https://www.privoxy.org/
4. ACCESS CONTROL AND SECURITY #
5. FORWARDING #
6. MISCELLANEOUS #
- 7. WINDOWS GUI OPTIONS #
+ 7. HTTPS INSPECTION (EXPERIMENTAL) #
+ 8. WINDOWS GUI OPTIONS #
#
##################################################################
@@ -737,6 +738,7 @@ actionsfile
fk 2007-11-07
-->
@@actionsfile user.action # User customizations]]>
+@@#regression-tests.action # Tests for privoxy-regression-test]]>
@@ -1015,9 +1017,9 @@ 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 4 # show tagging-related messages
debug 8 # show header parsing
debug 16 # log all data written to the network
debug 32 # debug force feature
@@ -1259,13 +1261,16 @@ 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.
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
@@ -1626,7 +1631,7 @@ actionsfile
- Examples:
+ Example:
enforce-blocks 1
@@ -1673,7 +1678,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
@@ -1983,6 +1988,11 @@ ACLs: permit-access and deny-access
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
@@ -1997,6 +2007,74 @@ ACLs: permit-access and deny-access
@@#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/]]>
+
+
@@ -2153,7 +2231,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
target_pattern
- socks_proxy[:port]
+ [user:pass@]socks_proxy[:port]
http_parent[:port]
@@ -2166,7 +2244,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.
@@ -2242,6 +2321,13 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
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:
@@ -2423,7 +2509,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
forwarded-connect-retries 1
@@ -2500,7 +2586,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
accept-intercepted-requests 1
@@ -2558,7 +2644,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
allow-cgi-request-crunching 1
@@ -2625,7 +2711,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
split-large-forms 1
@@ -2708,7 +2794,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
keep-alive-timeout 300
@@ -2777,7 +2863,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
tolerate-pipelining 1
@@ -2858,7 +2944,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
default-server-timeout 60
@@ -2866,7 +2952,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
-@@#default-server-timeout 60]]>
+@@#default-server-timeout 5]]>
@@ -2957,7 +3043,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
connection-sharing 1
@@ -3013,7 +3099,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
socket-timeout 300
@@ -3101,7 +3187,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
max-client-connections 256
@@ -3150,13 +3236,13 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
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.
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.
Note that Privoxy can only request a certain queue length,
@@ -3180,7 +3266,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
listen-backlog 4096
@@ -3251,7 +3337,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
enable-accept-filter 1
@@ -3497,7 +3583,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.
@@ -3511,9 +3600,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
]]>
@@ -3547,12 +3640,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
@@ -3586,7 +3673,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.
@@ -3597,7 +3684,12 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
# 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
+ 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
@@ -3633,12 +3725,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
@@ -3654,7 +3740,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
# Increase the time to life for temporarily enabled tags to 3 minutes
@@ -3694,12 +3780,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.
@@ -3726,7 +3806,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
# Allow systems that can reach Privoxy to provide the client
@@ -3799,7 +3879,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
- Examples:
+ Example:
# Increase the receive buffer size
@@ -3814,6 +3894,549 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
+
+
+HTTPS Inspection (Experimental)
+
+
+ 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.
+
+
+
+
+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.
+ 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.
+
+
+
+
+ Example:
+
+
+ ca-key-file cakey.pem
+
+
+
+
+@@#ca-key-file cakey.pem]]>
+
+
+
+
+
+
+ca-password
+
+
+ Specifies:
+
+
+ The password for the CA keyfile.
+
+
+
+
+ Type of value:
+
+
+ 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
+
+
+
+
+@@#ca-password swordfish]]>
+
+
+
+
+
+
+certificate-directory
+
+
+ Specifies:
+
+
+ Directory to save generated keys and certificates.
+
+
+
+
+ Type of value:
+
+
+ Text
+
+
+
+
+ Default value:
+
+ ./certs
+
+
+
+ Effect if unset:
+
+
+ Default value is used.
+
+
+
+
+ Notes:
+
+
+ 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 keys and certificates currently have to be deleted manually
+ when changing the ca-cert-file
+ and the ca-cert-key.
+
+
+ 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:
+
+
+ certificate-directory /usr/local/var/privoxy/certs
+
+
+
+
+@@#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.se/ca/cacert.pem.
+ If you want to create the file yourself, please see:
+ https://curl.se/docs/caextract.html.
+
+
+
+
+ Example:
+
+
+ trusted-cas-file trusted_cas_file.pem
+
+
+
+
+@@#trusted-cas-file trustedCAs.pem]]>
+
+
+
+
+
+