doc/webserver/user-manual/filter-file.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
   2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4   <head>
   5     <meta name="generator" content="HTML Tidy, see www.w3.org">
   6     <title>
   7       Filter Files
   8     </title>
   9     <meta name="GENERATOR" content=
  10     "Modular DocBook HTML Stylesheet Version 1.79">
  11     <link rel="HOME" title="Privoxy 3.0.18 User Manual" href="index.html">
  12     <link rel="PREVIOUS" title="Actions Files" href="actions-file.html">
  13     <link rel="NEXT" title="Privoxy's Template Files" href="templates.html">
  14     <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
  15     <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  16     <link rel="STYLESHEET" type="text/css" href="p_doc.css">
  17 <style type="text/css">
  18  body {
  19   background-color: #EEEEEE;
  20   color: #000000;
  21  }
  22  :link { color: #0000FF }
  23  :visited { color: #840084 }
  24  :active { color: #0000FF }
  25  hr.c1 {text-align: left}
  26 </style>
  27   </head>
  28   <body class="SECT1">
  29     <div class="NAVHEADER">
  30       <table summary="Header navigation table" width="100%" border="0"
  31       cellpadding="0" cellspacing="0">
  32         <tr>
  33           <th colspan="3" align="center">
  34             Privoxy 3.0.18 User Manual
  35           </th>
  36         </tr>
  37         <tr>
  38           <td width="10%" align="left" valign="bottom">
  39             <a href="actions-file.html" accesskey="P">Prev</a>
  40           </td>
  41           <td width="80%" align="center" valign="bottom">
  42           </td>
  43           <td width="10%" align="right" valign="bottom">
  44             <a href="templates.html" accesskey="N">Next</a>
  45           </td>
  46         </tr>
  47       </table>
  48       <hr width="100%" class="c1">
  49     </div>
  50     <div class="SECT1">
  51       <h1 class="SECT1">
  52         <a name="FILTER-FILE">9. Filter Files</a>
  53       </h1>
  54       <p>
  55         On-the-fly text substitutions need to be defined in a <span class=
  56         "QUOTE">"filter file"</span>. Once defined, they can then be invoked
  57         as an <span class="QUOTE">"action"</span>.
  58       </p>
  59       <p>
  60         <span class="APPLICATION">Privoxy</span> supports three different
  61         filter actions: <tt class="LITERAL"><a href=
  62         "actions-file.html#FILTER">filter</a></tt> to rewrite the content
  63         that is send to the client, <tt class="LITERAL"><a href=
  64         "actions-file.html#CLIENT-HEADER-FILTER">client-header-filter</a></tt>
  65         to rewrite headers that are send by the client, and <tt class=
  66         "LITERAL"><a href=
  67         "actions-file.html#SERVER-HEADER-FILTER">server-header-filter</a></tt>
  68         to rewrite headers that are send by the server.
  69       </p>
  70       <p>
  71         <span class="APPLICATION">Privoxy</span> also supports two tagger
  72         actions: <tt class="LITERAL"><a href=
  73         "actions-file.html#CLIENT-HEADER-TAGGER">client-header-tagger</a></tt>
  74         and <tt class="LITERAL"><a href=
  75         "actions-file.html#SERVER-HEADER-TAGGER">server-header-tagger</a></tt>.
  76         Taggers and filters use the same syntax in the filter files, the
  77         difference is that taggers don't modify the text they are filtering,
  78         but use a rewritten version of the filtered text as tag. The tags can
  79         then be used to change the applying actions through sections with <a
  80         href="actions-file.html#TAG-PATTERN">tag-patterns</a>.
  81       </p>
  82       <p>
  83         Multiple filter files can be defined through the <tt class=
  84         "LITERAL"><a href="config.html#FILTERFILE">filterfile</a></tt> config
  85         directive. The filters as supplied by the developers are located in
  86         <tt class="FILENAME">default.filter</tt>. It is recommended that any
  87         locally defined or modified filters go in a separately defined file
  88         such as <tt class="FILENAME">user.filter</tt>.
  89       </p>
  90       <p>
  91         Common tasks for content filters are to eliminate common annoyances
  92         in HTML and JavaScript, such as pop-up windows, exit consoles,
  93         crippled windows without navigation tools, the infamous &lt;BLINK&gt;
  94         tag etc, to suppress images with certain width and height attributes
  95         (standard banner sizes or web-bugs), or just to have fun.
  96       </p>
  97       <p>
  98         Enabled content filters are applied to any content whose <span class=
  99         "QUOTE">"Content Type"</span> header is recognised as a sign of
 100         text-based content, with the exception of <tt class=
 101         "LITERAL">text/plain</tt>. Use the <a href=
 102         "actions-file.html#FORCE-TEXT-MODE">force-text-mode</a> action to
 103         also filter other content.
 104       </p>
 105       <p>
 106         Substitutions are made at the source level, so if you want to <span
 107         class="QUOTE">"roll your own"</span> filters, you should first be
 108         familiar with HTML syntax, and, of course, regular expressions.
 109       </p>
 110       <p>
 111         Just like the <a href="actions-file.html">actions files</a>, the
 112         filter file is organized in sections, which are called <span class=
 113         "emphasis"><i class="EMPHASIS">filters</i></span> here. Each filter
 114         consists of a heading line, that starts with one of the <span class=
 115         "emphasis"><i class="EMPHASIS">keywords</i></span> <tt class=
 116         "LITERAL">FILTER:</tt>, <tt class=
 117         "LITERAL">CLIENT-HEADER-FILTER:</tt> or <tt class=
 118         "LITERAL">SERVER-HEADER-FILTER:</tt> followed by the filter's <span
 119         class="emphasis"><i class="EMPHASIS">name</i></span>, and a short
 120         (one line) <span class="emphasis"><i class=
 121         "EMPHASIS">description</i></span> of what it does. Below that line
 122         come the <span class="emphasis"><i class="EMPHASIS">jobs</i></span>,
 123         i.e. lines that define the actual text substitutions. By convention,
 124         the name of a filter should describe what the filter <span class=
 125         "emphasis"><i class="EMPHASIS">eliminates</i></span>. The comment is
 126         used in the <a href="http://config.privoxy.org/" target=
 127         "_top">web-based user interface</a>.
 128       </p>
 129       <p>
 130         Once a filter called <tt class="REPLACEABLE"><i>name</i></tt> has
 131         been defined in the filter file, it can be invoked by using an action
 132         of the form +<tt class="LITERAL"><a href=
 133         "actions-file.html#FILTER">filter</a>{<tt class=
 134         "REPLACEABLE"><i>name</i></tt>}</tt> in any <a href=
 135         "actions-file.html">actions file</a>.
 136       </p>
 137       <p>
 138         Filter definitions start with a header line that contains the filter
 139         type, the filter name and the filter description. A content filter
 140         header line for a filter called <span class="QUOTE">"foo"</span>
 141         could look like this:
 142       </p>
 143       <p>
 144       </p>
 145       <table border="0" bgcolor="#E0E0E0" width="100%">
 146         <tr>
 147           <td>
 148 <pre class="SCREEN">
 149 FILTER: foo Replace all "foo" with "bar"
 150 </pre>
 151           </td>
 152         </tr>
 153       </table>
 154
 155       <p>
 156         Below that line, and up to the next header line, come the jobs that
 157         define what text replacements the filter executes. They are specified
 158         in a syntax that imitates <a href="http://www.perl.org/" target=
 159         "_top">Perl</a>'s <tt class="LITERAL">s///</tt> operator. If you are
 160         familiar with Perl, you will find this to be quite intuitive, and may
 161         want to look at the PCRS documentation for the subtle differences to
 162         Perl behaviour. Most notably, the non-standard option letter <tt
 163         class="LITERAL">U</tt> is supported, which turns the default to
 164         ungreedy matching.
 165       </p>
 166       <p>
 167         If you are new to <a href=
 168         "http://en.wikipedia.org/wiki/Regular_expressions" target=
 169         "_top"><span class="QUOTE">"Regular Expressions"</span></a>, you
 170         might want to take a look at the <a href=
 171         "appendix.html#REGEX">Appendix on regular expressions</a>, and see
 172         the <a href="http://perldoc.perl.org/perlre.html" target="_top">Perl
 173         manual</a> for <a href="http://perldoc.perl.org/perlop.html" target=
 174         "_top">the <tt class="LITERAL">s///</tt> operator's syntax</a> and <a
 175         href="http://perldoc.perl.org/perlre.html" target="_top">Perl-style
 176         regular expressions</a> in general. The below examples might also
 177         help to get you started.
 178       </p>
 179       <div class="SECT2">
 180         <h2 class="SECT2">
 181           <a name="AEN4903">9.1. Filter File Tutorial</a>
 182         </h2>
 183         <p>
 184           Now, let's complete our <span class="QUOTE">"foo"</span> content
 185           filter. We have already defined the heading, but the jobs are still
 186           missing. Since all it does is to replace <span class=
 187           "QUOTE">"foo"</span> with <span class="QUOTE">"bar"</span>, there
 188           is only one (trivial) job needed:
 189         </p>
 190         <p>
 191         </p>
 192         <table border="0" bgcolor="#E0E0E0" width="100%">
 193           <tr>
 194             <td>
 195 <pre class="SCREEN">
 196 s/foo/bar/
 197 </pre>
 198             </td>
 199           </tr>
 200         </table>
 201
 202         <p>
 203           But wait! Didn't the comment say that <span class="emphasis"><i
 204           class="EMPHASIS">all</i></span> occurrences of <span class=
 205           "QUOTE">"foo"</span> should be replaced? Our current job will only
 206           take care of the first <span class="QUOTE">"foo"</span> on each
 207           page. For global substitution, we'll need to add the <tt class=
 208           "LITERAL">g</tt> option:
 209         </p>
 210         <p>
 211         </p>
 212         <table border="0" bgcolor="#E0E0E0" width="100%">
 213           <tr>
 214             <td>
 215 <pre class="SCREEN">
 216 s/foo/bar/g
 217 </pre>
 218             </td>
 219           </tr>
 220         </table>
 221
 222         <p>
 223           Our complete filter now looks like this:
 224         </p>
 225         <p>
 226         </p>
 227         <table border="0" bgcolor="#E0E0E0" width="100%">
 228           <tr>
 229             <td>
 230 <pre class="SCREEN">
 231 FILTER: foo Replace all "foo" with "bar"
 232 s/foo/bar/g
 233 </pre>
 234             </td>
 235           </tr>
 236         </table>
 237
 238         <p>
 239           Let's look at some real filters for more interesting examples. Here
 240           you see a filter that protects against some common annoyances that
 241           arise from JavaScript abuse. Let's look at its jobs one after the
 242           other:
 243         </p>
 244         <p>
 245         </p>
 246         <table border="0" bgcolor="#E0E0E0" width="100%">
 247           <tr>
 248             <td>
 249 <pre class="SCREEN">
 250 FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse
 251
 252 # Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm
 253 #
 254 s|(&lt;script.*)document\.referrer(.*&lt;/script&gt;)|$1"Not Your Business!"$2|Usg
 255 </pre>
 256             </td>
 257           </tr>
 258         </table>
 259
 260         <p>
 261           Following the header line and a comment, you see the job. Note that
 262           it uses <tt class="LITERAL">|</tt> as the delimiter instead of <tt
 263           class="LITERAL">/</tt>, because the pattern contains a forward
 264           slash, which would otherwise have to be escaped by a backslash (<tt
 265           class="LITERAL">\</tt>).
 266         </p>
 267         <p>
 268           Now, let's examine the pattern: it starts with the text <tt class=
 269           "LITERAL">&lt;script.*</tt> enclosed in parentheses. Since the dot
 270           matches any character, and <tt class="LITERAL">*</tt> means: <span
 271           class="QUOTE">"Match an arbitrary number of the element left of
 272           myself"</span>, this matches <span class=
 273           "QUOTE">"&lt;script"</span>, followed by <span class="emphasis"><i
 274           class="EMPHASIS">any</i></span> text, i.e. it matches the whole
 275           page, from the start of the first &lt;script&gt; tag.
 276         </p>
 277         <p>
 278           That's more than we want, but the pattern continues: <tt class=
 279           "LITERAL">document\.referrer</tt> matches only the exact string
 280           <span class="QUOTE">"document.referrer"</span>. The dot needed to
 281           be <span class="emphasis"><i class="EMPHASIS">escaped</i></span>,
 282           i.e. preceded by a backslash, to take away its special meaning as a
 283           joker, and make it just a regular dot. So far, the meaning is:
 284           Match from the start of the first &lt;script&gt; tag in a the page,
 285           up to, and including, the text <span class=
 286           "QUOTE">"document.referrer"</span>, if <span class="emphasis"><i
 287           class="EMPHASIS">both</i></span> are present in the page (and
 288           appear in that order).
 289         </p>
 290         <p>
 291           But there's still more pattern to go. The next element, again
 292           enclosed in parentheses, is <tt class=
 293           "LITERAL">.*&lt;/script&gt;</tt>. You already know what <tt class=
 294           "LITERAL">.*</tt> means, so the whole pattern translates to: Match
 295           from the start of the first &lt;script&gt; tag in a page to the end
 296           of the last &lt;script&gt; tag, provided that the text <span class=
 297           "QUOTE">"document.referrer"</span> appears somewhere in between.
 298         </p>
 299         <p>
 300           This is still not the whole story, since we have ignored the
 301           options and the parentheses: The portions of the page matched by
 302           sub-patterns that are enclosed in parentheses, will be remembered
 303           and be available through the variables <tt class="LITERAL">$1, $2,
 304           ...</tt> in the substitute. The <tt class="LITERAL">U</tt> option
 305           switches to ungreedy matching, which means that the first <tt
 306           class="LITERAL">.*</tt> in the pattern will only <span class=
 307           "QUOTE">"eat up"</span> all text in between <span class=
 308           "QUOTE">"&lt;script"</span> and the <span class="emphasis"><i
 309           class="EMPHASIS">first</i></span> occurrence of <span class=
 310           "QUOTE">"document.referrer"</span>, and that the second <tt class=
 311           "LITERAL">.*</tt> will only span the text up to the <span class=
 312           "emphasis"><i class="EMPHASIS">first</i></span> <span class=
 313           "QUOTE">"&lt;/script&gt;"</span> tag. Furthermore, the <tt class=
 314           "LITERAL">s</tt> option says that the match may span multiple lines
 315           in the page, and the <tt class="LITERAL">g</tt> option again means
 316           that the substitution is global.
 317         </p>
 318         <p>
 319           So, to summarize, the pattern means: Match all scripts that contain
 320           the text <span class="QUOTE">"document.referrer"</span>. Remember
 321           the parts of the script from (and including) the start tag up to
 322           (and excluding) the string <span class=
 323           "QUOTE">"document.referrer"</span> as <tt class="LITERAL">$1</tt>,
 324           and the part following that string, up to and including the closing
 325           tag, as <tt class="LITERAL">$2</tt>.
 326         </p>
 327         <p>
 328           Now the pattern is deciphered, but wasn't this about substituting
 329           things? So lets look at the substitute: <tt class="LITERAL">$1"Not
 330           Your Business!"$2</tt> is easy to read: The text remembered as <tt
 331           class="LITERAL">$1</tt>, followed by <tt class="LITERAL">"Not Your
 332           Business!"</tt> (<span class="emphasis"><i class=
 333           "EMPHASIS">including</i></span> the quotation marks!), followed by
 334           the text remembered as <tt class="LITERAL">$2</tt>. This produces
 335           an exact copy of the original string, with the middle part (the
 336           <span class="QUOTE">"document.referrer"</span>) replaced by <tt
 337           class="LITERAL">"Not Your Business!"</tt>.
 338         </p>
 339         <p>
 340           The whole job now reads: Replace <span class=
 341           "QUOTE">"document.referrer"</span> by <tt class="LITERAL">"Not Your
 342           Business!"</tt> wherever it appears inside a &lt;script&gt; tag.
 343           Note that this job won't break JavaScript syntax, since both the
 344           original and the replacement are syntactically valid string
 345           objects. The script just won't have access to the referrer
 346           information anymore.
 347         </p>
 348         <p>
 349           We'll show you two other jobs from the JavaScript taming
 350           department, but this time only point out the constructs of special
 351           interest:
 352         </p>
 353         <p>
 354         </p>
 355         <table border="0" bgcolor="#E0E0E0" width="100%">
 356           <tr>
 357             <td>
 358 <pre class="SCREEN">
 359 # The status bar is for displaying link targets, not pointless blahblah
 360 #
 361 s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig
 362 </pre>
 363             </td>
 364           </tr>
 365         </table>
 366
 367         <p>
 368           <tt class="LITERAL">\s</tt> stands for whitespace characters
 369           (space, tab, newline, carriage return, form feed), so that <tt
 370           class="LITERAL">\s*</tt> means: <span class="QUOTE">"zero or more
 371           whitespace"</span>. The <tt class="LITERAL">?</tt> in <tt class=
 372           "LITERAL">.*?</tt> makes this matching of arbitrary text ungreedy.
 373           (Note that the <tt class="LITERAL">U</tt> option is not set). The
 374           <tt class="LITERAL">['"]</tt> construct means: <span class=
 375           "QUOTE">"a single <span class="emphasis"><i class=
 376           "EMPHASIS">or</i></span> a double quote"</span>. Finally, <tt
 377           class="LITERAL">\1</tt> is a back-reference to the first
 378           parenthesis just like <tt class="LITERAL">$1</tt> above, with the
 379           difference that in the <span class="emphasis"><i class=
 380           "EMPHASIS">pattern</i></span>, a backslash indicates a
 381           back-reference, whereas in the <span class="emphasis"><i class=
 382           "EMPHASIS">substitute</i></span>, it's the dollar.
 383         </p>
 384         <p>
 385           So what does this job do? It replaces assignments of single- or
 386           double-quoted strings to the <span class=
 387           "QUOTE">"window.status"</span> object with a dummy assignment
 388           (using a variable name that is hopefully odd enough not to conflict
 389           with real variables in scripts). Thus, it catches many cases where
 390           e.g. pointless descriptions are displayed in the status bar instead
 391           of the link target when you move your mouse over links.
 392         </p>
 393         <p>
 394         </p>
 395         <table border="0" bgcolor="#E0E0E0" width="100%">
 396           <tr>
 397             <td>
 398 <pre class="SCREEN">
 399 # Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
 400 #
 401 s/(&lt;body [^&gt;]*)onunload(.*&gt;)/$1never$2/iU
 402 </pre>
 403             </td>
 404           </tr>
 405         </table>
 406
 407         <p>
 408           Including the <a href=
 409           "http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents"
 410            target="_top">OnUnload event binding</a> in the HTML DOM was a
 411           <span class="emphasis"><i class="EMPHASIS">CRIME</i></span>. When I
 412           close a browser window, I want it to close and die. Basta. This job
 413           replaces the <span class="QUOTE">"onunload"</span> attribute in
 414           <span class="QUOTE">"&lt;body&gt;"</span> tags with the dummy word
 415           <tt class="LITERAL">never</tt>. Note that the <tt class=
 416           "LITERAL">i</tt> option makes the pattern matching
 417           case-insensitive. Also note that ungreedy matching alone doesn't
 418           always guarantee a minimal match: In the first parenthesis, we had
 419           to use <tt class="LITERAL">[^&gt;]*</tt> instead of <tt class=
 420           "LITERAL">.*</tt> to prevent the match from exceeding the
 421           &lt;body&gt; tag if it doesn't contain <span class=
 422           "QUOTE">"OnUnload"</span>, but the page's content does.
 423         </p>
 424         <p>
 425           The last example is from the fun department:
 426         </p>
 427         <p>
 428         </p>
 429         <table border="0" bgcolor="#E0E0E0" width="100%">
 430           <tr>
 431             <td>
 432 <pre class="SCREEN">
 433 FILTER: fun Fun text replacements
 434
 435 # Spice the daily news:
 436 #
 437 s/microsoft(?!\.com)/MicroSuck/ig
 438 </pre>
 439             </td>
 440           </tr>
 441         </table>
 442
 443         <p>
 444           Note the <tt class="LITERAL">(?!\.com)</tt> part (a so-called
 445           negative lookahead) in the job's pattern, which means: Don't match,
 446           if the string <span class="QUOTE">".com"</span> appears directly
 447           following <span class="QUOTE">"microsoft"</span> in the page. This
 448           prevents links to microsoft.com from being trashed, while still
 449           replacing the word everywhere else.
 450         </p>
 451         <p>
 452         </p>
 453         <table border="0" bgcolor="#E0E0E0" width="100%">
 454           <tr>
 455             <td>
 456 <pre class="SCREEN">
 457 # Buzzword Bingo (example for extended regex syntax)
 458 #
 459 s* industry[ -]leading \
 460 |  cutting[ -]edge \
 461 |  customer[ -]focused \
 462 |  market[ -]driven \
 463 |  award[ -]winning # Comments are OK, too! \
 464 |  high[ -]performance \
 465 |  solutions[ -]based \
 466 |  unmatched \
 467 |  unparalleled \
 468 |  unrivalled \
 469 *&lt;font color="red"&gt;&lt;b&gt;BINGO!&lt;/b&gt;&lt;/font&gt; \
 470 *igx
 471 </pre>
 472             </td>
 473           </tr>
 474         </table>
 475
 476         <p>
 477           The <tt class="LITERAL">x</tt> option in this job turns on extended
 478           syntax, and allows for e.g. the liberal use of (non-interpreted!)
 479           whitespace for nicer formatting.
 480         </p>
 481         <p>
 482           You get the idea?
 483         </p>
 484       </div>
 485       <div class="SECT2">
 486         <h2 class="SECT2">
 487           <a name="PREDEFINED-FILTERS">9.2. The Pre-defined Filters</a>
 488         </h2>
 489         <p>
 490           The distribution <tt class="FILENAME">default.filter</tt> file
 491           contains a selection of pre-defined filters for your convenience:
 492         </p>
 493         <div class="VARIABLELIST">
 494           <dl>
 495             <dt>
 496               <span class="emphasis"><i class=
 497               "EMPHASIS">js-annoyances</i></span>
 498             </dt>
 499             <dd>
 500               <p>
 501                 The purpose of this filter is to get rid of particularly
 502                 annoying JavaScript abuse. To that end, it
 503               </p>
 504               <ul>
 505                 <li>
 506                   <p>
 507                     replaces JavaScript references to the browser's referrer
 508                     information with the string "Not Your Business!". This
 509                     compliments the <tt class="LITERAL"><a href=
 510                     "actions-file.html#HIDE-REFERRER">hide-referrer</a></tt>
 511                     action on the content level.
 512                   </p>
 513                 </li>
 514                 <li>
 515                   <p>
 516                     removes the bindings to the DOM's <a href=
 517                     "http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents"
 518                      target="_top">unload event</a> which we feel has no
 519                     right to exist and is responsible for most <span class=
 520                     "QUOTE">"exit consoles"</span>, i.e. nasty windows that
 521                     pop up when you close another one.
 522                   </p>
 523                 </li>
 524                 <li>
 525                   <p>
 526                     removes code that causes new windows to be opened with
 527                     undesired properties, such as being full-screen,
 528                     non-resizeable, without location, status or menu bar etc.
 529                   </p>
 530                 </li>
 531               </ul>
 532
 533               <p>
 534                 Use with caution. This is an aggressive filter, and can break
 535                 sites that rely heavily on JavaScript.
 536               </p>
 537             </dd>
 538             <dt>
 539               <span class="emphasis"><i class="EMPHASIS">js-events</i></span>
 540             </dt>
 541             <dd>
 542               <p>
 543                 This is a very radical measure. It removes virtually all
 544                 JavaScript event bindings, which means that scripts can not
 545                 react to user actions such as mouse movements or clicks,
 546                 window resizing etc, anymore. Use with caution!
 547               </p>
 548               <p>
 549                 We <span class="emphasis"><i class="EMPHASIS">strongly
 550                 discourage</i></span> using this filter as a default since it
 551                 breaks many legitimate scripts. It is meant for use only on
 552                 extra-nasty sites (should you really need to go there).
 553               </p>
 554             </dd>
 555             <dt>
 556               <span class="emphasis"><i class=
 557               "EMPHASIS">html-annoyances</i></span>
 558             </dt>
 559             <dd>
 560               <p>
 561                 This filter will undo many common instances of HTML based
 562                 abuse.
 563               </p>
 564               <p>
 565                 The <tt class="LITERAL">BLINK</tt> and <tt class=
 566                 "LITERAL">MARQUEE</tt> tags are neutralized (yeah baby!), and
 567                 browser windows will be created as resizeable (as of course
 568                 they should be!), and will have location, scroll and menu
 569                 bars -- even if specified otherwise.
 570               </p>
 571             </dd>
 572             <dt>
 573               <span class="emphasis"><i class=
 574               "EMPHASIS">content-cookies</i></span>
 575             </dt>
 576             <dd>
 577               <p>
 578                 Most cookies are set in the HTTP dialog, where they can be
 579                 intercepted by the <tt class="LITERAL"><a href=
 580                 "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a></tt>
 581                 and <tt class="LITERAL"><a href=
 582                 "actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a></tt>
 583                 actions. But web sites increasingly make use of HTML meta
 584                 tags and JavaScript to sneak cookies to the browser on the
 585                 content level.
 586               </p>
 587               <p>
 588                 This filter disables most HTML and JavaScript code that reads
 589                 or sets cookies. It cannot detect all clever uses of these
 590                 types of code, so it should not be relied on as an absolute
 591                 fix. Use it wherever you would also use the cookie crunch
 592                 actions.
 593               </p>
 594             </dd>
 595             <dt>
 596               <span class="emphasis"><i class="EMPHASIS">refresh
 597               tags</i></span>
 598             </dt>
 599             <dd>
 600               <p>
 601                 Disable any refresh tags if the interval is greater than nine
 602                 seconds (so that redirections done via refresh tags are not
 603                 destroyed). This is useful for dial-on-demand setups, or for
 604                 those who find this HTML feature annoying.
 605               </p>
 606             </dd>
 607             <dt>
 608               <span class="emphasis"><i class=
 609               "EMPHASIS">unsolicited-popups</i></span>
 610             </dt>
 611             <dd>
 612               <p>
 613                 This filter attempts to prevent only <span class=
 614                 "QUOTE">"unsolicited"</span> pop-up windows from opening, yet
 615                 still allow pop-up windows that the user has explicitly
 616                 chosen to open. It was added in version 3.0.1, as an
 617                 improvement over earlier such filters.
 618               </p>
 619               <p>
 620                 Technical note: The filter works by redefining the
 621                 window.open JavaScript function to a dummy function, <tt
 622                 class="LITERAL">PrivoxyWindowOpen()</tt>, during the loading
 623                 and rendering phase of each HTML page access, and restoring
 624                 the function afterward.
 625               </p>
 626               <p>
 627                 This is recommended only for browsers that cannot perform
 628                 this function reliably themselves. And be aware that some
 629                 sites require such windows in order to function normally. Use
 630                 with caution.
 631               </p>
 632             </dd>
 633             <dt>
 634               <span class="emphasis"><i class=
 635               "EMPHASIS">all-popups</i></span>
 636             </dt>
 637             <dd>
 638               <p>
 639                 Attempt to prevent <span class="emphasis"><i class=
 640                 "EMPHASIS">all</i></span> pop-up windows from opening. Note
 641                 this should be used with even more discretion than the above,
 642                 since it is more likely to break some sites that require
 643                 pop-ups for normal usage. Use with caution.
 644               </p>
 645             </dd>
 646             <dt>
 647               <span class="emphasis"><i class=
 648               "EMPHASIS">img-reorder</i></span>
 649             </dt>
 650             <dd>
 651               <p>
 652                 This is a helper filter that has no value if used alone. It
 653                 makes the <tt class="LITERAL">banners-by-size</tt> and <tt
 654                 class="LITERAL">banners-by-link</tt> (see below) filters more
 655                 effective and should be enabled together with them.
 656               </p>
 657             </dd>
 658             <dt>
 659               <span class="emphasis"><i class=
 660               "EMPHASIS">banners-by-size</i></span>
 661             </dt>
 662             <dd>
 663               <p>
 664                 This filter removes image tags purely based on what size they
 665                 are. Fortunately for us, many ads and banner images tend to
 666                 conform to certain standardized sizes, which makes this
 667                 filter quite effective for ad stripping purposes.
 668               </p>
 669               <p>
 670                 Occasionally this filter will cause false positives on images
 671                 that are not ads, but just happen to be of one of the
 672                 standard banner sizes.
 673               </p>
 674               <p>
 675                 Recommended only for those who require extreme ad blocking.
 676                 The default block rules should catch 95+% of all ads <span
 677                 class="emphasis"><i class="EMPHASIS">without</i></span> this
 678                 filter enabled.
 679               </p>
 680             </dd>
 681             <dt>
 682               <span class="emphasis"><i class=
 683               "EMPHASIS">banners-by-link</i></span>
 684             </dt>
 685             <dd>
 686               <p>
 687                 This is an experimental filter that attempts to kill any
 688                 banners if their URLs seem to point to known or suspected
 689                 click trackers. It is currently not of much value and is not
 690                 recommended for use by default.
 691               </p>
 692             </dd>
 693             <dt>
 694               <span class="emphasis"><i class="EMPHASIS">webbugs</i></span>
 695             </dt>
 696             <dd>
 697               <p>
 698                 Webbugs are small, invisible images (technically 1X1 GIF
 699                 images), that are used to track users across websites, and
 700                 collect information on them. As an HTML page is loaded by the
 701                 browser, an embedded image tag causes the browser to contact
 702                 a third-party site, disclosing the tracking information
 703                 through the requested URL and/or cookies for that third-party
 704                 domain, without the user ever becoming aware of the
 705                 interaction with the third-party site. HTML-ized spam also
 706                 uses a similar technique to verify email addresses.
 707               </p>
 708               <p>
 709                 This filter removes the HTML code that loads such <span
 710                 class="QUOTE">"webbugs"</span>.
 711               </p>
 712             </dd>
 713             <dt>
 714               <span class="emphasis"><i class=
 715               "EMPHASIS">tiny-textforms</i></span>
 716             </dt>
 717             <dd>
 718               <p>
 719                 A rather special-purpose filter that can be used to enlarge
 720                 textareas (those multi-line text boxes in web forms) and turn
 721                 off hard word wrap in them. It was written for the
 722                 sourceforge.net tracker system where such boxes are a
 723                 nuisance, but it can be handy on other sites, too.
 724               </p>
 725               <p>
 726                 It is not recommended to use this filter as a default.
 727               </p>
 728             </dd>
 729             <dt>
 730               <span class="emphasis"><i class=
 731               "EMPHASIS">jumping-windows</i></span>
 732             </dt>
 733             <dd>
 734               <p>
 735                 Many consider windows that move, or resize themselves to be
 736                 abusive. This filter neutralizes the related JavaScript code.
 737                 Note that some sites might not display or behave as intended
 738                 when using this filter. Use with caution.
 739               </p>
 740             </dd>
 741             <dt>
 742               <span class="emphasis"><i class=
 743               "EMPHASIS">frameset-borders</i></span>
 744             </dt>
 745             <dd>
 746               <p>
 747                 Some web designers seem to assume that everyone in the world
 748                 will view their web sites using the same browser brand and
 749                 version, screen resolution etc, because only that assumption
 750                 could explain why they'd use static frame sizes, yet prevent
 751                 their frames from being resized by the user, should they be
 752                 too small to show their whole content.
 753               </p>
 754               <p>
 755                 This filter removes the related HTML code. It should only be
 756                 applied to sites which need it.
 757               </p>
 758             </dd>
 759             <dt>
 760               <span class="emphasis"><i class=
 761               "EMPHASIS">demoronizer</i></span>
 762             </dt>
 763             <dd>
 764               <p>
 765                 Many Microsoft products that generate HTML use non-standard
 766                 extensions (read: violations) of the ISO 8859-1 aka Latin-1
 767                 character set. This can cause those HTML documents to display
 768                 with errors on standard-compliant platforms.
 769               </p>
 770               <p>
 771                 This filter translates the MS-only characters into Latin-1
 772                 equivalents. It is not necessary when using MS products, and
 773                 will cause corruption of all documents that use 8-bit
 774                 character sets other than Latin-1. It's mostly worthwhile for
 775                 Europeans on non-MS platforms, if weird garbage characters
 776                 sometimes appear on some pages, or user agents that don't
 777                 correct for this on the fly.
 778               </p>
 779             </dd>
 780             <dt>
 781               <span class="emphasis"><i class=
 782               "EMPHASIS">shockwave-flash</i></span>
 783             </dt>
 784             <dd>
 785               <p>
 786                 A filter for shockwave haters. As the name suggests, this
 787                 filter strips code out of web pages that is used to embed
 788                 shockwave flash objects.
 789               </p>
 790               <p>
 791               </p>
 792             </dd>
 793             <dt>
 794               <span class="emphasis"><i class=
 795               "EMPHASIS">quicktime-kioskmode</i></span>
 796             </dt>
 797             <dd>
 798               <p>
 799                 Change HTML code that embeds Quicktime objects so that
 800                 kioskmode, which prevents saving, is disabled.
 801               </p>
 802             </dd>
 803             <dt>
 804               <span class="emphasis"><i class="EMPHASIS">fun</i></span>
 805             </dt>
 806             <dd>
 807               <p>
 808                 Text replacements for subversive browsing fun. Make fun of
 809                 your favorite Monopolist or play buzzword bingo.
 810               </p>
 811             </dd>
 812             <dt>
 813               <span class="emphasis"><i class=
 814               "EMPHASIS">crude-parental</i></span>
 815             </dt>
 816             <dd>
 817               <p>
 818                 A demonstration-only filter that shows how <span class=
 819                 "APPLICATION">Privoxy</span> can be used to delete web
 820                 content on a keyword basis.
 821               </p>
 822             </dd>
 823             <dt>
 824               <span class="emphasis"><i class=
 825               "EMPHASIS">ie-exploits</i></span>
 826             </dt>
 827             <dd>
 828               <p>
 829                 An experimental collection of text replacements to disable
 830                 malicious HTML and JavaScript code that exploits known
 831                 security holes in Internet Explorer.
 832               </p>
 833               <p>
 834                 Presently, it only protects against Nimda and a cross-site
 835                 scripting bug, and would need active maintenance to provide
 836                 more substantial protection.
 837               </p>
 838             </dd>
 839             <dt>
 840               <span class="emphasis"><i class=
 841               "EMPHASIS">site-specifics</i></span>
 842             </dt>
 843             <dd>
 844               <p>
 845                 Some web sites have very specific problems, the cure for
 846                 which doesn't apply anywhere else, or could even cause damage
 847                 on other sites.
 848               </p>
 849               <p>
 850                 This is a collection of such site-specific cures which should
 851                 only be applied to the sites they were intended for, which is
 852                 what the supplied <tt class="FILENAME">default.action</tt>
 853                 file does. Users shouldn't need to change anything regarding
 854                 this filter.
 855               </p>
 856             </dd>
 857             <dt>
 858               <span class="emphasis"><i class="EMPHASIS">google</i></span>
 859             </dt>
 860             <dd>
 861               <p>
 862                 A CSS based block for Google text ads. Also removes a width
 863                 limitation and the toolbar advertisement.
 864               </p>
 865             </dd>
 866             <dt>
 867               <span class="emphasis"><i class="EMPHASIS">yahoo</i></span>
 868             </dt>
 869             <dd>
 870               <p>
 871                 Another CSS based block, this time for Yahoo text ads. And
 872                 removes a width limitation as well.
 873               </p>
 874             </dd>
 875             <dt>
 876               <span class="emphasis"><i class="EMPHASIS">msn</i></span>
 877             </dt>
 878             <dd>
 879               <p>
 880                 Another CSS based block, this time for MSN text ads. And
 881                 removes tracking URLs, as well as a width limitation.
 882               </p>
 883             </dd>
 884             <dt>
 885               <span class="emphasis"><i class="EMPHASIS">blogspot</i></span>
 886             </dt>
 887             <dd>
 888               <p>
 889                 Cleans up some Blogspot blogs. Read the fine print before
 890                 using this one!
 891               </p>
 892               <p>
 893                 This filter also intentionally removes some navigation stuff
 894                 and sets the page width to 100%. As a result, some rounded
 895                 <span class="QUOTE">"corners"</span> would appear to early or
 896                 not at all and as fixing this would require a browser that
 897                 understands background-size (CSS3), they are removed instead.
 898               </p>
 899             </dd>
 900             <dt>
 901               <span class="emphasis"><i class=
 902               "EMPHASIS">xml-to-html</i></span>
 903             </dt>
 904             <dd>
 905               <p>
 906                 Server-header filter to change the Content-Type from xml to
 907                 html.
 908               </p>
 909             </dd>
 910             <dt>
 911               <span class="emphasis"><i class=
 912               "EMPHASIS">html-to-xml</i></span>
 913             </dt>
 914             <dd>
 915               <p>
 916                 Server-header filter to change the Content-Type from html to
 917                 xml.
 918               </p>
 919             </dd>
 920             <dt>
 921               <span class="emphasis"><i class="EMPHASIS">no-ping</i></span>
 922             </dt>
 923             <dd>
 924               <p>
 925                 Removes the non-standard <tt class="LITERAL">ping</tt>
 926                 attribute from anchor and area HTML tags.
 927               </p>
 928             </dd>
 929             <dt>
 930               <span class="emphasis"><i class=
 931               "EMPHASIS">hide-tor-exit-notation</i></span>
 932             </dt>
 933             <dd>
 934               <p>
 935                 Client-header filter to remove the <b class="COMMAND">Tor</b>
 936                 exit node notation found in Host and Referer headers.
 937               </p>
 938               <p>
 939                 If <span class="APPLICATION">Privoxy</span> and <b class=
 940                 "COMMAND">Tor</b> are chained and <span class=
 941                 "APPLICATION">Privoxy</span> is configured to use socks4a,
 942                 one can use <span class=
 943                 "QUOTE">"http://www.example.org.foobar.exit/"</span> to
 944                 access the host <span class="QUOTE">"www.example.org"</span>
 945                 through the <b class="COMMAND">Tor</b> exit node <span class=
 946                 "QUOTE">"foobar"</span>.
 947               </p>
 948               <p>
 949                 As the HTTP client isn't aware of this notation, it treats
 950                 the whole string <span class=
 951                 "QUOTE">"www.example.org.foobar.exit"</span> as host and uses
 952                 it for the <span class="QUOTE">"Host"</span> and <span class=
 953                 "QUOTE">"Referer"</span> headers. From the server's point of
 954                 view the resulting headers are invalid and can cause
 955                 problems.
 956               </p>
 957               <p>
 958                 An invalid <span class="QUOTE">"Referer"</span> header can
 959                 trigger <span class="QUOTE">"hot-linking"</span> protections,
 960                 an invalid <span class="QUOTE">"Host"</span> header will make
 961                 it impossible for the server to find the right vhost (several
 962                 domains hosted on the same IP address).
 963               </p>
 964               <p>
 965                 This client-header filter removes the <span class=
 966                 "QUOTE">"foo.exit"</span> part in those headers to prevent
 967                 the mentioned problems. Note that it only modifies the HTTP
 968                 headers, it doesn't make it impossible for the server to
 969                 detect your <b class="COMMAND">Tor</b> exit node based on the
 970                 IP address the request is coming from.
 971               </p>
 972             </dd>
 973           </dl>
 974         </div>
 975       </div>
 976     </div>
 977     <div class="NAVFOOTER">
 978       <hr width="100%" class="c1">
 979       <table summary="Footer navigation table" width="100%" border="0"
 980       cellpadding="0" cellspacing="0">
 981         <tr>
 982           <td width="33%" align="left" valign="top">
 983             <a href="actions-file.html" accesskey="P">Prev</a>
 984           </td>
 985           <td width="34%" align="center" valign="top">
 986             <a href="index.html" accesskey="H">Home</a>
 987           </td>
 988           <td width="33%" align="right" valign="top">
 989             <a href="templates.html" accesskey="N">Next</a>
 990           </td>
 991         </tr>
 992         <tr>
 993           <td width="33%" align="left" valign="top">
 994             Actions Files
 995           </td>
 996           <td width="34%" align="center" valign="top">
 997             &nbsp;
 998           </td>
 999           <td width="33%" align="right" valign="top">
1000             Privoxy's Template Files
1001           </td>
1002         </tr>
1003       </table>
1004     </div>
1005   </body>
1006 </html>
1007