X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fp-config.sgml;h=8223117d61b1d8ca8b9a8027dc2cc53ccf6ec8eb;hb=86f4ed42c5c2314ecbc5b765374c2c4e23a18bd6;hp=617dd0b8ed29c6d65aefb2bec1e55da921b68a1b;hpb=e44a50f4c135a068c5b0333ad832fdfc134587bd;p=privoxy.git diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml index 617dd0b8..8223117d 100644 --- a/doc/source/p-config.sgml +++ b/doc/source/p-config.sgml @@ -3,9 +3,9 @@ Purpose : Used with other docs and files only. - $Id: p-config.sgml,v 1.1.2.3 2002/05/31 02:56:25 hal9 Exp $ + $Id: p-config.sgml,v 2.8 2006/09/06 02:17:53 hal9 Exp $ - Copyright (C) 2001, 2002 Privoxy Developers + Copyright (C) 2001-2006 Privoxy Developers See LICENSE. ======================================================================== @@ -95,10 +95,10 @@ Sample Configuration File for Privoxy v&p-version; -Copyright (C) 2001, 2002 Privoxy Developers http://privoxy.org + $Id: p-config.sgml,v 2.8 2006/09/06 02:17:53 hal9 Exp $ -$Id: p-config.sgml,v 1.1.2.3 2002/05/31 02:56:25 hal9 Exp $ +Copyright (C) 2001-2006 Privoxy Developers http://privoxy.org @@ -126,7 +126,7 @@ $Id: p-config.sgml,v 1.1.2.3 2002/05/31 02:56:25 hal9 Exp $ This file holds the Privoxy configuration. If you modify this - file, you will need to send a couple of requests to the proxy + file, you will need to send a couple of requests (of any kind) to the proxy before any changes take effect. @@ -376,7 +376,7 @@ actionsfile Specifies: - The filter file to use + The filter file(s) to use @@ -406,30 +406,38 @@ actionsfile Notes: - The filter file contains content modification + Multiple filterfile lines are permitted. + + + The filter files contain content modification rules that use regular expressions. These rules permit - powerful changes on the content of Web pages, e.g., you could disable your favorite - JavaScript annoyances, re-write the actual displayed text, or just have some - fun replacing Microsoft with MicroSuck wherever - it appears on a Web page. + powerful changes on the content of Web pages, and optionally the headers + as well, e.g., you could disable your favorite JavaScript annoyances, + re-write the actual displayed text, or just have some fun + playing buzzword bingo with web pages. The +filter{name} actions rely on the relevant filter (name) - to be defined in the filter file! + to be defined in a filter file! A pre-defined filter file called default.filter that contains - a bunch of handy filters for common problems is included in the distribution. + a number of useful filters for common problems is included in the distribution. See the section on the filter action for a list. + + It is recommended to place any locally adapted filters into a separate + file, such as user.filter. + @@filterfile default.filter]]> +@@#filterfile user.filter # User customizations]]> @@ -468,9 +476,13 @@ actionsfile Notes: + The logfile is where all logging and error messages are written. The level of detail and number of messages are set with the debug @@ -523,14 +535,14 @@ actionsfile Default value: - jarfile (Unix) or privoxy.jar (Windows) + Unset (commented out). When activated: jarfile (Unix) or privoxy.jar (Windows) Effect if unset: - Intercepted cookies are not stored at all. + Intercepted cookies are not stored in a dedicated log file. @@ -540,11 +552,15 @@ actionsfile The jarfile may grow to ridiculous sizes over time. + + If debug 8 (show header parsing) is enabled, cookies are + written to the logfile with the rest of the headers. + -@@jarfile jarfile]]> +@@#jarfile jarfile]]> @@ -575,7 +591,7 @@ actionsfile Effect if unset: - The whole trust mechanism is turned off. + The entire trust mechanism is turned off. @@ -588,16 +604,37 @@ actionsfile If you specify a trust file, Privoxy will only allow - access to sites that are named in the trustfile. - You can also mark sites as trusted referrers (with +), with - the effect that access to untrusted sites will be granted, if a link from a - trusted referrer was used. - The link target will then be added to the trustfile. - Possible applications include limiting Internet access for children. + access to sites that are specified in the trustfile. Sites can be listed + in one of two ways: + + + Prepending a ~ character limits access to this site + only (and any sub-paths within this site), e.g. + ~www.example.com. - If you use + operator in the trust file, it may grow considerably over time. + Or, you can designate sites as trusted referrers, by + prepending the name with a + character. The effect is that + access to untrusted sites will be granted -- but only if a link from this + trusted referrer was used. The link target will then be added to the + trustfile so that future, direct accesses will be granted. + Sites added via this mechanism do not become trusted referrers themselves + (i.e. they are added with a ~ designation). + + If you use the + operator in the trust file, it may grow + considerably over time. + + + It is recommended that Privoxy be compiled with + the --disable-force, --disable-toggle and + --disable-editor options, if this feature is to be + used. + + + Possible applications include limiting Internet access for children. + + @@ -668,13 +705,25 @@ actionsfile Unix, in local filesystem: - 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/ + + + Windows, UNC notation (with forward slashes): + + +   user-manual  file://///some-server/some-path/privoxy-&p-version;/user-manual/ Any platform, on local webserver (called local-webserver): - user-manual  http://local-webserver/privoxy-user-manual/ +   user-manual  http://local-webserver/privoxy-user-manual/ @@ -928,6 +977,7 @@ actionsfile debug 256 # debug GIF de-animation debug 512 # Common Log Format debug 1024 # debug kill pop-ups + debug 2048 # CGI user interface debug 4096 # Startup banner and warnings. debug 8192 # Non-fatal errors @@ -958,7 +1008,7 @@ actionsfile @@debug 1 # show each GET/POST/CONNECT request]]> @@debug 4096 # Startup banner and warnings]]> -@@debug 8192 # Errors - *we highly recommended enabling this]]> +@@debug 8192 # Errors - *we highly recommended enabling this*]]> @@ -1225,6 +1275,60 @@ actionsfile + +enable-remote-http-toggle + + + Specifies: + + + Whether or not Privoxy recognizes special HTTP headers to change its behaviour. + + + + + Type of value: + + 0 or 1 + + + + Default value: + + 1 + + + + Effect if unset: + + + Privoxy ignores special HTTP headers. + + + + + Notes: + + + When toggled on, the client can change Privoxy's + behaviour by setting special HTTP headers. Currently the only supported + special header is X-Filter: No, to disable filtering for + the ongoing request, even if it is enabled in one of the action files. + + + If you are using Privoxy in a + multi-user environment or with untrustworthy clients and want to + enforce filtering, you will have to disable this option, + otherwise you can ignore it. + + + + + +@@enable-remote-http-toggle 1]]> + + + enable-edit-actions @@ -1507,17 +1611,17 @@ ACLs: permit-access and deny-access Type of value: - target_domain[:port] - http_parent[/port] + target_pattern + http_parent[:port] - Where target_domain is a domain name pattern (see the - chapter on domain matching in the default.action file), - http_parent is the address of the parent HTTP proxy - as an IP addresses in dotted decimal notation or as a valid DNS name (or . to denote - no forwarding, and the optional - port parameters are TCP ports, i.e. integer - values from 1 to 64535 + where target_pattern is a URL pattern + that specifies to which requests (i.e. URLs) this forward rule shall apply. Use / to + denote all URLs. + http_parent[:port] + is the DNS name or IP address of the parent HTTP proxy through which the requests should be forwarded, + optionally followed by its listening port (default: 8080). + Use a single dot (.) to denote no forwarding. @@ -1555,7 +1659,7 @@ ACLs: permit-access and deny-access - forward .* anon-proxy.example.org:8080 + forward / anon-proxy.example.org:8080 forward :443 . @@ -1565,7 +1669,7 @@ ACLs: permit-access and deny-access - forward .*. caching-proxy.example-isp.net:8000 + forward / caching-proxy.example-isp.net:8000 forward .example-isp.net . @@ -1594,13 +1698,14 @@ forward-socks4 and forward-socks4a Type of value: - target_domain[:port] - socks_proxy[/port] - http_parent[/port] + target_pattern + socks_proxy[:port] + http_parent[:port] - Where target_domain is a domain name pattern (see the - chapter on domain matching in the default.action file), + where target_pattern is a URL pattern + that specifies to which requests (i.e. URLs) this forward rule shall apply. Use / to + denote all URLs. http_parent and socks_proxy are IP addresses in dotted decimal notation or valid DNS names (http_parent may be . to denote no HTTP forwarding), and the optional @@ -1651,7 +1756,7 @@ forward-socks4 and forward-socks4a - forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080 + forward-socks4a / socks-gw.example.com:1080 www-cache.example-isp.net:8080 forward .example.com . @@ -1660,9 +1765,47 @@ forward-socks4 and forward-socks4a - forward-socks4 .*. socks-gw.example.com:1080 . + forward-socks4 / socks-gw.example.com:1080 . + + + To chain Privoxy and Tor, both running on the same system, you should use + the rule: + + + + forward-socks4 / 127.0.0.1:9050 . + + + + + The public Tor network can't be used to reach your local network, + therefore it's a good idea to make some exceptions: + + + + forward 192.168.*.*/ . + 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 + can't reach the network at all. + + + If you also want to be able to reach servers in your local network by + using their names, you will need additional exceptions that look like + this: + + + + forward localhost/ . + + + @@ -1691,7 +1834,7 @@ forward-socks4 and forward-socks4a - forward .*. . + forward / . forward .isp-b.net host-b:8118 @@ -1702,7 +1845,7 @@ forward-socks4 and forward-socks4a - forward .*. . + forward / . forward .isp-a.net host-a:8118 @@ -1744,9 +1887,81 @@ forward-socks4 and forward-socks4a Squid normally uses port 3128. If unsure consult http_port in squid.conf. + + You could just as well decide to only forward requests for Windows executables through + a virus-scanning parent proxy, say, on antivir.example.com, port 8010: + + + + + forward / . + forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010 + + ]]> +forwarded-connect-retries + + + Specifies: + + + How often Privoxy retries if a forwarded connection request fails. + + + + + Type of value: + + + Number of retries. + + + + + Default value: + + 0 + + + + Effect if unset: + + + Forwarded connections are treated like direct connections and no retry attempts are made. + + + + + Notes: + + + forwarded-connect-retries is mainly interesting + for socks4a connections, where Privoxy can't detect why the connections failed. + The connection might have failed because of a DNS timeout in which case a retry makes sense, + but it might also have failed because the server doesn't exist or isn't reachable. In this + case the retry will just delay the appearance of Privoxy's error message. + + + Only use this option, if you are getting many forwarding related error messages, + that go away when you try again manually. Start with a small value and check Privoxy's + logfile from time to time, to see how many retries are usually needed. + + + + + Examples: + + + forwarded-connect-retries 1 + + + + +@@forwarded-connect-retries 0]]> + + @@ -1978,14 +2193,15 @@ forward-socks4 and forward-socks4a - + + + ]]>