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 determine
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
107 >and have no influence on your browsing unless
108 you select them explicitly in the editor</I
109 >. It is not recommend
118 > - is the primary action file
119 that sets the initial values for all actions. It is intended to
120 provide a base level of functionality for
124 > array of features. So it is
125 a set of broad rules that should work reasonably well for users everywhere.
126 This is the file that the developers are keeping updated, and making
135 > - is intended to be for local site
136 preferences and exceptions. As an example, if your ISP or your bank
137 has specific requirements, and need special handling, this kind of
138 thing should go here. This file will not be upgraded.
145 > The list of actions files to be used are defined in the main configuration
146 file, and are processed in the order they are defined. The content of these
147 can all be viewed and edited from <A
148 HREF="http://config.privoxy.org/show-status"
150 >http://config.privoxy.org/show-status</A
153 > An actions file typically has multiple sections. If you want to use
157 > in an actions file, you have to place the (optional)
159 HREF="actions-file.html#ALIASES"
161 > at the top of that file.
162 Then comes the default set of rules which will apply universally to all
163 sites and pages (be <I
170 > or any other actions file after
174 >, because it will override the result
175 from consulting any previous file). And then below that,
176 exceptions to the defined universal policies. You can regard
180 > as an appendix to <TT
184 with the advantage that is a separate file, which makes preserving your
185 personal settings across <SPAN
188 > upgrades easier.</P
191 Actions can be used to block anything you want, including ads, banners, or
192 just some obnoxious URL that you would rather not see. Cookies can be accepted
193 or rejected, or accepted only during the current browser session (i.e. not
194 written to disk), content can be modified, JavaScripts tamed, user-tracking
195 fooled, and much more. See below for a <A
196 HREF="actions-file.html#ACTIONS"
206 >8.1. Finding the Right Mix</A
210 HREF="actions-file.html#ACTIONS"
212 >, like cookie suppression
213 or script disabling, may render some sites unusable that rely on these
214 techniques to work properly. Finding the right mix of actions is not always easy and
215 certainly a matter of personal taste. In general, it can be said that the more
219 > your default settings (in the top section of the
220 actions file) are, the more exceptions for <SPAN
224 will have to make later. If, for example, you want to kill popup windows per
225 default, you'll have to make exceptions from that rule for sites that you
226 regularly use and that require popups for actually useful content, like maybe
227 your bank, favorite shop, or newspaper.</P
229 > We have tried to provide you with reasonable rules to start from in the
230 distribution actions files. But there is no general rule of thumb on these
231 things. There just are too many variables, and sites are constantly changing.
232 Sooner or later you will want to change the rules (and read this chapter again :).</P
243 > The easiest way to edit the actions files is with a browser by
244 using our browser-based editor, which can be reached from <A
245 HREF="http://config.privoxy.org/show-status"
247 >http://config.privoxy.org/show-status</A
249 The editor allows both fine-grained control over every single feature on a
250 per-URL basis, and easy choosing from wholesale sets of defaults like
262 > If you prefer plain text editing to GUIs, you can of course also directly edit the
263 the actions files. Look at <TT
275 >8.3. How Actions are Applied to URLs</A
278 > Actions files are divided into sections. There are special sections,
282 HREF="actions-file.html#ALIASES"
285 > sections which will be discussed later. For now
286 let's concentrate on regular sections: They have a heading line (often split
287 up to multiple lines for readability) which consist of a list of actions,
288 separated by whitespace and enclosed in curly braces. Below that, there
289 is a list of URL patterns, each on a separate line.</P
291 > To determine which actions apply to a request, the URL of the request is
292 compared to all patterns in each action file file. Every time it matches, the list of
293 applicable actions for the URL is incrementally updated, using the heading
294 of the section in which the pattern is located. If multiple matches for
295 the same URL set the same action differently, the last match wins. If not,
296 the effects are aggregated (e.g. a URL might match both the
298 HREF="actions-file.html#HANDLE-AS-IMAGE"
302 >"+handle-as-image"</SPAN
306 HREF="actions-file.html#BLOCK"
315 > You can trace this process for any given URL by visiting <A
316 HREF="http://config.privoxy.org/show-url-info"
318 >http://config.privoxy.org/show-url-info</A
321 > More detail on this is provided in the Appendix, <A
322 HREF="appendix.html#ACTIONSANAT"
323 > Anatomy of an Action</A
335 > Generally, a pattern has the form <TT
337 ><domain>/<path></TT
341 ><domain></TT
346 are optional. (This is why the pattern <TT
349 > matches all URLs).</P
358 >www.example.com/</TT
362 > is a domain-only pattern and will match any request to <TT
366 regardless of which document on that server is requested.
376 > means exactly the same. For domain-only patterns, the trailing <TT
386 >www.example.com/index.html</TT
390 > matches only the single document <TT
407 > matches the document <TT
410 >, regardless of the domain,
424 > matches nothing, since it would be interpreted as a domain name and
425 there is no top-level domain called <TT
439 >8.4.1. The Domain Pattern</A
442 > The matching of the domain part offers some flexible options: if the
443 domain starts or ends with a dot, it becomes unanchored at that end.
457 > matches any domain that <I
474 > matches any domain that <I
491 > matches any domain that <I
498 (Correctly speaking: It matches any FQDN that contains <TT
507 > Additionally, there are wild-cards that you can use in the domain names
508 themselves. They work pretty similar to shell wild-cards: <SPAN
512 stands for zero or more arbitrary characters, <SPAN
516 any single character, you can define character classes in square
517 brackets and all of that can be freely mixed:</P
532 >"adserver.example.com"</SPAN
536 >"ads.example.com"</SPAN
539 >"sfads.example.com"</SPAN
546 >*ad*.example.com</TT
550 > matches all of the above, and then some.
566 >pictures.epix.com</TT
569 >a.b.c.d.e.upix.com</TT
576 >www[1-9a-ez].example.c*</TT
582 >www1.example.com</TT
593 >wwwz.example.com</TT
600 >wwww.example.com</TT
613 >8.4.2. The Path Pattern</A
619 > uses Perl compatible regular expressions
621 HREF="http://www.pcre.org/"
625 matching the path.</P
628 HREF="appendix.html#REGEX"
630 > with a brief quick-start into regular
631 expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
633 HREF="http://www.pcre.org/man.txt"
635 >http://www.pcre.org/man.txt</A
637 You might also find the Perl man page on regular expressions (<TT
641 useful, which is available on-line at <A
642 HREF="http://www.perldoc.com/perl5.6/pod/perlre.html"
644 >http://www.perldoc.com/perl5.6/pod/perlre.html</A
647 > Note that the path pattern is automatically left-anchored at the <SPAN
651 i.e. it matches as if it would start with a <SPAN
654 > (regular expression speak
655 for the beginning of a line).</P
657 > Please also note that matching in the path is case
661 > by default, but you can switch to case
662 sensitive at any point in the pattern by using the
669 >www.example.com/(?-i)PaTtErN.*</TT
671 documents whose path starts with <TT
678 > this capitalization.</P
690 > All actions are disabled by default, until they are explicitly enabled
691 somewhere in an actions file. Actions are turned on if preceded with a
695 >, and turned off if preceded with a <SPAN
704 >"do that action"</SPAN
711 >"please block URLs that match the
712 following patterns"</SPAN
719 block URLs that match the following patterns, even if <TT
723 previously applied."</SPAN
727 Again, actions are invoked by placing them on a line, enclosed in curly braces and
728 separated by whitespace, like in
731 >{+some-action -some-other-action{some-parameter}}</TT
733 followed by a list of URL patterns, one per line, to which they apply.
734 Together, the actions line and the following pattern lines make up a section
735 of the actions file. </P
738 There are three classes of actions:</P
746 Boolean, i.e the action can only be <SPAN
769 > # enable action <TT
780 > # disable action <TT
802 Parameterized, where some value is required in order to enable this type of action.
824 >} # enable action and set parameter to <TT
830 # overwriting parameter from previous match if necessary
836 > # disable action. The parameter can be omitted</PRE
843 > Note that if the URL matches multiple positive forms of a parameterized action,
844 the last match wins, i.e. the params from earlier matches are simply ignored.
850 >+hide-user-agent{ Mozilla 1.0 }</TT
857 Multi-value. These look exactly like parameterized actions,
858 but they behave differently: If the action applies multiple times to the
859 same URL, but with different parameters, <I
866 > matches are remembered. This is used for actions
867 that can be executed for the same request repeatedly, like adding multiple
868 headers, or filtering through multiple filters. Syntax:
889 >} # enable action and add <TT
894 > to the list of parameters
905 >} # remove the parameter <TT
910 > from the list of parameters
911 # If it was the last one left, disable the action.
917 > # disable this action completely and remove all parameters from the list</PRE
927 >+add-header{X-Fun-Header: Some text}</TT
931 >+filter{html-annoyances}</TT
938 > If nothing is specified in any actions file, no <SPAN
942 taken. So in this case <SPAN
946 normal, non-blocking, non-anonymizing proxy. You must specifically enable the
947 privacy and blocking features you need (although the provided default actions
948 files will give a good starting point).</P
950 > Later defined actions always over-ride earlier ones. So exceptions
951 to any rules you make, should come in the latter part of the file (or
952 in a file that is processed later when using multiple actions files). For
953 multi-valued actions, the actions are applied in the order they are specified.
954 Actions files are processed in the order they are defined in
958 > (the default installation has three actions
959 files). It also quite possible for any given URL pattern to match more than
960 one pattern and thus more than one set of actions!</P
962 > The list of valid <SPAN
989 >Purpose and typical uses:</DT
992 > Send a user defined HTTP header to the web server. Can be used to confuse log analysis.
996 >Possible values:</DT
999 > Any value is possible. Validity of the defined HTTP headers is not checked.
1000 It is recommended that you use the <SPAN
1014 CLASS="LITERALLAYOUT"
1015 > <I
1017 >{+add-header{X-User-Tracking: sucks}}</I
1019 <I
1028 > This action may be specified multiple times, in order to define multiple
1029 headers. This is rarely needed for the typical user. If you don't know what
1032 >"HTTP headers"</SPAN
1033 > are, you definitely don't need to worry about this
1054 CLASS="VARIABLELIST"
1063 >Purpose and typical uses:</DT
1066 > Requests for URLs to which this action applies are blocked, i.e. the requests are not
1067 forwarded to the remote server, but answered locally with a substitute page or image,
1068 as determined by the <A
1069 HREF="actions-file.html#HANDLE-AS-IMAGE"
1073 HREF="actions-file.html#SET-IMAGE-BLOCKER"
1074 >set-image-blocker</A
1076 It is typically used to block ads or other obnoxious content.
1080 >Possible values:</DT
1089 CLASS="LITERALLAYOUT"
1090 > <I
1094 <I
1096 >.banners.example.com</I
1098 <I
1102 </P
1108 > If a URL matches one of the blocked patterns, <SPAN
1112 will intercept the URL and display its special <SPAN
1116 instead. If there is sufficient space, a large red banner will appear with
1117 a friendly message about why the page was blocked, and a way to go there
1118 anyway. If there is insufficient space a smaller <SPAN
1122 page will appear without the red banner.
1124 HREF="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"
1128 to view the default blocked HTML page (<SPAN
1132 for this to work as intended!).
1136 A very important exception is if the URL <I
1144 HREF="actions-file.html#HANDLE-AS-IMAGE"
1148 >"+handle-as-image"</SPAN
1151 then it will be handled by
1153 HREF="actions-file.html#SET-IMAGE-BLOCKER"
1157 >"+set-image-blocker"</SPAN
1160 (see below). It is important to understand this process, in order
1161 to understand how <SPAN
1164 > is able to deal with
1165 ads and other objectionable content.
1169 HREF="actions-file.html#FILTER"
1176 action can also perform some of the
1177 same functionality as <SPAN
1180 >, but by virtue of very
1181 different programming techniques, and is most often used for different
1193 NAME="DEANIMATE-GIFS"
1202 CLASS="VARIABLELIST"
1214 > To stop those annoying, distracting animated GIF images.
1218 >Possible values:</DT
1234 CLASS="LITERALLAYOUT"
1235 > <I
1237 >{+deanimate-gifs{last}}</I
1239 <I
1243 </P
1249 > De-animate all animated GIF images, i.e. reduce them to their last frame.
1250 This will also shrink the images considerably (in bytes, not pixels!). If
1254 > is given, the first frame of the animation
1255 is used as the replacement. If <SPAN
1258 > is given, the last
1259 frame of the animation is used instead, which probably makes more sense for
1260 most banner animations, but also has the risk of not showing the entire
1261 last frame (if it is only a delta to an earlier frame).
1272 NAME="DOWNGRADE-HTTP-VERSION"
1275 >+downgrade-http-version</I
1281 CLASS="VARIABLELIST"
1295 >"+downgrade-http-version"</SPAN
1296 > will downgrade HTTP/1.1 client requests to
1297 HTTP/1.0 and downgrade the responses as well.
1301 >Possible values:</DT
1311 CLASS="LITERALLAYOUT"
1312 > <I
1314 >{+downgrade-http-version}</I
1316 <I
1320 </P
1326 > Use this action for servers that use HTTP/1.1 protocol features that
1330 > doesn't handle well yet. HTTP/1.1 is
1331 only partially implemented. Default is not to downgrade requests. This is
1332 an infrequently needed action, and is used to help with rare problem sites only.
1343 NAME="FAST-REDIRECTS"
1352 CLASS="VARIABLELIST"
1366 >"+fast-redirects"</SPAN
1367 > action enables interception of
1371 > requests from one server to another, which
1372 are used to track users.<SPAN
1376 all but the last valid URL in a redirect request and send a local redirect
1377 back to your browser without contacting the intermediate site(s).
1381 >Possible values:</DT
1391 CLASS="LITERALLAYOUT"
1392 > <I
1394 >{+fast-redirects}</I
1396 <I
1400 </P
1407 Many sites, like yahoo.com, don't just link to other sites. Instead, they
1408 will link to some script on their own server, giving the destination as a
1409 parameter, which will then redirect you to the final target. URLs
1410 resulting from this scheme typically look like:
1413 >http://some.place/some_script?http://some.where-else</I
1417 > Sometimes, there are even multiple consecutive redirects encoded in the
1418 URL. These redirections via scripts make your web browsing more traceable,
1419 since the server from which you follow such a link can see where you go
1420 to. Apart from that, valuable bandwidth and time is wasted, while your
1421 browser ask the server for one redirect after the other. Plus, it feeds
1425 > This is a normally <SPAN
1428 > feature, and often requires exceptions
1429 for sites that are sensitive to defeating this mechanism.
1449 CLASS="VARIABLELIST"
1461 > Apply page filtering as defined by named sections of the
1465 > file to the specified site(s).
1469 > can be any modification of the raw
1470 page content, including re-writing or deletion of content.
1474 >Possible values:</DT
1480 > must include the name of one of the section identifiers
1488 > is specified in <TT
1495 >Example usage (from the current <TT
1508 NAME="FILTER-HTML-ANNOYANCES"
1513 >+filter{html-annoyances}</I
1514 >: Get rid of particularly annoying HTML abuse.
1529 NAME="FILTER-JS-ANNOYANCES"
1534 >+filter{js-annoyances}</I
1535 >: Get rid of particularly annoying JavaScript abuse
1550 NAME="FILTER-CONTENT-COOKIES"
1555 >+filter{content-cookies}</I
1556 >: Kill cookies that come in the HTML or JS content
1571 NAME="FILTER-POPUPS"
1577 >: Kill all popups in JS and HTML
1592 NAME="FILTER-FRAMESET-BORDERS"
1597 >+filter{frameset-borders}</I
1598 >: Give frames a border and make them resizable
1613 NAME="FILTER-WEBBUGS"
1618 >+filter{webbugs}</I
1619 >: Squish WebBugs (1x1 invisible GIFs used for user tracking)
1634 NAME="FILTER-REFRESH-TAGS"
1639 >+filter{refresh-tags}</I
1640 >: Kill automatic refresh tags (for dial-on-demand setups)
1661 >: Text replacements for subversive browsing fun!
1682 >: Remove Nimda (virus) code.
1697 NAME="FILTER-BANNERS-BY-SIZE"
1702 >+filter{banners-by-size}</I
1703 >: Kill banners by size (<I
1721 NAME="FILTER-SHOCKWAVE-FLASH"
1726 >+filter{shockwave-flash}</I
1727 >: Kill embedded Shockwave Flash objects
1742 NAME="FILTER-CRUDE-PARENTAL"
1747 >+filter{crude-parental}</I
1748 >: Kill all web pages that contain the words "sex" or "warez"
1760 > This is potentially a very powerful feature! And requires a knowledge
1761 of regular expressions if you want to <SPAN
1763 >"roll your own"</SPAN
1765 Filtering operates on a line by line basis throughout the entire page.
1768 > Filtering requires buffering the page content, which may appear to
1769 slow down page rendering since nothing is displayed until all content has
1770 passed the filters. (It does not really take longer, but seems that way
1771 since the page is not incrementally displayed.) This effect will be more
1772 noticeable on slower connections.
1775 > Filtering can achieve some of the effects as the
1777 HREF="actions-file#BLOCK"
1784 action, i.e. it can be used to block ads and banners. In the overall
1785 scheme of things, filtering is one of the first things <SPAN
1789 does with a web page. So other most other actions are applied to the
1804 NAME="HIDE-FORWARDED-FOR-HEADERS"
1807 >+hide-forwarded-for-headers</I
1813 CLASS="VARIABLELIST"
1825 > Block any existing X-Forwarded-for HTTP header, and do not add a new one.
1829 >Possible values:</DT
1839 CLASS="LITERALLAYOUT"
1840 > <I
1842 >{+hide-forwarded-for-headers}</I
1844 <I
1848 </P
1854 > It is fairly safe to leave this on. It does not seem to break many sites.
1865 NAME="HIDE-FROM-HEADER"
1868 >+hide-from-header</I
1874 CLASS="VARIABLELIST"
1886 > To block the browser from sending your email address in a <SPAN
1894 >Possible values:</DT
1900 >, or any user defined value.
1907 CLASS="LITERALLAYOUT"
1908 > <I
1910 >{+hide-from-header{block}}</I
1912 <I
1916 </P
1925 > will completely remove the header
1926 (not to be confused with the <A
1927 HREF="actions-file.html#BLOCK"
1934 Alternately, you can specify any value you prefer to send to the web
1953 NAME="HIDE-REFERRER"
1958 CLASS="VARIABLELIST"
1970 > Don't send the <SPAN
1973 > (sic) HTTP header to the web site.
1974 Or, alternately send a forged header instead.
1978 >Possible values:</DT
1981 > Prevent the header from being sent with the keyword, <SPAN
1988 > a URL to one from the same server as the request.
1989 Or, set to user defined value of your choice.
1996 CLASS="LITERALLAYOUT"
1997 > <I
1999 >{+hide-referer{forge}}</I
2001 <I
2005 </P
2014 > is the preferred option here, since some servers will
2015 not send images back otherwise.
2021 >"+hide-referrer"</SPAN
2022 > is an alternate spelling of
2025 >"+hide-referer"</SPAN
2026 >. It has the exact same parameters, and can be freely
2029 >"+hide-referer"</SPAN
2034 correct English spelling, however the HTTP specification has a bug - it
2035 requires it to be spelled as <SPAN
2049 NAME="HIDE-USER-AGENT"
2052 >+hide-user-agent</I
2058 CLASS="VARIABLELIST"
2070 > To change the <SPAN
2072 >"User-Agent:"</SPAN
2073 > header so web servers can't tell
2074 your browser type. Who's business is it anyway?
2078 >Possible values:</DT
2081 > Any user defined string.
2088 CLASS="LITERALLAYOUT"
2089 > <I
2091 >{+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}}</I
2093 <I
2097 </P
2103 > Warning! This breaks many web sites that depend on this in order
2104 to determine how the target browser will respond to various
2105 requests. Use with caution.
2116 NAME="HANDLE-AS-IMAGE"
2119 >+handle-as-image</I
2125 CLASS="VARIABLELIST"
2137 > To define what <SPAN
2141 automatically as an image, and is an important ingredient of how
2146 >Possible values:</DT
2156 CLASS="LITERALLAYOUT"
2157 > <I
2159 >{+handle-as-image}</I
2161 <I
2163 >/.*\.(gif|jpg|jpeg|png|bmp|ico)</I
2165 </P
2171 > This only has meaning if the URL (or pattern) also is
2175 >ed, in which case a user definable image can
2176 be sent rather than a HTML page. This is integral to the whole concept of
2177 ad blocking: the URL must match <I
2181 HREF="actions-file.html#BLOCK"
2193 >"+handle-as-image"</SPAN
2196 HREF="actions-file.html#SET-IMAGE-BLOCKER"
2200 >"+set-image-blocker"</SPAN
2203 below for control over what will actually be displayed by the browser.)
2206 > There is little reason to change the default definition for this action.
2217 NAME="SET-IMAGE-BLOCKER"
2220 >+set-image-blocker</I
2226 CLASS="VARIABLELIST"
2238 > Decide what to do with URLs that end up tagged with <I
2243 HREF="actions-file.html#BLOCK"
2251 HREF="actions-file.html#HANDLE-AS-IMAGE"
2255 >"+handle-as-image"</SPAN
2258 e.g an advertisement.
2262 >Possible values:</DT
2265 > There are four available options: <SPAN
2267 >"-set-image-blocker"</SPAN
2272 > page, usually resulting in a <SPAN
2279 >"+set-image-blocker{<I
2284 1x1 transparent GIF image.
2287 >"+set-image-blocker{<I
2292 checkerboard type pattern (the default). And finally,
2295 >"+set-image-blocker{<I
2300 send a HTTP temporary redirect to the specified image. This has the
2301 advantage of the icon being being cached by the browser, which will speed
2309 CLASS="LITERALLAYOUT"
2310 > <I
2312 >{+set-image-blocker{blank}}</I
2314 <I
2318 </P
2327 > ads, they need to meet
2328 criteria as matching both <I
2335 actions. And then, <SPAN
2337 >"image-blocker"</SPAN
2342 > for invisibility. Note you cannot treat HTML pages as
2343 images in most cases. For instance, frames require an HTML page to
2344 display. So a frame that is an ad, typically cannot be treated as an image.
2348 > in this situation just will not work
2360 NAME="LIMIT-CONNECT"
2369 CLASS="VARIABLELIST"
2384 > only allows HTTP CONNECT
2385 requests to port 443 (the standard, secure HTTPS port). Use
2388 >"+limit-connect"</SPAN
2389 > to disable this altogether, or to allow
2394 >Possible values:</DT
2397 > Any valid port number, or port number range.
2401 >Example usages:</DT
2404 CLASS="LITERALLAYOUT"
2405 > <I
2407 >+limit-connect{443}</I
2408 > # This is the default and need not be specified.<br>
2409 <I
2411 >+limit-connect{80,443}</I
2412 > # Ports 80 and 443 are OK.<br>
2413 <I
2415 >+limit-connect{-3, 7, 20-100, 500-}</I
2416 > # Port less than 3, 7, 20 to 100 and above 500 are OK.<br>
2417 </P
2423 > The CONNECT methods exists in HTTP to allow access to secure websites
2424 (https:// URLs) through proxies. It works very simply: the proxy connects
2425 to the server on the specified port, and then short-circuits its
2426 connections to the client <I
2429 > to the remote proxy.
2430 This can be a big security hole, since CONNECT-enabled proxies can be
2431 abused as TCP relays very easily.
2435 If you want to allow CONNECT for more ports than this, or want to forbid
2436 CONNECT altogether, you can specify a comma separated list of ports and
2437 port ranges (the latter using dashes, with the minimum defaulting to 0 and
2441 > If you don't know what any of this means, there probably is no reason to
2453 NAME="PREVENT-COMPRESSION"
2456 >+prevent-compression</I
2462 CLASS="VARIABLELIST"
2474 > Prevent the specified websites from compressing HTTP data.
2478 >Possible values:</DT
2488 CLASS="LITERALLAYOUT"
2489 > <I
2491 >{+prevent-compression}</I
2493 <I
2497 </P
2503 > Some websites do this, which can be a problem for
2509 HREF="actions-file.html#FILTER"
2517 HREF="actions-file.html#KILL-POPUPS"
2521 >"+kill-popups"</SPAN
2525 HREF="actions-file.html#GIF-DEANIMATE"
2529 >"+gif-deanimate"</SPAN
2532 will not work on compressed data. This will slow down connections to those
2533 websites, though. Default typically is to turn
2536 >"prevent-compression"</SPAN
2548 NAME="SESSION-COOKIES-ONLY"
2551 >+session-cookies-only</I
2557 CLASS="VARIABLELIST"
2569 > Allow cookies for the current browser session <I
2576 >Possible values:</DT
2583 >Example usage (disabling):</DT
2586 CLASS="LITERALLAYOUT"
2587 > <I
2589 >{-session-cookies-only}</I
2591 <I
2595 </P
2601 > If websites set cookies, <SPAN
2603 >"+session-cookies-only"</SPAN
2605 they are erased when you exit and restart your web browser. This makes
2606 profiling cookies useless, but won't break sites which require cookies so
2607 that you can log in for transactions. This is generally turned on for all
2608 sites, and is the recommended setting.
2613 >"+prevent-*-cookies"</SPAN
2614 > actions should be turned off as well (see
2617 >"+session-cookies-only"</SPAN
2618 > to work. Or, else no cookies
2619 will get through at all. For, <SPAN
2622 > cookies that survive
2623 across browser sessions, see below as well.
2634 NAME="PREVENT-READING-COOKIES"
2637 >+prevent-reading-cookies</I
2643 CLASS="VARIABLELIST"
2655 > Explicitly prevent the web server from reading any cookies on your
2660 >Possible values:</DT
2670 CLASS="LITERALLAYOUT"
2671 > <I
2673 >{+prevent-reading-cookies}</I
2675 <I
2679 </P
2685 > Often used in conjunction with <SPAN
2687 >"+prevent-setting-cookies"</SPAN
2689 disable cookies completely. Note that
2691 HREF="actions-file.html#SESSION-COOKIES-ONLY"
2695 >"+session-cookies-only"</SPAN
2698 requires these to both be disabled (or else it never gets any cookies to cache).
2704 > cookies to work (i.e. they survive across browser
2705 sessions and reboots), all three cookie settings should be <SPAN
2709 for the specified sites.
2720 NAME="PREVENT-SETTING-COOKIES"
2723 >+prevent-setting-cookies</I
2729 CLASS="VARIABLELIST"
2741 > Explicitly block the web server from storing cookies on your
2746 >Possible values:</DT
2756 CLASS="LITERALLAYOUT"
2757 > <I
2759 >{+prevent-setting-cookies}</I
2761 <I
2765 </P
2771 > Often used in conjunction with <SPAN
2773 >"+prevent-reading-cookies"</SPAN
2775 disable cookies completely (see above).
2798 CLASS="VARIABLELIST"
2810 > Stop those annoying JavaScript pop-up windows!
2814 >Possible values:</DT
2824 CLASS="LITERALLAYOUT"
2825 > <I
2829 <I
2833 </P
2841 >"+kill-popups"</SPAN
2842 > uses a built in filter to disable pop-ups
2846 > function, etc. This is
2847 one of the first actions processed by <SPAN
2851 as it contacts the remote web server. This action is not always 100% reliable,
2852 and is supplemented by <SPAN
2869 NAME="SEND-VANILLA-WAFER"
2872 >+send-vanilla-wafer</I
2878 CLASS="VARIABLELIST"
2890 > Sends a cookie for every site stating that you do not accept any copyright
2891 on cookies sent to you, and asking them not to track you.
2895 >Possible values:</DT
2905 CLASS="LITERALLAYOUT"
2906 > <I
2908 >{+send-vanilla-wafer}</I
2910 <I
2914 </P
2920 > This action only applies if you are using a <TT
2924 for saving cookies. Of course, this is a (relatively) unique header and
2925 could conceivably be used to track you.
2945 CLASS="VARIABLELIST"
2957 > This allows you to send an arbitrary, user definable cookie.
2961 >Possible values:</DT
2964 > User specified cookie name and corresponding value.
2971 CLASS="LITERALLAYOUT"
2972 > <I
2974 >{+send-wafer{name=value}}</I
2976 <I
2980 </P
2986 > This can be specified multiple times in order to add as many cookies as you
3002 > Note that many of these actions have the potential to cause a page to
3003 misbehave, possibly even not to display at all. There are many ways
3004 a site designer may choose to design his site, and what HTTP header
3005 content, and other criteria, he may depend on. There is no way to have hard
3006 and fast rules for all sites. See the <A
3007 HREF="appendix.html#ACTIONSANAT"
3009 > for a brief example on troubleshooting
3018 >8.5.22. Sample Actions Files</A
3021 > Remember that the meaning of any of the above references is reversed by preceding
3022 the action with a <SPAN
3025 >, in place of the <SPAN
3029 that some actions are turned on in the default section of the actions file,
3030 and require little to no additional configuration. These are just <SPAN
3035 > But, other actions that are turned on in the default section <I
3038 typically require</I
3039 > exceptions to be listed in the latter sections of
3040 one of our actions file. For instance, by default no URLs are
3044 > (i.e. in the default definitions of
3048 >). We need exceptions to this in order to
3052 > ad blocking in the lower sections. But we need to
3053 be very selective about what we do block. Thus, the default is <SPAN
3059 > Below is a liberally commented sample <TT
3063 to demonstrate how all the pieces come together. And to show how exceptions
3064 to the default policies can be handled. This is followed by a brief
3068 > with similar examples.</P
3073 CLASS="LITERALLAYOUT"
3074 ># Sample default.action file <developers@privoxy.org><br>
3076 # Settings -- Don't change! For internal Privoxy use ONLY.<br>
3078 for-privoxy-version=3.0<br>
3081 ##########################################################################<br>
3083 HREF="actions-file.html#ALIASES"
3086 > must be defined *before* they are used. These are<br>
3087 # easier to remember, and can combine several actions into one. Once <br>
3088 # defined they can be used just like any built-in action -- but within <br>
3089 # this file only! Aliases do not require a + or - sign.<br>
3090 ##########################################################################<br>
3092 # Some useful aliases.<br>
3093 # Alias to turn off cookie handling, ie allow all cookies unmolested.<br>
3094 -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \<br>
3095 -session-cookies-only<br>
3097 # Alias to both block and treat as if an image for ad blocking<br>
3098 # purposes.<br>
3099 +imageblock = +block +handle-as-image<br>
3101 # Fragile sites should have the minimum changes:<br>
3102 fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \<br>
3103 -prevent-cookies -kill-popups<br>
3105 # Shops should be allowed to set persistent cookies<br>
3106 shop = -filter -prevent-cookies -session-cookies-only<br>
3109 ##########################################################################<br>
3110 # Begin default action settings. Anything in this section will match <br>
3111 # all URLs -- UNLESS we have exceptions that also match, defined below this <br>
3112 # section. We will show all potential actions here whether they are on <br>
3113 # or off. We could omit any disabled action if we wanted, since all <br>
3114 # actions are 'off' by default anyway. Shown for completeness only.<br>
3115 # Actions are enabled if preceded by a '+', otherwise they are disabled <br>
3116 # (unless an alias has been defined without this).<br>
3117 ##########################################################################<br>
3120 HREF="actions-file.html#ADD-HEADER"
3125 HREF="actions-file.html#BLOCK"
3130 HREF="actions-file.html#DEANIMATE-GIFS"
3135 HREF="actions-file.html#DOWNGRADE-HTTP-VERSION"
3137 >-downgrade-http-version</A
3140 HREF="actions-file.html#FAST-REDIRECTS"
3145 HREF="actions-file.html#FILTER-HTML-ANNOYANCES"
3147 >+filter{html-annoyances}</A
3150 HREF="actions-file.html#FILTER-JS-ANNOYANCES"
3152 >+filter{js-annoyances}</A
3155 HREF="actions-file.html#FILTER-CONTENT-COOKIES"
3157 >-filter{content-cookies}</A
3160 HREF="actions-file.html#FILTER-POPUPS"
3165 HREF="actions-file.html#FILTER-WEBBUGS"
3167 >+filter{webbugs}</A
3170 HREF="actions-file.html#FILTER-REFRESH-TAGS"
3172 >-filter{refresh-tags}</A
3175 HREF="actions-file.html#FILTER-FUN"
3180 HREF="actions-file.html#FILTER-NIMDA"
3185 HREF="actions-file.html#FILTER-BANNERS-BY-SIZE"
3187 >+filter{banners-by-size}</A
3190 HREF="actions-file.html#FILTER-SHOCKWAVE-FLASH"
3192 >-filter{shockwave-flash}</A
3195 HREF="actions-file.html#FILTER-CRUDE-PARENTAL"
3197 >-filter{crude-prental}</A
3200 HREF="actions-file.html#HIDE-FORWARDED-FOR-HEADERS"
3202 >+hide-forwarded-for-headers</A
3205 HREF="actions-file.html#HIDE-FROM-HEADER"
3207 >+hide-from-header{block}</A
3210 HREF="actions-file.html#HIDE-REFERER"
3215 HREF="actions-file.html#HIDE-USER-AGENT"
3217 >-hide-user-agent</A
3220 HREF="actions-file.html#HANDLE-AS-IMAGE"
3222 >-handle-as-image</A
3225 HREF="actions-file.html#SET-IMAGE-BLOCKER"
3227 >+set-image-blocker{pattern}</A
3230 HREF="actions-file.html#LIMIT-CONNECT"
3235 HREF="actions-file.html#PREVENT-COMPRESSION"
3237 >+prevent-compression</A
3240 HREF="actions-file.html#SESSION-COOKIES-ONLY"
3242 >-session-cookies-only</A
3245 HREF="actions-file.html#PREVENT-READING-COOKIES"
3247 >-prevent-reading-cookies</A
3250 HREF="actions-file.html#PREVENT-SETTING-COOKIES"
3252 >-prevent-setting-cookies</A
3255 HREF="actions-file.html#KILL-POPUPS"
3260 HREF="actions-file.html#SEND-VANILLA-WAFER"
3262 >-send-vanilla-wafer</A
3265 HREF="actions-file.html#SEND-WAFER"
3270 / # forward slash will match *all* potential URL patterns. <br>
3272 ##########################################################################<br>
3273 # Default behavior is now set. Now we will define some exceptions to our <br>
3274 # default action policies.<br>
3275 ##########################################################################<br>
3277 # These sites are very complex and require very minimal interference.<br>
3278 # We'll disable most actions with our 'fragile' alias:<br>
3279 { fragile }<br>
3280 .office.microsoft.com # surprise, surprise!<br>
3281 .windowsupdate.microsoft.com<br>
3284 # Shopping sites - not as fragile but require some special <br>
3285 # handling. We still want to block ads, and we will allow <br>
3286 # persistant cookies via the 'shop' alias:<br>
3287 { shop }<br>
3288 .quietpc.com <br>
3289 .worldpay.com # for quietpc.com<br>
3290 .jungle.com<br>
3291 .scan.co.uk<br>
3294 # These sites require pop-ups too :( We'll combine our 'shop' <br>
3295 # alias with two other actions into one rule to allow all popups.<br>
3296 { shop <A
3297 HREF="actions-file.html#KILL-POPUPS"
3301 HREF="actions-file.html#FILTER-POPUPS"
3306 .overclockers.co.uk<br>
3309 # The 'Fast-redirects' action breaks some sites. Disable this action<br>
3310 # for these known sensitive sites:<br>
3312 HREF="actions-file.html#FAST-REDIRECTS"
3316 login.yahoo.com<br>
3317 edit.europe.yahoo.com<br>
3318 .google.com<br>
3319 .altavista.com/.*(like|url|link):http<br>
3320 .altavista.com/trans.*urltext=http<br>
3321 .nytimes.com<br>
3324 # Define which file types will be treated as images. Important<br>
3325 # for ad blocking.<br>
3327 HREF="actions-file.html#HANDLE-AS-IMAGE"
3329 >+handle-as-image</A
3331 /.*\.(gif|jpe?g|png|bmp|ico)<br>
3334 # Now lets list some domains that are known ad generators. And<br>
3335 # our alias that we use here will block these as well as force <br>
3336 # them to be treated as images. This combination of actions is <br>
3337 # important for ad blocking. What the browser will show instead is <br>
3338 # determined by the setting of <A
3339 HREF="actions-file.html#SET-IMAGE-BLOCKER"
3343 >"+set-image-blocker"</SPAN
3346 { +imageblock }<br>
3347 ar.atwola.com <br>
3348 .ad.doubleclick.net<br>
3349 .a.yimg.com/(?:(?!/i/).)*$<br>
3350 .a[0-9].yimg.com/(?:(?!/i/).)*$<br>
3351 bs*.gsanet.com<br>
3352 bs*.einets.com<br>
3353 .qkimg.net<br>
3354 ad.*.doubleclick.net<br>
3357 # These will just simply be blocked. They will generate the BLOCKED<br>
3358 # banner page, if matched. Heavy use of wildcards and regular <br>
3359 # expressions in this example. Enable block action:<br>
3361 HREF="actions-file.html#BLOCK"
3369 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)<br>
3370 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/<br>
3371 .hitbox.com <br>
3374 # The above block section will probably inadvertantly catch some <br>
3375 # sites we DO NOT want blocked via the wildcards and regular expressions. <br>
3376 # Now let's set exceptions to the exceptions so the good guys get better <br>
3377 # treatment. Disable block action:<br>
3379 HREF="actions-file.html#BLOCK"
3383 advogato.org<br>
3387 # Let's just trust all .edu top level domains.<br>
3389 www.ugu.com/sui/ugu/adv<br>
3390 # We'll need to access to path names containing 'download' <br>
3391 .*downloads.<br>
3392 /downloads/<br>
3393 # 'adv' is for globalintersec and means advanced, not advertisement<br>
3394 www.globalintersec.com/adv<br>
3397 # Don't filter *anything* from our friends at sourceforge.<br>
3398 # Notice we don't have to name the individual filter <br>
3399 # identifiers -- we just turn them all off in one fell swoop.<br>
3400 # Disable all filters for this one site:<br>
3402 HREF="actions-file.html#FILTER"
3406 .sourceforge.net<br>
3407 </P
3412 > So far we are painting with a broad brush by setting general policies.
3413 The above would be a reasonable starting point for many situations. Now,
3414 we want to be more specific and have customized rules that are more suitable
3415 to our personal habits and preferences. These would be for narrowly defined
3416 situations like your ISP or your bank, and should be placed in
3420 >, which is parsed after all other
3421 actions files and should not be clobbered by upgrades. So any settings here,
3422 will have the last word and over-ride any previously defined actions.</P
3424 > Now a few examples of some things that one might do with a
3433 CLASS="LITERALLAYOUT"
3434 ># Sample user.action file.<br>
3436 # Any aliases you want to use need to be re-defined here.<br>
3437 # Alias to turn off cookie handling, ie allow all cookies unmolested.<br>
3438 -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \<br>
3439 -session-cookies-only<br>
3441 # Fragile sites should have the minimum changes:<br>
3442 fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \<br>
3443 -prevent-cookies -kill-popups<br>
3445 # Allow persistent cookies for a few regular sites that we <br>
3446 # trust via our above alias. These will be saved from one browser session <br>
3447 # to the next. We are explicity turning off any and all cookie handling, <br>
3448 # even though the prevent-*-cookie settings were disabled in our above <br>
3449 # default.action anyway. So cookies from these domains will come through <br>
3450 # unmolested.<br>
3451 { -prevent-cookies }<br>
3453 .yahoo.com<br>
3454 .msdn.microsoft.com<br>
3455 .redhat.com<br>
3458 # My ISP uses obnoxious self promoting images on many pages.<br>
3459 # Nuke them :) Note that <A
3460 HREF="actions-file.html#HANDLE-AS-IMAGE"
3464 >"+handle-as-image"</SPAN
3466 > need not be specified,<br>
3467 # since all URLs ending in .gif will be tagged as images by the<br>
3468 # general rules in default.action anyway.<br>
3470 HREF="actions-file.html#BLOCK"
3474 www.my-isp-example.com/logo[0-9].gif<br>
3477 # Say the site where you do your homebanking needs to open<br>
3478 # popup windows, but you have chosen to kill popups by<br>
3479 # default. This will allow it for your-example-bank.com:<br>
3482 HREF="actions-file.html#FILTER-POPUPS"
3486 HREF="actions-file.html#KILL-POPUPS"
3490 .my-example-bank.com<br>
3493 # This site is delicate, and requires kid-glove <br>
3494 # treatment.<br>
3495 { fragile }<br>
3496 .forbes.com<br>
3497 </P
3522 >, can be defined by combining other <SPAN
3526 These can in turn be invoked just like the built-in <SPAN
3530 Currently, an alias can contain any character except space, tab, <SPAN
3540 >. But please use only <SPAN
3560 >. Alias names are not case sensitive, and
3563 >must be defined before other actions</I
3565 actions file! And there can only be one set of <SPAN
3569 defined per file. Each actions file may have its own aliases, but they are
3570 only visible within that file. Aliases do not requir a <SPAN
3577 > sign in front, since they are merely expanded.</P
3579 > Now let's define a few aliases:</P
3584 CLASS="LITERALLAYOUT"
3585 > # Useful custom aliases we can use later. These must come first!<br>
3587 +prevent-cookies = +prevent-setting-cookies +prevent-reading-cookies<br>
3588 -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies<br>
3589 fragile = -block -prevent-cookies -filter -fast-redirects -hide-referer -kill-popups<br>
3590 shop = -prevent-cookies -filter -fast-redirects<br>
3591 +imageblock = +block +handle-as-image<br>
3593 # Aliases defined from other aliases, for people who don't like to type <br>
3594 # too much: ;-)<br>
3595 c0 = +prevent-cookies<br>
3596 c1 = -prevent-cookies<br>
3597 #... etc. Customize to your heart's content.<br>
3598 </P
3603 > Some examples using our <SPAN
3610 aliases from above. These would appear in the lower sections of an
3611 actions file as exceptions to the default actions (as defined in the
3617 CLASS="LITERALLAYOUT"
3618 > # These sites are very complex and require<br>
3619 # minimal interference.<br>
3621 .office.microsoft.com<br>
3622 .windowsupdate.microsoft.com<br>
3623 .nytimes.com<br>
3625 # Shopping sites - but we still want to block ads.<br>
3627 .quietpc.com<br>
3628 .worldpay.com # for quietpc.com<br>
3629 .scan.co.uk<br>
3631 # These shops require pop-ups also <br>
3632 {shop -kill-popups}<br>
3633 .dabs.com<br>
3634 .overclockers.co.uk<br>
3635 </P
3646 > aliases are often used for
3650 > sites that require most actions to be disabled
3651 in order to function properly. </P
3685 HREF="filter-file.html"
3694 >The Main Configuration File</TD
3704 >The Filter File</TD
projects / privoxy.git / blob