X-Git-Url: http://www.privoxy.org/gitweb/%40proxy-info-url%40?a=blobdiff_plain;f=doc%2Fwebserver%2Fuser-manual%2Factions-file.html;h=9963c8851be084015d44a9bde9595925444abd75;hb=7ecdaff4e6e989eaa70d1ffec88c0e5dfbeb19bb;hp=58f50dec614142bcb784d110c6a37ac1b78e1580;hpb=e4446b36c844acb82cc754737b739fd0cdc402ed;p=privoxy.git diff --git a/doc/webserver/user-manual/actions-file.html b/doc/webserver/user-manual/actions-file.html index 58f50dec..9963c885 100644 --- a/doc/webserver/user-manual/actions-file.html +++ b/doc/webserver/user-manual/actions-file.html @@ -7,7 +7,7 @@ NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79">Privoxy 3.0.10 User ManualPrivoxy 3.0.27 User ManualPrivoxy 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). + 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 + 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 +> There are three action files included with Privoxy with - differing purposes: -

-

The list of actions files to be used are defined in the main configuration +> 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. .action). +>). Generally, user.actionuser.action or any other actions file after +> or any other actions file after default.actionPrivoxy upgrades easier.

- Actions can be used to block anything you want, including ads, banners, or +> 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 @@ -531,7 +495,7 @@ CLASS="SECT2" >

8.1. Finding the Right Mix

, 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 + 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

8.2. How to Edit

"Advanced" setting is more aggressive, and will be more likely to cause problems for some sites. - Experienced users only! + Experienced users only!

If you prefer plain text editing to GUIs, you can of course also directly edit the @@ -605,7 +569,7 @@ CLASS="QUOTE" default.action which is richly commented with many +> which is richly commented with many good examples.

{ +>{ +handle-as-imageboth actions to apply. And there may well be - cases where you will want to combine actions together. Such a section then +> 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 8.4. Patterns

- As mentioned, As mentioned, Privoxy uses Generally, an URL pattern has the form <domain>/<path>, where both the +><host><port>/<path>, where the <domain> and <host>, the <port> + and the <path> are - optional. (This is why the special are optional. (This is why the special + / pattern matches all - URLs). Note that the protocol portion of the URL pattern (e.g. - pattern matches all URLs). Note that the protocol + portion of the URL pattern (e.g. http://) should ) should + not be included in - the pattern. This is assumed already!

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 +> The pattern matching syntax is different for the host and path parts of + the URL. The host part uses a simple globbing type matching technique, + while the path part uses more flexible (POSIX 1003.2).

The port part of a pattern is a decimal port number preceded by a colon + (:). If the host 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 is a host-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 + this domain would be covered by the scope of this action. Note that a simple example.com

means exactly the same. For domain-only patterns, the trailing means exactly the same. For host-only patterns, the trailing / may @@ -877,6 +854,55 @@ CLASS="EMPHASIS" >

/

Matches any URL because there's no requirement for either the + domain or the path to match anything. +

:8000/

Matches any URL pointing to TCP port 8000. +

10.0.0.1/

Matches any URL with the host address 10.0.0.1. + (Note that the real URL uses plain brackets, not angle brackets.) +

<2001:db8::1>/

Matches any URL with the host address 2001:db8::1. + (Note that the real URL uses plain brackets, not angle brackets.) +

index.html
.html. So its +>. So its a mistake.

8.4.1. The Domain Pattern8.4.1. The Host Pattern

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. +> The matching of the host part offers some flexible options: if the + host pattern starts or ends with a dot, it becomes unanchored at that end. + The host pattern is often referred to as domain pattern as it is usually + used to match domain names and not IP addresses. For example:

www.example.net/cgi/testing.pl for instance. All these - cases are matched. + cases are matched.

"*" represents zero or more arbitrary characters (this is - equivalent to the + equivalent to the "character classes" in square brackets which is similar to +> 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", a.b.c.d.e.upix.com etc. +> etc.

matches www1.example.com, +>, www4.example.cc, wwwd.example.cy, +>, wwwz.example.comnot +> wwww.example.com

8.4.2. The Path Pattern

"^" (regular expression speak +> (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 + by default, but you can switch to case sensitive at any point in the pattern by using the "(?-i)" Is equivalent to just ".example.com", since any documents +>, since any documents within that domain are matched with or without the ".*""/'s", thus the path - requirement. It also would match +>, thus the path + requirement. It also would match "www.example.com/testing/index_html", because of the +>, because of the special meta-character "."

This regular expression is conditional so it will match any page +> This regular expression is conditional so it will match any page named "index.html" regardless of path which in this case can +> regardless of path which in this case can have one or more "/'s". And this one must contain exactly +>. And this one must contain exactly ".html" (but does not have to end with that!). +> (and end with that!).

, "banner", +>, "banners""junk". The path does not have to end in these words, just contain them. + The path has to contain at least two slashes (including the one at the beginning).

This is very much the same as above, except now it must end in either +> This is very much the same as above, except now it must end in either ".jpg" or ".png". So this +>. 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 expressions8.4.3. The Tag Pattern8.4.3. The Request Tag Pattern

Tag patterns are used to change the applying actions based on the - request's tags. Tags can be created with either the - Request tag patterns are used to change the applying actions based on the + request's tags. Tags can be created based on HTTP headers with either + the client-header-tagger @@ -1374,14 +1403,14 @@ HREF="actions-file.html#SERVER-HEADER-TAGGER" >server-header-tagger action.

Tag patterns have to start with Request tag patterns have to start with "TAG:", so Privoxy - can tell them apart from URL patterns. Everything after the colon + can tell them apart from other 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 ("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 +> Sections can contain URL and request tag patterns at the same time, + but request 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 +> Once a new request tag is added, Privoxy checks right away if it's matched by one + of the request tag patterns and updates the action settings accordingly. As a result + request 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 @@ -1440,6 +1469,122 @@ CLASS="LITERAL" indirection is seldom needed anyway and even the example doesn't make too much sense.

8.4.4. The Negative Request Tag Patterns

To match requests that do not have a certain request tag, specify a negative tag pattern + by prefixing the tag pattern line with either "NO-REQUEST-TAG:" + or "NO-RESPONSE-TAG:" instead of "TAG:".

Negative request tag patterns created with "NO-REQUEST-TAG:" are checked + after all client headers are scanned, the ones created with "NO-RESPONSE-TAG:" + are checked after all server headers are scanned. In both cases all the created + tags are considered.

8.4.5. The Client Tag Pattern

Warning

This is an experimental feature. The syntax is likely to change in future versions.

Client tag patterns are not set based on HTTP headers but based on + the client's IP address. Users can enable them themselves, but the + Privoxy admin controls which tags are available and what their effect + is.

After a client-specific tag has been defined with the + client-specific-tag, + directive, action sections can be activated based on the tag by using a + CLIENT-TAG pattern. The CLIENT-TAG pattern is evaluated at the same priority + as URL patterns, as a result the last matching pattern wins. Tags that + are created based on client or server headers are evaluated later on + and can overrule CLIENT-TAG and URL patterns!

The tag is set for all requests that come from clients that requested + it to be set. Note that "clients" are differentiated by IP address, + if the IP address changes the tag has to be requested again.

Clients can request tags to be set by using the CGI interface http://config.privoxy.org/client-tags.

Example:

# If the admin defined the client-specific-tag circumvent-blocks,
+# and the request comes from a client that previously requested
+# the tag to be set, overrule all previous +block actions that
+# are enabled based on URL to CLIENT-TAG patterns.
+{-block}
+CLIENT-TAG:^circumvent-blocks$
+
+# This section is not overruled because it's located after
+# the previous one.
+{+block{Nobody is supposed to request this.}}
+example.org/blocked-example-page
+block previously applied."

- Again, actions are invoked by placing them on a line, enclosed in curly braces and - separated by whitespace, like in +> 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:

Actions fall into three categories:

  • - Boolean, i.e the action can only be Boolean, i.e the action can only be "enabled" or @@ -1515,8 +1656,7 @@ CLASS="QUOTE" >"disabled". Syntax:

    -

    - Example: Example: +handle-as-image @@ -1561,12 +1698,10 @@ CLASS="LITERAL" >

  • - Parameterized, where some value is required in order to enable this type of action. +> Parameterized, where some value is required in order to enable this type of action. Syntax:

    -

    Note that if the URL matches multiple positive forms of a parameterized action, the last match wins, i.e. the params from earlier matches are simply ignored.

    - Example: Example: +hide-user-agent{Mozilla/5.0 (X11; U; FreeBSD i386; en-US; rv:1.8.1.4) Gecko/20070602 Firefox/2.0.0.4} @@ -1616,8 +1748,7 @@ CLASS="LITERAL" >

  • - Multi-value. These look exactly like parameterized actions, +> Multi-value. These look exactly like parameterized actions, but they behave differently: If the action applies multiple times to the same URL, but with different parameters,

    -

    - Examples: Examples: +add-header{X-Fun-Header: Some text} and @@ -1702,7 +1829,6 @@ CLASS="LITERAL"

If nothing is specified in any actions file, no

Later defined action sections always over-ride earlier ones of the same type. - So exceptions to any rules you make, should come in the latter part of the file (or - in a file that is processed later when using multiple actions files such + So exceptions to any rules you make, should come in the latter part of the file (or + in a file that is processed later when using multiple actions files such as user.actionNotes:

This action may be specified multiple times, in order to define multiple - headers. This is rarely needed for the typical user. If you don't know what +> This action may be specified multiple times, in order to define multiple + headers. This is rarely needed for the typical user. If you don't know what "HTTP headers" are, you definitely don't need to worry about this +> are, you definitely don't need to worry about this one.

Headers added by this action are not modified by other actions. +

Example usage:

+add-header{X-User-Tracking: sucks}
# Add a DNT ("Do not track") header to all requests, +# event to those that already have one. +# +# This is just an example, not a recommendation. +# +# There is no reason to believe that user-tracking websites care +# about the DNT header and depending on the User-Agent, adding the +# header may make user-tracking easier. +{+add-header{DNT: 1}} +/
-

set-image-blocker, and +>, and handle-as-empty-document actions. - +

- A very important exception occurs if A very important exception occurs if both +> blockhandle-as-image, - apply to the same request: it will then be replaced by an image. If + apply to the same request: it will then be replaced by an image. If

It is important to understand this process, in order +> 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 +> deals with + ads and other unwanted content. Blocking is a core feature, and one upon which various other features depend.

Example usage (section):

-

8.5.3. client-header-filter8.5.3. change-x-forwarded-for

Typical use:

Rewrite or remove single client headers. -

Improve privacy by not forwarding the source of the request in the HTTP headers.

Effect:

All client headers to which this action applies are filtered on-the-fly through - the specified regular expression based substitutions. +> Deletes the "X-Forwarded-For:" HTTP header from the client request, + or adds a new one.

Parameter:

The name of a client-header filter, as defined in one of the - filter files. -

  • "block" to delete the header.

  • "add" to create the header (or append + the client's IP address to an already existing one). +

Notes:

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. +> 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. +

Example usage:
+change-x-forwarded-for{block}

8.5.4. client-header-filter

Typical use:

Rewrite or remove single client headers. +

Effect:

All client headers to which this action applies are filtered on-the-fly through + the specified regular expression based substitutions. +

Type:

Multi-value.

Parameter:

The name of a client-header filter, as defined in one of the + filter files. +

Notes:

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, If the request URI gets changed, Privoxy will detect that and use the new @@ -2070,8 +2294,7 @@ HREF="filter-file.html" >

Example usage (section):

# Hide Tor exit notation in Host and Referer Headers {+client-header-filter{hide-tor-exit-notation}} -/ -
-

8.5.4. client-header-tagger8.5.5. client-header-tagger

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. + tag.

Type:

Parameterized.

Multi-value.

Parameter:
Example usage (section):

- 

# Tag all requests with the Range header set
+{+client-header-tagger{range-requests}}
+/
+
+# Disable filtering for the tagged requests.
+#
+# With filtering enabled Privoxy would remove the Range headers
+# to be able to filter the whole response. The downside is that
+# it prevents clients from resuming downloads or skipping over
+# parts of multimedia files.
+{-filter -deanimate-gifs}
+TAG:^RANGE-REQUEST$
+    
# Tag all requests with the client IP address
+#
+# (Technically the client IP address isn't included in the
+# client headers but client-header taggers can set it anyway.
+# For details see the tagger in default.filter)
+{+client-header-tagger{client-ip-address}}
+/
+
+# Change forwarding settings for requests coming from address 10.0.0.1
+{+forward-override{forward-socks5 127.0.1.2:2222 .}}
+TAG:^IP-ADDRESS: 10\.0\.0\.1$
+
8.5.5. content-type-overwrite8.5.6. content-type-overwrite

Parameter:

Any string. +> Any string.

The declared content type can also affect which rendering mode @@ -2280,7 +2544,7 @@ CLASS="QUOTE" >"application/xml" and validate the web master's claim inside your XHTML-supporting browser. - If the syntax is incorrect, the browser will complain loudly. + If the syntax is incorrect, the browser will complain loudly.

You can also go the opposite direction: if your browser prints @@ -2289,7 +2553,7 @@ CLASS="QUOTE" "text/html" and have it rendered as broken HTML document. +> and have it rendered as broken HTML document.

By default content-type-overwrite to a whole site and then make URL based exceptions, but it's a lot - more work to get the same precision. + more work to get the same precision.

Example usage (sections):

-

8.5.6. crunch-client-header8.5.7. crunch-client-header

Example usage (section):

# Block the non-existent "Privacy-Violation:" client header 
+># Block the non-existent "Privacy-Violation:" client header
 { +crunch-client-header{Privacy-Violation:} }
 /
-

8.5.7. crunch-if-none-match8.5.8. crunch-if-none-match

Example usage (section):

-

8.5.8. crunch-incoming-cookies8.5.9. crunch-incoming-cookies

session-cookies-only action, - since it would prevent the session cookies from being set. See also + since it would prevent the session cookies from being set. See also
Example usage:

-

8.5.9. crunch-server-header8.5.10. crunch-server-header

Example usage (section):

-

8.5.10. crunch-outgoing-cookies8.5.11. crunch-outgoing-cookies

Example usage:

-

8.5.11. deanimate-gifs8.5.12. deanimate-gifs

Example usage:

-

8.5.12. downgrade-http-version8.5.13. downgrade-http-version

Privoxy didn't support important HTTP/1.1 features well. It is left here for the - unlikely case that you experience HTTP/1.1 related problems with some server - out there. Not all HTTP/1.1 features and requirements are supported yet, - so there is a chance you might need this action. + unlikely case that you experience HTTP/1.1-related problems with some server + out there. +

Note that enabling this action is only a workaround. It should not + be enabled for sites that work without it. While it shouldn't break + any pages, it has an (usually negative) performance impact. +

If you come across a site where enabling this action helps, please report it, + so the cause of the problem can be analyzed. If the problem turns out to be + caused by a bug in Privoxy it should be + fixed so the following release works without the work around.

Example usage (section):

8.5.14. external-filter

Typical use:

Modify content using a programming language of your choice.

Effect:

All instances of text-based type, most notably HTML and JavaScript, to which + this action applies, can be filtered on-the-fly through the specified external + filter. + By default plain text documents are exempted from filtering, because web + servers often use the text/plain MIME type for all files + whose type they don't know.) +

Type:

Multi-value.

Parameter:

The name of an external content filter, as defined in the + filter file. + External filters can be defined in one or more files as defined by the + filterfile + option in the config file. +

When used in its negative form, + and without parameters, all filtering with external + filters is completely disabled. +

Notes:

External filters are scripts or programs that can modify the content in + case common filters + aren't powerful enough. With the exception that this action doesn't + use pcrs-based filters, the notes in the + filter section apply. +

Warning

Currently external filters are executed with Privoxy's privileges. + Only use external filters you understand and trust.

This feature is experimental, the syntax + may change in the future. +

Example usage:
+external-filter{fancy-filter}
8.5.13. fast-redirects8.5.15. fast-redirects

Notes:

- Many sites, like yahoo.com, don't just link to other sites. Instead, they +> Many sites, like yahoo.com, don't just link to other sites. Instead, they will link to some script on their own servers, giving the destination as a parameter, which will then redirect you to the final target. URLs resulting from this scheme typically look like: @@ -3236,7 +3643,7 @@ CLASS="QUOTE" >

This feature is currently not very smart and is scheduled for improvement. If it is enabled by default, you will have to create some exceptions to - this action. It can lead to failures in several ways: + this action. It can lead to failures in several ways:

Not every URLs with other URLs as parameters is evil. @@ -3308,8 +3715,7 @@ CLASS="LITERAL" >

Example usage:

 { +fast-redirects{simple-check} }
-   one.example.com 
+   one.example.com
 
  { +fast-redirects{check-decoded-url} }
    another.example.com/testing
-

8.5.14. filter8.5.16. filter

Typical use:

Get rid of HTML and JavaScript annoyances, banner advertisements (by size), +>Get rid of HTML and JavaScript annoyances, banner advertisements (by size), do fun text replacements, add personalized effects, etc.

Type:

Parameterized.

Multi-value.

Parameter:
filter file. - Filters can be defined in one or more files as defined by the + Filters can be defined in one or more files as defined by the config file. +>. default.filter is the collection of filters - supplied by the developers. Locally defined filters should go +> is the collection of filters + supplied by the developers. Locally defined filters should go in their own file, such as user.filterNotes:

For your convenience, there are a number of pre-defined filters available +> For your convenience, there are a number of pre-defined filters available in the distribution filter file that you can use. See the examples below for a list.

Filtering requires buffering the page content, which may appear to slow down page rendering since nothing is displayed until all content has - passed the filters. (It does not really take longer, but seems that way - since the page is not incrementally displayed.) This effect will be more - noticeable on slower connections. + passed the filters. (The total time until the page is completely rendered + doesn't change much, but it may be perceived as slower since the page is + not incrementally displayed.) + This effect will be more noticeable on slower connections.

"Rolling your own" - filters requires a knowledge of + filters requires a knowledge of "Regular Expressions" and +> and "HTML". - This is very powerful feature, and potentially very intrusive. + This is very powerful feature, and potentially very intrusive. Filters should be used with caution, and where an equivalent is not available.

The amount of data that can be filtered is limited to the +> The amount of data that can be filtered is limited to the config file. The +>. The default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered - data, and all pending data, is passed through unfiltered. + data, and all pending data, is passed through unfiltered.

Inappropriate MIME types, such as zipped files, are not filtered at all. @@ -3485,19 +3890,16 @@ CLASS="LITERAL" > exceptions.

Compressed content can't be filtered either, unless Compressed content can't be filtered either, but if Privoxy - is compiled with zlib support (requires at least Privoxy 3.0.7), - in which case Privoxy will decompress the content before filtering - it. +> can first decompress the content + and then filter it.

If you use a .

Content filtering can achieve some of the same effects as the +> Content filtering can achieve some of the same effects as the block - action, i.e. it can be used to block ads and banners. But the mechanism - works quite differently. One effective use, is to block ad banners - based on their size (see below), since many of these seem to be somewhat + action, i.e. it can be used to block ads and banners. But the mechanism + works quite differently. One effective use, is to block ad banners + based on their size (see below), since many of these seem to be somewhat standardized.

the Predefined Filters section for +> for more explanation on each:

-
-

- 
+filter{js-events}           # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).
+filter{js-events} # Kill JavaScript event bindings and timers (Radically destructive! Only for extra nasty sites).
-

-
-

-
-

- 
+filter{refresh-tags}        # Kill automatic refresh tags (for dial-on-demand setups).
+filter{refresh-tags} # Kill automatic refresh tags if refresh time is larger than 9 seconds.
-

- 
+filter{unsolicited-popups}  # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.
+filter{unsolicited-popups} # Disable only unsolicited pop-up windows.
-

- 
+filter{all-popups}          # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.
+filter{all-popups} # Kill all popups in JavaScript and HTML.
-

-
-

-
-

-
-

-
-

-
-

-
-

- 

+filter{iframes}             # Removes all detected iframes. Should only be enabled for individual sites.

-
-

-
-

-
-

-
-

-
-

-
-

-
-

-
-

-
-

-
-

-
-

-
-

8.5.15. force-text-mode8.5.17. force-text-mode

Example usage:

-

8.5.16. forward-override8.5.18. forward-override

Type:

Multi-value.

Parameterized.

Parameter:
to use a socks4 connection (with local DNS resolution) instead, use "forward-socks5" - for socks5 connections (with remote DNS resolution). +>"forward-socks5" + for socks5 connections (with remote DNS resolution). +

  • "forward-webserver 127.0.0.1:80" to use the HTTP + server listening at 127.0.0.1 port 80 without adjusting the + request headers. +

    This makes it more convenient to use Privoxy to make + existing websites available as onion services as well. +

    Many websites serve content with hardcoded URLs and + can't be easily adjusted to change the domain based + on the one used by the client. +

    Putting Privoxy between Tor and the webserver (or an stunnel + that forwards to the webserver) allows to rewrite headers and + content to make client and server happy at the same time. +

    Using Privoxy for webservers that are only reachable through + onion addresses and whose location is supposed to be secret + is not recommended and should not be necessary anyway.

    • If the ports are missing or invalid, default values will be used. This might change in the future and you shouldn't rely on it. Otherwise incorrect syntax causes Privoxy - to exit. + to exit. Due to design limitations, invalid parameter syntax isn't detected until the + action is used the first time.

    Use the

    Example usage:

    # Always use direct connections for requests previously tagged as
+># Use an ssh tunnel for requests previously tagged as
 # "User-Agent: fetch libfetch/2.0" and make sure
 # resuming downloads continues to work.
+#
 # This way you can continue to use Tor for your normal browsing,
 # without overloading the Tor network with your FreeBSD ports updates
 # or downloads of bigger files like ISOs.
+#
 # Note that HTTP headers are easy to fake and therefore their
 # values are as (un)trustworthy as your clients and users.
-{+forward-override{forward .} \
+{+forward-override{forward-socks5 10.0.0.2:2222 .} \
  -hide-if-modified-since      \
  -overwrite-last-modified     \
 }
@@ -4376,8 +4798,6 @@ TAG:^User-Agent: fetch libfetch/2\.0$
 >
    -

    8.5.17. handle-as-empty-document8.5.19. handle-as-empty-document

    Example usage:

    # Block all documents on example.org that end with ".js",
-# but send an empty document instead of the usual HTML message. 
+# but send an empty document instead of the usual HTML message.
 {+block{Blocked JavaScript} +handle-as-empty-document}
 example.org/.*\.js$
    -

    8.5.18. handle-as-image8.5.20. handle-as-image

    default.action    . It marks all URLs with well-known image file name extensions as images and should - be left intact. + be left intact.

    Users will probably only want to use the handle-as-image action in conjunction with @@ -4611,8 +5028,7 @@ CLASS="LITERAL" >

    Example usage (sections):

    -

    8.5.19. hide-accept-language8.5.21. hide-accept-language

    Example usage (section):

    -

    8.5.20. hide-content-disposition8.5.22. hide-content-disposition

    Example usage:

    -

    8.5.21. hide-if-modified-since8.5.23. hide-if-modified-since

    Deletes the "If-Modified-Since:" HTTP client header or modifies its value. +> HTTP client header or modifies its value.

    Example usage (section):

    -

    8.5.22. hide-forwarded-for-headers

    Typical use:

    Improve privacy by not forwarding the source of the request in the HTTP headers.

    Effect:

    Deletes any existing "X-Forwarded-for:" HTTP header from client requests. -

    Type:

    Boolean.

    Parameter:

    N/A -

    Notes:

    It is safe and recommended to leave this on. -

    Example usage:

    +hide-forwarded-for-headers
    -

    8.5.23. hide-from-header8.5.24. hide-from-header

    The keyword "block" will completely remove the header +> will completely remove the header (not to be confused with the
    Example usage:

    or -

    or

    -

    8.5.24. hide-referrer8.5.25. hide-referrer

    - hide-referer is an alternate spelling of @@ -5322,14 +5653,13 @@ CLASS="QUOTE" requires it to be spelled as "referer".) +>.)

    Example usage:

    or -

    or

    -

    8.5.25. hide-user-agent8.5.26. hide-user-agent

    NOT the right thing to do: good web sites - work browser-independently). + work browser-independently).

    . In single-user, single-browser setups, you might use it to delete your OS version information from the headers, because it is an invitation to exploit known bugs for your - OS. It is also occasionally useful to forge this in order to access - sites that won't let you in otherwise (though there may be a good - reason in some cases). Example of this: some MSN sites will not - let Mozilla enter, yet forging to a - Netscape 6.1 user-agent works just fine. - (Must be just a silly MS goof, I'm sure :-). + OS. It is also occasionally useful to forge this in order to access + sites that won't let you in otherwise (though there may be a good + reason in some cases).

    More information on known user-agent strings can be found at +> More information on known user-agent strings can be found at http://www.user-agents.org/ - and + and

    Example usage:

    -

    8.5.26. limit-connect8.5.27. limit-connect

    Example usages:

    +>

    8.5.28. limit-cookie-lifetime

    Typical use:

    Limit the lifetime of HTTP cookies to a couple of minutes or hours.

    Effect:

    Overwrites the expires field in Set-Cookie server headers if it's above the specified limit. +

    Type:

    Parameterized.

    Parameter:

    The lifetime limit in minutes, or 0. +

    Notes:

    This action reduces the lifetime of HTTP cookies coming from the + server to the specified number of minutes, starting from the time + the cookie passes Privoxy. +

    Cookies with a lifetime below the limit are not modified. + The lifetime of session cookies is set to the specified limit. +

    The effect of this action depends on the server. +

    In case of servers which refresh their cookies with each response + (or at least frequently), the lifetime limit set by this action + is updated as well. + Thus, a session associated with the cookie continues to work with + this action enabled, as long as a new request is made before the + last limit set is reached.

    However, some servers send their cookies once, with a lifetime of several + years (the year 2037 is a popular choice), and do not refresh them + until a certain event in the future, for example the user logging out. + In this case this action may limit the absolute lifetime of the session, + even if requests are made frequently. +

    If the parameter is "0", this action behaves like + session-cookies-only. +

    Example usages:
    +limit-cookie-lifetime{60}
    8.5.27. prevent-compression8.5.29. prevent-compression

    Most text-based instances compress very well, the size is seldom decreased by less than 50%, for markup-heavy instances like news feeds saving more than 90% of the original size isn't - unusual. + unusual.

    Not using compression will therefore slow down the transfer, and you should only @@ -5721,8 +6137,7 @@ CLASS="LITERAL" >

    Example usage (sections):

    -

    8.5.28. overwrite-last-modified8.5.30. overwrite-last-modified

    Deletes the "Last-Modified:" HTTP server header or modifies its value. +> HTTP server header or modifies its value.

    "Randomize" - makes it impossible and the browser can still revalidate cached documents. + makes it impossible and the browser can still revalidate cached documents.

    hided-if-modified-sincehide-if-modified-since to further customize your random range. @@ -5881,7 +6294,7 @@ HREF="actions-file.html#HIDE-IF-MODIFIED-SINCE" >hided-if-modified-since, - just to be sure. + just to be sure.

    It is also recommended to use this action together with @@ -5897,8 +6310,7 @@ HREF="actions-file.html#CRUNCH-IF-NONE-MATCH" >

    Example usage:

    -

    8.5.29. redirect8.5.31. redirect

    This action will be ignored if you use it together with +> The syntax for pcrs commands is documented in the + filter file section. +

    Requests can't be blocked and redirected at the same time, + applying this action together with block. - It can be combined with +> + is a configuration error. Currently the request is blocked + and an error message logged, the behavior may change in the + future and result in Privoxy rejecting the action file. +

    This action can be combined with

    Example usages:

    Privoxy) -{ +redirect{http://www.privoxy.org/user-manual/actions-file.html} } +{ +redirect{https://www.privoxy.org/user-manual/actions-file.html} } a # Always use the expanded view for Undeadly.org articles @@ -6040,6 +6462,19 @@ undeadly.org/cgi\?action=article&sid=\d*$ {+redirect{s@^http://[^/]*/results\.aspx\?q=([^&]*).*@http://search.yahoo.com/search?p=$1@}} search.msn.com//results\.aspx\?q= +# Redirect http://example.com/&bla=fasel&toChange=foo (and any other value but "bar") +# to http://example.com/&bla=fasel&toChange=bar +# +# The URL pattern makes sure that the following request isn't redirected again. +{+redirect{s@toChange=[^&]+@toChange=bar@}} +example.com/.*toChange=(?!bar) + +# Add a shortcut to look up illumos bugs +{+redirect{s@^http://i([0-9]+)/.*@https://www.illumos.org/issues/$1@}} +# Redirected URL = http://i4974/ +# Redirect Destination = https://www.illumos.org/issues/4974 +i[0-9][0-9][0-9][0-9]*/ + # Redirect remote requests for this manual # to the local version delivered by Privoxy {+redirect{s@^http://www@http://config@}} @@ -6047,8 +6482,6 @@ www.privoxy.org/user-manual/
    -

    8.5.30. server-header-filter8.5.32. server-header-filter

    Type:

    Parameterized.

    Multi-value.

    Parameter:
    Example usage (section):

    -

    8.5.31. server-header-tagger8.5.33. server-header-tagger

    Type:

    Parameterized.

    Multi-value.

    Parameter:
    Example usage (section):

    # Tag every request with the content type declared by the server {+server-header-tagger{content-type}} / - silly example. +{+external-filter{rotate-image} +force-text-mode} +TAG:^image/
    -

    8.5.32. session-cookies-only8.5.34. session-cookies-only

    only). +>).

    crunch-incoming-cookies / +> / session-cookies-only and will forget about them between sessions. This makes profiling cookies useless, but won't break sites which require cookies so - that you can log in for transactions. This is generally turned on for all + that you can log in for transactions. This is generally turned on for all sites, and is the recommended setting.

    Privoxy also uses +> also uses the content-cookies filter - to block some types of cookies. Content cookies are not effected by +> + to block some types of cookies. Content cookies are not effected by session-cookies-only

    Example usage:

    +session-cookies-only
    -

    8.5.33. set-image-blocker8.5.35. set-image-blocker

    "file:///" URL. +> URL. (But note that not all browsers support redirecting to a local file system).

    Built-in pattern:

    -

    Redirect to the BSD daemon:

    -

    Redirect to the built-in pattern for better caching:

    -

    8.5.34. Summary8.5.36. Summary

    Note that many of these actions have the potential to cause a page to - misbehave, possibly even not to display at all. There are many ways - a site designer may choose to design his site, and what HTTP header + misbehave, possibly even not to display at all. There are many ways + a site designer may choose to design his site, and what HTTP header content, and other criteria, he may depend on. There is no way to have hard and fast rules for all sites. See the strongly +>strongly recommend that you only use

    Now let's define some aliases...

    ...and put them to use. These sections would appear in the lower part of an +> ...and put them to use. These sections would appear in the lower part of an actions file and define exceptions to the default actions (as specified further up for the "/" pattern):

    Aliases like and "fragile" are typically used for +> are typically used for "problem" sites that require more than one action to be disabled +> sites that require more than one action to be disabled in order to function properly.

    . Now, let's look at an example match-all.action, default.action and + and user.action - file and see how all these pieces come together:

    file and see how all these pieces come together:

    8.7.1. default.action8.7.1. match-all.action

    Every config file should start with a short comment stating its purpose:

    Remember all actions are disabled when matching starts, + so we have to explicitly enable the ones we want.

    While the match-all.action file only contains a + single section, it is probably the most important one. It has only one + pattern, "/", but this pattern + matches all URLs. Therefore, the set of + actions used in this "default" section will + be applied to all requests as a start. It can be partly or + wholly overridden by other actions files like default.action + and user.action, but it will still be largely responsible + for your overall browsing experience.

    Again, at the start of matching, all actions are disabled, so there is + no need to disable any actions here. (Remember: a "+" + preceding the action name enables the action, a "-" disables!). + Also note how this long line has been made more readable by splitting it into + multiple lines with line continuation.

    # Sample default.action file <ijbswa-developers@lists.sourceforge.net>
    { \ + +change-x-forwarded-for{block} \ + +hide-from-header{block} \ + +set-image-blocker{pattern} \ +} +/ # Match all URLs +

    Then, since this is the The default behavior is now set.

    8.7.2. default.action

    If you aren't a developer, there's no need for you to edit the + default.action file. It is maintained by + the Privoxy developers and if you disagree with some of the + sections, you should overrule them in your user.action.

    Understanding the default.action file, the -first section is a special section for internal use that you needn't -change or worry about:

    file can + help you with your user.action, though.

    The first section in this file is a special section for internal use + that prevents older Privoxy versions from reading the file:

    ########################################################################## # Settings -- Don't change! For internal Privoxy use ONLY. ########################################################################## - {{settings}} -for-privoxy-version=3.0

    After that comes the (optional) alias section. We'll use the example -section from the above After that comes the (optional) alias section. We'll use the example + section from the above chapter on aliases, -that also explains why and how aliases are used:

    Now come the regular sections, i.e. sets of actions, accompanied - by URL patterns to which they apply. Remember all actions - are disabled when matching starts, so we have to explicitly - enable the ones we want.

    The first regular section is probably the most important. It has only - one pattern, "/", but this pattern - matches all URLs. Therefore, the - set of actions used in this "default" section will - be applied to all requests as a start. It can be partly or - wholly overridden by later matches further down this file, or in user.action, - but it will still be largely responsible for your overall browsing - experience.

    Again, at the start of matching, all actions are disabled, so there is - no need to disable any actions here. (Remember: a "+" - preceding the action name enables the action, a "-" disables!). - Also note how this long line has been made more readable by splitting it into - multiple lines with line continuation.

    ##########################################################################
-# "Defaults" section:
-##########################################################################
- { \
- +deanimate-gifs \
- +filter{html-annoyances} \
- +filter{refresh-tags} \
- +filter{webbugs} \
- +filter{ie-exploits} \     
- +hide-forwarded-for-headers \
- +hide-from-header{block} \
- +hide-referrer{forge} \
- +prevent-compression \
- +session-cookies-only \
- +set-image-blocker{pattern} \
- }
- / # forward slash will match *all* potential URL patterns.

    The default behavior is now set. -

    The first of our specialized sections is concerned with sites, i.e. sites that require minimum interference, because they are either very complex or very keen on tracking you (and have mechanisms in place that - make them unusable for people who avoid being tracked). We will simply use + make them unusable for people who avoid being tracked). We will use our pre-defined fragile alias instead of stating the list of actions explicitly:

    Shopping sites are not as fragile, but they typically require cookies to log in, and pop-up windows for shopping carts or item details. Again, we'll use a pre-defined alias:

    # Shopping sites: # { shop } -.quietpc.com +.quietpc.com .worldpay.com # for quietpc.com .jungle.com .scan.co.uk

    The fast-redirects - action, which we enabled per default above, breaks some sites. So disable - it for popular sites where we know it misbehaves:

    match-all.action, + breaks some sites. So disable it for popular sites where we know it misbehaves:

    It is important that and - information). We can mark any URL as an image with the action, and marking all URLs that end in a known image file extension is a good start:

    And then there are known banner sources. They often use scripts to generate the banners, so it won't be visible from the URL that the @@ -7402,8 +7799,7 @@ HREF="actions-file.html#SET-IMAGE-BLOCKER" >{pattern} action before, it still applies and needn't be repeated:

    # Known ad generators: # { +block-as-image } -ar.atwola.com +ar.atwola.com .ad.doubleclick.net .ad.*.doubleclick.net .a.yimg.com/(?:(?!/i/).)*$ @@ -7424,7 +7820,6 @@ bs*.gsanet.com >

    One of the most important jobs of

    } # Generic patterns: -# +# ad*. .*ads. banner?. @@ -7490,7 +7884,6 @@ count*. >

    It's quite remarkable how many advertisers actually call their banner servers ads.company.com, or call the directory - in which the banners are stored simply "banners". So the above @@ -7509,7 +7902,7 @@ CLASS="QUOTE" to block. The pattern .*ads. e.g. catches +> e.g. catches "nasty-block action applying.

    block

    Filtering source code can have nasty side effects, so make an exception for our friends at sourceforge.net, @@ -7657,8 +8048,7 @@ CLASS="EMPHASIS" >all filters in one fell swoop!

    The actual

    8.7.2. user.action8.7.3. user.action

    So far we are painting with a broad brush by setting general policies, - which would be a reasonable starting point for many people. Now, + which would be a reasonable starting point for many people. Now, you might want to be more specific and have customized rules that are more suitable to your personal habits and preferences. These would be for narrowly defined situations like your ISP or your bank, and should be placed in user.action, which is parsed after all other +>, which is parsed after all other actions files and hence has the last word, over-riding any previously defined actions. user.action is also a +> is also a user.action:

    :

    As default.action, unless you repeat them here:

    Say you have accounts on some sites that you visit regularly, and you don't want to have to log in manually each time. So you'd like @@ -7818,10 +8203,9 @@ HREF="actions-file.html#HIDE-CONTENT-DISPOSITION" CLASS="LITERAL" >allow-all-cookies alias defined above does exactly - that, i.e. it disables crunching of cookies in any direction, and the + that, i.e. it disables crunching of cookies in any direction, and the processing of cookies to make them only temporary.

    Your bank is allergic to some filter, but you don't know which, so you disable them all:

    Some file types you may not want to filter for various reasons:

    Example of a simple "copy image location" - and pasted the URL below while removing the leading http://, into a + and pasted the URL below while removing the leading http://, into a { +block{} }.gif will be tagged as images by the general rules as set in default.action anyway:

    The URLs of dynamically generated banners, especially from large banner farms, often don't use the well-known image file name extensions, which @@ -7933,7 +8310,7 @@ HREF="actions-file.html#BLOCK" CLASS="APPLICATION" >Privoxy to guess - the file type just by looking at the URL. + the file type just by looking at the URL. You can use the +block-as-image"broken image" icon by the browser. Use cautiously.

    Now you noticed that the default configuration breaks Forbes Magazine, but you were too lazy to find out which action is the culprit, and you @@ -7989,9 +8364,8 @@ CLASS="LITERAL" CLASS="APPLICATION" >Privoxy - that is causing the problem or not. We later find other regular sites + that is causing the problem or not. We later find other regular sites that misbehave, and add those to our personalized list of troublemakers:

    You like the

    Note that the above is not really a good idea: There are exceptions to the filters in

    Note that allow-ads has been aliased to +> has been aliased to -block, +>, -filter{banners-by-size}, and +>, and - Invoke another alias here to force an over-ride of the MIME type application/x-sh which typically would open a download type +> which typically would open a download type dialog. In my case, I want to look at the shell script, and then I can save it should I choose to.

    "/" of course matches all URL paths and patterns: