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