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

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2 "http://www.w3.org/TR/html4/loose.dtd">
   3
   4 <html>
   5 <head>
   6   <meta name="generator" content=
   7   "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
   8
   9   <title>Actions Files</title>
  10   <meta name="GENERATOR" content=
  11   "Modular DocBook HTML Stylesheet Version 1.79">
  12   <link rel="HOME" title="Privoxy 3.0.18 User Manual" href="index.html">
  13   <link rel="PREVIOUS" title="The Main Configuration File" href=
  14   "config.html">
  15   <link rel="NEXT" title="Filter Files" href="filter-file.html">
  16   <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
  17   <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  18   <link rel="STYLESHEET" type="text/css" href="p_doc.css">
  19   <style type="text/css">
  20 body {
  21   background-color: #EEEEEE;
  22   color: #000000;
  23   }
  24   :link { color: #0000FF }
  25   :visited { color: #840084 }
  26   :active { color: #0000FF }
  27   td.c6 {font-weight: bold}
  28   tt.c5 {font-style: italic}
  29   table.c4 {background-color: #E0E0E0}
  30   p.c3 {font-weight: bold}
  31   span.c2 {font-style: italic}
  32   hr.c1 {text-align: left}
  33   </style>
  34 </head>
  35
  36 <body class="SECT1">
  37   <div class="NAVHEADER">
  38     <table summary="Header navigation table" width="100%" border="0"
  39     cellpadding="0" cellspacing="0">
  40       <tr>
  41         <th colspan="3" align="center">Privoxy 3.0.18 User Manual</th>
  42       </tr>
  43
  44       <tr>
  45         <td width="10%" align="left" valign="bottom"><a href="config.html"
  46         accesskey="P">Prev</a></td>
  47
  48         <td width="80%" align="center" valign="bottom"></td>
  49
  50         <td width="10%" align="right" valign="bottom"><a href=
  51         "filter-file.html" accesskey="N">Next</a></td>
  52       </tr>
  53     </table>
  54     <hr class="c1" width="100%">
  55   </div>
  56
  57   <div class="SECT1">
  58     <h1 class="SECT1"><a name="ACTIONS-FILE" id="ACTIONS-FILE">8. Actions
  59     Files</a></h1>
  60
  61     <p>The actions files are used to define what <span class=
  62     "emphasis EMPHASIS c2">actions</span> <span class=
  63     "APPLICATION">Privoxy</span> takes for which URLs, and thus determines
  64     how ad images, cookies and various other aspects of HTTP content and
  65     transactions are handled, and on which sites (or even parts thereof).
  66     There are a number of such actions, with a wide range of functionality.
  67     Each action does something a little different. These actions give us a
  68     veritable arsenal of tools with which to exert our control, preferences
  69     and independence. Actions can be combined so that their effects are
  70     aggregated when applied against a given set of URLs.</p>
  71
  72     <p>There are three action files included with <span class=
  73     "APPLICATION">Privoxy</span> with differing purposes:</p>
  74
  75     <ul>
  76       <li>
  77         <p><tt class="FILENAME">match-all.action</tt> - is used to define
  78         which <span class="QUOTE">"actions"</span> relating to
  79         banner-blocking, images, pop-ups, content modification, cookie
  80         handling etc should be applied by default. It should be the first
  81         actions file loaded</p>
  82       </li>
  83
  84       <li>
  85         <p><tt class="FILENAME">default.action</tt> - defines many exceptions
  86         (both positive and negative) from the default set of actions that's
  87         configured in <tt class="FILENAME">match-all.action</tt>. It is a set
  88         of rules that should work reasonably well as-is for most users. This
  89         file is only supposed to be edited by the developers. It should be
  90         the second actions file loaded.</p>
  91       </li>
  92
  93       <li>
  94         <p><tt class="FILENAME">user.action</tt> - is intended to be for
  95         local site preferences and exceptions. As an example, if your ISP or
  96         your bank has specific requirements, and need special handling, this
  97         kind of thing should go here. This file will not be upgraded.</p>
  98       </li>
  99
 100       <li>
 101         <p><span class="GUIBUTTON">Edit</span> <span class="GUIBUTTON">Set to
 102         Cautious</span> <span class="GUIBUTTON">Set to Medium</span>
 103         <span class="GUIBUTTON">Set to Advanced</span></p>
 104
 105         <p>These have increasing levels of aggressiveness <span class=
 106         "emphasis EMPHASIS c2">and have no influence on your browsing unless
 107         you select them explicitly in the editor</span>. A default
 108         installation should be pre-set to <tt class="LITERAL">Cautious</tt>.
 109         New users should try this for a while before adjusting the settings
 110         to more aggressive levels. The more aggressive the settings, then the
 111         more likelihood there is of problems such as sites not working as
 112         they should.</p>
 113
 114         <p>The <span class="GUIBUTTON">Edit</span> button allows you to turn
 115         each action on/off individually for fine-tuning. The <span class=
 116         "GUIBUTTON">Cautious</span> button changes the actions list to
 117         low/safe settings which will activate ad blocking and a minimal set
 118         of <span class="APPLICATION">Privoxy</span>'s features, and
 119         subsequently there will be less of a chance for accidental problems.
 120         The <span class="GUIBUTTON">Medium</span> button sets the list to a
 121         medium level of other features and a low level set of privacy
 122         features. The <span class="GUIBUTTON">Advanced</span> button sets the
 123         list to a high level of ad blocking and medium level of privacy. See
 124         the chart below. The latter three buttons over-ride any changes via
 125         with the <span class="GUIBUTTON">Edit</span> button. More fine-tuning
 126         can be done in the lower sections of this internal page.</p>
 127
 128         <p>While the actions file editor allows to enable these settings in
 129         all actions files, they are only supposed to be enabled in the first
 130         one to make sure you don't unintentionally overrule earlier
 131         rules.</p>
 132
 133         <p>The default profiles, and their associated actions, as pre-defined
 134         in <tt class="FILENAME">default.action</tt> are:</p>
 135
 136         <div class="TABLE">
 137           <a name="AEN2764" id="AEN2764"></a>
 138
 139           <p class="c3">Table 1. Default Configurations</p>
 140
 141           <table border="1" frame="border" rules="all" class="CALSTABLE">
 142             <col width="1*" title="C1">
 143             <col width="1*" title="C2">
 144             <col width="1*" title="C3">
 145             <col width="1*" title="C4">
 146
 147             <thead>
 148               <tr>
 149                 <th>Feature</th>
 150
 151                 <th>Cautious</th>
 152
 153                 <th>Medium</th>
 154
 155                 <th>Advanced</th>
 156               </tr>
 157             </thead>
 158
 159             <tbody>
 160               <tr>
 161                 <td>Ad-blocking Aggressiveness</td>
 162
 163                 <td>medium</td>
 164
 165                 <td>high</td>
 166
 167                 <td>high</td>
 168               </tr>
 169
 170               <tr>
 171                 <td>Ad-filtering by size</td>
 172
 173                 <td>no</td>
 174
 175                 <td>yes</td>
 176
 177                 <td>yes</td>
 178               </tr>
 179
 180               <tr>
 181                 <td>Ad-filtering by link</td>
 182
 183                 <td>no</td>
 184
 185                 <td>no</td>
 186
 187                 <td>yes</td>
 188               </tr>
 189
 190               <tr>
 191                 <td>Pop-up killing</td>
 192
 193                 <td>blocks only</td>
 194
 195                 <td>blocks only</td>
 196
 197                 <td>blocks only</td>
 198               </tr>
 199
 200               <tr>
 201                 <td>Privacy Features</td>
 202
 203                 <td>low</td>
 204
 205                 <td>medium</td>
 206
 207                 <td>medium/high</td>
 208               </tr>
 209
 210               <tr>
 211                 <td>Cookie handling</td>
 212
 213                 <td>none</td>
 214
 215                 <td>session-only</td>
 216
 217                 <td>kill</td>
 218               </tr>
 219
 220               <tr>
 221                 <td>Referer forging</td>
 222
 223                 <td>no</td>
 224
 225                 <td>yes</td>
 226
 227                 <td>yes</td>
 228               </tr>
 229
 230               <tr>
 231                 <td>GIF de-animation</td>
 232
 233                 <td>no</td>
 234
 235                 <td>yes</td>
 236
 237                 <td>yes</td>
 238               </tr>
 239
 240               <tr>
 241                 <td>Fast redirects</td>
 242
 243                 <td>no</td>
 244
 245                 <td>no</td>
 246
 247                 <td>yes</td>
 248               </tr>
 249
 250               <tr>
 251                 <td>HTML taming</td>
 252
 253                 <td>no</td>
 254
 255                 <td>no</td>
 256
 257                 <td>yes</td>
 258               </tr>
 259
 260               <tr>
 261                 <td>JavaScript taming</td>
 262
 263                 <td>no</td>
 264
 265                 <td>no</td>
 266
 267                 <td>yes</td>
 268               </tr>
 269
 270               <tr>
 271                 <td>Web-bug killing</td>
 272
 273                 <td>no</td>
 274
 275                 <td>yes</td>
 276
 277                 <td>yes</td>
 278               </tr>
 279
 280               <tr>
 281                 <td>Image tag reordering</td>
 282
 283                 <td>no</td>
 284
 285                 <td>yes</td>
 286
 287                 <td>yes</td>
 288               </tr>
 289             </tbody>
 290           </table>
 291         </div>
 292       </li>
 293     </ul>
 294
 295     <p>The list of actions files to be used are defined in the main
 296     configuration file, and are processed in the order they are defined (e.g.
 297     <tt class="FILENAME">default.action</tt> is typically processed before
 298     <tt class="FILENAME">user.action</tt>). The content of these can all be
 299     viewed and edited from <a href="http://config.privoxy.org/show-status"
 300     target="_top">http://config.privoxy.org/show-status</a>. The over-riding
 301     principle when applying actions, is that the last action that matches a
 302     given URL wins. The broadest, most general rules go first (defined in
 303     <tt class="FILENAME">default.action</tt>), followed by any exceptions
 304     (typically also in <tt class="FILENAME">default.action</tt>), which are
 305     then followed lastly by any local preferences (typically in <span class=
 306     "emphasis EMPHASIS c2">user</span><tt class="FILENAME">.action</tt>).
 307     Generally, <tt class="FILENAME">user.action</tt> has the last word.</p>
 308
 309     <p>An actions file typically has multiple sections. If you want to use
 310     <span class="QUOTE">"aliases"</span> in an actions file, you have to
 311     place the (optional) <a href="actions-file.html#ALIASES">alias
 312     section</a> at the top of that file. Then comes the default set of rules
 313     which will apply universally to all sites and pages (be <span class=
 314     "emphasis EMPHASIS c2">very careful</span> with using such a universal
 315     set in <tt class="FILENAME">user.action</tt> or any other actions file
 316     after <tt class="FILENAME">default.action</tt>, because it will override
 317     the result from consulting any previous file). And then below that,
 318     exceptions to the defined universal policies. You can regard <tt class=
 319     "FILENAME">user.action</tt> as an appendix to <tt class=
 320     "FILENAME">default.action</tt>, with the advantage that it is a separate
 321     file, which makes preserving your personal settings across <span class=
 322     "APPLICATION">Privoxy</span> upgrades easier.</p>
 323
 324     <p>Actions can be used to block anything you want, including ads,
 325     banners, or just some obnoxious URL whose content you would rather not
 326     see. Cookies can be accepted or rejected, or accepted only during the
 327     current browser session (i.e. not written to disk), content can be
 328     modified, some JavaScripts tamed, user-tracking fooled, and much more.
 329     See below for a <a href="actions-file.html#ACTIONS">complete list of
 330     actions</a>.</p>
 331
 332     <div class="SECT2">
 333       <h2 class="SECT2"><a name="AEN2863" id="AEN2863">8.1. Finding the Right
 334       Mix</a></h2>
 335
 336       <p>Note that some <a href="actions-file.html#ACTIONS">actions</a>, like
 337       cookie suppression or script disabling, may render some sites unusable
 338       that rely on these techniques to work properly. Finding the right mix
 339       of actions is not always easy and certainly a matter of personal taste.
 340       And, things can always change, requiring refinements in the
 341       configuration. In general, it can be said that the more <span class=
 342       "QUOTE">"aggressive"</span> your default settings (in the top section
 343       of the actions file) are, the more exceptions for <span class=
 344       "QUOTE">"trusted"</span> sites you will have to make later. If, for
 345       example, you want to crunch all cookies per default, you'll have to
 346       make exceptions from that rule for sites that you regularly use and
 347       that require cookies for actually useful purposes, like maybe your
 348       bank, favorite shop, or newspaper.</p>
 349
 350       <p>We have tried to provide you with reasonable rules to start from in
 351       the distribution actions files. But there is no general rule of thumb
 352       on these things. There just are too many variables, and sites are
 353       constantly changing. Sooner or later you will want to change the rules
 354       (and read this chapter again :).</p>
 355     </div>
 356
 357     <div class="SECT2">
 358       <h2 class="SECT2"><a name="AEN2870" id="AEN2870">8.2. How to
 359       Edit</a></h2>
 360
 361       <p>The easiest way to edit the actions files is with a browser by using
 362       our browser-based editor, which can be reached from <a href=
 363       "http://config.privoxy.org/show-status" target=
 364       "_top">http://config.privoxy.org/show-status</a>. Note: the config file
 365       option <a href=
 366       "config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions</a> must be
 367       enabled for this to work. The editor allows both fine-grained control
 368       over every single feature on a per-URL basis, and easy choosing from
 369       wholesale sets of defaults like <span class="QUOTE">"Cautious"</span>,
 370       <span class="QUOTE">"Medium"</span> or <span class=
 371       "QUOTE">"Advanced"</span>. Warning: the <span class=
 372       "QUOTE">"Advanced"</span> setting is more aggressive, and will be more
 373       likely to cause problems for some sites. Experienced users only!</p>
 374
 375       <p>If you prefer plain text editing to GUIs, you can of course also
 376       directly edit the the actions files with your favorite text editor.
 377       Look at <tt class="FILENAME">default.action</tt> which is richly
 378       commented with many good examples.</p>
 379     </div>
 380
 381     <div class="SECT2">
 382       <h2 class="SECT2"><a name="ACTIONS-APPLY" id="ACTIONS-APPLY">8.3. How
 383       Actions are Applied to Requests</a></h2>
 384
 385       <p>Actions files are divided into sections. There are special sections,
 386       like the <span class="QUOTE">"<a href=
 387       "actions-file.html#ALIASES">alias</a>"</span> sections which will be
 388       discussed later. For now let's concentrate on regular sections: They
 389       have a heading line (often split up to multiple lines for readability)
 390       which consist of a list of actions, separated by whitespace and
 391       enclosed in curly braces. Below that, there is a list of URL and tag
 392       patterns, each on a separate line.</p>
 393
 394       <p>To determine which actions apply to a request, the URL of the
 395       request is compared to all URL patterns in each <span class=
 396       "QUOTE">"action file"</span>. Every time it matches, the list of
 397       applicable actions for the request is incrementally updated, using the
 398       heading of the section in which the pattern is located. The same is
 399       done again for tags and tag patterns later on.</p>
 400
 401       <p>If multiple applying sections set the same action differently, the
 402       last match wins. If not, the effects are aggregated. E.g. a URL might
 403       match a regular section with a heading line of <tt class="LITERAL">{
 404       +<a href="actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a>
 405       }</tt>, then later another one with just <tt class="LITERAL">{
 406       +<a href="actions-file.html#BLOCK">block</a> }</tt>, resulting in
 407       <span class="emphasis EMPHASIS c2">both</span> actions to apply. And
 408       there may well be cases where you will want to combine actions
 409       together. Such a section then might look like:</p>
 410
 411       <table class="c4" border="0" width="100%">
 412         <tr>
 413           <td>
 414             <pre class="SCREEN">
 415   { +<tt class="LITERAL">handle-as-image</tt>  +<tt class=
 416 "LITERAL">block{Banner ads.}</tt> }
 417   # Block these as if they were images. Send no block page.
 418    banners.example.com
 419    media.example.com/.*banners
 420    .example.com/images/ads/
 421 </pre>
 422           </td>
 423         </tr>
 424       </table>
 425
 426       <p>You can trace this process for URL patterns and any given URL by
 427       visiting <a href="http://config.privoxy.org/show-url-info" target=
 428       "_top">http://config.privoxy.org/show-url-info</a>.</p>
 429
 430       <p>Examples and more detail on this is provided in the Appendix,
 431       <a href="appendix.html#ACTIONSANAT">Troubleshooting: Anatomy of an
 432       Action</a> section.</p>
 433     </div>
 434
 435     <div class="SECT2">
 436       <h2 class="SECT2"><a name="AF-PATTERNS" id="AF-PATTERNS">8.4.
 437       Patterns</a></h2>
 438
 439       <p>As mentioned, <span class="APPLICATION">Privoxy</span> uses
 440       <span class="QUOTE">"patterns"</span> to determine what <span class=
 441       "emphasis EMPHASIS c2">actions</span> might apply to which sites and
 442       pages your browser attempts to access. These <span class=
 443       "QUOTE">"patterns"</span> use wild card type <span class=
 444       "emphasis EMPHASIS c2">pattern</span> matching to achieve a high degree
 445       of flexibility. This allows one expression to be expanded and
 446       potentially match against many similar patterns.</p>
 447
 448       <p>Generally, an URL pattern has the form <tt class=
 449       "LITERAL">&lt;domain&gt;&lt;port&gt;/&lt;path&gt;</tt>, where the
 450       <tt class="LITERAL">&lt;domain&gt;</tt>, the <tt class=
 451       "LITERAL">&lt;port&gt;</tt> and the <tt class=
 452       "LITERAL">&lt;path&gt;</tt> are optional. (This is why the special
 453       <tt class="LITERAL">/</tt> pattern matches all URLs). Note that the
 454       protocol portion of the URL pattern (e.g. <tt class=
 455       "LITERAL">http://</tt>) should <span class=
 456       "emphasis EMPHASIS c2">not</span> be included in the pattern. This is
 457       assumed already!</p>
 458
 459       <p>The pattern matching syntax is different for the domain and path
 460       parts of the URL. The domain part uses a simple globbing type matching
 461       technique, while the path part uses more flexible <a href=
 462       "http://en.wikipedia.org/wiki/Regular_expressions" target=
 463       "_top"><span class="QUOTE">"Regular Expressions"</span></a> (POSIX
 464       1003.2).</p>
 465
 466       <p>The port part of a pattern is a decimal port number preceded by a
 467       colon (<tt class="LITERAL">:</tt>). If the domain part contains a
 468       numerical IPv6 address, it has to be put into angle brackets
 469       (<tt class="LITERAL">&lt;</tt>, <tt class="LITERAL">&gt;</tt>).</p>
 470
 471       <div class="VARIABLELIST">
 472         <dl>
 473           <dt><tt class="LITERAL">www.example.com/</tt></dt>
 474
 475           <dd>
 476             <p>is a domain-only pattern and will match any request to
 477             <tt class="LITERAL">www.example.com</tt>, regardless of which
 478             document on that server is requested. So ALL pages in this domain
 479             would be covered by the scope of this action. Note that a simple
 480             <tt class="LITERAL">example.com</tt> is different and would NOT
 481             match.</p>
 482           </dd>
 483
 484           <dt><tt class="LITERAL">www.example.com</tt></dt>
 485
 486           <dd>
 487             <p>means exactly the same. For domain-only patterns, the trailing
 488             <tt class="LITERAL">/</tt> may be omitted.</p>
 489           </dd>
 490
 491           <dt><tt class="LITERAL">www.example.com/index.html</tt></dt>
 492
 493           <dd>
 494             <p>matches all the documents on <tt class=
 495             "LITERAL">www.example.com</tt> whose name starts with <tt class=
 496             "LITERAL">/index.html</tt>.</p>
 497           </dd>
 498
 499           <dt><tt class="LITERAL">www.example.com/index.html$</tt></dt>
 500
 501           <dd>
 502             <p>matches only the single document <tt class=
 503             "LITERAL">/index.html</tt> on <tt class=
 504             "LITERAL">www.example.com</tt>.</p>
 505           </dd>
 506
 507           <dt><tt class="LITERAL">/index.html$</tt></dt>
 508
 509           <dd>
 510             <p>matches the document <tt class="LITERAL">/index.html</tt>,
 511             regardless of the domain, i.e. on <span class=
 512             "emphasis EMPHASIS c2">any</span> web server anywhere.</p>
 513           </dd>
 514
 515           <dt><tt class="LITERAL">/</tt></dt>
 516
 517           <dd>
 518             <p>Matches any URL because there's no requirement for either the
 519             domain or the path to match anything.</p>
 520           </dd>
 521
 522           <dt><tt class="LITERAL">:8000/</tt></dt>
 523
 524           <dd>
 525             <p>Matches any URL pointing to TCP port 8000.</p>
 526           </dd>
 527
 528           <dt><tt class="LITERAL">&lt;2001:db8::1&gt;/</tt></dt>
 529
 530           <dd>
 531             <p>Matches any URL with the host address <tt class=
 532             "LITERAL">2001:db8::1</tt>. (Note that the real URL uses plain
 533             brackets, not angle brackets.)</p>
 534           </dd>
 535
 536           <dt><tt class="LITERAL">index.html</tt></dt>
 537
 538           <dd>
 539             <p>matches nothing, since it would be interpreted as a domain
 540             name and there is no top-level domain called <tt class=
 541             "LITERAL">.html</tt>. So its a mistake.</p>
 542           </dd>
 543         </dl>
 544       </div>
 545
 546       <div class="SECT3">
 547         <h3 class="SECT3"><a name="AEN2982" id="AEN2982">8.4.1. The Domain
 548         Pattern</a></h3>
 549
 550         <p>The matching of the domain part offers some flexible options: if
 551         the domain starts or ends with a dot, it becomes unanchored at that
 552         end. For example:</p>
 553
 554         <div class="VARIABLELIST">
 555           <dl>
 556             <dt><tt class="LITERAL">.example.com</tt></dt>
 557
 558             <dd>
 559               <p>matches any domain with first-level domain <tt class=
 560               "LITERAL">com</tt> and second-level domain <tt class=
 561               "LITERAL">example</tt>. For example <tt class=
 562               "LITERAL">www.example.com</tt>, <tt class=
 563               "LITERAL">example.com</tt> and <tt class=
 564               "LITERAL">foo.bar.baz.example.com</tt>. Note that it wouldn't
 565               match if the second-level domain was <tt class=
 566               "LITERAL">another-example</tt>.</p>
 567             </dd>
 568
 569             <dt><tt class="LITERAL">www.</tt></dt>
 570
 571             <dd>
 572               <p>matches any domain that <span class=
 573               "emphasis EMPHASIS c2">STARTS</span> with <tt class=
 574               "LITERAL">www.</tt> (It also matches the domain <tt class=
 575               "LITERAL">www</tt> but most of the time that doesn't
 576               matter.)</p>
 577             </dd>
 578
 579             <dt><tt class="LITERAL">.example.</tt></dt>
 580
 581             <dd>
 582               <p>matches any domain that <span class=
 583               "emphasis EMPHASIS c2">CONTAINS</span> <tt class=
 584               "LITERAL">.example.</tt>. And, by the way, also included would
 585               be any files or documents that exist within that domain since
 586               no path limitations are specified. (Correctly speaking: It
 587               matches any FQDN that contains <tt class="LITERAL">example</tt>
 588               as a domain.) This might be <tt class=
 589               "LITERAL">www.example.com</tt>, <tt class=
 590               "LITERAL">news.example.de</tt>, or <tt class=
 591               "LITERAL">www.example.net/cgi/testing.pl</tt> for instance. All
 592               these cases are matched.</p>
 593             </dd>
 594           </dl>
 595         </div>
 596
 597         <p>Additionally, there are wild-cards that you can use in the domain
 598         names themselves. These work similarly to shell globbing type
 599         wild-cards: <span class="QUOTE">"*"</span> represents zero or more
 600         arbitrary characters (this is equivalent to the <a href=
 601         "http://en.wikipedia.org/wiki/Regular_expressions" target=
 602         "_top"><span class="QUOTE">"Regular Expression"</span></a> based
 603         syntax of <span class="QUOTE">".*"</span>), <span class=
 604         "QUOTE">"?"</span> represents any single character (this is
 605         equivalent to the regular expression syntax of a simple <span class=
 606         "QUOTE">"."</span>), and you can define <span class=
 607         "QUOTE">"character classes"</span> in square brackets which is
 608         similar to the same regular expression technique. All of this can be
 609         freely mixed:</p>
 610
 611         <div class="VARIABLELIST">
 612           <dl>
 613             <dt><tt class="LITERAL">ad*.example.com</tt></dt>
 614
 615             <dd>
 616               <p>matches <span class="QUOTE">"adserver.example.com"</span>,
 617               <span class="QUOTE">"ads.example.com"</span>, etc but not
 618               <span class="QUOTE">"sfads.example.com"</span></p>
 619             </dd>
 620
 621             <dt><tt class="LITERAL">*ad*.example.com</tt></dt>
 622
 623             <dd>
 624               <p>matches all of the above, and then some.</p>
 625             </dd>
 626
 627             <dt><tt class="LITERAL">.?pix.com</tt></dt>
 628
 629             <dd>
 630               <p>matches <tt class="LITERAL">www.ipix.com</tt>, <tt class=
 631               "LITERAL">pictures.epix.com</tt>, <tt class=
 632               "LITERAL">a.b.c.d.e.upix.com</tt> etc.</p>
 633             </dd>
 634
 635             <dt><tt class="LITERAL">www[1-9a-ez].example.c*</tt></dt>
 636
 637             <dd>
 638               <p>matches <tt class="LITERAL">www1.example.com</tt>,
 639               <tt class="LITERAL">www4.example.cc</tt>, <tt class=
 640               "LITERAL">wwwd.example.cy</tt>, <tt class=
 641               "LITERAL">wwwz.example.com</tt> etc., but <span class=
 642               "emphasis EMPHASIS c2">not</span> <tt class=
 643               "LITERAL">wwww.example.com</tt>.</p>
 644             </dd>
 645           </dl>
 646         </div>
 647
 648         <p>While flexible, this is not the sophistication of full regular
 649         expression based syntax.</p>
 650       </div>
 651
 652       <div class="SECT3">
 653         <h3 class="SECT3"><a name="AEN3058" id="AEN3058">8.4.2. The Path
 654         Pattern</a></h3>
 655
 656         <p><span class="APPLICATION">Privoxy</span> uses <span class=
 657         "QUOTE">"modern"</span> POSIX 1003.2 <a href=
 658         "http://en.wikipedia.org/wiki/Regular_expressions" target=
 659         "_top"><span class="QUOTE">"Regular Expressions"</span></a> for
 660         matching the path portion (after the slash), and is thus more
 661         flexible.</p>
 662
 663         <p>There is an <a href="appendix.html#REGEX">Appendix</a> with a
 664         brief quick-start into regular expressions, you also might want to
 665         have a look at your operating system's documentation on regular
 666         expressions (try <tt class="LITERAL">man re_format</tt>).</p>
 667
 668         <p>Note that the path pattern is automatically left-anchored at the
 669         <span class="QUOTE">"/"</span>, i.e. it matches as if it would start
 670         with a <span class="QUOTE">"^"</span> (regular expression speak for
 671         the beginning of a line).</p>
 672
 673         <p>Please also note that matching in the path is <span class=
 674         "emphasis EMPHASIS c2">CASE INSENSITIVE</span> by default, but you
 675         can switch to case sensitive at any point in the pattern by using the
 676         <span class="QUOTE">"(?-i)"</span> switch: <tt class=
 677         "LITERAL">www.example.com/(?-i)PaTtErN.*</tt> will match only
 678         documents whose path starts with <tt class="LITERAL">PaTtErN</tt> in
 679         <span class="emphasis EMPHASIS c2">exactly</span> this
 680         capitalization.</p>
 681
 682         <div class="VARIABLELIST">
 683           <dl>
 684             <dt><tt class="LITERAL">.example.com/.*</tt></dt>
 685
 686             <dd>
 687               <p>Is equivalent to just <span class=
 688               "QUOTE">".example.com"</span>, since any documents within that
 689               domain are matched with or without the <span class=
 690               "QUOTE">".*"</span> regular expression. This is redundant</p>
 691             </dd>
 692
 693             <dt><tt class="LITERAL">.example.com/.*/index.html$</tt></dt>
 694
 695             <dd>
 696               <p>Will match any page in the domain of <span class=
 697               "QUOTE">"example.com"</span> that is named <span class=
 698               "QUOTE">"index.html"</span>, and that is part of some path. For
 699               example, it matches <span class=
 700               "QUOTE">"www.example.com/testing/index.html"</span> but NOT
 701               <span class="QUOTE">"www.example.com/index.html"</span> because
 702               the regular expression called for at least two <span class=
 703               "QUOTE">"/'s"</span>, thus the path requirement. It also would
 704               match <span class=
 705               "QUOTE">"www.example.com/testing/index_html"</span>, because of
 706               the special meta-character <span class="QUOTE">"."</span>.</p>
 707             </dd>
 708
 709             <dt><tt class="LITERAL">.example.com/(.*/)?index\.html$</tt></dt>
 710
 711             <dd>
 712               <p>This regular expression is conditional so it will match any
 713               page named <span class="QUOTE">"index.html"</span> regardless
 714               of path which in this case can have one or more <span class=
 715               "QUOTE">"/'s"</span>. And this one must contain exactly
 716               <span class="QUOTE">".html"</span> (but does not have to end
 717               with that!).</p>
 718             </dd>
 719
 720             <dt><tt class=
 721             "LITERAL">.example.com/(.*/)(ads|banners?|junk)</tt></dt>
 722
 723             <dd>
 724               <p>This regular expression will match any path of <span class=
 725               "QUOTE">"example.com"</span> that contains any of the words
 726               <span class="QUOTE">"ads"</span>, <span class=
 727               "QUOTE">"banner"</span>, <span class="QUOTE">"banners"</span>
 728               (because of the <span class="QUOTE">"?"</span>) or <span class=
 729               "QUOTE">"junk"</span>. The path does not have to end in these
 730               words, just contain them.</p>
 731             </dd>
 732
 733             <dt><tt class=
 734             "LITERAL">.example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$</tt></dt>
 735
 736             <dd>
 737               <p>This is very much the same as above, except now it must end
 738               in either <span class="QUOTE">".jpg"</span>, <span class=
 739               "QUOTE">".jpeg"</span>, <span class="QUOTE">".gif"</span> or
 740               <span class="QUOTE">".png"</span>. So this one is limited to
 741               common image formats.</p>
 742             </dd>
 743           </dl>
 744         </div>
 745
 746         <p>There are many, many good examples to be found in <tt class=
 747         "FILENAME">default.action</tt>, and more tutorials below in <a href=
 748         "appendix.html#REGEX">Appendix on regular expressions</a>.</p>
 749       </div>
 750
 751       <div class="SECT3">
 752         <h3 class="SECT3"><a name="TAG-PATTERN" id="TAG-PATTERN">8.4.3. The
 753         Tag Pattern</a></h3>
 754
 755         <p>Tag patterns are used to change the applying actions based on the
 756         request's tags. Tags can be created with either the <a href=
 757         "actions-file.html#CLIENT-HEADER-TAGGER">client-header-tagger</a> or
 758         the <a href=
 759         "actions-file.html#SERVER-HEADER-TAGGER">server-header-tagger</a>
 760         action.</p>
 761
 762         <p>Tag patterns have to start with <span class="QUOTE">"TAG:"</span>,
 763         so <span class="APPLICATION">Privoxy</span> can tell them apart from
 764         URL patterns. Everything after the colon including white space, is
 765         interpreted as a regular expression with path pattern syntax, except
 766         that tag patterns aren't left-anchored automatically (<span class=
 767         "APPLICATION">Privoxy</span> doesn't silently add a <span class=
 768         "QUOTE">"^"</span>, you have to do it yourself if you need it).</p>
 769
 770         <p>To match all requests that are tagged with <span class=
 771         "QUOTE">"foo"</span> your pattern line should be <span class=
 772         "QUOTE">"TAG:^foo$"</span>, <span class="QUOTE">"TAG:foo"</span>
 773         would work as well, but it would also match requests whose tags
 774         contain <span class="QUOTE">"foo"</span> somewhere. <span class=
 775         "QUOTE">"TAG: foo"</span> wouldn't work as it requires white
 776         space.</p>
 777
 778         <p>Sections can contain URL and tag patterns at the same time, but
 779         tag patterns are checked after the URL patterns and thus always
 780         overrule them, even if they are located before the URL patterns.</p>
 781
 782         <p>Once a new tag is added, Privoxy checks right away if it's matched
 783         by one of the tag patterns and updates the action settings
 784         accordingly. As a result tags can be used to activate other tagger
 785         actions, as long as these other taggers look for headers that haven't
 786         already be parsed.</p>
 787
 788         <p>For example you could tag client requests which use the <tt class=
 789         "LITERAL">POST</tt> method, then use this tag to activate another
 790         tagger that adds a tag if cookies are sent, and then use a block
 791         action based on the cookie tag. This allows the outcome of one
 792         action, to be input into a subsequent action. However if you'd
 793         reverse the position of the described taggers, and activated the
 794         method tagger based on the cookie tagger, no method tags would be
 795         created. The method tagger would look for the request line, but at
 796         the time the cookie tag is created, the request line has already been
 797         parsed.</p>
 798
 799         <p>While this is a limitation you should be aware of, this kind of
 800         indirection is seldom needed anyway and even the example doesn't make
 801         too much sense.</p>
 802       </div>
 803     </div>
 804
 805     <div class="SECT2">
 806       <h2 class="SECT2"><a name="ACTIONS" id="ACTIONS">8.5. Actions</a></h2>
 807
 808       <p>All actions are disabled by default, until they are explicitly
 809       enabled somewhere in an actions file. Actions are turned on if preceded
 810       with a <span class="QUOTE">"+"</span>, and turned off if preceded with
 811       a <span class="QUOTE">"-"</span>. So a <tt class="LITERAL">+action</tt>
 812       means <span class="QUOTE">"do that action"</span>, e.g. <tt class=
 813       "LITERAL">+block</tt> means <span class="QUOTE">"please block URLs that
 814       match the following patterns"</span>, and <tt class=
 815       "LITERAL">-block</tt> means <span class="QUOTE">"don't block URLs that
 816       match the following patterns, even if <tt class="LITERAL">+block</tt>
 817       previously applied."</span></p>
 818
 819       <p>Again, actions are invoked by placing them on a line, enclosed in
 820       curly braces and separated by whitespace, like in <tt class=
 821       "LITERAL">{+some-action -some-other-action{some-parameter}}</tt>,
 822       followed by a list of URL patterns, one per line, to which they apply.
 823       Together, the actions line and the following pattern lines make up a
 824       section of the actions file.</p>
 825
 826       <p>Actions fall into three categories:</p>
 827
 828       <ul>
 829         <li>
 830           <p>Boolean, i.e the action can only be <span class=
 831           "QUOTE">"enabled"</span> or <span class="QUOTE">"disabled"</span>.
 832           Syntax:</p>
 833
 834           <table class="c4" border="0" width="90%">
 835             <tr>
 836               <td>
 837                 <pre class="SCREEN">
 838   +<tt class="REPLACEABLE c5">name</tt>        # enable action <tt class=
 839 "REPLACEABLE c5">name</tt>
 840   -<tt class="REPLACEABLE c5">name</tt>        # disable action <tt class=
 841 "REPLACEABLE c5">name</tt>
 842 </pre>
 843               </td>
 844             </tr>
 845           </table>
 846
 847           <p>Example: <tt class="LITERAL">+handle-as-image</tt></p>
 848         </li>
 849
 850         <li>
 851           <p>Parameterized, where some value is required in order to enable
 852           this type of action. Syntax:</p>
 853
 854           <table class="c4" border="0" width="90%">
 855             <tr>
 856               <td>
 857                 <pre class="SCREEN">
 858   +<tt class="REPLACEABLE c5">name</tt>{<tt class=
 859 "REPLACEABLE c5">param</tt>}  # enable action and set parameter to <tt class=
 860 "REPLACEABLE c5">param</tt>,
 861                # overwriting parameter from previous match if necessary
 862   -<tt class=
 863 "REPLACEABLE c5">name</tt>         # disable action. The parameter can be omitted
 864 </pre>
 865               </td>
 866             </tr>
 867           </table>
 868
 869           <p>Note that if the URL matches multiple positive forms of a
 870           parameterized action, the last match wins, i.e. the params from
 871           earlier matches are simply ignored.</p>
 872
 873           <p>Example: <tt class="LITERAL">+hide-user-agent{Mozilla/5.0 (X11;
 874           U; FreeBSD i386; en-US; rv:1.8.1.4) Gecko/20070602
 875           Firefox/2.0.0.4}</tt></p>
 876         </li>
 877
 878         <li>
 879           <p>Multi-value. These look exactly like parameterized actions, but
 880           they behave differently: If the action applies multiple times to
 881           the same URL, but with different parameters, <span class=
 882           "emphasis EMPHASIS c2">all</span> the parameters from <span class=
 883           "emphasis EMPHASIS c2">all</span> matches are remembered. This is
 884           used for actions that can be executed for the same request
 885           repeatedly, like adding multiple headers, or filtering through
 886           multiple filters. Syntax:</p>
 887
 888           <table class="c4" border="0" width="90%">
 889             <tr>
 890               <td>
 891                 <pre class="SCREEN">
 892   +<tt class="REPLACEABLE c5">name</tt>{<tt class=
 893 "REPLACEABLE c5">param</tt>}   # enable action and add <tt class=
 894 "REPLACEABLE c5">param</tt> to the list of parameters
 895   -<tt class="REPLACEABLE c5">name</tt>{<tt class=
 896 "REPLACEABLE c5">param</tt>}   # remove the parameter <tt class=
 897 "REPLACEABLE c5">param</tt> from the list of parameters
 898                 # If it was the last one left, disable the action.
 899   <tt class=
 900 "REPLACEABLE c5">-name</tt>          # disable this action completely and remove all parameters from the list
 901 </pre>
 902               </td>
 903             </tr>
 904           </table>
 905
 906           <p>Examples: <tt class="LITERAL">+add-header{X-Fun-Header: Some
 907           text}</tt> and <tt class=
 908           "LITERAL">+filter{html-annoyances}</tt></p>
 909         </li>
 910       </ul>
 911
 912       <p>If nothing is specified in any actions file, no <span class=
 913       "QUOTE">"actions"</span> are taken. So in this case <span class=
 914       "APPLICATION">Privoxy</span> would just be a normal, non-blocking,
 915       non-filtering proxy. You must specifically enable the privacy and
 916       blocking features you need (although the provided default actions files
 917       will give a good starting point).</p>
 918
 919       <p>Later defined action sections always over-ride earlier ones of the
 920       same type. So exceptions to any rules you make, should come in the
 921       latter part of the file (or in a file that is processed later when
 922       using multiple actions files such as <tt class=
 923       "FILENAME">user.action</tt>). For multi-valued actions, the actions are
 924       applied in the order they are specified. Actions files are processed in
 925       the order they are defined in <tt class="FILENAME">config</tt> (the
 926       default installation has three actions files). It also quite possible
 927       for any given URL to match more than one <span class=
 928       "QUOTE">"pattern"</span> (because of wildcards and regular
 929       expressions), and thus to trigger more than one set of actions! Last
 930       match wins.</p>
 931
 932       <p>The list of valid <span class="APPLICATION">Privoxy</span> actions
 933       are:</p>
 934
 935       <div class="SECT3">
 936         <h4 class="SECT3"><a name="ADD-HEADER" id="ADD-HEADER">8.5.1.
 937         add-header</a></h4>
 938
 939         <div class="VARIABLELIST">
 940           <dl>
 941             <dt>Typical use:</dt>
 942
 943             <dd>
 944               <p>Confuse log analysis, custom applications</p>
 945             </dd>
 946
 947             <dt>Effect:</dt>
 948
 949             <dd>
 950               <p>Sends a user defined HTTP header to the web server.</p>
 951             </dd>
 952
 953             <dt>Type:</dt>
 954
 955             <dd>
 956               <p>Multi-value.</p>
 957             </dd>
 958
 959             <dt>Parameter:</dt>
 960
 961             <dd>
 962               <p>Any string value is possible. Validity of the defined HTTP
 963               headers is not checked. It is recommended that you use the
 964               <span class="QUOTE">"<tt class="LITERAL">X-</tt>"</span> prefix
 965               for custom headers.</p>
 966             </dd>
 967
 968             <dt>Notes:</dt>
 969
 970             <dd>
 971               <p>This action may be specified multiple times, in order to
 972               define multiple headers. This is rarely needed for the typical
 973               user. If you don't know what <span class="QUOTE">"HTTP
 974               headers"</span> are, you definitely don't need to worry about
 975               this one.</p>
 976
 977               <p>Headers added by this action are not modified by other
 978               actions.</p>
 979             </dd>
 980
 981             <dt>Example usage:</dt>
 982
 983             <dd>
 984               <table class="c4" border="0" width="90%">
 985                 <tr>
 986                   <td>
 987                     <pre class="SCREEN">
 988 +add-header{X-User-Tracking: sucks}
 989 </pre>
 990                   </td>
 991                 </tr>
 992               </table>
 993             </dd>
 994           </dl>
 995         </div>
 996       </div>
 997
 998       <div class="SECT3">
 999         <h4 class="SECT3"><a name="BLOCK" id="BLOCK">8.5.2. block</a></h4>
1000
1001         <div class="VARIABLELIST">
1002           <dl>
1003             <dt>Typical use:</dt>
1004
1005             <dd>
1006               <p>Block ads or other unwanted content</p>
1007             </dd>
1008
1009             <dt>Effect:</dt>
1010
1011             <dd>
1012               <p>Requests for URLs to which this action applies are blocked,
1013               i.e. the requests are trapped by <span class=
1014               "APPLICATION">Privoxy</span> and the requested URL is never
1015               retrieved, but is answered locally with a substitute page or
1016               image, as determined by the <tt class="LITERAL"><a href=
1017               "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt>,
1018               <tt class="LITERAL"><a href=
1019               "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></tt>,
1020               and <tt class="LITERAL"><a href=
1021               "actions-file.html#HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document</a></tt>
1022               actions.</p>
1023             </dd>
1024
1025             <dt>Type:</dt>
1026
1027             <dd>
1028               <p>Parameterized.</p>
1029             </dd>
1030
1031             <dt>Parameter:</dt>
1032
1033             <dd>
1034               <p>A block reason that should be given to the user.</p>
1035             </dd>
1036
1037             <dt>Notes:</dt>
1038
1039             <dd>
1040               <p><span class="APPLICATION">Privoxy</span> sends a special
1041               <span class="QUOTE">"BLOCKED"</span> page for requests to
1042               blocked pages. This page contains the block reason given as
1043               parameter, a link to find out why the block action applies, and
1044               a click-through to the blocked content (the latter only if the
1045               force feature is available and enabled).</p>
1046
1047               <p>A very important exception occurs if <span class=
1048               "emphasis EMPHASIS c2">both</span> <tt class=
1049               "LITERAL">block</tt> and <tt class="LITERAL"><a href=
1050               "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt>,
1051               apply to the same request: it will then be replaced by an
1052               image. If <tt class="LITERAL"><a href=
1053               "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></tt>
1054               (see below) also applies, the type of image will be determined
1055               by its parameter, if not, the standard checkerboard pattern is
1056               sent.</p>
1057
1058               <p>It is important to understand this process, in order to
1059               understand how <span class="APPLICATION">Privoxy</span> deals
1060               with ads and other unwanted content. Blocking is a core
1061               feature, and one upon which various other features depend.</p>
1062
1063               <p>The <tt class="LITERAL"><a href=
1064               "actions-file.html#FILTER">filter</a></tt> action can perform a
1065               very similar task, by <span class="QUOTE">"blocking"</span>
1066               banner images and other content through rewriting the relevant
1067               URLs in the document's HTML source, so they don't get requested
1068               in the first place. Note that this is a totally different
1069               technique, and it's easy to confuse the two.</p>
1070             </dd>
1071
1072             <dt>Example usage (section):</dt>
1073
1074             <dd>
1075               <table class="c4" border="0" width="90%">
1076                 <tr>
1077                   <td>
1078                     <pre class="SCREEN">
1079 {+block{No nasty stuff for you.}}
1080 # Block and replace with "blocked" page
1081  .nasty-stuff.example.com
1082
1083 {+block{Doubleclick banners.} +handle-as-image}
1084 # Block and replace with image
1085  .ad.doubleclick.net
1086  .ads.r.us/banners/
1087
1088 {+block{Layered ads.} +handle-as-empty-document}
1089 # Block and then ignore
1090  adserver.example.net/.*\.js$
1091 </pre>
1092                   </td>
1093                 </tr>
1094               </table>
1095             </dd>
1096           </dl>
1097         </div>
1098       </div>
1099
1100       <div class="SECT3">
1101         <h4 class="SECT3"><a name="CHANGE-X-FORWARDED-FOR" id=
1102         "CHANGE-X-FORWARDED-FOR">8.5.3. change-x-forwarded-for</a></h4>
1103
1104         <div class="VARIABLELIST">
1105           <dl>
1106             <dt>Typical use:</dt>
1107
1108             <dd>
1109               <p>Improve privacy by not forwarding the source of the request
1110               in the HTTP headers.</p>
1111             </dd>
1112
1113             <dt>Effect:</dt>
1114
1115             <dd>
1116               <p>Deletes the <span class="QUOTE">"X-Forwarded-For:"</span>
1117               HTTP header from the client request, or adds a new one.</p>
1118             </dd>
1119
1120             <dt>Type:</dt>
1121
1122             <dd>
1123               <p>Parameterized.</p>
1124             </dd>
1125
1126             <dt>Parameter:</dt>
1127
1128             <dd>
1129               <ul>
1130                 <li>
1131                   <p><span class="QUOTE">"block"</span> to delete the
1132                   header.</p>
1133                 </li>
1134
1135                 <li>
1136                   <p><span class="QUOTE">"add"</span> to create the header
1137                   (or append the client's IP address to an already existing
1138                   one).</p>
1139                 </li>
1140               </ul>
1141             </dd>
1142
1143             <dt>Notes:</dt>
1144
1145             <dd>
1146               <p>It is safe and recommended to use <tt class=
1147               "LITERAL">block</tt>.</p>
1148
1149               <p>Forwarding the source address of the request may make sense
1150               in some multi-user setups but is also a privacy risk.</p>
1151             </dd>
1152
1153             <dt>Example usage:</dt>
1154
1155             <dd>
1156               <table class="c4" border="0" width="90%">
1157                 <tr>
1158                   <td>
1159                     <pre class="SCREEN">
1160 +change-x-forwarded-for{block}
1161 </pre>
1162                   </td>
1163                 </tr>
1164               </table>
1165             </dd>
1166           </dl>
1167         </div>
1168       </div>
1169
1170       <div class="SECT3">
1171         <h4 class="SECT3"><a name="CLIENT-HEADER-FILTER" id=
1172         "CLIENT-HEADER-FILTER">8.5.4. client-header-filter</a></h4>
1173
1174         <div class="VARIABLELIST">
1175           <dl>
1176             <dt>Typical use:</dt>
1177
1178             <dd>
1179               <p>Rewrite or remove single client headers.</p>
1180             </dd>
1181
1182             <dt>Effect:</dt>
1183
1184             <dd>
1185               <p>All client headers to which this action applies are filtered
1186               on-the-fly through the specified regular expression based
1187               substitutions.</p>
1188             </dd>
1189
1190             <dt>Type:</dt>
1191
1192             <dd>
1193               <p>Parameterized.</p>
1194             </dd>
1195
1196             <dt>Parameter:</dt>
1197
1198             <dd>
1199               <p>The name of a client-header filter, as defined in one of the
1200               <a href="filter-file.html">filter files</a>.</p>
1201             </dd>
1202
1203             <dt>Notes:</dt>
1204
1205             <dd>
1206               <p>Client-header filters are applied to each header on its own,
1207               not to all at once. This makes it easier to diagnose problems,
1208               but on the downside you can't write filters that only change
1209               header x if header y's value is z. You can do that by using
1210               tags though.</p>
1211
1212               <p>Client-header filters are executed after the other header
1213               actions have finished and use their output as input.</p>
1214
1215               <p>If the request URL gets changed, <span class=
1216               "APPLICATION">Privoxy</span> will detect that and use the new
1217               one. This can be used to rewrite the request destination behind
1218               the client's back, for example to specify a Tor exit relay for
1219               certain requests.</p>
1220
1221               <p>Please refer to the <a href="filter-file.html">filter file
1222               chapter</a> to learn which client-header filters are available
1223               by default, and how to create your own.</p>
1224             </dd>
1225
1226             <dt>Example usage (section):</dt>
1227
1228             <dd>
1229               <table class="c4" border="0" width="90%">
1230                 <tr>
1231                   <td>
1232                     <pre class="SCREEN">
1233 # Hide Tor exit notation in Host and Referer Headers
1234 {+client-header-filter{hide-tor-exit-notation}}
1235 /
1236
1237 </pre>
1238                   </td>
1239                 </tr>
1240               </table>
1241             </dd>
1242           </dl>
1243         </div>
1244       </div>
1245
1246       <div class="SECT3">
1247         <h4 class="SECT3"><a name="CLIENT-HEADER-TAGGER" id=
1248         "CLIENT-HEADER-TAGGER">8.5.5. client-header-tagger</a></h4>
1249
1250         <div class="VARIABLELIST">
1251           <dl>
1252             <dt>Typical use:</dt>
1253
1254             <dd>
1255               <p>Block requests based on their headers.</p>
1256             </dd>
1257
1258             <dt>Effect:</dt>
1259
1260             <dd>
1261               <p>Client headers to which this action applies are filtered
1262               on-the-fly through the specified regular expression based
1263               substitutions, the result is used as tag.</p>
1264             </dd>
1265
1266             <dt>Type:</dt>
1267
1268             <dd>
1269               <p>Parameterized.</p>
1270             </dd>
1271
1272             <dt>Parameter:</dt>
1273
1274             <dd>
1275               <p>The name of a client-header tagger, as defined in one of the
1276               <a href="filter-file.html">filter files</a>.</p>
1277             </dd>
1278
1279             <dt>Notes:</dt>
1280
1281             <dd>
1282               <p>Client-header taggers are applied to each header on its own,
1283               and as the header isn't modified, each tagger <span class=
1284               "QUOTE">"sees"</span> the original.</p>
1285
1286               <p>Client-header taggers are the first actions that are
1287               executed and their tags can be used to control every other
1288               action.</p>
1289             </dd>
1290
1291             <dt>Example usage (section):</dt>
1292
1293             <dd>
1294               <table class="c4" border="0" width="90%">
1295                 <tr>
1296                   <td>
1297                     <pre class="SCREEN">
1298 # Tag every request with the User-Agent header
1299 {+client-header-tagger{user-agent}}
1300 /
1301
1302 # Tagging itself doesn't change the action
1303 # settings, sections with TAG patterns do:
1304 #
1305 # If it's a download agent, use a different forwarding proxy,
1306 # show the real User-Agent and make sure resume works.
1307 {+forward-override{forward-socks5 10.0.0.2:2222 .} \
1308  -hide-if-modified-since      \
1309  -overwrite-last-modified     \
1310  -hide-user-agent             \
1311  -filter                      \
1312  -deanimate-gifs              \
1313 }
1314 TAG:^User-Agent: NetBSD-ftp/
1315 TAG:^User-Agent: Novell ZYPP Installer
1316 TAG:^User-Agent: RPM APT-HTTP/
1317 TAG:^User-Agent: fetch libfetch/
1318 TAG:^User-Agent: Ubuntu APT-HTTP/
1319 TAG:^User-Agent: MPlayer/
1320
1321 </pre>
1322                   </td>
1323                 </tr>
1324               </table>
1325             </dd>
1326           </dl>
1327         </div>
1328       </div>
1329
1330       <div class="SECT3">
1331         <h4 class="SECT3"><a name="CONTENT-TYPE-OVERWRITE" id=
1332         "CONTENT-TYPE-OVERWRITE">8.5.6. content-type-overwrite</a></h4>
1333
1334         <div class="VARIABLELIST">
1335           <dl>
1336             <dt>Typical use:</dt>
1337
1338             <dd>
1339               <p>Stop useless download menus from popping up, or change the
1340               browser's rendering mode</p>
1341             </dd>
1342
1343             <dt>Effect:</dt>
1344
1345             <dd>
1346               <p>Replaces the <span class="QUOTE">"Content-Type:"</span> HTTP
1347               server header.</p>
1348             </dd>
1349
1350             <dt>Type:</dt>
1351
1352             <dd>
1353               <p>Parameterized.</p>
1354             </dd>
1355
1356             <dt>Parameter:</dt>
1357
1358             <dd>
1359               <p>Any string.</p>
1360             </dd>
1361
1362             <dt>Notes:</dt>
1363
1364             <dd>
1365               <p>The <span class="QUOTE">"Content-Type:"</span> HTTP server
1366               header is used by the browser to decide what to do with the
1367               document. The value of this header can cause the browser to
1368               open a download menu instead of displaying the document by
1369               itself, even if the document's format is supported by the
1370               browser.</p>
1371
1372               <p>The declared content type can also affect which rendering
1373               mode the browser chooses. If XHTML is delivered as <span class=
1374               "QUOTE">"text/html"</span>, many browsers treat it as yet
1375               another broken HTML document. If it is send as <span class=
1376               "QUOTE">"application/xml"</span>, browsers with XHTML support
1377               will only display it, if the syntax is correct.</p>
1378
1379               <p>If you see a web site that proudly uses XHTML buttons, but
1380               sets <span class="QUOTE">"Content-Type: text/html"</span>, you
1381               can use <span class="APPLICATION">Privoxy</span> to overwrite
1382               it with <span class="QUOTE">"application/xml"</span> and
1383               validate the web master's claim inside your XHTML-supporting
1384               browser. If the syntax is incorrect, the browser will complain
1385               loudly.</p>
1386
1387               <p>You can also go the opposite direction: if your browser
1388               prints error messages instead of rendering a document falsely
1389               declared as XHTML, you can overwrite the content type with
1390               <span class="QUOTE">"text/html"</span> and have it rendered as
1391               broken HTML document.</p>
1392
1393               <p>By default <tt class="LITERAL">content-type-overwrite</tt>
1394               only replaces <span class="QUOTE">"Content-Type:"</span>
1395               headers that look like some kind of text. If you want to
1396               overwrite it unconditionally, you have to combine it with
1397               <tt class="LITERAL"><a href=
1398               "actions-file.html#FORCE-TEXT-MODE">force-text-mode</a></tt>.
1399               This limitation exists for a reason, think twice before
1400               circumventing it.</p>
1401
1402               <p>Most of the time it's easier to replace this action with a
1403               custom <tt class="LITERAL"><a href=
1404               "actions-file.html#SERVER-HEADER-FILTER">server-header
1405               filter</a></tt>. It allows you to activate it for every
1406               document of a certain site and it will still only replace the
1407               content types you aimed at.</p>
1408
1409               <p>Of course you can apply <tt class=
1410               "LITERAL">content-type-overwrite</tt> to a whole site and then
1411               make URL based exceptions, but it's a lot more work to get the
1412               same precision.</p>
1413             </dd>
1414
1415             <dt>Example usage (sections):</dt>
1416
1417             <dd>
1418               <table class="c4" border="0" width="90%">
1419                 <tr>
1420                   <td>
1421                     <pre class="SCREEN">
1422 # Check if www.example.net/ really uses valid XHTML
1423 { +content-type-overwrite{application/xml} }
1424 www.example.net/
1425
1426 # but leave the content type unmodified if the URL looks like a style sheet
1427 {-content-type-overwrite}
1428 www.example.net/.*\.css$
1429 www.example.net/.*style
1430 </pre>
1431                   </td>
1432                 </tr>
1433               </table>
1434             </dd>
1435           </dl>
1436         </div>
1437       </div>
1438
1439       <div class="SECT3">
1440         <h4 class="SECT3"><a name="CRUNCH-CLIENT-HEADER" id=
1441         "CRUNCH-CLIENT-HEADER">8.5.7. crunch-client-header</a></h4>
1442
1443         <div class="VARIABLELIST">
1444           <dl>
1445             <dt>Typical use:</dt>
1446
1447             <dd>
1448               <p>Remove a client header <span class=
1449               "APPLICATION">Privoxy</span> has no dedicated action for.</p>
1450             </dd>
1451
1452             <dt>Effect:</dt>
1453
1454             <dd>
1455               <p>Deletes every header sent by the client that contains the
1456               string the user supplied as parameter.</p>
1457             </dd>
1458
1459             <dt>Type:</dt>
1460
1461             <dd>
1462               <p>Parameterized.</p>
1463             </dd>
1464
1465             <dt>Parameter:</dt>
1466
1467             <dd>
1468               <p>Any string.</p>
1469             </dd>
1470
1471             <dt>Notes:</dt>
1472
1473             <dd>
1474               <p>This action allows you to block client headers for which no
1475               dedicated <span class="APPLICATION">Privoxy</span> action
1476               exists. <span class="APPLICATION">Privoxy</span> will remove
1477               every client header that contains the string you supplied as
1478               parameter.</p>
1479
1480               <p>Regular expressions are <span class=
1481               "emphasis EMPHASIS c2">not supported</span> and you can't use
1482               this action to block different headers in the same request,
1483               unless they contain the same string.</p>
1484
1485               <p><tt class="LITERAL">crunch-client-header</tt> is only meant
1486               for quick tests. If you have to block several different
1487               headers, or only want to modify parts of them, you should use a
1488               <tt class="LITERAL"><a href=
1489               "actions-file.html#CLIENT-HEADER-FILTER">client-header
1490               filter</a></tt>.</p>
1491
1492               <div class="WARNING">
1493                 <table class="WARNING" border="1" width="90%">
1494                   <tr>
1495                     <td class="c6" align="center">Warning</td>
1496                   </tr>
1497
1498                   <tr>
1499                     <td align="left">
1500                       <p>Don't block any header without understanding the
1501                       consequences.</p>
1502                     </td>
1503                   </tr>
1504                 </table>
1505               </div>
1506             </dd>
1507
1508             <dt>Example usage (section):</dt>
1509
1510             <dd>
1511               <table class="c4" border="0" width="90%">
1512                 <tr>
1513                   <td>
1514                     <pre class="SCREEN">
1515 # Block the non-existent "Privacy-Violation:" client header
1516 { +crunch-client-header{Privacy-Violation:} }
1517 /
1518
1519 </pre>
1520                   </td>
1521                 </tr>
1522               </table>
1523             </dd>
1524           </dl>
1525         </div>
1526       </div>
1527
1528       <div class="SECT3">
1529         <h4 class="SECT3"><a name="CRUNCH-IF-NONE-MATCH" id=
1530         "CRUNCH-IF-NONE-MATCH">8.5.8. crunch-if-none-match</a></h4>
1531
1532         <div class="VARIABLELIST">
1533           <dl>
1534             <dt>Typical use:</dt>
1535
1536             <dd>
1537               <p>Prevent yet another way to track the user's steps between
1538               sessions.</p>
1539             </dd>
1540
1541             <dt>Effect:</dt>
1542
1543             <dd>
1544               <p>Deletes the <span class="QUOTE">"If-None-Match:"</span> HTTP
1545               client header.</p>
1546             </dd>
1547
1548             <dt>Type:</dt>
1549
1550             <dd>
1551               <p>Boolean.</p>
1552             </dd>
1553
1554             <dt>Parameter:</dt>
1555
1556             <dd>
1557               <p>N/A</p>
1558             </dd>
1559
1560             <dt>Notes:</dt>
1561
1562             <dd>
1563               <p>Removing the <span class="QUOTE">"If-None-Match:"</span>
1564               HTTP client header is useful for filter testing, where you want
1565               to force a real reload instead of getting status code
1566               <span class="QUOTE">"304"</span> which would cause the browser
1567               to use a cached copy of the page.</p>
1568
1569               <p>It is also useful to make sure the header isn't used as a
1570               cookie replacement (unlikely but possible).</p>
1571
1572               <p>Blocking the <span class="QUOTE">"If-None-Match:"</span>
1573               header shouldn't cause any caching problems, as long as the
1574               <span class="QUOTE">"If-Modified-Since:"</span> header isn't
1575               blocked or missing as well.</p>
1576
1577               <p>It is recommended to use this action together with
1578               <tt class="LITERAL"><a href=
1579               "actions-file.html#HIDE-IF-MODIFIED-SINCE">hide-if-modified-since</a></tt>
1580               and <tt class="LITERAL"><a href=
1581               "actions-file.html#OVERWRITE-LAST-MODIFIED">overwrite-last-modified</a></tt>.</p>
1582             </dd>
1583
1584             <dt>Example usage (section):</dt>
1585
1586             <dd>
1587               <table class="c4" border="0" width="90%">
1588                 <tr>
1589                   <td>
1590                     <pre class="SCREEN">
1591 # Let the browser revalidate cached documents but don't
1592 # allow the server to use the revalidation headers for user tracking.
1593 {+hide-if-modified-since{-60} \
1594  +overwrite-last-modified{randomize} \
1595  +crunch-if-none-match}
1596 /
1597 </pre>
1598                   </td>
1599                 </tr>
1600               </table>
1601             </dd>
1602           </dl>
1603         </div>
1604       </div>
1605
1606       <div class="SECT3">
1607         <h4 class="SECT3"><a name="CRUNCH-INCOMING-COOKIES" id=
1608         "CRUNCH-INCOMING-COOKIES">8.5.9. crunch-incoming-cookies</a></h4>
1609
1610         <div class="VARIABLELIST">
1611           <dl>
1612             <dt>Typical use:</dt>
1613
1614             <dd>
1615               <p>Prevent the web server from setting HTTP cookies on your
1616               system</p>
1617             </dd>
1618
1619             <dt>Effect:</dt>
1620
1621             <dd>
1622               <p>Deletes any <span class="QUOTE">"Set-Cookie:"</span> HTTP
1623               headers from server replies.</p>
1624             </dd>
1625
1626             <dt>Type:</dt>
1627
1628             <dd>
1629               <p>Boolean.</p>
1630             </dd>
1631
1632             <dt>Parameter:</dt>
1633
1634             <dd>
1635               <p>N/A</p>
1636             </dd>
1637
1638             <dt>Notes:</dt>
1639
1640             <dd>
1641               <p>This action is only concerned with <span class=
1642               "emphasis EMPHASIS c2">incoming</span> HTTP cookies. For
1643               <span class="emphasis EMPHASIS c2">outgoing</span> HTTP
1644               cookies, use <tt class="LITERAL"><a href=
1645               "actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a></tt>.
1646               Use <span class="emphasis EMPHASIS c2">both</span> to disable
1647               HTTP cookies completely.</p>
1648
1649               <p>It makes <span class="emphasis EMPHASIS c2">no sense at
1650               all</span> to use this action in conjunction with the
1651               <tt class="LITERAL"><a href=
1652               "actions-file.html#SESSION-COOKIES-ONLY">session-cookies-only</a></tt>
1653               action, since it would prevent the session cookies from being
1654               set. See also <tt class="LITERAL"><a href=
1655               "actions-file.html#FILTER-CONTENT-COOKIES">filter-content-cookies</a></tt>.</p>
1656             </dd>
1657
1658             <dt>Example usage:</dt>
1659
1660             <dd>
1661               <table class="c4" border="0" width="90%">
1662                 <tr>
1663                   <td>
1664                     <pre class="SCREEN">
1665 +crunch-incoming-cookies
1666 </pre>
1667                   </td>
1668                 </tr>
1669               </table>
1670             </dd>
1671           </dl>
1672         </div>
1673       </div>
1674
1675       <div class="SECT3">
1676         <h4 class="SECT3"><a name="CRUNCH-SERVER-HEADER" id=
1677         "CRUNCH-SERVER-HEADER">8.5.10. crunch-server-header</a></h4>
1678
1679         <div class="VARIABLELIST">
1680           <dl>
1681             <dt>Typical use:</dt>
1682
1683             <dd>
1684               <p>Remove a server header <span class=
1685               "APPLICATION">Privoxy</span> has no dedicated action for.</p>
1686             </dd>
1687
1688             <dt>Effect:</dt>
1689
1690             <dd>
1691               <p>Deletes every header sent by the server that contains the
1692               string the user supplied as parameter.</p>
1693             </dd>
1694
1695             <dt>Type:</dt>
1696
1697             <dd>
1698               <p>Parameterized.</p>
1699             </dd>
1700
1701             <dt>Parameter:</dt>
1702
1703             <dd>
1704               <p>Any string.</p>
1705             </dd>
1706
1707             <dt>Notes:</dt>
1708
1709             <dd>
1710               <p>This action allows you to block server headers for which no
1711               dedicated <span class="APPLICATION">Privoxy</span> action
1712               exists. <span class="APPLICATION">Privoxy</span> will remove
1713               every server header that contains the string you supplied as
1714               parameter.</p>
1715
1716               <p>Regular expressions are <span class=
1717               "emphasis EMPHASIS c2">not supported</span> and you can't use
1718               this action to block different headers in the same request,
1719               unless they contain the same string.</p>
1720
1721               <p><tt class="LITERAL">crunch-server-header</tt> is only meant
1722               for quick tests. If you have to block several different
1723               headers, or only want to modify parts of them, you should use a
1724               custom <tt class="LITERAL"><a href=
1725               "actions-file.html#SERVER-HEADER-FILTER">server-header
1726               filter</a></tt>.</p>
1727
1728               <div class="WARNING">
1729                 <table class="WARNING" border="1" width="90%">
1730                   <tr>
1731                     <td class="c6" align="center">Warning</td>
1732                   </tr>
1733
1734                   <tr>
1735                     <td align="left">
1736                       <p>Don't block any header without understanding the
1737                       consequences.</p>
1738                     </td>
1739                   </tr>
1740                 </table>
1741               </div>
1742             </dd>
1743
1744             <dt>Example usage (section):</dt>
1745
1746             <dd>
1747               <table class="c4" border="0" width="90%">
1748                 <tr>
1749                   <td>
1750                     <pre class="SCREEN">
1751 # Crunch server headers that try to prevent caching
1752 { +crunch-server-header{no-cache} }
1753 /
1754 </pre>
1755                   </td>
1756                 </tr>
1757               </table>
1758             </dd>
1759           </dl>
1760         </div>
1761       </div>
1762
1763       <div class="SECT3">
1764         <h4 class="SECT3"><a name="CRUNCH-OUTGOING-COOKIES" id=
1765         "CRUNCH-OUTGOING-COOKIES">8.5.11. crunch-outgoing-cookies</a></h4>
1766
1767         <div class="VARIABLELIST">
1768           <dl>
1769             <dt>Typical use:</dt>
1770
1771             <dd>
1772               <p>Prevent the web server from reading any HTTP cookies from
1773               your system</p>
1774             </dd>
1775
1776             <dt>Effect:</dt>
1777
1778             <dd>
1779               <p>Deletes any <span class="QUOTE">"Cookie:"</span> HTTP
1780               headers from client requests.</p>
1781             </dd>
1782
1783             <dt>Type:</dt>
1784
1785             <dd>
1786               <p>Boolean.</p>
1787             </dd>
1788
1789             <dt>Parameter:</dt>
1790
1791             <dd>
1792               <p>N/A</p>
1793             </dd>
1794
1795             <dt>Notes:</dt>
1796
1797             <dd>
1798               <p>This action is only concerned with <span class=
1799               "emphasis EMPHASIS c2">outgoing</span> HTTP cookies. For
1800               <span class="emphasis EMPHASIS c2">incoming</span> HTTP
1801               cookies, use <tt class="LITERAL"><a href=
1802               "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a></tt>.
1803               Use <span class="emphasis EMPHASIS c2">both</span> to disable
1804               HTTP cookies completely.</p>
1805
1806               <p>It makes <span class="emphasis EMPHASIS c2">no sense at
1807               all</span> to use this action in conjunction with the
1808               <tt class="LITERAL"><a href=
1809               "actions-file.html#SESSION-COOKIES-ONLY">session-cookies-only</a></tt>
1810               action, since it would prevent the session cookies from being
1811               read.</p>
1812             </dd>
1813
1814             <dt>Example usage:</dt>
1815
1816             <dd>
1817               <table class="c4" border="0" width="90%">
1818                 <tr>
1819                   <td>
1820                     <pre class="SCREEN">
1821 +crunch-outgoing-cookies
1822 </pre>
1823                   </td>
1824                 </tr>
1825               </table>
1826             </dd>
1827           </dl>
1828         </div>
1829       </div>
1830
1831       <div class="SECT3">
1832         <h4 class="SECT3"><a name="DEANIMATE-GIFS" id=
1833         "DEANIMATE-GIFS">8.5.12. deanimate-gifs</a></h4>
1834
1835         <div class="VARIABLELIST">
1836           <dl>
1837             <dt>Typical use:</dt>
1838
1839             <dd>
1840               <p>Stop those annoying, distracting animated GIF images.</p>
1841             </dd>
1842
1843             <dt>Effect:</dt>
1844
1845             <dd>
1846               <p>De-animate GIF animations, i.e. reduce them to their first
1847               or last image.</p>
1848             </dd>
1849
1850             <dt>Type:</dt>
1851
1852             <dd>
1853               <p>Parameterized.</p>
1854             </dd>
1855
1856             <dt>Parameter:</dt>
1857
1858             <dd>
1859               <p><span class="QUOTE">"last"</span> or <span class=
1860               "QUOTE">"first"</span></p>
1861             </dd>
1862
1863             <dt>Notes:</dt>
1864
1865             <dd>
1866               <p>This will also shrink the images considerably (in bytes, not
1867               pixels!). If the option <span class="QUOTE">"first"</span> is
1868               given, the first frame of the animation is used as the
1869               replacement. If <span class="QUOTE">"last"</span> is given, the
1870               last frame of the animation is used instead, which probably
1871               makes more sense for most banner animations, but also has the
1872               risk of not showing the entire last frame (if it is only a
1873               delta to an earlier frame).</p>
1874
1875               <p>You can safely use this action with patterns that will also
1876               match non-GIF objects, because no attempt will be made at
1877               anything that doesn't look like a GIF.</p>
1878             </dd>
1879
1880             <dt>Example usage:</dt>
1881
1882             <dd>
1883               <table class="c4" border="0" width="90%">
1884                 <tr>
1885                   <td>
1886                     <pre class="SCREEN">
1887 +deanimate-gifs{last}
1888 </pre>
1889                   </td>
1890                 </tr>
1891               </table>
1892             </dd>
1893           </dl>
1894         </div>
1895       </div>
1896
1897       <div class="SECT3">
1898         <h4 class="SECT3"><a name="DOWNGRADE-HTTP-VERSION" id=
1899         "DOWNGRADE-HTTP-VERSION">8.5.13. downgrade-http-version</a></h4>
1900
1901         <div class="VARIABLELIST">
1902           <dl>
1903             <dt>Typical use:</dt>
1904
1905             <dd>
1906               <p>Work around (very rare) problems with HTTP/1.1</p>
1907             </dd>
1908
1909             <dt>Effect:</dt>
1910
1911             <dd>
1912               <p>Downgrades HTTP/1.1 client requests and server replies to
1913               HTTP/1.0.</p>
1914             </dd>
1915
1916             <dt>Type:</dt>
1917
1918             <dd>
1919               <p>Boolean.</p>
1920             </dd>
1921
1922             <dt>Parameter:</dt>
1923
1924             <dd>
1925               <p>N/A</p>
1926             </dd>
1927
1928             <dt>Notes:</dt>
1929
1930             <dd>
1931               <p>This is a left-over from the time when <span class=
1932               "APPLICATION">Privoxy</span> didn't support important HTTP/1.1
1933               features well. It is left here for the unlikely case that you
1934               experience HTTP/1.1 related problems with some server out
1935               there. Not all HTTP/1.1 features and requirements are supported
1936               yet, so there is a chance you might need this action.</p>
1937             </dd>
1938
1939             <dt>Example usage (section):</dt>
1940
1941             <dd>
1942               <table class="c4" border="0" width="90%">
1943                 <tr>
1944                   <td>
1945                     <pre class="SCREEN">
1946 {+downgrade-http-version}
1947 problem-host.example.com
1948 </pre>
1949                   </td>
1950                 </tr>
1951               </table>
1952             </dd>
1953           </dl>
1954         </div>
1955       </div>
1956
1957       <div class="SECT3">
1958         <h4 class="SECT3"><a name="FAST-REDIRECTS" id=
1959         "FAST-REDIRECTS">8.5.14. fast-redirects</a></h4>
1960
1961         <div class="VARIABLELIST">
1962           <dl>
1963             <dt>Typical use:</dt>
1964
1965             <dd>
1966               <p>Fool some click-tracking scripts and speed up indirect
1967               links.</p>
1968             </dd>
1969
1970             <dt>Effect:</dt>
1971
1972             <dd>
1973               <p>Detects redirection URLs and redirects the browser without
1974               contacting the redirection server first.</p>
1975             </dd>
1976
1977             <dt>Type:</dt>
1978
1979             <dd>
1980               <p>Parameterized.</p>
1981             </dd>
1982
1983             <dt>Parameter:</dt>
1984
1985             <dd>
1986               <ul>
1987                 <li>
1988                   <p><span class="QUOTE">"simple-check"</span> to just search
1989                   for the string <span class="QUOTE">"http://"</span> to
1990                   detect redirection URLs.</p>
1991                 </li>
1992
1993                 <li>
1994                   <p><span class="QUOTE">"check-decoded-url"</span> to decode
1995                   URLs (if necessary) before searching for redirection
1996                   URLs.</p>
1997                 </li>
1998               </ul>
1999             </dd>
2000
2001             <dt>Notes:</dt>
2002
2003             <dd>
2004               <p>Many sites, like yahoo.com, don't just link to other sites.
2005               Instead, they will link to some script on their own servers,
2006               giving the destination as a parameter, which will then redirect
2007               you to the final target. URLs resulting from this scheme
2008               typically look like: <span class=
2009               "QUOTE">"http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/"</span>.</p>
2010
2011               <p>Sometimes, there are even multiple consecutive redirects
2012               encoded in the URL. These redirections via scripts make your
2013               web browsing more traceable, since the server from which you
2014               follow such a link can see where you go to. Apart from that,
2015               valuable bandwidth and time is wasted, while your browser asks
2016               the server for one redirect after the other. Plus, it feeds the
2017               advertisers.</p>
2018
2019               <p>This feature is currently not very smart and is scheduled
2020               for improvement. If it is enabled by default, you will have to
2021               create some exceptions to this action. It can lead to failures
2022               in several ways:</p>
2023
2024               <p>Not every URLs with other URLs as parameters is evil. Some
2025               sites offer a real service that requires this information to
2026               work. For example a validation service needs to know, which
2027               document to validate. <tt class="LITERAL">fast-redirects</tt>
2028               assumes that every URL parameter that looks like another URL is
2029               a redirection target, and will always redirect to the last one.
2030               Most of the time the assumption is correct, but if it isn't,
2031               the user gets redirected anyway.</p>
2032
2033               <p>Another failure occurs if the URL contains other parameters
2034               after the URL parameter. The URL: <span class=
2035               "QUOTE">"http://www.example.org/?redirect=http%3a//www.example.net/&amp;foo=bar"</span>.
2036               contains the redirection URL <span class=
2037               "QUOTE">"http://www.example.net/"</span>, followed by another
2038               parameter. <tt class="LITERAL">fast-redirects</tt> doesn't know
2039               that and will cause a redirect to <span class=
2040               "QUOTE">"http://www.example.net/&amp;foo=bar"</span>. Depending
2041               on the target server configuration, the parameter will be
2042               silently ignored or lead to a <span class="QUOTE">"page not
2043               found"</span> error. You can prevent this problem by first
2044               using the <tt class="LITERAL"><a href=
2045               "actions-file.html#REDIRECT">redirect</a></tt> action to remove
2046               the last part of the URL, but it requires a little effort.</p>
2047
2048               <p>To detect a redirection URL, <tt class=
2049               "LITERAL">fast-redirects</tt> only looks for the string
2050               <span class="QUOTE">"http://"</span>, either in plain text
2051               (invalid but often used) or encoded as <span class=
2052               "QUOTE">"http%3a//"</span>. Some sites use their own URL
2053               encoding scheme, encrypt the address of the target server or
2054               replace it with a database id. In theses cases <tt class=
2055               "LITERAL">fast-redirects</tt> is fooled and the request reaches
2056               the redirection server where it probably gets logged.</p>
2057             </dd>
2058
2059             <dt>Example usage:</dt>
2060
2061             <dd>
2062               <table class="c4" border="0" width="90%">
2063                 <tr>
2064                   <td>
2065                     <pre class="SCREEN">
2066  { +fast-redirects{simple-check} }
2067    one.example.com
2068
2069  { +fast-redirects{check-decoded-url} }
2070    another.example.com/testing
2071 </pre>
2072                   </td>
2073                 </tr>
2074               </table>
2075             </dd>
2076           </dl>
2077         </div>
2078       </div>
2079
2080       <div class="SECT3">
2081         <h4 class="SECT3"><a name="FILTER" id="FILTER">8.5.15.
2082         filter</a></h4>
2083
2084         <div class="VARIABLELIST">
2085           <dl>
2086             <dt>Typical use:</dt>
2087
2088             <dd>
2089               <p>Get rid of HTML and JavaScript annoyances, banner
2090               advertisements (by size), do fun text replacements, add
2091               personalized effects, etc.</p>
2092             </dd>
2093
2094             <dt>Effect:</dt>
2095
2096             <dd>
2097               <p>All instances of text-based type, most notably HTML and
2098               JavaScript, to which this action applies, can be filtered
2099               on-the-fly through the specified regular expression based
2100               substitutions. (Note: as of version 3.0.3 plain text documents
2101               are exempted from filtering, because web servers often use the
2102               <tt class="LITERAL">text/plain</tt> MIME type for all files
2103               whose type they don't know.)</p>
2104             </dd>
2105
2106             <dt>Type:</dt>
2107
2108             <dd>
2109               <p>Parameterized.</p>
2110             </dd>
2111
2112             <dt>Parameter:</dt>
2113
2114             <dd>
2115               <p>The name of a content filter, as defined in the <a href=
2116               "filter-file.html">filter file</a>. Filters can be defined in
2117               one or more files as defined by the <tt class=
2118               "LITERAL"><a href="config.html#FILTERFILE">filterfile</a></tt>
2119               option in the <a href="config.html">config file</a>. <tt class=
2120               "FILENAME">default.filter</tt> is the collection of filters
2121               supplied by the developers. Locally defined filters should go
2122               in their own file, such as <tt class=
2123               "FILENAME">user.filter</tt>.</p>
2124
2125               <p>When used in its negative form, and without parameters,
2126               <span class="emphasis EMPHASIS c2">all</span> filtering is
2127               completely disabled.</p>
2128             </dd>
2129
2130             <dt>Notes:</dt>
2131
2132             <dd>
2133               <p>For your convenience, there are a number of pre-defined
2134               filters available in the distribution filter file that you can
2135               use. See the examples below for a list.</p>
2136
2137               <p>Filtering requires buffering the page content, which may
2138               appear to slow down page rendering since nothing is displayed
2139               until all content has passed the filters. (The total time until
2140               the page is completely rendered doesn't change much, but it may
2141               be perceived as slower since the page is not incrementally
2142               displayed.) This effect will be more noticeable on slower
2143               connections.</p>
2144
2145               <p><span class="QUOTE">"Rolling your own"</span> filters
2146               requires a knowledge of <a href=
2147               "http://en.wikipedia.org/wiki/Regular_expressions" target=
2148               "_top"><span class="QUOTE">"Regular Expressions"</span></a> and
2149               <a href="http://en.wikipedia.org/wiki/Html" target=
2150               "_top"><span class="QUOTE">"HTML"</span></a>. This is very
2151               powerful feature, and potentially very intrusive. Filters
2152               should be used with caution, and where an equivalent
2153               <span class="QUOTE">"action"</span> is not available.</p>
2154
2155               <p>The amount of data that can be filtered is limited to the
2156               <tt class="LITERAL"><a href=
2157               "config.html#BUFFER-LIMIT">buffer-limit</a></tt> option in the
2158               main <a href="config.html">config file</a>. The default is 4096
2159               KB (4 Megs). Once this limit is exceeded, the buffered data,
2160               and all pending data, is passed through unfiltered.</p>
2161
2162               <p>Inappropriate MIME types, such as zipped files, are not
2163               filtered at all. (Again, only text-based types except plain
2164               text). Encrypted SSL data (from HTTPS servers) cannot be
2165               filtered either, since this would violate the integrity of the
2166               secure transaction. In some situations it might be necessary to
2167               protect certain text, like source code, from filtering by
2168               defining appropriate <tt class="LITERAL">-filter</tt>
2169               exceptions.</p>
2170
2171               <p>Compressed content can't be filtered either, but if
2172               <span class="APPLICATION">Privoxy</span> is compiled with zlib
2173               support and a supported compression algorithm is used (gzip or
2174               deflate), <span class="APPLICATION">Privoxy</span> can first
2175               decompress the content and then filter it.</p>
2176
2177               <p>If you use a <span class="APPLICATION">Privoxy</span>
2178               version without zlib support, but want filtering to work on as
2179               much documents as possible, even those that would normally be
2180               sent compressed, you must use the <tt class="LITERAL"><a href=
2181               "actions-file.html#PREVENT-COMPRESSION">prevent-compression</a></tt>
2182               action in conjunction with <tt class="LITERAL">filter</tt>.</p>
2183
2184               <p>Content filtering can achieve some of the same effects as
2185               the <tt class="LITERAL"><a href=
2186               "actions-file.html#BLOCK">block</a></tt> action, i.e. it can be
2187               used to block ads and banners. But the mechanism works quite
2188               differently. One effective use, is to block ad banners based on
2189               their size (see below), since many of these seem to be somewhat
2190               standardized.</p>
2191
2192               <p><a href="contact.html">Feedback</a> with suggestions for new
2193               or improved filters is particularly welcome!</p>
2194
2195               <p>The below list has only the names and a one-line description
2196               of each predefined filter. There are <a href=
2197               "filter-file.html#PREDEFINED-FILTERS">more verbose
2198               explanations</a> of what these filters do in the <a href=
2199               "filter-file.html">filter file chapter</a>.</p>
2200             </dd>
2201
2202             <dt>Example usage (with filters from the distribution <tt class=
2203             "FILENAME">default.filter</tt> file). See <a href=
2204             "filter-file.html#PREDEFINED-FILTERS">the Predefined Filters
2205             section</a> for more explanation on each:</dt>
2206
2207             <dd>
2208               <p><a name="FILTER-JS-ANNOYANCES" id=
2209               "FILTER-JS-ANNOYANCES"></a></p>
2210
2211               <table class="c4" border="0" width="90%">
2212                 <tr>
2213                   <td>
2214                     <pre class="SCREEN">
2215 +filter{js-annoyances}       # Get rid of particularly annoying JavaScript abuse.
2216 </pre>
2217                   </td>
2218                 </tr>
2219               </table>
2220
2221               <p><a name="FILTER-JS-EVENTS" id="FILTER-JS-EVENTS"></a></p>
2222
2223               <table class="c4" border="0" width="90%">
2224                 <tr>
2225                   <td>
2226                     <pre class="SCREEN">
2227 +filter{js-events}           # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).
2228 </pre>
2229                   </td>
2230                 </tr>
2231               </table>
2232
2233               <p><a name="FILTER-HTML-ANNOYANCES" id=
2234               "FILTER-HTML-ANNOYANCES"></a></p>
2235
2236               <table class="c4" border="0" width="90%">
2237                 <tr>
2238                   <td>
2239                     <pre class="SCREEN">
2240 +filter{html-annoyances}     # Get rid of particularly annoying HTML abuse.
2241 </pre>
2242                   </td>
2243                 </tr>
2244               </table>
2245
2246               <p><a name="FILTER-CONTENT-COOKIES" id=
2247               "FILTER-CONTENT-COOKIES"></a></p>
2248
2249               <table class="c4" border="0" width="90%">
2250                 <tr>
2251                   <td>
2252                     <pre class="SCREEN">
2253 +filter{content-cookies}     # Kill cookies that come in the HTML or JS content.
2254 </pre>
2255                   </td>
2256                 </tr>
2257               </table>
2258
2259               <p><a name="FILTER-REFRESH-TAGS" id=
2260               "FILTER-REFRESH-TAGS"></a></p>
2261
2262               <table class="c4" border="0" width="90%">
2263                 <tr>
2264                   <td>
2265                     <pre class="SCREEN">
2266 +filter{refresh-tags}        # Kill automatic refresh tags (for dial-on-demand setups).
2267 </pre>
2268                   </td>
2269                 </tr>
2270               </table>
2271
2272               <p><a name="FILTER-UNSOLICITED-POPUPS" id=
2273               "FILTER-UNSOLICITED-POPUPS"></a></p>
2274
2275               <table class="c4" border="0" width="90%">
2276                 <tr>
2277                   <td>
2278                     <pre class="SCREEN">
2279 +filter{unsolicited-popups}  # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.
2280 </pre>
2281                   </td>
2282                 </tr>
2283               </table>
2284
2285               <p><a name="FILTER-ALL-POPUPS" id="FILTER-ALL-POPUPS"></a></p>
2286
2287               <table class="c4" border="0" width="90%">
2288                 <tr>
2289                   <td>
2290                     <pre class="SCREEN">
2291 +filter{all-popups}          # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.
2292 </pre>
2293                   </td>
2294                 </tr>
2295               </table>
2296
2297               <p><a name="FILTER-IMG-REORDER" id=
2298               "FILTER-IMG-REORDER"></a></p>
2299
2300               <table class="c4" border="0" width="90%">
2301                 <tr>
2302                   <td>
2303                     <pre class="SCREEN">
2304 +filter{img-reorder}         # Reorder attributes in &lt;img&gt; tags to make the banners-by-* filters more effective.
2305 </pre>
2306                   </td>
2307                 </tr>
2308               </table>
2309
2310               <p><a name="FILTER-BANNERS-BY-SIZE" id=
2311               "FILTER-BANNERS-BY-SIZE"></a></p>
2312
2313               <table class="c4" border="0" width="90%">
2314                 <tr>
2315                   <td>
2316                     <pre class="SCREEN">
2317 +filter{banners-by-size}     # Kill banners by size.
2318 </pre>
2319                   </td>
2320                 </tr>
2321               </table>
2322
2323               <p><a name="FILTER-BANNERS-BY-LINK" id=
2324               "FILTER-BANNERS-BY-LINK"></a></p>
2325
2326               <table class="c4" border="0" width="90%">
2327                 <tr>
2328                   <td>
2329                     <pre class="SCREEN">
2330 +filter{banners-by-link}     # Kill banners by their links to known clicktrackers.
2331 </pre>
2332                   </td>
2333                 </tr>
2334               </table>
2335
2336               <p><a name="FILTER-WEBBUGS" id="FILTER-WEBBUGS"></a></p>
2337
2338               <table class="c4" border="0" width="90%">
2339                 <tr>
2340                   <td>
2341                     <pre class="SCREEN">
2342 +filter{webbugs}             # Squish WebBugs (1x1 invisible GIFs used for user tracking).
2343 </pre>
2344                   </td>
2345                 </tr>
2346               </table>
2347
2348               <p><a name="FILTER-TINY-TEXTFORMS" id=
2349               "FILTER-TINY-TEXTFORMS"></a></p>
2350
2351               <table class="c4" border="0" width="90%">
2352                 <tr>
2353                   <td>
2354                     <pre class="SCREEN">
2355 +filter{tiny-textforms}      # Extend those tiny textareas up to 40x80 and kill the hard wrap.
2356 </pre>
2357                   </td>
2358                 </tr>
2359               </table>
2360
2361               <p><a name="FILTER-JUMPING-WINDOWS" id=
2362               "FILTER-JUMPING-WINDOWS"></a></p>
2363
2364               <table class="c4" border="0" width="90%">
2365                 <tr>
2366                   <td>
2367                     <pre class="SCREEN">
2368 +filter{jumping-windows}     # Prevent windows from resizing and moving themselves.
2369 </pre>
2370                   </td>
2371                 </tr>
2372               </table>
2373
2374               <p><a name="FILTER-FRAMESET-BORDERS" id=
2375               "FILTER-FRAMESET-BORDERS"></a></p>
2376
2377               <table class="c4" border="0" width="90%">
2378                 <tr>
2379                   <td>
2380                     <pre class="SCREEN">
2381 +filter{frameset-borders}    # Give frames a border and make them resizable.
2382 </pre>
2383                   </td>
2384                 </tr>
2385               </table>
2386
2387               <p><a name="FILTER-DEMORONIZER" id=
2388               "FILTER-DEMORONIZER"></a></p>
2389
2390               <table class="c4" border="0" width="90%">
2391                 <tr>
2392                   <td>
2393                     <pre class="SCREEN">
2394 +filter{demoronizer}         # Fix MS's non-standard use of standard charsets.
2395 </pre>
2396                   </td>
2397                 </tr>
2398               </table>
2399
2400               <p><a name="FILTER-SHOCKWAVE-FLASH" id=
2401               "FILTER-SHOCKWAVE-FLASH"></a></p>
2402
2403               <table class="c4" border="0" width="90%">
2404                 <tr>
2405                   <td>
2406                     <pre class="SCREEN">
2407 +filter{shockwave-flash}     # Kill embedded Shockwave Flash objects.
2408 </pre>
2409                   </td>
2410                 </tr>
2411               </table>
2412
2413               <p><a name="FILTER-QUICKTIME-KIOSKMODE" id=
2414               "FILTER-QUICKTIME-KIOSKMODE"></a></p>
2415
2416               <table class="c4" border="0" width="90%">
2417                 <tr>
2418                   <td>
2419                     <pre class="SCREEN">
2420 +filter{quicktime-kioskmode} # Make Quicktime movies saveable.
2421 </pre>
2422                   </td>
2423                 </tr>
2424               </table>
2425
2426               <p><a name="FILTER-FUN" id="FILTER-FUN"></a></p>
2427
2428               <table class="c4" border="0" width="90%">
2429                 <tr>
2430                   <td>
2431                     <pre class="SCREEN">
2432 +filter{fun}                 # Text replacements for subversive browsing fun!
2433 </pre>
2434                   </td>
2435                 </tr>
2436               </table>
2437
2438               <p><a name="FILTER-CRUDE-PARENTAL" id=
2439               "FILTER-CRUDE-PARENTAL"></a></p>
2440
2441               <table class="c4" border="0" width="90%">
2442                 <tr>
2443                   <td>
2444                     <pre class="SCREEN">
2445 +filter{crude-parental}      # Crude parental filtering. Note that this filter doesn't work reliably.
2446 </pre>
2447                   </td>
2448                 </tr>
2449               </table>
2450
2451               <p><a name="FILTER-IE-EXPLOITS" id=
2452               "FILTER-IE-EXPLOITS"></a></p>
2453
2454               <table class="c4" border="0" width="90%">
2455                 <tr>
2456                   <td>
2457                     <pre class="SCREEN">
2458 +filter{ie-exploits}         # Disable some known Internet Explorer bug exploits.
2459 </pre>
2460                   </td>
2461                 </tr>
2462               </table>
2463
2464               <p><a name="FILTER-SITE-SPECIFICS" id=
2465               "FILTER-SITE-SPECIFICS"></a></p>
2466
2467               <table class="c4" border="0" width="90%">
2468                 <tr>
2469                   <td>
2470                     <pre class="SCREEN">
2471 +filter{site-specifics}      # Cure for site-specific problems. Don't apply generally!
2472 </pre>
2473                   </td>
2474                 </tr>
2475               </table>
2476
2477               <p><a name="FILTER-NO-PING" id="FILTER-NO-PING"></a></p>
2478
2479               <table class="c4" border="0" width="90%">
2480                 <tr>
2481                   <td>
2482                     <pre class="SCREEN">
2483 +filter{no-ping}             # Removes non-standard ping attributes in &lt;a&gt; and &lt;area&gt; tags.
2484 </pre>
2485                   </td>
2486                 </tr>
2487               </table>
2488
2489               <p><a name="FILTER-GOOGLE" id="FILTER-GOOGLE"></a></p>
2490
2491               <table class="c4" border="0" width="90%">
2492                 <tr>
2493                   <td>
2494                     <pre class="SCREEN">
2495 +filter{google}              # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement.
2496 </pre>
2497                   </td>
2498                 </tr>
2499               </table>
2500
2501               <p><a name="FILTER-YAHOO" id="FILTER-YAHOO"></a></p>
2502
2503               <table class="c4" border="0" width="90%">
2504                 <tr>
2505                   <td>
2506                     <pre class="SCREEN">
2507 +filter{yahoo}               # CSS-based block for Yahoo text ads. Also removes a width limitation.
2508 </pre>
2509                   </td>
2510                 </tr>
2511               </table>
2512
2513               <p><a name="FILTER-MSN" id="FILTER-MSN"></a></p>
2514
2515               <table class="c4" border="0" width="90%">
2516                 <tr>
2517                   <td>
2518                     <pre class="SCREEN">
2519 +filter{msn}                 # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.
2520 </pre>
2521                   </td>
2522                 </tr>
2523               </table>
2524
2525               <p><a name="FILTER-BLOGSPOT" id="FILTER-BLOGSPOT"></a></p>
2526
2527               <table class="c4" border="0" width="90%">
2528                 <tr>
2529                   <td>
2530                     <pre class="SCREEN">
2531 +filter{blogspot}            # Cleans up some Blogspot blogs. Read the fine print before using this.
2532 </pre>
2533                   </td>
2534                 </tr>
2535               </table>
2536             </dd>
2537           </dl>
2538         </div>
2539       </div>
2540
2541       <div class="SECT3">
2542         <h4 class="SECT3"><a name="FORCE-TEXT-MODE" id=
2543         "FORCE-TEXT-MODE">8.5.16. force-text-mode</a></h4>
2544
2545         <div class="VARIABLELIST">
2546           <dl>
2547             <dt>Typical use:</dt>
2548
2549             <dd>
2550               <p>Force <span class="APPLICATION">Privoxy</span> to treat a
2551               document as if it was in some kind of <span class=
2552               "emphasis EMPHASIS c2">text</span> format.</p>
2553             </dd>
2554
2555             <dt>Effect:</dt>
2556
2557             <dd>
2558               <p>Declares a document as text, even if the <span class=
2559               "QUOTE">"Content-Type:"</span> isn't detected as such.</p>
2560             </dd>
2561
2562             <dt>Type:</dt>
2563
2564             <dd>
2565               <p>Boolean.</p>
2566             </dd>
2567
2568             <dt>Parameter:</dt>
2569
2570             <dd>
2571               <p>N/A</p>
2572             </dd>
2573
2574             <dt>Notes:</dt>
2575
2576             <dd>
2577               <p>As explained <tt class="LITERAL"><a href=
2578               "actions-file.html#FILTER">above</a></tt>, <span class=
2579               "APPLICATION">Privoxy</span> tries to only filter files that
2580               are in some kind of text format. The same restrictions apply to
2581               <tt class="LITERAL"><a href=
2582               "actions-file.html#CONTENT-TYPE-OVERWRITE">content-type-overwrite</a></tt>.
2583               <tt class="LITERAL">force-text-mode</tt> declares a document as
2584               text, without looking at the <span class=
2585               "QUOTE">"Content-Type:"</span> first.</p>
2586
2587               <div class="WARNING">
2588                 <table class="WARNING" border="1" width="90%">
2589                   <tr>
2590                     <td class="c6" align="center">Warning</td>
2591                   </tr>
2592
2593                   <tr>
2594                     <td align="left">
2595                       <p>Think twice before activating this action. Filtering
2596                       binary data with regular expressions can cause file
2597                       damage.</p>
2598                     </td>
2599                   </tr>
2600                 </table>
2601               </div>
2602             </dd>
2603
2604             <dt>Example usage:</dt>
2605
2606             <dd>
2607               <table class="c4" border="0" width="90%">
2608                 <tr>
2609                   <td>
2610                     <pre class="SCREEN">
2611 +force-text-mode
2612
2613 </pre>
2614                   </td>
2615                 </tr>
2616               </table>
2617             </dd>
2618           </dl>
2619         </div>
2620       </div>
2621
2622       <div class="SECT3">
2623         <h4 class="SECT3"><a name="FORWARD-OVERRIDE" id=
2624         "FORWARD-OVERRIDE">8.5.17. forward-override</a></h4>
2625
2626         <div class="VARIABLELIST">
2627           <dl>
2628             <dt>Typical use:</dt>
2629
2630             <dd>
2631               <p>Change the forwarding settings based on User-Agent or
2632               request origin</p>
2633             </dd>
2634
2635             <dt>Effect:</dt>
2636
2637             <dd>
2638               <p>Overrules the forward directives in the configuration
2639               file.</p>
2640             </dd>
2641
2642             <dt>Type:</dt>
2643
2644             <dd>
2645               <p>Multi-value.</p>
2646             </dd>
2647
2648             <dt>Parameter:</dt>
2649
2650             <dd>
2651               <ul>
2652                 <li>
2653                   <p><span class="QUOTE">"forward ."</span> to use a direct
2654                   connection without any additional proxies.</p>
2655                 </li>
2656
2657                 <li>
2658                   <p><span class="QUOTE">"forward 127.0.0.1:8123"</span> to
2659                   use the HTTP proxy listening at 127.0.0.1 port 8123.</p>
2660                 </li>
2661
2662                 <li>
2663                   <p><span class="QUOTE">"forward-socks4a 127.0.0.1:9050
2664                   ."</span> to use the socks4a proxy listening at 127.0.0.1
2665                   port 9050. Replace <span class=
2666                   "QUOTE">"forward-socks4a"</span> with <span class=
2667                   "QUOTE">"forward-socks4"</span> to use a socks4 connection
2668                   (with local DNS resolution) instead, use <span class=
2669                   "QUOTE">"forward-socks5"</span> for socks5 connections
2670                   (with remote DNS resolution).</p>
2671                 </li>
2672
2673                 <li>
2674                   <p><span class="QUOTE">"forward-socks4a 127.0.0.1:9050
2675                   proxy.example.org:8000"</span> to use the socks4a proxy
2676                   listening at 127.0.0.1 port 9050 to reach the HTTP proxy
2677                   listening at proxy.example.org port 8000. Replace
2678                   <span class="QUOTE">"forward-socks4a"</span> with
2679                   <span class="QUOTE">"forward-socks4"</span> to use a socks4
2680                   connection (with local DNS resolution) instead, use
2681                   <span class="QUOTE">"forward-socks5"</span> for socks5
2682                   connections (with remote DNS resolution).</p>
2683                 </li>
2684               </ul>
2685             </dd>
2686
2687             <dt>Notes:</dt>
2688
2689             <dd>
2690               <p>This action takes parameters similar to the <a href=
2691               "config.html#FORWARDING">forward</a> directives in the
2692               configuration file, but without the URL pattern. It can be used
2693               as replacement, but normally it's only used in cases where
2694               matching based on the request URL isn't sufficient.</p>
2695
2696               <div class="WARNING">
2697                 <table class="WARNING" border="1" width="90%">
2698                   <tr>
2699                     <td class="c6" align="center">Warning</td>
2700                   </tr>
2701
2702                   <tr>
2703                     <td align="left">
2704                       <p>Please read the description for the <a href=
2705                       "config.html#FORWARDING">forward</a> directives before
2706                       using this action. Forwarding to the wrong people will
2707                       reduce your privacy and increase the chances of
2708                       man-in-the-middle attacks.</p>
2709
2710                       <p>If the ports are missing or invalid, default values
2711                       will be used. This might change in the future and you
2712                       shouldn't rely on it. Otherwise incorrect syntax causes
2713                       Privoxy to exit.</p>
2714
2715                       <p>Use the <a href=
2716                       "http://config.privoxy.org/show-url-info" target=
2717                       "_top">show-url-info CGI page</a> to verify that your
2718                       forward settings do what you thought the do.</p>
2719                     </td>
2720                   </tr>
2721                 </table>
2722               </div>
2723             </dd>
2724
2725             <dt>Example usage:</dt>
2726
2727             <dd>
2728               <table class="c4" border="0" width="90%">
2729                 <tr>
2730                   <td>
2731                     <pre class="SCREEN">
2732 # Always use direct connections for requests previously tagged as
2733 # <span class="QUOTE">"User-Agent: fetch libfetch/2.0"</span> and make sure
2734 # resuming downloads continues to work.
2735 # This way you can continue to use Tor for your normal browsing,
2736 # without overloading the Tor network with your FreeBSD ports updates
2737 # or downloads of bigger files like ISOs.
2738 # Note that HTTP headers are easy to fake and therefore their
2739 # values are as (un)trustworthy as your clients and users.
2740 {+forward-override{forward .} \
2741  -hide-if-modified-since      \
2742  -overwrite-last-modified     \
2743 }
2744 TAG:^User-Agent: fetch libfetch/2\.0$
2745
2746 </pre>
2747                   </td>
2748                 </tr>
2749               </table>
2750             </dd>
2751           </dl>
2752         </div>
2753       </div>
2754
2755       <div class="SECT3">
2756         <h4 class="SECT3"><a name="HANDLE-AS-EMPTY-DOCUMENT" id=
2757         "HANDLE-AS-EMPTY-DOCUMENT">8.5.18. handle-as-empty-document</a></h4>
2758
2759         <div class="VARIABLELIST">
2760           <dl>
2761             <dt>Typical use:</dt>
2762
2763             <dd>
2764               <p>Mark URLs that should be replaced by empty documents
2765               <span class="emphasis EMPHASIS c2">if they get
2766               blocked</span></p>
2767             </dd>
2768
2769             <dt>Effect:</dt>
2770
2771             <dd>
2772               <p>This action alone doesn't do anything noticeable. It just
2773               marks URLs. If the <tt class="LITERAL"><a href=
2774               "actions-file.html#BLOCK">block</a></tt> action <span class=
2775               "emphasis EMPHASIS c2">also applies</span>, the presence or
2776               absence of this mark decides whether an HTML <span class=
2777               "QUOTE">"BLOCKED"</span> page, or an empty document will be
2778               sent to the client as a substitute for the blocked content. The
2779               <span class="emphasis EMPHASIS c2">empty</span> document isn't
2780               literally empty, but actually contains a single space.</p>
2781             </dd>
2782
2783             <dt>Type:</dt>
2784
2785             <dd>
2786               <p>Boolean.</p>
2787             </dd>
2788
2789             <dt>Parameter:</dt>
2790
2791             <dd>
2792               <p>N/A</p>
2793             </dd>
2794
2795             <dt>Notes:</dt>
2796
2797             <dd>
2798               <p>Some browsers complain about syntax errors if JavaScript
2799               documents are blocked with <span class=
2800               "APPLICATION">Privoxy's</span> default HTML page; this option
2801               can be used to silence them. And of course this action can also
2802               be used to eliminate the <span class=
2803               "APPLICATION">Privoxy</span> BLOCKED message in frames.</p>
2804
2805               <p>The content type for the empty document can be specified
2806               with <tt class="LITERAL"><a href=
2807               "actions-file.html#CONTENT-TYPE-OVERWRITE">content-type-overwrite{}</a></tt>,
2808               but usually this isn't necessary.</p>
2809             </dd>
2810
2811             <dt>Example usage:</dt>
2812
2813             <dd>
2814               <table class="c4" border="0" width="90%">
2815                 <tr>
2816                   <td>
2817                     <pre class="SCREEN">
2818 # Block all documents on example.org that end with ".js",
2819 # but send an empty document instead of the usual HTML message.
2820 {+block{Blocked JavaScript} +handle-as-empty-document}
2821 example.org/.*\.js$
2822
2823 </pre>
2824                   </td>
2825                 </tr>
2826               </table>
2827             </dd>
2828           </dl>
2829         </div>
2830       </div>
2831
2832       <div class="SECT3">
2833         <h4 class="SECT3"><a name="HANDLE-AS-IMAGE" id=
2834         "HANDLE-AS-IMAGE">8.5.19. handle-as-image</a></h4>
2835
2836         <div class="VARIABLELIST">
2837           <dl>
2838             <dt>Typical use:</dt>
2839
2840             <dd>
2841               <p>Mark URLs as belonging to images (so they'll be replaced by
2842               images <span class="emphasis EMPHASIS c2">if they do get
2843               blocked</span>, rather than HTML pages)</p>
2844             </dd>
2845
2846             <dt>Effect:</dt>
2847
2848             <dd>
2849               <p>This action alone doesn't do anything noticeable. It just
2850               marks URLs as images. If the <tt class="LITERAL"><a href=
2851               "actions-file.html#BLOCK">block</a></tt> action <span class=
2852               "emphasis EMPHASIS c2">also applies</span>, the presence or
2853               absence of this mark decides whether an HTML <span class=
2854               "QUOTE">"blocked"</span> page, or a replacement image (as
2855               determined by the <tt class="LITERAL"><a href=
2856               "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></tt>
2857               action) will be sent to the client as a substitute for the
2858               blocked content.</p>
2859             </dd>
2860
2861             <dt>Type:</dt>
2862
2863             <dd>
2864               <p>Boolean.</p>
2865             </dd>
2866
2867             <dt>Parameter:</dt>
2868
2869             <dd>
2870               <p>N/A</p>
2871             </dd>
2872
2873             <dt>Notes:</dt>
2874
2875             <dd>
2876               <p>The below generic example section is actually part of
2877               <tt class="FILENAME">default.action</tt>. It marks all URLs
2878               with well-known image file name extensions as images and should
2879               be left intact.</p>
2880
2881               <p>Users will probably only want to use the handle-as-image
2882               action in conjunction with <tt class="LITERAL"><a href=
2883               "actions-file.html#BLOCK">block</a></tt>, to block sources of
2884               banners, whose URLs don't reflect the file type, like in the
2885               second example section.</p>
2886
2887               <p>Note that you cannot treat HTML pages as images in most
2888               cases. For instance, (in-line) ad frames require an HTML page
2889               to be sent, or they won't display properly. Forcing <tt class=
2890               "LITERAL">handle-as-image</tt> in this situation will not
2891               replace the ad frame with an image, but lead to error
2892               messages.</p>
2893             </dd>
2894
2895             <dt>Example usage (sections):</dt>
2896
2897             <dd>
2898               <table class="c4" border="0" width="90%">
2899                 <tr>
2900                   <td>
2901                     <pre class="SCREEN">
2902 # Generic image extensions:
2903 #
2904 {+handle-as-image}
2905 /.*\.(gif|jpg|jpeg|png|bmp|ico)$
2906
2907 # These don't look like images, but they're banners and should be
2908 # blocked as images:
2909 #
2910 {+block{Nasty banners.} +handle-as-image}
2911 nasty-banner-server.example.com/junk.cgi\?output=trash
2912 </pre>
2913                   </td>
2914                 </tr>
2915               </table>
2916             </dd>
2917           </dl>
2918         </div>
2919       </div>
2920
2921       <div class="SECT3">
2922         <h4 class="SECT3"><a name="HIDE-ACCEPT-LANGUAGE" id=
2923         "HIDE-ACCEPT-LANGUAGE">8.5.20. hide-accept-language</a></h4>
2924
2925         <div class="VARIABLELIST">
2926           <dl>
2927             <dt>Typical use:</dt>
2928
2929             <dd>
2930               <p>Pretend to use different language settings.</p>
2931             </dd>
2932
2933             <dt>Effect:</dt>
2934
2935             <dd>
2936               <p>Deletes or replaces the <span class=
2937               "QUOTE">"Accept-Language:"</span> HTTP header in client
2938               requests.</p>
2939             </dd>
2940
2941             <dt>Type:</dt>
2942
2943             <dd>
2944               <p>Parameterized.</p>
2945             </dd>
2946
2947             <dt>Parameter:</dt>
2948
2949             <dd>
2950               <p>Keyword: <span class="QUOTE">"block"</span>, or any user
2951               defined value.</p>
2952             </dd>
2953
2954             <dt>Notes:</dt>
2955
2956             <dd>
2957               <p>Faking the browser's language settings can be useful to make
2958               a foreign User-Agent set with <tt class="LITERAL"><a href=
2959               "actions-file.html#HIDE-USER-AGENT">hide-user-agent</a></tt>
2960               more believable.</p>
2961
2962               <p>However some sites with content in different languages check
2963               the <span class="QUOTE">"Accept-Language:"</span> to decide
2964               which one to take by default. Sometimes it isn't possible to
2965               later switch to another language without changing the
2966               <span class="QUOTE">"Accept-Language:"</span> header first.</p>
2967
2968               <p>Therefore it's a good idea to either only change the
2969               <span class="QUOTE">"Accept-Language:"</span> header to
2970               languages you understand, or to languages that aren't wide
2971               spread.</p>
2972
2973               <p>Before setting the <span class=
2974               "QUOTE">"Accept-Language:"</span> header to a rare language,
2975               you should consider that it helps to make your requests unique
2976               and thus easier to trace. If you don't plan to change this
2977               header frequently, you should stick to a common language.</p>
2978             </dd>
2979
2980             <dt>Example usage (section):</dt>
2981
2982             <dd>
2983               <table class="c4" border="0" width="90%">
2984                 <tr>
2985                   <td>
2986                     <pre class="SCREEN">
2987 # Pretend to use Canadian language settings.
2988 {+hide-accept-language{en-ca} \
2989 +hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \
2990 }
2991 /
2992 </pre>
2993                   </td>
2994                 </tr>
2995               </table>
2996             </dd>
2997           </dl>
2998         </div>
2999       </div>
3000
3001       <div class="SECT3">
3002         <h4 class="SECT3"><a name="HIDE-CONTENT-DISPOSITION" id=
3003         "HIDE-CONTENT-DISPOSITION">8.5.21. hide-content-disposition</a></h4>
3004
3005         <div class="VARIABLELIST">
3006           <dl>
3007             <dt>Typical use:</dt>
3008
3009             <dd>
3010               <p>Prevent download menus for content you prefer to view inside
3011               the browser.</p>
3012             </dd>
3013
3014             <dt>Effect:</dt>
3015
3016             <dd>
3017               <p>Deletes or replaces the <span class=
3018               "QUOTE">"Content-Disposition:"</span> HTTP header set by some
3019               servers.</p>
3020             </dd>
3021
3022             <dt>Type:</dt>
3023
3024             <dd>
3025               <p>Parameterized.</p>
3026             </dd>
3027
3028             <dt>Parameter:</dt>
3029
3030             <dd>
3031               <p>Keyword: <span class="QUOTE">"block"</span>, or any user
3032               defined value.</p>
3033             </dd>
3034
3035             <dt>Notes:</dt>
3036
3037             <dd>
3038               <p>Some servers set the <span class=
3039               "QUOTE">"Content-Disposition:"</span> HTTP header for documents
3040               they assume you want to save locally before viewing them. The
3041               <span class="QUOTE">"Content-Disposition:"</span> header
3042               contains the file name the browser is supposed to use by
3043               default.</p>
3044
3045               <p>In most browsers that understand this header, it makes it
3046               impossible to <span class="emphasis EMPHASIS c2">just
3047               view</span> the document, without downloading it first, even if
3048               it's just a simple text file or an image.</p>
3049
3050               <p>Removing the <span class=
3051               "QUOTE">"Content-Disposition:"</span> header helps to prevent
3052               this annoyance, but some browsers additionally check the
3053               <span class="QUOTE">"Content-Type:"</span> header, before they
3054               decide if they can display a document without saving it first.
3055               In these cases, you have to change this header as well, before
3056               the browser stops displaying download menus.</p>
3057
3058               <p>It is also possible to change the server's file name
3059               suggestion to another one, but in most cases it isn't worth the
3060               time to set it up.</p>
3061
3062               <p>This action will probably be removed in the future, use
3063               server-header filters instead.</p>
3064             </dd>
3065
3066             <dt>Example usage:</dt>
3067
3068             <dd>
3069               <table class="c4" border="0" width="90%">
3070                 <tr>
3071                   <td>
3072                     <pre class="SCREEN">
3073 # Disarm the download link in Sourceforge's patch tracker
3074 { -filter \
3075  +content-type-overwrite{text/plain}\
3076  +hide-content-disposition{block} }
3077  .sourceforge.net/tracker/download\.php
3078 </pre>
3079                   </td>
3080                 </tr>
3081               </table>
3082             </dd>
3083           </dl>
3084         </div>
3085       </div>
3086
3087       <div class="SECT3">
3088         <h4 class="SECT3"><a name="HIDE-IF-MODIFIED-SINCE" id=
3089         "HIDE-IF-MODIFIED-SINCE">8.5.22. hide-if-modified-since</a></h4>
3090
3091         <div class="VARIABLELIST">
3092           <dl>
3093             <dt>Typical use:</dt>
3094
3095             <dd>
3096               <p>Prevent yet another way to track the user's steps between
3097               sessions.</p>
3098             </dd>
3099
3100             <dt>Effect:</dt>
3101
3102             <dd>
3103               <p>Deletes the <span class="QUOTE">"If-Modified-Since:"</span>
3104               HTTP client header or modifies its value.</p>
3105             </dd>
3106
3107             <dt>Type:</dt>
3108
3109             <dd>
3110               <p>Parameterized.</p>
3111             </dd>
3112
3113             <dt>Parameter:</dt>
3114
3115             <dd>
3116               <p>Keyword: <span class="QUOTE">"block"</span>, or a user
3117               defined value that specifies a range of hours.</p>
3118             </dd>
3119
3120             <dt>Notes:</dt>
3121
3122             <dd>
3123               <p>Removing this header is useful for filter testing, where you
3124               want to force a real reload instead of getting status code
3125               <span class="QUOTE">"304"</span>, which would cause the browser
3126               to use a cached copy of the page.</p>
3127
3128               <p>Instead of removing the header, <tt class=
3129               "LITERAL">hide-if-modified-since</tt> can also add or subtract
3130               a random amount of time to/from the header's value. You specify
3131               a range of minutes where the random factor should be chosen
3132               from and <span class="APPLICATION">Privoxy</span> does the
3133               rest. A negative value means subtracting, a positive value
3134               adding.</p>
3135
3136               <p>Randomizing the value of the <span class=
3137               "QUOTE">"If-Modified-Since:"</span> makes it less likely that
3138               the server can use the time as a cookie replacement, but you
3139               will run into caching problems if the random range is too
3140               high.</p>
3141
3142               <p>It is a good idea to only use a small negative value and let
3143               <tt class="LITERAL"><a href=
3144               "actions-file.html#OVERWRITE-LAST-MODIFIED">overwrite-last-modified</a></tt>
3145               handle the greater changes.</p>
3146
3147               <p>It is also recommended to use this action together with
3148               <tt class="LITERAL"><a href=
3149               "actions-file.html#CRUNCH-IF-NONE-MATCH">crunch-if-none-match</a></tt>,
3150               otherwise it's more or less pointless.</p>
3151             </dd>
3152
3153             <dt>Example usage (section):</dt>
3154
3155             <dd>
3156               <table class="c4" border="0" width="90%">
3157                 <tr>
3158                   <td>
3159                     <pre class="SCREEN">
3160 # Let the browser revalidate but make tracking based on the time less likely.
3161 {+hide-if-modified-since{-60} \
3162  +overwrite-last-modified{randomize} \
3163  +crunch-if-none-match}
3164 /
3165 </pre>
3166                   </td>
3167                 </tr>
3168               </table>
3169             </dd>
3170           </dl>
3171         </div>
3172       </div>
3173
3174       <div class="SECT3">
3175         <h4 class="SECT3"><a name="HIDE-FROM-HEADER" id=
3176         "HIDE-FROM-HEADER">8.5.23. hide-from-header</a></h4>
3177
3178         <div class="VARIABLELIST">
3179           <dl>
3180             <dt>Typical use:</dt>
3181
3182             <dd>
3183               <p>Keep your (old and ill) browser from telling web servers
3184               your email address</p>
3185             </dd>
3186
3187             <dt>Effect:</dt>
3188
3189             <dd>
3190               <p>Deletes any existing <span class="QUOTE">"From:"</span> HTTP
3191               header, or replaces it with the specified string.</p>
3192             </dd>
3193
3194             <dt>Type:</dt>
3195
3196             <dd>
3197               <p>Parameterized.</p>
3198             </dd>
3199
3200             <dt>Parameter:</dt>
3201
3202             <dd>
3203               <p>Keyword: <span class="QUOTE">"block"</span>, or any user
3204               defined value.</p>
3205             </dd>
3206
3207             <dt>Notes:</dt>
3208
3209             <dd>
3210               <p>The keyword <span class="QUOTE">"block"</span> will
3211               completely remove the header (not to be confused with the
3212               <tt class="LITERAL"><a href=
3213               "actions-file.html#BLOCK">block</a></tt> action).</p>
3214
3215               <p>Alternately, you can specify any value you prefer to be sent
3216               to the web server. If you do, it is a matter of fairness not to
3217               use any address that is actually used by a real person.</p>
3218
3219               <p>This action is rarely needed, as modern web browsers don't
3220               send <span class="QUOTE">"From:"</span> headers anymore.</p>
3221             </dd>
3222
3223             <dt>Example usage:</dt>
3224
3225             <dd>
3226               <table class="c4" border="0" width="90%">
3227                 <tr>
3228                   <td>
3229                     <pre class="SCREEN">
3230 +hide-from-header{block}
3231 </pre>
3232                   </td>
3233                 </tr>
3234               </table>or
3235
3236               <table class="c4" border="0" width="90%">
3237                 <tr>
3238                   <td>
3239                     <pre class="SCREEN">
3240 +hide-from-header{spam-me-senseless@sittingduck.example.com}
3241 </pre>
3242                   </td>
3243                 </tr>
3244               </table>
3245             </dd>
3246           </dl>
3247         </div>
3248       </div>
3249
3250       <div class="SECT3">
3251         <h4 class="SECT3"><a name="HIDE-REFERRER" id="HIDE-REFERRER">8.5.24.
3252         hide-referrer</a></h4><a name="HIDE-REFERER" id="HIDE-REFERER"></a>
3253
3254         <div class="VARIABLELIST">
3255           <dl>
3256             <dt>Typical use:</dt>
3257
3258             <dd>
3259               <p>Conceal which link you followed to get to a particular
3260               site</p>
3261             </dd>
3262
3263             <dt>Effect:</dt>
3264
3265             <dd>
3266               <p>Deletes the <span class="QUOTE">"Referer:"</span> (sic) HTTP
3267               header from the client request, or replaces it with a forged
3268               one.</p>
3269             </dd>
3270
3271             <dt>Type:</dt>
3272
3273             <dd>
3274               <p>Parameterized.</p>
3275             </dd>
3276
3277             <dt>Parameter:</dt>
3278
3279             <dd>
3280               <ul>
3281                 <li>
3282                   <p><span class="QUOTE">"conditional-block"</span> to delete
3283                   the header completely if the host has changed.</p>
3284                 </li>
3285
3286                 <li>
3287                   <p><span class="QUOTE">"conditional-forge"</span> to forge
3288                   the header if the host has changed.</p>
3289                 </li>
3290
3291                 <li>
3292                   <p><span class="QUOTE">"block"</span> to delete the header
3293                   unconditionally.</p>
3294                 </li>
3295
3296                 <li>
3297                   <p><span class="QUOTE">"forge"</span> to pretend to be
3298                   coming from the homepage of the server we are talking
3299                   to.</p>
3300                 </li>
3301
3302                 <li>
3303                   <p>Any other string to set a user defined referrer.</p>
3304                 </li>
3305               </ul>
3306             </dd>
3307
3308             <dt>Notes:</dt>
3309
3310             <dd>
3311               <p><tt class="LITERAL">conditional-block</tt> is the only
3312               parameter, that isn't easily detected in the server's log file.
3313               If it blocks the referrer, the request will look like the
3314               visitor used a bookmark or typed in the address directly.</p>
3315
3316               <p>Leaving the referrer unmodified for requests on the same
3317               host allows the server owner to see the visitor's <span class=
3318               "QUOTE">"click path"</span>, but in most cases she could also
3319               get that information by comparing other parts of the log file:
3320               for example the User-Agent if it isn't a very common one, or
3321               the user's IP address if it doesn't change between different
3322               requests.</p>
3323
3324               <p>Always blocking the referrer, or using a custom one, can
3325               lead to failures on servers that check the referrer before they
3326               answer any requests, in an attempt to prevent their content
3327               from being embedded or linked to elsewhere.</p>
3328
3329               <p>Both <tt class="LITERAL">conditional-block</tt> and
3330               <tt class="LITERAL">forge</tt> will work with referrer checks,
3331               as long as content and valid referring page are on the same
3332               host. Most of the time that's the case.</p>
3333
3334               <p><tt class="LITERAL">hide-referer</tt> is an alternate
3335               spelling of <tt class="LITERAL">hide-referrer</tt> and the two
3336               can be can be freely substituted with each other. (<span class=
3337               "QUOTE">"referrer"</span> is the correct English spelling,
3338               however the HTTP specification has a bug - it requires it to be
3339               spelled as <span class="QUOTE">"referer"</span>.)</p>
3340             </dd>
3341
3342             <dt>Example usage:</dt>
3343
3344             <dd>
3345               <table class="c4" border="0" width="90%">
3346                 <tr>
3347                   <td>
3348                     <pre class="SCREEN">
3349 +hide-referrer{forge}
3350 </pre>
3351                   </td>
3352                 </tr>
3353               </table>or
3354
3355               <table class="c4" border="0" width="90%">
3356                 <tr>
3357                   <td>
3358                     <pre class="SCREEN">
3359 +hide-referrer{http://www.yahoo.com/}
3360 </pre>
3361                   </td>
3362                 </tr>
3363               </table>
3364             </dd>
3365           </dl>
3366         </div>
3367       </div>
3368
3369       <div class="SECT3">
3370         <h4 class="SECT3"><a name="HIDE-USER-AGENT" id=
3371         "HIDE-USER-AGENT">8.5.25. hide-user-agent</a></h4>
3372
3373         <div class="VARIABLELIST">
3374           <dl>
3375             <dt>Typical use:</dt>
3376
3377             <dd>
3378               <p>Try to conceal your type of browser and client operating
3379               system</p>
3380             </dd>
3381
3382             <dt>Effect:</dt>
3383
3384             <dd>
3385               <p>Replaces the value of the <span class=
3386               "QUOTE">"User-Agent:"</span> HTTP header in client requests
3387               with the specified value.</p>
3388             </dd>
3389
3390             <dt>Type:</dt>
3391
3392             <dd>
3393               <p>Parameterized.</p>
3394             </dd>
3395
3396             <dt>Parameter:</dt>
3397
3398             <dd>
3399               <p>Any user-defined string.</p>
3400             </dd>
3401
3402             <dt>Notes:</dt>
3403
3404             <dd>
3405               <div class="WARNING">
3406                 <table class="WARNING" border="1" width="90%">
3407                   <tr>
3408                     <td class="c6" align="center">Warning</td>
3409                   </tr>
3410
3411                   <tr>
3412                     <td align="left">
3413                       <p>This can lead to problems on web sites that depend
3414                       on looking at this header in order to customize their
3415                       content for different browsers (which, by the way, is
3416                       <span class="emphasis EMPHASIS c2">NOT</span> the right
3417                       thing to do: good web sites work
3418                       browser-independently).</p>
3419                     </td>
3420                   </tr>
3421                 </table>
3422               </div>
3423
3424               <p>Using this action in multi-user setups or wherever different
3425               types of browsers will access the same <span class=
3426               "APPLICATION">Privoxy</span> is <span class=
3427               "emphasis EMPHASIS c2">not recommended</span>. In single-user,
3428               single-browser setups, you might use it to delete your OS
3429               version information from the headers, because it is an
3430               invitation to exploit known bugs for your OS. It is also
3431               occasionally useful to forge this in order to access sites that
3432               won't let you in otherwise (though there may be a good reason
3433               in some cases).</p>
3434
3435               <p>More information on known user-agent strings can be found at
3436               <a href="http://www.user-agents.org/" target=
3437               "_top">http://www.user-agents.org/</a> and <a href=
3438               "http://en.wikipedia.org/wiki/User_agent" target=
3439               "_top">http://en.wikipedia.org/wiki/User_agent</a>.</p>
3440             </dd>
3441
3442             <dt>Example usage:</dt>
3443
3444             <dd>
3445               <table class="c4" border="0" width="90%">
3446                 <tr>
3447                   <td>
3448                     <pre class="SCREEN">
3449 +hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}
3450 </pre>
3451                   </td>
3452                 </tr>
3453               </table>
3454             </dd>
3455           </dl>
3456         </div>
3457       </div>
3458
3459       <div class="SECT3">
3460         <h4 class="SECT3"><a name="LIMIT-CONNECT" id="LIMIT-CONNECT">8.5.26.
3461         limit-connect</a></h4>
3462
3463         <div class="VARIABLELIST">
3464           <dl>
3465             <dt>Typical use:</dt>
3466
3467             <dd>
3468               <p>Prevent abuse of <span class="APPLICATION">Privoxy</span> as
3469               a TCP proxy relay or disable SSL for untrusted sites</p>
3470             </dd>
3471
3472             <dt>Effect:</dt>
3473
3474             <dd>
3475               <p>Specifies to which ports HTTP CONNECT requests are
3476               allowable.</p>
3477             </dd>
3478
3479             <dt>Type:</dt>
3480
3481             <dd>
3482               <p>Parameterized.</p>
3483             </dd>
3484
3485             <dt>Parameter:</dt>
3486
3487             <dd>
3488               <p>A comma-separated list of ports or port ranges (the latter
3489               using dashes, with the minimum defaulting to 0 and the maximum
3490               to 65K).</p>
3491             </dd>
3492
3493             <dt>Notes:</dt>
3494
3495             <dd>
3496               <p>By default, i.e. if no <tt class=
3497               "LITERAL">limit-connect</tt> action applies, <span class=
3498               "APPLICATION">Privoxy</span> allows HTTP CONNECT requests to
3499               all ports. Use <tt class="LITERAL">limit-connect</tt> if
3500               fine-grained control is desired for some or all
3501               destinations.</p>
3502
3503               <p>The CONNECT methods exists in HTTP to allow access to secure
3504               websites (<span class="QUOTE">"https://"</span> URLs) through
3505               proxies. It works very simply: the proxy connects to the server
3506               on the specified port, and then short-circuits its connections
3507               to the client and to the remote server. This means
3508               CONNECT-enabled proxies can be used as TCP relays very
3509               easily.</p>
3510
3511               <p><span class="APPLICATION">Privoxy</span> relays HTTPS
3512               traffic without seeing the decoded content. Websites can
3513               leverage this limitation to circumvent <span class=
3514               "APPLICATION">Privoxy</span>'s filters. By specifying an
3515               invalid port range you can disable HTTPS entirely.</p>
3516             </dd>
3517
3518             <dt>Example usages:</dt>
3519
3520             <dd>
3521               <table class="c4" border="0" width="90%">
3522                 <tr>
3523                   <td>
3524                     <pre class="SCREEN">
3525 +limit-connect{443}                   # Port 443 is OK.
3526 +limit-connect{80,443}                # Ports 80 and 443 are OK.
3527 +limit-connect{-3, 7, 20-100, 500-}   # Ports less than 3, 7, 20 to 100 and above 500 are OK.
3528 +limit-connect{-}                     # All ports are OK
3529 +limit-connect{,}                     # No HTTPS/SSL traffic is allowed
3530 </pre>
3531                   </td>
3532                 </tr>
3533               </table>
3534             </dd>
3535           </dl>
3536         </div>
3537       </div>
3538
3539       <div class="SECT3">
3540         <h4 class="SECT3"><a name="PREVENT-COMPRESSION" id=
3541         "PREVENT-COMPRESSION">8.5.27. prevent-compression</a></h4>
3542
3543         <div class="VARIABLELIST">
3544           <dl>
3545             <dt>Typical use:</dt>
3546
3547             <dd>
3548               <p>Ensure that servers send the content uncompressed, so it can
3549               be passed through <tt class="LITERAL"><a href=
3550               "actions-file.html#FILTER">filter</a></tt>s.</p>
3551             </dd>
3552
3553             <dt>Effect:</dt>
3554
3555             <dd>
3556               <p>Removes the Accept-Encoding header which can be used to ask
3557               for compressed transfer.</p>
3558             </dd>
3559
3560             <dt>Type:</dt>
3561
3562             <dd>
3563               <p>Boolean.</p>
3564             </dd>
3565
3566             <dt>Parameter:</dt>
3567
3568             <dd>
3569               <p>N/A</p>
3570             </dd>
3571
3572             <dt>Notes:</dt>
3573
3574             <dd>
3575               <p>More and more websites send their content compressed by
3576               default, which is generally a good idea and saves bandwidth.
3577               But the <tt class="LITERAL"><a href=
3578               "actions-file.html#FILTER">filter</a></tt> and <tt class=
3579               "LITERAL"><a href=
3580               "actions-file.html#DEANIMATE-GIFS">deanimate-gifs</a></tt>
3581               actions need access to the uncompressed data.</p>
3582
3583               <p>When compiled with zlib support (available since
3584               <span class="APPLICATION">Privoxy</span> 3.0.7), content that
3585               should be filtered is decompressed on-the-fly and you don't
3586               have to worry about this action. If you are using an older
3587               <span class="APPLICATION">Privoxy</span> version, or one that
3588               hasn't been compiled with zlib support, this action can be used
3589               to convince the server to send the content uncompressed.</p>
3590
3591               <p>Most text-based instances compress very well, the size is
3592               seldom decreased by less than 50%, for markup-heavy instances
3593               like news feeds saving more than 90% of the original size isn't
3594               unusual.</p>
3595
3596               <p>Not using compression will therefore slow down the transfer,
3597               and you should only enable this action if you really need it.
3598               As of <span class="APPLICATION">Privoxy</span> 3.0.7 it's
3599               disabled in all predefined action settings.</p>
3600
3601               <p>Note that some (rare) ill-configured sites don't handle
3602               requests for uncompressed documents correctly. Broken PHP
3603               applications tend to send an empty document body, some IIS
3604               versions only send the beginning of the content. If you enable
3605               <tt class="LITERAL">prevent-compression</tt> per default, you
3606               might want to add exceptions for those sites. See the example
3607               for how to do that.</p>
3608             </dd>
3609
3610             <dt>Example usage (sections):</dt>
3611
3612             <dd>
3613               <table class="c4" border="0" width="90%">
3614                 <tr>
3615                   <td>
3616                     <pre class="SCREEN">
3617 # Selectively turn off compression, and enable a filter
3618 #
3619 { +filter{tiny-textforms} +prevent-compression }
3620 # Match only these sites
3621  .google.
3622  sourceforge.net
3623  sf.net
3624
3625 # Or instead, we could set a universal default:
3626 #
3627 { +prevent-compression }
3628  / # Match all sites
3629
3630 # Then maybe make exceptions for broken sites:
3631 #
3632 { -prevent-compression }
3633 .compusa.com/
3634 </pre>
3635                   </td>
3636                 </tr>
3637               </table>
3638             </dd>
3639           </dl>
3640         </div>
3641       </div>
3642
3643       <div class="SECT3">
3644         <h4 class="SECT3"><a name="OVERWRITE-LAST-MODIFIED" id=
3645         "OVERWRITE-LAST-MODIFIED">8.5.28. overwrite-last-modified</a></h4>
3646
3647         <div class="VARIABLELIST">
3648           <dl>
3649             <dt>Typical use:</dt>
3650
3651             <dd>
3652               <p>Prevent yet another way to track the user's steps between
3653               sessions.</p>
3654             </dd>
3655
3656             <dt>Effect:</dt>
3657
3658             <dd>
3659               <p>Deletes the <span class="QUOTE">"Last-Modified:"</span> HTTP
3660               server header or modifies its value.</p>
3661             </dd>
3662
3663             <dt>Type:</dt>
3664
3665             <dd>
3666               <p>Parameterized.</p>
3667             </dd>
3668
3669             <dt>Parameter:</dt>
3670
3671             <dd>
3672               <p>One of the keywords: <span class="QUOTE">"block"</span>,
3673               <span class="QUOTE">"reset-to-request-time"</span> and
3674               <span class="QUOTE">"randomize"</span></p>
3675             </dd>
3676
3677             <dt>Notes:</dt>
3678
3679             <dd>
3680               <p>Removing the <span class="QUOTE">"Last-Modified:"</span>
3681               header is useful for filter testing, where you want to force a
3682               real reload instead of getting status code <span class=
3683               "QUOTE">"304"</span>, which would cause the browser to reuse
3684               the old version of the page.</p>
3685
3686               <p>The <span class="QUOTE">"randomize"</span> option overwrites
3687               the value of the <span class="QUOTE">"Last-Modified:"</span>
3688               header with a randomly chosen time between the original value
3689               and the current time. In theory the server could send each
3690               document with a different <span class=
3691               "QUOTE">"Last-Modified:"</span> header to track visits without
3692               using cookies. <span class="QUOTE">"Randomize"</span> makes it
3693               impossible and the browser can still revalidate cached
3694               documents.</p>
3695
3696               <p><span class="QUOTE">"reset-to-request-time"</span>
3697               overwrites the value of the <span class=
3698               "QUOTE">"Last-Modified:"</span> header with the current time.
3699               You could use this option together with <tt class=
3700               "LITERAL"><a href=
3701               "actions-file.html#HIDE-IF-MODIFIED-SINCE">hide-if-modified-since</a></tt>
3702               to further customize your random range.</p>
3703
3704               <p>The preferred parameter here is <span class=
3705               "QUOTE">"randomize"</span>. It is safe to use, as long as the
3706               time settings are more or less correct. If the server sets the
3707               <span class="QUOTE">"Last-Modified:"</span> header to the time
3708               of the request, the random range becomes zero and the value
3709               stays the same. Therefore you should later randomize it a
3710               second time with <tt class="LITERAL"><a href=
3711               "actions-file.html#HIDE-IF-MODIFIED-SINCE">hided-if-modified-since</a></tt>,
3712               just to be sure.</p>
3713
3714               <p>It is also recommended to use this action together with
3715               <tt class="LITERAL"><a href=
3716               "actions-file.html#CRUNCH-IF-NONE-MATCH">crunch-if-none-match</a></tt>.</p>
3717             </dd>
3718
3719             <dt>Example usage:</dt>
3720
3721             <dd>
3722               <table class="c4" border="0" width="90%">
3723                 <tr>
3724                   <td>
3725                     <pre class="SCREEN">
3726 # Let the browser revalidate without being tracked across sessions
3727 { +hide-if-modified-since{-60} \
3728  +overwrite-last-modified{randomize} \
3729  +crunch-if-none-match}
3730 /
3731 </pre>
3732                   </td>
3733                 </tr>
3734               </table>
3735             </dd>
3736           </dl>
3737         </div>
3738       </div>
3739
3740       <div class="SECT3">
3741         <h4 class="SECT3"><a name="REDIRECT" id="REDIRECT">8.5.29.
3742         redirect</a></h4>
3743
3744         <div class="VARIABLELIST">
3745           <dl>
3746             <dt>Typical use:</dt>
3747
3748             <dd>
3749               <p>Redirect requests to other sites.</p>
3750             </dd>
3751
3752             <dt>Effect:</dt>
3753
3754             <dd>
3755               <p>Convinces the browser that the requested document has been
3756               moved to another location and the browser should get it from
3757               there.</p>
3758             </dd>
3759
3760             <dt>Type:</dt>
3761
3762             <dd>
3763               <p>Parameterized</p>
3764             </dd>
3765
3766             <dt>Parameter:</dt>
3767
3768             <dd>
3769               <p>An absolute URL or a single pcrs command.</p>
3770             </dd>
3771
3772             <dt>Notes:</dt>
3773
3774             <dd>
3775               <p>Requests to which this action applies are answered with a
3776               HTTP redirect to URLs of your choosing. The new URL is either
3777               provided as parameter, or derived by applying a single pcrs
3778               command to the original URL.</p>
3779
3780               <p>This action will be ignored if you use it together with
3781               <tt class="LITERAL"><a href=
3782               "actions-file.html#BLOCK">block</a></tt>. It can be combined
3783               with <tt class="LITERAL"><a href=
3784               "actions-file.html#FAST-REDIRECTS">fast-redirects{check-decoded-url}</a></tt>
3785               to redirect to a decoded version of a rewritten URL.</p>
3786
3787               <p>Use this action carefully, make sure not to create
3788               redirection loops and be aware that using your own redirects
3789               might make it possible to fingerprint your requests.</p>
3790
3791               <p>In case of problems with your redirects, or simply to watch
3792               them working, enable <a href="config.html#DEBUG">debug
3793               128</a>.</p>
3794             </dd>
3795
3796             <dt>Example usages:</dt>
3797
3798             <dd>
3799               <table class="c4" border="0" width="90%">
3800                 <tr>
3801                   <td>
3802                     <pre class="SCREEN">
3803 # Replace example.com's style sheet with another one
3804 { +redirect{http://localhost/css-replacements/example.com.css} }
3805  example.com/stylesheet\.css
3806
3807 # Create a short, easy to remember nickname for a favorite site
3808 # (relies on the browser accept and forward invalid URLs to <span class=
3809 "APPLICATION">Privoxy</span>)
3810 { +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
3811  a
3812
3813 # Always use the expanded view for Undeadly.org articles
3814 # (Note the $ at the end of the URL pattern to make sure
3815 # the request for the rewritten URL isn't redirected as well)
3816 {+redirect{s@$@&amp;mode=expanded@}}
3817 undeadly.org/cgi\?action=article&amp;sid=\d*$
3818
3819 # Redirect Google search requests to MSN
3820 {+redirect{s@^http://[^/]*/search\?q=([^&amp;]*).*@http://search.msn.com/results.aspx?q=$1@}}
3821 .google.com/search
3822
3823 # Redirect MSN search requests to Yahoo
3824 {+redirect{s@^http://[^/]*/results\.aspx\?q=([^&amp;]*).*@http://search.yahoo.com/search?p=$1@}}
3825 search.msn.com//results\.aspx\?q=
3826
3827 # Redirect remote requests for this manual
3828 # to the local version delivered by Privoxy
3829 {+redirect{s@^http://www@http://config@}}
3830 www.privoxy.org/user-manual/
3831 </pre>
3832                   </td>
3833                 </tr>
3834               </table>
3835             </dd>
3836           </dl>
3837         </div>
3838       </div>
3839
3840       <div class="SECT3">
3841         <h4 class="SECT3"><a name="SERVER-HEADER-FILTER" id=
3842         "SERVER-HEADER-FILTER">8.5.30. server-header-filter</a></h4>
3843
3844         <div class="VARIABLELIST">
3845           <dl>
3846             <dt>Typical use:</dt>
3847
3848             <dd>
3849               <p>Rewrite or remove single server headers.</p>
3850             </dd>
3851
3852             <dt>Effect:</dt>
3853
3854             <dd>
3855               <p>All server headers to which this action applies are filtered
3856               on-the-fly through the specified regular expression based
3857               substitutions.</p>
3858             </dd>
3859
3860             <dt>Type:</dt>
3861
3862             <dd>
3863               <p>Parameterized.</p>
3864             </dd>
3865
3866             <dt>Parameter:</dt>
3867
3868             <dd>
3869               <p>The name of a server-header filter, as defined in one of the
3870               <a href="filter-file.html">filter files</a>.</p>
3871             </dd>
3872
3873             <dt>Notes:</dt>
3874
3875             <dd>
3876               <p>Server-header filters are applied to each header on its own,
3877               not to all at once. This makes it easier to diagnose problems,
3878               but on the downside you can't write filters that only change
3879               header x if header y's value is z. You can do that by using
3880               tags though.</p>
3881
3882               <p>Server-header filters are executed after the other header
3883               actions have finished and use their output as input.</p>
3884
3885               <p>Please refer to the <a href="filter-file.html">filter file
3886               chapter</a> to learn which server-header filters are available
3887               by default, and how to create your own.</p>
3888             </dd>
3889
3890             <dt>Example usage (section):</dt>
3891
3892             <dd>
3893               <table class="c4" border="0" width="90%">
3894                 <tr>
3895                   <td>
3896                     <pre class="SCREEN">
3897 {+server-header-filter{html-to-xml}}
3898 example.org/xml-instance-that-is-delivered-as-html
3899
3900 {+server-header-filter{xml-to-html}}
3901 example.org/instance-that-is-delivered-as-xml-but-is-not
3902
3903 </pre>
3904                   </td>
3905                 </tr>
3906               </table>
3907             </dd>
3908           </dl>
3909         </div>
3910       </div>
3911
3912       <div class="SECT3">
3913         <h4 class="SECT3"><a name="SERVER-HEADER-TAGGER" id=
3914         "SERVER-HEADER-TAGGER">8.5.31. server-header-tagger</a></h4>
3915
3916         <div class="VARIABLELIST">
3917           <dl>
3918             <dt>Typical use:</dt>
3919
3920             <dd>
3921               <p>Enable or disable filters based on the Content-Type
3922               header.</p>
3923             </dd>
3924
3925             <dt>Effect:</dt>
3926
3927             <dd>
3928               <p>Server headers to which this action applies are filtered
3929               on-the-fly through the specified regular expression based
3930               substitutions, the result is used as tag.</p>
3931             </dd>
3932
3933             <dt>Type:</dt>
3934
3935             <dd>
3936               <p>Parameterized.</p>
3937             </dd>
3938
3939             <dt>Parameter:</dt>
3940
3941             <dd>
3942               <p>The name of a server-header tagger, as defined in one of the
3943               <a href="filter-file.html">filter files</a>.</p>
3944             </dd>
3945
3946             <dt>Notes:</dt>
3947
3948             <dd>
3949               <p>Server-header taggers are applied to each header on its own,
3950               and as the header isn't modified, each tagger <span class=
3951               "QUOTE">"sees"</span> the original.</p>
3952
3953               <p>Server-header taggers are executed before all other header
3954               actions that modify server headers. Their tags can be used to
3955               control all of the other server-header actions, the content
3956               filters and the crunch actions (<a href=
3957               "actions-file.html#REDIRECT">redirect</a> and <a href=
3958               "actions-file.html#BLOCK">block</a>).</p>
3959
3960               <p>Obviously crunching based on tags created by server-header
3961               taggers doesn't prevent the request from showing up in the
3962               server's log file.</p>
3963             </dd>
3964
3965             <dt>Example usage (section):</dt>
3966
3967             <dd>
3968               <table class="c4" border="0" width="90%">
3969                 <tr>
3970                   <td>
3971                     <pre class="SCREEN">
3972 # Tag every request with the content type declared by the server
3973 {+server-header-tagger{content-type}}
3974 /
3975
3976 </pre>
3977                   </td>
3978                 </tr>
3979               </table>
3980             </dd>
3981           </dl>
3982         </div>
3983       </div>
3984
3985       <div class="SECT3">
3986         <h4 class="SECT3"><a name="SESSION-COOKIES-ONLY" id=
3987         "SESSION-COOKIES-ONLY">8.5.32. session-cookies-only</a></h4>
3988
3989         <div class="VARIABLELIST">
3990           <dl>
3991             <dt>Typical use:</dt>
3992
3993             <dd>
3994               <p>Allow only temporary <span class="QUOTE">"session"</span>
3995               cookies (for the current browser session <span class=
3996               "emphasis EMPHASIS c2">only</span>).</p>
3997             </dd>
3998
3999             <dt>Effect:</dt>
4000
4001             <dd>
4002               <p>Deletes the <span class="QUOTE">"expires"</span> field from
4003               <span class="QUOTE">"Set-Cookie:"</span> server headers. Most
4004               browsers will not store such cookies permanently and forget
4005               them in between sessions.</p>
4006             </dd>
4007
4008             <dt>Type:</dt>
4009
4010             <dd>
4011               <p>Boolean.</p>
4012             </dd>
4013
4014             <dt>Parameter:</dt>
4015
4016             <dd>
4017               <p>N/A</p>
4018             </dd>
4019
4020             <dt>Notes:</dt>
4021
4022             <dd>
4023               <p>This is less strict than <tt class="LITERAL"><a href=
4024               "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a></tt>
4025               / <tt class="LITERAL"><a href=
4026               "actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a></tt>
4027               and allows you to browse websites that insist or rely on
4028               setting cookies, without compromising your privacy too
4029               badly.</p>
4030
4031               <p>Most browsers will not permanently store cookies that have
4032               been processed by <tt class="LITERAL">session-cookies-only</tt>
4033               and will forget about them between sessions. This makes
4034               profiling cookies useless, but won't break sites which require
4035               cookies so that you can log in for transactions. This is
4036               generally turned on for all sites, and is the recommended
4037               setting.</p>
4038
4039               <p>It makes <span class="emphasis EMPHASIS c2">no sense at
4040               all</span> to use <tt class="LITERAL">session-cookies-only</tt>
4041               together with <tt class="LITERAL"><a href=
4042               "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a></tt>
4043               or <tt class="LITERAL"><a href=
4044               "actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a></tt>.
4045               If you do, cookies will be plainly killed.</p>
4046
4047               <p>Note that it is up to the browser how it handles such
4048               cookies without an <span class="QUOTE">"expires"</span> field.
4049               If you use an exotic browser, you might want to try it out to
4050               be sure.</p>
4051
4052               <p>This setting also has no effect on cookies that may have
4053               been stored previously by the browser before starting
4054               <span class="APPLICATION">Privoxy</span>. These would have to
4055               be removed manually.</p>
4056
4057               <p><span class="APPLICATION">Privoxy</span> also uses the
4058               <a href=
4059               "actions-file.html#FILTER-CONTENT-COOKIES">content-cookies
4060               filter</a> to block some types of cookies. Content cookies are
4061               not effected by <tt class=
4062               "LITERAL">session-cookies-only</tt>.</p>
4063             </dd>
4064
4065             <dt>Example usage:</dt>
4066
4067             <dd>
4068               <table class="c4" border="0" width="90%">
4069                 <tr>
4070                   <td>
4071                     <pre class="SCREEN">
4072 +session-cookies-only
4073 </pre>
4074                   </td>
4075                 </tr>
4076               </table>
4077             </dd>
4078           </dl>
4079         </div>
4080       </div>
4081
4082       <div class="SECT3">
4083         <h4 class="SECT3"><a name="SET-IMAGE-BLOCKER" id=
4084         "SET-IMAGE-BLOCKER">8.5.33. set-image-blocker</a></h4>
4085
4086         <div class="VARIABLELIST">
4087           <dl>
4088             <dt>Typical use:</dt>
4089
4090             <dd>
4091               <p>Choose the replacement for blocked images</p>
4092             </dd>
4093
4094             <dt>Effect:</dt>
4095
4096             <dd>
4097               <p>This action alone doesn't do anything noticeable. If
4098               <span class="emphasis EMPHASIS c2">both</span> <tt class=
4099               "LITERAL"><a href="actions-file.html#BLOCK">block</a></tt>
4100               <span class="emphasis EMPHASIS c2">and</span> <tt class=
4101               "LITERAL"><a href=
4102               "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt>
4103               <span class="emphasis EMPHASIS c2">also</span> apply, i.e. if
4104               the request is to be blocked as an image, <span class=
4105               "emphasis EMPHASIS c2">then</span> the parameter of this action
4106               decides what will be sent as a replacement.</p>
4107             </dd>
4108
4109             <dt>Type:</dt>
4110
4111             <dd>
4112               <p>Parameterized.</p>
4113             </dd>
4114
4115             <dt>Parameter:</dt>
4116
4117             <dd>
4118               <ul>
4119                 <li>
4120                   <p><span class="QUOTE">"pattern"</span> to send a built-in
4121                   checkerboard pattern image. The image is visually decent,
4122                   scales very well, and makes it obvious where banners were
4123                   busted.</p>
4124                 </li>
4125
4126                 <li>
4127                   <p><span class="QUOTE">"blank"</span> to send a built-in
4128                   transparent image. This makes banners disappear completely,
4129                   but makes it hard to detect where <span class=
4130                   "APPLICATION">Privoxy</span> has blocked images on a given
4131                   page and complicates troubleshooting if <span class=
4132                   "APPLICATION">Privoxy</span> has blocked innocent images,
4133                   like navigation icons.</p>
4134                 </li>
4135
4136                 <li>
4137                   <p><span class="QUOTE">"<tt class=
4138                   "REPLACEABLE c5">target-url</tt>"</span> to send a redirect
4139                   to <tt class="REPLACEABLE c5">target-url</tt>. You can
4140                   redirect to any image anywhere, even in your local
4141                   filesystem via <span class="QUOTE">"file:///"</span> URL.
4142                   (But note that not all browsers support redirecting to a
4143                   local file system).</p>
4144
4145                   <p>A good application of redirects is to use special
4146                   <span class="APPLICATION">Privoxy</span>-built-in URLs,
4147                   which send the built-in images, as <tt class=
4148                   "REPLACEABLE c5">target-url</tt>. This has the same visual
4149                   effect as specifying <span class="QUOTE">"blank"</span> or
4150                   <span class="QUOTE">"pattern"</span> in the first place,
4151                   but enables your browser to cache the replacement image,
4152                   instead of requesting it over and over again.</p>
4153                 </li>
4154               </ul>
4155             </dd>
4156
4157             <dt>Notes:</dt>
4158
4159             <dd>
4160               <p>The URLs for the built-in images are <span class=
4161               "QUOTE">"http://config.privoxy.org/send-banner?type=<tt class=
4162               "REPLACEABLE c5">type</tt>"</span>, where <tt class=
4163               "REPLACEABLE c5">type</tt> is either <span class=
4164               "QUOTE">"blank"</span> or <span class=
4165               "QUOTE">"pattern"</span>.</p>
4166
4167               <p>There is a third (advanced) type, called <span class=
4168               "QUOTE">"auto"</span>. It is <span class=
4169               "emphasis EMPHASIS c2">NOT</span> to be used in <tt class=
4170               "LITERAL">set-image-blocker</tt>, but meant for use from
4171               <a href="filter-file.html">filters</a>. Auto will select the
4172               type of image that would have applied to the referring page,
4173               had it been an image.</p>
4174             </dd>
4175
4176             <dt>Example usage:</dt>
4177
4178             <dd>
4179               <p>Built-in pattern:</p>
4180
4181               <table class="c4" border="0" width="90%">
4182                 <tr>
4183                   <td>
4184                     <pre class="SCREEN">
4185 +set-image-blocker{pattern}
4186 </pre>
4187                   </td>
4188                 </tr>
4189               </table>
4190
4191               <p>Redirect to the BSD daemon:</p>
4192
4193               <table class="c4" border="0" width="90%">
4194                 <tr>
4195                   <td>
4196                     <pre class="SCREEN">
4197 +set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}
4198 </pre>
4199                   </td>
4200                 </tr>
4201               </table>
4202
4203               <p>Redirect to the built-in pattern for better caching:</p>
4204
4205               <table class="c4" border="0" width="90%">
4206                 <tr>
4207                   <td>
4208                     <pre class="SCREEN">
4209 +set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}
4210 </pre>
4211                   </td>
4212                 </tr>
4213               </table>
4214             </dd>
4215           </dl>
4216         </div>
4217       </div>
4218
4219       <div class="SECT3">
4220         <h3 class="SECT3"><a name="AEN4687" id="AEN4687">8.5.34.
4221         Summary</a></h3>
4222
4223         <p>Note that many of these actions have the potential to cause a page
4224         to misbehave, possibly even not to display at all. There are many
4225         ways a site designer may choose to design his site, and what HTTP
4226         header content, and other criteria, he may depend on. There is no way
4227         to have hard and fast rules for all sites. See the <a href=
4228         "appendix.html#ACTIONSANAT">Appendix</a> for a brief example on
4229         troubleshooting actions.</p>
4230       </div>
4231     </div>
4232
4233     <div class="SECT2">
4234       <h2 class="SECT2"><a name="ALIASES" id="ALIASES">8.6. Aliases</a></h2>
4235
4236       <p>Custom <span class="QUOTE">"actions"</span>, known to <span class=
4237       "APPLICATION">Privoxy</span> as <span class="QUOTE">"aliases"</span>,
4238       can be defined by combining other actions. These can in turn be invoked
4239       just like the built-in actions. Currently, an alias name can contain
4240       any character except space, tab, <span class="QUOTE">"="</span>,
4241       <span class="QUOTE">"{"</span> and <span class="QUOTE">"}"</span>, but
4242       we <span class="emphasis EMPHASIS c2">strongly recommend</span> that
4243       you only use <span class="QUOTE">"a"</span> to <span class=
4244       "QUOTE">"z"</span>, <span class="QUOTE">"0"</span> to <span class=
4245       "QUOTE">"9"</span>, <span class="QUOTE">"+"</span>, and <span class=
4246       "QUOTE">"-"</span>. Alias names are not case sensitive, and are not
4247       required to start with a <span class="QUOTE">"+"</span> or <span class=
4248       "QUOTE">"-"</span> sign, since they are merely textually expanded.</p>
4249
4250       <p>Aliases can be used throughout the actions file, but they
4251       <span class="emphasis EMPHASIS c2">must be defined in a special section
4252       at the top of the file!</span> And there can only be one such section
4253       per actions file. Each actions file may have its own alias section, and
4254       the aliases defined in it are only visible within that file.</p>
4255
4256       <p>There are two main reasons to use aliases: One is to save typing for
4257       frequently used combinations of actions, the other one is a gain in
4258       flexibility: If you decide once how you want to handle shops by
4259       defining an alias called <span class="QUOTE">"shop"</span>, you can
4260       later change your policy on shops in <span class=
4261       "emphasis EMPHASIS c2">one</span> place, and your changes will take
4262       effect everywhere in the actions file where the <span class=
4263       "QUOTE">"shop"</span> alias is used. Calling aliases by their purpose
4264       also makes your actions files more readable.</p>
4265
4266       <p>Currently, there is one big drawback to using aliases, though:
4267       <span class="APPLICATION">Privoxy</span>'s built-in web-based action
4268       file editor honors aliases when reading the actions files, but it
4269       expands them before writing. So the effects of your aliases are of
4270       course preserved, but the aliases themselves are lost when you edit
4271       sections that use aliases with it.</p>
4272
4273       <p>Now let's define some aliases...</p>
4274
4275       <table class="c4" border="0" width="100%">
4276         <tr>
4277           <td>
4278             <pre class="SCREEN">
4279  # Useful custom aliases we can use later.
4280  #
4281  # Note the (required!) section header line and that this section
4282  # must be at the top of the actions file!
4283  #
4284  {{alias}}
4285
4286  # These aliases just save typing later:
4287  # (Note that some already use other aliases!)
4288  #
4289  +crunch-all-cookies = +<a href=
4290 "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a> +<a href="actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a>
4291  -crunch-all-cookies = -<a href=
4292 "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a> -<a href="actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a>
4293  +block-as-image      = +block{Blocked image.} +handle-as-image
4294  allow-all-cookies   = -crunch-all-cookies -<a href=
4295 "actions-file.html#SESSION-COOKIES-ONLY">session-cookies-only</a> -<a href=
4296 "actions-file.html#FILTER-CONTENT-COOKIES">filter{content-cookies}</a>
4297
4298  # These aliases define combinations of actions
4299  # that are useful for certain types of sites:
4300  #
4301  fragile     = -<a href="actions-file.html#BLOCK">block</a> -<a href=
4302 "actions-file.html#FILTER">filter</a> -crunch-all-cookies -<a href=
4303 "actions-file.html#FAST-REDIRECTS">fast-redirects</a> -<a href=
4304 "actions-file.html#HIDE-REFERER">hide-referrer</a> -<a href=
4305 "actions-file.html#PREVENT-COMPRESSION">prevent-compression</a>
4306
4307  shop        = -crunch-all-cookies -<a href=
4308 "actions-file.html#FILTER-ALL-POPUPS">filter{all-popups}</a>
4309
4310  # Short names for other aliases, for really lazy people ;-)
4311  #
4312  c0 = +crunch-all-cookies
4313  c1 = -crunch-all-cookies
4314 </pre>
4315           </td>
4316         </tr>
4317       </table>
4318
4319       <p>...and put them to use. These sections would appear in the lower
4320       part of an actions file and define exceptions to the default actions
4321       (as specified further up for the <span class="QUOTE">"/"</span>
4322       pattern):</p>
4323
4324       <table class="c4" border="0" width="100%">
4325         <tr>
4326           <td>
4327             <pre class="SCREEN">
4328  # These sites are either very complex or very keen on
4329  # user data and require minimal interference to work:
4330  #
4331  {fragile}
4332  .office.microsoft.com
4333  .windowsupdate.microsoft.com
4334  # Gmail is really mail.google.com, not gmail.com
4335  mail.google.com
4336
4337  # Shopping sites:
4338  # Allow cookies (for setting and retrieving your customer data)
4339  #
4340  {shop}
4341  .quietpc.com
4342  .worldpay.com   # for quietpc.com
4343  mybank.example.com
4344
4345  # These shops require pop-ups:
4346  #
4347  {-filter{all-popups} -filter{unsolicited-popups}}
4348   .dabs.com
4349   .overclockers.co.uk
4350 </pre>
4351           </td>
4352         </tr>
4353       </table>
4354
4355       <p>Aliases like <span class="QUOTE">"shop"</span> and <span class=
4356       "QUOTE">"fragile"</span> are typically used for <span class=
4357       "QUOTE">"problem"</span> sites that require more than one action to be
4358       disabled in order to function properly.</p>
4359     </div>
4360
4361     <div class="SECT2">
4362       <h2 class="SECT2"><a name="ACT-EXAMPLES" id="ACT-EXAMPLES">8.7. Actions
4363       Files Tutorial</a></h2>
4364
4365       <p>The above chapters have shown <a href="actions-file.html">which
4366       actions files there are and how they are organized</a>, how actions are
4367       <a href="actions-file.html#ACTIONS">specified</a> and <a href=
4368       "actions-file.html#ACTIONS-APPLY">applied to URLs</a>, how <a href=
4369       "actions-file.html#AF-PATTERNS">patterns</a> work, and how to define
4370       and use <a href="actions-file.html#ALIASES">aliases</a>. Now, let's
4371       look at an example <tt class="FILENAME">match-all.action</tt>,
4372       <tt class="FILENAME">default.action</tt> and <tt class=
4373       "FILENAME">user.action</tt> file and see how all these pieces come
4374       together:</p>
4375
4376       <div class="SECT3">
4377         <h3 class="SECT3"><a name="AEN4751" id="AEN4751">8.7.1.
4378         match-all.action</a></h3>
4379
4380         <p>Remember <span class="emphasis EMPHASIS c2">all actions are
4381         disabled when matching starts</span>, so we have to explicitly enable
4382         the ones we want.</p>
4383
4384         <p>While the <tt class="FILENAME">match-all.action</tt> file only
4385         contains a single section, it is probably the most important one. It
4386         has only one pattern, <span class="QUOTE">"<tt class=
4387         "LITERAL">/</tt>"</span>, but this pattern <a href=
4388         "actions-file.html#AF-PATTERNS">matches all URLs</a>. Therefore, the
4389         set of actions used in this <span class="QUOTE">"default"</span>
4390         section <span class="emphasis EMPHASIS c2">will be applied to all
4391         requests as a start</span>. It can be partly or wholly overridden by
4392         other actions files like <tt class="FILENAME">default.action</tt> and
4393         <tt class="FILENAME">user.action</tt>, but it will still be largely
4394         responsible for your overall browsing experience.</p>
4395
4396         <p>Again, at the start of matching, all actions are disabled, so
4397         there is no need to disable any actions here. (Remember: a
4398         <span class="QUOTE">"+"</span> preceding the action name enables the
4399         action, a <span class="QUOTE">"-"</span> disables!). Also note how
4400         this long line has been made more readable by splitting it into
4401         multiple lines with line continuation.</p>
4402
4403         <table class="c4" border="0" width="100%">
4404           <tr>
4405             <td>
4406               <pre class="SCREEN">
4407 { \
4408  +<a href=
4409 "actions-file.html#CHANGE-X-FORWARDED-FOR">change-x-forwarded-for{block}</a> \
4410  +<a href="actions-file.html#HIDE-FROM-HEADER">hide-from-header{block}</a> \
4411  +<a href=
4412 "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker{pattern}</a> \
4413 }
4414 / # Match all URLs
4415
4416 </pre>
4417             </td>
4418           </tr>
4419         </table>
4420
4421         <p>The default behavior is now set.</p>
4422       </div>
4423
4424       <div class="SECT3">
4425         <h3 class="SECT3"><a name="AEN4773" id="AEN4773">8.7.2.
4426         default.action</a></h3>
4427
4428         <p>If you aren't a developer, there's no need for you to edit the
4429         <tt class="FILENAME">default.action</tt> file. It is maintained by
4430         the <span class="APPLICATION">Privoxy</span> developers and if you
4431         disagree with some of the sections, you should overrule them in your
4432         <tt class="FILENAME">user.action</tt>.</p>
4433
4434         <p>Understanding the <tt class="FILENAME">default.action</tt> file
4435         can help you with your <tt class="FILENAME">user.action</tt>,
4436         though.</p>
4437
4438         <p>The first section in this file is a special section for internal
4439         use that prevents older <span class="APPLICATION">Privoxy</span>
4440         versions from reading the file:</p>
4441
4442         <table class="c4" border="0" width="100%">
4443           <tr>
4444             <td>
4445               <pre class="SCREEN">
4446 ##########################################################################
4447 # Settings -- Don't change! For internal Privoxy use ONLY.
4448 ##########################################################################
4449 {{settings}}
4450 for-privoxy-version=3.0.11
4451 </pre>
4452             </td>
4453           </tr>
4454         </table>
4455
4456         <p>After that comes the (optional) alias section. We'll use the
4457         example section from the above <a href=
4458         "actions-file.html#ALIASES">chapter on aliases</a>, that also
4459         explains why and how aliases are used:</p>
4460
4461         <table class="c4" border="0" width="100%">
4462           <tr>
4463             <td>
4464               <pre class="SCREEN">
4465 ##########################################################################
4466 # Aliases
4467 ##########################################################################
4468 {{alias}}
4469
4470  # These aliases just save typing later:
4471  # (Note that some already use other aliases!)
4472  #
4473  +crunch-all-cookies = +<a href=
4474 "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a> +<a href="actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a>
4475  -crunch-all-cookies = -<a href=
4476 "actions-file.html#CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</a> -<a href="actions-file.html#CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</a>
4477  +block-as-image      = +block{Blocked image.} +handle-as-image
4478  mercy-for-cookies   = -crunch-all-cookies -<a href=
4479 "actions-file.html#SESSION-COOKIES-ONLY">session-cookies-only</a> -<a href=
4480 "actions-file.html#FILTER-CONTENT-COOKIES">filter{content-cookies}</a>
4481
4482  # These aliases define combinations of actions
4483  # that are useful for certain types of sites:
4484  #
4485  fragile     = -<a href="actions-file.html#BLOCK">block</a> -<a href=
4486 "actions-file.html#FILTER">filter</a> -crunch-all-cookies -<a href=
4487 "actions-file.html#FAST-REDIRECTS">fast-redirects</a> -<a href=
4488 "actions-file.html#HIDE-REFERER">hide-referrer</a>
4489  shop        = -crunch-all-cookies -<a href=
4490 "actions-file.html#FILTER-ALL-POPUPS">filter{all-popups}</a>
4491 </pre>
4492             </td>
4493           </tr>
4494         </table>
4495
4496         <p>The first of our specialized sections is concerned with
4497         <span class="QUOTE">"fragile"</span> sites, i.e. sites that require
4498         minimum interference, because they are either very complex or very
4499         keen on tracking you (and have mechanisms in place that make them
4500         unusable for people who avoid being tracked). We will simply use our
4501         pre-defined <tt class="LITERAL">fragile</tt> alias instead of stating
4502         the list of actions explicitly:</p>
4503
4504         <table class="c4" border="0" width="100%">
4505           <tr>
4506             <td>
4507               <pre class="SCREEN">
4508 ##########################################################################
4509 # Exceptions for sites that'll break under the default action set:
4510 ##########################################################################
4511
4512 # "Fragile" Use a minimum set of actions for these sites (see alias above):
4513 #
4514 { fragile }
4515 .office.microsoft.com           # surprise, surprise!
4516 .windowsupdate.microsoft.com
4517 mail.google.com
4518 </pre>
4519             </td>
4520           </tr>
4521         </table>
4522
4523         <p>Shopping sites are not as fragile, but they typically require
4524         cookies to log in, and pop-up windows for shopping carts or item
4525         details. Again, we'll use a pre-defined alias:</p>
4526
4527         <table class="c4" border="0" width="100%">
4528           <tr>
4529             <td>
4530               <pre class="SCREEN">
4531 # Shopping sites:
4532 #
4533 { shop }
4534 .quietpc.com
4535 .worldpay.com   # for quietpc.com
4536 .jungle.com
4537 .scan.co.uk
4538 </pre>
4539             </td>
4540           </tr>
4541         </table>
4542
4543         <p>The <tt class="LITERAL"><a href=
4544         "actions-file.html#FAST-REDIRECTS">fast-redirects</a></tt> action,
4545         which may have been enabled in <tt class=
4546         "FILENAME">match-all.action</tt>, breaks some sites. So disable it
4547         for popular sites where we know it misbehaves:</p>
4548
4549         <table class="c4" border="0" width="100%">
4550           <tr>
4551             <td>
4552               <pre class="SCREEN">
4553 { -<a href="actions-file.html#FAST-REDIRECTS">fast-redirects</a> }
4554 login.yahoo.com
4555 edit.*.yahoo.com
4556 .google.com
4557 .altavista.com/.*(like|url|link):http
4558 .altavista.com/trans.*urltext=http
4559 .nytimes.com
4560 </pre>
4561             </td>
4562           </tr>
4563         </table>
4564
4565         <p>It is important that <span class="APPLICATION">Privoxy</span>
4566         knows which URLs belong to images, so that <span class=
4567         "emphasis EMPHASIS c2">if</span> they are to be blocked, a substitute
4568         image can be sent, rather than an HTML page. Contacting the remote
4569         site to find out is not an option, since it would destroy the loading
4570         time advantage of banner blocking, and it would feed the advertisers
4571         information about you. We can mark any URL as an image with the
4572         <tt class="LITERAL"><a href=
4573         "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt> action,
4574         and marking all URLs that end in a known image file extension is a
4575         good start:</p>
4576
4577         <table class="c4" border="0" width="100%">
4578           <tr>
4579             <td>
4580               <pre class="SCREEN">
4581 ##########################################################################
4582 # Images:
4583 ##########################################################################
4584
4585 # Define which file types will be treated as images, in case they get
4586 # blocked further down this file:
4587 #
4588 { +<a href="actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a> }
4589 /.*\.(gif|jpe?g|png|bmp|ico)$
4590 </pre>
4591             </td>
4592           </tr>
4593         </table>
4594
4595         <p>And then there are known banner sources. They often use scripts to
4596         generate the banners, so it won't be visible from the URL that the
4597         request is for an image. Hence we block them <span class=
4598         "emphasis EMPHASIS c2">and</span> mark them as images in one go, with
4599         the help of our <tt class="LITERAL">+block-as-image</tt> alias
4600         defined above. (We could of course just as well use <tt class=
4601         "LITERAL">+<a href="actions-file.html#BLOCK">block</a> +<a href=
4602         "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></tt> here.)
4603         Remember that the type of the replacement image is chosen by the
4604         <tt class="LITERAL"><a href=
4605         "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></tt>
4606         action. Since all URLs have matched the default section with its
4607         <tt class="LITERAL">+<a href=
4608         "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a>{pattern}</tt>
4609         action before, it still applies and needn't be repeated:</p>
4610
4611         <table class="c4" border="0" width="100%">
4612           <tr>
4613             <td>
4614               <pre class="SCREEN">
4615 # Known ad generators:
4616 #
4617 { +block-as-image }
4618 ar.atwola.com
4619 .ad.doubleclick.net
4620 .ad.*.doubleclick.net
4621 .a.yimg.com/(?:(?!/i/).)*$
4622 .a[0-9].yimg.com/(?:(?!/i/).)*$
4623 bs*.gsanet.com
4624 .qkimg.net
4625 </pre>
4626             </td>
4627           </tr>
4628         </table>
4629
4630         <p>One of the most important jobs of <span class=
4631         "APPLICATION">Privoxy</span> is to block banners. Many of these can
4632         be <span class="QUOTE">"blocked"</span> by the <tt class=
4633         "LITERAL"><a href=
4634         "actions-file.html#FILTER">filter</a>{banners-by-size}</tt> action,
4635         which we enabled above, and which deletes the references to banner
4636         images from the pages while they are loaded, so the browser doesn't
4637         request them anymore, and hence they don't need to be blocked here.
4638         But this naturally doesn't catch all banners, and some people choose
4639         not to use filters, so we need a comprehensive list of patterns for
4640         banner URLs here, and apply the <tt class="LITERAL"><a href=
4641         "actions-file.html#BLOCK">block</a></tt> action to them.</p>
4642
4643         <p>First comes many generic patterns, which do most of the work, by
4644         matching typical domain and path name components of banners. Then
4645         comes a list of individual patterns for specific sites, which is
4646         omitted here to keep the example short:</p>
4647
4648         <table class="c4" border="0" width="100%">
4649           <tr>
4650             <td>
4651               <pre class="SCREEN">
4652 ##########################################################################
4653 # Block these fine banners:
4654 ##########################################################################
4655 { <a href="actions-file.html#BLOCK">+block{Banner ads.}</a> }
4656
4657 # Generic patterns:
4658 #
4659 ad*.
4660 .*ads.
4661 banner?.
4662 count*.
4663 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
4664 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
4665
4666 # Site-specific patterns (abbreviated):
4667 #
4668 .hitbox.com
4669 </pre>
4670             </td>
4671           </tr>
4672         </table>
4673
4674         <p>It's quite remarkable how many advertisers actually call their
4675         banner servers ads.<tt class="REPLACEABLE c5">company</tt>.com, or
4676         call the directory in which the banners are stored simply
4677         <span class="QUOTE">"banners"</span>. So the above generic patterns
4678         are surprisingly effective.</p>
4679
4680         <p>But being very generic, they necessarily also catch URLs that we
4681         don't want to block. The pattern <tt class="LITERAL">.*ads.</tt> e.g.
4682         catches <span class="QUOTE">"nasty-<span class=
4683         "emphasis EMPHASIS c2">ads</span>.nasty-corp.com"</span> as intended,
4684         but also <span class="QUOTE">"downlo<span class=
4685         "emphasis EMPHASIS c2">ads</span>.sourcefroge.net"</span> or
4686         <span class="QUOTE">"<span class=
4687         "emphasis EMPHASIS c2">ads</span>l.some-provider.net."</span> So here
4688         come some well-known exceptions to the <tt class="LITERAL">+<a href=
4689         "actions-file.html#BLOCK">block</a></tt> section above.</p>
4690
4691         <p>Note that these are exceptions to exceptions from the default!
4692         Consider the URL <span class=
4693         "QUOTE">"downloads.sourcefroge.net"</span>: Initially, all actions
4694         are deactivated, so it wouldn't get blocked. Then comes the defaults
4695         section, which matches the URL, but just deactivates the <tt class=
4696         "LITERAL"><a href="actions-file.html#BLOCK">block</a></tt> action
4697         once again. Then it matches <tt class="LITERAL">.*ads.</tt>, an
4698         exception to the general non-blocking policy, and suddenly <tt class=
4699         "LITERAL"><a href="actions-file.html#BLOCK">+block</a></tt> applies.
4700         And now, it'll match <tt class="LITERAL">.*loads.</tt>, where
4701         <tt class="LITERAL"><a href="actions-file.html#BLOCK">-block</a></tt>
4702         applies, so (unless it matches <span class=
4703         "emphasis EMPHASIS c2">again</span> further down) it ends up with no
4704         <tt class="LITERAL"><a href="actions-file.html#BLOCK">block</a></tt>
4705         action applying.</p>
4706
4707         <table class="c4" border="0" width="100%">
4708           <tr>
4709             <td>
4710               <pre class="SCREEN">
4711 ##########################################################################
4712 # Save some innocent victims of the above generic block patterns:
4713 ##########################################################################
4714
4715 # By domain:
4716 #
4717 { -<a href="actions-file.html#BLOCK">block</a> }
4718 adv[io]*.  # (for advogato.org and advice.*)
4719 adsl.      # (has nothing to do with ads)
4720 adobe.     # (has nothing to do with ads either)
4721 ad[ud]*.   # (adult.* and add.*)
4722 .edu       # (universities don't host banners (yet!))
4723 .*loads.   # (downloads, uploads etc)
4724
4725 # By path:
4726 #
4727 /.*loads/
4728
4729 # Site-specific:
4730 #
4731 www.globalintersec.com/adv # (adv = advanced)
4732 www.ugu.com/sui/ugu/adv
4733 </pre>
4734             </td>
4735           </tr>
4736         </table>
4737
4738         <p>Filtering source code can have nasty side effects, so make an
4739         exception for our friends at sourceforge.net, and all paths with
4740         <span class="QUOTE">"cvs"</span> in them. Note that <tt class=
4741         "LITERAL">-<a href="actions-file.html#FILTER">filter</a></tt>
4742         disables <span class="emphasis EMPHASIS c2">all</span> filters in one
4743         fell swoop!</p>
4744
4745         <table class="c4" border="0" width="100%">
4746           <tr>
4747             <td>
4748               <pre class="SCREEN">
4749 # Don't filter code!
4750 #
4751 { -<a href="actions-file.html#FILTER">filter</a> }
4752 /(.*/)?cvs
4753 bugzilla.
4754 developer.
4755 wiki.
4756 .sourceforge.net
4757 </pre>
4758             </td>
4759           </tr>
4760         </table>
4761
4762         <p>The actual <tt class="FILENAME">default.action</tt> is of course
4763         much more comprehensive, but we hope this example made clear how it
4764         works.</p>
4765       </div>
4766
4767       <div class="SECT3">
4768         <h3 class="SECT3"><a name="AEN4886" id="AEN4886">8.7.3.
4769         user.action</a></h3>
4770
4771         <p>So far we are painting with a broad brush by setting general
4772         policies, which would be a reasonable starting point for many people.
4773         Now, you might want to be more specific and have customized rules
4774         that are more suitable to your personal habits and preferences. These
4775         would be for narrowly defined situations like your ISP or your bank,
4776         and should be placed in <tt class="FILENAME">user.action</tt>, which
4777         is parsed after all other actions files and hence has the last word,
4778         over-riding any previously defined actions. <tt class=
4779         "FILENAME">user.action</tt> is also a <span class=
4780         "emphasis EMPHASIS c2">safe</span> place for your personal settings,
4781         since <tt class="FILENAME">default.action</tt> is actively maintained
4782         by the <span class="APPLICATION">Privoxy</span> developers and you'll
4783         probably want to install updated versions from time to time.</p>
4784
4785         <p>So let's look at a few examples of things that one might typically
4786         do in <tt class="FILENAME">user.action</tt>:</p>
4787
4788         <table class="c4" border="0" width="100%">
4789           <tr>
4790             <td>
4791               <pre class="SCREEN">
4792 # My user.action file. &lt;fred@example.com&gt;
4793 </pre>
4794             </td>
4795           </tr>
4796         </table>
4797
4798         <p>As <a href="actions-file.html#ALIASES">aliases</a> are local to
4799         the actions file that they are defined in, you can't use the ones
4800         from <tt class="FILENAME">default.action</tt>, unless you repeat them
4801         here:</p>
4802
4803         <table class="c4" border="0" width="100%">
4804           <tr>
4805             <td>
4806               <pre class="SCREEN">
4807 # Aliases are local to the file they are defined in.
4808 # (Re-)define aliases for this file:
4809 #
4810 {{alias}}
4811 #
4812 # These aliases just save typing later, and the alias names should
4813 # be self explanatory.
4814 #
4815 +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
4816 -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
4817  allow-all-cookies  = -crunch-all-cookies -session-cookies-only
4818  allow-popups       = -filter{all-popups}
4819 +block-as-image     = +block{Blocked as image.} +handle-as-image
4820 -block-as-image     = -block
4821
4822 # These aliases define combinations of actions that are useful for
4823 # certain types of sites:
4824 #
4825 fragile     = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer
4826 shop        = -crunch-all-cookies allow-popups
4827
4828 # Allow ads for selected useful free sites:
4829 #
4830 allow-ads   = -block -filter{banners-by-size} -filter{banners-by-link}
4831
4832 # Alias for specific file types that are text, but might have conflicting
4833 # MIME types. We want the browser to force these to be text documents.
4834 handle-as-text = -<a href="actions-file.html#FILTER">filter</a> +-<a href=
4835 "actions-file.html#CONTENT-TYPE-OVERWRITE">content-type-overwrite{text/plain}</a> +-<a href="actions-file.html#FORCE-TEXT-MODE">force-text-mode</a> -<a href="actions-file.html#HIDE-CONTENT-DISPOSITION">hide-content-disposition</a>
4836 </pre>
4837             </td>
4838           </tr>
4839         </table>
4840
4841         <p>Say you have accounts on some sites that you visit regularly, and
4842         you don't want to have to log in manually each time. So you'd like to
4843         allow persistent cookies for these sites. The <tt class=
4844         "LITERAL">allow-all-cookies</tt> alias defined above does exactly
4845         that, i.e. it disables crunching of cookies in any direction, and the
4846         processing of cookies to make them only temporary.</p>
4847
4848         <table class="c4" border="0" width="100%">
4849           <tr>
4850             <td>
4851               <pre class="SCREEN">
4852 { allow-all-cookies }
4853  sourceforge.net
4854  .yahoo.com
4855  .msdn.microsoft.com
4856  .redhat.com
4857 </pre>
4858             </td>
4859           </tr>
4860         </table>
4861
4862         <p>Your bank is allergic to some filter, but you don't know which, so
4863         you disable them all:</p>
4864
4865         <table class="c4" border="0" width="100%">
4866           <tr>
4867             <td>
4868               <pre class="SCREEN">
4869 { -<a href="actions-file.html#FILTER">filter</a> }
4870  .your-home-banking-site.com
4871 </pre>
4872             </td>
4873           </tr>
4874         </table>
4875
4876         <p>Some file types you may not want to filter for various
4877         reasons:</p>
4878
4879         <table class="c4" border="0" width="100%">
4880           <tr>
4881             <td>
4882               <pre class="SCREEN">
4883 # Technical documentation is likely to contain strings that might
4884 # erroneously get altered by the JavaScript-oriented filters:
4885 #
4886 .tldp.org
4887 /(.*/)?selfhtml/
4888
4889 # And this stupid host sends streaming video with a wrong MIME type,
4890 # so that Privoxy thinks it is getting HTML and starts filtering:
4891 #
4892 stupid-server.example.com/
4893 </pre>
4894             </td>
4895           </tr>
4896         </table>
4897
4898         <p>Example of a simple <a href="actions-file.html#BLOCK">block</a>
4899         action. Say you've seen an ad on your favourite page on example.com
4900         that you want to get rid of. You have right-clicked the image,
4901         selected <span class="QUOTE">"copy image location"</span> and pasted
4902         the URL below while removing the leading http://, into a <tt class=
4903         "LITERAL">{ +block{} }</tt> section. Note that <tt class="LITERAL">{
4904         +handle-as-image }</tt> need not be specified, since all URLs ending
4905         in <tt class="LITERAL">.gif</tt> will be tagged as images by the
4906         general rules as set in default.action anyway:</p>
4907
4908         <table class="c4" border="0" width="100%">
4909           <tr>
4910             <td>
4911               <pre class="SCREEN">
4912 { +<a href="actions-file.html#BLOCK">block</a>{Nasty ads.} }
4913  www.example.com/nasty-ads/sponsor\.gif
4914  another.example.net/more/junk/here/
4915 </pre>
4916             </td>
4917           </tr>
4918         </table>
4919
4920         <p>The URLs of dynamically generated banners, especially from large
4921         banner farms, often don't use the well-known image file name
4922         extensions, which makes it impossible for <span class=
4923         "APPLICATION">Privoxy</span> to guess the file type just by looking
4924         at the URL. You can use the <tt class="LITERAL">+block-as-image</tt>
4925         alias defined above for these cases. Note that objects which match
4926         this rule but then turn out NOT to be an image are typically rendered
4927         as a <span class="QUOTE">"broken image"</span> icon by the browser.
4928         Use cautiously.</p>
4929
4930         <table class="c4" border="0" width="100%">
4931           <tr>
4932             <td>
4933               <pre class="SCREEN">
4934 { +block-as-image }
4935  .doubleclick.net
4936  .fastclick.net
4937  /Realmedia/ads/
4938  ar.atwola.com/
4939 </pre>
4940             </td>
4941           </tr>
4942         </table>
4943
4944         <p>Now you noticed that the default configuration breaks Forbes
4945         Magazine, but you were too lazy to find out which action is the
4946         culprit, and you were again too lazy to give <a href=
4947         "contact.html">feedback</a>, so you just used the <tt class=
4948         "LITERAL">fragile</tt> alias on the site, and -- <span class=
4949         "emphasis EMPHASIS c2">whoa!</span> -- it worked. The <tt class=
4950         "LITERAL">fragile</tt> aliases disables those actions that are most
4951         likely to break a site. Also, good for testing purposes to see if it
4952         is <span class="APPLICATION">Privoxy</span> that is causing the
4953         problem or not. We later find other regular sites that misbehave, and
4954         add those to our personalized list of troublemakers:</p>
4955
4956         <table class="c4" border="0" width="100%">
4957           <tr>
4958             <td>
4959               <pre class="SCREEN">
4960 { fragile }
4961  .forbes.com
4962  webmail.example.com
4963  .mybank.com
4964 </pre>
4965             </td>
4966           </tr>
4967         </table>
4968
4969         <p>You like the <span class="QUOTE">"fun"</span> text replacements in
4970         <tt class="FILENAME">default.filter</tt>, but it is disabled in the
4971         distributed actions file. So you'd like to turn it on in your
4972         private, update-safe config, once and for all:</p>
4973
4974         <table class="c4" border="0" width="100%">
4975           <tr>
4976             <td>
4977               <pre class="SCREEN">
4978 { +<a href="actions-file.html#FILTER-FUN">filter{fun}</a> }
4979  / # For ALL sites!
4980 </pre>
4981             </td>
4982           </tr>
4983         </table>
4984
4985         <p>Note that the above is not really a good idea: There are
4986         exceptions to the filters in <tt class="FILENAME">default.action</tt>
4987         for things that really shouldn't be filtered, like code on
4988         CVS-&gt;Web interfaces. Since <tt class="FILENAME">user.action</tt>
4989         has the last word, these exceptions won't be valid for the
4990         <span class="QUOTE">"fun"</span> filtering specified here.</p>
4991
4992         <p>You might also worry about how your favourite free websites are
4993         funded, and find that they rely on displaying banner advertisements
4994         to survive. So you might want to specifically allow banners for those
4995         sites that you feel provide value to you:</p>
4996
4997         <table class="c4" border="0" width="100%">
4998           <tr>
4999             <td>
5000               <pre class="SCREEN">
5001 { allow-ads }
5002  .sourceforge.net
5003  .slashdot.org
5004  .osdn.net
5005 </pre>
5006             </td>
5007           </tr>
5008         </table>
5009
5010         <p>Note that <tt class="LITERAL">allow-ads</tt> has been aliased to
5011         <tt class="LITERAL">-<a href=
5012         "actions-file.html#BLOCK">block</a></tt>, <tt class=
5013         "LITERAL">-<a href=
5014         "actions-file.html#FILTER-BANNERS-BY-SIZE">filter{banners-by-size}</a></tt>,
5015         and <tt class="LITERAL">-<a href=
5016         "actions-file.html#FILTER-BANNERS-BY-LINK">filter{banners-by-link}</a></tt>
5017         above.</p>
5018
5019         <p>Invoke another alias here to force an over-ride of the MIME type
5020         <tt class="LITERAL">application/x-sh</tt> which typically would open
5021         a download type dialog. In my case, I want to look at the shell
5022         script, and then I can save it should I choose to.</p>
5023
5024         <table class="c4" border="0" width="100%">
5025           <tr>
5026             <td>
5027               <pre class="SCREEN">
5028 { handle-as-text }
5029  /.*\.sh$
5030 </pre>
5031             </td>
5032           </tr>
5033         </table>
5034
5035         <p><tt class="FILENAME">user.action</tt> is generally the best place
5036         to define exceptions and additions to the default policies of
5037         <tt class="FILENAME">default.action</tt>. Some actions are safe to
5038         have their default policies set here though. So let's set a default
5039         policy to have a <span class="QUOTE">"blank"</span> image as opposed
5040         to the checkerboard pattern for <span class=
5041         "emphasis EMPHASIS c2">ALL</span> sites. <span class=
5042         "QUOTE">"/"</span> of course matches all URL paths and patterns:</p>
5043
5044         <table class="c4" border="0" width="100%">
5045           <tr>
5046             <td>
5047               <pre class="SCREEN">
5048 { +<a href=
5049 "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker{blank}</a> }
5050 / # ALL sites
5051 </pre>
5052             </td>
5053           </tr>
5054         </table>
5055       </div>
5056     </div>
5057   </div>
5058
5059   <div class="NAVFOOTER">
5060     <hr class="c1" width="100%">
5061
5062     <table summary="Footer navigation table" width="100%" border="0"
5063     cellpadding="0" cellspacing="0">
5064       <tr>
5065         <td width="33%" align="left" valign="top"><a href="config.html"
5066         accesskey="P">Prev</a></td>
5067
5068         <td width="34%" align="center" valign="top"><a href="index.html"
5069         accesskey="H">Home</a></td>
5070
5071         <td width="33%" align="right" valign="top"><a href="filter-file.html"
5072         accesskey="N">Next</a></td>
5073       </tr>
5074
5075       <tr>
5076         <td width="33%" align="left" valign="top">The Main Configuration
5077         File</td>
5078
5079         <td width="34%" align="center" valign="top">&nbsp;</td>
5080
5081         <td width="33%" align="right" valign="top">Filter Files</td>
5082       </tr>
5083     </table>
5084   </div>
5085 </body>
5086 </html>