1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
5 <meta name="generator" content="HTML Tidy, see www.w3.org">
9 <meta name="GENERATOR" content=
10 "Modular DocBook HTML Stylesheet Version 1.79">
11 <link rel="HOME" title="Privoxy 3.0.18 User Manual" href="index.html">
12 <link rel="PREVIOUS" title="The Main Configuration File" href=
14 <link rel="NEXT" title="Filter Files" href="filter-file.html">
15 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
16 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
17 <link rel="STYLESHEET" type="text/css" href="p_doc.css">
18 <style type="text/css">
20 background-color: #EEEEEE;
23 :link { color: #0000FF }
24 :visited { color: #840084 }
25 :active { color: #0000FF }
26 p.c2 {font-weight: bold}
27 hr.c1 {text-align: left}
31 <div class="NAVHEADER">
32 <table summary="Header navigation table" width="100%" border="0"
33 cellpadding="0" cellspacing="0">
35 <th colspan="3" align="center">
36 Privoxy 3.0.18 User Manual
40 <td width="10%" align="left" valign="bottom">
41 <a href="config.html" accesskey="P">Prev</a>
43 <td width="80%" align="center" valign="bottom">
45 <td width="10%" align="right" valign="bottom">
46 <a href="filter-file.html" accesskey="N">Next</a>
50 <hr width="100%" class="c1">
54 <a name="ACTIONS-FILE">8. Actions Files</a>
57 The actions files are used to define what <span class="emphasis"><i
58 class="EMPHASIS">actions</i></span> <span class=
59 "APPLICATION">Privoxy</span> takes for which URLs, and thus
60 determines how ad images, cookies and various other aspects of HTTP
61 content and transactions are handled, and on which sites (or even
62 parts thereof). There are a number of such actions, with a wide range
63 of functionality. Each action does something a little different.
64 These actions give us a veritable arsenal of tools with which to
65 exert our control, preferences and independence. Actions can be
66 combined so that their effects are aggregated when applied against a
70 There are three action files included with <span class=
71 "APPLICATION">Privoxy</span> with differing purposes:
78 <tt class="FILENAME">match-all.action</tt> - is used to define
79 which <span class="QUOTE">"actions"</span> relating to
80 banner-blocking, images, pop-ups, content modification, cookie
81 handling etc should be applied by default. It should be the first
87 <tt class="FILENAME">default.action</tt> - defines many
88 exceptions (both positive and negative) from the default set of
89 actions that's configured in <tt class=
90 "FILENAME">match-all.action</tt>. It is a set of rules that
91 should work reasonably well as-is for most users. This file is
92 only supposed to be edited by the developers. It should be the
93 second actions file loaded.
98 <tt class="FILENAME">user.action</tt> - is intended to be for
99 local site preferences and exceptions. As an example, if your ISP
100 or your bank has specific requirements, and need special
101 handling, this kind of thing should go here. This file will not
107 <span class="GUIBUTTON">Edit</span> <span class="GUIBUTTON">Set
108 to Cautious</span> <span class="GUIBUTTON">Set to Medium</span>
109 <span class="GUIBUTTON">Set to Advanced</span>
112 These have increasing levels of aggressiveness <span class=
113 "emphasis"><i class="EMPHASIS">and have no influence on your
114 browsing unless you select them explicitly in the
115 editor</i></span>. A default installation should be pre-set to
116 <tt class="LITERAL">Cautious</tt>. New users should try this for
117 a while before adjusting the settings to more aggressive levels.
118 The more aggressive the settings, then the more likelihood there
119 is of problems such as sites not working as they should.
122 The <span class="GUIBUTTON">Edit</span> button allows you to turn
123 each action on/off individually for fine-tuning. The <span class=
124 "GUIBUTTON">Cautious</span> button changes the actions list to
125 low/safe settings which will activate ad blocking and a minimal
126 set of <span class="APPLICATION">Privoxy</span>'s features, and
127 subsequently there will be less of a chance for accidental
128 problems. The <span class="GUIBUTTON">Medium</span> button sets
129 the list to a medium level of other features and a low level set
130 of privacy features. The <span class="GUIBUTTON">Advanced</span>
131 button sets the list to a high level of ad blocking and medium
132 level of privacy. See the chart below. The latter three buttons
133 over-ride any changes via with the <span class=
134 "GUIBUTTON">Edit</span> button. More fine-tuning can be done in
135 the lower sections of this internal page.
138 While the actions file editor allows to enable these settings in
139 all actions files, they are only supposed to be enabled in the
140 first one to make sure you don't unintentionally overrule earlier
144 The default profiles, and their associated actions, as
145 pre-defined in <tt class="FILENAME">default.action</tt> are:
150 <a name="AEN2625"></a>
152 Table 1. Default Configurations
154 <table border="1" frame="border" rules="all" class="CALSTABLE">
155 <col width="1*" title="C1">
156 <col width="1*" title="C2">
157 <col width="1*" title="C3">
158 <col width="1*" title="C4">
178 Ad-blocking Aggressiveness
365 The list of actions files to be used are defined in the main
366 configuration file, and are processed in the order they are defined
367 (e.g. <tt class="FILENAME">default.action</tt> is typically processed
368 before <tt class="FILENAME">user.action</tt>). The content of these
369 can all be viewed and edited from <a href=
370 "http://config.privoxy.org/show-status" target=
371 "_top">http://config.privoxy.org/show-status</a>. The over-riding
372 principle when applying actions, is that the last action that matches
373 a given URL wins. The broadest, most general rules go first (defined
374 in <tt class="FILENAME">default.action</tt>), followed by any
375 exceptions (typically also in <tt class=
376 "FILENAME">default.action</tt>), which are then followed lastly by
377 any local preferences (typically in <span class="emphasis"><i class=
378 "EMPHASIS">user</i></span><tt class="FILENAME">.action</tt>).
379 Generally, <tt class="FILENAME">user.action</tt> has the last word.
382 An actions file typically has multiple sections. If you want to use
383 <span class="QUOTE">"aliases"</span> in an actions file, you have to
384 place the (optional) <a href="actions-file.html#ALIASES">alias
385 section</a> at the top of that file. Then comes the default set of
386 rules which will apply universally to all sites and pages (be <span
387 class="emphasis"><i class="EMPHASIS">very careful</i></span> with
388 using such a universal set in <tt class="FILENAME">user.action</tt>
389 or any other actions file after <tt class=
390 "FILENAME">default.action</tt>, because it will override the result
391 from consulting any previous file). And then below that, exceptions
392 to the defined universal policies. You can regard <tt class=
393 "FILENAME">user.action</tt> as an appendix to <tt class=
394 "FILENAME">default.action</tt>, with the advantage that it is a
395 separate file, which makes preserving your personal settings across
396 <span class="APPLICATION">Privoxy</span> upgrades easier.
399 Actions can be used to block anything you want, including ads,
400 banners, or just some obnoxious URL whose content you would rather
401 not see. Cookies can be accepted or rejected, or accepted only during
402 the current browser session (i.e. not written to disk), content can
403 be modified, some JavaScripts tamed, user-tracking fooled, and much
404 more. See below for a <a href="actions-file.html#ACTIONS">complete
409 <a name="AEN2724">8.1. Finding the Right Mix</a>
412 Note that some <a href="actions-file.html#ACTIONS">actions</a>,
413 like cookie suppression or script disabling, may render some sites
414 unusable that rely on these techniques to work properly. Finding
415 the right mix of actions is not always easy and certainly a matter
416 of personal taste. And, things can always change, requiring
417 refinements in the configuration. In general, it can be said that
418 the more <span class="QUOTE">"aggressive"</span> your default
419 settings (in the top section of the actions file) are, the more
420 exceptions for <span class="QUOTE">"trusted"</span> sites you will
421 have to make later. If, for example, you want to crunch all cookies
422 per default, you'll have to make exceptions from that rule for
423 sites that you regularly use and that require cookies for actually
424 useful purposes, like maybe your bank, favorite shop, or newspaper.
427 We have tried to provide you with reasonable rules to start from in
428 the distribution actions files. But there is no general rule of
429 thumb on these things. There just are too many variables, and sites
430 are constantly changing. Sooner or later you will want to change
431 the rules (and read this chapter again :).
436 <a name="AEN2731">8.2. How to Edit</a>
439 The easiest way to edit the actions files is with a browser by
440 using our browser-based editor, which can be reached from <a href=
441 "http://config.privoxy.org/show-status" target=
442 "_top">http://config.privoxy.org/show-status</a>. Note: the config
444 "config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions</a> must be
445 enabled for this to work. The editor allows both fine-grained
446 control over every single feature on a per-URL basis, and easy
447 choosing from wholesale sets of defaults like <span class=
448 "QUOTE">"Cautious"</span>, <span class="QUOTE">"Medium"</span> or
449 <span class="QUOTE">"Advanced"</span>. Warning: the <span class=
450 "QUOTE">"Advanced"</span> setting is more aggressive, and will be
451 more likely to cause problems for some sites. Experienced users
455 If you prefer plain text editing to GUIs, you can of course also
456 directly edit the the actions files with your favorite text editor.
457 Look at <tt class="FILENAME">default.action</tt> which is richly
458 commented with many good examples.
463 <a name="ACTIONS-APPLY">8.3. How Actions are Applied to
467 Actions files are divided into sections. There are special
468 sections, like the <span class="QUOTE">"<a href=
469 "actions-file.html#ALIASES">alias</a>"</span> sections which will
470 be discussed later. For now let's concentrate on regular sections:
471 They have a heading line (often split up to multiple lines for
472 readability) which consist of a list of actions, separated by
473 whitespace and enclosed in curly braces. Below that, there is a
474 list of URL and tag patterns, each on a separate line.
477 To determine which actions apply to a request, the URL of the
478 request is compared to all URL patterns in each <span class=
479 "QUOTE">"action file"</span>. Every time it matches, the list of
480 applicable actions for the request is incrementally updated, using
481 the heading of the section in which the pattern is located. The
482 same is done again for tags and tag patterns later on.
485 If multiple applying sections set the same action differently, the
486 last match wins. If not, the effects are aggregated. E.g. a URL
487 might match a regular section with a heading line of <tt class=
488 "LITERAL">{ +<a href=
489 "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a> }</tt>,
490 then later another one with just <tt class="LITERAL">{ +<a href=
491 "actions-file.html#BLOCK">block</a> }</tt>, resulting in <span
492 class="emphasis"><i class="EMPHASIS">both</i></span> actions to
493 apply. And there may well be cases where you will want to combine
494 actions together. Such a section then might look like:
498 <table border="0" bgcolor="#E0E0E0" width="100%">
502 { +<tt class="LITERAL">handle-as-image</tt> +<tt class=
503 "LITERAL">block{Banner ads.}</tt> }
504 # Block these as if they were images. Send no block page.
506 media.example.com/.*banners
507 .example.com/images/ads/
514 You can trace this process for URL patterns and any given URL by
515 visiting <a href="http://config.privoxy.org/show-url-info" target=
516 "_top">http://config.privoxy.org/show-url-info</a>.
519 Examples and more detail on this is provided in the Appendix, <a
520 href="appendix.html#ACTIONSANAT">Troubleshooting: Anatomy of an
526 <a name="AF-PATTERNS">8.4. Patterns</a>
529 As mentioned, <span class="APPLICATION">Privoxy</span> uses <span
530 class="QUOTE">"patterns"</span> to determine what <span class=
531 "emphasis"><i class="EMPHASIS">actions</i></span> might apply to
532 which sites and pages your browser attempts to access. These <span
533 class="QUOTE">"patterns"</span> use wild card type <span class=
534 "emphasis"><i class="EMPHASIS">pattern</i></span> matching to
535 achieve a high degree of flexibility. This allows one expression to
536 be expanded and potentially match against many similar patterns.
539 Generally, an URL pattern has the form <tt class=
540 "LITERAL"><domain><port>/<path></tt>, where the
541 <tt class="LITERAL"><domain></tt>, the <tt class=
542 "LITERAL"><port></tt> and the <tt class=
543 "LITERAL"><path></tt> are optional. (This is why the special
544 <tt class="LITERAL">/</tt> pattern matches all URLs). Note that the
545 protocol portion of the URL pattern (e.g. <tt class=
546 "LITERAL">http://</tt>) should <span class="emphasis"><i class=
547 "EMPHASIS">not</i></span> be included in the pattern. This is
551 The pattern matching syntax is different for the domain and path
552 parts of the URL. The domain part uses a simple globbing type
553 matching technique, while the path part uses more flexible <a href=
554 "http://en.wikipedia.org/wiki/Regular_expressions" target=
555 "_top"><span class="QUOTE">"Regular Expressions"</span></a> (POSIX
559 The port part of a pattern is a decimal port number preceded by a
560 colon (<tt class="LITERAL">:</tt>). If the domain part contains a
561 numerical IPv6 address, it has to be put into angle brackets (<tt
562 class="LITERAL"><</tt>, <tt class="LITERAL">></tt>).
564 <div class="VARIABLELIST">
567 <tt class="LITERAL">www.example.com/</tt>
571 is a domain-only pattern and will match any request to <tt
572 class="LITERAL">www.example.com</tt>, regardless of which
573 document on that server is requested. So ALL pages in this
574 domain would be covered by the scope of this action. Note
575 that a simple <tt class="LITERAL">example.com</tt> is
576 different and would NOT match.
580 <tt class="LITERAL">www.example.com</tt>
584 means exactly the same. For domain-only patterns, the
585 trailing <tt class="LITERAL">/</tt> may be omitted.
589 <tt class="LITERAL">www.example.com/index.html</tt>
593 matches all the documents on <tt class=
594 "LITERAL">www.example.com</tt> whose name starts with <tt
595 class="LITERAL">/index.html</tt>.
599 <tt class="LITERAL">www.example.com/index.html$</tt>
603 matches only the single document <tt class=
604 "LITERAL">/index.html</tt> on <tt class=
605 "LITERAL">www.example.com</tt>.
609 <tt class="LITERAL">/index.html$</tt>
613 matches the document <tt class="LITERAL">/index.html</tt>,
614 regardless of the domain, i.e. on <span class="emphasis"><i
615 class="EMPHASIS">any</i></span> web server anywhere.
619 <tt class="LITERAL">/</tt>
623 Matches any URL because there's no requirement for either the
624 domain or the path to match anything.
628 <tt class="LITERAL">:8000/</tt>
632 Matches any URL pointing to TCP port 8000.
636 <tt class="LITERAL"><2001:db8::1>/</tt>
640 Matches any URL with the host address <tt class=
641 "LITERAL">2001:db8::1</tt>. (Note that the real URL uses
642 plain brackets, not angle brackets.)
646 <tt class="LITERAL">index.html</tt>
650 matches nothing, since it would be interpreted as a domain
651 name and there is no top-level domain called <tt class=
652 "LITERAL">.html</tt>. So its a mistake.
659 <a name="AEN2843">8.4.1. The Domain Pattern</a>
662 The matching of the domain part offers some flexible options: if
663 the domain starts or ends with a dot, it becomes unanchored at
664 that end. For example:
666 <div class="VARIABLELIST">
669 <tt class="LITERAL">.example.com</tt>
673 matches any domain with first-level domain <tt class=
674 "LITERAL">com</tt> and second-level domain <tt class=
675 "LITERAL">example</tt>. For example <tt class=
676 "LITERAL">www.example.com</tt>, <tt class=
677 "LITERAL">example.com</tt> and <tt class=
678 "LITERAL">foo.bar.baz.example.com</tt>. Note that it
679 wouldn't match if the second-level domain was <tt class=
680 "LITERAL">another-example</tt>.
684 <tt class="LITERAL">www.</tt>
688 matches any domain that <span class="emphasis"><i class=
689 "EMPHASIS">STARTS</i></span> with <tt class=
690 "LITERAL">www.</tt> (It also matches the domain <tt class=
691 "LITERAL">www</tt> but most of the time that doesn't
696 <tt class="LITERAL">.example.</tt>
700 matches any domain that <span class="emphasis"><i class=
701 "EMPHASIS">CONTAINS</i></span> <tt class=
702 "LITERAL">.example.</tt>. And, by the way, also included
703 would be any files or documents that exist within that
704 domain since no path limitations are specified. (Correctly
705 speaking: It matches any FQDN that contains <tt class=
706 "LITERAL">example</tt> as a domain.) This might be <tt
707 class="LITERAL">www.example.com</tt>, <tt class=
708 "LITERAL">news.example.de</tt>, or <tt class=
709 "LITERAL">www.example.net/cgi/testing.pl</tt> for instance.
710 All these cases are matched.
716 Additionally, there are wild-cards that you can use in the domain
717 names themselves. These work similarly to shell globbing type
718 wild-cards: <span class="QUOTE">"*"</span> represents zero or
719 more arbitrary characters (this is equivalent to the <a href=
720 "http://en.wikipedia.org/wiki/Regular_expressions" target=
721 "_top"><span class="QUOTE">"Regular Expression"</span></a> based
722 syntax of <span class="QUOTE">".*"</span>), <span class=
723 "QUOTE">"?"</span> represents any single character (this is
724 equivalent to the regular expression syntax of a simple <span
725 class="QUOTE">"."</span>), and you can define <span class=
726 "QUOTE">"character classes"</span> in square brackets which is
727 similar to the same regular expression technique. All of this can
730 <div class="VARIABLELIST">
733 <tt class="LITERAL">ad*.example.com</tt>
737 matches <span class="QUOTE">"adserver.example.com"</span>,
738 <span class="QUOTE">"ads.example.com"</span>, etc but not
739 <span class="QUOTE">"sfads.example.com"</span>
743 <tt class="LITERAL">*ad*.example.com</tt>
747 matches all of the above, and then some.
751 <tt class="LITERAL">.?pix.com</tt>
755 matches <tt class="LITERAL">www.ipix.com</tt>, <tt class=
756 "LITERAL">pictures.epix.com</tt>, <tt class=
757 "LITERAL">a.b.c.d.e.upix.com</tt> etc.
761 <tt class="LITERAL">www[1-9a-ez].example.c*</tt>
765 matches <tt class="LITERAL">www1.example.com</tt>, <tt
766 class="LITERAL">www4.example.cc</tt>, <tt class=
767 "LITERAL">wwwd.example.cy</tt>, <tt class=
768 "LITERAL">wwwz.example.com</tt> etc., but <span class=
769 "emphasis"><i class="EMPHASIS">not</i></span> <tt class=
770 "LITERAL">wwww.example.com</tt>.
776 While flexible, this is not the sophistication of full regular
777 expression based syntax.
782 <a name="AEN2919">8.4.2. The Path Pattern</a>
785 <span class="APPLICATION">Privoxy</span> uses <span class=
786 "QUOTE">"modern"</span> POSIX 1003.2 <a href=
787 "http://en.wikipedia.org/wiki/Regular_expressions" target=
788 "_top"><span class="QUOTE">"Regular Expressions"</span></a> for
789 matching the path portion (after the slash), and is thus more
793 There is an <a href="appendix.html#REGEX">Appendix</a> with a
794 brief quick-start into regular expressions, you also might want
795 to have a look at your operating system's documentation on
796 regular expressions (try <tt class="LITERAL">man re_format</tt>).
799 Note that the path pattern is automatically left-anchored at the
800 <span class="QUOTE">"/"</span>, i.e. it matches as if it would
801 start with a <span class="QUOTE">"^"</span> (regular expression
802 speak for the beginning of a line).
805 Please also note that matching in the path is <span class=
806 "emphasis"><i class="EMPHASIS">CASE INSENSITIVE</i></span> by
807 default, but you can switch to case sensitive at any point in the
808 pattern by using the <span class="QUOTE">"(?-i)"</span> switch:
809 <tt class="LITERAL">www.example.com/(?-i)PaTtErN.*</tt> will
810 match only documents whose path starts with <tt class=
811 "LITERAL">PaTtErN</tt> in <span class="emphasis"><i class=
812 "EMPHASIS">exactly</i></span> this capitalization.
814 <div class="VARIABLELIST">
817 <tt class="LITERAL">.example.com/.*</tt>
821 Is equivalent to just <span class=
822 "QUOTE">".example.com"</span>, since any documents within
823 that domain are matched with or without the <span class=
824 "QUOTE">".*"</span> regular expression. This is redundant
828 <tt class="LITERAL">.example.com/.*/index.html$</tt>
832 Will match any page in the domain of <span class=
833 "QUOTE">"example.com"</span> that is named <span class=
834 "QUOTE">"index.html"</span>, and that is part of some path.
835 For example, it matches <span class=
836 "QUOTE">"www.example.com/testing/index.html"</span> but NOT
837 <span class="QUOTE">"www.example.com/index.html"</span>
838 because the regular expression called for at least two
839 <span class="QUOTE">"/'s"</span>, thus the path
840 requirement. It also would match <span class=
841 "QUOTE">"www.example.com/testing/index_html"</span>,
842 because of the special meta-character <span class=
847 <tt class="LITERAL">.example.com/(.*/)?index\.html$</tt>
851 This regular expression is conditional so it will match any
852 page named <span class="QUOTE">"index.html"</span>
853 regardless of path which in this case can have one or more
854 <span class="QUOTE">"/'s"</span>. And this one must contain
855 exactly <span class="QUOTE">".html"</span> (but does not
856 have to end with that!).
861 "LITERAL">.example.com/(.*/)(ads|banners?|junk)</tt>
865 This regular expression will match any path of <span class=
866 "QUOTE">"example.com"</span> that contains any of the words
867 <span class="QUOTE">"ads"</span>, <span class=
868 "QUOTE">"banner"</span>, <span class=
869 "QUOTE">"banners"</span> (because of the <span class=
870 "QUOTE">"?"</span>) or <span class="QUOTE">"junk"</span>.
871 The path does not have to end in these words, just contain
877 "LITERAL">.example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$</tt>
881 This is very much the same as above, except now it must end
882 in either <span class="QUOTE">".jpg"</span>, <span class=
883 "QUOTE">".jpeg"</span>, <span class="QUOTE">".gif"</span>
884 or <span class="QUOTE">".png"</span>. So this one is
885 limited to common image formats.
891 There are many, many good examples to be found in <tt class=
892 "FILENAME">default.action</tt>, and more tutorials below in <a
893 href="appendix.html#REGEX">Appendix on regular expressions</a>.
898 <a name="TAG-PATTERN">8.4.3. The Tag Pattern</a>
901 Tag patterns are used to change the applying actions based on the
902 request's tags. Tags can be created with either the <a href=
903 "actions-file.html#CLIENT-HEADER-TAGGER">client-header-tagger</a>
905 "actions-file.html#SERVER-HEADER-TAGGER">server-header-tagger</a>
909 Tag patterns have to start with <span class=
910 "QUOTE">"TAG:"</span>, so <span class=
911 "APPLICATION">Privoxy</span> can tell them apart from URL
912 patterns. Everything after the colon including white space, is
913 interpreted as a regular expression with path pattern syntax,
914 except that tag patterns aren't left-anchored automatically
915 (<span class="APPLICATION">Privoxy</span> doesn't silently add a
916 <span class="QUOTE">"^"</span>, you have to do it yourself if you
920 To match all requests that are tagged with <span class=
921 "QUOTE">"foo"</span> your pattern line should be <span class=
922 "QUOTE">"TAG:^foo$"</span>, <span class="QUOTE">"TAG:foo"</span>
923 would work as well, but it would also match requests whose tags
924 contain <span class="QUOTE">"foo"</span> somewhere. <span class=
925 "QUOTE">"TAG: foo"</span> wouldn't work as it requires white
929 Sections can contain URL and tag patterns at the same time, but
930 tag patterns are checked after the URL patterns and thus always
931 overrule them, even if they are located before the URL patterns.
934 Once a new tag is added, Privoxy checks right away if it's
935 matched by one of the tag patterns and updates the action
936 settings accordingly. As a result tags can be used to activate
937 other tagger actions, as long as these other taggers look for
938 headers that haven't already be parsed.
941 For example you could tag client requests which use the <tt
942 class="LITERAL">POST</tt> method, then use this tag to activate
943 another tagger that adds a tag if cookies are sent, and then use
944 a block action based on the cookie tag. This allows the outcome
945 of one action, to be input into a subsequent action. However if
946 you'd reverse the position of the described taggers, and
947 activated the method tagger based on the cookie tagger, no method
948 tags would be created. The method tagger would look for the
949 request line, but at the time the cookie tag is created, the
950 request line has already been parsed.
953 While this is a limitation you should be aware of, this kind of
954 indirection is seldom needed anyway and even the example doesn't
961 <a name="ACTIONS">8.5. Actions</a>
964 All actions are disabled by default, until they are explicitly
965 enabled somewhere in an actions file. Actions are turned on if
966 preceded with a <span class="QUOTE">"+"</span>, and turned off if
967 preceded with a <span class="QUOTE">"-"</span>. So a <tt class=
968 "LITERAL">+action</tt> means <span class="QUOTE">"do that
969 action"</span>, e.g. <tt class="LITERAL">+block</tt> means <span
970 class="QUOTE">"please block URLs that match the following
971 patterns"</span>, and <tt class="LITERAL">-block</tt> means <span
972 class="QUOTE">"don't block URLs that match the following patterns,
973 even if <tt class="LITERAL">+block</tt> previously
974 applied."</span>
977 Again, actions are invoked by placing them on a line, enclosed in
978 curly braces and separated by whitespace, like in <tt class=
979 "LITERAL">{+some-action -some-other-action{some-parameter}}</tt>,
980 followed by a list of URL patterns, one per line, to which they
981 apply. Together, the actions line and the following pattern lines
982 make up a section of the actions file.
985 Actions fall into three categories:
992 Boolean, i.e the action can only be <span class=
993 "QUOTE">"enabled"</span> or <span class=
994 "QUOTE">"disabled"</span>. Syntax:
998 <table border="0" bgcolor="#E0E0E0" width="90%">
1001 <pre class="SCREEN">
1002 +<tt class="REPLACEABLE"><i>name</i></tt> # enable action <tt class=
1003 "REPLACEABLE"><i>name</i></tt>
1004 -<tt class="REPLACEABLE"><i>name</i></tt> # disable action <tt
1005 class="REPLACEABLE"><i>name</i></tt>
1012 Example: <tt class="LITERAL">+handle-as-image</tt>
1017 Parameterized, where some value is required in order to enable
1018 this type of action. Syntax:
1022 <table border="0" bgcolor="#E0E0E0" width="90%">
1025 <pre class="SCREEN">
1026 +<tt class="REPLACEABLE"><i>name</i></tt>{<tt class=
1027 "REPLACEABLE"><i>param</i></tt>} # enable action and set parameter to <tt
1028 class="REPLACEABLE"><i>param</i></tt>,
1029 # overwriting parameter from previous match if necessary
1031 "REPLACEABLE"><i>name</i></tt> # disable action. The parameter can be omitted
1038 Note that if the URL matches multiple positive forms of a
1039 parameterized action, the last match wins, i.e. the params from
1040 earlier matches are simply ignored.
1043 Example: <tt class="LITERAL">+hide-user-agent{Mozilla/5.0 (X11;
1044 U; FreeBSD i386; en-US; rv:1.8.1.4) Gecko/20070602
1045 Firefox/2.0.0.4}</tt>
1050 Multi-value. These look exactly like parameterized actions, but
1051 they behave differently: If the action applies multiple times
1052 to the same URL, but with different parameters, <span class=
1053 "emphasis"><i class="EMPHASIS">all</i></span> the parameters
1054 from <span class="emphasis"><i class="EMPHASIS">all</i></span>
1055 matches are remembered. This is used for actions that can be
1056 executed for the same request repeatedly, like adding multiple
1057 headers, or filtering through multiple filters. Syntax:
1061 <table border="0" bgcolor="#E0E0E0" width="90%">
1064 <pre class="SCREEN">
1065 +<tt class="REPLACEABLE"><i>name</i></tt>{<tt class=
1066 "REPLACEABLE"><i>param</i></tt>} # enable action and add <tt class=
1067 "REPLACEABLE"><i>param</i></tt> to the list of parameters
1068 -<tt class="REPLACEABLE"><i>name</i></tt>{<tt class=
1069 "REPLACEABLE"><i>param</i></tt>} # remove the parameter <tt class=
1070 "REPLACEABLE"><i>param</i></tt> from the list of parameters
1071 # If it was the last one left, disable the action.
1073 "REPLACEABLE"><i>-name</i></tt> # disable this action completely and remove all parameters from the list
1080 Examples: <tt class="LITERAL">+add-header{X-Fun-Header: Some
1081 text}</tt> and <tt class=
1082 "LITERAL">+filter{html-annoyances}</tt>
1088 If nothing is specified in any actions file, no <span class=
1089 "QUOTE">"actions"</span> are taken. So in this case <span class=
1090 "APPLICATION">Privoxy</span> would just be a normal, non-blocking,
1091 non-filtering proxy. You must specifically enable the privacy and
1092 blocking features you need (although the provided default actions
1093 files will give a good starting point).
1096 Later defined action sections always over-ride earlier ones of the
1097 same type. So exceptions to any rules you make, should come in the
1098 latter part of the file (or in a file that is processed later when
1099 using multiple actions files such as <tt class=
1100 "FILENAME">user.action</tt>). For multi-valued actions, the actions
1101 are applied in the order they are specified. Actions files are
1102 processed in the order they are defined in <tt class=
1103 "FILENAME">config</tt> (the default installation has three actions
1104 files). It also quite possible for any given URL to match more than
1105 one <span class="QUOTE">"pattern"</span> (because of wildcards and
1106 regular expressions), and thus to trigger more than one set of
1107 actions! Last match wins.
1110 The list of valid <span class="APPLICATION">Privoxy</span> actions
1115 <a name="ADD-HEADER">8.5.1. add-header</a>
1117 <div class="VARIABLELIST">
1124 Confuse log analysis, custom applications
1132 Sends a user defined HTTP header to the web server.
1148 Any string value is possible. Validity of the defined HTTP
1149 headers is not checked. It is recommended that you use the
1150 <span class="QUOTE">"<tt class="LITERAL">X-</tt>"</span>
1151 prefix for custom headers.
1159 This action may be specified multiple times, in order to
1160 define multiple headers. This is rarely needed for the
1161 typical user. If you don't know what <span class=
1162 "QUOTE">"HTTP headers"</span> are, you definitely don't
1163 need to worry about this one.
1166 Headers added by this action are not modified by other
1176 <table border="0" bgcolor="#E0E0E0" width="90%">
1179 <pre class="SCREEN">
1180 +add-header{X-User-Tracking: sucks}
1191 <a name="BLOCK">8.5.2. block</a>
1193 <div class="VARIABLELIST">
1200 Block ads or other unwanted content
1208 Requests for URLs to which this action applies are blocked,
1209 i.e. the requests are trapped by <span class=
1210 "APPLICATION">Privoxy</span> and the requested URL is never
1211 retrieved, but is answered locally with a substitute page
1212 or image, as determined by the <tt class="LITERAL"><a href=
1213 "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt>,
1214 <tt class="LITERAL"><a href=
1215 "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></tt>,
1216 and <tt class="LITERAL"><a href=
1217 "actions-file.html#HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document</a></tt>
1234 A block reason that should be given to the user.
1242 <span class="APPLICATION">Privoxy</span> sends a special
1243 <span class="QUOTE">"BLOCKED"</span> page for requests to
1244 blocked pages. This page contains the block reason given as
1245 parameter, a link to find out why the block action applies,
1246 and a click-through to the blocked content (the latter only
1247 if the force feature is available and enabled).
1250 A very important exception occurs if <span class=
1251 "emphasis"><i class="EMPHASIS">both</i></span> <tt class=
1252 "LITERAL">block</tt> and <tt class="LITERAL"><a href=
1253 "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt>,
1254 apply to the same request: it will then be replaced by an
1255 image. If <tt class="LITERAL"><a href=
1256 "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></tt>
1257 (see below) also applies, the type of image will be
1258 determined by its parameter, if not, the standard
1259 checkerboard pattern is sent.
1262 It is important to understand this process, in order to
1263 understand how <span class="APPLICATION">Privoxy</span>
1264 deals with ads and other unwanted content. Blocking is a
1265 core feature, and one upon which various other features
1269 The <tt class="LITERAL"><a href=
1270 "actions-file.html#FILTER">filter</a></tt> action can
1271 perform a very similar task, by <span class=
1272 "QUOTE">"blocking"</span> banner images and other content
1273 through rewriting the relevant URLs in the document's HTML
1274 source, so they don't get requested in the first place.
1275 Note that this is a totally different technique, and it's
1276 easy to confuse the two.
1280 Example usage (section):
1285 <table border="0" bgcolor="#E0E0E0" width="90%">
1288 <pre class="SCREEN">
1289 {+block{No nasty stuff for you.}}
1290 # Block and replace with "blocked" page
1291 .nasty-stuff.example.com
1293 {+block{Doubleclick banners.} +handle-as-image}
1294 # Block and replace with image
1298 {+block{Layered ads.} +handle-as-empty-document}
1299 # Block and then ignore
1300 adserver.example.net/.*\.js$
1311 <a name="CHANGE-X-FORWARDED-FOR">8.5.3.
1312 change-x-forwarded-for</a>
1314 <div class="VARIABLELIST">
1321 Improve privacy by not forwarding the source of the request
1322 in the HTTP headers.
1330 Deletes the <span class="QUOTE">"X-Forwarded-For:"</span>
1331 HTTP header from the client request, or adds a new one.
1349 <span class="QUOTE">"block"</span> to delete the
1355 <span class="QUOTE">"add"</span> to create the header
1356 (or append the client's IP address to an already
1367 It is safe and recommended to use <tt class=
1368 "LITERAL">block</tt>.
1371 Forwarding the source address of the request may make sense
1372 in some multi-user setups but is also a privacy risk.
1381 <table border="0" bgcolor="#E0E0E0" width="90%">
1384 <pre class="SCREEN">
1385 +change-x-forwarded-for{block}
1396 <a name="CLIENT-HEADER-FILTER">8.5.4. client-header-filter</a>
1398 <div class="VARIABLELIST">
1405 Rewrite or remove single client headers.
1413 All client headers to which this action applies are
1414 filtered on-the-fly through the specified regular
1415 expression based substitutions.
1431 The name of a client-header filter, as defined in one of
1432 the <a href="filter-file.html">filter files</a>.
1440 Client-header filters are applied to each header on its
1441 own, not to all at once. This makes it easier to diagnose
1442 problems, but on the downside you can't write filters that
1443 only change header x if header y's value is z. You can do
1444 that by using tags though.
1447 Client-header filters are executed after the other header
1448 actions have finished and use their output as input.
1451 If the request URL gets changed, <span class=
1452 "APPLICATION">Privoxy</span> will detect that and use the
1453 new one. This can be used to rewrite the request
1454 destination behind the client's back, for example to
1455 specify a Tor exit relay for certain requests.
1458 Please refer to the <a href="filter-file.html">filter file
1459 chapter</a> to learn which client-header filters are
1460 available by default, and how to create your own.
1464 Example usage (section):
1469 <table border="0" bgcolor="#E0E0E0" width="90%">
1472 <pre class="SCREEN">
1473 # Hide Tor exit notation in Host and Referer Headers
1474 {+client-header-filter{hide-tor-exit-notation}}
1487 <a name="CLIENT-HEADER-TAGGER">8.5.5. client-header-tagger</a>
1489 <div class="VARIABLELIST">
1496 Block requests based on their headers.
1504 Client headers to which this action applies are filtered
1505 on-the-fly through the specified regular expression based
1506 substitutions, the result is used as tag.
1522 The name of a client-header tagger, as defined in one of
1523 the <a href="filter-file.html">filter files</a>.
1531 Client-header taggers are applied to each header on its
1532 own, and as the header isn't modified, each tagger <span
1533 class="QUOTE">"sees"</span> the original.
1536 Client-header taggers are the first actions that are
1537 executed and their tags can be used to control every other
1542 Example usage (section):
1547 <table border="0" bgcolor="#E0E0E0" width="90%">
1550 <pre class="SCREEN">
1551 # Tag every request with the User-Agent header
1552 {+client-header-tagger{user-agent}}
1555 # Tagging itself doesn't change the action
1556 # settings, sections with TAG patterns do:
1558 # If it's a download agent, use a different forwarding proxy,
1559 # show the real User-Agent and make sure resume works.
1560 {+forward-override{forward-socks5 10.0.0.2:2222 .} \
1561 -hide-if-modified-since \
1562 -overwrite-last-modified \
1567 TAG:^User-Agent: NetBSD-ftp/
1568 TAG:^User-Agent: Novell ZYPP Installer
1569 TAG:^User-Agent: RPM APT-HTTP/
1570 TAG:^User-Agent: fetch libfetch/
1571 TAG:^User-Agent: Ubuntu APT-HTTP/
1572 TAG:^User-Agent: MPlayer/
1584 <a name="CONTENT-TYPE-OVERWRITE">8.5.6.
1585 content-type-overwrite</a>
1587 <div class="VARIABLELIST">
1594 Stop useless download menus from popping up, or change the
1595 browser's rendering mode
1603 Replaces the <span class="QUOTE">"Content-Type:"</span>
1628 The <span class="QUOTE">"Content-Type:"</span> HTTP server
1629 header is used by the browser to decide what to do with the
1630 document. The value of this header can cause the browser to
1631 open a download menu instead of displaying the document by
1632 itself, even if the document's format is supported by the
1636 The declared content type can also affect which rendering
1637 mode the browser chooses. If XHTML is delivered as <span
1638 class="QUOTE">"text/html"</span>, many browsers treat it as
1639 yet another broken HTML document. If it is send as <span
1640 class="QUOTE">"application/xml"</span>, browsers with XHTML
1641 support will only display it, if the syntax is correct.
1644 If you see a web site that proudly uses XHTML buttons, but
1645 sets <span class="QUOTE">"Content-Type: text/html"</span>,
1646 you can use <span class="APPLICATION">Privoxy</span> to
1647 overwrite it with <span class=
1648 "QUOTE">"application/xml"</span> and validate the web
1649 master's claim inside your XHTML-supporting browser. If the
1650 syntax is incorrect, the browser will complain loudly.
1653 You can also go the opposite direction: if your browser
1654 prints error messages instead of rendering a document
1655 falsely declared as XHTML, you can overwrite the content
1656 type with <span class="QUOTE">"text/html"</span> and have
1657 it rendered as broken HTML document.
1660 By default <tt class="LITERAL">content-type-overwrite</tt>
1661 only replaces <span class="QUOTE">"Content-Type:"</span>
1662 headers that look like some kind of text. If you want to
1663 overwrite it unconditionally, you have to combine it with
1664 <tt class="LITERAL"><a href=
1665 "actions-file.html#FORCE-TEXT-MODE">force-text-mode</a></tt>.
1666 This limitation exists for a reason, think twice before
1670 Most of the time it's easier to replace this action with a
1671 custom <tt class="LITERAL"><a href=
1672 "actions-file.html#SERVER-HEADER-FILTER">server-header
1673 filter</a></tt>. It allows you to activate it for every
1674 document of a certain site and it will still only replace
1675 the content types you aimed at.
1678 Of course you can apply <tt class=
1679 "LITERAL">content-type-overwrite</tt> to a whole site and
1680 then make URL based exceptions, but it's a lot more work to
1681 get the same precision.
1685 Example usage (sections):
1690 <table border="0" bgcolor="#E0E0E0" width="90%">
1693 <pre class="SCREEN">
1694 # Check if www.example.net/ really uses valid XHTML
1695 { +content-type-overwrite{application/xml} }
1698 # but leave the content type unmodified if the URL looks like a style sheet
1699 {-content-type-overwrite}
1700 www.example.net/.*\.css$
1701 www.example.net/.*style
1712 <a name="CRUNCH-CLIENT-HEADER">8.5.7. crunch-client-header</a>
1714 <div class="VARIABLELIST">
1721 Remove a client header <span class=
1722 "APPLICATION">Privoxy</span> has no dedicated action for.
1730 Deletes every header sent by the client that contains the
1731 string the user supplied as parameter.
1755 This action allows you to block client headers for which no
1756 dedicated <span class="APPLICATION">Privoxy</span> action
1757 exists. <span class="APPLICATION">Privoxy</span> will
1758 remove every client header that contains the string you
1759 supplied as parameter.
1762 Regular expressions are <span class="emphasis"><i class=
1763 "EMPHASIS">not supported</i></span> and you can't use this
1764 action to block different headers in the same request,
1765 unless they contain the same string.
1768 <tt class="LITERAL">crunch-client-header</tt> is only meant
1769 for quick tests. If you have to block several different
1770 headers, or only want to modify parts of them, you should
1771 use a <tt class="LITERAL"><a href=
1772 "actions-file.html#CLIENT-HEADER-FILTER">client-header
1775 <div class="WARNING">
1776 <table class="WARNING" border="1" width="90%">
1785 Don't block any header without understanding the
1794 Example usage (section):
1799 <table border="0" bgcolor="#E0E0E0" width="90%">
1802 <pre class="SCREEN">
1803 # Block the non-existent "Privacy-Violation:" client header
1804 { +crunch-client-header{Privacy-Violation:} }
1817 <a name="CRUNCH-IF-NONE-MATCH">8.5.8. crunch-if-none-match</a>
1819 <div class="VARIABLELIST">
1826 Prevent yet another way to track the user's steps between
1835 Deletes the <span class="QUOTE">"If-None-Match:"</span>
1860 Removing the <span class="QUOTE">"If-None-Match:"</span>
1861 HTTP client header is useful for filter testing, where you
1862 want to force a real reload instead of getting status code
1863 <span class="QUOTE">"304"</span> which would cause the
1864 browser to use a cached copy of the page.
1867 It is also useful to make sure the header isn't used as a
1868 cookie replacement (unlikely but possible).
1871 Blocking the <span class="QUOTE">"If-None-Match:"</span>
1872 header shouldn't cause any caching problems, as long as the
1873 <span class="QUOTE">"If-Modified-Since:"</span> header
1874 isn't blocked or missing as well.
1877 It is recommended to use this action together with <tt
1878 class="LITERAL"><a href=
1879 "actions-file.html#HIDE-IF-MODIFIED-SINCE">hide-if-modified-since</a></tt>
1880 and <tt class="LITERAL"><a href=
1881 "actions-file.html#OVERWRITE-LAST-MODIFIED">overwrite-last-modified</a></tt>.
1885 Example usage (section):
1890 <table border="0" bgcolor="#E0E0E0" width="90%">
1893 <pre class="SCREEN">
1894 # Let the browser revalidate cached documents but don't
1895 # allow the server to use the revalidation headers for user tracking.
1896 {+hide-if-modified-since{-60} \
1897 +overwrite-last-modified{randomize} \
1898 +crunch-if-none-match}
1910 <a name="CRUNCH-INCOMING-COOKIES">8.5.9.
1911 crunch-incoming-cookies</a>
1913 <div class="VARIABLELIST">
1920 Prevent the web server from setting HTTP cookies on your
1929 Deletes any <span class="QUOTE">"Set-Cookie:"</span> HTTP
1930 headers from server replies.
1954 This action is only concerned with <span class=
1955 "emphasis"><i class="EMPHASIS">incoming</i></span> HTTP
1956 cookies. For <span class="emphasis"><i class=
1957 "EMPHASIS">outgoing</i></span> HTTP cookies, use <tt class=
1959 "actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a></tt>.
1960 Use <span class="emphasis"><i class=
1961 "EMPHASIS">both</i></span> to disable HTTP cookies
1965 It makes <span class="emphasis"><i class="EMPHASIS">no
1966 sense at all</i></span> to use this action in conjunction
1967 with the <tt class="LITERAL"><a href=
1968 "actions-file.html#SESSION-COOKIES-ONLY">session-cookies-only</a></tt>
1969 action, since it would prevent the session cookies from
1970 being set. See also <tt class="LITERAL"><a href=
1971 "actions-file.html#FILTER-CONTENT-COOKIES">filter-content-cookies</a></tt>.
1980 <table border="0" bgcolor="#E0E0E0" width="90%">
1983 <pre class="SCREEN">
1984 +crunch-incoming-cookies
1995 <a name="CRUNCH-SERVER-HEADER">8.5.10. crunch-server-header</a>
1997 <div class="VARIABLELIST">
2004 Remove a server header <span class=
2005 "APPLICATION">Privoxy</span> has no dedicated action for.
2013 Deletes every header sent by the server that contains the
2014 string the user supplied as parameter.
2038 This action allows you to block server headers for which no
2039 dedicated <span class="APPLICATION">Privoxy</span> action
2040 exists. <span class="APPLICATION">Privoxy</span> will
2041 remove every server header that contains the string you
2042 supplied as parameter.
2045 Regular expressions are <span class="emphasis"><i class=
2046 "EMPHASIS">not supported</i></span> and you can't use this
2047 action to block different headers in the same request,
2048 unless they contain the same string.
2051 <tt class="LITERAL">crunch-server-header</tt> is only meant
2052 for quick tests. If you have to block several different
2053 headers, or only want to modify parts of them, you should
2054 use a custom <tt class="LITERAL"><a href=
2055 "actions-file.html#SERVER-HEADER-FILTER">server-header
2058 <div class="WARNING">
2059 <table class="WARNING" border="1" width="90%">
2068 Don't block any header without understanding the
2077 Example usage (section):
2082 <table border="0" bgcolor="#E0E0E0" width="90%">
2085 <pre class="SCREEN">
2086 # Crunch server headers that try to prevent caching
2087 { +crunch-server-header{no-cache} }
2099 <a name="CRUNCH-OUTGOING-COOKIES">8.5.11.
2100 crunch-outgoing-cookies</a>
2102 <div class="VARIABLELIST">
2109 Prevent the web server from reading any HTTP cookies from
2118 Deletes any <span class="QUOTE">"Cookie:"</span> HTTP
2119 headers from client requests.
2143 This action is only concerned with <span class=
2144 "emphasis"><i class="EMPHASIS">outgoing</i></span> HTTP
2145 cookies. For <span class="emphasis"><i class=
2146 "EMPHASIS">incoming</i></span> HTTP cookies, use <tt class=
2148 "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a></tt>.
2149 Use <span class="emphasis"><i class=
2150 "EMPHASIS">both</i></span> to disable HTTP cookies
2154 It makes <span class="emphasis"><i class="EMPHASIS">no
2155 sense at all</i></span> to use this action in conjunction
2156 with the <tt class="LITERAL"><a href=
2157 "actions-file.html#SESSION-COOKIES-ONLY">session-cookies-only</a></tt>
2158 action, since it would prevent the session cookies from
2168 <table border="0" bgcolor="#E0E0E0" width="90%">
2171 <pre class="SCREEN">
2172 +crunch-outgoing-cookies
2183 <a name="DEANIMATE-GIFS">8.5.12. deanimate-gifs</a>
2185 <div class="VARIABLELIST">
2192 Stop those annoying, distracting animated GIF images.
2200 De-animate GIF animations, i.e. reduce them to their first
2217 <span class="QUOTE">"last"</span> or <span class=
2218 "QUOTE">"first"</span>
2226 This will also shrink the images considerably (in bytes,
2227 not pixels!). If the option <span class=
2228 "QUOTE">"first"</span> is given, the first frame of the
2229 animation is used as the replacement. If <span class=
2230 "QUOTE">"last"</span> is given, the last frame of the
2231 animation is used instead, which probably makes more sense
2232 for most banner animations, but also has the risk of not
2233 showing the entire last frame (if it is only a delta to an
2237 You can safely use this action with patterns that will also
2238 match non-GIF objects, because no attempt will be made at
2239 anything that doesn't look like a GIF.
2248 <table border="0" bgcolor="#E0E0E0" width="90%">
2251 <pre class="SCREEN">
2252 +deanimate-gifs{last}
2263 <a name="DOWNGRADE-HTTP-VERSION">8.5.13.
2264 downgrade-http-version</a>
2266 <div class="VARIABLELIST">
2273 Work around (very rare) problems with HTTP/1.1
2281 Downgrades HTTP/1.1 client requests and server replies to
2306 This is a left-over from the time when <span class=
2307 "APPLICATION">Privoxy</span> didn't support important
2308 HTTP/1.1 features well. It is left here for the unlikely
2309 case that you experience HTTP/1.1 related problems with
2310 some server out there. Not all HTTP/1.1 features and
2311 requirements are supported yet, so there is a chance you
2312 might need this action.
2316 Example usage (section):
2321 <table border="0" bgcolor="#E0E0E0" width="90%">
2324 <pre class="SCREEN">
2325 {+downgrade-http-version}
2326 problem-host.example.com
2337 <a name="FAST-REDIRECTS">8.5.14. fast-redirects</a>
2339 <div class="VARIABLELIST">
2346 Fool some click-tracking scripts and speed up indirect
2355 Detects redirection URLs and redirects the browser without
2356 contacting the redirection server first.
2374 <span class="QUOTE">"simple-check"</span> to just
2375 search for the string <span class=
2376 "QUOTE">"http://"</span> to detect redirection URLs.
2381 <span class="QUOTE">"check-decoded-url"</span> to
2382 decode URLs (if necessary) before searching for
2393 Many sites, like yahoo.com, don't just link to other sites.
2394 Instead, they will link to some script on their own
2395 servers, giving the destination as a parameter, which will
2396 then redirect you to the final target. URLs resulting from
2397 this scheme typically look like: <span class=
2398 "QUOTE">"http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/"</span>.
2401 Sometimes, there are even multiple consecutive redirects
2402 encoded in the URL. These redirections via scripts make
2403 your web browsing more traceable, since the server from
2404 which you follow such a link can see where you go to. Apart
2405 from that, valuable bandwidth and time is wasted, while
2406 your browser asks the server for one redirect after the
2407 other. Plus, it feeds the advertisers.
2410 This feature is currently not very smart and is scheduled
2411 for improvement. If it is enabled by default, you will have
2412 to create some exceptions to this action. It can lead to
2413 failures in several ways:
2416 Not every URLs with other URLs as parameters is evil. Some
2417 sites offer a real service that requires this information
2418 to work. For example a validation service needs to know,
2419 which document to validate. <tt class=
2420 "LITERAL">fast-redirects</tt> assumes that every URL
2421 parameter that looks like another URL is a redirection
2422 target, and will always redirect to the last one. Most of
2423 the time the assumption is correct, but if it isn't, the
2424 user gets redirected anyway.
2427 Another failure occurs if the URL contains other parameters
2428 after the URL parameter. The URL: <span class=
2429 "QUOTE">"http://www.example.org/?redirect=http%3a//www.example.net/&foo=bar"</span>.
2430 contains the redirection URL <span class=
2431 "QUOTE">"http://www.example.net/"</span>, followed by
2432 another parameter. <tt class="LITERAL">fast-redirects</tt>
2433 doesn't know that and will cause a redirect to <span class=
2434 "QUOTE">"http://www.example.net/&foo=bar"</span>.
2435 Depending on the target server configuration, the parameter
2436 will be silently ignored or lead to a <span class=
2437 "QUOTE">"page not found"</span> error. You can prevent this
2438 problem by first using the <tt class="LITERAL"><a href=
2439 "actions-file.html#REDIRECT">redirect</a></tt> action to
2440 remove the last part of the URL, but it requires a little
2444 To detect a redirection URL, <tt class=
2445 "LITERAL">fast-redirects</tt> only looks for the string
2446 <span class="QUOTE">"http://"</span>, either in plain text
2447 (invalid but often used) or encoded as <span class=
2448 "QUOTE">"http%3a//"</span>. Some sites use their own URL
2449 encoding scheme, encrypt the address of the target server
2450 or replace it with a database id. In theses cases <tt
2451 class="LITERAL">fast-redirects</tt> is fooled and the
2452 request reaches the redirection server where it probably
2462 <table border="0" bgcolor="#E0E0E0" width="90%">
2465 <pre class="SCREEN">
2466 { +fast-redirects{simple-check} }
2469 { +fast-redirects{check-decoded-url} }
2470 another.example.com/testing
2481 <a name="FILTER">8.5.15. filter</a>
2483 <div class="VARIABLELIST">
2490 Get rid of HTML and JavaScript annoyances, banner
2491 advertisements (by size), do fun text replacements, add
2492 personalized effects, etc.
2500 All instances of text-based type, most notably HTML and
2501 JavaScript, to which this action applies, can be filtered
2502 on-the-fly through the specified regular expression based
2503 substitutions. (Note: as of version 3.0.3 plain text
2504 documents are exempted from filtering, because web servers
2505 often use the <tt class="LITERAL">text/plain</tt> MIME type
2506 for all files whose type they don't know.)
2522 The name of a content filter, as defined in the <a href=
2523 "filter-file.html">filter file</a>. Filters can be defined
2524 in one or more files as defined by the <tt class=
2526 "config.html#FILTERFILE">filterfile</a></tt> option in the
2527 <a href="config.html">config file</a>. <tt class=
2528 "FILENAME">default.filter</tt> is the collection of filters
2529 supplied by the developers. Locally defined filters should
2530 go in their own file, such as <tt class=
2531 "FILENAME">user.filter</tt>.
2534 When used in its negative form, and without parameters,
2535 <span class="emphasis"><i class="EMPHASIS">all</i></span>
2536 filtering is completely disabled.
2544 For your convenience, there are a number of pre-defined
2545 filters available in the distribution filter file that you
2546 can use. See the examples below for a list.
2549 Filtering requires buffering the page content, which may
2550 appear to slow down page rendering since nothing is
2551 displayed until all content has passed the filters. (The
2552 total time until the page is completely rendered doesn't
2553 change much, but it may be perceived as slower since the
2554 page is not incrementally displayed.) This effect will be
2555 more noticeable on slower connections.
2558 <span class="QUOTE">"Rolling your own"</span> filters
2559 requires a knowledge of <a href=
2560 "http://en.wikipedia.org/wiki/Regular_expressions" target=
2561 "_top"><span class="QUOTE">"Regular Expressions"</span></a>
2562 and <a href="http://en.wikipedia.org/wiki/Html" target=
2563 "_top"><span class="QUOTE">"HTML"</span></a>. This is very
2564 powerful feature, and potentially very intrusive. Filters
2565 should be used with caution, and where an equivalent <span
2566 class="QUOTE">"action"</span> is not available.
2569 The amount of data that can be filtered is limited to the
2570 <tt class="LITERAL"><a href=
2571 "config.html#BUFFER-LIMIT">buffer-limit</a></tt> option in
2572 the main <a href="config.html">config file</a>. The default
2573 is 4096 KB (4 Megs). Once this limit is exceeded, the
2574 buffered data, and all pending data, is passed through
2578 Inappropriate MIME types, such as zipped files, are not
2579 filtered at all. (Again, only text-based types except plain
2580 text). Encrypted SSL data (from HTTPS servers) cannot be
2581 filtered either, since this would violate the integrity of
2582 the secure transaction. In some situations it might be
2583 necessary to protect certain text, like source code, from
2584 filtering by defining appropriate <tt class=
2585 "LITERAL">-filter</tt> exceptions.
2588 Compressed content can't be filtered either, unless <span
2589 class="APPLICATION">Privoxy</span> is compiled with zlib
2590 support (requires at least <span class=
2591 "APPLICATION">Privoxy</span> 3.0.7), in which case <span
2592 class="APPLICATION">Privoxy</span> will decompress the
2593 content before filtering it.
2596 If you use a <span class="APPLICATION">Privoxy</span>
2597 version without zlib support, but want filtering to work on
2598 as much documents as possible, even those that would
2599 normally be sent compressed, you must use the <tt class=
2601 "actions-file.html#PREVENT-COMPRESSION">prevent-compression</a></tt>
2602 action in conjunction with <tt class="LITERAL">filter</tt>.
2605 Content filtering can achieve some of the same effects as
2606 the <tt class="LITERAL"><a href=
2607 "actions-file.html#BLOCK">block</a></tt> action, i.e. it
2608 can be used to block ads and banners. But the mechanism
2609 works quite differently. One effective use, is to block ad
2610 banners based on their size (see below), since many of
2611 these seem to be somewhat standardized.
2614 <a href="contact.html">Feedback</a> with suggestions for
2615 new or improved filters is particularly welcome!
2618 The below list has only the names and a one-line
2619 description of each predefined filter. There are <a href=
2620 "filter-file.html#PREDEFINED-FILTERS">more verbose
2621 explanations</a> of what these filters do in the <a href=
2622 "filter-file.html">filter file chapter</a>.
2626 Example usage (with filters from the distribution <tt class=
2627 "FILENAME">default.filter</tt> file). See <a href=
2628 "filter-file.html#PREDEFINED-FILTERS">the Predefined Filters
2629 section</a> for more explanation on each:
2633 <a name="FILTER-JS-ANNOYANCES"></a>
2635 <table border="0" bgcolor="#E0E0E0" width="90%">
2638 <pre class="SCREEN">
2639 +filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse.
2646 <a name="FILTER-JS-EVENTS"></a>
2648 <table border="0" bgcolor="#E0E0E0" width="90%">
2651 <pre class="SCREEN">
2652 +filter{js-events} # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).
2659 <a name="FILTER-HTML-ANNOYANCES"></a>
2661 <table border="0" bgcolor="#E0E0E0" width="90%">
2664 <pre class="SCREEN">
2665 +filter{html-annoyances} # Get rid of particularly annoying HTML abuse.
2672 <a name="FILTER-CONTENT-COOKIES"></a>
2674 <table border="0" bgcolor="#E0E0E0" width="90%">
2677 <pre class="SCREEN">
2678 +filter{content-cookies} # Kill cookies that come in the HTML or JS content.
2685 <a name="FILTER-REFRESH-TAGS"></a>
2687 <table border="0" bgcolor="#E0E0E0" width="90%">
2690 <pre class="SCREEN">
2691 +filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups).
2698 <a name="FILTER-UNSOLICITED-POPUPS"></a>
2700 <table border="0" bgcolor="#E0E0E0" width="90%">
2703 <pre class="SCREEN">
2704 +filter{unsolicited-popups} # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.
2711 <a name="FILTER-ALL-POPUPS"></a>
2713 <table border="0" bgcolor="#E0E0E0" width="90%">
2716 <pre class="SCREEN">
2717 +filter{all-popups} # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.
2724 <a name="FILTER-IMG-REORDER"></a>
2726 <table border="0" bgcolor="#E0E0E0" width="90%">
2729 <pre class="SCREEN">
2730 +filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective.
2737 <a name="FILTER-BANNERS-BY-SIZE"></a>
2739 <table border="0" bgcolor="#E0E0E0" width="90%">
2742 <pre class="SCREEN">
2743 +filter{banners-by-size} # Kill banners by size.
2750 <a name="FILTER-BANNERS-BY-LINK"></a>
2752 <table border="0" bgcolor="#E0E0E0" width="90%">
2755 <pre class="SCREEN">
2756 +filter{banners-by-link} # Kill banners by their links to known clicktrackers.
2763 <a name="FILTER-WEBBUGS"></a>
2765 <table border="0" bgcolor="#E0E0E0" width="90%">
2768 <pre class="SCREEN">
2769 +filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking).
2776 <a name="FILTER-TINY-TEXTFORMS"></a>
2778 <table border="0" bgcolor="#E0E0E0" width="90%">
2781 <pre class="SCREEN">
2782 +filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap.
2789 <a name="FILTER-JUMPING-WINDOWS"></a>
2791 <table border="0" bgcolor="#E0E0E0" width="90%">
2794 <pre class="SCREEN">
2795 +filter{jumping-windows} # Prevent windows from resizing and moving themselves.
2802 <a name="FILTER-FRAMESET-BORDERS"></a>
2804 <table border="0" bgcolor="#E0E0E0" width="90%">
2807 <pre class="SCREEN">
2808 +filter{frameset-borders} # Give frames a border and make them resizable.
2815 <a name="FILTER-DEMORONIZER"></a>
2817 <table border="0" bgcolor="#E0E0E0" width="90%">
2820 <pre class="SCREEN">
2821 +filter{demoronizer} # Fix MS's non-standard use of standard charsets.
2828 <a name="FILTER-SHOCKWAVE-FLASH"></a>
2830 <table border="0" bgcolor="#E0E0E0" width="90%">
2833 <pre class="SCREEN">
2834 +filter{shockwave-flash} # Kill embedded Shockwave Flash objects.
2841 <a name="FILTER-QUICKTIME-KIOSKMODE"></a>
2843 <table border="0" bgcolor="#E0E0E0" width="90%">
2846 <pre class="SCREEN">
2847 +filter{quicktime-kioskmode} # Make Quicktime movies saveable.
2854 <a name="FILTER-FUN"></a>
2856 <table border="0" bgcolor="#E0E0E0" width="90%">
2859 <pre class="SCREEN">
2860 +filter{fun} # Text replacements for subversive browsing fun!
2867 <a name="FILTER-CRUDE-PARENTAL"></a>
2869 <table border="0" bgcolor="#E0E0E0" width="90%">
2872 <pre class="SCREEN">
2873 +filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliably.
2880 <a name="FILTER-IE-EXPLOITS"></a>
2882 <table border="0" bgcolor="#E0E0E0" width="90%">
2885 <pre class="SCREEN">
2886 +filter{ie-exploits} # Disable some known Internet Explorer bug exploits.
2893 <a name="FILTER-SITE-SPECIFICS"></a>
2895 <table border="0" bgcolor="#E0E0E0" width="90%">
2898 <pre class="SCREEN">
2899 +filter{site-specifics} # Cure for site-specific problems. Don't apply generally!
2906 <a name="FILTER-NO-PING"></a>
2908 <table border="0" bgcolor="#E0E0E0" width="90%">
2911 <pre class="SCREEN">
2912 +filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags.
2919 <a name="FILTER-GOOGLE"></a>
2921 <table border="0" bgcolor="#E0E0E0" width="90%">
2924 <pre class="SCREEN">
2925 +filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement.
2932 <a name="FILTER-YAHOO"></a>
2934 <table border="0" bgcolor="#E0E0E0" width="90%">
2937 <pre class="SCREEN">
2938 +filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation.
2945 <a name="FILTER-MSN"></a>
2947 <table border="0" bgcolor="#E0E0E0" width="90%">
2950 <pre class="SCREEN">
2951 +filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.
2958 <a name="FILTER-BLOGSPOT"></a>
2960 <table border="0" bgcolor="#E0E0E0" width="90%">
2963 <pre class="SCREEN">
2964 +filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this.
2975 <a name="FORCE-TEXT-MODE">8.5.16. force-text-mode</a>
2977 <div class="VARIABLELIST">
2984 Force <span class="APPLICATION">Privoxy</span> to treat a
2985 document as if it was in some kind of <span class=
2986 "emphasis"><i class="EMPHASIS">text</i></span> format.
2994 Declares a document as text, even if the <span class=
2995 "QUOTE">"Content-Type:"</span> isn't detected as such.
3019 As explained <tt class="LITERAL"><a href=
3020 "actions-file.html#FILTER">above</a></tt>, <span class=
3021 "APPLICATION">Privoxy</span> tries to only filter files
3022 that are in some kind of text format. The same restrictions
3023 apply to <tt class="LITERAL"><a href=
3024 "actions-file.html#CONTENT-TYPE-OVERWRITE">content-type-overwrite</a></tt>.
3025 <tt class="LITERAL">force-text-mode</tt> declares a
3026 document as text, without looking at the <span class=
3027 "QUOTE">"Content-Type:"</span> first.
3029 <div class="WARNING">
3030 <table class="WARNING" border="1" width="90%">
3039 Think twice before activating this action.
3040 Filtering binary data with regular expressions can
3054 <table border="0" bgcolor="#E0E0E0" width="90%">
3057 <pre class="SCREEN">
3070 <a name="FORWARD-OVERRIDE">8.5.17. forward-override</a>
3072 <div class="VARIABLELIST">
3079 Change the forwarding settings based on User-Agent or
3088 Overrules the forward directives in the configuration file.
3106 <span class="QUOTE">"forward ."</span> to use a direct
3107 connection without any additional proxies.
3112 <span class="QUOTE">"forward 127.0.0.1:8123"</span> to
3113 use the HTTP proxy listening at 127.0.0.1 port 8123.
3118 <span class="QUOTE">"forward-socks4a 127.0.0.1:9050
3119 ."</span> to use the socks4a proxy listening at
3120 127.0.0.1 port 9050. Replace <span class=
3121 "QUOTE">"forward-socks4a"</span> with <span class=
3122 "QUOTE">"forward-socks4"</span> to use a socks4
3123 connection (with local DNS resolution) instead, use
3124 <span class="QUOTE">"forward-socks5"</span> for socks5
3125 connections (with remote DNS resolution).
3130 <span class="QUOTE">"forward-socks4a 127.0.0.1:9050
3131 proxy.example.org:8000"</span> to use the socks4a proxy
3132 listening at 127.0.0.1 port 9050 to reach the HTTP
3133 proxy listening at proxy.example.org port 8000. Replace
3134 <span class="QUOTE">"forward-socks4a"</span> with <span
3135 class="QUOTE">"forward-socks4"</span> to use a socks4
3136 connection (with local DNS resolution) instead, use
3137 <span class="QUOTE">"forward-socks5"</span> for socks5
3138 connections (with remote DNS resolution).
3148 This action takes parameters similar to the <a href=
3149 "config.html#FORWARDING">forward</a> directives in the
3150 configuration file, but without the URL pattern. It can be
3151 used as replacement, but normally it's only used in cases
3152 where matching based on the request URL isn't sufficient.
3154 <div class="WARNING">
3155 <table class="WARNING" border="1" width="90%">
3164 Please read the description for the <a href=
3165 "config.html#FORWARDING">forward</a> directives
3166 before using this action. Forwarding to the wrong
3167 people will reduce your privacy and increase the
3168 chances of man-in-the-middle attacks.
3171 If the ports are missing or invalid, default values
3172 will be used. This might change in the future and
3173 you shouldn't rely on it. Otherwise incorrect
3174 syntax causes Privoxy to exit.
3178 "http://config.privoxy.org/show-url-info" target=
3179 "_top">show-url-info CGI page</a> to verify that
3180 your forward settings do what you thought the do.
3193 <table border="0" bgcolor="#E0E0E0" width="90%">
3196 <pre class="SCREEN">
3197 # Always use direct connections for requests previously tagged as
3198 # <span class="QUOTE">"User-Agent: fetch libfetch/2.0"</span> and make sure
3199 # resuming downloads continues to work.
3200 # This way you can continue to use Tor for your normal browsing,
3201 # without overloading the Tor network with your FreeBSD ports updates
3202 # or downloads of bigger files like ISOs.
3203 # Note that HTTP headers are easy to fake and therefore their
3204 # values are as (un)trustworthy as your clients and users.
3205 {+forward-override{forward .} \
3206 -hide-if-modified-since \
3207 -overwrite-last-modified \
3209 TAG:^User-Agent: fetch libfetch/2\.0$
3221 <a name="HANDLE-AS-EMPTY-DOCUMENT">8.5.18.
3222 handle-as-empty-document</a>
3224 <div class="VARIABLELIST">
3231 Mark URLs that should be replaced by empty documents <span
3232 class="emphasis"><i class="EMPHASIS">if they get
3241 This action alone doesn't do anything noticeable. It just
3242 marks URLs. If the <tt class="LITERAL"><a href=
3243 "actions-file.html#BLOCK">block</a></tt> action <span
3244 class="emphasis"><i class="EMPHASIS">also
3245 applies</i></span>, the presence or absence of this mark
3246 decides whether an HTML <span class=
3247 "QUOTE">"BLOCKED"</span> page, or an empty document will be
3248 sent to the client as a substitute for the blocked content.
3249 The <span class="emphasis"><i class=
3250 "EMPHASIS">empty</i></span> document isn't literally empty,
3251 but actually contains a single space.
3275 Some browsers complain about syntax errors if JavaScript
3276 documents are blocked with <span class=
3277 "APPLICATION">Privoxy's</span> default HTML page; this
3278 option can be used to silence them. And of course this
3279 action can also be used to eliminate the <span class=
3280 "APPLICATION">Privoxy</span> BLOCKED message in frames.
3283 The content type for the empty document can be specified
3284 with <tt class="LITERAL"><a href=
3285 "actions-file.html#CONTENT-TYPE-OVERWRITE">content-type-overwrite{}</a></tt>,
3286 but usually this isn't necessary.
3295 <table border="0" bgcolor="#E0E0E0" width="90%">
3298 <pre class="SCREEN">
3299 # Block all documents on example.org that end with ".js",
3300 # but send an empty document instead of the usual HTML message.
3301 {+block{Blocked JavaScript} +handle-as-empty-document}
3314 <a name="HANDLE-AS-IMAGE">8.5.19. handle-as-image</a>
3316 <div class="VARIABLELIST">
3323 Mark URLs as belonging to images (so they'll be replaced by
3324 images <span class="emphasis"><i class="EMPHASIS">if they
3325 do get blocked</i></span>, rather than HTML pages)
3333 This action alone doesn't do anything noticeable. It just
3334 marks URLs as images. If the <tt class="LITERAL"><a href=
3335 "actions-file.html#BLOCK">block</a></tt> action <span
3336 class="emphasis"><i class="EMPHASIS">also
3337 applies</i></span>, the presence or absence of this mark
3338 decides whether an HTML <span class=
3339 "QUOTE">"blocked"</span> page, or a replacement image (as
3340 determined by the <tt class="LITERAL"><a href=
3341 "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></tt>
3342 action) will be sent to the client as a substitute for the
3367 The below generic example section is actually part of <tt
3368 class="FILENAME">default.action</tt>. It marks all URLs
3369 with well-known image file name extensions as images and
3370 should be left intact.
3373 Users will probably only want to use the handle-as-image
3374 action in conjunction with <tt class="LITERAL"><a href=
3375 "actions-file.html#BLOCK">block</a></tt>, to block sources
3376 of banners, whose URLs don't reflect the file type, like in
3377 the second example section.
3380 Note that you cannot treat HTML pages as images in most
3381 cases. For instance, (in-line) ad frames require an HTML
3382 page to be sent, or they won't display properly. Forcing
3383 <tt class="LITERAL">handle-as-image</tt> in this situation
3384 will not replace the ad frame with an image, but lead to
3389 Example usage (sections):
3394 <table border="0" bgcolor="#E0E0E0" width="90%">
3397 <pre class="SCREEN">
3398 # Generic image extensions:
3401 /.*\.(gif|jpg|jpeg|png|bmp|ico)$
3403 # These don't look like images, but they're banners and should be
3404 # blocked as images:
3406 {+block{Nasty banners.} +handle-as-image}
3407 nasty-banner-server.example.com/junk.cgi\?output=trash
3418 <a name="HIDE-ACCEPT-LANGUAGE">8.5.20. hide-accept-language</a>
3420 <div class="VARIABLELIST">
3427 Pretend to use different language settings.
3435 Deletes or replaces the <span class=
3436 "QUOTE">"Accept-Language:"</span> HTTP header in client
3453 Keyword: <span class="QUOTE">"block"</span>, or any user
3462 Faking the browser's language settings can be useful to
3463 make a foreign User-Agent set with <tt class="LITERAL"><a
3465 "actions-file.html#HIDE-USER-AGENT">hide-user-agent</a></tt>
3469 However some sites with content in different languages
3470 check the <span class="QUOTE">"Accept-Language:"</span> to
3471 decide which one to take by default. Sometimes it isn't
3472 possible to later switch to another language without
3473 changing the <span class="QUOTE">"Accept-Language:"</span>
3477 Therefore it's a good idea to either only change the <span
3478 class="QUOTE">"Accept-Language:"</span> header to languages
3479 you understand, or to languages that aren't wide spread.
3482 Before setting the <span class=
3483 "QUOTE">"Accept-Language:"</span> header to a rare
3484 language, you should consider that it helps to make your
3485 requests unique and thus easier to trace. If you don't plan
3486 to change this header frequently, you should stick to a
3491 Example usage (section):
3496 <table border="0" bgcolor="#E0E0E0" width="90%">
3499 <pre class="SCREEN">
3500 # Pretend to use Canadian language settings.
3501 {+hide-accept-language{en-ca} \
3502 +hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \
3515 <a name="HIDE-CONTENT-DISPOSITION">8.5.21.
3516 hide-content-disposition</a>
3518 <div class="VARIABLELIST">
3525 Prevent download menus for content you prefer to view
3534 Deletes or replaces the <span class=
3535 "QUOTE">"Content-Disposition:"</span> HTTP header set by
3552 Keyword: <span class="QUOTE">"block"</span>, or any user
3561 Some servers set the <span class=
3562 "QUOTE">"Content-Disposition:"</span> HTTP header for
3563 documents they assume you want to save locally before
3564 viewing them. The <span class=
3565 "QUOTE">"Content-Disposition:"</span> header contains the
3566 file name the browser is supposed to use by default.
3569 In most browsers that understand this header, it makes it
3570 impossible to <span class="emphasis"><i class=
3571 "EMPHASIS">just view</i></span> the document, without
3572 downloading it first, even if it's just a simple text file
3576 Removing the <span class=
3577 "QUOTE">"Content-Disposition:"</span> header helps to
3578 prevent this annoyance, but some browsers additionally
3579 check the <span class="QUOTE">"Content-Type:"</span>
3580 header, before they decide if they can display a document
3581 without saving it first. In these cases, you have to change
3582 this header as well, before the browser stops displaying
3586 It is also possible to change the server's file name
3587 suggestion to another one, but in most cases it isn't worth
3588 the time to set it up.
3591 This action will probably be removed in the future, use
3592 server-header filters instead.
3601 <table border="0" bgcolor="#E0E0E0" width="90%">
3604 <pre class="SCREEN">
3605 # Disarm the download link in Sourceforge's patch tracker
3607 +content-type-overwrite{text/plain}\
3608 +hide-content-disposition{block} }
3609 .sourceforge.net/tracker/download\.php
3620 <a name="HIDE-IF-MODIFIED-SINCE">8.5.22.
3621 hide-if-modified-since</a>
3623 <div class="VARIABLELIST">
3630 Prevent yet another way to track the user's steps between
3639 Deletes the <span class="QUOTE">"If-Modified-Since:"</span>
3640 HTTP client header or modifies its value.
3656 Keyword: <span class="QUOTE">"block"</span>, or a user
3657 defined value that specifies a range of hours.
3665 Removing this header is useful for filter testing, where
3666 you want to force a real reload instead of getting status
3667 code <span class="QUOTE">"304"</span>, which would cause
3668 the browser to use a cached copy of the page.
3671 Instead of removing the header, <tt class=
3672 "LITERAL">hide-if-modified-since</tt> can also add or
3673 subtract a random amount of time to/from the header's
3674 value. You specify a range of minutes where the random
3675 factor should be chosen from and <span class=
3676 "APPLICATION">Privoxy</span> does the rest. A negative
3677 value means subtracting, a positive value adding.
3680 Randomizing the value of the <span class=
3681 "QUOTE">"If-Modified-Since:"</span> makes it less likely
3682 that the server can use the time as a cookie replacement,
3683 but you will run into caching problems if the random range
3687 It is a good idea to only use a small negative value and
3688 let <tt class="LITERAL"><a href=
3689 "actions-file.html#OVERWRITE-LAST-MODIFIED">overwrite-last-modified</a></tt>
3690 handle the greater changes.
3693 It is also recommended to use this action together with <tt
3694 class="LITERAL"><a href=
3695 "actions-file.html#CRUNCH-IF-NONE-MATCH">crunch-if-none-match</a></tt>,
3696 otherwise it's more or less pointless.
3700 Example usage (section):
3705 <table border="0" bgcolor="#E0E0E0" width="90%">
3708 <pre class="SCREEN">
3709 # Let the browser revalidate but make tracking based on the time less likely.
3710 {+hide-if-modified-since{-60} \
3711 +overwrite-last-modified{randomize} \
3712 +crunch-if-none-match}
3724 <a name="HIDE-FROM-HEADER">8.5.23. hide-from-header</a>
3726 <div class="VARIABLELIST">
3733 Keep your (old and ill) browser from telling web servers
3742 Deletes any existing <span class="QUOTE">"From:"</span>
3743 HTTP header, or replaces it with the specified string.
3759 Keyword: <span class="QUOTE">"block"</span>, or any user
3768 The keyword <span class="QUOTE">"block"</span> will
3769 completely remove the header (not to be confused with the
3770 <tt class="LITERAL"><a href=
3771 "actions-file.html#BLOCK">block</a></tt> action).
3774 Alternately, you can specify any value you prefer to be
3775 sent to the web server. If you do, it is a matter of
3776 fairness not to use any address that is actually used by a
3780 This action is rarely needed, as modern web browsers don't
3781 send <span class="QUOTE">"From:"</span> headers anymore.
3790 <table border="0" bgcolor="#E0E0E0" width="90%">
3793 <pre class="SCREEN">
3794 +hide-from-header{block}
3800 <table border="0" bgcolor="#E0E0E0" width="90%">
3803 <pre class="SCREEN">
3804 +hide-from-header{spam-me-senseless@sittingduck.example.com}
3815 <a name="HIDE-REFERRER">8.5.24. hide-referrer</a>
3817 <a name="HIDE-REFERER"></a>
3818 <div class="VARIABLELIST">
3825 Conceal which link you followed to get to a particular site
3833 Deletes the <span class="QUOTE">"Referer:"</span> (sic)
3834 HTTP header from the client request, or replaces it with a
3853 <span class="QUOTE">"conditional-block"</span> to
3854 delete the header completely if the host has changed.
3859 <span class="QUOTE">"conditional-forge"</span> to forge
3860 the header if the host has changed.
3865 <span class="QUOTE">"block"</span> to delete the header
3871 <span class="QUOTE">"forge"</span> to pretend to be
3872 coming from the homepage of the server we are talking
3878 Any other string to set a user defined referrer.
3888 <tt class="LITERAL">conditional-block</tt> is the only
3889 parameter, that isn't easily detected in the server's log
3890 file. If it blocks the referrer, the request will look like
3891 the visitor used a bookmark or typed in the address
3895 Leaving the referrer unmodified for requests on the same
3896 host allows the server owner to see the visitor's <span
3897 class="QUOTE">"click path"</span>, but in most cases she
3898 could also get that information by comparing other parts of
3899 the log file: for example the User-Agent if it isn't a very
3900 common one, or the user's IP address if it doesn't change
3901 between different requests.
3904 Always blocking the referrer, or using a custom one, can
3905 lead to failures on servers that check the referrer before
3906 they answer any requests, in an attempt to prevent their
3907 content from being embedded or linked to elsewhere.
3910 Both <tt class="LITERAL">conditional-block</tt> and <tt
3911 class="LITERAL">forge</tt> will work with referrer checks,
3912 as long as content and valid referring page are on the same
3913 host. Most of the time that's the case.
3916 <tt class="LITERAL">hide-referer</tt> is an alternate
3917 spelling of <tt class="LITERAL">hide-referrer</tt> and the
3918 two can be can be freely substituted with each other.
3919 (<span class="QUOTE">"referrer"</span> is the correct
3920 English spelling, however the HTTP specification has a bug
3921 - it requires it to be spelled as <span class=
3922 "QUOTE">"referer"</span>.)
3931 <table border="0" bgcolor="#E0E0E0" width="90%">
3934 <pre class="SCREEN">
3935 +hide-referrer{forge}
3941 <table border="0" bgcolor="#E0E0E0" width="90%">
3944 <pre class="SCREEN">
3945 +hide-referrer{http://www.yahoo.com/}
3956 <a name="HIDE-USER-AGENT">8.5.25. hide-user-agent</a>
3958 <div class="VARIABLELIST">
3965 Try to conceal your type of browser and client operating
3974 Replaces the value of the <span class=
3975 "QUOTE">"User-Agent:"</span> HTTP header in client requests
3976 with the specified value.
3992 Any user-defined string.
3999 <div class="WARNING">
4000 <table class="WARNING" border="1" width="90%">
4009 This can lead to problems on web sites that depend
4010 on looking at this header in order to customize
4011 their content for different browsers (which, by the
4012 way, is <span class="emphasis"><i class=
4013 "EMPHASIS">NOT</i></span> the right thing to do:
4014 good web sites work browser-independently).
4021 Using this action in multi-user setups or wherever
4022 different types of browsers will access the same <span
4023 class="APPLICATION">Privoxy</span> is <span class=
4024 "emphasis"><i class="EMPHASIS">not recommended</i></span>.
4025 In single-user, single-browser setups, you might use it to
4026 delete your OS version information from the headers,
4027 because it is an invitation to exploit known bugs for your
4028 OS. It is also occasionally useful to forge this in order
4029 to access sites that won't let you in otherwise (though
4030 there may be a good reason in some cases).
4033 More information on known user-agent strings can be found
4034 at <a href="http://www.user-agents.org/" target=
4035 "_top">http://www.user-agents.org/</a> and <a href=
4036 "http://en.wikipedia.org/wiki/User_agent" target=
4037 "_top">http://en.wikipedia.org/wiki/User_agent</a>.
4046 <table border="0" bgcolor="#E0E0E0" width="90%">
4049 <pre class="SCREEN">
4050 +hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}
4061 <a name="LIMIT-CONNECT">8.5.26. limit-connect</a>
4063 <div class="VARIABLELIST">
4070 Prevent abuse of <span class="APPLICATION">Privoxy</span>
4071 as a TCP proxy relay or disable SSL for untrusted sites
4079 Specifies to which ports HTTP CONNECT requests are
4096 A comma-separated list of ports or port ranges (the latter
4097 using dashes, with the minimum defaulting to 0 and the
4106 By default, i.e. if no <tt class=
4107 "LITERAL">limit-connect</tt> action applies, <span class=
4108 "APPLICATION">Privoxy</span> allows HTTP CONNECT requests
4109 to all ports. Use <tt class="LITERAL">limit-connect</tt> if
4110 fine-grained control is desired for some or all
4114 The CONNECT methods exists in HTTP to allow access to
4115 secure websites (<span class="QUOTE">"https://"</span>
4116 URLs) through proxies. It works very simply: the proxy
4117 connects to the server on the specified port, and then
4118 short-circuits its connections to the client and to the
4119 remote server. This means CONNECT-enabled proxies can be
4120 used as TCP relays very easily.
4123 <span class="APPLICATION">Privoxy</span> relays HTTPS
4124 traffic without seeing the decoded content. Websites can
4125 leverage this limitation to circumvent <span class=
4126 "APPLICATION">Privoxy</span>'s filters. By specifying an
4127 invalid port range you can disable HTTPS entirely.
4136 <table border="0" bgcolor="#E0E0E0" width="90%">
4139 <pre class="SCREEN">
4140 +limit-connect{443} # Port 443 is OK.
4141 +limit-connect{80,443} # Ports 80 and 443 are OK.
4142 +limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK.
4143 +limit-connect{-} # All ports are OK
4144 +limit-connect{,} # No HTTPS/SSL traffic is allowed
4155 <a name="PREVENT-COMPRESSION">8.5.27. prevent-compression</a>
4157 <div class="VARIABLELIST">
4164 Ensure that servers send the content uncompressed, so it
4165 can be passed through <tt class="LITERAL"><a href=
4166 "actions-file.html#FILTER">filter</a></tt>s.
4174 Removes the Accept-Encoding header which can be used to ask
4175 for compressed transfer.
4199 More and more websites send their content compressed by
4200 default, which is generally a good idea and saves
4201 bandwidth. But the <tt class="LITERAL"><a href=
4202 "actions-file.html#FILTER">filter</a></tt> and <tt class=
4204 "actions-file.html#DEANIMATE-GIFS">deanimate-gifs</a></tt>
4205 actions need access to the uncompressed data.
4208 When compiled with zlib support (available since <span
4209 class="APPLICATION">Privoxy</span> 3.0.7), content that
4210 should be filtered is decompressed on-the-fly and you don't
4211 have to worry about this action. If you are using an older
4212 <span class="APPLICATION">Privoxy</span> version, or one
4213 that hasn't been compiled with zlib support, this action
4214 can be used to convince the server to send the content
4218 Most text-based instances compress very well, the size is
4219 seldom decreased by less than 50%, for markup-heavy
4220 instances like news feeds saving more than 90% of the
4221 original size isn't unusual.
4224 Not using compression will therefore slow down the
4225 transfer, and you should only enable this action if you
4226 really need it. As of <span class=
4227 "APPLICATION">Privoxy</span> 3.0.7 it's disabled in all
4228 predefined action settings.
4231 Note that some (rare) ill-configured sites don't handle
4232 requests for uncompressed documents correctly. Broken PHP
4233 applications tend to send an empty document body, some IIS
4234 versions only send the beginning of the content. If you
4235 enable <tt class="LITERAL">prevent-compression</tt> per
4236 default, you might want to add exceptions for those sites.
4237 See the example for how to do that.
4241 Example usage (sections):
4246 <table border="0" bgcolor="#E0E0E0" width="90%">
4249 <pre class="SCREEN">
4250 # Selectively turn off compression, and enable a filter
4252 { +filter{tiny-textforms} +prevent-compression }
4253 # Match only these sites
4258 # Or instead, we could set a universal default:
4260 { +prevent-compression }
4263 # Then maybe make exceptions for broken sites:
4265 { -prevent-compression }
4277 <a name="OVERWRITE-LAST-MODIFIED">8.5.28.
4278 overwrite-last-modified</a>
4280 <div class="VARIABLELIST">
4287 Prevent yet another way to track the user's steps between
4296 Deletes the <span class="QUOTE">"Last-Modified:"</span>
4297 HTTP server header or modifies its value.
4313 One of the keywords: <span class="QUOTE">"block"</span>,
4314 <span class="QUOTE">"reset-to-request-time"</span> and
4315 <span class="QUOTE">"randomize"</span>
4323 Removing the <span class="QUOTE">"Last-Modified:"</span>
4324 header is useful for filter testing, where you want to
4325 force a real reload instead of getting status code <span
4326 class="QUOTE">"304"</span>, which would cause the browser
4327 to reuse the old version of the page.
4330 The <span class="QUOTE">"randomize"</span> option
4331 overwrites the value of the <span class=
4332 "QUOTE">"Last-Modified:"</span> header with a randomly
4333 chosen time between the original value and the current
4334 time. In theory the server could send each document with a
4335 different <span class="QUOTE">"Last-Modified:"</span>
4336 header to track visits without using cookies. <span class=
4337 "QUOTE">"Randomize"</span> makes it impossible and the
4338 browser can still revalidate cached documents.
4341 <span class="QUOTE">"reset-to-request-time"</span>
4342 overwrites the value of the <span class=
4343 "QUOTE">"Last-Modified:"</span> header with the current
4344 time. You could use this option together with <tt class=
4346 "actions-file.html#HIDE-IF-MODIFIED-SINCE">hide-if-modified-since</a></tt>
4347 to further customize your random range.
4350 The preferred parameter here is <span class=
4351 "QUOTE">"randomize"</span>. It is safe to use, as long as
4352 the time settings are more or less correct. If the server
4353 sets the <span class="QUOTE">"Last-Modified:"</span> header
4354 to the time of the request, the random range becomes zero
4355 and the value stays the same. Therefore you should later
4356 randomize it a second time with <tt class="LITERAL"><a
4358 "actions-file.html#HIDE-IF-MODIFIED-SINCE">hided-if-modified-since</a></tt>,
4362 It is also recommended to use this action together with <tt
4363 class="LITERAL"><a href=
4364 "actions-file.html#CRUNCH-IF-NONE-MATCH">crunch-if-none-match</a></tt>.
4373 <table border="0" bgcolor="#E0E0E0" width="90%">
4376 <pre class="SCREEN">
4377 # Let the browser revalidate without being tracked across sessions
4378 { +hide-if-modified-since{-60} \
4379 +overwrite-last-modified{randomize} \
4380 +crunch-if-none-match}
4392 <a name="REDIRECT">8.5.29. redirect</a>
4394 <div class="VARIABLELIST">
4401 Redirect requests to other sites.
4409 Convinces the browser that the requested document has been
4410 moved to another location and the browser should get it
4427 An absolute URL or a single pcrs command.
4435 Requests to which this action applies are answered with a
4436 HTTP redirect to URLs of your choosing. The new URL is
4437 either provided as parameter, or derived by applying a
4438 single pcrs command to the original URL.
4441 This action will be ignored if you use it together with <tt
4442 class="LITERAL"><a href=
4443 "actions-file.html#BLOCK">block</a></tt>. It can be
4444 combined with <tt class="LITERAL"><a href=
4445 "actions-file.html#FAST-REDIRECTS">fast-redirects{check-decoded-url}</a></tt>
4446 to redirect to a decoded version of a rewritten URL.
4449 Use this action carefully, make sure not to create
4450 redirection loops and be aware that using your own
4451 redirects might make it possible to fingerprint your
4455 In case of problems with your redirects, or simply to watch
4456 them working, enable <a href="config.html#DEBUG">debug
4466 <table border="0" bgcolor="#E0E0E0" width="90%">
4469 <pre class="SCREEN">
4470 # Replace example.com's style sheet with another one
4471 { +redirect{http://localhost/css-replacements/example.com.css} }
4472 example.com/stylesheet\.css
4474 # Create a short, easy to remember nickname for a favorite site
4475 # (relies on the browser accept and forward invalid URLs to <span class=
4476 "APPLICATION">Privoxy</span>)
4477 { +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
4480 # Always use the expanded view for Undeadly.org articles
4481 # (Note the $ at the end of the URL pattern to make sure
4482 # the request for the rewritten URL isn't redirected as well)
4483 {+redirect{s@$@&mode=expanded@}}
4484 undeadly.org/cgi\?action=article&sid=\d*$
4486 # Redirect Google search requests to MSN
4487 {+redirect{s@^http://[^/]*/search\?q=([^&]*).*@http://search.msn.com/results.aspx?q=$1@}}
4490 # Redirect MSN search requests to Yahoo
4491 {+redirect{s@^http://[^/]*/results\.aspx\?q=([^&]*).*@http://search.yahoo.com/search?p=$1@}}
4492 search.msn.com//results\.aspx\?q=
4494 # Redirect remote requests for this manual
4495 # to the local version delivered by Privoxy
4496 {+redirect{s@^http://www@http://config@}}
4497 www.privoxy.org/user-manual/
4508 <a name="SERVER-HEADER-FILTER">8.5.30. server-header-filter</a>
4510 <div class="VARIABLELIST">
4517 Rewrite or remove single server headers.
4525 All server headers to which this action applies are
4526 filtered on-the-fly through the specified regular
4527 expression based substitutions.
4543 The name of a server-header filter, as defined in one of
4544 the <a href="filter-file.html">filter files</a>.
4552 Server-header filters are applied to each header on its
4553 own, not to all at once. This makes it easier to diagnose
4554 problems, but on the downside you can't write filters that
4555 only change header x if header y's value is z. You can do
4556 that by using tags though.
4559 Server-header filters are executed after the other header
4560 actions have finished and use their output as input.
4563 Please refer to the <a href="filter-file.html">filter file
4564 chapter</a> to learn which server-header filters are
4565 available by default, and how to create your own.
4569 Example usage (section):
4574 <table border="0" bgcolor="#E0E0E0" width="90%">
4577 <pre class="SCREEN">
4578 {+server-header-filter{html-to-xml}}
4579 example.org/xml-instance-that-is-delivered-as-html
4581 {+server-header-filter{xml-to-html}}
4582 example.org/instance-that-is-delivered-as-xml-but-is-not
4594 <a name="SERVER-HEADER-TAGGER">8.5.31. server-header-tagger</a>
4596 <div class="VARIABLELIST">
4603 Enable or disable filters based on the Content-Type header.
4611 Server headers to which this action applies are filtered
4612 on-the-fly through the specified regular expression based
4613 substitutions, the result is used as tag.
4629 The name of a server-header tagger, as defined in one of
4630 the <a href="filter-file.html">filter files</a>.
4638 Server-header taggers are applied to each header on its
4639 own, and as the header isn't modified, each tagger <span
4640 class="QUOTE">"sees"</span> the original.
4643 Server-header taggers are executed before all other header
4644 actions that modify server headers. Their tags can be used
4645 to control all of the other server-header actions, the
4646 content filters and the crunch actions (<a href=
4647 "actions-file.html#REDIRECT">redirect</a> and <a href=
4648 "actions-file.html#BLOCK">block</a>).
4651 Obviously crunching based on tags created by server-header
4652 taggers doesn't prevent the request from showing up in the
4657 Example usage (section):
4662 <table border="0" bgcolor="#E0E0E0" width="90%">
4665 <pre class="SCREEN">
4666 # Tag every request with the content type declared by the server
4667 {+server-header-tagger{content-type}}
4680 <a name="SESSION-COOKIES-ONLY">8.5.32. session-cookies-only</a>
4682 <div class="VARIABLELIST">
4689 Allow only temporary <span class="QUOTE">"session"</span>
4690 cookies (for the current browser session <span class=
4691 "emphasis"><i class="EMPHASIS">only</i></span>).
4699 Deletes the <span class="QUOTE">"expires"</span> field from
4700 <span class="QUOTE">"Set-Cookie:"</span> server headers.
4701 Most browsers will not store such cookies permanently and
4702 forget them in between sessions.
4726 This is less strict than <tt class="LITERAL"><a href=
4727 "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a></tt>
4728 / <tt class="LITERAL"><a href=
4729 "actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a></tt>
4730 and allows you to browse websites that insist or rely on
4731 setting cookies, without compromising your privacy too
4735 Most browsers will not permanently store cookies that have
4736 been processed by <tt class=
4737 "LITERAL">session-cookies-only</tt> and will forget about
4738 them between sessions. This makes profiling cookies
4739 useless, but won't break sites which require cookies so
4740 that you can log in for transactions. This is generally
4741 turned on for all sites, and is the recommended setting.
4744 It makes <span class="emphasis"><i class="EMPHASIS">no
4745 sense at all</i></span> to use <tt class=
4746 "LITERAL">session-cookies-only</tt> together with <tt
4747 class="LITERAL"><a href=
4748 "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a></tt>
4749 or <tt class="LITERAL"><a href=
4750 "actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a></tt>.
4751 If you do, cookies will be plainly killed.
4754 Note that it is up to the browser how it handles such
4755 cookies without an <span class="QUOTE">"expires"</span>
4756 field. If you use an exotic browser, you might want to try
4760 This setting also has no effect on cookies that may have
4761 been stored previously by the browser before starting <span
4762 class="APPLICATION">Privoxy</span>. These would have to be
4766 <span class="APPLICATION">Privoxy</span> also uses the <a
4768 "actions-file.html#FILTER-CONTENT-COOKIES">content-cookies
4769 filter</a> to block some types of cookies. Content cookies
4770 are not effected by <tt class=
4771 "LITERAL">session-cookies-only</tt>.
4780 <table border="0" bgcolor="#E0E0E0" width="90%">
4783 <pre class="SCREEN">
4784 +session-cookies-only
4795 <a name="SET-IMAGE-BLOCKER">8.5.33. set-image-blocker</a>
4797 <div class="VARIABLELIST">
4804 Choose the replacement for blocked images
4812 This action alone doesn't do anything noticeable. If <span
4813 class="emphasis"><i class="EMPHASIS">both</i></span> <tt
4814 class="LITERAL"><a href=
4815 "actions-file.html#BLOCK">block</a></tt> <span class=
4816 "emphasis"><i class="EMPHASIS">and</i></span> <tt class=
4818 "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt>
4819 <span class="emphasis"><i class="EMPHASIS">also</i></span>
4820 apply, i.e. if the request is to be blocked as an image,
4821 <span class="emphasis"><i class="EMPHASIS">then</i></span>
4822 the parameter of this action decides what will be sent as a
4841 <span class="QUOTE">"pattern"</span> to send a built-in
4842 checkerboard pattern image. The image is visually
4843 decent, scales very well, and makes it obvious where
4844 banners were busted.
4849 <span class="QUOTE">"blank"</span> to send a built-in
4850 transparent image. This makes banners disappear
4851 completely, but makes it hard to detect where <span
4852 class="APPLICATION">Privoxy</span> has blocked images
4853 on a given page and complicates troubleshooting if
4854 <span class="APPLICATION">Privoxy</span> has blocked
4855 innocent images, like navigation icons.
4860 <span class="QUOTE">"<tt class=
4861 "REPLACEABLE"><i>target-url</i></tt>"</span> to send a
4862 redirect to <tt class=
4863 "REPLACEABLE"><i>target-url</i></tt>. You can redirect
4864 to any image anywhere, even in your local filesystem
4865 via <span class="QUOTE">"file:///"</span> URL. (But
4866 note that not all browsers support redirecting to a
4870 A good application of redirects is to use special <span
4871 class="APPLICATION">Privoxy</span>-built-in URLs, which
4872 send the built-in images, as <tt class=
4873 "REPLACEABLE"><i>target-url</i></tt>. This has the same
4874 visual effect as specifying <span class=
4875 "QUOTE">"blank"</span> or <span class=
4876 "QUOTE">"pattern"</span> in the first place, but
4877 enables your browser to cache the replacement image,
4878 instead of requesting it over and over again.
4888 The URLs for the built-in images are <span class=
4889 "QUOTE">"http://config.privoxy.org/send-banner?type=<tt
4890 class="REPLACEABLE"><i>type</i></tt>"</span>, where <tt
4891 class="REPLACEABLE"><i>type</i></tt> is either <span class=
4892 "QUOTE">"blank"</span> or <span class=
4893 "QUOTE">"pattern"</span>.
4896 There is a third (advanced) type, called <span class=
4897 "QUOTE">"auto"</span>. It is <span class="emphasis"><i
4898 class="EMPHASIS">NOT</i></span> to be used in <tt class=
4899 "LITERAL">set-image-blocker</tt>, but meant for use from <a
4900 href="filter-file.html">filters</a>. Auto will select the
4901 type of image that would have applied to the referring
4902 page, had it been an image.
4914 <table border="0" bgcolor="#E0E0E0" width="90%">
4917 <pre class="SCREEN">
4918 +set-image-blocker{pattern}
4925 Redirect to the BSD daemon:
4929 <table border="0" bgcolor="#E0E0E0" width="90%">
4932 <pre class="SCREEN">
4933 +set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}
4940 Redirect to the built-in pattern for better caching:
4944 <table border="0" bgcolor="#E0E0E0" width="90%">
4947 <pre class="SCREEN">
4948 +set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}
4959 <a name="AEN4549">8.5.34. Summary</a>
4962 Note that many of these actions have the potential to cause a
4963 page to misbehave, possibly even not to display at all. There are
4964 many ways a site designer may choose to design his site, and what
4965 HTTP header content, and other criteria, he may depend on. There
4966 is no way to have hard and fast rules for all sites. See the <a
4967 href="appendix.html#ACTIONSANAT">Appendix</a> for a brief example
4968 on troubleshooting actions.
4974 <a name="ALIASES">8.6. Aliases</a>
4977 Custom <span class="QUOTE">"actions"</span>, known to <span class=
4978 "APPLICATION">Privoxy</span> as <span class=
4979 "QUOTE">"aliases"</span>, can be defined by combining other
4980 actions. These can in turn be invoked just like the built-in
4981 actions. Currently, an alias name can contain any character except
4982 space, tab, <span class="QUOTE">"="</span>, <span class=
4983 "QUOTE">"{"</span> and <span class="QUOTE">"}"</span>, but we <span
4984 class="emphasis"><i class="EMPHASIS">strongly recommend</i></span>
4985 that you only use <span class="QUOTE">"a"</span> to <span class=
4986 "QUOTE">"z"</span>, <span class="QUOTE">"0"</span> to <span class=
4987 "QUOTE">"9"</span>, <span class="QUOTE">"+"</span>, and <span
4988 class="QUOTE">"-"</span>. Alias names are not case sensitive, and
4989 are not required to start with a <span class="QUOTE">"+"</span> or
4990 <span class="QUOTE">"-"</span> sign, since they are merely
4994 Aliases can be used throughout the actions file, but they <span
4995 class="emphasis"><i class="EMPHASIS">must be defined in a special
4996 section at the top of the file!</i></span> And there can only be
4997 one such section per actions file. Each actions file may have its
4998 own alias section, and the aliases defined in it are only visible
5002 There are two main reasons to use aliases: One is to save typing
5003 for frequently used combinations of actions, the other one is a
5004 gain in flexibility: If you decide once how you want to handle
5005 shops by defining an alias called <span class=
5006 "QUOTE">"shop"</span>, you can later change your policy on shops in
5007 <span class="emphasis"><i class="EMPHASIS">one</i></span> place,
5008 and your changes will take effect everywhere in the actions file
5009 where the <span class="QUOTE">"shop"</span> alias is used. Calling
5010 aliases by their purpose also makes your actions files more
5014 Currently, there is one big drawback to using aliases, though:
5015 <span class="APPLICATION">Privoxy</span>'s built-in web-based
5016 action file editor honors aliases when reading the actions files,
5017 but it expands them before writing. So the effects of your aliases
5018 are of course preserved, but the aliases themselves are lost when
5019 you edit sections that use aliases with it.
5022 Now let's define some aliases...
5026 <table border="0" bgcolor="#E0E0E0" width="100%">
5029 <pre class="SCREEN">
5030 # Useful custom aliases we can use later.
5032 # Note the (required!) section header line and that this section
5033 # must be at the top of the actions file!
5037 # These aliases just save typing later:
5038 # (Note that some already use other aliases!)
5040 +crunch-all-cookies = +<a href=
5041 "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a> +<a
5042 href="actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a>
5043 -crunch-all-cookies = -<a href=
5044 "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a> -<a
5045 href="actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a>
5046 +block-as-image = +block{Blocked image.} +handle-as-image
5047 allow-all-cookies = -crunch-all-cookies -<a href=
5048 "actions-file.html#SESSION-COOKIES-ONLY">session-cookies-only</a> -<a href=
5049 "actions-file.html#FILTER-CONTENT-COOKIES">filter{content-cookies}</a>
5051 # These aliases define combinations of actions
5052 # that are useful for certain types of sites:
5054 fragile = -<a href="actions-file.html#BLOCK">block</a> -<a href=
5055 "actions-file.html#FILTER">filter</a> -crunch-all-cookies -<a href=
5056 "actions-file.html#FAST-REDIRECTS">fast-redirects</a> -<a href=
5057 "actions-file.html#HIDE-REFERER">hide-referrer</a> -<a href=
5058 "actions-file.html#PREVENT-COMPRESSION">prevent-compression</a>
5060 shop = -crunch-all-cookies -<a href=
5061 "actions-file.html#FILTER-ALL-POPUPS">filter{all-popups}</a>
5063 # Short names for other aliases, for really lazy people ;-)
5065 c0 = +crunch-all-cookies
5066 c1 = -crunch-all-cookies
5073 ...and put them to use. These sections would appear in the lower
5074 part of an actions file and define exceptions to the default
5075 actions (as specified further up for the <span class=
5076 "QUOTE">"/"</span> pattern):
5080 <table border="0" bgcolor="#E0E0E0" width="100%">
5083 <pre class="SCREEN">
5084 # These sites are either very complex or very keen on
5085 # user data and require minimal interference to work:
5088 .office.microsoft.com
5089 .windowsupdate.microsoft.com
5090 # Gmail is really mail.google.com, not gmail.com
5094 # Allow cookies (for setting and retrieving your customer data)
5098 .worldpay.com # for quietpc.com
5101 # These shops require pop-ups:
5103 {-filter{all-popups} -filter{unsolicited-popups}}
5112 Aliases like <span class="QUOTE">"shop"</span> and <span class=
5113 "QUOTE">"fragile"</span> are typically used for <span class=
5114 "QUOTE">"problem"</span> sites that require more than one action to
5115 be disabled in order to function properly.
5120 <a name="ACT-EXAMPLES">8.7. Actions Files Tutorial</a>
5123 The above chapters have shown <a href="actions-file.html">which
5124 actions files there are and how they are organized</a>, how actions
5125 are <a href="actions-file.html#ACTIONS">specified</a> and <a href=
5126 "actions-file.html#ACTIONS-APPLY">applied to URLs</a>, how <a href=
5127 "actions-file.html#AF-PATTERNS">patterns</a> work, and how to
5128 define and use <a href="actions-file.html#ALIASES">aliases</a>.
5129 Now, let's look at an example <tt class=
5130 "FILENAME">match-all.action</tt>, <tt class=
5131 "FILENAME">default.action</tt> and <tt class=
5132 "FILENAME">user.action</tt> file and see how all these pieces come
5137 <a name="AEN4613">8.7.1. match-all.action</a>
5140 Remember <span class="emphasis"><i class="EMPHASIS">all actions
5141 are disabled when matching starts</i></span>, so we have to
5142 explicitly enable the ones we want.
5145 While the <tt class="FILENAME">match-all.action</tt> file only
5146 contains a single section, it is probably the most important one.
5147 It has only one pattern, <span class="QUOTE">"<tt class=
5148 "LITERAL">/</tt>"</span>, but this pattern <a href=
5149 "actions-file.html#AF-PATTERNS">matches all URLs</a>. Therefore,
5150 the set of actions used in this <span class=
5151 "QUOTE">"default"</span> section <span class="emphasis"><i class=
5152 "EMPHASIS">will be applied to all requests as a start</i></span>.
5153 It can be partly or wholly overridden by other actions files like
5154 <tt class="FILENAME">default.action</tt> and <tt class=
5155 "FILENAME">user.action</tt>, but it will still be largely
5156 responsible for your overall browsing experience.
5159 Again, at the start of matching, all actions are disabled, so
5160 there is no need to disable any actions here. (Remember: a <span
5161 class="QUOTE">"+"</span> preceding the action name enables the
5162 action, a <span class="QUOTE">"-"</span> disables!). Also note
5163 how this long line has been made more readable by splitting it
5164 into multiple lines with line continuation.
5168 <table border="0" bgcolor="#E0E0E0" width="100%">
5171 <pre class="SCREEN">
5174 "actions-file.html#CHANGE-X-FORWARDED-FOR">change-x-forwarded-for{block}</a> \
5175 +<a href="actions-file.html#HIDE-FROM-HEADER">hide-from-header{block}</a> \
5177 "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker{pattern}</a> \
5186 The default behavior is now set.
5191 <a name="AEN4635">8.7.2. default.action</a>
5194 If you aren't a developer, there's no need for you to edit the
5195 <tt class="FILENAME">default.action</tt> file. It is maintained
5196 by the <span class="APPLICATION">Privoxy</span> developers and if
5197 you disagree with some of the sections, you should overrule them
5198 in your <tt class="FILENAME">user.action</tt>.
5201 Understanding the <tt class="FILENAME">default.action</tt> file
5202 can help you with your <tt class="FILENAME">user.action</tt>,
5206 The first section in this file is a special section for internal
5207 use that prevents older <span class="APPLICATION">Privoxy</span>
5208 versions from reading the file:
5212 <table border="0" bgcolor="#E0E0E0" width="100%">
5215 <pre class="SCREEN">
5216 ##########################################################################
5217 # Settings -- Don't change! For internal Privoxy use ONLY.
5218 ##########################################################################
5220 for-privoxy-version=3.0.11
5227 After that comes the (optional) alias section. We'll use the
5228 example section from the above <a href=
5229 "actions-file.html#ALIASES">chapter on aliases</a>, that also
5230 explains why and how aliases are used:
5234 <table border="0" bgcolor="#E0E0E0" width="100%">
5237 <pre class="SCREEN">
5238 ##########################################################################
5240 ##########################################################################
5243 # These aliases just save typing later:
5244 # (Note that some already use other aliases!)
5246 +crunch-all-cookies = +<a href=
5247 "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a> +<a
5248 href="actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a>
5249 -crunch-all-cookies = -<a href=
5250 "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a> -<a
5251 href="actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a>
5252 +block-as-image = +block{Blocked image.} +handle-as-image
5253 mercy-for-cookies = -crunch-all-cookies -<a href=
5254 "actions-file.html#SESSION-COOKIES-ONLY">session-cookies-only</a> -<a href=
5255 "actions-file.html#FILTER-CONTENT-COOKIES">filter{content-cookies}</a>
5257 # These aliases define combinations of actions
5258 # that are useful for certain types of sites:
5260 fragile = -<a href="actions-file.html#BLOCK">block</a> -<a href=
5261 "actions-file.html#FILTER">filter</a> -crunch-all-cookies -<a href=
5262 "actions-file.html#FAST-REDIRECTS">fast-redirects</a> -<a href=
5263 "actions-file.html#HIDE-REFERER">hide-referrer</a>
5264 shop = -crunch-all-cookies -<a href=
5265 "actions-file.html#FILTER-ALL-POPUPS">filter{all-popups}</a>
5272 The first of our specialized sections is concerned with <span
5273 class="QUOTE">"fragile"</span> sites, i.e. sites that require
5274 minimum interference, because they are either very complex or
5275 very keen on tracking you (and have mechanisms in place that make
5276 them unusable for people who avoid being tracked). We will simply
5277 use our pre-defined <tt class="LITERAL">fragile</tt> alias
5278 instead of stating the list of actions explicitly:
5282 <table border="0" bgcolor="#E0E0E0" width="100%">
5285 <pre class="SCREEN">
5286 ##########################################################################
5287 # Exceptions for sites that'll break under the default action set:
5288 ##########################################################################
5290 # "Fragile" Use a minimum set of actions for these sites (see alias above):
5293 .office.microsoft.com # surprise, surprise!
5294 .windowsupdate.microsoft.com
5302 Shopping sites are not as fragile, but they typically require
5303 cookies to log in, and pop-up windows for shopping carts or item
5304 details. Again, we'll use a pre-defined alias:
5308 <table border="0" bgcolor="#E0E0E0" width="100%">
5311 <pre class="SCREEN">
5316 .worldpay.com # for quietpc.com
5325 The <tt class="LITERAL"><a href=
5326 "actions-file.html#FAST-REDIRECTS">fast-redirects</a></tt>
5327 action, which may have been enabled in <tt class=
5328 "FILENAME">match-all.action</tt>, breaks some sites. So disable
5329 it for popular sites where we know it misbehaves:
5333 <table border="0" bgcolor="#E0E0E0" width="100%">
5336 <pre class="SCREEN">
5337 { -<a href="actions-file.html#FAST-REDIRECTS">fast-redirects</a> }
5341 .altavista.com/.*(like|url|link):http
5342 .altavista.com/trans.*urltext=http
5350 It is important that <span class="APPLICATION">Privoxy</span>
5351 knows which URLs belong to images, so that <span class=
5352 "emphasis"><i class="EMPHASIS">if</i></span> they are to be
5353 blocked, a substitute image can be sent, rather than an HTML
5354 page. Contacting the remote site to find out is not an option,
5355 since it would destroy the loading time advantage of banner
5356 blocking, and it would feed the advertisers information about
5357 you. We can mark any URL as an image with the <tt class=
5359 "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt>
5360 action, and marking all URLs that end in a known image file
5361 extension is a good start:
5365 <table border="0" bgcolor="#E0E0E0" width="100%">
5368 <pre class="SCREEN">
5369 ##########################################################################
5371 ##########################################################################
5373 # Define which file types will be treated as images, in case they get
5374 # blocked further down this file:
5376 { +<a href="actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a> }
5377 /.*\.(gif|jpe?g|png|bmp|ico)$
5384 And then there are known banner sources. They often use scripts
5385 to generate the banners, so it won't be visible from the URL that
5386 the request is for an image. Hence we block them <span class=
5387 "emphasis"><i class="EMPHASIS">and</i></span> mark them as images
5388 in one go, with the help of our <tt class=
5389 "LITERAL">+block-as-image</tt> alias defined above. (We could of
5390 course just as well use <tt class="LITERAL">+<a href=
5391 "actions-file.html#BLOCK">block</a> +<a href=
5392 "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt>
5393 here.) Remember that the type of the replacement image is chosen
5394 by the <tt class="LITERAL"><a href=
5395 "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></tt>
5396 action. Since all URLs have matched the default section with its
5397 <tt class="LITERAL">+<a href=
5398 "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a>{pattern}</tt>
5399 action before, it still applies and needn't be repeated:
5403 <table border="0" bgcolor="#E0E0E0" width="100%">
5406 <pre class="SCREEN">
5407 # Known ad generators:
5412 .ad.*.doubleclick.net
5413 .a.yimg.com/(?:(?!/i/).)*$
5414 .a[0-9].yimg.com/(?:(?!/i/).)*$
5423 One of the most important jobs of <span class=
5424 "APPLICATION">Privoxy</span> is to block banners. Many of these
5425 can be <span class="QUOTE">"blocked"</span> by the <tt class=
5427 "actions-file.html#FILTER">filter</a>{banners-by-size}</tt>
5428 action, which we enabled above, and which deletes the references
5429 to banner images from the pages while they are loaded, so the
5430 browser doesn't request them anymore, and hence they don't need
5431 to be blocked here. But this naturally doesn't catch all banners,
5432 and some people choose not to use filters, so we need a
5433 comprehensive list of patterns for banner URLs here, and apply
5434 the <tt class="LITERAL"><a href=
5435 "actions-file.html#BLOCK">block</a></tt> action to them.
5438 First comes many generic patterns, which do most of the work, by
5439 matching typical domain and path name components of banners. Then
5440 comes a list of individual patterns for specific sites, which is
5441 omitted here to keep the example short:
5445 <table border="0" bgcolor="#E0E0E0" width="100%">
5448 <pre class="SCREEN">
5449 ##########################################################################
5450 # Block these fine banners:
5451 ##########################################################################
5452 { <a href="actions-file.html#BLOCK">+block{Banner ads.}</a> }
5460 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
5461 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
5463 # Site-specific patterns (abbreviated):
5472 It's quite remarkable how many advertisers actually call their
5473 banner servers ads.<tt class=
5474 "REPLACEABLE"><i>company</i></tt>.com, or call the directory in
5475 which the banners are stored simply <span class=
5476 "QUOTE">"banners"</span>. So the above generic patterns are
5477 surprisingly effective.
5480 But being very generic, they necessarily also catch URLs that we
5481 don't want to block. The pattern <tt class="LITERAL">.*ads.</tt>
5482 e.g. catches <span class="QUOTE">"nasty-<span class="emphasis"><i
5483 class="EMPHASIS">ads</i></span>.nasty-corp.com"</span> as
5484 intended, but also <span class="QUOTE">"downlo<span class=
5485 "emphasis"><i class=
5486 "EMPHASIS">ads</i></span>.sourcefroge.net"</span> or <span class=
5487 "QUOTE">"<span class="emphasis"><i class=
5488 "EMPHASIS">ads</i></span>l.some-provider.net."</span> So here
5489 come some well-known exceptions to the <tt class="LITERAL">+<a
5490 href="actions-file.html#BLOCK">block</a></tt> section above.
5493 Note that these are exceptions to exceptions from the default!
5494 Consider the URL <span class=
5495 "QUOTE">"downloads.sourcefroge.net"</span>: Initially, all
5496 actions are deactivated, so it wouldn't get blocked. Then comes
5497 the defaults section, which matches the URL, but just deactivates
5498 the <tt class="LITERAL"><a href=
5499 "actions-file.html#BLOCK">block</a></tt> action once again. Then
5500 it matches <tt class="LITERAL">.*ads.</tt>, an exception to the
5501 general non-blocking policy, and suddenly <tt class="LITERAL"><a
5502 href="actions-file.html#BLOCK">+block</a></tt> applies. And now,
5503 it'll match <tt class="LITERAL">.*loads.</tt>, where <tt class=
5504 "LITERAL"><a href="actions-file.html#BLOCK">-block</a></tt>
5505 applies, so (unless it matches <span class="emphasis"><i class=
5506 "EMPHASIS">again</i></span> further down) it ends up with no <tt
5507 class="LITERAL"><a href="actions-file.html#BLOCK">block</a></tt>
5512 <table border="0" bgcolor="#E0E0E0" width="100%">
5515 <pre class="SCREEN">
5516 ##########################################################################
5517 # Save some innocent victims of the above generic block patterns:
5518 ##########################################################################
5522 { -<a href="actions-file.html#BLOCK">block</a> }
5523 adv[io]*. # (for advogato.org and advice.*)
5524 adsl. # (has nothing to do with ads)
5525 adobe. # (has nothing to do with ads either)
5526 ad[ud]*. # (adult.* and add.*)
5527 .edu # (universities don't host banners (yet!))
5528 .*loads. # (downloads, uploads etc)
5536 www.globalintersec.com/adv # (adv = advanced)
5537 www.ugu.com/sui/ugu/adv
5544 Filtering source code can have nasty side effects, so make an
5545 exception for our friends at sourceforge.net, and all paths with
5546 <span class="QUOTE">"cvs"</span> in them. Note that <tt class=
5547 "LITERAL">-<a href="actions-file.html#FILTER">filter</a></tt>
5548 disables <span class="emphasis"><i class=
5549 "EMPHASIS">all</i></span> filters in one fell swoop!
5553 <table border="0" bgcolor="#E0E0E0" width="100%">
5556 <pre class="SCREEN">
5557 # Don't filter code!
5559 { -<a href="actions-file.html#FILTER">filter</a> }
5571 The actual <tt class="FILENAME">default.action</tt> is of course
5572 much more comprehensive, but we hope this example made clear how
5578 <a name="AEN4748">8.7.3. user.action</a>
5581 So far we are painting with a broad brush by setting general
5582 policies, which would be a reasonable starting point for many
5583 people. Now, you might want to be more specific and have
5584 customized rules that are more suitable to your personal habits
5585 and preferences. These would be for narrowly defined situations
5586 like your ISP or your bank, and should be placed in <tt class=
5587 "FILENAME">user.action</tt>, which is parsed after all other
5588 actions files and hence has the last word, over-riding any
5589 previously defined actions. <tt class="FILENAME">user.action</tt>
5590 is also a <span class="emphasis"><i class=
5591 "EMPHASIS">safe</i></span> place for your personal settings,
5592 since <tt class="FILENAME">default.action</tt> is actively
5593 maintained by the <span class="APPLICATION">Privoxy</span>
5594 developers and you'll probably want to install updated versions
5598 So let's look at a few examples of things that one might
5599 typically do in <tt class="FILENAME">user.action</tt>:
5603 <table border="0" bgcolor="#E0E0E0" width="100%">
5606 <pre class="SCREEN">
5607 # My user.action file. <fred@example.com>
5614 As <a href="actions-file.html#ALIASES">aliases</a> are local to
5615 the actions file that they are defined in, you can't use the ones
5616 from <tt class="FILENAME">default.action</tt>, unless you repeat
5621 <table border="0" bgcolor="#E0E0E0" width="100%">
5624 <pre class="SCREEN">
5625 # Aliases are local to the file they are defined in.
5626 # (Re-)define aliases for this file:
5630 # These aliases just save typing later, and the alias names should
5631 # be self explanatory.
5633 +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
5634 -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
5635 allow-all-cookies = -crunch-all-cookies -session-cookies-only
5636 allow-popups = -filter{all-popups}
5637 +block-as-image = +block{Blocked as image.} +handle-as-image
5638 -block-as-image = -block
5640 # These aliases define combinations of actions that are useful for
5641 # certain types of sites:
5643 fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer
5644 shop = -crunch-all-cookies allow-popups
5646 # Allow ads for selected useful free sites:
5648 allow-ads = -block -filter{banners-by-size} -filter{banners-by-link}
5650 # Alias for specific file types that are text, but might have conflicting
5651 # MIME types. We want the browser to force these to be text documents.
5652 handle-as-text = -<a href="actions-file.html#FILTER">filter</a> +-<a href=
5653 "actions-file.html#CONTENT-TYPE-OVERWRITE">content-type-overwrite{text/plain}</a> +-<a
5654 href="actions-file.html#FORCE-TEXT-MODE">force-text-mode</a> -<a href=
5655 "actions-file.html#HIDE-CONTENT-DISPOSITION">hide-content-disposition</a>
5663 Say you have accounts on some sites that you visit regularly, and
5664 you don't want to have to log in manually each time. So you'd
5665 like to allow persistent cookies for these sites. The <tt class=
5666 "LITERAL">allow-all-cookies</tt> alias defined above does exactly
5667 that, i.e. it disables crunching of cookies in any direction, and
5668 the processing of cookies to make them only temporary.
5672 <table border="0" bgcolor="#E0E0E0" width="100%">
5675 <pre class="SCREEN">
5676 { allow-all-cookies }
5687 Your bank is allergic to some filter, but you don't know which,
5688 so you disable them all:
5692 <table border="0" bgcolor="#E0E0E0" width="100%">
5695 <pre class="SCREEN">
5696 { -<a href="actions-file.html#FILTER">filter</a> }
5697 .your-home-banking-site.com
5704 Some file types you may not want to filter for various reasons:
5708 <table border="0" bgcolor="#E0E0E0" width="100%">
5711 <pre class="SCREEN">
5712 # Technical documentation is likely to contain strings that might
5713 # erroneously get altered by the JavaScript-oriented filters:
5718 # And this stupid host sends streaming video with a wrong MIME type,
5719 # so that Privoxy thinks it is getting HTML and starts filtering:
5721 stupid-server.example.com/
5728 Example of a simple <a href="actions-file.html#BLOCK">block</a>
5729 action. Say you've seen an ad on your favourite page on
5730 example.com that you want to get rid of. You have right-clicked
5731 the image, selected <span class="QUOTE">"copy image
5732 location"</span> and pasted the URL below while removing the
5733 leading http://, into a <tt class="LITERAL">{ +block{} }</tt>
5734 section. Note that <tt class="LITERAL">{ +handle-as-image }</tt>
5735 need not be specified, since all URLs ending in <tt class=
5736 "LITERAL">.gif</tt> will be tagged as images by the general rules
5737 as set in default.action anyway:
5741 <table border="0" bgcolor="#E0E0E0" width="100%">
5744 <pre class="SCREEN">
5745 { +<a href="actions-file.html#BLOCK">block</a>{Nasty ads.} }
5746 www.example.com/nasty-ads/sponsor\.gif
5747 another.example.net/more/junk/here/
5754 The URLs of dynamically generated banners, especially from large
5755 banner farms, often don't use the well-known image file name
5756 extensions, which makes it impossible for <span class=
5757 "APPLICATION">Privoxy</span> to guess the file type just by
5758 looking at the URL. You can use the <tt class=
5759 "LITERAL">+block-as-image</tt> alias defined above for these
5760 cases. Note that objects which match this rule but then turn out
5761 NOT to be an image are typically rendered as a <span class=
5762 "QUOTE">"broken image"</span> icon by the browser. Use
5767 <table border="0" bgcolor="#E0E0E0" width="100%">
5770 <pre class="SCREEN">
5782 Now you noticed that the default configuration breaks Forbes
5783 Magazine, but you were too lazy to find out which action is the
5784 culprit, and you were again too lazy to give <a href=
5785 "contact.html">feedback</a>, so you just used the <tt class=
5786 "LITERAL">fragile</tt> alias on the site, and -- <span class=
5787 "emphasis"><i class="EMPHASIS">whoa!</i></span> -- it worked. The
5788 <tt class="LITERAL">fragile</tt> aliases disables those actions
5789 that are most likely to break a site. Also, good for testing
5790 purposes to see if it is <span class="APPLICATION">Privoxy</span>
5791 that is causing the problem or not. We later find other regular
5792 sites that misbehave, and add those to our personalized list of
5795 <table border="0" bgcolor="#E0E0E0" width="100%">
5798 <pre class="SCREEN">
5809 You like the <span class="QUOTE">"fun"</span> text replacements
5810 in <tt class="FILENAME">default.filter</tt>, but it is disabled
5811 in the distributed actions file. So you'd like to turn it on in
5812 your private, update-safe config, once and for all:
5814 <table border="0" bgcolor="#E0E0E0" width="100%">
5817 <pre class="SCREEN">
5818 { +<a href="actions-file.html#FILTER-FUN">filter{fun}</a> }
5826 Note that the above is not really a good idea: There are
5827 exceptions to the filters in <tt class=
5828 "FILENAME">default.action</tt> for things that really shouldn't
5829 be filtered, like code on CVS->Web interfaces. Since <tt
5830 class="FILENAME">user.action</tt> has the last word, these
5831 exceptions won't be valid for the <span class=
5832 "QUOTE">"fun"</span> filtering specified here.
5835 You might also worry about how your favourite free websites are
5836 funded, and find that they rely on displaying banner
5837 advertisements to survive. So you might want to specifically
5838 allow banners for those sites that you feel provide value to you:
5840 <table border="0" bgcolor="#E0E0E0" width="100%">
5843 <pre class="SCREEN">
5854 Note that <tt class="LITERAL">allow-ads</tt> has been aliased to
5855 <tt class="LITERAL">-<a href=
5856 "actions-file.html#BLOCK">block</a></tt>, <tt class="LITERAL">-<a
5858 "actions-file.html#FILTER-BANNERS-BY-SIZE">filter{banners-by-size}</a></tt>,
5859 and <tt class="LITERAL">-<a href=
5860 "actions-file.html#FILTER-BANNERS-BY-LINK">filter{banners-by-link}</a></tt>
5864 Invoke another alias here to force an over-ride of the MIME type
5865 <tt class="LITERAL">application/x-sh</tt> which typically would
5866 open a download type dialog. In my case, I want to look at the
5867 shell script, and then I can save it should I choose to.
5869 <table border="0" bgcolor="#E0E0E0" width="100%">
5872 <pre class="SCREEN">
5881 <tt class="FILENAME">user.action</tt> is generally the best place
5882 to define exceptions and additions to the default policies of <tt
5883 class="FILENAME">default.action</tt>. Some actions are safe to
5884 have their default policies set here though. So let's set a
5885 default policy to have a <span class="QUOTE">"blank"</span> image
5886 as opposed to the checkerboard pattern for <span class=
5887 "emphasis"><i class="EMPHASIS">ALL</i></span> sites. <span class=
5888 "QUOTE">"/"</span> of course matches all URL paths and patterns:
5890 <table border="0" bgcolor="#E0E0E0" width="100%">
5893 <pre class="SCREEN">
5895 "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker{blank}</a> }
5904 <div class="NAVFOOTER">
5905 <hr width="100%" class="c1">
5906 <table summary="Footer navigation table" width="100%" border="0"
5907 cellpadding="0" cellspacing="0">
5909 <td width="33%" align="left" valign="top">
5910 <a href="config.html" accesskey="P">Prev</a>
5912 <td width="34%" align="center" valign="top">
5913 <a href="index.html" accesskey="H">Home</a>
5915 <td width="33%" align="right" valign="top">
5916 <a href="filter-file.html" accesskey="N">Next</a>
5920 <td width="33%" align="left" valign="top">
5921 The Main Configuration File
5923 <td width="34%" align="center" valign="top">
5926 <td width="33%" align="right" valign="top">