7 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
10 TITLE="Privoxy User Manual"
11 HREF="index.html"><LINK
13 TITLE="The Main Configuration File"
14 HREF="config.html"><LINK
16 TITLE="The Filter File"
17 HREF="filter-file.html"><LINK
20 HREF="../p_doc.css"></HEAD
39 >Privoxy User Manual</TH
60 HREF="filter-file.html"
77 > The actions files are used to define what actions
81 > takes for which URLs, and thus determines
82 how ad images, cookies and various other aspects of HTTP content and
83 transactions are handled, and on which sites (or even parts thereof). There
84 are three such files included with <SPAN
88 with slightly different purposes. <TT
92 the default policies. <TT
99 > and the web based editor to set
100 pre-defined values (and normally should not be edited). Local exceptions
104 >. The content of these
105 can all be viewed and edited from <A
106 HREF="http://config.privoxy.org/show-status"
108 >http://config.privoxy.org/show-status</A
113 Anything you want can be blocked, including ads, banners, or just some obnoxious
114 URL that you would rather not see is done here. Cookies can be accepted or rejected, or
115 accepted only during the current browser session (i.e. not written to disk),
116 content can be modified, JavaScripts tamed, user-tracking fooled, and much more.
117 See below for a complete list of available actions.</P
119 > An actions file typically has sections. Near the top, <SPAN
123 optionally defined (discussed <A
124 HREF="actions-file.html#ALIASES"
127 >), then the default set of rules
128 which will apply universally to all sites and pages. And then below that,
129 exceptions to the defined universal policies. </P
136 >9.1. Finding the Right Mix</A
140 HREF="actions-file.html#ACTIONS"
142 >, like cookie suppression
143 or script disabling, may render some sites unusable that rely on these
144 techniques to work properly. Finding the right mix of actions is not always easy and
145 certainly a matter of personal taste. In general, it can be said that the more
149 > your default settings (in the top section of the
150 actions file) are, the more exceptions for <SPAN
154 will have to make later. If, for example, you want to kill popup windows per
155 default, you'll have to make exceptions from that rule for sites that you
156 regularly use and that require popups for actually useful content, like maybe
157 your bank, favorite shop, or newspaper.</P
159 > We have tried to provide you with reasonable rules to start from in the
160 distribution actions files. But there is no general rule of thumb on these
161 things. There just are too many variables, and sites are constantly changing.
162 Sooner or later you will want to change the rules (and read this chapter again :).</P
173 > The easiest way to edit the <SPAN
176 > files is with a browser by
177 using our browser-based editor, which can be reached from <A
178 HREF="http://config.privoxy.org/show-status"
180 >http://config.privoxy.org/show-status</A
183 > If you prefer plain text editing to GUIs, you can of course also directly edit the
184 the actions files.</P
192 >9.3. How Actions are Applied to URLs</A
195 > Actions files are divided into sections. There are special sections,
199 HREF="actions-file.html#ALIASES"
202 > sections which will be discussed later. For now
203 let's concentrate on regular sections: They have a heading line (often split
204 up to multiple lines for readability) which consist of a list of actions,
205 separated by whitespace and enclosed in curly braces. Below that, there
206 is a list of URL patterns, each on a separate line.</P
208 > To determine which actions apply to a request, the URL of the request is
209 compared to all patterns in this file. Every time it matches, the list of
210 applicable actions for the URL is incrementally updated, using the heading
211 of the section in which the pattern is located. If multiple matches for
212 the same URL set the same action differently, the last match wins. If not,
213 the effects are aggregated (e.g. a URL might match both the
215 HREF="actions-file.html#HANDLE-AS-IMAGE"
219 >"+handle-as-image"</SPAN
223 HREF="actions-file.html#BLOCK"
232 > You can trace this process by visiting <A
233 HREF="http://config.privoxy.org/show-url-info"
235 >http://config.privoxy.org/show-url-info</A
238 > More detail on this is provided in the Appendix, <A
239 HREF="appendix.html#ACTIONSANAT"
240 > Anatomy of an Action</A
252 > Generally, a pattern has the form <TT
254 ><domain>/<path></TT
258 ><domain></TT
263 are optional. (This is why the pattern <TT
266 > matches all URLs).</P
275 >www.example.com/</TT
279 > is a domain-only pattern and will match any request to <TT
283 regardless of which document on that server is requested.
293 > means exactly the same. For domain-only patterns, the trailing <TT
303 >www.example.com/index.html</TT
307 > matches only the single document <TT
324 > matches the document <TT
327 >, regardless of the domain,
341 > matches nothing, since it would be interpreted as a domain name and
342 there is no top-level domain called <TT
356 >9.4.1. The Domain Pattern</A
359 > The matching of the domain part offers some flexible options: if the
360 domain starts or ends with a dot, it becomes unanchored at that end.
374 > matches any domain that <I
391 > matches any domain that <I
408 > matches any domain that <I
415 (Correctly speaking: It matches any FQDN that contains <TT
424 > Additionally, there are wild-cards that you can use in the domain names
425 themselves. They work pretty similar to shell wild-cards: <SPAN
429 stands for zero or more arbitrary characters, <SPAN
433 any single character, you can define character classes in square
434 brackets and all of that can be freely mixed:</P
449 >"adserver.example.com"</SPAN
453 >"ads.example.com"</SPAN
456 >"sfads.example.com"</SPAN
463 >*ad*.example.com</TT
467 > matches all of the above, and then some.
483 >pictures.epix.com</TT
486 >a.b.c.d.e.upix.com</TT
493 >www[1-9a-ez].example.c*</TT
499 >www1.example.com</TT
510 >wwwz.example.com</TT
517 >wwww.example.com</TT
530 >9.4.2. The Path Pattern</A
536 > uses Perl compatible regular expressions
538 HREF="http://www.pcre.org/"
542 matching the path.</P
545 HREF="appendix.html#REGEX"
547 > with a brief quick-start into regular
548 expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
550 HREF="http://www.pcre.org/man.txt"
552 >http://www.pcre.org/man.txt</A
554 You might also find the Perl man page on regular expressions (<TT
558 useful, which is available on-line at <A
559 HREF="http://www.perldoc.com/perl5.6/pod/perlre.html"
561 >http://www.perldoc.com/perl5.6/pod/perlre.html</A
564 > Note that the path pattern is automatically left-anchored at the <SPAN
568 i.e. it matches as if it would start with a <SPAN
571 > (regular expression speak
572 for the beginning of a line).</P
574 > Please also note that matching in the path is case
578 > by default, but you can switch to case
579 sensitive at any point in the pattern by using the
586 >www.example.com/(?-i)PaTtErN.*</TT
588 documents whose path starts with <TT
595 > this capitalization.</P
607 > All actions are disabled by default, until they are explicitly enabled
608 somewhere in an actions file. Actions are turned on if preceded with a
612 >, and turned off if preceded with a <SPAN
621 >"do that action"</SPAN
628 >"block the following URL
633 Actions are invoked by enclosing the action name in curly braces (e.g.
634 {+some_action}), followed by a list of URLs (or patterns that match URLs) to
635 which the action applies. There are three classes of actions: </P
643 Boolean, i.e the action can only be <SPAN
656 CLASS="LITERALLAYOUT"
660 > # enable this action<br>
664 > # disable this action<br>
665 </P
674 Parameterized, e.g. <SPAN
676 >"+/-hide-user-agent{ Mozilla 1.0 }"</SPAN
678 where some value is required in order to enable this type of action.
685 CLASS="LITERALLAYOUT"
689 > # enable action and set parameter to <SPAN
696 > # disable action (<SPAN
699 >) can be omitted<br>
700 </P
710 Multi-value, e.g. <SPAN
712 >"{+/-add-header{Name: value}}"</SPAN
716 >"{+/-send-wafer{name=value}}"</SPAN
717 >), where some value needs to be defined
718 in addition to simply enabling the action. Examples:
724 CLASS="LITERALLAYOUT"
727 >{+name{param=value}}</I
728 > # enable action and set <SPAN
737 >{-name{param=value}}</I
738 > # remove the parameter <SPAN
741 > completely<br>
745 > # disable this action totally and remove <SPAN
749 </P
758 > If nothing is specified in any actions file, no <SPAN
762 taken. So in this case <SPAN
766 normal, non-blocking, non-anonymizing proxy. You must specifically enable the
767 privacy and blocking features you need (although the provided default actions
768 files will give a good starting point).</P
770 > Later defined actions always over-ride earlier ones. So exceptions
771 to any rules you make, should come in the latter part of the file (or
772 in a file that is processed later when using multiple actions files). For
773 multi-valued actions, the actions are applied in the order they are specified.
774 Actions files are processed in the order they are defined in
778 > (the default installation has three actions
779 files). It also quite possible for any given URL pattern to match more than
782 > The list of valid <SPAN
815 > Send a user defined HTTP header to the web server.
819 >Possible values:</DT
822 > Any value is possible. Validity of the defined HTTP headers is not checked.
829 CLASS="LITERALLAYOUT"
830 > <I
832 >{+add-header{X-User-Tracking: sucks}}</I
834 <I
838 </P
844 > This action may be specified multiple times, in order to define multiple
845 headers. This is rarely needed for the typical user. If you don't know what
848 >"HTTP headers"</SPAN
849 > are, you definitely don't need to worry about this
882 > Used to block a URL from reaching your browser. The URL may be
883 anything, but is typically used to block ads or other obnoxious
888 >Possible values:</DT
897 CLASS="LITERALLAYOUT"
898 > <I
902 <I
904 >.banners.example.com</I
906 <I
910 </P
916 > If a URL matches one of the blocked patterns, <SPAN
920 will intercept the URL and display its special <SPAN
924 instead. If there is sufficient space, a large red banner will appear with
925 a friendly message about why the page was blocked, and a way to go there
926 anyway. If there is insufficient space a smaller <SPAN
930 page will appear without the red banner.
932 HREF="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"
936 to view the default blocked HTML page (<SPAN
940 for this to work as intended!).
944 A very important exception is if the URL <I
952 HREF="actions-file.html#HANDLE-AS-IMAGE"
956 >"+handle-as-image"</SPAN
959 then it will be handled by
961 HREF="actions-file.html#SET-IMAGE-BLOCKER"
965 >"+set-image-blocker"</SPAN
968 (see below). It is important to understand this process, in order
969 to understand how <SPAN
972 > is able to deal with
973 ads and other objectionable content.
977 HREF="actions-file.html#FILTER"
984 action can also perform some of the
985 same functionality as <SPAN
988 >, but by virtue of very
989 different programming techniques, and is most often used for different
1001 NAME="DEANIMATE-GIFS"
1010 CLASS="VARIABLELIST"
1022 > To stop those annoying, distracting animated GIF images.
1026 >Possible values:</DT
1042 CLASS="LITERALLAYOUT"
1043 > <I
1045 >{+deanimate-gifs{last}}</I
1047 <I
1051 </P
1057 > De-animate all animated GIF images, i.e. reduce them to their last frame.
1058 This will also shrink the images considerably (in bytes, not pixels!). If
1062 > is given, the first frame of the animation
1063 is used as the replacement. If <SPAN
1066 > is given, the last
1067 frame of the animation is used instead, which probably makes more sense for
1068 most banner animations, but also has the risk of not showing the entire
1069 last frame (if it is only a delta to an earlier frame).
1080 NAME="DOWNGRADE-HTTP-VERSION"
1083 >+downgrade-http-version</I
1089 CLASS="VARIABLELIST"
1103 >"+downgrade-http-version"</SPAN
1104 > will downgrade HTTP/1.1 client requests to
1105 HTTP/1.0 and downgrade the responses as well.
1109 >Possible values:</DT
1119 CLASS="LITERALLAYOUT"
1120 > <I
1122 >{+downgrade-http-version}</I
1124 <I
1128 </P
1134 > Use this action for servers that use HTTP/1.1 protocol features that
1138 > doesn't handle well yet. HTTP/1.1 is
1139 only partially implemented. Default is not to downgrade requests. This is
1140 an infrequently needed action, and is used to help with rare problem sites only.
1151 NAME="FAST-REDIRECTS"
1160 CLASS="VARIABLELIST"
1174 >"+fast-redirects"</SPAN
1175 > action enables interception of
1179 > requests from one server to another, which
1180 are used to track users.<SPAN
1184 all but the last valid URL in a redirect request and send a local redirect
1185 back to your browser without contacting the intermediate site(s).
1189 >Possible values:</DT
1199 CLASS="LITERALLAYOUT"
1200 > <I
1202 >{+fast-redirects}</I
1204 <I
1208 </P
1215 Many sites, like yahoo.com, don't just link to other sites. Instead, they
1216 will link to some script on their own server, giving the destination as a
1217 parameter, which will then redirect you to the final target. URLs
1218 resulting from this scheme typically look like:
1221 >http://some.place/some_script?http://some.where-else</I
1225 > Sometimes, there are even multiple consecutive redirects encoded in the
1226 URL. These redirections via scripts make your web browsing more traceable,
1227 since the server from which you follow such a link can see where you go
1228 to. Apart from that, valuable bandwidth and time is wasted, while your
1229 browser ask the server for one redirect after the other. Plus, it feeds
1233 > This is a normally <SPAN
1236 > feature, and often requires exceptions
1237 for sites that are sensitive to defeating this mechanism.
1257 CLASS="VARIABLELIST"
1269 > Apply page filtering as defined by named sections of the
1273 > file to the specified site(s).
1277 > can be any modification of the raw
1278 page content, including re-writing or deletion of content.
1282 >Possible values:</DT
1288 > must include the name of one of the section identifiers
1296 > is specified in <TT
1303 >Example usage (from the current <TT
1316 NAME="FILTER-HTML-ANNOYANCES"
1321 >+filter{html-annoyances}</I
1322 >: Get rid of particularly annoying HTML abuse.
1337 NAME="FILTER-JS-ANNOYANCES"
1342 >+filter{js-annoyances}</I
1343 >: Get rid of particularly annoying JavaScript abuse
1358 NAME="FILTER-CONTENT-COOKIES"
1363 >+filter{content-cookies}</I
1364 >: Kill cookies that come in the HTML or JS content
1379 NAME="FILTER-POPUPS"
1385 >: Kill all popups in JS and HTML
1400 NAME="FILTER-FRAMESET-BORDERS"
1405 >+filter{frameset-borders}</I
1406 >: Give frames a border and make them resizable
1421 NAME="FILTER-WEBBUGS"
1426 >+filter{webbugs}</I
1427 >: Squish WebBugs (1x1 invisible GIFs used for user tracking)
1442 NAME="FILTER-REFRESH-TAGS"
1447 >+filter{refresh-tags}</I
1448 >: Kill automatic refresh tags (for dial-on-demand setups)
1469 >: Text replacements for subversive browsing fun!
1490 >: Remove Nimda (virus) code.
1505 NAME="FILTER-BANNERS-BY-SIZE"
1510 >+filter{banners-by-size}</I
1511 >: Kill banners by size (<I
1529 NAME="FILTER-SHOCKWAVE-FLASH"
1534 >+filter{shockwave-flash}</I
1535 >: Kill embedded Shockwave Flash objects
1550 NAME="FILTER-CRUDE-PARENTAL"
1555 >+filter{crude-parental}</I
1556 >: Kill all web pages that contain the words "sex" or "warez"
1568 > This is potentially a very powerful feature! And requires a knowledge
1569 of regular expressions if you want to <SPAN
1571 >"roll your own"</SPAN
1573 Filtering operates on a line by line basis throughout the entire page.
1576 > Filtering requires buffering the page content, which may appear to
1577 slow down page rendering since nothing is displayed until all content has
1578 passed the filters. (It does not really take longer, but seems that way
1579 since the page is not incrementally displayed.) This effect will be more
1580 noticeable on slower connections.
1583 > Filtering can achieve some of the effects as the
1585 HREF="actions-file#BLOCK"
1592 action, i.e. it can be used to block ads and banners. In the overall
1593 scheme of things, filtering is one of the first things <SPAN
1597 does with a web page. So other most other actions are applied to the
1612 NAME="HIDE-FORWARDED-FOR-HEADERS"
1615 >+hide-forwarded-for-headers</I
1621 CLASS="VARIABLELIST"
1633 > Block any existing X-Forwarded-for HTTP header, and do not add a new one.
1637 >Possible values:</DT
1647 CLASS="LITERALLAYOUT"
1648 > <I
1650 >{+hide-forwarded-for-headers}</I
1652 <I
1656 </P
1662 > It is fairly safe to leave this on. It does not seem to break many sites.
1673 NAME="HIDE-FROM-HEADER"
1676 >+hide-from-header</I
1682 CLASS="VARIABLELIST"
1694 > To block the browser from sending your email address in a <SPAN
1702 >Possible values:</DT
1708 >, or any user defined value.
1715 CLASS="LITERALLAYOUT"
1716 > <I
1718 >{+hide-from-header{block}}</I
1720 <I
1724 </P
1733 > will completely remove the header
1734 (not to be confused with the <A
1735 HREF="actions-file.html#BLOCK"
1742 Alternately, you can specify any value you prefer to send to the web
1761 NAME="HIDE-REFERRER"
1766 CLASS="VARIABLELIST"
1778 > Don't send the <SPAN
1781 > (sic) HTTP header to the web site.
1782 Or, alternately send a forged header instead.
1786 >Possible values:</DT
1789 > Prevent the header from being sent with the keyword, <SPAN
1796 > a URL to one from the same server as the request.
1797 Or, set to user defined value of your choice.
1804 CLASS="LITERALLAYOUT"
1805 > <I
1807 >{+hide-referer{forge}}</I
1809 <I
1813 </P
1822 > is the preferred option here, since some servers will
1823 not send images back otherwise.
1829 >"+hide-referrer"</SPAN
1830 > is an alternate spelling of
1833 >"+hide-referer"</SPAN
1834 >. It has the exact same parameters, and can be freely
1837 >"+hide-referer"</SPAN
1842 correct English spelling, however the HTTP specification has a bug - it
1843 requires it to be spelled as <SPAN
1857 NAME="HIDE-USER-AGENT"
1860 >+hide-user-agent</I
1866 CLASS="VARIABLELIST"
1878 > To change the <SPAN
1880 >"User-Agent:"</SPAN
1881 > header so web servers can't tell
1882 your browser type. Who's business is it anyway?
1886 >Possible values:</DT
1889 > Any user defined string.
1896 CLASS="LITERALLAYOUT"
1897 > <I
1899 >{+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}}</I
1901 <I
1905 </P
1911 > Warning! This breaks many web sites that depend on this in order
1912 to determine how the target browser will respond to various
1913 requests. Use with caution.
1924 NAME="HANDLE-AS-IMAGE"
1927 >+handle-as-image</I
1933 CLASS="VARIABLELIST"
1945 > To define what <SPAN
1949 automatically as an image, and is an important ingredient of how
1954 >Possible values:</DT
1964 CLASS="LITERALLAYOUT"
1965 > <I
1967 >{+handle-as-image}</I
1969 <I
1971 >/.*\.(gif|jpg|jpeg|png|bmp|ico)</I
1973 </P
1979 > This only has meaning if the URL (or pattern) also is
1983 >ed, in which case a user definable image can
1984 be sent rather than a HTML page. This is integral to the whole concept of
1985 ad blocking: the URL must match <I
1989 HREF="actions-file.html#BLOCK"
2001 >"+handle-as-image"</SPAN
2004 HREF="actions-file.html#SET-IMAGE-BLOCKER"
2008 >"+set-image-blocker"</SPAN
2011 below for control over what will actually be displayed by the browser.)
2014 > There is little reason to change the default definition for this action.
2025 NAME="SET-IMAGE-BLOCKER"
2028 >+set-image-blocker</I
2034 CLASS="VARIABLELIST"
2046 > Decide what to do with URLs that end up tagged with <I
2051 HREF="actions-file.html#BLOCK"
2059 HREF="actions-file.html#HANDLE-AS-IMAGE"
2063 >"+handle-as-image"</SPAN
2066 e.g an advertisement.
2070 >Possible values:</DT
2073 > There are four available options: <SPAN
2075 >"-set-image-blocker"</SPAN
2080 > page, usually resulting in a <SPAN
2087 >"+set-image-blocker{<I
2092 1x1 transparent GIF image.
2095 >"+set-image-blocker{<I
2100 checkerboard type pattern (the default). And finally,
2103 >"+set-image-blocker{<I
2108 send a HTTP temporary redirect to the specified image. This has the
2109 advantage of the icon being being cached by the browser, which will speed
2117 CLASS="LITERALLAYOUT"
2118 > <I
2120 >{+set-image-blocker{blank}}</I
2122 <I
2126 </P
2135 > ads, they need to meet
2136 criteria as matching both <I
2143 actions. And then, <SPAN
2145 >"image-blocker"</SPAN
2150 > for invisibility. Note you cannot treat HTML pages as
2151 images in most cases. For instance, frames require an HTML page to
2152 display. So a frame that is an ad, typically cannot be treated as an image.
2156 > in this situation just will not work
2168 NAME="LIMIT-CONNECT"
2177 CLASS="VARIABLELIST"
2192 > only allows HTTP CONNECT
2193 requests to port 443 (the standard, secure HTTPS port). Use
2196 >"+limit-connect"</SPAN
2197 > to disable this altogether, or to allow
2202 >Possible values:</DT
2205 > Any valid port number, or port number range.
2209 >Example usages:</DT
2212 CLASS="LITERALLAYOUT"
2213 > <I
2215 >+limit-connect{443}</I
2216 > # This is the default and need not be specified.<br>
2217 <I
2219 >+limit-connect{80,443}</I
2220 > # Ports 80 and 443 are OK.<br>
2221 <I
2223 >+limit-connect{-3, 7, 20-100, 500-}</I
2224 > # Port less than 3, 7, 20 to 100 and above 500 are OK.<br>
2225 </P
2231 > The CONNECT methods exists in HTTP to allow access to secure websites
2232 (https:// URLs) through proxies. It works very simply: the proxy connects
2233 to the server on the specified port, and then short-circuits its
2234 connections to the client <I
2237 > to the remote proxy.
2238 This can be a big security hole, since CONNECT-enabled proxies can be
2239 abused as TCP relays very easily.
2243 If you want to allow CONNECT for more ports than this, or want to forbid
2244 CONNECT altogether, you can specify a comma separated list of ports and
2245 port ranges (the latter using dashes, with the minimum defaulting to 0 and
2249 > If you don't know what any of this means, there probably is no reason to
2261 NAME="PREVENT-COMPRESSION"
2264 >+prevent-compression</I
2270 CLASS="VARIABLELIST"
2282 > Prevent the specified websites from compressing HTTP data.
2286 >Possible values:</DT
2296 CLASS="LITERALLAYOUT"
2297 > <I
2299 >{+prevent-compression}</I
2301 <I
2305 </P
2311 > Some websites do this, which can be a problem for
2317 HREF="actions-file.html#FILTER"
2325 HREF="actions-file.html#KILL-POPUPS"
2329 >"+kill-popups"</SPAN
2333 HREF="actions-file.html#GIF-DEANIMATE"
2337 >"+gif-deanimate"</SPAN
2340 will not work on compressed data. This will slow down connections to those
2341 websites, though. Default typically is to turn
2344 >"prevent-compression"</SPAN
2356 NAME="SESSION-COOKIES-ONLY"
2359 >+session-cookies-only</I
2365 CLASS="VARIABLELIST"
2377 > Allow cookies for the current browser session <I
2384 >Possible values:</DT
2391 >Example usage (disabling):</DT
2394 CLASS="LITERALLAYOUT"
2395 > <I
2397 >{-session-cookies-only}</I
2399 <I
2403 </P
2409 > If websites set cookies, <SPAN
2411 >"+session-cookies-only"</SPAN
2413 they are erased when you exit and restart your web browser. This makes
2414 profiling cookies useless, but won't break sites which require cookies so
2415 that you can log in for transactions. This is generally turned on for all
2416 sites, and is the recommended setting.
2421 >"+prevent-*-cookies"</SPAN
2422 > actions should be turned off as well (see
2425 >"+session-cookies-only"</SPAN
2426 > to work. Or, else no cookies
2427 will get through at all. For, <SPAN
2430 > cookies that survive
2431 across browser sessions, see below as well.
2442 NAME="PREVENT-READING-COOKIES"
2445 >+prevent-reading-cookies</I
2451 CLASS="VARIABLELIST"
2463 > Explicitly prevent the web server from reading any cookies on your
2468 >Possible values:</DT
2478 CLASS="LITERALLAYOUT"
2479 > <I
2481 >{+prevent-reading-cookies}</I
2483 <I
2487 </P
2493 > Often used in conjunction with <SPAN
2495 >"+prevent-setting-cookies"</SPAN
2497 disable cookies completely. Note that
2499 HREF="actions-file.html#SESSION-COOKIES-ONLY"
2503 >"+session-cookies-only"</SPAN
2506 requires these to both be disabled (or else it never gets any cookies to cache).
2512 > cookies to work (i.e. they survive across browser
2513 sessions and reboots), all three cookie settings should be <SPAN
2517 for the specified sites.
2528 NAME="PREVENT-SETTING-COOKIES"
2531 >+prevent-setting-cookies</I
2537 CLASS="VARIABLELIST"
2549 > Explicitly block the web server from storing cookies on your
2554 >Possible values:</DT
2564 CLASS="LITERALLAYOUT"
2565 > <I
2567 >{+prevent-setting-cookies}</I
2569 <I
2573 </P
2579 > Often used in conjunction with <SPAN
2581 >"+prevent-reading-cookies"</SPAN
2583 disable cookies completely (see above).
2606 CLASS="VARIABLELIST"
2618 > Stop those annoying JavaScript pop-up windows!
2622 >Possible values:</DT
2632 CLASS="LITERALLAYOUT"
2633 > <I
2637 <I
2641 </P
2649 >"+kill-popups"</SPAN
2650 > uses a built in filter to disable pop-ups
2654 > function, etc. This is
2655 one of the first actions processed by <SPAN
2659 as it contacts the remote web server. This action is not always 100% reliable,
2660 and is supplemented by <SPAN
2677 NAME="SEND-VANILLA-WAFER"
2680 >+send-vanilla-wafer</I
2686 CLASS="VARIABLELIST"
2698 > Sends a cookie for every site stating that you do not accept any copyright
2699 on cookies sent to you, and asking them not to track you.
2703 >Possible values:</DT
2713 CLASS="LITERALLAYOUT"
2714 > <I
2716 >{+send-vanilla-wafer}</I
2718 <I
2722 </P
2728 > This action only applies if you are using a <TT
2732 for saving cookies. Of course, this is a (relatively) unique header and
2733 could conceivably be used to track you.
2753 CLASS="VARIABLELIST"
2765 > This allows you to send an arbitrary, user definable cookie.
2769 >Possible values:</DT
2772 > User specified cookie name and corresponding value.
2779 CLASS="LITERALLAYOUT"
2780 > <I
2782 >{+send-wafer{name=value}}</I
2784 <I
2788 </P
2794 > This can be specified multiple times in order to add as many cookies as you
2810 > Note that many of these actions have the potential to cause a page to
2811 misbehave, possibly even not to display at all. There are many ways
2812 a site designer may choose to design his site, and what HTTP header
2813 content, and other criteria, he may depend on. There is no way to have hard
2814 and fast rules for all sites. See the <A
2815 HREF="appendix.html#ACTIONSANAT"
2817 > for a brief example on troubleshooting
2826 >9.5.22. Sample Actions Files</A
2829 > Remember that the meaning of any of the above references is reversed by preceding
2830 the action with a <SPAN
2833 >, in place of the <SPAN
2837 that some actions are turned on in the default section of the actions file,
2838 and require little to no additional configuration. These are just <SPAN
2843 > But, other actions that are turned on in the default section <I
2846 typically require</I
2847 > exceptions to be listed in the latter sections of
2848 one of our actions file. For instance, by default no URLs are
2852 > (i.e. in the default definitions of
2856 >). We need exceptions to this in order to
2860 > ad blocking in the lower sections. But we need to
2861 be very selective about what we do block. Thus, the default is <SPAN
2867 > Below is a liberally commented sample <TT
2871 to demonstrate how all the pieces come together. And to show how exceptions
2872 to the default policies can be handled. This is followed by a brief
2876 > with similar examples.</P
2881 CLASS="LITERALLAYOUT"
2882 ># Sample default.action file <developers@privoxy.org><br>
2884 # Settings -- Don't change! For internal Privoxy use ONLY.<br>
2886 for-privoxy-version=3.0<br>
2889 ##########################################################################<br>
2891 HREF="actions-file.html#ALIASES"
2894 > must be defined *before* they are used. These are<br>
2895 # easier to remember, and can combine several actions into one. Once <br>
2896 # defined they can be used just like any built-in action -- but within <br>
2897 # this file only! Aliases do not require a + or - sign.<br>
2898 ##########################################################################<br>
2900 # Some useful aliases.<br>
2901 # Alias to turn off cookie handling, ie allow all cookies unmolested.<br>
2902 -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \<br>
2903 -session-cookies-only<br>
2905 # Alias to both block and treat as if an image for ad blocking<br>
2906 # purposes.<br>
2907 +imageblock = +block +handle-as-image<br>
2909 # Fragile sites should have the minimum changes:<br>
2910 fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \<br>
2911 -prevent-cookies -kill-popups<br>
2913 # Shops should be allowed to set persistent cookies<br>
2914 shop = -filter -prevent-cookies -session-cookies-only<br>
2917 ##########################################################################<br>
2918 # Begin default action settings. Anything in this section will match <br>
2919 # all URLs -- UNLESS we have exceptions that also match, defined below this <br>
2920 # section. We will show all potential actions here whether they are on <br>
2921 # or off. We could omit any disabled action if we wanted, since all <br>
2922 # actions are 'off' by default anyway. Shown for completeness only.<br>
2923 # Actions are enabled if preceded by a '+', otherwise they are disabled <br>
2924 # (unless an alias has been defined without this).<br>
2925 ##########################################################################<br>
2928 HREF="actions-file.html#ADD-HEADER"
2933 HREF="actions-file.html#BLOCK"
2938 HREF="actions-file.html#DEANIMATE-GIFS"
2943 HREF="actions-file.html#DOWNGRADE-HTTP-VERSION"
2945 >-downgrade-http-version</A
2948 HREF="actions-file.html#FAST-REDIRECTS"
2953 HREF="actions-file.html#FILTER-HTML-ANNOYANCES"
2955 >+filter{html-annoyances}</A
2958 HREF="actions-file.html#FILTER-JS-ANNOYANCES"
2960 >+filter{js-annoyances}</A
2963 HREF="actions-file.html#FILTER-CONTENT-COOKIES"
2965 >-filter{content-cookies}</A
2968 HREF="actions-file.html#FILTER-POPUPS"
2973 HREF="actions-file.html#FILTER-WEBBUGS"
2975 >+filter{webbugs}</A
2978 HREF="actions-file.html#FILTER-REFRESH-TAGS"
2980 >-filter{refresh-tags}</A
2983 HREF="actions-file.html#FILTER-FUN"
2988 HREF="actions-file.html#FILTER-NIMDA"
2993 HREF="actions-file.html#FILTER-BANNERS-BY-SIZE"
2995 >+filter{banners-by-size}</A
2998 HREF="actions-file.html#FILTER-SHOCKWAVE-FLASH"
3000 >-filter{shockwave-flash}</A
3003 HREF="actions-file.html#FILTER-CRUDE-PARENTAL"
3005 >-filter{crude-prental}</A
3008 HREF="actions-file.html#HIDE-FORWARDED-FOR-HEADERS"
3010 >+hide-forwarded-for-headers</A
3013 HREF="actions-file.html#HIDE-FROM-HEADER"
3015 >+hide-from-header{block}</A
3018 HREF="actions-file.html#HIDE-REFERER"
3023 HREF="actions-file.html#HIDE-USER-AGENT"
3025 >-hide-user-agent</A
3028 HREF="actions-file.html#HANDLE-AS-IMAGE"
3030 >-handle-as-image</A
3033 HREF="actions-file.html#SET-IMAGE-BLOCKER"
3035 >+set-image-blocker{pattern}</A
3038 HREF="actions-file.html#LIMIT-CONNECT"
3043 HREF="actions-file.html#PREVENT-COMPRESSION"
3045 >+prevent-compression</A
3048 HREF="actions-file.html#SESSION-COOKIES-ONLY"
3050 >-session-cookies-only</A
3053 HREF="actions-file.html#PREVENT-READING-COOKIES"
3055 >-prevent-reading-cookies</A
3058 HREF="actions-file.html#PREVENT-SETTING-COOKIES"
3060 >-prevent-setting-cookies</A
3063 HREF="actions-file.html#KILL-POPUPS"
3068 HREF="actions-file.html#SEND-VANILLA-WAFER"
3070 >-send-vanilla-wafer</A
3073 HREF="actions-file.html#SEND-WAFER"
3078 / # forward slash will match *all* potential URL patterns. <br>
3080 ##########################################################################<br>
3081 # Default behavior is now set. Now we will define some exceptions to our <br>
3082 # default action policies.<br>
3083 ##########################################################################<br>
3085 # These sites are very complex and require very minimal interference.<br>
3086 # We'll disable most actions with our 'fragile' alias:<br>
3087 { fragile }<br>
3088 .office.microsoft.com # surprise, surprise!<br>
3089 .windowsupdate.microsoft.com<br>
3092 # Shopping sites - not as fragile but require some special <br>
3093 # handling. We still want to block ads, and we will allow <br>
3094 # persistant cookies via the 'shop' alias:<br>
3095 { shop }<br>
3096 .quietpc.com <br>
3097 .worldpay.com # for quietpc.com<br>
3098 .jungle.com<br>
3099 .scan.co.uk<br>
3102 # These sites require pop-ups too :( We'll combine our 'shop' <br>
3103 # alias with two other actions into one rule to allow all popups.<br>
3104 { shop <A
3105 HREF="actions-file.html#KILL-POPUPS"
3109 HREF="actions-file.html#FILTER-POPUPS"
3114 .overclockers.co.uk<br>
3117 # The 'Fast-redirects' action breaks some sites. Disable this action<br>
3118 # for these known sensitive sites:<br>
3120 HREF="actions-file.html#FAST-REDIRECTS"
3124 login.yahoo.com<br>
3125 edit.europe.yahoo.com<br>
3126 .google.com<br>
3127 .altavista.com/.*(like|url|link):http<br>
3128 .altavista.com/trans.*urltext=http<br>
3129 .nytimes.com<br>
3132 # Define which file types will be treated as images. Important<br>
3133 # for ad blocking.<br>
3135 HREF="actions-file.html#HANDLE-AS-IMAGE"
3137 >+handle-as-image</A
3139 /.*\.(gif|jpe?g|png|bmp|ico)<br>
3142 # Now lets list some domains that are known ad generators. And<br>
3143 # our alias that we use here will block these as well as force <br>
3144 # them to be treated as images. This combination of actions is <br>
3145 # important for ad blocking. What the browser will show instead is <br>
3146 # determined by the setting of <A
3147 HREF="actions-file.html#SET-IMAGE-BLOCKER"
3151 >"+set-image-blocker"</SPAN
3154 { +imageblock }<br>
3155 ar.atwola.com <br>
3156 .ad.doubleclick.net<br>
3157 .a.yimg.com/(?:(?!/i/).)*$<br>
3158 .a[0-9].yimg.com/(?:(?!/i/).)*$<br>
3159 bs*.gsanet.com<br>
3160 bs*.einets.com<br>
3161 .qkimg.net<br>
3162 ad.*.doubleclick.net<br>
3165 # These will just simply be blocked. They will generate the BLOCKED<br>
3166 # banner page, if matched. Heavy use of wildcards and regular <br>
3167 # expressions in this example. Enable block action:<br>
3169 HREF="actions-file.html#BLOCK"
3177 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)<br>
3178 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/<br>
3179 .hitbox.com <br>
3182 # The above block section will probably inadvertantly catch some <br>
3183 # sites we DO NOT want blocked via the wildcards and regular expressions. <br>
3184 # Now let's set exceptions to the exceptions so the good guys get better <br>
3185 # treatment. Disable block action:<br>
3187 HREF="actions-file.html#BLOCK"
3191 advogato.org<br>
3195 # Let's just trust all .edu top level domains.<br>
3197 www.ugu.com/sui/ugu/adv<br>
3198 # We'll need to access to path names containing 'download' <br>
3199 .*downloads.<br>
3200 /downloads/<br>
3201 # 'adv' is for globalintersec and means advanced, not advertisement<br>
3202 www.globalintersec.com/adv<br>
3205 # Don't filter *anything* from our friends at sourceforge.<br>
3206 # Notice we don't have to name the individual filter <br>
3207 # identifiers -- we just turn them all off in one fell swoop.<br>
3208 # Disable all filters for this one site:<br>
3210 HREF="actions-file.html#FILTER"
3214 .sourceforge.net<br>
3215 </P
3220 > So far we are painting with a broad brush by setting general policies.
3221 The above would be a reasonable starting point for many situations. Now,
3222 we want to be more specific and have customized rules that are more suitable
3223 to our personal habits and preferences. These would be for narrowly defined
3224 situations like your ISP or your bank, and should be placed in
3228 >, which is parsed after all other
3229 actions files and should not be clobbered by upgrades. So any settings here,
3230 will have the last word and over-ride any previously defined actions.</P
3232 > Now a few examples of some things that one might do with a
3241 CLASS="LITERALLAYOUT"
3242 ># Sample user.action file.<br>
3244 # Any aliases you want to use need to be re-defined here.<br>
3245 # Alias to turn off cookie handling, ie allow all cookies unmolested.<br>
3246 -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \<br>
3247 -session-cookies-only<br>
3249 # Fragile sites should have the minimum changes:<br>
3250 fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \<br>
3251 -prevent-cookies -kill-popups<br>
3253 # Allow persistent cookies for a few regular sites that we <br>
3254 # trust via our above alias. These will be saved from one browser session <br>
3255 # to the next. We are explicity turning off any and all cookie handling, <br>
3256 # even though the prevent-*-cookie settings were disabled in our above <br>
3257 # default.action anyway. So cookies from these domains will come through <br>
3258 # unmolested.<br>
3259 { -prevent-cookies }<br>
3261 .yahoo.com<br>
3262 .msdn.microsoft.com<br>
3263 .redhat.com<br>
3266 # My ISP uses obnoxious self promoting images on many pages.<br>
3267 # Nuke them :) Note that <A
3268 HREF="actions-file.html#HANDLE-AS-IMAGE"
3272 >"+handle-as-image"</SPAN
3274 > need not be specified,<br>
3275 # since all URLs ending in .gif will be tagged as images by the<br>
3276 # general rules in default.action anyway.<br>
3278 HREF="actions-file.html#BLOCK"
3282 www.my-isp-example.com/logo[0-9].gif<br>
3284 # Say the site where you do your homebanking needs to open<br>
3285 # popup windows, but you have chosen to kill popups by<br>
3286 # default. This will allow it for your-example-bank.com:<br>
3289 HREF="actions-file.html#FILTER-POPUPS"
3293 HREF="actions-file.html#KILL-POPUPS"
3297 .my-example-bank.com<br>
3299 # This site is delicate, and requires kid-glove <br>
3300 # treatment.<br>
3301 { fragile }<br>
3302 .forbes.com<br>
3303 </P
3328 >, can be defined by combining other <SPAN
3332 These can in turn be invoked just like the built-in <SPAN
3336 Currently, an alias can contain any character except space, tab, <SPAN
3346 >. But please use only <SPAN
3366 >. Alias names are not case sensitive, and
3369 >must be defined before other actions</I
3371 actions file! And there can only be one set of <SPAN
3375 defined per file. Each actions file may have its own aliases, but they are
3376 only visible within that file. Aliases do not requir a <SPAN
3383 > sign in front, since they are merely expanded.</P
3385 > Now let's define a few aliases:</P
3390 CLASS="LITERALLAYOUT"
3391 > # Useful custom aliases we can use later. These must come first!<br>
3393 +prevent-cookies = +prevent-setting-cookies +prevent-reading-cookies<br>
3394 -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies<br>
3395 fragile = -block -prevent-cookies -filter -fast-redirects -hide-referer -kill-popups<br>
3396 shop = -prevent-cookies -filter -fast-redirects<br>
3397 +imageblock = +block +handle-as-image<br>
3399 # Aliases defined from other aliases, for people who don't like to type <br>
3400 # too much: ;-)<br>
3401 c0 = +prevent-cookies<br>
3402 c1 = -prevent-cookies<br>
3403 #... etc. Customize to your heart's content.<br>
3404 </P
3409 > Some examples using our <SPAN
3416 aliases from above. These would appear in the lower sections of an
3417 actions file as exceptions to the default actions (as defined in the
3423 CLASS="LITERALLAYOUT"
3424 > # These sites are very complex and require<br>
3425 # minimal interference.<br>
3427 .office.microsoft.com<br>
3428 .windowsupdate.microsoft.com<br>
3429 .nytimes.com<br>
3431 # Shopping sites - but we still want to block ads.<br>
3433 .quietpc.com<br>
3434 .worldpay.com # for quietpc.com<br>
3435 .scan.co.uk<br>
3437 # These shops require pop-ups also <br>
3438 {shop -kill-popups}<br>
3439 .dabs.com<br>
3440 .overclockers.co.uk<br>
3441 </P
3452 > aliases are often used for
3456 > sites that require most actions to be disabled
3457 in order to function properly. </P
3491 HREF="filter-file.html"
3500 >The Main Configuration File</TD
3510 >The Filter File</TD
projects / privoxy.git / blob