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