X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fuser-manual%2Fconfig.html;h=7adee4c9993f178168f41592ab16b26d0dc135c6;hp=a25a894814a2e8d137f027ea68b3c578f3c06120;hb=3db7a58b2bbed7b6356b2a0600e93ec4f2846499;hpb=9adfbd2f4dd6acc1d92f00d46d18a16e8dfd5f1b diff --git a/doc/webserver/user-manual/config.html b/doc/webserver/user-manual/config.html index a25a8948..7adee4c9 100644 --- a/doc/webserver/user-manual/config.html +++ b/doc/webserver/user-manual/config.html @@ -1,13 +1,13 @@ +
Again, the main configuration file is named Privoxy's operation that are not location dependent (i.e. they apply universally, no matter - where you may be surfing).
Privoxy can (and normally does) use a number of - other files for additional configuration, help and logging. - This section of the configuration file tells Privoxy - where to find those other files.
7.1. Local Set-up DocumentationThe user running If you intend to operate Privoxy, must have read - permission for all configuration files, and write permission to any files - that would be modified, such as log files and actions files.
for more users + than just yourself, it might be a good idea to let them know how to reach + you, what you block and why you do that, your policies, etc. +The directory where the other configuration files are located
Location of the Privoxy User Manual. +Path name
A fully qualified URI/etc/privoxy (Unix) orUnset Privoxy installation dir (Windows)
http://www.privoxy.org/Mandatory
version/user-manual/ + will be used, where version is the Privoxy version. +No trailing "/", please +> The User Manual URI is the single best source of information on + Privoxy, and is used for help links from some + of the internal CGI pages. The manual itself is normally packaged with the + binary distributions, so you probably want to set this to a locally + installed copy.
When development goes modular and multi-user, the blocker, filter, and - per-user config will be stored in subdirectories of "confdir". - For now, the configuration directory structure is flat, except for - confdir/templates, where the HTML templates for CGI - output reside (e.g. Examples: +
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 |
The User Manual is then available to anyone with access to + Privoxy's 404 error page). +>Privoxy, by following the built-in URL: + http://config.privoxy.org/user-manual/ + (or the shortcut: http://p.p/user-manual/). +
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/ |
Warning |
If set, this option should be the first option in the config + file, because it is used while the config file is being read + on start-up. |
The directory where all logging takes place (i.e. where logfile and - jarfile are located) +> A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
Path name
URL/var/log/privoxy (Unix) orUnset Privoxy installation dir (Windows)
No links are displayed on the "untrusted" error page. +
The value of this option only matters if the experimental trust mechanism has been + activated. (See Mandatorytrustfile
No trailing "/", please +> If you use the trust mechanism, it is a good idea to write up some on-line + documentation about your trust policy and to specify the URL(s) here. + Use multiple times for multiple URLs. +
The URL(s) should be added to the trustfile as well, so users don't end up + locked out from the information on why they were locked out in the first place!
The actions file(s) to use +> An email address to reach the Privoxy administrator.
File name, relative to confdir, without the .action suffix
Email address standard # Internal purposes, no editing recommended - |
default # Main actions file - |
user # User customizations - |
Unset
No actions are taken at all. Simple neutral proxying. +> No email address is displayed on error pages and the CGI user interface.
Multiple If both actionsfile lines are permitted, and are in fact recommended! -
- The default values include standard.action, which is used for internal - purposes and should be loaded, default.action, which is the - "main" actions file maintained by the developers, and - user.action, where you can make your personal additions. -
- Actions files are where all the per site and per URL configuration is done for - ad blocking, cookie management, privacy considerations, etc. - There is no point in using Privoxy without at - least one actions file. +>admin-address and proxy-info-url + are unset, the whole "Local Privoxy Support" box on all generated pages will + not be shown.
The filter file(s) to use +> A URL to documentation about the local Privoxy setup, + configuration or policies.
File name, relative to confdir
URLdefault.filter (Unix) orUnset default.filter.txt (Windows)
No textual content filtering takes place, i.e. all - +filter{name} - actions in the actions files are turned neutral. +> No link to local documentation is displayed on error pages and the CGI user interface.
Multiple filterfiles 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, 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 replacing - "Microsoft" with "MicroSuck" wherever it appears - on a Web page. -
The - If both +filter{name} - actions rely on the relevant filter (name) - to be defined in a filter file! -
A pre-defined filter file called default.filter that contains - a number of useful filters for common problems is included in the distribution. - See the section on the admin-address and filterproxy-info-url - action for a list. + are unset, the whole "Local Privoxy Support" box on all generated pages will + not be shown.
It is recommended to place any locally adapted filters into a separate - file, such as user.filter. +> This URL shouldn't be blocked ;-)
Privoxy can (and normally does) use a number of + other files for additional configuration, help and logging. + This section of the configuration file tells Privoxy + where to find those other files.
The user running Privoxy, must have read + permission for all configuration files, and write permission to any files + that would be modified, such as log files and actions files.
The log file to use -
The directory where the other configuration files are located.File name, relative to logdir
Path namelogfile (Unix) /etc/privoxy (Unix) or privoxy.log (Windows)
Privoxy installation dir (Windows)No log file is used, all log messages go to the console (STDERR). -
MandatoryThe logfile is where all logging and error messages are written. The level - of detail and number of messages are set with the debug - option (see below). The logfile can be useful for tracking down a problem with - Privoxy (e.g., it's not blocking an ad you - think it should block) but in most cases you probably will never look at it. -
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"). For Red Hat, a logrotate - script has been included. -
On SuSE Linux systems, you can place a line like "/var/log/privoxy.* - +1024k 644 nobody.nogroup" in /etc/logfiles, with - the effect that cron.daily will automatically archive, gzip, and empty the - log, when it exceeds 1M size. -
Any log files must be writable by whatever user Privoxy - is being run as (default on UNIX, user id is No trailing "privoxy"). +>"/", please.
The file to store intercepted cookies in -
An alternative directory where the templates are loaded from.File name, relative to logdir
Path namejarfile (Unix) or privoxy.jar (Windows)
unsetIntercepted cookies are not stored at all. -
The templates are assumed to be located in confdir/template.The jarfile may grow to ridiculous sizes over time. +> Privoxy's original templates are usually + overwritten with each update. Use this option to relocate customized + templates that should be kept. As template variables might change + between updates, you shouldn't expect templates to work with + Privoxy releases other than the one + they were part of, though.
The trust file to use +> The directory where all logging takes place + (i.e. where the logfile is located).
File name, relative to confdir
Path name/var/log/privoxy (Unix) Unset (commented out)or. When activated: trust (Unix) Privoxy installation dir (Windows)
orMandatory trust.txt (Windows)
The entire trust mechanism is turned off. +> No trailing "/", please.
The trust mechanism is an experimental feature for building white-lists and should - be used with care. It is NOT recommended for the casual user. +> The actions file(s) to use
If you specify a trust file, Privoxy will only allow - access to sites that are specified in the trustfile. Sites can be listed - in one of two ways: +>Complete file name, relative to confdir
match-all.action # Actions that are applied to all sites and maybe overruled later on. + |
default.action # Main actions file + |
user.action # User customizations + |
No actions are taken at all. More or less neutral proxying.
Prepending a ~ character limits access to this site - only (and any sub-paths within this site), e.g. - Multiple ~www.example.com. +>actionsfile lines are permitted, and are in fact recommended!
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 +> + The default values are default.action, which is 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. +>"main" actions file maintained by the developers, and + user.action, where you can make your personal additions.
It is recommended that + 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 be compiled with - the --disable-force, --disable-toggle and - --disable-editor options, if this feature is to be - used. +> without at + least one actions file.
Possible applications include limiting Internet access for children. +> 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.
If you intend to operate Privoxy for more users - than just yourself, it might be a good idea to let them know how to reach - you, what you block and why you do that, your policies, etc. -
Location of the Privoxy User Manual. +> The filter file(s) to use
A fully qualified URI
File name, relative to confdirdefault.filter (Unix) Unsetor
default.filter.txt (Windows)http://www.privoxy.org/ No textual content filtering takes place, i.e. all + +filter{versionname/user-manual/} - will be used, where version is the Privoxy version. + actions in the actions files are turned neutral.
The User Manual URI is used for help links from some of the internal CGI pages. - The manual itself is normally packaged with the binary distributions, so you probably want - to set this to a locally installed copy. For multi-user setups, you could provide a copy on - a local webserver for all your users and use the corresponding URL here. -
Examples: +> Multiple filterfile lines are permitted.
Unix, in local filesystem: -
user-manual file:///usr/share/doc/privoxy-3.0.4/user-manual/ |
Windows, in local filesystem, The + +filter{must use forward slash notation: -
user-manual file:/c:/some-dir/privoxy-3.0.4/user-manual/ |
Windows, UNC notation (with forward slashes): -
user-manual file://///some-server/some-path/privoxy-3.0.4/user-manual/ |
Any platform, on local webserver (called "local-webserver"): -
name) + to be defined in a filter file! +
user-manual http://local-webserver/privoxy-user-manual/ |
Warning |
If set, this option should be the first option in the config - file, because it is used while the config file is being read. +> It is recommended to place any locally adapted filters into a separate + file, such as user.filter. |
A URL to be displayed in the error page that users will see if access to an untrusted page is denied. +> The log file to use
URL
File name, relative to logdirTwo example URL are provided
Unset (commented out). When activated: logfile (Unix) or privoxy.log (Windows).No links are displayed on the "untrusted" error page. +> No logfile is written.
The value of this option only matters if the experimental trust mechanism has been - activated. (See trustfile above.) +> The logfile is where all logging and error messages are written. The level + of detail and number of messages are set with the debug + option (see below). The logfile can be useful for tracking down a problem with + Privoxy (e.g., it's not blocking an ad you + think it should block) and it can help you to monitor what your browser + is doing.
If you use the trust mechanism, it is a good idea to write up some on-line - documentation about your trust policy and to specify the URL(s) here. - Use multiple times for multiple URLs. +> 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.
The URL(s) should be added to the trustfile as well, so users don't end up - locked out from the information on why they were locked out in the first place! +> 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"). For Red Hat based Linux distributions, a + logrotate script has been included. +
Any log files must be writable by whatever user Privoxy + is being run as (on Unix, default user id is "privoxy").
An email address to reach the proxy administrator. +> The name of the trust file to use
Email address
File name, relative to confdirNo email address is displayed on error pages and the CGI user interface. +> The entire trust mechanism is disabled.
If both The trust mechanism is an experimental feature for building white-lists and should + be used with care. It is NOT recommended for the casual user. +
If you specify a trust file, Privoxy will only allow + access to sites that are specified in the trustfile. Sites can be listed + in one of two ways: +
Prepending a admin-address and ~ character limits access to this site + only (and any sub-paths within this site), e.g. + proxy-info-url - are unset, the whole "Local Privoxy Support" box on all generated pages will - not be shown. -
A URL to documentation about the local Privoxy setup, - configuration or policies. +>~www.example.com allows access to + ~www.example.com/features/news.html, etc.
URL
Or, you can designate sites as Unsettrusted referrers
No link to local documentation is displayed on error pages and the CGI user interface. +> If you use the + operator in the trust file, it may grow + considerably over time.
If both It is recommended that Privoxy be compiled with + the admin-address and --disable-force, proxy-info-url - are unset, the whole "Local Privoxy Support" box on all generated pages will - not be shown. +>--disable-toggle and + --disable-editor options, if this feature is to be + used.
This URL shouldn't be blocked ;-) +> Possible applications include limiting Internet access for children.
These options are mainly useful when tracing a problem. Note that you might also want to invoke @@ -1333,8 +1325,8 @@ CLASS="SECT3" CLASS="SECT3" >7.3.1. debug7.3.1. debug
Key values that determine what information gets logged to the - logfile. +> Key values that determine what information gets logged.
12289 (i.e.: URLs plus informational and warning messages)
0 (i.e.: only fatal errors (that cause Privoxy to exit) are logged)Nothing gets logged. +> Default value is used (see above).
debug 1 # show each GET/POST/CONNECT request - debug 2 # show each connection status - debug 4 # show I/O status - debug 8 # show header parsing - debug 16 # log all data into the logfile - debug 32 # debug force feature - debug 64 # debug regular expression filter - debug 128 # debug fast redirects - 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 errorsdebug 1 # Log the destination for each request Privoxy let through. 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 Privoxy 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
The reporting of fatal errors (i.e. ones which crash - Privoxy) is always on and cannot be disabled. +> 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 want to use CLF (Common Log Format), you should set If you are used to the more verbose settings, simply enable the debug lines + below again. +
If you want to use pure CLF (Common Log Format), you should set "debug 512" and not enable anything else.
Privoxy has a hard-coded limit for the + length of log messages. If it's reached, messages are logged truncated + and marked with "... [too long, truncated]". +
Please don't file any support requests without trying to reproduce + the problem with increased debug level first. Once you read the log + messages, you may even be able to solve the problem on your own. +
7.3.2. single-threaded7.3.2. single-threadedWhether to run only one server thread +> Whether to run only one server thread.
This option is only there for debug purposes and you should never - need to use it. This option is only there for debugging purposes. +
The hostname shown on the CGI pages. +
Text
Unset
The hostname provided by the operating system is used. +
On some misconfigured systems resolving the hostname fails or + takes too much time and slows Privoxy down. Setting a fixed hostname + works around the problem. +
In other circumstances it might be desirable to show a hostname + other than the one returned by the operating system. For example + if the system has several different hostnames and you don't want + to use the first one. +
Note that Privoxy does not validate the specified hostname value. +
This section of the config file controls the security-relevant aspects
of 7.4.1. listen-address7.4.1. listen-address Bind to 127.0.0.1 (localhost), port 8118. This is suitable and recommended for
- home users who run Bind to 127.0.0.1 (IPv4 localhost), port 8118. This is suitable and
+ recommended for home users who run Privoxy on the same machine as
- their browser.
+> on
+ the same machine as their browser.
IPv6 addresses containing colons have to be quoted by brackets.
+ If you leave out the IP address, Privoxy will
- bind to all interfaces (addresses) on your machine and may become reachable
+ bind to all IPv4 interfaces (addresses) on your machine and may become reachable
from the Internet. In that case, consider using access control listsPrivoxy to untrusted users, you will
- also want to turn off the enable-remote-toggle
- options!
Suppose you are running Privoxy on an
+ IPv6-capable machine and you want it to listen on the IPv6 address
+ of the loopback device:
+ The windows version will only display the toggle icon in the system tray
@@ -1760,8 +1846,8 @@ CLASS="SECT3"
CLASS="SECT3"
>7.4.3. enable-remote-toggle7.4.3. enable-remote-toggle 1 For the time being, access to the toggle feature can Access to the toggle feature can Note that malicious client side code (e.g Java) is also
+ capable of using this option.
+ As a lot of Privoxy users don't read
+ documentation, this feature is disabled by default.
+ Note that you must have compiled Privoxy Whether or not the web-based actions
- file editor may be used
+> Whether or not Privoxy recognizes special HTTP headers to change its behaviour.
1 The web-based actions file editor is disabled.
+> Privoxy ignores special HTTP headers.
For the time being, access to the editor can not be
- controlled separately by "ACLs" or HTTP authentication,
- so that everybody who can access When toggled on, the client can change Privoxy (see
- Privoxy's
+ behaviour by setting special HTTP headers. Currently the only supported
+ special header is "ACLs" and listen-address above) can
- modify its configuration for all users. So this option is not
- recommended for multi-user environments with untrusted users.
+>"X-Filter: No", to disable filtering for
+ the ongoing request, even if it is enabled in one of the action files.
Note that you must have compiled This feature is disabled by default. If you are using
+ Privoxy with
- support for this feature, otherwise this option has no effect.
+> in a environment with trusted clients,
+ you may enable this feature at your discretion. Note that malicious client
+ side code (e.g Java) is also capable of using this feature.
This option will be removed in future releases as it has been obsoleted
+ by the more general header taggers.
+ Whether or not the web-based actions
+ file editor may be used
+ 0 or 1 0 The web-based actions file editor is disabled.
+ Access to the editor can not be
+ controlled separately by "ACLs" or HTTP authentication,
+ so that everybody who can access Privoxy (see
+ "ACLs" and listen-address above) can
+ modify its configuration for all users.
+ This option is not recommended for environments
+ with untrusted users and as a lot of Privoxy
+ users don't read documentation, this feature is disabled by default.
+ Note that malicious client side code (e.g Java) is also
+ capable of using the actions editor and you shouldn't enable
+ this options unless you understand the consequences and are
+ sure your browser is configured correctly.
+ Note that you must have compiled Privoxy with
+ support for this feature, otherwise this option has no effect.
+ Whether the user is allowed to ignore blocks and can "go there anyway".
+ 0 or 1
+ 0 Blocks are not enforced.
+ Privoxy is mainly used to block and filter
+ requests as a service to the user, for example to block ads and other
+ junk that clogs the pipes. Privoxy's configuration
+ isn't perfect and sometimes innocent pages are blocked. In this situation it
+ makes sense to allow the user to enforce the request and have
+ Privoxy ignore the block.
+ In the default configuration Privoxy's
+ "Blocked" page contains a "go there anyway"
+ link to adds a special string (the force prefix) to the request URL.
+ If that link is used, Privoxy will
+ detect the force prefix, remove it again and let the request pass.
+ Of course Privoxy can also be used to enforce
+ a network policy. In that case the user obviously should not be able to
+ bypass any blocks, and that's what the "enforce-blocks"
+ option is for. If it's enabled, Privoxy hides
+ the "go there anyway" link. If the user adds the force
+ prefix by hand, it will not be accepted and the circumvention attempt
+ is logged.
+ enforce-blocks 1
+ If your system implements
+ RFC 3493, then
+ src_addr and dst_addr can be IPv6 addresses delimeted by
+ brackets, port can be a number
+ or a service name, and
+ src_masklen and
+ dst_masklen can be a number
+ from 0 to 128.
+ If no port is specified,
+ any port will match. If no src_masklen or
+ src_masklen is given, the complete IP
+ address has to match (i.e. 32 bits for IPv4 and 128 bits for IPv6).
+ Please see the warnings in the FAQ that this proxy is not intended to be a substitute
- for a firewall or to encourage anyone to defer addressing basic security
- weaknesses.
+> Please see the warnings in the FAQ that Privoxy
+ is not intended to be a substitute for a firewall or to encourage anyone
+ to defer addressing basic security weaknesses.
Multiple ACL lines are OK.
- If any ACLs are specified, then the Privoxy
- talks only to IP addresses that match at least one only talks
+ to IP addresses that match at least one permit-access line
@@ -2144,8 +2528,19 @@ CLASS="QUOTE"
IP addresses, only the first one is used.
Some systems allow IPv4 clients to connect to IPv6 server sockets.
+ Then the client's IPv4 address will be translated by the system into
+ IPv6 address space with special prefix ::ffff:0:0/96 (so called IPv4
+ mapped IPv6 address). Privoxy can handle it
+ and maps such ACL addresses automatically.
+ Denying access to particular sites by ACL may have undesired side effects
- if the site in question is hosted on a machine which also hosts other sites.
+ if the site in question is hosted on a machine which also hosts other sites
+ (most sites are).
Allow any host on the same class C subnet as www.privoxy.org access to
- nothing but www.example.com:
+ nothing but www.example.com (or other domains hosted on the same system):
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 www.dirty-stuff.example.com:
+ with the exception that 192.168.45.73 may not access the IP address behind
+ 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):
+ This is equivalent to the following line even if listening on an
+ IPv4 address (not supported on all platforms):
+ This feature allows routing of HTTP requests through a chain of
- multiple proxies.
- It can be used to better protect privacy and confidentiality when
- accessing specific domains by routing requests to those domains
- through an anonymous public proxy (see e.g. http://www.multiproxy.org/anon_list.htm)
- Or to use a caching proxy to speed up browsing. Or chaining to a parent
- proxy may be necessary because the machine that Forwarding can be used to chain Privoxy with a caching proxy to speed
+ up browsing. Using a parent proxy may also be necessary if the machine
+ that Privoxy runs on has no direct Internet access. Note that parent proxies can severely decrease your privacy level.
+ For example a parent proxy could add your IP address to the request
+ headers and if it's a caching proxy it may add the "Etag"
- runs on has no direct Internet access. Also specified here are SOCKS proxies. 7.5.1. forward7.5.1. forward http_parent can be a
+ numerical IPv6 address (if
+ RFC 3493 is
+ implemented). To prevent clashes with the port delimiter, the whole IP
+ address has to be put into brackets. On the other hand a target_pattern containing an IPv6 address
+ has to be put into angle brackets (normal brackets are reserved for
+ regular expressions already).
+ Multiple lines are OK, they are checked in sequence, and the last match wins.
Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle):
+> Everything goes to an example parent proxy, except SSL on port 443 (which it doesn't handle):
Parent proxy specified by an IPv6 address:
+ Suppose your parent proxy doesn't support IPv6:
+ Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed.
+> Through which SOCKS proxy (and optionally to which parent HTTP proxy) specific requests should be routed.
With forward-socks5 the DNS resolution will happen on the remote server as well.
+ socks_proxy and
+ http_parent can be a
+ numerical IPv6 address (if
+ RFC 3493 is
+ implemented). To prevent clashes with the port delimiter, the whole IP
+ address has to be put into brackets. On the other hand a target_pattern containing an IPv6 address
+ has to be put into angle brackets (normal brackets are reserved for
+ regular expressions already).
+ If A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
+> A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
+ To chain Privoxy and Tor, both running on the same system, you would use
+ something like:
+ 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:
+ 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 local network through Privoxy
+ at all. Of course this may actually be desired and there is no reason
+ to make these exceptions if you aren't sure you need them.
+ 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:
+ If you have links to multiple ISPs that provide various special content
+ only to their subscribers, you can configure multiple Privoxies
+ which have connections to the respective ISPs to act as forwarders to each other, so that
+ your users can see the internal content of all ISPs. Assume that host-a has a PPP connection to isp-a.example.net. And host-b has a PPP connection to
+ isp-b.example.org. Both run Privoxy. Their forwarding
+ configuration can look like this: host-a: host-b: Now, your users can set their browser's proxy to use either
+ host-a or host-b and be able to browse the internal content
+ of both isp-a and isp-b. If you intend to chain Privoxy and
+ squid locally, then chaining as
+ browser -> squid -> privoxy is the recommended way. Assuming that Privoxy and squid
+ run on the same box, your squid configuration could then look like this: You would then need to change your browser's proxy settings to squid's address and port.
+ Squid normally uses port 3128. If unsure consult http_port in squid.conf. You could just as well decide to only forward requests you suspect
+ of leading to Windows executables through a virus-scanning parent proxy,
+ say, on antivir.example.com, port 8010: How often Privoxy retries if a forwarded connection request fails.
+ Number of retries.
+ 0 Connections forwarded through other proxies are treated like direct connections and no retry attempts are made.
+ 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.
+ Note that in the context of this option, "forwarded connections" includes all connections
+ that Privoxy forwards through other proxies. This option is not limited to the HTTP CONNECT method.
+ Only use this option, if you are getting lots of 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.
+ Due to a bug, this option currently also causes Privoxy to
+ retry in case of certain problems with direct connections.
+ forwarded-connect-retries 1
+ Whether intercepted requests should be treated as valid.
+ 0 or 1
+ 0 Only proxy requests are accepted, intercepted requests are treated as invalid.
+ If you don't trust your clients and want to force them
+ to use Privoxy, enable this
+ option and configure your packet filter to redirect outgoing
+ HTTP connections into Privoxy.
+ Make sure that Privoxy's own requests
+ aren't redirected as well. Additionally take care that
+ Privoxy can't intentionally connect
+ to itself, otherwise you could run into redirection loops if
+ Privoxy's listening port is reachable
+ by the outside or an attacker has access to the pages you visit.
+ accept-intercepted-requests 1
+ Whether requests to Privoxy's CGI pages can be blocked or redirected.
+ 0 or 1
+ 0 Privoxy ignores block and redirect actions for its CGI pages.
+ By default Privoxy ignores block or redirect actions
+ for its CGI pages. Intercepting these requests can be useful in multi-user
+ setups to implement fine-grained access control, but it can also render the complete
+ web interface useless and make debugging problems painful if done without care.
+ Don't enable this option unless you're sure that you really need it.
+ allow-cgi-request-crunching 1
+ Whether the CGI interface should stay compatible with broken HTTP clients.
+ 0 or 1
+ 0 The CGI form generate long GET URLs.
+ Privoxy's CGI forms can lead to
+ rather long URLs. This isn't a problem as far as the HTTP
+ standard is concerned, but it can confuse clients with arbitrary
+ URL length limitations.
+ Enabling split-large-forms causes Privoxy
+ to divide big forms into smaller ones to keep the URL length down.
+ It makes editing a lot less convenient and you can no longer
+ submit all changes at once, but at least it works around this
+ browser bug.
+ If you don't notice any editing problems, there is no reason
+ to enable this option, but if one of the submit buttons appears
+ to be broken, you should give it a try.
+ split-large-forms 1
+ Number of seconds after which an open connection will no longer be reused.
+ Time in seconds.
+ None Connections are not kept alive.
+ This option allows clients to keep the connection to Privoxy
+ alive. If the server supports it, Privoxy will keep
+ the connection to the server alive as well. Under certain
+ circumstances this may result in speed-ups.
+ By default, Privoxy will close the connection to the server if
+ the client connection gets closed, or if the specified timeout
+ has been reached without a new request coming in. This behaviour
+ can be changed with the connection-sharing option.
+ This option has no effect if Privoxy
+ has been compiled without keep-alive support.
+ Note that a timeout of five seconds as used in the default
+ configuration file significantly decreases the number of
+ connections that will be reused. The value is used because
+ some browsers limit the number of connections they open to
+ a single host and apply the same limit to proxies. This can
+ result in a single website "grabbing" all the
+ connections the browser allows, which means connections to
+ other websites can't be opened until the connections currently
+ in use time out.
+ Several users have reported this as a Privoxy bug, so the
+ default value has been reduced. Consider increasing it to
+ 300 seconds or even more if you think your browser can handle
+ it. If your browser appears to be hanging it can't.
+ keep-alive-timeout 300
+ Assumed server-side keep-alive timeout if not specified by the server.
+ Time in seconds.
+ None Connections for which the server didn't specify the keep-alive
+ timeout are not reused.
+ Enabling this option significantly increases the number of connections
+ that are reused, provided the keep-alive-timeout option
+ is also enabled.
+ While it also increases the number of connections problems
+ when Privoxy tries to reuse a connection that already has
+ been closed on the server side, or is closed while Privoxy
+ is trying to reuse it, this should only be a problem if it
+ happens for the first request sent by the client. If it happens
+ for requests on reused client connections, Privoxy will simply
+ close the connection and the client is supposed to retry the
+ request without bothering the user.
+ Enabling this option is therefore only recommended if the
+ connection-sharing option
+ is disabled.
+ It is an error to specify a value larger than the keep-alive-timeout value.
+ This option has no effect if Privoxy
+ has been compiled without keep-alive support.
+ default-server-timeout 60
+ Whether or not outgoing connections that have been kept alive
+ should be shared between different incoming connections.
+ 0 or 1
+ None Connections are not shared.
+ This option has no effect if Privoxy
+ has been compiled without keep-alive support, or if it's disabled.
+ Note that reusing connections doesn't necessary cause speedups.
+ There are also a few privacy implications you should be aware of.
+ If this option is effective, 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 Privoxy
+ and the server unless the client's request hasn't been completed yet.
+ If the outgoing connection is idle, it will not be closed until either
+ Privoxy's or the server's timeout is reached.
+ While it's open, the server knows that the system running Privoxy is still
+ there.
+ If there are more than one client (maybe even belonging to multiple users),
+ they will be able to reuse each others connections. This is potentially
+ dangerous in case of authentication schemes like NTLM where only the
+ connection is authenticated, instead of requiring authentication for
+ each request.
+ If there is only a single client, and if said client can keep connections
+ alive on its own, enabling this option has next to no effect. If the client
+ doesn't support connection keep-alive, enabling this option may make sense
+ as it allows Privoxy to keep outgoing connections alive even if the client
+ itself doesn't support it.
+ You should also be aware that enabling this option increases the likelihood
+ of getting the "No server or forwarder data" error message, especially if you
+ are using a slow connection to the Internet.
+ This option should only be used by experienced users who
+ understand the risks and can weight them against the benefits.
+ connection-sharing 1
+ Number of seconds after which a socket times out if
+ no data is received.
+ Time in seconds.
+ None A default value of 300 seconds is used.
+ For SOCKS requests the timeout currently doesn't start until
+ the SOCKS server accepted the request. This will be fixed in
+ the next release.
If you have links to multiple ISPs that provide various special content
- only to their subscribers, you can configure multiple Privoxies
- which have connections to the respective ISPs to act as forwarders to each other, so that
- your users can see the internal content of all ISPs. Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP connection to
- isp-b.net. Both run Privoxy. Their forwarding
- configuration can look like this: host-a: host-b: Now, your users can set their browser's proxy to use either
- host-a or host-b and be able to browse the internal content
- of both isp-a and isp-b. If you intend to chain If the system is powerful enough, Privoxy and
- can theoretically deal with
+ several hundred (or thousand) connections at the same time, but some
+ operating systems enforce resource limits by shutting down offending
+ processes and their default limits may be below the ones squid locally, then chain as
- browser -> squid -> privoxy is the recommended way. Assuming that Configuring Privoxy and to enforce a connection limit below the thread
+ or process limit used by the operating system makes sure this doesn't
+ happen. Simply increasing the operating system's limit would work too,
+ but if squid
- run on the same box, your Privoxy isn't the only application running on the system,
+ you may actually want to limit the resources used by squid configuration could then look like this: If Privoxy is only used by a single trusted user, limiting the
+ number of client connections is probably unnecessary. If there
+ are multiple possibly untrusted users you probably still want to
+ additionally use a packet filter to limit the maximal number of
+ incoming connections per client. Otherwise a malicious user could
+ intentionally create a high number of connections to prevent other
+ users from using Privoxy.
+ Obviously using this option only makes sense if you choose a limit
+ below the one enforced by the operating system.
+ max-client-connections 256
+ You would then need to change your browser's proxy settings to squid's address and port.
- 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 The status code Privoxy returns for pages blocked with
+
+ antivir.example.com, port 8010: 0 Privoxy returns a status 403(forbidden) for all blocked pages.
+ Privoxy returns a status 200(OK) for pages blocked with +handle-as-empty-document
+ and a status 403(Forbidden) for all other blocked pages.
+
7.4.2. toggle7.4.2. toggle listen-address [::1]:8118
7.4.4. enable-edit-actions
7.4.4. enable-remote-http-toggle7.4.5. enable-edit-actions
7.4.6. enforce-blocks
+ permit-access 192.0.2.0/24
+ permit-access [::ffff:192.0.2.0]/120
7.4.6. buffer-limit
7.4.8. buffer-limit
+ forward / anon-proxy.example.org:8080
+> forward / parent-proxy.example.org:8080
forward :443 .
forward / caching-proxy.example-isp.net:8000
- forward .example-isp.net .
forward / caching-proxy.isp.example.net:8000
+ forward .isp.example.net .
+ foward / [2001:DB8::1]:8000
7.5.2. forward-socks4 and forward-socks4a7.5.2. forward-socks4, forward-socks4a and forward-socks5Specifies: forward / parent-proxy.example.org:8000
+ forward ipv6-server.example.org .
+ forward <[2-3][0-9a-f][0-9a-f][0-9a-f]:*> .
forward-socks4a / socks-gw.example.com:1080 www-cache.example-isp.net:8080
+> forward-socks4a / socks-gw.example.com:1080 www-cache.isp.example.net:8080
forward .example.com .
+ forward-socks4 / socks-gw.example.com:1080 .
+ forward-socks5 / 127.0.0.1:9050 .
+ forward 192.168.*.*/ .
+ forward 10.*.*.*/ .
+ forward 127.*.*.*/ .
+ forward localhost/ .
7.5.3. Advanced Forwarding Examples
forward / .
+ forward .isp-b.example.net host-b:8118
forward / .
+ forward .isp-a.example.org host-a:8118
# 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
+
+ # Do not forward FTP requests to Privoxy
+ always_direct allow ftp
+
+ # Forward all the rest to Privoxy
+ never_direct allow all
forward / .
+ forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010
7.5.4. forwarded-connect-retries
7.6. Miscellaneous
7.6.1. accept-intercepted-requests
7.6.2. allow-cgi-request-crunching
7.6.3. split-large-forms
7.6.4. keep-alive-timeout
7.6.5. default-server-timeout
7.6.6. connection-sharing
7.6.7. socket-timeout
+> socket-timeout 300
forward-socks4 / socks-gw.example.com:1080 .
7.5.3. Advanced Forwarding Examples
Positive number.
+ forward / .
- forward .isp-b.net host-b:8118
Connections are served until a resource limit is reached.
+ forward / .
- forward .isp-a.net host-a:8118
7.6.9. handle-as-empty-doc-returns-ok
# 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
-
- # Do not forward FTP requests to Privoxy
- always_direct allow ftp
-
- # Forward all the rest to Privoxy
- never_direct allow all
0 or 1
+ forward / .
- forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010