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.7 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.7 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="AEN5252"
 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="AEN5266"
 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="AEN5274"
 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="AEN5279"
 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="AEN5284"
 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="AEN5289"
 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="AEN5295"
 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="AEN5299"
 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="AEN5302"
 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  -client-header-filter{hide-tor-exit-notation}
1450  -content-type-overwrite
1451  -crunch-client-header
1452  -crunch-if-none-match
1453  -crunch-incoming-cookies
1454  -crunch-outgoing-cookies
1455  -crunch-server-header
1456  +deanimate-gifs {last}
1457  -downgrade-http-version
1458  +fast-redirects {check-decoded-url}
1459  -filter {js-events}
1460  -filter {content-cookies}
1461  -filter {all-popups}
1462  -filter {banners-by-link}
1463  -filter {tiny-textforms}
1464  -filter {frameset-borders}
1465  -filter {demoronizer}
1466  -filter {shockwave-flash}
1467  -filter {quicktime-kioskmode}
1468  -filter {fun}
1469  -filter {crude-parental}
1470  -filter {site-specifics}
1471  -filter {js-annoyances}
1472  -filter {html-annoyances}
1473  +filter {refresh-tags}
1474  -filter {unsolicited-popups}
1475  +filter {img-reorder}
1476  +filter {banners-by-size}
1477  +filter {webbugs}
1478  +filter {jumping-windows}
1479  +filter {ie-exploits}
1480  -filter {google}
1481  -filter {yahoo}
1482  -filter {msn}
1483  -filter {blogspot}
1484  -filter {no-ping}
1485  -force-text-mode
1486  -handle-as-empty-document
1487  -handle-as-image
1488  -hide-accept-language
1489  -hide-content-disposition
1490  +hide-forwarded-for-headers
1491  +hide-from-header {block}
1492  -hide-if-modified-since
1493  +hide-referrer {forge}
1494  -hide-user-agent
1495  -inspect-jpegs
1496  -kill-popups
1497  -limit-connect
1498  -overwrite-last-modified
1499  +prevent-compression
1500  -redirect
1501  -send-vanilla-wafer
1502  -send-wafer
1503  -server-header-filter{xml-to-html}
1504  -server-header-filter{html-to-xml}
1505  +session-cookies-only
1506  +set-image-blocker {pattern}
1507  -treat-forbidden-connects-like-blocks }
1508 /
1509
1510  { -session-cookies-only }
1511  .google.com
1512
1513  { -fast-redirects }
1514  .google.com
1515
1516 In file: user.action <SPAN
1517 CLASS="GUIBUTTON"
1518 >[ View ]</SPAN
1519 > <SPAN
1520 CLASS="GUIBUTTON"
1521 >[ Edit ]</SPAN
1522 >
1523 (no matches in this file)  </PRE
1524 ></TD
1525 ></TR
1526 ></TABLE
1527 ></P
1528 ><P
1529 > This is telling us how we have defined our
1530  <A
1531 HREF="actions-file.html#ACTIONS"
1532 ><SPAN
1533 CLASS="QUOTE"
1534 >"actions"</SPAN
1535 ></A
1536 >, and
1537  which ones match for our test case, <SPAN
1538 CLASS="QUOTE"
1539 >"google.com"</SPAN
1540 >.
1541  Displayed is all the actions that are available to us. Remember,
1542  the <TT
1543 CLASS="LITERAL"
1544 >+</TT
1545 > sign denotes <SPAN
1546 CLASS="QUOTE"
1547 >"on"</SPAN
1548 >. <TT
1549 CLASS="LITERAL"
1550 >-</TT
1551 >
1552  denotes <SPAN
1553 CLASS="QUOTE"
1554 >"off"</SPAN
1555 >. So some are <SPAN
1556 CLASS="QUOTE"
1557 >"on"</SPAN
1558 > here, but many
1559  are <SPAN
1560 CLASS="QUOTE"
1561 >"off"</SPAN
1562 >. Each example we try may provide a slightly different
1563  end result, depending on our configuration directives.</P
1564 ><P
1565 > The first listing
1566   is for our <TT
1567 CLASS="FILENAME"
1568 >default.action</TT
1569 > file. The large, multi-line
1570   listing, is how the actions are set to match for all URLs, i.e. our default
1571   settings. If you look at your <SPAN
1572 CLASS="QUOTE"
1573 >"actions"</SPAN
1574 > file, this would be the
1575   section just below the <SPAN
1576 CLASS="QUOTE"
1577 >"aliases"</SPAN
1578 > section near the top. This
1579   will apply to all URLs as signified by the single forward slash at the end
1580   of the listing -- <SPAN
1581 CLASS="QUOTE"
1582 >" / "</SPAN
1583 >.</P
1584 ><P
1585 > But we have defined additional actions that would be exceptions to these general
1586  rules, and then we list specific URLs (or patterns) that these exceptions
1587  would apply to. Last match wins. Just below this then are two explicit
1588  matches for <SPAN
1589 CLASS="QUOTE"
1590 >".google.com"</SPAN
1591 >. The first is negating our previous
1592  cookie setting, which was for <A
1593 HREF="actions-file.html#SESSION-COOKIES-ONLY"
1594 ><SPAN
1595 CLASS="QUOTE"
1596 >"+session-cookies-only"</SPAN
1597 ></A
1598 >
1599  (i.e. not persistent). So we will allow persistent cookies for google, at
1600  least that is how it is in this example. The second turns
1601  <SPAN
1602 CLASS="emphasis"
1603 ><I
1604 CLASS="EMPHASIS"
1605 >off</I
1606 ></SPAN
1607 > any <A
1608 HREF="actions-file.html#FAST-REDIRECTS"
1609 ><SPAN
1610 CLASS="QUOTE"
1611 >"+fast-redirects"</SPAN
1612 ></A
1613 >
1614  action, allowing this to take place unmolested. Note that there is a leading
1615  dot here -- <SPAN
1616 CLASS="QUOTE"
1617 >".google.com"</SPAN
1618 >. This will match any hosts and
1619  sub-domains, in the google.com domain also, such as
1620  <SPAN
1621 CLASS="QUOTE"
1622 >"www.google.com"</SPAN
1623 > or <SPAN
1624 CLASS="QUOTE"
1625 >"mail.google.com"</SPAN
1626 >. But it would not
1627  match <SPAN
1628 CLASS="QUOTE"
1629 >"www.google.de"</SPAN
1630 >! So, apparently, we have these two actions
1631  defined as exceptions to the general rules at the top somewhere in the lower
1632  part of our <TT
1633 CLASS="FILENAME"
1634 >default.action</TT
1635 > file, and
1636  <SPAN
1637 CLASS="QUOTE"
1638 >"google.com"</SPAN
1639 > is referenced somewhere in these latter sections.</P
1640 ><P
1641 > Then, for our <TT
1642 CLASS="FILENAME"
1643 >user.action</TT
1644 > file, we again have no hits.
1645  So there is nothing google-specific that we might have added to our own, local
1646  configuration. If there was, those actions would over-rule any actions from
1647  previously processed files, such as <TT
1648 CLASS="FILENAME"
1649 >default.action</TT
1650 >.
1651  <TT
1652 CLASS="FILENAME"
1653 >user.action</TT
1654 > typically has the last word. This is the
1655  best place to put hard and fast exceptions,</P
1656 ><P
1657 > And finally we pull it all together in the bottom section and summarize how
1658  <SPAN
1659 CLASS="APPLICATION"
1660 >Privoxy</SPAN
1661 > is applying all its <SPAN
1662 CLASS="QUOTE"
1663 >"actions"</SPAN
1664 >
1665  to <SPAN
1666 CLASS="QUOTE"
1667 >"google.com"</SPAN
1668 >:&#13;</P
1669 ><P
1670 > <TABLE
1671 BORDER="0"
1672 BGCOLOR="#E0E0E0"
1673 WIDTH="100%"
1674 ><TR
1675 ><TD
1676 ><PRE
1677 CLASS="SCREEN"
1678 >&#13; Final results:
1679
1680  -add-header
1681  -block
1682  -client-header-filter{hide-tor-exit-notation}
1683  -content-type-overwrite
1684  -crunch-client-header
1685  -crunch-if-none-match
1686  -crunch-incoming-cookies
1687  -crunch-outgoing-cookies
1688  -crunch-server-header
1689  +deanimate-gifs {last}
1690  -downgrade-http-version
1691  +fast-redirects {check-decoded-url}
1692  -filter {js-events}
1693  -filter {content-cookies}
1694  -filter {all-popups}
1695  -filter {banners-by-link}
1696  -filter {tiny-textforms}
1697  -filter {frameset-borders}
1698  -filter {demoronizer}
1699  -filter {shockwave-flash}
1700  -filter {quicktime-kioskmode}
1701  -filter {fun}
1702  -filter {crude-parental}
1703  -filter {site-specifics}
1704  -filter {js-annoyances}
1705  -filter {html-annoyances}
1706  +filter {refresh-tags}
1707  -filter {unsolicited-popups}
1708  +filter {img-reorder}
1709  +filter {banners-by-size}
1710  +filter {webbugs}
1711  +filter {jumping-windows}
1712  +filter {ie-exploits}
1713  -filter {google}
1714  -filter {yahoo}
1715  -filter {msn}
1716  -filter {blogspot}
1717  -filter {no-ping}
1718  -force-text-mode
1719  -handle-as-empty-document
1720  -handle-as-image
1721  -hide-accept-language
1722  -hide-content-disposition
1723  +hide-forwarded-for-headers
1724  +hide-from-header {block}
1725  -hide-if-modified-since
1726  +hide-referrer {forge}
1727  -hide-user-agent
1728  -inspect-jpegs
1729  -kill-popups
1730  -limit-connect
1731  -overwrite-last-modified
1732  +prevent-compression
1733  -redirect
1734  -send-vanilla-wafer
1735  -send-wafer
1736  -server-header-filter{xml-to-html}
1737  -server-header-filter{html-to-xml}
1738  -session-cookies-only
1739  +set-image-blocker {pattern}
1740  -treat-forbidden-connects-like-blocks </PRE
1741 ></TD
1742 ></TR
1743 ></TABLE
1744 ></P
1745 ><P
1746 > Notice the only difference here to the previous listing, is to
1747  <SPAN
1748 CLASS="QUOTE"
1749 >"fast-redirects"</SPAN
1750 > and <SPAN
1751 CLASS="QUOTE"
1752 >"session-cookies-only"</SPAN
1753 >,
1754  which are activated specifically for this site in our configuration,
1755  and thus show in the <SPAN
1756 CLASS="QUOTE"
1757 >"Final Results"</SPAN
1758 >.</P
1759 ><P
1760 > Now another example, <SPAN
1761 CLASS="QUOTE"
1762 >"ad.doubleclick.net"</SPAN
1763 >:</P
1764 ><P
1765 > <TABLE
1766 BORDER="0"
1767 BGCOLOR="#E0E0E0"
1768 WIDTH="100%"
1769 ><TR
1770 ><TD
1771 ><PRE
1772 CLASS="SCREEN"
1773 >&#13; { +block }
1774   ad*.
1775
1776  { +block }
1777   .ad.
1778
1779  { +block +handle-as-image }
1780   .[a-vx-z]*.doubleclick.net</PRE
1781 ></TD
1782 ></TR
1783 ></TABLE
1784 ></P
1785 ><P
1786 > We'll just show the interesting part here - the explicit matches. It is
1787  matched three different times. Two <SPAN
1788 CLASS="QUOTE"
1789 >"+block"</SPAN
1790 > sections,
1791  and a <SPAN
1792 CLASS="QUOTE"
1793 >"+block +handle-as-image"</SPAN
1794 >,
1795  which is the expanded form of one of our aliases that had been defined as:
1796  <SPAN
1797 CLASS="QUOTE"
1798 >"+block-as-image"</SPAN
1799 >. (<A
1800 HREF="actions-file.html#ALIASES"
1801 ><SPAN
1802 CLASS="QUOTE"
1803 >"Aliases"</SPAN
1804 ></A
1805 > are defined in
1806  the first section of the actions file and typically used to combine more
1807  than one action.)</P
1808 ><P
1809 > Any one of these would have done the trick and blocked this as an unwanted
1810  image. This is unnecessarily redundant since the last case effectively
1811  would also cover the first. No point in taking chances with these guys
1812  though ;-) Note that if you want an ad or obnoxious
1813  URL to be invisible, it should be defined as <SPAN
1814 CLASS="QUOTE"
1815 >"ad.doubleclick.net"</SPAN
1816 >
1817  is done here -- as both a <A
1818 HREF="actions-file.html#BLOCK"
1819 ><SPAN
1820 CLASS="QUOTE"
1821 >"+block"</SPAN
1822 ></A
1823 >
1824  <SPAN
1825 CLASS="emphasis"
1826 ><I
1827 CLASS="EMPHASIS"
1828 >and</I
1829 ></SPAN
1830 > an
1831  <A
1832 HREF="actions-file.html#HANDLE-AS-IMAGE"
1833 ><SPAN
1834 CLASS="QUOTE"
1835 >"+handle-as-image"</SPAN
1836 ></A
1837 >.
1838  The custom alias <SPAN
1839 CLASS="QUOTE"
1840 >"<TT
1841 CLASS="LITERAL"
1842 >+block-as-image</TT
1843 >"</SPAN
1844 > just
1845  simplifies the process and make it more readable.</P
1846 ><P
1847 > One last example. Let's try <SPAN
1848 CLASS="QUOTE"
1849 >"http://www.example.net/adsl/HOWTO/"</SPAN
1850 >.
1851  This one is giving us problems. We are getting a blank page. Hmmm ...</P
1852 ><P
1853 > <TABLE
1854 BORDER="0"
1855 BGCOLOR="#E0E0E0"
1856 WIDTH="100%"
1857 ><TR
1858 ><TD
1859 ><PRE
1860 CLASS="SCREEN"
1861 >&#13; Matches for http://www.example.net/adsl/HOWTO/:
1862
1863  In file: default.action <SPAN
1864 CLASS="GUIBUTTON"
1865 >[ View ]</SPAN
1866 > <SPAN
1867 CLASS="GUIBUTTON"
1868 >[ Edit ]</SPAN
1869 >
1870
1871  {-add-header
1872   -block
1873   -client-header-filter{hide-tor-exit-notation}
1874   -content-type-overwrite
1875   -crunch-client-header
1876   -crunch-if-none-match
1877   -crunch-incoming-cookies
1878   -crunch-outgoing-cookies
1879   -crunch-server-header
1880   +deanimate-gifs
1881   -downgrade-http-version
1882   +fast-redirects {check-decoded-url}
1883   -filter {js-events}
1884   -filter {content-cookies}
1885   -filter {all-popups}
1886   -filter {banners-by-link}
1887   -filter {tiny-textforms}
1888   -filter {frameset-borders}
1889   -filter {demoronizer}
1890   -filter {shockwave-flash}
1891   -filter {quicktime-kioskmode}
1892   -filter {fun}
1893   -filter {crude-parental}
1894   -filter {site-specifics}
1895   -filter {js-annoyances}
1896   -filter {html-annoyances}
1897   +filter {refresh-tags}
1898   -filter {unsolicited-popups}
1899   +filter {img-reorder}
1900   +filter {banners-by-size}
1901   +filter {webbugs}
1902   +filter {jumping-windows}
1903   +filter {ie-exploits}
1904   -filter {google}
1905   -filter {yahoo}
1906   -filter {msn}
1907   -filter {blogspot}
1908   -filter {no-ping}
1909   -force-text-mode
1910   -handle-as-empty-document
1911   -handle-as-image
1912   -hide-accept-language
1913   -hide-content-disposition
1914   +hide-forwarded-for-headers
1915   +hide-from-header{block}
1916   +hide-referer{forge}
1917   -hide-user-agent
1918   -inspect-jpegs
1919   -kill-popups
1920   -overwrite-last-modified
1921   +prevent-compression
1922   -redirect
1923   -send-vanilla-wafer
1924   -send-wafer
1925   -server-header-filter{xml-to-html}
1926   -server-header-filter{html-to-xml}
1927   +session-cookies-only
1928   +set-image-blocker{blank}
1929   -treat-forbidden-connects-like-blocks }
1930    /
1931
1932  { +block +handle-as-image }
1933   /ads</PRE
1934 ></TD
1935 ></TR
1936 ></TABLE
1937 ></P
1938 ><P
1939 > Ooops, the <SPAN
1940 CLASS="QUOTE"
1941 >"/adsl/"</SPAN
1942 > is matching <SPAN
1943 CLASS="QUOTE"
1944 >"/ads"</SPAN
1945 > in our
1946  configuration! But we did not want this at all! Now we see why we get the
1947  blank page. It is actually triggering two different actions here, and
1948  the effects are aggregated so that the URL is blocked, and <SPAN
1949 CLASS="APPLICATION"
1950 >Privoxy</SPAN
1951 > is told
1952  to treat the block as if it were an image. But this is, of course, all wrong.
1953   We could now add a new action below this (or better in our own
1954   <TT
1955 CLASS="FILENAME"
1956 >user.action</TT
1957 > file) that explicitly
1958   <SPAN
1959 CLASS="emphasis"
1960 ><I
1961 CLASS="EMPHASIS"
1962 >un</I
1963 ></SPAN
1964 > blocks (
1965   <A
1966 HREF="actions-file.html#BLOCK"
1967 ><SPAN
1968 CLASS="QUOTE"
1969 >"{-block}"</SPAN
1970 ></A
1971 >) paths with
1972   <SPAN
1973 CLASS="QUOTE"
1974 >"adsl"</SPAN
1975 > in them (remember, last match in the configuration
1976   wins). There are various ways to handle such exceptions. Example:</P
1977 ><P
1978 > <TABLE
1979 BORDER="0"
1980 BGCOLOR="#E0E0E0"
1981 WIDTH="100%"
1982 ><TR
1983 ><TD
1984 ><PRE
1985 CLASS="SCREEN"
1986 >&#13; { -block }
1987   /adsl</PRE
1988 ></TD
1989 ></TR
1990 ></TABLE
1991 ></P
1992 ><P
1993 > Now the page displays ;-)
1994  Remember to flush your browser's caches when making these kinds of changes to
1995  your configuration to insure that you get a freshly delivered page! Or, try
1996  using <TT
1997 CLASS="LITERAL"
1998 >Shift+Reload</TT
1999 >.</P
2000 ><P
2001 > But now what about a situation where we get no explicit matches like
2002  we did with:</P
2003 ><P
2004 > <TABLE
2005 BORDER="0"
2006 BGCOLOR="#E0E0E0"
2007 WIDTH="100%"
2008 ><TR
2009 ><TD
2010 ><PRE
2011 CLASS="SCREEN"
2012 >&#13; { +block +handle-as-image }
2013  /ads</PRE
2014 ></TD
2015 ></TR
2016 ></TABLE
2017 ></P
2018 ><P
2019 > That actually was very helpful and pointed us quickly to where the problem
2020  was. If you don't get this kind of match, then it means one of the default
2021  rules in the first section of <TT
2022 CLASS="FILENAME"
2023 >default.action</TT
2024 > is causing
2025  the problem. This would require some guesswork, and maybe a little trial and
2026  error to isolate the offending rule. One likely cause would be one of the
2027  <A
2028 HREF="actions-file.html#FILTER"
2029 ><SPAN
2030 CLASS="QUOTE"
2031 >"+filter"</SPAN
2032 ></A
2033 > actions.
2034  These tend to be harder to troubleshoot.
2035  Try adding the URL for the site to one of aliases that turn off
2036  <A
2037 HREF="actions-file.html#FILTER"
2038 ><SPAN
2039 CLASS="QUOTE"
2040 >"+filter"</SPAN
2041 ></A
2042 >:</P
2043 ><P
2044 > <TABLE
2045 BORDER="0"
2046 BGCOLOR="#E0E0E0"
2047 WIDTH="100%"
2048 ><TR
2049 ><TD
2050 ><PRE
2051 CLASS="SCREEN"
2052 >&#13; { shop }
2053  .quietpc.com
2054  .worldpay.com   # for quietpc.com
2055  .jungle.com
2056  .scan.co.uk
2057  .forbes.com</PRE
2058 ></TD
2059 ></TR
2060 ></TABLE
2061 ></P
2062 ><P
2063 > <SPAN
2064 CLASS="QUOTE"
2065 >"<TT
2066 CLASS="LITERAL"
2067 >{ shop }</TT
2068 >"</SPAN
2069 > is an <SPAN
2070 CLASS="QUOTE"
2071 >"alias"</SPAN
2072 > that expands to
2073  <SPAN
2074 CLASS="QUOTE"
2075 >"<TT
2076 CLASS="LITERAL"
2077 >{ -filter -session-cookies-only }</TT
2078 >"</SPAN
2079 >.
2080  Or you could do your own exception to negate filtering:&#13;</P
2081 ><P
2082 > <TABLE
2083 BORDER="0"
2084 BGCOLOR="#E0E0E0"
2085 WIDTH="100%"
2086 ><TR
2087 ><TD
2088 ><PRE
2089 CLASS="SCREEN"
2090 >&#13; { -filter }
2091  # Disable ALL filter actions for sites in this section
2092  .forbes.com
2093  developer.ibm.com
2094  localhost</PRE
2095 ></TD
2096 ></TR
2097 ></TABLE
2098 ></P
2099 ><P
2100 > This would turn off all filtering for these sites. This is best
2101  put in <TT
2102 CLASS="FILENAME"
2103 >user.action</TT
2104 >, for local site
2105  exceptions. Note that when a simple domain pattern is used by itself (without
2106  the subsequent path portion), all sub-pages within that domain are included
2107  automatically in the scope of the action.</P
2108 ><P
2109 > Images that are inexplicably being blocked, may well be hitting the
2110 <A
2111 HREF="actions-file.html#FILTER-BANNERS-BY-SIZE"
2112 ><SPAN
2113 CLASS="QUOTE"
2114 >"+filter{banners-by-size}"</SPAN
2115 ></A
2116 >
2117  rule, which assumes
2118  that images of certain sizes are ad banners (works well
2119  <SPAN
2120 CLASS="emphasis"
2121 ><I
2122 CLASS="EMPHASIS"
2123 >most of the time</I
2124 ></SPAN
2125 >  since these tend to be standardized).</P
2126 ><P
2127 > <SPAN
2128 CLASS="QUOTE"
2129 >"<TT
2130 CLASS="LITERAL"
2131 >{ fragile }</TT
2132 >"</SPAN
2133 > is an alias that disables most
2134  actions that are the most likely to cause trouble. This can be used as a
2135  last resort for problem sites. </P
2136 ><P
2137 > <TABLE
2138 BORDER="0"
2139 BGCOLOR="#E0E0E0"
2140 WIDTH="100%"
2141 ><TR
2142 ><TD
2143 ><PRE
2144 CLASS="SCREEN"
2145 >&#13; { fragile }
2146  # Handle with care: easy to break
2147  mail.google.
2148  mybank.example.com</PRE
2149 ></TD
2150 ></TR
2151 ></TABLE
2152 ></P
2153 ><P
2154 > <SPAN
2155 CLASS="emphasis"
2156 ><I
2157 CLASS="EMPHASIS"
2158 >Remember to flush caches!</I
2159 ></SPAN
2160 > Note that the
2161  <TT
2162 CLASS="LITERAL"
2163 >mail.google</TT
2164 > reference lacks the TLD portion (e.g.
2165  <SPAN
2166 CLASS="QUOTE"
2167 >".com"</SPAN
2168 >. This will effectively match any TLD with
2169  <TT
2170 CLASS="LITERAL"
2171 >google</TT
2172 > in it, such as <TT
2173 CLASS="LITERAL"
2174 >mail.google.de</TT
2175 >,
2176  just as an example.</P
2177 ><P
2178 >
2179  If this still does not work, you will have to go through the remaining
2180  actions one by one to find which one(s) is causing the problem.</P
2181 ></DIV
2182 ></DIV
2183 ><DIV
2184 CLASS="NAVFOOTER"
2185 ><HR
2186 ALIGN="LEFT"
2187 WIDTH="100%"><TABLE
2188 SUMMARY="Footer navigation table"
2189 WIDTH="100%"
2190 BORDER="0"
2191 CELLPADDING="0"
2192 CELLSPACING="0"
2193 ><TR
2194 ><TD
2195 WIDTH="33%"
2196 ALIGN="left"
2197 VALIGN="top"
2198 ><A
2199 HREF="seealso.html"
2200 ACCESSKEY="P"
2201 >Prev</A
2202 ></TD
2203 ><TD
2204 WIDTH="34%"
2205 ALIGN="center"
2206 VALIGN="top"
2207 ><A
2208 HREF="index.html"
2209 ACCESSKEY="H"
2210 >Home</A
2211 ></TD
2212 ><TD
2213 WIDTH="33%"
2214 ALIGN="right"
2215 VALIGN="top"
2216 >&nbsp;</TD
2217 ></TR
2218 ><TR
2219 ><TD
2220 WIDTH="33%"
2221 ALIGN="left"
2222 VALIGN="top"
2223 >See Also</TD
2224 ><TD
2225 WIDTH="34%"
2226 ALIGN="center"
2227 VALIGN="top"
2228 >&nbsp;</TD
2229 ><TD
2230 WIDTH="33%"
2231 ALIGN="right"
2232 VALIGN="top"
2233 >&nbsp;</TD
2234 ></TR
2235 ></TABLE
2236 ></DIV
2237 ></BODY
2238 ></HTML
2239 >