X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fuser-manual%2Fconfiguration.html;h=d75573b4f47017d55dda0e92a329c5a2b7cb908f;hp=abfbabb402b556fcb95348af528619f59fa92b59;hb=46174e1f222d671ce9aab072e6174499756911ed;hpb=56d03106907472899fa6e8933e81058744ce0fed diff --git a/doc/webserver/user-manual/configuration.html b/doc/webserver/user-manual/configuration.html index abfbabb4..d75573b4 100644 --- a/doc/webserver/user-manual/configuration.html +++ b/doc/webserver/user-manual/configuration.html @@ -1,24 +1,25 @@ +
Privoxy User Manual | Privoxy 3.0.7 User Manual||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Prev | Next |
Please choose from the following options: - - * Privoxy main page - * Show information about the current configuration - * Show the source code version numbers - * Show the request headers. - * Show which actions apply to a URL and why - * Toggle Privoxy on or off - * Edit the actions list - - |
This should be self-explanatory. Note the last item is an editor for the - "actions list", which is where much of the ad, banner, cookie, - and URL blocking magic is configured as well as other advanced features of +> This should be self-explanatory. Note the first item leads to an editor for the + actions files, which is where the ad, banner, + cookie, and URL blocking magic is configured as well as other advanced features of PrivoxyPrivoxy continues - to run as a proxy in this case, but all filtering is disabled. There + to run as a proxy in this case, but all manipulation is disabled, i.e. + Privoxy acts like a normal forwarding proxy. There is even a toggle BookmarkletPrivoxy with one click from your browser.
Note that several of the features described above are disabled by default + in Privoxy 3.0.7 beta and later. + Check the + configuration file to learn why + and in which cases it's safe to enable them again.
For Unix, *BSD and Linux, all configuration files are located in @@ -205,16 +276,19 @@ CLASS="APPLICATION" and number of configuration files has changed from previous versions, and is subject to change as development progresses.
The installed defaults provide a reasonable starting point, though possibly - aggressive by some standards. For the time being, there are only three - default configuration files (this may change in time):
The installed defaults provide a reasonable starting point, though + some settings may be aggressive by some standards. For the time being, the + principle configuration files are:
The main configuration file is named The main configuration file is named config @@ -222,7 +296,7 @@ CLASS="FILENAME" CLASS="FILENAME" >config.txt - on Windows. + on Windows. This is a required file.
Multiple actions files may be defined in config. These + are processed in the order they are defined. Local customizations and locally + preferred exceptions to the default policies as defined in + default.action (which you will most probably want + to define sooner or later) are probably best applied in + user.action, where you can preserve them across + upgrades. standard.action is only for + Privoxy's internal use. +
+ There is also a web based editor that can be accessed from + http://config.privoxy.org/edit-actions/http://config.privoxy.org/show-status
(Shortcut: http://p.p/edit-actions/). - (Other actions files are included as well with differing levels of filtering - and blocking, e.g. basic.action.) +>http://p.p/show-status) for the + various actions files."Filter files" (the filter + file) can be used to re-write the raw page content, including + viewable text as well as embedded HTML and JavaScript, and whatever else + lurks on any given web page. The filtering jobs are only pre-defined here; + whether to apply them or not is up to the actions files. + default.filter (the filter file) can be used to re-write the raw - page content, including viewable text as well as embedded HTML and JavaScript, - and whatever else lurks on any given web page. The filtering jobs are only - pre-defined here; whether to apply them or not is up to the actions file. +> includes various filters made + available for use by the developers. Some are much more intrusive than + others, and all should be used with caution. You may define additional + filter files in config as you can with + actions files. We suggest user.filter for any + locally defined filters or customizations.
The syntax of the configuration and filter files may change between different + Privoxy versions, unfortunately some enhancements cost backwards compatibility. +
All files use the "# in front of an otherwise valid configuration line to prevent it from being interpreted is called "commenting - out" that line.
default.action and default.filter +> The actions files and filter files can use Perl style regular expressions"wake up" requests - must obviously be sent to the old listening address.
While under development, the configuration content is subject to change. @@ -334,5505 +462,43 @@ CLASS="QUOTE" > setting, may change, so please check all your configuration files on important issues.
Again, the main configuration file is named config on - Linux/Unix/BSD and OS/2, and config.txt on Windows. - Configuration lines consist of an initial keyword followed by a list of - values, all separated by whitespace (any number of spaces or tabs). For - example:
confdir /etc/privoxy
-
Assigns the value /etc/privoxy to the option - confdir and thus indicates that the configuration - directory is named "/etc/privoxy/".
All options in the config file except for confdir and - logdir are optional. Watch out in the below description - for what happens if you leave them unset.
The main config file controls all aspects of 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 and logging. - This section of the configuration file tells Privoxy - where to find those other files.
The directory where the other configuration files are located
Path name
/etc/privoxy (Unix) or Privoxy installation dir (Windows)
Mandatory
No trailing "/", please -
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. Privoxy's 404 error page). -
5.3.1.2. logdir
Prev | 5.3.1.3. actionsfile
Home | 5.3.1.4. filterfile
5.3.1.5. logfile
5.3.1.6. jarfile
5.3.1.7. trustfile
5.3.2. Local Set-up DocumentationIf you intend to operate Privoxy for more users - that 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. - 5.3.2.1. trust-info-url
5.3.2.2. admin-address
5.3.2.3. proxy-info-url
5.3.3. DebuggingThese options are mainly useful when tracing a problem. - Note that you might also want to invoke - Privoxy with the --no-daemon - command line option when debugging. - 5.3.3.1. debug
5.3.3.2. single-threaded
5.3.4. Access Control and SecurityThis section of the config file controls the security-relevant aspects - of Privoxy's configuration. - 5.3.4.1. listen-address
5.3.4.2. toggle
5.3.4.3. enable-remote-toggle
5.3.4.4. enable-edit-actions
5.3.4.5. ACLs: permit-access and deny-access
5.3.4.6. buffer-limit
5.3.5. ForwardingThis 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. 5.3.5.1. forward
5.3.5.2. forward-socks4 and forward-socks4a
5.3.5.3. Advanced Forwarding ExamplesIf 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 - 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. 5.3.6. Windows GUI OptionsPrivoxy has a number of options specific to the - Windows GUI interface: If "activity-animation" is set to 1, the - Privoxy icon will animate when - "Privoxy" is active. To turn off, set to 0.
activity-animation 1 If "log-messages" is set to 1, - Privoxy will log messages to the console - window:
log-messages 1 - If "log-buffer-size" is set to 1, the size of the log buffer, - i.e. the amount of memory used for the log messages displayed in the - console window, will be limited to "log-max-lines" (see below). Warning: Setting this to 0 will result in the buffer to grow infinitely and - eat up all your memory!
log-buffer-size 1 log-max-lines is the maximum number of lines held - in the log buffer. See above.
log-max-lines 200 If "log-highlight-messages" is set to 1, - Privoxy will highlight portions of the log - messages with a bold-faced font:
log-highlight-messages 1 The font used in the console window:
log-font-name Comic Sans MS Font size used in the console window:
log-font-size 8 - "show-on-task-bar" controls whether or not - Privoxy will appear as a button on the Task bar - when minimized:
show-on-task-bar 0 If "close-button-minimizes" is set to 1, the Windows close - button will minimize Privoxy instead of closing - the program (close with the exit option on the File menu).
close-button-minimizes 1 The "hide-console" option is specific to the MS-Win console - version of Privoxy. If this option is used, - Privoxy will disconnect from and hide the - command console.
#hide-console 5.4. The Actions FileThe actions file (default.action, formerly: - actionsfile or ijb.action) is used - to define what actions Privoxy takes for which - URLs, and thus determines how ad images, cookies and various other aspects - of HTTP content and transactions are handled on which sites (or even parts - thereof). - Anything you want can blocked, including ads, banners, or just some obnoxious - URL that you would rather not see. Cookies can be accepted or rejected, or - accepted only during the current browser session (i.e. not written to disk), - content can be modified, JavaScripts tamed, user-tracking fooled, and much more. - See below for a complete list of available actions. An actions file typically has sections. At the top, "aliases" are - defined (discussed below), then the default set of rules which will apply - universally to all sites and pages. And then below that is generally a lengthy - set of exceptions to the defined universal policies. 5.4.1. Finding the Right MixNote that some actions like cookie suppression or script disabling may - render some sites unusable, which rely on these techniques to work properly. - Finding the right mix of actions is not easy and certainly a matter of personal - taste. In general, it can be said that the more "aggressive" - your default settings (in the top section of the actions file) are, - the more exceptions for "trusted" sites you will have to - make later. If, for example, you want to kill popup windows per default, you'll - have to make exceptions from that rule for sites that you regularly use - and that require popups for actually useful content, like maybe your bank, - favorite shop, or newspaper. We have tried to provide you with reasonable rules to start from in the - distribution actions file. But there is no general rule of thumb on these - things. There just are too many variables, and sites are constantly changing. - Sooner or later you will want to change the rules (and read this chapter). 5.4.2. How to EditThe easiest way to edit the "actions" file is with a browser by - using our browser-based editor, which is available at http://config.privoxy.org/edit-actions. If you prefer plain text editing to GUIs, you can of course also directly edit the - default.action file. 5.4.3. How Actions are Applied to URLsThe actions file is divided into sections. There are special sections, - like the "alias" sections which will be discussed later. For now - let's concentrate on regular sections: They have a heading line (often split - up to multiple lines for readability) which consist of a list of actions, - separated by whitespace and enclosed in curly braces. Below that, there - is a list of URL patterns, each on a separate line. To determine which actions apply to a request, the URL of the request is - compared to all patterns in this file. Every time it matches, the list of - applicable actions for the URL is incrementally updated, using the heading - of the section in which the pattern is located. If multiple matches for - the same URL set the same action differently, the last match wins. You can trace this process by visiting http://config.privoxy.org/show-url-info. More detail on this is provided in the Appendix, Anatomy of an Action. 5.4.4. PatternsGenerally, a pattern has the form <domain>/<path>, - where both the <domain> and <path> - are optional. (This is why the pattern / matches all URLs).
5.4.4.1. The Domain PatternThe matching of the domain part offers some flexible options: if the - domain starts or ends with a dot, it becomes unanchored at that end. - For example:
Additionally, there are wild-cards that you can use in the domain names - themselves. They work pretty similar to shell wild-cards: "*" - stands for zero or more arbitrary characters, "?" stands for - any single character, you can define character classes in square - brackets and all of that can be freely mixed:
5.4.4.2. The Path PatternPrivoxy uses Perl compatible regular expressions - (through the PCRE library) for - matching the path. There is an Appendix with a brief quick-start into regular - expressions, and full (very technical) documentation on PCRE regex syntax is available on-line - at http://www.pcre.org/man.txt. - You might also find the Perl man page on regular expressions (man perlre) - useful, which is available on-line at http://www.perldoc.com/perl5.6/pod/perlre.html. Note that the path pattern is automatically left-anchored at the "/", - i.e. it matches as if it would start with a "^". Please also note that matching in the path is case - INSENSITIVE by default, but you can switch to case - sensitive at any point in the pattern by using the - "(?-i)" switch: - www.example.com/(?-i)PaTtErN.* will match only - documents whose path starts with PaTtErN in - exactly this capitalization. 5.4.5. ActionsActions are enabled if preceded with a "+", and disabled if - preceded with a "-". So a "+action" means - "do that action", e.g. "+block" means please - "block the following URLs and/or patterns". All actions are - disabled by default, until they are explicitly enabled somewhere in an actions - file. - Actions are invoked by enclosing the action name in curly braces (e.g. - {+some_action}), followed by a list of URLs (or patterns that match URLs) to - which the action applies. There are three classes of actions:
If nothing is specified in this file, no "actions" are taken. - So in this case Privoxy would just be a - normal, non-blocking, non-anonymizing proxy. You must specifically - enable the privacy and blocking features you need (although the - provided default default.action file will - give a good starting point). Later defined actions always over-ride earlier ones. So exceptions - to any rules you make, should come in the latter part of the file. For - multi-valued actions, the actions are applied in the order they are - specified. The list of valid Privoxy "actions" are: 5.4.5.1. +add-header{Name: value}
5.4.5.2. +block
5.4.5.3. +deanimate-gifs
5.4.5.4. +downgrade
5.4.5.5. +fast-redirects
5.4.5.6. +filter
5.4.5.7. +hide-forwarded
5.4.5.8. +hide-from
5.4.5.9. +hide-referer
5.4.5.10. +hide-user-agent
5.4.5.11. +image
5.4.5.12. +image-blocker
5.4.5.13. +limit-connect
5.4.5.14. +no-compression
5.4.5.15. +no-cookies-keep
5.4.5.16. +no-cookies-read
5.4.5.17. +no-cookies-set
5.4.5.18. +no-popup
5.4.5.19. +vanilla-wafer
5.4.5.20. +wafer
5.4.5.21. Actions ExamplesNote that the meaning of any of the above examples is reversed by preceding - the action with a "-", in place of the "+". Also, - that some actions are turned on in the default section of the actions file, - and require little to no additional configuration. These are just "on". - Some actions that are turned on the default section do typically require - exceptions to be listed in the lower sections of actions file. Some examples: Turn off cookies by default, then allow a few through for specified sites:
# Turn off all persistent cookies Now turn off "fast redirects", and then we allow two exceptions:
# Turn them off! Turn on page filtering according to rules in the defined sections - of default.filter, and make one exception for - Sourceforge: -
# Run everything through the filter file, using only the Now some URLs that we want "blocked" (normally generates - the "blocked" banner). Many of these use - regular expressions that will expand to match - multiple URLs:
# Blocklist: Note that many of these actions have the potential to cause a page to - misbehave, possibly even not to display at all. There are many ways - a site designer may choose to design his site, and what HTTP header - content he may depend on. There is no way to have hard and fast rules - for all sites. See the Appendix - for a brief example on troubleshooting actions. 5.4.6. AliasesCustom "actions", known to Privoxy - as "aliases", can be defined by combining other "actions". - These can in turn be invoked just like the built-in "actions". - Currently, an alias can contain any character except space, tab, "=", - "{" or "}". But please use only "a"- - "z", "0"-"9", "+", and - "-". Alias names are not case sensitive, and - must be defined before anything else in the - default.actionfile! And there can only be one set of - "aliases" defined. Now let's define a few aliases:
# Useful custom aliases we can use later. These must come first! Some examples using our "shop" and "fragile" - aliases from above:
# These sites are very complex and require The "shop" and "fragile" aliases are often used for - "problem" sites that require most actions to be disabled - in order to function properly. 5.5. The Filter FileAny web page can be dynamically modified with the filter file. This - modification can be removal, or re-writing, of any web page content, - including tags and non-visible content. The default filter file is - default.filter, located in the config directory. This is potentially a very powerful feature, and requires knowledge of both - "regular expression" and HTML in order create custom - filters. But, there are a number of useful filters included with - Privoxy for many common situations. The included example file is divided into sections. Each section begins - with the FILTER keyword, followed by the identifier - for that section, e.g. "FILTER: webbugs". Each section performs - a similar type of filtering, such as "html-annoyances". This file uses regular expressions to alter or remove any string in the - target page. The expressions can only operate on one line at a time. Some - examples from the included default default.filter: Stop web pages from displaying annoying messages in the status bar by - deleting such references:
FILTER: html-annoyances Just for kicks, replace any occurrence of "Microsoft" with - "MicroSuck", and have a little fun with topical buzzwords:
FILTER: fun Kill those pesky little web-bugs:
# webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking) 5.6. TemplatesWhen Privoxy displays one of its internal - pages, such as a 404 Not Found error page, it uses the appropriate template. - On Linux, BSD, and Unix, these are located in - /etc/privoxy/templates by default. These may be - customized, if desired. cgi-style.css is - used to control the HTML attributes (fonts, etc). The default "Blocked" banner page with the bright red top - banner, is called just "blocked". This - may be customized or replaced with something else if desired. |