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