>Actions Files</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.64
-"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.60"><LINK
REL="HOME"
TITLE="Privoxy User Manual"
HREF="index.html"><LINK
><UL
><LI
><P
-> <TT
-CLASS="FILENAME"
->standard.action</TT
-> - is used by the web based editor,
- to set various pre-defined sets of rules for the default actions section
- in <TT
-CLASS="FILENAME"
->default.action</TT
->. These have increasing levels of
- aggressiveness <I
-CLASS="EMPHASIS"
->and have no influence on your browsing unless
- you select them explicitly in the editor</I
->. It is not recommend
- to edit this file.
- </P
-></LI
-><LI
-><P
> <TT
CLASS="FILENAME"
>default.action</TT
thing should go here. This file will not be upgraded.
</P
></LI
+><LI
+><P
+> <TT
+CLASS="FILENAME"
+>standard.action</TT
+> - is used by the web based editor,
+ to set various pre-defined sets of rules for the default actions section
+ in <TT
+CLASS="FILENAME"
+>default.action</TT
+>. These have increasing levels of
+ aggressiveness <I
+CLASS="EMPHASIS"
+>and have no influence on your browsing unless
+ you select them explicitly in the editor</I
+>. It is not recommend
+ to edit this file.
+ </P
+></LI
></UL
>
</P
><H2
CLASS="SECT2"
><A
-NAME="AEN1378"
+NAME="AEN1403"
>8.1. Finding the Right Mix</A
></H2
><P
><H2
CLASS="SECT2"
><A
-NAME="AEN1385"
+NAME="AEN1410"
>8.2. How to Edit</A
></H2
><P
><H2
CLASS="SECT2"
><A
-NAME="AEN1394"
+NAME="ACTIONS-APPLY"
>8.3. How Actions are Applied to URLs</A
></H2
><P
><H2
CLASS="SECT2"
><A
-NAME="AEN1408"
+NAME="AF-PATTERNS"
>8.4. Patterns</A
></H2
><P
><H3
CLASS="SECT3"
><A
-NAME="AEN1448"
+NAME="AEN1473"
>8.4.1. The Domain Pattern</A
></H3
><P
><H3
CLASS="SECT3"
><A
-NAME="AEN1510"
+NAME="AEN1535"
>8.4.2. The Path Pattern</A
></H3
><P
NAME="ADD-HEADER"
>8.5.1. <I
CLASS="EMPHASIS"
->+add-header</I
+>add-header</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Multi-value.</P
+>Confuse log analysis, custom applications</P
></DD
><DT
->Purpose and typical uses:</DT
+>Effect:</DT
><DD
><P
-> Send a user defined HTTP header to the web server. Can be used to confuse log analysis.
+> Sends a user defined HTTP header to the web server.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
+><DD
+><P
+>Multi-value.</P
+></DD
+><DT
+>Parameter:</DT
><DD
><P
-> Any value is possible. Validity of the defined HTTP headers is not checked.
+> Any string value is possible. Validity of the defined HTTP headers is not checked.
It is recommended that you use the <SPAN
CLASS="QUOTE"
>"<TT
</P
></DD
><DT
->Example usage:</DT
-><DD
-><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+add-header{X-User-Tracking: sucks}}</I
-><br>
- <I
-CLASS="EMPHASIS"
->.example.com</I
-></P
-></DD
-><DT
>Notes:</DT
><DD
><P
one.
</P
></DD
+><DT
+>Example usage:</DT
+><DD
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+add-header{X-User-Tracking: sucks}</PRE
+></TD
+></TR
+></TABLE
+>
+ </P
+></DD
></DL
></DIV
></DIV
NAME="BLOCK"
>8.5.2. <I
CLASS="EMPHASIS"
->+block</I
+>block</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Boolean.</P
+>Block ads or other obnoxious content</P
></DD
><DT
->Purpose and typical uses:</DT
+>Effect:</DT
><DD
><P
> Requests for URLs to which this action applies are blocked, i.e. the requests are not
forwarded to the remote server, but answered locally with a substitute page or image,
- as determined by the <A
+ as determined by the <TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#HANDLE-AS-IMAGE"
>handle-as-image</A
-> and
- <A
+></TT
+>
+ and <TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#SET-IMAGE-BLOCKER"
>set-image-blocker</A
+></TT
> actions.
- It is typically used to block ads or other obnoxious content.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
><DD
><P
->N/A</P
+>Boolean.</P
></DD
><DT
->Example usage:</DT
+>Parameter:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+block}</I
-><br>
- <I
-CLASS="EMPHASIS"
->.banners.example.com</I
-><br>
- <I
-CLASS="EMPHASIS"
->.ads.r.us</I
-><br>
- </P
+>N/A</P
></DD
><DT
>Notes:</DT
><DD
><P
-> If a URL matches one of the blocked patterns, <SPAN
+> <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
->
- will intercept the URL and display its special <SPAN
+> sends a special <SPAN
CLASS="QUOTE"
>"BLOCKED"</SPAN
> page
- instead. If there is sufficient space, a large red banner will appear with
- a friendly message about why the page was blocked, and a way to go there
- anyway. If there is insufficient space a smaller <SPAN
+ 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
>
- page will appear without the red banner.
+ right now, you can take a look at the
<A
HREF="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"
TARGET="_top"
->Click here</A
+><SPAN
+CLASS="QUOTE"
+>"BLOCKED"</SPAN
>
- to view the default blocked HTML page (<SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> must be running
- for this to work as intended!).
+ page</A
+>.
</P
><P
>
- A very important exception is if the URL <I
+ A very important exception occurs if <I
CLASS="EMPHASIS"
->matches both</I
->
- <SPAN
-CLASS="QUOTE"
->"+block"</SPAN
-> and <A
+>both</I
+>
+ <TT
+CLASS="LITERAL"
+>block</TT
+> and <TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#HANDLE-AS-IMAGE"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+handle-as-image"</SPAN
-></A
+>handle-as-image</A
+></TT
>,
- then it will be handled by
- <A
+ apply to the same request: it will then be replaced by an image. If
+ <TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#SET-IMAGE-BLOCKER"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+set-image-blocker"</SPAN
-></A
+>set-image-blocker</A
+></TT
>
- (see below). It is important to understand this process, in order
+ (see below) also applies, the type of image will be determined by its parameter,
+ if not, the standard checkerboard pattern is sent.
+ </P
+><P
+> It is important to understand this process, in order
to understand how <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> is able to deal with
- ads and other objectionable content.
+> deals with
+ ads and other unwanted content.
</P
><P
-> The <A
+> The <TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#FILTER"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+filter"</SPAN
-></A
+>filter</A
+></TT
>
- action can also perform some of the
- same functionality as <SPAN
+ action can perform a very similar task, by <SPAN
CLASS="QUOTE"
->"+block"</SPAN
->, but by virtue of very
- different programming techniques, and is most often used for different
- reasons.
+>"blocking"</SPAN
+>
+ banner images and other content through rewriting the relevant URLs in the
+ document's HTML source, so they don't get requested in the first place.
+ Note that this is a totally different technique, and it's easy to confuse the two.
</P
></DD
+><DT
+>Example usage (section):</DT
+><DD
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>{+block} # Block and replace with "blocked" page
+.nasty-stuff.example.com
+
+{+block +handle-as-image} # Block and replace with image
+.ad.doubleclick.net
+.ads.r.us</PRE
+></TD
+></TR
+></TABLE
+>
+ </P
+></DD
></DL
></DIV
></DIV
><H4
CLASS="SECT3"
><A
-NAME="DEANIMATE-GIFS"
+NAME="CRUNCH-INCOMING-COOKIES"
>8.5.3. <I
CLASS="EMPHASIS"
->+deanimate-gifs</I
+>crunch-incoming-cookies</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Parameterized.</P
+> Prevent the web server from setting any cookies on your system
+ </P
></DD
><DT
->Typical uses:</DT
+>Effect:</DT
><DD
><P
-> To stop those annoying, distracting animated GIF images.
+> Deletes any <SPAN
+CLASS="QUOTE"
+>"Set-Cookie:"</SPAN
+> HTTP headers from server replies.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
><DD
><P
-> <SPAN
-CLASS="QUOTE"
->"last"</SPAN
-> or <SPAN
-CLASS="QUOTE"
->"first"</SPAN
->
+>Boolean.</P
+></DD
+><DT
+>Parameter:</DT
+><DD
+><P
+> N/A
</P
></DD
><DT
->Example usage:</DT
+>Notes:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
+> This action is only concerned with <I
+CLASS="EMPHASIS"
+>incoming</I
+> cookies. For
+ <I
+CLASS="EMPHASIS"
+>outgoing</I
+> cookies, use
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
+>crunch-outgoing-cookies</A
+></TT
+>.
+ Use <I
CLASS="EMPHASIS"
->{+deanimate-gifs{last}}</I
-><br>
- <I
+>both</I
+> to disable cookies completely.
+ </P
+><P
+> It makes <I
CLASS="EMPHASIS"
->.example.com</I
-><br>
- </P
+>no sense at all</I
+> to use this action in conjunction
+ with the <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#SESSION-COOKIES-ONLY"
+>session-cookies-only</A
+></TT
+> action,
+ since it would prevent the session cookies from being set.
+ </P
></DD
><DT
->Notes:</DT
+>Example usage:</DT
><DD
><P
-> De-animate all animated GIF images, i.e. reduce them to their last frame.
- This will also shrink the images considerably (in bytes, not pixels!). If
- the option <SPAN
-CLASS="QUOTE"
->"first"</SPAN
-> is given, the first frame of the animation
- is used as the replacement. If <SPAN
-CLASS="QUOTE"
->"last"</SPAN
-> is given, the last
- frame of the animation is used instead, which probably makes more sense for
- most banner animations, but also has the risk of not showing the entire
- last frame (if it is only a delta to an earlier frame).
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+crunch-incoming-cookies</PRE
+></TD
+></TR
+></TABLE
+>
</P
></DD
></DL
><H4
CLASS="SECT3"
><A
-NAME="DOWNGRADE-HTTP-VERSION"
+NAME="CRUNCH-OUTGOING-COOKIES"
>8.5.4. <I
CLASS="EMPHASIS"
->+downgrade-http-version</I
+>crunch-outgoing-cookies</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Boolean.</P
+> Prevent the web server from reading any cookies from your system
+ </P
></DD
><DT
->Typical uses:</DT
+>Effect:</DT
><DD
><P
-> <SPAN
+> Deletes any <SPAN
CLASS="QUOTE"
->"+downgrade-http-version"</SPAN
-> will downgrade HTTP/1.1 client requests to
- HTTP/1.0 and downgrade the responses as well.
+>"Cookie:"</SPAN
+> HTTP headers from client requests.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
+><DD
+><P
+>Boolean.</P
+></DD
+><DT
+>Parameter:</DT
><DD
><P
> N/A
</P
></DD
><DT
->Example usage:</DT
+>Notes:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
+> This action is only concerned with <I
+CLASS="EMPHASIS"
+>outgoing</I
+> cookies. For
+ <I
+CLASS="EMPHASIS"
+>incoming</I
+> cookies, use
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
+>crunch-incoming-cookies</A
+></TT
+>.
+ Use <I
CLASS="EMPHASIS"
->{+downgrade-http-version}</I
-><br>
- <I
+>both</I
+> to disable cookies completely.
+ </P
+><P
+> It makes <I
CLASS="EMPHASIS"
->.example.com</I
-><br>
- </P
+>no sense at all</I
+> to use this action in conjunction
+ with the <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#SESSION-COOKIES-ONLY"
+>session-cookies-only</A
+></TT
+> action,
+ since it would prevent the session cookies from being read.
+ </P
></DD
><DT
->Notes:</DT
+>Example usage:</DT
><DD
><P
-> Use this action for servers that use HTTP/1.1 protocol features that
- <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> doesn't handle well yet. HTTP/1.1 is
- only partially implemented. Default is not to downgrade requests. This is
- an infrequently needed action, and is used to help with rare problem sites only.
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+crunch-outgoing-cookies</PRE
+></TD
+></TR
+></TABLE
+>
</P
></DD
></DL
><H4
CLASS="SECT3"
><A
-NAME="FAST-REDIRECTS"
+NAME="DEANIMATE-GIFS"
>8.5.5. <I
CLASS="EMPHASIS"
->+fast-redirects</I
+>deanimate-gifs</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Boolean.</P
+>Stop those annoying, distracting animated GIF images.</P
></DD
><DT
->Typical uses:</DT
+>Effect:</DT
><DD
><P
-> The <SPAN
-CLASS="QUOTE"
->"+fast-redirects"</SPAN
-> action enables interception of
- <SPAN
+> De-animate GIF animations, i.e. reduce them to their first or last image.
+ </P
+></DD
+><DT
+>Type:</DT
+><DD
+><P
+>Parameterized.</P
+></DD
+><DT
+>Parameter:</DT
+><DD
+><P
+> <SPAN
CLASS="QUOTE"
->"redirect"</SPAN
-> requests from one server to another, which
- are used to track users.<SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> can cut off
- all but the last valid URL in a redirect request and send a local redirect
- back to your browser without contacting the intermediate site(s).
+>"last"</SPAN
+> or <SPAN
+CLASS="QUOTE"
+>"first"</SPAN
+>
</P
></DD
><DT
->Possible values:</DT
+>Notes:</DT
><DD
><P
-> N/A
+> This will also shrink the images considerably (in bytes, not pixels!). If
+ the option <SPAN
+CLASS="QUOTE"
+>"first"</SPAN
+> is given, the first frame of the animation
+ is used as the replacement. If <SPAN
+CLASS="QUOTE"
+>"last"</SPAN
+> is given, the last
+ frame of the animation is used instead, which probably makes more sense for
+ most banner animations, but also has the risk of not showing the entire
+ last frame (if it is only a delta to an earlier frame).
+ </P
+><P
+> You can safely use this action with patterns that will also match non-GIF
+ objects, because no attempt will be made at anything that doesn't look like
+ a GIF.
</P
></DD
><DT
>Example usage:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+deanimate-gifs{last}</PRE
+></TD
+></TR
+></TABLE
+>
+ </P
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="SECT3"
+><H4
+CLASS="SECT3"
+><A
+NAME="DOWNGRADE-HTTP-VERSION"
+>8.5.6. <I
CLASS="EMPHASIS"
->{+fast-redirects}</I
-><br>
- <I
+>downgrade-http-version</I
+></A
+></H4
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>Typical use:</DT
+><DD
+><P
+>Work around (very rare) problems with HTTP/1.1</P
+></DD
+><DT
+>Effect:</DT
+><DD
+><P
+> Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
+ </P
+></DD
+><DT
+>Type:</DT
+><DD
+><P
+>Boolean.</P
+></DD
+><DT
+>Parameter:</DT
+><DD
+><P
+> N/A
+ </P
+></DD
+><DT
+>Notes:</DT
+><DD
+><P
+> This is a left-over from the time when <SPAN
+CLASS="APPLICATION"
+>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 (optional) HTTP/1.1 features are supported yet, so there
+ is a chance you might need this action.
+ </P
+></DD
+><DT
+>Example usage (section):</DT
+><DD
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>{+downgrade-http-version}
+problem-host.example.com</PRE
+></TD
+></TR
+></TABLE
+>
+ </P
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="SECT3"
+><H4
+CLASS="SECT3"
+><A
+NAME="FAST-REDIRECTS"
+>8.5.7. <I
CLASS="EMPHASIS"
->.example.com</I
-><br>
- </P
+>fast-redirects</I
+></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
+> Cut off all but the last valid URL from requests.
+ </P
+></DD
+><DT
+>Type:</DT
+><DD
+><P
+>Boolean.</P
+></DD
+><DT
+>Parameter:</DT
+><DD
+><P
+> N/A
+ </P
></DD
><DT
>Notes:</DT
><P
>
Many sites, like yahoo.com, don't just link to other sites. Instead, they
- will link to some script on their own server, giving the destination as a
+ 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:
<I
CLASS="EMPHASIS"
->http://some.place/some_script?http://some.where-else</I
+>http://some.place/click-tracker.cgi?target=http://some.where.else</I
>.
</P
><P
the advertisers.
</P
><P
-> This is a normally <SPAN
-CLASS="QUOTE"
->"on"</SPAN
-> feature, and often requires exceptions
- for sites that are sensitive to defeating this mechanism.
+> This feature is currently not very smart and is scheduled for improvement.
+ It is likely to break some sites. You should expect to need possibly
+ many exceptions to this action, if it is enabled by default in
+ <TT
+CLASS="FILENAME"
+>default.action</TT
+>. Some sites just don't work without
+ it.
</P
></DD
+><DT
+>Example usage:</DT
+><DD
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>{+fast-redirects}</PRE
+></TD
+></TR
+></TABLE
+>
+ </P
+></DD
></DL
></DIV
></DIV
CLASS="SECT3"
><A
NAME="FILTER"
->8.5.6. <I
+>8.5.8. <I
CLASS="EMPHASIS"
->+filter</I
+>filter</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
+>Typical use:</DT
+><DD
+><P
+>Get rid of HTML and JavaScript annoyances, banner advertisements (by size), do fun text replacements, etc.</P
+></DD
+><DT
+>Effect:</DT
+><DD
+><P
+> Text documents, including HTML and JavaScript, to which this action applies, are filtered on-the-fly
+ through the specified regular expression based substitutions.
+ </P
+></DD
+><DT
>Type:</DT
><DD
><P
>Parameterized.</P
></DD
><DT
->Typical uses:</DT
+>Parameter:</DT
><DD
><P
-> Apply page filtering as defined by named sections of the
- <TT
+> The name of a filter, as defined in the <A
+HREF="filter-file.html"
+>filter file</A
+>
+ (typically <TT
CLASS="FILENAME"
>default.filter</TT
-> file to the specified site(s).
- <SPAN
-CLASS="QUOTE"
->"Filtering"</SPAN
-> can be any modification of the raw
- page content, including re-writing or deletion of content.
+>, set by the
+ <TT
+CLASS="LITERAL"
+><A
+HREF="config.html#FILTERFILE"
+>filterfile</A
+></TT
+>
+ option in the <A
+HREF="config.html"
+>config file</A
+>)
</P
></DD
><DT
->Possible values:</DT
+>Notes:</DT
><DD
><P
-> <SPAN
+> For your convenience, there are a bunch of pre-defined filters available
+ in the distribution filter file that you can use. See the example below for
+ a list.
+ </P
+><P
+> This is potentially a very powerful feature! But <SPAN
CLASS="QUOTE"
->"+filter"</SPAN
-> must include the name of one of the section identifiers
- from <TT
-CLASS="FILENAME"
->default.filter</TT
-> (or whatever
- <I
-CLASS="EMPHASIS"
->filterfile</I
-> is specified in <TT
-CLASS="FILENAME"
->config</TT
->).
+>"rolling your own"</SPAN
+>
+ filters requires a knowledge of regular expressions and HTML.
+ </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.
+ </P
+><P
+> At this time, <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> cannot (yet!) uncompress compressed
+ documents. If you want filtering to work on all documents, even those that
+ would normally be sent compressed, use the
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#PREVENT-COMPRESSION"
+>prevent-compression</A
+></TT
+>
+ action in conjunction with <TT
+CLASS="LITERAL"
+>filter</TT
+>.
+ </P
+><P
+> Filtering can achieve some of the effects as the
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>block</A
+></TT
+>
+ action, i.e. it can be used to block ads and banners.
+ </P
+><P
+> <A
+HREF="contact.html"
+>Feedback</A
+> with suggestions for new or improved filters is particularly
+ welcome!
</P
></DD
><DT
->Example usage (from the current <TT
+>Example usage (with filters from the distribution <TT
CLASS="FILENAME"
>default.filter</TT
->):</DT
+> file):</DT
><DD
><P
-></P
-><TABLE
-BORDER="0"
-><TBODY
-><TR
-><TD
> <A
NAME="FILTER-HTML-ANNOYANCES"
></A
>
- <I
-CLASS="EMPHASIS"
->+filter{html-annoyances}</I
->: Get rid of particularly annoying HTML abuse.
- </TD
-></TR
-></TBODY
-></TABLE
-><P
-></P
-><P
-></P
-><TABLE
+ <TABLE
BORDER="0"
-><TBODY
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
><TR
><TD
-> <A
-NAME="FILTER-JS-ANNOYANCES"
-></A
->
- <I
-CLASS="EMPHASIS"
->+filter{js-annoyances}</I
->: Get rid of particularly annoying JavaScript abuse
- </TD
+><PRE
+CLASS="SCREEN"
+>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse.</PRE
+></TD
></TR
-></TBODY
></TABLE
+>
+ </P
><P
-></P
-><P
-></P
-><TABLE
+> <A
+NAME="FILTER-JS-ANNOYANCES"
+></A
+>
+ <TABLE
BORDER="0"
-><TBODY
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
><TR
><TD
+><PRE
+CLASS="SCREEN"
+>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse</PRE
+></TD
+></TR
+></TABLE
+>
+ </P
+><P
> <A
-NAME="FILTER-CONTENT-COOKIES"
+NAME="FILTER-BANNERS-BY-SIZE"
></A
>
- <I
+ <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+filter{banners-by-size} # Kill banners by size (<I
CLASS="EMPHASIS"
->+filter{content-cookies}</I
->: Kill cookies that come in the HTML or JS content
- </TD
+>very</I
+> efficient!)</PRE
+></TD
></TR
-></TBODY
></TABLE
+>
+ </P
><P
-></P
-><P
-></P
-><TABLE
+> <A
+NAME="FILTER-CONTENT-COOKIES"
+></A
+>
+ <TABLE
BORDER="0"
-><TBODY
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
><TR
><TD
+><PRE
+CLASS="SCREEN"
+>+filter{content-cookies} # Kill cookies that come sneaking in the HTML or JS content</PRE
+></TD
+></TR
+></TABLE
+>
+ </P
+><P
> <A
NAME="FILTER-POPUPS"
></A
>
- <I
-CLASS="EMPHASIS"
->+filter{popups}</I
->: Kill all popups in JS and HTML
- </TD
-></TR
-></TBODY
-></TABLE
-><P
-></P
-><P
-></P
-><TABLE
+ <TABLE
BORDER="0"
-><TBODY
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
><TR
><TD
-> <A
-NAME="FILTER-FRAMESET-BORDERS"
-></A
->
- <I
-CLASS="EMPHASIS"
->+filter{frameset-borders}</I
->: Give frames a border and make them resizable
- </TD
+><PRE
+CLASS="SCREEN"
+>+filter{popups} # Kill all popups in JS and HTML</PRE
+></TD
></TR
-></TBODY
></TABLE
+>
+ </P
><P
-></P
-><P
-></P
-><TABLE
-BORDER="0"
-><TBODY
-><TR
-><TD
> <A
NAME="FILTER-WEBBUGS"
></A
>
- <I
-CLASS="EMPHASIS"
->+filter{webbugs}</I
->: Squish WebBugs (1x1 invisible GIFs used for user tracking)
- </TD
-></TR
-></TBODY
-></TABLE
-><P
-></P
-><P
-></P
-><TABLE
+ <TABLE
BORDER="0"
-><TBODY
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
><TR
><TD
-> <A
-NAME="FILTER-REFRESH-TAGS"
-></A
->
- <I
-CLASS="EMPHASIS"
->+filter{refresh-tags}</I
->: Kill automatic refresh tags (for dial-on-demand setups)
- </TD
+><PRE
+CLASS="SCREEN"
+>+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking)</PRE
+></TD
></TR
-></TBODY
></TABLE
+>
+ </P
><P
-></P
-><P
-></P
-><TABLE
-BORDER="0"
-><TBODY
-><TR
-><TD
> <A
NAME="FILTER-FUN"
></A
>
- <I
-CLASS="EMPHASIS"
->+filter{fun}</I
->: Text replacements for subversive browsing fun!
- </TD
-></TR
-></TBODY
-></TABLE
-><P
-></P
-><P
-></P
-><TABLE
+ <TABLE
BORDER="0"
-><TBODY
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
><TR
><TD
-> <A
-NAME="FILTER-NIMDA"
-></A
->
- <I
-CLASS="EMPHASIS"
->+filter{nimda}</I
->: Remove Nimda (virus) code.
- </TD
+><PRE
+CLASS="SCREEN"
+>+filter{fun} # Text replacements for subversive browsing fun!</PRE
+></TD
></TR
-></TBODY
></TABLE
+>
+ </P
><P
-></P
-><P
-></P
-><TABLE
+> <A
+NAME="FILTER-FRAMESET-BORDERS"
+></A
+>
+ <TABLE
BORDER="0"
-><TBODY
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
><TR
><TD
+><PRE
+CLASS="SCREEN"
+>+filter{frameset-borders} # Give frames a border and make them resizeable</PRE
+></TD
+></TR
+></TABLE
+>
+ </P
+><P
> <A
-NAME="FILTER-BANNERS-BY-SIZE"
+NAME="FILTER-REFRESH-TAGS"
></A
>
- <I
-CLASS="EMPHASIS"
->+filter{banners-by-size}</I
->: Kill banners by size (<I
-CLASS="EMPHASIS"
->very</I
-> efficient!)
- </TD
+ <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups)</PRE
+></TD
></TR
-></TBODY
></TABLE
+>
+ </P
><P
-></P
-><P
-></P
-><TABLE
+> <A
+NAME="FILTER-NIMDA"
+></A
+>
+ <TABLE
BORDER="0"
-><TBODY
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
><TR
><TD
+><PRE
+CLASS="SCREEN"
+>+filter{nimda} # Remove Nimda (virus) code.</PRE
+></TD
+></TR
+></TABLE
+>
+ </P
+><P
> <A
NAME="FILTER-SHOCKWAVE-FLASH"
></A
>
- <I
-CLASS="EMPHASIS"
->+filter{shockwave-flash}</I
->: Kill embedded Shockwave Flash objects
- </TD
-></TR
-></TBODY
-></TABLE
-><P
-></P
-><P
-></P
-><TABLE
+ <TABLE
BORDER="0"
-><TBODY
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
><TR
><TD
+><PRE
+CLASS="SCREEN"
+>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects</PRE
+></TD
+></TR
+></TABLE
+>
+ </P
+><P
> <A
NAME="FILTER-CRUDE-PARENTAL"
></A
>
- <I
-CLASS="EMPHASIS"
->+filter{crude-parental}</I
->: Kill all web pages that contain the words "sex" or "warez"
- </TD
+ <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+filter{crude-parental} # Kill all web pages that contain the words "sex" or "warez"</PRE
+></TD
></TR
-></TBODY
></TABLE
-><P
-></P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> This is potentially a very powerful feature! And requires a knowledge
- of regular expressions if you want to <SPAN
-CLASS="QUOTE"
->"roll your own"</SPAN
->.
- Filtering operates on a line by line basis throughout the entire page.
- </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.
- </P
-><P
-> Filtering can achieve some of the effects as the
- <A
-HREF="actions-file#BLOCK"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+block"</SPAN
-></A
>
- action, i.e. it can be used to block ads and banners. In the overall
- scheme of things, filtering is one of the first things <SPAN
-CLASS="QUOTE"
->"Privoxy"</SPAN
->
- does with a web page. So other most other actions are applied to the
- already <SPAN
-CLASS="QUOTE"
->"filtered"</SPAN
-> page.
</P
></DD
></DL
><H4
CLASS="SECT3"
><A
-NAME="HIDE-FORWARDED-FOR-HEADERS"
->8.5.7. <I
+NAME="HANDLE-AS-IMAGE"
+>8.5.9. <I
CLASS="EMPHASIS"
->+hide-forwarded-for-headers</I
+>handle-as-image</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
-><DD
-><P
->Boolean.</P
-></DD
-><DT
->Typical uses:</DT
+>Typical use:</DT
><DD
><P
-> Block any existing X-Forwarded-for HTTP header, and do not add a new one.
- </P
+>Mark URLs as belonging to images (so they'll be replaced by images <I
+CLASS="EMPHASIS"
+>if they get blocked</I
+>)</P
></DD
><DT
->Possible values:</DT
+>Effect:</DT
+><DD
+><P
+> This action alone doesn't do anything noticeable. It just marks URLs as images.
+ If the <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>block</A
+></TT
+> action <I
+CLASS="EMPHASIS"
+>also applies</I
+>,
+ the presence or absence of this mark decides whether an HTML <SPAN
+CLASS="QUOTE"
+>"blocked"</SPAN
+>
+ page, or a replacement image (as determined by the <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#SET-IMAGE-BLOCKER"
+>set-image-blocker</A
+></TT
+> action) will be sent to the
+ client as a substitute for the blocked content.
+ </P
+></DD
+><DT
+>Type:</DT
+><DD
+><P
+>Boolean.</P
+></DD
+><DT
+>Parameter:</DT
><DD
><P
> N/A
</P
></DD
><DT
->Example usage:</DT
+>Notes:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+hide-forwarded-for-headers}</I
-><br>
- <I
+> The below generic example section is actually part of <TT
+CLASS="FILENAME"
+>default.action</TT
+>.
+ It marks all URLs with well-known image file name extensions as images and should
+ be left intact.
+ </P
+><P
+> Users will probably only want to use the handle-as-image action in conjunction with
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>block</A
+></TT
+>, to block sources of banners, whose URLs don't
+ reflect the file type, like in the second example section.
+ </P
+><P
+> Note that you cannot treat HTML pages as images in most cases. For instance, (inline) ad
+ frames require an HTML page to be sent, or they won't display properly.
+ Forcing <TT
+CLASS="LITERAL"
+>handle-as-image</TT
+> in this situation will not replace the
+ ad frame with an image, but lead to error messages.
+ </P
+></DD
+><DT
+>Example usage (sections):</DT
+><DD
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+># Generic image extensions:
+#
+{+handle-as-image}
+/.*\.(gif|jpg|jpeg|png|bmp|ico)$
+
+# 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
+></TD
+></TR
+></TABLE
+>
+ </P
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="SECT3"
+><H4
+CLASS="SECT3"
+><A
+NAME="HIDE-FORWARDED-FOR-HEADERS"
+>8.5.10. <I
CLASS="EMPHASIS"
->.example.com</I
-><br>
- </P
+>hide-forwarded-for-headers</I
+></A
+></H4
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>Typical use:</DT
+><DD
+><P
+>Improve privacy by hiding the true source of the request</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 fairly safe to leave this on. It does not seem to break many sites.
+> It is fairly safe to leave this on.
+ </P
+><P
+> This action is scheduled for improvement: It should be able to generate forged
+ <SPAN
+CLASS="QUOTE"
+>"X-Forwarded-for:"</SPAN
+> headers using random IP addresses from a specified network,
+ to make successive requests from the same client look like requests from a pool of different
+ users sharing the same proxy.
+ </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
CLASS="SECT3"
><A
NAME="HIDE-FROM-HEADER"
->8.5.8. <I
+>8.5.11. <I
CLASS="EMPHASIS"
->+hide-from-header</I
+>hide-from-header</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Parameterized.</P
+>Keep your (old and ill) browser from telling web servers your email address</P
></DD
><DT
->Typical uses:</DT
+>Effect:</DT
><DD
><P
-> To block the browser from sending your email address in a <SPAN
+> Deletes any existing <SPAN
CLASS="QUOTE"
>"From:"</SPAN
->
- header.
+> HTTP header, or replaces it with the
+ specified string.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
+><DD
+><P
+>Parameterized.</P
+></DD
+><DT
+>Parameter:</DT
><DD
><P
> Keyword: <SPAN
</P
></DD
><DT
->Example usage:</DT
-><DD
-><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+hide-from-header{block}}</I
-><br>
- <I
-CLASS="EMPHASIS"
->.example.com</I
-><br>
- </P
-></DD
-><DT
>Notes:</DT
><DD
><P
CLASS="QUOTE"
>"block"</SPAN
> will completely remove the header
- (not to be confused with the <A
+ (not to be confused with the <TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#BLOCK"
-TARGET="_top"
-><SPAN
+>block</A
+></TT
+>
+ action).
+ </P
+><P
+> Alternately, you can specify any value you prefer to be sent to the web
+ server. If you do, it is a matter of fairness not to use any address that
+ is actually used by a real person.
+ </P
+><P
+> This action is rarely needed, as modern web browsers don't send
+ <SPAN
CLASS="QUOTE"
->"+block"</SPAN
-></A
-> action).
- Alternately, you can specify any value you prefer to send to the web
- server.
+>"From:"</SPAN
+> headers anymore.
+ </P
+></DD
+><DT
+>Example usage:</DT
+><DD
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+hide-from-header{block}</PRE
+></TD
+></TR
+></TABLE
+> or
+ <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+hide-from-header{spam-me-senseless@sittingduck.example.com}</PRE
+></TD
+></TR
+></TABLE
+>
</P
></DD
></DL
><H4
CLASS="SECT3"
><A
-NAME="HIDE-REFERER"
->8.5.9. <I
+NAME="HIDE-REFERRER"
+>8.5.12. <I
CLASS="EMPHASIS"
->+hide-referer</I
+>hide-referrer</I
></A
></H4
><A
-NAME="HIDE-REFERRER"
+NAME="HIDE-REFERER"
></A
><P
></P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Parameterized.</P
+>Conceal which link you followed to get to a particular site</P
></DD
><DT
->Typical uses:</DT
+>Effect:</DT
><DD
><P
-> Don't send the <SPAN
+> Deletes the <SPAN
CLASS="QUOTE"
>"Referer:"</SPAN
-> (sic) HTTP header to the web site.
- Or, alternately send a forged header instead.
+> (sic) HTTP header from the client request,
+ or replaces it with a forged one.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
+><DD
+><P
+>Parameterized.</P
+></DD
+><DT
+>Parameter:</DT
><DD
><P
-> Prevent the header from being sent with the keyword, <SPAN
+></P
+><UL
+><LI
+><P
+><SPAN
CLASS="QUOTE"
>"block"</SPAN
->.
- Or, <SPAN
+> to delete the header completely.</P
+></LI
+><LI
+><P
+><SPAN
CLASS="QUOTE"
>"forge"</SPAN
-> a URL to one from the same server as the request.
- Or, set to user defined value of your choice.
- </P
-></DD
-><DT
->Example usage:</DT
-><DD
+> to pretend to be coming from the homepage of the server we are talking to.</P
+></LI
+><LI
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+hide-referer{forge}}</I
-><br>
- <I
-CLASS="EMPHASIS"
->.example.com</I
-><br>
- </P
+>Any other string to set a user defined referrer.</P
+></LI
+></UL
></DD
><DT
>Notes:</DT
CLASS="QUOTE"
>"forge"</SPAN
> is the preferred option here, since some servers will
- not send images back otherwise.
+ not send images back otherwise, in an attempt to prevent their valuable
+ content from being embedded elsewhere (and hence, without being surrounded
+ by <I
+CLASS="EMPHASIS"
+>their</I
+> banners).
</P
><P
>
- <SPAN
-CLASS="QUOTE"
->"+hide-referrer"</SPAN
+ <TT
+CLASS="LITERAL"
+>hide-referer</TT
> is an alternate spelling of
- <SPAN
-CLASS="QUOTE"
->"+hide-referer"</SPAN
->. It has the exact same parameters, and can be freely
- mixed with, <SPAN
-CLASS="QUOTE"
->"+hide-referer"</SPAN
->. (<SPAN
+ <TT
+CLASS="LITERAL"
+>hide-referrer</TT
+> and the two can be can be freely
+ substituted with each other. (<SPAN
CLASS="QUOTE"
>"referrer"</SPAN
> is the
>.)
</P
></DD
+><DT
+>Example usage:</DT
+><DD
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+hide-referrer{forge}</PRE
+></TD
+></TR
+></TABLE
+> or
+ <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+hide-referrer{http://www.yahoo.com/}</PRE
+></TD
+></TR
+></TABLE
+>
+ </P
+></DD
></DL
></DIV
></DIV
CLASS="SECT3"
><A
NAME="HIDE-USER-AGENT"
->8.5.10. <I
+>8.5.13. <I
CLASS="EMPHASIS"
->+hide-user-agent</I
+>hide-user-agent</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Parameterized.</P
+>Conceal your type of browser and client operating system</P
></DD
><DT
->Typical uses:</DT
+>Effect:</DT
><DD
><P
-> To change the <SPAN
+> Replaces the value of the <SPAN
CLASS="QUOTE"
>"User-Agent:"</SPAN
-> header so web servers can't tell
- your browser type. Who's business is it anyway?
+> HTTP header
+ in client requests with the specified value.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
><DD
><P
-> Any user defined string.
+>Parameterized.</P
+></DD
+><DT
+>Parameter:</DT
+><DD
+><P
+> Any user-defined string.
</P
></DD
><DT
->Example usage:</DT
+>Notes:</DT
><DD
+><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
-CLASS="LITERALLAYOUT"
-> <I
+> This breaks many web sites that depend on looking at this header in order
+ to customize their content for different browsers (which, by the
+ way, is <I
CLASS="EMPHASIS"
->{+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}}</I
-><br>
- <I
+>NOT</I
+> a <A
+HREF="http://www.javascriptkit.com/javaindex.shtml"
+TARGET="_top"
+>smart way to do
+ that</A
+>!).
+ </P
+></TD
+></TR
+></TABLE
+></DIV
+><P
+> Using this action in multi-user setups or wherever different types of
+ browsers will access the same <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> is
+ <I
CLASS="EMPHASIS"
->.msn.com</I
-><br>
- </P
+>not recommended</I
+>. 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 :-).
+ </P
+><P
+> This action is scheduled for improvement.
+ </P
></DD
><DT
->Notes:</DT
+>Example usage:</DT
><DD
><P
-> Warning! This breaks many web sites that depend on this in order
- to determine how the target browser will respond to various
- requests. Use with caution.
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</PRE
+></TD
+></TR
+></TABLE
+>
</P
></DD
></DL
><H4
CLASS="SECT3"
><A
-NAME="HANDLE-AS-IMAGE"
->8.5.11. <I
+NAME="KILL-POPUPS"
+>8.5.14. <I
CLASS="EMPHASIS"
->+handle-as-image</I
+>kill-popups<A
+NAME="KILL-POPUP"
+></A
+></I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Boolean.</P
+>Eliminate those annoying pop-up windows</P
></DD
><DT
->Typical uses:</DT
+>Effect:</DT
><DD
><P
-> To define what <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> should treat
- automatically as an image, and is an important ingredient of how
- ads are handled.
+> While loading the document, replace JavaScript code that opens
+ pop-up windows with (syntactically neutral) dummy code on the fly.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
><DD
><P
-> N/A
- </P
+>Boolean.</P
></DD
><DT
->Example usage:</DT
+>Parameter:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+handle-as-image}</I
-><br>
- <I
-CLASS="EMPHASIS"
->/.*\.(gif|jpg|jpeg|png|bmp|ico)</I
-><br>
- </P
+> N/A
+ </P
></DD
><DT
>Notes:</DT
><DD
><P
-> This only has meaning if the URL (or pattern) also is
- <SPAN
-CLASS="QUOTE"
->"+block"</SPAN
->ed, in which case a user definable image can
- be sent rather than a HTML page. This is integral to the whole concept of
- ad blocking: the URL must match <I
-CLASS="EMPHASIS"
->both</I
-> a <A
-HREF="actions-file.html#BLOCK"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+block"</SPAN
-></A
-> rule,
+> This action is easily confused with the built-in, hardwired <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#FILTER"
+>filter</A
+></TT
+>
+ 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"
+>filter</A
+>{<TT
+CLASS="REPLACEABLE"
+><I
+>popups</I
+></TT
+>}</TT
+>
+ does.
+ </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
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#FILTER"
+>filter</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 is a dangerous business. Many shops and banks rely on
+ pop-ups to display forms, shopping carts etc, and killing only the unwanted pop-ups
+ would require artificial intelligence in <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>.
+ If the only kind of pop-ups that you want to kill are exit consoles (those
<I
CLASS="EMPHASIS"
->and</I
-> <SPAN
-CLASS="QUOTE"
->"+handle-as-image"</SPAN
->.
- (See <A
-HREF="actions-file.html#SET-IMAGE-BLOCKER"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+set-image-blocker"</SPAN
-></A
+>really nasty</I
+> 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
>
- below for control over what will actually be displayed by the browser.)
+ instead.
</P
+></DD
+><DT
+>Example usage:</DT
+><DD
><P
-> There is little reason to change the default definition for this action.
- </P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+kill-popups</PRE
+></TD
+></TR
+></TABLE
+></P
></DD
></DL
></DIV
><H4
CLASS="SECT3"
><A
-NAME="SET-IMAGE-BLOCKER"
->8.5.12. <I
+NAME="LIMIT-CONNECT"
+>8.5.15. <I
CLASS="EMPHASIS"
->+set-image-blocker</I
+>limit-connect</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Parameterized.</P
+>Prevent abuse of <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> as a TCP proxy relay</P
></DD
><DT
->Typical uses:</DT
+>Effect:</DT
><DD
><P
-> Decide what to do with URLs that end up tagged with <I
-CLASS="EMPHASIS"
->both</I
->
- <A
-HREF="actions-file.html#BLOCK"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+block"</SPAN
-></A
->
- and <A
-HREF="actions-file.html#HANDLE-AS-IMAGE"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+handle-as-image"</SPAN
-></A
->,
- e.g an advertisement.
+> Specifies to which ports HTTP CONNECT requests are allowable.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
><DD
><P
-> There are four available options: <SPAN
-CLASS="QUOTE"
->"-set-image-blocker"</SPAN
-> will send a HTML
- <SPAN
-CLASS="QUOTE"
->"blocked"</SPAN
-> page, usually resulting in a <SPAN
-CLASS="QUOTE"
->"broken
- image"</SPAN
-> icon.
- <SPAN
-CLASS="QUOTE"
->"+set-image-blocker{<I
-CLASS="EMPHASIS"
->blank</I
->}"</SPAN
-> will send a
- 1x1 transparent GIF image.
- <SPAN
-CLASS="QUOTE"
->"+set-image-blocker{<I
-CLASS="EMPHASIS"
->pattern</I
->}"</SPAN
-> will send a
- checkerboard type pattern (the default). And finally,
- <SPAN
-CLASS="QUOTE"
->"+set-image-blocker{<I
-CLASS="EMPHASIS"
->http://xyz.com</I
->}"</SPAN
-> will
- send a HTTP temporary redirect to the specified image. This has the
- advantage of the icon being being cached by the browser, which will speed
- up the display.
- </P
+>Parameterized.</P
></DD
><DT
->Example usage:</DT
+>Parameter:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+set-image-blocker{blank}}</I
-><br>
- <I
-CLASS="EMPHASIS"
->.example.com</I
-><br>
- </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
-> If you want <I
-CLASS="EMPHASIS"
->invisible</I
-> ads, they need to meet
- criteria as matching both <I
-CLASS="EMPHASIS"
->images</I
-> and <I
-CLASS="EMPHASIS"
->blocked</I
->
- actions. And then, <SPAN
-CLASS="QUOTE"
->"image-blocker"</SPAN
-> should be set to
+> 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"
->"blank"</SPAN
-> for invisibility. Note you cannot treat HTML pages as
- images in most cases. For instance, frames require an HTML page to
- display. So a frame that is an ad, typically cannot be treated as an image.
- Forcing an <SPAN
-CLASS="QUOTE"
->"image"</SPAN
-> in this situation just will not work
- reliably.
+>"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
+> If you don't know what any of this means, there probably is no reason to
+ change this one, since the default is already very restrictive.
+ </P
+></DD
+><DT
+>Example usages:</DT
+><DD
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><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 (gaping security hole!)</PRE
+></TD
+></TR
+></TABLE
+>
</P
></DD
></DL
><H4
CLASS="SECT3"
><A
-NAME="LIMIT-CONNECT"
->8.5.13. <I
+NAME="PREVENT-COMPRESSION"
+>8.5.16. <I
CLASS="EMPHASIS"
->+limit-connect</I
+>prevent-compression</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Parameterized.</P
+> Ensure that servers send the content uncompressed, so it can be
+ passed through <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#FILTER"
+>filter</A
+></TT
+>s
+ </P
></DD
><DT
->Typical uses:</DT
+>Effect:</DT
><DD
><P
-> By default, <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> only allows HTTP CONNECT
- requests to port 443 (the standard, secure HTTPS port). Use
- <SPAN
-CLASS="QUOTE"
->"+limit-connect"</SPAN
-> to disable this altogether, or to allow
- more ports.
+> Adds a header to the request that asks for uncompressed transfer.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
><DD
><P
-> Any valid port number, or port number range.
- </P
+>Boolean.</P
></DD
><DT
->Example usages:</DT
+>Parameter:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->+limit-connect{443}</I
-> # This is the default and need not be specified.<br>
- <I
-CLASS="EMPHASIS"
->+limit-connect{80,443}</I
-> # Ports 80 and 443 are OK.<br>
- <I
-CLASS="EMPHASIS"
->+limit-connect{-3, 7, 20-100, 500-}</I
-> # Port less than 3, 7, 20 to 100 and above 500 are OK.<br>
- </P
+> N/A
+ </P
></DD
><DT
>Notes:</DT
><DD
><P
-> The CONNECT methods exists in HTTP to allow access to secure websites
- (https:// 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 <I
-CLASS="EMPHASIS"
->and</I
-> to the remote proxy.
- This can be a big security hole, since CONNECT-enabled proxies can be
- abused as TCP relays very easily.
- </P
+> More and more websites send their content compressed by default, which
+ is generally a good idea and saves bandwidth. But for the <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#FILTER"
+>filter</A
+></TT
+>, <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 to work,
+ <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> needs access to the uncompressed data.
+ Unfortunately, <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> can't yet(!) uncompress, filter, and
+ re-compress the content on the fly. So if you want to ensure that all websites, including
+ those that normally compress, can be filtered, you need to use this action.
+ </P
><P
->
- If you want to allow CONNECT for more ports than this, or want to forbid
- CONNECT altogether, you can specify a comma separated list of ports and
- port ranges (the latter using dashes, with the minimum defaulting to 0 and
- max to 65K).
- </P
+> This will slow down transfers from those websites, though. If you use any of the above-mentioned
+ actions, you will typically want to use <TT
+CLASS="LITERAL"
+>prevent-compression</TT
+> in conjunction
+ with them.
+ </P
><P
-> If you don't know what any of this means, there probably is no reason to
- change this one.
- </P
+> Note that some (rare) ill-configured sites don't handle requests for uncompressed
+ documents correctly (they send an empty document body). If you use <TT
+CLASS="LITERAL"
+>prevent-compression</TT
+>
+ per default, you'll have to add exceptions for those sites. See the example for how to do that.
+ </P
+></DD
+><DT
+>Example usage (sections):</DT
+><DD
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+># Set default:
+#
+{+prevent-compression}
+/ # Match all sites
+
+# Make exceptions for ill sites:
+#
+{-prevent-compression}
+www.debianhelp.org
+www.pclinuxonline.com</PRE
+></TD
+></TR
+></TABLE
+>
+ </P
></DD
></DL
></DIV
><H4
CLASS="SECT3"
><A
-NAME="PREVENT-COMPRESSION"
->8.5.14. <I
+NAME="SEND-VANILLA-WAFER"
+>8.5.17. <I
CLASS="EMPHASIS"
->+prevent-compression</I
+>send-vanilla-wafer</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Boolean.</P
+> Feed log analysis scripts with useless data.
+ </P
></DD
><DT
->Typical uses:</DT
+>Effect:</DT
><DD
><P
-> Prevent the specified websites from compressing HTTP data.
+> 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
->Possible values:</DT
+>Type:</DT
+><DD
+><P
+>Boolean.</P
+></DD
+><DT
+>Parameter:</DT
><DD
><P
> N/A
</P
></DD
><DT
->Example usage:</DT
+>Notes:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+prevent-compression}</I
-><br>
- <I
-CLASS="EMPHASIS"
->.example.com</I
-><br>
- </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
->Notes:</DT
+>Example usage:</DT
><DD
><P
-> Some websites do this, which can be a problem for
- <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
->, since
- <A
-HREF="actions-file.html#FILTER"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+filter"</SPAN
-></A
->,
- <A
-HREF="actions-file.html#KILL-POPUPS"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+kill-popups"</SPAN
-></A
->
- and <A
-HREF="actions-file.html#GIF-DEANIMATE"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+gif-deanimate"</SPAN
-></A
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+send-vanilla-wafer</PRE
+></TD
+></TR
+></TABLE
>
- will not work on compressed data. This will slow down connections to those
- websites, though. Default typically is to turn
- <SPAN
-CLASS="QUOTE"
->"prevent-compression"</SPAN
-> on.
</P
></DD
></DL
><H4
CLASS="SECT3"
><A
-NAME="SESSION-COOKIES-ONLY"
->8.5.15. <I
+NAME="SEND-WAFER"
+>8.5.18. <I
CLASS="EMPHASIS"
->+session-cookies-only</I
+>send-wafer</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Boolean.</P
+> Send custom cookies or feed log analysis scripts with even more useless data.
+ </P
></DD
><DT
->Typical uses:</DT
+>Effect:</DT
><DD
><P
-> Allow cookies for the current browser session <I
-CLASS="EMPHASIS"
->only</I
->.
+> Sends a custom, user-defined cookie with each request.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
><DD
><P
-> N/A
- </P
+>Multi-value.</P
></DD
><DT
->Example usage (disabling):</DT
+>Parameter:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{-session-cookies-only}</I
-><br>
- <I
-CLASS="EMPHASIS"
->.example.com</I
-><br>
- </P
+> A string of the form <SPAN
+CLASS="QUOTE"
+>"<TT
+CLASS="REPLACEABLE"
+><I
+>name</I
+></TT
+>=<TT
+CLASS="REPLACEABLE"
+><I
+>value</I
+></TT
+>"</SPAN
+>.
+ </P
></DD
><DT
>Notes:</DT
><DD
><P
-> If websites set cookies, <SPAN
-CLASS="QUOTE"
->"+session-cookies-only"</SPAN
-> will make sure
- they are erased when you exit and restart your web browser. 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
- sites, and is the recommended setting.
+> Being multi-valued, multiple instances of this action can apply to the same request,
+ resulting in multiple cookies being sent.
</P
><P
-> <SPAN
-CLASS="QUOTE"
->"+prevent-*-cookies"</SPAN
-> actions should be turned off as well (see
- below), for <SPAN
-CLASS="QUOTE"
->"+session-cookies-only"</SPAN
-> to work. Or, else no cookies
- will get through at all. For, <SPAN
-CLASS="QUOTE"
->"persistent"</SPAN
-> cookies that survive
- across browser sessions, see below as well.
+> This action is rarely used and not enabled in the default configuration.
+ </P
+></DD
+><DT
+>Example usage (section):</DT
+><DD
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>{+send-wafer{UsingPrivoxy=true}}
+my-internal-testing-server.void</PRE
+></TD
+></TR
+></TABLE
+>
</P
></DD
></DL
><H4
CLASS="SECT3"
><A
-NAME="PREVENT-READING-COOKIES"
->8.5.16. <I
+NAME="SESSION-COOKIES-ONLY"
+>8.5.19. <I
CLASS="EMPHASIS"
->+prevent-reading-cookies</I
+>session-cookies-only</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
+>Typical use:</DT
><DD
><P
->Boolean.</P
+> Allow only temporary <SPAN
+CLASS="QUOTE"
+>"session"</SPAN
+> cookies (for the current browser session <I
+CLASS="EMPHASIS"
+>only</I
+>).
+ </P
></DD
><DT
->Typical uses:</DT
+>Effect:</DT
><DD
><P
-> Explicitly prevent the web server from reading any cookies on your
- system.
+> Deletes the <SPAN
+CLASS="QUOTE"
+>"expires"</SPAN
+> field from <SPAN
+CLASS="QUOTE"
+>"Set-Cookie:"</SPAN
+> server headers.
+ Most browsers will not store such cookies permanently and forget them in between sessions.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
><DD
><P
-> N/A
- </P
+>Boolean.</P
></DD
><DT
->Example usage:</DT
+>Parameter:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+prevent-reading-cookies}</I
-><br>
- <I
-CLASS="EMPHASIS"
->.example.com</I
-><br>
- </P
+> N/A
+ </P
></DD
><DT
>Notes:</DT
><DD
><P
-> Often used in conjunction with <SPAN
-CLASS="QUOTE"
->"+prevent-setting-cookies"</SPAN
-> to
- disable cookies completely. Note that
- <A
-HREF="actions-file.html#SESSION-COOKIES-ONLY"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+session-cookies-only"</SPAN
-></A
+> This is less strict than <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
+>crunch-incoming-cookies</A
+></TT
+> /
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
+>crunch-outgoing-cookies</A
+></TT
+> and allows you to browse
+ websites that insist or rely on setting cookies, without compromising your privacy too badly.
+ </P
+><P
+> Most browsers will not permanently store cookies that have been processed by
+ <TT
+CLASS="LITERAL"
+>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
+ sites, and is the recommended setting.
+ </P
+><P
+> It makes <I
+CLASS="EMPHASIS"
+>no sense at all</I
+> to use <TT
+CLASS="LITERAL"
+>session-cookies-only</TT
>
- requires these to both be disabled (or else it never gets any cookies to cache).
+ together with <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
+>crunch-incoming-cookies</A
+></TT
+> or
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
+>crunch-outgoing-cookies</A
+></TT
+>. If you do, cookies
+ will be plainly killed.
</P
><P
-> For <SPAN
+> Note that it is up to the browser how it handles such cookies without an <SPAN
CLASS="QUOTE"
->"persistent"</SPAN
-> cookies to work (i.e. they survive across browser
- sessions and reboots), all three cookie settings should be <SPAN
-CLASS="QUOTE"
->"off"</SPAN
->
- for the specified sites.
+>"expires"</SPAN
+>
+ field. If you use an exotic browser, you might want to try it out to be sure.
+ </P
+></DD
+><DT
+>Example usage:</DT
+><DD
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+session-cookies-only</PRE
+></TD
+></TR
+></TABLE
+>
</P
></DD
></DL
><H4
CLASS="SECT3"
><A
-NAME="PREVENT-SETTING-COOKIES"
->8.5.17. <I
+NAME="SET-IMAGE-BLOCKER"
+>8.5.20. <I
CLASS="EMPHASIS"
->+prevent-setting-cookies</I
+>set-image-blocker</I
></A
></H4
><P
CLASS="VARIABLELIST"
><DL
><DT
->Type:</DT
-><DD
-><P
->Boolean.</P
-></DD
-><DT
->Typical uses:</DT
-><DD
-><P
-> Explicitly block the web server from storing cookies on your
- system.
- </P
-></DD
-><DT
->Possible values:</DT
+>Typical use:</DT
><DD
><P
-> N/A
- </P
+>Choose the replacement for blocked images</P
></DD
><DT
->Example usage:</DT
+>Effect:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+prevent-setting-cookies}</I
-><br>
- <I
+> This action alone doesn't do anything noticeable. If <I
CLASS="EMPHASIS"
->.example.com</I
-><br>
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> Often used in conjunction with <SPAN
-CLASS="QUOTE"
->"+prevent-reading-cookies"</SPAN
-> to
- disable cookies completely (see above).
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
+>both</I
+>
+ <TT
+CLASS="LITERAL"
><A
-NAME="KILL-POPUP"
->8.5.18. <I
+HREF="actions-file.html#BLOCK"
+>block</A
+></TT
+> <I
CLASS="EMPHASIS"
->+kill-popups<A
-NAME="KILL-POPUPS"
-></A
-></I
-></A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Type:</DT
-><DD
-><P
->Boolean.</P
-></DD
-><DT
->Typical uses:</DT
-><DD
-><P
-> Stop those annoying JavaScript pop-up windows!
+>and</I
+> <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#HANDLE-AS-IMAGE"
+>handle-as-image</A
+></TT
+> <I
+CLASS="EMPHASIS"
+>also</I
+>
+ apply, i.e. if the request is to be blocked as an image,
+ <I
+CLASS="EMPHASIS"
+>then</I
+> the parameter of this action decides what will be
+ sent as a replacement.
</P
></DD
><DT
->Possible values:</DT
+>Type:</DT
><DD
><P
-> N/A
- </P
+>Parameterized.</P
></DD
><DT
->Example usage:</DT
+>Parameter:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+kill-popups}</I
-><br>
- <I
-CLASS="EMPHASIS"
->.example.com</I
-><br>
- </P
-></DD
-><DT
->Notes:</DT
-><DD
+></P
+><UL
+><LI
><P
-> <SPAN
+> <SPAN
CLASS="QUOTE"
->"+kill-popups"</SPAN
-> uses a built in filter to disable pop-ups
- that use the <TT
-CLASS="LITERAL"
->window.open()</TT
-> function, etc. This is
- one of the first actions processed by <SPAN
+>"pattern"</SPAN
+> to send a built-in checkerboard pattern image. The image is visually
+ decent, scales very well, and makes it obvious where banners were busted.
+ </P
+></LI
+><LI
+><P
+> <SPAN
+CLASS="QUOTE"
+>"blank"</SPAN
+> to send a built-in transparent image. This makes banners disappear
+ completely, but makes it hard to detect where <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> has blocked
+ images on a given page and complicates troubleshooting if <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
>
- as it contacts the remote web server. This action is not always 100% reliable,
- and is supplemented by <SPAN
-CLASS="QUOTE"
->"+filter{<I
-CLASS="EMPHASIS"
->popups</I
->}"</SPAN
->.
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="SEND-VANILLA-WAFER"
->8.5.19. <I
-CLASS="EMPHASIS"
->+send-vanilla-wafer</I
-></A
-></H4
+ has blocked innocent images, like navigation icons.
+ </P
+></LI
+><LI
><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Type:</DT
-><DD
+> <SPAN
+CLASS="QUOTE"
+>"<TT
+CLASS="REPLACEABLE"
+><I
+>target-url</I
+></TT
+>"</SPAN
+> to
+ send a redirect to <TT
+CLASS="REPLACEABLE"
+><I
+>target-url</I
+></TT
+>. You can redirect
+ to any image anywhere, even in your local filesystem (via <SPAN
+CLASS="QUOTE"
+>"file:///"</SPAN
+> URL).
+ </P
><P
->Boolean.</P
+> A good application of redirects is to use special <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>-built-in
+ URLs, which send the built-in images, as <TT
+CLASS="REPLACEABLE"
+><I
+>target-url</I
+></TT
+>.
+ This has the same visual effect as specifying <SPAN
+CLASS="QUOTE"
+>"blank"</SPAN
+> or <SPAN
+CLASS="QUOTE"
+>"pattern"</SPAN
+> in
+ the first place, but enables your browser to cache the replacement image, instead of requesting
+ it over and over again.
+ </P
+></LI
+></UL
></DD
><DT
->Typical uses:</DT
+>Notes:</DT
><DD
><P
-> Sends a cookie for every site stating that you do not accept any copyright
- on cookies sent to you, and asking them not to track you.
+> The URLs for the built-in images are <SPAN
+CLASS="QUOTE"
+>"http://config.privoxy.org/send-banner?type=<TT
+CLASS="REPLACEABLE"
+><I
+>type</I
+></TT
+>"</SPAN
+>, where <TT
+CLASS="REPLACEABLE"
+><I
+>type</I
+></TT
+> is
+ either <SPAN
+CLASS="QUOTE"
+>"blank"</SPAN
+> or <SPAN
+CLASS="QUOTE"
+>"pattern"</SPAN
+>.
</P
-></DD
-><DT
->Possible values:</DT
-><DD
><P
-> N/A
+> There is a third (advanced) type, called <SPAN
+CLASS="QUOTE"
+>"auto"</SPAN
+>. It is <I
+CLASS="EMPHASIS"
+>NOT</I
+> to be
+ used in <TT
+CLASS="LITERAL"
+>set-image-blocker</TT
+>, but meant for use from <A
+HREF="filter-file.html"
+>filters</A
+>.
+ Auto will select the type of image that would have applied to the referring page, had it been an image.
</P
></DD
><DT
>Example usage:</DT
><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+send-vanilla-wafer}</I
-><br>
- <I
-CLASS="EMPHASIS"
->.example.com</I
-><br>
- </P
-></DD
-><DT
->Notes:</DT
-><DD
+> Built-in pattern:
+ </P
><P
-> This action only applies if you are using a <TT
-CLASS="FILENAME"
->jarfile</TT
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+set-image-blocker{pattern}</PRE
+></TD
+></TR
+></TABLE
>
- for saving cookies. Of course, this is a (relatively) unique header and
- could conceivably be used to track you.
</P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="SEND-WAFER"
->8.5.20. <I
-CLASS="EMPHASIS"
->+send-wafer</I
-></A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Type:</DT
-><DD
-><P
->Multi-value.</P
-></DD
-><DT
->Typical uses:</DT
-><DD
><P
-> This allows you to send an arbitrary, user definable cookie.
+> Redirect to the BSD devil:
</P
-></DD
-><DT
->Possible values:</DT
-><DD
><P
-> User specified cookie name and corresponding value.
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}</PRE
+></TD
+></TR
+></TABLE
+>
</P
-></DD
-><DT
->Example usage:</DT
-><DD
><P
-CLASS="LITERALLAYOUT"
-> <I
-CLASS="EMPHASIS"
->{+send-wafer{name=value}}</I
-><br>
- <I
-CLASS="EMPHASIS"
->.example.com</I
-><br>
- </P
-></DD
-><DT
->Notes:</DT
-><DD
+> Redirect to the built-in pattern for better caching:
+ </P
><P
-> This can be specified multiple times in order to add as many cookies as you
- like.
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="90%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>+set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}</PRE
+></TD
+></TR
+></TABLE
+>
</P
></DD
></DL
><H3
CLASS="SECT3"
><A
-NAME="AEN2289"
+NAME="AEN2469"
>8.5.21. Summary</A
></H3
><P
> for a brief example on troubleshooting
actions.</P
></DIV
+></DIV
><DIV
-CLASS="SECT3"
+CLASS="SECT2"
><H2
-CLASS="SECT3"
+CLASS="SECT2"
><A
-NAME="ACT-EXAMPLES"
->8.5.22. Sample Actions Files</A
+NAME="ALIASES"
+>8.6. Aliases</A
></H2
><P
-> Remember that the meaning of any of the above references is reversed by preceding
- the action with a <SPAN
+> Custom <SPAN
CLASS="QUOTE"
->"-"</SPAN
->, in place of the <SPAN
+>"actions"</SPAN
+>, known to <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>
+ as <SPAN
CLASS="QUOTE"
->"+"</SPAN
->. Also,
- that some actions are turned on in the default section of the actions file,
- and require little to no additional configuration. These are just <SPAN
+>"aliases"</SPAN
+>, can be defined by combining other actions.
+ These can in turn be invoked just like the built-in actions.
+ Currently, an alias name can contain any character except space, tab,
+ <SPAN
CLASS="QUOTE"
->"on"</SPAN
->.</P
-><P
-> But, other actions that are turned on in the default section <I
-CLASS="EMPHASIS"
->do
- typically require</I
-> exceptions to be listed in the latter sections of
- one of our actions file. For instance, by default no URLs are
+>"="</SPAN
+>,
<SPAN
CLASS="QUOTE"
->"blocked"</SPAN
-> (i.e. in the default definitions of
- <TT
-CLASS="FILENAME"
->default.action</TT
->). We need exceptions to this in order to
- <I
+>"{"</SPAN
+> and <SPAN
+CLASS="QUOTE"
+>"}"</SPAN
+>, but we <I
CLASS="EMPHASIS"
->enable</I
-> ad blocking in the lower sections. But we need to
- be very selective about what we do block. Thus, the default is <SPAN
+>strongly
+ recommend</I
+> that you only use <SPAN
+CLASS="QUOTE"
+>"a"</SPAN
+> to <SPAN
+CLASS="QUOTE"
+>"z"</SPAN
+>,
+ <SPAN
+CLASS="QUOTE"
+>"0"</SPAN
+> to <SPAN
+CLASS="QUOTE"
+>"9"</SPAN
+>, <SPAN
+CLASS="QUOTE"
+>"+"</SPAN
+>, and <SPAN
+CLASS="QUOTE"
+>"-"</SPAN
+>.
+ Alias names are not case sensitive, and are not required to start with a
+ <SPAN
+CLASS="QUOTE"
+>"+"</SPAN
+> or <SPAN
CLASS="QUOTE"
->"off"</SPAN
+>"-"</SPAN
+> sign, since they are merely textually
+ expanded.</P
+><P
+> Aliases can be used throughout the actions file, but they <I
+CLASS="EMPHASIS"
+>must be
+ defined in a special section at the top of the file!</I
>
- for blocking.</P
+ And there can only be one such section per actions file. Each actions file may
+ have its own alias section, and the aliases defined in it are only visible
+ within that file.</P
+><P
+> There are two main reasons to use aliases: One is to save typing for frequently
+ used combinations of actions, the other one is a gain in flexibility: If you
+ decide once how you want to handle shops by defining an alias called
+ <SPAN
+CLASS="QUOTE"
+>"shop"</SPAN
+>, you can later change your policy on shops in
+ <I
+CLASS="EMPHASIS"
+>one</I
+> place, and your changes will take effect everywhere
+ in the actions file where the <SPAN
+CLASS="QUOTE"
+>"shop"</SPAN
+> alias is used. Calling aliases
+ by their purpose also makes your actions files more readable.</P
+><P
+> Currently, there is one big drawback to using aliases, though:
+ <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>'s built-in web-based action file
+ editor honors aliases when reading the actions files, but it expands
+ them before writing. So the effects of your aliases are of course preserved,
+ but the aliases themselves are lost when you edit sections that use aliases
+ with it.
+ This is likely to change in future versions of <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>.</P
+><P
+> Now let's define some aliases...</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+> # Useful custom aliases we can use later.
+ #
+ # Note the (required!) section header line and that this section
+ # must be at the top of the actions file!
+ #
+ {{alias}}
+
+ # These aliases just save typing later:
+ # (Note that some already use other aliases!)
+ #
+ +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
+ -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
+ block-as-image = +block +handle-as-image
+ mercy-for-cookies = -crunch-all-cookies -session-cookies-only
+
+ # These aliases define combinations of actions
+ # that are useful for certain types of sites:
+ #
+ fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups
+ shop = -crunch-all-cookies -filter{popups} -kill-popups
+
+ # Short names for other aliases, for really lazy people ;-)
+ #
+ c0 = +crunch-all-cookies
+ c1 = -crunch-all-cookies</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> ...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
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+> # These sites are either very complex or very keen on
+ # user data and require minimal interference to work:
+ #
+ {fragile}
+ .office.microsoft.com
+ .windowsupdate.microsoft.com
+ .nytimes.com
+
+ # Shopping sites:
+ # Allow cookies (for setting and retrieving your customer data)
+ #
+ {shop}
+ .quietpc.com
+ .worldpay.com # for quietpc.com
+ .scan.co.uk
+
+ # These shops require pop-ups:
+ #
+ {shop -kill-popups -filter{popups}}
+ .dabs.com
+ .overclockers.co.uk</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> Aliases like <SPAN
+CLASS="QUOTE"
+>"shop"</SPAN
+> and <SPAN
+CLASS="QUOTE"
+>"fragile"</SPAN
+> are often used for
+ <SPAN
+CLASS="QUOTE"
+>"problem"</SPAN
+> sites that require some actions to be disabled
+ in order to function properly.</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="ACT-EXAMPLES"
+>8.7. Actions Files Tutorial</A
+></H2
><P
-> Below is a liberally commented sample <TT
+> The above chapters have shown <A
+HREF="actions-file.html"
+>which actions files
+ there are and how they are organized</A
+>, how actions are <A
+HREF="actions-file.html#ACTIONS"
+>specified</A
+> and <A
+HREF="actions-file.html#ACTIONS-APPLY"
+>applied
+ to URLs</A
+>, how <A
+HREF="actions-file.html#AF-PATTERNS"
+>patterns</A
+> work, and how to
+ define and use <A
+HREF="actions-file.html#ALIASES"
+>aliases</A
+>. Now, let's look at an
+ example <TT
CLASS="FILENAME"
>default.action</TT
-> file
- to demonstrate how all the pieces come together. And to show how exceptions
- to the default policies can be handled. This is followed by a brief
- <TT
+> and <TT
CLASS="FILENAME"
>user.action</TT
-> with similar examples.</P
+>
+ file and see how all these pieces come together:</P
+><DIV
+CLASS="SECT3"
+><H3
+CLASS="SECT3"
+><A
+NAME="AEN2521"
+>8.7.1. default.action</A
+></H3
><P
-> <TT
-CLASS="LITERAL"
-> <P
-CLASS="LITERALLAYOUT"
-># Sample default.action file <developers@privoxy.org><br>
-<br>
-# Settings -- Don't change! For internal Privoxy use ONLY.<br>
-{{settings}}<br>
-for-privoxy-version=3.0<br>
-<br>
-<br>
-##########################################################################<br>
-# <A
+>Every config file should start with a short comment stating its purpose:</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+># Sample default.action file <developers@privoxy.org></PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+>Then, since this is 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
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>##########################################################################
+# Settings -- Don't change! For internal Privoxy use ONLY.
+##########################################################################
+
+{{settings}}
+for-privoxy-version=3.0</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+>After that comes the (optional) alias section. We'll use the example
+section from the above <A
HREF="actions-file.html#ALIASES"
-TARGET="_top"
->Aliases</A
-> must be defined *before* they are used. These are<br>
-# easier to remember, and can combine several actions into one. Once <br>
-# defined they can be used just like any built-in action -- but within <br>
-# this file only! Aliases do not require a + or - sign.<br>
-##########################################################################<br>
-<br>
-# Some useful aliases.<br>
-# Alias to turn off cookie handling, ie allow all cookies unmolested.<br>
- -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \<br>
- -session-cookies-only<br>
-<br>
-# Alias to both block and treat as if an image for ad blocking<br>
-# purposes.<br>
- +imageblock = +block +handle-as-image<br>
-<br>
-# Fragile sites should have the minimum changes:<br>
- fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \<br>
- -prevent-cookies -kill-popups<br>
-<br>
-# Shops should be allowed to set persistent cookies<br>
- shop = -filter -prevent-cookies -session-cookies-only<br>
-<br>
-<br>
-##########################################################################<br>
-# Begin default action settings. Anything in this section will match <br>
-# all URLs -- UNLESS we have exceptions that also match, defined below this <br>
-# section. We will show all potential actions here whether they are on <br>
-# or off. We could omit any disabled action if we wanted, since all <br>
-# actions are 'off' by default anyway. Shown for completeness only.<br>
-# Actions are enabled if preceded by a '+', otherwise they are disabled <br>
-# (unless an alias has been defined without this).<br>
-##########################################################################<br>
- { \<br>
- <A
+>chapter on aliases</A
+>,
+that also explains why and how aliases are used:</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>##########################################################################
+# Aliases
+##########################################################################
+{{alias}}
+
+# These aliases just save typing later:
+# (Note that some already use other aliases!)
+#
++crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
+-crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
+block-as-image = +block +handle-as-image
+mercy-for-cookies = -crunch-all-cookies -session-cookies-only
+
+# These aliases define combinations of actions
+# that are useful for certain types of sites:
+#
+fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups
+shop = mercy-for-cookies -filter{popups} -kill-popups</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 <I
+CLASS="EMPHASIS"
+>all actions
+ are disabled when matching starts</I
+>, 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 <I
+CLASS="EMPHASIS"
+>will
+ be applied to all requests as a start</I
+>. 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"
-TARGET="_top"
->-add-header</A
-> \<br>
- <A
+>add-header</A
+> \
+ -<A
HREF="actions-file.html#BLOCK"
-TARGET="_top"
->-block</A
-> \<br>
- <A
+>block</A
+> \
+ -<A
+HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
+>crunch-incoming-cookies</A
+> \
+ -<A
+HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
+>crunch-outgoing-cookies</A
+> \
+ +<A
HREF="actions-file.html#DEANIMATE-GIFS"
-TARGET="_top"
->-deanimate-gifs</A
-> \<br>
- <A
+>deanimate-gifs</A
+> \
+ -<A
HREF="actions-file.html#DOWNGRADE-HTTP-VERSION"
-TARGET="_top"
->-downgrade-http-version</A
-> \<br>
- <A
+>downgrade-http-version</A
+> \
+ +<A
HREF="actions-file.html#FAST-REDIRECTS"
-TARGET="_top"
->+fast-redirects</A
-> \<br>
- <A
+>fast-redirects</A
+> \
+ +<A
HREF="actions-file.html#FILTER-HTML-ANNOYANCES"
-TARGET="_top"
->+filter{html-annoyances}</A
-> \<br>
- <A
+>filter{html-annoyances}</A
+> \
+ +<A
HREF="actions-file.html#FILTER-JS-ANNOYANCES"
-TARGET="_top"
->+filter{js-annoyances}</A
-> \<br>
- <A
+>filter{js-annoyances}</A
+> \
+ -<A
HREF="actions-file.html#FILTER-CONTENT-COOKIES"
-TARGET="_top"
->-filter{content-cookies}</A
-> \<br>
- <A
+>filter{content-cookies}</A
+> \
+ +<A
HREF="actions-file.html#FILTER-POPUPS"
-TARGET="_top"
->-filter{popups}</A
-> \<br>
- <A
+>filter{popups}</A
+> \
+ +<A
HREF="actions-file.html#FILTER-WEBBUGS"
-TARGET="_top"
->+filter{webbugs}</A
-> \<br>
- <A
+>filter{webbugs}</A
+> \
+ -<A
HREF="actions-file.html#FILTER-REFRESH-TAGS"
-TARGET="_top"
->-filter{refresh-tags}</A
-> \<br>
- <A
+>filter{refresh-tags}</A
+> \
+ -<A
HREF="actions-file.html#FILTER-FUN"
-TARGET="_top"
->-filter{fun}</A
-> \<br>
- <A
+>filter{fun}</A
+> \
+ +<A
HREF="actions-file.html#FILTER-NIMDA"
-TARGET="_top"
->+filter{nimda}</A
-> \<br>
- <A
+>filter{nimda}</A
+> \
+ +<A
HREF="actions-file.html#FILTER-BANNERS-BY-SIZE"
-TARGET="_top"
->+filter{banners-by-size}</A
-> \<br>
- <A
+>filter{banners-by-size}</A
+> \
+ -<A
HREF="actions-file.html#FILTER-SHOCKWAVE-FLASH"
-TARGET="_top"
->-filter{shockwave-flash}</A
-> \<br>
- <A
+>filter{shockwave-flash}</A
+> \
+ -<A
HREF="actions-file.html#FILTER-CRUDE-PARENTAL"
-TARGET="_top"
->-filter{crude-prental}</A
-> \<br>
- <A
+>filter{crude-parental}</A
+> \
+ -<A
+HREF="actions-file.html#HANDLE-AS-IMAGE"
+>handle-as-image</A
+> \
+ +<A
HREF="actions-file.html#HIDE-FORWARDED-FOR-HEADERS"
-TARGET="_top"
->+hide-forwarded-for-headers</A
-> \<br>
- <A
+>hide-forwarded-for-headers</A
+> \
+ +<A
HREF="actions-file.html#HIDE-FROM-HEADER"
-TARGET="_top"
->+hide-from-header{block}</A
-> \<br>
- <A
+>hide-from-header{block}</A
+> \
+ +<A
HREF="actions-file.html#HIDE-REFERER"
-TARGET="_top"
->-hide-referrer</A
-> \<br>
- <A
+>hide-referrer{forge}</A
+> \
+ -<A
HREF="actions-file.html#HIDE-USER-AGENT"
-TARGET="_top"
->-hide-user-agent</A
-> \<br>
- <A
-HREF="actions-file.html#HANDLE-AS-IMAGE"
-TARGET="_top"
->-handle-as-image</A
-> \<br>
- <A
-HREF="actions-file.html#SET-IMAGE-BLOCKER"
-TARGET="_top"
->+set-image-blocker{pattern}</A
-> \<br>
- <A
+>hide-user-agent</A
+> \
+ -<A
+HREF="actions-file.html#KILL-POPUPS"
+>kill-popups</A
+> \
+ -<A
HREF="actions-file.html#LIMIT-CONNECT"
-TARGET="_top"
->-limit-connect</A
-> \<br>
- <A
+>limit-connect</A
+> \
+ +<A
HREF="actions-file.html#PREVENT-COMPRESSION"
-TARGET="_top"
->+prevent-compression</A
-> \<br>
- <A
-HREF="actions-file.html#SESSION-COOKIES-ONLY"
-TARGET="_top"
->-session-cookies-only</A
-> \<br>
- <A
-HREF="actions-file.html#PREVENT-READING-COOKIES"
-TARGET="_top"
->-prevent-reading-cookies</A
-> \<br>
- <A
-HREF="actions-file.html#PREVENT-SETTING-COOKIES"
-TARGET="_top"
->-prevent-setting-cookies</A
-> \<br>
- <A
-HREF="actions-file.html#KILL-POPUPS"
-TARGET="_top"
->-kill-popups</A
-> \<br>
- <A
+>prevent-compression</A
+> \
+ -<A
HREF="actions-file.html#SEND-VANILLA-WAFER"
-TARGET="_top"
->-send-vanilla-wafer</A
-> \<br>
- <A
+>send-vanilla-wafer</A
+> \
+ -<A
HREF="actions-file.html#SEND-WAFER"
-TARGET="_top"
->-send-wafer</A
-> \<br>
- }<br>
- / # forward slash will match *all* potential URL patterns. <br>
-<br>
-##########################################################################<br>
-# Default behavior is now set. Now we will define some exceptions to our <br>
-# default action policies.<br>
-##########################################################################<br>
-<br>
-# These sites are very complex and require very minimal interference.<br>
-# We'll disable most actions with our 'fragile' alias:<br>
- { fragile }<br>
- .office.microsoft.com # surprise, surprise!<br>
- .windowsupdate.microsoft.com<br>
-<br>
-<br>
-# Shopping sites - not as fragile but require some special <br>
-# handling. We still want to block ads, and we will allow <br>
-# persistant cookies via the 'shop' alias:<br>
- { shop }<br>
- .quietpc.com <br>
- .worldpay.com # for quietpc.com<br>
- .jungle.com<br>
- .scan.co.uk<br>
-<br>
-<br>
-# These sites require pop-ups too :( We'll combine our 'shop' <br>
-# alias with two other actions into one rule to allow all popups.<br>
- { shop <A
-HREF="actions-file.html#KILL-POPUPS"
-TARGET="_top"
->-kill-popups</A
-> <A
-HREF="actions-file.html#FILTER-POPUPS"
-TARGET="_top"
->-filter{popups}</A
-> }<br>
- .dabs.com<br>
- .overclockers.co.uk<br>
-<br>
-<br>
-# The 'Fast-redirects' action breaks some sites. Disable this action<br>
-# for these known sensitive sites:<br>
- { <A
-HREF="actions-file.html#FAST-REDIRECTS"
-TARGET="_top"
->-fast-redirects</A
-> }<br>
- login.yahoo.com<br>
- edit.europe.yahoo.com<br>
- .google.com<br>
- .altavista.com/.*(like|url|link):http<br>
- .altavista.com/trans.*urltext=http<br>
- .nytimes.com<br>
-<br>
-<br>
-# Define which file types will be treated as images. Important<br>
-# for ad blocking.<br>
- { <A
-HREF="actions-file.html#HANDLE-AS-IMAGE"
-TARGET="_top"
->+handle-as-image</A
-> }<br>
- /.*\.(gif|jpe?g|png|bmp|ico)<br>
-<br>
-<br>
-# Now lets list some domains that are known ad generators. And<br>
-# our alias that we use here will block these as well as force <br>
-# them to be treated as images. This combination of actions is <br>
-# important for ad blocking. What the browser will show instead is <br>
-# determined by the setting of <A
+>send-wafer</A
+> \
+ +<A
+HREF="actions-file.html#SESSION-COOKIES-ONLY"
+>session-cookies-only</A
+> \
+ +<A
HREF="actions-file.html#SET-IMAGE-BLOCKER"
-TARGET="_top"
-><SPAN
+>set-image-blocker{pattern}</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"
->"+set-image-blocker"</SPAN
-></A
-><br>
- { +imageblock }<br>
- ar.atwola.com <br>
- .ad.doubleclick.net<br>
- .a.yimg.com/(?:(?!/i/).)*$<br>
- .a[0-9].yimg.com/(?:(?!/i/).)*$<br>
- bs*.gsanet.com<br>
- bs*.einets.com<br>
- .qkimg.net<br>
- ad.*.doubleclick.net<br>
-<br>
-<br>
-# These will just simply be blocked. They will generate the BLOCKED<br>
-# banner page, if matched. Heavy use of wildcards and regular <br>
-# expressions in this example. Enable block action:<br>
- { <A
-HREF="actions-file.html#BLOCK"
-TARGET="_top"
->+block</A
-> }<br>
- ad*.<br>
- .*ads.<br>
- banner?.<br>
- count*.<br>
- /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)<br>
- /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/<br>
- .hitbox.com <br>
-<br>
-<br>
-# The above block section will probably inadvertantly catch some <br>
-# sites we DO NOT want blocked via the wildcards and regular expressions. <br>
-# Now let's set exceptions to the exceptions so the good guys get better <br>
-# treatment. Disable block action:<br>
- { <A
-HREF="actions-file.html#BLOCK"
-TARGET="_top"
->-block</A
-> }<br>
- advogato.org<br>
- adsl.<br>
- ad[ud]*.<br>
- advice.<br>
-# Let's just trust all .edu top level domains.<br>
- .edu<br>
- www.ugu.com/sui/ugu/adv<br>
-# We'll need to access to path names containing 'download' <br>
- .*downloads.<br>
- /downloads/<br>
-# 'adv' is for globalintersec and means advanced, not advertisement<br>
- www.globalintersec.com/adv<br>
-<br>
-<br>
-# Don't filter *anything* from our friends at sourceforge.<br>
-# Notice we don't have to name the individual filter <br>
-# identifiers -- we just turn them all off in one fell swoop.<br>
-# Disable all filters for this one site:<br>
- { <A
-HREF="actions-file.html#FILTER"
-TARGET="_top"
->-filter</A
-> }<br>
- .sourceforge.net<br>
- </P
->
- </TT
+>"general policy"</SPAN
+> that applies
+ universally and won't get any exceptions defined later. Other choices,
+ like not blocking (which is <I
+CLASS="EMPHASIS"
+>understandably</I
+> the
+ default!) need exceptions, i.e. we need to specify explicitly what we
+ want to block in later sections.
+ We will also want to make exceptions from our general pop-up-killing,
+ and use our defined aliases for that.</P
+><P
+> The first of our specialized sections is concerned with <SPAN
+CLASS="QUOTE"
+>"fragile"</SPAN
+>
+ sites, i.e. sites that require minimum interference, because they are either
+ very complex or very keen on tracking you (and have mechanisms in place that
+ make them unusable for people who avoid being tracked). We will simply use
+ our pre-defined <TT
+CLASS="LITERAL"
+>fragile</TT
+> alias instead of stating the list
+ of actions explicitly:</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>##########################################################################
+# Exceptions for sites that'll break under the default action set:
+##########################################################################
+
+# "Fragile" Use a minimum set of actions for these sites (see alias above):
+#
+{ fragile }
+.office.microsoft.com # surprise, surprise!
+.windowsupdate.microsoft.com</PRE
+></TD
+></TR
+></TABLE
></P
><P
-> So far we are painting with a broad brush by setting general policies.
- The above would be a reasonable starting point for many situations. Now,
- we want to be more specific and have customized rules that are more suitable
- to our 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
- actions files and should not be clobbered by upgrades. So any settings here,
- will have the last word and over-ride any previously defined actions.</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
-> Now a few examples of some things that one might do with a
- <TT
-CLASS="FILENAME"
->user.action</TT
-> file. </P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+># Shopping sites:
+#
+{ shop }
+.quietpc.com
+.worldpay.com # for quietpc.com
+.jungle.com
+.scan.co.uk</PRE
+></TD
+></TR
+></TABLE
+></P
><P
-> <TT
-CLASS="LITERAL"
-> <P
-CLASS="LITERALLAYOUT"
-># Sample user.action file.<br>
-<br>
-# Any aliases you want to use need to be re-defined here.<br>
-# Alias to turn off cookie handling, ie allow all cookies unmolested.<br>
- -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \<br>
- -session-cookies-only<br>
-<br>
-# Fragile sites should have the minimum changes:<br>
- fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \<br>
- -prevent-cookies -kill-popups<br>
-<br>
-# Allow persistent cookies for a few regular sites that we <br>
-# trust via our above alias. These will be saved from one browser session <br>
-# to the next. We are explicity turning off any and all cookie handling, <br>
-# even though the prevent-*-cookie settings were disabled in our above <br>
-# default.action anyway. So cookies from these domains will come through <br>
-# unmolested.<br>
- { -prevent-cookies }<br>
- .sun.com<br>
- .yahoo.com<br>
- .msdn.microsoft.com<br>
- .redhat.com<br>
-<br>
-<br>
-# My ISP uses obnoxious self promoting images on many pages.<br>
-# Nuke them :) Note that <A
-HREF="actions-file.html#HANDLE-AS-IMAGE"
-TARGET="_top"
-><SPAN
-CLASS="QUOTE"
->"+handle-as-image"</SPAN
-></A
-> need not be specified,<br>
-# since all URLs ending in .gif will be tagged as images by the<br>
-# general rules in default.action anyway.<br>
- { <A
-HREF="actions-file.html#BLOCK"
+> Then, there are sites which rely on pop-up windows (yuck!) to work.
+ Since we made pop-up-killing our default above, we need to make exceptions
+ now. <A
+HREF="http://www.mozilla.org/"
TARGET="_top"
->+block</A
-> }<br>
- www.my-isp-example.com/logo[0-9].gif<br>
-<br>
-<br>
-# Say the site where you do your homebanking needs to open<br>
-# popup windows, but you have chosen to kill popups by<br>
-# default. This will allow it for your-example-bank.com:<br>
-#<br>
- { <A
+>Mozilla</A
+> users, who
+ can turn on smart handling of unwanted pop-ups in their browsers, can
+ safely choose
+ -<TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#FILTER-POPUPS"
-TARGET="_top"
->-filter{popups}</A
-> <A
+>filter{popups}</A
+></TT
+> (and
+ -<TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#KILL-POPUPS"
-TARGET="_top"
->-kill-popups</A
-> }<br>
- .my-example-bank.com<br>
-<br>
-<br>
-# This site is delicate, and requires kid-glove <br>
-# treatment.<br>
- { fragile }<br>
- .forbes.com<br>
- </P
->
- </TT
+>kill-popups</A
+></TT
+>) above
+ and hence don't need this section. Anyway, disabling an already disabled
+ action doesn't hurt, so we'll define our exceptions regardless of what was
+ chosen in the defaults section:</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+># These sites require pop-ups too :(
+#
+{ -<A
+HREF="actions-file.html#KILL-POPUPS"
+>kill-popups</A
+> -<A
+HREF="actions-file.html#FILTER-POPUPS"
+>filter{popups}</A
+> }
+.dabs.com
+.overclockers.co.uk
+.deutsche-bank-24.de</PRE
+></TD
+></TR
+></TABLE
></P
-></DIV
-></DIV
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
+><P
+> The <TT
+CLASS="LITERAL"
><A
-NAME="ALIASES"
->8.6. Aliases</A
-></H2
+HREF="actions-file.html#FAST-REDIRECTS"
+>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
-> Custom <SPAN
-CLASS="QUOTE"
->"actions"</SPAN
->, known to <SPAN
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>{ -<A
+HREF="actions-file.html#FAST-REDIRECTS"
+>fast-redirects</A
+> }
+login.yahoo.com
+edit.*.yahoo.com
+.google.com
+.altavista.com/.*(like|url|link):http
+.altavista.com/trans.*urltext=http
+.nytimes.com</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> It is important that <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
+> knows which
+ URLs belong to images, so that <I
+CLASS="EMPHASIS"
+>if</I
+> they are to
+ be blocked, a substitute image can be sent, rather than an HTML page.
+ Contacting the remote site to find out is not an option, since it
+ would destroy the loading time advantage of banner blocking, and it
+ would feed the advertisers (in terms of money <I
+CLASS="EMPHASIS"
+>and</I
>
- as <SPAN
-CLASS="QUOTE"
->"aliases"</SPAN
->, can be defined by combining other <SPAN
-CLASS="QUOTE"
->"actions"</SPAN
->.
- These can in turn be invoked just like the built-in <SPAN
+ information). We can mark any URL as an image with the <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#HANDLE-AS-IMAGE"
+>handle-as-image</A
+></TT
+> action,
+ and marking all URLs that end in a known image file extension is a
+ good start:</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>##########################################################################
+# Images:
+##########################################################################
+
+# Define which file types will be treated as images, in case they get
+# blocked further down this file:
+#
+{ +<A
+HREF="actions-file.html#HANDLE-AS-IMAGE"
+>handle-as-image</A
+> }
+/.*\.(gif|jpe?g|png|bmp|ico)$</PRE
+></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
+ request is for an image. Hence we block them <I
+CLASS="EMPHASIS"
+>and</I
+>
+ mark them as images in one go, with the help of our
+ <TT
+CLASS="LITERAL"
+>block-as-image</TT
+> alias defined above. (We could of
+ course just as well use <TT
+CLASS="LITERAL"
+>+<A
+HREF="actions-file.html#BLOCK"
+>block</A
+>
+ +<A
+HREF="actions-file.html#HANDLE-AS-IMAGE"
+>handle-as-image</A
+></TT
+> here.)
+ Remember that the type of the replacement image is chosen by the
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#SET-IMAGE-BLOCKER"
+>set-image-blocker</A
+></TT
+>
+ action. Since all URLs have matched the default section with its
+ <TT
+CLASS="LITERAL"
+>+<A
+HREF="actions-file.html#SET-IMAGE-BLOCKER"
+>set-image-blocker</A
+>{pattern}</TT
+>
+ action before, it still applies and needn't be repeated:</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+># Known ad generators:
+#
+{ block-as-image }
+ar.atwola.com
+.ad.doubleclick.net
+.ad.*.doubleclick.net
+.a.yimg.com/(?:(?!/i/).)*$
+.a[0-9].yimg.com/(?:(?!/i/).)*$
+bs*.gsanet.com
+bs*.einets.com
+.qkimg.net</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> One of the most important jobs of <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>
+ is to block banners. A huge bunch of them are already <SPAN
CLASS="QUOTE"
->"actions"</SPAN
->.
- Currently, an alias can contain any character except space, tab, <SPAN
+>"blocked"</SPAN
+>
+ by the <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#FILTER"
+>filter</A
+>{banners-by-size}</TT
+>
+ action, which we enabled above, and which deletes the references to banner
+ images from the pages while they are loaded, so the browser doesn't request
+ them anymore, and hence they don't need to be blocked here. But this naturally
+ doesn't catch all banners, and some people choose not to use filters, so we
+ need a comprehensive list of patterns for banner URLs here, and apply the
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>block</A
+></TT
+> action to them.</P
+><P
+> First comes a bunch of generic patterns, which do most of the work, by
+ matching typical domain and path name components of banners. Then comes
+ a list of individual patterns for specific sites, which is omitted here
+ to keep the example short:</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>##########################################################################
+# Block these fine banners:
+##########################################################################
+{ <A
+HREF="actions-file.html#BLOCK"
+>+block</A
+> }
+
+# Generic patterns:
+#
+ad*.
+.*ads.
+banner?.
+count*.
+/.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
+/(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
+
+# Site-specific patterns (abbreviated):
+#
+.hitbox.com</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> You wouldn't believe how many advertisers actually call their banner
+ servers ads.<TT
+CLASS="REPLACEABLE"
+><I
+>company</I
+></TT
+>.com, or call the directory
+ in which the banners are stored simply <SPAN
CLASS="QUOTE"
->"="</SPAN
->,
+>"banners"</SPAN
+>. So the above
+ generic patterns are surprisingly effective.</P
+><P
+> But being very generic, they necessarily also catch URLs that we don't want
+ to block. The pattern <TT
+CLASS="LITERAL"
+>.*ads.</TT
+> e.g. catches
<SPAN
CLASS="QUOTE"
->"{"</SPAN
-> or <SPAN
-CLASS="QUOTE"
->"}"</SPAN
->. But please use only <SPAN
+>"nasty-<I
+CLASS="EMPHASIS"
+>ads</I
+>.nasty-corp.com"</SPAN
+> as intended,
+ but also <SPAN
CLASS="QUOTE"
->"a"</SPAN
->-
+>"downlo<I
+CLASS="EMPHASIS"
+>ads</I
+>.sourcefroge.net"</SPAN
+> or
<SPAN
CLASS="QUOTE"
->"z"</SPAN
->, <SPAN
-CLASS="QUOTE"
->"0"</SPAN
->-<SPAN
-CLASS="QUOTE"
->"9"</SPAN
->, <SPAN
-CLASS="QUOTE"
->"+"</SPAN
->, and
+>"<I
+CLASS="EMPHASIS"
+>ads</I
+>l.some-provider.net."</SPAN
+> So here come some
+ well-known exceptions to the <TT
+CLASS="LITERAL"
+>+<A
+HREF="actions-file.html#BLOCK"
+>block</A
+></TT
+>
+ section above.</P
+><P
+> Note that these are exceptions to exceptions from the default! Consider the URL
<SPAN
CLASS="QUOTE"
->"-"</SPAN
->. Alias names are not case sensitive, and
- <I
+>"downloads.sourcefroge.net"</SPAN
+>: Initially, all actions are deactivated,
+ so it wouldn't get blocked. Then comes the defaults section, which matches the
+ URL, but just deactivates the <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>block</A
+></TT
+>
+ action once again. Then it matches <TT
+CLASS="LITERAL"
+>.*ads.</TT
+>, an exception to the
+ general non-blocking policy, and suddenly
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>+block</A
+></TT
+> applies. And now, it'll match
+ <TT
+CLASS="LITERAL"
+>.*loads.</TT
+>, where <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>-block</A
+></TT
+>
+ applies, so (unless it matches <I
CLASS="EMPHASIS"
->must be defined before other actions</I
-> in the
- actions file! And there can only be one set of <SPAN
+>again</I
+> further down) it ends up
+ with no <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>block</A
+></TT
+> action applying.</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>##########################################################################
+# Save some innocent victims of the above generic block patterns:
+##########################################################################
+
+# By domain:
+#
+{ -<A
+HREF="actions-file.html#BLOCK"
+>block</A
+> }
+adv[io]*. # (for advogato.org and advice.*)
+adsl. # (has nothing to do with ads)
+ad[ud]*. # (adult.* and add.*)
+.edu # (universities don't host banners (yet!))
+.*loads. # (downloads, uploads etc)
+
+# By path:
+#
+/.*loads/
+
+# Site-specific:
+#
+www.globalintersec.com/adv # (adv = advanced)
+www.ugu.com/sui/ugu/adv</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> Filtering source code can have nasty side effects,
+ so make an exception for our friends at sourceforge.net,
+ and all paths with <SPAN
CLASS="QUOTE"
->"aliases"</SPAN
+>"cvs"</SPAN
+> in them. Note that
+ <TT
+CLASS="LITERAL"
+>-<A
+HREF="actions-file.html#FILTER"
+>filter</A
+></TT
>
- defined per file. Each actions file may have its own aliases, but they are
- only visible within that file. Aliases do not requir a <SPAN
-CLASS="QUOTE"
->"+"</SPAN
-> or
+ disables <I
+CLASS="EMPHASIS"
+>all</I
+> filters in one fell swoop!</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+># Don't filter code!
+#
+{ -<A
+HREF="actions-file.html#FILTER"
+>filter</A
+> }
+/.*cvs
+.sourceforge.net</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> The actual <TT
+CLASS="FILENAME"
+>default.action</TT
+> is of course more
+ comprehensive, but we hope this example made clear how it works.</P
+></DIV
+><DIV
+CLASS="SECT3"
+><H3
+CLASS="SECT3"
+><A
+NAME="AEN2675"
+>8.7.2. 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,
+ you'd maybe 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
+ actions files and hence has the last word, over-riding any previously
+ defined actions. <TT
+CLASS="FILENAME"
+>user.action</TT
+> is also a
+ <I
+CLASS="EMPHASIS"
+>safe</I
+> place for your personal settings, since
+ <TT
+CLASS="FILENAME"
+>default.action</TT
+> is actively maintained by the
<SPAN
-CLASS="QUOTE"
->"-"</SPAN
-> sign in front, since they are merely expanded.</P
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> developers and you'll probably want
+ to install updated versions from time to time.</P
><P
-> Now let's define a few aliases:</P
+> So let's look at a few examples of things that one might typically do in
+ <TT
+CLASS="FILENAME"
+>user.action</TT
+>: </P
><P
-> <TT
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+># My user.action file. <fred@foobar.com></PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> As <A
+HREF="actions-file.html#ALIASES"
+>aliases</A
+> are local to the actions
+ file that they are defined in, you can't use the ones from
+ <TT
+CLASS="FILENAME"
+>default.action</TT
+>, unless you repeat them here:</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+># (Re-)define aliases for this file:
+#
+{{alias}}
+-crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
+mercy-for-cookies = -crunch-all-cookies -session-cookies-only
+fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups
+shop = mercy-for-cookies -filter{popups} -kill-popups
+allow-ads = -block -filter{banners-by-size} # (see below)</PRE
+></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
+ to allow persistent cookies for these sites. The
+ <TT
CLASS="LITERAL"
-> <P
-CLASS="LITERALLAYOUT"
-> # Useful custom aliases we can use later. These must come first!<br>
- {{alias}}<br>
- +prevent-cookies = +prevent-setting-cookies +prevent-reading-cookies<br>
- -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies<br>
- fragile = -block -prevent-cookies -filter -fast-redirects -hide-referer -kill-popups<br>
- shop = -prevent-cookies -filter -fast-redirects<br>
- +imageblock = +block +handle-as-image<br>
-<br>
- # Aliases defined from other aliases, for people who don't like to type <br>
- # too much: ;-)<br>
- c0 = +prevent-cookies<br>
- c1 = -prevent-cookies<br>
- #... etc. Customize to your heart's content.<br>
- </P
->
- </TT
+>mercy-for-cookies</TT
+> alias defined above does exactly
+ that, i.e. it disables crunching of cookies in any direction, and
+ processing of cookies to make them temporary.</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>{ mercy-for-cookies }
+sunsolve.sun.com
+slashdot.org
+.yahoo.com
+.msdn.microsoft.com
+.redhat.com</PRE
+></TD
+></TR
+></TABLE
></P
><P
-> Some examples using our <SPAN
-CLASS="QUOTE"
->"shop"</SPAN
-> and <SPAN
-CLASS="QUOTE"
->"fragile"</SPAN
+> Your bank needs popups and is allergic to some filter, but you don't
+ know which, so you disable them all:</P
+><P
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>{ -<A
+HREF="actions-file.html#FILTER"
+>filter</A
+> -<A
+HREF="actions-file.html#KILL-POPUPS"
+>kill-popups</A
+> }
+.your-home-banking-site.com</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> While browsing the web with <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> you
+ noticed some ads that sneaked through, but you were too lazy to
+ report them through our fine and easy <A
+HREF="contact.html"
+>feedback</A
>
- aliases from above. These would appear in the lower sections of an
- actions file as exceptions to the default actions (as defined in the
- upper section):</P
+ system, so you have added them here:</P
><P
-> <TT
+> <TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>{ +<A
+HREF="actions-file.html#BLOCK"
+>block</A
+> }
+www.a-popular-site.com/some/unobvious/path
+another.popular.site.net/more/junk/here/</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> Note that, assuming the banners in the above example have regular image
+ extensions (most do),
+ <TT
CLASS="LITERAL"
-> <P
-CLASS="LITERALLAYOUT"
-> # These sites are very complex and require<br>
- # minimal interference.<br>
- {fragile}<br>
- .office.microsoft.com<br>
- .windowsupdate.microsoft.com<br>
- .nytimes.com<br>
-<br>
- # Shopping sites - but we still want to block ads.<br>
- {shop}<br>
- .quietpc.com<br>
- .worldpay.com # for quietpc.com<br>
- .scan.co.uk<br>
-<br>
- # These shops require pop-ups also <br>
- {shop -kill-popups}<br>
- .dabs.com<br>
- .overclockers.co.uk<br>
- </P
->
- </TT
+>+<A
+HREF="actions-file.html#HANDLE-AS-IMAGE"
+>handle-as-image</A
+></TT
+>
+ need not be specified, since all URLs ending in these extensions will
+ already have been tagged as images in the relevant section of
+ <TT
+CLASS="FILENAME"
+>default.action</TT
+> by now.</P
+><P
+> Then you noticed that the default configuration breaks Forbes Magazine,
+ but you were too lazy to find out which action is the culprit, and you
+ were again too lazy to give <A
+HREF="contact.html"
+>feedback</A
+>, so
+ you just used the <TT
+CLASS="LITERAL"
+>fragile</TT
+> alias on the site, and
+ -- whoa! -- it worked:</P
+><P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>{ fragile }
+.forbes.com</PRE
+></TD
+></TR
+></TABLE
></P
><P
-> The <SPAN
-CLASS="QUOTE"
->"shop"</SPAN
-> and <SPAN
+> You like the <SPAN
CLASS="QUOTE"
->"fragile"</SPAN
-> aliases are often used for
- <SPAN
+>"fun"</SPAN
+> text replacements in <TT
+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,
+ update-safe config, once and for all:</P
+><P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>{ +<A
+HREF="actions-file.html#FILTER-FUN"
+>filter{fun}</A
+> }
+/ # For ALL sites!</PRE
+></TD
+></TR
+></TABLE
+></P
+><P
+> Note that the above is not really a good idea: There are exceptions
+ to the filters in <TT
+CLASS="FILENAME"
+>default.action</TT
+> for things that
+ really shouldn't be filtered, like code on CVS->Web interfaces. Since
+ <TT
+CLASS="FILENAME"
+>user.action</TT
+> has the last word, these exceptions
+ won't be valid for the <SPAN
CLASS="QUOTE"
->"problem"</SPAN
-> sites that require most actions to be disabled
- in order to function properly. </P
+>"fun"</SPAN
+> filtering specified here.</P
+><P
+> Finally, you might think about how your favourite free websites are
+ funded, and find that they rely on displaying banner advertisements
+ to survive. So you might want to specifically allow banners for those
+ sites that you feel provide value to you:</P
+><P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>{ allow-ads }
+.sourceforge.net
+.slashdot.org
+.osdn.net</PRE
+></TD
+></TR
+></TABLE
+> </P
+><P
+> Note that <TT
+CLASS="LITERAL"
+>allow-ads</TT
+> 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
+>
+ above.</P
+></DIV
></DIV
></DIV
><DIV
projects / privoxy.git / blobdiff