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

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