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