doc/webserver/user-manual/appendix.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
   2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4   <head>
   5     <title>
   6       Appendix
   7     </title>
   8     <meta name="GENERATOR" content=
   9     "Modular DocBook HTML Stylesheet Version 1.79">
  10     <link rel="HOME" title="Privoxy 3.0.26 User Manual" href="index.html">
  11     <link rel="PREVIOUS" title="See Also" href="seealso.html">
  12     <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
  13     <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  14     <link rel="STYLESHEET" type="text/css" href="p_doc.css">
  15   </head>
  16   <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
  17   "#840084" alink="#0000FF">
  18     <div class="NAVHEADER">
  19       <table summary="Header navigation table" width="100%" border="0"
  20       cellpadding="0" cellspacing="0">
  21         <tr>
  22           <th colspan="3" align="center">
  23             Privoxy 3.0.26 User Manual
  24           </th>
  25         </tr>
  26         <tr>
  27           <td width="10%" align="left" valign="bottom">
  28             <a href="seealso.html" accesskey="P">Prev</a>
  29           </td>
  30           <td width="80%" align="center" valign="bottom">
  31           </td>
  32           <td width="10%" align="right" valign="bottom">
  33             &nbsp;
  34           </td>
  35         </tr>
  36       </table>
  37       <hr align="LEFT" width="100%">
  38     </div>
  39     <div class="SECT1">
  40       <h1 class="SECT1">
  41         <a name="APPENDIX">14. Appendix</a>
  42       </h1>
  43       <div class="SECT2">
  44         <h2 class="SECT2">
  45           <a name="REGEX">14.1. Regular Expressions</a>
  46         </h2>
  47         <p>
  48           <span class="APPLICATION">Privoxy</span> uses Perl-style <span
  49           class="QUOTE">"regular expressions"</span> in its <a href=
  50           "actions-file.html">actions files</a> and <a href=
  51           "filter-file.html">filter file</a>, through the <a href=
  52           "http://www.pcre.org/" target="_top">PCRE</a> and <span class=
  53           "APPLICATION">PCRS</span> libraries.
  54         </p>
  55         <p>
  56           If you are reading this, you probably don't understand what <span
  57           class="QUOTE">"regular expressions"</span> are, or what they can
  58           do. So this will be a very brief introduction only. A full
  59           explanation would require a <a href=
  60           "http://www.oreilly.com/catalog/regex/" target="_top">book</a> ;-)
  61         </p>
  62         <p>
  63           Regular expressions provide a language to describe patterns that
  64           can be run against strings of characters (letter, numbers, etc), to
  65           see if they match the string or not. The patterns are themselves
  66           (sometimes complex) strings of literal characters, combined with
  67           wild-cards, and other special characters, called meta-characters.
  68           The <span class="QUOTE">"meta-characters"</span> have special
  69           meanings and are used to build complex patterns to be matched
  70           against. Perl Compatible Regular Expressions are an especially
  71           convenient <span class="QUOTE">"dialect"</span> of the regular
  72           expression language.
  73         </p>
  74         <p>
  75           To make a simple analogy, we do something similar when we use
  76           wild-card characters when listing files with the <b class=
  77           "COMMAND">dir</b> command in DOS. <tt class="LITERAL">*.*</tt>
  78           matches all filenames. The <span class="QUOTE">"special"</span>
  79           character here is the asterisk which matches any and all
  80           characters. We can be more specific and use <tt class=
  81           "LITERAL">?</tt> to match just individual characters. So <span
  82           class="QUOTE">"dir file?.text"</span> would match <span class=
  83           "QUOTE">"file1.txt"</span>, <span class="QUOTE">"file2.txt"</span>,
  84           etc. We are pattern matching, using a similar technique to <span
  85           class="QUOTE">"regular expressions"</span>!
  86         </p>
  87         <p>
  88           Regular expressions do essentially the same thing, but are much,
  89           much more powerful. There are many more <span class=
  90           "QUOTE">"special characters"</span> and ways of building complex
  91           patterns however. Let's look at a few of the common ones, and then
  92           some examples:
  93         </p>
  94         <table border="0">
  95           <tbody>
  96             <tr>
  97               <td>
  98                 <span class="emphasis"><i class="EMPHASIS">.</i></span> -
  99                 Matches any single character, e.g. <span class=
 100                 "QUOTE">"a"</span>, <span class="QUOTE">"A"</span>, <span
 101                 class="QUOTE">"4"</span>, <span class="QUOTE">":"</span>, or
 102                 <span class="QUOTE">"@"</span>.
 103               </td>
 104             </tr>
 105           </tbody>
 106         </table>
 107
 108         <table border="0">
 109           <tbody>
 110             <tr>
 111               <td>
 112                 <span class="emphasis"><i class="EMPHASIS">?</i></span> - The
 113                 preceding character or expression is matched ZERO or ONE
 114                 times. Either/or.
 115               </td>
 116             </tr>
 117           </tbody>
 118         </table>
 119
 120         <table border="0">
 121           <tbody>
 122             <tr>
 123               <td>
 124                 <span class="emphasis"><i class="EMPHASIS">+</i></span> - The
 125                 preceding character or expression is matched ONE or MORE
 126                 times.
 127               </td>
 128             </tr>
 129           </tbody>
 130         </table>
 131
 132         <table border="0">
 133           <tbody>
 134             <tr>
 135               <td>
 136                 <span class="emphasis"><i class="EMPHASIS">*</i></span> - The
 137                 preceding character or expression is matched ZERO or MORE
 138                 times.
 139               </td>
 140             </tr>
 141           </tbody>
 142         </table>
 143
 144         <table border="0">
 145           <tbody>
 146             <tr>
 147               <td>
 148                 <span class="emphasis"><i class="EMPHASIS">\</i></span> - The
 149                 <span class="QUOTE">"escape"</span> character denotes that
 150                 the following character should be taken literally. This is
 151                 used where one of the special characters (e.g. <span class=
 152                 "QUOTE">"."</span>) needs to be taken literally and not as a
 153                 special meta-character. Example: <span class=
 154                 "QUOTE">"example\.com"</span>, makes sure the period is
 155                 recognized only as a period (and not expanded to its
 156                 meta-character meaning of any single character).
 157               </td>
 158             </tr>
 159           </tbody>
 160         </table>
 161
 162         <table border="0">
 163           <tbody>
 164             <tr>
 165               <td>
 166                 <span class="emphasis"><i class="EMPHASIS">[ ]</i></span> -
 167                 Characters enclosed in brackets will be matched if any of the
 168                 enclosed characters are encountered. For instance, <span
 169                 class="QUOTE">"[0-9]"</span> matches any numeric digit (zero
 170                 through nine). As an example, we can combine this with <span
 171                 class="QUOTE">"+"</span> to match any digit one of more
 172                 times: <span class="QUOTE">"[0-9]+"</span>.
 173               </td>
 174             </tr>
 175           </tbody>
 176         </table>
 177
 178         <table border="0">
 179           <tbody>
 180             <tr>
 181               <td>
 182                 <span class="emphasis"><i class="EMPHASIS">( )</i></span> -
 183                 parentheses are used to group a sub-expression, or multiple
 184                 sub-expressions.
 185               </td>
 186             </tr>
 187           </tbody>
 188         </table>
 189
 190         <table border="0">
 191           <tbody>
 192             <tr>
 193               <td>
 194                 <span class="emphasis"><i class="EMPHASIS">|</i></span> - The
 195                 <span class="QUOTE">"bar"</span> character works like an
 196                 <span class="QUOTE">"or"</span> conditional statement. A
 197                 match is successful if the sub-expression on either side of
 198                 <span class="QUOTE">"|"</span> matches. As an example: <span
 199                 class="QUOTE">"/(this|that) example/"</span> uses grouping
 200                 and the bar character and would match either <span class=
 201                 "QUOTE">"this example"</span> or <span class="QUOTE">"that
 202                 example"</span>, and nothing else.
 203               </td>
 204             </tr>
 205           </tbody>
 206         </table>
 207
 208         <p>
 209           These are just some of the ones you are likely to use when matching
 210           URLs with <span class="APPLICATION">Privoxy</span>, and is a long
 211           way from a definitive list. This is enough to get us started with a
 212           few simple examples which may be more illuminating:
 213         </p>
 214         <p>
 215           <span class="emphasis"><i class="EMPHASIS"><tt class=
 216           "LITERAL">/.*/banners/.*</tt></i></span> - A simple example that
 217           uses the common combination of <span class="QUOTE">"."</span> and
 218           <span class="QUOTE">"*"</span> to denote any character, zero or
 219           more times. In other words, any string at all. So we start with a
 220           literal forward slash, then our regular expression pattern (<span
 221           class="QUOTE">".*"</span>) another literal forward slash, the
 222           string <span class="QUOTE">"banners"</span>, another forward slash,
 223           and lastly another <span class="QUOTE">".*"</span>. We are building
 224           a directory path here. This will match any file with the path that
 225           has a directory named <span class="QUOTE">"banners"</span> in it.
 226           The <span class="QUOTE">".*"</span> matches any characters, and
 227           this could conceivably be more forward slashes, so it might expand
 228           into a much longer looking path. For example, this could match:
 229           <span class=
 230           "QUOTE">"/eye/hate/spammers/banners/annoy_me_please.gif"</span>, or
 231           just <span class="QUOTE">"/banners/annoying.html"</span>, or almost
 232           an infinite number of other possible combinations, just so it has
 233           <span class="QUOTE">"banners"</span> in the path somewhere.
 234         </p>
 235         <p>
 236           And now something a little more complex:
 237         </p>
 238         <p>
 239           <span class="emphasis"><i class="EMPHASIS"><tt class=
 240           "LITERAL">/.*/adv((er)?ts?|ertis(ing|ements?))?/</tt></i></span> -
 241           We have several literal forward slashes again (<span class=
 242           "QUOTE">"/"</span>), so we are building another expression that is
 243           a file path statement. We have another <span class=
 244           "QUOTE">".*"</span>, so we are matching against any conceivable
 245           sub-path, just so it matches our expression. The only true literal
 246           that <span class="emphasis"><i class="EMPHASIS">must
 247           match</i></span> our pattern is <span class=
 248           "APPLICATION">adv</span>, together with the forward slashes. What
 249           comes after the <span class="QUOTE">"adv"</span> string is the
 250           interesting part.
 251         </p>
 252         <p>
 253           Remember the <span class="QUOTE">"?"</span> means the preceding
 254           expression (either a literal character or anything grouped with
 255           <span class="QUOTE">"(...)"</span> in this case) can exist or not,
 256           since this means either zero or one match. So <span class=
 257           "QUOTE">"((er)?ts?|ertis(ing|ements?))"</span> is optional, as are
 258           the individual sub-expressions: <span class="QUOTE">"(er)"</span>,
 259           <span class="QUOTE">"(ing|ements?)"</span>, and the <span class=
 260           "QUOTE">"s"</span>. The <span class="QUOTE">"|"</span> means <span
 261           class="QUOTE">"or"</span>. We have two of those. For instance,
 262           <span class="QUOTE">"(ing|ements?)"</span>, can expand to match
 263           either <span class="QUOTE">"ing"</span> <span class="emphasis"><i
 264           class="EMPHASIS">OR</i></span> <span class=
 265           "QUOTE">"ements?"</span>. What is being done here, is an attempt at
 266           matching as many variations of <span class=
 267           "QUOTE">"advertisement"</span>, and similar, as possible. So this
 268           would expand to match just <span class="QUOTE">"adv"</span>, or
 269           <span class="QUOTE">"advert"</span>, or <span class=
 270           "QUOTE">"adverts"</span>, or <span class=
 271           "QUOTE">"advertising"</span>, or <span class=
 272           "QUOTE">"advertisement"</span>, or <span class=
 273           "QUOTE">"advertisements"</span>. You get the idea. But it would not
 274           match <span class="QUOTE">"advertizements"</span> (with a <span
 275           class="QUOTE">"z"</span>). We could fix that by changing our
 276           regular expression to: <span class=
 277           "QUOTE">"/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/"</span>, which
 278           would then match either spelling.
 279         </p>
 280         <p>
 281           <span class="emphasis"><i class="EMPHASIS"><tt class=
 282           "LITERAL">/.*/advert[0-9]+\.(gif|jpe?g)</tt></i></span> - Again
 283           another path statement with forward slashes. Anything in the square
 284           brackets <span class="QUOTE">"[ ]"</span> can be matched. This is
 285           using <span class="QUOTE">"0-9"</span> as a shorthand expression to
 286           mean any digit one through nine. It is the same as saying <span
 287           class="QUOTE">"0123456789"</span>. So any digit matches. The <span
 288           class="QUOTE">"+"</span> means one or more of the preceding
 289           expression must be included. The preceding expression here is what
 290           is in the square brackets -- in this case, any digit one through
 291           nine. Then, at the end, we have a grouping: <span class=
 292           "QUOTE">"(gif|jpe?g)"</span>. This includes a <span class=
 293           "QUOTE">"|"</span>, so this needs to match the expression on either
 294           side of that bar character also. A simple <span class=
 295           "QUOTE">"gif"</span> on one side, and the other side will in turn
 296           match either <span class="QUOTE">"jpeg"</span> or <span class=
 297           "QUOTE">"jpg"</span>, since the <span class="QUOTE">"?"</span>
 298           means the letter <span class="QUOTE">"e"</span> is optional and can
 299           be matched once or not at all. So we are building an expression
 300           here to match image GIF or JPEG type image file. It must include
 301           the literal string <span class="QUOTE">"advert"</span>, then one or
 302           more digits, and a <span class="QUOTE">"."</span> (which is now a
 303           literal, and not a special character, since it is escaped with
 304           <span class="QUOTE">"\"</span>), and lastly either <span class=
 305           "QUOTE">"gif"</span>, or <span class="QUOTE">"jpeg"</span>, or
 306           <span class="QUOTE">"jpg"</span>. Some possible matches would
 307           include: <span class="QUOTE">"//advert1.jpg"</span>, <span class=
 308           "QUOTE">"/nasty/ads/advert1234.gif"</span>, <span class=
 309           "QUOTE">"/banners/from/hell/advert99.jpg"</span>. It would not
 310           match <span class="QUOTE">"advert1.gif"</span> (no leading slash),
 311           or <span class="QUOTE">"/adverts232.jpg"</span> (the expression
 312           does not include an <span class="QUOTE">"s"</span>), or <span
 313           class="QUOTE">"/advert1.jsp"</span> (<span class=
 314           "QUOTE">"jsp"</span> is not in the expression anywhere).
 315         </p>
 316         <p>
 317           We are barely scratching the surface of regular expressions here so
 318           that you can understand the default <span class=
 319           "APPLICATION">Privoxy</span> configuration files, and maybe use
 320           this knowledge to customize your own installation. There is much,
 321           much more that can be done with regular expressions. Now that you
 322           know enough to get started, you can learn more on your own :/
 323         </p>
 324         <p>
 325           More reading on Perl Compatible Regular expressions: <a href=
 326           "http://perldoc.perl.org/perlre.html" target=
 327           "_top">http://perldoc.perl.org/perlre.html</a>
 328         </p>
 329         <p>
 330           For information on regular expression based substitutions and their
 331           applications in filters, please see the <a href=
 332           "filter-file.html">filter file tutorial</a> in this manual.
 333         </p>
 334       </div>
 335       <div class="SECT2">
 336         <h2 class="SECT2">
 337           <a name="INTERNAL-PAGES">14.2. Privoxy's Internal Pages</a>
 338         </h2>
 339         <p>
 340           Since <span class="APPLICATION">Privoxy</span> proxies each
 341           requested web page, it is easy for <span class=
 342           "APPLICATION">Privoxy</span> to trap certain special URLs. In this
 343           way, we can talk directly to <span class=
 344           "APPLICATION">Privoxy</span>, and see how it is configured, see how
 345           our rules are being applied, change these rules and other
 346           configuration options, and even turn <span class=
 347           "APPLICATION">Privoxy's</span> filtering off, all with a web
 348           browser.&#13;
 349         </p>
 350         <p>
 351           The URLs listed below are the special ones that allow direct access
 352           to <span class="APPLICATION">Privoxy</span>. Of course, <span
 353           class="APPLICATION">Privoxy</span> must be running to access these.
 354           If not, you will get a friendly error message. Internet access is
 355           not necessary either.
 356         </p>
 357         <p>
 358         </p>
 359         <ul>
 360           <li>
 361             <p>
 362               Privoxy main page:
 363             </p>
 364             <a name="AEN5923"></a>
 365             <blockquote class="BLOCKQUOTE">
 366               <p>
 367                 <a href="http://config.privoxy.org/" target=
 368                 "_top">http://config.privoxy.org/</a>
 369               </p>
 370             </blockquote>
 371             <p>
 372               There is a shortcut: <a href="http://p.p/" target=
 373               "_top">http://p.p/</a> (But it doesn't provide a fall-back to a
 374               real page, in case the request is not sent through <span class=
 375               "APPLICATION">Privoxy</span>)
 376             </p>
 377           </li>
 378           <li>
 379             <p>
 380               Show information about the current configuration, including
 381               viewing and editing of actions files:
 382             </p>
 383             <a name="AEN5931"></a>
 384             <blockquote class="BLOCKQUOTE">
 385               <p>
 386                 <a href="http://config.privoxy.org/show-status" target=
 387                 "_top">http://config.privoxy.org/show-status</a>
 388               </p>
 389             </blockquote>
 390           </li>
 391           <li>
 392             <p>
 393               Show the source code version numbers:
 394             </p>
 395             <a name="AEN5936"></a>
 396             <blockquote class="BLOCKQUOTE">
 397               <p>
 398                 <a href="http://config.privoxy.org/show-version" target=
 399                 "_top">http://config.privoxy.org/show-version</a>
 400               </p>
 401             </blockquote>
 402           </li>
 403           <li>
 404             <p>
 405               Show the browser's request headers:
 406             </p>
 407             <a name="AEN5941"></a>
 408             <blockquote class="BLOCKQUOTE">
 409               <p>
 410                 <a href="http://config.privoxy.org/show-request" target=
 411                 "_top">http://config.privoxy.org/show-request</a>
 412               </p>
 413             </blockquote>
 414           </li>
 415           <li>
 416             <p>
 417               Show which actions apply to a URL and why:
 418             </p>
 419             <a name="AEN5946"></a>
 420             <blockquote class="BLOCKQUOTE">
 421               <p>
 422                 <a href="http://config.privoxy.org/show-url-info" target=
 423                 "_top">http://config.privoxy.org/show-url-info</a>
 424               </p>
 425             </blockquote>
 426           </li>
 427           <li>
 428             <p>
 429               Toggle Privoxy on or off. This feature can be turned off/on in
 430               the main <tt class="FILENAME">config</tt> file. When toggled
 431               <span class="QUOTE">"off"</span>, <span class=
 432               "QUOTE">"Privoxy"</span> continues to run, but only as a
 433               pass-through proxy, with no actions taking place:
 434             </p>
 435             <a name="AEN5954"></a>
 436             <blockquote class="BLOCKQUOTE">
 437               <p>
 438                 <a href="http://config.privoxy.org/toggle" target=
 439                 "_top">http://config.privoxy.org/toggle</a>
 440               </p>
 441             </blockquote>
 442             <p>
 443               Short cuts. Turn off, then on:
 444             </p>
 445             <a name="AEN5958"></a>
 446             <blockquote class="BLOCKQUOTE">
 447               <p>
 448                 <a href="http://config.privoxy.org/toggle?set=disable"
 449                 target=
 450                 "_top">http://config.privoxy.org/toggle?set=disable</a>
 451               </p>
 452             </blockquote>
 453             <a name="AEN5961"></a>
 454             <blockquote class="BLOCKQUOTE">
 455               <p>
 456                 <a href="http://config.privoxy.org/toggle?set=enable" target=
 457                 "_top">http://config.privoxy.org/toggle?set=enable</a>
 458               </p>
 459             </blockquote>
 460           </li>
 461         </ul>
 462       </div>
 463       <div class="SECT2">
 464         <h2 class="SECT2">
 465           <a name="CHAIN">14.3. Chain of Events</a>
 466         </h2>
 467         <p>
 468           Let's take a quick look at how some of <span class=
 469           "APPLICATION">Privoxy's</span> core features are triggered, and the
 470           ensuing sequence of events when a web page is requested by your
 471           browser:
 472         </p>
 473         <p>
 474         </p>
 475         <ul>
 476           <li>
 477             <p>
 478               First, your web browser requests a web page. The browser knows
 479               to send the request to <span class=
 480               "APPLICATION">Privoxy</span>, which will in turn, relay the
 481               request to the remote web server after passing the following
 482               tests:
 483             </p>
 484           </li>
 485           <li>
 486             <p>
 487               <span class="APPLICATION">Privoxy</span> traps any request for
 488               its own internal CGI pages (e.g <a href="http://p.p/" target=
 489               "_top">http://p.p/</a>) and sends the CGI page back to the
 490               browser.
 491             </p>
 492           </li>
 493           <li>
 494             <p>
 495               Next, <span class="APPLICATION">Privoxy</span> checks to see if
 496               the URL matches any <a href="actions-file.html#BLOCK"><span
 497               class="QUOTE">"+block"</span></a> patterns. If so, the URL is
 498               then blocked, and the remote web server will not be contacted.
 499               <a href="actions-file.html#HANDLE-AS-IMAGE"><span class=
 500               "QUOTE">"+handle-as-image"</span></a> and <a href=
 501               "actions-file.html#HANDLE-AS-EMPTY-DOCUMENT"><span class=
 502               "QUOTE">"+handle-as-empty-document"</span></a> are then
 503               checked, and if there is no match, an HTML <span class=
 504               "QUOTE">"BLOCKED"</span> page is sent back to the browser.
 505               Otherwise, if it does match, an image is returned for the
 506               former, and an empty text document for the latter. The type of
 507               image would depend on the setting of <a href=
 508               "actions-file.html#SET-IMAGE-BLOCKER"><span class=
 509               "QUOTE">"+set-image-blocker"</span></a> (blank, checkerboard
 510               pattern, or an HTTP redirect to an image elsewhere).
 511             </p>
 512           </li>
 513           <li>
 514             <p>
 515               Untrusted URLs are blocked. If URLs are being added to the <tt
 516               class="FILENAME">trust</tt> file, then that is done.
 517             </p>
 518           </li>
 519           <li>
 520             <p>
 521               If the URL pattern matches the <a href=
 522               "actions-file.html#FAST-REDIRECTS"><span class=
 523               "QUOTE">"+fast-redirects"</span></a> action, it is then
 524               processed. Unwanted parts of the requested URL are stripped.
 525             </p>
 526           </li>
 527           <li>
 528             <p>
 529               Now the rest of the client browser's request headers are
 530               processed. If any of these match any of the relevant actions
 531               (e.g. <a href="actions-file.html#HIDE-USER-AGENT"><span class=
 532               "QUOTE">"+hide-user-agent"</span></a>, etc.), headers are
 533               suppressed or forged as determined by these actions and their
 534               parameters.
 535             </p>
 536           </li>
 537           <li>
 538             <p>
 539               Now the web server starts sending its response back (i.e.
 540               typically a web page).
 541             </p>
 542           </li>
 543           <li>
 544             <p>
 545               First, the server headers are read and processed to determine,
 546               among other things, the MIME type (document type) and encoding.
 547               The headers are then filtered as determined by the <a href=
 548               "actions-file.html#CRUNCH-INCOMING-COOKIES"><span class=
 549               "QUOTE">"+crunch-incoming-cookies"</span></a>, <a href=
 550               "actions-file.html#SESSION-COOKIES-ONLY"><span class=
 551               "QUOTE">"+session-cookies-only"</span></a>, and <a href=
 552               "actions-file.html#DOWNGRADE-HTTP-VERSION"><span class=
 553               "QUOTE">"+downgrade-http-version"</span></a> actions.
 554             </p>
 555           </li>
 556           <li>
 557             <p>
 558               If any <a href="actions-file.html#FILTER"><span class=
 559               "QUOTE">"+filter"</span></a> action or <a href=
 560               "actions-file.html#DEANIMATE-GIFS"><span class=
 561               "QUOTE">"+deanimate-gifs"</span></a> action applies (and the
 562               document type fits the action), the rest of the page is read
 563               into memory (up to a configurable limit). Then the filter rules
 564               (from <tt class="FILENAME">default.filter</tt> and any other
 565               filter files) are processed against the buffered content.
 566               Filters are applied in the order they are specified in one of
 567               the filter files. Animated GIFs, if present, are reduced to
 568               either the first or last frame, depending on the action
 569               setting.The entire page, which is now filtered, is then sent by
 570               <span class="APPLICATION">Privoxy</span> back to your browser.
 571             </p>
 572             <p>
 573               If neither a <a href="actions-file.html#FILTER"><span class=
 574               "QUOTE">"+filter"</span></a> action or <a href=
 575               "actions-file.html#DEANIMATE-GIFS"><span class=
 576               "QUOTE">"+deanimate-gifs"</span></a> matches, then <span class=
 577               "APPLICATION">Privoxy</span> passes the raw data through to the
 578               client browser as it becomes available.
 579             </p>
 580           </li>
 581           <li>
 582             <p>
 583               As the browser receives the now (possibly filtered) page
 584               content, it reads and then requests any URLs that may be
 585               embedded within the page source, e.g. ad images, stylesheets,
 586               JavaScript, other HTML documents (e.g. frames), sounds, etc.
 587               For each of these objects, the browser issues a separate
 588               request (this is easily viewable in <span class=
 589               "APPLICATION">Privoxy's</span> logs). And each such request is
 590               in turn processed just as above. Note that a complex web page
 591               will have many, many such embedded URLs. If these secondary
 592               requests are to a different server, then quite possibly a very
 593               differing set of actions is triggered.
 594             </p>
 595           </li>
 596         </ul>
 597
 598         <p>
 599           NOTE: This is somewhat of a simplistic overview of what happens
 600           with each URL request. For the sake of brevity and simplicity, we
 601           have focused on <span class="APPLICATION">Privoxy's</span> core
 602           features only.
 603         </p>
 604       </div>
 605       <div class="SECT2">
 606         <h2 class="SECT2">
 607           <a name="ACTIONSANAT">14.4. Troubleshooting: Anatomy of an
 608           Action</a>
 609         </h2>
 610         <p>
 611           The way <span class="APPLICATION">Privoxy</span> applies <a href=
 612           "actions-file.html#ACTIONS">actions</a> and <a href=
 613           "actions-file.html#FILTER">filters</a> to any given URL can be
 614           complex, and not always so easy to understand what is happening.
 615           And sometimes we need to be able to <span class="emphasis"><i
 616           class="EMPHASIS">see</i></span> just what <span class=
 617           "APPLICATION">Privoxy</span> is doing. Especially, if something
 618           <span class="APPLICATION">Privoxy</span> is doing is causing us a
 619           problem inadvertently. It can be a little daunting to look at the
 620           actions and filters files themselves, since they tend to be filled
 621           with <a href="appendix.html#REGEX">regular expressions</a> whose
 622           consequences are not always so obvious.
 623         </p>
 624         <p>
 625           One quick test to see if <span class="APPLICATION">Privoxy</span>
 626           is causing a problem or not, is to disable it temporarily. This
 627           should be the first troubleshooting step (be sure to flush caches
 628           afterward!). Looking at the logs is a good idea too. (Note that
 629           both the toggle feature and logging are enabled via <tt class=
 630           "FILENAME">config</tt> file settings, and may need to be turned
 631           <span class="QUOTE">"on"</span>.)
 632         </p>
 633         <p>
 634           Another easy troubleshooting step to try is if you have done any
 635           customization of your installation, revert back to the installed
 636           defaults and see if that helps. There are times the developers get
 637           complaints about one thing or another, and the problem is more
 638           related to a customized configuration issue.
 639         </p>
 640         <p>
 641           <span class="APPLICATION">Privoxy</span> also provides the <a href=
 642           "http://config.privoxy.org/show-url-info" target=
 643           "_top">http://config.privoxy.org/show-url-info</a> page that can
 644           show us very specifically how <span class=
 645           "APPLICATION">actions</span> are being applied to any given URL.
 646           This is a big help for troubleshooting.
 647         </p>
 648         <p>
 649           First, enter one URL (or partial URL) at the prompt, and then <span
 650           class="APPLICATION">Privoxy</span> will tell us how the current
 651           configuration will handle it. This will not help with filtering
 652           effects (i.e. the <a href="actions-file.html#FILTER"><span class=
 653           "QUOTE">"+filter"</span></a> action) from one of the filter files
 654           since this is handled very differently and not so easy to trap! It
 655           also will not tell you about any other URLs that may be embedded
 656           within the URL you are testing. For instance, images such as ads
 657           are expressed as URLs within the raw page source of HTML pages. So
 658           you will only get info for the actual URL that is pasted into the
 659           prompt area -- not any sub-URLs. If you want to know about embedded
 660           URLs like ads, you will have to dig those out of the HTML source.
 661           Use your browser's <span class="QUOTE">"View Page Source"</span>
 662           option for this. Or right click on the ad, and grab the URL.
 663         </p>
 664         <p>
 665           Let's try an example, <a href="http://google.com" target=
 666           "_top">google.com</a>, and look at it one section at a time in a
 667           sample configuration (your real configuration may vary):
 668         </p>
 669         <p>
 670         </p>
 671         <table border="0" bgcolor="#E0E0E0" width="100%">
 672           <tr>
 673             <td>
 674 <pre class="SCREEN">
 675  Matches for http://www.google.com:
 676
 677  In file: default.action <span class="GUIBUTTON">[ View ]</span> <span class=
 678 "GUIBUTTON">[ Edit ]</span>
 679
 680  {+change-x-forwarded-for{block}
 681  +deanimate-gifs {last}
 682  +fast-redirects {check-decoded-url}
 683  +filter {refresh-tags}
 684  +filter {img-reorder}
 685  +filter {banners-by-size}
 686  +filter {webbugs}
 687  +filter {jumping-windows}
 688  +filter {ie-exploits}
 689  +hide-from-header {block}
 690  +hide-referrer {forge}
 691  +session-cookies-only
 692  +set-image-blocker {pattern}
 693 /
 694
 695  { -session-cookies-only }
 696  .google.com
 697
 698  { -fast-redirects }
 699  .google.com
 700
 701 In file: user.action <span class="GUIBUTTON">[ View ]</span> <span class=
 702 "GUIBUTTON">[ Edit ]</span>
 703 (no matches in this file)
 704 </pre>
 705             </td>
 706           </tr>
 707         </table>
 708
 709         <p>
 710           This is telling us how we have defined our <a href=
 711           "actions-file.html#ACTIONS"><span class=
 712           "QUOTE">"actions"</span></a>, and which ones match for our test
 713           case, <span class="QUOTE">"google.com"</span>. Displayed is all the
 714           actions that are available to us. Remember, the <tt class=
 715           "LITERAL">+</tt> sign denotes <span class="QUOTE">"on"</span>. <tt
 716           class="LITERAL">-</tt> denotes <span class="QUOTE">"off"</span>. So
 717           some are <span class="QUOTE">"on"</span> here, but many are <span
 718           class="QUOTE">"off"</span>. Each example we try may provide a
 719           slightly different end result, depending on our configuration
 720           directives.
 721         </p>
 722         <p>
 723           The first listing is for our <tt class=
 724           "FILENAME">default.action</tt> file. The large, multi-line listing,
 725           is how the actions are set to match for all URLs, i.e. our default
 726           settings. If you look at your <span class="QUOTE">"actions"</span>
 727           file, this would be the section just below the <span class=
 728           "QUOTE">"aliases"</span> section near the top. This will apply to
 729           all URLs as signified by the single forward slash at the end of the
 730           listing -- <span class="QUOTE">" / "</span>.
 731         </p>
 732         <p>
 733           But we have defined additional actions that would be exceptions to
 734           these general rules, and then we list specific URLs (or patterns)
 735           that these exceptions would apply to. Last match wins. Just below
 736           this then are two explicit matches for <span class=
 737           "QUOTE">".google.com"</span>. The first is negating our previous
 738           cookie setting, which was for <a href=
 739           "actions-file.html#SESSION-COOKIES-ONLY"><span class=
 740           "QUOTE">"+session-cookies-only"</span></a> (i.e. not persistent).
 741           So we will allow persistent cookies for google, at least that is
 742           how it is in this example. The second turns <span class=
 743           "emphasis"><i class="EMPHASIS">off</i></span> any <a href=
 744           "actions-file.html#FAST-REDIRECTS"><span class=
 745           "QUOTE">"+fast-redirects"</span></a> action, allowing this to take
 746           place unmolested. Note that there is a leading dot here -- <span
 747           class="QUOTE">".google.com"</span>. This will match any hosts and
 748           sub-domains, in the google.com domain also, such as <span class=
 749           "QUOTE">"www.google.com"</span> or <span class=
 750           "QUOTE">"mail.google.com"</span>. But it would not match <span
 751           class="QUOTE">"www.google.de"</span>! So, apparently, we have these
 752           two actions defined as exceptions to the general rules at the top
 753           somewhere in the lower part of our <tt class=
 754           "FILENAME">default.action</tt> file, and <span class=
 755           "QUOTE">"google.com"</span> is referenced somewhere in these latter
 756           sections.
 757         </p>
 758         <p>
 759           Then, for our <tt class="FILENAME">user.action</tt> file, we again
 760           have no hits. So there is nothing google-specific that we might
 761           have added to our own, local configuration. If there was, those
 762           actions would over-rule any actions from previously processed
 763           files, such as <tt class="FILENAME">default.action</tt>. <tt class=
 764           "FILENAME">user.action</tt> typically has the last word. This is
 765           the best place to put hard and fast exceptions,
 766         </p>
 767         <p>
 768           And finally we pull it all together in the bottom section and
 769           summarize how <span class="APPLICATION">Privoxy</span> is applying
 770           all its <span class="QUOTE">"actions"</span> to <span class=
 771           "QUOTE">"google.com"</span>:&#13;
 772         </p>
 773         <p>
 774         </p>
 775         <table border="0" bgcolor="#E0E0E0" width="100%">
 776           <tr>
 777             <td>
 778 <pre class="SCREEN">
 779 &#13; Final results:
 780
 781  -add-header
 782  -block
 783  +change-x-forwarded-for{block}
 784  -client-header-filter{hide-tor-exit-notation}
 785  -content-type-overwrite
 786  -crunch-client-header
 787  -crunch-if-none-match
 788  -crunch-incoming-cookies
 789  -crunch-outgoing-cookies
 790  -crunch-server-header
 791  +deanimate-gifs {last}
 792  -downgrade-http-version
 793  -fast-redirects
 794  -filter {js-events}
 795  -filter {content-cookies}
 796  -filter {all-popups}
 797  -filter {banners-by-link}
 798  -filter {tiny-textforms}
 799  -filter {frameset-borders}
 800  -filter {demoronizer}
 801  -filter {shockwave-flash}
 802  -filter {quicktime-kioskmode}
 803  -filter {fun}
 804  -filter {crude-parental}
 805  -filter {site-specifics}
 806  -filter {js-annoyances}
 807  -filter {html-annoyances}
 808  +filter {refresh-tags}
 809  -filter {unsolicited-popups}
 810  +filter {img-reorder}
 811  +filter {banners-by-size}
 812  +filter {webbugs}
 813  +filter {jumping-windows}
 814  +filter {ie-exploits}
 815  -filter {google}
 816  -filter {yahoo}
 817  -filter {msn}
 818  -filter {blogspot}
 819  -filter {no-ping}
 820  -force-text-mode
 821  -handle-as-empty-document
 822  -handle-as-image
 823  -hide-accept-language
 824  -hide-content-disposition
 825  +hide-from-header {block}
 826  -hide-if-modified-since
 827  +hide-referrer {forge}
 828  -hide-user-agent
 829  -limit-connect
 830  -overwrite-last-modified
 831  -prevent-compression
 832  -redirect
 833  -server-header-filter{xml-to-html}
 834  -server-header-filter{html-to-xml}
 835  -session-cookies-only
 836  +set-image-blocker {pattern}
 837 </pre>
 838             </td>
 839           </tr>
 840         </table>
 841
 842         <p>
 843           Notice the only difference here to the previous listing, is to
 844           <span class="QUOTE">"fast-redirects"</span> and <span class=
 845           "QUOTE">"session-cookies-only"</span>, which are activated
 846           specifically for this site in our configuration, and thus show in
 847           the <span class="QUOTE">"Final Results"</span>.
 848         </p>
 849         <p>
 850           Now another example, <span class=
 851           "QUOTE">"ad.doubleclick.net"</span>:
 852         </p>
 853         <p>
 854         </p>
 855         <table border="0" bgcolor="#E0E0E0" width="100%">
 856           <tr>
 857             <td>
 858 <pre class="SCREEN">
 859 &#13; { +block{Domains starts with "ad"} }
 860   ad*.
 861
 862  { +block{Domain contains "ad"} }
 863   .ad.
 864
 865  { +block{Doubleclick banner server} +handle-as-image }
 866   .[a-vx-z]*.doubleclick.net
 867 </pre>
 868             </td>
 869           </tr>
 870         </table>
 871
 872         <p>
 873           We'll just show the interesting part here - the explicit matches.
 874           It is matched three different times. Two <span class=
 875           "QUOTE">"+block{}"</span> sections, and a <span class=
 876           "QUOTE">"+block{} +handle-as-image"</span>, which is the expanded
 877           form of one of our aliases that had been defined as: <span class=
 878           "QUOTE">"+block-as-image"</span>. (<a href=
 879           "actions-file.html#ALIASES"><span class=
 880           "QUOTE">"Aliases"</span></a> are defined in the first section of
 881           the actions file and typically used to combine more than one
 882           action.)
 883         </p>
 884         <p>
 885           Any one of these would have done the trick and blocked this as an
 886           unwanted image. This is unnecessarily redundant since the last case
 887           effectively would also cover the first. No point in taking chances
 888           with these guys though ;-) Note that if you want an ad or obnoxious
 889           URL to be invisible, it should be defined as <span class=
 890           "QUOTE">"ad.doubleclick.net"</span> is done here -- as both a <a
 891           href="actions-file.html#BLOCK"><span class=
 892           "QUOTE">"+block{}"</span></a> <span class="emphasis"><i class=
 893           "EMPHASIS">and</i></span> an <a href=
 894           "actions-file.html#HANDLE-AS-IMAGE"><span class=
 895           "QUOTE">"+handle-as-image"</span></a>. The custom alias <span
 896           class="QUOTE">"<tt class="LITERAL">+block-as-image</tt>"</span>
 897           just simplifies the process and make it more readable.
 898         </p>
 899         <p>
 900           One last example. Let's try <span class=
 901           "QUOTE">"http://www.example.net/adsl/HOWTO/"</span>. This one is
 902           giving us problems. We are getting a blank page. Hmmm ...
 903         </p>
 904         <p>
 905         </p>
 906         <table border="0" bgcolor="#E0E0E0" width="100%">
 907           <tr>
 908             <td>
 909 <pre class="SCREEN">
 910 &#13; Matches for http://www.example.net/adsl/HOWTO/:
 911
 912  In file: default.action <span class="GUIBUTTON">[ View ]</span> <span class=
 913 "GUIBUTTON">[ Edit ]</span>
 914
 915  {-add-header
 916   -block
 917   +change-x-forwarded-for{block}
 918   -client-header-filter{hide-tor-exit-notation}
 919   -content-type-overwrite
 920   -crunch-client-header
 921   -crunch-if-none-match
 922   -crunch-incoming-cookies
 923   -crunch-outgoing-cookies
 924   -crunch-server-header
 925   +deanimate-gifs
 926   -downgrade-http-version
 927   +fast-redirects {check-decoded-url}
 928   -filter {js-events}
 929   -filter {content-cookies}
 930   -filter {all-popups}
 931   -filter {banners-by-link}
 932   -filter {tiny-textforms}
 933   -filter {frameset-borders}
 934   -filter {demoronizer}
 935   -filter {shockwave-flash}
 936   -filter {quicktime-kioskmode}
 937   -filter {fun}
 938   -filter {crude-parental}
 939   -filter {site-specifics}
 940   -filter {js-annoyances}
 941   -filter {html-annoyances}
 942   +filter {refresh-tags}
 943   -filter {unsolicited-popups}
 944   +filter {img-reorder}
 945   +filter {banners-by-size}
 946   +filter {webbugs}
 947   +filter {jumping-windows}
 948   +filter {ie-exploits}
 949   -filter {google}
 950   -filter {yahoo}
 951   -filter {msn}
 952   -filter {blogspot}
 953   -filter {no-ping}
 954   -force-text-mode
 955   -handle-as-empty-document
 956   -handle-as-image
 957   -hide-accept-language
 958   -hide-content-disposition
 959   +hide-from-header{block}
 960   +hide-referer{forge}
 961   -hide-user-agent
 962   -overwrite-last-modified
 963   +prevent-compression
 964   -redirect
 965   -server-header-filter{xml-to-html}
 966   -server-header-filter{html-to-xml}
 967   +session-cookies-only
 968   +set-image-blocker{blank} }
 969    /
 970
 971  { +block{Path contains "ads".} +handle-as-image }
 972   /ads
 973 </pre>
 974             </td>
 975           </tr>
 976         </table>
 977
 978         <p>
 979           Ooops, the <span class="QUOTE">"/adsl/"</span> is matching <span
 980           class="QUOTE">"/ads"</span> in our configuration! But we did not
 981           want this at all! Now we see why we get the blank page. It is
 982           actually triggering two different actions here, and the effects are
 983           aggregated so that the URL is blocked, and <span class=
 984           "APPLICATION">Privoxy</span> is told to treat the block as if it
 985           were an image. But this is, of course, all wrong. We could now add
 986           a new action below this (or better in our own <tt class=
 987           "FILENAME">user.action</tt> file) that explicitly <span class=
 988           "emphasis"><i class="EMPHASIS">un</i></span> blocks ( <a href=
 989           "actions-file.html#BLOCK"><span class=
 990           "QUOTE">"{-block}"</span></a>) paths with <span class=
 991           "QUOTE">"adsl"</span> in them (remember, last match in the
 992           configuration wins). There are various ways to handle such
 993           exceptions. Example:
 994         </p>
 995         <p>
 996         </p>
 997         <table border="0" bgcolor="#E0E0E0" width="100%">
 998           <tr>
 999             <td>
1000 <pre class="SCREEN">
1001 &#13; { -block }
1002   /adsl
1003 </pre>
1004             </td>
1005           </tr>
1006         </table>
1007
1008         <p>
1009           Now the page displays ;-) Remember to flush your browser's caches
1010           when making these kinds of changes to your configuration to insure
1011           that you get a freshly delivered page! Or, try using <tt class=
1012           "LITERAL">Shift+Reload</tt>.
1013         </p>
1014         <p>
1015           But now what about a situation where we get no explicit matches
1016           like we did with:
1017         </p>
1018         <p>
1019         </p>
1020         <table border="0" bgcolor="#E0E0E0" width="100%">
1021           <tr>
1022             <td>
1023 <pre class="SCREEN">
1024 &#13; { +block{Path starts with "ads".} +handle-as-image }
1025  /ads
1026 </pre>
1027             </td>
1028           </tr>
1029         </table>
1030
1031         <p>
1032           That actually was very helpful and pointed us quickly to where the
1033           problem was. If you don't get this kind of match, then it means one
1034           of the default rules in the first section of <tt class=
1035           "FILENAME">default.action</tt> is causing the problem. This would
1036           require some guesswork, and maybe a little trial and error to
1037           isolate the offending rule. One likely cause would be one of the <a
1038           href="actions-file.html#FILTER"><span class=
1039           "QUOTE">"+filter"</span></a> actions. These tend to be harder to
1040           troubleshoot. Try adding the URL for the site to one of aliases
1041           that turn off <a href="actions-file.html#FILTER"><span class=
1042           "QUOTE">"+filter"</span></a>:
1043         </p>
1044         <p>
1045         </p>
1046         <table border="0" bgcolor="#E0E0E0" width="100%">
1047           <tr>
1048             <td>
1049 <pre class="SCREEN">
1050 &#13; { shop }
1051  .quietpc.com
1052  .worldpay.com   # for quietpc.com
1053  .jungle.com
1054  .scan.co.uk
1055  .forbes.com
1056 </pre>
1057             </td>
1058           </tr>
1059         </table>
1060
1061         <p>
1062           <span class="QUOTE">"<tt class="LITERAL">{ shop }</tt>"</span> is
1063           an <span class="QUOTE">"alias"</span> that expands to <span class=
1064           "QUOTE">"<tt class="LITERAL">{ -filter -session-cookies-only
1065           }</tt>"</span>. Or you could do your own exception to negate
1066           filtering:&#13;
1067         </p>
1068         <p>
1069         </p>
1070         <table border="0" bgcolor="#E0E0E0" width="100%">
1071           <tr>
1072             <td>
1073 <pre class="SCREEN">
1074 &#13; { -filter }
1075  # Disable ALL filter actions for sites in this section
1076  .forbes.com
1077  developer.ibm.com
1078  localhost
1079 </pre>
1080             </td>
1081           </tr>
1082         </table>
1083
1084         <p>
1085           This would turn off all filtering for these sites. This is best put
1086           in <tt class="FILENAME">user.action</tt>, for local site
1087           exceptions. Note that when a simple domain pattern is used by
1088           itself (without the subsequent path portion), all sub-pages within
1089           that domain are included automatically in the scope of the action.
1090         </p>
1091         <p>
1092           Images that are inexplicably being blocked, may well be hitting the
1093           <a href="actions-file.html#FILTER-BANNERS-BY-SIZE"><span class=
1094           "QUOTE">"+filter{banners-by-size}"</span></a> rule, which assumes
1095           that images of certain sizes are ad banners (works well <span
1096           class="emphasis"><i class="EMPHASIS">most of the time</i></span>
1097           since these tend to be standardized).
1098         </p>
1099         <p>
1100           <span class="QUOTE">"<tt class="LITERAL">{ fragile }</tt>"</span>
1101           is an alias that disables most actions that are the most likely to
1102           cause trouble. This can be used as a last resort for problem sites.
1103         </p>
1104         <p>
1105         </p>
1106         <table border="0" bgcolor="#E0E0E0" width="100%">
1107           <tr>
1108             <td>
1109 <pre class="SCREEN">
1110 &#13; { fragile }
1111  # Handle with care: easy to break
1112  mail.google.
1113  mybank.example.com
1114 </pre>
1115             </td>
1116           </tr>
1117         </table>
1118
1119         <p>
1120           <span class="emphasis"><i class="EMPHASIS">Remember to flush
1121           caches!</i></span> Note that the <tt class=
1122           "LITERAL">mail.google</tt> reference lacks the TLD portion (e.g.
1123           <span class="QUOTE">".com"</span>). This will effectively match any
1124           TLD with <tt class="LITERAL">google</tt> in it, such as <tt class=
1125           "LITERAL">mail.google.de.</tt>, just as an example.
1126         </p>
1127         <p>
1128           If this still does not work, you will have to go through the
1129           remaining actions one by one to find which one(s) is causing the
1130           problem.
1131         </p>
1132       </div>
1133     </div>
1134     <div class="NAVFOOTER">
1135       <hr align="LEFT" width="100%">
1136       <table summary="Footer navigation table" width="100%" border="0"
1137       cellpadding="0" cellspacing="0">
1138         <tr>
1139           <td width="33%" align="left" valign="top">
1140             <a href="seealso.html" accesskey="P">Prev</a>
1141           </td>
1142           <td width="34%" align="center" valign="top">
1143             <a href="index.html" accesskey="H">Home</a>
1144           </td>
1145           <td width="33%" align="right" valign="top">
1146             &nbsp;
1147           </td>
1148         </tr>
1149         <tr>
1150           <td width="33%" align="left" valign="top">
1151             See Also
1152           </td>
1153           <td width="34%" align="center" valign="top">
1154             &nbsp;
1155           </td>
1156           <td width="33%" align="right" valign="top">
1157             &nbsp;
1158           </td>
1159         </tr>
1160       </table>
1161     </div>
1162   </body>
1163 </html>
1164