NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
-TITLE="Privoxy 3.0.7 User Manual"
+TITLE="Privoxy 3.0.27 User Manual"
HREF="index.html"><LINK
REL="PREVIOUS"
TITLE="The Main Configuration File"
HREF="filter-file.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
-HREF="../p_doc.css">
+HREF="../p_doc.css"><META
+HTTP-EQUIV="Content-Type"
+CONTENT="text/html;
+charset=ISO-8859-1">
<LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css">
</head
><BODY
><TH
COLSPAN="3"
ALIGN="center"
->Privoxy 3.0.7 User Manual</TH
+>Privoxy 3.0.27 User Manual</TH
></TR
><TR
><TD
>Privoxy</SPAN
> 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.</P
><P
-> There
+> There
are three action files included with <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
> with
- differing purposes:
- </P
+ differing purposes:</P
><P
-> <P
></P
><UL
><LI
><P
-> <TT
+> <TT
+CLASS="FILENAME"
+>match-all.action</TT
+> - is used to define which
+ <SPAN
+CLASS="QUOTE"
+>"actions"</SPAN
+> 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
+ </P
+></LI
+><LI
+><P
+> <TT
CLASS="FILENAME"
>default.action</TT
-> - is the primary action file
- that sets the initial values for all actions. It is intended to
- provide a base level of functionality for
- <SPAN
-CLASS="APPLICATION"
->Privoxy's</SPAN
-> array of features. So it is
- a set of broad rules that should work reasonably well as-is for most users.
- This is the file that the developers are keeping updated, and <A
-HREF="installation.html#INSTALLATION-KEEPUPDATED"
->making available to users</A
->.
- The user's preferences as set in <TT
+> - defines many exceptions (both
+ positive and negative) from the default set of actions that's configured
+ in <TT
CLASS="FILENAME"
->standard.action</TT
->,
- e.g. either <TT
-CLASS="LITERAL"
->Cautious</TT
-> (the default),
- <TT
-CLASS="LITERAL"
->Medium</TT
->, or <TT
-CLASS="LITERAL"
->Advanced</TT
-> (see
- below).
- </P
+>match-all.action</TT
+>. 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.
+ </P
></LI
><LI
><P
-> <TT
+> <TT
CLASS="FILENAME"
>user.action</TT
-> - 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.
- </P
+> - 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.
+ </P
></LI
><LI
><P
-> <TT
-CLASS="FILENAME"
->standard.action</TT
-> - is used only by the web based editor
- at <A
-HREF="http://config.privoxy.org/edit-actions-list?f=default"
-TARGET="_top"
-> http://config.privoxy.org/edit-actions-list?f=default</A
->,
- to set various pre-defined sets of rules for the default actions section
- in <TT
-CLASS="FILENAME"
->default.action</TT
->.
- </P
-><P
-> <SPAN
+> <SPAN
CLASS="GUIBUTTON"
>Edit</SPAN
> <SPAN
CLASS="GUIBUTTON"
>Set to Advanced</SPAN
>
- </P
+ </P
><P
-> These have increasing levels of aggressiveness <SPAN
+> These have increasing levels of aggressiveness <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>and have no
- influence on your browsing unless you select them explicitly in the
- editor</I
+ influence on your browsing unless you select them explicitly in the
+ editor</I
></SPAN
->. A default installation should be pre-set to
- <TT
+>. A default installation should be pre-set to
+ <TT
CLASS="LITERAL"
>Cautious</TT
-> (versions prior to 3.0.5 were set to
- <TT
-CLASS="LITERAL"
->Medium</TT
->). 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.
- </P
+>. 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.
+ </P
><P
-> The <SPAN
+> The <SPAN
CLASS="GUIBUTTON"
>Edit</SPAN
-> button allows you to turn each
- action on/off individually for fine-tuning. The <SPAN
+> button allows you to turn each
+ action on/off individually for fine-tuning. The <SPAN
CLASS="GUIBUTTON"
>Cautious</SPAN
>
- button changes the actions list to low/safe settings which will activate
- ad blocking and a minimal set of <SPAN
+ button changes the actions list to low/safe settings which will activate
+ ad blocking and a minimal set of <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
>'s features, and subsequently
- there will be less of a chance for accidental problems. The
- <SPAN
+ there will be less of a chance for accidental problems. The
+ <SPAN
CLASS="GUIBUTTON"
>Medium</SPAN
> button sets the list to a medium level of
- other features and a low level set of privacy features. The
- <SPAN
+ other features and a low level set of privacy features. The
+ <SPAN
CLASS="GUIBUTTON"
>Advanced</SPAN
> 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
- <SPAN
+ ad blocking and medium level of privacy. See the chart below. The latter
+ three buttons over-ride any changes via with the
+ <SPAN
CLASS="GUIBUTTON"
>Edit</SPAN
> button. More fine-tuning can be done in the
- lower sections of this internal page.
- </P
+ lower sections of this internal page.
+ </P
><P
-> It is not recommend to edit the <TT
-CLASS="FILENAME"
->standard.action</TT
-> file
- itself.
- </P
+> 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.
+ </P
><P
-> The default profiles, and their associated actions, as pre-defined in
- <TT
+> The default profiles, and their associated actions, as pre-defined in
+ <TT
CLASS="FILENAME"
->standard.action</TT
+>default.action</TT
> are:
- </P
-><P
-> <DIV
+ </P
+><DIV
CLASS="TABLE"
><A
-NAME="AEN2085"
+NAME="AEN2870"
></A
><P
><B
><TD
>no</TD
><TD
->no</TD
+>yes</TD
><TD
>yes</TD
></TR
></TBODY
></TABLE
></DIV
->
- </P
></LI
></UL
->
- </P
><P
-> 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.
<TT
CLASS="FILENAME"
><TT
CLASS="FILENAME"
>.action</TT
->).
+>).
Generally, <TT
CLASS="FILENAME"
>user.action</TT
universal set in <TT
CLASS="FILENAME"
>user.action</TT
-> or any other actions file after
+> or any other actions file after
<TT
CLASS="FILENAME"
>default.action</TT
>Privoxy</SPAN
> upgrades easier.</P
><P
->
- 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
><H2
CLASS="SECT2"
><A
-NAME="AEN2184"
+NAME="RIGHT-MIX"
>8.1. Finding the Right Mix</A
></H2
><P
>, 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
<SPAN
CLASS="QUOTE"
><H2
CLASS="SECT2"
><A
-NAME="AEN2191"
+NAME="HOW-TO-EDIT"
>8.2. How to Edit</A
></H2
><P
>.
Note: the config file option <A
HREF="config.html#ENABLE-EDIT-ACTIONS"
->enale-edit-actions</A
+>enable-edit-actions</A
> 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
>"Advanced"</SPAN
> setting is more
aggressive, and will be more likely to cause problems for some sites.
- Experienced users only!
+ Experienced users only!
</P
><P
> If you prefer plain text editing to GUIs, you can of course also directly edit the
<TT
CLASS="FILENAME"
>default.action</TT
-> which is richly commented with many
+> which is richly commented with many
good examples.</P
></DIV
><DIV
the last match wins. If not, the effects are aggregated.
E.g. a URL might match a regular section with a heading line of <TT
CLASS="LITERAL"
->{
+>{
+<A
HREF="actions-file.html#HANDLE-AS-IMAGE"
>handle-as-image</A
CLASS="EMPHASIS"
>both</I
></SPAN
-> 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:</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
>handle-as-image</TT
> +<TT
CLASS="LITERAL"
->block</TT
+>block{Banner ads.}</TT
> }
# Block these as if they were images. Send no block page.
banners.example.com
></TD
></TR
></TABLE
->
- </P
><P
> You can trace this process for URL patterns and any given URL by visiting <A
HREF="http://config.privoxy.org/show-url-info"
>8.4. Patterns</A
></H2
><P
->
- As mentioned, <SPAN
+> As mentioned, <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
> uses <SPAN
> Generally, an URL pattern has the form
<TT
CLASS="LITERAL"
-><domain>/<path></TT
->, where both the
+><host><port>/<path></TT
+>, where the
<TT
CLASS="LITERAL"
-><domain></TT
-> and <TT
+><host></TT
+>, the <TT
+CLASS="LITERAL"
+><port></TT
+>
+ and the <TT
CLASS="LITERAL"
><path></TT
-> are
- optional. (This is why the special <TT
+> are optional. (This is why the special
+ <TT
CLASS="LITERAL"
>/</TT
-> pattern matches all
- URLs). Note that the protocol portion of the URL pattern (e.g.
- <TT
+> pattern matches all URLs). Note that the protocol
+ portion of the URL pattern (e.g. <TT
CLASS="LITERAL"
>http://</TT
->) should <SPAN
+>) should
+ <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
-> be included in
- the pattern. This is assumed already!</P
+> be included in the pattern. This is assumed already!</P
><P
-> 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 a 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
<A
HREF="http://en.wikipedia.org/wiki/Regular_expressions"
TARGET="_top"
><SPAN
CLASS="QUOTE"
>"Regular
- Expressions (PCRE)"</SPAN
+ Expressions"</SPAN
></A
-> based syntax.</P
+> (POSIX 1003.2).</P
+><P
+> The port part of a pattern is a decimal port number preceded by a colon
+ (<TT
+CLASS="LITERAL"
+>:</TT
+>). If the host part contains a numerical IPv6 address,
+ it has to be put into angle brackets
+ (<TT
+CLASS="LITERAL"
+><</TT
+>, <TT
+CLASS="LITERAL"
+>></TT
+>).</P
><P
></P
><DIV
></DT
><DD
><P
-> is a domain-only pattern and will match any request to <TT
+> is a host-only pattern and will match any request to <TT
CLASS="LITERAL"
>www.example.com</TT
>,
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 <TT
CLASS="LITERAL"
>example.com</TT
></DT
><DD
><P
-> means exactly the same. For domain-only patterns, the trailing <TT
+> means exactly the same. For host-only patterns, the trailing <TT
CLASS="LITERAL"
>/</TT
> may
><DT
><TT
CLASS="LITERAL"
->www.example.com/index.html$</TT
+>www.example.com/index.html</TT
></DT
><DD
><P
><DT
><TT
CLASS="LITERAL"
+>/</TT
+></DT
+><DD
+><P
+> Matches any URL because there's no requirement for either the
+ domain or the path to match anything.
+ </P
+></DD
+><DT
+><TT
+CLASS="LITERAL"
+>:8000/</TT
+></DT
+><DD
+><P
+> Matches any URL pointing to TCP port 8000.
+ </P
+></DD
+><DT
+><TT
+CLASS="LITERAL"
+>10.0.0.1/</TT
+></DT
+><DD
+><P
+> Matches any URL with the host address <TT
+CLASS="LITERAL"
+>10.0.0.1</TT
+>.
+ (Note that the real URL uses plain brackets, not angle brackets.)
+ </P
+></DD
+><DT
+><TT
+CLASS="LITERAL"
+><2001:db8::1>/</TT
+></DT
+><DD
+><P
+> Matches any URL with the host address <TT
+CLASS="LITERAL"
+>2001:db8::1</TT
+>.
+ (Note that the real URL uses plain brackets, not angle brackets.)
+ </P
+></DD
+><DT
+><TT
+CLASS="LITERAL"
>index.html</TT
></DT
><DD
there is no top-level domain called <TT
CLASS="LITERAL"
>.html</TT
->. So its
+>. So its
a mistake.
</P
></DD
><H3
CLASS="SECT3"
><A
-NAME="AEN2282"
->8.4.1. The Domain Pattern</A
+NAME="HOST-PATTERN"
+>8.4.1. The Host Pattern</A
></H3
><P
-> 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:</P
><P
></P
></DT
><DD
><P
-> matches any domain that <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->ENDS</I
-></SPAN
-> in
- <TT
+> matches any domain with first-level domain <TT
CLASS="LITERAL"
->.example.com</TT
+>com</TT
>
+ and second-level domain <TT
+CLASS="LITERAL"
+>example</TT
+>.
+ For example <TT
+CLASS="LITERAL"
+>www.example.com</TT
+>,
+ <TT
+CLASS="LITERAL"
+>example.com</TT
+> and <TT
+CLASS="LITERAL"
+>foo.bar.baz.example.com</TT
+>.
+ Note that it wouldn't match if the second-level domain was <TT
+CLASS="LITERAL"
+>another-example</TT
+>.
</P
></DD
><DT
<TT
CLASS="LITERAL"
>www.</TT
->
+> (It also matches the domain
+ <TT
+CLASS="LITERAL"
+>www</TT
+> but most of the time that doesn't matter.)
</P
></DD
><DT
CLASS="LITERAL"
>www.example.net/cgi/testing.pl</TT
> for instance. All these
- cases are matched.
+ cases are matched.
</P
></DD
></DL
CLASS="QUOTE"
>"*"</SPAN
> represents zero or more arbitrary characters (this is
- equivalent to the
+ equivalent to the
<A
HREF="http://en.wikipedia.org/wiki/Regular_expressions"
TARGET="_top"
<SPAN
CLASS="QUOTE"
>"character classes"</SPAN
-> 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:</P
><P
></P
> matches <SPAN
CLASS="QUOTE"
>"adserver.example.com"</SPAN
->,
+>,
<SPAN
CLASS="QUOTE"
>"ads.example.com"</SPAN
>, <TT
CLASS="LITERAL"
>a.b.c.d.e.upix.com</TT
-> etc.
+> etc.
</P
></DD
><DT
> matches <TT
CLASS="LITERAL"
>www1.example.com</TT
->,
+>,
<TT
CLASS="LITERAL"
>www4.example.cc</TT
>, <TT
CLASS="LITERAL"
>wwwd.example.cy</TT
->,
+>,
<TT
CLASS="LITERAL"
>wwwz.example.com</TT
CLASS="EMPHASIS"
>not</I
></SPAN
->
+>
<TT
CLASS="LITERAL"
>wwww.example.com</TT
><H3
CLASS="SECT3"
><A
-NAME="AEN2353"
+NAME="PATH-PATTERN"
>8.4.2. The Path Pattern</A
></H3
><P
> <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> uses Perl compatible (PCRE)
+> uses <SPAN
+CLASS="QUOTE"
+>"modern"</SPAN
+> POSIX 1003.2
<A
HREF="http://en.wikipedia.org/wiki/Regular_expressions"
TARGET="_top"
><SPAN
CLASS="QUOTE"
>"Regular
- Expression"</SPAN
+ Expressions"</SPAN
></A
-> based syntax
- (through the <A
-HREF="http://www.pcre.org/"
-TARGET="_top"
->PCRE</A
-> library) for
- matching the path portion (after the slash), and is thus more flexible.</P
+> for matching the path portion (after the slash),
+ and is thus more flexible.</P
><P
> There is an <A
HREF="appendix.html#REGEX"
>Appendix</A
> with a brief quick-start into regular
- expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
- at <A
-HREF="http://www.pcre.org/man.txt"
-TARGET="_top"
->http://www.pcre.org/man.txt</A
->.
- You might also find the Perl man page on regular expressions (<TT
+ expressions, you also might want to have a look at your operating system's documentation
+ on regular expressions (try <TT
CLASS="LITERAL"
->man perlre</TT
->)
- useful, which is available on-line at <A
-HREF="http://perldoc.perl.org/perlre.html"
-TARGET="_top"
->http://perldoc.perl.org/perlre.html</A
->.</P
+>man re_format</TT
+>).</P
><P
> Note that the path pattern is automatically left-anchored at the <SPAN
CLASS="QUOTE"
i.e. it matches as if it would start with a <SPAN
CLASS="QUOTE"
>"^"</SPAN
-> (regular expression speak
+> (regular expression speak
for the beginning of a line).</P
><P
> Please also note that matching in the path is <SPAN
>CASE INSENSITIVE</I
></SPAN
>
- 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
<SPAN
CLASS="QUOTE"
>"(?-i)"</SPAN
> Is equivalent to just <SPAN
CLASS="QUOTE"
>".example.com"</SPAN
->, since any documents
+>, since any documents
within that domain are matched with or without the <SPAN
CLASS="QUOTE"
>".*"</SPAN
expression called for at least two <SPAN
CLASS="QUOTE"
>"/'s"</SPAN
->, thus the path
- requirement. It also would match
+>, thus the path
+ requirement. It also would match
<SPAN
CLASS="QUOTE"
>"www.example.com/testing/index_html"</SPAN
->, because of the
+>, because of the
special meta-character <SPAN
CLASS="QUOTE"
>"."</SPAN
></DT
><DD
><P
-> This regular expression is conditional so it will match any page
+> This regular expression is conditional so it will match any page
named <SPAN
CLASS="QUOTE"
>"index.html"</SPAN
-> regardless of path which in this case can
+> regardless of path which in this case can
have one or more <SPAN
CLASS="QUOTE"
>"/'s"</SPAN
->. And this one must contain exactly
+>. And this one must contain exactly
<SPAN
CLASS="QUOTE"
>".html"</SPAN
-> (but does not have to end with that!).
+> (and end with that!).
</P
></DD
><DT
>, <SPAN
CLASS="QUOTE"
>"banner"</SPAN
->,
+>,
<SPAN
CLASS="QUOTE"
>"banners"</SPAN
>"junk"</SPAN
>.
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).
</P
></DD
><DT
></DT
><DD
><P
-> 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
<SPAN
CLASS="QUOTE"
>".jpg"</SPAN
> or <SPAN
CLASS="QUOTE"
>".png"</SPAN
->. So this
+>. So this
one is limited to common image formats.
</P
></DD
> There are many, many good examples to be found in <TT
CLASS="FILENAME"
>default.action</TT
->,
+>,
and more tutorials below in <A
HREF="appendix.html#REGEX"
>Appendix on regular expressions</A
CLASS="SECT3"
><A
NAME="TAG-PATTERN"
->8.4.3. The Tag Pattern</A
+>8.4.3. The Request Tag Pattern</A
></H3
><P
-> Tag patterns are used to change the applying actions based on the
- request's tags. Tags can be created with either the
- <A
+> 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
HREF="actions-file.html#CLIENT-HEADER-TAGGER"
>client-header-tagger</A
>
>server-header-tagger</A
> action.</P
><P
-> Tag patterns have to start with <SPAN
+> Request tag patterns have to start with <SPAN
CLASS="QUOTE"
>"TAG:"</SPAN
>, so <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
>
- 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 (Privoxy doesn't silently add a <SPAN
+ automatically (<SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> doesn't silently add a <SPAN
CLASS="QUOTE"
>"^"</SPAN
>,
>"TAG: foo"</SPAN
> wouldn't work as it requires white space.</P
><P
-> 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.</P
><P
-> 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.</P
><P
-> For example you could tag client requests which use the POST method,
- use this tag to activate another tagger that adds a tag if cookies
- are send, and then block based on the cookie tag. However if you'd
- reverse the position of the described taggers, and activated the method
- tagger based on the cookie tagger, no method tags would be created.
+> For example you could tag client requests which use the
+ <TT
+CLASS="LITERAL"
+>POST</TT
+> method,
+ then use this tag to activate another tagger that adds a tag if cookies
+ are sent, and then use a block action based on the cookie tag. This allows
+ the outcome of one action, to be input into a subsequent action. However if
+ you'd reverse the position of the described taggers, and activated the
+ method tagger based on the cookie tagger, no method tags would be created.
The method tagger would look for the request line, but at the time
- the cookie tag is created the request line has already been parsed.</P
+ the cookie tag is created, the request line has already been parsed.</P
><P
> While this is a limitation you should be aware of, this kind of
indirection is seldom needed anyway and even the example doesn't
make too much sense.</P
></DIV
+><DIV
+CLASS="SECT3"
+><H3
+CLASS="SECT3"
+><A
+NAME="NEGATIVE-TAG-PATTERNS"
+>8.4.4. The Negative Request Tag Patterns</A
+></H3
+><P
+> To match requests that do not have a certain request tag, specify a negative tag pattern
+ by prefixing the tag pattern line with either <SPAN
+CLASS="QUOTE"
+>"NO-REQUEST-TAG:"</SPAN
+>
+ or <SPAN
+CLASS="QUOTE"
+>"NO-RESPONSE-TAG:"</SPAN
+> instead of <SPAN
+CLASS="QUOTE"
+>"TAG:"</SPAN
+>.</P
+><P
+> Negative request tag patterns created with <SPAN
+CLASS="QUOTE"
+>"NO-REQUEST-TAG:"</SPAN
+> are checked
+ after all client headers are scanned, the ones created with <SPAN
+CLASS="QUOTE"
+>"NO-RESPONSE-TAG:"</SPAN
+>
+ are checked after all server headers are scanned. In both cases all the created
+ tags are considered.</P
+></DIV
+><DIV
+CLASS="SECT3"
+><H3
+CLASS="SECT3"
+><A
+NAME="CLIENT-TAG-PATTERN"
+>8.4.5. The Client Tag Pattern</A
+></H3
+><DIV
+CLASS="WARNING"
+><P
+></P
+><TABLE
+CLASS="WARNING"
+BORDER="1"
+WIDTH="100%"
+><TR
+><TD
+ALIGN="CENTER"
+><B
+>Warning</B
+></TD
+></TR
+><TR
+><TD
+ALIGN="LEFT"
+><P
+> This is an experimental feature. The syntax is likely to change in future versions.</P
+></TD
+></TR
+></TABLE
+></DIV
+><P
+> 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.</P
+><P
+> After a client-specific tag has been defined with the
+ <A
+HREF="config.html#CLIENT-SPECIFIC-TAG"
+>client-specific-tag</A
+>,
+ 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!</P
+><P
+> 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.</P
+><P
+> Clients can request tags to be set by using the CGI interface <A
+HREF="http://config.privoxy.org/client-tags"
+TARGET="_top"
+>http://config.privoxy.org/client-tags</A
+>.</P
+><P
+> Example:</P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+># 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</PRE
+></TD
+></TR
+></TABLE
+></DIV
></DIV
><DIV
CLASS="SECT2"
>+block</TT
>
previously applied."</SPAN
-> </P
+></P
><P
->
- 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
<TT
CLASS="LITERAL"
>{+some-action -some-other-action{some-parameter}}</TT
>,
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. </P
+ of the actions file.</P
><P
->
- Actions fall into three categories:</P
+> Actions fall into three categories:</P
><P
-> <P
></P
><UL
><LI
><P
->
- Boolean, i.e the action can only be <SPAN
+> Boolean, i.e the action can only be <SPAN
CLASS="QUOTE"
>"enabled"</SPAN
> or
>"disabled"</SPAN
>. Syntax:
</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
><P
->
- Example: <TT
+> Example: <TT
CLASS="LITERAL"
->+block</TT
+>+handle-as-image</TT
>
</P
></LI
><LI
><P
->
- 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:
</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
><P
> 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.
</P
><P
->
- Example: <TT
+> Example: <TT
CLASS="LITERAL"
>+hide-user-agent{Mozilla/5.0 (X11; U; FreeBSD i386; en-US; rv:1.8.1.4) Gecko/20070602 Firefox/2.0.0.4}</TT
>
></LI
><LI
><P
->
- 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, <SPAN
CLASS="emphasis"
that can be executed for the same request repeatedly, like adding multiple
headers, or filtering through multiple filters. Syntax:
</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
><P
->
- Examples: <TT
+> Examples: <TT
CLASS="LITERAL"
>+add-header{X-Fun-Header: Some text}</TT
> and
</P
></LI
></UL
-></P
><P
> If nothing is specified in any actions file, no <SPAN
CLASS="QUOTE"
files will give a good starting point).</P
><P
> 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 <TT
CLASS="FILENAME"
>user.action</TT
>Notes:</DT
><DD
><P
-> 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
<SPAN
CLASS="QUOTE"
>"HTTP headers"</SPAN
-> are, you definitely don't need to worry about this
+> are, you definitely don't need to worry about this
one.
</P
+><P
+> Headers added by this action are not modified by other actions.
+ </P
></DD
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+add-header{X-User-Tracking: sucks}</PRE
+># 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}}
+/</PRE
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
HREF="actions-file.html#SET-IMAGE-BLOCKER"
>set-image-blocker</A
></TT
->, and
+>, and
<TT
CLASS="LITERAL"
><A
>handle-as-empty-document</A
></TT
> actions.
-
+
</P
></DD
><DT
>Type:</DT
><DD
><P
->Boolean.</P
+>Parameterized.</P
></DD
><DT
>Parameter:</DT
><DD
><P
->N/A</P
+>A block reason that should be given to the user.</P
></DD
><DT
>Notes:</DT
CLASS="QUOTE"
>"BLOCKED"</SPAN
> page
- for requests to blocked pages. This page contains links to find out why the request
- was blocked, and a click-through to the blocked content (the latter only if compiled with the
- force feature enabled). The <SPAN
-CLASS="QUOTE"
->"BLOCKED"</SPAN
-> page adapts to the available
- screen space -- it displays full-blown if space allows, or miniaturized and text-only
- if loaded into a small frame or window. If you are using <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
->
- right now, you can take a look at the
- <A
-HREF="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"BLOCKED"</SPAN
->
- page</A
->.
+ for requests to blocked pages. This page contains the block reason given as
+ parameter, a link to find out why the block action applies, and a click-through
+ to the blocked content (the latter only if the force feature is available and
+ enabled).
</P
><P
->
- A very important exception occurs if <SPAN
+> A very important exception occurs if <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>both</I
></SPAN
->
+>
<TT
CLASS="LITERAL"
>block</TT
>handle-as-image</A
></TT
>,
- 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
<TT
CLASS="LITERAL"
><A
if not, the standard checkerboard pattern is sent.
</P
><P
-> It is important to understand this process, in order
+> It is important to understand this process, in order
to understand how <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> 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.
</P
><P
><DT
>Example usage (section):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->{+block}
+>{+block{No nasty stuff for you.}}
# Block and replace with "blocked" page
.nasty-stuff.example.com
-{+block +handle-as-image}
+{+block{Doubleclick banners.} +handle-as-image}
# Block and replace with image
.ad.doubleclick.net
.ads.r.us/banners/
-{+block +handle-as-empty-document}
+{+block{Layered ads.} +handle-as-empty-document}
# Block and then ignore
- adserver.exampleclick.net/.*\.js$</PRE
+ adserver.example.net/.*\.js$</PRE
+></TD
+></TR
+></TABLE
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="SECT3"
+><H4
+CLASS="SECT3"
+><A
+NAME="CHANGE-X-FORWARDED-FOR"
+>8.5.3. change-x-forwarded-for</A
+></H4
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>Typical use:</DT
+><DD
+><P
+>Improve privacy by not forwarding the source of the request in the HTTP headers.</P
+></DD
+><DT
+>Effect:</DT
+><DD
+><P
+> Deletes the <SPAN
+CLASS="QUOTE"
+>"X-Forwarded-For:"</SPAN
+> HTTP header from the client request,
+ or adds a new one.
+ </P
+></DD
+><DT
+>Type:</DT
+><DD
+><P
+>Parameterized.</P
+></DD
+><DT
+>Parameter:</DT
+><DD
+><P
+></P
+><UL
+><LI
+><P
+><SPAN
+CLASS="QUOTE"
+>"block"</SPAN
+> to delete the header.</P
+></LI
+><LI
+><P
+> <SPAN
+CLASS="QUOTE"
+>"add"</SPAN
+> to create the header (or append
+ the client's IP address to an already existing one).
+ </P
+></LI
+></UL
+></DD
+><DT
+>Notes:</DT
+><DD
+><P
+> It is safe and recommended to use <TT
+CLASS="LITERAL"
+>block</TT
+>.
+ </P
+><P
+> Forwarding the source address of the request may make
+ sense in some multi-user setups but is also a privacy risk.
+ </P
+></DD
+><DT
+>Example usage:</DT
+><DD
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+change-x-forwarded-for{block}</PRE
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="CLIENT-HEADER-FILTER"
->8.5.3. client-header-filter</A
+>8.5.4. client-header-filter</A
></H4
><P
></P
>Type:</DT
><DD
><P
->Parameterized.</P
+>Multi-value.</P
></DD
><DT
>Parameter:</DT
and use their output as input.
</P
><P
+> If the request URI gets changed, <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> will detect that and use the new
+ one. This can be used to rewrite the request destination behind the client's
+ back, for example to specify a Tor exit relay for certain requests.
+ </P
+><P
> Please refer to the <A
HREF="filter-file.html"
>filter file chapter</A
><DT
>Example usage (section):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->{+client-header-filter{hide-tor-exit-notation}}
-.exit/
- </PRE
+># Hide Tor exit notation in Host and Referer Headers
+{+client-header-filter{hide-tor-exit-notation}}
+/</PRE
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="CLIENT-HEADER-TAGGER"
->8.5.4. client-header-tagger</A
+>8.5.5. client-header-tagger</A
></H4
><P
></P
><P
> 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.
</P
></DD
><DT
>Type:</DT
><DD
><P
->Parameterized.</P
+>Multi-value.</P
></DD
><DT
>Parameter:</DT
><DT
>Example usage (section):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><PRE
CLASS="SCREEN"
># Tag every request with the User-Agent header
-{+client-header-filter{user-agent}}
+{+client-header-tagger{user-agent}}
/
+
+# Tagging itself doesn't change the action
+# settings, sections with TAG patterns do:
+#
+# If it's a download agent, use a different forwarding proxy,
+# show the real User-Agent and make sure resume works.
+{+forward-override{forward-socks5 10.0.0.2:2222 .} \
+ -hide-if-modified-since \
+ -overwrite-last-modified \
+ -hide-user-agent \
+ -filter \
+ -deanimate-gifs \
+}
+TAG:^User-Agent: NetBSD-ftp/
+TAG:^User-Agent: Novell ZYPP Installer
+TAG:^User-Agent: RPM APT-HTTP/
+TAG:^User-Agent: fetch libfetch/
+TAG:^User-Agent: Ubuntu APT-HTTP/
+TAG:^User-Agent: MPlayer/
</PRE
></TD
></TR
></TABLE
->
- </P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+># 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$
+ </PRE
+></TD
+></TR
+></TABLE
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+># 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$
+ </PRE
+></TD
+></TR
+></TABLE
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="CONTENT-TYPE-OVERWRITE"
->8.5.5. content-type-overwrite</A
+>8.5.6. content-type-overwrite</A
></H4
><P
></P
>Parameter:</DT
><DD
><P
-> Any string.
+> Any string.
</P
></DD
><DT
browser to decide what to do with the document. The value of this
header can cause the browser to open a download menu instead of
displaying the document by itself, even if the document's format is
- supported by the browser.
+ supported by the browser.
</P
><P
> The declared content type can also affect which rendering mode
>"application/xml"</SPAN
> 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.
</P
><P
> You can also go the opposite direction: if your browser prints
<SPAN
CLASS="QUOTE"
>"text/html"</SPAN
-> and have it rendered as broken HTML document.
+> and have it rendered as broken HTML document.
</P
><P
> By default <TT
>content-type-overwrite</TT
>
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.
</P
></DD
><DT
>Example usage (sections):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="CRUNCH-CLIENT-HEADER"
->8.5.6. crunch-client-header</A
+>8.5.7. crunch-client-header</A
></H4
><P
></P
><DT
>Example usage (section):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
-># Block the non-existent "Privacy-Violation:" client header
+># Block the non-existent "Privacy-Violation:" client header
{ +crunch-client-header{Privacy-Violation:} }
/
</PRE
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="CRUNCH-IF-NONE-MATCH"
->8.5.7. crunch-if-none-match</A
+>8.5.8. crunch-if-none-match</A
></H4
><P
></P
><DT
>Example usage (section):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="CRUNCH-INCOMING-COOKIES"
->8.5.8. crunch-incoming-cookies</A
+>8.5.9. crunch-incoming-cookies</A
></H4
><P
></P
>session-cookies-only</A
></TT
> 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
<TT
CLASS="LITERAL"
><A
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="CRUNCH-SERVER-HEADER"
->8.5.9. crunch-server-header</A
+>8.5.10. crunch-server-header</A
></H4
><P
></P
><DT
>Example usage (section):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="CRUNCH-OUTGOING-COOKIES"
->8.5.10. crunch-outgoing-cookies</A
+>8.5.11. crunch-outgoing-cookies</A
></H4
><P
></P
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="DEANIMATE-GIFS"
->8.5.11. deanimate-gifs</A
+>8.5.12. deanimate-gifs</A
></H4
><P
></P
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="DOWNGRADE-HTTP-VERSION"
->8.5.12. downgrade-http-version</A
+>8.5.13. downgrade-http-version</A
></H4
><P
></P
>Privoxy</SPAN
>
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.
+ </P
+><P
+> 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.
+ </P
+><P
+> 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 <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> it should be
+ fixed so the following release works without the work around.
</P
></DD
><DT
>Example usage (section):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
><H4
CLASS="SECT3"
><A
-NAME="FAST-REDIRECTS"
->8.5.13. fast-redirects</A
+NAME="EXTERNAL-FILTER"
+>8.5.14. external-filter</A
></H4
><P
></P
>Typical use:</DT
><DD
><P
->Fool some click-tracking scripts and speed up indirect links.</P
+>Modify content using a programming language of your choice.</P
></DD
><DT
>Effect:</DT
><DD
><P
-> Detects redirection URLs and redirects the browser without contacting
- the redirection server first.
+> 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 <TT
+CLASS="LITERAL"
+>text/plain</TT
+> MIME type for all files
+ whose type they don't know.)
</P
></DD
><DT
>Type:</DT
><DD
><P
->Parameterized.</P
+>Multi-value.</P
></DD
><DT
>Parameter:</DT
><DD
><P
-></P
-><UL
-><LI
-><P
-> <SPAN
-CLASS="QUOTE"
->"simple-check"</SPAN
-> to just search for the string <SPAN
-CLASS="QUOTE"
->"http://"</SPAN
+> The name of an external content filter, as defined in the
+ <A
+HREF="filter-file.html"
+>filter file</A
+>.
+ External filters can be defined in one or more files as defined by the
+ <TT
+CLASS="LITERAL"
+><A
+HREF="config.html#FILTERFILE"
+>filterfile</A
+></TT
>
- to detect redirection URLs.
- </P
-></LI
-><LI
+ option in the <A
+HREF="config.html"
+>config file</A
+>.
+ </P
><P
-> <SPAN
-CLASS="QUOTE"
->"check-decoded-url"</SPAN
-> to decode URLs (if necessary) before searching
- for redirection URLs.
- </P
-></LI
-></UL
+> When used in its negative form,
+ and without parameters, <SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>all</I
+></SPAN
+> filtering with external
+ filters is completely disabled.
+ </P
></DD
><DT
>Notes:</DT
><DD
><P
->
- 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:
- <SPAN
-CLASS="QUOTE"
->"http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/"</SPAN
->.
- </P
-><P
-> Sometimes, there are even multiple consecutive redirects encoded in the
- URL. These redirections via scripts make your web browsing more traceable,
- since the server from which you follow such a link can see where you go
- to. Apart from that, valuable bandwidth and time is wasted, while your
+> External filters are scripts or programs that can modify the content in
+ case common <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#FILTER"
+>filters</A
+></TT
+>
+ aren't powerful enough. With the exception that this action doesn't
+ use pcrs-based filters, the notes in the
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#FILTER"
+>filter</A
+></TT
+> section apply.
+ </P
+><DIV
+CLASS="WARNING"
+><P
+></P
+><TABLE
+CLASS="WARNING"
+BORDER="1"
+WIDTH="90%"
+><TR
+><TD
+ALIGN="CENTER"
+><B
+>Warning</B
+></TD
+></TR
+><TR
+><TD
+ALIGN="LEFT"
+><P
+> Currently external filters are executed with <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>'s privileges.
+ Only use external filters you understand and trust.
+ </P
+></TD
+></TR
+></TABLE
+></DIV
+><P
+> This feature is experimental, the <TT
+CLASS="LITERAL"
+><A
+HREF="filter-file.html#EXTERNAL-FILTER-SYNTAX"
+>syntax</A
+></TT
+>
+ may change in the future.
+ </P
+></DD
+><DT
+>Example usage:</DT
+><DD
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+external-filter{fancy-filter}</PRE
+></TD
+></TR
+></TABLE
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="SECT3"
+><H4
+CLASS="SECT3"
+><A
+NAME="FAST-REDIRECTS"
+>8.5.15. fast-redirects</A
+></H4
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>Typical use:</DT
+><DD
+><P
+>Fool some click-tracking scripts and speed up indirect links.</P
+></DD
+><DT
+>Effect:</DT
+><DD
+><P
+> Detects redirection URLs and redirects the browser without contacting
+ the redirection server first.
+ </P
+></DD
+><DT
+>Type:</DT
+><DD
+><P
+>Parameterized.</P
+></DD
+><DT
+>Parameter:</DT
+><DD
+><P
+></P
+><UL
+><LI
+><P
+> <SPAN
+CLASS="QUOTE"
+>"simple-check"</SPAN
+> to just search for the string <SPAN
+CLASS="QUOTE"
+>"http://"</SPAN
+>
+ to detect redirection URLs.
+ </P
+></LI
+><LI
+><P
+> <SPAN
+CLASS="QUOTE"
+>"check-decoded-url"</SPAN
+> to decode URLs (if necessary) before searching
+ for redirection URLs.
+ </P
+></LI
+></UL
+></DD
+><DT
+>Notes:</DT
+><DD
+><P
+> 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:
+ <SPAN
+CLASS="QUOTE"
+>"http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/"</SPAN
+>.
+ </P
+><P
+> Sometimes, there are even multiple consecutive redirects encoded in the
+ URL. These redirections via scripts make your web browsing more traceable,
+ since the server from which you follow such a link can see where you go
+ to. Apart from that, valuable bandwidth and time is wasted, while your
browser asks the server for one redirect after the other. Plus, it feeds
the advertisers.
</P
><P
> 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:
</P
><P
> Not every URLs with other URLs as parameters is evil.
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><PRE
CLASS="SCREEN"
> { +fast-redirects{simple-check} }
- one.example.com
+ one.example.com
{ +fast-redirects{check-decoded-url} }
another.example.com/testing</PRE
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="FILTER"
->8.5.14. filter</A
+>8.5.16. filter</A
></H4
><P
></P
>Typical use:</DT
><DD
><P
->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.</P
></DD
><DT
>Type:</DT
><DD
><P
->Parameterized.</P
+>Multi-value.</P
></DD
><DT
>Parameter:</DT
HREF="filter-file.html"
>filter file</A
>.
- 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
<TT
CLASS="LITERAL"
><A
option in the <A
HREF="config.html"
>config file</A
->.
+>.
<TT
CLASS="FILENAME"
>default.filter</TT
-> 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 <TT
CLASS="FILENAME"
>user.filter</TT
>Notes:</DT
><DD
><P
-> 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.
</P
><P
> 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.
</P
><P
> <SPAN
CLASS="QUOTE"
>"Rolling your own"</SPAN
>
- filters requires a knowledge of
+ filters requires a knowledge of
<A
HREF="http://en.wikipedia.org/wiki/Regular_expressions"
TARGET="_top"
>"Regular
Expressions"</SPAN
></A
-> and
+> and
<A
HREF="http://en.wikipedia.org/wiki/Html"
TARGET="_top"
>"HTML"</SPAN
></A
>.
- 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
<SPAN
CLASS="QUOTE"
> is not available.
</P
><P
-> The amount of data that can be filtered is limited to the
+> The amount of data that can be filtered is limited to the
<TT
CLASS="LITERAL"
><A
option in the main <A
HREF="config.html"
>config file</A
->. 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.
</P
><P
> Inappropriate MIME types, such as zipped files, are not filtered at all.
> exceptions.
</P
><P
-> Compressed content can't be filtered either, unless <SPAN
+> Compressed content can't be filtered either, but if <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
>
- is compiled with zlib support (requires at least <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> 3.0.7),
- in which case <SPAN
+ is compiled with zlib support and a supported compression algorithm
+ is used (gzip or deflate), <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> will decompress the content before filtering
- it.
+> can first decompress the content
+ and then filter it.
</P
><P
> If you use a <SPAN
>.
</P
><P
-> Content filtering can achieve some of the same effects as the
+> Content filtering can achieve some of the same effects as the
<TT
CLASS="LITERAL"
><A
>block</A
></TT
>
- 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.
</P
><P
See <A
HREF="filter-file.html#PREDEFINED-FILTERS"
>the Predefined Filters section</A
-> for
+> for
more explanation on each:</DT
><DD
><P
NAME="FILTER-JS-ANNOYANCES"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse</PRE
+>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-JS-EVENTS"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{js-events} # Kill all JS event bindings (Radically destructive! Only for extra nasty sites)</PRE
+>+filter{js-events} # Kill JavaScript event bindings and timers (Radically destructive! Only for extra nasty sites).</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-HTML-ANNOYANCES"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{html-annoyances} # Get rid of particularly annoying HTML abuse</PRE
+>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-CONTENT-COOKIES"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{content-cookies} # Kill cookies that come in the HTML or JS content</PRE
+>+filter{content-cookies} # Kill cookies that come in the HTML or JS content.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-REFRESH-TAGS"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups)</PRE
+>+filter{refresh-tags} # Kill automatic refresh tags if refresh time is larger than 9 seconds.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-UNSOLICITED-POPUPS"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{unsolicited-popups} # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.</PRE
+>+filter{unsolicited-popups} # Disable only unsolicited pop-up windows.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-ALL-POPUPS"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{all-popups} # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.</PRE
+>+filter{all-popups} # Kill all popups in JavaScript and HTML.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-IMG-REORDER"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective</PRE
+>+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-BANNERS-BY-SIZE"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{banners-by-size} # Kill banners by size</PRE
+>+filter{banners-by-size} # Kill banners by size.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-BANNERS-BY-LINK"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{banners-by-link} # Kill banners by their links to known clicktrackers</PRE
+>+filter{banners-by-link} # Kill banners by their links to known clicktrackers.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-WEBBUGS"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking)</PRE
+>+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking).</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-TINY-TEXTFORMS"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap</PRE
+>+filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-JUMPING-WINDOWS"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{jumping-windows} # Prevent windows from resizing and moving themselves</PRE
+>+filter{jumping-windows} # Prevent windows from resizing and moving themselves.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-FRAMESET-BORDERS"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{frameset-borders} # Give frames a border and make them resizeable</PRE
+>+filter{frameset-borders} # Give frames a border and make them resizable.</PRE
></TD
></TR
></TABLE
+><P
+> <A
+NAME="FILTER-IFRAMES"
+></A
>
</P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+filter{iframes} # Removes all detected iframes. Should only be enabled for individual sites.</PRE
+></TD
+></TR
+></TABLE
><P
> <A
NAME="FILTER-DEMORONIZER"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{demoronizer} # Fix MS's non-standard use of standard charsets</PRE
+>+filter{demoronizer} # Fix MS's non-standard use of standard charsets.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-SHOCKWAVE-FLASH"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{shockwave-flash} # Kill embedded Shockwave Flash objects</PRE
+>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-QUICKTIME-KIOSKMODE"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{quicktime-kioskmode} # Make Quicktime movies savable</PRE
+>+filter{quicktime-kioskmode} # Make Quicktime movies saveable.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-FUN"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-CRUDE-PARENTAL"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{crude-parental} # Crude parental filtering (demo only)</PRE
+>+filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliably.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-IE-EXPLOITS"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{ie-exploits} # Disable a known Internet Explorer bug exploits</PRE
+>+filter{ie-exploits} # Disable some known Internet Explorer bug exploits.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
NAME="FILTER-SITE-SPECIFICS"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{site-specifics} # Custom filters for specific site related problems</PRE
+>+filter{site-specifics} # Cure for site-specific problems. Don't apply generally!</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
-NAME="FILTER-GOOGLE"
+NAME="FILTER-NO-PING"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{google} # Removes text ads and other Google specific improvements</PRE
+>+filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
-NAME="FILTER-YAHOO"
+NAME="FILTER-GOOGLE"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{yahoo} # Removes text ads and other Yahoo specific improvements</PRE
+>+filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
-NAME="FILTER-MSN"
+NAME="FILTER-YAHOO"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{msn} # Removes text ads and other MSN specific improvements</PRE
+>+filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
-NAME="FILTER-BLOGSPOT"
+NAME="FILTER-MSN"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{blogspot} # Cleans up Blogspot blogs</PRE
+>+filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.</PRE
></TD
></TR
></TABLE
->
- </P
><P
> <A
-NAME="FILTER-NO-PING"
+NAME="FILTER-BLOGSPOT"
></A
>
- <TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+filter{no-ping} # Removes non-standard ping attributes from anchor and area tags</PRE
+>+filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this.</PRE
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="FORCE-TEXT-MODE"
->8.5.15. force-text-mode</A
+>8.5.17. force-text-mode</A
></H4
><P
></P
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="FORWARD-OVERRIDE"
->8.5.16. forward-override</A
+>8.5.18. forward-override</A
></H4
><P
></P
>Type:</DT
><DD
><P
->Multi-value.</P
+>Parameterized.</P
></DD
><DT
>Parameter:</DT
CLASS="QUOTE"
>"forward-socks4"</SPAN
>
- to use a socks4 connection (with local DNS resolution) instead.
+ to use a socks4 connection (with local DNS resolution) instead, use <SPAN
+CLASS="QUOTE"
+>"forward-socks5"</SPAN
+>
+ for socks5 connections (with remote DNS resolution).
</P
></LI
><LI
CLASS="QUOTE"
>"forward-socks4"</SPAN
> to use a socks4 connection
- (with local DNS resolution) instead.
+ (with local DNS resolution) instead, use <SPAN
+CLASS="QUOTE"
+>"forward-socks5"</SPAN
+>
+ for socks5 connections (with remote DNS resolution).
+ </P
+></LI
+><LI
+><P
+> <SPAN
+CLASS="QUOTE"
+>"forward-webserver 127.0.0.1:80"</SPAN
+> to use the HTTP
+ server listening at 127.0.0.1 port 80 without adjusting the
+ request headers.
+ </P
+><P
+> This makes it more convenient to use Privoxy to make
+ existing websites available as onion services as well.
+ </P
+><P
+> 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.
+ </P
+><P
+> 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.
+ </P
+><P
+> 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.
</P
></LI
></UL
>Notes:</DT
><DD
><P
-> This action takes parameters similar to the
+> This action takes parameters similar to the
<A
HREF="config.html#FORWARDING"
>forward</A
><P
> 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.
</P
><P
> Use the <A
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
-># Always use direct connections for requests previously tagged as
+># Use an ssh tunnel for requests previously tagged as
# <SPAN
CLASS="QUOTE"
>"User-Agent: fetch libfetch/2.0"</SPAN
> 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.
-{+forward-override{forward .} \
+#
+# Note that HTTP headers are easy to fake and therefore their
+# values are as (un)trustworthy as your clients and users.
+{+forward-override{forward-socks5 10.0.0.2:2222 .} \
-hide-if-modified-since \
-overwrite-last-modified \
}
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="HANDLE-AS-EMPTY-DOCUMENT"
->8.5.17. handle-as-empty-document</A
+>8.5.19. handle-as-empty-document</A
></H4
><P
></P
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><PRE
CLASS="SCREEN"
># Block all documents on example.org that end with ".js",
-# but send an empty document instead of the usual HTML message.
-{+block +handle-as-empty-document}
+# but send an empty document instead of the usual HTML message.
+{+block{Blocked JavaScript} +handle-as-empty-document}
example.org/.*\.js$
</PRE
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="HANDLE-AS-IMAGE"
->8.5.18. handle-as-image</A
+>8.5.20. handle-as-image</A
></H4
><P
></P
>default.action</TT
>.
It marks all URLs with well-known image file name extensions as images and should
- be left intact.
+ be left intact.
</P
><P
> Users will probably only want to use the handle-as-image action in conjunction with
><DT
>Example usage (sections):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
# These don't look like images, but they're banners and should be
# blocked as images:
#
-{+block +handle-as-image}
-some.nasty-banner-server.com/junk.cgi\?output=trash
-
-# Banner source! Who cares if they also have non-image content?
-ad.doubleclick.net </PRE
+{+block{Nasty banners.} +handle-as-image}
+nasty-banner-server.example.com/junk.cgi\?output=trash</PRE
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="HIDE-ACCEPT-LANGUAGE"
->8.5.19. hide-accept-language</A
+>8.5.21. hide-accept-language</A
></H4
><P
></P
to a rare language, you should consider that it helps to
make your requests unique and thus easier to trace.
If you don't plan to change this header frequently,
- you should stick to a common language.
+ you should stick to a common language.
</P
></DD
><DT
>Example usage (section):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="HIDE-CONTENT-DISPOSITION"
->8.5.20. hide-content-disposition</A
+>8.5.22. hide-content-disposition</A
></H4
><P
></P
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="HIDE-IF-MODIFIED-SINCE"
->8.5.21. hide-if-modified-since</A
+>8.5.23. hide-if-modified-since</A
></H4
><P
></P
> Deletes the <SPAN
CLASS="QUOTE"
>"If-Modified-Since:"</SPAN
-> HTTP client header or modifies its value.
+> HTTP client header or modifies its value.
</P
></DD
><DT
CLASS="QUOTE"
>"If-Modified-Since:"</SPAN
> makes
- sure it isn't used as a cookie replacement, but you will run into
- caching problems if the random range is too high.
+ it less likely that the server can use the time as a cookie replacement,
+ but you will run into caching problems if the random range is too high.
</P
><P
> It is a good idea to only use a small negative value and let
HREF="actions-file.html#CRUNCH-IF-NONE-MATCH"
>crunch-if-none-match</A
></TT
->.
+>,
+ otherwise it's more or less pointless.
</P
></DD
><DT
>Example usage (section):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
-># Let the browser revalidate without being tracked across sessions
-{ +hide-if-modified-since{-60} \
+># Let the browser revalidate but make tracking based on the time less likely.
+{+hide-if-modified-since{-60} \
+overwrite-last-modified{randomize} \
+crunch-if-none-match}
/</PRE
></TD
></TR
></TABLE
->
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="HIDE-FORWARDED-FOR-HEADERS"
->8.5.22. hide-forwarded-for-headers</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Typical use:</DT
-><DD
-><P
->Improve privacy by not embedding the source of the request in the HTTP headers.</P
-></DD
-><DT
->Effect:</DT
-><DD
-><P
-> Deletes any existing <SPAN
-CLASS="QUOTE"
->"X-Forwarded-for:"</SPAN
-> HTTP header from client requests,
- and prevents adding a new one.
- </P
-></DD
-><DT
->Type:</DT
-><DD
-><P
->Boolean.</P
-></DD
-><DT
->Parameter:</DT
-><DD
-><P
-> N/A
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> It is safe to leave this on.
- </P
-></DD
-><DT
->Example usage:</DT
-><DD
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
->+hide-forwarded-for-headers</PRE
-></TD
-></TR
-></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="HIDE-FROM-HEADER"
->8.5.23. hide-from-header</A
+>8.5.24. hide-from-header</A
></H4
><P
></P
> The keyword <SPAN
CLASS="QUOTE"
>"block"</SPAN
-> will completely remove the header
+> will completely remove the header
(not to be confused with the <TT
CLASS="LITERAL"
><A
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
-> or
- <TABLE
+><P
+>or</P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="HIDE-REFERRER"
->8.5.24. hide-referrer</A
+>8.5.25. hide-referrer</A
></H4
><A
NAME="HIDE-REFERER"
><P
><SPAN
CLASS="QUOTE"
+>"conditional-forge"</SPAN
+> to forge the header if the host has changed.</P
+></LI
+><LI
+><P
+><SPAN
+CLASS="QUOTE"
>"block"</SPAN
> to delete the header unconditionally.</P
></LI
><P
> Always blocking the referrer, or using a custom one, can lead to
failures on servers that check the referrer before they answer any
- requests, in an attempt to prevent their valuable content from being
+ requests, in an attempt to prevent their content from being
embedded or linked to elsewhere.
</P
><P
are on the same host. Most of the time that's the case.
</P
><P
->
- <TT
+> <TT
CLASS="LITERAL"
>hide-referer</TT
> is an alternate spelling of
requires it to be spelled as <SPAN
CLASS="QUOTE"
>"referer"</SPAN
->.)
+>.)
</P
></DD
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
-> or
- <TABLE
+><P
+>or</P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="HIDE-USER-AGENT"
->8.5.25. hide-user-agent</A
+>8.5.26. hide-user-agent</A
></H4
><P
></P
>Typical use:</DT
><DD
><P
->Conceal your type of browser and client operating system</P
+>Try to conceal your type of browser and client operating system</P
></DD
><DT
>Effect:</DT
>NOT</I
></SPAN
> the right thing to do: good web sites
- work browser-independently).
-
+ work browser-independently).
</P
></TD
></TR
>. 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 <SPAN
-CLASS="APPLICATION"
->Mozilla</SPAN
-> enter, yet forging to a
- <SPAN
-CLASS="APPLICATION"
->Netscape 6.1</SPAN
-> 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).
</P
><P
-> More information on known user-agent strings can be found at
+> More information on known user-agent strings can be found at
<A
HREF="http://www.user-agents.org/"
TARGET="_top"
>http://www.user-agents.org/</A
>
- and
+ and
<A
HREF="http://en.wikipedia.org/wiki/User_agent"
TARGET="_top"
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
><H4
CLASS="SECT3"
><A
-NAME="INSPECT-JPEGS"
->8.5.26. inspect-jpegs</A
+NAME="LIMIT-CONNECT"
+>8.5.27. limit-connect</A
></H4
><P
></P
>Typical use:</DT
><DD
><P
->To protect against the MS buffer over-run in JPEG processing</P
+>Prevent abuse of <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> as a TCP proxy relay or disable SSL for untrusted sites</P
></DD
><DT
>Effect:</DT
><DD
><P
-> Protect against a known exploit
+> Specifies to which ports HTTP CONNECT requests are allowable.
</P
></DD
><DT
>Type:</DT
><DD
><P
->Boolean.</P
+>Parameterized.</P
></DD
><DT
>Parameter:</DT
><DD
><P
-> N/A
+> A comma-separated list of ports or port ranges (the latter using dashes, with the minimum
+ defaulting to 0 and the maximum to 65K).
</P
></DD
><DT
>Notes:</DT
><DD
><P
-> See Microsoft Security Bulletin MS04-028. JPEG images are one of the most
- common image types found across the Internet. The exploit as described can
- allow execution of code on the target system, giving an attacker access
- to the system in question by merely planting an altered JPEG image, which
- would have no obvious indications of what lurks inside. This action
- prevents this exploit.
+> By default, i.e. if no <TT
+CLASS="LITERAL"
+>limit-connect</TT
+> action applies,
+ <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> allows HTTP CONNECT requests to all
+ ports. Use <TT
+CLASS="LITERAL"
+>limit-connect</TT
+> if fine-grained control
+ is desired for some or all destinations.
</P
><P
-> Note that the described exploit is only one of many,
- using this action does not mean that you no longer
- have to patch the client.
- </P
+> The CONNECT methods exists in HTTP to allow access to secure websites
+ (<SPAN
+CLASS="QUOTE"
+>"https://"</SPAN
+> URLs) through proxies. It works very simply:
+ the proxy connects to the server on the specified port, and then
+ short-circuits its connections to the client and to the remote server.
+ This means CONNECT-enabled proxies can be used as TCP relays very easily.
+ </P
+><P
+> <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> relays HTTPS traffic without seeing
+ the decoded content. Websites can leverage this limitation to circumvent <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>'s
+ filters. By specifying an invalid port range you can disable HTTPS entirely.
+ </P
></DD
><DT
->Example usage:</DT
+>Example usages:</DT
><DD
-><P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
><TD
><PRE
CLASS="SCREEN"
->+inspect-jpegs</PRE
+>+limit-connect{443} # Port 443 is OK.
++limit-connect{80,443} # Ports 80 and 443 are OK.
++limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK.
++limit-connect{-} # All ports are OK
++limit-connect{,} # No HTTPS/SSL traffic is allowed</PRE
></TD
></TR
></TABLE
-></P
></DD
></DL
></DIV
><H4
CLASS="SECT3"
><A
-NAME="KILL-POPUPS"
->8.5.27. kill-popups<A
-NAME="KILL-POPUP"
-></A
-></A
+NAME="LIMIT-COOKIE-LIFETIME"
+>8.5.28. limit-cookie-lifetime</A
></H4
><P
></P
>Typical use:</DT
><DD
><P
->Eliminate those annoying pop-up windows (deprecated)</P
+>Limit the lifetime of HTTP cookies to a couple of minutes or hours.</P
></DD
><DT
>Effect:</DT
><DD
><P
-> While loading the document, replace JavaScript code that opens
- pop-up windows with (syntactically neutral) dummy code on the fly.
+> Overwrites the expires field in Set-Cookie server headers if it's above the specified limit.
</P
></DD
><DT
>Type:</DT
><DD
><P
->Boolean.</P
+>Parameterized.</P
></DD
><DT
>Parameter:</DT
><DD
><P
-> N/A
+> The lifetime limit in minutes, or 0.
</P
></DD
><DT
>Notes:</DT
><DD
><P
-> This action is basically a built-in, hardwired special-purpose filter
- action, but there are important differences: For <TT
-CLASS="LITERAL"
->kill-popups</TT
->,
- the document need not be buffered, so it can be incrementally rendered while
- downloading. But <TT
-CLASS="LITERAL"
->kill-popups</TT
-> doesn't catch as many pop-ups as
- <TT
-CLASS="LITERAL"
-><A
-HREF="actions-file.html#FILTER-ALL-POPUPS"
->filter{<TT
-CLASS="REPLACEABLE"
-><I
->all-popups</I
-></TT
->}</A
-></TT
->
- does and is not as smart as <TT
-CLASS="LITERAL"
-><A
-HREF="actions-file.html#FILTER-UNSOLICITED-POPUPS"
->filter{<TT
-CLASS="REPLACEABLE"
-><I
->unsolicited-popups</I
-></TT
->}</A
->
- </TT
->is.
+> 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.
</P
><P
-> Think of it as a fast and efficient replacement for a filter that you
- can use if you don't want any filtering at all. Note that it doesn't make
- sense to combine it with any <TT
+> Cookies with a lifetime below the limit are not modified.
+ The lifetime of session cookies is set to the specified limit.
+ </P
+><P
+> The effect of this action depends on the server.
+ </P
+><P
+> 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.
+ </P
+><P
+> 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.
+ </P
+><P
+> If the parameter is <SPAN
+CLASS="QUOTE"
+>"0"</SPAN
+>, this action behaves like
+ <TT
CLASS="LITERAL"
><A
-HREF="actions-file.html#FILTER"
->filter</A
+HREF="actions-file.html#SESSION-COOKIES-ONLY"
+>session-cookies-only</A
></TT
-> action,
- since as soon as one <TT
-CLASS="LITERAL"
-><A
-HREF="actions-file.html#FILTER"
->filter</A
-></TT
-> applies,
- the whole document needs to be buffered anyway, which destroys the advantage of
- the <TT
-CLASS="LITERAL"
->kill-popups</TT
-> action over its filter equivalent.
- </P
-><P
-> Killing all pop-ups unconditionally is problematic. Many shops and banks rely on
- pop-ups to display forms, shopping carts etc, and the <TT
-CLASS="LITERAL"
-><A
-HREF="actions-file.html#FILTER-UNSOLICITED-POPUPS"
->filter{<TT
-CLASS="REPLACEABLE"
-><I
->unsolicited-popups</I
-></TT
->}</A
->
- </TT
-> does a better job of catching only the unwanted ones.
- </P
-><P
-> If the only kind of pop-ups that you want to kill are exit consoles (those
- <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->really nasty</I
-></SPAN
-> windows that appear when you close an other
- one), you might want to use
- <TT
-CLASS="LITERAL"
-><A
-HREF="actions-file.html#FILTER"
->filter</A
->{<TT
-CLASS="REPLACEABLE"
-><I
->js-annoyances</I
-></TT
->}</TT
->
- instead.
- </P
-><P
-> This action is most appropriate for browsers that don't have any controls
- for unwanted pop-ups. Not recommended for general usage.
- </P
-></DD
-><DT
->Example usage:</DT
-><DD
-><P
-><TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
->+kill-popups</PRE
-></TD
-></TR
-></TABLE
-></P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="LIMIT-CONNECT"
->8.5.28. limit-connect</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Typical use:</DT
-><DD
-><P
->Prevent abuse of <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> as a TCP proxy relay or disable SSL for untrusted sites</P
-></DD
-><DT
->Effect:</DT
-><DD
-><P
-> Specifies to which ports HTTP CONNECT requests are allowable.
- </P
-></DD
-><DT
->Type:</DT
-><DD
-><P
->Parameterized.</P
-></DD
-><DT
->Parameter:</DT
-><DD
-><P
-> A comma-separated list of ports or port ranges (the latter using dashes, with the minimum
- defaulting to 0 and the maximum to 65K).
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> By default, i.e. if no <TT
-CLASS="LITERAL"
->limit-connect</TT
-> action applies,
- <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> only allows HTTP CONNECT
- requests to port 443 (the standard, secure HTTPS port). Use
- <TT
-CLASS="LITERAL"
->limit-connect</TT
-> if more fine-grained control is desired
- for some or all destinations.
+>.
</P
-><P
-> The CONNECT methods exists in HTTP to allow access to secure websites
- (<SPAN
-CLASS="QUOTE"
->"https://"</SPAN
-> URLs) through proxies. It works very simply:
- the proxy connects to the server on the specified port, and then
- short-circuits its connections to the client and to the remote server.
- This can be a big security hole, since CONNECT-enabled proxies can be
- abused as TCP relays very easily.
- </P
-><P
-> <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> relays HTTPS traffic without seeing
- the decoded content. Websites can leverage this limitation to circumvent <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
->'s
- filters. By specifying an invalid port range you can disable HTTPS entirely.
- If you plan to disable SSL by default, consider enabling
- <TT
-CLASS="LITERAL"
-><A
-HREF="actions-file.html#TREAT-FORBIDDEN-CONNECTS-LIKE-BLOCKS"
->treat-forbidden-connects-like-blocks</A
-></TT
->
- as well, to be able to quickly create exceptions.
- </P
></DD
><DT
>Example usages:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->+limit-connect{443} # This is the default and need not be specified.
-+limit-connect{80,443} # Ports 80 and 443 are OK.
-+limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK.
-+limit-connect{-} # All ports are OK
-+limit-connect{,} # No HTTPS/SSL traffic is allowed</PRE
+>+limit-cookie-lifetime{60}</PRE
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
HREF="actions-file.html#FILTER"
>filter</A
></TT
->, <TT
+> and
+ <TT
CLASS="LITERAL"
><A
HREF="actions-file.html#DEANIMATE-GIFS"
>deanimate-gifs</A
></TT
>
- and <TT
-CLASS="LITERAL"
-><A
-HREF="actions-file.html#KILL-POPUPS"
->kill-popups</A
-></TT
-> actions need
- access to the uncompressed data.
+ actions need access to the uncompressed data.
</P
><P
> When compiled with zlib support (available since <SPAN
><P
> 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.
</P
><P
> Not using compression will therefore slow down the transfer, and you should only
><DT
>Example usage (sections):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
> Deletes the <SPAN
CLASS="QUOTE"
>"Last-Modified:"</SPAN
-> HTTP server header or modifies its value.
+> HTTP server header or modifies its value.
</P
></DD
><DT
CLASS="QUOTE"
>"Randomize"</SPAN
>
- makes it impossible and the browser can still revalidate cached documents.
+ makes it impossible and the browser can still revalidate cached documents.
</P
><P
> <SPAN
CLASS="LITERAL"
><A
HREF="actions-file.html#HIDE-IF-MODIFIED-SINCE"
->hided-if-modified-since</A
+>hide-if-modified-since</A
></TT
>
to further customize your random range.
>hided-if-modified-since</A
></TT
>,
- just to be sure.
+ just to be sure.
</P
><P
> It is also recommended to use this action together with
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
single pcrs command to the original URL.
</P
><P
-> This action will be ignored if you use it together with
- <TT
-CLASS="LITERAL"
-><A
-HREF="actions-file.html#BLOCK"
->block</A
-></TT
->.
- It can be combined with
- <TT
-CLASS="LITERAL"
-><A
-HREF="actions-file.html#FAST-REDIRECTS"
->fast-redirects{check-decoded-url}</A
-></TT
->
- to redirect to a decoded version of a rewritten URL.
- </P
-><P
-> Use this action carefully, make sure not to create redirection loops
- and be aware that using your own redirects might make it
- possible to fingerprint your requests.
- </P
-></DD
-><DT
->Example usages:</DT
-><DD
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-># Replace example.com's style sheet with another one
-{ +redirect{http://localhost/css-replacements/example.com.css} }
- example.com/stylesheet\.css
-
-# Create a short, easy to remember nickname for a favorite site
-# (relies on the browser accept and forward invalid URLs to <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
->)
-{ +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
- a
-
-# Always use the expanded view for Undeadly.org articles
-# (Note the $ at the end of the URL pattern to make sure
-# the request for the rewritten URL isn't redirected as well)
-{+redirect{s@$@&mode=expanded@}}
-undeadly.org/cgi\?action=article&sid=\d*$</PRE
-></TD
-></TR
-></TABLE
->
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="SEND-VANILLA-WAFER"
->8.5.32. send-vanilla-wafer</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Typical use:</DT
-><DD
-><P
-> Feed log analysis scripts with useless data.
- </P
-></DD
-><DT
->Effect:</DT
-><DD
-><P
-> Sends a cookie with each request stating that you do not accept any copyright
- on cookies sent to you, and asking the site operator not to track you.
- </P
-></DD
-><DT
->Type:</DT
-><DD
-><P
->Boolean.</P
-></DD
-><DT
->Parameter:</DT
-><DD
-><P
-> N/A
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> The vanilla wafer is a (relatively) unique header and could conceivably be used to track you.
- </P
-><P
-> This action is rarely used and not enabled in the default configuration.
- </P
-></DD
-><DT
->Example usage:</DT
-><DD
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
->+send-vanilla-wafer</PRE
-></TD
-></TR
-></TABLE
->
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="SEND-WAFER"
->8.5.33. send-wafer</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Typical use:</DT
-><DD
-><P
-> Send custom cookies or feed log analysis scripts with even more useless data.
- </P
-></DD
-><DT
->Effect:</DT
-><DD
-><P
-> Sends a custom, user-defined cookie with each request.
- </P
-></DD
-><DT
->Type:</DT
-><DD
-><P
->Multi-value.</P
-></DD
-><DT
->Parameter:</DT
-><DD
-><P
-> A string of the form <SPAN
-CLASS="QUOTE"
->"<TT
-CLASS="REPLACEABLE"
-><I
->name</I
+> The syntax for pcrs commands is documented in the
+ <A
+HREF="filter-file.html"
+>filter file</A
+> section.
+ </P
+><P
+> Requests can't be blocked and redirected at the same time,
+ applying this action together with
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>block</A
></TT
->=<TT
-CLASS="REPLACEABLE"
-><I
->value</I
+>
+ 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.
+ </P
+><P
+> This action can be combined with
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#FAST-REDIRECTS"
+>fast-redirects{check-decoded-url}</A
></TT
->"</SPAN
->.
+>
+ to redirect to a decoded version of a rewritten URL.
</P
-></DD
-><DT
->Notes:</DT
-><DD
><P
-> Being multi-valued, multiple instances of this action can apply to the same request,
- resulting in multiple cookies being sent.
+> Use this action carefully, make sure not to create redirection loops
+ and be aware that using your own redirects might make it
+ possible to fingerprint your requests.
</P
><P
-> This action is rarely used and not enabled in the default configuration.
+> In case of problems with your redirects, or simply to watch
+ them working, enable <A
+HREF="config.html#DEBUG"
+>debug 128</A
+>.
</P
></DD
><DT
->Example usage (section):</DT
+>Example usages:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
->{+send-wafer{UsingPrivoxy=true}}
-my-internal-testing-server.void</PRE
+># Replace example.com's style sheet with another one
+{ +redirect{http://localhost/css-replacements/example.com.css} }
+ example.com/stylesheet\.css
+
+# Create a short, easy to remember nickname for a favorite site
+# (relies on the browser to accept and forward invalid URLs to <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>)
+{ +redirect{https://www.privoxy.org/user-manual/actions-file.html} }
+ a
+
+# Always use the expanded view for Undeadly.org articles
+# (Note the $ at the end of the URL pattern to make sure
+# the request for the rewritten URL isn't redirected as well)
+{+redirect{s@$@&mode=expanded@}}
+undeadly.org/cgi\?action=article&sid=\d*$
+
+# Redirect Google search requests to MSN
+{+redirect{s@^http://[^/]*/search\?q=([^&]*).*@http://search.msn.com/results.aspx?q=$1@}}
+.google.com/search
+
+# Redirect MSN search requests to Yahoo
+{+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@}}
+www.privoxy.org/user-manual/</PRE
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="SERVER-HEADER-FILTER"
->8.5.34. server-header-filter</A
+>8.5.32. server-header-filter</A
></H4
><P
></P
>Type:</DT
><DD
><P
->Parameterized.</P
+>Multi-value.</P
></DD
><DT
>Parameter:</DT
><DT
>Example usage (section):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="SERVER-HEADER-TAGGER"
->8.5.35. server-header-tagger</A
+>8.5.33. server-header-tagger</A
></H4
><P
></P
>Typical use:</DT
><DD
><P
-> Disable or disable filters based on the Content-Type header.
+> Enable or disable filters based on the Content-Type header.
</P
></DD
><DT
>Type:</DT
><DD
><P
->Parameterized.</P
+>Multi-value.</P
></DD
><DT
>Parameter:</DT
><DT
>Example usage (section):</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
><TD
><PRE
CLASS="SCREEN"
-># Tag every request with the declared content type
-{+client-header-tagger{content-type}}
+># Tag every request with the content type declared by the server
+{+server-header-tagger{content-type}}
/
- </PRE
+
+# If the response has a tag starting with 'image/' enable an external
+# filter that only applies to images.
+#
+# Note that the filter is not available by default, it's just a
+# <TT
+CLASS="LITERAL"
+><A
+HREF="filter-file.html#EXTERNAL-FILTER-SYNTAX"
+>silly example</A
+></TT
+>.
+{+external-filter{rotate-image} +force-text-mode}
+TAG:^image/</PRE
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="SESSION-COOKIES-ONLY"
->8.5.36. session-cookies-only</A
+>8.5.34. session-cookies-only</A
></H4
><P
></P
CLASS="EMPHASIS"
>only</I
></SPAN
->).
+>).
</P
></DD
><DT
HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
>crunch-incoming-cookies</A
></TT
-> /
+> /
<TT
CLASS="LITERAL"
><A
>session-cookies-only</TT
> 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.
</P
><P
> <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> also uses
+> also uses
the <A
HREF="actions-file.html#FILTER-CONTENT-COOKIES"
>content-cookies filter</A
->
- to block some types of cookies. Content cookies are not effected by
+>
+ to block some types of cookies. Content cookies are not effected by
<TT
CLASS="LITERAL"
>session-cookies-only</TT
><DT
>Example usage:</DT
><DD
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
></DD
></DL
></DIV
CLASS="SECT3"
><A
NAME="SET-IMAGE-BLOCKER"
->8.5.37. set-image-blocker</A
+>8.5.35. set-image-blocker</A
></H4
><P
></P
to any image anywhere, even in your local filesystem via <SPAN
CLASS="QUOTE"
>"file:///"</SPAN
-> URL.
+> URL.
(But note that not all browsers support redirecting to a local file system).
</P
><P
><P
> Built-in pattern:
</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
><P
> Redirect to the BSD daemon:
</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
><P
> Redirect to the built-in pattern for better caching:
</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="90%"
></TD
></TR
></TABLE
->
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="TREAT-FORBIDDEN-CONNECTS-LIKE-BLOCKS"
->8.5.38. treat-forbidden-connects-like-blocks</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Typical use:</DT
-><DD
-><P
->Block forbidden connects with an easy to find error message.</P
-></DD
-><DT
->Effect:</DT
-><DD
-><P
-> If this action is enabled, <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> no longer
- makes a difference between forbidden connects and ordinary blocks.
- </P
-></DD
-><DT
->Type:</DT
-><DD
-><P
->Boolean</P
-></DD
-><DT
->Parameter:</DT
-><DD
-><P
->N/A</P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> By default <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> answers
- <A
-HREF="actions-file.html#LIMIT-CONNECT"
->forbidden <SPAN
-CLASS="QUOTE"
->"Connect"</SPAN
-> requests</A
->
- with a short error message inside the headers. If the browser doesn't display
- headers (most don't), you just see an empty page.
- </P
-><P
-> With this action enabled, <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> displays
- the message that is used for ordinary blocks instead. If you decide
- to make an exception for the page in question, you can do so by
- following the <SPAN
-CLASS="QUOTE"
->"See why"</SPAN
-> link.
- </P
-><P
-> For <SPAN
-CLASS="QUOTE"
->"Connect"</SPAN
-> requests the clients tell
- <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> which host they are interested
- in, but not which document they plan to get later. As a result, the
- <SPAN
-CLASS="QUOTE"
->"Go there anyway"</SPAN
-> wouldn't work and is therefore suppressed.
- </P
-></DD
-><DT
->Example usage:</DT
-><DD
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
->+treat-forbidden-connects-like-blocks</PRE
-></TD
-></TR
-></TABLE
->
- </P
></DD
></DL
></DIV
><H3
CLASS="SECT3"
><A
-NAME="AEN4157"
->8.5.39. Summary</A
+NAME="SUMMARY"
+>8.5.36. Summary</A
></H3
><P
> 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 <A
HREF="appendix.html#ACTIONSANAT"
CLASS="emphasis"
><I
CLASS="EMPHASIS"
->strongly
+>strongly
recommend</I
></SPAN
> that you only use <SPAN
with it.</P
><P
> Now let's define some aliases...</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
>crunch-outgoing-cookies</A
>
- +block-as-image = +block +handle-as-image
+ +block-as-image = +block{Blocked image.} +handle-as-image
allow-all-cookies = -crunch-all-cookies -<A
HREF="actions-file.html#SESSION-COOKIES-ONLY"
>session-cookies-only</A
HREF="actions-file.html#HIDE-REFERER"
>hide-referrer</A
> -<A
-HREF="actions-file.html#KILL-POPUPS"
->kill-popups</A
-> -<A
HREF="actions-file.html#PREVENT-COMPRESSION"
>prevent-compression</A
>
shop = -crunch-all-cookies -<A
HREF="actions-file.html#FILTER-ALL-POPUPS"
>filter{all-popups}</A
-> -<A
-HREF="actions-file.html#KILL-POPUPS"
->kill-popups</A
>
# Short names for other aliases, for really lazy people ;-)
></TD
></TR
></TABLE
-></P
><P
-> ...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 <SPAN
CLASS="QUOTE"
>"/"</SPAN
> pattern):</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
# Shopping sites:
# Allow cookies (for setting and retrieving your customer data)
- #
+ #
{shop}
.quietpc.com
.worldpay.com # for quietpc.com
# These shops require pop-ups:
#
- {-kill-popups -filter{all-popups} -filter{unsolicited-popups}}
+ {-filter{all-popups} -filter{unsolicited-popups}}
.dabs.com
.overclockers.co.uk</PRE
></TD
></TR
></TABLE
-></P
><P
> Aliases like <SPAN
CLASS="QUOTE"
> and <SPAN
CLASS="QUOTE"
>"fragile"</SPAN
-> are typically used for
+> are typically used for
<SPAN
CLASS="QUOTE"
>"problem"</SPAN
-> 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.</P
></DIV
><DIV
>. Now, let's look at an
example <TT
CLASS="FILENAME"
+>match-all.action</TT
+>, <TT
+CLASS="FILENAME"
>default.action</TT
-> and <TT
+>
+ and <TT
CLASS="FILENAME"
>user.action</TT
->
- file and see how all these pieces come together:</P
+> file and see how all these pieces come together:</P
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="AEN4222"
->8.7.1. default.action</A
+NAME="MATCH-ALL"
+>8.7.1. match-all.action</A
></H3
><P
->Every config file should start with a short comment stating its purpose:</P
+> Remember <SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>all actions are disabled when matching starts</I
+></SPAN
+>,
+ so we have to explicitly enable the ones we want.</P
+><P
+> While the <TT
+CLASS="FILENAME"
+>match-all.action</TT
+> file only contains a
+ single section, it is probably the most important one. It has only one
+ pattern, <SPAN
+CLASS="QUOTE"
+>"<TT
+CLASS="LITERAL"
+>/</TT
+>"</SPAN
+>, but this pattern
+ <A
+HREF="actions-file.html#AF-PATTERNS"
+>matches all URLs</A
+>. Therefore, the set of
+ actions used in this <SPAN
+CLASS="QUOTE"
+>"default"</SPAN
+> section <SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>will
+ be applied to all requests as a start</I
+></SPAN
+>. It can be partly or
+ wholly overridden by other actions files like <TT
+CLASS="FILENAME"
+>default.action</TT
+>
+ and <TT
+CLASS="FILENAME"
+>user.action</TT
+>, but it will still be largely responsible
+ for your overall browsing experience.</P
><P
-> <TABLE
+> Again, at the start of matching, all actions are disabled, so there is
+ no need to disable any actions here. (Remember: a <SPAN
+CLASS="QUOTE"
+>"+"</SPAN
+>
+ preceding the action name enables the action, a <SPAN
+CLASS="QUOTE"
+>"-"</SPAN
+> disables!).
+ Also note how this long line has been made more readable by splitting it into
+ multiple lines with line continuation.</P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TD
><PRE
CLASS="SCREEN"
-># Sample default.action file <ijbswa-developers@lists.sourceforge.net></PRE
+>{ \
+ +<A
+HREF="actions-file.html#CHANGE-X-FORWARDED-FOR"
+>change-x-forwarded-for{block}</A
+> \
+ +<A
+HREF="actions-file.html#HIDE-FROM-HEADER"
+>hide-from-header{block}</A
+> \
+ +<A
+HREF="actions-file.html#SET-IMAGE-BLOCKER"
+>set-image-blocker{pattern}</A
+> \
+}
+/ # Match all URLs
+ </PRE
></TD
></TR
></TABLE
-></P
><P
->Then, since this is the <TT
+> The default behavior is now set.</P
+></DIV
+><DIV
+CLASS="SECT3"
+><H3
+CLASS="SECT3"
+><A
+NAME="DEFAULT-ACTION"
+>8.7.2. default.action</A
+></H3
+><P
+> If you aren't a developer, there's no need for you to edit the
+ <TT
+CLASS="FILENAME"
+>default.action</TT
+> file. It is maintained by
+ the <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> developers and if you disagree with some of the
+ sections, you should overrule them in your <TT
+CLASS="FILENAME"
+>user.action</TT
+>.</P
+><P
+> Understanding the <TT
CLASS="FILENAME"
>default.action</TT
-> file, the
-first section is a special section for internal use that you needn't
-change or worry about:</P
+> file can
+ help you with your <TT
+CLASS="FILENAME"
+>user.action</TT
+>, though.</P
><P
-> <TABLE
+> The first section in this file is a special section for internal use
+ that prevents older <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> versions from reading the file:</P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
>##########################################################################
# Settings -- Don't change! For internal Privoxy use ONLY.
##########################################################################
-
{{settings}}
-for-privoxy-version=3.0</PRE
+for-privoxy-version=3.0.11</PRE
></TD
></TR
></TABLE
-></P
><P
->After that comes the (optional) alias section. We'll use the example
-section from the above <A
+> After that comes the (optional) alias section. We'll use the example
+
section from the above <A
HREF="actions-file.html#ALIASES"
>chapter on aliases</A
>,
-that also explains why and how aliases are used:</P
-><P
-> <TABLE
+ that also explains why and how aliases are used:</P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
>crunch-outgoing-cookies</A
>
- +block-as-image = +block +handle-as-image
+ +block-as-image = +block{Blocked image.} +handle-as-image
mercy-for-cookies = -crunch-all-cookies -<A
HREF="actions-file.html#SESSION-COOKIES-ONLY"
>session-cookies-only</A
> -<A
HREF="actions-file.html#HIDE-REFERER"
>hide-referrer</A
-> -<A
-HREF="actions-file.html#KILL-POPUPS"
->kill-popups</A
>
shop = -crunch-all-cookies -<A
HREF="actions-file.html#FILTER-ALL-POPUPS"
>filter{all-popups}</A
-> -<A
-HREF="actions-file.html#KILL-POPUPS"
->kill-popups</A
></PRE
></TD
></TR
></TABLE
-></P
-><P
-> Now come the regular sections, i.e. sets of actions, accompanied
- by URL patterns to which they apply. Remember <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->all actions
- are disabled when matching starts</I
-></SPAN
->, so we have to explicitly
- enable the ones we want.</P
-><P
-> The first regular section is probably the most important. It has only
- one pattern, <SPAN
-CLASS="QUOTE"
->"<TT
-CLASS="LITERAL"
->/</TT
->"</SPAN
->, but this pattern
- <A
-HREF="actions-file.html#AF-PATTERNS"
->matches all URLs</A
->. Therefore, the
- set of actions used in this <SPAN
-CLASS="QUOTE"
->"default"</SPAN
-> section <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->will
- be applied to all requests as a start</I
-></SPAN
->. 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.</P
-><P
-> Again, at the start of matching, all actions are disabled, so there is
- no real need to disable any actions here, but we will do that nonetheless,
- to have a complete listing for your reference. (Remember: a <SPAN
-CLASS="QUOTE"
->"+"</SPAN
->
- preceding the action name enables the action, a <SPAN
-CLASS="QUOTE"
->"-"</SPAN
-> disables!).
- Also note how this long line has been made more readable by splitting it into
- multiple lines with line continuation.</P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="100%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
->##########################################################################
-# "Defaults" section:
-##########################################################################
- { \
- -<A
-HREF="actions-file.html#ADD-HEADER"
->add-header</A
-> \
- -<A
-HREF="actions-file.html#CLIENT-HEADER-FILTER"
->client-header-filter{hide-tor-exit-notation}</A
-> \
- -<A
-HREF="actions-file.html#BLOCK"
->block</A
-> \
- -<A
-HREF="actions-file.html#CONTENT-TYPE-OVERWRITE"
->content-type-overwrite</A
-> \
- -<A
-HREF="actions-file.html#CRUNCH-CLIENT-HEADER"
->crunch-client-header</A
-> \
- -<A
-HREF="actions-file.html#CRUNCH-IF-NONE-MATCH"
->crunch-if-none-match</A
-> \
- -<A
-HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
->crunch-incoming-cookies</A
-> \
- -<A
-HREF="actions-file.html#CRUNCH-SERVER-HEADER"
->crunch-server-header</A
-> \
- -<A
-HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
->crunch-outgoing-cookies</A
-> \
- +<A
-HREF="actions-file.html#DEANIMATE-GIFS"
->deanimate-gifs</A
-> \
- -<A
-HREF="actions-file.html#DOWNGRADE-HTTP-VERSION"
->downgrade-http-version</A
-> \
- -<A
-HREF="actions-file.html#FAST-REDIRECTS"
->fast-redirects{check-decoded-url}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-JS-ANNOYANCES"
->filter{js-annoyances}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-JS-EVENTS"
->filter{js-events}</A
-> \
- +<A
-HREF="actions-file.html#FILTER-HTML-ANNOYANCES"
->filter{html-annoyances}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-CONTENT-COOKIES"
->filter{content-cookies}</A
-> \
- +<A
-HREF="actions-file.html#FILTER-REFRESH-TAGS"
->filter{refresh-tags}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-UNSOLICITED-POPUPS"
->filter{unsolicited-popups}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-ALL-POPUPS"
->filter{all-popups}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-IMG-REORDER"
->filter{img-reorder}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-BANNERS-BY-SIZE"
->filter{banners-by-size}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-BANNERS-BY-LINK"
->filter{banners-by-link}</A
-> \
- +<A
-HREF="actions-file.html#FILTER-WEBBUGS"
->filter{webbugs}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-TINY-TEXTFORMS"
->filter{tiny-textforms}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-JUMPING-WINDOWS"
->filter{jumping-windows}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-FRAMESET-BORDERS"
->filter{frameset-borders}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-DEMORONIZER"
->filter{demoronizer}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-SHOCKWAVE-FLASH"
->filter{shockwave-flash}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-QUICKTIME-KIOSKMODE"
->filter{quicktime-kioskmode}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-FUN"
->filter{fun}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-CRUDE-PARENTAL"
->filter{crude-parental}</A
-> \
- +<A
-HREF="actions-file.html#FILTER-IE-EXPLOITS"
->filter{ie-exploits}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-GOOGLE"
->filter{google}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-YAHOO"
->filter{yahoo}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-MSN"
->filter{msn}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-BLOGSPOT"
->filter{blogspot}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-NO-PING"
->filter{no-ping}</A
-> \
- -<A
-HREF="actions-file.html#FORCE-TEXT-MODE"
->force-text-mode</A
-> \
- -<A
-HREF="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT"
->handle-as-empty-document</A
-> \
- -<A
-HREF="actions-file.html#HANDLE-AS-IMAGE"
->handle-as-image</A
-> \
- -<A
-HREF="actions-file.html#HIDE-ACCEPT-LANGUAGE"
->hide-accept-language</A
-> \
- -<A
-HREF="actions-file.html#HIDE-CONTENT-DISPOSITION"
->hide-content-disposition</A
-> \
- -<A
-HREF="actions-file.html#HIDE-IF-MODIFIED-SINCE"
->hide-if-modified-since</A
-> \
- +<A
-HREF="actions-file.html#HIDE-FORWARDED-FOR-HEADERS"
->hide-forwarded-for-headers</A
-> \
- +<A
-HREF="actions-file.html#HIDE-FROM-HEADER"
->hide-from-header{block}</A
-> \
- +<A
-HREF="actions-file.html#HIDE-REFERER"
->hide-referrer{forge}</A
-> \
- -<A
-HREF="actions-file.html#HIDE-USER-AGENT"
->hide-user-agent</A
-> \
- -<A
-HREF="actions-file.html#INSPECT-JPEGS"
->inspect-jpegs</A
-> \
- -<A
-HREF="actions-file.html#KILL-POPUPS"
->kill-popups</A
-> \
- -<A
-HREF="actions-file.html#LIMIT-CONNECT"
->limit-connect</A
-> \
- +<A
-HREF="actions-file.html#PREVENT-COMPRESSION"
->prevent-compression</A
-> \
- -<A
-HREF="actions-file.html#OVERWRITE-LAST-MODIFIED"
->overwrite-last-modified</A
-> \
- -<A
-HREF="actions-file.html#REDIRECT"
->redirect</A
-> \
- -<A
-HREF="actions-file.html#SEND-VANILLA-WAFER"
->send-vanilla-wafer</A
-> \
- -<A
-HREF="actions-file.html#SEND-WAFER"
->send-wafer</A
-> \
- -<A
-HREF="actions-file.html#SERVER-HEADER-FILTER"
->server-header-filter{xml-to-html}</A
-> \
- -<A
-HREF="actions-file.html#SERVER-HEADER-FILTER"
->server-header-filter{html-to-xml}</A
-> \
- +<A
-HREF="actions-file.html#SESSION-COOKIES-ONLY"
->session-cookies-only</A
-> \
- +<A
-HREF="actions-file.html#SET-IMAGE-BLOCKER"
->set-image-blocker{pattern}</A
-> \
- -<A
-HREF="actions-file.html#TREAT-FORBIDDEN-CONNECTS-LIKE-BLOCKS"
->treat-forbidden-connects-like-blocks</A
-> \
- }
- / # forward slash will match *all* potential URL patterns.</PRE
-></TD
-></TR
-></TABLE
-></P
-><P
-> The default behavior is now set. Note that some actions, like not hiding
- the user agent, are part of a <SPAN
-CLASS="QUOTE"
->"general policy"</SPAN
-> that applies
- universally and won't get any exceptions defined later. Other choices,
- like not blocking (which is <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->understandably</I
-></SPAN
-> the
- default!) need exceptions, i.e. we need to specify explicitly what we
- want to block in later sections.</P
><P
> The first of our specialized sections is concerned with <SPAN
CLASS="QUOTE"
>
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 <TT
CLASS="LITERAL"
>fragile</TT
> alias instead of stating the list
of actions explicitly:</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
></TD
></TR
></TABLE
-></P
><P
> 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:</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
># Shopping sites:
#
{ shop }
-.quietpc.com
+.quietpc.com
.worldpay.com # for quietpc.com
.jungle.com
.scan.co.uk</PRE
></TD
></TR
></TABLE
-></P
><P
> The <TT
CLASS="LITERAL"
>fast-redirects</A
></TT
>
- action, which we enabled per default above, breaks some sites. So disable
- it for popular sites where we know it misbehaves:</P
-><P
-> <TABLE
+ action, which may have been enabled in <TT
+CLASS="FILENAME"
+>match-all.action</TT
+>,
+ breaks some sites. So disable it for popular sites where we know it misbehaves:</P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
></TD
></TR
></TABLE
-></P
><P
> It is important that <SPAN
CLASS="APPLICATION"
be blocked, a substitute image can be sent, rather than an HTML page.
Contacting the remote site to find out is not an option, since it
would destroy the loading time advantage of banner blocking, and it
- would feed the advertisers (in terms of money <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->and</I
-></SPAN
->
- information). We can mark any URL as an image with the <TT
+ would feed the advertisers information about you. We can mark any
+ URL as an image with the <TT
CLASS="LITERAL"
><A
HREF="actions-file.html#HANDLE-AS-IMAGE"
> action,
and marking all URLs that end in a known image file extension is a
good start:</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
></TD
></TR
></TABLE
-></P
><P
> 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
>{pattern}</TT
>
action before, it still applies and needn't be repeated:</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
># Known ad generators:
#
{ +block-as-image }
-ar.atwola.com
+ar.atwola.com
.ad.doubleclick.net
.ad.*.doubleclick.net
.a.yimg.com/(?:(?!/i/).)*$
></TD
></TR
></TABLE
-></P
><P
> One of the most important jobs of <SPAN
CLASS="APPLICATION"
matching typical domain and path name components of banners. Then comes
a list of individual patterns for specific sites, which is omitted here
to keep the example short:</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
##########################################################################
{ <A
HREF="actions-file.html#BLOCK"
->+block</A
+>+block{Banner ads.}</A
> }
# Generic patterns:
-#
+#
ad*.
.*ads.
banner?.
></TD
></TR
></TABLE
-></P
><P
> It's quite remarkable how many advertisers actually call their banner
servers ads.<TT
>company</I
></TT
>.com, or call the directory
- in which the banners are stored simply <SPAN
+ in which the banners are stored literally <SPAN
CLASS="QUOTE"
>"banners"</SPAN
>. So the above
to block. The pattern <TT
CLASS="LITERAL"
>.*ads.</TT
-> e.g. catches
+> e.g. catches
<SPAN
CLASS="QUOTE"
>"nasty-<SPAN
>block</A
></TT
> action applying.</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
##########################################################################
# By domain:
-#
+#
{ -<A
HREF="actions-file.html#BLOCK"
>block</A
></TD
></TR
></TABLE
-></P
><P
> Filtering source code can have nasty side effects,
so make an exception for our friends at sourceforge.net,
>all</I
></SPAN
> filters in one fell swoop!</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
></TD
></TR
></TABLE
-></P
><P
> The actual <TT
CLASS="FILENAME"
><H3
CLASS="SECT3"
><A
-NAME="AEN4409"
->8.7.2. user.action</A
+NAME="USER-ACTION"
+>8.7.3. user.action</A
></H3
><P
> 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 <TT
CLASS="FILENAME"
>user.action</TT
->, 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. <TT
CLASS="FILENAME"
>user.action</TT
-> is also a
+> is also a
<SPAN
CLASS="emphasis"
><I
<TT
CLASS="FILENAME"
>user.action</TT
->: </P
-><P
-> <TABLE
+>:</P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TD
><PRE
CLASS="SCREEN"
-># My user.action file. <fred@foobar.com></PRE
+># My user.action file. <fred@example.com></PRE
></TD
></TR
></TABLE
-></P
><P
> As <A
HREF="actions-file.html#ALIASES"
CLASS="FILENAME"
>default.action</TT
>, unless you repeat them here:</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
# (Re-)define aliases for this file:
#
{{alias}}
-#
-# These aliases just save typing later, and the alias names should
+#
+# These aliases just save typing later, and the alias names should
# be self explanatory.
#
+crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
-crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
allow-all-cookies = -crunch-all-cookies -session-cookies-only
- allow-popups = -filter{all-popups} -kill-popups
-+block-as-image = +block +handle-as-image
+ allow-popups = -filter{all-popups}
++block-as-image = +block{Blocked as image.} +handle-as-image
-block-as-image = -block
# These aliases define combinations of actions that are useful for
# certain types of sites:
#
-fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer -kill-popups
+fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer
shop = -crunch-all-cookies allow-popups
# Allow ads for selected useful free sites:
></TD
></TR
></TABLE
-> </P
><P
> 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
CLASS="LITERAL"
>allow-all-cookies</TT
> 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.</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
></TD
></TR
></TABLE
-></P
><P
> Your bank is allergic to some filter, but you don't know which, so you disable them all:</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
></TD
></TR
></TABLE
-></P
><P
> Some file types you may not want to filter for various reasons:</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
></TD
></TR
></TABLE
-></P
><P
> Example of a simple <A
HREF="actions-file.html#BLOCK"
CLASS="QUOTE"
>"copy image location"</SPAN
>
- and pasted the URL below while removing the leading http://, into a
+ and pasted the URL below while removing the leading http://, into a
<TT
CLASS="LITERAL"
->{ +block }</TT
+>{ +block{} }</TT
> section. Note that <TT
CLASS="LITERAL"
>{ +handle-as-image
>.gif</TT
> will be tagged as images by the general rules as set
in default.action anyway:</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
>{ +<A
HREF="actions-file.html#BLOCK"
>block</A
-> }
+>{Nasty ads.} }
www.example.com/nasty-ads/sponsor\.gif
- another.popular.site.net/more/junk/here/</PRE
+ another.example.net/more/junk/here/</PRE
></TD
></TR
></TABLE
-></P
><P
> The URLs of dynamically generated banners, especially from large banner
farms, often don't use the well-known image file name extensions, which
CLASS="APPLICATION"
>Privoxy</SPAN
> to guess
- the file type just by looking at the URL.
+ the file type just by looking at the URL.
You can use the <TT
CLASS="LITERAL"
>+block-as-image</TT
>"broken image"</SPAN
> icon by the
browser. Use cautiously.</P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
></TD
></TR
></TABLE
-></P
><P
> 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
CLASS="APPLICATION"
>Privoxy</SPAN
>
- 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:</P
-><P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
></TD
></TR
></TABLE
-></P
><P
> You like the <SPAN
CLASS="QUOTE"
CLASS="FILENAME"
>default.filter</TT
>,
- but it is disabled in the distributed actions file. (My colleagues on the team just
- don't have a sense of humour, that's why! ;-). So you'd like to turn it on in your private,
+ but it is disabled in the distributed actions file.
+ So you'd like to turn it on in your private,
update-safe config, once and for all:</P
-><P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
></TD
></TR
></TABLE
-></P
><P
> Note that the above is not really a good idea: There are exceptions
to the filters in <TT
funded, and find that they rely on displaying banner advertisements
to survive. So you might want to specifically allow banners for those
sites that you feel provide value to you:</P
-><P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
></TD
></TR
></TABLE
-> </P
><P
> Note that <TT
CLASS="LITERAL"
>allow-ads</TT
-> has been aliased to
+> has been aliased to
<TT
CLASS="LITERAL"
>-<A
HREF="actions-file.html#BLOCK"
>block</A
></TT
->,
+>,
<TT
CLASS="LITERAL"
>-<A
HREF="actions-file.html#FILTER-BANNERS-BY-SIZE"
>filter{banners-by-size}</A
></TT
->, and
+>, and
<TT
CLASS="LITERAL"
>-<A
> Invoke another alias here to force an over-ride of the MIME type <TT
CLASS="LITERAL"
> application/x-sh</TT
-> 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.</P
-><P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
></TD
></TR
></TABLE
-> </P
><P
> <TT
CLASS="FILENAME"
>"/"</SPAN
> of course matches all URL
paths and patterns:</P
-><P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
></TD
></TR
></TABLE
-></P
></DIV
></DIV
></DIV
projects / privoxy.git / blobdiff