X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fwebserver%2Fuser-manual%2Fconfig.html;h=f0f54e42164fbd20b8518905d21b062cab2ff630;hb=bb351be8595d489bc90f06f300aeef011aa2f8f4;hp=a25a894814a2e8d137f027ea68b3c578f3c06120;hpb=9adfbd2f4dd6acc1d92f00d46d18a16e8dfd5f1b;p=privoxy.git diff --git a/doc/webserver/user-manual/config.html b/doc/webserver/user-manual/config.html index a25a8948..f0f54e42 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 7.1. Configuration and Log File Locations
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 +1323,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 into the logfile + 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
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 The windows version will only display the toggle icon in the system tray
@@ -1760,8 +1817,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 Privoxy recognizes special HTTP headers to change its behaviour.
+ 0 or 1 0 Privoxy ignores special HTTP headers.
+ 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.
+ This feature is disabled by default. If you are using
+ Privoxy 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.
+ 1 For the time being, access to the editor can Access to the editor can listen-address above) can
- modify its configuration for all users. So this option is 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
+ Who can access what.
+ src_addr[/src_masklen]
+ [dst_addr[/dst_masklen]]
+ Where src_addr and
+ dst_addr are IP addresses in dotted decimal notation or valid
+ DNS names, and src_masklen and
+ dst_masklen are subnet masks in CIDR notation, i.e. integer
+ values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
+ destination part are optional.
+ Unset Don't restrict access further than implied by listen-address
+ Access controls are included at the request of ISPs and systems
+ administrators, and are not usually needed by individual users.
+ For a typical home user, it will normally suffice to ensure that
+ Privoxy only listens on the localhost
+ (127.0.0.1) or internal (home) network address by means of the
+ listen-address
+ option.
+ 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, Privoxy only talks
+ to IP addresses that match at least one permit-access line
+ and don't match any subsequent deny-access line. In other words, the
+ last match wins, with the default being deny-access.
+ If Privoxy is using a forwarder (see forward below)
+ for a particular destination URL, the dst_addr
+ that is examined is the address of the forwarder and NOT the address
+ of the ultimate target. This is necessary because it may be impossible for the local
+ Privoxy to determine the IP address of the
+ ultimate target (that's often what gateways are used for).
+ You should prefer using IP addresses over DNS names, because the address lookups take
+ time. All DNS names must resolve! You can not use domain patterns
+ like "*.org" or partial domain names. If a DNS name resolves to multiple
+ IP addresses, only the first one is used.
+ 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
+ (most sites are).
+ Explicitly define the default behavior if no ACL and
+ listen-address are set: "localhost"
+ is OK. The absence of a dst_addr implies that
+ all destination addresses are OK:
+ 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):
+ 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:
+ Maximum size of the buffer for content filtering.
+ Size in Kbytes 4096 Use a 4MB (4096 KB) limit.
+ For content filtering, i.e. the +filter and
+ +deanimate-gif actions, it is necessary that
+ Privoxy buffers the entire document body.
+ This can be potentially dangerous, since a server could just keep sending
+ data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
+ Hence this option.
+ When a document buffer size reaches the buffer-limit, it is
+ flushed to the client unfiltered and no further attempt to
+ filter the rest of the document is made. Remember that there may be multiple threads
+ running, which might require up to buffer-limit Kbytes
+ each, unless you have enabled "single-threaded"
+ above.
+ This feature allows routing of HTTP requests through a chain of
+ multiple proxies. 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"
+ header to revalidation requests again, even though you configured Privoxy
+ to remove it. It may also ignore Privoxy's header time randomization and use the
+ original values which could be used by the server as cookie replacement
+ to track your steps between visits. Also specified here are SOCKS proxies. Privoxy
+ supports the SOCKS 4 and SOCKS 4A protocols. To which parent HTTP proxy specific requests should be routed.
+ target_pattern
+ http_parent[:port]
+ 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".
+ Unset Don't use parent HTTP proxies.
+ If http_parent is ".", then requests are not
+ forwarded to another HTTP proxy but are made directly to the web servers.
+ Multiple lines are OK, they are checked in sequence, and the last match wins.
+ Everything goes to an example parent proxy, except SSL on port 443 (which it doesn't handle):
+ Everything goes to our example ISP's caching proxy, except for requests
+ to that ISP's sites:
+ Through which SOCKS proxy (and optionally to which parent HTTP proxy) specific requests should be routed.
+ target_pattern
+ socks_proxy[:port]
+ http_parent[:port]
+ 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
+ port parameters are TCP ports,
+ i.e. integer values from 1 to 65535
+ Unset Don't use SOCKS proxies.
+ Multiple lines are OK, they are checked in sequence, and the last match wins.
+ The difference between forward-socks4 and forward-socks4a
+ is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
+ server, while in SOCKS 4 it happens locally.
+ With forward-socks5 the DNS resolution will happen on the remote server as well.
+ If http_parent is ".", then requests are not
+ forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
+ a SOCKS proxy.
+ From the company example.com, direct connections are made to all
+ "internal" domains, but everything outbound goes through
+ their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
+ the Internet.
+ 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.
+ not
- recommended0 for multi-user environments with untrusted users.
+> Connections forwarded through other proxies are treated like direct connections and no retry attempts are made.
Note that you must have compiled forwarded-connect-retries is mainly interesting
+ for socks4a connections, where Privoxy with
- support for this feature, otherwise this option has no effect.
+> 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.
+ forwarded-connect-retries 1
Who can access what.
+> Whether intercepted requests should be treated as valid.
Where src_addr and
- dst_addr are IP addresses in dotted decimal notation or valid
- DNS names, and src_masklen and
- dst_masklen0 or 1 are subnet masks in CIDR notation, i.e. integer
- values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
- destination part are optional.
+>
Don't restrict access further than implied by listen-address
+> Only proxy requests are accepted, intercepted requests are treated as invalid.
Access controls are included at the request of ISPs and systems
- administrators, and are not usually needed by individual users.
- For a typical home user, it will normally suffice to ensure that
- If you don't trust your clients and want to force them
+ to use Privoxy only listens on the localhost
- (127.0.0.1) or internal (home) network address by means of the
- listen-address
- option.
- 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.
- Multiple ACL lines are OK.
- If any ACLs are specified, then the , enable this
+ option and configure your packet filter to redirect outgoing
+ HTTP connections into Privoxy
- talks only to IP addresses that match at least one permit-access line
- and don't match any subsequent deny-access line. In other words, the
- last match wins, with the default being deny-access.
+>.
If Make sure that Privoxy is using a forwarder (see forward below)
- for a particular destination URL, the dst_addr
- that is examined is the address of the forwarder and NOT the address
- of the ultimate target. This is necessary because it may be impossible for the local
+>Privoxy's own requests
+ aren't redirected as well. Additionally take care that
Privoxy to determine the IP address of the
- ultimate target (that's often what gateways are used for).
- You should prefer using IP addresses over DNS names, because the address lookups take
- time. All DNS names must resolve! You can not use domain patterns
- like "*.org" or partial domain names. If a DNS name resolves to multiple
- IP addresses, only the first one is used.
- 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.
+> 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.
Explicitly define the default behavior if no ACL and
- listen-address are set: "localhost"
- is OK. The absence of a dst_addr implies that
- all destination addresses are OK:
- Allow any host on the same class C subnet as www.privoxy.org access to
- nothing but www.example.com:
- 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:
- Maximum size of the buffer for content filtering.
+> Whether requests to Privoxy's CGI pages can be blocked or redirected.
Size in Kbytes 4096 Use a 4MB (4096 KB) limit.
+> Privoxy ignores block and redirect actions for its CGI pages.
For content filtering, i.e. the +filter and
- +deanimate-gif actions, it is necessary that
- By default Privoxy buffers the entire document body.
- This can be potentially dangerous, since a server could just keep sending
- data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
- Hence this option.
+> 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.
When a document buffer size reaches the buffer-limit, it is
- flushed to the client unfiltered and no further attempt to
- filter the rest of the document is made. Remember that there may be multiple threads
- running, which might require up to buffer-limit Kbytes
- each, unless you have enabled "single-threaded"
- above.
+> Don't enable this option unless you're sure that you really need it.
+ allow-cgi-request-crunching 1
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 Privoxy
- runs on has no direct Internet access. Also specified here are SOCKS proxies. Privoxy
- supports the SOCKS 4 and SOCKS 4A protocols. To which parent HTTP proxy specific requests should be routed.
+> Whether the CGI interface should stay compatible with broken HTTP clients.
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".
Don't use parent HTTP proxies.
+> The CGI form generate long GET URLs.
If http_parent is ".", then requests are not
- forwarded to another HTTP proxy but are made directly to the web servers.
+> 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.
Multiple lines are OK, they are checked in sequence, and the last match wins.
+> 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.
Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle):
- Everything goes to our example ISP's caching proxy, except for requests
- to that ISP's sites:
- Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed.
+> Number of seconds after which an open connection will no longer be reused.
target_pattern
- socks_proxy[:port]
- http_parent[:port]
- 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 (Type of value: http_parentTime in seconds.
- may be "." to denote "no HTTP forwarding"), and the optional
- port parameters are TCP ports, i.e. integer values from 1 to 64535
Unset Don't use SOCKS proxies.
+> Connections are not reused.
Multiple lines are OK, they are checked in sequence, and the last match wins.
- The difference between forward-socks4 and forward-socks4a This option has no effect if Privoxy
- is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
- server, while in SOCKS 4 it happens locally.
- If http_parent is ".", then requests are not
- forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
- a SOCKS proxy.
+ has been compiled without keep-alive support.
From the company example.com, direct connections are made to all
- "internal" domains, but everything outbound goes through
- their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
- the Internet.
- A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks 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.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 Privoxy and
- squid locally, then chain as
- browser -> squid -> privoxy is the recommended way. Assuming that Privoxy and squid Time in seconds.
- 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 for Windows executables through
- a virus-scanning parent proxy, say, on antivir.example.com, port 8010: 7.4.4. enable-remote-http-toggle
7.4.4. enable-edit-actions
7.4.5. enable-edit-actions7.4.6. enforce-blocks
7.4.7. ACLs: permit-access and deny-access
+ permit-access localhost
+ permit-access www.privoxy.org/24 www.example.com/32
+ permit-access 192.168.45.64/26
+ deny-access 192.168.45.73 www.dirty-stuff.example.com
7.4.8. buffer-limit
7.5. Forwarding
7.5.1. forward
+ forward / parent-proxy.example.org:8080
+ forward :443 .
+ forward / caching-proxy.isp.example.net:8000
+ forward .isp.example.net .
7.5.2. forward-socks4, forward-socks4a and forward-socks5
+ forward-socks4a / socks-gw.example.com:1080 www-cache.isp.example.net:8080
+ forward .example.com .
+ forward-socks4 / socks-gw.example.com:1080 .
+ forward-socks4a / 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.4.5. ACLs: permit-access and deny-access
7.5.5. accept-intercepted-requests
- permit-access localhost
- permit-access www.privoxy.org/24 www.example.com/32
+> accept-intercepted-requests 1
permit-access 192.168.45.64/26
- deny-access 192.168.45.73 www.dirty-stuff.example.com
7.4.6. buffer-limit
7.5.6. allow-cgi-request-crunching7.5. Forwarding
7.5.1. forward
7.5.7. split-large-forms
- forward / anon-proxy.example.org:8080
- forward :443 .
+> split-large-forms 1
forward / caching-proxy.example-isp.net:8000
- forward .example-isp.net .
7.5.2. forward-socks4 and forward-socks4a
7.5.8. keep-alive-timeout
- forward-socks4a / socks-gw.example.com:1080 www-cache.example-isp.net:8080
- forward .example.com .
+> keep-alive-timeout 300
forward-socks4 / socks-gw.example.com:1080 .
7.5.3. Advanced Forwarding Examples
7.5.9. socket-timeout forward / .
- forward .isp-b.net host-b:8118
forward / .
- forward .isp-a.net 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
socket-timeout 180
+ forward / .
- forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010