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.} }
# Block these as if they were images. Send no block page.
banners.example.com
media.example.com/.*banners
.example.com/images/ads/ |
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).
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.
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. Forhat 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.} }
# Block these as if they were images. Send no block page.
banners.example.com
media.example.com/.*banners
.example.com/images/ads/ |
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).
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.
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. Forhat 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.} }
# Block these as if they were images. Send no block page.
banners.example.com
media.example.com/.*banners
.example.com/images/ads/ |
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).
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.
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. Forhat 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.} }
# Block these as if they were images. Send no block page.
banners.example.com
media.example.com/.*banners
.example.com/images/ads/ |
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).
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.
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. Forhat 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.} }
# Block these as if they were images. Send no block page.
banners.example.com
media.example.com/.*banners
.example.com/images/ads/ |
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).
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.
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. Forhat 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.} }
# Block these as if they were images. Send no block page.
banners.example.com
media.example.com/.*banners
.example.com/images/ads/ |
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).
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.
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. Forhat 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.} }
# Block these as if they were images. Send no block page.
banners.example.com
media.example.com/.*banners
.example.com/images/ads/ |
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).
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.
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. Forhat 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.} }
# Block these as if they were images. Send no block page.
banners.example.com
media.example.com/.*banners
.example.com/images/ads/ |
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).
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.
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. Forhat 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.} }
# Block these as if they were images. Send no block page.
banners.example.com
media.example.com/.*banners
.example.com/images/ads/ |
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).
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.
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,