X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fuser-manual%2Factions-file.html;h=f78109e2f4808806fada3d9ad0e7b242a4a976bc;hp=5dceae76d139980183b97e5d3824f8d3f1d5ac7d;hb=7d0d8bdd53947864c64d968062ca132b65f2e162;hpb=2afbba3d1be8e0c53169a05faeab2ac24ccc23b1 diff --git a/doc/webserver/user-manual/actions-file.html b/doc/webserver/user-manual/actions-file.html index 5dceae76..f78109e2 100644 --- a/doc/webserver/user-manual/actions-file.html +++ b/doc/webserver/user-manual/actions-file.html @@ -1,4736 +1,3163 @@ - -
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.} } + + + + + |
Improve privacy by not forwarding the source of the request in the HTTP headers.
Deletes the "X-Forwarded-For:" HTTP header from the client request, - or adds a new one. -
Parameterized.
"block" to delete the header.
"add" to create the header (or append - the client's IP address to an already existing one). -
It is safe and recommended to use block. -
Forwarding the source address of the request may make - sense in some multi-user setups but is also a privacy risk. -
+change-x-forwarded-for{block} |
Rewrite or remove single client headers. -
All client headers to which this action applies are filtered on-the-fly through - the specified regular expression based substitutions. -
Parameterized.
The name of a client-header filter, as defined in one of the - filter files. -
Client-header filters are applied to each header on its own, not to - all at once. This makes it easier to diagnose problems, but on the downside - you can't write filters that only change header x if header y's value is z. - You can do that by using tags though. -
Client-header filters are executed after the other header actions have finished - and use their output as input. -
If the request URL gets changed, Privoxy will detect that and use the new - one. This can be used to rewrite the request destination behind the client's - back, for example to specify a Tor exit relay for certain requests. -
Please refer to the filter file chapter - to learn which client-header filters are available by default, and how to - create your own. -
# Hide Tor exit notation in Host and Referer Headers -{+client-header-filter{hide-tor-exit-notation}} -/ - |
Block requests based on their headers. -
Client headers to which this action applies are filtered on-the-fly through - the specified regular expression based substitutions, the result is used as - tag. -
Parameterized.
The name of a client-header tagger, as defined in one of the - filter files. -
Client-header taggers are applied to each header on its own, - and as the header isn't modified, each tagger "sees" - the original. -
Client-header taggers are the first actions that are executed - and their tags can be used to control every other action. -
# Tag every request with the User-Agent header -{+client-header-tagger{user-agent}} -/ + -# Tagging itself doesn't change the action -# settings, sections with TAG patterns do: -# -# If it's a download agent, use a different forwarding proxy, -# show the real User-Agent and make sure resume works. -{+forward-override{forward-socks5 10.0.0.2:2222 .} \ - -hide-if-modified-since \ - -overwrite-last-modified \ - -hide-user-agent \ - -filter \ - -deanimate-gifs \ -} -TAG:^User-Agent: NetBSD-ftp/ -TAG:^User-Agent: Novell ZYPP Installer -TAG:^User-Agent: RPM APT-HTTP/ -TAG:^User-Agent: fetch libfetch/ -TAG:^User-Agent: Ubuntu APT-HTTP/ -TAG:^User-Agent: MPlayer/ - |
Stop useless download menus from popping up, or change the browser's rendering mode
Replaces the "Content-Type:" HTTP server header. -
Parameterized.
Any string. -
The "Content-Type:" HTTP server header is used by the - browser to decide what to do with the document. The value of this - header can cause the browser to open a download menu instead of - displaying the document by itself, even if the document's format is - supported by the browser. -
The declared content type can also affect which rendering mode - the browser chooses. If XHTML is delivered as "text/html", - many browsers treat it as yet another broken HTML document. - If it is send as "application/xml", browsers with - XHTML support will only display it, if the syntax is correct. -
If you see a web site that proudly uses XHTML buttons, but sets - "Content-Type: text/html", you can use Privoxy - to overwrite it with "application/xml" and validate - the web master's claim inside your XHTML-supporting browser. - If the syntax is incorrect, the browser will complain loudly. -
You can also go the opposite direction: if your browser prints - error messages instead of rendering a document falsely declared - as XHTML, you can overwrite the content type with - "text/html" and have it rendered as broken HTML document. -
By default content-type-overwrite only replaces - "Content-Type:" headers that look like some kind of text. - If you want to overwrite it unconditionally, you have to combine it with - force-text-mode. - This limitation exists for a reason, think twice before circumventing it. -
Most of the time it's easier to replace this action with a custom - server-header filter. - It allows you to activate it for every document of a certain site and it will still - only replace the content types you aimed at. -
Of course you can apply content-type-overwrite - to a whole site and then make URL based exceptions, but it's a lot - more work to get the same precision. -
# Check if www.example.net/ really uses valid XHTML -{ +content-type-overwrite{application/xml} } -www.example.net/ +
|
Remove a client header Privoxy has no dedicated action for.
Deletes every header sent by the client that contains the string the user supplied as parameter. -
Parameterized.
Any string. -
This action allows you to block client headers for which no dedicated - Privoxy action exists. - Privoxy will remove every client header that - contains the string you supplied as parameter. -
Regular expressions are not supported and you can't - use this action to block different headers in the same request, unless - they contain the same string. -
crunch-client-header is only meant for quick tests. - If you have to block several different headers, or only want to modify - parts of them, you should use a - client-header filter. -
Warning |
Don't block any header without understanding the consequences. - |
# Block the non-existent "Privacy-Violation:" client header -{ +crunch-client-header{Privacy-Violation:} } -/ - |
Prevent yet another way to track the user's steps between sessions.
Deletes the "If-None-Match:" HTTP client header. -
Boolean.
N/A -
Removing the "If-None-Match:" HTTP client header - is useful for filter testing, where you want to force a real - reload instead of getting status code "304" which - would cause the browser to use a cached copy of the page. -
It is also useful to make sure the header isn't used as a cookie - replacement (unlikely but possible). -
Blocking the "If-None-Match:" header shouldn't cause any - caching problems, as long as the "If-Modified-Since:" header - isn't blocked or missing as well. -
It is recommended to use this action together with - hide-if-modified-since - and - overwrite-last-modified. -
# Let the browser revalidate cached documents but don't -# allow the server to use the revalidation headers for user tracking. -{+hide-if-modified-since{-60} \ - +overwrite-last-modified{randomize} \ - +crunch-if-none-match} -/ |
Prevent the web server from setting HTTP cookies on your system -
Deletes any "Set-Cookie:" HTTP headers from server replies. -
Boolean.
N/A -
This action is only concerned with incoming HTTP cookies. For - outgoing HTTP cookies, use - crunch-outgoing-cookies. - Use both to disable HTTP cookies completely. -
It makes no sense at all to use this action in conjunction - with the session-cookies-only action, - since it would prevent the session cookies from being set. See also - filter-content-cookies. -
+crunch-incoming-cookies |
Remove a server header Privoxy has no dedicated action for.
Deletes every header sent by the server that contains the string the user supplied as parameter. -
Parameterized.
Any string. -
This action allows you to block server headers for which no dedicated - Privoxy action exists. Privoxy - will remove every server header that contains the string you supplied as parameter. -
Regular expressions are not supported and you can't - use this action to block different headers in the same request, unless - they contain the same string. -
crunch-server-header is only meant for quick tests. - If you have to block several different headers, or only want to modify - parts of them, you should use a custom - server-header filter. -
Warning |
Don't block any header without understanding the consequences. - |
# Crunch server headers that try to prevent caching -{ +crunch-server-header{no-cache} } -/ |
Prevent the web server from reading any HTTP cookies from your system -
Deletes any "Cookie:" HTTP headers from client requests. -
Boolean.
N/A -
This action is only concerned with outgoing HTTP cookies. For - incoming HTTP cookies, use - crunch-incoming-cookies. - Use both to disable HTTP cookies completely. -
It makes no sense at all to use this action in conjunction - with the session-cookies-only action, - since it would prevent the session cookies from being read. -
+crunch-outgoing-cookies |
Stop those annoying, distracting animated GIF images.
De-animate GIF animations, i.e. reduce them to their first or last image. -
Parameterized.
"last" or "first" -
This will also shrink the images considerably (in bytes, not pixels!). If - the option "first" is given, the first frame of the animation - is used as the replacement. If "last" is given, the last - frame of the animation is used instead, which probably makes more sense for - most banner animations, but also has the risk of not showing the entire - last frame (if it is only a delta to an earlier frame). -
You can safely use this action with patterns that will also match non-GIF - objects, because no attempt will be made at anything that doesn't look like - a GIF. -
+deanimate-gifs{last} |
Work around (very rare) problems with HTTP/1.1
Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0. -
Boolean.
N/A -
This is a left-over from the time when Privoxy - didn't support important HTTP/1.1 features well. It is left here for the - unlikely case that you experience HTTP/1.1 related problems with some server - out there. Not all HTTP/1.1 features and requirements are supported yet, - so there is a chance you might need this action. -
{+downgrade-http-version} -problem-host.example.com |
Fool some click-tracking scripts and speed up indirect links.
Detects redirection URLs and redirects the browser without contacting - the redirection server first. -
Parameterized.
"simple-check" to just search for the string "http://" - to detect redirection URLs. -
"check-decoded-url" to decode URLs (if necessary) before searching - for redirection URLs. -
- Many sites, like yahoo.com, don't just link to other sites. Instead, they - will link to some script on their own servers, giving the destination as a - parameter, which will then redirect you to the final target. URLs - resulting from this scheme typically look like: - "http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/". -
Sometimes, there are even multiple consecutive redirects encoded in the - URL. These redirections via scripts make your web browsing more traceable, - since the server from which you follow such a link can see where you go - to. Apart from that, valuable bandwidth and time is wasted, while your - browser asks the server for one redirect after the other. Plus, it feeds - the advertisers. -
This feature is currently not very smart and is scheduled for improvement. - If it is enabled by default, you will have to create some exceptions to - this action. It can lead to failures in several ways: -
Not every URLs with other URLs as parameters is evil. - Some sites offer a real service that requires this information to work. - For example a validation service needs to know, which document to validate. - fast-redirects assumes that every URL parameter that - looks like another URL is a redirection target, and will always redirect to - the last one. Most of the time the assumption is correct, but if it isn't, - the user gets redirected anyway. -
Another failure occurs if the URL contains other parameters after the URL parameter. - The URL: - "http://www.example.org/?redirect=http%3a//www.example.net/&foo=bar". - contains the redirection URL "http://www.example.net/", - followed by another parameter. fast-redirects doesn't know that - and will cause a redirect to "http://www.example.net/&foo=bar". - Depending on the target server configuration, the parameter will be silently ignored - or lead to a "page not found" error. You can prevent this problem by - first using the redirect action - to remove the last part of the URL, but it requires a little effort. -
To detect a redirection URL, fast-redirects only - looks for the string "http://", either in plain text - (invalid but often used) or encoded as "http%3a//". - Some sites use their own URL encoding scheme, encrypt the address - of the target server or replace it with a database id. In theses cases - fast-redirects is fooled and the request reaches the - redirection server where it probably gets logged. -
{ +fast-redirects{simple-check} } - one.example.com + - { +fast-redirects{check-decoded-url} } - another.example.com/testing |
Get rid of HTML and JavaScript annoyances, banner advertisements (by size), - do fun text replacements, add personalized effects, etc.
All instances of text-based type, most notably HTML and JavaScript, to which - this action applies, can be filtered on-the-fly through the specified regular - expression based substitutions. (Note: as of version 3.0.3 plain text documents - are exempted from filtering, because web servers often use the - text/plain MIME type for all files whose type they don't know.) -
Parameterized.
The name of a content filter, as defined in the filter file. - Filters can be defined in one or more files as defined by the - filterfile - option in the config file. - default.filter is the collection of filters - supplied by the developers. Locally defined filters should go - in their own file, such as user.filter. -
When used in its negative form, - and without parameters, all filtering is completely disabled. -
For your convenience, there are a number of pre-defined filters available - in the distribution filter file that you can use. See the examples below for - a list. -
Filtering requires buffering the page content, which may appear to - slow down page rendering since nothing is displayed until all content has - passed the filters. (It does not really take longer, but seems that way - since the page is not incrementally displayed.) This effect will be more - noticeable on slower connections. -
"Rolling your own" - filters requires a knowledge of - "Regular - Expressions" and - "HTML". - This is very powerful feature, and potentially very intrusive. - Filters should be used with caution, and where an equivalent - "action" is not available. -
The amount of data that can be filtered is limited to the - buffer-limit - option in the main config file. The - default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered - data, and all pending data, is passed through unfiltered. -
Inappropriate MIME types, such as zipped files, are not filtered at all. - (Again, only text-based types except plain text). Encrypted SSL data - (from HTTPS servers) cannot be filtered either, since this would violate - the integrity of the secure transaction. In some situations it might - be necessary to protect certain text, like source code, from filtering - by defining appropriate -filter exceptions. -
Compressed content can't be filtered either, unless Privoxy - is compiled with zlib support (requires at least Privoxy 3.0.7), - in which case Privoxy will decompress the content before filtering - it. -
If you use a Privoxy version without zlib support, but want filtering to work on - as much documents as possible, even those that would normally be sent compressed, - you must use the prevent-compression - action in conjunction with filter. -
Content filtering can achieve some of the same effects as the - block - action, i.e. it can be used to block ads and banners. But the mechanism - works quite differently. One effective use, is to block ad banners - based on their size (see below), since many of these seem to be somewhat - standardized. -
Feedback with suggestions for new or - improved filters is particularly welcome! -
The below list has only the names and a one-line description of each - predefined filter. There are more - verbose explanations of what these filters do in the filter file chapter. -
+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse. |
+filter{js-events} # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites). |
+filter{html-annoyances} # Get rid of particularly annoying HTML abuse. |
+filter{content-cookies} # Kill cookies that come in the HTML or JS content. |
+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups). |
+filter{unsolicited-popups} # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability. |
+filter{all-popups} # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability. |
+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective. |
+filter{banners-by-size} # Kill banners by size. |
+filter{banners-by-link} # Kill banners by their links to known clicktrackers. |
+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking). |
+filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap. |
+filter{jumping-windows} # Prevent windows from resizing and moving themselves. |
+filter{frameset-borders} # Give frames a border and make them resizable. |
+filter{demoronizer} # Fix MS's non-standard use of standard charsets. |
+filter{shockwave-flash} # Kill embedded Shockwave Flash objects. |
+filter{quicktime-kioskmode} # Make Quicktime movies saveable. |
+filter{fun} # Text replacements for subversive browsing fun! |
+filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliably. |
+filter{ie-exploits} # Disable some known Internet Explorer bug exploits. |
+filter{site-specifics} # Cure for site-specific problems. Don't apply generally! |
+filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags. |
+filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement. |
+filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation. |
+filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation. |
+filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this. |
Force Privoxy to treat a document as if it was in some kind of text format.
Declares a document as text, even if the "Content-Type:" isn't detected as such. -
Boolean.
N/A -
As explained above, - Privoxy tries to only filter files that are - in some kind of text format. The same restrictions apply to - content-type-overwrite. - force-text-mode declares a document as text, - without looking at the "Content-Type:" first. -
Warning |
Think twice before activating this action. Filtering binary data - with regular expressions can cause file damage. - |
+force-text-mode - |
Change the forwarding settings based on User-Agent or request origin
Overrules the forward directives in the configuration file. -
Multi-value.
"forward ." to use a direct connection without any additional proxies.
"forward 127.0.0.1:8123" to use the HTTP proxy listening at 127.0.0.1 port 8123. -
"forward-socks4a 127.0.0.1:9050 ." to use the socks4a proxy listening at - 127.0.0.1 port 9050. Replace "forward-socks4a" with "forward-socks4" - to use a socks4 connection (with local DNS resolution) instead, use "forward-socks5" - for socks5 connections (with remote DNS resolution). -
"forward-socks4a 127.0.0.1:9050 proxy.example.org:8000" to use the socks4a proxy - listening at 127.0.0.1 port 9050 to reach the HTTP proxy listening at proxy.example.org port 8000. - Replace "forward-socks4a" with "forward-socks4" to use a socks4 connection - (with local DNS resolution) instead, use "forward-socks5" - for socks5 connections (with remote DNS resolution). -
This action takes parameters similar to the - forward directives in the configuration - file, but without the URL pattern. It can be used as replacement, but normally it's only - used in cases where matching based on the request URL isn't sufficient. -
Warning |
Please read the description for the forward directives before - using this action. Forwarding to the wrong people will reduce your privacy and increase the - chances of man-in-the-middle attacks. - If the ports are missing or invalid, default values will be used. This might change - in the future and you shouldn't rely on it. Otherwise incorrect syntax causes Privoxy - to exit. - Use the show-url-info CGI page - to verify that your forward settings do what you thought the do. - |
# Always use direct connections for requests previously tagged as
-# "User-Agent: fetch libfetch/2.0" and make sure
+
+
+
+ 8.5.17. force-text-mode+ +
+
+
+ 8.5.18. forward-override+ +
+
8.5.18. handle-as-empty-document
+ 8.5.19. handle-as-empty-document+ +
+
8.5.19. handle-as-image
+ 8.5.20. handle-as-image+ +
+
8.5.20. hide-accept-language
+ 8.5.21. hide-accept-language+ +
+
8.5.21. hide-content-disposition
+ 8.5.22. hide-content-disposition+ +
+
8.5.22. hide-if-modified-since
+ 8.5.23. hide-if-modified-since+ +
+
8.5.23. hide-from-header
8.5.24. hide-referrer
8.5.25. hide-user-agent
8.5.26. limit-connect
+
+
+ 8.5.24. hide-from-header+ +
+
+
+
+
+ 8.5.25. + hide-referrer+ +
+
+
+
+
+ 8.5.26. hide-user-agent+ +
+
+
+ 8.5.27. + limit-connect+ +
+
8.5.27. prevent-compression
+
+
+ 8.5.28. limit-cookie-lifetime+ +
+
+
+ 8.5.29. prevent-compression+ +
+
8.5.28. overwrite-last-modified
+ 8.5.30. overwrite-last-modified+ +
+
8.5.29. redirect
+ 8.5.31. + redirect+ +
+
8.5.30. server-header-filter
+ 8.5.32. server-header-filter+ +
+
8.5.31. server-header-tagger
+ 8.5.33. server-header-tagger+ +
+
8.5.32. session-cookies-only
8.5.33. set-image-blocker
8.5.34. SummaryNote 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, and other criteria, 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. 8.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 name can contain any character except space, tab, - "=", - "{" and "}", but we strongly - recommend that you only use "a" to "z", - "0" to "9", "+", and "-". - Alias names are not case sensitive, and are not required to start with a - "+" or "-" sign, since they are merely textually - expanded. Aliases can be used throughout the actions file, but they must be - defined in a special section at the top of the file! - And there can only be one such section per actions file. Each actions file may - have its own alias section, and the aliases defined in it are only visible - within that file. There are two main reasons to use aliases: One is to save typing for frequently - used combinations of actions, the other one is a gain in flexibility: If you - decide once how you want to handle shops by defining an alias called - "shop", you can later change your policy on shops in - one place, and your changes will take effect everywhere - in the actions file where the "shop" alias is used. Calling aliases - by their purpose also makes your actions files more readable. Currently, there is one big drawback to using aliases, though: - Privoxy's built-in web-based action file - editor honors aliases when reading the actions files, but it expands - them before writing. So the effects of your aliases are of course preserved, - but the aliases themselves are lost when you edit sections that use aliases - with it. Now let's define some aliases...
+
+
+ 8.5.34. session-cookies-only+ +
+
+
+
+
+ 8.5.35. set-image-blocker+ +
+
+
+
+
+
+ 8.5.36. + Summary+ +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, and other criteria, 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. +
+ 8.6. Aliases+ +Custom "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 name can contain + any character except space, tab, "=", + "{" and "}", but + we strongly + recommend that you only use "a" + to "z", "0" to + "9", "+", and + "-". Alias names are not case sensitive, and + are not required to start with a "+" or + "-" sign, since they are merely textually + expanded. + +Aliases can be used throughout the actions file, but they + must be defined in a special + section at the top of the file! And there can only be one + such section per actions file. Each actions file may have its own alias + section, and the aliases defined in it are only visible within that + file. + +There are two main reasons to use aliases: One is to save typing for + frequently used combinations of actions, the other one is a gain in + flexibility: If you decide once how you want to handle shops by + defining an alias called "shop", you can + later change your policy on shops in one place, and your changes will take effect + everywhere in the actions file where the "shop" alias is used. Calling aliases by their purpose + also makes your actions files more readable. + +Currently, there is one big drawback to using aliases, though: + Privoxy's built-in web-based action + file editor honors aliases when reading the actions files, but it + expands them before writing. So the effects of your aliases are of + course preserved, but the aliases themselves are lost when you edit + sections that use aliases with it. + +Now let's define some aliases... + +
...and put them to use. These sections would appear in the lower part of an - actions file and define exceptions to the default actions (as specified further - up for the "/" pattern):
...and put them to use. These sections would appear in the lower + part of an actions file and define exceptions to the default actions + (as specified further up for the "/" + pattern): + +
Aliases like "shop" and "fragile" are typically used for - "problem" sites that require more than one action to be disabled - in order to function properly. 8.7. Actions Files TutorialThe above chapters have shown which actions files - there are and how they are organized, how actions are specified and applied - to URLs, how patterns work, and how to - define and use aliases. Now, let's look at an - example match-all.action, default.action - and user.action file and see how all these pieces come together: 8.7.1. match-all.actionRemember all actions are disabled when matching starts, - so we have to explicitly enable the ones we want. While the match-all.action file only contains a - single section, it is probably the most important one. It has only one - pattern, "/", but this pattern - matches all URLs. Therefore, the set of - actions used in this "default" section will - be applied to all requests as a start. It can be partly or - wholly overridden by other actions files like default.action - and user.action, but it will still be largely responsible - for your overall browsing experience. Again, at the start of matching, all actions are disabled, so there is - no need to disable any actions here. (Remember: a "+" - preceding the action name enables the action, a "-" disables!). - Also note how this long line has been made more readable by splitting it into - multiple lines with line continuation.
Aliases like "shop" and "fragile" are typically used for "problem" sites that require more than one action to be + disabled in order to function properly. +
+ 8.7. Actions + Files Tutorial+ +The above chapters have shown which + actions files there are and how they are organized, how actions are + specified and applied to URLs, how patterns work, and how to define + and use aliases. Now, let's + look at an example match-all.action, + default.action and user.action file and see how all these pieces come + together: + +
+ 8.7.1. + match-all.action+ +Remember all actions + are disabled when matching starts, so we have to + explicitly enable the ones we want. + +While the match-all.action file only + contains a single section, it is probably the most important one. It + has only one pattern, "/", but this pattern matches all URLs. Therefore, the + set of actions used in this "default" + section will be applied to + all requests as a start. It can be partly or wholly + overridden by other actions files like default.action and user.action, but it will still be largely responsible + for your overall browsing experience. + +Again, at the start of matching, all actions are disabled, so + there is no need to disable any actions here. (Remember: a + "+" preceding the action name enables the + action, a "-" disables!). Also note how + this long line has been made more readable by splitting it into + multiple lines with line continuation. + +
The default behavior is now set. 8.7.2. default.actionIf you aren't a developer, there's no need for you to edit the - default.action file. It is maintained by - the Privoxy developers and if you disagree with some of the - sections, you should overrule them in your user.action. Understanding the default.action file can - help you with your user.action, though. The first section in this file is a special section for internal use - that prevents older Privoxy versions from reading the file:
The default behavior is now set. +
+ 8.7.2. + default.action+ +If you aren't a developer, there's no need for you to edit the + default.action file. It is maintained by + the Privoxy developers and if you + disagree with some of the sections, you should overrule them in your + user.action. + +Understanding the default.action file + can help you with your user.action, + though. + +The first section in this file is a special section for internal + use that prevents older Privoxy + versions from reading the file: + +
After that comes the (optional) alias section. We'll use the example - section from the above chapter on aliases, - that also explains why and how aliases are used:
After that comes the (optional) alias section. We'll use the + example section from the above chapter on aliases, that also + explains why and how aliases are used: + +
The first of our specialized sections is concerned with "fragile" - sites, i.e. sites that require minimum interference, because they are either - very complex or very keen on tracking you (and have mechanisms in place that - make them unusable for people who avoid being tracked). We will simply use - our pre-defined fragile alias instead of stating the list - of actions explicitly:
The first of our specialized sections is concerned with + "fragile" sites, i.e. sites that require + minimum interference, because they are either very complex or very + keen on tracking you (and have mechanisms in place that make them + unusable for people who avoid being tracked). We will simply use our + pre-defined fragile alias instead of stating + the list of actions explicitly: + +
Shopping sites are not as fragile, but they typically - require cookies to log in, and pop-up windows for shopping - carts or item details. Again, we'll use a pre-defined alias:
Shopping sites are not as fragile, but they typically require + cookies to log in, and pop-up windows for shopping carts or item + details. Again, we'll use a pre-defined alias: + +
The fast-redirects - action, which may have been enabled in match-all.action, - breaks some sites. So disable it for popular sites where we know it misbehaves:
The fast-redirects action, + which may have been enabled in match-all.action, breaks some sites. So disable it + for popular sites where we know it misbehaves: + +
It is important that Privoxy knows which - URLs belong to images, so that if they are to - be blocked, a substitute image can be sent, rather than an HTML page. - Contacting the remote site to find out is not an option, since it - would destroy the loading time advantage of banner blocking, and it - would feed the advertisers information about you. We can mark any - URL as an image with the handle-as-image action, - and marking all URLs that end in a known image file extension is a - good start:
It is important that Privoxy + knows which URLs belong to images, so that if they are to be blocked, + a substitute image can be sent, rather than an HTML page. Contacting + the remote site to find out is not an option, since it would destroy + the loading time advantage of banner blocking, and it would feed the + advertisers information about you. We can mark any URL as an image + with the handle-as-image action, + and marking all URLs that end in a known image file extension is a + good start: + +
And then there are known banner sources. They often use scripts to - generate the banners, so it won't be visible from the URL that the - request is for an image. Hence we block them and - mark them as images in one go, with the help of our - +block-as-image alias defined above. (We could of - course just as well use +block - +handle-as-image here.) - Remember that the type of the replacement image is chosen by the - set-image-blocker - action. Since all URLs have matched the default section with its - +set-image-blocker{pattern} - action before, it still applies and needn't be repeated:
And then there are known banner sources. They often use scripts to + generate the banners, so it won't be visible from the URL that the + request is for an image. Hence we block them and mark them as images in + one go, with the help of our +block-as-image + alias defined above. (We could of course just as well use +block +handle-as-image here.) + Remember that the type of the replacement image is chosen by the + set-image-blocker + action. Since all URLs have matched the default section with its + +set-image-blocker{pattern} + action before, it still applies and needn't be repeated: + +
One of the most important jobs of Privoxy - is to block banners. Many of these can be "blocked" - by the filter{banners-by-size} - action, which we enabled above, and which deletes the references to banner - images from the pages while they are loaded, so the browser doesn't request - them anymore, and hence they don't need to be blocked here. But this naturally - doesn't catch all banners, and some people choose not to use filters, so we - need a comprehensive list of patterns for banner URLs here, and apply the - block action to them. First comes many generic patterns, which do most of the work, by - matching typical domain and path name components of banners. Then comes - a list of individual patterns for specific sites, which is omitted here - to keep the example short:
One of the most important jobs of Privoxy is to block banners. Many of these can + be "blocked" by the filter{banners-by-size} action, + which we enabled above, and which deletes the references to banner + images from the pages while they are loaded, so the browser doesn't + request them anymore, and hence they don't need to be blocked here. + But this naturally doesn't catch all banners, and some people choose + not to use filters, so we need a comprehensive list of patterns for + banner URLs here, and apply the block action to them. + +First comes many generic patterns, which do most of the work, by + matching typical domain and path name components of banners. Then + comes a list of individual patterns for specific sites, which is + omitted here to keep the example short: + +
It's quite remarkable how many advertisers actually call their banner - servers ads.company.com, or call the directory - in which the banners are stored simply "banners". So the above - generic patterns are surprisingly effective. But being very generic, they necessarily also catch URLs that we don't want - to block. The pattern .*ads. e.g. catches - "nasty-ads.nasty-corp.com" as intended, - but also "downloads.sourcefroge.net" or - "adsl.some-provider.net." So here come some - well-known exceptions to the +block - section above. Note that these are exceptions to exceptions from the default! Consider the URL - "downloads.sourcefroge.net": Initially, all actions are deactivated, - so it wouldn't get blocked. Then comes the defaults section, which matches the - URL, but just deactivates the block - action once again. Then it matches .*ads., an exception to the - general non-blocking policy, and suddenly - +block applies. And now, it'll match - .*loads., where -block - applies, so (unless it matches again further down) it ends up - with no block action applying.
It's quite remarkable how many advertisers actually call their + banner servers ads.company.com, + or call the directory in which the banners are stored simply + "banners". So the above generic patterns + are surprisingly effective. + +But being very generic, they necessarily also catch URLs that we + don't want to block. The pattern .*ads. e.g. + catches "nasty-ads.nasty-corp.com" as intended, but + also "downloads.sourcefroge.net" or "adsl.some-provider.net." So here come + some well-known exceptions to the +block section above. + +Note that these are exceptions to exceptions from the default! + Consider the URL "downloads.sourcefroge.net": Initially, all actions + are deactivated, so it wouldn't get blocked. Then comes the defaults + section, which matches the URL, but just deactivates the block action + once again. Then it matches .*ads., an + exception to the general non-blocking policy, and suddenly +block applies. + And now, it'll match .*loads., where + -block + applies, so (unless it matches again further down) it ends up with no + block + action applying. + +
Filtering source code can have nasty side effects, - so make an exception for our friends at sourceforge.net, - and all paths with "cvs" in them. Note that - -filter - disables all filters in one fell swoop!
Filtering source code can have nasty side effects, so make an + exception for our friends at sourceforge.net, and all paths with + "cvs" in them. Note that -filter + disables all + filters in one fell swoop! + +
The actual default.action is of course much more - comprehensive, but we hope this example made clear how it works. 8.7.3. user.actionSo far we are painting with a broad brush by setting general policies, - which would be a reasonable starting point for many people. Now, - you might want to be more specific and have customized rules that - are more suitable to your personal habits and preferences. These would - be for narrowly defined situations like your ISP or your bank, and should - be placed in user.action, which is parsed after all other - actions files and hence has the last word, over-riding any previously - defined actions. user.action is also a - safe place for your personal settings, since - default.action is actively maintained by the - Privoxy developers and you'll probably want - to install updated versions from time to time. So let's look at a few examples of things that one might typically do in - user.action:
As aliases are local to the actions - file that they are defined in, you can't use the ones from - default.action, unless you repeat them here:
The actual default.action is of course + much more comprehensive, but we hope this example made clear how it + works. +
+ 8.7.3. + user.action+ +So far we are painting with a broad brush by setting general + policies, which would be a reasonable starting point for many people. + Now, you might want to be more specific and have customized rules + that are more suitable to your personal habits and preferences. These + would be for narrowly defined situations like your ISP or your bank, + and should be placed in user.action, which + is parsed after all other actions files and hence has the last word, + over-riding any previously defined actions. user.action is also a safe place for your + personal settings, since default.action is + actively maintained by the Privoxy + developers and you'll probably want to install updated versions from + time to time. + +So let's look at a few examples of things that one might typically + do in user.action: + +
As aliases are local to + the actions file that they are defined in, you can't use the ones + from default.action, unless you repeat them + here: + +
Say you have accounts on some sites that you visit regularly, and - you don't want to have to log in manually each time. So you'd like - to allow persistent cookies for these sites. The - allow-all-cookies alias defined above does exactly - that, i.e. it disables crunching of cookies in any direction, and the - processing of cookies to make them only temporary.
Say you have accounts on some sites that you visit regularly, and + you don't want to have to log in manually each time. So you'd like to + allow persistent cookies for these sites. The allow-all-cookies alias defined above does exactly + that, i.e. it disables crunching of cookies in any direction, and the + processing of cookies to make them only temporary. + +
Your bank is allergic to some filter, but you don't know which, so you disable them all:
Some file types you may not want to filter for various reasons:
Your bank is allergic to some filter, but you don't know which, so + you disable them all: + +
Some file types you may not want to filter for various + reasons: + +
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:
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: + +
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.
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. + +
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:
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: + +
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:
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:
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: + +
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: + +
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.
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:
|
+
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 ++ |
+