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

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >Filter Files</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
   9 REL="HOME"
  10 TITLE="Privoxy 3.0.27 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"><META
  21 HTTP-EQUIV="Content-Type"
  22 CONTENT="text/html;
  23 charset=ISO-8859-1">
  24 <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css">
  25 </head
  26 ><BODY
  27 CLASS="SECT1"
  28 BGCOLOR="#EEEEEE"
  29 TEXT="#000000"
  30 LINK="#0000FF"
  31 VLINK="#840084"
  32 ALINK="#0000FF"
  33 ><DIV
  34 CLASS="NAVHEADER"
  35 ><TABLE
  36 SUMMARY="Header navigation table"
  37 WIDTH="100%"
  38 BORDER="0"
  39 CELLPADDING="0"
  40 CELLSPACING="0"
  41 ><TR
  42 ><TH
  43 COLSPAN="3"
  44 ALIGN="center"
  45 >Privoxy 3.0.27 User Manual</TH
  46 ></TR
  47 ><TR
  48 ><TD
  49 WIDTH="10%"
  50 ALIGN="left"
  51 VALIGN="bottom"
  52 ><A
  53 HREF="actions-file.html"
  54 ACCESSKEY="P"
  55 >Prev</A
  56 ></TD
  57 ><TD
  58 WIDTH="80%"
  59 ALIGN="center"
  60 VALIGN="bottom"
  61 ></TD
  62 ><TD
  63 WIDTH="10%"
  64 ALIGN="right"
  65 VALIGN="bottom"
  66 ><A
  67 HREF="templates.html"
  68 ACCESSKEY="N"
  69 >Next</A
  70 ></TD
  71 ></TR
  72 ></TABLE
  73 ><HR
  74 ALIGN="LEFT"
  75 WIDTH="100%"></DIV
  76 ><DIV
  77 CLASS="SECT1"
  78 ><H1
  79 CLASS="SECT1"
  80 ><A
  81 NAME="FILTER-FILE"
  82 >9. Filter Files</A
  83 ></H1
  84 ><P
  85 > On-the-fly text substitutions need
  86  to be defined in a <SPAN
  87 CLASS="QUOTE"
  88 >"filter file"</SPAN
  89 >. Once defined, they
  90  can then be invoked as an <SPAN
  91 CLASS="QUOTE"
  92 >"action"</SPAN
  93 >.</P
  94 ><P
  95 > <SPAN
  96 CLASS="APPLICATION"
  97 >Privoxy</SPAN
  98 > supports three different pcrs-based filter actions:
  99  <TT
 100 CLASS="LITERAL"
 101 ><A
 102 HREF="actions-file.html#FILTER"
 103 >filter</A
 104 ></TT
 105 > to
 106  rewrite the content that is send to the client,
 107  <TT
 108 CLASS="LITERAL"
 109 ><A
 110 HREF="actions-file.html#CLIENT-HEADER-FILTER"
 111 >client-header-filter</A
 112 ></TT
 113 >
 114  to rewrite headers that are send by the client, and
 115  <TT
 116 CLASS="LITERAL"
 117 ><A
 118 HREF="actions-file.html#SERVER-HEADER-FILTER"
 119 >server-header-filter</A
 120 ></TT
 121 >
 122  to rewrite headers that are send by the server.</P
 123 ><P
 124 > <SPAN
 125 CLASS="APPLICATION"
 126 >Privoxy</SPAN
 127 > also supports two tagger actions:
 128  <TT
 129 CLASS="LITERAL"
 130 ><A
 131 HREF="actions-file.html#CLIENT-HEADER-TAGGER"
 132 >client-header-tagger</A
 133 ></TT
 134 >
 135  and
 136  <TT
 137 CLASS="LITERAL"
 138 ><A
 139 HREF="actions-file.html#SERVER-HEADER-TAGGER"
 140 >server-header-tagger</A
 141 ></TT
 142 >.
 143  Taggers and filters use the same syntax in the filter files, the difference
 144  is that taggers don't modify the text they are filtering, but use a rewritten
 145  version of the filtered text as tag. The tags can then be used to change the
 146  applying actions through sections with <A
 147 HREF="actions-file.html#TAG-PATTERN"
 148 >tag-patterns</A
 149 >.</P
 150 ><P
 151 > Finally <SPAN
 152 CLASS="APPLICATION"
 153 >Privoxy</SPAN
 154 > supports the
 155  <TT
 156 CLASS="LITERAL"
 157 ><A
 158 HREF="actions-file.html#EXTERNAL-FILTER"
 159 >external-filter</A
 160 ></TT
 161 > action
 162  to enable <TT
 163 CLASS="LITERAL"
 164 ><A
 165 HREF="filter-file.html#EXTERNAL-FILTER-SYNTAX"
 166 >external filters</A
 167 ></TT
 168 >
 169  written in proper programming languages.</P
 170 ><P
 171 > Multiple filter files can be defined through the <TT
 172 CLASS="LITERAL"
 173 > <A
 174 HREF="config.html#FILTERFILE"
 175 >filterfile</A
 176 ></TT
 177 > config directive. The filters
 178  as supplied by the developers are located in
 179  <TT
 180 CLASS="FILENAME"
 181 >default.filter</TT
 182 >. It is recommended that any locally
 183  defined or modified filters go in a separately defined file such as
 184  <TT
 185 CLASS="FILENAME"
 186 >user.filter</TT
 187 >.
 188  </P
 189 ><P
 190 > Common tasks for content filters are to eliminate common annoyances in
 191  HTML and JavaScript, such as pop-up windows,
 192  exit consoles, crippled windows without navigation tools, the
 193  infamous &#60;BLINK&#62; tag etc, to suppress images with certain
 194  width and height attributes (standard banner sizes or web-bugs),
 195  or just to have fun.</P
 196 ><P
 197 > Enabled content filters are applied to any content whose
 198  <SPAN
 199 CLASS="QUOTE"
 200 >"Content Type"</SPAN
 201 > header is recognised as a sign
 202  of text-based content, with the exception of <TT
 203 CLASS="LITERAL"
 204 >text/plain</TT
 205 >.
 206  Use the <A
 207 HREF="actions-file.html#FORCE-TEXT-MODE"
 208 >force-text-mode</A
 209 > action
 210  to also filter other content.</P
 211 ><P
 212 > Substitutions are made at the source level, so if you want to <SPAN
 213 CLASS="QUOTE"
 214 >"roll
 215  your own"</SPAN
 216 > filters, you should first be familiar with HTML syntax,
 217  and, of course, regular expressions.</P
 218 ><P
 219 > Just like the <A
 220 HREF="actions-file.html"
 221 >actions files</A
 222 >, the
 223  filter file is organized in sections, which are called <SPAN
 224 CLASS="emphasis"
 225 ><I
 226 CLASS="EMPHASIS"
 227 >filters</I
 228 ></SPAN
 229 >
 230  here. Each filter consists of a heading line, that starts with one of the
 231  <SPAN
 232 CLASS="emphasis"
 233 ><I
 234 CLASS="EMPHASIS"
 235 >keywords</I
 236 ></SPAN
 237 > <TT
 238 CLASS="LITERAL"
 239 >FILTER:</TT
 240 >,
 241  <TT
 242 CLASS="LITERAL"
 243 >CLIENT-HEADER-FILTER:</TT
 244 > or <TT
 245 CLASS="LITERAL"
 246 >SERVER-HEADER-FILTER:</TT
 247 >
 248  followed by the filter's <SPAN
 249 CLASS="emphasis"
 250 ><I
 251 CLASS="EMPHASIS"
 252 >name</I
 253 ></SPAN
 254 >, and a short (one line)
 255  <SPAN
 256 CLASS="emphasis"
 257 ><I
 258 CLASS="EMPHASIS"
 259 >description</I
 260 ></SPAN
 261 > of what it does. Below that line
 262  come the <SPAN
 263 CLASS="emphasis"
 264 ><I
 265 CLASS="EMPHASIS"
 266 >jobs</I
 267 ></SPAN
 268 >, i.e. lines that define the actual
 269  text substitutions. By convention, the name of a filter
 270  should describe what the filter <SPAN
 271 CLASS="emphasis"
 272 ><I
 273 CLASS="EMPHASIS"
 274 >eliminates</I
 275 ></SPAN
 276 >. The
 277  comment is used in the <A
 278 HREF="http://config.privoxy.org/"
 279 TARGET="_top"
 280 >web-based
 281  user interface</A
 282 >.</P
 283 ><P
 284 > Once a filter called <TT
 285 CLASS="REPLACEABLE"
 286 ><I
 287 >name</I
 288 ></TT
 289 > has been defined
 290  in the filter file, it can be invoked by using an action of the form
 291  +<TT
 292 CLASS="LITERAL"
 293 ><A
 294 HREF="actions-file.html#FILTER"
 295 >filter</A
 296 >{<TT
 297 CLASS="REPLACEABLE"
 298 ><I
 299 >name</I
 300 ></TT
 301 >}</TT
 302 >
 303  in any <A
 304 HREF="actions-file.html"
 305 >actions file</A
 306 >.</P
 307 ><P
 308 > Filter definitions start with a header line that contains the filter
 309  type, the filter name and the filter description.
 310  A content filter header line for a filter called <SPAN
 311 CLASS="QUOTE"
 312 >"foo"</SPAN
 313 > could look
 314  like this:</P
 315 ><TABLE
 316 BORDER="0"
 317 BGCOLOR="#E0E0E0"
 318 WIDTH="100%"
 319 ><TR
 320 ><TD
 321 ><PRE
 322 CLASS="SCREEN"
 323 >FILTER: foo Replace all "foo" with "bar"</PRE
 324 ></TD
 325 ></TR
 326 ></TABLE
 327 ><P
 328 > Below that line, and up to the next header line, come the jobs that
 329  define what text replacements the filter executes. They are specified
 330  in a syntax that imitates <A
 331 HREF="http://www.perl.org/"
 332 TARGET="_top"
 333 >Perl</A
 334 >'s
 335  <TT
 336 CLASS="LITERAL"
 337 >s///</TT
 338 > operator. If you are familiar with Perl, you
 339  will find this to be quite intuitive, and may want to look at the
 340  PCRS documentation for the subtle differences to Perl behaviour.</P
 341 ><P
 342 > Most notably, the non-standard option letter <TT
 343 CLASS="LITERAL"
 344 >U</TT
 345 > is supported,
 346  which turns the default to ungreedy matching (add <TT
 347 CLASS="LITERAL"
 348 >?</TT
 349 > to
 350  quantifiers to turn them greedy again).</P
 351 ><P
 352 > The non-standard option letter <TT
 353 CLASS="LITERAL"
 354 >D</TT
 355 > (dynamic) allows
 356  to use the variables $host, $origin (the IP address the request came from),
 357  $path, $url and $listen-address (the address on which Privoxy accepted the
 358  client request. Example: 127.0.0.1:8118).
 359  They will be replaced with the value they refer to before the filter
 360  is executed.</P
 361 ><P
 362 > Note that '$' is a bad choice for a delimiter in a dynamic filter as you
 363  might end up with unintended variables if you use a variable name
 364  directly after the delimiter. Variables will be resolved without
 365  escaping anything, therefore you also have to be careful not to chose
 366  delimiters that appear in the replacement text. For example '&#60;' should
 367  be save, while '?' will sooner or later cause conflicts with $url.</P
 368 ><P
 369 > The non-standard option letter <TT
 370 CLASS="LITERAL"
 371 >T</TT
 372 > (trivial) prevents
 373  parsing for backreferences in the substitute. Use it if you want to include
 374  text like '$&#38;' in your substitute without quoting.</P
 375 ><P
 376 > If you are new to
 377   <A
 378 HREF="http://en.wikipedia.org/wiki/Regular_expressions"
 379 TARGET="_top"
 380 ><SPAN
 381 CLASS="QUOTE"
 382 >"Regular
 383   Expressions"</SPAN
 384 ></A
 385 >, you might want to take a look at
 386  the <A
 387 HREF="appendix.html#REGEX"
 388 >Appendix on regular expressions</A
 389 >, and
 390  see the <A
 391 HREF="http://perldoc.perl.org/perlre.html"
 392 TARGET="_top"
 393 >Perl
 394  manual</A
 395 > for
 396  <A
 397 HREF="http://perldoc.perl.org/perlop.html"
 398 TARGET="_top"
 399 >the
 400  <TT
 401 CLASS="LITERAL"
 402 >s///</TT
 403 > operator's syntax</A
 404 > and <A
 405 HREF="http://perldoc.perl.org/perlre.html"
 406 TARGET="_top"
 407 >Perl-style regular
 408  expressions</A
 409 > in general.
 410  The below examples might also help to get you started.</P
 411 ><DIV
 412 CLASS="SECT2"
 413 ><H2
 414 CLASS="SECT2"
 415 ><A
 416 NAME="FILTER-FILE-TUT"
 417 >9.1. Filter File Tutorial</A
 418 ></H2
 419 ><P
 420 > Now, let's complete our <SPAN
 421 CLASS="QUOTE"
 422 >"foo"</SPAN
 423 > content filter. We have already defined
 424  the heading, but the jobs are still missing. Since all it does is to replace
 425  <SPAN
 426 CLASS="QUOTE"
 427 >"foo"</SPAN
 428 > with <SPAN
 429 CLASS="QUOTE"
 430 >"bar"</SPAN
 431 >, there is only one (trivial) job
 432  needed:</P
 433 ><TABLE
 434 BORDER="0"
 435 BGCOLOR="#E0E0E0"
 436 WIDTH="100%"
 437 ><TR
 438 ><TD
 439 ><PRE
 440 CLASS="SCREEN"
 441 >s/foo/bar/</PRE
 442 ></TD
 443 ></TR
 444 ></TABLE
 445 ><P
 446 > But wait! Didn't the comment say that <SPAN
 447 CLASS="emphasis"
 448 ><I
 449 CLASS="EMPHASIS"
 450 >all</I
 451 ></SPAN
 452 > occurrences
 453  of <SPAN
 454 CLASS="QUOTE"
 455 >"foo"</SPAN
 456 > should be replaced? Our current job will only take
 457  care of the first <SPAN
 458 CLASS="QUOTE"
 459 >"foo"</SPAN
 460 > on each page. For global substitution,
 461  we'll need to add the <TT
 462 CLASS="LITERAL"
 463 >g</TT
 464 > option:</P
 465 ><TABLE
 466 BORDER="0"
 467 BGCOLOR="#E0E0E0"
 468 WIDTH="100%"
 469 ><TR
 470 ><TD
 471 ><PRE
 472 CLASS="SCREEN"
 473 >s/foo/bar/g</PRE
 474 ></TD
 475 ></TR
 476 ></TABLE
 477 ><P
 478 > Our complete filter now looks like this:</P
 479 ><TABLE
 480 BORDER="0"
 481 BGCOLOR="#E0E0E0"
 482 WIDTH="100%"
 483 ><TR
 484 ><TD
 485 ><PRE
 486 CLASS="SCREEN"
 487 >FILTER: foo Replace all "foo" with "bar"
 488 s/foo/bar/g</PRE
 489 ></TD
 490 ></TR
 491 ></TABLE
 492 ><P
 493 > Let's look at some real filters for more interesting examples. Here you see
 494  a filter that protects against some common annoyances that arise from JavaScript
 495  abuse. Let's look at its jobs one after the other:</P
 496 ><TABLE
 497 BORDER="0"
 498 BGCOLOR="#E0E0E0"
 499 WIDTH="100%"
 500 ><TR
 501 ><TD
 502 ><PRE
 503 CLASS="SCREEN"
 504 >FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse
 505
 506 # Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm
 507 #
 508 s|(&#60;script.*)document\.referrer(.*&#60;/script&#62;)|$1"Not Your Business!"$2|Usg</PRE
 509 ></TD
 510 ></TR
 511 ></TABLE
 512 ><P
 513 > Following the header line and a comment, you see the job. Note that it uses
 514  <TT
 515 CLASS="LITERAL"
 516 >|</TT
 517 > as the delimiter instead of <TT
 518 CLASS="LITERAL"
 519 >/</TT
 520 >, because
 521  the pattern contains a forward slash, which would otherwise have to be escaped
 522  by a backslash (<TT
 523 CLASS="LITERAL"
 524 >\</TT
 525 >).</P
 526 ><P
 527 > Now, let's examine the pattern: it starts with the text <TT
 528 CLASS="LITERAL"
 529 >&#60;script.*</TT
 530 >
 531  enclosed in parentheses. Since the dot matches any character, and <TT
 532 CLASS="LITERAL"
 533 >*</TT
 534 >
 535  means: <SPAN
 536 CLASS="QUOTE"
 537 >"Match an arbitrary number of the element left of myself"</SPAN
 538 >, this
 539  matches <SPAN
 540 CLASS="QUOTE"
 541 >"&#60;script"</SPAN
 542 >, followed by <SPAN
 543 CLASS="emphasis"
 544 ><I
 545 CLASS="EMPHASIS"
 546 >any</I
 547 ></SPAN
 548 > text, i.e.
 549  it matches the whole page, from the start of the first &#60;script&#62; tag.</P
 550 ><P
 551 > That's more than we want, but the pattern continues: <TT
 552 CLASS="LITERAL"
 553 >document\.referrer</TT
 554 >
 555  matches only the exact string <SPAN
 556 CLASS="QUOTE"
 557 >"document.referrer"</SPAN
 558 >. The dot needed to
 559  be <SPAN
 560 CLASS="emphasis"
 561 ><I
 562 CLASS="EMPHASIS"
 563 >escaped</I
 564 ></SPAN
 565 >, i.e. preceded by a backslash, to take away its
 566  special meaning as a joker, and make it just a regular dot. So far, the meaning is:
 567  Match from the start of the first &#60;script&#62; tag in a the page, up to, and including,
 568  the text <SPAN
 569 CLASS="QUOTE"
 570 >"document.referrer"</SPAN
 571 >, if <SPAN
 572 CLASS="emphasis"
 573 ><I
 574 CLASS="EMPHASIS"
 575 >both</I
 576 ></SPAN
 577 > are present
 578  in the page (and appear in that order).</P
 579 ><P
 580 > But there's still more pattern to go. The next element, again enclosed in parentheses,
 581  is <TT
 582 CLASS="LITERAL"
 583 >.*&#60;/script&#62;</TT
 584 >. You already know what <TT
 585 CLASS="LITERAL"
 586 >.*</TT
 587 >
 588  means, so the whole pattern translates to: Match from the start of the first  &#60;script&#62;
 589  tag in a page to the end of the last &#60;script&#62; tag, provided that the text
 590  <SPAN
 591 CLASS="QUOTE"
 592 >"document.referrer"</SPAN
 593 > appears somewhere in between.</P
 594 ><P
 595 > This is still not the whole story, since we have ignored the options and the parentheses:
 596  The portions of the page matched by sub-patterns that are enclosed in parentheses, will be
 597  remembered and be available through the variables <TT
 598 CLASS="LITERAL"
 599 >$1, $2, ...</TT
 600 > in
 601  the substitute. The <TT
 602 CLASS="LITERAL"
 603 >U</TT
 604 > option switches to ungreedy matching, which means
 605  that the first <TT
 606 CLASS="LITERAL"
 607 >.*</TT
 608 > in the pattern will only <SPAN
 609 CLASS="QUOTE"
 610 >"eat up"</SPAN
 611 > all
 612  text in between <SPAN
 613 CLASS="QUOTE"
 614 >"&#60;script"</SPAN
 615 > and the <SPAN
 616 CLASS="emphasis"
 617 ><I
 618 CLASS="EMPHASIS"
 619 >first</I
 620 ></SPAN
 621 > occurrence
 622  of <SPAN
 623 CLASS="QUOTE"
 624 >"document.referrer"</SPAN
 625 >, and that the second <TT
 626 CLASS="LITERAL"
 627 >.*</TT
 628 > will
 629  only span the text up to the <SPAN
 630 CLASS="emphasis"
 631 ><I
 632 CLASS="EMPHASIS"
 633 >first</I
 634 ></SPAN
 635 > <SPAN
 636 CLASS="QUOTE"
 637 >"&#60;/script&#62;"</SPAN
 638 >
 639  tag. Furthermore, the <TT
 640 CLASS="LITERAL"
 641 >s</TT
 642 > option says that the match may span
 643  multiple lines in the page, and the <TT
 644 CLASS="LITERAL"
 645 >g</TT
 646 > option again means that the
 647  substitution is global.</P
 648 ><P
 649 > So, to summarize, the pattern means: Match all scripts that contain the text
 650  <SPAN
 651 CLASS="QUOTE"
 652 >"document.referrer"</SPAN
 653 >. Remember the parts of the script from
 654  (and including) the start tag up to (and excluding) the string
 655  <SPAN
 656 CLASS="QUOTE"
 657 >"document.referrer"</SPAN
 658 > as <TT
 659 CLASS="LITERAL"
 660 >$1</TT
 661 >, and the part following
 662  that string, up to and including the closing tag, as <TT
 663 CLASS="LITERAL"
 664 >$2</TT
 665 >.</P
 666 ><P
 667 > Now the pattern is deciphered, but wasn't this about substituting things? So
 668  lets look at the substitute: <TT
 669 CLASS="LITERAL"
 670 >$1"Not Your Business!"$2</TT
 671 > is
 672  easy to read: The text remembered as <TT
 673 CLASS="LITERAL"
 674 >$1</TT
 675 >, followed by
 676  <TT
 677 CLASS="LITERAL"
 678 >"Not Your Business!"</TT
 679 > (<SPAN
 680 CLASS="emphasis"
 681 ><I
 682 CLASS="EMPHASIS"
 683 >including</I
 684 ></SPAN
 685 >
 686  the quotation marks!), followed by the text remembered as <TT
 687 CLASS="LITERAL"
 688 >$2</TT
 689 >.
 690  This produces an exact copy of the original string, with the middle part
 691  (the <SPAN
 692 CLASS="QUOTE"
 693 >"document.referrer"</SPAN
 694 >) replaced by <TT
 695 CLASS="LITERAL"
 696 >"Not Your
 697  Business!"</TT
 698 >.</P
 699 ><P
 700 > The whole job now reads: Replace <SPAN
 701 CLASS="QUOTE"
 702 >"document.referrer"</SPAN
 703 > by
 704  <TT
 705 CLASS="LITERAL"
 706 >"Not Your Business!"</TT
 707 > wherever it appears inside a
 708  &#60;script&#62; tag. Note that this job won't break JavaScript syntax,
 709  since both the original and the replacement are syntactically valid
 710  string objects. The script just won't have access to the referrer
 711  information anymore.</P
 712 ><P
 713 > We'll show you two other jobs from the JavaScript taming department, but
 714  this time only point out the constructs of special interest:</P
 715 ><TABLE
 716 BORDER="0"
 717 BGCOLOR="#E0E0E0"
 718 WIDTH="100%"
 719 ><TR
 720 ><TD
 721 ><PRE
 722 CLASS="SCREEN"
 723 ># The status bar is for displaying link targets, not pointless blahblah
 724 #
 725 s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig</PRE
 726 ></TD
 727 ></TR
 728 ></TABLE
 729 ><P
 730 > <TT
 731 CLASS="LITERAL"
 732 >\s</TT
 733 > stands for whitespace characters (space, tab, newline,
 734  carriage return, form feed), so that <TT
 735 CLASS="LITERAL"
 736 >\s*</TT
 737 > means: <SPAN
 738 CLASS="QUOTE"
 739 >"zero
 740  or more whitespace"</SPAN
 741 >. The <TT
 742 CLASS="LITERAL"
 743 >?</TT
 744 > in <TT
 745 CLASS="LITERAL"
 746 >.*?</TT
 747 >
 748  makes this matching of arbitrary text ungreedy. (Note that the <TT
 749 CLASS="LITERAL"
 750 >U</TT
 751 >
 752  option is not set). The <TT
 753 CLASS="LITERAL"
 754 >['"]</TT
 755 > construct means: <SPAN
 756 CLASS="QUOTE"
 757 >"a single
 758  <SPAN
 759 CLASS="emphasis"
 760 ><I
 761 CLASS="EMPHASIS"
 762 >or</I
 763 ></SPAN
 764 > a double quote"</SPAN
 765 >. Finally, <TT
 766 CLASS="LITERAL"
 767 >\1</TT
 768 > is
 769  a back-reference to the first parenthesis just like <TT
 770 CLASS="LITERAL"
 771 >$1</TT
 772 > above,
 773  with the difference that in the <SPAN
 774 CLASS="emphasis"
 775 ><I
 776 CLASS="EMPHASIS"
 777 >pattern</I
 778 ></SPAN
 779 >, a backslash indicates
 780  a back-reference, whereas in the <SPAN
 781 CLASS="emphasis"
 782 ><I
 783 CLASS="EMPHASIS"
 784 >substitute</I
 785 ></SPAN
 786 >, it's the dollar.</P
 787 ><P
 788 > So what does this job do? It replaces assignments of single- or double-quoted
 789  strings to the <SPAN
 790 CLASS="QUOTE"
 791 >"window.status"</SPAN
 792 > object with a dummy assignment
 793  (using a variable name that is hopefully odd enough not to conflict with
 794  real variables in scripts). Thus, it catches many cases where e.g. pointless
 795  descriptions are displayed in the status bar instead of the link target when
 796  you move your mouse over links.</P
 797 ><TABLE
 798 BORDER="0"
 799 BGCOLOR="#E0E0E0"
 800 WIDTH="100%"
 801 ><TR
 802 ><TD
 803 ><PRE
 804 CLASS="SCREEN"
 805 ># Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
 806 #
 807 s/(&#60;body [^&#62;]*)onunload(.*&#62;)/$1never$2/iU</PRE
 808 ></TD
 809 ></TR
 810 ></TABLE
 811 ><P
 812 > Including the
 813  <A
 814 HREF="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents"
 815 TARGET="_top"
 816 >OnUnload
 817  event binding</A
 818 > in the HTML DOM was a <SPAN
 819 CLASS="emphasis"
 820 ><I
 821 CLASS="EMPHASIS"
 822 >CRIME</I
 823 ></SPAN
 824 >.
 825  When I close a browser window, I want it to close and die. Basta.
 826  This job replaces the <SPAN
 827 CLASS="QUOTE"
 828 >"onunload"</SPAN
 829 > attribute in
 830  <SPAN
 831 CLASS="QUOTE"
 832 >"&#60;body&#62;"</SPAN
 833 > tags with the dummy word <TT
 834 CLASS="LITERAL"
 835 >never</TT
 836 >.
 837  Note that the <TT
 838 CLASS="LITERAL"
 839 >i</TT
 840 > option makes the pattern matching
 841  case-insensitive. Also note that ungreedy matching alone doesn't always guarantee
 842  a minimal match: In the first parenthesis, we had to use <TT
 843 CLASS="LITERAL"
 844 >[^&#62;]*</TT
 845 >
 846  instead of <TT
 847 CLASS="LITERAL"
 848 >.*</TT
 849 > to prevent the match from exceeding the
 850  &#60;body&#62; tag if it doesn't contain <SPAN
 851 CLASS="QUOTE"
 852 >"OnUnload"</SPAN
 853 >, but the page's
 854  content does.</P
 855 ><P
 856 > The last example is from the fun department:</P
 857 ><TABLE
 858 BORDER="0"
 859 BGCOLOR="#E0E0E0"
 860 WIDTH="100%"
 861 ><TR
 862 ><TD
 863 ><PRE
 864 CLASS="SCREEN"
 865 >FILTER: fun Fun text replacements
 866
 867 # Spice the daily news:
 868 #
 869 s/microsoft(?!\.com)/MicroSuck/ig</PRE
 870 ></TD
 871 ></TR
 872 ></TABLE
 873 ><P
 874 > Note the <TT
 875 CLASS="LITERAL"
 876 >(?!\.com)</TT
 877 > part (a so-called negative lookahead)
 878  in the job's pattern, which means: Don't match, if the string
 879  <SPAN
 880 CLASS="QUOTE"
 881 >".com"</SPAN
 882 > appears directly following <SPAN
 883 CLASS="QUOTE"
 884 >"microsoft"</SPAN
 885 >
 886  in the page. This prevents links to microsoft.com from being trashed, while
 887  still replacing the word everywhere else.</P
 888 ><TABLE
 889 BORDER="0"
 890 BGCOLOR="#E0E0E0"
 891 WIDTH="100%"
 892 ><TR
 893 ><TD
 894 ><PRE
 895 CLASS="SCREEN"
 896 ># Buzzword Bingo (example for extended regex syntax)
 897 #
 898 s* industry[ -]leading \
 899 |  cutting[ -]edge \
 900 |  customer[ -]focused \
 901 |  market[ -]driven \
 902 |  award[ -]winning # Comments are OK, too! \
 903 |  high[ -]performance \
 904 |  solutions[ -]based \
 905 |  unmatched \
 906 |  unparalleled \
 907 |  unrivalled \
 908 *&#60;font color="red"&#62;&#60;b&#62;BINGO!&#60;/b&#62;&#60;/font&#62; \
 909 *igx</PRE
 910 ></TD
 911 ></TR
 912 ></TABLE
 913 ><P
 914 > The <TT
 915 CLASS="LITERAL"
 916 >x</TT
 917 > option in this job turns on extended syntax, and allows for
 918  e.g. the liberal use of (non-interpreted!) whitespace for nicer formatting.</P
 919 ><P
 920 > You get the idea?</P
 921 ></DIV
 922 ><DIV
 923 CLASS="SECT2"
 924 ><H2
 925 CLASS="SECT2"
 926 ><A
 927 NAME="PREDEFINED-FILTERS"
 928 >9.2. The Pre-defined Filters</A
 929 ></H2
 930 ><P
 931 >The distribution <TT
 932 CLASS="FILENAME"
 933 >default.filter</TT
 934 > file contains a selection of
 935 pre-defined filters for your convenience:</P
 936 ><P
 937 ></P
 938 ><DIV
 939 CLASS="VARIABLELIST"
 940 ><DL
 941 ><DT
 942 ><SPAN
 943 CLASS="emphasis"
 944 ><I
 945 CLASS="EMPHASIS"
 946 >js-annoyances</I
 947 ></SPAN
 948 ></DT
 949 ><DD
 950 ><P
 951 >    The purpose of this filter is to get rid of particularly annoying JavaScript abuse.
 952     To that end, it
 953    </P
 954 ><P
 955 ></P
 956 ><UL
 957 ><LI
 958 ><P
 959 >      replaces JavaScript references to the browser's referrer information
 960       with the string "Not Your Business!". This compliments the <TT
 961 CLASS="LITERAL"
 962 ><A
 963 HREF="actions-file.html#HIDE-REFERRER"
 964 >hide-referrer</A
 965 ></TT
 966 > action on the content level.
 967      </P
 968 ></LI
 969 ><LI
 970 ><P
 971 >      removes the bindings to the DOM's
 972       <A
 973 HREF="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents"
 974 TARGET="_top"
 975 >unload
 976       event</A
 977 > which we feel has no right to exist and is responsible for most <SPAN
 978 CLASS="QUOTE"
 979 >"exit consoles"</SPAN
 980 >, i.e.
 981       nasty windows that pop up when you close another one.
 982      </P
 983 ></LI
 984 ><LI
 985 ><P
 986 >      removes code that causes new windows to be opened with undesired properties, such as being
 987       full-screen, non-resizeable, without location, status or menu bar etc.
 988      </P
 989 ></LI
 990 ></UL
 991 ><P
 992 >    Use with caution. This is an aggressive filter, and can break sites that
 993     rely heavily on JavaScript.
 994    </P
 995 ></DD
 996 ><DT
 997 ><SPAN
 998 CLASS="emphasis"
 999 ><I
1000 CLASS="EMPHASIS"
1001 >js-events</I
1002 ></SPAN
1003 ></DT
1004 ><DD
1005 ><P
1006 >    This is a very radical measure. It removes virtually all JavaScript event bindings, which
1007     means that scripts can not react to user actions such as mouse movements or clicks, window
1008     resizing etc, anymore. Use with caution!
1009    </P
1010 ><P
1011 >    We <SPAN
1012 CLASS="emphasis"
1013 ><I
1014 CLASS="EMPHASIS"
1015 >strongly discourage</I
1016 ></SPAN
1017 > using this filter as a default since it breaks
1018     many legitimate scripts. It is meant for use only on extra-nasty sites (should you really
1019     need to go there).
1020    </P
1021 ></DD
1022 ><DT
1023 ><SPAN
1024 CLASS="emphasis"
1025 ><I
1026 CLASS="EMPHASIS"
1027 >html-annoyances</I
1028 ></SPAN
1029 ></DT
1030 ><DD
1031 ><P
1032 >    This filter will undo many common instances of HTML based abuse.
1033    </P
1034 ><P
1035 >    The <TT
1036 CLASS="LITERAL"
1037 >BLINK</TT
1038 > and <TT
1039 CLASS="LITERAL"
1040 >MARQUEE</TT
1041 > tags
1042     are neutralized (yeah baby!), and browser windows will be created as
1043     resizeable (as of course they should be!), and will have location,
1044     scroll and menu bars -- even if specified otherwise.
1045    </P
1046 ></DD
1047 ><DT
1048 ><SPAN
1049 CLASS="emphasis"
1050 ><I
1051 CLASS="EMPHASIS"
1052 >content-cookies</I
1053 ></SPAN
1054 ></DT
1055 ><DD
1056 ><P
1057 >    Most cookies are set in the HTTP dialog, where they can be intercepted
1058     by the
1059     <TT
1060 CLASS="LITERAL"
1061 ><A
1062 HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
1063 >crunch-incoming-cookies</A
1064 ></TT
1065 >
1066     and <TT
1067 CLASS="LITERAL"
1068 ><A
1069 HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
1070 >crunch-outgoing-cookies</A
1071 ></TT
1072 >
1073     actions. But web sites increasingly make use of HTML meta tags and JavaScript
1074     to sneak cookies to the browser on the content level.
1075    </P
1076 ><P
1077 >    This filter disables most HTML and JavaScript code that reads or sets
1078     cookies. It cannot detect all clever uses of these types of code, so it
1079     should not be relied on as an absolute fix. Use it wherever you would also
1080     use the cookie crunch actions.
1081    </P
1082 ></DD
1083 ><DT
1084 ><SPAN
1085 CLASS="emphasis"
1086 ><I
1087 CLASS="EMPHASIS"
1088 >refresh-tags</I
1089 ></SPAN
1090 ></DT
1091 ><DD
1092 ><P
1093 >    Disable any refresh tags if the interval is greater than nine seconds (so
1094     that redirections done via refresh tags are not destroyed). This is useful
1095     for dial-on-demand setups, or for those who find this HTML feature
1096     annoying.
1097    </P
1098 ></DD
1099 ><DT
1100 ><SPAN
1101 CLASS="emphasis"
1102 ><I
1103 CLASS="EMPHASIS"
1104 >unsolicited-popups</I
1105 ></SPAN
1106 ></DT
1107 ><DD
1108 ><P
1109 >    This filter attempts to prevent only <SPAN
1110 CLASS="QUOTE"
1111 >"unsolicited"</SPAN
1112 > pop-up
1113     windows from opening, yet still allow pop-up windows that the user
1114     has explicitly chosen to open. It was added in version 3.0.1,
1115     as an improvement over earlier such filters.
1116    </P
1117 ><P
1118 >    Technical note: The filter works by redefining the window.open JavaScript
1119     function to a dummy function, <TT
1120 CLASS="LITERAL"
1121 >PrivoxyWindowOpen()</TT
1122 >,
1123     during the loading and rendering phase of each HTML page access, and
1124     restoring the function afterward.
1125    </P
1126 ><P
1127 >    This is recommended only for browsers that cannot perform this function
1128     reliably themselves. And be aware that some sites require such windows
1129     in order to function normally. Use with caution.
1130    </P
1131 ></DD
1132 ><DT
1133 ><SPAN
1134 CLASS="emphasis"
1135 ><I
1136 CLASS="EMPHASIS"
1137 >all-popups</I
1138 ></SPAN
1139 ></DT
1140 ><DD
1141 ><P
1142 >    Attempt to prevent <SPAN
1143 CLASS="emphasis"
1144 ><I
1145 CLASS="EMPHASIS"
1146 >all</I
1147 ></SPAN
1148 > pop-up windows from opening.
1149     Note this should be used with even more discretion than the above, since
1150     it is more likely to break some sites that require pop-ups for normal
1151     usage. Use with caution.
1152    </P
1153 ></DD
1154 ><DT
1155 ><SPAN
1156 CLASS="emphasis"
1157 ><I
1158 CLASS="EMPHASIS"
1159 >img-reorder</I
1160 ></SPAN
1161 ></DT
1162 ><DD
1163 ><P
1164 >    This is a helper filter that has no value if used alone. It makes the
1165     <TT
1166 CLASS="LITERAL"
1167 >banners-by-size</TT
1168 > and <TT
1169 CLASS="LITERAL"
1170 >banners-by-link</TT
1171 >
1172     (see below) filters more effective and should be enabled together with them.
1173    </P
1174 ></DD
1175 ><DT
1176 ><SPAN
1177 CLASS="emphasis"
1178 ><I
1179 CLASS="EMPHASIS"
1180 >banners-by-size</I
1181 ></SPAN
1182 ></DT
1183 ><DD
1184 ><P
1185 >    This filter removes image tags purely based on what size they are. Fortunately
1186     for us, many ads and banner images tend to conform to certain standardized
1187     sizes, which makes this filter quite effective for ad stripping purposes.
1188    </P
1189 ><P
1190 >    Occasionally this filter will cause false positives on images that are not ads,
1191     but just happen to be of one of the standard banner sizes.
1192    </P
1193 ><P
1194 >    Recommended only for those who require extreme ad blocking. The default
1195     block rules should catch 95+% of all ads <SPAN
1196 CLASS="emphasis"
1197 ><I
1198 CLASS="EMPHASIS"
1199 >without</I
1200 ></SPAN
1201 > this filter enabled.
1202    </P
1203 ></DD
1204 ><DT
1205 ><SPAN
1206 CLASS="emphasis"
1207 ><I
1208 CLASS="EMPHASIS"
1209 >banners-by-link</I
1210 ></SPAN
1211 ></DT
1212 ><DD
1213 ><P
1214 >    This is an experimental filter that attempts to kill any banners if
1215     their URLs seem to point to known or suspected click trackers. It is currently
1216     not of much value and is not recommended for use by default.
1217    </P
1218 ></DD
1219 ><DT
1220 ><SPAN
1221 CLASS="emphasis"
1222 ><I
1223 CLASS="EMPHASIS"
1224 >webbugs</I
1225 ></SPAN
1226 ></DT
1227 ><DD
1228 ><P
1229 >    Webbugs are small, invisible images (technically 1X1 GIF images), that
1230     are used to track users across websites, and collect information on them.
1231     As an HTML page is loaded by the browser, an embedded image tag causes the
1232     browser to contact a third-party site, disclosing the tracking information
1233     through the requested URL and/or cookies for that third-party domain, without
1234     the user ever becoming aware of the interaction with the third-party site.
1235     HTML-ized spam also uses a similar technique to verify email addresses.
1236    </P
1237 ><P
1238 >    This filter removes the HTML code that loads such <SPAN
1239 CLASS="QUOTE"
1240 >"webbugs"</SPAN
1241 >.
1242    </P
1243 ></DD
1244 ><DT
1245 ><SPAN
1246 CLASS="emphasis"
1247 ><I
1248 CLASS="EMPHASIS"
1249 >tiny-textforms</I
1250 ></SPAN
1251 ></DT
1252 ><DD
1253 ><P
1254 >    A rather special-purpose filter that can be used to enlarge textareas (those
1255     multi-line text boxes in web forms) and turn off hard word wrap in them.
1256     It was written for the sourceforge.net tracker system where such boxes are
1257     a nuisance, but it can be handy on other sites, too.
1258    </P
1259 ><P
1260 >    It is not recommended to use this filter as a default.
1261    </P
1262 ></DD
1263 ><DT
1264 ><SPAN
1265 CLASS="emphasis"
1266 ><I
1267 CLASS="EMPHASIS"
1268 >jumping-windows</I
1269 ></SPAN
1270 ></DT
1271 ><DD
1272 ><P
1273 >    Many consider windows that move, or resize themselves to be abusive. This filter
1274     neutralizes the related JavaScript code. Note that some sites might not display
1275     or behave as intended when using this filter. Use with caution.
1276    </P
1277 ></DD
1278 ><DT
1279 ><SPAN
1280 CLASS="emphasis"
1281 ><I
1282 CLASS="EMPHASIS"
1283 >frameset-borders</I
1284 ></SPAN
1285 ></DT
1286 ><DD
1287 ><P
1288 >    Some web designers seem to assume that everyone in the world will view their
1289     web sites using the same browser brand and version, screen resolution etc,
1290     because only that assumption could explain why they'd use static frame sizes,
1291     yet prevent their frames from being resized by the user, should they be too
1292     small to show their whole content.
1293    </P
1294 ><P
1295 >    This filter removes the related HTML code. It should only be applied to sites
1296     which need it.
1297    </P
1298 ></DD
1299 ><DT
1300 ><SPAN
1301 CLASS="emphasis"
1302 ><I
1303 CLASS="EMPHASIS"
1304 >demoronizer</I
1305 ></SPAN
1306 ></DT
1307 ><DD
1308 ><P
1309 >    Many Microsoft products that generate HTML use non-standard extensions (read:
1310     violations) of the ISO 8859-1 aka Latin-1 character set. This can cause those
1311     HTML documents to display with errors on standard-compliant platforms.
1312    </P
1313 ><P
1314 >    This filter translates the MS-only characters into Latin-1 equivalents.
1315     It is not necessary when using MS products, and will cause corruption of
1316     all documents that use 8-bit character sets other than Latin-1. It's mostly
1317     worthwhile for Europeans on non-MS platforms, if weird garbage characters
1318     sometimes appear on some pages, or user agents that don't correct for this on
1319     the fly.
1320    </P
1321 ></DD
1322 ><DT
1323 ><SPAN
1324 CLASS="emphasis"
1325 ><I
1326 CLASS="EMPHASIS"
1327 >shockwave-flash</I
1328 ></SPAN
1329 ></DT
1330 ><DD
1331 ><P
1332 >    A filter for shockwave haters. As the name suggests, this filter strips code
1333     out of web pages that is used to embed shockwave flash objects.
1334    </P
1335 ><P
1336 >   </P
1337 ></DD
1338 ><DT
1339 ><SPAN
1340 CLASS="emphasis"
1341 ><I
1342 CLASS="EMPHASIS"
1343 >quicktime-kioskmode</I
1344 ></SPAN
1345 ></DT
1346 ><DD
1347 ><P
1348 >    Change HTML code that embeds Quicktime objects so that kioskmode, which
1349     prevents saving, is disabled.
1350    </P
1351 ></DD
1352 ><DT
1353 ><SPAN
1354 CLASS="emphasis"
1355 ><I
1356 CLASS="EMPHASIS"
1357 >fun</I
1358 ></SPAN
1359 ></DT
1360 ><DD
1361 ><P
1362 >    Text replacements for subversive browsing fun. Make fun of your favorite
1363     Monopolist or play buzzword bingo.
1364    </P
1365 ></DD
1366 ><DT
1367 ><SPAN
1368 CLASS="emphasis"
1369 ><I
1370 CLASS="EMPHASIS"
1371 >crude-parental</I
1372 ></SPAN
1373 ></DT
1374 ><DD
1375 ><P
1376 >    A demonstration-only filter that shows how <SPAN
1377 CLASS="APPLICATION"
1378 >Privoxy</SPAN
1379 >
1380     can be used to delete web content on a keyword basis.
1381    </P
1382 ></DD
1383 ><DT
1384 ><SPAN
1385 CLASS="emphasis"
1386 ><I
1387 CLASS="EMPHASIS"
1388 >ie-exploits</I
1389 ></SPAN
1390 ></DT
1391 ><DD
1392 ><P
1393 >    An experimental collection of text replacements to disable malicious HTML and JavaScript
1394     code that exploits known security holes in Internet Explorer.
1395    </P
1396 ><P
1397 >    Presently, it only protects against Nimda and a cross-site scripting bug, and
1398     would need active maintenance to provide more substantial protection.
1399    </P
1400 ></DD
1401 ><DT
1402 ><SPAN
1403 CLASS="emphasis"
1404 ><I
1405 CLASS="EMPHASIS"
1406 >site-specifics</I
1407 ></SPAN
1408 ></DT
1409 ><DD
1410 ><P
1411 >    Some web sites have very specific problems, the cure for which doesn't apply
1412     anywhere else, or could even cause damage on other sites.
1413    </P
1414 ><P
1415 >    This is a collection of such site-specific cures which should only be applied
1416     to the sites they were intended for, which is what the supplied
1417     <TT
1418 CLASS="FILENAME"
1419 >default.action</TT
1420 > file does. Users shouldn't need to change
1421     anything regarding this filter.
1422    </P
1423 ></DD
1424 ><DT
1425 ><SPAN
1426 CLASS="emphasis"
1427 ><I
1428 CLASS="EMPHASIS"
1429 >google</I
1430 ></SPAN
1431 ></DT
1432 ><DD
1433 ><P
1434 >    A CSS based block for Google text ads. Also removes a width limitation
1435     and the toolbar advertisement.
1436    </P
1437 ></DD
1438 ><DT
1439 ><SPAN
1440 CLASS="emphasis"
1441 ><I
1442 CLASS="EMPHASIS"
1443 >yahoo</I
1444 ></SPAN
1445 ></DT
1446 ><DD
1447 ><P
1448 >    Another CSS based block, this time for Yahoo text ads. And removes
1449     a width limitation as well.
1450    </P
1451 ></DD
1452 ><DT
1453 ><SPAN
1454 CLASS="emphasis"
1455 ><I
1456 CLASS="EMPHASIS"
1457 >msn</I
1458 ></SPAN
1459 ></DT
1460 ><DD
1461 ><P
1462 >    Another CSS based block, this time for MSN text ads. And removes
1463     tracking URLs, as well as a width limitation.
1464    </P
1465 ></DD
1466 ><DT
1467 ><SPAN
1468 CLASS="emphasis"
1469 ><I
1470 CLASS="EMPHASIS"
1471 >blogspot</I
1472 ></SPAN
1473 ></DT
1474 ><DD
1475 ><P
1476 >    Cleans up some Blogspot blogs. Read the fine print before using this one!
1477    </P
1478 ><P
1479 >    This filter also intentionally removes some navigation stuff and sets the
1480     page width to 100%. As a result, some rounded <SPAN
1481 CLASS="QUOTE"
1482 >"corners"</SPAN
1483 > would
1484     appear to early or not at all and as fixing this would require a browser
1485     that understands background-size (CSS3), they are removed instead.
1486    </P
1487 ></DD
1488 ><DT
1489 ><SPAN
1490 CLASS="emphasis"
1491 ><I
1492 CLASS="EMPHASIS"
1493 >xml-to-html</I
1494 ></SPAN
1495 ></DT
1496 ><DD
1497 ><P
1498 >    Server-header filter to change the Content-Type from xml to html.
1499    </P
1500 ></DD
1501 ><DT
1502 ><SPAN
1503 CLASS="emphasis"
1504 ><I
1505 CLASS="EMPHASIS"
1506 >html-to-xml</I
1507 ></SPAN
1508 ></DT
1509 ><DD
1510 ><P
1511 >    Server-header filter to change the Content-Type from html to xml.
1512    </P
1513 ></DD
1514 ><DT
1515 ><SPAN
1516 CLASS="emphasis"
1517 ><I
1518 CLASS="EMPHASIS"
1519 >no-ping</I
1520 ></SPAN
1521 ></DT
1522 ><DD
1523 ><P
1524 >    Removes the non-standard <TT
1525 CLASS="LITERAL"
1526 >ping</TT
1527 > attribute from
1528     anchor and area HTML tags.
1529    </P
1530 ></DD
1531 ><DT
1532 ><SPAN
1533 CLASS="emphasis"
1534 ><I
1535 CLASS="EMPHASIS"
1536 >hide-tor-exit-notation</I
1537 ></SPAN
1538 ></DT
1539 ><DD
1540 ><P
1541 >    Client-header filter to remove the <B
1542 CLASS="COMMAND"
1543 >Tor</B
1544 > exit node notation
1545     found in Host and Referer headers.
1546    </P
1547 ><P
1548 >    If <SPAN
1549 CLASS="APPLICATION"
1550 >Privoxy</SPAN
1551 > and <B
1552 CLASS="COMMAND"
1553 >Tor</B
1554 > are chained and <SPAN
1555 CLASS="APPLICATION"
1556 >Privoxy</SPAN
1557 >
1558     is configured to use socks4a, one can use <SPAN
1559 CLASS="QUOTE"
1560 >"http://www.example.org.foobar.exit/"</SPAN
1561 >
1562     to access the host <SPAN
1563 CLASS="QUOTE"
1564 >"www.example.org"</SPAN
1565 > through the
1566     <B
1567 CLASS="COMMAND"
1568 >Tor</B
1569 > exit node <SPAN
1570 CLASS="QUOTE"
1571 >"foobar"</SPAN
1572 >.
1573    </P
1574 ><P
1575 >    As the HTTP client isn't aware of this notation, it treats the
1576     whole string <SPAN
1577 CLASS="QUOTE"
1578 >"www.example.org.foobar.exit"</SPAN
1579 > as host and uses it
1580     for the <SPAN
1581 CLASS="QUOTE"
1582 >"Host"</SPAN
1583 > and <SPAN
1584 CLASS="QUOTE"
1585 >"Referer"</SPAN
1586 > headers. From the
1587     server's point of view the resulting headers are invalid and can cause problems.
1588    </P
1589 ><P
1590 >    An invalid <SPAN
1591 CLASS="QUOTE"
1592 >"Referer"</SPAN
1593 > header can trigger <SPAN
1594 CLASS="QUOTE"
1595 >"hot-linking"</SPAN
1596 >
1597     protections, an invalid <SPAN
1598 CLASS="QUOTE"
1599 >"Host"</SPAN
1600 > header will make it impossible for
1601     the server to find the right vhost (several domains hosted on the same IP address).
1602    </P
1603 ><P
1604 >    This client-header filter removes the <SPAN
1605 CLASS="QUOTE"
1606 >"foo.exit"</SPAN
1607 > part in those headers
1608     to prevent the mentioned problems. Note that it only modifies
1609     the HTTP headers, it doesn't make it impossible for the server
1610     to detect your <B
1611 CLASS="COMMAND"
1612 >Tor</B
1613 > exit node based on the IP address
1614     the request is coming from.
1615    </P
1616 ></DD
1617 ></DL
1618 ></DIV
1619 ></DIV
1620 ><DIV
1621 CLASS="SECT2"
1622 ><H2
1623 CLASS="SECT2"
1624 ><A
1625 NAME="EXTERNAL-FILTER-SYNTAX"
1626 >9.3. External filter syntax</A
1627 ></H2
1628 ><P
1629 > External filters are scripts or programs that can modify the content in
1630  case common <TT
1631 CLASS="LITERAL"
1632 ><A
1633 HREF="actions-file.html#FILTER"
1634 >filters</A
1635 ></TT
1636 >
1637  aren't powerful enough.</P
1638 ><P
1639 > External filters can be written in any language the platform <SPAN
1640 CLASS="APPLICATION"
1641 >Privoxy</SPAN
1642 > runs
1643  on supports.</P
1644 ><P
1645 > They are controlled with the
1646  <TT
1647 CLASS="LITERAL"
1648 ><A
1649 HREF="actions-file.html#EXTERNAL-FILTER"
1650 >external-filter</A
1651 ></TT
1652 > action
1653  and have to be defined in the <TT
1654 CLASS="LITERAL"
1655 ><A
1656 HREF="config.html#FILTERFILE"
1657 >filterfile</A
1658 ></TT
1659 >
1660  first.</P
1661 ><P
1662 > The header looks like any other filter, but instead of pcrs jobs, external
1663  filters contain a single job which can be a program or a shell script (which
1664  may call other scripts or programs).</P
1665 ><P
1666 > External filters read the content from STDIN and write the rewritten
1667  content to STDOUT.
1668  The environment variables PRIVOXY_URL, PRIVOXY_PATH, PRIVOXY_HOST,
1669  PRIVOXY_ORIGIN, PRIVOXY_LISTEN_ADDRESS can be used to get some details
1670  about the client request.</P
1671 ><P
1672 > <SPAN
1673 CLASS="APPLICATION"
1674 >Privoxy</SPAN
1675 > will temporary store the content to filter in the
1676  <TT
1677 CLASS="LITERAL"
1678 ><A
1679 HREF="config.html#TEMPORARY-DIRECTORY"
1680 >temporary-directory</A
1681 ></TT
1682 >.</P
1683 ><TABLE
1684 BORDER="0"
1685 BGCOLOR="#E0E0E0"
1686 WIDTH="100%"
1687 ><TR
1688 ><TD
1689 ><PRE
1690 CLASS="SCREEN"
1691 >EXTERNAL-FILTER: cat Pointless example filter that doesn't actually modify the content
1692 /bin/cat
1693
1694 # Incorrect reimplementation of the filter above in POSIX shell.
1695 #
1696 # Note that it's a single job that spans multiple lines, the line
1697 # breaks are not passed to the shell, thus the semicolons are required.
1698 #
1699 # If the script isn't trivial, it is recommended to put it into an external file.
1700 #
1701 # In general, writing external filters entirely in POSIX shell is not
1702 # considered a good idea.
1703 EXTERNAL-FILTER: cat2 Pointless example filter that despite its name may actually modify the content
1704 while read line; \
1705 do \
1706   echo "$line"; \
1707 done
1708
1709 EXTERNAL-FILTER: rotate-image Rotate an image by 180 degree. Test filter with limited value.
1710 /usr/local/bin/convert - -rotate 180 -
1711
1712 EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The coordinates may need adjustment.
1713 /usr/local/bin/convert - -pointsize 16 -fill white  -annotate +17+418 "[citation needed]" -</PRE
1714 ></TD
1715 ></TR
1716 ></TABLE
1717 ><DIV
1718 CLASS="WARNING"
1719 ><P
1720 ></P
1721 ><TABLE
1722 CLASS="WARNING"
1723 BORDER="1"
1724 WIDTH="100%"
1725 ><TR
1726 ><TD
1727 ALIGN="CENTER"
1728 ><B
1729 >Warning</B
1730 ></TD
1731 ></TR
1732 ><TR
1733 ><TD
1734 ALIGN="LEFT"
1735 ><P
1736 >  Currently external filters are executed with <SPAN
1737 CLASS="APPLICATION"
1738 >Privoxy</SPAN
1739 >'s privileges!
1740   Only use external filters you understand and trust.
1741  </P
1742 ></TD
1743 ></TR
1744 ></TABLE
1745 ></DIV
1746 ><P
1747 > External filters are experimental and the syntax may change in the future.</P
1748 ></DIV
1749 ></DIV
1750 ><DIV
1751 CLASS="NAVFOOTER"
1752 ><HR
1753 ALIGN="LEFT"
1754 WIDTH="100%"><TABLE
1755 SUMMARY="Footer navigation table"
1756 WIDTH="100%"
1757 BORDER="0"
1758 CELLPADDING="0"
1759 CELLSPACING="0"
1760 ><TR
1761 ><TD
1762 WIDTH="33%"
1763 ALIGN="left"
1764 VALIGN="top"
1765 ><A
1766 HREF="actions-file.html"
1767 ACCESSKEY="P"
1768 >Prev</A
1769 ></TD
1770 ><TD
1771 WIDTH="34%"
1772 ALIGN="center"
1773 VALIGN="top"
1774 ><A
1775 HREF="index.html"
1776 ACCESSKEY="H"
1777 >Home</A
1778 ></TD
1779 ><TD
1780 WIDTH="33%"
1781 ALIGN="right"
1782 VALIGN="top"
1783 ><A
1784 HREF="templates.html"
1785 ACCESSKEY="N"
1786 >Next</A
1787 ></TD
1788 ></TR
1789 ><TR
1790 ><TD
1791 WIDTH="33%"
1792 ALIGN="left"
1793 VALIGN="top"
1794 >Actions Files</TD
1795 ><TD
1796 WIDTH="34%"
1797 ALIGN="center"
1798 VALIGN="top"
1799 >&nbsp;</TD
1800 ><TD
1801 WIDTH="33%"
1802 ALIGN="right"
1803 VALIGN="top"
1804 >Privoxy's Template Files</TD
1805 ></TR
1806 ></TABLE
1807 ></DIV
1808 ></BODY
1809 ></HTML
1810 >