-<HTML
-><HEAD
-><TITLE
->Actions Files</TITLE
-><META
-NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
-"><LINK
-REL="HOME"
-TITLE="Privoxy 3.0.4 User Manual"
-HREF="index.html"><LINK
-REL="PREVIOUS"
-TITLE="The Main Configuration File"
-HREF="config.html"><LINK
-REL="NEXT"
-TITLE="Filter Files"
-HREF="filter-file.html"><LINK
-REL="STYLESHEET"
-TYPE="text/css"
-HREF="../p_doc.css">
-<LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css">
-</head
-><BODY
-CLASS="SECT1"
-BGCOLOR="#EEEEEE"
-TEXT="#000000"
-LINK="#0000FF"
-VLINK="#840084"
-ALINK="#0000FF"
-><DIV
-CLASS="NAVHEADER"
-><TABLE
-SUMMARY="Header navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TH
-COLSPAN="3"
-ALIGN="center"
->Privoxy 3.0.4 User Manual</TH
-></TR
-><TR
-><TD
-WIDTH="10%"
-ALIGN="left"
-VALIGN="bottom"
-><A
-HREF="config.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
-></TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="filter-file.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><DIV
-CLASS="SECT1"
-><H1
-CLASS="SECT1"
-><A
-NAME="ACTIONS-FILE"
-></A
->8. Actions Files</H1
-><P
-> The actions files are used to define what <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->actions</I
-></SPAN
->
- <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> takes for which URLs, and thus determines
- how ad images, cookies and various other aspects of HTTP content and
- transactions are handled, and on which sites (or even parts thereof).
- There are a number of such actions, with a wide range of functionality.
- Each action does something a little different.
- These actions give us a veritable arsenal of tools with which to exert
- our control, preferences and independence.</P
-><P
-> There
- are three action files included with <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> with
- differing purposes:
- </P
-><P
-> <P
-></P
-><UL
-><LI
-><P
-> <TT
-CLASS="FILENAME"
->default.action</TT
-> - is the primary action file
- that sets the initial values for all actions. It is intended to
- provide a base level of functionality for
- <SPAN
-CLASS="APPLICATION"
->Privoxy's</SPAN
-> array of features. So it is
- a set of broad rules that should work reasonably well for users everywhere.
- This is the file that the developers are keeping updated, and <A
-HREF="installation.html#INSTALLATION-KEEPUPDATED"
->making available to users</A
->.
- </P
-></LI
-><LI
-><P
-> <TT
-CLASS="FILENAME"
->user.action</TT
-> - is intended to be for local site
- preferences and exceptions. As an example, if your ISP or your bank
- has specific requirements, and need special handling, this kind of
- thing should go here. This file will not be upgraded.
- </P
-></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 <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->and have no influence on your browsing unless
- you select them explicitly in the editor</I
-></SPAN
->. It is not recommend
- to edit this file.
- </P
-><P
-> The default profiles, and their associated actions, as pre-defined in
- <TT
-CLASS="FILENAME"
->standard.action</TT
-> are:
- </P
-><P
-> <DIV
-CLASS="TABLE"
-><A
-NAME="AEN1912"
-></A
-><P
-><B
->Table 1. Default Configurations</B
-></P
-><TABLE
-BORDER="1"
-CLASS="CALSTABLE"
-><THEAD
-><TR
-><TH
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Feature</TH
-><TH
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Cautious</TH
-><TH
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Medium</TH
-><TH
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Adventuresome</TH
-></TR
-></THEAD
-><TBODY
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Ad-blocking by URL</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Ad-filtering by size</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->GIF de-animation</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->no</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Referer forging</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->no</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Cookie handling</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->none</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->session-only</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->kill</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Pop-up killing</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->unsolicited</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->unsolicited</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->all</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Fast redirects</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->no</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->no</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->HTML taming</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->JavaScript taming</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Web-bug killing</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Fun text replacements</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->no</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->no</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Image tag reordering</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->no</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->no</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Ad-filtering by link</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->no</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->no</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-></TR
-><TR
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->Demoronizer</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->no</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->no</TD
-><TD
-WIDTH="25%"
-ALIGN="LEFT"
-VALIGN="TOP"
->yes</TD
-></TR
-></TBODY
-></TABLE
-></DIV
->
- </P
-></LI
-></UL
->
- </P
-><P
-> The list of actions files to be used are defined in the main configuration
- file, and are processed in the order they are defined (e.g.
- <TT
-CLASS="FILENAME"
->default.action</TT
-> is typically process before
- <TT
-CLASS="FILENAME"
->user.action</TT
->). The content of these can all be viewed and
- edited from <A
-HREF="http://config.privoxy.org/show-status"
-TARGET="_top"
->http://config.privoxy.org/show-status</A
->.</P
-><P
-> An actions file typically has multiple sections. If you want to use
- <SPAN
-CLASS="QUOTE"
->"aliases"</SPAN
-> in an actions file, you have to place the (optional)
- <A
-HREF="actions-file.html#ALIASES"
->alias section</A
-> at the top of that file.
- Then comes the default set of rules which will apply universally to all
- sites and pages (be <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->very careful</I
-></SPAN
-> with using such a
- universal set in <TT
-CLASS="FILENAME"
->user.action</TT
-> or any other actions file after
- <TT
-CLASS="FILENAME"
->default.action</TT
->, because it will override the result
- from consulting any previous file). And then below that,
- exceptions to the defined universal policies. You can regard
- <TT
-CLASS="FILENAME"
->user.action</TT
-> as an appendix to <TT
-CLASS="FILENAME"
->default.action</TT
->,
- with the advantage that is a separate file, which makes preserving your
- personal settings across <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> upgrades easier.</P
-><P
->
- Actions can be used to block anything you want, including ads, banners, or
- just some obnoxious URL that you would rather not see. Cookies can be accepted
- or rejected, or accepted only during the current browser session (i.e. not
- written to disk), content can be modified, JavaScripts tamed, user-tracking
- fooled, and much more. See below for a <A
-HREF="actions-file.html#ACTIONS"
->complete list
- of actions</A
->.</P
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="AEN2011"
-></A
->8.1. Finding the Right Mix</H2
-><P
-> Note that some <A
-HREF="actions-file.html#ACTIONS"
->actions</A
->, like cookie suppression
- or script disabling, may render some sites unusable that rely on these
- techniques to work properly. Finding the right mix of actions is not always easy and
- certainly a matter of personal taste. In general, it can be said that the more
- <SPAN
-CLASS="QUOTE"
->"aggressive"</SPAN
-> your default settings (in the top section of the
- actions file) are, the more exceptions for <SPAN
-CLASS="QUOTE"
->"trusted"</SPAN
-> sites you
- will have to make later. If, for example, you want to crunch all cookies per
- default, you'll have to make exceptions from that rule for sites that you
- regularly use and that require cookies for actually useful puposes, like maybe
- your bank, favorite shop, or newspaper. </P
-><P
-> We have tried to provide you with reasonable rules to start from in the
- distribution actions files. But there is no general rule of thumb on these
- things. There just are too many variables, and sites are constantly changing.
- Sooner or later you will want to change the rules (and read this chapter again :).</P
-></DIV
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="AEN2018"
-></A
->8.2. How to Edit</H2
-><P
-> The easiest way to edit the actions files is with a browser by
- using our browser-based editor, which can be reached from <A
-HREF="http://config.privoxy.org/show-status"
-TARGET="_top"
->http://config.privoxy.org/show-status</A
->.
- The editor allows both fine-grained control over every single feature on a
- per-URL basis, and easy choosing from wholesale sets of defaults like
- <SPAN
-CLASS="QUOTE"
->"Cautious"</SPAN
->, <SPAN
-CLASS="QUOTE"
->"Medium"</SPAN
-> or <SPAN
-CLASS="QUOTE"
->"Adventuresome"</SPAN
->.
- Warning: the <SPAN
-CLASS="QUOTE"
->"Adventuresome"</SPAN
-> setting is not only more aggressive,
- but includes settings that are fun and subversive, and which some may find of
- dubious merit!</P
-><P
-> If you prefer plain text editing to GUIs, you can of course also directly edit the
- the actions files. Look at <TT
-CLASS="FILENAME"
->default.action</TT
-> which is richly
- commented.</P
-></DIV
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="ACTIONS-APPLY"
-></A
->8.3. How Actions are Applied to URLs</H2
-><P
-> Actions files are divided into sections. There are special sections,
- like the <SPAN
-CLASS="QUOTE"
->"<A
-HREF="actions-file.html#ALIASES"
->alias</A
->"</SPAN
-> sections which will
- be discussed later. For now let's concentrate on regular sections: They have a
- heading line (often split up to multiple lines for readability) which consist
- of a list of actions, separated by whitespace and enclosed in curly braces.
- Below that, there is a list of URL patterns, each on a separate line.</P
-><P
-> To determine which actions apply to a request, the URL of the request is
- compared to all patterns in each <SPAN
-CLASS="QUOTE"
->"action file"</SPAN
-> file. Every time it matches, the list of
- applicable actions for the URL is incrementally updated, using the heading
- of the section in which the pattern is located. If multiple matches for
- the same URL set the same action differently, the last match wins. If not,
- the effects are aggregated. E.g. a URL might match a regular section with
- a heading line of <TT
-CLASS="LITERAL"
->{
- +<A
-HREF="actions-file.html#HANDLE-AS-IMAGE"
->handle-as-image</A
-> }</TT
->,
- then later another one with just <TT
-CLASS="LITERAL"
->{
- +<A
-HREF="actions-file.html#BLOCK"
->block</A
-> }</TT
->, resulting
- in <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->both</I
-></SPAN
-> actions to apply.</P
-><P
-> You can trace this process for any given URL by visiting <A
-HREF="http://config.privoxy.org/show-url-info"
-TARGET="_top"
->http://config.privoxy.org/show-url-info</A
->.</P
-><P
-> More detail on this is provided in the Appendix, <A
-HREF="appendix.html#ACTIONSANAT"
-> Anatomy of an Action</A
->.</P
-></DIV
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="AF-PATTERNS"
-></A
->8.4. Patterns</H2
-><P
->
- As mentioned, <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> uses <SPAN
-CLASS="QUOTE"
->"patterns"</SPAN
->
- to determine what actions might apply to which sites and pages your browser
- attempts to access. These <SPAN
-CLASS="QUOTE"
->"patterns"</SPAN
-> use wild card type
- <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->pattern</I
-></SPAN
-> matching to achieve a high degree of
- flexibility. This allows one expression to be expanded and potentially match
- against many similar patterns.</P
-><P
-> Generally, a <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> pattern has the form
- <TT
-CLASS="LITERAL"
-><domain>/<path></TT
->, where both the
- <TT
-CLASS="LITERAL"
-><domain></TT
-> and <TT
-CLASS="LITERAL"
-><path></TT
-> are
- optional. (This is why the special <TT
-CLASS="LITERAL"
->/</TT
-> pattern matches all
- URLs). Note that the protocol portion of the URL pattern (e.g.
- <TT
-CLASS="LITERAL"
->http://</TT
->) should <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->not</I
-></SPAN
-> be included in
- the pattern. This is assumed already!</P
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
-><TT
-CLASS="LITERAL"
->www.example.com/</TT
-></DT
-><DD
-><P
-> is a domain-only pattern and will match any request to <TT
-CLASS="LITERAL"
->www.example.com</TT
->,
- regardless of which document on that server is requested.
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->www.example.com</TT
-></DT
-><DD
-><P
-> means exactly the same. For domain-only patterns, the trailing <TT
-CLASS="LITERAL"
->/</TT
-> may
- be omitted.
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->www.example.com/index.html</TT
-></DT
-><DD
-><P
-> matches only the single document <TT
-CLASS="LITERAL"
->/index.html</TT
->
- on <TT
-CLASS="LITERAL"
->www.example.com</TT
->.
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->/index.html</TT
-></DT
-><DD
-><P
-> matches the document <TT
-CLASS="LITERAL"
->/index.html</TT
->, regardless of the domain,
- i.e. on <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->any</I
-></SPAN
-> web server.
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->index.html</TT
-></DT
-><DD
-><P
-> matches nothing, since it would be interpreted as a domain name and
- there is no top-level domain called <TT
-CLASS="LITERAL"
->.html</TT
->.
- </P
-></DD
-></DL
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="AEN2092"
-></A
->8.4.1. The Domain Pattern</H3
-><P
-> The matching of the domain part offers some flexible options: if the
- domain starts or ends with a dot, it becomes unanchored at that end.
- For example:</P
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
-><TT
-CLASS="LITERAL"
->.example.com</TT
-></DT
-><DD
-><P
-> matches any domain that <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->ENDS</I
-></SPAN
-> in
- <TT
-CLASS="LITERAL"
->.example.com</TT
->
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->www.</TT
-></DT
-><DD
-><P
-> matches any domain that <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->STARTS</I
-></SPAN
-> with
- <TT
-CLASS="LITERAL"
->www.</TT
->
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->.example.</TT
-></DT
-><DD
-><P
-> matches any domain that <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->CONTAINS</I
-></SPAN
-> <TT
-CLASS="LITERAL"
->.example.</TT
->
- (Correctly speaking: It matches any FQDN that contains <TT
-CLASS="LITERAL"
->example</TT
-> as a domain.)
- </P
-></DD
-></DL
-></DIV
-><P
-> Additionally, there are wild-cards that you can use in the domain names
- themselves. They work pretty similar to shell wild-cards: <SPAN
-CLASS="QUOTE"
->"*"</SPAN
->
- stands for zero or more arbitrary characters, <SPAN
-CLASS="QUOTE"
->"?"</SPAN
-> stands for
- any single character, you can define character classes in square
- brackets and all of that can be freely mixed:</P
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
-><TT
-CLASS="LITERAL"
->ad*.example.com</TT
-></DT
-><DD
-><P
-> matches <SPAN
-CLASS="QUOTE"
->"adserver.example.com"</SPAN
->,
- <SPAN
-CLASS="QUOTE"
->"ads.example.com"</SPAN
->, etc but not <SPAN
-CLASS="QUOTE"
->"sfads.example.com"</SPAN
->
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->*ad*.example.com</TT
-></DT
-><DD
-><P
-> matches all of the above, and then some.
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->.?pix.com</TT
-></DT
-><DD
-><P
-> matches <TT
-CLASS="LITERAL"
->www.ipix.com</TT
->,
- <TT
-CLASS="LITERAL"
->pictures.epix.com</TT
->, <TT
-CLASS="LITERAL"
->a.b.c.d.e.upix.com</TT
-> etc.
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->www[1-9a-ez].example.c*</TT
-></DT
-><DD
-><P
-> matches <TT
-CLASS="LITERAL"
->www1.example.com</TT
->,
- <TT
-CLASS="LITERAL"
->www4.example.cc</TT
->, <TT
-CLASS="LITERAL"
->wwwd.example.cy</TT
->,
- <TT
-CLASS="LITERAL"
->wwwz.example.com</TT
-> etc., but <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->not</I
-></SPAN
->
- <TT
-CLASS="LITERAL"
->wwww.example.com</TT
->.
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="AEN2154"
-></A
->8.4.2. The Path Pattern</H3
-><P
-> <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> uses Perl compatible regular expressions
- (through the <A
-HREF="http://www.pcre.org/"
-TARGET="_top"
->PCRE</A
-> library) for
- matching the path.</P
-><P
-> There is an <A
-HREF="appendix.html#REGEX"
->Appendix</A
-> with a brief quick-start into regular
- expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
- at <A
-HREF="http://www.pcre.org/man.txt"
-TARGET="_top"
->http://www.pcre.org/man.txt</A
->.
- You might also find the Perl man page on regular expressions (<TT
-CLASS="LITERAL"
->man perlre</TT
->)
- useful, which is available on-line at <A
-HREF="http://perldoc.perl.org/perlre.html"
-TARGET="_top"
->http://perldoc.perl.org/perlre.html</A
->.</P
-><P
-> Note that the path pattern is automatically left-anchored at the <SPAN
-CLASS="QUOTE"
->"/"</SPAN
->,
- i.e. it matches as if it would start with a <SPAN
-CLASS="QUOTE"
->"^"</SPAN
-> (regular expression speak
- for the beginning of a line).</P
-><P
-> Please also note that matching in the path is <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->CASE INSENSITIVE</I
-></SPAN
->
- by default, but you can switch to case sensitive at any point in the pattern by using the
- <SPAN
-CLASS="QUOTE"
->"(?-i)"</SPAN
-> switch: <TT
-CLASS="LITERAL"
->www.example.com/(?-i)PaTtErN.*</TT
-> will match
- only documents whose path starts with <TT
-CLASS="LITERAL"
->PaTtErN</TT
-> in
- <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->exactly</I
-></SPAN
-> this capitalization.</P
-></DIV
-></DIV
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="ACTIONS"
-></A
->8.5. Actions</H2
-><P
-> All actions are disabled by default, until they are explicitly enabled
- somewhere in an actions file. Actions are turned on if preceded with a
- <SPAN
-CLASS="QUOTE"
->"+"</SPAN
->, and turned off if preceded with a <SPAN
-CLASS="QUOTE"
->"-"</SPAN
->. So a
- <TT
-CLASS="LITERAL"
->+action</TT
-> means <SPAN
-CLASS="QUOTE"
->"do that action"</SPAN
->, e.g.
- <TT
-CLASS="LITERAL"
->+block</TT
-> means <SPAN
-CLASS="QUOTE"
->"please block URLs that match the
- following patterns"</SPAN
->, and <TT
-CLASS="LITERAL"
->-block</TT
-> means <SPAN
-CLASS="QUOTE"
->"don't
- block URLs that match the following patterns, even if <TT
-CLASS="LITERAL"
->+block</TT
->
- previously applied."</SPAN
-> </P
-><P
->
- Again, actions are invoked by placing them on a line, enclosed in curly braces and
- separated by whitespace, like in
- <TT
-CLASS="LITERAL"
->{+some-action -some-other-action{some-parameter}}</TT
->,
- followed by a list of URL patterns, one per line, to which they apply.
- Together, the actions line and the following pattern lines make up a section
- of the actions file. </P
-><P
->
- There are three classes of actions:</P
-><P
-> <P
-></P
-><UL
-><LI
-><P
->
- Boolean, i.e the action can only be <SPAN
-CLASS="QUOTE"
->"enabled"</SPAN
-> or
- <SPAN
-CLASS="QUOTE"
->"disabled"</SPAN
->. Syntax:
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> +<TT
-CLASS="REPLACEABLE"
-><I
->name</I
-></TT
-> # enable action <TT
-CLASS="REPLACEABLE"
-><I
->name</I
-></TT
->
- -<TT
-CLASS="REPLACEABLE"
-><I
->name</I
-></TT
-> # disable action <TT
-CLASS="REPLACEABLE"
-><I
->name</I
-></TT
-></PRE
-></TD
-></TR
-></TABLE
->
- </P
-><P
->
- Example: <TT
-CLASS="LITERAL"
->+block</TT
->
- </P
-></LI
-><LI
-><P
->
- Parameterized, where some value is required in order to enable this type of action.
- Syntax:
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> +<TT
-CLASS="REPLACEABLE"
-><I
->name</I
-></TT
->{<TT
-CLASS="REPLACEABLE"
-><I
->param</I
-></TT
->} # enable action and set parameter to <TT
-CLASS="REPLACEABLE"
-><I
->param</I
-></TT
->,
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+
+<html>
+<head>
+ <title>Actions Files</title>
+ <meta name="GENERATOR" content=
+ "Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="HOME" title="Privoxy 3.0.21 User Manual" href="index.html">
+ <link rel="PREVIOUS" title="The Main Configuration File" href=
+ "config.html">
+ <link rel="NEXT" title="Filter Files" href="filter-file.html">
+ <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <link rel="STYLESHEET" type="text/css" href="p_doc.css">
+</head>
+
+<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
+"#840084" alink="#0000FF">
+ <div class="NAVHEADER">
+ <table summary="Header navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <th colspan="3" align="center">Privoxy 3.0.21 User Manual</th>
+ </tr>
+
+ <tr>
+ <td width="10%" align="left" valign="bottom"><a href="config.html"
+ accesskey="P">Prev</a></td>
+
+ <td width="80%" align="center" valign="bottom"></td>
+
+ <td width="10%" align="right" valign="bottom"><a href=
+ "filter-file.html" accesskey="N">Next</a></td>
+ </tr>
+ </table>
+ <hr align="left" width="100%">
+ </div>
+
+ <div class="SECT1">
+ <h1 class="SECT1"><a name="ACTIONS-FILE" id="ACTIONS-FILE">8. Actions
+ Files</a></h1>
+
+ <p>The actions files are used to define what <span class=
+ "emphasis"><i class="EMPHASIS">actions</i></span> <span class=
+ "APPLICATION">Privoxy</span> takes for which URLs, and thus determines
+ how ad images, cookies and various other aspects of HTTP content and
+ transactions are handled, and on which sites (or even parts thereof).
+ There are a number of such actions, with a wide range of functionality.
+ Each action does something a little different. These actions give us a
+ veritable arsenal of tools with which to exert our control, preferences
+ and independence. Actions can be combined so that their effects are
+ aggregated when applied against a given set of URLs.</p>
+
+ <p>There are three action files included with <span class=
+ "APPLICATION">Privoxy</span> with differing purposes:</p>
+
+ <ul>
+ <li>
+ <p><tt class="FILENAME">match-all.action</tt> - is used to define
+ which <span class="QUOTE">"actions"</span> relating to
+ banner-blocking, images, pop-ups, content modification, cookie
+ handling etc should be applied by default. It should be the first
+ actions file loaded</p>
+ </li>
+
+ <li>
+ <p><tt class="FILENAME">default.action</tt> - defines many exceptions
+ (both positive and negative) from the default set of actions that's
+ configured in <tt class="FILENAME">match-all.action</tt>. It is a set
+ of rules that should work reasonably well as-is for most users. This
+ file is only supposed to be edited by the developers. It should be
+ the second actions file loaded.</p>
+ </li>
+
+ <li>
+ <p><tt class="FILENAME">user.action</tt> - is intended to be for
+ local site preferences and exceptions. As an example, if your ISP or
+ your bank has specific requirements, and need special handling, this
+ kind of thing should go here. This file will not be upgraded.</p>
+ </li>
+
+ <li>
+ <p><span class="GUIBUTTON">Edit</span> <span class="GUIBUTTON">Set to
+ Cautious</span> <span class="GUIBUTTON">Set to Medium</span>
+ <span class="GUIBUTTON">Set to Advanced</span></p>
+
+ <p>These have increasing levels of aggressiveness <span class=
+ "emphasis"><i class="EMPHASIS">and have no influence on your browsing
+ unless you select them explicitly in the editor</i></span>. A default
+ installation should be pre-set to <tt class="LITERAL">Cautious</tt>.
+ New users should try this for a while before adjusting the settings
+ to more aggressive levels. The more aggressive the settings, then the
+ more likelihood there is of problems such as sites not working as
+ they should.</p>
+
+ <p>The <span class="GUIBUTTON">Edit</span> button allows you to turn
+ each action on/off individually for fine-tuning. The <span class=
+ "GUIBUTTON">Cautious</span> button changes the actions list to
+ low/safe settings which will activate ad blocking and a minimal set
+ of <span class="APPLICATION">Privoxy</span>'s features, and
+ subsequently there will be less of a chance for accidental problems.
+ The <span class="GUIBUTTON">Medium</span> button sets the list to a
+ medium level of other features and a low level set of privacy
+ features. The <span class="GUIBUTTON">Advanced</span> button sets the
+ list to a high level of ad blocking and medium level of privacy. See
+ the chart below. The latter three buttons over-ride any changes via
+ with the <span class="GUIBUTTON">Edit</span> button. More fine-tuning
+ can be done in the lower sections of this internal page.</p>
+
+ <p>While the actions file editor allows to enable these settings in
+ all actions files, they are only supposed to be enabled in the first
+ one to make sure you don't unintentionally overrule earlier
+ rules.</p>
+
+ <p>The default profiles, and their associated actions, as pre-defined
+ in <tt class="FILENAME">default.action</tt> are:</p>
+
+ <div class="TABLE">
+ <a name="AEN2777" id="AEN2777"></a>
+
+ <p><b>Table 1. Default Configurations</b></p>
+
+ <table border="1" frame="border" rules="all" class="CALSTABLE">
+ <col width="1*" title="C1">
+ <col width="1*" title="C2">
+ <col width="1*" title="C3">
+ <col width="1*" title="C4">
+
+ <thead>
+ <tr>
+ <th>Feature</th>
+
+ <th>Cautious</th>
+
+ <th>Medium</th>
+
+ <th>Advanced</th>
+ </tr>
+ </thead>
+
+ <tbody>
+ <tr>
+ <td>Ad-blocking Aggressiveness</td>
+
+ <td>medium</td>
+
+ <td>high</td>
+
+ <td>high</td>
+ </tr>
+
+ <tr>
+ <td>Ad-filtering by size</td>
+
+ <td>no</td>
+
+ <td>yes</td>
+
+ <td>yes</td>
+ </tr>
+
+ <tr>
+ <td>Ad-filtering by link</td>
+
+ <td>no</td>
+
+ <td>no</td>
+
+ <td>yes</td>
+ </tr>
+
+ <tr>
+ <td>Pop-up killing</td>
+
+ <td>blocks only</td>
+
+ <td>blocks only</td>
+
+ <td>blocks only</td>
+ </tr>
+
+ <tr>
+ <td>Privacy Features</td>
+
+ <td>low</td>
+
+ <td>medium</td>
+
+ <td>medium/high</td>
+ </tr>
+
+ <tr>
+ <td>Cookie handling</td>
+
+ <td>none</td>
+
+ <td>session-only</td>
+
+ <td>kill</td>
+ </tr>
+
+ <tr>
+ <td>Referer forging</td>
+
+ <td>no</td>
+
+ <td>yes</td>
+
+ <td>yes</td>
+ </tr>
+
+ <tr>
+ <td>GIF de-animation</td>
+
+ <td>no</td>
+
+ <td>yes</td>
+
+ <td>yes</td>
+ </tr>
+
+ <tr>
+ <td>Fast redirects</td>
+
+ <td>no</td>
+
+ <td>no</td>
+
+ <td>yes</td>
+ </tr>
+
+ <tr>
+ <td>HTML taming</td>
+
+ <td>no</td>
+
+ <td>no</td>
+
+ <td>yes</td>
+ </tr>
+
+ <tr>
+ <td>JavaScript taming</td>
+
+ <td>no</td>
+
+ <td>no</td>
+
+ <td>yes</td>
+ </tr>
+
+ <tr>
+ <td>Web-bug killing</td>
+
+ <td>no</td>
+
+ <td>yes</td>
+
+ <td>yes</td>
+ </tr>
+
+ <tr>
+ <td>Image tag reordering</td>
+
+ <td>no</td>
+
+ <td>yes</td>
+
+ <td>yes</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </li>
+ </ul>
+
+ <p>The list of actions files to be used are defined in the main
+ configuration file, and are processed in the order they are defined (e.g.
+ <tt class="FILENAME">default.action</tt> is typically processed before
+ <tt class="FILENAME">user.action</tt>). The content of these can all be
+ viewed and edited from <a href="http://config.privoxy.org/show-status"
+ target="_top">http://config.privoxy.org/show-status</a>. The over-riding
+ principle when applying actions, is that the last action that matches a
+ given URL wins. The broadest, most general rules go first (defined in
+ <tt class="FILENAME">default.action</tt>), followed by any exceptions
+ (typically also in <tt class="FILENAME">default.action</tt>), which are
+ then followed lastly by any local preferences (typically in <span class=
+ "emphasis"><i class="EMPHASIS">user</i></span><tt class=
+ "FILENAME">.action</tt>). Generally, <tt class=
+ "FILENAME">user.action</tt> has the last word.</p>
+
+ <p>An actions file typically has multiple sections. If you want to use
+ <span class="QUOTE">"aliases"</span> in an actions file, you have to
+ place the (optional) <a href="actions-file.html#ALIASES">alias
+ section</a> at the top of that file. Then comes the default set of rules
+ which will apply universally to all sites and pages (be <span class=
+ "emphasis"><i class="EMPHASIS">very careful</i></span> with using such a
+ universal set in <tt class="FILENAME">user.action</tt> or any other
+ actions file after <tt class="FILENAME">default.action</tt>, because it
+ will override the result from consulting any previous file). And then
+ below that, exceptions to the defined universal policies. You can regard
+ <tt class="FILENAME">user.action</tt> as an appendix to <tt class=
+ "FILENAME">default.action</tt>, with the advantage that it is a separate
+ file, which makes preserving your personal settings across <span class=
+ "APPLICATION">Privoxy</span> upgrades easier.</p>
+
+ <p>Actions can be used to block anything you want, including ads,
+ banners, or just some obnoxious URL whose content you would rather not
+ see. Cookies can be accepted or rejected, or accepted only during the
+ current browser session (i.e. not written to disk), content can be
+ modified, some JavaScripts tamed, user-tracking fooled, and much more.
+ See below for a <a href="actions-file.html#ACTIONS">complete list of
+ actions</a>.</p>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="AEN2876" id="AEN2876">8.1. Finding the Right
+ Mix</a></h2>
+
+ <p>Note that some <a href="actions-file.html#ACTIONS">actions</a>, like
+ cookie suppression or script disabling, may render some sites unusable
+ that rely on these techniques to work properly. Finding the right mix
+ of actions is not always easy and certainly a matter of personal taste.
+ And, things can always change, requiring refinements in the
+ configuration. In general, it can be said that the more <span class=
+ "QUOTE">"aggressive"</span> your default settings (in the top section
+ of the actions file) are, the more exceptions for <span class=
+ "QUOTE">"trusted"</span> sites you will have to make later. If, for
+ example, you want to crunch all cookies per default, you'll have to
+ make exceptions from that rule for sites that you regularly use and
+ that require cookies for actually useful purposes, like maybe your
+ bank, favorite shop, or newspaper.</p>
+
+ <p>We have tried to provide you with reasonable rules to start from in
+ the distribution actions files. But there is no general rule of thumb
+ on these things. There just are too many variables, and sites are
+ constantly changing. Sooner or later you will want to change the rules
+ (and read this chapter again :).</p>
+ </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="AEN2883" id="AEN2883">8.2. How to
+ Edit</a></h2>
+
+ <p>The easiest way to edit the actions files is with a browser by using
+ our browser-based editor, which can be reached from <a href=
+ "http://config.privoxy.org/show-status" target=
+ "_top">http://config.privoxy.org/show-status</a>. Note: the config file
+ option <a href=
+ "config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions</a> must be
+ enabled for this to work. The editor allows both fine-grained control
+ over every single feature on a per-URL basis, and easy choosing from
+ wholesale sets of defaults like <span class="QUOTE">"Cautious"</span>,
+ <span class="QUOTE">"Medium"</span> or <span class=
+ "QUOTE">"Advanced"</span>. Warning: the <span class=
+ "QUOTE">"Advanced"</span> setting is more aggressive, and will be more
+ likely to cause problems for some sites. Experienced users only!</p>
+
+ <p>If you prefer plain text editing to GUIs, you can of course also
+ directly edit the the actions files with your favorite text editor.
+ Look at <tt class="FILENAME">default.action</tt> which is richly
+ commented with many good examples.</p>
+ </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="ACTIONS-APPLY" id="ACTIONS-APPLY">8.3. How
+ Actions are Applied to Requests</a></h2>
+
+ <p>Actions files are divided into sections. There are special sections,
+ like the <span class="QUOTE">"<a href=
+ "actions-file.html#ALIASES">alias</a>"</span> sections which will be
+ discussed later. For now let's concentrate on regular sections: They
+ have a heading line (often split up to multiple lines for readability)
+ which consist of a list of actions, separated by whitespace and
+ enclosed in curly braces. Below that, there is a list of URL and tag
+ patterns, each on a separate line.</p>
+
+ <p>To determine which actions apply to a request, the URL of the
+ request is compared to all URL patterns in each <span class=
+ "QUOTE">"action file"</span>. Every time it matches, the list of
+ applicable actions for the request is incrementally updated, using the
+ heading of the section in which the pattern is located. The same is
+ done again for tags and tag patterns later on.</p>
+
+ <p>If multiple applying sections set the same action differently, the
+ last match wins. If not, the effects are aggregated. E.g. a URL might
+ match a regular section with a heading line of <tt class="LITERAL">{
+ +<a href="actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a>
+ }</tt>, then later another one with just <tt class="LITERAL">{
+ +<a href="actions-file.html#BLOCK">block</a> }</tt>, resulting in
+ <span class="emphasis"><i class="EMPHASIS">both</i></span> actions to
+ apply. And there may well be cases where you will want to combine
+ actions together. Such a section then might look like:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="SCREEN">
+ { +<tt class="LITERAL">handle-as-image</tt> +<tt class=
+"LITERAL">block{Banner ads.}</tt> }
+ # Block these as if they were images. Send no block page.
+ banners.example.com
+ media.example.com/.*banners
+ .example.com/images/ads/
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>You can trace this process for URL patterns and any given URL by
+ visiting <a href="http://config.privoxy.org/show-url-info" target=
+ "_top">http://config.privoxy.org/show-url-info</a>.</p>
+
+ <p>Examples and more detail on this is provided in the Appendix,
+ <a href="appendix.html#ACTIONSANAT">Troubleshooting: Anatomy of an
+ Action</a> section.</p>
+ </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="AF-PATTERNS" id="AF-PATTERNS">8.4.
+ Patterns</a></h2>
+
+ <p>As mentioned, <span class="APPLICATION">Privoxy</span> uses
+ <span class="QUOTE">"patterns"</span> to determine what <span class=
+ "emphasis"><i class="EMPHASIS">actions</i></span> might apply to which
+ sites and pages your browser attempts to access. These <span class=
+ "QUOTE">"patterns"</span> use wild card type <span class=
+ "emphasis"><i class="EMPHASIS">pattern</i></span> matching to achieve a
+ high degree of flexibility. This allows one expression to be expanded
+ and potentially match against many similar patterns.</p>
+
+ <p>Generally, an URL pattern has the form <tt class=
+ "LITERAL"><domain><port>/<path></tt>, where the
+ <tt class="LITERAL"><domain></tt>, the <tt class=
+ "LITERAL"><port></tt> and the <tt class=
+ "LITERAL"><path></tt> are optional. (This is why the special
+ <tt class="LITERAL">/</tt> pattern matches all URLs). Note that the
+ protocol portion of the URL pattern (e.g. <tt class=
+ "LITERAL">http://</tt>) should <span class="emphasis"><i class=
+ "EMPHASIS">not</i></span> be included in the pattern. This is assumed
+ already!</p>
+
+ <p>The pattern matching syntax is different for the domain and path
+ parts of the URL. The domain part uses a simple globbing type matching
+ technique, while the path part uses more flexible <a href=
+ "http://en.wikipedia.org/wiki/Regular_expressions" target=
+ "_top"><span class="QUOTE">"Regular Expressions"</span></a> (POSIX
+ 1003.2).</p>
+
+ <p>The port part of a pattern is a decimal port number preceded by a
+ colon (<tt class="LITERAL">:</tt>). If the domain part contains a
+ numerical IPv6 address, it has to be put into angle brackets
+ (<tt class="LITERAL"><</tt>, <tt class="LITERAL">></tt>).</p>
+
+ <div class="VARIABLELIST">
+ <dl>
+ <dt><tt class="LITERAL">www.example.com/</tt></dt>
+
+ <dd>
+ <p>is a domain-only pattern and will match any request to
+ <tt class="LITERAL">www.example.com</tt>, regardless of which
+ document on that server is requested. So ALL pages in this domain
+ would be covered by the scope of this action. Note that a simple
+ <tt class="LITERAL">example.com</tt> is different and would NOT
+ match.</p>
+ </dd>
+
+ <dt><tt class="LITERAL">www.example.com</tt></dt>
+
+ <dd>
+ <p>means exactly the same. For domain-only patterns, the trailing
+ <tt class="LITERAL">/</tt> may be omitted.</p>
+ </dd>
+
+ <dt><tt class="LITERAL">www.example.com/index.html</tt></dt>
+
+ <dd>
+ <p>matches all the documents on <tt class=
+ "LITERAL">www.example.com</tt> whose name starts with <tt class=
+ "LITERAL">/index.html</tt>.</p>
+ </dd>
+
+ <dt><tt class="LITERAL">www.example.com/index.html$</tt></dt>
+
+ <dd>
+ <p>matches only the single document <tt class=
+ "LITERAL">/index.html</tt> on <tt class=
+ "LITERAL">www.example.com</tt>.</p>
+ </dd>
+
+ <dt><tt class="LITERAL">/index.html$</tt></dt>
+
+ <dd>
+ <p>matches the document <tt class="LITERAL">/index.html</tt>,
+ regardless of the domain, i.e. on <span class=
+ "emphasis"><i class="EMPHASIS">any</i></span> web server
+ anywhere.</p>
+ </dd>
+
+ <dt><tt class="LITERAL">/</tt></dt>
+
+ <dd>
+ <p>Matches any URL because there's no requirement for either the
+ domain or the path to match anything.</p>
+ </dd>
+
+ <dt><tt class="LITERAL">:8000/</tt></dt>
+
+ <dd>
+ <p>Matches any URL pointing to TCP port 8000.</p>
+ </dd>
+
+ <dt><tt class="LITERAL"><2001:db8::1>/</tt></dt>
+
+ <dd>
+ <p>Matches any URL with the host address <tt class=
+ "LITERAL">2001:db8::1</tt>. (Note that the real URL uses plain
+ brackets, not angle brackets.)</p>
+ </dd>
+
+ <dt><tt class="LITERAL">index.html</tt></dt>
+
+ <dd>
+ <p>matches nothing, since it would be interpreted as a domain
+ name and there is no top-level domain called <tt class=
+ "LITERAL">.html</tt>. So its a mistake.</p>
+ </dd>
+ </dl>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="AEN2995" id="AEN2995">8.4.1. The Domain
+ Pattern</a></h3>
+
+ <p>The matching of the domain part offers some flexible options: if
+ the domain starts or ends with a dot, it becomes unanchored at that
+ end. For example:</p>
+
+ <div class="VARIABLELIST">
+ <dl>
+ <dt><tt class="LITERAL">.example.com</tt></dt>
+
+ <dd>
+ <p>matches any domain with first-level domain <tt class=
+ "LITERAL">com</tt> and second-level domain <tt class=
+ "LITERAL">example</tt>. For example <tt class=
+ "LITERAL">www.example.com</tt>, <tt class=
+ "LITERAL">example.com</tt> and <tt class=
+ "LITERAL">foo.bar.baz.example.com</tt>. Note that it wouldn't
+ match if the second-level domain was <tt class=
+ "LITERAL">another-example</tt>.</p>
+ </dd>
+
+ <dt><tt class="LITERAL">www.</tt></dt>
+
+ <dd>
+ <p>matches any domain that <span class="emphasis"><i class=
+ "EMPHASIS">STARTS</i></span> with <tt class="LITERAL">www.</tt>
+ (It also matches the domain <tt class="LITERAL">www</tt> but
+ most of the time that doesn't matter.)</p>
+ </dd>
+
+ <dt><tt class="LITERAL">.example.</tt></dt>
+
+ <dd>
+ <p>matches any domain that <span class="emphasis"><i class=
+ "EMPHASIS">CONTAINS</i></span> <tt class=
+ "LITERAL">.example.</tt>. And, by the way, also included would
+ be any files or documents that exist within that domain since
+ no path limitations are specified. (Correctly speaking: It
+ matches any FQDN that contains <tt class="LITERAL">example</tt>
+ as a domain.) This might be <tt class=
+ "LITERAL">www.example.com</tt>, <tt class=
+ "LITERAL">news.example.de</tt>, or <tt class=
+ "LITERAL">www.example.net/cgi/testing.pl</tt> for instance. All
+ these cases are matched.</p>
+ </dd>
+ </dl>
+ </div>
+
+ <p>Additionally, there are wild-cards that you can use in the domain
+ names themselves. These work similarly to shell globbing type
+ wild-cards: <span class="QUOTE">"*"</span> represents zero or more
+ arbitrary characters (this is equivalent to the <a href=
+ "http://en.wikipedia.org/wiki/Regular_expressions" target=
+ "_top"><span class="QUOTE">"Regular Expression"</span></a> based
+ syntax of <span class="QUOTE">".*"</span>), <span class=
+ "QUOTE">"?"</span> represents any single character (this is
+ equivalent to the regular expression syntax of a simple <span class=
+ "QUOTE">"."</span>), and you can define <span class=
+ "QUOTE">"character classes"</span> in square brackets which is
+ similar to the same regular expression technique. All of this can be
+ freely mixed:</p>
+
+ <div class="VARIABLELIST">
+ <dl>
+ <dt><tt class="LITERAL">ad*.example.com</tt></dt>
+
+ <dd>
+ <p>matches <span class="QUOTE">"adserver.example.com"</span>,
+ <span class="QUOTE">"ads.example.com"</span>, etc but not
+ <span class="QUOTE">"sfads.example.com"</span></p>
+ </dd>
+
+ <dt><tt class="LITERAL">*ad*.example.com</tt></dt>
+
+ <dd>
+ <p>matches all of the above, and then some.</p>
+ </dd>
+
+ <dt><tt class="LITERAL">.?pix.com</tt></dt>
+
+ <dd>
+ <p>matches <tt class="LITERAL">www.ipix.com</tt>, <tt class=
+ "LITERAL">pictures.epix.com</tt>, <tt class=
+ "LITERAL">a.b.c.d.e.upix.com</tt> etc.</p>
+ </dd>
+
+ <dt><tt class="LITERAL">www[1-9a-ez].example.c*</tt></dt>
+
+ <dd>
+ <p>matches <tt class="LITERAL">www1.example.com</tt>,
+ <tt class="LITERAL">www4.example.cc</tt>, <tt class=
+ "LITERAL">wwwd.example.cy</tt>, <tt class=
+ "LITERAL">wwwz.example.com</tt> etc., but <span class=
+ "emphasis"><i class="EMPHASIS">not</i></span> <tt class=
+ "LITERAL">wwww.example.com</tt>.</p>
+ </dd>
+ </dl>
+ </div>
+
+ <p>While flexible, this is not the sophistication of full regular
+ expression based syntax.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="AEN3071" id="AEN3071">8.4.2. The Path
+ Pattern</a></h3>
+
+ <p><span class="APPLICATION">Privoxy</span> uses <span class=
+ "QUOTE">"modern"</span> POSIX 1003.2 <a href=
+ "http://en.wikipedia.org/wiki/Regular_expressions" target=
+ "_top"><span class="QUOTE">"Regular Expressions"</span></a> for
+ matching the path portion (after the slash), and is thus more
+ flexible.</p>
+
+ <p>There is an <a href="appendix.html#REGEX">Appendix</a> with a
+ brief quick-start into regular expressions, you also might want to
+ have a look at your operating system's documentation on regular
+ expressions (try <tt class="LITERAL">man re_format</tt>).</p>
+
+ <p>Note that the path pattern is automatically left-anchored at the
+ <span class="QUOTE">"/"</span>, i.e. it matches as if it would start
+ with a <span class="QUOTE">"^"</span> (regular expression speak for
+ the beginning of a line).</p>
+
+ <p>Please also note that matching in the path is <span class=
+ "emphasis"><i class="EMPHASIS">CASE INSENSITIVE</i></span> by
+ default, but you can switch to case sensitive at any point in the
+ pattern by using the <span class="QUOTE">"(?-i)"</span> switch:
+ <tt class="LITERAL">www.example.com/(?-i)PaTtErN.*</tt> will match
+ only documents whose path starts with <tt class=
+ "LITERAL">PaTtErN</tt> in <span class="emphasis"><i class=
+ "EMPHASIS">exactly</i></span> this capitalization.</p>
+
+ <div class="VARIABLELIST">
+ <dl>
+ <dt><tt class="LITERAL">.example.com/.*</tt></dt>
+
+ <dd>
+ <p>Is equivalent to just <span class=
+ "QUOTE">".example.com"</span>, since any documents within that
+ domain are matched with or without the <span class=
+ "QUOTE">".*"</span> regular expression. This is redundant</p>
+ </dd>
+
+ <dt><tt class="LITERAL">.example.com/.*/index.html$</tt></dt>
+
+ <dd>
+ <p>Will match any page in the domain of <span class=
+ "QUOTE">"example.com"</span> that is named <span class=
+ "QUOTE">"index.html"</span>, and that is part of some path. For
+ example, it matches <span class=
+ "QUOTE">"www.example.com/testing/index.html"</span> but NOT
+ <span class="QUOTE">"www.example.com/index.html"</span> because
+ the regular expression called for at least two <span class=
+ "QUOTE">"/'s"</span>, thus the path requirement. It also would
+ match <span class=
+ "QUOTE">"www.example.com/testing/index_html"</span>, because of
+ the special meta-character <span class="QUOTE">"."</span>.</p>
+ </dd>
+
+ <dt><tt class="LITERAL">.example.com/(.*/)?index\.html$</tt></dt>
+
+ <dd>
+ <p>This regular expression is conditional so it will match any
+ page named <span class="QUOTE">"index.html"</span> regardless
+ of path which in this case can have one or more <span class=
+ "QUOTE">"/'s"</span>. And this one must contain exactly
+ <span class="QUOTE">".html"</span> (but does not have to end
+ with that!).</p>
+ </dd>
+
+ <dt><tt class=
+ "LITERAL">.example.com/(.*/)(ads|banners?|junk)</tt></dt>
+
+ <dd>
+ <p>This regular expression will match any path of <span class=
+ "QUOTE">"example.com"</span> that contains any of the words
+ <span class="QUOTE">"ads"</span>, <span class=
+ "QUOTE">"banner"</span>, <span class="QUOTE">"banners"</span>
+ (because of the <span class="QUOTE">"?"</span>) or <span class=
+ "QUOTE">"junk"</span>. The path does not have to end in these
+ words, just contain them.</p>
+ </dd>
+
+ <dt><tt class=
+ "LITERAL">.example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$</tt></dt>
+
+ <dd>
+ <p>This is very much the same as above, except now it must end
+ in either <span class="QUOTE">".jpg"</span>, <span class=
+ "QUOTE">".jpeg"</span>, <span class="QUOTE">".gif"</span> or
+ <span class="QUOTE">".png"</span>. So this one is limited to
+ common image formats.</p>
+ </dd>
+ </dl>
+ </div>
+
+ <p>There are many, many good examples to be found in <tt class=
+ "FILENAME">default.action</tt>, and more tutorials below in <a href=
+ "appendix.html#REGEX">Appendix on regular expressions</a>.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="TAG-PATTERN" id="TAG-PATTERN">8.4.3. The
+ Tag Pattern</a></h3>
+
+ <p>Tag patterns are used to change the applying actions based on the
+ request's tags. Tags can be created with either the <a href=
+ "actions-file.html#CLIENT-HEADER-TAGGER">client-header-tagger</a> or
+ the <a href=
+ "actions-file.html#SERVER-HEADER-TAGGER">server-header-tagger</a>
+ action.</p>
+
+ <p>Tag patterns have to start with <span class="QUOTE">"TAG:"</span>,
+ so <span class="APPLICATION">Privoxy</span> can tell them apart from
+ URL patterns. Everything after the colon including white space, is
+ interpreted as a regular expression with path pattern syntax, except
+ that tag patterns aren't left-anchored automatically (<span class=
+ "APPLICATION">Privoxy</span> doesn't silently add a <span class=
+ "QUOTE">"^"</span>, you have to do it yourself if you need it).</p>
+
+ <p>To match all requests that are tagged with <span class=
+ "QUOTE">"foo"</span> your pattern line should be <span class=
+ "QUOTE">"TAG:^foo$"</span>, <span class="QUOTE">"TAG:foo"</span>
+ would work as well, but it would also match requests whose tags
+ contain <span class="QUOTE">"foo"</span> somewhere. <span class=
+ "QUOTE">"TAG: foo"</span> wouldn't work as it requires white
+ space.</p>
+
+ <p>Sections can contain URL and tag patterns at the same time, but
+ tag patterns are checked after the URL patterns and thus always
+ overrule them, even if they are located before the URL patterns.</p>
+
+ <p>Once a new tag is added, Privoxy checks right away if it's matched
+ by one of the tag patterns and updates the action settings
+ accordingly. As a result tags can be used to activate other tagger
+ actions, as long as these other taggers look for headers that haven't
+ already be parsed.</p>
+
+ <p>For example you could tag client requests which use the <tt class=
+ "LITERAL">POST</tt> method, then use this tag to activate another
+ tagger that adds a tag if cookies are sent, and then use a block
+ action based on the cookie tag. This allows the outcome of one
+ action, to be input into a subsequent action. However if you'd
+ reverse the position of the described taggers, and activated the
+ method tagger based on the cookie tagger, no method tags would be
+ created. The method tagger would look for the request line, but at
+ the time the cookie tag is created, the request line has already been
+ parsed.</p>
+
+ <p>While this is a limitation you should be aware of, this kind of
+ indirection is seldom needed anyway and even the example doesn't make
+ too much sense.</p>
+ </div>
+ </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="ACTIONS" id="ACTIONS">8.5. Actions</a></h2>
+
+ <p>All actions are disabled by default, until they are explicitly
+ enabled somewhere in an actions file. Actions are turned on if preceded
+ with a <span class="QUOTE">"+"</span>, and turned off if preceded with
+ a <span class="QUOTE">"-"</span>. So a <tt class="LITERAL">+action</tt>
+ means <span class="QUOTE">"do that action"</span>, e.g. <tt class=
+ "LITERAL">+block</tt> means <span class="QUOTE">"please block URLs that
+ match the following patterns"</span>, and <tt class=
+ "LITERAL">-block</tt> means <span class="QUOTE">"don't block URLs that
+ match the following patterns, even if <tt class="LITERAL">+block</tt>
+ previously applied."</span></p>
+
+ <p>Again, actions are invoked by placing them on a line, enclosed in
+ curly braces and separated by whitespace, like in <tt class=
+ "LITERAL">{+some-action -some-other-action{some-parameter}}</tt>,
+ followed by a list of URL patterns, one per line, to which they apply.
+ Together, the actions line and the following pattern lines make up a
+ section of the actions file.</p>
+
+ <p>Actions fall into three categories:</p>
+
+ <ul>
+ <li>
+ <p>Boolean, i.e the action can only be <span class=
+ "QUOTE">"enabled"</span> or <span class="QUOTE">"disabled"</span>.
+ Syntax:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="SCREEN">
+ +<tt class="REPLACEABLE"><i>name</i></tt> # enable action <tt class=
+"REPLACEABLE"><i>name</i></tt>
+ -<tt class=
+"REPLACEABLE"><i>name</i></tt> # disable action <tt class="REPLACEABLE"><i>name</i></tt>
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Example: <tt class="LITERAL">+handle-as-image</tt></p>
+ </li>
+
+ <li>
+ <p>Parameterized, where some value is required in order to enable
+ this type of action. Syntax:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="SCREEN">
+ +<tt class="REPLACEABLE"><i>name</i></tt>{<tt class=
+"REPLACEABLE"><i>param</i></tt>} # enable action and set parameter to <tt class="REPLACEABLE"><i>param</i></tt>,