Rebuilt with p-status stable. D'oh.
[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.16 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.16 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="AEN2487"
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="AEN2586"
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="AEN2593"
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 >:8000/</TT
868 ></DT
869 ><DD
870 ><P
871 >    Matches any URL pointing to TCP port 8000.
872    </P
873 ></DD
874 ><DT
875 ><TT
876 CLASS="LITERAL"
877 >&#60;2001:db8::1&#62;/</TT
878 ></DT
879 ><DD
880 ><P
881 >    Matches any URL with the host address <TT
882 CLASS="LITERAL"
883 >2001:db8::1</TT
884 >.
885     (Note that the real URL uses plain brackets, not angle brackets.)
886    </P
887 ></DD
888 ><DT
889 ><TT
890 CLASS="LITERAL"
891 >index.html</TT
892 ></DT
893 ><DD
894 ><P
895 >    matches nothing, since it would be interpreted as a domain name and
896     there is no top-level domain called <TT
897 CLASS="LITERAL"
898 >.html</TT
899 >. So its 
900     a mistake.
901    </P
902 ></DD
903 ></DL
904 ></DIV
905 ><DIV
906 CLASS="SECT3"
907 ><H3
908 CLASS="SECT3"
909 ><A
910 NAME="AEN2700"
911 >8.4.1. The Domain Pattern</A
912 ></H3
913 ><P
914 > The matching of the domain part offers some flexible options: if the
915  domain starts or ends with a dot, it becomes unanchored at that end. 
916  For example:</P
917 ><P
918 ></P
919 ><DIV
920 CLASS="VARIABLELIST"
921 ><DL
922 ><DT
923 ><TT
924 CLASS="LITERAL"
925 >.example.com</TT
926 ></DT
927 ><DD
928 ><P
929 >    matches any domain with first-level domain <TT
930 CLASS="LITERAL"
931 >com</TT
932 >
933     and second-level domain <TT
934 CLASS="LITERAL"
935 >example</TT
936 >.
937     For example <TT
938 CLASS="LITERAL"
939 >www.example.com</TT
940 >,
941     <TT
942 CLASS="LITERAL"
943 >example.com</TT
944 > and <TT
945 CLASS="LITERAL"
946 >foo.bar.baz.example.com</TT
947 >.
948     Note that it wouldn't match if the second-level domain was <TT
949 CLASS="LITERAL"
950 >another-example</TT
951 >.
952    </P
953 ></DD
954 ><DT
955 ><TT
956 CLASS="LITERAL"
957 >www.</TT
958 ></DT
959 ><DD
960 ><P
961 >    matches any domain that <SPAN
962 CLASS="emphasis"
963 ><I
964 CLASS="EMPHASIS"
965 >STARTS</I
966 ></SPAN
967 > with
968     <TT
969 CLASS="LITERAL"
970 >www.</TT
971 > (It also matches the domain
972     <TT
973 CLASS="LITERAL"
974 >www</TT
975 > but most of the time that doesn't matter.)
976    </P
977 ></DD
978 ><DT
979 ><TT
980 CLASS="LITERAL"
981 >.example.</TT
982 ></DT
983 ><DD
984 ><P
985 >    matches any domain that <SPAN
986 CLASS="emphasis"
987 ><I
988 CLASS="EMPHASIS"
989 >CONTAINS</I
990 ></SPAN
991 > <TT
992 CLASS="LITERAL"
993 >.example.</TT
994 >.
995     And, by the way, also included would be any files or documents that exist
996     within that domain since no path limitations are specified. (Correctly
997     speaking: It matches any FQDN that contains <TT
998 CLASS="LITERAL"
999 >example</TT
1000 > as
1001     a domain.) This might be <TT
1002 CLASS="LITERAL"
1003 >www.example.com</TT
1004 >,
1005     <TT
1006 CLASS="LITERAL"
1007 >news.example.de</TT
1008 >, or
1009     <TT
1010 CLASS="LITERAL"
1011 >www.example.net/cgi/testing.pl</TT
1012 > for instance. All these
1013     cases are matched. 
1014    </P
1015 ></DD
1016 ></DL
1017 ></DIV
1018 ><P
1019 > Additionally, there are wild-cards that you can use in the domain names
1020  themselves. These work similarly to shell globbing type wild-cards:
1021  <SPAN
1022 CLASS="QUOTE"
1023 >"*"</SPAN
1024 > represents zero or more arbitrary characters (this is
1025  equivalent to the 
1026  <A
1027 HREF="http://en.wikipedia.org/wiki/Regular_expressions"
1028 TARGET="_top"
1029 ><SPAN
1030 CLASS="QUOTE"
1031 >"Regular
1032  Expression"</SPAN
1033 ></A
1034 > based syntax of <SPAN
1035 CLASS="QUOTE"
1036 >".*"</SPAN
1037 >),
1038  <SPAN
1039 CLASS="QUOTE"
1040 >"?"</SPAN
1041 >  represents any single character (this is equivalent to the
1042  regular expression syntax of a simple <SPAN
1043 CLASS="QUOTE"
1044 >"."</SPAN
1045 >), and you can define
1046  <SPAN
1047 CLASS="QUOTE"
1048 >"character classes"</SPAN
1049 > in square brackets which is similar to 
1050  the same regular expression technique. All of this can be freely mixed:</P
1051 ><P
1052 ></P
1053 ><DIV
1054 CLASS="VARIABLELIST"
1055 ><DL
1056 ><DT
1057 ><TT
1058 CLASS="LITERAL"
1059 >ad*.example.com</TT
1060 ></DT
1061 ><DD
1062 ><P
1063 >    matches <SPAN
1064 CLASS="QUOTE"
1065 >"adserver.example.com"</SPAN
1066 >, 
1067     <SPAN
1068 CLASS="QUOTE"
1069 >"ads.example.com"</SPAN
1070 >, etc but not <SPAN
1071 CLASS="QUOTE"
1072 >"sfads.example.com"</SPAN
1073 >
1074    </P
1075 ></DD
1076 ><DT
1077 ><TT
1078 CLASS="LITERAL"
1079 >*ad*.example.com</TT
1080 ></DT
1081 ><DD
1082 ><P
1083 >    matches all of the above, and then some.
1084    </P
1085 ></DD
1086 ><DT
1087 ><TT
1088 CLASS="LITERAL"
1089 >.?pix.com</TT
1090 ></DT
1091 ><DD
1092 ><P
1093 >    matches <TT
1094 CLASS="LITERAL"
1095 >www.ipix.com</TT
1096 >,
1097     <TT
1098 CLASS="LITERAL"
1099 >pictures.epix.com</TT
1100 >, <TT
1101 CLASS="LITERAL"
1102 >a.b.c.d.e.upix.com</TT
1103 > etc. 
1104    </P
1105 ></DD
1106 ><DT
1107 ><TT
1108 CLASS="LITERAL"
1109 >www[1-9a-ez].example.c*</TT
1110 ></DT
1111 ><DD
1112 ><P
1113 >     matches <TT
1114 CLASS="LITERAL"
1115 >www1.example.com</TT
1116 >, 
1117      <TT
1118 CLASS="LITERAL"
1119 >www4.example.cc</TT
1120 >, <TT
1121 CLASS="LITERAL"
1122 >wwwd.example.cy</TT
1123 >, 
1124      <TT
1125 CLASS="LITERAL"
1126 >wwwz.example.com</TT
1127 > etc., but <SPAN
1128 CLASS="emphasis"
1129 ><I
1130 CLASS="EMPHASIS"
1131 >not</I
1132 ></SPAN
1133
1134      <TT
1135 CLASS="LITERAL"
1136 >wwww.example.com</TT
1137 >.
1138    </P
1139 ></DD
1140 ></DL
1141 ></DIV
1142 ><P
1143 > While flexible, this is not the sophistication of full regular expression based syntax.</P
1144 ></DIV
1145 ><DIV
1146 CLASS="SECT3"
1147 ><H3
1148 CLASS="SECT3"
1149 ><A
1150 NAME="AEN2776"
1151 >8.4.2. The Path Pattern</A
1152 ></H3
1153 ><P
1154 > <SPAN
1155 CLASS="APPLICATION"
1156 >Privoxy</SPAN
1157 > uses <SPAN
1158 CLASS="QUOTE"
1159 >"modern"</SPAN
1160 > POSIX 1003.2
1161   <A
1162 HREF="http://en.wikipedia.org/wiki/Regular_expressions"
1163 TARGET="_top"
1164 ><SPAN
1165 CLASS="QUOTE"
1166 >"Regular
1167   Expressions"</SPAN
1168 ></A
1169 > for matching the path portion (after the slash),
1170   and is thus more flexible.</P
1171 ><P
1172 > There is an <A
1173 HREF="appendix.html#REGEX"
1174 >Appendix</A
1175 > with a brief quick-start into regular
1176  expressions, you also might want to have a look at your operating system's documentation
1177  on regular expressions (try <TT
1178 CLASS="LITERAL"
1179 >man re_format</TT
1180 >).</P
1181 ><P
1182 > Note that the path pattern is automatically left-anchored at the <SPAN
1183 CLASS="QUOTE"
1184 >"/"</SPAN
1185 >,
1186  i.e. it matches as if it would start with a <SPAN
1187 CLASS="QUOTE"
1188 >"^"</SPAN
1189 > (regular expression speak 
1190  for the beginning of a line).</P
1191 ><P
1192 > Please also note that matching in the path is <SPAN
1193 CLASS="emphasis"
1194 ><I
1195 CLASS="EMPHASIS"
1196 >CASE INSENSITIVE</I
1197 ></SPAN
1198 >
1199  by default, but you can switch to case sensitive at any point in the pattern by using the 
1200  <SPAN
1201 CLASS="QUOTE"
1202 >"(?-i)"</SPAN
1203 > switch: <TT
1204 CLASS="LITERAL"
1205 >www.example.com/(?-i)PaTtErN.*</TT
1206 > will match
1207  only documents whose path starts with <TT
1208 CLASS="LITERAL"
1209 >PaTtErN</TT
1210 > in
1211  <SPAN
1212 CLASS="emphasis"
1213 ><I
1214 CLASS="EMPHASIS"
1215 >exactly</I
1216 ></SPAN
1217 > this capitalization.</P
1218 ><P
1219 ></P
1220 ><DIV
1221 CLASS="VARIABLELIST"
1222 ><DL
1223 ><DT
1224 ><TT
1225 CLASS="LITERAL"
1226 >.example.com/.*</TT
1227 ></DT
1228 ><DD
1229 ><P
1230 >     Is equivalent to just <SPAN
1231 CLASS="QUOTE"
1232 >".example.com"</SPAN
1233 >, since any documents 
1234      within that domain are matched with or without the <SPAN
1235 CLASS="QUOTE"
1236 >".*"</SPAN
1237 >
1238      regular expression. This is redundant
1239    </P
1240 ></DD
1241 ><DT
1242 ><TT
1243 CLASS="LITERAL"
1244 >.example.com/.*/index.html$</TT
1245 ></DT
1246 ><DD
1247 ><P
1248 >    Will match any page in the domain of <SPAN
1249 CLASS="QUOTE"
1250 >"example.com"</SPAN
1251 > that is
1252     named <SPAN
1253 CLASS="QUOTE"
1254 >"index.html"</SPAN
1255 >, and that is part of some path. For
1256     example, it matches <SPAN
1257 CLASS="QUOTE"
1258 >"www.example.com/testing/index.html"</SPAN
1259 > but
1260     NOT <SPAN
1261 CLASS="QUOTE"
1262 >"www.example.com/index.html"</SPAN
1263 > because the regular
1264     expression called for at least two <SPAN
1265 CLASS="QUOTE"
1266 >"/'s"</SPAN
1267 >, thus the path 
1268     requirement. It also would match 
1269     <SPAN
1270 CLASS="QUOTE"
1271 >"www.example.com/testing/index_html"</SPAN
1272 >, because of the 
1273     special meta-character <SPAN
1274 CLASS="QUOTE"
1275 >"."</SPAN
1276 >.
1277    </P
1278 ></DD
1279 ><DT
1280 ><TT
1281 CLASS="LITERAL"
1282 >.example.com/(.*/)?index\.html$</TT
1283 ></DT
1284 ><DD
1285 ><P
1286 >    This regular expression is conditional so it will match any page 
1287     named <SPAN
1288 CLASS="QUOTE"
1289 >"index.html"</SPAN
1290 > regardless of path which in this case can 
1291     have one or more <SPAN
1292 CLASS="QUOTE"
1293 >"/'s"</SPAN
1294 >. And this one must contain exactly 
1295     <SPAN
1296 CLASS="QUOTE"
1297 >".html"</SPAN
1298 > (but does not have to end with that!).
1299    </P
1300 ></DD
1301 ><DT
1302 ><TT
1303 CLASS="LITERAL"
1304 >.example.com/(.*/)(ads|banners?|junk)</TT
1305 ></DT
1306 ><DD
1307 ><P
1308 >    This regular expression will match any path of <SPAN
1309 CLASS="QUOTE"
1310 >"example.com"</SPAN
1311 >
1312     that contains any of the words <SPAN
1313 CLASS="QUOTE"
1314 >"ads"</SPAN
1315 >, <SPAN
1316 CLASS="QUOTE"
1317 >"banner"</SPAN
1318 >, 
1319     <SPAN
1320 CLASS="QUOTE"
1321 >"banners"</SPAN
1322 > (because of the <SPAN
1323 CLASS="QUOTE"
1324 >"?"</SPAN
1325 >) or <SPAN
1326 CLASS="QUOTE"
1327 >"junk"</SPAN
1328 >.
1329     The path does not have to end in these words, just contain them.
1330    </P
1331 ></DD
1332 ><DT
1333 ><TT
1334 CLASS="LITERAL"
1335 >.example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$</TT
1336 ></DT
1337 ><DD
1338 ><P
1339 >    This is very much the same as above, except now it must end in either 
1340     <SPAN
1341 CLASS="QUOTE"
1342 >".jpg"</SPAN
1343 >, <SPAN
1344 CLASS="QUOTE"
1345 >".jpeg"</SPAN
1346 >, <SPAN
1347 CLASS="QUOTE"
1348 >".gif"</SPAN
1349 > or <SPAN
1350 CLASS="QUOTE"
1351 >".png"</SPAN
1352 >. So this 
1353     one is limited to common image formats.
1354    </P
1355 ></DD
1356 ></DL
1357 ></DIV
1358 ><P
1359 > There are many, many good examples to be found in <TT
1360 CLASS="FILENAME"
1361 >default.action</TT
1362 >, 
1363  and more tutorials below in <A
1364 HREF="appendix.html#REGEX"
1365 >Appendix on regular expressions</A
1366 >.</P
1367 ></DIV
1368 ><DIV
1369 CLASS="SECT3"
1370 ><H3
1371 CLASS="SECT3"
1372 ><A
1373 NAME="TAG-PATTERN"
1374 >8.4.3. The Tag Pattern</A
1375 ></H3
1376 ><P
1377 > Tag patterns are used to change the applying actions based on the
1378  request's tags. Tags can be created with either the
1379  <A
1380 HREF="actions-file.html#CLIENT-HEADER-TAGGER"
1381 >client-header-tagger</A
1382 >
1383  or the  <A
1384 HREF="actions-file.html#SERVER-HEADER-TAGGER"
1385 >server-header-tagger</A
1386 > action.</P
1387 ><P
1388 > Tag patterns have to start with <SPAN
1389 CLASS="QUOTE"
1390 >"TAG:"</SPAN
1391 >, so <SPAN
1392 CLASS="APPLICATION"
1393 >Privoxy</SPAN
1394 >
1395  can tell them apart from URL patterns. Everything after the colon
1396  including white space, is interpreted as a regular expression with
1397  path pattern syntax, except that tag patterns aren't left-anchored
1398  automatically (<SPAN
1399 CLASS="APPLICATION"
1400 >Privoxy</SPAN
1401 > doesn't silently add a <SPAN
1402 CLASS="QUOTE"
1403 >"^"</SPAN
1404 >,
1405  you have to do it yourself if you need it).</P
1406 ><P
1407 > To match all requests that are tagged with <SPAN
1408 CLASS="QUOTE"
1409 >"foo"</SPAN
1410 >
1411  your pattern line should be <SPAN
1412 CLASS="QUOTE"
1413 >"TAG:^foo$"</SPAN
1414 >,
1415  <SPAN
1416 CLASS="QUOTE"
1417 >"TAG:foo"</SPAN
1418 > would work as well, but it would also
1419  match requests whose tags contain <SPAN
1420 CLASS="QUOTE"
1421 >"foo"</SPAN
1422 > somewhere.
1423  <SPAN
1424 CLASS="QUOTE"
1425 >"TAG: foo"</SPAN
1426 > wouldn't work as it requires white space.</P
1427 ><P
1428 > Sections can contain URL and tag patterns at the same time,
1429  but tag patterns are checked after the URL patterns and thus
1430  always overrule them, even if they are located before the URL patterns.</P
1431 ><P
1432 > Once a new tag is added, Privoxy checks right away if it's matched by one
1433  of the tag patterns and updates the action settings accordingly. As a result
1434  tags can be used to activate other tagger actions, as long as these other
1435  taggers look for headers that haven't already be parsed.</P
1436 ><P
1437 > For example you could tag client requests which use the
1438  <TT
1439 CLASS="LITERAL"
1440 >POST</TT
1441 > method,
1442  then use this tag to activate another tagger that adds a tag if cookies
1443  are sent, and then use a block action based on the cookie tag. This allows
1444  the outcome of one action, to be input into a subsequent action. However if
1445  you'd reverse the position of the described taggers, and activated the
1446  method tagger based on the cookie tagger, no method tags would be created.
1447  The method tagger would look for the request line, but at the time
1448  the cookie tag is created, the request line has already been parsed.</P
1449 ><P
1450 > While this is a limitation you should be aware of, this kind of
1451  indirection is seldom needed anyway and even the example doesn't
1452  make too much sense.</P
1453 ></DIV
1454 ></DIV
1455 ><DIV
1456 CLASS="SECT2"
1457 ><H2
1458 CLASS="SECT2"
1459 ><A
1460 NAME="ACTIONS"
1461 >8.5. Actions</A
1462 ></H2
1463 ><P
1464 > All actions are disabled by default, until they are explicitly enabled
1465  somewhere in an actions file. Actions are turned on if preceded with a
1466  <SPAN
1467 CLASS="QUOTE"
1468 >"+"</SPAN
1469 >, and turned off if preceded with a <SPAN
1470 CLASS="QUOTE"
1471 >"-"</SPAN
1472 >. So a
1473  <TT
1474 CLASS="LITERAL"
1475 >+action</TT
1476 > means <SPAN
1477 CLASS="QUOTE"
1478 >"do that action"</SPAN
1479 >, e.g.
1480  <TT
1481 CLASS="LITERAL"
1482 >+block</TT
1483 > means <SPAN
1484 CLASS="QUOTE"
1485 >"please block URLs that match the
1486  following patterns"</SPAN
1487 >, and <TT
1488 CLASS="LITERAL"
1489 >-block</TT
1490 > means <SPAN
1491 CLASS="QUOTE"
1492 >"don't
1493  block URLs that match the following patterns, even if <TT
1494 CLASS="LITERAL"
1495 >+block</TT
1496 >
1497  previously applied."</SPAN
1498 >&#13;</P
1499 ><P
1500
1501  Again, actions are invoked by placing them on a line, enclosed in curly braces and
1502  separated by whitespace, like in 
1503  <TT
1504 CLASS="LITERAL"
1505 >{+some-action -some-other-action{some-parameter}}</TT
1506 >,
1507  followed by a list of URL patterns, one per line, to which they apply.
1508  Together, the actions line and the following pattern lines make up a section
1509  of the actions file. </P
1510 ><P
1511
1512  Actions fall into three categories:</P
1513 ><P
1514 > <P
1515 ></P
1516 ><UL
1517 ><LI
1518 ><P
1519 >  
1520    Boolean, i.e the action can only be <SPAN
1521 CLASS="QUOTE"
1522 >"enabled"</SPAN
1523 > or
1524    <SPAN
1525 CLASS="QUOTE"
1526 >"disabled"</SPAN
1527 >. Syntax:
1528   </P
1529 ><P
1530 >   <TABLE
1531 BORDER="0"
1532 BGCOLOR="#E0E0E0"
1533 WIDTH="90%"
1534 ><TR
1535 ><TD
1536 ><PRE
1537 CLASS="SCREEN"
1538 >  +<TT
1539 CLASS="REPLACEABLE"
1540 ><I
1541 >name</I
1542 ></TT
1543 >        # enable action <TT
1544 CLASS="REPLACEABLE"
1545 ><I
1546 >name</I
1547 ></TT
1548 >
1549   -<TT
1550 CLASS="REPLACEABLE"
1551 ><I
1552 >name</I
1553 ></TT
1554 >        # disable action <TT
1555 CLASS="REPLACEABLE"
1556 ><I
1557 >name</I
1558 ></TT
1559 ></PRE
1560 ></TD
1561 ></TR
1562 ></TABLE
1563 >
1564   </P
1565 ><P
1566 >  
1567    Example: <TT
1568 CLASS="LITERAL"
1569 >+handle-as-image</TT
1570 >
1571   </P
1572 ></LI
1573 ><LI
1574 ><P
1575 >  
1576    Parameterized, where some value is required in order to enable this type of action.
1577    Syntax:
1578   </P
1579 ><P
1580 >   <TABLE
1581 BORDER="0"
1582 BGCOLOR="#E0E0E0"
1583 WIDTH="90%"
1584 ><TR
1585 ><TD
1586 ><PRE
1587 CLASS="SCREEN"
1588 >  +<TT
1589 CLASS="REPLACEABLE"
1590 ><I
1591 >name</I
1592 ></TT
1593 >{<TT
1594 CLASS="REPLACEABLE"
1595 ><I
1596 >param</I
1597 ></TT
1598 >}  # enable action and set parameter to <TT
1599 CLASS="REPLACEABLE"
1600 ><I
1601 >param</I
1602 ></TT
1603 >,
1604                # overwriting parameter from previous match if necessary
1605   -<TT
1606 CLASS="REPLACEABLE"
1607 ><I
1608 >name</I
1609 ></TT
1610 >         # disable action. The parameter can be omitted</PRE
1611 ></TD
1612 ></TR
1613 ></TABLE
1614 >
1615   </P
1616 ><P
1617 >   Note that if the URL matches multiple positive forms of a parameterized action,
1618    the last match wins, i.e. the params from earlier matches are simply ignored.
1619   </P
1620 ><P
1621 >  
1622    Example: <TT
1623 CLASS="LITERAL"
1624 >+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
1625 >
1626   </P
1627 ></LI
1628 ><LI
1629 ><P
1630 >  
1631    Multi-value. These look exactly like parameterized actions,
1632    but they behave differently: If the action applies multiple times to the
1633    same URL, but with different parameters, <SPAN
1634 CLASS="emphasis"
1635 ><I
1636 CLASS="EMPHASIS"
1637 >all</I
1638 ></SPAN
1639 > the parameters
1640    from <SPAN
1641 CLASS="emphasis"
1642 ><I
1643 CLASS="EMPHASIS"
1644 >all</I
1645 ></SPAN
1646 > matches are remembered. This is used for actions
1647    that can be executed for the same request repeatedly, like adding multiple
1648    headers, or filtering through multiple filters. Syntax:
1649   </P
1650 ><P
1651 >   <TABLE
1652 BORDER="0"
1653 BGCOLOR="#E0E0E0"
1654 WIDTH="90%"
1655 ><TR
1656 ><TD
1657 ><PRE
1658 CLASS="SCREEN"
1659 >  +<TT
1660 CLASS="REPLACEABLE"
1661 ><I
1662 >name</I
1663 ></TT
1664 >{<TT
1665 CLASS="REPLACEABLE"
1666 ><I
1667 >param</I
1668 ></TT
1669 >}   # enable action and add <TT
1670 CLASS="REPLACEABLE"
1671 ><I
1672 >param</I
1673 ></TT
1674 > to the list of parameters
1675   -<TT
1676 CLASS="REPLACEABLE"
1677 ><I
1678 >name</I
1679 ></TT
1680 >{<TT
1681 CLASS="REPLACEABLE"
1682 ><I
1683 >param</I
1684 ></TT
1685 >}   # remove the parameter <TT
1686 CLASS="REPLACEABLE"
1687 ><I
1688 >param</I
1689 ></TT
1690 > from the list of parameters
1691                 # If it was the last one left, disable the action.
1692   <TT
1693 CLASS="REPLACEABLE"
1694 ><I
1695 >-name</I
1696 ></TT
1697 >          # disable this action completely and remove all parameters from the list</PRE
1698 ></TD
1699 ></TR
1700 ></TABLE
1701 >
1702   </P
1703 ><P
1704 >  
1705    Examples: <TT
1706 CLASS="LITERAL"
1707 >+add-header{X-Fun-Header: Some text}</TT
1708 > and
1709    <TT
1710 CLASS="LITERAL"
1711 >+filter{html-annoyances}</TT
1712 >
1713   </P
1714 ></LI
1715 ></UL
1716 ></P
1717 ><P
1718 > If nothing is specified in any actions file, no <SPAN
1719 CLASS="QUOTE"
1720 >"actions"</SPAN
1721 > are
1722  taken. So in this case <SPAN
1723 CLASS="APPLICATION"
1724 >Privoxy</SPAN
1725 > would just be a
1726  normal, non-blocking, non-filtering proxy. You must specifically enable the
1727  privacy and blocking features you need (although the provided default actions
1728  files will give a good starting point).</P
1729 ><P
1730 > Later defined action sections always over-ride earlier ones of the same type.
1731  So exceptions to any rules you make, should come in the latter part of the file (or 
1732  in a file that is processed later when using multiple actions files such 
1733  as <TT
1734 CLASS="FILENAME"
1735 >user.action</TT
1736 >). For multi-valued actions, the actions
1737  are applied in the order they are specified. Actions files are processed in
1738  the order they are defined in <TT
1739 CLASS="FILENAME"
1740 >config</TT
1741 > (the default
1742  installation has three actions files). It also quite possible for any given
1743  URL to match more than one <SPAN
1744 CLASS="QUOTE"
1745 >"pattern"</SPAN
1746 > (because of wildcards and
1747  regular expressions), and thus to trigger more than one set of actions! Last
1748  match wins.</P
1749 ><P
1750 > The list of valid <SPAN
1751 CLASS="APPLICATION"
1752 >Privoxy</SPAN
1753 > actions are:</P
1754 ><DIV
1755 CLASS="SECT3"
1756 ><H4
1757 CLASS="SECT3"
1758 ><A
1759 NAME="ADD-HEADER"
1760 >8.5.1. add-header</A
1761 ></H4
1762 ><P
1763 ></P
1764 ><DIV
1765 CLASS="VARIABLELIST"
1766 ><DL
1767 ><DT
1768 >Typical use:</DT
1769 ><DD
1770 ><P
1771 >Confuse log analysis, custom applications</P
1772 ></DD
1773 ><DT
1774 >Effect:</DT
1775 ><DD
1776 ><P
1777 >    Sends a user defined HTTP header to the web server.
1778    </P
1779 ></DD
1780 ><DT
1781 >Type:</DT
1782 ><DD
1783 ><P
1784 >Multi-value.</P
1785 ></DD
1786 ><DT
1787 >Parameter:</DT
1788 ><DD
1789 ><P
1790 >    Any string value is possible. Validity of the defined HTTP headers is not checked.
1791     It is recommended that you use the <SPAN
1792 CLASS="QUOTE"
1793 >"<TT
1794 CLASS="LITERAL"
1795 >X-</TT
1796 >"</SPAN
1797 > prefix
1798     for custom headers.
1799    </P
1800 ></DD
1801 ><DT
1802 >Notes:</DT
1803 ><DD
1804 ><P
1805 >    This action may be specified multiple times, in order to define multiple 
1806     headers. This is rarely needed for the typical user. If you don't know what 
1807     <SPAN
1808 CLASS="QUOTE"
1809 >"HTTP headers"</SPAN
1810 > are, you definitely don't need to worry about this 
1811     one.
1812    </P
1813 ><P
1814 >    Headers added by this action are not modified by other actions.
1815    </P
1816 ></DD
1817 ><DT
1818 >Example usage:</DT
1819 ><DD
1820 ><P
1821 >     <TABLE
1822 BORDER="0"
1823 BGCOLOR="#E0E0E0"
1824 WIDTH="90%"
1825 ><TR
1826 ><TD
1827 ><PRE
1828 CLASS="SCREEN"
1829 >+add-header{X-User-Tracking: sucks}</PRE
1830 ></TD
1831 ></TR
1832 ></TABLE
1833 >
1834    </P
1835 ></DD
1836 ></DL
1837 ></DIV
1838 ></DIV
1839 ><DIV
1840 CLASS="SECT3"
1841 ><H4
1842 CLASS="SECT3"
1843 ><A
1844 NAME="BLOCK"
1845 >8.5.2. block</A
1846 ></H4
1847 ><P
1848 ></P
1849 ><DIV
1850 CLASS="VARIABLELIST"
1851 ><DL
1852 ><DT
1853 >Typical use:</DT
1854 ><DD
1855 ><P
1856 >Block ads or other unwanted content</P
1857 ></DD
1858 ><DT
1859 >Effect:</DT
1860 ><DD
1861 ><P
1862 >    Requests for URLs to which this action applies are blocked, i.e. the
1863     requests are trapped by <SPAN
1864 CLASS="APPLICATION"
1865 >Privoxy</SPAN
1866 > and the requested URL is never retrieved,
1867     but is answered locally with a substitute page or image, as determined by
1868     the <TT
1869 CLASS="LITERAL"
1870 ><A
1871 HREF="actions-file.html#HANDLE-AS-IMAGE"
1872 >handle-as-image</A
1873 ></TT
1874 >,
1875     <TT
1876 CLASS="LITERAL"
1877 ><A
1878 HREF="actions-file.html#SET-IMAGE-BLOCKER"
1879 >set-image-blocker</A
1880 ></TT
1881 >, and 
1882     <TT
1883 CLASS="LITERAL"
1884 ><A
1885 HREF="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT"
1886 >handle-as-empty-document</A
1887 ></TT
1888 > actions.
1889     
1890    </P
1891 ></DD
1892 ><DT
1893 >Type:</DT
1894 ><DD
1895 ><P
1896 >Parameterized.</P
1897 ></DD
1898 ><DT
1899 >Parameter:</DT
1900 ><DD
1901 ><P
1902 >A block reason that should be given to the user.</P
1903 ></DD
1904 ><DT
1905 >Notes:</DT
1906 ><DD
1907 ><P
1908 >    <SPAN
1909 CLASS="APPLICATION"
1910 >Privoxy</SPAN
1911 > sends a special <SPAN
1912 CLASS="QUOTE"
1913 >"BLOCKED"</SPAN
1914 > page
1915     for requests to blocked pages. This page contains the block reason given as
1916     parameter, a link to find out why the block action applies, and a click-through
1917     to the blocked content (the latter only if the force feature is available and
1918     enabled).
1919    </P
1920 ><P
1921
1922     A very important exception occurs if <SPAN
1923 CLASS="emphasis"
1924 ><I
1925 CLASS="EMPHASIS"
1926 >both</I
1927 ></SPAN
1928
1929     <TT
1930 CLASS="LITERAL"
1931 >block</TT
1932 > and <TT
1933 CLASS="LITERAL"
1934 ><A
1935 HREF="actions-file.html#HANDLE-AS-IMAGE"
1936 >handle-as-image</A
1937 ></TT
1938 >,
1939     apply to the same request: it will then be replaced by an image. If 
1940     <TT
1941 CLASS="LITERAL"
1942 ><A
1943 HREF="actions-file.html#SET-IMAGE-BLOCKER"
1944 >set-image-blocker</A
1945 ></TT
1946 >
1947     (see below) also applies, the type of image will be determined by its parameter,
1948     if not, the standard checkerboard pattern is sent.
1949    </P
1950 ><P
1951 >    It is important to understand this process, in order 
1952     to understand how <SPAN
1953 CLASS="APPLICATION"
1954 >Privoxy</SPAN
1955 > deals with 
1956     ads and other unwanted content. Blocking is a core feature, and one 
1957     upon which various other features depend.
1958    </P
1959 ><P
1960 >    The <TT
1961 CLASS="LITERAL"
1962 ><A
1963 HREF="actions-file.html#FILTER"
1964 >filter</A
1965 ></TT
1966 >
1967     action can perform a very similar task, by <SPAN
1968 CLASS="QUOTE"
1969 >"blocking"</SPAN
1970 >
1971     banner images and other content through rewriting the relevant URLs in the
1972     document's HTML source, so they don't get requested in the first place.
1973     Note that this is a totally different technique, and it's easy to confuse the two.
1974    </P
1975 ></DD
1976 ><DT
1977 >Example usage (section):</DT
1978 ><DD
1979 ><P
1980 >     <TABLE
1981 BORDER="0"
1982 BGCOLOR="#E0E0E0"
1983 WIDTH="90%"
1984 ><TR
1985 ><TD
1986 ><PRE
1987 CLASS="SCREEN"
1988 >{+block{No nasty stuff for you.}}
1989 # Block and replace with "blocked" page
1990  .nasty-stuff.example.com
1991
1992 {+block{Doubleclick banners.} +handle-as-image} 
1993 # Block and replace with image
1994  .ad.doubleclick.net
1995  .ads.r.us/banners/
1996
1997 {+block{Layered ads.} +handle-as-empty-document} 
1998 # Block and then ignore
1999  adserver.example.net/.*\.js$</PRE
2000 ></TD
2001 ></TR
2002 ></TABLE
2003 >
2004     </P
2005 ></DD
2006 ></DL
2007 ></DIV
2008 ></DIV
2009 ><DIV
2010 CLASS="SECT3"
2011 ><H4
2012 CLASS="SECT3"
2013 ><A
2014 NAME="CHANGE-X-FORWARDED-FOR"
2015 >8.5.3. change-x-forwarded-for</A
2016 ></H4
2017 ><P
2018 ></P
2019 ><DIV
2020 CLASS="VARIABLELIST"
2021 ><DL
2022 ><DT
2023 >Typical use:</DT
2024 ><DD
2025 ><P
2026 >Improve privacy by not forwarding the source of the request in the HTTP headers.</P
2027 ></DD
2028 ><DT
2029 >Effect:</DT
2030 ><DD
2031 ><P
2032 >    Deletes the <SPAN
2033 CLASS="QUOTE"
2034 >"X-Forwarded-For:"</SPAN
2035 > HTTP header from the client request,
2036     or adds a new one.
2037    </P
2038 ></DD
2039 ><DT
2040 >Type:</DT
2041 ><DD
2042 ><P
2043 >Parameterized.</P
2044 ></DD
2045 ><DT
2046 >Parameter:</DT
2047 ><DD
2048 ><P
2049 ></P
2050 ><UL
2051 ><LI
2052 ><P
2053 ><SPAN
2054 CLASS="QUOTE"
2055 >"block"</SPAN
2056 > to delete the header.</P
2057 ></LI
2058 ><LI
2059 ><P
2060 >       <SPAN
2061 CLASS="QUOTE"
2062 >"add"</SPAN
2063 > to create the header (or append
2064        the client's IP address to an already existing one).
2065      </P
2066 ></LI
2067 ></UL
2068 ></DD
2069 ><DT
2070 >Notes:</DT
2071 ><DD
2072 ><P
2073 >    It is safe and recommended to use <TT
2074 CLASS="LITERAL"
2075 >block</TT
2076 >.
2077    </P
2078 ><P
2079 >    Forwarding the source address of the request may make
2080     sense in some multi-user setups but is also a privacy risk.
2081    </P
2082 ></DD
2083 ><DT
2084 >Example usage:</DT
2085 ><DD
2086 ><P
2087 >     <TABLE
2088 BORDER="0"
2089 BGCOLOR="#E0E0E0"
2090 WIDTH="90%"
2091 ><TR
2092 ><TD
2093 ><PRE
2094 CLASS="SCREEN"
2095 >+change-x-forwarded-for{block}</PRE
2096 ></TD
2097 ></TR
2098 ></TABLE
2099 >
2100    </P
2101 ></DD
2102 ></DL
2103 ></DIV
2104 ></DIV
2105 ><DIV
2106 CLASS="SECT3"
2107 ><H4
2108 CLASS="SECT3"
2109 ><A
2110 NAME="CLIENT-HEADER-FILTER"
2111 >8.5.4. client-header-filter</A
2112 ></H4
2113 ><P
2114 ></P
2115 ><DIV
2116 CLASS="VARIABLELIST"
2117 ><DL
2118 ><DT
2119 >Typical use:</DT
2120 ><DD
2121 ><P
2122 >   Rewrite or remove single client headers.
2123    </P
2124 ></DD
2125 ><DT
2126 >Effect:</DT
2127 ><DD
2128 ><P
2129 >    All client headers to which this action applies are filtered on-the-fly through
2130     the specified regular expression based substitutions.
2131    </P
2132 ></DD
2133 ><DT
2134 >Type:</DT
2135 ><DD
2136 ><P
2137 >Parameterized.</P
2138 ></DD
2139 ><DT
2140 >Parameter:</DT
2141 ><DD
2142 ><P
2143 >    The name of a client-header filter, as defined in one of the
2144     <A
2145 HREF="filter-file.html"
2146 >filter files</A
2147 >.
2148    </P
2149 ></DD
2150 ><DT
2151 >Notes:</DT
2152 ><DD
2153 ><P
2154 >    Client-header filters are applied to each header on its own, not to
2155     all at once. This makes it easier to diagnose problems, but on the downside
2156     you can't write filters that only change header x if header y's value is z.
2157     You can do that by using tags though.
2158    </P
2159 ><P
2160 >    Client-header filters are executed after the other header actions have finished
2161     and use their output as input.
2162    </P
2163 ><P
2164 >    If the request URL gets changed, <SPAN
2165 CLASS="APPLICATION"
2166 >Privoxy</SPAN
2167 > will detect that and use the new
2168     one. This can be used to rewrite the request destination behind the client's
2169     back, for example to specify a Tor exit relay for certain requests.
2170    </P
2171 ><P
2172 >    Please refer to the <A
2173 HREF="filter-file.html"
2174 >filter file chapter</A
2175 >
2176     to learn which client-header filters are available by default, and how to
2177     create your own.
2178    </P
2179 ></DD
2180 ><DT
2181 >Example usage (section):</DT
2182 ><DD
2183 ><P
2184 >     <TABLE
2185 BORDER="0"
2186 BGCOLOR="#E0E0E0"
2187 WIDTH="90%"
2188 ><TR
2189 ><TD
2190 ><PRE
2191 CLASS="SCREEN"
2192 ># Hide Tor exit notation in Host and Referer Headers
2193 {+client-header-filter{hide-tor-exit-notation}}
2194 /
2195     </PRE
2196 ></TD
2197 ></TR
2198 ></TABLE
2199 >
2200     </P
2201 ></DD
2202 ></DL
2203 ></DIV
2204 ></DIV
2205 ><DIV
2206 CLASS="SECT3"
2207 ><H4
2208 CLASS="SECT3"
2209 ><A
2210 NAME="CLIENT-HEADER-TAGGER"
2211 >8.5.5. client-header-tagger</A
2212 ></H4
2213 ><P
2214 ></P
2215 ><DIV
2216 CLASS="VARIABLELIST"
2217 ><DL
2218 ><DT
2219 >Typical use:</DT
2220 ><DD
2221 ><P
2222 >   Block requests based on their headers.
2223    </P
2224 ></DD
2225 ><DT
2226 >Effect:</DT
2227 ><DD
2228 ><P
2229 >    Client headers to which this action applies are filtered on-the-fly through
2230     the specified regular expression based substitutions, the result is used as
2231     tag. 
2232    </P
2233 ></DD
2234 ><DT
2235 >Type:</DT
2236 ><DD
2237 ><P
2238 >Parameterized.</P
2239 ></DD
2240 ><DT
2241 >Parameter:</DT
2242 ><DD
2243 ><P
2244 >    The name of a client-header tagger, as defined in one of the
2245     <A
2246 HREF="filter-file.html"
2247 >filter files</A
2248 >.
2249    </P
2250 ></DD
2251 ><DT
2252 >Notes:</DT
2253 ><DD
2254 ><P
2255 >    Client-header taggers are applied to each header on its own,
2256     and as the header isn't modified, each tagger <SPAN
2257 CLASS="QUOTE"
2258 >"sees"</SPAN
2259 >
2260     the original.
2261    </P
2262 ><P
2263 >    Client-header taggers are the first actions that are executed
2264     and their tags can be used to control every other action.
2265    </P
2266 ></DD
2267 ><DT
2268 >Example usage (section):</DT
2269 ><DD
2270 ><P
2271 >     <TABLE
2272 BORDER="0"
2273 BGCOLOR="#E0E0E0"
2274 WIDTH="90%"
2275 ><TR
2276 ><TD
2277 ><PRE
2278 CLASS="SCREEN"
2279 ># Tag every request with the User-Agent header
2280 {+client-header-tagger{user-agent}}
2281 /
2282
2283 # Tagging itself doesn't change the action
2284 # settings, sections with TAG patterns do:
2285 #
2286 # If it's a download agent, use a different forwarding proxy,
2287 # show the real User-Agent and make sure resume works.
2288 {+forward-override{forward-socks5 10.0.0.2:2222 .} \
2289  -hide-if-modified-since      \
2290  -overwrite-last-modified     \
2291  -hide-user-agent             \
2292  -filter                      \
2293  -deanimate-gifs              \
2294 }
2295 TAG:^User-Agent: NetBSD-ftp/
2296 TAG:^User-Agent: Novell ZYPP Installer
2297 TAG:^User-Agent: RPM APT-HTTP/
2298 TAG:^User-Agent: fetch libfetch/
2299 TAG:^User-Agent: Ubuntu APT-HTTP/
2300 TAG:^User-Agent: MPlayer/
2301     </PRE
2302 ></TD
2303 ></TR
2304 ></TABLE
2305 >
2306     </P
2307 ></DD
2308 ></DL
2309 ></DIV
2310 ></DIV
2311 ><DIV
2312 CLASS="SECT3"
2313 ><H4
2314 CLASS="SECT3"
2315 ><A
2316 NAME="CONTENT-TYPE-OVERWRITE"
2317 >8.5.6. content-type-overwrite</A
2318 ></H4
2319 ><P
2320 ></P
2321 ><DIV
2322 CLASS="VARIABLELIST"
2323 ><DL
2324 ><DT
2325 >Typical use:</DT
2326 ><DD
2327 ><P
2328 >Stop useless download menus from popping up, or change the browser's rendering mode</P
2329 ></DD
2330 ><DT
2331 >Effect:</DT
2332 ><DD
2333 ><P
2334 >    Replaces the <SPAN
2335 CLASS="QUOTE"
2336 >"Content-Type:"</SPAN
2337 > HTTP server header.
2338    </P
2339 ></DD
2340 ><DT
2341 >Type:</DT
2342 ><DD
2343 ><P
2344 >Parameterized.</P
2345 ></DD
2346 ><DT
2347 >Parameter:</DT
2348 ><DD
2349 ><P
2350 >    Any string. 
2351    </P
2352 ></DD
2353 ><DT
2354 >Notes:</DT
2355 ><DD
2356 ><P
2357 >    The <SPAN
2358 CLASS="QUOTE"
2359 >"Content-Type:"</SPAN
2360 > HTTP server header is used by the
2361     browser to decide what to do with the document. The value of this
2362     header can cause the browser to open a download menu instead of
2363     displaying the document by itself, even if the document's format is
2364     supported by the browser. 
2365    </P
2366 ><P
2367 >    The declared content type can also affect which rendering mode
2368     the browser chooses. If XHTML is delivered as <SPAN
2369 CLASS="QUOTE"
2370 >"text/html"</SPAN
2371 >,
2372     many browsers treat it as yet another broken HTML document.
2373     If it is send as <SPAN
2374 CLASS="QUOTE"
2375 >"application/xml"</SPAN
2376 >, browsers with
2377     XHTML support will only display it, if the syntax is correct.
2378    </P
2379 ><P
2380 >    If you see a web site that proudly uses XHTML buttons, but sets
2381     <SPAN
2382 CLASS="QUOTE"
2383 >"Content-Type: text/html"</SPAN
2384 >, you can use <SPAN
2385 CLASS="APPLICATION"
2386 >Privoxy</SPAN
2387 >
2388     to overwrite it with <SPAN
2389 CLASS="QUOTE"
2390 >"application/xml"</SPAN
2391 > and validate
2392     the web master's claim inside your XHTML-supporting browser.
2393     If the syntax is incorrect, the browser will complain loudly. 
2394    </P
2395 ><P
2396 >    You can also go the opposite direction: if your browser prints
2397     error messages instead of rendering a document falsely declared
2398     as XHTML, you can overwrite the content type with
2399     <SPAN
2400 CLASS="QUOTE"
2401 >"text/html"</SPAN
2402 > and have it rendered as broken HTML document. 
2403    </P
2404 ><P
2405 >    By default <TT
2406 CLASS="LITERAL"
2407 >content-type-overwrite</TT
2408 > only replaces
2409     <SPAN
2410 CLASS="QUOTE"
2411 >"Content-Type:"</SPAN
2412 > headers that look like some kind of text.
2413     If you want to overwrite it unconditionally, you have to combine it with
2414     <TT
2415 CLASS="LITERAL"
2416 ><A
2417 HREF="actions-file.html#FORCE-TEXT-MODE"
2418 >force-text-mode</A
2419 ></TT
2420 >.
2421     This limitation exists for a reason, think twice before circumventing it.
2422    </P
2423 ><P
2424 >    Most of the time it's easier to replace this action with a custom
2425     <TT
2426 CLASS="LITERAL"
2427 ><A
2428 HREF="actions-file.html#SERVER-HEADER-FILTER"
2429 >server-header filter</A
2430 ></TT
2431 >.
2432     It allows you to activate it for every document of a certain site and it will still
2433     only replace the content types you aimed at.
2434    </P
2435 ><P
2436 >    Of course you can apply <TT
2437 CLASS="LITERAL"
2438 >content-type-overwrite</TT
2439 >
2440     to a whole site and then make URL based exceptions, but it's a lot
2441     more work to get the same precision. 
2442    </P
2443 ></DD
2444 ><DT
2445 >Example usage (sections):</DT
2446 ><DD
2447 ><P
2448 >     <TABLE
2449 BORDER="0"
2450 BGCOLOR="#E0E0E0"
2451 WIDTH="90%"
2452 ><TR
2453 ><TD
2454 ><PRE
2455 CLASS="SCREEN"
2456 ># Check if www.example.net/ really uses valid XHTML
2457 { +content-type-overwrite{application/xml} }
2458 www.example.net/
2459
2460 # but leave the content type unmodified if the URL looks like a style sheet
2461 {-content-type-overwrite}
2462 www.example.net/.*\.css$
2463 www.example.net/.*style</PRE
2464 ></TD
2465 ></TR
2466 ></TABLE
2467 >
2468    </P
2469 ></DD
2470 ></DL
2471 ></DIV
2472 ></DIV
2473 ><DIV
2474 CLASS="SECT3"
2475 ><H4
2476 CLASS="SECT3"
2477 ><A
2478 NAME="CRUNCH-CLIENT-HEADER"
2479 >8.5.7. crunch-client-header</A
2480 ></H4
2481 ><P
2482 ></P
2483 ><DIV
2484 CLASS="VARIABLELIST"
2485 ><DL
2486 ><DT
2487 >Typical use:</DT
2488 ><DD
2489 ><P
2490 >Remove a client header <SPAN
2491 CLASS="APPLICATION"
2492 >Privoxy</SPAN
2493 > has no dedicated action for.</P
2494 ></DD
2495 ><DT
2496 >Effect:</DT
2497 ><DD
2498 ><P
2499 >    Deletes every header sent by the client that contains the string the user supplied as parameter.
2500    </P
2501 ></DD
2502 ><DT
2503 >Type:</DT
2504 ><DD
2505 ><P
2506 >Parameterized.</P
2507 ></DD
2508 ><DT
2509 >Parameter:</DT
2510 ><DD
2511 ><P
2512 >    Any string.
2513    </P
2514 ></DD
2515 ><DT
2516 >Notes:</DT
2517 ><DD
2518 ><P
2519 >    This action allows you to block client headers for which no dedicated
2520     <SPAN
2521 CLASS="APPLICATION"
2522 >Privoxy</SPAN
2523 > action exists.
2524     <SPAN
2525 CLASS="APPLICATION"
2526 >Privoxy</SPAN
2527 > will remove every client header that
2528     contains the string you supplied as parameter.
2529    </P
2530 ><P
2531 >    Regular expressions are <SPAN
2532 CLASS="emphasis"
2533 ><I
2534 CLASS="EMPHASIS"
2535 >not supported</I
2536 ></SPAN
2537 > and you can't
2538     use this action to block different headers in the same request, unless
2539     they contain the same string.
2540    </P
2541 ><P
2542 >    <TT
2543 CLASS="LITERAL"
2544 >crunch-client-header</TT
2545 > is only meant for quick tests.
2546     If you have to block several different headers, or only want to modify
2547     parts of them, you should use a
2548     <TT
2549 CLASS="LITERAL"
2550 ><A
2551 HREF="actions-file.html#CLIENT-HEADER-FILTER"
2552 >client-header filter</A
2553 ></TT
2554 >.
2555    </P
2556 ><DIV
2557 CLASS="WARNING"
2558 ><P
2559 ></P
2560 ><TABLE
2561 CLASS="WARNING"
2562 BORDER="1"
2563 WIDTH="90%"
2564 ><TR
2565 ><TD
2566 ALIGN="CENTER"
2567 ><B
2568 >Warning</B
2569 ></TD
2570 ></TR
2571 ><TR
2572 ><TD
2573 ALIGN="LEFT"
2574 ><P
2575 >      Don't block any header without understanding the consequences.
2576      </P
2577 ></TD
2578 ></TR
2579 ></TABLE
2580 ></DIV
2581 ></DD
2582 ><DT
2583 >Example usage (section):</DT
2584 ><DD
2585 ><P
2586 >     <TABLE
2587 BORDER="0"
2588 BGCOLOR="#E0E0E0"
2589 WIDTH="90%"
2590 ><TR
2591 ><TD
2592 ><PRE
2593 CLASS="SCREEN"
2594 ># Block the non-existent "Privacy-Violation:" client header 
2595 { +crunch-client-header{Privacy-Violation:} }
2596 /
2597     </PRE
2598 ></TD
2599 ></TR
2600 ></TABLE
2601 >
2602    </P
2603 ></DD
2604 ></DL
2605 ></DIV
2606 ></DIV
2607 ><DIV
2608 CLASS="SECT3"
2609 ><H4
2610 CLASS="SECT3"
2611 ><A
2612 NAME="CRUNCH-IF-NONE-MATCH"
2613 >8.5.8. crunch-if-none-match</A
2614 ></H4
2615 ><P
2616 ></P
2617 ><DIV
2618 CLASS="VARIABLELIST"
2619 ><DL
2620 ><DT
2621 >Typical use:</DT
2622 ><DD
2623 ><P
2624 >Prevent yet another way to track the user's steps between sessions.</P
2625 ></DD
2626 ><DT
2627 >Effect:</DT
2628 ><DD
2629 ><P
2630 >    Deletes the <SPAN
2631 CLASS="QUOTE"
2632 >"If-None-Match:"</SPAN
2633 > HTTP client header.
2634    </P
2635 ></DD
2636 ><DT
2637 >Type:</DT
2638 ><DD
2639 ><P
2640 >Boolean.</P
2641 ></DD
2642 ><DT
2643 >Parameter:</DT
2644 ><DD
2645 ><P
2646 >    N/A
2647    </P
2648 ></DD
2649 ><DT
2650 >Notes:</DT
2651 ><DD
2652 ><P
2653 >    Removing the <SPAN
2654 CLASS="QUOTE"
2655 >"If-None-Match:"</SPAN
2656 > HTTP client header
2657     is useful for filter testing, where you want to force a real
2658     reload instead of getting status code <SPAN
2659 CLASS="QUOTE"
2660 >"304"</SPAN
2661 > which
2662     would cause the browser to use a cached copy of the page.
2663    </P
2664 ><P
2665 >    It is also useful to make sure the header isn't used as a cookie
2666     replacement (unlikely but possible).
2667    </P
2668 ><P
2669 >    Blocking the <SPAN
2670 CLASS="QUOTE"
2671 >"If-None-Match:"</SPAN
2672 > header shouldn't cause any
2673     caching problems, as long as the <SPAN
2674 CLASS="QUOTE"
2675 >"If-Modified-Since:"</SPAN
2676 > header
2677     isn't blocked or missing as well.
2678    </P
2679 ><P
2680 >    It is recommended to use this action together with
2681     <TT
2682 CLASS="LITERAL"
2683 ><A
2684 HREF="actions-file.html#HIDE-IF-MODIFIED-SINCE"
2685 >hide-if-modified-since</A
2686 ></TT
2687 >
2688     and
2689     <TT
2690 CLASS="LITERAL"
2691 ><A
2692 HREF="actions-file.html#OVERWRITE-LAST-MODIFIED"
2693 >overwrite-last-modified</A
2694 ></TT
2695 >.
2696    </P
2697 ></DD
2698 ><DT
2699 >Example usage (section):</DT
2700 ><DD
2701 ><P
2702 >     <TABLE
2703 BORDER="0"
2704 BGCOLOR="#E0E0E0"
2705 WIDTH="90%"
2706 ><TR
2707 ><TD
2708 ><PRE
2709 CLASS="SCREEN"
2710 ># Let the browser revalidate cached documents but don't
2711 # allow the server to use the revalidation headers for user tracking.
2712 {+hide-if-modified-since{-60} \
2713  +overwrite-last-modified{randomize} \
2714  +crunch-if-none-match}
2715 /   </PRE
2716 ></TD
2717 ></TR
2718 ></TABLE
2719 >
2720    </P
2721 ></DD
2722 ></DL
2723 ></DIV
2724 ></DIV
2725 ><DIV
2726 CLASS="SECT3"
2727 ><H4
2728 CLASS="SECT3"
2729 ><A
2730 NAME="CRUNCH-INCOMING-COOKIES"
2731 >8.5.9. crunch-incoming-cookies</A
2732 ></H4
2733 ><P
2734 ></P
2735 ><DIV
2736 CLASS="VARIABLELIST"
2737 ><DL
2738 ><DT
2739 >Typical use:</DT
2740 ><DD
2741 ><P
2742 >    Prevent the web server from setting HTTP cookies on your system
2743    </P
2744 ></DD
2745 ><DT
2746 >Effect:</DT
2747 ><DD
2748 ><P
2749 >    Deletes any <SPAN
2750 CLASS="QUOTE"
2751 >"Set-Cookie:"</SPAN
2752 > HTTP headers from server replies.
2753    </P
2754 ></DD
2755 ><DT
2756 >Type:</DT
2757 ><DD
2758 ><P
2759 >Boolean.</P
2760 ></DD
2761 ><DT
2762 >Parameter:</DT
2763 ><DD
2764 ><P
2765 >    N/A
2766    </P
2767 ></DD
2768 ><DT
2769 >Notes:</DT
2770 ><DD
2771 ><P
2772 >    This action is only concerned with <SPAN
2773 CLASS="emphasis"
2774 ><I
2775 CLASS="EMPHASIS"
2776 >incoming</I
2777 ></SPAN
2778 > HTTP cookies. For
2779     <SPAN
2780 CLASS="emphasis"
2781 ><I
2782 CLASS="EMPHASIS"
2783 >outgoing</I
2784 ></SPAN
2785 > HTTP cookies, use
2786     <TT
2787 CLASS="LITERAL"
2788 ><A
2789 HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
2790 >crunch-outgoing-cookies</A
2791 ></TT
2792 >.
2793     Use <SPAN
2794 CLASS="emphasis"
2795 ><I
2796 CLASS="EMPHASIS"
2797 >both</I
2798 ></SPAN
2799 > to disable HTTP cookies completely.
2800    </P
2801 ><P
2802 >    It makes <SPAN
2803 CLASS="emphasis"
2804 ><I
2805 CLASS="EMPHASIS"
2806 >no sense at all</I
2807 ></SPAN
2808 > to use this action in conjunction
2809     with the <TT
2810 CLASS="LITERAL"
2811 ><A
2812 HREF="actions-file.html#SESSION-COOKIES-ONLY"
2813 >session-cookies-only</A
2814 ></TT
2815 > action,
2816     since it would prevent the session cookies from being set. See also 
2817     <TT
2818 CLASS="LITERAL"
2819 ><A
2820 HREF="actions-file.html#FILTER-CONTENT-COOKIES"
2821 >filter-content-cookies</A
2822 ></TT
2823 >.
2824    </P
2825 ></DD
2826 ><DT
2827 >Example usage:</DT
2828 ><DD
2829 ><P
2830 >    <TABLE
2831 BORDER="0"
2832 BGCOLOR="#E0E0E0"
2833 WIDTH="90%"
2834 ><TR
2835 ><TD
2836 ><PRE
2837 CLASS="SCREEN"
2838 >+crunch-incoming-cookies</PRE
2839 ></TD
2840 ></TR
2841 ></TABLE
2842 >
2843    </P
2844 ></DD
2845 ></DL
2846 ></DIV
2847 ></DIV
2848 ><DIV
2849 CLASS="SECT3"
2850 ><H4
2851 CLASS="SECT3"
2852 ><A
2853 NAME="CRUNCH-SERVER-HEADER"
2854 >8.5.10. crunch-server-header</A
2855 ></H4
2856 ><P
2857 ></P
2858 ><DIV
2859 CLASS="VARIABLELIST"
2860 ><DL
2861 ><DT
2862 >Typical use:</DT
2863 ><DD
2864 ><P
2865 >Remove a server header <SPAN
2866 CLASS="APPLICATION"
2867 >Privoxy</SPAN
2868 > has no dedicated action for.</P
2869 ></DD
2870 ><DT
2871 >Effect:</DT
2872 ><DD
2873 ><P
2874 >    Deletes every header sent by the server that contains the string the user supplied as parameter.
2875    </P
2876 ></DD
2877 ><DT
2878 >Type:</DT
2879 ><DD
2880 ><P
2881 >Parameterized.</P
2882 ></DD
2883 ><DT
2884 >Parameter:</DT
2885 ><DD
2886 ><P
2887 >    Any string.
2888    </P
2889 ></DD
2890 ><DT
2891 >Notes:</DT
2892 ><DD
2893 ><P
2894 >    This action allows you to block server headers for which no dedicated
2895     <SPAN
2896 CLASS="APPLICATION"
2897 >Privoxy</SPAN
2898 > action exists. <SPAN
2899 CLASS="APPLICATION"
2900 >Privoxy</SPAN
2901 >
2902     will remove every server header that contains the string you supplied as parameter.
2903    </P
2904 ><P
2905 >    Regular expressions are <SPAN
2906 CLASS="emphasis"
2907 ><I
2908 CLASS="EMPHASIS"
2909 >not supported</I
2910 ></SPAN
2911 > and you can't
2912     use this action to block different headers in the same request, unless
2913     they contain the same string.
2914    </P
2915 ><P
2916 >    <TT
2917 CLASS="LITERAL"
2918 >crunch-server-header</TT
2919 > is only meant for quick tests.
2920     If you have to block several different headers, or only want to modify
2921     parts of them, you should use a custom
2922     <TT
2923 CLASS="LITERAL"
2924 ><A
2925 HREF="actions-file.html#SERVER-HEADER-FILTER"
2926 >server-header filter</A
2927 ></TT
2928 >.
2929    </P
2930 ><DIV
2931 CLASS="WARNING"
2932 ><P
2933 ></P
2934 ><TABLE
2935 CLASS="WARNING"
2936 BORDER="1"
2937 WIDTH="90%"
2938 ><TR
2939 ><TD
2940 ALIGN="CENTER"
2941 ><B
2942 >Warning</B
2943 ></TD
2944 ></TR
2945 ><TR
2946 ><TD
2947 ALIGN="LEFT"
2948 ><P
2949 >     Don't block any header without understanding the consequences.
2950      </P
2951 ></TD
2952 ></TR
2953 ></TABLE
2954 ></DIV
2955 ></DD
2956 ><DT
2957 >Example usage (section):</DT
2958 ><DD
2959 ><P
2960 >     <TABLE
2961 BORDER="0"
2962 BGCOLOR="#E0E0E0"
2963 WIDTH="90%"
2964 ><TR
2965 ><TD
2966 ><PRE
2967 CLASS="SCREEN"
2968 ># Crunch server headers that try to prevent caching
2969 { +crunch-server-header{no-cache} }
2970 /   </PRE
2971 ></TD
2972 ></TR
2973 ></TABLE
2974 >
2975    </P
2976 ></DD
2977 ></DL
2978 ></DIV
2979 ></DIV
2980 ><DIV
2981 CLASS="SECT3"
2982 ><H4
2983 CLASS="SECT3"
2984 ><A
2985 NAME="CRUNCH-OUTGOING-COOKIES"
2986 >8.5.11. crunch-outgoing-cookies</A
2987 ></H4
2988 ><P
2989 ></P
2990 ><DIV
2991 CLASS="VARIABLELIST"
2992 ><DL
2993 ><DT
2994 >Typical use:</DT
2995 ><DD
2996 ><P
2997 >    Prevent the web server from reading any HTTP cookies from your system
2998    </P
2999 ></DD
3000 ><DT
3001 >Effect:</DT
3002 ><DD
3003 ><P
3004 >    Deletes any <SPAN
3005 CLASS="QUOTE"
3006 >"Cookie:"</SPAN
3007 > HTTP headers from client requests.
3008    </P
3009 ></DD
3010 ><DT
3011 >Type:</DT
3012 ><DD
3013 ><P
3014 >Boolean.</P
3015 ></DD
3016 ><DT
3017 >Parameter:</DT
3018 ><DD
3019 ><P
3020 >    N/A
3021    </P
3022 ></DD
3023 ><DT
3024 >Notes:</DT
3025 ><DD
3026 ><P
3027 >    This action is only concerned with <SPAN
3028 CLASS="emphasis"
3029 ><I
3030 CLASS="EMPHASIS"
3031 >outgoing</I
3032 ></SPAN
3033 > HTTP cookies. For
3034     <SPAN
3035 CLASS="emphasis"
3036 ><I
3037 CLASS="EMPHASIS"
3038 >incoming</I
3039 ></SPAN
3040 > HTTP cookies, use
3041     <TT
3042 CLASS="LITERAL"
3043 ><A
3044 HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
3045 >crunch-incoming-cookies</A
3046 ></TT
3047 >.
3048     Use <SPAN
3049 CLASS="emphasis"
3050 ><I
3051 CLASS="EMPHASIS"
3052 >both</I
3053 ></SPAN
3054 > to disable HTTP cookies completely.
3055    </P
3056 ><P
3057 >    It makes <SPAN
3058 CLASS="emphasis"
3059 ><I
3060 CLASS="EMPHASIS"
3061 >no sense at all</I
3062 ></SPAN
3063 > to use this action in conjunction
3064     with the <TT
3065 CLASS="LITERAL"
3066 ><A
3067 HREF="actions-file.html#SESSION-COOKIES-ONLY"
3068 >session-cookies-only</A
3069 ></TT
3070 > action,
3071     since it would prevent the session cookies from being read.
3072    </P
3073 ></DD
3074 ><DT
3075 >Example usage:</DT
3076 ><DD
3077 ><P
3078 >    <TABLE
3079 BORDER="0"
3080 BGCOLOR="#E0E0E0"
3081 WIDTH="90%"
3082 ><TR
3083 ><TD
3084 ><PRE
3085 CLASS="SCREEN"
3086 >+crunch-outgoing-cookies</PRE
3087 ></TD
3088 ></TR
3089 ></TABLE
3090 >
3091    </P
3092 ></DD
3093 ></DL
3094 ></DIV
3095 ></DIV
3096 ><DIV
3097 CLASS="SECT3"
3098 ><H4
3099 CLASS="SECT3"
3100 ><A
3101 NAME="DEANIMATE-GIFS"
3102 >8.5.12. deanimate-gifs</A
3103 ></H4
3104 ><P
3105 ></P
3106 ><DIV
3107 CLASS="VARIABLELIST"
3108 ><DL
3109 ><DT
3110 >Typical use:</DT
3111 ><DD
3112 ><P
3113 >Stop those annoying, distracting animated GIF images.</P
3114 ></DD
3115 ><DT
3116 >Effect:</DT
3117 ><DD
3118 ><P
3119 >    De-animate GIF animations, i.e. reduce them to their first or last image.
3120    </P
3121 ></DD
3122 ><DT
3123 >Type:</DT
3124 ><DD
3125 ><P
3126 >Parameterized.</P
3127 ></DD
3128 ><DT
3129 >Parameter:</DT
3130 ><DD
3131 ><P
3132 >    <SPAN
3133 CLASS="QUOTE"
3134 >"last"</SPAN
3135 > or <SPAN
3136 CLASS="QUOTE"
3137 >"first"</SPAN
3138 >
3139    </P
3140 ></DD
3141 ><DT
3142 >Notes:</DT
3143 ><DD
3144 ><P
3145 >    This will also shrink the images considerably (in bytes, not pixels!). If
3146     the option <SPAN
3147 CLASS="QUOTE"
3148 >"first"</SPAN
3149 > is given, the first frame of the animation
3150     is used as the replacement. If <SPAN
3151 CLASS="QUOTE"
3152 >"last"</SPAN
3153 > is given, the last
3154     frame of the animation is used instead, which probably makes more sense for
3155     most banner animations, but also has the risk of not showing the entire
3156     last frame (if it is only a delta to an earlier frame).
3157    </P
3158 ><P
3159 >    You can safely use this action with patterns that will also match non-GIF
3160     objects, because no attempt will be made at anything that doesn't look like
3161     a GIF.
3162    </P
3163 ></DD
3164 ><DT
3165 >Example usage:</DT
3166 ><DD
3167 ><P
3168 >      <TABLE
3169 BORDER="0"
3170 BGCOLOR="#E0E0E0"
3171 WIDTH="90%"
3172 ><TR
3173 ><TD
3174 ><PRE
3175 CLASS="SCREEN"
3176 >+deanimate-gifs{last}</PRE
3177 ></TD
3178 ></TR
3179 ></TABLE
3180 >
3181     </P
3182 ></DD
3183 ></DL
3184 ></DIV
3185 ></DIV
3186 ><DIV
3187 CLASS="SECT3"
3188 ><H4
3189 CLASS="SECT3"
3190 ><A
3191 NAME="DOWNGRADE-HTTP-VERSION"
3192 >8.5.13. downgrade-http-version</A
3193 ></H4
3194 ><P
3195 ></P
3196 ><DIV
3197 CLASS="VARIABLELIST"
3198 ><DL
3199 ><DT
3200 >Typical use:</DT
3201 ><DD
3202 ><P
3203 >Work around (very rare) problems with HTTP/1.1</P
3204 ></DD
3205 ><DT
3206 >Effect:</DT
3207 ><DD
3208 ><P
3209 >    Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
3210    </P
3211 ></DD
3212 ><DT
3213 >Type:</DT
3214 ><DD
3215 ><P
3216 >Boolean.</P
3217 ></DD
3218 ><DT
3219 >Parameter:</DT
3220 ><DD
3221 ><P
3222 >    N/A
3223    </P
3224 ></DD
3225 ><DT
3226 >Notes:</DT
3227 ><DD
3228 ><P
3229 >    This is a left-over from the time when <SPAN
3230 CLASS="APPLICATION"
3231 >Privoxy</SPAN
3232 >
3233     didn't support important HTTP/1.1 features well. It is left here for the
3234     unlikely case that you experience HTTP/1.1 related problems with some server
3235     out there. Not all HTTP/1.1 features and requirements are supported yet,
3236     so there is a chance you might need this action.
3237    </P
3238 ></DD
3239 ><DT
3240 >Example usage (section):</DT
3241 ><DD
3242 ><P
3243 >     <TABLE
3244 BORDER="0"
3245 BGCOLOR="#E0E0E0"
3246 WIDTH="90%"
3247 ><TR
3248 ><TD
3249 ><PRE
3250 CLASS="SCREEN"
3251 >{+downgrade-http-version}
3252 problem-host.example.com</PRE
3253 ></TD
3254 ></TR
3255 ></TABLE
3256 >
3257     </P
3258 ></DD
3259 ></DL
3260 ></DIV
3261 ></DIV
3262 ><DIV
3263 CLASS="SECT3"
3264 ><H4
3265 CLASS="SECT3"
3266 ><A
3267 NAME="FAST-REDIRECTS"
3268 >8.5.14. fast-redirects</A
3269 ></H4
3270 ><P
3271 ></P
3272 ><DIV
3273 CLASS="VARIABLELIST"
3274 ><DL
3275 ><DT
3276 >Typical use:</DT
3277 ><DD
3278 ><P
3279 >Fool some click-tracking scripts and speed up indirect links.</P
3280 ></DD
3281 ><DT
3282 >Effect:</DT
3283 ><DD
3284 ><P
3285 >    Detects redirection URLs and redirects the browser without contacting
3286     the redirection server first.
3287    </P
3288 ></DD
3289 ><DT
3290 >Type:</DT
3291 ><DD
3292 ><P
3293 >Parameterized.</P
3294 ></DD
3295 ><DT
3296 >Parameter:</DT
3297 ><DD
3298 ><P
3299 ></P
3300 ><UL
3301 ><LI
3302 ><P
3303 >      <SPAN
3304 CLASS="QUOTE"
3305 >"simple-check"</SPAN
3306 > to just search for the string <SPAN
3307 CLASS="QUOTE"
3308 >"http://"</SPAN
3309 >
3310       to detect redirection URLs.
3311      </P
3312 ></LI
3313 ><LI
3314 ><P
3315 >      <SPAN
3316 CLASS="QUOTE"
3317 >"check-decoded-url"</SPAN
3318 > to decode URLs (if necessary) before searching
3319       for redirection URLs.
3320      </P
3321 ></LI
3322 ></UL
3323 ></DD
3324 ><DT
3325 >Notes:</DT
3326 ><DD
3327 ><P
3328 >  
3329     Many sites, like yahoo.com, don't just link to other sites. Instead, they
3330     will link to some script on their own servers, giving the destination as a
3331     parameter, which will then redirect you to the final target. URLs
3332     resulting from this scheme typically look like:
3333     <SPAN
3334 CLASS="QUOTE"
3335 >"http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/"</SPAN
3336 >.
3337   </P
3338 ><P
3339 >    Sometimes, there are even multiple consecutive redirects encoded in the
3340     URL. These redirections via scripts make your web browsing more traceable,
3341     since the server from which you follow such a link can see where you go
3342     to. Apart from that, valuable bandwidth and time is wasted, while your
3343     browser asks the server for one redirect after the other. Plus, it feeds
3344     the advertisers.
3345    </P
3346 ><P
3347 >    This feature is currently not very smart and is scheduled for improvement.
3348     If it is enabled by default, you will have to create some exceptions to
3349     this action. It can lead to failures in several ways: 
3350    </P
3351 ><P
3352 >    Not every URLs with other URLs as parameters is evil.
3353     Some sites offer a real service that requires this information to work.
3354     For example a validation service needs to know, which document to validate.
3355     <TT
3356 CLASS="LITERAL"
3357 >fast-redirects</TT
3358 > assumes that every URL parameter that
3359     looks like another URL is a redirection target, and will always redirect to
3360     the last one. Most of the time the assumption is correct, but if it isn't,
3361     the user gets redirected anyway.
3362    </P
3363 ><P
3364 >    Another failure occurs if the URL contains other parameters after the URL parameter.
3365     The URL:
3366     <SPAN
3367 CLASS="QUOTE"
3368 >"http://www.example.org/?redirect=http%3a//www.example.net/&#38;foo=bar"</SPAN
3369 >.
3370     contains the redirection URL <SPAN
3371 CLASS="QUOTE"
3372 >"http://www.example.net/"</SPAN
3373 >,
3374     followed by another parameter. <TT
3375 CLASS="LITERAL"
3376 >fast-redirects</TT
3377 > doesn't know that
3378     and will cause a redirect to <SPAN
3379 CLASS="QUOTE"
3380 >"http://www.example.net/&#38;foo=bar"</SPAN
3381 >.
3382     Depending on the target server configuration, the parameter will be silently ignored
3383     or lead to a <SPAN
3384 CLASS="QUOTE"
3385 >"page not found"</SPAN
3386 > error. You can prevent this problem by
3387     first using the <TT
3388 CLASS="LITERAL"
3389 ><A
3390 HREF="actions-file.html#REDIRECT"
3391 >redirect</A
3392 ></TT
3393 > action
3394     to remove the last part of the URL, but it requires a little effort.
3395    </P
3396 ><P
3397 >    To detect a redirection URL, <TT
3398 CLASS="LITERAL"
3399 >fast-redirects</TT
3400 > only
3401     looks for the string <SPAN
3402 CLASS="QUOTE"
3403 >"http://"</SPAN
3404 >, either in plain text
3405     (invalid but often used) or encoded as <SPAN
3406 CLASS="QUOTE"
3407 >"http%3a//"</SPAN
3408 >.
3409     Some sites use their own URL encoding scheme, encrypt the address
3410     of the target server or replace it with a database id. In theses cases
3411     <TT
3412 CLASS="LITERAL"
3413 >fast-redirects</TT
3414 > is fooled and the request reaches the
3415     redirection server where it probably gets logged.
3416    </P
3417 ></DD
3418 ><DT
3419 >Example usage:</DT
3420 ><DD
3421 ><P
3422 >     <TABLE
3423 BORDER="0"
3424 BGCOLOR="#E0E0E0"
3425 WIDTH="90%"
3426 ><TR
3427 ><TD
3428 ><PRE
3429 CLASS="SCREEN"
3430 > { +fast-redirects{simple-check} }
3431    one.example.com 
3432
3433  { +fast-redirects{check-decoded-url} }
3434    another.example.com/testing</PRE
3435 ></TD
3436 ></TR
3437 ></TABLE
3438 >
3439     </P
3440 ></DD
3441 ></DL
3442 ></DIV
3443 ></DIV
3444 ><DIV
3445 CLASS="SECT3"
3446 ><H4
3447 CLASS="SECT3"
3448 ><A
3449 NAME="FILTER"
3450 >8.5.15. filter</A
3451 ></H4
3452 ><P
3453 ></P
3454 ><DIV
3455 CLASS="VARIABLELIST"
3456 ><DL
3457 ><DT
3458 >Typical use:</DT
3459 ><DD
3460 ><P
3461 >Get rid of HTML and JavaScript annoyances, banner advertisements (by size), 
3462          do fun text replacements, add personalized effects, etc.</P
3463 ></DD
3464 ><DT
3465 >Effect:</DT
3466 ><DD
3467 ><P
3468 >    All instances of text-based type, most notably HTML and JavaScript, to which
3469     this action applies, can be filtered on-the-fly through the specified regular
3470     expression based substitutions. (Note: as of version 3.0.3 plain text documents
3471     are exempted from filtering, because web servers often use the
3472    <TT
3473 CLASS="LITERAL"
3474 >text/plain</TT
3475 > MIME type for all files whose type they don't know.)
3476    </P
3477 ></DD
3478 ><DT
3479 >Type:</DT
3480 ><DD
3481 ><P
3482 >Parameterized.</P
3483 ></DD
3484 ><DT
3485 >Parameter:</DT
3486 ><DD
3487 ><P
3488 >    The name of a content filter, as defined in the <A
3489 HREF="filter-file.html"
3490 >filter file</A
3491 >.
3492     Filters can be defined in one or more  files as defined by the 
3493     <TT
3494 CLASS="LITERAL"
3495 ><A
3496 HREF="config.html#FILTERFILE"
3497 >filterfile</A
3498 ></TT
3499 >
3500     option in the <A
3501 HREF="config.html"
3502 >config file</A
3503 >. 
3504     <TT
3505 CLASS="FILENAME"
3506 >default.filter</TT
3507 > is the collection of filters 
3508     supplied by the developers. Locally defined filters should go 
3509     in their own file, such as <TT
3510 CLASS="FILENAME"
3511 >user.filter</TT
3512 >.
3513    </P
3514 ><P
3515 >     When used in its negative form,
3516      and without parameters, <SPAN
3517 CLASS="emphasis"
3518 ><I
3519 CLASS="EMPHASIS"
3520 >all</I
3521 ></SPAN
3522 > filtering is completely disabled.
3523   </P
3524 ></DD
3525 ><DT
3526 >Notes:</DT
3527 ><DD
3528 ><P
3529 >    For your convenience, there are a number of pre-defined filters available 
3530     in the distribution filter file that you can use. See the examples below for
3531     a list.
3532    </P
3533 ><P
3534 >    Filtering requires buffering the page content, which may appear to
3535     slow down page rendering since nothing is displayed until all content has
3536     passed the filters. (It does not really take longer, but seems that way
3537     since the page is not incrementally displayed.) This effect will be more
3538     noticeable on slower connections.
3539    </P
3540 ><P
3541 >   <SPAN
3542 CLASS="QUOTE"
3543 >"Rolling your own"</SPAN
3544 >
3545     filters requires a knowledge of 
3546      <A
3547 HREF="http://en.wikipedia.org/wiki/Regular_expressions"
3548 TARGET="_top"
3549 ><SPAN
3550 CLASS="QUOTE"
3551 >"Regular
3552      Expressions"</SPAN
3553 ></A
3554 > and 
3555       <A
3556 HREF="http://en.wikipedia.org/wiki/Html"
3557 TARGET="_top"
3558 ><SPAN
3559 CLASS="QUOTE"
3560 >"HTML"</SPAN
3561 ></A
3562 >.
3563     This is very powerful feature, and potentially very intrusive. 
3564     Filters should be used with caution, and where an equivalent
3565     <SPAN
3566 CLASS="QUOTE"
3567 >"action"</SPAN
3568 > is not available.
3569    </P
3570 ><P
3571 >    The amount of data that can be filtered is limited to the 
3572     <TT
3573 CLASS="LITERAL"
3574 ><A
3575 HREF="config.html#BUFFER-LIMIT"
3576 >buffer-limit</A
3577 ></TT
3578 >
3579     option in the main <A
3580 HREF="config.html"
3581 >config file</A
3582 >. The 
3583     default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered
3584     data, and all pending data, is passed through unfiltered. 
3585    </P
3586 ><P
3587 >    Inappropriate MIME types, such as zipped files, are not filtered at all.
3588     (Again, only text-based types except plain text). Encrypted SSL data
3589     (from HTTPS servers) cannot be filtered either, since this would violate
3590     the integrity of the secure transaction. In some situations it might
3591     be necessary to protect certain text, like source code, from filtering
3592     by defining appropriate <TT
3593 CLASS="LITERAL"
3594 >-filter</TT
3595 > exceptions.
3596    </P
3597 ><P
3598 >    Compressed content can't be filtered either, unless <SPAN
3599 CLASS="APPLICATION"
3600 >Privoxy</SPAN
3601 >
3602     is compiled with zlib support (requires at least <SPAN
3603 CLASS="APPLICATION"
3604 >Privoxy</SPAN
3605 > 3.0.7),
3606     in which case <SPAN
3607 CLASS="APPLICATION"
3608 >Privoxy</SPAN
3609 > will decompress the content before filtering
3610     it.
3611    </P
3612 ><P
3613 >    If you use a <SPAN
3614 CLASS="APPLICATION"
3615 >Privoxy</SPAN
3616 > version without zlib support, but want filtering to work on
3617     as much documents as possible, even those that would normally be sent compressed,
3618     you must use the <TT
3619 CLASS="LITERAL"
3620 ><A
3621 HREF="actions-file.html#PREVENT-COMPRESSION"
3622 >prevent-compression</A
3623 ></TT
3624 >
3625     action in conjunction with <TT
3626 CLASS="LITERAL"
3627 >filter</TT
3628 >.
3629    </P
3630 ><P
3631 >    Content filtering can achieve some of the same effects as the 
3632     <TT
3633 CLASS="LITERAL"
3634 ><A
3635 HREF="actions-file.html#BLOCK"
3636 >block</A
3637 ></TT
3638 >
3639     action, i.e. it can be used to block ads and banners. But the mechanism 
3640     works quite differently. One effective use, is to block ad banners 
3641     based on their size (see below), since many of these seem to be somewhat 
3642     standardized.
3643    </P
3644 ><P
3645 >    <A
3646 HREF="contact.html"
3647 >Feedback</A
3648 > with suggestions for new or
3649     improved filters is particularly welcome!
3650    </P
3651 ><P
3652 >    The below list has only the names and a one-line description of each
3653     predefined filter. There are <A
3654 HREF="filter-file.html#PREDEFINED-FILTERS"
3655 >more
3656     verbose explanations</A
3657 > of what these filters do in the <A
3658 HREF="filter-file.html"
3659 >filter file chapter</A
3660 >.
3661    </P
3662 ></DD
3663 ><DT
3664 >Example usage (with filters from the distribution <TT
3665 CLASS="FILENAME"
3666 >default.filter</TT
3667 > file).
3668   See <A
3669 HREF="filter-file.html#PREDEFINED-FILTERS"
3670 >the Predefined Filters section</A
3671 > for 
3672   more explanation on each:</DT
3673 ><DD
3674 ><P
3675 >    <A
3676 NAME="FILTER-JS-ANNOYANCES"
3677 ></A
3678 >
3679     <TABLE
3680 BORDER="0"
3681 BGCOLOR="#E0E0E0"
3682 WIDTH="90%"
3683 ><TR
3684 ><TD
3685 ><PRE
3686 CLASS="SCREEN"
3687 >+filter{js-annoyances}       # Get rid of particularly annoying JavaScript abuse.</PRE
3688 ></TD
3689 ></TR
3690 ></TABLE
3691 >
3692    </P
3693 ><P
3694 >    <A
3695 NAME="FILTER-JS-EVENTS"
3696 ></A
3697 >
3698     <TABLE
3699 BORDER="0"
3700 BGCOLOR="#E0E0E0"
3701 WIDTH="90%"
3702 ><TR
3703 ><TD
3704 ><PRE
3705 CLASS="SCREEN"
3706 >+filter{js-events}           # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).</PRE
3707 ></TD
3708 ></TR
3709 ></TABLE
3710 >
3711    </P
3712 ><P
3713 >    <A
3714 NAME="FILTER-HTML-ANNOYANCES"
3715 ></A
3716 >
3717     <TABLE
3718 BORDER="0"
3719 BGCOLOR="#E0E0E0"
3720 WIDTH="90%"
3721 ><TR
3722 ><TD
3723 ><PRE
3724 CLASS="SCREEN"
3725 >+filter{html-annoyances}     # Get rid of particularly annoying HTML abuse.</PRE
3726 ></TD
3727 ></TR
3728 ></TABLE
3729 >
3730    </P
3731 ><P
3732 >    <A
3733 NAME="FILTER-CONTENT-COOKIES"
3734 ></A
3735 >
3736     <TABLE
3737 BORDER="0"
3738 BGCOLOR="#E0E0E0"
3739 WIDTH="90%"
3740 ><TR
3741 ><TD
3742 ><PRE
3743 CLASS="SCREEN"
3744 >+filter{content-cookies}     # Kill cookies that come in the HTML or JS content.</PRE
3745 ></TD
3746 ></TR
3747 ></TABLE
3748 >
3749    </P
3750 ><P
3751 >    <A
3752 NAME="FILTER-REFRESH-TAGS"
3753 ></A
3754 >
3755     <TABLE
3756 BORDER="0"
3757 BGCOLOR="#E0E0E0"
3758 WIDTH="90%"
3759 ><TR
3760 ><TD
3761 ><PRE
3762 CLASS="SCREEN"
3763 >+filter{refresh-tags}        # Kill automatic refresh tags (for dial-on-demand setups).</PRE
3764 ></TD
3765 ></TR
3766 ></TABLE
3767 >
3768    </P
3769 ><P
3770 >    <A
3771 NAME="FILTER-UNSOLICITED-POPUPS"
3772 ></A
3773 >
3774     <TABLE
3775 BORDER="0"
3776 BGCOLOR="#E0E0E0"
3777 WIDTH="90%"
3778 ><TR
3779 ><TD
3780 ><PRE
3781 CLASS="SCREEN"
3782 >+filter{unsolicited-popups}  # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.</PRE
3783 ></TD
3784 ></TR
3785 ></TABLE
3786 >
3787    </P
3788 ><P
3789 >    <A
3790 NAME="FILTER-ALL-POPUPS"
3791 ></A
3792 >
3793     <TABLE
3794 BORDER="0"
3795 BGCOLOR="#E0E0E0"
3796 WIDTH="90%"
3797 ><TR
3798 ><TD
3799 ><PRE
3800 CLASS="SCREEN"
3801 >+filter{all-popups}          # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.</PRE
3802 ></TD
3803 ></TR
3804 ></TABLE
3805 >
3806    </P
3807 ><P
3808 >    <A
3809 NAME="FILTER-IMG-REORDER"
3810 ></A
3811 >
3812     <TABLE
3813 BORDER="0"
3814 BGCOLOR="#E0E0E0"
3815 WIDTH="90%"
3816 ><TR
3817 ><TD
3818 ><PRE
3819 CLASS="SCREEN"
3820 >+filter{img-reorder}         # Reorder attributes in &#60;img&#62; tags to make the banners-by-* filters more effective.</PRE
3821 ></TD
3822 ></TR
3823 ></TABLE
3824 >
3825    </P
3826 ><P
3827 >    <A
3828 NAME="FILTER-BANNERS-BY-SIZE"
3829 ></A
3830 >
3831     <TABLE
3832 BORDER="0"
3833 BGCOLOR="#E0E0E0"
3834 WIDTH="90%"
3835 ><TR
3836 ><TD
3837 ><PRE
3838 CLASS="SCREEN"
3839 >+filter{banners-by-size}     # Kill banners by size.</PRE
3840 ></TD
3841 ></TR
3842 ></TABLE
3843 >
3844    </P
3845 ><P
3846 >    <A
3847 NAME="FILTER-BANNERS-BY-LINK"
3848 ></A
3849 >