X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fp-config.sgml;h=f5bc81f66f6715d6c3eed48196ccb4b08292573a;hp=d509c42ffd850b344bbd9cff7836dee92566a9f6;hb=4634f728955847bfb053f6a887bc13fb230cecb0;hpb=65e01393b77af2ab94844cb13efb3d5e321f1254
diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml
index d509c42f..f5bc81f6 100644
--- a/doc/source/p-config.sgml
+++ b/doc/source/p-config.sgml
@@ -1,11 +1,9 @@
+
+I. INTRODUCTION
+ ===============
+
This file holds Privoxy's main configuration. Privoxy detects
@@ -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/
@@ -1035,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
@@ -1054,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.
@@ -1282,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.
@@ -1329,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
-
@@ -1700,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
@@ -1790,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
-
@@ -2020,6 +1987,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
@@ -2031,7 +2003,75 @@ ACLs: permit-access and deny-access
-@@trusted-cgi-referer http://www.example.org/local-privoxy-control-page]]>
+@@#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/]]>
@@ -2138,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]:*> .
-
@@ -2198,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]
@@ -2211,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.
@@ -2276,30 +2309,31 @@ 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).
@@ -2311,13 +2345,11 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
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
@@ -2330,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/ .
-
@@ -2362,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
@@ -2397,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
@@ -2410,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.
@@ -2423,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
-
]]>
@@ -2929,7 +2951,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
-@@#default-server-timeout 60]]>
+@@#default-server-timeout 5]]>
@@ -3213,13 +3235,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,
@@ -3375,8 +3397,8 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
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),
+ (
+ 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.
@@ -3495,20 +3517,20 @@ 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
-
-
+
@@ -3656,14 +3678,12 @@ 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
- 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
+
@@ -3721,12 +3741,10 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Examples:
-
# Increase the time to life for temporarily enabled tags to 3 minutes
client-tag-lifetime 180
-
-
+
@@ -3795,13 +3813,11 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Examples:
-
# Allow systems that can reach Privoxy to provide the client
# IP address with a X-Forwarded-For header.
trust-x-forwarded-for 1
-
-
+
@@ -3870,15 +3886,402 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
Examples:
-
# Increase the receive buffer size
receive-buffer-size 32768
-
+
+
+
+
+
+
+
+
+
+
+
+
+TLS/SSL Inspection (Experimental)
+
+
+
+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.
+
+
+
+
+ Examples:
+
+
+ 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
+
+
+
+
+ Examples:
+
+
+ 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.
+
+
+
+
+ Examples:
+
+
+ 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.
+
+
+
+
+ Examples:
+
+
+ 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.
+
+
+
+
+ Examples:
+
+
+ certificate-directory /usr/local/var/privoxy/certs
+
+
+
+
+@@#certificate-directory /usr/local/var/privoxy/certs]]>
+
+
+
+
+
+
+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.
+
+
+
+
+ Examples:
+
+
+ trusted-cas-file trusted_cas_file.pem
+
+
+
+
+@@#trusted-cas-file trustedCAs.pem]]>
@@ -3904,15 +4307,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#activity-animation 1]]>
-
- activity-animation 1
-
-
-
-
+
]]>
@@ -3926,15 +4323,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#log-messages 1]]>
-
- log-messages 1
-
-
-
-
+
]]>
@@ -3952,15 +4343,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#log-buffer-size 1]]>
-
- log-buffer-size 1
-
-
-
-
+
]]>
@@ -3972,15 +4357,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#log-max-lines 200]]>
-
- log-max-lines 200
-
-
-
-
+
]]>
@@ -3993,15 +4372,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#log-highlight-messages 1]]>
-
- log-highlight-messages 1
-
-
-
-
+
]]>
@@ -4012,15 +4385,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#log-font-name Comic Sans MS]]>
-
- log-font-name Comic Sans MS
-
-
-
-
+
]]>
@@ -4031,15 +4398,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#log-font-size 8]]>
-
- log-font-size 8
-
-
-
-
+
]]>
@@ -4052,15 +4413,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#show-on-task-bar 0]]>
-
- show-on-task-bar 0
-
-
-
-
+
]]>
@@ -4073,15 +4428,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#close-button-minimizes 1]]>
-
- close-button-minimizes 1
-
-
-
-
+
]]>
@@ -4095,15 +4444,9 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t
@@#hide-console]]>
-
-
#hide-console
-
-
-
-
+
]]>