X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fuser-manual%2Factions-file.html;h=f8885724ba17a0e4c05f223304387d47439b6fb4;hp=cbffcee712ef30e84850927870b542f02ef159db;hb=07cf496b6edcbd3cf315ec7c48f2c94be27357b1;hpb=c01ca2fed6ffe149fba107a7896d80528dc9fbea diff --git a/doc/webserver/user-manual/actions-file.html b/doc/webserver/user-manual/actions-file.html index cbffcee7..f8885724 100644 --- a/doc/webserver/user-manual/actions-file.html +++ b/doc/webserver/user-manual/actions-file.html @@ -1,504 +1,417 @@ - + + -
- -- Privoxy 3.0.18 User Manual - | -||
---|---|---|
- Prev - | -- | -- Next - | -
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 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: -
--
-
-+ |
+
You can trace this process for URL patterns and any given URL by + visiting http://config.privoxy.org/show-url-info.
+ +Examples and more detail on this is provided in the Appendix, + Troubleshooting: Anatomy of an + Action section.
+As mentioned, Privoxy uses + "patterns" to determine what actions might apply to which sites and + pages your browser attempts to access. These "patterns" use wild card type pattern matching to achieve a high degree + of flexibility. This allows one expression to be expanded and + potentially match against many similar patterns.
+ +Generally, an URL pattern has the form <domain><port>/<path>, where the + <domain>, the <port> and the <path> are optional. (This is why the special + / pattern matches all URLs). Note that the + protocol portion of the URL pattern (e.g. http://) should not be included in the pattern. This is + assumed already!
+ +The pattern matching syntax is different for the domain and path + parts of the URL. The domain part uses a simple globbing type matching + technique, while the path part uses more flexible "Regular Expressions" (POSIX + 1003.2).
-- You can trace this process for URL patterns and any given URL by - visiting http://config.privoxy.org/show-url-info. -
-- Examples and more detail on this is provided in the Appendix, Troubleshooting: Anatomy of an - Action section. -
+The port part of a pattern is a decimal port number preceded by a + colon (:). If the domain part contains a + numerical IPv6 address, it has to be put into angle brackets + (<, >).
+ +is a domain-only pattern and will match any request to + www.example.com, regardless of which + document on that server is requested. So ALL pages in this domain + would be covered by the scope of this action. Note that a simple + example.com is different and would NOT + match.
+means exactly the same. For domain-only patterns, the trailing + / may be omitted.
+matches all the documents on www.example.com whose name starts with /index.html.
+matches only the single document /index.html on www.example.com.
+matches the document /index.html, + regardless of the domain, i.e. on any web server anywhere.
+Matches any URL because there's no requirement for either the + domain or the path to match anything.
+Matches any URL pointing to TCP port 8000.
+Matches any URL with the host address 2001:db8::1. (Note that the real URL uses plain + brackets, not angle brackets.)
+matches nothing, since it would be interpreted as a domain + name and there is no top-level domain called .html. So its a mistake.
+- As mentioned, Privoxy uses "patterns" to determine what actions might apply to - which sites and pages your browser attempts to access. These "patterns" use wild card type pattern matching to - achieve a high degree of flexibility. This allows one expression to - be expanded and potentially match against many similar patterns. -
-- Generally, an URL pattern has the form <domain><port>/<path>, where the - <domain>, the <port> and the <path> are optional. (This is why the special - / pattern matches all URLs). Note that the - protocol portion of the URL pattern (e.g. http://) should not be included in the pattern. This is - assumed already! -
-- The pattern matching syntax is different for the domain and path - parts of the URL. The domain part uses a simple globbing type - matching technique, while the path part uses more flexible "Regular Expressions" (POSIX - 1003.2). -
-- The port part of a pattern is a decimal port number preceded by a - colon (:). If the domain part contains a - numerical IPv6 address, it has to be put into angle brackets (<, >). -
+ +The 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:
+- is a domain-only pattern and will match any request to www.example.com, regardless of which - document on that server is requested. So ALL pages in this - domain would be covered by the scope of this action. Note - that a simple example.com is - different and would NOT match. -
-- means exactly the same. For domain-only patterns, the - trailing / may be omitted. -
-- matches all the documents on www.example.com whose name starts with /index.html. -
-- matches only the single document /index.html on www.example.com. -
-- matches the document /index.html, - regardless of the domain, i.e. on any web server anywhere. -
-- Matches any URL because there's no requirement for either the - domain or the path to match anything. -
-- Matches any URL pointing to TCP port 8000. -
-- Matches any URL with the host address 2001:db8::1. (Note that the real URL uses - plain brackets, not angle brackets.) -
-- matches nothing, since it would be interpreted as a domain - name and there is no top-level domain called .html. So its a mistake. -
+matches any domain with first-level domain com and second-level domain example. For example www.example.com, example.com and foo.bar.baz.example.com. Note that it wouldn't + match if the second-level domain was another-example.
+matches any domain that STARTS with www. (It also matches the domain www but most of the time that doesn't + matter.)
+matches any domain that CONTAINS .example.. And, by the way, also included would + be any files or documents that exist within that domain since + no path limitations are specified. (Correctly speaking: It + matches any FQDN that contains example + as a domain.) This might be www.example.com, news.example.de, or www.example.net/cgi/testing.pl for instance. All + these cases are matched.
- The 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: -
-- matches any domain with first-level domain com and second-level domain example. For example www.example.com, example.com and foo.bar.baz.example.com. Note that it - wouldn't match if the second-level domain was another-example. -
-- matches any domain that STARTS with www. (It also matches the domain www but most of the time that doesn't - matter.) -
-- matches any domain that CONTAINS .example.. And, by the way, also included - would be any files or documents that exist within that - domain since no path limitations are specified. (Correctly - speaking: It matches any FQDN that contains example as a domain.) This might be www.example.com, news.example.de, or www.example.net/cgi/testing.pl for instance. - All these cases are matched. -
-- Additionally, there are wild-cards that you can use in the domain - names themselves. These work similarly to shell globbing type - wild-cards: "*" represents zero or - more arbitrary characters (this is equivalent to the "Regular Expression" based - syntax of ".*"), "?" represents any single character (this is - equivalent to the regular expression syntax of a simple "."), and you can define "character classes" in square brackets which is - similar to the same regular expression technique. All of this can - be freely mixed: -
-- matches "adserver.example.com", - "ads.example.com", etc but not - "sfads.example.com" -
-- matches all of the above, and then some. -
-- matches www.ipix.com, pictures.epix.com, a.b.c.d.e.upix.com etc. -
-- matches www1.example.com, www4.example.cc, wwwd.example.cy, wwwz.example.com etc., but not wwww.example.com. -
-- While flexible, this is not the sophistication of full regular - expression based syntax. -
-- Privoxy uses "modern" POSIX 1003.2 "Regular Expressions" for - matching the path portion (after the slash), and is thus more - flexible. -
-- There is an Appendix with a - brief quick-start into regular expressions, you also might want - to have a look at your operating system's documentation on - regular expressions (try man re_format). -
-- Note that the path pattern is automatically left-anchored at the - "/", i.e. it matches as if it would - start with a "^" (regular expression - speak for the beginning of a line). -
-- 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. -
-- Is equivalent to just ".example.com", since any documents within - that domain are matched with or without the ".*" regular expression. This is redundant -
-- Will match any page in the domain of "example.com" that is named "index.html", and that is part of some path. - For example, it matches "www.example.com/testing/index.html" but NOT - "www.example.com/index.html" - because the regular expression called for at least two - "/'s", thus the path - requirement. It also would match "www.example.com/testing/index_html", - because of the special meta-character ".". -
-- This regular expression is conditional so it will match any - page named "index.html" - regardless of path which in this case can have one or more - "/'s". And this one must contain - exactly ".html" (but does not - have to end with that!). -
-- This regular expression will match any path of "example.com" that contains any of the words - "ads", "banner", "banners" (because of the "?") or "junk". - The path does not have to end in these words, just contain - them. -
-- This is very much the same as above, except now it must end - in either ".jpg", ".jpeg", ".gif" - or ".png". So this one is - limited to common image formats. -
-- There are many, many good examples to be found in default.action, and more tutorials below in Appendix on regular expressions. -
+ +Additionally, there are wild-cards that you can use in the domain + names themselves. These work similarly to shell globbing type + wild-cards: "*" represents zero or more + arbitrary characters (this is equivalent to the "Regular Expression" based + syntax of ".*"), "?" represents any single character (this is + equivalent to the regular expression syntax of a simple "."), and you can define "character classes" in square brackets which is + similar to the same regular expression technique. All of this can be + freely mixed:
+ +matches "adserver.example.com", + "ads.example.com", etc but not + "sfads.example.com"
+matches all of the above, and then some.
+matches www.ipix.com, pictures.epix.com, a.b.c.d.e.upix.com etc.
+matches www1.example.com, + www4.example.cc, wwwd.example.cy, wwwz.example.com etc., but not wwww.example.com.
+- Tag patterns are used to change the applying actions based on the - request's tags. Tags can be created with either the client-header-tagger - or the server-header-tagger - action. -
-- Tag patterns have to start with "TAG:", so Privoxy can tell them apart from URL - patterns. Everything after the colon including white space, is - interpreted as a regular expression with path pattern syntax, - except that tag patterns aren't left-anchored automatically - (Privoxy doesn't silently add a - "^", you have to do it yourself if you - need it). -
-- To match all requests that are tagged with "foo" your pattern line should be "TAG:^foo$", "TAG:foo" - would work as well, but it would also match requests whose tags - contain "foo" somewhere. "TAG: foo" wouldn't work as it requires white - space. -
-- Sections can contain URL and tag patterns at the same time, but - tag patterns are checked after the URL patterns and thus always - overrule them, even if they are located before the URL patterns. -
-- Once a new tag is added, Privoxy checks right away if it's - matched by one of the tag patterns and updates the action - settings accordingly. As a result tags can be used to activate - other tagger actions, as long as these other taggers look for - headers that haven't already be parsed. -
-- For example you could tag client requests which use the POST method, then use this tag to activate - another tagger that adds a tag if cookies are sent, and then use - a block action based on the cookie tag. This allows the outcome - of one action, to be input into a subsequent action. However if - you'd reverse the position of the described taggers, and - activated the method tagger based on the cookie tagger, no method - tags would be created. The method tagger would look for the - request line, but at the time the cookie tag is created, the - request line has already been parsed. -
-- While this is a limitation you should be aware of, this kind of - indirection is seldom needed anyway and even the example doesn't - make too much sense. -
+ +While flexible, this is not the sophistication of full regular + expression based syntax.
+Privoxy uses "modern" POSIX 1003.2 "Regular Expressions" for + matching the path portion (after the slash), and is thus more + flexible.
+ +There is an Appendix with a + brief quick-start into regular expressions, you also might want to + have a look at your operating system's documentation on regular + expressions (try man re_format).
+ +Note that the path pattern is automatically left-anchored at the + "/", i.e. it matches as if it would start + with a "^" (regular expression speak for + the beginning of a line).
+ +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.
+ +Is equivalent to just ".example.com", since any documents within that + domain are matched with or without the ".*" regular expression. This is redundant
+Will match any page in the domain of "example.com" that is named "index.html", and that is part of some path. For + example, it matches "www.example.com/testing/index.html" but NOT + "www.example.com/index.html" because + the regular expression called for at least two "/'s", thus the path requirement. It also would + match "www.example.com/testing/index_html", because of + the special meta-character ".".
+This regular expression is conditional so it will match any + page named "index.html" regardless + of path which in this case can have one or more "/'s". And this one must contain exactly + ".html" (but does not have to end + with that!).
+This regular expression will match any path of "example.com" that contains any of the words + "ads", "banner", "banners" + (because of the "?") or "junk". The path does not have to end in these + words, just contain them.
+This is very much the same as above, except now it must end + in either ".jpg", ".jpeg", ".gif" or + ".png". So this one is limited to + common image formats.
+There are many, many good examples to be found in default.action, and more tutorials below in Appendix on regular expressions.
- All actions are disabled by default, until they are explicitly - enabled somewhere in an actions file. Actions are turned on if - preceded with a "+", and turned off if - preceded with a "-". So a +action means "do that - action", e.g. +block means "please block URLs that match the following - patterns", and -block means "don't block URLs that match the following patterns, - even if +block previously - applied." -
-- Again, actions are invoked by placing them on a line, enclosed in - curly braces and separated by whitespace, like in {+some-action -some-other-action{some-parameter}}, - followed by a list of URL patterns, one per line, to which they - apply. Together, the actions line and the following pattern lines - make up a section of the actions file. -
-- Actions fall into three categories: -
--
-- Boolean, i.e the action can only be "enabled" or "disabled". Syntax: -
--
-
-- +name # enable action name - -name # disable action name + + |
+
- Block ads or other unwanted content -
-- Requests for URLs to which this action applies are blocked, - i.e. the requests are trapped by Privoxy and the requested URL is never - retrieved, but is answered locally with a substitute page - or image, as determined by the handle-as-image, - set-image-blocker, - and handle-as-empty-document - actions. -
-- Parameterized. -
-- A block reason that should be given to the user. -
-- Privoxy sends a special - "BLOCKED" page for requests to - blocked pages. This page contains the block reason given as - parameter, a link to find out why the block action applies, - and a click-through to the blocked content (the latter only - if the force feature is available and enabled). -
-- A very important exception occurs if both block and handle-as-image, - apply to the same request: it will then be replaced by an - image. If set-image-blocker - (see below) also applies, the type of image will be - determined by its parameter, if not, the standard - checkerboard pattern is sent. -
-- It is important to understand this process, in order to - understand how Privoxy - deals with ads and other unwanted content. Blocking is a - core feature, and one upon which various other features - depend. -
-- The filter action can - perform a very similar task, by "blocking" banner images and other content - through rewriting the relevant URLs in the document's HTML - source, so they don't get requested in the first place. - Note that this is a totally different technique, and it's - easy to confuse the two. -
--
-
-+ + + |
+
- 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. -
--
-
-+ + + |
+
- 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. -
--
-
-+ + + |
+
- 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. -
--
-
-+ + + |