doc/webserver/user-manual/filter-file.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >Filter Files</TITLE
   5 ><META
   6 NAME="GENERATOR"
   7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
   8 "><LINK
   9 REL="HOME"
  10 TITLE="Privoxy 3.0.5 User Manual"
  11 HREF="index.html"><LINK
  12 REL="PREVIOUS"
  13 TITLE="Actions Files"
  14 HREF="actions-file.html"><LINK
  15 REL="NEXT"
  16 TITLE="Privoxy's Template Files"
  17 HREF="templates.html"><LINK
  18 REL="STYLESHEET"
  19 TYPE="text/css"
  20 HREF="../p_doc.css">
  21 <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css">
  22 </head
  23 ><BODY
  24 CLASS="SECT1"
  25 BGCOLOR="#EEEEEE"
  26 TEXT="#000000"
  27 LINK="#0000FF"
  28 VLINK="#840084"
  29 ALINK="#0000FF"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 SUMMARY="Header navigation table"
  34 WIDTH="100%"
  35 BORDER="0"
  36 CELLPADDING="0"
  37 CELLSPACING="0"
  38 ><TR
  39 ><TH
  40 COLSPAN="3"
  41 ALIGN="center"
  42 >Privoxy 3.0.5 User Manual</TH
  43 ></TR
  44 ><TR
  45 ><TD
  46 WIDTH="10%"
  47 ALIGN="left"
  48 VALIGN="bottom"
  49 ><A
  50 HREF="actions-file.html"
  51 ACCESSKEY="P"
  52 >Prev</A
  53 ></TD
  54 ><TD
  55 WIDTH="80%"
  56 ALIGN="center"
  57 VALIGN="bottom"
  58 ></TD
  59 ><TD
  60 WIDTH="10%"
  61 ALIGN="right"
  62 VALIGN="bottom"
  63 ><A
  64 HREF="templates.html"
  65 ACCESSKEY="N"
  66 >Next</A
  67 ></TD
  68 ></TR
  69 ></TABLE
  70 ><HR
  71 ALIGN="LEFT"
  72 WIDTH="100%"></DIV
  73 ><DIV
  74 CLASS="SECT1"
  75 ><H1
  76 CLASS="SECT1"
  77 ><A
  78 NAME="FILTER-FILE"
  79 ></A
  80 >9. Filter Files</H1
  81 ><P
  82 > On-the-fly text substitutions that can be invoked through the
  83  <TT
  84 CLASS="LITERAL"
  85 ><A
  86 HREF="actions-file.html#FILTER"
  87 >filter</A
  88 ></TT
  89 > action need
  90  to be defined in a <SPAN
  91 CLASS="QUOTE"
  92 >"filter file"</SPAN
  93 >. Once defined, they
  94  can then be invoked as an <SPAN
  95 CLASS="QUOTE"
  96 >"action"</SPAN
  97 >. Multiple filter files can be
  98  defined through the <TT
  99 CLASS="LITERAL"
 100 > <A
 101 HREF="config.html#FILTERFILE"
 102 >filterfile</A
 103 ></TT
 104 > config directive. The filters
 105  as supplied by the developers will be found in
 106  <TT
 107 CLASS="FILENAME"
 108 >default.filter</TT
 109 >. It is recommended that any locally
 110  defined or modified filters go in a separately defined file such as
 111  <TT
 112 CLASS="FILENAME"
 113 >user.filter</TT
 114 >.
 115  </P
 116 ><P
 117 > Typical reasons for doing these kinds of substitutions are to eliminate
 118  common annoyances in HTML and JavaScript, such as pop-up windows,
 119  exit consoles, crippled windows without navigation tools, the
 120  infamous &#60;BLINK&#62; tag etc, to suppress images with certain
 121  width and height attributes (standard banner sizes or web-bugs),
 122  or just to have fun. The possibilities are endless.</P
 123 ><P
 124 > Filtering works on any text-based document type, including
 125  HTML, JavaScript, CSS etc. (all <TT
 126 CLASS="LITERAL"
 127 >text/*</TT
 128 >
 129  MIME types, <SPAN
 130 CLASS="emphasis"
 131 ><I
 132 CLASS="EMPHASIS"
 133 >except</I
 134 ></SPAN
 135 > <TT
 136 CLASS="LITERAL"
 137 >text/plain</TT
 138 >).
 139  Substitutions are made at the source level, so if you want to <SPAN
 140 CLASS="QUOTE"
 141 >"roll
 142  your own"</SPAN
 143 > filters, you should first be familiar with HTML syntax,
 144  and, of course, regular expressions. By default, filters are only applied
 145  to the raw document content, but can be extended to the HTTP headers with
 146  the supplemental actions:
 147  <A
 148 HREF="actions-file.html#FILTER-CLIENT-HEADERS"
 149 >filter-client-headers</A
 150 >  and
 151  <A
 152 HREF="actions-file.html#FILTER-SERVER-HEADERS"
 153 >filter-server-headers</A
 154 >.</P
 155 ><P
 156 > Just like the <A
 157 HREF="actions-file.html"
 158 >actions files</A
 159 >, the
 160  filter file is organized in sections, which are called <SPAN
 161 CLASS="emphasis"
 162 ><I
 163 CLASS="EMPHASIS"
 164 >filters</I
 165 ></SPAN
 166 >
 167  here. Each filter consists of a heading line, that starts with the
 168  <SPAN
 169 CLASS="emphasis"
 170 ><I
 171 CLASS="EMPHASIS"
 172 >keyword</I
 173 ></SPAN
 174 > <TT
 175 CLASS="LITERAL"
 176 >FILTER:</TT
 177 >, followed by
 178  the filter's <SPAN
 179 CLASS="emphasis"
 180 ><I
 181 CLASS="EMPHASIS"
 182 >name</I
 183 ></SPAN
 184 >, and a short (one line)
 185  <SPAN
 186 CLASS="emphasis"
 187 ><I
 188 CLASS="EMPHASIS"
 189 >description</I
 190 ></SPAN
 191 > of what it does. Below that line
 192  come the <SPAN
 193 CLASS="emphasis"
 194 ><I
 195 CLASS="EMPHASIS"
 196 >jobs</I
 197 ></SPAN
 198 >, i.e. lines that define the actual
 199  text substitutions. By convention, the name of a filter
 200  should describe what the filter <SPAN
 201 CLASS="emphasis"
 202 ><I
 203 CLASS="EMPHASIS"
 204 >eliminates</I
 205 ></SPAN
 206 >. The
 207  comment is used in the <A
 208 HREF="http://config.privoxy.org/"
 209 TARGET="_top"
 210 >web-based
 211  user interface</A
 212 >.</P
 213 ><P
 214 > Once a filter called <TT
 215 CLASS="REPLACEABLE"
 216 ><I
 217 >name</I
 218 ></TT
 219 > has been defined
 220  in the filter file, it can be invoked by using an action of the form
 221  +<TT
 222 CLASS="LITERAL"
 223 ><A
 224 HREF="actions-file.html#FILTER"
 225 >filter</A
 226 >{<TT
 227 CLASS="REPLACEABLE"
 228 ><I
 229 >name</I
 230 ></TT
 231 >}</TT
 232 >
 233  in any <A
 234 HREF="actions-file.html"
 235 >actions file</A
 236 >.</P
 237 ><P
 238 > A filter header line for a filter called <SPAN
 239 CLASS="QUOTE"
 240 >"foo"</SPAN
 241 > could look
 242  like this:</P
 243 ><P
 244 > <TABLE
 245 BORDER="0"
 246 BGCOLOR="#E0E0E0"
 247 WIDTH="100%"
 248 ><TR
 249 ><TD
 250 ><PRE
 251 CLASS="SCREEN"
 252 >FILTER: foo Replace all "foo" with "bar"</PRE
 253 ></TD
 254 ></TR
 255 ></TABLE
 256 ></P
 257 ><P
 258 > Below that line, and up to the next header line, come the jobs that
 259  define what text replacements the filter executes. They are specified
 260  in a syntax that imitates <A
 261 HREF="http://www.perl.org/"
 262 TARGET="_top"
 263 >Perl</A
 264 >'s
 265  <TT
 266 CLASS="LITERAL"
 267 >s///</TT
 268 > operator. If you are familiar with Perl, you
 269  will find this to be quite intuitive, and may want to look at the
 270  PCRS documentation for the subtle differences to Perl behaviour. Most
 271  notably, the non-standard option letter <TT
 272 CLASS="LITERAL"
 273 >U</TT
 274 > is supported,
 275  which turns the default to ungreedy matching.</P
 276 ><P
 277 > If you are new to
 278   <A
 279 HREF="http://en.wikipedia.org/wiki/Regular_expressions"
 280 TARGET="_top"
 281 ><SPAN
 282 CLASS="QUOTE"
 283 >"Regular
 284   Expressions"</SPAN
 285 ></A
 286 >, you might want to take a look at
 287  the <A
 288 HREF="appendix.html#REGEX"
 289 >Appendix on regular expressions</A
 290 >, and
 291  see the <A
 292 HREF="http://perldoc.perl.org/perlre.html"
 293 TARGET="_top"
 294 >Perl
 295  manual</A
 296 > for
 297  <A
 298 HREF="http://perldoc.perl.org/perlop.html"
 299 TARGET="_top"
 300 >the
 301  <TT
 302 CLASS="LITERAL"
 303 >s///</TT
 304 > operator's syntax</A
 305 > and <A
 306 HREF="http://perldoc.perl.org/perlre.html"
 307 TARGET="_top"
 308 >Perl-style regular
 309  expressions</A
 310 > in general.
 311  The below examples might also help to get you started.</P
 312 ><DIV
 313 CLASS="SECT2"
 314 ><H2
 315 CLASS="SECT2"
 316 ><A
 317 NAME="AEN4271"
 318 ></A
 319 >9.1. Filter File Tutorial</H2
 320 ><P
 321 > Now, let's complete our <SPAN
 322 CLASS="QUOTE"
 323 >"foo"</SPAN
 324 > filter. We have already defined
 325  the heading, but the jobs are still missing. Since all it does is to replace
 326  <SPAN
 327 CLASS="QUOTE"
 328 >"foo"</SPAN
 329 > with <SPAN
 330 CLASS="QUOTE"
 331 >"bar"</SPAN
 332 >, there is only one (trivial) job
 333  needed:</P
 334 ><P
 335 > <TABLE
 336 BORDER="0"
 337 BGCOLOR="#E0E0E0"
 338 WIDTH="100%"
 339 ><TR
 340 ><TD
 341 ><PRE
 342 CLASS="SCREEN"
 343 >s/foo/bar/</PRE
 344 ></TD
 345 ></TR
 346 ></TABLE
 347 ></P
 348 ><P
 349 > But wait! Didn't the comment say that <SPAN
 350 CLASS="emphasis"
 351 ><I
 352 CLASS="EMPHASIS"
 353 >all</I
 354 ></SPAN
 355 > occurrences
 356  of <SPAN
 357 CLASS="QUOTE"
 358 >"foo"</SPAN
 359 > should be replaced? Our current job will only take
 360  care of the first <SPAN
 361 CLASS="QUOTE"
 362 >"foo"</SPAN
 363 > on each page. For global substitution,
 364  we'll need to add the <TT
 365 CLASS="LITERAL"
 366 >g</TT
 367 > option:</P
 368 ><P
 369 > <TABLE
 370 BORDER="0"
 371 BGCOLOR="#E0E0E0"
 372 WIDTH="100%"
 373 ><TR
 374 ><TD
 375 ><PRE
 376 CLASS="SCREEN"
 377 >s/foo/bar/g</PRE
 378 ></TD
 379 ></TR
 380 ></TABLE
 381 ></P
 382 ><P
 383 > Our complete filter now looks like this:</P
 384 ><P
 385 > <TABLE
 386 BORDER="0"
 387 BGCOLOR="#E0E0E0"
 388 WIDTH="100%"
 389 ><TR
 390 ><TD
 391 ><PRE
 392 CLASS="SCREEN"
 393 >FILTER: foo Replace all "foo" with "bar"
 394 s/foo/bar/g</PRE
 395 ></TD
 396 ></TR
 397 ></TABLE
 398 ></P
 399 ><P
 400 > Let's look at some real filters for more interesting examples. Here you see
 401  a filter that protects against some common annoyances that arise from JavaScript
 402  abuse. Let's look at its jobs one after the other:</P
 403 ><P
 404 > <TABLE
 405 BORDER="0"
 406 BGCOLOR="#E0E0E0"
 407 WIDTH="100%"
 408 ><TR
 409 ><TD
 410 ><PRE
 411 CLASS="SCREEN"
 412 >FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse
 413
 414 # Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm
 415 #
 416 s|(&#60;script.*)document\.referrer(.*&#60;/script&#62;)|$1"Not Your Business!"$2|Usg</PRE
 417 ></TD
 418 ></TR
 419 ></TABLE
 420 ></P
 421 ><P
 422 > Following the header line and a comment, you see the job. Note that it uses
 423  <TT
 424 CLASS="LITERAL"
 425 >|</TT
 426 > as the delimiter instead of <TT
 427 CLASS="LITERAL"
 428 >/</TT
 429 >, because
 430  the pattern contains a forward slash, which would otherwise have to be escaped
 431  by a backslash (<TT
 432 CLASS="LITERAL"
 433 >\</TT
 434 >).</P
 435 ><P
 436 > Now, let's examine the pattern: it starts with the text <TT
 437 CLASS="LITERAL"
 438 >&#60;script.*</TT
 439 >
 440  enclosed in parentheses. Since the dot matches any character, and <TT
 441 CLASS="LITERAL"
 442 >*</TT
 443 >
 444  means: <SPAN
 445 CLASS="QUOTE"
 446 >"Match an arbitrary number of the element left of myself"</SPAN
 447 >, this
 448  matches <SPAN
 449 CLASS="QUOTE"
 450 >"&#60;script"</SPAN
 451 >, followed by <SPAN
 452 CLASS="emphasis"
 453 ><I
 454 CLASS="EMPHASIS"
 455 >any</I
 456 ></SPAN
 457 > text, i.e.
 458  it matches the whole page, from the start of the first &#60;script&#62; tag.</P
 459 ><P
 460 > That's more than we want, but the pattern continues: <TT
 461 CLASS="LITERAL"
 462 >document\.referrer</TT
 463 >
 464  matches only the exact string <SPAN
 465 CLASS="QUOTE"
 466 >"document.referrer"</SPAN
 467 >. The dot needed to
 468  be <SPAN
 469 CLASS="emphasis"
 470 ><I
 471 CLASS="EMPHASIS"
 472 >escaped</I
 473 ></SPAN
 474 >, i.e. preceded by a backslash, to take away its
 475  special meaning as a joker, and make it just a regular dot. So far, the meaning is:
 476  Match from the start of the first &#60;script&#62; tag in a the page, up to, and including,
 477  the text <SPAN
 478 CLASS="QUOTE"
 479 >"document.referrer"</SPAN
 480 >, if <SPAN
 481 CLASS="emphasis"
 482 ><I
 483 CLASS="EMPHASIS"
 484 >both</I
 485 ></SPAN
 486 > are present
 487  in the page (and appear in that order).</P
 488 ><P
 489 > But there's still more pattern to go. The next element, again enclosed in parentheses,
 490  is <TT
 491 CLASS="LITERAL"
 492 >.*&#60;/script&#62;</TT
 493 >. You already know what <TT
 494 CLASS="LITERAL"
 495 >.*</TT
 496 >
 497  means, so the whole pattern translates to: Match from the start of the first  &#60;script&#62;
 498  tag in a page to the end of the last &#60;script&#62; tag, provided that the text
 499  <SPAN
 500 CLASS="QUOTE"
 501 >"document.referrer"</SPAN
 502 > appears somewhere in between.</P
 503 ><P
 504 > This is still not the whole story, since we have ignored the options and the parentheses:
 505  The portions of the page matched by sub-patterns that are enclosed in parentheses, will be
 506  remembered and be available through the variables <TT
 507 CLASS="LITERAL"
 508 >$1, $2, ...</TT
 509 > in
 510  the substitute. The <TT
 511 CLASS="LITERAL"
 512 >U</TT
 513 > option switches to ungreedy matching, which means
 514  that the first <TT
 515 CLASS="LITERAL"
 516 >.*</TT
 517 > in the pattern will only <SPAN
 518 CLASS="QUOTE"
 519 >"eat up"</SPAN
 520 > all
 521  text in between <SPAN
 522 CLASS="QUOTE"
 523 >"&#60;script"</SPAN
 524 > and the <SPAN
 525 CLASS="emphasis"
 526 ><I
 527 CLASS="EMPHASIS"
 528 >first</I
 529 ></SPAN
 530 > occurrence
 531  of <SPAN
 532 CLASS="QUOTE"
 533 >"document.referrer"</SPAN
 534 >, and that the second <TT
 535 CLASS="LITERAL"
 536 >.*</TT
 537 > will
 538  only span the text up to the <SPAN
 539 CLASS="emphasis"
 540 ><I
 541 CLASS="EMPHASIS"
 542 >first</I
 543 ></SPAN
 544 > <SPAN
 545 CLASS="QUOTE"
 546 >"&#60;/script&#62;"</SPAN
 547 >
 548  tag. Furthermore, the <TT
 549 CLASS="LITERAL"
 550 >s</TT
 551 > option says that the match may span
 552  multiple lines in the page, and the <TT
 553 CLASS="LITERAL"
 554 >g</TT
 555 > option again means that the
 556  substitution is global.</P
 557 ><P
 558 > So, to summarize, the pattern means: Match all scripts that contain the text
 559  <SPAN
 560 CLASS="QUOTE"
 561 >"document.referrer"</SPAN
 562 >. Remember the parts of the script from
 563  (and including) the start tag up to (and excluding) the string
 564  <SPAN
 565 CLASS="QUOTE"
 566 >"document.referrer"</SPAN
 567 > as <TT
 568 CLASS="LITERAL"
 569 >$1</TT
 570 >, and the part following
 571  that string, up to and including the closing tag, as <TT
 572 CLASS="LITERAL"
 573 >$2</TT
 574 >.</P
 575 ><P
 576 > Now the pattern is deciphered, but wasn't this about substituting things? So
 577  lets look at the substitute: <TT
 578 CLASS="LITERAL"
 579 >$1"Not Your Business!"$2</TT
 580 > is
 581  easy to read: The text remembered as <TT
 582 CLASS="LITERAL"
 583 >$1</TT
 584 >, followed by
 585  <TT
 586 CLASS="LITERAL"
 587 >"Not Your Business!"</TT
 588 > (<SPAN
 589 CLASS="emphasis"
 590 ><I
 591 CLASS="EMPHASIS"
 592 >including</I
 593 ></SPAN
 594 >
 595  the quotation marks!), followed by the text remembered as <TT
 596 CLASS="LITERAL"
 597 >$2</TT
 598 >.
 599  This produces an exact copy of the original string, with the middle part
 600  (the <SPAN
 601 CLASS="QUOTE"
 602 >"document.referrer"</SPAN
 603 >) replaced by <TT
 604 CLASS="LITERAL"
 605 >"Not Your
 606  Business!"</TT
 607 >.</P
 608 ><P
 609 > The whole job now reads: Replace <SPAN
 610 CLASS="QUOTE"
 611 >"document.referrer"</SPAN
 612 > by
 613  <TT
 614 CLASS="LITERAL"
 615 >"Not Your Business!"</TT
 616 > wherever it appears inside a
 617  &#60;script&#62; tag. Note that this job won't break JavaScript syntax,
 618  since both the original and the replacement are syntactically valid
 619  string objects. The script just won't have access to the referrer
 620  information anymore.</P
 621 ><P
 622 > We'll show you two other jobs from the JavaScript taming department, but
 623  this time only point out the constructs of special interest:</P
 624 ><P
 625 > <TABLE
 626 BORDER="0"
 627 BGCOLOR="#E0E0E0"
 628 WIDTH="100%"
 629 ><TR
 630 ><TD
 631 ><PRE
 632 CLASS="SCREEN"
 633 ># The status bar is for displaying link targets, not pointless blahblah
 634 #
 635 s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig</PRE
 636 ></TD
 637 ></TR
 638 ></TABLE
 639 ></P
 640 ><P
 641 > <TT
 642 CLASS="LITERAL"
 643 >\s</TT
 644 > stands for whitespace characters (space, tab, newline,
 645  carriage return, form feed), so that <TT
 646 CLASS="LITERAL"
 647 >\s*</TT
 648 > means: <SPAN
 649 CLASS="QUOTE"
 650 >"zero
 651  or more whitespace"</SPAN
 652 >. The <TT
 653 CLASS="LITERAL"
 654 >?</TT
 655 > in <TT
 656 CLASS="LITERAL"
 657 >.*?</TT
 658 >
 659  makes this matching of arbitrary text ungreedy. (Note that the <TT
 660 CLASS="LITERAL"
 661 >U</TT
 662 >
 663  option is not set). The <TT
 664 CLASS="LITERAL"
 665 >['"]</TT
 666 > construct means: <SPAN
 667 CLASS="QUOTE"
 668 >"a single
 669  <SPAN
 670 CLASS="emphasis"
 671 ><I
 672 CLASS="EMPHASIS"
 673 >or</I
 674 ></SPAN
 675 > a double quote"</SPAN
 676 >. Finally, <TT
 677 CLASS="LITERAL"
 678 >\1</TT
 679 > is
 680  a back-reference to the first parenthesis just like <TT
 681 CLASS="LITERAL"
 682 >$1</TT
 683 > above,
 684  with the difference that in the <SPAN
 685 CLASS="emphasis"
 686 ><I
 687 CLASS="EMPHASIS"
 688 >pattern</I
 689 ></SPAN
 690 >, a backslash indicates
 691  a back-reference, whereas in the <SPAN
 692 CLASS="emphasis"
 693 ><I
 694 CLASS="EMPHASIS"
 695 >substitute</I
 696 ></SPAN
 697 >, it's the dollar.</P
 698 ><P
 699 > So what does this job do? It replaces assignments of single- or double-quoted
 700  strings to the <SPAN
 701 CLASS="QUOTE"
 702 >"window.status"</SPAN
 703 > object with a dummy assignment
 704  (using a variable name that is hopefully odd enough not to conflict with
 705  real variables in scripts). Thus, it catches many cases where e.g. pointless
 706  descriptions are displayed in the status bar instead of the link target when
 707  you move your mouse over links.</P
 708 ><P
 709 > <TABLE
 710 BORDER="0"
 711 BGCOLOR="#E0E0E0"
 712 WIDTH="100%"
 713 ><TR
 714 ><TD
 715 ><PRE
 716 CLASS="SCREEN"
 717 ># Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
 718 #
 719 s/(&#60;body [^&#62;]*)onunload(.*&#62;)/$1never$2/iU</PRE
 720 ></TD
 721 ></TR
 722 ></TABLE
 723 ></P
 724 ><P
 725 > Including the
 726  <A
 727 HREF="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents"
 728 TARGET="_top"
 729 >OnUnload
 730  event binding</A
 731 > in the HTML DOM was a <SPAN
 732 CLASS="emphasis"
 733 ><I
 734 CLASS="EMPHASIS"
 735 >CRIME</I
 736 ></SPAN
 737 >.
 738  When I close a browser window, I want it to close and die. Basta.
 739  This job replaces the <SPAN
 740 CLASS="QUOTE"
 741 >"onunload"</SPAN
 742 > attribute in
 743  <SPAN
 744 CLASS="QUOTE"
 745 >"&#60;body&#62;"</SPAN
 746 > tags with the dummy word <TT
 747 CLASS="LITERAL"
 748 >never</TT
 749 >.
 750  Note that the <TT
 751 CLASS="LITERAL"
 752 >i</TT
 753 > option makes the pattern matching
 754  case-insensitive. Also note that ungreedy matching alone doesn't always guarantee
 755  a minimal match: In the first parenthesis, we had to use <TT
 756 CLASS="LITERAL"
 757 >[^&#62;]*</TT
 758 >
 759  instead of <TT
 760 CLASS="LITERAL"
 761 >.*</TT
 762 > to prevent the match from exceeding the
 763  &#60;body&#62; tag if it doesn't contain <SPAN
 764 CLASS="QUOTE"
 765 >"OnUnload"</SPAN
 766 >, but the page's
 767  content does.</P
 768 ><P
 769 > The last example is from the fun department:</P
 770 ><P
 771 > <TABLE
 772 BORDER="0"
 773 BGCOLOR="#E0E0E0"
 774 WIDTH="100%"
 775 ><TR
 776 ><TD
 777 ><PRE
 778 CLASS="SCREEN"
 779 >FILTER: fun Fun text replacements
 780
 781 # Spice the daily news:
 782 #
 783 s/microsoft(?!\.com)/MicroSuck/ig</PRE
 784 ></TD
 785 ></TR
 786 ></TABLE
 787 ></P
 788 ><P
 789 > Note the <TT
 790 CLASS="LITERAL"
 791 >(?!\.com)</TT
 792 > part (a so-called negative lookahead)
 793  in the job's pattern, which means: Don't match, if the string
 794  <SPAN
 795 CLASS="QUOTE"
 796 >".com"</SPAN
 797 > appears directly following <SPAN
 798 CLASS="QUOTE"
 799 >"microsoft"</SPAN
 800 >
 801  in the page. This prevents links to microsoft.com from being trashed, while
 802  still replacing the word everywhere else.</P
 803 ><P
 804 > <TABLE
 805 BORDER="0"
 806 BGCOLOR="#E0E0E0"
 807 WIDTH="100%"
 808 ><TR
 809 ><TD
 810 ><PRE
 811 CLASS="SCREEN"
 812 ># Buzzword Bingo (example for extended regex syntax)
 813 #
 814 s* industry[ -]leading \
 815 |  cutting[ -]edge \
 816 |  customer[ -]focused \
 817 |  market[ -]driven \
 818 |  award[ -]winning # Comments are OK, too! \
 819 |  high[ -]performance \
 820 |  solutions[ -]based \
 821 |  unmatched \
 822 |  unparalleled \
 823 |  unrivalled \
 824 *&#60;font color="red"&#62;&#60;b&#62;BINGO!&#60;/b&#62;&#60;/font&#62; \
 825 *igx</PRE
 826 ></TD
 827 ></TR
 828 ></TABLE
 829 ></P
 830 ><P
 831 > The <TT
 832 CLASS="LITERAL"
 833 >x</TT
 834 > option in this job turns on extended syntax, and allows for
 835  e.g. the liberal use of (non-interpreted!) whitespace for nicer formatting. </P
 836 ><P
 837 > You get the idea?</P
 838 ></DIV
 839 ><DIV
 840 CLASS="SECT2"
 841 ><H2
 842 CLASS="SECT2"
 843 ><A
 844 NAME="PREDEFINED-FILTERS"
 845 ></A
 846 >9.2. The Pre-defined Filters</H2
 847 ><P
 848 >The distribution <TT
 849 CLASS="FILENAME"
 850 >default.filter</TT
 851 > file contains a selection of
 852 pre-defined filters for your convenience:</P
 853 ><P
 854 ></P
 855 ><DIV
 856 CLASS="VARIABLELIST"
 857 ><DL
 858 ><DT
 859 ><SPAN
 860 CLASS="emphasis"
 861 ><I
 862 CLASS="EMPHASIS"
 863 >js-annoyances</I
 864 ></SPAN
 865 ></DT
 866 ><DD
 867 ><P
 868 >    The purpose of this filter is to get rid of particularly annoying JavaScript abuse.
 869     To that end, it
 870    <P
 871 ></P
 872 ><UL
 873 ><LI
 874 ><P
 875 >      replaces JavaScript references to the browser's referrer information
 876       with the string "Not Your Business!". This compliments the <TT
 877 CLASS="LITERAL"
 878 ><A
 879 HREF="actions-file.html#HIDE-REFERRER"
 880 >hide-referrer</A
 881 ></TT
 882 > action on the content level.
 883      </P
 884 ></LI
 885 ><LI
 886 ><P
 887 >      removes the bindings to the DOM's
 888       <A
 889 HREF="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents"
 890 TARGET="_top"
 891 >unload
 892       event</A
 893 > which we feel has no right to exist and is responsible for most <SPAN
 894 CLASS="QUOTE"
 895 >"exit consoles"</SPAN
 896 >, i.e.
 897       nasty windows that pop up when you close another one.
 898      </P
 899 ></LI
 900 ><LI
 901 ><P
 902 >      removes code that causes new windows to be opened with undesired properties, such as being
 903       full-screen, non-resizeable, without location, status or menu bar etc.
 904      </P
 905 ></LI
 906 ></UL
 907 >
 908    </P
 909 ></DD
 910 ><DT
 911 ><SPAN
 912 CLASS="emphasis"
 913 ><I
 914 CLASS="EMPHASIS"
 915 >js-events</I
 916 ></SPAN
 917 ></DT
 918 ><DD
 919 ><P
 920 >    This is a very radical measure. It removes virtually all JavaScript event bindings, which
 921     means that scripts can not react to user actions such as mouse movements or clicks, window
 922     resizing etc, anymore.
 923    </P
 924 ><P
 925 >    We <SPAN
 926 CLASS="emphasis"
 927 ><I
 928 CLASS="EMPHASIS"
 929 >strongly discourage</I
 930 ></SPAN
 931 > using this filter as a default since it breaks
 932     many legitimate scripts. It is meant for use only on extra-nasty sites (should you really
 933     need to go there).
 934    </P
 935 ></DD
 936 ><DT
 937 ><SPAN
 938 CLASS="emphasis"
 939 ><I
 940 CLASS="EMPHASIS"
 941 >html-annoyances</I
 942 ></SPAN
 943 ></DT
 944 ><DD
 945 ><P
 946 >    This filter will undo many common instances of HTML based abuse.
 947    </P
 948 ><P
 949 >    The <TT
 950 CLASS="LITERAL"
 951 >BLINK</TT
 952 > and <TT
 953 CLASS="LITERAL"
 954 >MARQUEE</TT
 955 > tags
 956     are neutralized (yeah baby!), and browser windows will be created as
 957     resizeable (as of course they should be!), and will have location,
 958     scroll and menu bars -- even if specified otherwise.
 959    </P
 960 ></DD
 961 ><DT
 962 ><SPAN
 963 CLASS="emphasis"
 964 ><I
 965 CLASS="EMPHASIS"
 966 >content-cookies</I
 967 ></SPAN
 968 ></DT
 969 ><DD
 970 ><P
 971 >    Most cookies are set in the HTTP dialog, where they can be intercepted
 972     by the
 973     <TT
 974 CLASS="LITERAL"
 975 ><A
 976 HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
 977 >crunch-incoming-cookies</A
 978 ></TT
 979 >
 980     and <TT
 981 CLASS="LITERAL"
 982 ><A
 983 HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
 984 >crunch-outgoing-cookies</A
 985 ></TT
 986 >
 987     actions. But web sites increasingly make use of HTML meta tags and JavaScript
 988     to sneak cookies to the browser on the content level.
 989    </P
 990 ><P
 991 >    This filter disables HTML and JavaScript code that reads or sets cookies. Use
 992     it wherever you would also use the cookie crunch actions.
 993    </P
 994 ></DD
 995 ><DT
 996 ><SPAN
 997 CLASS="emphasis"
 998 ><I
 999 CLASS="EMPHASIS"
1000 >refresh tags</I
1001 ></SPAN
1002 ></DT
1003 ><DD
1004 ><P
1005 >    Disable any refresh tags if the interval is greater than nine seconds (so
1006     that redirections done via refresh tags are not destroyed). This is useful
1007     for dial-on-demand setups, or for those who find this HTML feature
1008     annoying.
1009    </P
1010 ></DD
1011 ><DT
1012 ><SPAN
1013 CLASS="emphasis"
1014 ><I
1015 CLASS="EMPHASIS"
1016 >unsolicited-popups</I
1017 ></SPAN
1018 ></DT
1019 ><DD
1020 ><P
1021 >    This filter attempts to prevent only <SPAN
1022 CLASS="QUOTE"
1023 >"unsolicited"</SPAN
1024 > pop-up
1025     windows from opening, yet still allow pop-up windows that the user
1026     has explicitly chosen to open. It was added in version 3.0.1,
1027     as an improvement over earlier such filters.
1028    </P
1029 ><P
1030 >    Technical note: The filter works by redefining the window.open JavaScript
1031     function to a dummy function during the loading and rendering phase of each
1032     HTML page access, and restoring the function afterward.
1033    </P
1034 ></DD
1035 ><DT
1036 ><SPAN
1037 CLASS="emphasis"
1038 ><I
1039 CLASS="EMPHASIS"
1040 >all-popups</I
1041 ></SPAN
1042 ></DT
1043 ><DD
1044 ><P
1045 >    Attempt to prevent <SPAN
1046 CLASS="emphasis"
1047 ><I
1048 CLASS="EMPHASIS"
1049 >all</I
1050 ></SPAN
1051 > pop-up windows from opening.
1052     Note this should be used with more discretion than the above, since it is
1053     more likely to break some sites that require pop-ups for normal usage. Use
1054     with caution.
1055    </P
1056 ></DD
1057 ><DT
1058 ><SPAN
1059 CLASS="emphasis"
1060 ><I
1061 CLASS="EMPHASIS"
1062 >img-reorder</I
1063 ></SPAN
1064 ></DT
1065 ><DD
1066 ><P
1067 >    This is a helper filter that has no value if used alone. It makes the
1068     <TT
1069 CLASS="LITERAL"
1070 >banners-by-size</TT
1071 > and <TT
1072 CLASS="LITERAL"
1073 >banners-by-link</TT
1074 >
1075     (see below) filters more effective and should be enabled together with them.
1076    </P
1077 ></DD
1078 ><DT
1079 ><SPAN
1080 CLASS="emphasis"
1081 ><I
1082 CLASS="EMPHASIS"
1083 >banners-by-size</I
1084 ></SPAN
1085 ></DT
1086 ><DD
1087 ><P
1088 >    This filter removes image tags purely based on what size they are. Fortunately
1089     for us, many ads and banner images tend to conform to certain standardized
1090     sizes, which makes this filter quite effective for ad stripping purposes.
1091    </P
1092 ><P
1093 >    Occasionally this filter will cause false positives on images that are not ads,
1094     but just happen to be of one of the standard banner sizes.
1095    </P
1096 ></DD
1097 ><DT
1098 ><SPAN
1099 CLASS="emphasis"
1100 ><I
1101 CLASS="EMPHASIS"
1102 >banners-by-link</I
1103 ></SPAN
1104 ></DT
1105 ><DD
1106 ><P
1107 >    This is an experimental filter that attempts to kill any banners if
1108     their URLs seem to point to known or suspected click trackers. It is currently
1109     not of much value and is not recommended for use by default.
1110    </P
1111 ></DD
1112 ><DT
1113 ><SPAN
1114 CLASS="emphasis"
1115 ><I
1116 CLASS="EMPHASIS"
1117 >webbugs</I
1118 ></SPAN
1119 ></DT
1120 ><DD
1121 ><P
1122 >    Webbugs are small, invisible images (technically 1X1 GIF images), that
1123     are used to track users across websites, and collect information on them.
1124     As an HTML page is loaded by the browser, an embedded image tag causes the
1125     browser to contact a third-party site, disclosing the tracking information
1126     through the requested URL and/or cookies for that third-party domain, without
1127     the use ever becoming aware of the interaction with the third-party site.
1128     HTML-ized spam also uses a similar technique to verify email addresses.
1129    </P
1130 ><P
1131 >    This filter removes the HTML code that loads such <SPAN
1132 CLASS="QUOTE"
1133 >"webbugs"</SPAN
1134 >.
1135    </P
1136 ></DD
1137 ><DT
1138 ><SPAN
1139 CLASS="emphasis"
1140 ><I
1141 CLASS="EMPHASIS"
1142 >tiny-textforms</I
1143 ></SPAN
1144 ></DT
1145 ><DD
1146 ><P
1147 >    A rather special-purpose filter that can be used to enlarge textareas (those
1148     multi-line text boxes in web forms) and turn off hard word wrap in them.
1149     It was written for the sourceforge.net tracker system where such boxes are
1150     a nuisance, but it can be handy on other sites, too.
1151    </P
1152 ><P
1153 >    It is not recommended to use this filter as a default.
1154    </P
1155 ></DD
1156 ><DT
1157 ><SPAN
1158 CLASS="emphasis"
1159 ><I
1160 CLASS="EMPHASIS"
1161 >jumping-windows</I
1162 ></SPAN
1163 ></DT
1164 ><DD
1165 ><P
1166 >    Many consider windows that move, or resize themselves to be abusive. This filter
1167     neutralizes the related JavaScript code. Note that some sites might not display
1168     or behave as intended when using this filter.
1169    </P
1170 ></DD
1171 ><DT
1172 ><SPAN
1173 CLASS="emphasis"
1174 ><I
1175 CLASS="EMPHASIS"
1176 >frameset-borders</I
1177 ></SPAN
1178 ></DT
1179 ><DD
1180 ><P
1181 >    Some web designers seem to assume that everyone in the world will view their
1182     web sites using the same browser brand and version, screen resolution etc,
1183     because only that assumption could explain why they'd use static frame sizes,
1184     yet prevent their frames from being resized by the user, should they be too
1185     small to show their whole content.
1186    </P
1187 ><P
1188 >    This filter removes the related HTML code. It should only be applied to sites
1189     which need it.
1190    </P
1191 ></DD
1192 ><DT
1193 ><SPAN
1194 CLASS="emphasis"
1195 ><I
1196 CLASS="EMPHASIS"
1197 >demoronizer</I
1198 ></SPAN
1199 ></DT
1200 ><DD
1201 ><P
1202 >    Many Microsoft products that generate HTML use non-standard extensions (read:
1203     violations) of the ISO 8859-1 aka Latin-1 character set. This can cause those
1204     HTML documents to display with errors on standard-compliant platforms.
1205    </P
1206 ><P
1207 >    This filter translates the MS-only characters into Latin-1 equivalents.
1208     It is not necessary when using MS products, and will cause corruption of
1209     all documents that use 8-bit character sets other than Latin-1. It's mostly
1210     worthwhile for Europeans on non-MS platforms, if weird garbage characters
1211     sometimes appear on some pages, or user agents that don't correct for this on
1212     the fly.
1213
1214    </P
1215 ></DD
1216 ><DT
1217 ><SPAN
1218 CLASS="emphasis"
1219 ><I
1220 CLASS="EMPHASIS"
1221 >shockwave-flash</I
1222 ></SPAN
1223 ></DT
1224 ><DD
1225 ><P
1226 >    A filter for shockwave haters. As the name suggests, this filter strips code
1227     out of web pages that is used to embed shockwave flash objects.
1228    </P
1229 ><P
1230 >   </P
1231 ></DD
1232 ><DT
1233 ><SPAN
1234 CLASS="emphasis"
1235 ><I
1236 CLASS="EMPHASIS"
1237 >quicktime-kioskmode</I
1238 ></SPAN
1239 ></DT
1240 ><DD
1241 ><P
1242 >    Change HTML code that embeds Quicktime objects so that kioskmode, which
1243     prevents saving, is disabled.
1244    </P
1245 ></DD
1246 ><DT
1247 ><SPAN
1248 CLASS="emphasis"
1249 ><I
1250 CLASS="EMPHASIS"
1251 >fun</I
1252 ></SPAN
1253 ></DT
1254 ><DD
1255 ><P
1256 >    Text replacements for subversive browsing fun. Make fun of your favorite
1257     Monopolist or play buzzword bingo.
1258    </P
1259 ></DD
1260 ><DT
1261 ><SPAN
1262 CLASS="emphasis"
1263 ><I
1264 CLASS="EMPHASIS"
1265 >crude-parental</I
1266 ></SPAN
1267 ></DT
1268 ><DD
1269 ><P
1270 >    A demonstration-only filter that shows how <SPAN
1271 CLASS="APPLICATION"
1272 >Privoxy</SPAN
1273 >
1274     can be used to delete web content on a keyword basis.
1275    </P
1276 ></DD
1277 ><DT
1278 ><SPAN
1279 CLASS="emphasis"
1280 ><I
1281 CLASS="EMPHASIS"
1282 >ie-exploits</I
1283 ></SPAN
1284 ></DT
1285 ><DD
1286 ><P
1287 >    A collection of text replacements to disable malicious HTML and JavaScript
1288     code that exploits known security holes in Internet Explorer.
1289    </P
1290 ><P
1291 >    Presently, it only protects against Nimda and a cross-site scripting bug, and
1292     would need active maintenance to provide more substantial protection.
1293    </P
1294 ></DD
1295 ><DT
1296 ><SPAN
1297 CLASS="emphasis"
1298 ><I
1299 CLASS="EMPHASIS"
1300 >site-specifics</I
1301 ></SPAN
1302 ></DT
1303 ><DD
1304 ><P
1305 >    Some web sites have very specific problems, the cure for which doesn't apply
1306     anywhere else, or could even cause damage on other sites.
1307    </P
1308 ><P
1309 >    This is a collection of such site-specific cures which should only be applied
1310     to the sites they were intended for, which is what the supplied
1311     <TT
1312 CLASS="FILENAME"
1313 >default.action</TT
1314 > file does. Users shouldn't need to change
1315     anything regarding this filter.
1316    </P
1317 ></DD
1318 ></DL
1319 ></DIV
1320 ></DIV
1321 ></DIV
1322 ><DIV
1323 CLASS="NAVFOOTER"
1324 ><HR
1325 ALIGN="LEFT"
1326 WIDTH="100%"><TABLE
1327 SUMMARY="Footer navigation table"
1328 WIDTH="100%"
1329 BORDER="0"
1330 CELLPADDING="0"
1331 CELLSPACING="0"
1332 ><TR
1333 ><TD
1334 WIDTH="33%"
1335 ALIGN="left"
1336 VALIGN="top"
1337 ><A
1338 HREF="actions-file.html"
1339 ACCESSKEY="P"
1340 >Prev</A
1341 ></TD
1342 ><TD
1343 WIDTH="34%"
1344 ALIGN="center"
1345 VALIGN="top"
1346 ><A
1347 HREF="index.html"
1348 ACCESSKEY="H"
1349 >Home</A
1350 ></TD
1351 ><TD
1352 WIDTH="33%"
1353 ALIGN="right"
1354 VALIGN="top"
1355 ><A
1356 HREF="templates.html"
1357 ACCESSKEY="N"
1358 >Next</A
1359 ></TD
1360 ></TR
1361 ><TR
1362 ><TD
1363 WIDTH="33%"
1364 ALIGN="left"
1365 VALIGN="top"
1366 >Actions Files</TD
1367 ><TD
1368 WIDTH="34%"
1369 ALIGN="center"
1370 VALIGN="top"
1371 >&nbsp;</TD
1372 ><TD
1373 WIDTH="33%"
1374 ALIGN="right"
1375 VALIGN="top"
1376 >Privoxy's Template Files</TD
1377 ></TR
1378 ></TABLE
1379 ></DIV
1380 ></BODY
1381 ></HTML
1382 >