Rebuild for 3.0.17 stable
[privoxy.git] / doc / webserver / user-manual / actions-file.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
2 <HTML
3 ><HEAD
4 ><TITLE
5 >Actions Files</TITLE
6 ><META
7 NAME="GENERATOR"
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9 REL="HOME"
10 TITLE="Privoxy 3.0.17 User Manual"
11 HREF="index.html"><LINK
12 REL="PREVIOUS"
13 TITLE="The Main Configuration File"
14 HREF="config.html"><LINK
15 REL="NEXT"
16 TITLE="Filter Files"
17 HREF="filter-file.html"><LINK
18 REL="STYLESHEET"
19 TYPE="text/css"
20 HREF="../p_doc.css"><META
21 HTTP-EQUIV="Content-Type"
22 CONTENT="text/html;
23 charset=ISO-8859-1">
24 <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css">
25 </head
26 ><BODY
27 CLASS="SECT1"
28 BGCOLOR="#EEEEEE"
29 TEXT="#000000"
30 LINK="#0000FF"
31 VLINK="#840084"
32 ALINK="#0000FF"
33 ><DIV
34 CLASS="NAVHEADER"
35 ><TABLE
36 SUMMARY="Header navigation table"
37 WIDTH="100%"
38 BORDER="0"
39 CELLPADDING="0"
40 CELLSPACING="0"
41 ><TR
42 ><TH
43 COLSPAN="3"
44 ALIGN="center"
45 >Privoxy 3.0.17 User Manual</TH
46 ></TR
47 ><TR
48 ><TD
49 WIDTH="10%"
50 ALIGN="left"
51 VALIGN="bottom"
52 ><A
53 HREF="config.html"
54 ACCESSKEY="P"
55 >Prev</A
56 ></TD
57 ><TD
58 WIDTH="80%"
59 ALIGN="center"
60 VALIGN="bottom"
61 ></TD
62 ><TD
63 WIDTH="10%"
64 ALIGN="right"
65 VALIGN="bottom"
66 ><A
67 HREF="filter-file.html"
68 ACCESSKEY="N"
69 >Next</A
70 ></TD
71 ></TR
72 ></TABLE
73 ><HR
74 ALIGN="LEFT"
75 WIDTH="100%"></DIV
76 ><DIV
77 CLASS="SECT1"
78 ><H1
79 CLASS="SECT1"
80 ><A
81 NAME="ACTIONS-FILE"
82 >8. Actions Files</A
83 ></H1
84 ><P
85 > The actions files are used to define what <SPAN
86 CLASS="emphasis"
87 ><I
88 CLASS="EMPHASIS"
89 >actions</I
90 ></SPAN
91 >
92  <SPAN
93 CLASS="APPLICATION"
94 >Privoxy</SPAN
95 > takes for which URLs, and thus determines
96  how ad images, cookies and various other aspects of HTTP content and
97  transactions are handled, and on which sites (or even parts thereof). 
98  There are a number of such actions, with a wide range of functionality.
99  Each action does something a little different.
100  These actions give us a veritable arsenal of tools with which to exert 
101  our control, preferences and independence. Actions can be combined so that 
102  their effects are aggregated when applied against a given set of URLs.</P
103 ><P
104 > There 
105  are three action files included with <SPAN
106 CLASS="APPLICATION"
107 >Privoxy</SPAN
108 > with
109  differing purposes:</P
110 ><P
111 > <P
112 ></P
113 ><UL
114 ><LI
115 ><P
116 >    <TT
117 CLASS="FILENAME"
118 >match-all.action</TT
119 > - is used to define which
120     <SPAN
121 CLASS="QUOTE"
122 >"actions"</SPAN
123 > relating to banner-blocking, images, pop-ups,
124     content modification, cookie handling etc should be applied by default.
125     It should be the first actions file loaded
126    </P
127 ></LI
128 ><LI
129 ><P
130 >    <TT
131 CLASS="FILENAME"
132 >default.action</TT
133 > - defines many exceptions (both
134     positive and negative) from the default set of actions that's configured
135     in <TT
136 CLASS="FILENAME"
137 >match-all.action</TT
138 >. It is a set of rules that should
139     work reasonably well as-is for most users. This file is only supposed to
140     be edited by the developers. It should be the second actions file loaded.
141    </P
142 ></LI
143 ><LI
144 ><P
145 >    <TT
146 CLASS="FILENAME"
147 >user.action</TT
148 > - is intended to be for local site 
149     preferences and exceptions. As an example, if your ISP or your bank
150     has specific requirements, and need special handling, this kind of 
151     thing should go here. This file will not be upgraded.
152    </P
153 ></LI
154 ><LI
155 ><P
156 >    <SPAN
157 CLASS="GUIBUTTON"
158 >Edit</SPAN
159 >  <SPAN
160 CLASS="GUIBUTTON"
161 >Set to Cautious</SPAN
162 > <SPAN
163 CLASS="GUIBUTTON"
164 >Set to Medium</SPAN
165 >  <SPAN
166 CLASS="GUIBUTTON"
167 >Set to Advanced</SPAN
168 >
169    </P
170 ><P
171 >    These have increasing levels of aggressiveness <SPAN
172 CLASS="emphasis"
173 ><I
174 CLASS="EMPHASIS"
175 >and have no
176     influence on your browsing unless you select them explicitly in the
177     editor</I
178 ></SPAN
179 >. A default installation should be pre-set to 
180     <TT
181 CLASS="LITERAL"
182 >Cautious</TT
183 >. New users should try this for a while before
184     adjusting the settings to more aggressive levels. The more aggressive 
185     the settings, then the more likelihood there is of problems such as sites 
186     not working as they should.
187    </P
188 ><P
189 >    The <SPAN
190 CLASS="GUIBUTTON"
191 >Edit</SPAN
192 > button allows you to turn each 
193     action on/off individually for fine-tuning. The <SPAN
194 CLASS="GUIBUTTON"
195 >Cautious</SPAN
196 >
197     button changes the actions list to low/safe settings which will activate 
198     ad blocking and a minimal set of <SPAN
199 CLASS="APPLICATION"
200 >Privoxy</SPAN
201 >'s features, and subsequently
202     there will be less of a chance for accidental problems. The
203     <SPAN
204 CLASS="GUIBUTTON"
205 >Medium</SPAN
206 > button sets the list to a medium level of
207     other features and a low level set of privacy features. The
208     <SPAN
209 CLASS="GUIBUTTON"
210 >Advanced</SPAN
211 > button sets the list to a high level of
212     ad blocking and medium level of privacy. See the chart below. The latter
213     three buttons over-ride any changes via with the
214     <SPAN
215 CLASS="GUIBUTTON"
216 >Edit</SPAN
217 > button. More fine-tuning can be done in the
218     lower sections of this internal page.
219    </P
220 ><P
221 >    While the actions file editor allows to enable these settings in all
222     actions files, they are only supposed to be enabled in the first one
223     to make sure you don't unintentionally overrule earlier rules.
224    </P
225 ><P
226 >    The default profiles, and their associated actions, as pre-defined in
227     <TT
228 CLASS="FILENAME"
229 >default.action</TT
230 > are:
231    </P
232 ><P
233 >    <DIV
234 CLASS="TABLE"
235 ><A
236 NAME="AEN2534"
237 ></A
238 ><P
239 ><B
240 >Table 1. Default Configurations</B
241 ></P
242 ><TABLE
243 BORDER="1"
244 FRAME="border"
245 RULES="all"
246 CLASS="CALSTABLE"
247 ><COL
248 WIDTH="1*"
249 TITLE="C1"><COL
250 WIDTH="1*"
251 TITLE="C2"><COL
252 WIDTH="1*"
253 TITLE="C3"><COL
254 WIDTH="1*"
255 TITLE="C4"><THEAD
256 ><TR
257 ><TH
258 >Feature</TH
259 ><TH
260 >Cautious</TH
261 ><TH
262 >Medium</TH
263 ><TH
264 >Advanced</TH
265 ></TR
266 ></THEAD
267 ><TBODY
268 ><TR
269 ><TD
270 >Ad-blocking Aggressiveness</TD
271 ><TD
272 >medium</TD
273 ><TD
274 >high</TD
275 ><TD
276 >high</TD
277 ></TR
278 ><TR
279 ><TD
280 >Ad-filtering by size</TD
281 ><TD
282 >no</TD
283 ><TD
284 >yes</TD
285 ><TD
286 >yes</TD
287 ></TR
288 ><TR
289 ><TD
290 >Ad-filtering by link</TD
291 ><TD
292 >no</TD
293 ><TD
294 >no</TD
295 ><TD
296 >yes</TD
297 ></TR
298 ><TR
299 ><TD
300 >Pop-up killing</TD
301 ><TD
302 >blocks only</TD
303 ><TD
304 >blocks only</TD
305 ><TD
306 >blocks only</TD
307 ></TR
308 ><TR
309 ><TD
310 >Privacy Features</TD
311 ><TD
312 >low</TD
313 ><TD
314 >medium</TD
315 ><TD
316 >medium/high</TD
317 ></TR
318 ><TR
319 ><TD
320 >Cookie handling</TD
321 ><TD
322 >none</TD
323 ><TD
324 >session-only</TD
325 ><TD
326 >kill</TD
327 ></TR
328 ><TR
329 ><TD
330 >Referer forging</TD
331 ><TD
332 >no</TD
333 ><TD
334 >yes</TD
335 ><TD
336 >yes</TD
337 ></TR
338 ><TR
339 ><TD
340 >GIF de-animation</TD
341 ><TD
342 >no</TD
343 ><TD
344 >yes</TD
345 ><TD
346 >yes</TD
347 ></TR
348 ><TR
349 ><TD
350 >Fast redirects</TD
351 ><TD
352 >no</TD
353 ><TD
354 >no</TD
355 ><TD
356 >yes</TD
357 ></TR
358 ><TR
359 ><TD
360 >HTML taming</TD
361 ><TD
362 >no</TD
363 ><TD
364 >no</TD
365 ><TD
366 >yes</TD
367 ></TR
368 ><TR
369 ><TD
370 >JavaScript taming</TD
371 ><TD
372 >no</TD
373 ><TD
374 >no</TD
375 ><TD
376 >yes</TD
377 ></TR
378 ><TR
379 ><TD
380 >Web-bug killing</TD
381 ><TD
382 >no</TD
383 ><TD
384 >yes</TD
385 ><TD
386 >yes</TD
387 ></TR
388 ><TR
389 ><TD
390 >Image tag reordering</TD
391 ><TD
392 >no</TD
393 ><TD
394 >yes</TD
395 ><TD
396 >yes</TD
397 ></TR
398 ></TBODY
399 ></TABLE
400 ></DIV
401 >
402     </P
403 ></LI
404 ></UL
405 ></P
406 ><P
407 > The list of actions files to be used are defined in the main configuration 
408  file, and are processed in the order they are defined (e.g.
409  <TT
410 CLASS="FILENAME"
411 >default.action</TT
412 > is typically processed before
413  <TT
414 CLASS="FILENAME"
415 >user.action</TT
416 >). The content of these can all be viewed and
417  edited from <A
418 HREF="http://config.privoxy.org/show-status"
419 TARGET="_top"
420 >http://config.privoxy.org/show-status</A
421 >.
422  The over-riding principle when applying actions, is that the last action that
423  matches a given URL wins. The broadest, most general rules go first
424  (defined in <TT
425 CLASS="FILENAME"
426 >default.action</TT
427 >),
428  followed by any exceptions (typically also in
429  <TT
430 CLASS="FILENAME"
431 >default.action</TT
432 >), which are then followed lastly by any
433  local preferences (typically in <SPAN
434 CLASS="emphasis"
435 ><I
436 CLASS="EMPHASIS"
437 >user</I
438 ></SPAN
439 ><TT
440 CLASS="FILENAME"
441 >.action</TT
442 >). 
443  Generally, <TT
444 CLASS="FILENAME"
445 >user.action</TT
446 > has the last word.
447  </P
448 ><P
449 > An actions file typically has multiple sections. If you want to use
450  <SPAN
451 CLASS="QUOTE"
452 >"aliases"</SPAN
453 > in an actions file, you have to place the (optional)
454  <A
455 HREF="actions-file.html#ALIASES"
456 >alias section</A
457 > at the top of that file.
458  Then comes the default set of rules which will apply universally to all
459  sites and pages (be <SPAN
460 CLASS="emphasis"
461 ><I
462 CLASS="EMPHASIS"
463 >very careful</I
464 ></SPAN
465 > with using such a
466  universal set in <TT
467 CLASS="FILENAME"
468 >user.action</TT
469 > or any other actions file after 
470  <TT
471 CLASS="FILENAME"
472 >default.action</TT
473 >, because it will override the result
474  from consulting any previous file). And then below that,
475  exceptions to the defined universal policies. You can regard
476  <TT
477 CLASS="FILENAME"
478 >user.action</TT
479 > as an appendix to <TT
480 CLASS="FILENAME"
481 >default.action</TT
482 >,
483  with the advantage that it is a separate file, which makes preserving your
484  personal settings across <SPAN
485 CLASS="APPLICATION"
486 >Privoxy</SPAN
487 > upgrades easier.</P
488 ><P
489
490  Actions can be used to block anything you want, including ads, banners, or
491  just some obnoxious URL whose content you would rather not see. Cookies can be accepted
492  or rejected, or accepted only during the current browser session (i.e. not
493  written to disk), content can be modified, some JavaScripts tamed, user-tracking
494  fooled, and much more. See below for a <A
495 HREF="actions-file.html#ACTIONS"
496 >complete list
497  of actions</A
498 >.</P
499 ><DIV
500 CLASS="SECT2"
501 ><H2
502 CLASS="SECT2"
503 ><A
504 NAME="AEN2633"
505 >8.1. Finding the Right Mix</A
506 ></H2
507 ><P
508 > Note that some <A
509 HREF="actions-file.html#ACTIONS"
510 >actions</A
511 >, like cookie suppression
512  or script disabling, may render some sites unusable that rely on these
513  techniques to work properly. Finding the right mix of actions is not always easy and
514  certainly a matter of personal taste. And, things can always change, requiring 
515  refinements in the configuration. In general, it can be said that the more
516  <SPAN
517 CLASS="QUOTE"
518 >"aggressive"</SPAN
519 > your default settings (in the top section of the
520  actions file) are, the more exceptions for <SPAN
521 CLASS="QUOTE"
522 >"trusted"</SPAN
523 > sites you
524  will have to make later. If, for example, you want to crunch all cookies per
525  default, you'll have to make exceptions from that rule for sites that you
526  regularly use and that require cookies for actually useful purposes, like maybe
527  your bank, favorite shop, or newspaper.</P
528 ><P
529 > We have tried to provide you with reasonable rules to start from in the
530  distribution actions files. But there is no general rule of thumb on these
531  things. There just are too many variables, and sites are constantly changing.
532  Sooner or later you will want to change the rules (and read this chapter again :).</P
533 ></DIV
534 ><DIV
535 CLASS="SECT2"
536 ><H2
537 CLASS="SECT2"
538 ><A
539 NAME="AEN2640"
540 >8.2. How to Edit</A
541 ></H2
542 ><P
543 > The easiest way to edit the actions files is with a browser by
544  using our browser-based editor, which can be reached from <A
545 HREF="http://config.privoxy.org/show-status"
546 TARGET="_top"
547 >http://config.privoxy.org/show-status</A
548 >.
549  Note: the config file option <A
550 HREF="config.html#ENABLE-EDIT-ACTIONS"
551 >enable-edit-actions</A
552 > must be enabled for
553  this to work. The editor allows both fine-grained control over every single
554  feature on a per-URL basis, and easy choosing from wholesale sets of defaults
555  like <SPAN
556 CLASS="QUOTE"
557 >"Cautious"</SPAN
558 >, <SPAN
559 CLASS="QUOTE"
560 >"Medium"</SPAN
561 > or
562  <SPAN
563 CLASS="QUOTE"
564 >"Advanced"</SPAN
565 >. Warning: the <SPAN
566 CLASS="QUOTE"
567 >"Advanced"</SPAN
568 > setting is more
569  aggressive, and will be more likely to cause problems for some sites.
570  Experienced users only! 
571  </P
572 ><P
573 > If you prefer plain text editing to GUIs, you can of course also directly edit the
574  the actions files with your favorite text editor. Look at
575  <TT
576 CLASS="FILENAME"
577 >default.action</TT
578 > which is richly commented with many 
579  good examples.</P
580 ></DIV
581 ><DIV
582 CLASS="SECT2"
583 ><H2
584 CLASS="SECT2"
585 ><A
586 NAME="ACTIONS-APPLY"
587 >8.3. How Actions are Applied to Requests</A
588 ></H2
589 ><P
590 > Actions files are divided into sections. There are special sections,
591  like the <SPAN
592 CLASS="QUOTE"
593 >"<A
594 HREF="actions-file.html#ALIASES"
595 >alias</A
596 >"</SPAN
597 > sections which will
598  be discussed later. For now let's concentrate on regular sections: They have a
599  heading line (often split up to multiple lines for readability) which consist
600  of a list of actions, separated by whitespace and enclosed in curly braces.
601  Below that, there is a list of URL and tag patterns, each on a separate line.</P
602 ><P
603 > To determine which actions apply to a request, the URL of the request is
604  compared to all URL patterns in each <SPAN
605 CLASS="QUOTE"
606 >"action file"</SPAN
607 >.
608  Every time it matches, the list of applicable actions for the request is
609  incrementally updated, using the heading of the section in which the
610  pattern is located. The same is done again for tags and tag patterns later on.</P
611 ><P
612 > If multiple applying sections set the same action differently,
613  the last match wins. If not, the effects are aggregated.
614  E.g. a URL might match a regular section with a heading line of <TT
615 CLASS="LITERAL"
616 >{ 
617  +<A
618 HREF="actions-file.html#HANDLE-AS-IMAGE"
619 >handle-as-image</A
620 > }</TT
621 >,
622  then later another one with just <TT
623 CLASS="LITERAL"
624 >{
625  +<A
626 HREF="actions-file.html#BLOCK"
627 >block</A
628 > }</TT
629 >, resulting
630  in <SPAN
631 CLASS="emphasis"
632 ><I
633 CLASS="EMPHASIS"
634 >both</I
635 ></SPAN
636 > actions to apply. And there may well be 
637  cases where you will want to combine actions together. Such a section then 
638  might look like:</P
639 ><P
640 > <TABLE
641 BORDER="0"
642 BGCOLOR="#E0E0E0"
643 WIDTH="100%"
644 ><TR
645 ><TD
646 ><PRE
647 CLASS="SCREEN"
648 >  { +<TT
649 CLASS="LITERAL"
650 >handle-as-image</TT
651 >  +<TT
652 CLASS="LITERAL"
653 >block{Banner ads.}</TT
654 > }
655   # Block these as if they were images. Send no block page.
656    banners.example.com
657    media.example.com/.*banners
658    .example.com/images/ads/</PRE
659 ></TD
660 ></TR
661 ></TABLE
662 >
663  </P
664 ><P
665 > You can trace this process for URL patterns and any given URL by visiting <A
666 HREF="http://config.privoxy.org/show-url-info"
667 TARGET="_top"
668 >http://config.privoxy.org/show-url-info</A
669 >.</P
670 ><P
671 > Examples and more detail on this is provided in the Appendix, <A
672 HREF="appendix.html#ACTIONSANAT"
673 > Troubleshooting: Anatomy of an Action</A
674 > section.</P
675 ></DIV
676 ><DIV
677 CLASS="SECT2"
678 ><H2
679 CLASS="SECT2"
680 ><A
681 NAME="AF-PATTERNS"
682 >8.4. Patterns</A
683 ></H2
684 ><P
685
686  As mentioned, <SPAN
687 CLASS="APPLICATION"
688 >Privoxy</SPAN
689 > uses <SPAN
690 CLASS="QUOTE"
691 >"patterns"</SPAN
692 >
693  to determine what <SPAN
694 CLASS="emphasis"
695 ><I
696 CLASS="EMPHASIS"
697 >actions</I
698 ></SPAN
699 > might apply to which sites and
700  pages your browser attempts to access. These <SPAN
701 CLASS="QUOTE"
702 >"patterns"</SPAN
703 > use wild
704  card type <SPAN
705 CLASS="emphasis"
706 ><I
707 CLASS="EMPHASIS"
708 >pattern</I
709 ></SPAN
710 > matching to achieve a high degree of
711  flexibility. This allows one expression to be expanded and potentially match
712  against many similar patterns.</P
713 ><P
714 > Generally, an URL pattern has the form
715  <TT
716 CLASS="LITERAL"
717 >&#60;domain&#62;&#60;port&#62;/&#60;path&#62;</TT
718 >, where the
719  <TT
720 CLASS="LITERAL"
721 >&#60;domain&#62;</TT
722 >, the <TT
723 CLASS="LITERAL"
724 >&#60;port&#62;</TT
725 >
726  and the <TT
727 CLASS="LITERAL"
728 >&#60;path&#62;</TT
729 > are optional. (This is why the special
730  <TT
731 CLASS="LITERAL"
732 >/</TT
733 > pattern matches all URLs). Note that the protocol
734  portion of the URL pattern (e.g. <TT
735 CLASS="LITERAL"
736 >http://</TT
737 >) should
738  <SPAN
739 CLASS="emphasis"
740 ><I
741 CLASS="EMPHASIS"
742 >not</I
743 ></SPAN
744 > be included in the pattern. This is assumed already!</P
745 ><P
746 > The pattern matching syntax is different for the domain and path parts of
747  the URL. The domain part uses a simple globbing type matching technique, 
748  while the path part uses more flexible 
749  <A
750 HREF="http://en.wikipedia.org/wiki/Regular_expressions"
751 TARGET="_top"
752 ><SPAN
753 CLASS="QUOTE"
754 >"Regular
755   Expressions"</SPAN
756 ></A
757 > (POSIX 1003.2).</P
758 ><P
759 > The port part of a pattern is a decimal port number preceded by a colon
760  (<TT
761 CLASS="LITERAL"
762 >:</TT
763 >). If the domain part contains a numerical IPv6 address,
764  it has to be put into angle brackets
765  (<TT
766 CLASS="LITERAL"
767 >&#60;</TT
768 >, <TT
769 CLASS="LITERAL"
770 >&#62;</TT
771 >).</P
772 ><P
773 ></P
774 ><DIV
775 CLASS="VARIABLELIST"
776 ><DL
777 ><DT
778 ><TT
779 CLASS="LITERAL"
780 >www.example.com/</TT
781 ></DT
782 ><DD
783 ><P
784 >    is a domain-only pattern and will match any request to <TT
785 CLASS="LITERAL"
786 >www.example.com</TT
787 >,
788     regardless of which document on that server is requested. So ALL pages in
789     this domain would be covered by the scope of this action. Note that a 
790     simple <TT
791 CLASS="LITERAL"
792 >example.com</TT
793 > is different and would NOT match.
794    </P
795 ></DD
796 ><DT
797 ><TT
798 CLASS="LITERAL"
799 >www.example.com</TT
800 ></DT
801 ><DD
802 ><P
803 >    means exactly the same. For domain-only patterns, the trailing <TT
804 CLASS="LITERAL"
805 >/</TT
806 > may
807     be omitted.
808    </P
809 ></DD
810 ><DT
811 ><TT
812 CLASS="LITERAL"
813 >www.example.com/index.html</TT
814 ></DT
815 ><DD
816 ><P
817 >    matches all the documents on <TT
818 CLASS="LITERAL"
819 >www.example.com</TT
820 >
821     whose name starts with <TT
822 CLASS="LITERAL"
823 >/index.html</TT
824 >.
825    </P
826 ></DD
827 ><DT
828 ><TT
829 CLASS="LITERAL"
830 >www.example.com/index.html$</TT
831 ></DT
832 ><DD
833 ><P
834 >    matches only the single document <TT
835 CLASS="LITERAL"
836 >/index.html</TT
837 >
838     on <TT
839 CLASS="LITERAL"
840 >www.example.com</TT
841 >.
842    </P
843 ></DD
844 ><DT
845 ><TT
846 CLASS="LITERAL"
847 >/index.html$</TT
848 ></DT
849 ><DD
850 ><P
851 >    matches the document <TT
852 CLASS="LITERAL"
853 >/index.html</TT
854 >, regardless of the domain,
855     i.e. on <SPAN
856 CLASS="emphasis"
857 ><I
858 CLASS="EMPHASIS"
859 >any</I
860 ></SPAN
861 > web server anywhere.
862    </P
863 ></DD
864 ><DT
865 ><TT
866 CLASS="LITERAL"
867 >/</TT
868 ></DT
869 ><DD
870 ><P
871 >    Matches any URL because there's no requirement for either the
872     domain or the path to match anything.
873    </P
874 ></DD
875 ><DT
876 ><TT
877 CLASS="LITERAL"
878 >:8000/</TT
879 ></DT
880 ><DD
881 ><P
882 >    Matches any URL pointing to TCP port 8000.
883    </P
884 ></DD
885 ><DT
886 ><TT
887 CLASS="LITERAL"
888 >&#60;2001:db8::1&#62;/</TT
889 ></DT
890 ><DD
891 ><P
892 >    Matches any URL with the host address <TT
893 CLASS="LITERAL"
894 >2001:db8::1</TT
895 >.
896     (Note that the real URL uses plain brackets, not angle brackets.)
897    </P
898 ></DD
899 ><DT
900 ><TT
901 CLASS="LITERAL"
902 >index.html</TT
903 ></DT
904 ><DD
905 ><P
906 >    matches nothing, since it would be interpreted as a domain name and
907     there is no top-level domain called <TT
908 CLASS="LITERAL"
909 >.html</TT
910 >. So its 
911     a mistake.
912    </P
913 ></DD
914 ></DL
915 ></DIV
916 ><DIV
917 CLASS="SECT3"
918 ><H3
919 CLASS="SECT3"
920 ><A
921 NAME="AEN2752"
922 >8.4.1. The Domain Pattern</A
923 ></H3
924 ><P
925 > The matching of the domain part offers some flexible options: if the
926  domain starts or ends with a dot, it becomes unanchored at that end. 
927  For example:</P
928 ><P
929 ></P
930 ><DIV
931 CLASS="VARIABLELIST"
932 ><DL
933 ><DT
934 ><TT
935 CLASS="LITERAL"
936 >.example.com</TT
937 ></DT
938 ><DD
939 ><P
940 >    matches any domain with first-level domain <TT
941 CLASS="LITERAL"
942 >com</TT
943 >
944     and second-level domain <TT
945 CLASS="LITERAL"
946 >example</TT
947 >.
948     For example <TT
949 CLASS="LITERAL"
950 >www.example.com</TT
951 >,
952     <TT
953 CLASS="LITERAL"
954 >example.com</TT
955 > and <TT
956 CLASS="LITERAL"
957 >foo.bar.baz.example.com</TT
958 >.
959     Note that it wouldn't match if the second-level domain was <TT
960 CLASS="LITERAL"
961 >another-example</TT
962 >.
963    </P
964 ></DD
965 ><DT
966 ><TT
967 CLASS="LITERAL"
968 >www.</TT
969 ></DT
970 ><DD
971 ><P
972 >    matches any domain that <SPAN
973 CLASS="emphasis"
974 ><I
975 CLASS="EMPHASIS"
976 >STARTS</I
977 ></SPAN
978 > with
979     <TT
980 CLASS="LITERAL"
981 >www.</TT
982 > (It also matches the domain
983     <TT
984 CLASS="LITERAL"
985 >www</TT
986 > but most of the time that doesn't matter.)
987    </P
988 ></DD
989 ><DT
990 ><TT
991 CLASS="LITERAL"
992 >.example.</TT
993 ></DT
994 ><DD
995 ><P
996 >    matches any domain that <SPAN
997 CLASS="emphasis"
998 ><I
999 CLASS="EMPHASIS"
1000 >CONTAINS</I
1001 ></SPAN
1002 > <TT
1003 CLASS="LITERAL"
1004 >.example.</TT
1005 >.
1006     And, by the way, also included would be any files or documents that exist
1007     within that domain since no path limitations are specified. (Correctly
1008     speaking: It matches any FQDN that contains <TT
1009 CLASS="LITERAL"
1010 >example</TT
1011 > as
1012     a domain.) This might be <TT
1013 CLASS="LITERAL"
1014 >www.example.com</TT
1015 >,
1016     <TT
1017 CLASS="LITERAL"
1018 >news.example.de</TT
1019 >, or
1020     <TT
1021 CLASS="LITERAL"
1022 >www.example.net/cgi/testing.pl</TT
1023 > for instance. All these
1024     cases are matched. 
1025    </P
1026 ></DD
1027 ></DL
1028 ></DIV
1029 ><P
1030 > Additionally, there are wild-cards that you can use in the domain names
1031  themselves. These work similarly to shell globbing type wild-cards:
1032  <SPAN
1033 CLASS="QUOTE"
1034 >"*"</SPAN
1035 > represents zero or more arbitrary characters (this is
1036  equivalent to the 
1037  <A
1038 HREF="http://en.wikipedia.org/wiki/Regular_expressions"
1039 TARGET="_top"
1040 ><SPAN
1041 CLASS="QUOTE"
1042 >"Regular
1043  Expression"</SPAN
1044 ></A
1045 > based syntax of <SPAN
1046 CLASS="QUOTE"
1047 >".*"</SPAN
1048 >),
1049  <SPAN
1050 CLASS="QUOTE"
1051 >"?"</SPAN
1052 >  represents any single character (this is equivalent to the
1053  regular expression syntax of a simple <SPAN
1054 CLASS="QUOTE"
1055 >"."</SPAN
1056 >), and you can define
1057  <SPAN
1058 CLASS="QUOTE"
1059 >"character classes"</SPAN
1060 > in square brackets which is similar to 
1061  the same regular expression technique. All of this can be freely mixed:</P
1062 ><P
1063 ></P
1064 ><DIV
1065 CLASS="VARIABLELIST"
1066 ><DL
1067 ><DT
1068 ><TT
1069 CLASS="LITERAL"
1070 >ad*.example.com</TT
1071 ></DT
1072 ><DD
1073 ><P
1074 >    matches <SPAN
1075 CLASS="QUOTE"
1076 >"adserver.example.com"</SPAN
1077 >, 
1078     <SPAN
1079 CLASS="QUOTE"
1080 >"ads.example.com"</SPAN
1081 >, etc but not <SPAN
1082 CLASS="QUOTE"
1083 >"sfads.example.com"</SPAN
1084 >
1085    </P
1086 ></DD
1087 ><DT
1088 ><TT
1089 CLASS="LITERAL"
1090 >*ad*.example.com</TT
1091 ></DT
1092 ><DD
1093 ><P
1094 >    matches all of the above, and then some.
1095    </P
1096 ></DD
1097 ><DT
1098 ><TT
1099 CLASS="LITERAL"
1100 >.?pix.com</TT
1101 ></DT
1102 ><DD
1103 ><P
1104 >    matches <TT
1105 CLASS="LITERAL"
1106 >www.ipix.com</TT
1107 >,
1108     <TT
1109 CLASS="LITERAL"
1110 >pictures.epix.com</TT
1111 >, <TT
1112 CLASS="LITERAL"
1113 >a.b.c.d.e.upix.com</TT
1114 > etc. 
1115    </P
1116 ></DD
1117 ><DT
1118 ><TT
1119 CLASS="LITERAL"
1120 >www[1-9a-ez].example.c*</TT
1121 ></DT
1122 ><DD
1123 ><P
1124 >     matches <TT
1125 CLASS="LITERAL"
1126 >www1.example.com</TT
1127 >, 
1128      <TT
1129 CLASS="LITERAL"
1130 >www4.example.cc</TT
1131 >, <TT
1132 CLASS="LITERAL"
1133 >wwwd.example.cy</TT
1134 >, 
1135      <TT
1136 CLASS="LITERAL"
1137 >wwwz.example.com</TT
1138 > etc., but <SPAN
1139 CLASS="emphasis"
1140 ><I
1141 CLASS="EMPHASIS"
1142 >not</I
1143 ></SPAN
1144
1145      <TT
1146 CLASS="LITERAL"
1147 >wwww.example.com</TT
1148 >.
1149    </P
1150 ></DD
1151 ></DL
1152 ></DIV
1153 ><P
1154 > While flexible, this is not the sophistication of full regular expression based syntax.</P
1155 ></DIV
1156 ><DIV
1157 CLASS="SECT3"
1158 ><H3
1159 CLASS="SECT3"
1160 ><A
1161 NAME="AEN2828"
1162 >8.4.2. The Path Pattern</A
1163 ></H3
1164 ><P
1165 > <SPAN
1166 CLASS="APPLICATION"
1167 >Privoxy</SPAN
1168 > uses <SPAN
1169 CLASS="QUOTE"
1170 >"modern"</SPAN
1171 > POSIX 1003.2
1172   <A
1173 HREF="http://en.wikipedia.org/wiki/Regular_expressions"
1174 TARGET="_top"
1175 ><SPAN
1176 CLASS="QUOTE"
1177 >"Regular
1178   Expressions"</SPAN
1179 ></A
1180 > for matching the path portion (after the slash),
1181   and is thus more flexible.</P
1182 ><P
1183 > There is an <A
1184 HREF="appendix.html#REGEX"
1185 >Appendix</A
1186 > with a brief quick-start into regular
1187  expressions, you also might want to have a look at your operating system's documentation
1188  on regular expressions (try <TT
1189 CLASS="LITERAL"
1190 >man re_format</TT
1191 >).</P
1192 ><P
1193 > Note that the path pattern is automatically left-anchored at the <SPAN
1194 CLASS="QUOTE"
1195 >"/"</SPAN
1196 >,
1197  i.e. it matches as if it would start with a <SPAN
1198 CLASS="QUOTE"
1199 >"^"</SPAN
1200 > (regular expression speak 
1201  for the beginning of a line).</P
1202 ><P
1203 > Please also note that matching in the path is <SPAN
1204 CLASS="emphasis"
1205 ><I
1206 CLASS="EMPHASIS"
1207 >CASE INSENSITIVE</I
1208 ></SPAN
1209 >
1210  by default, but you can switch to case sensitive at any point in the pattern by using the 
1211  <SPAN
1212 CLASS="QUOTE"
1213 >"(?-i)"</SPAN
1214 > switch: <TT
1215 CLASS="LITERAL"
1216 >www.example.com/(?-i)PaTtErN.*</TT
1217 > will match
1218  only documents whose path starts with <TT
1219 CLASS="LITERAL"
1220 >PaTtErN</TT
1221 > in
1222  <SPAN
1223 CLASS="emphasis"
1224 ><I
1225 CLASS="EMPHASIS"
1226 >exactly</I
1227 ></SPAN
1228 > this capitalization.</P
1229 ><P
1230 ></P
1231 ><DIV
1232 CLASS="VARIABLELIST"
1233 ><DL
1234 ><DT
1235 ><TT
1236 CLASS="LITERAL"
1237 >.example.com/.*</TT
1238 ></DT
1239 ><DD
1240 ><P
1241 >     Is equivalent to just <SPAN
1242 CLASS="QUOTE"
1243 >".example.com"</SPAN
1244 >, since any documents 
1245      within that domain are matched with or without the <SPAN
1246 CLASS="QUOTE"
1247 >".*"</SPAN
1248 >
1249      regular expression. This is redundant
1250    </P
1251 ></DD
1252 ><DT
1253 ><TT
1254 CLASS="LITERAL"
1255 >.example.com/.*/index.html$</TT
1256 ></DT
1257 ><DD
1258 ><P
1259 >    Will match any page in the domain of <SPAN
1260 CLASS="QUOTE"
1261 >"example.com"</SPAN
1262 > that is
1263     named <SPAN
1264 CLASS="QUOTE"
1265 >"index.html"</SPAN
1266 >, and that is part of some path. For
1267     example, it matches <SPAN
1268 CLASS="QUOTE"
1269 >"www.example.com/testing/index.html"</SPAN
1270 > but
1271     NOT <SPAN
1272 CLASS="QUOTE"
1273 >"www.example.com/index.html"</SPAN
1274 > because the regular
1275     expression called for at least two <SPAN
1276 CLASS="QUOTE"
1277 >"/'s"</SPAN
1278 >, thus the path 
1279     requirement. It also would match 
1280     <SPAN
1281 CLASS="QUOTE"
1282 >"www.example.com/testing/index_html"</SPAN
1283 >, because of the 
1284     special meta-character <SPAN
1285 CLASS="QUOTE"
1286 >"."</SPAN
1287 >.
1288    </P
1289 ></DD
1290 ><DT
1291 ><TT
1292 CLASS="LITERAL"
1293 >.example.com/(.*/)?index\.html$</TT
1294 ></DT
1295 ><DD
1296 ><P
1297 >    This regular expression is conditional so it will match any page 
1298     named <SPAN
1299 CLASS="QUOTE"
1300 >"index.html"</SPAN
1301 > regardless of path which in this case can 
1302     have one or more <SPAN
1303 CLASS="QUOTE"
1304 >"/'s"</SPAN
1305 >. And this one must contain exactly 
1306     <SPAN
1307 CLASS="QUOTE"
1308 >".html"</SPAN
1309 > (but does not have to end with that!).
1310    </P
1311 ></DD
1312 ><DT
1313 ><TT
1314 CLASS="LITERAL"
1315 >.example.com/(.*/)(ads|banners?|junk)</TT
1316 ></DT
1317 ><DD
1318 ><P
1319 >    This regular expression will match any path of <SPAN
1320 CLASS="QUOTE"
1321 >"example.com"</SPAN
1322 >
1323     that contains any of the words <SPAN
1324 CLASS="QUOTE"
1325 >"ads"</SPAN
1326 >, <SPAN
1327 CLASS="QUOTE"
1328 >"banner"</SPAN
1329 >, 
1330     <SPAN
1331 CLASS="QUOTE"
1332 >"banners"</SPAN
1333 > (because of the <SPAN
1334 CLASS="QUOTE"
1335 >"?"</SPAN
1336 >) or <SPAN
1337 CLASS="QUOTE"
1338 >"junk"</SPAN
1339 >.
1340     The path does not have to end in these words, just contain them.
1341    </P
1342 ></DD
1343 ><DT
1344 ><TT
1345 CLASS="LITERAL"
1346 >.example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$</TT
1347 ></DT
1348 ><DD
1349 ><P
1350 >    This is very much the same as above, except now it must end in either 
1351     <SPAN
1352 CLASS="QUOTE"
1353 >".jpg"</SPAN
1354 >, <SPAN
1355 CLASS="QUOTE"
1356 >".jpeg"</SPAN
1357 >, <SPAN
1358 CLASS="QUOTE"
1359 >".gif"</SPAN
1360 > or <SPAN
1361 CLASS="QUOTE"
1362 >".png"</SPAN
1363 >. So this 
1364     one is limited to common image formats.
1365    </P
1366 ></DD
1367 ></DL
1368 ></DIV
1369 ><P
1370 > There are many, many good examples to be found in <TT
1371 CLASS="FILENAME"
1372 >default.action</TT
1373 >, 
1374  and more tutorials below in <A
1375 HREF="appendix.html#REGEX"
1376 >Appendix on regular expressions</A
1377 >.</P
1378 ></DIV
1379 ><DIV
1380 CLASS="SECT3"
1381 ><H3
1382 CLASS="SECT3"
1383 ><A
1384 NAME="TAG-PATTERN"
1385 >8.4.3. The Tag Pattern</A
1386 ></H3
1387 ><P
1388 > Tag patterns are used to change the applying actions based on the
1389  request's tags. Tags can be created with either the
1390  <A
1391 HREF="actions-file.html#CLIENT-HEADER-TAGGER"
1392 >client-header-tagger</A
1393 >
1394  or the  <A
1395 HREF="actions-file.html#SERVER-HEADER-TAGGER"
1396 >server-header-tagger</A
1397 > action.</P
1398 ><P
1399 > Tag patterns have to start with <SPAN
1400 CLASS="QUOTE"
1401 >"TAG:"</SPAN
1402 >, so <SPAN
1403 CLASS="APPLICATION"
1404 >Privoxy</SPAN
1405 >
1406  can tell them apart from URL patterns. Everything after the colon
1407  including white space, is interpreted as a regular expression with
1408  path pattern syntax, except that tag patterns aren't left-anchored
1409  automatically (<SPAN
1410 CLASS="APPLICATION"
1411 >Privoxy</SPAN
1412 > doesn't silently add a <SPAN
1413 CLASS="QUOTE"
1414 >"^"</SPAN
1415 >,
1416  you have to do it yourself if you need it).</P
1417 ><P
1418 > To match all requests that are tagged with <SPAN
1419 CLASS="QUOTE"
1420 >"foo"</SPAN
1421 >
1422  your pattern line should be <SPAN
1423 CLASS="QUOTE"
1424 >"TAG:^foo$"</SPAN
1425 >,
1426  <SPAN
1427 CLASS="QUOTE"
1428 >"TAG:foo"</SPAN
1429 > would work as well, but it would also
1430  match requests whose tags contain <SPAN
1431 CLASS="QUOTE"
1432 >"foo"</SPAN
1433 > somewhere.
1434  <SPAN
1435 CLASS="QUOTE"
1436 >"TAG: foo"</SPAN
1437 > wouldn't work as it requires white space.</P
1438 ><P
1439 > Sections can contain URL and tag patterns at the same time,
1440  but tag patterns are checked after the URL patterns and thus
1441  always overrule them, even if they are located before the URL patterns.</P
1442 ><P
1443 > Once a new tag is added, Privoxy checks right away if it's matched by one
1444  of the tag patterns and updates the action settings accordingly. As a result
1445  tags can be used to activate other tagger actions, as long as these other
1446  taggers look for headers that haven't already be parsed.</P
1447 ><P
1448 > For example you could tag client requests which use the
1449  <TT
1450 CLASS="LITERAL"
1451 >POST</TT
1452 > method,
1453  then use this tag to activate another tagger that adds a tag if cookies
1454  are sent, and then use a block action based on the cookie tag. This allows
1455  the outcome of one action, to be input into a subsequent action. However if
1456  you'd reverse the position of the described taggers, and activated the
1457  method tagger based on the cookie tagger, no method tags would be created.
1458  The method tagger would look for the request line, but at the time
1459  the cookie tag is created, the request line has already been parsed.</P
1460 ><P
1461 > While this is a limitation you should be aware of, this kind of
1462  indirection is seldom needed anyway and even the example doesn't
1463  make too much sense.</P
1464 ></DIV
1465 ></DIV
1466 ><DIV
1467 CLASS="SECT2"
1468 ><H2
1469 CLASS="SECT2"
1470 ><A
1471 NAME="ACTIONS"
1472 >8.5. Actions</A
1473 ></H2
1474 ><P
1475 > All actions are disabled by default, until they are explicitly enabled
1476  somewhere in an actions file. Actions are turned on if preceded with a
1477  <SPAN
1478 CLASS="QUOTE"
1479 >"+"</SPAN
1480 >, and turned off if preceded with a <SPAN
1481 CLASS="QUOTE"
1482 >"-"</SPAN
1483 >. So a
1484  <TT
1485 CLASS="LITERAL"
1486 >+action</TT
1487 > means <SPAN
1488 CLASS="QUOTE"
1489 >"do that action"</SPAN
1490 >, e.g.
1491  <TT
1492 CLASS="LITERAL"
1493 >+block</TT
1494 > means <SPAN
1495 CLASS="QUOTE"
1496 >"please block URLs that match the
1497  following patterns"</SPAN
1498 >, and <TT
1499 CLASS="LITERAL"
1500 >-block</TT
1501 > means <SPAN
1502 CLASS="QUOTE"
1503 >"don't
1504  block URLs that match the following patterns, even if <TT
1505 CLASS="LITERAL"
1506 >+block</TT
1507 >
1508  previously applied."</SPAN
1509 >&#13;</P
1510 ><P
1511
1512  Again, actions are invoked by placing them on a line, enclosed in curly braces and
1513  separated by whitespace, like in 
1514  <TT
1515 CLASS="LITERAL"
1516 >{+some-action -some-other-action{some-parameter}}</TT
1517 >,
1518  followed by a list of URL patterns, one per line, to which they apply.
1519  Together, the actions line and the following pattern lines make up a section
1520  of the actions file. </P
1521 ><P
1522
1523  Actions fall into three categories:</P
1524 ><P
1525 > <P
1526 ></P
1527 ><UL
1528 ><LI
1529 ><P
1530 >  
1531    Boolean, i.e the action can only be <SPAN
1532 CLASS="QUOTE"
1533 >"enabled"</SPAN
1534 > or
1535    <SPAN
1536 CLASS="QUOTE"
1537 >"disabled"</SPAN
1538 >. Syntax:
1539   </P
1540 ><P
1541 >   <TABLE
1542 BORDER="0"
1543 BGCOLOR="#E0E0E0"
1544 WIDTH="90%"
1545 ><TR
1546 ><TD
1547 ><PRE
1548 CLASS="SCREEN"
1549 >  +<TT
1550 CLASS="REPLACEABLE"
1551 ><I
1552 >name</I
1553 ></TT
1554 >        # enable action <TT
1555 CLASS="REPLACEABLE"
1556 ><I
1557 >name</I
1558 ></TT
1559 >
1560   -<TT
1561 CLASS="REPLACEABLE"
1562 ><I
1563 >name</I
1564 ></TT
1565 >        # disable action <TT
1566 CLASS="REPLACEABLE"
1567 ><I
1568 >name</I
1569 ></TT
1570 ></PRE
1571 ></TD
1572 ></TR
1573 ></TABLE
1574 >
1575   </P
1576 ><P
1577 >  
1578    Example: <TT
1579 CLASS="LITERAL"
1580 >+handle-as-image</TT
1581 >
1582   </P
1583 ></LI
1584 ><LI
1585 ><P
1586 >  
1587    Parameterized, where some value is required in order to enable this type of action.
1588    Syntax:
1589   </P
1590 ><P
1591 >   <TABLE
1592 BORDER="0"
1593 BGCOLOR="#E0E0E0"
1594 WIDTH="90%"
1595 ><TR
1596 ><TD
1597 ><PRE
1598 CLASS="SCREEN"
1599 >  +<TT
1600 CLASS="REPLACEABLE"
1601 ><I
1602 >name</I
1603 ></TT
1604 >{<TT
1605 CLASS="REPLACEABLE"
1606 ><I
1607 >param</I
1608 ></TT
1609 >}  # enable action and set parameter to <TT
1610 CLASS="REPLACEABLE"
1611 ><I
1612 >param</I
1613 ></TT
1614 >,
1615                # overwriting parameter from previous match if necessary
1616   -<TT
1617 CLASS="REPLACEABLE"
1618 ><I
1619 >name</I
1620 ></TT
1621 >         # disable action. The parameter can be omitted</PRE
1622 ></TD
1623 ></TR
1624 ></TABLE
1625 >
1626   </P
1627 ><P
1628 >   Note that if the URL matches multiple positive forms of a parameterized action,
1629    the last match wins, i.e. the params from earlier matches are simply ignored.
1630   </P
1631 ><P
1632 >  
1633    Example: <TT
1634 CLASS="LITERAL"
1635 >+hide-user-agent{Mozilla/5.0 (X11; U; FreeBSD i386; en-US; rv:1.8.1.4) Gecko/20070602 Firefox/2.0.0.4}</TT
1636 >
1637   </P
1638 ></LI
1639 ><LI
1640 ><P
1641 >  
1642    Multi-value. These look exactly like parameterized actions,
1643    but they behave differently: If the action applies multiple times to the
1644    same URL, but with different parameters, <SPAN
1645 CLASS="emphasis"
1646 ><I
1647 CLASS="EMPHASIS"
1648 >all</I
1649 ></SPAN
1650 > the parameters
1651    from <SPAN
1652 CLASS="emphasis"
1653 ><I
1654 CLASS="EMPHASIS"
1655 >all</I
1656 ></SPAN
1657 > matches are remembered. This is used for actions
1658    that can be executed for the same request repeatedly, like adding multiple
1659    headers, or filtering through multiple filters. Syntax:
1660   </P
1661 ><P
1662 >   <TABLE
1663 BORDER="0"
1664 BGCOLOR="#E0E0E0"
1665 WIDTH="90%"
1666 ><TR
1667 ><TD
1668 ><PRE
1669 CLASS="SCREEN"
1670 >  +<TT
1671 CLASS="REPLACEABLE"
1672 ><I
1673 >name</I
1674 ></TT
1675 >{<TT
1676 CLASS="REPLACEABLE"
1677 ><I
1678 >param</I
1679 ></TT
1680 >}   # enable action and add <TT
1681 CLASS="REPLACEABLE"
1682 ><I
1683 >param</I
1684 ></TT
1685 > to the list of parameters
1686   -<TT
1687 CLASS="REPLACEABLE"
1688 ><I
1689 >name</I
1690 ></TT
1691 >{<TT
1692 CLASS="REPLACEABLE"
1693 ><I
1694 >param</I
1695 ></TT
1696 >}   # remove the parameter <TT
1697 CLASS="REPLACEABLE"
1698 ><I
1699 >param</I
1700 ></TT
1701 > from the list of parameters
1702                 # If it was the last one left, disable the action.
1703   <TT
1704 CLASS="REPLACEABLE"
1705 ><I
1706 >-name</I
1707 ></TT
1708 >          # disable this action completely and remove all parameters from the list</PRE
1709 ></TD
1710 ></TR
1711 ></TABLE
1712 >
1713   </P
1714 ><P
1715 >  
1716    Examples: <TT
1717 CLASS="LITERAL"
1718 >+add-header{X-Fun-Header: Some text}</TT
1719 > and
1720    <TT
1721 CLASS="LITERAL"
1722 >+filter{html-annoyances}</TT
1723 >
1724   </P
1725 ></LI
1726 ></UL
1727 ></P
1728 ><P
1729 > If nothing is specified in any actions file, no <SPAN
1730 CLASS="QUOTE"
1731 >"actions"</SPAN
1732 > are
1733  taken. So in this case <SPAN
1734 CLASS="APPLICATION"
1735 >Privoxy</SPAN
1736 > would just be a
1737  normal, non-blocking, non-filtering proxy. You must specifically enable the
1738  privacy and blocking features you need (although the provided default actions
1739  files will give a good starting point).</P
1740 ><P
1741 > Later defined action sections always over-ride earlier ones of the same type.
1742  So exceptions to any rules you make, should come in the latter part of the file (or 
1743  in a file that is processed later when using multiple actions files such 
1744  as <TT
1745 CLASS="FILENAME"
1746 >user.action</TT
1747 >). For multi-valued actions, the actions
1748  are applied in the order they are specified. Actions files are processed in
1749  the order they are defined in <TT
1750 CLASS="FILENAME"
1751 >config</TT
1752 > (the default
1753  installation has three actions files). It also quite possible for any given
1754  URL to match more than one <SPAN
1755 CLASS="QUOTE"
1756 >"pattern"</SPAN
1757 > (because of wildcards and
1758  regular expressions), and thus to trigger more than one set of actions! Last
1759  match wins.</P
1760 ><P
1761 > The list of valid <SPAN
1762 CLASS="APPLICATION"
1763 >Privoxy</SPAN
1764 > actions are:</P
1765 ><DIV
1766 CLASS="SECT3"
1767 ><H4
1768 CLASS="SECT3"
1769 ><A
1770 NAME="ADD-HEADER"
1771 >8.5.1. add-header</A
1772 ></H4
1773 ><P
1774 ></P
1775 ><DIV
1776 CLASS="VARIABLELIST"
1777 ><DL
1778 ><DT
1779 >Typical use:</DT
1780 ><DD
1781 ><P
1782 >Confuse log analysis, custom applications</P
1783 ></DD
1784 ><DT
1785 >Effect:</DT
1786 ><DD
1787 ><P
1788 >    Sends a user defined HTTP header to the web server.
1789    </P
1790 ></DD
1791 ><DT
1792 >Type:</DT
1793 ><DD
1794 ><P
1795 >Multi-value.</P
1796 ></DD
1797 ><DT
1798 >Parameter:</DT
1799 ><DD
1800 ><P
1801 >    Any string value is possible. Validity of the defined HTTP headers is not checked.
1802     It is recommended that you use the <SPAN
1803 CLASS="QUOTE"
1804 >"<TT
1805 CLASS="LITERAL"
1806 >X-</TT
1807 >"</SPAN
1808 > prefix
1809     for custom headers.
1810    </P
1811 ></DD
1812 ><DT
1813 >Notes:</DT
1814 ><DD
1815 ><P
1816 >    This action may be specified multiple times, in order to define multiple 
1817     headers. This is rarely needed for the typical user. If you don't know what 
1818     <SPAN
1819 CLASS="QUOTE"
1820 >"HTTP headers"</SPAN
1821 > are, you definitely don't need to worry about this 
1822     one.
1823    </P
1824 ><P
1825 >    Headers added by this action are not modified by other actions.
1826    </P
1827 ></DD
1828 ><DT
1829 >Example usage:</DT
1830 ><DD
1831 ><P
1832 >     <TABLE
1833 BORDER="0"
1834 BGCOLOR="#E0E0E0"
1835 WIDTH="90%"
1836 ><TR
1837 ><TD
1838 ><PRE
1839 CLASS="SCREEN"
1840 >+add-header{X-User-Tracking: sucks}</PRE
1841 ></TD
1842 ></TR
1843 ></TABLE
1844 >
1845    </P
1846 ></DD
1847 ></DL
1848 ></DIV
1849 ></DIV
1850 ><DIV
1851 CLASS="SECT3"
1852 ><H4
1853 CLASS="SECT3"
1854 ><A
1855 NAME="BLOCK"
1856 >8.5.2. block</A
1857 ></H4
1858 ><P
1859 ></P
1860 ><DIV
1861 CLASS="VARIABLELIST"
1862 ><DL
1863 ><DT
1864 >Typical use:</DT
1865 ><DD
1866 ><P
1867 >Block ads or other unwanted content</P
1868 ></DD
1869 ><DT
1870 >Effect:</DT
1871 ><DD
1872 ><P
1873 >    Requests for URLs to which this action applies are blocked, i.e. the
1874     requests are trapped by <SPAN
1875 CLASS="APPLICATION"
1876 >Privoxy</SPAN
1877 > and the requested URL is never retrieved,
1878     but is answered locally with a substitute page or image, as determined by
1879     the <TT
1880 CLASS="LITERAL"
1881 ><A
1882 HREF="actions-file.html#HANDLE-AS-IMAGE"
1883 >handle-as-image</A
1884 ></TT
1885 >,
1886     <TT
1887 CLASS="LITERAL"
1888 ><A
1889 HREF="actions-file.html#SET-IMAGE-BLOCKER"
1890 >set-image-blocker</A
1891 ></TT
1892 >, and 
1893     <TT
1894 CLASS="LITERAL"
1895 ><A
1896 HREF="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT"
1897 >handle-as-empty-document</A
1898 ></TT
1899 > actions.
1900     
1901    </P
1902 ></DD
1903 ><DT
1904 >Type:</DT
1905 ><DD
1906 ><P
1907 >Parameterized.</P
1908 ></DD
1909 ><DT
1910 >Parameter:</DT
1911 ><DD
1912 ><P
1913 >A block reason that should be given to the user.</P
1914 ></DD
1915 ><DT
1916 >Notes:</DT
1917 ><DD
1918 ><P
1919 >    <SPAN
1920 CLASS="APPLICATION"
1921 >Privoxy</SPAN
1922 > sends a special <SPAN
1923 CLASS="QUOTE"
1924 >"BLOCKED"</SPAN
1925 > page
1926     for requests to blocked pages. This page contains the block reason given as
1927     parameter, a link to find out why the block action applies, and a click-through
1928     to the blocked content (the latter only if the force feature is available and
1929     enabled).
1930    </P
1931 ><P
1932
1933     A very important exception occurs if <SPAN
1934 CLASS="emphasis"
1935 ><I
1936 CLASS="EMPHASIS"
1937 >both</I
1938 ></SPAN
1939
1940     <TT
1941 CLASS="LITERAL"
1942 >block</TT
1943 > and <TT
1944 CLASS="LITERAL"
1945 ><A
1946 HREF="actions-file.html#HANDLE-AS-IMAGE"
1947 >handle-as-image</A
1948 ></TT
1949 >,
1950     apply to the same request: it will then be replaced by an image. If 
1951     <TT
1952 CLASS="LITERAL"
1953 ><A
1954 HREF="actions-file.html#SET-IMAGE-BLOCKER"
1955 >set-image-blocker</A
1956 ></TT
1957 >
1958     (see below) also applies, the type of image will be determined by its parameter,
1959     if not, the standard checkerboard pattern is sent.
1960    </P
1961 ><P
1962 >    It is important to understand this process, in order 
1963     to understand how <SPAN
1964 CLASS="APPLICATION"
1965 >Privoxy</SPAN
1966 > deals with 
1967     ads and other unwanted content. Blocking is a core feature, and one 
1968     upon which various other features depend.
1969    </P
1970 ><P
1971 >    The <TT
1972 CLASS="LITERAL"
1973 ><A
1974 HREF="actions-file.html#FILTER"
1975 >filter</A
1976 ></TT
1977 >
1978     action can perform a very similar task, by <SPAN
1979 CLASS="QUOTE"
1980 >"blocking"</SPAN
1981 >
1982     banner images and other content through rewriting the relevant URLs in the
1983     document's HTML source, so they don't get requested in the first place.
1984     Note that this is a totally different technique, and it's easy to confuse the two.
1985    </P
1986 ></DD
1987 ><DT
1988 >Example usage (section):</DT
1989 ><DD
1990 ><P
1991 >     <TABLE
1992 BORDER="0"
1993 BGCOLOR="#E0E0E0"
1994 WIDTH="90%"
1995 ><TR
1996 ><TD
1997 ><PRE
1998 CLASS="SCREEN"
1999 >{+block{No nasty stuff for you.}}
2000 # Block and replace with "blocked" page
2001  .nasty-stuff.example.com
2002
2003 {+block{Doubleclick banners.} +handle-as-image} 
2004 # Block and replace with image
2005  .ad.doubleclick.net
2006  .ads.r.us/banners/
2007
2008 {+block{Layered ads.} +handle-as-empty-document} 
2009 # Block and then ignore
2010  adserver.example.net/.*\.js$</PRE
2011 ></TD
2012 ></TR
2013 ></TABLE
2014 >
2015     </P
2016 ></DD
2017 ></DL
2018 ></DIV
2019 ></DIV
2020 ><DIV
2021 CLASS="SECT3"
2022 ><H4
2023 CLASS="SECT3"
2024 ><A
2025 NAME="CHANGE-X-FORWARDED-FOR"
2026 >8.5.3. change-x-forwarded-for</A
2027 ></H4
2028 ><P
2029 ></P
2030 ><DIV
2031 CLASS="VARIABLELIST"
2032 ><DL
2033 ><DT
2034 >Typical use:</DT
2035 ><DD
2036 ><P
2037 >Improve privacy by not forwarding the source of the request in the HTTP headers.</P
2038 ></DD
2039 ><DT
2040 >Effect:</DT
2041 ><DD
2042 ><P
2043 >    Deletes the <SPAN
2044 CLASS="QUOTE"
2045 >"X-Forwarded-For:"</SPAN
2046 > HTTP header from the client request,
2047     or adds a new one.
2048    </P
2049 ></DD
2050 ><DT
2051 >Type:</DT
2052 ><DD
2053 ><P
2054 >Parameterized.</P
2055 ></DD
2056 ><DT
2057 >Parameter:</DT
2058 ><DD
2059 ><P
2060 ></P
2061 ><UL
2062 ><LI
2063 ><P
2064 ><SPAN
2065 CLASS="QUOTE"
2066 >"block"</SPAN
2067 > to delete the header.</P
2068 ></LI
2069 ><LI
2070 ><P
2071 >       <SPAN
2072 CLASS="QUOTE"
2073 >"add"</SPAN
2074 > to create the header (or append
2075        the client's IP address to an already existing one).
2076      </P
2077 ></LI
2078 ></UL
2079 ></DD
2080 ><DT
2081 >Notes:</DT
2082 ><DD
2083 ><P
2084 >    It is safe and recommended to use <TT
2085 CLASS="LITERAL"
2086 >block</TT
2087 >.
2088    </P
2089 ><P
2090 >    Forwarding the source address of the request may make
2091     sense in some multi-user setups but is also a privacy risk.
2092    </P
2093 ></DD
2094 ><DT
2095 >Example usage:</DT
2096 ><DD
2097 ><P
2098 >     <TABLE
2099 BORDER="0"
2100 BGCOLOR="#E0E0E0"
2101 WIDTH="90%"
2102 ><TR
2103 ><TD
2104 ><PRE
2105 CLASS="SCREEN"
2106 >+change-x-forwarded-for{block}</PRE
2107 ></TD
2108 ></TR
2109 ></TABLE
2110 >
2111    </P
2112 ></DD
2113 ></DL
2114 ></DIV
2115 ></DIV
2116 ><DIV
2117 CLASS="SECT3"
2118 ><H4
2119 CLASS="SECT3"
2120 ><A
2121 NAME="CLIENT-HEADER-FILTER"
2122 >8.5.4. client-header-filter</A
2123 ></H4
2124 ><P
2125 ></P
2126 ><DIV
2127 CLASS="VARIABLELIST"
2128 ><DL
2129 ><DT
2130 >Typical use:</DT
2131 ><DD
2132 ><P
2133 >   Rewrite or remove single client headers.
2134    </P
2135 ></DD
2136 ><DT
2137 >Effect:</DT
2138 ><DD
2139 ><P
2140 >    All client headers to which this action applies are filtered on-the-fly through
2141     the specified regular expression based substitutions.
2142    </P
2143 ></DD
2144 ><DT
2145 >Type:</DT
2146 ><DD
2147 ><P
2148 >Parameterized.</P
2149 ></DD
2150 ><DT
2151 >Parameter:</DT
2152 ><DD
2153 ><P
2154 >    The name of a client-header filter, as defined in one of the
2155     <A
2156 HREF="filter-file.html"
2157 >filter files</A
2158 >.
2159    </P
2160 ></DD
2161 ><DT
2162 >Notes:</DT
2163 ><DD
2164 ><P
2165 >    Client-header filters are applied to each header on its own, not to
2166     all at once. This makes it easier to diagnose problems, but on the downside
2167     you can't write filters that only change header x if header y's value is z.
2168     You can do that by using tags though.
2169    </P
2170 ><P
2171 >    Client-header filters are executed after the other header actions have finished
2172     and use their output as input.
2173    </P
2174 ><P
2175 >    If the request URL gets changed, <SPAN
2176 CLASS="APPLICATION"
2177 >Privoxy</SPAN
2178 > will detect that and use the new
2179     one. This can be used to rewrite the request destination behind the client's
2180     back, for example to specify a Tor exit relay for certain requests.
2181    </P
2182 ><P
2183 >    Please refer to the <A
2184 HREF="filter-file.html"
2185 >filter file chapter</A
2186 >
2187     to learn which client-header filters are available by default, and how to
2188     create your own.
2189    </P
2190 ></DD
2191 ><DT
2192 >Example usage (section):</DT
2193 ><DD
2194 ><P
2195 >     <TABLE
2196 BORDER="0"
2197 BGCOLOR="#E0E0E0"
2198 WIDTH="90%"
2199 ><TR
2200 ><TD
2201 ><PRE
2202 CLASS="SCREEN"
2203 ># Hide Tor exit notation in Host and Referer Headers
2204 {+client-header-filter{hide-tor-exit-notation}}
2205 /
2206     </PRE
2207 ></TD
2208 ></TR
2209 ></TABLE
2210 >
2211     </P
2212 ></DD
2213 ></DL
2214 ></DIV
2215 ></DIV
2216 ><DIV
2217 CLASS="SECT3"
2218 ><H4
2219 CLASS="SECT3"
2220 ><A
2221 NAME="CLIENT-HEADER-TAGGER"
2222 >8.5.5. client-header-tagger</A
2223 ></H4
2224 ><P
2225 ></P
2226 ><DIV
2227 CLASS="VARIABLELIST"
2228 ><DL
2229 ><DT
2230 >Typical use:</DT
2231 ><DD
2232 ><P
2233 >   Block requests based on their headers.
2234    </P
2235 ></DD
2236 ><DT
2237 >Effect:</DT
2238 ><DD
2239 ><P
2240 >    Client headers to which this action applies are filtered on-the-fly through
2241     the specified regular expression based substitutions, the result is used as
2242     tag. 
2243    </P
2244 ></DD
2245 ><DT
2246 >Type:</DT
2247 ><DD
2248 ><P
2249 >Parameterized.</P
2250 ></DD
2251 ><DT
2252 >Parameter:</DT
2253 ><DD
2254 ><P
2255 >    The name of a client-header tagger, as defined in one of the
2256     <A
2257 HREF="filter-file.html"
2258 >filter files</A
2259 >.
2260    </P
2261 ></DD
2262 ><DT
2263 >Notes:</DT
2264 ><DD
2265 ><P
2266 >    Client-header taggers are applied to each header on its own,
2267     and as the header isn't modified, each tagger <SPAN
2268 CLASS="QUOTE"
2269 >"sees"</SPAN
2270 >
2271     the original.
2272    </P
2273 ><P
2274 >    Client-header taggers are the first actions that are executed
2275     and their tags can be used to control every other action.
2276    </P
2277 ></DD
2278 ><DT
2279 >Example usage (section):</DT
2280 ><DD
2281 ><P
2282 >     <TABLE
2283 BORDER="0"
2284 BGCOLOR="#E0E0E0"
2285 WIDTH="90%"
2286 ><TR
2287 ><TD
2288 ><PRE
2289 CLASS="SCREEN"
2290 ># Tag every request with the User-Agent header
2291 {+client-header-tagger{user-agent}}
2292 /
2293
2294 # Tagging itself doesn't change the action
2295 # settings, sections with TAG patterns do:
2296 #
2297 # If it's a download agent, use a different forwarding proxy,
2298 # show the real User-Agent and make sure resume works.
2299 {+forward-override{forward-socks5 10.0.0.2:2222 .} \
2300  -hide-if-modified-since      \
2301  -overwrite-last-modified     \
2302  -hide-user-agent             \
2303  -filter                      \
2304  -deanimate-gifs              \
2305 }
2306 TAG:^User-Agent: NetBSD-ftp/
2307 TAG:^User-Agent: Novell ZYPP Installer
2308 TAG:^User-Agent: RPM APT-HTTP/
2309 TAG:^User-Agent: fetch libfetch/
2310 TAG:^User-Agent: Ubuntu APT-HTTP/
2311 TAG:^User-Agent: MPlayer/
2312     </PRE
2313 ></TD
2314 ></TR
2315 ></TABLE
2316 >
2317     </P
2318 ></DD
2319 ></DL
2320 ></DIV
2321 ></DIV
2322 ><DIV
2323 CLASS="SECT3"
2324 ><H4
2325 CLASS="SECT3"
2326 ><A
2327 NAME="CONTENT-TYPE-OVERWRITE"
2328 >8.5.6. content-type-overwrite</A
2329 ></H4
2330 ><P
2331 ></P
2332 ><DIV
2333 CLASS="VARIABLELIST"
2334 ><DL
2335 ><DT
2336 >Typical use:</DT
2337 ><DD
2338 ><P
2339 >Stop useless download menus from popping up, or change the browser's rendering mode</P
2340 ></DD
2341 ><DT
2342 >Effect:</DT
2343 ><DD
2344 ><P
2345 >    Replaces the <SPAN
2346 CLASS="QUOTE"
2347 >"Content-Type:"</SPAN
2348 > HTTP server header.
2349    </P
2350 ></DD
2351 ><DT
2352 >Type:</DT
2353 ><DD
2354 ><P
2355 >Parameterized.</P
2356 ></DD
2357 ><DT
2358 >Parameter:</DT
2359 ><DD
2360 ><P
2361 >    Any string. 
2362    </P
2363 ></DD
2364 ><DT
2365 >Notes:</DT
2366 ><DD
2367 ><P
2368 >    The <SPAN
2369 CLASS="QUOTE"
2370 >"Content-Type:"</SPAN
2371 > HTTP server header is used by the
2372     browser to decide what to do with the document. The value of this
2373     header can cause the browser to open a download menu instead of
2374     displaying the document by itself, even if the document's format is
2375     supported by the browser. 
2376    </P
2377 ><P
2378 >    The declared content type can also affect which rendering mode
2379     the browser chooses. If XHTML is delivered as <SPAN
2380 CLASS="QUOTE"
2381 >"text/html"</SPAN
2382 >,
2383     many browsers treat it as yet another broken HTML document.
2384     If it is send as <SPAN
2385 CLASS="QUOTE"
2386 >"application/xml"</SPAN
2387 >, browsers with
2388     XHTML support will only display it, if the syntax is correct.
2389    </P
2390 ><P
2391 >    If you see a web site that proudly uses XHTML buttons, but sets
2392     <SPAN
2393 CLASS="QUOTE"
2394 >"Content-Type: text/html"</SPAN
2395 >, you can use <SPAN
2396 CLASS="APPLICATION"
2397 >Privoxy</SPAN
2398 >
2399     to overwrite it with <SPAN
2400 CLASS="QUOTE"
2401 >"application/xml"</SPAN
2402 > and validate
2403     the web master's claim inside your XHTML-supporting browser.
2404     If the syntax is incorrect, the browser will complain loudly. 
2405    </P
2406 ><P
2407 >    You can also go the opposite direction: if your browser prints
2408     error messages instead of rendering a document falsely declared
2409     as XHTML, you can overwrite the content type with
2410     <SPAN
2411 CLASS="QUOTE"
2412 >"text/html"</SPAN
2413 > and have it rendered as broken HTML document. 
2414    </P
2415 ><P
2416 >    By default <TT
2417 CLASS="LITERAL"
2418 >content-type-overwrite</TT
2419 > only replaces
2420     <SPAN
2421 CLASS="QUOTE"
2422 >"Content-Type:"</SPAN
2423 > headers that look like some kind of text.
2424     If you want to overwrite it unconditionally, you have to combine it with
2425     <TT
2426 CLASS="LITERAL"
2427 ><A
2428 HREF="actions-file.html#FORCE-TEXT-MODE"
2429 >force-text-mode</A
2430 ></TT
2431 >.
2432     This limitation exists for a reason, think twice before circumventing it.
2433    </P
2434 ><P
2435 >    Most of the time it's easier to replace this action with a custom
2436     <TT
2437 CLASS="LITERAL"
2438 ><A
2439 HREF="actions-file.html#SERVER-HEADER-FILTER"
2440 >server-header filter</A
2441 ></TT
2442 >.
2443     It allows you to activate it for every document of a certain site and it will still
2444     only replace the content types you aimed at.
2445    </P
2446 ><P
2447 >    Of course you can apply <TT
2448 CLASS="LITERAL"
2449 >content-type-overwrite</TT
2450 >
2451     to a whole site and then make URL based exceptions, but it's a lot
2452     more work to get the same precision. 
2453    </P
2454 ></DD
2455 ><DT
2456 >Example usage (sections):</DT
2457 ><DD
2458 ><P
2459 >     <TABLE
2460 BORDER="0"
2461 BGCOLOR="#E0E0E0"
2462 WIDTH="90%"
2463 ><TR
2464 ><TD
2465 ><PRE
2466 CLASS="SCREEN"
2467 ># Check if www.example.net/ really uses valid XHTML
2468 { +content-type-overwrite{application/xml} }
2469 www.example.net/
2470
2471 # but leave the content type unmodified if the URL looks like a style sheet
2472 {-content-type-overwrite}
2473 www.example.net/.*\.css$
2474 www.example.net/.*style</PRE
2475 ></TD
2476 ></TR
2477 ></TABLE
2478 >
2479    </P
2480 ></DD
2481 ></DL
2482 ></DIV
2483 ></DIV
2484 ><DIV
2485 CLASS="SECT3"
2486 ><H4
2487 CLASS="SECT3"
2488 ><A
2489 NAME="CRUNCH-CLIENT-HEADER"
2490 >8.5.7. crunch-client-header</A
2491 ></H4
2492 ><P
2493 ></P
2494 ><DIV
2495 CLASS="VARIABLELIST"
2496 ><DL
2497 ><DT
2498 >Typical use:</DT
2499 ><DD
2500 ><P
2501 >Remove a client header <SPAN
2502 CLASS="APPLICATION"
2503 >Privoxy</SPAN
2504 > has no dedicated action for.</P
2505 ></DD
2506 ><DT
2507 >Effect:</DT
2508 ><DD
2509 ><P
2510 >    Deletes every header sent by the client that contains the string the user supplied as parameter.
2511    </P
2512 ></DD
2513 ><DT
2514 >Type:</DT
2515 ><DD
2516 ><P
2517 >Parameterized.</P
2518 ></DD
2519 ><DT
2520 >Parameter:</DT
2521 ><DD
2522 ><P
2523 >    Any string.
2524    </P
2525 ></DD
2526 ><DT
2527 >Notes:</DT
2528 ><DD
2529 ><P
2530 >    This action allows you to block client headers for which no dedicated
2531     <SPAN
2532 CLASS="APPLICATION"
2533 >Privoxy</SPAN
2534 > action exists.
2535     <SPAN
2536 CLASS="APPLICATION"
2537 >Privoxy</SPAN
2538 > will remove every client header that
2539     contains the string you supplied as parameter.
2540    </P
2541 ><P
2542 >    Regular expressions are <SPAN
2543 CLASS="emphasis"
2544 ><I
2545 CLASS="EMPHASIS"
2546 >not supported</I
2547 ></SPAN
2548 > and you can't
2549     use this action to block different headers in the same request, unless
2550     they contain the same string.
2551    </P
2552 ><P
2553 >    <TT
2554 CLASS="LITERAL"
2555 >crunch-client-header</TT
2556 > is only meant for quick tests.
2557     If you have to block several different headers, or only want to modify
2558     parts of them, you should use a
2559     <TT
2560 CLASS="LITERAL"
2561 ><A
2562 HREF="actions-file.html#CLIENT-HEADER-FILTER"
2563 >client-header filter</A
2564 ></TT
2565 >.
2566    </P
2567 ><DIV
2568 CLASS="WARNING"
2569 ><P
2570 ></P
2571 ><TABLE
2572 CLASS="WARNING"
2573 BORDER="1"
2574 WIDTH="90%"
2575 ><TR
2576 ><TD
2577 ALIGN="CENTER"
2578 ><B
2579 >Warning</B
2580 ></TD
2581 ></TR
2582 ><TR
2583 ><TD
2584 ALIGN="LEFT"
2585 ><P
2586 >      Don't block any header without understanding the consequences.
2587      </P
2588 ></TD
2589 ></TR
2590 ></TABLE
2591 ></DIV
2592 ></DD
2593 ><DT
2594 >Example usage (section):</DT
2595 ><DD
2596 ><P
2597 >     <TABLE
2598 BORDER="0"
2599 BGCOLOR="#E0E0E0"
2600 WIDTH="90%"
2601 ><TR
2602 ><TD
2603 ><PRE
2604 CLASS="SCREEN"
2605 ># Block the non-existent "Privacy-Violation:" client header 
2606 { +crunch-client-header{Privacy-Violation:} }
2607 /
2608     </PRE
2609 ></TD
2610 ></TR
2611 ></TABLE
2612 >
2613    </P
2614 ></DD
2615 ></DL
2616 ></DIV
2617 ></DIV
2618 ><DIV
2619 CLASS="SECT3"
2620 ><H4
2621 CLASS="SECT3"
2622 ><A
2623 NAME="CRUNCH-IF-NONE-MATCH"
2624 >8.5.8. crunch-if-none-match</A
2625 ></H4
2626 ><P
2627 ></P
2628 ><DIV
2629 CLASS="VARIABLELIST"
2630 ><DL
2631 ><DT
2632 >Typical use:</DT
2633 ><DD
2634 ><P
2635 >Prevent yet another way to track the user's steps between sessions.</P
2636 ></DD
2637 ><DT
2638 >Effect:</DT
2639 ><DD
2640 ><P
2641 >    Deletes the <SPAN
2642 CLASS="QUOTE"
2643 >"If-None-Match:"</SPAN
2644 > HTTP client header.
2645    </P
2646 ></DD
2647 ><DT
2648 >Type:</DT
2649 ><DD
2650 ><P
2651 >Boolean.</P
2652 ></DD
2653 ><DT
2654 >Parameter:</DT
2655 ><DD
2656 ><P
2657 >    N/A
2658    </P
2659 ></DD
2660 ><DT
2661 >Notes:</DT
2662 ><DD
2663 ><P
2664 >    Removing the <SPAN
2665 CLASS="QUOTE"
2666 >"If-None-Match:"</SPAN
2667 > HTTP client header
2668     is useful for filter testing, where you want to force a real
2669     reload instead of getting status code <SPAN
2670 CLASS="QUOTE"
2671 >"304"</SPAN
2672 > which
2673     would cause the browser to use a cached copy of the page.
2674    </P
2675 ><P
2676 >    It is also useful to make sure the header isn't used as a cookie
2677     replacement (unlikely but possible).
2678    </P
2679 ><P
2680 >    Blocking the <SPAN
2681 CLASS="QUOTE"
2682 >"If-None-Match:"</SPAN
2683 > header shouldn't cause any
2684     caching problems, as long as the <SPAN
2685 CLASS="QUOTE"
2686 >"If-Modified-Since:"</SPAN
2687 > header
2688     isn't blocked or missing as well.
2689    </P
2690 ><P
2691 >    It is recommended to use this action together with
2692     <TT
2693 CLASS="LITERAL"
2694 ><A
2695 HREF="actions-file.html#HIDE-IF-MODIFIED-SINCE"
2696 >hide-if-modified-since</A
2697 ></TT
2698 >
2699     and
2700     <TT
2701 CLASS="LITERAL"
2702 ><A
2703 HREF="actions-file.html#OVERWRITE-LAST-MODIFIED"
2704 >overwrite-last-modified</A
2705 ></TT
2706 >.
2707    </P
2708 ></DD
2709 ><DT
2710 >Example usage (section):</DT
2711 ><DD
2712 ><P
2713 >     <TABLE
2714 BORDER="0"
2715 BGCOLOR="#E0E0E0"
2716 WIDTH="90%"
2717 ><TR
2718 ><TD
2719 ><PRE
2720 CLASS="SCREEN"
2721 ># Let the browser revalidate cached documents but don't
2722 # allow the server to use the revalidation headers for user tracking.
2723 {+hide-if-modified-since{-60} \
2724  +overwrite-last-modified{randomize} \
2725  +crunch-if-none-match}
2726 /   </PRE
2727 ></TD
2728 ></TR
2729 ></TABLE
2730 >
2731    </P
2732 ></DD
2733 ></DL
2734 ></DIV
2735 ></DIV
2736 ><DIV
2737 CLASS="SECT3"
2738 ><H4
2739 CLASS="SECT3"
2740 ><A
2741 NAME="CRUNCH-INCOMING-COOKIES"
2742 >8.5.9. crunch-incoming-cookies</A
2743 ></H4
2744 ><P
2745 ></P
2746 ><DIV
2747 CLASS="VARIABLELIST"
2748 ><DL
2749 ><DT
2750 >Typical use:</DT
2751 ><DD
2752 ><P
2753 >    Prevent the web server from setting HTTP cookies on your system
2754    </P
2755 ></DD
2756 ><DT
2757 >Effect:</DT
2758 ><DD
2759 ><P
2760 >    Deletes any <SPAN
2761 CLASS="QUOTE"
2762 >"Set-Cookie:"</SPAN
2763 > HTTP headers from server replies.
2764    </P
2765 ></DD
2766 ><DT
2767 >Type:</DT
2768 ><DD
2769 ><P
2770 >Boolean.</P
2771 ></DD
2772 ><DT
2773 >Parameter:</DT
2774 ><DD
2775 ><P
2776 >    N/A
2777    </P
2778 ></DD
2779 ><DT
2780 >Notes:</DT
2781 ><DD
2782 ><P
2783 >    This action is only concerned with <SPAN
2784 CLASS="emphasis"
2785 ><I
2786 CLASS="EMPHASIS"
2787 >incoming</I
2788 ></SPAN
2789 > HTTP cookies. For
2790     <SPAN
2791 CLASS="emphasis"
2792 ><I
2793 CLASS="EMPHASIS"
2794 >outgoing</I
2795 ></SPAN
2796 > HTTP cookies, use
2797     <TT
2798 CLASS="LITERAL"
2799 ><A
2800 HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
2801 >crunch-outgoing-cookies</A
2802 ></TT
2803 >.
2804     Use <SPAN
2805 CLASS="emphasis"
2806 ><I
2807 CLASS="EMPHASIS"
2808 >both</I
2809 ></SPAN
2810 > to disable HTTP cookies completely.
2811    </P
2812 ><P
2813 >    It makes <SPAN
2814 CLASS="emphasis"
2815 ><I
2816 CLASS="EMPHASIS"
2817 >no sense at all</I
2818 ></SPAN
2819 > to use this action in conjunction
2820     with the <TT
2821 CLASS="LITERAL"
2822 ><A
2823 HREF="actions-file.html#SESSION-COOKIES-ONLY"
2824 >session-cookies-only</A
2825 ></TT
2826 > action,
2827     since it would prevent the session cookies from being set. See also 
2828     <TT
2829 CLASS="LITERAL"
2830 ><A
2831 HREF="actions-file.html#FILTER-CONTENT-COOKIES"
2832 >filter-content-cookies</A
2833 ></TT
2834 >.
2835    </P
2836 ></DD
2837 ><DT
2838 >Example usage:</DT
2839 ><DD
2840 ><P
2841 >    <TABLE
2842 BORDER="0"
2843 BGCOLOR="#E0E0E0"
2844 WIDTH="90%"
2845 ><TR
2846 ><TD
2847 ><PRE
2848 CLASS="SCREEN"
2849 >+crunch-incoming-cookies</PRE
2850 ></TD
2851 ></TR
2852 ></TABLE
2853 >
2854    </P
2855 ></DD
2856 ></DL
2857 ></DIV
2858 ></DIV
2859 ><DIV
2860 CLASS="SECT3"
2861 ><H4
2862 CLASS="SECT3"
2863 ><A
2864 NAME="CRUNCH-SERVER-HEADER"
2865 >8.5.10. crunch-server-header</A
2866 ></H4
2867 ><P
2868 ></P
2869 ><DIV
2870 CLASS="VARIABLELIST"
2871 ><DL
2872 ><DT
2873 >Typical use:</DT
2874 ><DD
2875 ><P
2876 >Remove a server header <SPAN
2877 CLASS="APPLICATION"
2878 >Privoxy</SPAN
2879 > has no dedicated action for.</P
2880 ></DD
2881 ><DT
2882 >Effect:</DT
2883 ><DD
2884 ><P
2885 >    Deletes every header sent by the server that contains the string the user supplied as parameter.
2886    </P
2887 ></DD
2888 ><DT
2889 >Type:</DT
2890 ><DD
2891 ><P
2892 >Parameterized.</P
2893 ></DD
2894 ><DT
2895 >Parameter:</DT
2896 ><DD
2897 ><P
2898 >    Any string.
2899    </P
2900 ></DD
2901 ><DT
2902 >Notes:</DT
2903 ><DD
2904 ><P
2905 >    This action allows you to block server headers for which no dedicated
2906     <SPAN
2907 CLASS="APPLICATION"
2908 >Privoxy</SPAN
2909 > action exists. <SPAN
2910 CLASS="APPLICATION"
2911 >Privoxy</SPAN
2912 >
2913     will remove every server header that contains the string you supplied as parameter.
2914    </P
2915 ><P
2916 >    Regular expressions are <SPAN
2917 CLASS="emphasis"
2918 ><I
2919 CLASS="EMPHASIS"
2920 >not supported</I
2921 ></SPAN
2922 > and you can't
2923     use this action to block different headers in the same request, unless
2924     they contain the same string.
2925    </P
2926 ><P
2927 >    <TT
2928 CLASS="LITERAL"
2929 >crunch-server-header</TT
2930 > is only meant for quick tests.
2931     If you have to block several different headers, or only want to modify
2932     parts of them, you should use a custom
2933     <TT
2934 CLASS="LITERAL"
2935 ><A
2936 HREF="actions-file.html#SERVER-HEADER-FILTER"
2937 >server-header filter</A
2938 ></TT
2939 >.
2940    </P
2941 ><DIV
2942 CLASS="WARNING"
2943 ><P
2944 ></P
2945 ><TABLE
2946 CLASS="WARNING"
2947 BORDER="1"
2948 WIDTH="90%"
2949 ><TR
2950 ><TD
2951 ALIGN="CENTER"
2952 ><B
2953 >Warning</B
2954 ></TD
2955 ></TR
2956 ><TR
2957 ><TD
2958 ALIGN="LEFT"
2959 ><P
2960 >     Don't block any header without understanding the consequences.
2961      </P
2962 ></TD
2963 ></TR
2964 ></TABLE
2965 ></DIV
2966 ></DD
2967 ><DT
2968 >Example usage (section):</DT
2969 ><DD
2970 ><P
2971 >     <TABLE
2972 BORDER="0"
2973 BGCOLOR="#E0E0E0"
2974 WIDTH="90%"
2975 ><TR
2976 ><TD
2977 ><PRE
2978 CLASS="SCREEN"
2979 ># Crunch server headers that try to prevent caching
2980 { +crunch-server-header{no-cache} }
2981 /   </PRE
2982 ></TD
2983 ></TR
2984 ></TABLE
2985 >
2986    </P
2987 ></DD
2988 ></DL
2989 ></DIV
2990 ></DIV
2991 ><DIV
2992 CLASS="SECT3"
2993 ><H4
2994 CLASS="SECT3"
2995 ><A
2996 NAME="CRUNCH-OUTGOING-COOKIES"
2997 >8.5.11. crunch-outgoing-cookies</A
2998 ></H4
2999 ><P
3000 ></P
3001 ><DIV
3002 CLASS="VARIABLELIST"
3003 ><DL
3004 ><DT
3005 >Typical use:</DT
3006 ><DD
3007 ><P
3008 >    Prevent the web server from reading any HTTP cookies from your system
3009    </P
3010 ></DD
3011 ><DT
3012 >Effect:</DT
3013 ><DD
3014 ><P
3015 >    Deletes any <SPAN
3016 CLASS="QUOTE"
3017 >"Cookie:"</SPAN
3018 > HTTP headers from client requests.
3019    </P
3020 ></DD
3021 ><DT
3022 >Type:</DT
3023 ><DD
3024 ><P
3025 >Boolean.</P
3026 ></DD
3027 ><DT
3028 >Parameter:</DT
3029 ><DD
3030 ><P
3031 >    N/A
3032    </P
3033 ></DD
3034 ><DT
3035 >Notes:</DT
3036 ><DD
3037 ><P
3038 >    This action is only concerned with <SPAN
3039 CLASS="emphasis"
3040 ><I
3041 CLASS="EMPHASIS"
3042 >outgoing</I
3043 ></SPAN
3044 > HTTP cookies. For
3045     <SPAN
3046 CLASS="emphasis"
3047 ><I
3048 CLASS="EMPHASIS"
3049 >incoming</I
3050 ></SPAN
3051 > HTTP cookies, use
3052     <TT
3053 CLASS="LITERAL"
3054 ><A
3055 HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
3056 >crunch-incoming-cookies</A
3057 ></TT
3058 >.
3059     Use <SPAN
3060 CLASS="emphasis"
3061 ><I
3062 CLASS="EMPHASIS"
3063 >both</I
3064 ></SPAN
3065 > to disable HTTP cookies completely.
3066    </P
3067 ><P
3068 >    It makes <SPAN
3069 CLASS="emphasis"
3070 ><I
3071 CLASS="EMPHASIS"
3072 >no sense at all</I
3073 ></SPAN
3074 > to use this action in conjunction
3075     with the <TT
3076 CLASS="LITERAL"
3077 ><A
3078 HREF="actions-file.html#SESSION-COOKIES-ONLY"
3079 >session-cookies-only</A
3080 ></TT
3081 > action,
3082     since it would prevent the session cookies from being read.
3083    </P
3084 ></DD
3085 ><DT
3086 >Example usage:</DT
3087 ><DD
3088 ><P
3089 >    <TABLE
3090 BORDER="0"
3091 BGCOLOR="#E0E0E0"
3092 WIDTH="90%"
3093 ><TR
3094 ><TD
3095 ><PRE
3096 CLASS="SCREEN"
3097 >+crunch-outgoing-cookies</PRE
3098 ></TD
3099 ></TR
3100 ></TABLE
3101 >
3102    </P
3103 ></DD
3104 ></DL
3105 ></DIV
3106 ></DIV
3107 ><DIV
3108 CLASS="SECT3"
3109 ><H4
3110 CLASS="SECT3"
3111 ><A
3112 NAME="DEANIMATE-GIFS"
3113 >8.5.12. deanimate-gifs</A
3114 ></H4
3115 ><P
3116 ></P
3117 ><DIV
3118 CLASS="VARIABLELIST"
3119 ><DL
3120 ><DT
3121 >Typical use:</DT
3122 ><DD
3123 ><P
3124 >Stop those annoying, distracting animated GIF images.</P
3125 ></DD
3126 ><DT
3127 >Effect:</DT
3128 ><DD
3129 ><P
3130 >    De-animate GIF animations, i.e. reduce them to their first or last image.
3131    </P
3132 ></DD
3133 ><DT
3134 >Type:</DT
3135 ><DD
3136 ><P
3137 >Parameterized.</P
3138 ></DD
3139 ><DT
3140 >Parameter:</DT
3141 ><DD
3142 ><P
3143 >    <SPAN
3144 CLASS="QUOTE"
3145 >"last"</SPAN
3146 > or <SPAN
3147 CLASS="QUOTE"
3148 >"first"</SPAN
3149 >
3150    </P
3151 ></DD
3152 ><DT
3153 >Notes:</DT
3154 ><DD
3155 ><P
3156 >    This will also shrink the images considerably (in bytes, not pixels!). If
3157     the option <SPAN
3158 CLASS="QUOTE"
3159 >"first"</SPAN
3160 > is given, the first frame of the animation
3161     is used as the replacement. If <SPAN
3162 CLASS="QUOTE"
3163 >"last"</SPAN
3164 > is given, the last
3165     frame of the animation is used instead, which probably makes more sense for
3166     most banner animations, but also has the risk of not showing the entire
3167     last frame (if it is only a delta to an earlier frame).
3168    </P
3169 ><P
3170 >    You can safely use this action with patterns that will also match non-GIF
3171     objects, because no attempt will be made at anything that doesn't look like
3172     a GIF.
3173    </P
3174 ></DD
3175 ><DT
3176 >Example usage:</DT
3177 ><DD
3178 ><P
3179 >      <TABLE
3180 BORDER="0"
3181 BGCOLOR="#E0E0E0"
3182 WIDTH="90%"
3183 ><TR
3184 ><TD
3185 ><PRE
3186 CLASS="SCREEN"
3187 >+deanimate-gifs{last}</PRE
3188 ></TD
3189 ></TR
3190 ></TABLE
3191 >
3192     </P
3193 ></DD
3194 ></DL
3195 ></DIV
3196 ></DIV
3197 ><DIV
3198 CLASS="SECT3"
3199 ><H4
3200 CLASS="SECT3"
3201 ><A
3202 NAME="DOWNGRADE-HTTP-VERSION"
3203 >8.5.13. downgrade-http-version</A
3204 ></H4
3205 ><P
3206 ></P
3207 ><DIV
3208 CLASS="VARIABLELIST"
3209 ><DL
3210 ><DT
3211 >Typical use:</DT
3212 ><DD
3213 ><P
3214 >Work around (very rare) problems with HTTP/1.1</P
3215 ></DD
3216 ><DT
3217 >Effect:</DT
3218 ><DD
3219 ><P
3220 >    Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
3221    </P
3222 ></DD
3223 ><DT
3224 >Type:</DT
3225 ><DD
3226 ><P
3227 >Boolean.</P
3228 ></DD
3229 ><DT
3230 >Parameter:</DT
3231 ><DD
3232 ><P
3233 >    N/A
3234    </P
3235 ></DD
3236 ><DT
3237 >Notes:</DT
3238 ><DD
3239 ><P
3240 >    This is a left-over from the time when <SPAN
3241 CLASS="APPLICATION"
3242 >Privoxy</SPAN
3243 >
3244     didn't support important HTTP/1.1 features well. It is left here for the
3245     unlikely case that you experience HTTP/1.1 related problems with some server
3246     out there. Not all HTTP/1.1 features and requirements are supported yet,
3247     so there is a chance you might need this action.
3248    </P
3249 ></DD
3250 ><DT
3251 >Example usage (section):</DT
3252 ><DD
3253 ><P
3254 >     <TABLE
3255 BORDER="0"
3256 BGCOLOR="#E0E0E0"
3257 WIDTH="90%"
3258 ><TR
3259 ><TD
3260 ><PRE
3261 CLASS="SCREEN"
3262 >{+downgrade-http-version}
3263 problem-host.example.com</PRE
3264 ></TD
3265 ></TR
3266 ></TABLE
3267 >
3268     </P
3269 ></DD
3270 ></DL
3271 ></DIV
3272 ></DIV
3273 ><DIV
3274 CLASS="SECT3"
3275 ><H4
3276 CLASS="SECT3"
3277 ><A
3278 NAME="FAST-REDIRECTS"
3279 >8.5.14. fast-redirects</A
3280 ></H4
3281 ><P
3282 ></P
3283 ><DIV
3284 CLASS="VARIABLELIST"
3285 ><DL
3286 ><DT
3287 >Typical use:</DT
3288 ><DD
3289 ><P
3290 >Fool some click-tracking scripts and speed up indirect links.</P
3291 ></DD
3292 ><DT
3293 >Effect:</DT
3294 ><DD
3295 ><P
3296 >    Detects redirection URLs and redirects the browser without contacting
3297     the redirection server first.
3298    </P
3299 ></DD
3300 ><DT
3301 >Type:</DT
3302 ><DD
3303 ><P
3304 >Parameterized.</P
3305 ></DD
3306 ><DT
3307 >Parameter:</DT
3308 ><DD
3309 ><P
3310 ></P
3311 ><UL
3312 ><LI
3313 ><P
3314 >      <SPAN
3315 CLASS="QUOTE"
3316 >"simple-check"</SPAN
3317 > to just search for the string <SPAN
3318 CLASS="QUOTE"
3319 >"http://"</SPAN
3320 >
3321       to detect redirection URLs.
3322      </P
3323 ></LI
3324 ><LI
3325 ><P
3326 >      <SPAN
3327 CLASS="QUOTE"
3328 >"check-decoded-url"</SPAN
3329 > to decode URLs (if necessary) before searching
3330       for redirection URLs.
3331      </P
3332 ></LI
3333 ></UL
3334 ></DD
3335 ><DT
3336 >Notes:</DT
3337 ><DD
3338 ><P
3339 >  
3340     Many sites, like yahoo.com, don't just link to other sites. Instead, they
3341     will link to some script on their own servers, giving the destination as a
3342     parameter, which will then redirect you to the final target. URLs
3343     resulting from this scheme typically look like:
3344     <SPAN
3345 CLASS="QUOTE"
3346 >"http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/"</SPAN
3347 >.
3348   </P
3349 ><P
3350 >    Sometimes, there are even multiple consecutive redirects encoded in the
3351     URL. These redirections via scripts make your web browsing more traceable,
3352     since the server from which you follow such a link can see where you go
3353     to. Apart from that, valuable bandwidth and time is wasted, while your
3354     browser asks the server for one redirect after the other. Plus, it feeds
3355     the advertisers.
3356    </P
3357 ><P
3358 >    This feature is currently not very smart and is scheduled for improvement.
3359     If it is enabled by default, you will have to create some exceptions to
3360     this action. It can lead to failures in several ways: 
3361    </P
3362 ><P
3363 >    Not every URLs with other URLs as parameters is evil.
3364     Some sites offer a real service that requires this information to work.
3365     For example a validation service needs to know, which document to validate.
3366     <TT
3367 CLASS="LITERAL"
3368 >fast-redirects</TT
3369 > assumes that every URL parameter that
3370     looks like another URL is a redirection target, and will always redirect to
3371     the last one. Most of the time the assumption is correct, but if it isn't,
3372     the user gets redirected anyway.
3373    </P
3374 ><P
3375 >    Another failure occurs if the URL contains other parameters after the URL parameter.
3376     The URL:
3377     <SPAN
3378 CLASS="QUOTE"
3379 >"http://www.example.org/?redirect=http%3a//www.example.net/&#38;foo=bar"</SPAN
3380 >.
3381     contains the redirection URL <SPAN
3382 CLASS="QUOTE"
3383 >"http://www.example.net/"</SPAN
3384 >,
3385     followed by another parameter. <TT
3386 CLASS="LITERAL"
3387 >fast-redirects</TT
3388 > doesn't know that
3389     and will cause a redirect to <SPAN
3390 CLASS="QUOTE"
3391 >"http://www.example.net/&#38;foo=bar"</SPAN
3392 >.
3393     Depending on the target server configuration, the parameter will be silently ignored
3394     or lead to a <SPAN
3395 CLASS="QUOTE"
3396 >"page not found"</SPAN
3397 > error. You can prevent this problem by
3398     first using the <TT
3399 CLASS="LITERAL"
3400 ><A
3401 HREF="actions-file.html#REDIRECT"
3402 >redirect</A
3403 ></TT
3404 > action
3405     to remove the last part of the URL, but it requires a little effort.
3406    </P
3407 ><P
3408 >    To detect a redirection URL, <TT
3409 CLASS="LITERAL"
3410 >fast-redirects</TT
3411 > only
3412     looks for the string <SPAN
3413 CLASS="QUOTE"
3414 >"http://"</SPAN
3415 >, either in plain text
3416     (invalid but often used) or encoded as <SPAN
3417 CLASS="QUOTE"
3418 >"http%3a//"</SPAN
3419 >.
3420     Some sites use their own URL encoding scheme, encrypt the address
3421     of the target server or replace it with a database id. In theses cases
3422     <TT
3423 CLASS="LITERAL"
3424 >fast-redirects</TT
3425 > is fooled and the request reaches the
3426     redirection server where it probably gets logged.
3427    </P
3428 ></DD
3429 ><DT
3430 >Example usage:</DT
3431 ><DD
3432 ><P
3433 >     <TABLE
3434 BORDER="0"
3435 BGCOLOR="#E0E0E0"
3436 WIDTH="90%"
3437 ><TR
3438 ><TD
3439 ><PRE
3440 CLASS="SCREEN"
3441 > { +fast-redirects{simple-check} }
3442    one.example.com 
3443
3444  { +fast-redirects{check-decoded-url} }
3445    another.example.com/testing</PRE
3446 ></TD
3447 ></TR
3448 ></TABLE
3449 >
3450     </P
3451 ></DD
3452 ></DL
3453 ></DIV
3454 ></DIV
3455 ><DIV
3456 CLASS="SECT3"
3457 ><H4
3458 CLASS="SECT3"
3459 ><A
3460 NAME="FILTER"
3461 >8.5.15. filter</A
3462 ></H4
3463 ><P
3464 ></P
3465 ><DIV
3466 CLASS="VARIABLELIST"
3467 ><DL
3468 ><DT
3469 >Typical use:</DT
3470 ><DD
3471 ><P
3472 >Get rid of HTML and JavaScript annoyances, banner advertisements (by size), 
3473          do fun text replacements, add personalized effects, etc.</P
3474 ></DD
3475 ><DT
3476 >Effect:</DT
3477 ><DD
3478 ><P
3479 >    All instances of text-based type, most notably HTML and JavaScript, to which
3480     this action applies, can be filtered on-the-fly through the specified regular
3481     expression based substitutions. (Note: as of version 3.0.3 plain text documents
3482     are exempted from filtering, because web servers often use the
3483    <TT
3484 CLASS="LITERAL"
3485 >text/plain</TT
3486 > MIME type for all files whose type they don't know.)
3487    </P
3488 ></DD
3489 ><DT
3490 >Type:</DT
3491 ><DD
3492 ><P
3493 >Parameterized.</P
3494 ></DD
3495 ><DT
3496 >Parameter:</DT
3497 ><DD
3498 ><P
3499 >    The name of a content filter, as defined in the <A
3500 HREF="filter-file.html"
3501 >filter file</A
3502 >.
3503     Filters can be defined in one or more  files as defined by the 
3504     <TT
3505 CLASS="LITERAL"
3506 ><A
3507 HREF="config.html#FILTERFILE"
3508 >filterfile</A
3509 ></TT
3510 >
3511     option in the <A
3512 HREF="config.html"
3513 >config file</A
3514 >. 
3515     <TT
3516 CLASS="FILENAME"
3517 >default.filter</TT
3518 > is the collection of filters 
3519     supplied by the developers. Locally defined filters should go 
3520     in their own file, such as <TT
3521 CLASS="FILENAME"
3522 >user.filter</TT
3523 >.
3524    </P
3525 ><P
3526 >     When used in its negative form,
3527      and without parameters, <SPAN
3528 CLASS="emphasis"
3529 ><I
3530 CLASS="EMPHASIS"
3531 >all</I
3532 ></SPAN
3533 > filtering is completely disabled.
3534   </P
3535 ></DD
3536 ><DT
3537 >Notes:</DT
3538 ><DD
3539 ><P
3540 >    For your convenience, there are a number of pre-defined filters available 
3541     in the distribution filter file that you can use. See the examples below for
3542     a list.
3543    </P
3544 ><P
3545 >    Filtering requires buffering the page content, which may appear to
3546     slow down page rendering since nothing is displayed until all content has
3547     passed the filters. (The total time until the page is completely rendered
3548     doesn't change much, but it may be perceived as slower since the page is
3549     not incrementally displayed.)
3550     This effect will be more noticeable on slower connections.
3551    </P
3552 ><P
3553 >   <SPAN
3554 CLASS="QUOTE"
3555 >"Rolling your own"</SPAN
3556 >
3557     filters requires a knowledge of 
3558      <A
3559 HREF="http://en.wikipedia.org/wiki/Regular_expressions"
3560 TARGET="_top"
3561 ><SPAN
3562 CLASS="QUOTE"
3563 >"Regular
3564      Expressions"</SPAN
3565 ></A
3566 > and 
3567       <A
3568 HREF="http://en.wikipedia.org/wiki/Html"
3569 TARGET="_top"
3570 ><SPAN
3571 CLASS="QUOTE"
3572 >"HTML"</SPAN
3573 ></A
3574 >.
3575     This is very powerful feature, and potentially very intrusive. 
3576     Filters should be used with caution, and where an equivalent
3577     <SPAN
3578 CLASS="QUOTE"
3579 >"action"</SPAN
3580 > is not available.
3581    </P
3582 ><P
3583 >    The amount of data that can be filtered is limited to the 
3584     <TT
3585 CLASS="LITERAL"
3586 ><A
3587 HREF="config.html#BUFFER-LIMIT"
3588 >buffer-limit</A
3589 ></TT
3590 >
3591     option in the main <A
3592 HREF="config.html"
3593 >config file</A
3594 >. The 
3595     default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered
3596     data, and all pending data, is passed through unfiltered. 
3597    </P
3598 ><P
3599 >    Inappropriate MIME types, such as zipped files, are not filtered at all.
3600     (Again, only text-based types except plain text). Encrypted SSL data
3601     (from HTTPS servers) cannot be filtered either, since this would violate
3602     the integrity of the secure transaction. In some situations it might
3603     be necessary to protect certain text, like source code, from filtering
3604     by defining appropriate <TT
3605 CLASS="LITERAL"
3606 >-filter</TT
3607 > exceptions.
3608    </P
3609 ><P
3610 >    Compressed content can't be filtered either, unless <SPAN
3611 CLASS="APPLICATION"
3612 >Privoxy</SPAN
3613 >
3614     is compiled with zlib support (requires at least <SPAN
3615 CLASS="APPLICATION"
3616 >Privoxy</SPAN
3617 > 3.0.7),
3618     in which case <SPAN
3619 CLASS="APPLICATION"
3620 >Privoxy</SPAN
3621 > will decompress the content before filtering
3622     it.
3623    </P
3624 ><P
3625 >    If you use a <SPAN
3626 CLASS="APPLICATION"
3627 >Privoxy</SPAN
3628 > version without zlib support, but want filtering to work on
3629     as much documents as possible, even those that would normally be sent compressed,
3630     you must use the <TT
3631 CLASS="LITERAL"
3632 ><A
3633 HREF="actions-file.html#PREVENT-COMPRESSION"
3634 >prevent-compression</A
3635 ></TT
3636 >
3637     action in conjunction with <TT
3638 CLASS="LITERAL"
3639 >filter</TT
3640 >.
3641    </P
3642 ><P
3643 >    Content filtering can achieve some of the same effects as the 
3644     <TT
3645 CLASS="LITERAL"
3646 ><A
3647 HREF="actions-file.html#BLOCK"
3648 >block</A
3649 ></TT
3650 >
3651     action, i.e. it can be used to block ads and banners. But the mechanism 
3652     works quite differently. One effective use, is to block ad banners 
3653     based on their size (see below), since many of these seem to be somewhat 
3654     standardized.
3655    </P
3656 ><P
3657 >    <A
3658 HREF="contact.html"
3659 >Feedback</A
3660 > with suggestions for new or
3661     improved filters is particularly welcome!
3662    </P
3663 ><P
3664 >    The below list has only the names and a one-line description of each
3665     predefined filter. There are <A
3666 HREF="filter-file.html#PREDEFINED-FILTERS"
3667 >more
3668     verbose explanations</A
3669 > of what these filters do in the <A
3670 HREF="filter-file.html"
3671 >filter file chapter</A
3672 >.
3673    </P
3674 ></DD
3675 ><DT
3676 >Example usage (with filters from the distribution <TT
3677 CLASS="FILENAME"
3678 >default.filter</TT
3679 > file).
3680   See <A
3681 HREF="filter-file.html#PREDEFINED-FILTERS"
3682 >the Predefined Filters section</A
3683 > for 
3684   more explanation on each:</DT
3685 ><DD
3686 ><P
3687 >    <A
3688 NAME="FILTER-JS-ANNOYANCES"
3689 ></A
3690 >
3691     <TABLE
3692 BORDER="0"
3693 BGCOLOR="#E0E0E0"
3694 WIDTH="90%"
3695 ><TR
3696 ><TD
3697 ><PRE
3698 CLASS="SCREEN"
3699 >+filter{js-annoyances}       # Get rid of particularly annoying JavaScript abuse.</PRE
3700 ></TD
3701 ></TR
3702 ></TABLE
3703 >
3704    </P
3705 ><P
3706 >    <A
3707 NAME="FILTER-JS-EVENTS"
3708 ></A
3709 >
3710     <TABLE
3711 BORDER="0"
3712 BGCOLOR="#E0E0E0"
3713 WIDTH="90%"
3714 ><TR
3715 ><TD
3716 ><PRE
3717 CLASS="SCREEN"
3718 >+filter{js-events}           # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).</PRE
3719 ></TD
3720 ></TR
3721 ></TABLE
3722 >
3723    </P
3724 ><P
3725 >    <A
3726 NAME="FILTER-HTML-ANNOYANCES"
3727 ></A
3728 >
3729     <TABLE
3730 BORDER="0"
3731 BGCOLOR="#E0E0E0"
3732 WIDTH="90%"
3733 ><TR
3734 ><TD
3735 ><PRE
3736 CLASS="SCREEN"
3737 >+filter{html-annoyances}     # Get rid of particularly annoying HTML abuse.</PRE
3738 ></TD
3739 ></TR
3740 ></TABLE
3741 >
3742    </P
3743 ><P
3744 >    <A
3745 NAME="FILTER-CONTENT-COOKIES"
3746 ></A
3747 >
3748     <TABLE
3749 BORDER="0"
3750 BGCOLOR="#E0E0E0"
3751 WIDTH="90%"
3752 ><TR
3753 ><TD
3754 ><PRE
3755 CLASS="SCREEN"
3756 >+filter{content-cookies}     # Kill cookies that come in the HTML or JS content.</PRE
3757 ></TD
3758 ></TR
3759 ></TABLE
3760 >
3761    </P
3762 ><P
3763 >    <A
3764 NAME="FILTER-REFRESH-TAGS"
3765 ></A
3766 >
3767     <TABLE
3768 BORDER="0"
3769 BGCOLOR="#E0E0E0"
3770 WIDTH="90%"
3771 ><TR
3772 ><TD
3773 ><PRE
3774 CLASS="SCREEN"
3775 >+filter{refresh-tags}        # Kill automatic refresh tags (for dial-on-demand setups).</PRE
3776 ></TD
3777 ></TR
3778 ></TABLE
3779 >
3780    </P
3781 ><P
3782 >    <A
3783 NAME="FILTER-UNSOLICITED-POPUPS"
3784 ></A
3785 >
3786     <TABLE
3787 BORDER="0"
3788 BGCOLOR="#E0E0E0"
3789 WIDTH="90%"
3790 ><TR
3791 ><TD
3792 ><PRE
3793 CLASS="SCREEN"
3794 >+filter{unsolicited-popups}  # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.</PRE
3795 ></TD
3796 ></TR
3797 ></TABLE
3798 >
3799    </P
3800 ><P
3801 >    <A
3802 NAME="FILTER-ALL-POPUPS"
3803 ></A
3804 >
3805     <TABLE
3806 BORDER="0"
3807 BGCOLOR="#E0E0E0"
3808 WIDTH="90%"
3809 ><TR
3810 ><TD
3811 ><PRE
3812 CLASS="SCREEN"
3813 >+filter{all-popups}          # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.</PRE
3814 ></TD
3815 ></TR
3816 ></TABLE
3817 >
3818    </P
3819 ><P
3820 >    <A
3821 NAME="FILTER-IMG-REORDER"
3822 ></A
3823 >
3824     <TABLE
3825 BORDER="0"
3826 BGCOLOR="#E0E0E0"
3827 WIDTH="90%"
3828 ><TR
3829 ><TD
3830 ><PRE
3831 CLASS="SCREEN"
3832 >+filter{img-reorder}         # Reorder attributes in &#60;img&#62; tags to make the banners-by-* filters more effective.</PRE
3833 ></TD
3834 ></TR
3835 ></TABLE
3836 >
3837    </P
3838 ><P
3839 >    <A
3840 NAME="FILTER-BANNERS-BY-SIZE"
3841 ></A
3842 >
3843     <TABLE
3844 BORDER="0"
3845 BGCOLOR="#E0E0E0"
3846 WIDTH="90%"
3847 ><TR
3848 ><TD
3849 ><PRE