doc/webserver/user-manual/appendix.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 >Appendix</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="See Also"
  14 HREF="seealso.html"><LINK
  15 REL="STYLESHEET"
  16 TYPE="text/css"
  17 HREF="../p_doc.css"><META
  18 HTTP-EQUIV="Content-Type"
  19 CONTENT="text/html;
  20 charset=ISO-8859-1">
  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.27 User Manual</TH
  43 ></TR
  44 ><TR
  45 ><TD
  46 WIDTH="10%"
  47 ALIGN="left"
  48 VALIGN="bottom"
  49 ><A
  50 HREF="seealso.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 >&nbsp;</TD
  64 ></TR
  65 ></TABLE
  66 ><HR
  67 ALIGN="LEFT"
  68 WIDTH="100%"></DIV
  69 ><DIV
  70 CLASS="SECT1"
  71 ><H1
  72 CLASS="SECT1"
  73 ><A
  74 NAME="APPENDIX"
  75 >14. Appendix</A
  76 ></H1
  77 ><DIV
  78 CLASS="SECT2"
  79 ><H2
  80 CLASS="SECT2"
  81 ><A
  82 NAME="REGEX"
  83 >14.1. Regular Expressions</A
  84 ></H2
  85 ><P
  86 > <SPAN
  87 CLASS="APPLICATION"
  88 >Privoxy</SPAN
  89 > uses Perl-style <SPAN
  90 CLASS="QUOTE"
  91 >"regular
  92  expressions"</SPAN
  93 > in its <A
  94 HREF="actions-file.html"
  95 >actions
  96  files</A
  97 > and <A
  98 HREF="filter-file.html"
  99 >filter file</A
 100 >,
 101  through the <A
 102 HREF="http://www.pcre.org/"
 103 TARGET="_top"
 104 >PCRE</A
 105 > and
 106  <SPAN
 107 CLASS="APPLICATION"
 108 >PCRS</SPAN
 109 > libraries.</P
 110 ><P
 111 > If you are reading this, you probably don't understand what <SPAN
 112 CLASS="QUOTE"
 113 >"regular
 114  expressions"</SPAN
 115 > are, or what they can do. So this will be a very brief
 116  introduction only. A full explanation would require a <A
 117 HREF="http://www.oreilly.com/catalog/regex/"
 118 TARGET="_top"
 119 >book</A
 120 > ;-)</P
 121 ><P
 122 > Regular expressions provide a language to describe patterns that can be
 123  run against strings of characters (letter, numbers, etc), to see if they
 124  match the string or not. The  patterns are themselves (sometimes complex)
 125  strings of literal characters, combined with  wild-cards, and other special
 126  characters, called meta-characters. The <SPAN
 127 CLASS="QUOTE"
 128 >"meta-characters"</SPAN
 129 > have
 130  special meanings and are used to build complex patterns to be matched against.
 131  Perl Compatible Regular Expressions are an especially convenient
 132  <SPAN
 133 CLASS="QUOTE"
 134 >"dialect"</SPAN
 135 > of the regular expression language.</P
 136 ><P
 137 > To make a simple analogy, we do something similar when we use wild-card
 138  characters when listing files with the <B
 139 CLASS="COMMAND"
 140 >dir</B
 141 > command in DOS.
 142  <TT
 143 CLASS="LITERAL"
 144 >*.*</TT
 145 > matches all filenames. The <SPAN
 146 CLASS="QUOTE"
 147 >"special"</SPAN
 148 >
 149  character here is the asterisk which matches any and all characters. We can be
 150  more specific and use <TT
 151 CLASS="LITERAL"
 152 >?</TT
 153 > to match just individual
 154  characters. So <SPAN
 155 CLASS="QUOTE"
 156 >"dir file?.text"</SPAN
 157 > would match
 158  <SPAN
 159 CLASS="QUOTE"
 160 >"file1.txt"</SPAN
 161 >, <SPAN
 162 CLASS="QUOTE"
 163 >"file2.txt"</SPAN
 164 >, etc. We are pattern
 165  matching, using a similar technique to <SPAN
 166 CLASS="QUOTE"
 167 >"regular expressions"</SPAN
 168 >!</P
 169 ><P
 170 > Regular expressions do essentially the same thing, but are much, much more
 171  powerful. There are many more <SPAN
 172 CLASS="QUOTE"
 173 >"special characters"</SPAN
 174 > and ways of
 175  building complex patterns however. Let's look at a few of the common ones,
 176  and then some examples:</P
 177 ><P
 178 ></P
 179 ><TABLE
 180 BORDER="0"
 181 ><TBODY
 182 ><TR
 183 ><TD
 184 >  <SPAN
 185 CLASS="emphasis"
 186 ><I
 187 CLASS="EMPHASIS"
 188 >.</I
 189 ></SPAN
 190 > - Matches any single character, e.g. <SPAN
 191 CLASS="QUOTE"
 192 >"a"</SPAN
 193 >,
 194   <SPAN
 195 CLASS="QUOTE"
 196 >"A"</SPAN
 197 >, <SPAN
 198 CLASS="QUOTE"
 199 >"4"</SPAN
 200 >, <SPAN
 201 CLASS="QUOTE"
 202 >":"</SPAN
 203 >, or <SPAN
 204 CLASS="QUOTE"
 205 >"@"</SPAN
 206 >.
 207  </TD
 208 ></TR
 209 ></TBODY
 210 ></TABLE
 211 ><P
 212 ></P
 213 ><P
 214 ></P
 215 ><TABLE
 216 BORDER="0"
 217 ><TBODY
 218 ><TR
 219 ><TD
 220 >  <SPAN
 221 CLASS="emphasis"
 222 ><I
 223 CLASS="EMPHASIS"
 224 >?</I
 225 ></SPAN
 226 > - The preceding character or expression is matched ZERO or ONE
 227   times. Either/or.
 228  </TD
 229 ></TR
 230 ></TBODY
 231 ></TABLE
 232 ><P
 233 ></P
 234 ><P
 235 ></P
 236 ><TABLE
 237 BORDER="0"
 238 ><TBODY
 239 ><TR
 240 ><TD
 241 >  <SPAN
 242 CLASS="emphasis"
 243 ><I
 244 CLASS="EMPHASIS"
 245 >+</I
 246 ></SPAN
 247 > - The preceding character or expression is matched ONE or MORE
 248   times.
 249  </TD
 250 ></TR
 251 ></TBODY
 252 ></TABLE
 253 ><P
 254 ></P
 255 ><P
 256 ></P
 257 ><TABLE
 258 BORDER="0"
 259 ><TBODY
 260 ><TR
 261 ><TD
 262 >  <SPAN
 263 CLASS="emphasis"
 264 ><I
 265 CLASS="EMPHASIS"
 266 >*</I
 267 ></SPAN
 268 > - The preceding character or expression is matched ZERO or MORE
 269   times.
 270  </TD
 271 ></TR
 272 ></TBODY
 273 ></TABLE
 274 ><P
 275 ></P
 276 ><P
 277 ></P
 278 ><TABLE
 279 BORDER="0"
 280 ><TBODY
 281 ><TR
 282 ><TD
 283 >  <SPAN
 284 CLASS="emphasis"
 285 ><I
 286 CLASS="EMPHASIS"
 287 >\</I
 288 ></SPAN
 289 > - The <SPAN
 290 CLASS="QUOTE"
 291 >"escape"</SPAN
 292 > character denotes that
 293   the following character should be taken literally. This is used where one of the
 294   special characters (e.g. <SPAN
 295 CLASS="QUOTE"
 296 >"."</SPAN
 297 >) needs to be taken literally and
 298   not as a special meta-character. Example: <SPAN
 299 CLASS="QUOTE"
 300 >"example\.com"</SPAN
 301 >, makes
 302   sure the period is recognized only as a period (and not expanded to its
 303   meta-character meaning of any single character).
 304  </TD
 305 ></TR
 306 ></TBODY
 307 ></TABLE
 308 ><P
 309 ></P
 310 ><P
 311 ></P
 312 ><TABLE
 313 BORDER="0"
 314 ><TBODY
 315 ><TR
 316 ><TD
 317 >  <SPAN
 318 CLASS="emphasis"
 319 ><I
 320 CLASS="EMPHASIS"
 321 >[ ]</I
 322 ></SPAN
 323 > - Characters enclosed in brackets will be matched if
 324   any of the enclosed characters are encountered. For instance, <SPAN
 325 CLASS="QUOTE"
 326 >"[0-9]"</SPAN
 327 >
 328   matches any numeric digit (zero through nine). As an example, we can combine
 329   this with <SPAN
 330 CLASS="QUOTE"
 331 >"+"</SPAN
 332 > to match any digit one of more times: <SPAN
 333 CLASS="QUOTE"
 334 >"[0-9]+"</SPAN
 335 >.
 336  </TD
 337 ></TR
 338 ></TBODY
 339 ></TABLE
 340 ><P
 341 ></P
 342 ><P
 343 ></P
 344 ><TABLE
 345 BORDER="0"
 346 ><TBODY
 347 ><TR
 348 ><TD
 349 >  <SPAN
 350 CLASS="emphasis"
 351 ><I
 352 CLASS="EMPHASIS"
 353 >( )</I
 354 ></SPAN
 355 > - parentheses are used to group a sub-expression,
 356   or multiple sub-expressions.
 357  </TD
 358 ></TR
 359 ></TBODY
 360 ></TABLE
 361 ><P
 362 ></P
 363 ><P
 364 ></P
 365 ><TABLE
 366 BORDER="0"
 367 ><TBODY
 368 ><TR
 369 ><TD
 370 >  <SPAN
 371 CLASS="emphasis"
 372 ><I
 373 CLASS="EMPHASIS"
 374 >|</I
 375 ></SPAN
 376 > - The <SPAN
 377 CLASS="QUOTE"
 378 >"bar"</SPAN
 379 > character works like an
 380   <SPAN
 381 CLASS="QUOTE"
 382 >"or"</SPAN
 383 > conditional statement. A match is successful if the
 384   sub-expression on either side of <SPAN
 385 CLASS="QUOTE"
 386 >"|"</SPAN
 387 > matches. As an example:
 388   <SPAN
 389 CLASS="QUOTE"
 390 >"/(this|that) example/"</SPAN
 391 > uses grouping and the bar character
 392   and would match either <SPAN
 393 CLASS="QUOTE"
 394 >"this example"</SPAN
 395 > or <SPAN
 396 CLASS="QUOTE"
 397 >"that
 398   example"</SPAN
 399 >, and nothing else.
 400  </TD
 401 ></TR
 402 ></TBODY
 403 ></TABLE
 404 ><P
 405 ></P
 406 ><P
 407 > These are just some of the ones you are likely to use when matching URLs with
 408  <SPAN
 409 CLASS="APPLICATION"
 410 >Privoxy</SPAN
 411 >, and is a long way from a definitive
 412  list. This is enough to get us started with a few simple examples which may
 413  be more illuminating:</P
 414 ><P
 415 > <SPAN
 416 CLASS="emphasis"
 417 ><I
 418 CLASS="EMPHASIS"
 419 ><TT
 420 CLASS="LITERAL"
 421 >/.*/banners/.*</TT
 422 ></I
 423 ></SPAN
 424 > - A  simple example
 425  that uses the common combination of <SPAN
 426 CLASS="QUOTE"
 427 >"."</SPAN
 428 > and <SPAN
 429 CLASS="QUOTE"
 430 >"*"</SPAN
 431 > to
 432  denote any character, zero or more times. In other words, any string at all.
 433  So we start with a literal forward slash, then our regular expression pattern
 434  (<SPAN
 435 CLASS="QUOTE"
 436 >".*"</SPAN
 437 >) another literal forward slash, the string
 438  <SPAN
 439 CLASS="QUOTE"
 440 >"banners"</SPAN
 441 >, another forward slash, and lastly another
 442  <SPAN
 443 CLASS="QUOTE"
 444 >".*"</SPAN
 445 >. We are building
 446  a directory path here. This will match any file with the path that has a
 447  directory named <SPAN
 448 CLASS="QUOTE"
 449 >"banners"</SPAN
 450 > in it. The <SPAN
 451 CLASS="QUOTE"
 452 >".*"</SPAN
 453 > matches
 454  any characters, and this could conceivably be more forward slashes, so it
 455  might expand into a much longer looking path. For example, this could match:
 456  <SPAN
 457 CLASS="QUOTE"
 458 >"/eye/hate/spammers/banners/annoy_me_please.gif"</SPAN
 459 >, or just
 460  <SPAN
 461 CLASS="QUOTE"
 462 >"/banners/annoying.html"</SPAN
 463 >, or almost an infinite number of other
 464  possible combinations, just so it has <SPAN
 465 CLASS="QUOTE"
 466 >"banners"</SPAN
 467 > in the path
 468  somewhere.</P
 469 ><P
 470 > And now something a little more complex:</P
 471 ><P
 472 > <SPAN
 473 CLASS="emphasis"
 474 ><I
 475 CLASS="EMPHASIS"
 476 ><TT
 477 CLASS="LITERAL"
 478 >/.*/adv((er)?ts?|ertis(ing|ements?))?/</TT
 479 ></I
 480 ></SPAN
 481 > -
 482  We have several literal forward slashes again (<SPAN
 483 CLASS="QUOTE"
 484 >"/"</SPAN
 485 >), so we are
 486  building another expression that is a file path statement. We have another
 487  <SPAN
 488 CLASS="QUOTE"
 489 >".*"</SPAN
 490 >, so we are matching against any conceivable sub-path, just so
 491  it matches our expression. The only true literal that <SPAN
 492 CLASS="emphasis"
 493 ><I
 494 CLASS="EMPHASIS"
 495 >must
 496  match</I
 497 ></SPAN
 498 > our pattern is <SPAN
 499 CLASS="APPLICATION"
 500 >adv</SPAN
 501 >, together with
 502  the forward slashes. What comes after the <SPAN
 503 CLASS="QUOTE"
 504 >"adv"</SPAN
 505 > string is the
 506  interesting part.</P
 507 ><P
 508 > Remember the <SPAN
 509 CLASS="QUOTE"
 510 >"?"</SPAN
 511 > means the preceding expression (either a
 512  literal character or anything grouped with <SPAN
 513 CLASS="QUOTE"
 514 >"(...)"</SPAN
 515 > in this case)
 516  can exist or not, since this means either zero or one match. So
 517  <SPAN
 518 CLASS="QUOTE"
 519 >"((er)?ts?|ertis(ing|ements?))"</SPAN
 520 > is optional, as are the
 521  individual sub-expressions: <SPAN
 522 CLASS="QUOTE"
 523 >"(er)"</SPAN
 524 >,
 525  <SPAN
 526 CLASS="QUOTE"
 527 >"(ing|ements?)"</SPAN
 528 >, and the <SPAN
 529 CLASS="QUOTE"
 530 >"s"</SPAN
 531 >. The <SPAN
 532 CLASS="QUOTE"
 533 >"|"</SPAN
 534 >
 535  means <SPAN
 536 CLASS="QUOTE"
 537 >"or"</SPAN
 538 >. We have two of those. For instance,
 539  <SPAN
 540 CLASS="QUOTE"
 541 >"(ing|ements?)"</SPAN
 542 >, can expand to match either <SPAN
 543 CLASS="QUOTE"
 544 >"ing"</SPAN
 545 >
 546  <SPAN
 547 CLASS="emphasis"
 548 ><I
 549 CLASS="EMPHASIS"
 550 >OR</I
 551 ></SPAN
 552 > <SPAN
 553 CLASS="QUOTE"
 554 >"ements?"</SPAN
 555 >. What is being done here, is an
 556  attempt at matching as many variations of <SPAN
 557 CLASS="QUOTE"
 558 >"advertisement"</SPAN
 559 >, and
 560  similar, as possible. So this would expand to match just <SPAN
 561 CLASS="QUOTE"
 562 >"adv"</SPAN
 563 >,
 564  or <SPAN
 565 CLASS="QUOTE"
 566 >"advert"</SPAN
 567 >, or <SPAN
 568 CLASS="QUOTE"
 569 >"adverts"</SPAN
 570 >, or
 571  <SPAN
 572 CLASS="QUOTE"
 573 >"advertising"</SPAN
 574 >, or <SPAN
 575 CLASS="QUOTE"
 576 >"advertisement"</SPAN
 577 >, or
 578  <SPAN
 579 CLASS="QUOTE"
 580 >"advertisements"</SPAN
 581 >. You get the idea. But it would not match
 582  <SPAN
 583 CLASS="QUOTE"
 584 >"advertizements"</SPAN
 585 > (with a <SPAN
 586 CLASS="QUOTE"
 587 >"z"</SPAN
 588 >). We could fix that by
 589  changing our regular expression to:
 590  <SPAN
 591 CLASS="QUOTE"
 592 >"/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/"</SPAN
 593 >, which would then match
 594  either spelling.</P
 595 ><P
 596 > <SPAN
 597 CLASS="emphasis"
 598 ><I
 599 CLASS="EMPHASIS"
 600 ><TT
 601 CLASS="LITERAL"
 602 >/.*/advert[0-9]+\.(gif|jpe?g)</TT
 603 ></I
 604 ></SPAN
 605 > - Again
 606  another path statement with forward slashes. Anything in the square brackets
 607  <SPAN
 608 CLASS="QUOTE"
 609 >"[ ]"</SPAN
 610 > can be matched. This is using <SPAN
 611 CLASS="QUOTE"
 612 >"0-9"</SPAN
 613 > as a
 614  shorthand expression to mean any digit one through nine. It is the same as
 615  saying <SPAN
 616 CLASS="QUOTE"
 617 >"0123456789"</SPAN
 618 >. So any digit matches. The <SPAN
 619 CLASS="QUOTE"
 620 >"+"</SPAN
 621 >
 622  means one or more of the preceding expression must be included. The preceding
 623  expression here is what is in the square brackets -- in this case, any digit
 624  one through nine. Then, at the end, we have a grouping: <SPAN
 625 CLASS="QUOTE"
 626 >"(gif|jpe?g)"</SPAN
 627 >.
 628  This includes a <SPAN
 629 CLASS="QUOTE"
 630 >"|"</SPAN
 631 >, so this needs to match the expression on
 632  either side of that bar character also. A simple <SPAN
 633 CLASS="QUOTE"
 634 >"gif"</SPAN
 635 > on one side, and the other
 636  side will in turn match either <SPAN
 637 CLASS="QUOTE"
 638 >"jpeg"</SPAN
 639 > or <SPAN
 640 CLASS="QUOTE"
 641 >"jpg"</SPAN
 642 >,
 643  since the <SPAN
 644 CLASS="QUOTE"
 645 >"?"</SPAN
 646 > means the letter <SPAN
 647 CLASS="QUOTE"
 648 >"e"</SPAN
 649 > is optional and
 650  can be matched once or not at all. So we are building an expression here to
 651  match image GIF or JPEG type image file. It must include the literal
 652  string <SPAN
 653 CLASS="QUOTE"
 654 >"advert"</SPAN
 655 >, then one or more digits, and a <SPAN
 656 CLASS="QUOTE"
 657 >"."</SPAN
 658 >
 659  (which is now a literal, and not a special character, since it is escaped
 660  with <SPAN
 661 CLASS="QUOTE"
 662 >"\"</SPAN
 663 >), and lastly either <SPAN
 664 CLASS="QUOTE"
 665 >"gif"</SPAN
 666 >, or
 667  <SPAN
 668 CLASS="QUOTE"
 669 >"jpeg"</SPAN
 670 >, or <SPAN
 671 CLASS="QUOTE"
 672 >"jpg"</SPAN
 673 >. Some possible matches would
 674  include: <SPAN
 675 CLASS="QUOTE"
 676 >"//advert1.jpg"</SPAN
 677 >,
 678  <SPAN
 679 CLASS="QUOTE"
 680 >"/nasty/ads/advert1234.gif"</SPAN
 681 >,
 682  <SPAN
 683 CLASS="QUOTE"
 684 >"/banners/from/hell/advert99.jpg"</SPAN
 685 >. It would not match
 686  <SPAN
 687 CLASS="QUOTE"
 688 >"advert1.gif"</SPAN
 689 > (no leading slash), or
 690  <SPAN
 691 CLASS="QUOTE"
 692 >"/adverts232.jpg"</SPAN
 693 > (the expression does not include an
 694  <SPAN
 695 CLASS="QUOTE"
 696 >"s"</SPAN
 697 >), or <SPAN
 698 CLASS="QUOTE"
 699 >"/advert1.jsp"</SPAN
 700 > (<SPAN
 701 CLASS="QUOTE"
 702 >"jsp"</SPAN
 703 > is not
 704  in the expression anywhere).</P
 705 ><P
 706 > We are barely scratching the surface of regular expressions here so that you
 707  can understand the default <SPAN
 708 CLASS="APPLICATION"
 709 >Privoxy</SPAN
 710 >
 711  configuration files, and maybe use this knowledge to customize your own
 712  installation. There is much, much more that can be done with regular
 713  expressions. Now that you know enough to get started, you can learn more on
 714  your own :/</P
 715 ><P
 716 > More reading on Perl Compatible Regular expressions:
 717  <A
 718 HREF="http://perldoc.perl.org/perlre.html"
 719 TARGET="_top"
 720 >http://perldoc.perl.org/perlre.html</A
 721 ></P
 722 ><P
 723 > For information on regular expression based substitutions and their applications
 724  in filters, please see the <A
 725 HREF="filter-file.html"
 726 >filter file tutorial</A
 727 >
 728  in this manual.</P
 729 ></DIV
 730 ><DIV
 731 CLASS="SECT2"
 732 ><H2
 733 CLASS="SECT2"
 734 ><A
 735 NAME="INTERNAL-PAGES"
 736 >14.2. Privoxy's Internal Pages</A
 737 ></H2
 738 ><P
 739 > Since <SPAN
 740 CLASS="APPLICATION"
 741 >Privoxy</SPAN
 742 > proxies each requested
 743  web page, it is easy for <SPAN
 744 CLASS="APPLICATION"
 745 >Privoxy</SPAN
 746 > to
 747  trap certain special URLs. In this way, we can talk directly to
 748  <SPAN
 749 CLASS="APPLICATION"
 750 >Privoxy</SPAN
 751 >, and see how it is
 752  configured, see how our rules are being applied, change these
 753  rules and other configuration options, and even turn
 754  <SPAN
 755 CLASS="APPLICATION"
 756 >Privoxy's</SPAN
 757 > filtering off, all with
 758  a web browser.</P
 759 ><P
 760 > The URLs listed below are the special ones that allow direct access
 761  to <SPAN
 762 CLASS="APPLICATION"
 763 >Privoxy</SPAN
 764 >. Of course,
 765  <SPAN
 766 CLASS="APPLICATION"
 767 >Privoxy</SPAN
 768 > must be running to access these. If
 769  not, you will get a friendly error message. Internet access is not
 770  necessary either.</P
 771 ><P
 772 ></P
 773 ><UL
 774 ><LI
 775 ><P
 776 >   Privoxy main page:
 777   </P
 778 ><A
 779 NAME="AEN5956"
 780 ></A
 781 ><BLOCKQUOTE
 782 CLASS="BLOCKQUOTE"
 783 ><P
 784 >     <A
 785 HREF="http://config.privoxy.org/"
 786 TARGET="_top"
 787 >http://config.privoxy.org/</A
 788 >
 789    </P
 790 ></BLOCKQUOTE
 791 ><P
 792 >   There is a shortcut: <A
 793 HREF="http://p.p/"
 794 TARGET="_top"
 795 >http://p.p/</A
 796 > (But it
 797    doesn't provide a fall-back to a real page, in case the request is not
 798    sent through <SPAN
 799 CLASS="APPLICATION"
 800 >Privoxy</SPAN
 801 >)
 802   </P
 803 ></LI
 804 ><LI
 805 ><P
 806 >    Show information about the current configuration, including viewing and
 807     editing of actions files:
 808   </P
 809 ><A
 810 NAME="AEN5964"
 811 ></A
 812 ><BLOCKQUOTE
 813 CLASS="BLOCKQUOTE"
 814 ><P
 815 >    <A
 816 HREF="http://config.privoxy.org/show-status"
 817 TARGET="_top"
 818 >http://config.privoxy.org/show-status</A
 819 >
 820    </P
 821 ></BLOCKQUOTE
 822 ></LI
 823 ><LI
 824 ><P
 825 >    Show the source code version numbers:
 826   </P
 827 ><A
 828 NAME="AEN5969"
 829 ></A
 830 ><BLOCKQUOTE
 831 CLASS="BLOCKQUOTE"
 832 ><P
 833 >    <A
 834 HREF="http://config.privoxy.org/show-version"
 835 TARGET="_top"
 836 >http://config.privoxy.org/show-version</A
 837 >
 838    </P
 839 ></BLOCKQUOTE
 840 ></LI
 841 ><LI
 842 ><P
 843 >   Show the browser's request headers:
 844   </P
 845 ><A
 846 NAME="AEN5974"
 847 ></A
 848 ><BLOCKQUOTE
 849 CLASS="BLOCKQUOTE"
 850 ><P
 851 >    <A
 852 HREF="http://config.privoxy.org/show-request"
 853 TARGET="_top"
 854 >http://config.privoxy.org/show-request</A
 855 >
 856    </P
 857 ></BLOCKQUOTE
 858 ></LI
 859 ><LI
 860 ><P
 861 >   Show which actions apply to a URL and why:
 862   </P
 863 ><A
 864 NAME="AEN5979"
 865 ></A
 866 ><BLOCKQUOTE
 867 CLASS="BLOCKQUOTE"
 868 ><P
 869 >    <A
 870 HREF="http://config.privoxy.org/show-url-info"
 871 TARGET="_top"
 872 >http://config.privoxy.org/show-url-info</A
 873 >
 874    </P
 875 ></BLOCKQUOTE
 876 ></LI
 877 ><LI
 878 ><P
 879 >   Toggle Privoxy on or off. This feature can be turned off/on in the main
 880    <TT
 881 CLASS="FILENAME"
 882 >config</TT
 883 > file. When toggled <SPAN
 884 CLASS="QUOTE"
 885 >"off"</SPAN
 886 >, <SPAN
 887 CLASS="QUOTE"
 888 >"Privoxy"</SPAN
 889 >
 890    continues to run, but only as a pass-through proxy, with no actions taking
 891    place:
 892   </P
 893 ><A
 894 NAME="AEN5987"
 895 ></A
 896 ><BLOCKQUOTE
 897 CLASS="BLOCKQUOTE"
 898 ><P
 899 >    <A
 900 HREF="http://config.privoxy.org/toggle"
 901 TARGET="_top"
 902 >http://config.privoxy.org/toggle</A
 903 >
 904    </P
 905 ></BLOCKQUOTE
 906 ><P
 907 >   Short cuts. Turn off, then on:
 908   </P
 909 ><A
 910 NAME="AEN5991"
 911 ></A
 912 ><BLOCKQUOTE
 913 CLASS="BLOCKQUOTE"
 914 ><P
 915 >     <A
 916 HREF="http://config.privoxy.org/toggle?set=disable"
 917 TARGET="_top"
 918 >http://config.privoxy.org/toggle?set=disable</A
 919 >
 920    </P
 921 ></BLOCKQUOTE
 922 ><A
 923 NAME="AEN5994"
 924 ></A
 925 ><BLOCKQUOTE
 926 CLASS="BLOCKQUOTE"
 927 ><P
 928 >     <A
 929 HREF="http://config.privoxy.org/toggle?set=enable"
 930 TARGET="_top"
 931 >http://config.privoxy.org/toggle?set=enable</A
 932 >
 933    </P
 934 ></BLOCKQUOTE
 935 ></LI
 936 ></UL
 937 ></DIV
 938 ><DIV
 939 CLASS="SECT2"
 940 ><H2
 941 CLASS="SECT2"
 942 ><A
 943 NAME="CHAIN"
 944 >14.3. Chain of Events</A
 945 ></H2
 946 ><P
 947 > Let's take a quick look at how some of <SPAN
 948 CLASS="APPLICATION"
 949 >Privoxy's</SPAN
 950 >
 951  core features are triggered, and the ensuing sequence of events when a web
 952  page is requested by your browser:</P
 953 ><P
 954 ></P
 955 ><UL
 956 ><LI
 957 ><P
 958 >   First, your web browser requests a web page. The browser knows to send
 959    the request to <SPAN
 960 CLASS="APPLICATION"
 961 >Privoxy</SPAN
 962 >, which will in turn,
 963    relay the request to the remote web server after passing the following
 964    tests:
 965   </P
 966 ></LI
 967 ><LI
 968 ><P
 969 >   <SPAN
 970 CLASS="APPLICATION"
 971 >Privoxy</SPAN
 972 > traps any request for its own internal CGI
 973    pages (e.g <A
 974 HREF="http://p.p/"
 975 TARGET="_top"
 976 >http://p.p/</A
 977 >) and sends the CGI page back to the browser.
 978   </P
 979 ></LI
 980 ><LI
 981 ><P
 982 >   Next, <SPAN
 983 CLASS="APPLICATION"
 984 >Privoxy</SPAN
 985 > checks to see if the URL
 986    matches any <A
 987 HREF="actions-file.html#BLOCK"
 988 ><SPAN
 989 CLASS="QUOTE"
 990 >"+block"</SPAN
 991 ></A
 992 > patterns. If
 993    so, the URL is then blocked, and the remote web server will not be contacted.
 994    <A
 995 HREF="actions-file.html#HANDLE-AS-IMAGE"
 996 ><SPAN
 997 CLASS="QUOTE"
 998 >"+handle-as-image"</SPAN
 999 ></A
1000 >
1001    and
1002    <A
1003 HREF="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT"
1004 ><SPAN
1005 CLASS="QUOTE"
1006 >"+handle-as-empty-document"</SPAN
1007 ></A
1008 >
1009    are then checked, and if there is no match, an
1010    HTML <SPAN
1011 CLASS="QUOTE"
1012 >"BLOCKED"</SPAN
1013 > page is sent back to the browser. Otherwise, if
1014    it does match, an image is returned for the former, and an empty text
1015    document for the latter. The type of image would depend on the setting of
1016    <A
1017 HREF="actions-file.html#SET-IMAGE-BLOCKER"
1018 ><SPAN
1019 CLASS="QUOTE"
1020 >"+set-image-blocker"</SPAN
1021 ></A
1022 >
1023    (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
1024   </P
1025 ></LI
1026 ><LI
1027 ><P
1028 >   Untrusted URLs are blocked. If URLs are being added to the
1029    <TT
1030 CLASS="FILENAME"
1031 >trust</TT
1032 > file, then that is done.
1033   </P
1034 ></LI
1035 ><LI
1036 ><P
1037 >   If the URL pattern matches the <A
1038 HREF="actions-file.html#FAST-REDIRECTS"
1039 ><SPAN
1040 CLASS="QUOTE"
1041 >"+fast-redirects"</SPAN
1042 ></A
1043 > action,
1044    it is then processed. Unwanted parts of the requested URL are stripped.
1045   </P
1046 ></LI
1047 ><LI
1048 ><P
1049 >   Now the rest of the client browser's request headers are processed. If any
1050    of these match any of the relevant actions (e.g. <A
1051 HREF="actions-file.html#HIDE-USER-AGENT"
1052 ><SPAN
1053 CLASS="QUOTE"
1054 >"+hide-user-agent"</SPAN
1055 ></A
1056 >,
1057    etc.), headers are suppressed or forged as determined by these actions and
1058    their parameters.
1059   </P
1060 ></LI
1061 ><LI
1062 ><P
1063 >   Now the web server starts sending its response back (i.e. typically a web
1064    page).
1065   </P
1066 ></LI
1067 ><LI
1068 ><P
1069 >   First, the server headers are read and processed to determine, among other
1070    things, the MIME type (document type) and encoding. The headers are then
1071    filtered as determined by the
1072    <A
1073 HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
1074 ><SPAN
1075 CLASS="QUOTE"
1076 >"+crunch-incoming-cookies"</SPAN
1077 ></A
1078 >,
1079    <A
1080 HREF="actions-file.html#SESSION-COOKIES-ONLY"
1081 ><SPAN
1082 CLASS="QUOTE"
1083 >"+session-cookies-only"</SPAN
1084 ></A
1085 >,
1086    and <A
1087 HREF="actions-file.html#DOWNGRADE-HTTP-VERSION"
1088 ><SPAN
1089 CLASS="QUOTE"
1090 >"+downgrade-http-version"</SPAN
1091 ></A
1092 >
1093    actions.
1094   </P
1095 ></LI
1096 ><LI
1097 ><P
1098 >   If any <A
1099 HREF="actions-file.html#FILTER"
1100 ><SPAN
1101 CLASS="QUOTE"
1102 >"+filter"</SPAN
1103 ></A
1104 > action
1105    or <A
1106 HREF="actions-file.html#DEANIMATE-GIFS"
1107 ><SPAN
1108 CLASS="QUOTE"
1109 >"+deanimate-gifs"</SPAN
1110 ></A
1111 >
1112    action applies (and the document type fits the action), the rest of the page is
1113    read into memory (up to a configurable limit). Then the filter rules (from
1114    <TT
1115 CLASS="FILENAME"
1116 >default.filter</TT
1117 > and any other filter files) are
1118    processed against the buffered content. Filters are applied in the order
1119    they are specified in one of the filter files. Animated GIFs, if present,
1120    are reduced to either the first or last frame, depending on the action
1121    setting.The entire page, which is now filtered, is then sent by
1122    <SPAN
1123 CLASS="APPLICATION"
1124 >Privoxy</SPAN
1125 > back to your browser.
1126   </P
1127 ><P
1128 >   If neither a <A
1129 HREF="actions-file.html#FILTER"
1130 ><SPAN
1131 CLASS="QUOTE"
1132 >"+filter"</SPAN
1133 ></A
1134 > action
1135    or <A
1136 HREF="actions-file.html#DEANIMATE-GIFS"
1137 ><SPAN
1138 CLASS="QUOTE"
1139 >"+deanimate-gifs"</SPAN
1140 ></A
1141 >
1142    matches, then <SPAN
1143 CLASS="APPLICATION"
1144 >Privoxy</SPAN
1145 > passes the raw data through
1146    to the client browser as it becomes available.
1147   </P
1148 ></LI
1149 ><LI
1150 ><P
1151 >   As the browser receives the now (possibly filtered) page content, it
1152    reads and then requests any URLs that may be embedded within the page
1153    source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
1154    frames), sounds, etc. For each of these objects, the browser issues a
1155    separate request (this is easily viewable in <SPAN
1156 CLASS="APPLICATION"
1157 >Privoxy's</SPAN
1158 >
1159    logs). And each such request is in turn processed just as above. Note that a
1160    complex web page will have many, many such embedded URLs. If these
1161    secondary requests are to a different server, then quite possibly a very
1162    differing set of actions is triggered.
1163   </P
1164 ></LI
1165 ></UL
1166 ><P
1167 > NOTE: This is somewhat of a simplistic overview of what happens with each URL
1168  request. For the sake of brevity and simplicity, we have focused on
1169  <SPAN
1170 CLASS="APPLICATION"
1171 >Privoxy's</SPAN
1172 > core features only.</P
1173 ></DIV
1174 ><DIV
1175 CLASS="SECT2"
1176 ><H2
1177 CLASS="SECT2"
1178 ><A
1179 NAME="ACTIONSANAT"
1180 >14.4. Troubleshooting: Anatomy of an Action</A
1181 ></H2
1182 ><P
1183 > The way <SPAN
1184 CLASS="APPLICATION"
1185 >Privoxy</SPAN
1186 > applies
1187  <A
1188 HREF="actions-file.html#ACTIONS"
1189 >actions</A
1190 > and <A
1191 HREF="actions-file.html#FILTER"
1192 >filters</A
1193 >
1194  to any given URL can be complex, and not always so
1195  easy to understand what is happening. And sometimes we need to be able to
1196  <SPAN
1197 CLASS="emphasis"
1198 ><I
1199 CLASS="EMPHASIS"
1200 >see</I
1201 ></SPAN
1202 > just what <SPAN
1203 CLASS="APPLICATION"
1204 >Privoxy</SPAN
1205 > is
1206  doing. Especially, if something <SPAN
1207 CLASS="APPLICATION"
1208 >Privoxy</SPAN
1209 > is doing
1210  is causing us a problem inadvertently. It can be a little daunting to look at
1211  the actions and filters files themselves, since they tend to be filled with
1212  <A
1213 HREF="appendix.html#REGEX"
1214 >regular expressions</A
1215 > whose consequences are not
1216  always so obvious.</P
1217 ><P
1218 > One quick test to see if <SPAN
1219 CLASS="APPLICATION"
1220 >Privoxy</SPAN
1221 > is causing a problem
1222  or not, is to disable it temporarily. This should be the first troubleshooting
1223  step (be sure to flush caches afterward!). Looking at the
1224  logs is a good idea too. (Note that both the toggle feature and logging are
1225  enabled via <TT
1226 CLASS="FILENAME"
1227 >config</TT
1228 > file settings, and may need to be
1229  turned <SPAN
1230 CLASS="QUOTE"
1231 >"on"</SPAN
1232 >.)</P
1233 ><P
1234 > Another easy troubleshooting step to try is if you have done any
1235  customization of your installation, revert back to the installed
1236  defaults and see if that helps. There are times the developers get complaints
1237  about one thing or another, and the problem is more related to a customized
1238  configuration issue.</P
1239 ><P
1240 > <SPAN
1241 CLASS="APPLICATION"
1242 >Privoxy</SPAN
1243 > also provides the
1244  <A
1245 HREF="http://config.privoxy.org/show-url-info"
1246 TARGET="_top"
1247 >http://config.privoxy.org/show-url-info</A
1248 >
1249  page that can show us very specifically how <SPAN
1250 CLASS="APPLICATION"
1251 >actions</SPAN
1252 >
1253  are being applied to any given URL. This is a big help for troubleshooting.</P
1254 ><P
1255 > First, enter one URL (or partial URL) at the prompt, and then
1256  <SPAN
1257 CLASS="APPLICATION"
1258 >Privoxy</SPAN
1259 > will tell us
1260  how the current configuration will handle it. This will not
1261  help with filtering effects (i.e. the <A
1262 HREF="actions-file.html#FILTER"
1263 ><SPAN
1264 CLASS="QUOTE"
1265 >"+filter"</SPAN
1266 ></A
1267 > action) from
1268  one of the filter files since this is handled very
1269  differently and not so easy to trap! It also will not tell you about any other
1270  URLs that may be embedded within the URL you are testing. For instance, images
1271  such as ads are expressed as URLs within the raw page source of HTML pages. So
1272  you will only get info for the actual URL that is pasted into the prompt area
1273  -- not any sub-URLs. If you want to know about embedded URLs like ads, you
1274  will have to dig those out of the HTML source. Use your browser's <SPAN
1275 CLASS="QUOTE"
1276 >"View
1277  Page Source"</SPAN
1278 > option for this. Or right click on the ad, and grab the
1279  URL.</P
1280 ><P
1281 > Let's try an example, <A
1282 HREF="http://google.com"
1283 TARGET="_top"
1284 >google.com</A
1285 >,
1286  and look at it one section at a time in a sample configuration (your real
1287  configuration may vary):</P
1288 ><TABLE
1289 BORDER="0"
1290 BGCOLOR="#E0E0E0"
1291 WIDTH="100%"
1292 ><TR
1293 ><TD
1294 ><PRE
1295 CLASS="SCREEN"
1296 > Matches for http://www.google.com:
1297
1298  In file: default.action <SPAN
1299 CLASS="GUIBUTTON"
1300 >[ View ]</SPAN
1301 > <SPAN
1302 CLASS="GUIBUTTON"
1303 >[ Edit ]</SPAN
1304 >
1305
1306  {+change-x-forwarded-for{block}
1307  +deanimate-gifs {last}
1308  +fast-redirects {check-decoded-url}
1309  +filter {refresh-tags}
1310  +filter {img-reorder}
1311  +filter {banners-by-size}
1312  +filter {webbugs}
1313  +filter {jumping-windows}
1314  +filter {ie-exploits}
1315  +hide-from-header {block}
1316  +hide-referrer {forge}
1317  +session-cookies-only
1318  +set-image-blocker {pattern}
1319 /
1320
1321  { -session-cookies-only }
1322  .google.com
1323
1324  { -fast-redirects }
1325  .google.com
1326
1327 In file: user.action <SPAN
1328 CLASS="GUIBUTTON"
1329 >[ View ]</SPAN
1330 > <SPAN
1331 CLASS="GUIBUTTON"
1332 >[ Edit ]</SPAN
1333 >
1334 (no matches in this file)</PRE
1335 ></TD
1336 ></TR
1337 ></TABLE
1338 ><P
1339 > This is telling us how we have defined our
1340  <A
1341 HREF="actions-file.html#ACTIONS"
1342 ><SPAN
1343 CLASS="QUOTE"
1344 >"actions"</SPAN
1345 ></A
1346 >, and
1347  which ones match for our test case, <SPAN
1348 CLASS="QUOTE"
1349 >"google.com"</SPAN
1350 >.
1351  Displayed is all the actions that are available to us. Remember,
1352  the <TT
1353 CLASS="LITERAL"
1354 >+</TT
1355 > sign denotes <SPAN
1356 CLASS="QUOTE"
1357 >"on"</SPAN
1358 >. <TT
1359 CLASS="LITERAL"
1360 >-</TT
1361 >
1362  denotes <SPAN
1363 CLASS="QUOTE"
1364 >"off"</SPAN
1365 >. So some are <SPAN
1366 CLASS="QUOTE"
1367 >"on"</SPAN
1368 > here, but many
1369  are <SPAN
1370 CLASS="QUOTE"
1371 >"off"</SPAN
1372 >. Each example we try may provide a slightly different
1373  end result, depending on our configuration directives.</P
1374 ><P
1375 > The first listing
1376   is for our <TT
1377 CLASS="FILENAME"
1378 >default.action</TT
1379 > file. The large, multi-line
1380   listing, is how the actions are set to match for all URLs, i.e. our default
1381   settings. If you look at your <SPAN
1382 CLASS="QUOTE"
1383 >"actions"</SPAN
1384 > file, this would be the
1385   section just below the <SPAN
1386 CLASS="QUOTE"
1387 >"aliases"</SPAN
1388 > section near the top. This
1389   will apply to all URLs as signified by the single forward slash at the end
1390   of the listing -- <SPAN
1391 CLASS="QUOTE"
1392 >" / "</SPAN
1393 >.</P
1394 ><P
1395 > But we have defined additional actions that would be exceptions to these general
1396  rules, and then we list specific URLs (or patterns) that these exceptions
1397  would apply to. Last match wins. Just below this then are two explicit
1398  matches for <SPAN
1399 CLASS="QUOTE"
1400 >".google.com"</SPAN
1401 >. The first is negating our previous
1402  cookie setting, which was for <A
1403 HREF="actions-file.html#SESSION-COOKIES-ONLY"
1404 ><SPAN
1405 CLASS="QUOTE"
1406 >"+session-cookies-only"</SPAN
1407 ></A
1408 >
1409  (i.e. not persistent). So we will allow persistent cookies for google, at
1410  least that is how it is in this example. The second turns
1411  <SPAN
1412 CLASS="emphasis"
1413 ><I
1414 CLASS="EMPHASIS"
1415 >off</I
1416 ></SPAN
1417 > any <A
1418 HREF="actions-file.html#FAST-REDIRECTS"
1419 ><SPAN
1420 CLASS="QUOTE"
1421 >"+fast-redirects"</SPAN
1422 ></A
1423 >
1424  action, allowing this to take place unmolested. Note that there is a leading
1425  dot here -- <SPAN
1426 CLASS="QUOTE"
1427 >".google.com"</SPAN
1428 >. This will match any hosts and
1429  sub-domains, in the google.com domain also, such as
1430  <SPAN
1431 CLASS="QUOTE"
1432 >"www.google.com"</SPAN
1433 > or <SPAN
1434 CLASS="QUOTE"
1435 >"mail.google.com"</SPAN
1436 >. But it would not
1437  match <SPAN
1438 CLASS="QUOTE"
1439 >"www.google.de"</SPAN
1440 >! So, apparently, we have these two actions
1441  defined as exceptions to the general rules at the top somewhere in the lower
1442  part of our <TT
1443 CLASS="FILENAME"
1444 >default.action</TT
1445 > file, and
1446  <SPAN
1447 CLASS="QUOTE"
1448 >"google.com"</SPAN
1449 > is referenced somewhere in these latter sections.</P
1450 ><P
1451 > Then, for our <TT
1452 CLASS="FILENAME"
1453 >user.action</TT
1454 > file, we again have no hits.
1455  So there is nothing google-specific that we might have added to our own, local
1456  configuration. If there was, those actions would over-rule any actions from
1457  previously processed files, such as <TT
1458 CLASS="FILENAME"
1459 >default.action</TT
1460 >.
1461  <TT
1462 CLASS="FILENAME"
1463 >user.action</TT
1464 > typically has the last word. This is the
1465  best place to put hard and fast exceptions,</P
1466 ><P
1467 > And finally we pull it all together in the bottom section and summarize how
1468  <SPAN
1469 CLASS="APPLICATION"
1470 >Privoxy</SPAN
1471 > is applying all its <SPAN
1472 CLASS="QUOTE"
1473 >"actions"</SPAN
1474 >
1475  to <SPAN
1476 CLASS="QUOTE"
1477 >"google.com"</SPAN
1478 >:</P
1479 ><TABLE
1480 BORDER="0"
1481 BGCOLOR="#E0E0E0"
1482 WIDTH="100%"
1483 ><TR
1484 ><TD
1485 ><PRE
1486 CLASS="SCREEN"
1487 > Final results:
1488
1489  -add-header
1490  -block
1491  +change-x-forwarded-for{block}
1492  -client-header-filter{hide-tor-exit-notation}
1493  -content-type-overwrite
1494  -crunch-client-header
1495  -crunch-if-none-match
1496  -crunch-incoming-cookies
1497  -crunch-outgoing-cookies
1498  -crunch-server-header
1499  +deanimate-gifs {last}
1500  -downgrade-http-version
1501  -fast-redirects
1502  -filter {js-events}
1503  -filter {content-cookies}
1504  -filter {all-popups}
1505  -filter {banners-by-link}
1506  -filter {tiny-textforms}
1507  -filter {frameset-borders}
1508  -filter {demoronizer}
1509  -filter {shockwave-flash}
1510  -filter {quicktime-kioskmode}
1511  -filter {fun}
1512  -filter {crude-parental}
1513  -filter {site-specifics}
1514  -filter {js-annoyances}
1515  -filter {html-annoyances}
1516  +filter {refresh-tags}
1517  -filter {unsolicited-popups}
1518  +filter {img-reorder}
1519  +filter {banners-by-size}
1520  +filter {webbugs}
1521  +filter {jumping-windows}
1522  +filter {ie-exploits}
1523  -filter {google}
1524  -filter {yahoo}
1525  -filter {msn}
1526  -filter {blogspot}
1527  -filter {no-ping}
1528  -force-text-mode
1529  -handle-as-empty-document
1530  -handle-as-image
1531  -hide-accept-language
1532  -hide-content-disposition
1533  +hide-from-header {block}
1534  -hide-if-modified-since
1535  +hide-referrer {forge}
1536  -hide-user-agent
1537  -limit-connect
1538  -overwrite-last-modified
1539  -prevent-compression
1540  -redirect
1541  -server-header-filter{xml-to-html}
1542  -server-header-filter{html-to-xml}
1543  -session-cookies-only
1544  +set-image-blocker {pattern} </PRE
1545 ></TD
1546 ></TR
1547 ></TABLE
1548 ><P
1549 > Notice the only difference here to the previous listing, is to
1550  <SPAN
1551 CLASS="QUOTE"
1552 >"fast-redirects"</SPAN
1553 > and <SPAN
1554 CLASS="QUOTE"
1555 >"session-cookies-only"</SPAN
1556 >,
1557  which are activated specifically for this site in our configuration,
1558  and thus show in the <SPAN
1559 CLASS="QUOTE"
1560 >"Final Results"</SPAN
1561 >.</P
1562 ><P
1563 > Now another example, <SPAN
1564 CLASS="QUOTE"
1565 >"ad.doubleclick.net"</SPAN
1566 >:</P
1567 ><TABLE
1568 BORDER="0"
1569 BGCOLOR="#E0E0E0"
1570 WIDTH="100%"
1571 ><TR
1572 ><TD
1573 ><PRE
1574 CLASS="SCREEN"
1575 > { +block{Domains starts with "ad"} }
1576   ad*.
1577
1578  { +block{Domain contains "ad"} }
1579   .ad.
1580
1581  { +block{Doubleclick banner server} +handle-as-image }
1582   .[a-vx-z]*.doubleclick.net</PRE
1583 ></TD
1584 ></TR
1585 ></TABLE
1586 ><P
1587 > We'll just show the interesting part here - the explicit matches. It is
1588  matched three different times. Two <SPAN
1589 CLASS="QUOTE"
1590 >"+block{}"</SPAN
1591 > sections,
1592  and a <SPAN
1593 CLASS="QUOTE"
1594 >"+block{} +handle-as-image"</SPAN
1595 >,
1596  which is the expanded form of one of our aliases that had been defined as:
1597  <SPAN
1598 CLASS="QUOTE"
1599 >"+block-as-image"</SPAN
1600 >. (<A
1601 HREF="actions-file.html#ALIASES"
1602 ><SPAN
1603 CLASS="QUOTE"
1604 >"Aliases"</SPAN
1605 ></A
1606 > are defined in
1607  the first section of the actions file and typically used to combine more
1608  than one action.)</P
1609 ><P
1610 > Any one of these would have done the trick and blocked this as an unwanted
1611  image. This is unnecessarily redundant since the last case effectively
1612  would also cover the first. No point in taking chances with these guys
1613  though ;-) Note that if you want an ad or obnoxious
1614  URL to be invisible, it should be defined as <SPAN
1615 CLASS="QUOTE"
1616 >"ad.doubleclick.net"</SPAN
1617 >
1618  is done here -- as both a <A
1619 HREF="actions-file.html#BLOCK"
1620 ><SPAN
1621 CLASS="QUOTE"
1622 >"+block{}"</SPAN
1623 ></A
1624 >
1625  <SPAN
1626 CLASS="emphasis"
1627 ><I
1628 CLASS="EMPHASIS"
1629 >and</I
1630 ></SPAN
1631 > an
1632  <A
1633 HREF="actions-file.html#HANDLE-AS-IMAGE"
1634 ><SPAN
1635 CLASS="QUOTE"
1636 >"+handle-as-image"</SPAN
1637 ></A
1638 >.
1639  The custom alias <SPAN
1640 CLASS="QUOTE"
1641 >"<TT
1642 CLASS="LITERAL"
1643 >+block-as-image</TT
1644 >"</SPAN
1645 > just
1646  simplifies the process and make it more readable.</P
1647 ><P
1648 > One last example. Let's try <SPAN
1649 CLASS="QUOTE"
1650 >"http://www.example.net/adsl/HOWTO/"</SPAN
1651 >.
1652  This one is giving us problems. We are getting a blank page. Hmmm ...</P
1653 ><TABLE
1654 BORDER="0"
1655 BGCOLOR="#E0E0E0"
1656 WIDTH="100%"
1657 ><TR
1658 ><TD
1659 ><PRE
1660 CLASS="SCREEN"
1661 > Matches for http://www.example.net/adsl/HOWTO/:
1662
1663  In file: default.action <SPAN
1664 CLASS="GUIBUTTON"
1665 >[ View ]</SPAN
1666 > <SPAN
1667 CLASS="GUIBUTTON"
1668 >[ Edit ]</SPAN
1669 >
1670
1671  {-add-header
1672   -block
1673   +change-x-forwarded-for{block}
1674   -client-header-filter{hide-tor-exit-notation}
1675   -content-type-overwrite
1676   -crunch-client-header
1677   -crunch-if-none-match
1678   -crunch-incoming-cookies
1679   -crunch-outgoing-cookies
1680   -crunch-server-header
1681   +deanimate-gifs
1682   -downgrade-http-version
1683   +fast-redirects {check-decoded-url}
1684   -filter {js-events}
1685   -filter {content-cookies}
1686   -filter {all-popups}
1687   -filter {banners-by-link}
1688   -filter {tiny-textforms}
1689   -filter {frameset-borders}
1690   -filter {demoronizer}
1691   -filter {shockwave-flash}
1692   -filter {quicktime-kioskmode}
1693   -filter {fun}
1694   -filter {crude-parental}
1695   -filter {site-specifics}
1696   -filter {js-annoyances}
1697   -filter {html-annoyances}
1698   +filter {refresh-tags}
1699   -filter {unsolicited-popups}
1700   +filter {img-reorder}
1701   +filter {banners-by-size}
1702   +filter {webbugs}
1703   +filter {jumping-windows}
1704   +filter {ie-exploits}
1705   -filter {google}
1706   -filter {yahoo}
1707   -filter {msn}
1708   -filter {blogspot}
1709   -filter {no-ping}
1710   -force-text-mode
1711   -handle-as-empty-document
1712   -handle-as-image
1713   -hide-accept-language
1714   -hide-content-disposition
1715   +hide-from-header{block}
1716   +hide-referer{forge}
1717   -hide-user-agent
1718   -overwrite-last-modified
1719   +prevent-compression
1720   -redirect
1721   -server-header-filter{xml-to-html}
1722   -server-header-filter{html-to-xml}
1723   +session-cookies-only
1724   +set-image-blocker{blank} }
1725    /
1726
1727  { +block{Path contains "ads".} +handle-as-image }
1728   /ads</PRE
1729 ></TD
1730 ></TR
1731 ></TABLE
1732 ><P
1733 > Ooops, the <SPAN
1734 CLASS="QUOTE"
1735 >"/adsl/"</SPAN
1736 > is matching <SPAN
1737 CLASS="QUOTE"
1738 >"/ads"</SPAN
1739 > in our
1740  configuration! But we did not want this at all! Now we see why we get the
1741  blank page. It is actually triggering two different actions here, and
1742  the effects are aggregated so that the URL is blocked, and <SPAN
1743 CLASS="APPLICATION"
1744 >Privoxy</SPAN
1745 > is told
1746  to treat the block as if it were an image. But this is, of course, all wrong.
1747   We could now add a new action below this (or better in our own
1748   <TT
1749 CLASS="FILENAME"
1750 >user.action</TT
1751 > file) that explicitly
1752   <SPAN
1753 CLASS="emphasis"
1754 ><I
1755 CLASS="EMPHASIS"
1756 >un</I
1757 ></SPAN
1758 > blocks (
1759   <A
1760 HREF="actions-file.html#BLOCK"
1761 ><SPAN
1762 CLASS="QUOTE"
1763 >"{-block}"</SPAN
1764 ></A
1765 >) paths with
1766   <SPAN
1767 CLASS="QUOTE"
1768 >"adsl"</SPAN
1769 > in them (remember, last match in the configuration
1770   wins). There are various ways to handle such exceptions. Example:</P
1771 ><TABLE
1772 BORDER="0"
1773 BGCOLOR="#E0E0E0"
1774 WIDTH="100%"
1775 ><TR
1776 ><TD
1777 ><PRE
1778 CLASS="SCREEN"
1779 > { -block }
1780   /adsl</PRE
1781 ></TD
1782 ></TR
1783 ></TABLE
1784 ><P
1785 > Now the page displays ;-)
1786  Remember to flush your browser's caches when making these kinds of changes to
1787  your configuration to insure that you get a freshly delivered page! Or, try
1788  using <TT
1789 CLASS="LITERAL"
1790 >Shift+Reload</TT
1791 >.</P
1792 ><P
1793 > But now what about a situation where we get no explicit matches like
1794  we did with:</P
1795 ><TABLE
1796 BORDER="0"
1797 BGCOLOR="#E0E0E0"
1798 WIDTH="100%"
1799 ><TR
1800 ><TD
1801 ><PRE
1802 CLASS="SCREEN"
1803 > { +block{Path starts with "ads".} +handle-as-image }
1804  /ads</PRE
1805 ></TD
1806 ></TR
1807 ></TABLE
1808 ><P
1809 > That actually was very helpful and pointed us quickly to where the problem
1810  was. If you don't get this kind of match, then it means one of the default
1811  rules in the first section of <TT
1812 CLASS="FILENAME"
1813 >default.action</TT
1814 > is causing
1815  the problem. This would require some guesswork, and maybe a little trial and
1816  error to isolate the offending rule. One likely cause would be one of the
1817  <A
1818 HREF="actions-file.html#FILTER"
1819 ><SPAN
1820 CLASS="QUOTE"
1821 >"+filter"</SPAN
1822 ></A
1823 > actions.
1824  These tend to be harder to troubleshoot.
1825  Try adding the URL for the site to one of aliases that turn off
1826  <A
1827 HREF="actions-file.html#FILTER"
1828 ><SPAN
1829 CLASS="QUOTE"
1830 >"+filter"</SPAN
1831 ></A
1832 >:</P
1833 ><TABLE
1834 BORDER="0"
1835 BGCOLOR="#E0E0E0"
1836 WIDTH="100%"
1837 ><TR
1838 ><TD
1839 ><PRE
1840 CLASS="SCREEN"
1841 > { shop }
1842  .quietpc.com
1843  .worldpay.com   # for quietpc.com
1844  .jungle.com
1845  .scan.co.uk
1846  .forbes.com</PRE
1847 ></TD
1848 ></TR
1849 ></TABLE
1850 ><P
1851 > <SPAN
1852 CLASS="QUOTE"
1853 >"<TT
1854 CLASS="LITERAL"
1855 >{ shop }</TT
1856 >"</SPAN
1857 > is an <SPAN
1858 CLASS="QUOTE"
1859 >"alias"</SPAN
1860 > that expands to
1861  <SPAN
1862 CLASS="QUOTE"
1863 >"<TT
1864 CLASS="LITERAL"
1865 >{ -filter -session-cookies-only }</TT
1866 >"</SPAN
1867 >.
1868  Or you could do your own exception to negate filtering:</P
1869 ><TABLE
1870 BORDER="0"
1871 BGCOLOR="#E0E0E0"
1872 WIDTH="100%"
1873 ><TR
1874 ><TD
1875 ><PRE
1876 CLASS="SCREEN"
1877 > { -filter }
1878  # Disable ALL filter actions for sites in this section
1879  .forbes.com
1880  developer.ibm.com
1881  localhost</PRE
1882 ></TD
1883 ></TR
1884 ></TABLE
1885 ><P
1886 > This would turn off all filtering for these sites. This is best
1887  put in <TT
1888 CLASS="FILENAME"
1889 >user.action</TT
1890 >, for local site
1891  exceptions. Note that when a simple domain pattern is used by itself (without
1892  the subsequent path portion), all sub-pages within that domain are included
1893  automatically in the scope of the action.</P
1894 ><P
1895 > Images that are inexplicably being blocked, may well be hitting the
1896 <A
1897 HREF="actions-file.html#FILTER-BANNERS-BY-SIZE"
1898 ><SPAN
1899 CLASS="QUOTE"
1900 >"+filter{banners-by-size}"</SPAN
1901 ></A
1902 >
1903  rule, which assumes
1904  that images of certain sizes are ad banners (works well
1905  <SPAN
1906 CLASS="emphasis"
1907 ><I
1908 CLASS="EMPHASIS"
1909 >most of the time</I
1910 ></SPAN
1911 >  since these tend to be standardized).</P
1912 ><P
1913 > <SPAN
1914 CLASS="QUOTE"
1915 >"<TT
1916 CLASS="LITERAL"
1917 >{ fragile }</TT
1918 >"</SPAN
1919 > is an alias that disables most
1920  actions that are the most likely to cause trouble. This can be used as a
1921  last resort for problem sites.</P
1922 ><TABLE
1923 BORDER="0"
1924 BGCOLOR="#E0E0E0"
1925 WIDTH="100%"
1926 ><TR
1927 ><TD
1928 ><PRE
1929 CLASS="SCREEN"
1930 > { fragile }
1931  # Handle with care: easy to break
1932  mail.google.
1933  mybank.example.com</PRE
1934 ></TD
1935 ></TR
1936 ></TABLE
1937 ><P
1938 > <SPAN
1939 CLASS="emphasis"
1940 ><I
1941 CLASS="EMPHASIS"
1942 >Remember to flush caches!</I
1943 ></SPAN
1944 > Note that the
1945  <TT
1946 CLASS="LITERAL"
1947 >mail.google</TT
1948 > reference lacks the TLD portion (e.g.
1949  <SPAN
1950 CLASS="QUOTE"
1951 >".com"</SPAN
1952 >). This will effectively match any TLD with
1953  <TT
1954 CLASS="LITERAL"
1955 >google</TT
1956 > in it, such as <TT
1957 CLASS="LITERAL"
1958 >mail.google.de.</TT
1959 >,
1960  just as an example.</P
1961 ><P
1962 > If this still does not work, you will have to go through the remaining
1963  actions one by one to find which one(s) is causing the problem.</P
1964 ></DIV
1965 ></DIV
1966 ><DIV
1967 CLASS="NAVFOOTER"
1968 ><HR
1969 ALIGN="LEFT"
1970 WIDTH="100%"><TABLE
1971 SUMMARY="Footer navigation table"
1972 WIDTH="100%"
1973 BORDER="0"
1974 CELLPADDING="0"
1975 CELLSPACING="0"
1976 ><TR
1977 ><TD
1978 WIDTH="33%"
1979 ALIGN="left"
1980 VALIGN="top"
1981 ><A
1982 HREF="seealso.html"
1983 ACCESSKEY="P"
1984 >Prev</A
1985 ></TD
1986 ><TD
1987 WIDTH="34%"
1988 ALIGN="center"
1989 VALIGN="top"
1990 ><A
1991 HREF="index.html"
1992 ACCESSKEY="H"
1993 >Home</A
1994 ></TD
1995 ><TD
1996 WIDTH="33%"
1997 ALIGN="right"
1998 VALIGN="top"
1999 >&nbsp;</TD
2000 ></TR
2001 ><TR
2002 ><TD
2003 WIDTH="33%"
2004 ALIGN="left"
2005 VALIGN="top"
2006 >See Also</TD
2007 ><TD
2008 WIDTH="34%"
2009 ALIGN="center"
2010 VALIGN="top"
2011 >&nbsp;</TD
2012 ><TD
2013 WIDTH="33%"
2014 ALIGN="right"
2015 VALIGN="top"
2016 >&nbsp;</TD
2017 ></TR
2018 ></TABLE
2019 ></DIV
2020 ></BODY
2021 ></HTML
2022 >