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