doc/webserver/user-manual/appendix.html

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