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