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 version 2.9.15), with differing purposes:
99 > - is used by the web based editor,
100 to set various pre-defined sets of rules for the default actions section
104 >. These have increasing levels of
105 aggressiveness. It is not recommend to edit this file.
113 > - is the primary action file
114 that sets the initial values for all actions. It is intended to
115 provide a base level of functionality for
119 > array of features. So it is
120 a set of broad rules that should work reasonably well for users everywhere.
121 This is the file that the developers are keeping updated, and making
130 > - is intended to be for local site
131 preferences and exceptions. As an example, if your ISP or your bank
132 has specific requirements, and need special handling, this kind of
133 thing should go here. This file will not be upgraded.
140 > The list of actions files to be used are defined in the main configuration
141 file, and are processed in the order they are defined. The content of these
142 can all be viewed and edited from <A
143 HREF="http://config.privoxy.org/show-status"
145 >http://config.privoxy.org/show-status</A
148 > An actions file typically has sections. Near the top, <SPAN
152 optionally defined (discussed <A
153 HREF="actions-file.html#ALIASES"
156 >), then the default set of rules
157 which will apply universally to all sites and pages. And then below that,
158 exceptions to the defined universal policies. </P
161 Actions can be used to block anything you want, including ads, banners, or
162 just some obnoxious URL that you would rather not see. Cookies can be accepted
163 or rejected, or accepted only during the current browser session (i.e. not
164 written to disk), content can be modified, JavaScripts tamed, user-tracking
165 fooled, and much more. See below for a complete list of actions.</P
172 >9.1. Finding the Right Mix</A
176 HREF="actions-file.html#ACTIONS"
178 >, like cookie suppression
179 or script disabling, may render some sites unusable that rely on these
180 techniques to work properly. Finding the right mix of actions is not always easy and
181 certainly a matter of personal taste. In general, it can be said that the more
185 > your default settings (in the top section of the
186 actions file) are, the more exceptions for <SPAN
190 will have to make later. If, for example, you want to kill popup windows per
191 default, you'll have to make exceptions from that rule for sites that you
192 regularly use and that require popups for actually useful content, like maybe
193 your bank, favorite shop, or newspaper.</P
195 > We have tried to provide you with reasonable rules to start from in the
196 distribution actions files. But there is no general rule of thumb on these
197 things. There just are too many variables, and sites are constantly changing.
198 Sooner or later you will want to change the rules (and read this chapter again :).</P
209 > The easiest way to edit the <SPAN
212 > files is with a browser by
213 using our browser-based editor, which can be reached from <A
214 HREF="http://config.privoxy.org/show-status"
216 >http://config.privoxy.org/show-status</A
219 > If you prefer plain text editing to GUIs, you can of course also directly edit the
220 the actions files.</P
228 >9.3. How Actions are Applied to URLs</A
231 > Actions files are divided into sections. There are special sections,
235 HREF="actions-file.html#ALIASES"
238 > sections which will be discussed later. For now
239 let's concentrate on regular sections: They have a heading line (often split
240 up to multiple lines for readability) which consist of a list of actions,
241 separated by whitespace and enclosed in curly braces. Below that, there
242 is a list of URL patterns, each on a separate line.</P
244 > To determine which actions apply to a request, the URL of the request is
245 compared to all patterns in this file. Every time it matches, the list of
246 applicable actions for the URL is incrementally updated, using the heading
247 of the section in which the pattern is located. If multiple matches for
248 the same URL set the same action differently, the last match wins. If not,
249 the effects are aggregated (e.g. a URL might match both the
251 HREF="actions-file.html#HANDLE-AS-IMAGE"
255 >"+handle-as-image"</SPAN
259 HREF="actions-file.html#BLOCK"
268 > You can trace this process by visiting <A
269 HREF="http://config.privoxy.org/show-url-info"
271 >http://config.privoxy.org/show-url-info</A
274 > More detail on this is provided in the Appendix, <A
275 HREF="appendix.html#ACTIONSANAT"
276 > Anatomy of an Action</A
288 > Generally, a pattern has the form <TT
290 ><domain>/<path></TT
294 ><domain></TT
299 are optional. (This is why the pattern <TT
302 > matches all URLs).</P
311 >www.example.com/</TT
315 > is a domain-only pattern and will match any request to <TT
319 regardless of which document on that server is requested.
329 > means exactly the same. For domain-only patterns, the trailing <TT
339 >www.example.com/index.html</TT
343 > matches only the single document <TT
360 > matches the document <TT
363 >, regardless of the domain,
377 > matches nothing, since it would be interpreted as a domain name and
378 there is no top-level domain called <TT
392 >9.4.1. The Domain Pattern</A
395 > The matching of the domain part offers some flexible options: if the
396 domain starts or ends with a dot, it becomes unanchored at that end.
410 > matches any domain that <I
427 > matches any domain that <I
444 > matches any domain that <I
451 (Correctly speaking: It matches any FQDN that contains <TT
460 > Additionally, there are wild-cards that you can use in the domain names
461 themselves. They work pretty similar to shell wild-cards: <SPAN
465 stands for zero or more arbitrary characters, <SPAN
469 any single character, you can define character classes in square
470 brackets and all of that can be freely mixed:</P
485 >"adserver.example.com"</SPAN
489 >"ads.example.com"</SPAN
492 >"sfads.example.com"</SPAN
499 >*ad*.example.com</TT
503 > matches all of the above, and then some.
519 >pictures.epix.com</TT
522 >a.b.c.d.e.upix.com</TT
529 >www[1-9a-ez].example.c*</TT
535 >www1.example.com</TT
546 >wwwz.example.com</TT
553 >wwww.example.com</TT
566 >9.4.2. The Path Pattern</A
572 > uses Perl compatible regular expressions
574 HREF="http://www.pcre.org/"
578 matching the path.</P
581 HREF="appendix.html#REGEX"
583 > with a brief quick-start into regular
584 expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
586 HREF="http://www.pcre.org/man.txt"
588 >http://www.pcre.org/man.txt</A
590 You might also find the Perl man page on regular expressions (<TT
594 useful, which is available on-line at <A
595 HREF="http://www.perldoc.com/perl5.6/pod/perlre.html"
597 >http://www.perldoc.com/perl5.6/pod/perlre.html</A
600 > Note that the path pattern is automatically left-anchored at the <SPAN
604 i.e. it matches as if it would start with a <SPAN
607 > (regular expression speak
608 for the beginning of a line).</P
610 > Please also note that matching in the path is case
614 > by default, but you can switch to case
615 sensitive at any point in the pattern by using the
622 >www.example.com/(?-i)PaTtErN.*</TT
624 documents whose path starts with <TT
631 > this capitalization.</P
643 > All actions are disabled by default, until they are explicitly enabled
644 somewhere in an actions file. Actions are turned on if preceded with a
648 >, and turned off if preceded with a <SPAN
657 >"do that action"</SPAN
664 >"block the following URL
669 Actions are invoked by enclosing the action name in curly braces (e.g.
670 {+some_action}), followed by a list of URLs (or patterns that match URLs) to
671 which the action applies. There are three classes of actions: </P
679 Boolean, i.e the action can only be <SPAN
692 CLASS="LITERALLAYOUT"
696 > # enable this action<br>
700 > # disable this action<br>
701 </P
710 Parameterized, e.g. <SPAN
712 >"+/-hide-user-agent{ Mozilla 1.0 }"</SPAN
714 where some value is required in order to enable this type of action.
721 CLASS="LITERALLAYOUT"
725 > # enable action and set parameter to <SPAN
732 > # disable action (<SPAN
735 >) can be omitted<br>
736 </P
746 Multi-value, e.g. <SPAN
748 >"{+/-add-header{Name: value}}"</SPAN
752 >"{+/-send-wafer{name=value}}"</SPAN
753 >), where some value needs to be defined
754 in addition to simply enabling the action. Examples:
760 CLASS="LITERALLAYOUT"
763 >{+name{param=value}}</I
764 > # enable action and set <SPAN
773 >{-name{param=value}}</I
774 > # remove the parameter <SPAN
777 > completely<br>
781 > # disable this action totally and remove <SPAN
785 </P
794 > If nothing is specified in any actions file, no <SPAN
798 taken. So in this case <SPAN
802 normal, non-blocking, non-anonymizing proxy. You must specifically enable the
803 privacy and blocking features you need (although the provided default actions
804 files will give a good starting point).</P
806 > Later defined actions always over-ride earlier ones. So exceptions
807 to any rules you make, should come in the latter part of the file (or
808 in a file that is processed later when using multiple actions files). For
809 multi-valued actions, the actions are applied in the order they are specified.
810 Actions files are processed in the order they are defined in
814 > (the default installation has three actions
815 files). It also quite possible for any given URL pattern to match more than
818 > The list of valid <SPAN
851 > Send a user defined HTTP header to the web server.
855 >Possible values:</DT
858 > Any value is possible. Validity of the defined HTTP headers is not checked.
865 CLASS="LITERALLAYOUT"
866 > <I
868 >{+add-header{X-User-Tracking: sucks}}</I
870 <I
874 </P
880 > This action may be specified multiple times, in order to define multiple
881 headers. This is rarely needed for the typical user. If you don't know what
884 >"HTTP headers"</SPAN
885 > are, you definitely don't need to worry about this
918 > Used to block a URL from reaching your browser. The URL may be
919 anything, but is typically used to block ads or other obnoxious
924 >Possible values:</DT
933 CLASS="LITERALLAYOUT"
934 > <I
938 <I
940 >.banners.example.com</I
942 <I
946 </P
952 > If a URL matches one of the blocked patterns, <SPAN
956 will intercept the URL and display its special <SPAN
960 instead. If there is sufficient space, a large red banner will appear with
961 a friendly message about why the page was blocked, and a way to go there
962 anyway. If there is insufficient space a smaller <SPAN
966 page will appear without the red banner.
968 HREF="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"
972 to view the default blocked HTML page (<SPAN
976 for this to work as intended!).
980 A very important exception is if the URL <I
988 HREF="actions-file.html#HANDLE-AS-IMAGE"
992 >"+handle-as-image"</SPAN
995 then it will be handled by
997 HREF="actions-file.html#SET-IMAGE-BLOCKER"
1001 >"+set-image-blocker"</SPAN
1004 (see below). It is important to understand this process, in order
1005 to understand how <SPAN
1008 > is able to deal with
1009 ads and other objectionable content.
1013 HREF="actions-file.html#FILTER"
1020 action can also perform some of the
1021 same functionality as <SPAN
1024 >, but by virtue of very
1025 different programming techniques, and is most often used for different
1037 NAME="DEANIMATE-GIFS"
1046 CLASS="VARIABLELIST"
1058 > To stop those annoying, distracting animated GIF images.
1062 >Possible values:</DT
1078 CLASS="LITERALLAYOUT"
1079 > <I
1081 >{+deanimate-gifs{last}}</I
1083 <I
1087 </P
1093 > De-animate all animated GIF images, i.e. reduce them to their last frame.
1094 This will also shrink the images considerably (in bytes, not pixels!). If
1098 > is given, the first frame of the animation
1099 is used as the replacement. If <SPAN
1102 > is given, the last
1103 frame of the animation is used instead, which probably makes more sense for
1104 most banner animations, but also has the risk of not showing the entire
1105 last frame (if it is only a delta to an earlier frame).
1116 NAME="DOWNGRADE-HTTP-VERSION"
1119 >+downgrade-http-version</I
1125 CLASS="VARIABLELIST"
1139 >"+downgrade-http-version"</SPAN
1140 > will downgrade HTTP/1.1 client requests to
1141 HTTP/1.0 and downgrade the responses as well.
1145 >Possible values:</DT
1155 CLASS="LITERALLAYOUT"
1156 > <I
1158 >{+downgrade-http-version}</I
1160 <I
1164 </P
1170 > Use this action for servers that use HTTP/1.1 protocol features that
1174 > doesn't handle well yet. HTTP/1.1 is
1175 only partially implemented. Default is not to downgrade requests. This is
1176 an infrequently needed action, and is used to help with rare problem sites only.
1187 NAME="FAST-REDIRECTS"
1196 CLASS="VARIABLELIST"
1210 >"+fast-redirects"</SPAN
1211 > action enables interception of
1215 > requests from one server to another, which
1216 are used to track users.<SPAN
1220 all but the last valid URL in a redirect request and send a local redirect
1221 back to your browser without contacting the intermediate site(s).
1225 >Possible values:</DT
1235 CLASS="LITERALLAYOUT"
1236 > <I
1238 >{+fast-redirects}</I
1240 <I
1244 </P
1251 Many sites, like yahoo.com, don't just link to other sites. Instead, they
1252 will link to some script on their own server, giving the destination as a
1253 parameter, which will then redirect you to the final target. URLs
1254 resulting from this scheme typically look like:
1257 >http://some.place/some_script?http://some.where-else</I
1261 > Sometimes, there are even multiple consecutive redirects encoded in the
1262 URL. These redirections via scripts make your web browsing more traceable,
1263 since the server from which you follow such a link can see where you go
1264 to. Apart from that, valuable bandwidth and time is wasted, while your
1265 browser ask the server for one redirect after the other. Plus, it feeds
1269 > This is a normally <SPAN
1272 > feature, and often requires exceptions
1273 for sites that are sensitive to defeating this mechanism.
1293 CLASS="VARIABLELIST"
1305 > Apply page filtering as defined by named sections of the
1309 > file to the specified site(s).
1313 > can be any modification of the raw
1314 page content, including re-writing or deletion of content.
1318 >Possible values:</DT
1324 > must include the name of one of the section identifiers
1332 > is specified in <TT
1339 >Example usage (from the current <TT
1352 NAME="FILTER-HTML-ANNOYANCES"
1357 >+filter{html-annoyances}</I
1358 >: Get rid of particularly annoying HTML abuse.
1373 NAME="FILTER-JS-ANNOYANCES"
1378 >+filter{js-annoyances}</I
1379 >: Get rid of particularly annoying JavaScript abuse
1394 NAME="FILTER-CONTENT-COOKIES"
1399 >+filter{content-cookies}</I
1400 >: Kill cookies that come in the HTML or JS content
1415 NAME="FILTER-POPUPS"
1421 >: Kill all popups in JS and HTML
1436 NAME="FILTER-FRAMESET-BORDERS"
1441 >+filter{frameset-borders}</I
1442 >: Give frames a border and make them resizable
1457 NAME="FILTER-WEBBUGS"
1462 >+filter{webbugs}</I
1463 >: Squish WebBugs (1x1 invisible GIFs used for user tracking)
1478 NAME="FILTER-REFRESH-TAGS"
1483 >+filter{refresh-tags}</I
1484 >: Kill automatic refresh tags (for dial-on-demand setups)
1505 >: Text replacements for subversive browsing fun!
1526 >: Remove Nimda (virus) code.
1541 NAME="FILTER-BANNERS-BY-SIZE"
1546 >+filter{banners-by-size}</I
1547 >: Kill banners by size (<I
1565 NAME="FILTER-SHOCKWAVE-FLASH"
1570 >+filter{shockwave-flash}</I
1571 >: Kill embedded Shockwave Flash objects
1586 NAME="FILTER-CRUDE-PARENTAL"
1591 >+filter{crude-parental}</I
1592 >: Kill all web pages that contain the words "sex" or "warez"
1604 > This is potentially a very powerful feature! And requires a knowledge
1605 of regular expressions if you want to <SPAN
1607 >"roll your own"</SPAN
1609 Filtering operates on a line by line basis throughout the entire page.
1612 > Filtering requires buffering the page content, which may appear to
1613 slow down page rendering since nothing is displayed until all content has
1614 passed the filters. (It does not really take longer, but seems that way
1615 since the page is not incrementally displayed.) This effect will be more
1616 noticeable on slower connections.
1619 > Filtering can achieve some of the effects as the
1621 HREF="actions-file#BLOCK"
1628 action, i.e. it can be used to block ads and banners. In the overall
1629 scheme of things, filtering is one of the first things <SPAN
1633 does with a web page. So other most other actions are applied to the
1648 NAME="HIDE-FORWARDED-FOR-HEADERS"
1651 >+hide-forwarded-for-headers</I
1657 CLASS="VARIABLELIST"
1669 > Block any existing X-Forwarded-for HTTP header, and do not add a new one.
1673 >Possible values:</DT
1683 CLASS="LITERALLAYOUT"
1684 > <I
1686 >{+hide-forwarded-for-headers}</I
1688 <I
1692 </P
1698 > It is fairly safe to leave this on. It does not seem to break many sites.
1709 NAME="HIDE-FROM-HEADER"
1712 >+hide-from-header</I
1718 CLASS="VARIABLELIST"
1730 > To block the browser from sending your email address in a <SPAN
1738 >Possible values:</DT
1744 >, or any user defined value.
1751 CLASS="LITERALLAYOUT"
1752 > <I
1754 >{+hide-from-header{block}}</I
1756 <I
1760 </P
1769 > will completely remove the header
1770 (not to be confused with the <A
1771 HREF="actions-file.html#BLOCK"
1778 Alternately, you can specify any value you prefer to send to the web
1797 NAME="HIDE-REFERRER"
1802 CLASS="VARIABLELIST"
1814 > Don't send the <SPAN
1817 > (sic) HTTP header to the web site.
1818 Or, alternately send a forged header instead.
1822 >Possible values:</DT
1825 > Prevent the header from being sent with the keyword, <SPAN
1832 > a URL to one from the same server as the request.
1833 Or, set to user defined value of your choice.
1840 CLASS="LITERALLAYOUT"
1841 > <I
1843 >{+hide-referer{forge}}</I
1845 <I
1849 </P
1858 > is the preferred option here, since some servers will
1859 not send images back otherwise.
1865 >"+hide-referrer"</SPAN
1866 > is an alternate spelling of
1869 >"+hide-referer"</SPAN
1870 >. It has the exact same parameters, and can be freely
1873 >"+hide-referer"</SPAN
1878 correct English spelling, however the HTTP specification has a bug - it
1879 requires it to be spelled as <SPAN
1893 NAME="HIDE-USER-AGENT"
1896 >+hide-user-agent</I
1902 CLASS="VARIABLELIST"
1914 > To change the <SPAN
1916 >"User-Agent:"</SPAN
1917 > header so web servers can't tell
1918 your browser type. Who's business is it anyway?
1922 >Possible values:</DT
1925 > Any user defined string.
1932 CLASS="LITERALLAYOUT"
1933 > <I
1935 >{+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}}</I
1937 <I
1941 </P
1947 > Warning! This breaks many web sites that depend on this in order
1948 to determine how the target browser will respond to various
1949 requests. Use with caution.
1960 NAME="HANDLE-AS-IMAGE"
1963 >+handle-as-image</I
1969 CLASS="VARIABLELIST"
1981 > To define what <SPAN
1985 automatically as an image, and is an important ingredient of how
1990 >Possible values:</DT
2000 CLASS="LITERALLAYOUT"
2001 > <I
2003 >{+handle-as-image}</I
2005 <I
2007 >/.*\.(gif|jpg|jpeg|png|bmp|ico)</I
2009 </P
2015 > This only has meaning if the URL (or pattern) also is
2019 >ed, in which case a user definable image can
2020 be sent rather than a HTML page. This is integral to the whole concept of
2021 ad blocking: the URL must match <I
2025 HREF="actions-file.html#BLOCK"
2037 >"+handle-as-image"</SPAN
2040 HREF="actions-file.html#SET-IMAGE-BLOCKER"
2044 >"+set-image-blocker"</SPAN
2047 below for control over what will actually be displayed by the browser.)
2050 > There is little reason to change the default definition for this action.
2061 NAME="SET-IMAGE-BLOCKER"
2064 >+set-image-blocker</I
2070 CLASS="VARIABLELIST"
2082 > Decide what to do with URLs that end up tagged with <I
2087 HREF="actions-file.html#BLOCK"
2095 HREF="actions-file.html#HANDLE-AS-IMAGE"
2099 >"+handle-as-image"</SPAN
2102 e.g an advertisement.
2106 >Possible values:</DT
2109 > There are four available options: <SPAN
2111 >"-set-image-blocker"</SPAN
2116 > page, usually resulting in a <SPAN
2123 >"+set-image-blocker{<I
2128 1x1 transparent GIF image.
2131 >"+set-image-blocker{<I
2136 checkerboard type pattern (the default). And finally,
2139 >"+set-image-blocker{<I
2144 send a HTTP temporary redirect to the specified image. This has the
2145 advantage of the icon being being cached by the browser, which will speed
2153 CLASS="LITERALLAYOUT"
2154 > <I
2156 >{+set-image-blocker{blank}}</I
2158 <I
2162 </P
2171 > ads, they need to meet
2172 criteria as matching both <I
2179 actions. And then, <SPAN
2181 >"image-blocker"</SPAN
2186 > for invisibility. Note you cannot treat HTML pages as
2187 images in most cases. For instance, frames require an HTML page to
2188 display. So a frame that is an ad, typically cannot be treated as an image.
2192 > in this situation just will not work
2204 NAME="LIMIT-CONNECT"
2213 CLASS="VARIABLELIST"
2228 > only allows HTTP CONNECT
2229 requests to port 443 (the standard, secure HTTPS port). Use
2232 >"+limit-connect"</SPAN
2233 > to disable this altogether, or to allow
2238 >Possible values:</DT
2241 > Any valid port number, or port number range.
2245 >Example usages:</DT
2248 CLASS="LITERALLAYOUT"
2249 > <I
2251 >+limit-connect{443}</I
2252 > # This is the default and need not be specified.<br>
2253 <I
2255 >+limit-connect{80,443}</I
2256 > # Ports 80 and 443 are OK.<br>
2257 <I
2259 >+limit-connect{-3, 7, 20-100, 500-}</I
2260 > # Port less than 3, 7, 20 to 100 and above 500 are OK.<br>
2261 </P
2267 > The CONNECT methods exists in HTTP to allow access to secure websites
2268 (https:// URLs) through proxies. It works very simply: the proxy connects
2269 to the server on the specified port, and then short-circuits its
2270 connections to the client <I
2273 > to the remote proxy.
2274 This can be a big security hole, since CONNECT-enabled proxies can be
2275 abused as TCP relays very easily.
2279 If you want to allow CONNECT for more ports than this, or want to forbid
2280 CONNECT altogether, you can specify a comma separated list of ports and
2281 port ranges (the latter using dashes, with the minimum defaulting to 0 and
2285 > If you don't know what any of this means, there probably is no reason to
2297 NAME="PREVENT-COMPRESSION"
2300 >+prevent-compression</I
2306 CLASS="VARIABLELIST"
2318 > Prevent the specified websites from compressing HTTP data.
2322 >Possible values:</DT
2332 CLASS="LITERALLAYOUT"
2333 > <I
2335 >{+prevent-compression}</I
2337 <I
2341 </P
2347 > Some websites do this, which can be a problem for
2353 HREF="actions-file.html#FILTER"
2361 HREF="actions-file.html#KILL-POPUPS"
2365 >"+kill-popups"</SPAN
2369 HREF="actions-file.html#GIF-DEANIMATE"
2373 >"+gif-deanimate"</SPAN
2376 will not work on compressed data. This will slow down connections to those
2377 websites, though. Default typically is to turn
2380 >"prevent-compression"</SPAN
2392 NAME="SESSION-COOKIES-ONLY"
2395 >+session-cookies-only</I
2401 CLASS="VARIABLELIST"
2413 > Allow cookies for the current browser session <I
2420 >Possible values:</DT
2427 >Example usage (disabling):</DT
2430 CLASS="LITERALLAYOUT"
2431 > <I
2433 >{-session-cookies-only}</I
2435 <I
2439 </P
2445 > If websites set cookies, <SPAN
2447 >"+session-cookies-only"</SPAN
2449 they are erased when you exit and restart your web browser. This makes
2450 profiling cookies useless, but won't break sites which require cookies so
2451 that you can log in for transactions. This is generally turned on for all
2452 sites, and is the recommended setting.
2457 >"+prevent-*-cookies"</SPAN
2458 > actions should be turned off as well (see
2461 >"+session-cookies-only"</SPAN
2462 > to work. Or, else no cookies
2463 will get through at all. For, <SPAN
2466 > cookies that survive
2467 across browser sessions, see below as well.
2478 NAME="PREVENT-READING-COOKIES"
2481 >+prevent-reading-cookies</I
2487 CLASS="VARIABLELIST"
2499 > Explicitly prevent the web server from reading any cookies on your
2504 >Possible values:</DT
2514 CLASS="LITERALLAYOUT"
2515 > <I
2517 >{+prevent-reading-cookies}</I
2519 <I
2523 </P
2529 > Often used in conjunction with <SPAN
2531 >"+prevent-setting-cookies"</SPAN
2533 disable cookies completely. Note that
2535 HREF="actions-file.html#SESSION-COOKIES-ONLY"
2539 >"+session-cookies-only"</SPAN
2542 requires these to both be disabled (or else it never gets any cookies to cache).
2548 > cookies to work (i.e. they survive across browser
2549 sessions and reboots), all three cookie settings should be <SPAN
2553 for the specified sites.
2564 NAME="PREVENT-SETTING-COOKIES"
2567 >+prevent-setting-cookies</I
2573 CLASS="VARIABLELIST"
2585 > Explicitly block the web server from storing cookies on your
2590 >Possible values:</DT
2600 CLASS="LITERALLAYOUT"
2601 > <I
2603 >{+prevent-setting-cookies}</I
2605 <I
2609 </P
2615 > Often used in conjunction with <SPAN
2617 >"+prevent-reading-cookies"</SPAN
2619 disable cookies completely (see above).
2642 CLASS="VARIABLELIST"
2654 > Stop those annoying JavaScript pop-up windows!
2658 >Possible values:</DT
2668 CLASS="LITERALLAYOUT"
2669 > <I
2673 <I
2677 </P
2685 >"+kill-popups"</SPAN
2686 > uses a built in filter to disable pop-ups
2690 > function, etc. This is
2691 one of the first actions processed by <SPAN
2695 as it contacts the remote web server. This action is not always 100% reliable,
2696 and is supplemented by <SPAN
2713 NAME="SEND-VANILLA-WAFER"
2716 >+send-vanilla-wafer</I
2722 CLASS="VARIABLELIST"
2734 > Sends a cookie for every site stating that you do not accept any copyright
2735 on cookies sent to you, and asking them not to track you.
2739 >Possible values:</DT
2749 CLASS="LITERALLAYOUT"
2750 > <I
2752 >{+send-vanilla-wafer}</I
2754 <I
2758 </P
2764 > This action only applies if you are using a <TT
2768 for saving cookies. Of course, this is a (relatively) unique header and
2769 could conceivably be used to track you.
2789 CLASS="VARIABLELIST"
2801 > This allows you to send an arbitrary, user definable cookie.
2805 >Possible values:</DT
2808 > User specified cookie name and corresponding value.
2815 CLASS="LITERALLAYOUT"
2816 > <I
2818 >{+send-wafer{name=value}}</I
2820 <I
2824 </P
2830 > This can be specified multiple times in order to add as many cookies as you
2846 > Note that many of these actions have the potential to cause a page to
2847 misbehave, possibly even not to display at all. There are many ways
2848 a site designer may choose to design his site, and what HTTP header
2849 content, and other criteria, he may depend on. There is no way to have hard
2850 and fast rules for all sites. See the <A
2851 HREF="appendix.html#ACTIONSANAT"
2853 > for a brief example on troubleshooting
2862 >9.5.22. Sample Actions Files</A
2865 > Remember that the meaning of any of the above references is reversed by preceding
2866 the action with a <SPAN
2869 >, in place of the <SPAN
2873 that some actions are turned on in the default section of the actions file,
2874 and require little to no additional configuration. These are just <SPAN
2879 > But, other actions that are turned on in the default section <I
2882 typically require</I
2883 > exceptions to be listed in the latter sections of
2884 one of our actions file. For instance, by default no URLs are
2888 > (i.e. in the default definitions of
2892 >). We need exceptions to this in order to
2896 > ad blocking in the lower sections. But we need to
2897 be very selective about what we do block. Thus, the default is <SPAN
2903 > Below is a liberally commented sample <TT
2907 to demonstrate how all the pieces come together. And to show how exceptions
2908 to the default policies can be handled. This is followed by a brief
2912 > with similar examples.</P
2917 CLASS="LITERALLAYOUT"
2918 ># Sample default.action file <developers@privoxy.org><br>
2920 # Settings -- Don't change! For internal Privoxy use ONLY.<br>
2922 for-privoxy-version=3.0<br>
2925 ##########################################################################<br>
2927 HREF="actions-file.html#ALIASES"
2930 > must be defined *before* they are used. These are<br>
2931 # easier to remember, and can combine several actions into one. Once <br>
2932 # defined they can be used just like any built-in action -- but within <br>
2933 # this file only! Aliases do not require a + or - sign.<br>
2934 ##########################################################################<br>
2936 # Some useful aliases.<br>
2937 # Alias to turn off cookie handling, ie allow all cookies unmolested.<br>
2938 -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \<br>
2939 -session-cookies-only<br>
2941 # Alias to both block and treat as if an image for ad blocking<br>
2942 # purposes.<br>
2943 +imageblock = +block +handle-as-image<br>
2945 # Fragile sites should have the minimum changes:<br>
2946 fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \<br>
2947 -prevent-cookies -kill-popups<br>
2949 # Shops should be allowed to set persistent cookies<br>
2950 shop = -filter -prevent-cookies -session-cookies-only<br>
2953 ##########################################################################<br>
2954 # Begin default action settings. Anything in this section will match <br>
2955 # all URLs -- UNLESS we have exceptions that also match, defined below this <br>
2956 # section. We will show all potential actions here whether they are on <br>
2957 # or off. We could omit any disabled action if we wanted, since all <br>
2958 # actions are 'off' by default anyway. Shown for completeness only.<br>
2959 # Actions are enabled if preceded by a '+', otherwise they are disabled <br>
2960 # (unless an alias has been defined without this).<br>
2961 ##########################################################################<br>
2964 HREF="actions-file.html#ADD-HEADER"
2969 HREF="actions-file.html#BLOCK"
2974 HREF="actions-file.html#DEANIMATE-GIFS"
2979 HREF="actions-file.html#DOWNGRADE-HTTP-VERSION"
2981 >-downgrade-http-version</A
2984 HREF="actions-file.html#FAST-REDIRECTS"
2989 HREF="actions-file.html#FILTER-HTML-ANNOYANCES"
2991 >+filter{html-annoyances}</A
2994 HREF="actions-file.html#FILTER-JS-ANNOYANCES"
2996 >+filter{js-annoyances}</A
2999 HREF="actions-file.html#FILTER-CONTENT-COOKIES"
3001 >-filter{content-cookies}</A
3004 HREF="actions-file.html#FILTER-POPUPS"
3009 HREF="actions-file.html#FILTER-WEBBUGS"
3011 >+filter{webbugs}</A
3014 HREF="actions-file.html#FILTER-REFRESH-TAGS"
3016 >-filter{refresh-tags}</A
3019 HREF="actions-file.html#FILTER-FUN"
3024 HREF="actions-file.html#FILTER-NIMDA"
3029 HREF="actions-file.html#FILTER-BANNERS-BY-SIZE"
3031 >+filter{banners-by-size}</A
3034 HREF="actions-file.html#FILTER-SHOCKWAVE-FLASH"
3036 >-filter{shockwave-flash}</A
3039 HREF="actions-file.html#FILTER-CRUDE-PARENTAL"
3041 >-filter{crude-prental}</A
3044 HREF="actions-file.html#HIDE-FORWARDED-FOR-HEADERS"
3046 >+hide-forwarded-for-headers</A
3049 HREF="actions-file.html#HIDE-FROM-HEADER"
3051 >+hide-from-header{block}</A
3054 HREF="actions-file.html#HIDE-REFERER"
3059 HREF="actions-file.html#HIDE-USER-AGENT"
3061 >-hide-user-agent</A
3064 HREF="actions-file.html#HANDLE-AS-IMAGE"
3066 >-handle-as-image</A
3069 HREF="actions-file.html#SET-IMAGE-BLOCKER"
3071 >+set-image-blocker{pattern}</A
3074 HREF="actions-file.html#LIMIT-CONNECT"
3079 HREF="actions-file.html#PREVENT-COMPRESSION"
3081 >+prevent-compression</A
3084 HREF="actions-file.html#SESSION-COOKIES-ONLY"
3086 >-session-cookies-only</A
3089 HREF="actions-file.html#PREVENT-READING-COOKIES"
3091 >-prevent-reading-cookies</A
3094 HREF="actions-file.html#PREVENT-SETTING-COOKIES"
3096 >-prevent-setting-cookies</A
3099 HREF="actions-file.html#KILL-POPUPS"
3104 HREF="actions-file.html#SEND-VANILLA-WAFER"
3106 >-send-vanilla-wafer</A
3109 HREF="actions-file.html#SEND-WAFER"
3114 / # forward slash will match *all* potential URL patterns. <br>
3116 ##########################################################################<br>
3117 # Default behavior is now set. Now we will define some exceptions to our <br>
3118 # default action policies.<br>
3119 ##########################################################################<br>
3121 # These sites are very complex and require very minimal interference.<br>
3122 # We'll disable most actions with our 'fragile' alias:<br>
3123 { fragile }<br>
3124 .office.microsoft.com # surprise, surprise!<br>
3125 .windowsupdate.microsoft.com<br>
3128 # Shopping sites - not as fragile but require some special <br>
3129 # handling. We still want to block ads, and we will allow <br>
3130 # persistant cookies via the 'shop' alias:<br>
3131 { shop }<br>
3132 .quietpc.com <br>
3133 .worldpay.com # for quietpc.com<br>
3134 .jungle.com<br>
3135 .scan.co.uk<br>
3138 # These sites require pop-ups too :( We'll combine our 'shop' <br>
3139 # alias with two other actions into one rule to allow all popups.<br>
3140 { shop <A
3141 HREF="actions-file.html#KILL-POPUPS"
3145 HREF="actions-file.html#FILTER-POPUPS"
3150 .overclockers.co.uk<br>
3153 # The 'Fast-redirects' action breaks some sites. Disable this action<br>
3154 # for these known sensitive sites:<br>
3156 HREF="actions-file.html#FAST-REDIRECTS"
3160 login.yahoo.com<br>
3161 edit.europe.yahoo.com<br>
3162 .google.com<br>
3163 .altavista.com/.*(like|url|link):http<br>
3164 .altavista.com/trans.*urltext=http<br>
3165 .nytimes.com<br>
3168 # Define which file types will be treated as images. Important<br>
3169 # for ad blocking.<br>
3171 HREF="actions-file.html#HANDLE-AS-IMAGE"
3173 >+handle-as-image</A
3175 /.*\.(gif|jpe?g|png|bmp|ico)<br>
3178 # Now lets list some domains that are known ad generators. And<br>
3179 # our alias that we use here will block these as well as force <br>
3180 # them to be treated as images. This combination of actions is <br>
3181 # important for ad blocking. What the browser will show instead is <br>
3182 # determined by the setting of <A
3183 HREF="actions-file.html#SET-IMAGE-BLOCKER"
3187 >"+set-image-blocker"</SPAN
3190 { +imageblock }<br>
3191 ar.atwola.com <br>
3192 .ad.doubleclick.net<br>
3193 .a.yimg.com/(?:(?!/i/).)*$<br>
3194 .a[0-9].yimg.com/(?:(?!/i/).)*$<br>
3195 bs*.gsanet.com<br>
3196 bs*.einets.com<br>
3197 .qkimg.net<br>
3198 ad.*.doubleclick.net<br>
3201 # These will just simply be blocked. They will generate the BLOCKED<br>
3202 # banner page, if matched. Heavy use of wildcards and regular <br>
3203 # expressions in this example. Enable block action:<br>
3205 HREF="actions-file.html#BLOCK"
3213 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)<br>
3214 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/<br>
3215 .hitbox.com <br>
3218 # The above block section will probably inadvertantly catch some <br>
3219 # sites we DO NOT want blocked via the wildcards and regular expressions. <br>
3220 # Now let's set exceptions to the exceptions so the good guys get better <br>
3221 # treatment. Disable block action:<br>
3223 HREF="actions-file.html#BLOCK"
3227 advogato.org<br>
3231 # Let's just trust all .edu top level domains.<br>
3233 www.ugu.com/sui/ugu/adv<br>
3234 # We'll need to access to path names containing 'download' <br>
3235 .*downloads.<br>
3236 /downloads/<br>
3237 # 'adv' is for globalintersec and means advanced, not advertisement<br>
3238 www.globalintersec.com/adv<br>
3241 # Don't filter *anything* from our friends at sourceforge.<br>
3242 # Notice we don't have to name the individual filter <br>
3243 # identifiers -- we just turn them all off in one fell swoop.<br>
3244 # Disable all filters for this one site:<br>
3246 HREF="actions-file.html#FILTER"
3250 .sourceforge.net<br>
3251 </P
3256 > So far we are painting with a broad brush by setting general policies.
3257 The above would be a reasonable starting point for many situations. Now,
3258 we want to be more specific and have customized rules that are more suitable
3259 to our personal habits and preferences. These would be for narrowly defined
3260 situations like your ISP or your bank, and should be placed in
3264 >, which is parsed after all other
3265 actions files and should not be clobbered by upgrades. So any settings here,
3266 will have the last word and over-ride any previously defined actions.</P
3268 > Now a few examples of some things that one might do with a
3277 CLASS="LITERALLAYOUT"
3278 ># Sample user.action file.<br>
3280 # Any aliases you want to use need to be re-defined here.<br>
3281 # Alias to turn off cookie handling, ie allow all cookies unmolested.<br>
3282 -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \<br>
3283 -session-cookies-only<br>
3285 # Fragile sites should have the minimum changes:<br>
3286 fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \<br>
3287 -prevent-cookies -kill-popups<br>
3289 # Allow persistent cookies for a few regular sites that we <br>
3290 # trust via our above alias. These will be saved from one browser session <br>
3291 # to the next. We are explicity turning off any and all cookie handling, <br>
3292 # even though the prevent-*-cookie settings were disabled in our above <br>
3293 # default.action anyway. So cookies from these domains will come through <br>
3294 # unmolested.<br>
3295 { -prevent-cookies }<br>
3297 .yahoo.com<br>
3298 .msdn.microsoft.com<br>
3299 .redhat.com<br>
3302 # My ISP uses obnoxious self promoting images on many pages.<br>
3303 # Nuke them :) Note that <A
3304 HREF="actions-file.html#HANDLE-AS-IMAGE"
3308 >"+handle-as-image"</SPAN
3310 > need not be specified,<br>
3311 # since all URLs ending in .gif will be tagged as images by the<br>
3312 # general rules in default.action anyway.<br>
3314 HREF="actions-file.html#BLOCK"
3318 www.my-isp-example.com/logo[0-9].gif<br>
3321 # Say the site where you do your homebanking needs to open<br>
3322 # popup windows, but you have chosen to kill popups by<br>
3323 # default. This will allow it for your-example-bank.com:<br>
3326 HREF="actions-file.html#FILTER-POPUPS"
3330 HREF="actions-file.html#KILL-POPUPS"
3334 .my-example-bank.com<br>
3337 # This site is delicate, and requires kid-glove <br>
3338 # treatment.<br>
3339 { fragile }<br>
3340 .forbes.com<br>
3341 </P
3366 >, can be defined by combining other <SPAN
3370 These can in turn be invoked just like the built-in <SPAN
3374 Currently, an alias can contain any character except space, tab, <SPAN
3384 >. But please use only <SPAN
3404 >. Alias names are not case sensitive, and
3407 >must be defined before other actions</I
3409 actions file! And there can only be one set of <SPAN
3413 defined per file. Each actions file may have its own aliases, but they are
3414 only visible within that file. Aliases do not requir a <SPAN
3421 > sign in front, since they are merely expanded.</P
3423 > Now let's define a few aliases:</P
3428 CLASS="LITERALLAYOUT"
3429 > # Useful custom aliases we can use later. These must come first!<br>
3431 +prevent-cookies = +prevent-setting-cookies +prevent-reading-cookies<br>
3432 -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies<br>
3433 fragile = -block -prevent-cookies -filter -fast-redirects -hide-referer -kill-popups<br>
3434 shop = -prevent-cookies -filter -fast-redirects<br>
3435 +imageblock = +block +handle-as-image<br>
3437 # Aliases defined from other aliases, for people who don't like to type <br>
3438 # too much: ;-)<br>
3439 c0 = +prevent-cookies<br>
3440 c1 = -prevent-cookies<br>
3441 #... etc. Customize to your heart's content.<br>
3442 </P
3447 > Some examples using our <SPAN
3454 aliases from above. These would appear in the lower sections of an
3455 actions file as exceptions to the default actions (as defined in the
3461 CLASS="LITERALLAYOUT"
3462 > # These sites are very complex and require<br>
3463 # minimal interference.<br>
3465 .office.microsoft.com<br>
3466 .windowsupdate.microsoft.com<br>
3467 .nytimes.com<br>
3469 # Shopping sites - but we still want to block ads.<br>
3471 .quietpc.com<br>
3472 .worldpay.com # for quietpc.com<br>
3473 .scan.co.uk<br>
3475 # These shops require pop-ups also <br>
3476 {shop -kill-popups}<br>
3477 .dabs.com<br>
3478 .overclockers.co.uk<br>
3479 </P
3490 > aliases are often used for
3494 > sites that require most actions to be disabled
3495 in order to function properly. </P
3529 HREF="filter-file.html"
3538 >The Main Configuration File</TD
3548 >The Filter File</TD
projects / privoxy.git / blob