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