X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fwebserver%2Fuser-manual%2Factions-file.html;h=ed626d76f1c5592dbf8360ffc93063ee0040bf29;hb=95923775ba5f094b8a09499e7c1e45f4e58074f3;hp=0bf9e3fa87385181546e67822e3ef4b788c3974f;hpb=5700aead3098beb0cc5a02bc0034a0d4194774a6;p=privoxy.git diff --git a/doc/webserver/user-manual/actions-file.html b/doc/webserver/user-manual/actions-file.html index 0bf9e3fa..ed626d76 100644 --- a/doc/webserver/user-manual/actions-file.html +++ b/doc/webserver/user-manual/actions-file.html @@ -1,8270 +1,3932 @@ - -
The actions files are 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, and on which sites (or even parts thereof). - There are a number of such actions, with a wide range of functionality. - Each action does something a little different. - These actions give us a veritable arsenal of tools with which to exert - our control, preferences and independence. Actions can be combined so that - their effects are aggregated when applied against a given set of URLs.
There - are three action files included with Privoxy with - differing purposes:
match-all.action - is used to define which - "actions" relating to banner-blocking, images, pop-ups, - content modification, cookie handling etc should be applied by default. - It should be the first actions file loaded -
default.action - defines many exceptions (both - positive and negative) from the default set of actions that's configured - in match-all.action. It is a set of rules that should - work reasonably well as-is for most users. This file is only supposed to - be edited by the developers. It should be the second actions file loaded. -
user.action - is intended to be for local site - preferences and exceptions. As an example, if your ISP or your bank - has specific requirements, and need special handling, this kind of - thing should go here. This file will not be upgraded. -
Edit Set to Cautious Set to Medium Set to Advanced -
These have increasing levels of aggressiveness and have no - influence on your browsing unless you select them explicitly in the - editor. A default installation should be pre-set to - Cautious. New users should try this for a while before - adjusting the settings to more aggressive levels. The more aggressive - the settings, then the more likelihood there is of problems such as sites - not working as they should. -
The Edit button allows you to turn each - action on/off individually for fine-tuning. The Cautious - button changes the actions list to low/safe settings which will activate - ad blocking and a minimal set of Privoxy's features, and subsequently - there will be less of a chance for accidental problems. The - Medium button sets the list to a medium level of - other features and a low level set of privacy features. The - Advanced button sets the list to a high level of - ad blocking and medium level of privacy. See the chart below. The latter - three buttons over-ride any changes via with the - Edit button. More fine-tuning can be done in the - lower sections of this internal page. -
While the actions file editor allows to enable these settings in all - actions files, they are only supposed to be enabled in the first one - to make sure you don't unintentionally overrule earlier rules. -
The default profiles, and their associated actions, as pre-defined in - default.action are: -
Table 1. Default Configurations
Feature | Cautious | Medium | Advanced |
---|---|---|---|
Ad-blocking Aggressiveness | medium | high | high |
Ad-filtering by size | no | yes | yes |
Ad-filtering by link | no | no | yes |
Pop-up killing | blocks only | blocks only | blocks only |
Privacy Features | low | medium | medium/high |
Cookie handling | none | session-only | kill |
Referer forging | no | yes | yes |
GIF de-animation | no | yes | yes |
Fast redirects | no | no | yes |
HTML taming | no | no | yes |
JavaScript taming | no | no | yes |
Web-bug killing | no | yes | yes |
Image tag reordering | no | yes | yes |
The list of actions files to be used are defined in the main configuration - file, and are processed in the order they are defined (e.g. - default.action is typically processed before - user.action). The content of these can all be viewed and - edited from http://config.privoxy.org/show-status. - The over-riding principle when applying actions, is that the last action that - matches a given URL wins. The broadest, most general rules go first - (defined in default.action), - followed by any exceptions (typically also in - default.action), which are then followed lastly by any - local preferences (typically in user.action). - Generally, user.action has the last word. -
An actions file typically has multiple sections. If you want to use - "aliases" in an actions file, you have to place the (optional) - alias section at the top of that file. - Then comes the default set of rules which will apply universally to all - sites and pages (be very careful with using such a - universal set in user.action or any other actions file after - default.action, because it will override the result - from consulting any previous file). And then below that, - exceptions to the defined universal policies. You can regard - user.action as an appendix to default.action, - with the advantage that it is a separate file, which makes preserving your - personal settings across Privoxy upgrades easier.
- Actions can be used to block anything you want, including ads, banners, or - just some obnoxious URL whose content 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, some JavaScripts tamed, user-tracking - fooled, and much more. See below for a complete list - of actions.
Note that some actions, like cookie suppression - or script disabling, may render some sites unusable that rely on these - techniques to work properly. Finding the right mix of actions is not always easy and - certainly a matter of personal taste. And, things can always change, requiring - refinements in the configuration. 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 crunch all cookies per - default, you'll have to make exceptions from that rule for sites that you - regularly use and that require cookies for actually useful purposes, like maybe - your bank, favorite shop, or newspaper.
We have tried to provide you with reasonable rules to start from in the - distribution actions files. 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 again :).
The easiest way to edit the actions files is with a browser by - using our browser-based editor, which can be reached from http://config.privoxy.org/show-status. - Note: the config file option enable-edit-actions must be enabled for - this to work. The editor allows both fine-grained control over every single - feature on a per-URL basis, and easy choosing from wholesale sets of defaults - like "Cautious", "Medium" or - "Advanced". Warning: the "Advanced" setting is more - aggressive, and will be more likely to cause problems for some sites. - Experienced users only! -
If you prefer plain text editing to GUIs, you can of course also directly edit the - the actions files with your favorite text editor. Look at - default.action which is richly commented with many - good examples.
Actions files are 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 and tag patterns, each on a separate line.
To determine which actions apply to a request, the URL of the request is - compared to all URL patterns in each "action file". - Every time it matches, the list of applicable actions for the request is - incrementally updated, using the heading of the section in which the - pattern is located. The same is done again for tags and tag patterns later on.
If multiple applying sections set the same action differently, - the last match wins. If not, the effects are aggregated. - E.g. a URL might match a regular section with a heading line of { - +handle-as-image }, - then later another one with just { - +block }, resulting - in both actions to apply. And there may well be - cases where you will want to combine actions together. Such a section then - might look like:
{ +handle-as-image +block{Banner ads.} } + + + + |
+
Example of a simple block action. Say you've seen an ad on your + favourite page on example.com that you want to get rid of. You have right-clicked the image, selected + "copy image location" and pasted the URL below while removing the leading http://, + into a { +block{} } section. Note that { +handle-as-image } + need not be specified, since all URLs ending in .gif will be tagged as images by the + general rules as set in default.action anyway:
+
+ { +block{Nasty ads.} } + www.example.com/nasty-ads/sponsor\.gif + another.example.net/more/junk/here/+ |
+
The URLs of dynamically generated banners, especially from large banner farms, often don't use the + well-known image file name extensions, which makes it impossible for Privoxy + to guess the file type just by looking at the URL. You can use the +block-as-image + alias defined above for these cases. Note that objects which match this rule but then turn out NOT to be an + image are typically rendered as a "broken image" icon by the browser. Use + cautiously.
+
+ { +block-as-image } + .doubleclick.net + .fastclick.net + /Realmedia/ads/ + ar.atwola.com/+ |
+
Now you noticed that the default configuration breaks Forbes Magazine, but you were too lazy to find out + which action is the culprit, and you were again too lazy to give feedback, so you + just used the fragile alias on the site, and -- whoa! -- it worked. The fragile aliases disables those actions + that are most likely to break a site. Also, good for testing purposes to see if it is Privoxy that is causing the problem or not. We later find other regular sites that + misbehave, and add those to our personalized list of troublemakers:
+
+ { fragile } + .forbes.com + webmail.example.com + .mybank.com+ |
+
You like the "fun" text replacements in default.filter, + but it is disabled in the distributed actions file. So you'd like to turn it on in your private, update-safe + config, once and for all:
+
+ { +filter{fun} } + / # For ALL sites!+ |
+
Note that the above is not really a good idea: There are exceptions to the filters in default.action for things that really shouldn't be filtered, like code on CVS->Web + interfaces. Since user.action has the last word, these exceptions won't be valid for + the "fun" filtering specified here.
+You might also worry about how your favourite free websites are funded, and find that they rely on + displaying banner advertisements to survive. So you might want to specifically allow banners for those sites + that you feel provide value to you:
+
+ { allow-ads } + .sourceforge.net + .slashdot.org + .osdn.net+ |
+
Note that allow-ads has been aliased to -block, -filter{banners-by-size}, and -filter{banners-by-link} above.
+Invoke another alias here to force an over-ride of the MIME type application/x-sh + which typically would open a download type dialog. In my case, I want to look at the shell script, and then I + can save it should I choose to.
+
+ { handle-as-text } + /.*\.sh$+ |
+
user.action is generally the best place to define exceptions and additions to the + default policies of default.action. Some actions are safe to have their default + policies set here though. So let's set a default policy to have a "blank" image as + opposed to the checkerboard pattern for ALL sites. + "/" of course matches all URL paths and patterns:
+
+ { +set-image-blocker{blank} } + / # ALL sites+ |
+