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