doc/source/user-manual.sgml

   1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
   2 <!entity % dummy "IGNORE">
   3 <!entity supported SYSTEM "supported.sgml">
   4 <!entity newfeatures SYSTEM "newfeatures.sgml">
   5 <!entity p-intro SYSTEM "privoxy.sgml">
   6 <!entity seealso SYSTEM "seealso.sgml">
   7 <!entity buildsource SYSTEM "buildsource.sgml">
   8 <!entity contacting SYSTEM "contacting.sgml">
   9 <!entity history SYSTEM "history.sgml">
  10 <!entity copyright SYSTEM "copyright.sgml">
  11 <!entity license SYSTEM "license.sgml">
  12 <!entity p-authors SYSTEM "p-authors.sgml">
  13 <!entity config SYSTEM "p-config.sgml">
  14 <!entity p-version "3.0.6">
  15 <!entity p-status "UNRELEASED">
  16 <!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc  -->
  17 <!entity % p-not-stable "INCLUDE">
  18 <!entity % p-stable "IGNORE">
  19 <!entity % p-text "IGNORE">        <!-- define we are not a text only doc -->
  20 <!entity % p-doc "INCLUDE">        <!-- and we are a formal doc           -->
  21 <!entity % p-readme "IGNORE">
  22 <!entity % user-man "IGNORE">
  23 <!entity % config-file "IGNORE">
  24 <!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml    -->
  25 <!entity  my-copy "&copy;">         <!-- kludge for docbook2man           -->
  26 <!entity % draft "IGNORE">          <!-- WIP stuff    -->
  27 <!entity  my-app "<application>Privoxy</application>">
  28 ]>
  29 <!--
  30  File        :  $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
  31
  32  Purpose     :  user manual
  33                 This file belongs into
  34                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
  35
  36  $Id: user-manual.sgml,v 2.23 2006/10/02 22:43:53 hal9 Exp $
  37
  38  Copyright (C) 2001- 2006 Privoxy Developers http://www.privoxy.org
  39  See LICENSE.
  40
  41  ========================================================================
  42  NOTE: Please read developer-manual/documentation.html before touching
  43  anything in this, or other Privoxy documentation.
  44  ========================================================================
  45
  46 -->
  47
  48 <article id="index">
  49 <artheader>
  50
  51 <title>Privoxy &p-version; User Manual</title>
  52
  53 <pubdate>
  54  <subscript>
  55 <!-- Completely the wrong markup, but very little is allowed  -->
  56 <!-- in this part of an article. FIXME -->
  57  <link linkend="copyright">Copyright</link> &my-copy; 2001 - 2006 by
  58  <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
  59  </subscript>
  60 </pubdate>
  61
  62 <pubdate>$Id: user-manual.sgml,v 2.23 2006/10/02 22:43:53 hal9 Exp $</pubdate>
  63
  64 <!--
  65
  66 Note: the following should generate a separate page, and a live link to it,
  67 all nicely done. But it doesn't for some mysterious reason. Please leave
  68 commented unless it can be fixed proper. For the time being, the
  69 copyright/license declarations will be in their own sgml.
  70
  71 Hal.
  72
  73
  74 -->
  75
  76
  77 <abstract>
  78
  79 <![%dummy;[
  80  <para>
  81  <comment>
  82   This is here to keep vim syntax file from breaking :/
  83   If I knew enough to fix it, I would.
  84   PLEASE DO NOT REMOVE! HB: hal@foobox.net
  85  </comment>
  86  </para>
  87 ]]>
  88
  89  <para>
  90   The <citetitle>Privoxy User Manual</citetitle> gives users information on how to
  91   install, configure and use <ulink
  92   url="http://www.privoxy.org/">Privoxy</ulink>.
  93  </para>
  94
  95 <!-- Include privoxy.sgml boilerplate: -->
  96  &p-intro;
  97 <!-- end privoxy.sgml -->
  98
  99  <para>
 100   You can find the latest version of the <citetitle>Privoxy User Manual</citetitle> at  <ulink
 101   url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
 102   Please see the <link linkend="contact">Contact section</link> on how to
 103   contact the developers.
 104  </para>
 105
 106 <!--   <para> -->
 107 <!--    Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
 108 <!--   </para> -->
 109 </abstract>
 110
 111 </artheader>
 112
 113 <!--   ~~~~~       New section      ~~~~~     -->
 114 <sect1 label="1" id="introduction"><title>Introduction</title>
 115 <para>
 116  This documentation is included with the current &p-status; version of
 117  <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[,
 118  and is mostly complete at this point. The most up to date reference for the
 119  time being is still the comments in the source files and in the individual
 120  configuration files. Development of a new version is currently nearing
 121  completion, and includes significant changes and enhancements over
 122  earlier versions. ]]>.
 123 </para>
 124
 125 <!-- include only in non-stable versions -->
 126 <![%p-not-stable;[
 127 <para>
 128  Since this is a &p-status; version, not all new features are well tested. This
 129  documentation may be slightly out of sync as a result (especially with
 130  CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
 131  not many!
 132 </para>
 133 ]]>
 134
 135 <!--   ~~~~~       New section      ~~~~~     -->
 136 <sect2 id="features"><title>Features</title>
 137 <para>
 138  In addition to the core
 139  features of ad blocking and
 140  <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> management,
 141  <application>Privoxy</application> provides many supplemental
 142  features<![%p-not-stable;[, some of them currently under development]]>,
 143  that give the end-user more control, more privacy and more freedom:
 144 </para>
 145 <!-- Include newfeatures.sgml boilerplate here: -->
 146  &newfeatures;
 147 <!-- end boilerplate -->
 148 </sect2>
 149
 150 </sect1>
 151
 152 <!--  ~  End section  ~  -->
 153
 154
 155 <!--   ~~~~~       New section      ~~~~~     -->
 156 <sect1 id="installation"><title>Installation</title>
 157
 158 <para>
 159  <application>Privoxy</application> is available both in convenient pre-compiled
 160  packages for a wide range of operating systems, and as raw source code.
 161  For most users, we recommend using the packages, which can be downloaded from our
 162  <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project
 163  Page</ulink>.
 164 </para>
 165
 166 <para>
 167  Note:
 168  On some platforms, the installer may remove previously installed versions, if
 169  found. (See below for your platform). In any case <emphasis>be sure to backup
 170  your old configuration if it is valuable to you.</emphasis> See the <link
 171  linkend="upgradersnote">note to upgraders</link> section below.
 172 </para>
 173
 174 <!--   ~~~~~       New section      ~~~~~     -->
 175 <sect2 id="installation-packages"><title>Binary Packages</title>
 176 <para>
 177 How to install the binary packages depends on your operating system:
 178 </para>
 179
 180 <!--   ~~~~~       New section      ~~~~~     -->
 181 <sect3 id="installation-pack-rpm"><title>Red Hat, SuSE and Conectiva RPMs</title>
 182
 183 <para>
 184  RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
 185  and will use <filename>/etc/privoxy</filename> for the location
 186  of configuration files.
 187 </para>
 188
 189 <para>
 190  Note that on Red Hat, <application>Privoxy</application> will
 191  <emphasis>not</emphasis> be automatically started on system boot. You will
 192  need to enable that using <command>chkconfig</command>,
 193  <command>ntsysv</command>, or similar methods.
 194 </para>
 195
 196 <para>
 197  If you have problems with failed dependencies, try rebuilding the SRC RPM:
 198  <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm</literal>. This
 199  will use your locally installed libraries and RPM version.
 200 </para>
 201
 202 <para>
 203  Also note that if you have a <application>Junkbuster</application> RPM installed
 204  on your system, you need to remove it first, because the packages conflict.
 205  Otherwise, RPM will try to remove <application>Junkbuster</application>
 206  automatically if found, before installing <application>Privoxy</application>.
 207 </para>
 208 </sect3>
 209
 210 <!--   ~~~~~       New section      ~~~~~     -->
 211 <sect3 id="installation-deb"><title>Debian</title>
 212 <para>
 213  DEBs can be installed with <literal>apt-get install privoxy</literal>,
 214  and will use <filename>/etc/privoxy</filename> for the location of
 215  configuration files.
 216 </para>
 217 </sect3>
 218
 219 <!--   ~~~~~       New section      ~~~~~     -->
 220 <sect3 id="installation-pack-win"><title>Windows</title>
 221
 222 <para>
 223  Just double-click the installer, which will guide you through
 224  the installation process. You will find the configuration files
 225  in the same directory as you installed <application>Privoxy</application> in.
 226 </para>
 227 <para>
 228  Version 3.0.4 introduced full <application>Windows</application> service
 229  functionality. On Windows only, the <application>Privoxy</application>
 230  program has two new command line arguments to install and uninstall
 231  <application>Privoxy</application> as a <emphasis>service</emphasis>.
 232 </para>
 233  <variablelist>
 234   <varlistentry>
 235    <term>Arguments:</term>
 236    <listitem>
 237     <para>
 238      <replaceable class="parameter">--install</replaceable>[:<replaceable class="parameter">service_name</replaceable>]
 239     </para>
 240     <para>
 241      <replaceable class="parameter">--uninstall</replaceable>[:<replaceable class="parameter">service_name</replaceable>]
 242     </para>
 243    </listitem>
 244   </varlistentry>
 245  </variablelist>
 246  <para>
 247  After invoking <application>Privoxy</application> with
 248  <command>--install</command>, you will need to bring up the
 249  <application>Windows</application> service console to assign the user you
 250  want <application>Privoxy</application> to run under, and whether or not you
 251  want it to run whenever the system starts. You can start the
 252  <application>Windows</application> services console with the following
 253  command: <command>services.msc</command>.  If you do not take the manual step
 254  of modifying <application>Privoxy's</application> service settings, it will
 255  not start.  Note too that you will need to give Privoxy a user account that
 256  actually exists, or it will not be permitted to
 257  write to its log and configuration files.
 258 </para>
 259
 260 </sect3>
 261
 262 <!--   ~~~~~       New section      ~~~~~     -->
 263 <sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, FreeBSD, HP-UX</title>
 264
 265 <para>
 266  Create a new directory, <literal>cd</literal> to it, then unzip and
 267  untar the archive. For the most part, you'll have to figure out where
 268  things go. <!-- FIXME, more info needed? -->
 269 </para>
 270 </sect3>
 271
 272 <!--   ~~~~~       New section      ~~~~~     -->
 273 <sect3 id="installation-os2"><title>OS/2</title>
 274
 275 <para>
 276  First, make sure that no previous installations of
 277  <application>Junkbuster</application> and / or
 278  <application>Privoxy</application> are left on your
 279  system. Check that no <application>Junkbuster</application>
 280  or <application>Privoxy</application> objects are in
 281  your startup folder.
 282
 283 </para>
 284
 285 <para>
 286  Then, just double-click the WarpIN self-installing archive, which will
 287  guide you through the installation process. A shadow of the
 288  <application>Privoxy</application> executable will be placed in your
 289  startup folder so it will start automatically whenever OS/2 starts.
 290 </para>
 291
 292 <para>
 293  The directory you choose to install <application>Privoxy</application>
 294  into will contain all of the configuration files.
 295 </para>
 296 </sect3>
 297
 298 <!--   ~~~~~       New section      ~~~~~     -->
 299 <sect3 id="installation-mac"><title>Mac OSX</title>
 300 <para>
 301  Unzip the downloaded file (you can either double-click on the file
 302  from the finder, or from the desktop if you downloaded it there).
 303  Then, double-click on the package installer icon named
 304  <literal>Privoxy.pkg</literal>
 305  and follow the installation process.
 306  <application>Privoxy</application> will be installed in the folder
 307  <literal>/Library/Privoxy</literal>.
 308  It will start automatically whenever you start up.  To prevent it from
 309  starting automatically, remove or rename the folder
 310  <literal>/Library/StartupItems/Privoxy</literal>.
 311 </para>
 312 <para>
 313  To start Privoxy by hand, double-click on
 314  <literal>StartPrivoxy.command</literal> in the
 315  <literal>/Library/Privoxy</literal> folder.
 316  Or, type this command in the Terminal:
 317 </para>
 318 <para>
 319   <screen>
 320   /Library/Privoxy/StartPrivoxy.command
 321   </screen>
 322 </para>
 323 <para>
 324  You will be prompted for the administrator password.
 325 </para>
 326 </sect3>
 327
 328 <!--   ~~~~~       New section      ~~~~~     -->
 329 <sect3 id="installation-amiga"><title>AmigaOS</title>
 330 <para>
 331  Copy and then unpack the <filename>lha</filename> archive to a suitable location.
 332  All necessary files will be installed into <application>Privoxy</application>
 333  directory, including all configuration and log files. To uninstall, just
 334  remove this directory.
 335 </para>
 336 </sect3>
 337
 338 <!--   ~~~~~       New section      ~~~~~     -->
 339 <sect3 id="installattion-gentoo"><title>Gentoo</title>
 340 <para>
 341  Gentoo source packages (Ebuilds) for <application>Privoxy</application> are
 342  contained in the Gentoo  Portage Tree (they are not on the download page,
 343  but there is a Gentoo section, where you can see when a new
 344  <application>Privoxy</application> Version is added to the  Portage Tree).
 345 </para>
 346 <para>
 347  Before installing <application>Privoxy</application> under Gentoo just do
 348  first <literal>emerge rsync</literal> to get the latest changes from the
 349  Portage tree. With <literal>emerge privoxy</literal> you install the latest
 350  version.
 351 </para>
 352 <para>
 353  Configuration files are in <filename>/etc/privoxy</filename>, the
 354  documentation is in <filename>/usr/share/doc/privoxy-&p-version;</filename>
 355  and the Log directory is in <filename>/var/log/privoxy</filename>.
 356 </para>
 357 </sect3>
 358
 359 </sect2>
 360
 361 <!--   ~~~~~       New section      ~~~~~     -->
 362 <sect2 id="installation-source"><title>Building from Source</title>
 363
 364 <para>
 365  The most convenient way to obtain the <application>Privoxy</application> sources
 366  is to download the source tarball from our <ulink url="http://sf.net/projects/ijbswa/">project
 367  page</ulink>.
 368 </para>
 369
 370 <para>
 371  If you like to live on the bleeding edge and are not afraid of using
 372  possibly unstable development versions, you can check out the up-to-the-minute
 373  version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
 374  CVS repository</ulink>.
 375 <!--
 376  deprecated...out of business.
 377  or simply download <ulink
 378  url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.bz2">the nightly CVS
 379  tarball.</ulink>
 380 -->
 381 </para>
 382
 383 <!-- include buildsource.sgml boilerplate: -->
 384 &buildsource;
 385 <!-- end boilerplate -->
 386
 387 </sect2>
 388 <!--   ~~~~~       New section      ~~~~~     -->
 389 <sect2 id="installation-keepupdated"><title>Keeping your Installation Up-to-Date</title>
 390 <para>
 391  As user feedback comes in and development continues, we will make updated versions
 392  of both the main <link linkend="actions-file">actions file</link> (as a <ulink
 393  url="http://sourceforge.net/project/showfiles.php?group_id=11118&amp;release_id=103670">separate
 394  package</ulink>) and the software itself (including the actions file) available for
 395  download.
 396 </para>
 397
 398 <para>
 399  If you wish to receive an email notification whenever we release updates of
 400  <application>Privoxy</application> or the actions file, <ulink
 401  url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce/">subscribe
 402  to our announce  mailing list</ulink>, ijbswa-announce@lists.sourceforge.net.
 403 </para>
 404
 405 <para>
 406  In order not to lose your personal changes and adjustments when updating
 407  to the latest <literal>default.action</literal> file we <emphasis>strongly
 408  recommend</emphasis> that you use <literal>user.action</literal> and
 409  <literal>user.filter</literal> for your local
 410  customizations of <application>Privoxy</application>. See the <link
 411  linkend="actions-file">Chapter on actions files</link> for details.
 412 </para>
 413
 414 </sect2>
 415
 416
 417 </sect1>
 418
 419 <!--  ~  End section  ~  -->
 420
 421 <!--   ~~~~~       New section      ~~~~~     -->
 422 <sect1 id="whatsnew">
 423 <title>What's New in this Release</title>
 424 <para>
 425  There are many improvements and new features since the last <application>Privoxy</application> stable release:
 426 </para>
 427
 428 <para>
 429  <itemizedlist>
 430   <listitem>
 431    <para>
 432     Multiple <link linkend="filter-file">filter files</link> can now be specified in <filename>config</filename>. This allows for
 433     locally defined filters that can be maintained separately from the filters as
 434     supplied by the developers, i.e. <filename>default.filter</filename>.
 435    </para>
 436   </listitem>
 437
 438  <listitem>
 439   <para>
 440    There are a number of new <link linkend="actions-file">actions</link>:
 441   </para>
 442
 443   <para>
 444   <itemizedlist>
 445
 446      <listitem>
 447       <para>
 448        <literal><link linkend="content-type-overwrite">content-type-overwrite</link></literal>
 449       </para>
 450      </listitem>
 451      <listitem>
 452       <para>
 453        <literal><link linkend="crunch-client-header">crunch-client-header</link></literal>
 454       </para>
 455      </listitem>
 456      <listitem>
 457       <para>
 458        <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>
 459       </para>
 460      </listitem>
 461      <listitem>
 462       <para>
 463        <literal><link linkend="crunch-server-header">crunch-server-header</link></literal>
 464       </para>
 465      </listitem>
 466      <listitem>
 467       <para>
 468        <literal><link linkend="filter-client-headers">filter-client-headers</link></literal>
 469       </para>
 470      </listitem>
 471      <listitem>
 472       <para>
 473        <literal><link linkend="filter-server-headers">filter-server-headers</link></literal>
 474       </para>
 475      </listitem>
 476      <listitem>
 477       <para>
 478        <literal><link linkend="force-text-mode">force-text-mode</link></literal>
 479       </para>
 480      </listitem>
 481      <listitem>
 482       <para>
 483        <literal><link linkend="handle-as-empty-document">handle-as-empty-document</link></literal>
 484       </para>
 485      </listitem>
 486      <listitem>
 487       <para>
 488        <literal><link linkend="hide-accept-language">hide-accept-language</link></literal>
 489       </para>
 490      </listitem>
 491      <listitem>
 492       <para>
 493        <literal><link linkend="hide-content-disposition">hide-content-disposition</link></literal>
 494       </para>
 495      </listitem>
 496      <listitem>
 497       <para>
 498        <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
 499       </para>
 500      </listitem>
 501     <listitem>
 502       <para>
 503        <literal><link linkend="inspect-jpegs">inspect-jpegs</link></literal>
 504       </para>
 505      </listitem>
 506      <listitem>
 507       <para>
 508        <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>
 509       </para>
 510      </listitem>
 511      <listitem>
 512       <para>
 513        <literal><link linkend="redirect">redirect</link></literal>
 514       </para>
 515      </listitem>
 516      <listitem>
 517       <para>
 518        <literal><link linkend="treat-forbidden-connects-like-blocks">treat-forbidden-connects-like-blocks</link></literal>
 519       </para>
 520      </listitem>
 521
 522   </itemizedlist>
 523   </para>
 524   <para>
 525      In addition, <literal><link linkend="fast-redirects">fast-redirects</link></literal>
 526      has been significantly improved with enhanced syntax.
 527   </para>
 528    <para>
 529      And <literal><link linkend="hide-referrer">hide-referrer</link></literal>
 530      has a new option, <literal>conditional block</literal>.
 531    </para>
 532
 533  </listitem>
 534
 535   <listitem>
 536    <para>
 537     <application>MS-Windows</application> versions can now be
 538     <link
 539     linkend="installation-pack-win">installed and
 540     started as a <emphasis>Windows service</emphasis></link>.
 541    </para>
 542   </listitem>
 543
 544   <listitem>
 545    <para>
 546     <filename>config</filename> has two new options:
 547     <link
 548     linkend="enable-remote-http-toggle">enable-remote-http-toggle</link>,
 549     and <link
 550     linkend="forwarded-connect-retries">forwarded-connect-retries</link>.
 551    </para>
 552    <para>
 553     And there is improved handling of the <link
 554     linkend="user-manual">user-manual</link>
 555     option, for placing documentation and help files on the local system.
 556    </para>
 557   </listitem>
 558
 559   <listitem>
 560    <para>
 561     There are six new <link linkend="FILTER">filters</link>.
 562    </para>
 563   </listitem>
 564
 565   <listitem>
 566    <para>
 567     Actions files problems and suggestions are now being directed to:
 568     <ulink url="http://sourceforge.net/tracker/?group_id=11118&amp;atid=460288">http://sourceforge.net/tracker/?group_id=11118&amp;atid=460288</ulink>.
 569     Please use this to report such configuration related problems as missed
 570     ads, sites that don't function properly due to one action or another,
 571     innocent images being blocked, etc.
 572    </para>
 573   </listitem>
 574
 575   <listitem>
 576    <para>
 577     In addition, there are numerous bug fixes and significant enhancements,
 578     including error pages should no longer be cached if the problem is fixed,
 579     much better DNS error handling, and various logging improvements.
 580    </para>
 581   </listitem>
 582
 583   <listitem>
 584    <para>
 585     The default actions setting is now <literal>Cautious</literal>. Previous
 586     releases had a default setting of <literal>Medium</literal>. Experienced
 587     users may want to adjust this, as it is fairly conservative by &my-app;
 588     standards and past practices. See <ulink
 589     url="http://config.privoxy.org/edit-actions-list?f=default">
 590     http://config.privoxy.org/edit-actions-list?f=default</ulink>. New users
 591     should try the default settings for a while before turning up the volume.
 592    </para>
 593   </listitem>
 594
 595  </itemizedlist>
 596 </para>
 597
 598 <!--   ~~~~~       New section      ~~~~~     -->
 599
 600 <sect2 id="upgradersnote">
 601 <title>Note to Upgraders</title>
 602
 603 <para>
 604  A quick list of things to be aware of before upgrading from earlier
 605  versions of <application>Privoxy</application>:
 606 </para>
 607
 608 <para>
 609  <itemizedlist>
 610
 611  <listitem>
 612   <para>
 613     Some installers may remove earlier versions completely, including
 614     configuration files. Save any important configuration files!
 615   </para>
 616  </listitem>
 617  <listitem>
 618   <para>
 619    On the other hand, other installers may not overwrite any existing configuration
 620    files, thinking you will want to do that. You may want to manually check
 621    your saved files against the newer versions to see if the improvements have
 622    merit, or whether there are new options that you may want to consider.
 623    There are a number of new features, but most won't be available unless
 624    these features are incorporated into your configuration somehow.
 625   </para>
 626  </listitem>
 627  <listitem>
 628     <para>
 629      See the full documentation on
 630      <literal><link linkend="fast-redirects">fast-redirects</link></literal>
 631      which has changed syntax, and will require adjustments to local configs,
 632      such as <filename>user.action</filename>. You must reference the new
 633      syntax:
 634    </para>
 635    <para>
 636  <screen>
 637   { +fast-redirects{check-decoded-url} }
 638    .example.com
 639    mybank.com
 640    .google.</screen>
 641 </para>
 642
 643   </listitem>
 644  <listitem>
 645     <para>
 646      The <filename>jarfile</filename>,
 647      <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> logger, is off by default now.
 648     </para>
 649   </listitem>
 650
 651  <listitem>
 652   <para>
 653    What constitutes a <quote>default</quote> configuration has changed,
 654    and you may want to review which actions are <quote>on</quote> by
 655    default. This is primarily a matter of emphasis, but some features
 656    you may have been used to, may now be <quote>off</quote> by default.
 657    There are also a number of new actions and filters you may want to
 658    consider, most of which are not incorporated into the default settings as
 659    yet (see above).
 660   </para>
 661  </listitem>
 662
 663   <listitem>
 664   <para>
 665 <!-- I think it is best to keep this somewhat vague, in case  -->
 666 <!-- the situation changes under our feet. -->
 667    Some installers may not automatically start
 668    <application>Privoxy</application> after installation.
 669   </para>
 670  </listitem>
 671
 672  </itemizedlist>
 673 </para>
 674 </sect2>
 675 </sect1>
 676
 677 <!--   ~~~~~       New section      ~~~~~     -->
 678 <sect1 id="quickstart"><title>Quickstart to Using Privoxy</title>
 679 <para>
 680  <itemizedlist>
 681
 682  <listitem>
 683   <para>
 684   Install <application>Privoxy</application>. See the <link
 685   linkend="installation">Installation Section</link> below for platform specific
 686   information.
 687  </para>
 688  </listitem>
 689
 690  <listitem>
 691   <para>
 692    Advanced users and those who want to offer <application>Privoxy</application>
 693    service to more than just their local machine should check the <link
 694    linkend="config">main config file</link>, especially the <link
 695    linkend="access-control">security-relevant</link> options. These are
 696    off by default.
 697   </para>
 698  </listitem>
 699
 700  <listitem>
 701   <para>
 702   Start <application>Privoxy</application>, if the installation program has
 703   not done this already (may vary according to platform). See the section
 704   <link linkend="startup">Starting <application>Privoxy</application></link>.
 705   </para>
 706  </listitem>
 707
 708  <listitem>
 709   <para>
 710    Set your browser to use <application>Privoxy</application> as HTTP and
 711    HTTPS (SSL)  <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>
 712    by setting the proxy configuration for address of
 713    <literal>127.0.0.1</literal> and port <literal>8118</literal>.
 714    <emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or
 715    any protocols besides HTTP and HTTPS (SSL)! It won't work!
 716   </para>
 717  </listitem>
 718
 719  <listitem>
 720   <para>
 721     Flush your browser's disk and memory caches, to remove any cached ad images.
 722     If using <application>Privoxy</application> to manage
 723     <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
 724     you should remove any currently stored cookies too.
 725   </para>
 726  </listitem>
 727
 728  <listitem>
 729   <para>
 730    A default installation should provide a reasonable starting point for
 731    most. There will undoubtedly be occasions where you will want to adjust the
 732    configuration, but that can be dealt with as the need arises. Little
 733    to no initial configuration is required in most cases.
 734   </para>
 735   <para>
 736    See the <link linkend="configuration">Configuration section</link> for more
 737    configuration options, and how to customize your installation.
 738    You might also want to look at the <link
 739    linkend="quickstart-ad-blocking">next section</link> for a quick
 740    introduction to how <application>Privoxy</application> blocks ads and
 741    banners.
 742 </para>
 743  </listitem>
 744
 745  <listitem>
 746   <para>
 747     If you experience ads that slip through, innocent images that are
 748     blocked, or otherwise feel the need to fine-tune
 749     <application>Privoxy's</application> behavior, take a look at the <link
 750     linkend="actions-file">actions files</link>. As a quick start, you might
 751     find the <link linkend="act-examples">richly commented examples</link>
 752     helpful. You can also view and edit the actions files through the <ulink
 753     url="http://config.privoxy.org">web-based user interface</ulink>. The
 754     Appendix <quote><link linkend="actionsanat">Troubleshooting: Anatomy of an
 755     Action</link></quote> has hints on how to understand and debug actions that
 756     <quote>misbehave</quote>.
 757   </para>
 758  </listitem>
 759
 760  <listitem>
 761   <para>
 762    For easy access to &my-app;'s most important controls, drag the provided
 763    <link linkend="bookmarklets">Bookmarklets</link> into your browser's
 764    personal toolbar.
 765   </para>
 766  </listitem>
 767
 768  <listitem>
 769   <para>
 770    Please see the section <link linkend="contact">Contacting the
 771    Developers</link> on how to report bugs, problems with websites or to get
 772    help.
 773   </para>
 774  </listitem>
 775
 776  <listitem>
 777   <para>
 778    Now enjoy surfing with enhanced control, comfort and privacy!
 779   </para>
 780  </listitem>
 781
 782  </itemizedlist>
 783 </para>
 784
 785
 786 <!--   ~~~~~       New section      ~~~~~     -->
 787
 788 <sect2 id="quickstart-ad-blocking">
 789 <title>Quickstart to Ad Blocking</title>
 790 <!--
 791  NOTE:  This section is deliberately redundant for those that don't
 792  want to read the whole thing (which is getting lengthy).
 793 -->
 794 <para>
 795  Ad blocking is but one of <application>Privoxy's</application>
 796  array of features. Many of these features are for the technically minded advanced
 797  user. But, ad and banner blocking is surely common ground for everybody.
 798 </para>
 799 <para>
 800  This section will provide a quick summary of ad blocking so
 801  you can get up to speed quickly without having to read the more extensive
 802  information provided below, though this is highly recommended.
 803 </para>
 804 <para>
 805  First a bit of a warning ... blocking ads is much like blocking SPAM: the
 806  more aggressive you are about it, the more likely you are to block
 807  things that were not intended. So there is a trade off here. If you want
 808  extreme ad free browsing, be prepared to deal with more
 809  <quote>problem</quote> sites, and to spend more time adjusting the
 810  configuration to solve these unintended consequences. In short, there is
 811  not an easy way to eliminate <emphasis>all</emphasis> ads. Either take
 812  the easy way and settle for <emphasis>most</emphasis> ads blocked with the
 813  default configuration, or jump in and tweak it for your personal surfing
 814  habits and preferences.
 815 </para>
 816 <para>
 817  Secondly, a brief explanation of <application>Privoxy's </application>
 818  <quote>actions</quote>. <quote>Actions</quote> in this context, are
 819  the directives we use to tell <application>Privoxy</application> to perform
 820  some task relating to HTTP transactions (i.e. web browsing). We tell
 821  <application>Privoxy</application> to take some <quote>action</quote>. Each
 822  action has a unique name and function. While there are many potential
 823  <application>actions</application> in <application>Privoxy's</application>
 824  arsenal, only a few are used for ad blocking. <link
 825  linkend="actions">Actions</link>, and <link linkend="actions-file">action
 826  configuration files</link>, are explained in depth below.
 827 </para>
 828 <para>
 829  Actions are specified in <application>Privoxy's</application> configuration,
 830  followed by one or more URLs to which the action should apply. URLs
 831  can actually be URL type <link linkend="af-patterns">patterns</link> that use
 832  wildcards so they can apply potentially to a range of similar URLs. The
 833  actions, together with the URL patterns are called a section.
 834 </para>
 835 <para>
 836  When you connect to a website, the full URL will either match one or more
 837  of the sections as defined in <application>Privoxy's</application> configuration,
 838  or not. If so, then <application>Privoxy</application> will perform the
 839  respective actions. If not, then nothing special happens. Furthermore, web
 840  pages may contain embedded, secondary URLs that your web browser will
 841  use to load additional components of the page, as it parses the
 842  original page's HTML content. An ad image for instance, is just an URL
 843  embedded in the page somewhere. The image itself may be on the same server,
 844  or a server somewhere else on the Internet. Complex web pages will have many
 845  such embedded URLs.
 846 </para>
 847
 848 <para>
 849  The actions we need to know about for ad blocking are:  <literal><link
 850  linkend="block">block</link></literal>, <literal><link
 851  linkend="handle-as-image">handle-as-image</link></literal>, and
 852  <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>:
 853 </para>
 854
 855 <para>
 856  <itemizedlist>
 857
 858  <listitem>
 859   <para>
 860    <literal><link linkend="block">block</link></literal> - this action stops
 861    any contact between your browser and any URL patterns that match this
 862    action's configuration. It can be used for blocking ads, but also anything
 863    that is determined to be unwanted. By itself, it simply stops any
 864    communication with the remote server and sends <application>Privoxy</application>'s
 865    own built-in BLOCKED page instead to let you now what has happened.
 866   </para>
 867  </listitem>
 868
 869  <listitem>
 870   <para>
 871    <literal><link linkend="handle-as-image">handle-as-image</link></literal> -
 872    tells <application>Privoxy</application> to treat this URL as an image.
 873    <application>Privoxy</application>'s default configuration already does this
 874    for all common image types (e.g. GIF), but there are many situations where this
 875    is not so easy to determine. So we'll force it in these cases. This is particularly
 876    important for ad blocking, since  only if we know that it's an image of
 877    some kind, can we replace it with an image of our choosing, instead of the
 878    <application>Privoxy</application> BLOCKED page (which would only result in
 879    a <quote>broken image</quote> icon). There are some limitations to this
 880    though. For instance, you can't just brute-force an image substitution for
 881    an entire HTML page in most situations.
 882   </para>
 883  </listitem>
 884
 885  <listitem>
 886   <para>
 887    <literal><link
 888    linkend="set-image-blocker">set-image-blocker</link></literal> - tells
 889    <application>Privoxy</application> what to display in place of an ad image that
 890    has hit a block rule. For this to come into play, the URL must match a
 891    <literal><link linkend="block">block</link></literal> action somewhere in the
 892    configuration, <emphasis>and</emphasis>, it must also match an
 893    <literal><link linkend="handle-as-image">handle-as-image</link></literal> action.
 894   </para>
 895   <para>
 896    The configuration options on what to display instead of the ad are:
 897   </para>
 898   <simplelist>
 899    <member>
 900     &nbsp;&nbsp;&nbsp;<emphasis>pattern</emphasis> - a checkerboard pattern, so that an ad
 901     replacement is obvious. This is the default.
 902    </member>
 903   </simplelist>
 904   <simplelist>
 905    <member>
 906     &nbsp;&nbsp;&nbsp;<emphasis>blank</emphasis> - A very small empty GIF image is displayed.
 907     This is the so-called <quote>invisible</quote> configuration option.
 908    </member>
 909   </simplelist>
 910   <simplelist>
 911    <member>
 912     &nbsp;&nbsp;&nbsp;<emphasis>http://&lt;URL&gt;</emphasis> - A redirect to any image anywhere
 913     of the user's choosing (advanced usage).
 914    </member>
 915   </simplelist>
 916   </listitem>
 917
 918 </itemizedlist>
 919 </para>
 920
 921 <para>
 922  The quickest way to adjust any of these settings is with your browser through
 923  the special <application>Privoxy</application> editor at <ulink
 924  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
 925  (shortcut: <ulink url="http://p.p/">http://p.p/show-status</ulink>). This
 926  is an internal page, and does not require Internet access. Select the
 927  appropriate <quote>actions</quote> file, and click
 928  <quote><guibutton>Edit</guibutton></quote>. It is best to put personal or
 929  local preferences in <filename>user.action</filename> since this is not
 930  meant to be overwritten during upgrades, and will over-ride the settings in
 931  other files. Here you can insert new <quote>actions</quote>, and URLs for ad
 932  blocking or other purposes, and make other adjustments to the configuration.
 933  <application>Privoxy</application> will detect these changes automatically.
 934 </para>
 935
 936 <para>
 937  A quick and simple step by step example:
 938 </para>
 939
 940 <para>
 941  <itemizedlist>
 942
 943   <listitem>
 944    <para>
 945      Right click on the ad image to be blocked, then select
 946      <quote><guimenuitem>Copy Link Location</guimenuitem></quote> from the
 947      pop-up menu.
 948    </para>
 949   </listitem>
 950   <listitem>
 951    <para>
 952     Set your browser to
 953     <ulink
 954  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
 955    </para>
 956   </listitem>
 957   <listitem>
 958    <para>
 959     Find <filename>user.action</filename> in the top section, and click
 960     on <quote><guibutton>Edit</guibutton></quote>:
 961    </para>
 962
 963  <!-- image of editor and actions files selections -->
 964  <para>
 965   <figure pgwide="0" float="0"><title>Actions Files in Use</title>
 966    <mediaobject>
 967      <imageobject>
 968       <imagedata  fileref="files-in-use.jpg" format="jpg">
 969        </imageobject>
 970        <textobject>
 971         <phrase>[ Screenshot of Actions Files in Use ]</phrase>
 972       </textobject>
 973    </mediaobject>
 974   </figure>
 975  </para>
 976  </listitem>
 977
 978  <listitem>
 979   <para>
 980    You should have a section with only
 981    <literal><link linkend="block">block</link></literal> listed under
 982    <quote>Actions:</quote>.
 983    If not, click a <quote><guibutton>Insert new section below</guibutton></quote>
 984    button, and in the new section that just appeared, click the
 985    <guibutton>Edit</guibutton> button right under the word <quote>Actions:</quote>.
 986    This will bring up a list of all actions. Find
 987    <literal><link linkend="block">block</link></literal> near the top, and click
 988    in the <quote>Enabled</quote> column, then <quote><guibutton>Submit</guibutton></quote>
 989    just below the list.
 990   </para>
 991  </listitem>
 992  <listitem>
 993   <para>
 994    Now, in the <literal><link linkend="block">block</link></literal> actions section,
 995    click the <quote><guibutton>Add</guibutton></quote> button, and paste the URL the
 996    browser got from <quote><guimenuitem>Copy Link Location</guimenuitem></quote>.
 997    Remove the <literal>http://</literal> at the beginning of the URL. Then, click
 998    <quote><guibutton>Submit</guibutton></quote> (or
 999    <quote><guibutton>OK</guibutton></quote> if in a pop-up window).
1000   </para>
1001  </listitem>
1002  <listitem>
1003   <para>
1004    Now go back to the original page, and press <keycap>SHIFT-Reload</keycap>
1005    (or flush all browser caches). The image should be gone now.
1006   </para>
1007  </listitem>
1008
1009  </itemizedlist>
1010 </para>
1011
1012 <para>
1013  This is a very crude and simple example. There might be good reasons to use a
1014  wildcard pattern match to include potentially similar images from the same
1015  site. For a more extensive explanation of <quote>patterns</quote>, and
1016  the entire actions concept, see <link linkend="actions-file">the Actions
1017  section</link>.
1018 </para>
1019
1020 <para>
1021  For advanced users who want to hand edit their config files, you might want
1022  to now go to the <link linkend="act-examples">Actions Files Tutorial</link>.
1023  The ideas explained therein also apply to the web-based editor.
1024 </para>
1025
1026 </sect2>
1027
1028 </sect1>
1029
1030 <!--  ~  End section  ~  -->
1031
1032
1033 <!--   ~~~~~       New section      ~~~~~     -->
1034 <sect1 id="startup">
1035 <title>Starting Privoxy</title>
1036 <para>
1037  Before launching <application>Privoxy</application> for the first time, you
1038  will want to configure your browser(s) to use
1039  <application>Privoxy</application> as a HTTP and HTTPS (SSL)
1040  <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>. The default is
1041  127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
1042  used port 8000). This is the one configuration step <emphasis>that must be done
1043 </emphasis>!
1044 </para>
1045 <para>
1046  Please note that <application>Privoxy</application> can only proxy HTTP and
1047  HTTPS traffic. It will not work with FTP or other protocols.
1048 </para>
1049
1050  <!-- image of Mozilla Proxy configuration -->
1051  <para>
1052   <figure pgwide="0" float="0"><title>Proxy Configuration Showing
1053   Mozilla/Netscape HTTP and HTTPS (SSL) Settings</title>
1054    <mediaobject>
1055      <imageobject>
1056       <imagedata  fileref="proxy_setup.jpg" format="jpg">
1057        </imageobject>
1058        <textobject>
1059         <phrase>[ Screenshot of Mozilla Proxy Configuration ]</phrase>
1060       </textobject>
1061    </mediaobject>
1062   </figure>
1063  </para>
1064
1065
1066 <para>
1067  With <application>Firefox</application>, this can be set under:
1068 </para>
1069
1070 <literallayout>
1071  <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> -> <guibutton>General</guibutton> -> <guibutton>Connection Settings</guibutton> -> <guibutton>Manual Proxy Configuration</guibutton>
1072
1073 </literallayout>
1074
1075
1076 <para>
1077  With <application>Netscape</application> (and
1078  <application>Mozilla</application>), this can be set under:
1079 </para>
1080
1081
1082 <literallayout>
1083 <!-- Mix ascii and gui art, something for everybody -->
1084 <!-- spacing on this is tricky -->
1085  <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Proxies</guibutton> -> <guibutton>HTTP Proxy</guibutton>
1086
1087 </literallayout>
1088
1089 <para>
1090  For <application>Internet Explorer v.5-6</application>:
1091 </para>
1092
1093 <literallayout>
1094  <guibutton>Tools</guibutton> -> <guibutton>Internet Options</guibutton> -> <guibutton>Connections</guibutton> -> <guibutton>LAN Settings</guibutton>
1095 </literallayout>
1096
1097 <para>
1098  Then, check <quote>Use Proxy</quote> and fill in the appropriate info
1099  (Address: 127.0.0.1, Port: 8118). Include HTTPS (SSL), if you want HTTPS
1100  proxy support too (sometimes labeled <quote>Secure</quote>). Make sure any
1101  checkboxes like <quote>Use the same proxy server for all protocols</quote> is
1102  <emphasis>UNCHECKED</emphasis>. You want only HTTP and HTTPS (SSL)!
1103 </para>
1104
1105  <!-- image of IE Proxy configuration -->
1106  <para>
1107   <figure pgwide="0" float="0"><title>Proxy Configuration Showing
1108   Internet Explorer HTTP and HTTPS (Secure) Settings</title>
1109    <mediaobject>
1110      <imageobject>
1111       <imagedata  fileref="proxy2.jpg" format="jpg">
1112        </imageobject>
1113        <textobject>
1114         <phrase>[ Screenshot of IE Proxy Configuration ]</phrase>
1115       </textobject>
1116    </mediaobject>
1117   </figure>
1118  </para>
1119
1120
1121 <para>
1122  After doing this, flush your browser's disk and memory caches to force a
1123  re-reading of all pages and to get rid of any ads that may be cached. Remove
1124  any <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
1125  if you want <application>Privoxy</application> to manage that. You are now
1126  ready to start enjoying the benefits of using
1127  <application>Privoxy</application>!
1128 </para>
1129
1130 <para>
1131  <application>Privoxy</application> itself is typically started by specifying the
1132  main configuration file to be used on the command line. If no configuration
1133  file is specified on the command line, <application>Privoxy</application>
1134  will look for a file named <filename>config</filename> in the current
1135  directory. Except on Win32 where it will try <filename>config.txt</filename>.
1136 </para>
1137
1138 <sect2 id="start-redhat">
1139 <title>Red Hat, Fedora and Conectiva</title>
1140 <para>
1141  A default Red Hat installation may not start &my-app; upon boot. It will use
1142  the file <filename>/etc/privoxy/config</filename> as its main configuration
1143  file.
1144 </para>
1145 <para>
1146  <screen>
1147  # /etc/rc.d/init.d/privoxy start
1148 </screen>
1149 </para>
1150 <para>
1151  Or ...
1152 </para>
1153 <para>
1154  <screen>
1155  # service privoxy start
1156 </screen>
1157 </para>
1158 </sect2>
1159
1160 <sect2 id="start-debian">
1161 <title>Debian</title>
1162 <para>
1163  We use a script. Note that Debian typically starts &my-app; upon booting per
1164  default.  It will use the file
1165  <filename>/etc/privoxy/config</filename> as its main configuration
1166  file.
1167 </para>
1168 <para>
1169  <screen>
1170  # /etc/init.d/privoxy start
1171 </screen>
1172 </para>
1173 </sect2>
1174
1175 <sect2 id="start-suse">
1176 <title>SuSE</title>
1177 <para>
1178 We use a script. It will use the file <filename>/etc/privoxy/config</filename>
1179 as its main configuration file. Note that SuSE starts Privoxy upon booting
1180 your PC.
1181 </para>
1182 <para>
1183  <screen>
1184  # rcprivoxy start
1185 </screen>
1186 </para>
1187 </sect2>
1188
1189 <sect2 id="start-windows">
1190 <title>Windows</title>
1191 <para>
1192 Click on the &my-app; Icon to start <application>Privoxy</application>. If no configuration file is
1193  specified on the command line, <application>Privoxy</application> will look
1194  for a file named <filename>config.txt</filename>. Note that Windows will
1195  automatically start &my-app; when the system starts if you chose that option
1196  when installing.
1197 </para>
1198 <para>
1199  <application>Privoxy</application> can run with full Windows service functionality.
1200  On Windows only, the &my-app; program has two new command line arguments
1201  to install and uninstall &my-app; as a service. See the
1202  <link linkend="installation-pack-win">Windows Installation
1203  instructions</link> for details.
1204 </para>
1205 </sect2>
1206
1207 <sect2 id="start-unices">
1208 <title>Solaris, NetBSD, FreeBSD, HP-UX and others</title>
1209 <para>
1210 Example Unix startup command:
1211 </para>
1212 <para>
1213  <screen>
1214  # /usr/sbin/privoxy /etc/privoxy/config
1215 </screen>
1216 </para>
1217 </sect2>
1218
1219 <sect2 id="start-os2">
1220 <title>OS/2</title>
1221 <para>
1222  During installation, <application>Privoxy</application> is configured to
1223  start automatically when the system restarts. You can start it manually by
1224  double-clicking on the <application>Privoxy</application> icon in the
1225  <application>Privoxy</application> folder.
1226 </para>
1227 </sect2>
1228
1229 <sect2 id="start-macosx">
1230 <title>Mac OSX</title>
1231 <para>
1232  During installation, <application>Privoxy</application> is configured to
1233  start automatically when the system restarts.  To start &my-app; manually,
1234  double-click on the <literal>StartPrivoxy.command</literal> icon in the
1235  <literal>/Library/Privoxy</literal> folder.  Or, type this command
1236  in the Terminal:
1237 </para>
1238 <para>
1239   <screen>
1240   /Library/Privoxy/StartPrivoxy.command
1241   </screen>
1242 </para>
1243 <para>
1244  You will be prompted for the administrator password.
1245 </para>
1246 </sect2>
1247
1248
1249 <sect2 id="start-amigaos">
1250 <title>AmigaOS</title>
1251 <para>
1252  Start <application>Privoxy</application> (with RUN &lt;&gt;NIL:) in your
1253  <filename>startnet</filename> script (AmiTCP), in
1254  <filename>s:user-startup</filename> (RoadShow), as startup program in your
1255  startup script (Genesis), or as startup action (Miami and MiamiDx).
1256  <application>Privoxy</application> will automatically quit when you quit your
1257  TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
1258  <application>Privoxy</application> is still running).
1259 </para>
1260 </sect2>
1261
1262 <sect2 id="start-gentoo">
1263 <title>Gentoo</title>
1264 <para>
1265  A script is again used. It will use the file <filename>/etc/privoxy/config
1266  </filename> as its main configuration file.
1267 </para>
1268 <para>
1269  <screen>
1270  /etc/init.d/privoxy start
1271  </screen>
1272 </para>
1273 <para>
1274  Note that <application>Privoxy</application> is not automatically started at
1275  boot time by default. You can change this with the <literal>rc-update</literal>
1276  command.
1277 </para>
1278 <para>
1279  <screen>
1280  rc-update add privoxy default
1281  </screen>
1282 </para>
1283 </sect2>
1284
1285 <!--
1286
1287 <para>
1288  See the section <link linkend="cmdoptions">Command line options</link> for
1289  further info.
1290 </para>
1291
1292 must find a better place for this paragraph
1293
1294 <para>
1295  The included default configuration files should give a reasonable starting
1296  point. Most of the per site configuration is done in the
1297  <ulink url="actions-file.html"><quote>actions</quote></ulink> files. These are
1298  where various cookie actions are defined, ad and banner blocking, and other
1299  aspects of <application>Privoxy</application> configuration. There are several
1300  such files included, with varying levels of aggressiveness.
1301 </para>
1302
1303 <para>
1304  You will probably want to keep an eye out for sites for which you may prefer
1305  persistent cookies, and add these to your actions configuration as needed. By
1306  default, most of these will be accepted only during the current browser
1307  session (aka <quote>session cookies</quote>), unless you add them to the
1308  configuration. If you want the browser to handle this instead, you will need
1309  to edit <filename>user.action</filename> (or through the web based interface)
1310  and disable this feature. If you use more than one browser, it would make
1311  more sense to let <application>Privoxy</application> handle this. In which
1312  case, the browser(s) should be set to accept all cookies.
1313 </para>
1314
1315 <para>
1316  Another feature where you will probably want to define exceptions for trusted
1317  sites is the popup-killing (through the <ulink
1318  url="actions-file.html#KILL-POPUPS"><quote>+kill-popups</quote></ulink> and
1319  <ulink
1320  url="actions-file.html#FILTER-POPUPS"><quote>+filter{popups}</quote></ulink>
1321  actions), because your favorite shopping, banking, or leisure site may need
1322  popups (explained below).
1323 </para>
1324
1325 <para>
1326  <application>Privoxy</application> is HTTP/1.1 compliant,  but not all of
1327  the optional 1.1 features are as yet supported. In the unlikely event that
1328  you experience inexplicable problems with browsers that use HTTP/1.1 per default
1329  (like <application>Mozilla</application> or recent versions of I.E.), you might
1330  try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit -&gt;
1331  Preferences -&gt; Debug -&gt; Networking</literal>.
1332  Alternatively, set the <quote>+downgrade-http-version</quote> config option in
1333  <filename>default.action</filename> which will downgrade your browser's HTTP
1334  requests from HTTP/1.1 to HTTP/1.0 before processing them.
1335 </para>
1336
1337 <para>
1338  After running <application>Privoxy</application> for a while, you can
1339  start to fine tune the configuration to suit your personal, or site,
1340  preferences and requirements. There are many, many aspects that can
1341  be customized. <quote>Actions</quote>
1342  can be adjusted by pointing your browser to
1343  <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
1344  (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
1345  and then follow the link to <quote>View &#38; Change the Current Configuration</quote>.
1346  (This is an internal page and does not require Internet access.)
1347 </para>
1348
1349 <para>
1350  In fact, various aspects of <application>Privoxy</application>
1351  configuration can be viewed from this page, including
1352  current configuration parameters, source code version numbers,
1353  the browser's request headers, and <quote>actions</quote> that apply
1354  to a given URL. In addition to the actions file
1355  editor mentioned above, <application>Privoxy</application> can also
1356  be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
1357 </para>
1358
1359 <para>
1360  If you encounter problems, try loading the page without
1361  <application>Privoxy</application>. If that helps, enter the URL where
1362  you have the problems into <ulink url="http://p.p/show-url-info">the browser
1363  based rule tracing utility</ulink>. See which rules apply and why, and
1364  then try turning them off for that site one after the other, until the problem
1365  is gone. When you have found the culprit, you might want to turn the rest on
1366  again.
1367 </para>
1368
1369 <para>
1370  If the above paragraph sounds gibberish to you, you might want to <link
1371  linkend="actions-file">read more about the actions concept</link>
1372  or even dive deep into the <link linkend="actionsanat">Appendix
1373  on actions</link>.
1374 </para>
1375
1376 <para>
1377  If you can't get rid of the problem at all, think you've found a bug in
1378  Privoxy, want to propose a new feature or smarter rules, please see the
1379  section <link linkend="contact"><quote>Contacting the
1380  Developers</quote></link> below.
1381 </para>
1382
1383 -->
1384
1385 <!--   ~~~~~       New section      ~~~~~     -->
1386 <sect2 id="cmdoptions">
1387 <title>Command Line Options</title>
1388 <para>
1389  <application>Privoxy</application> may be invoked with the following
1390  command-line options:
1391 </para>
1392
1393 <para>
1394  <itemizedlist>
1395
1396  <listitem>
1397   <para>
1398     <emphasis>--version</emphasis>
1399   </para>
1400   <para>
1401      Print version info and exit. Unix only.
1402   </para>
1403  </listitem>
1404  <listitem>
1405   <para>
1406     <emphasis>--help</emphasis>
1407   </para>
1408   <para>
1409    Print short usage info and exit. Unix only.
1410   </para>
1411  </listitem>
1412  <listitem>
1413   <para>
1414    <emphasis>--no-daemon</emphasis>
1415   </para>
1416   <para>
1417    Don't become a daemon, i.e. don't fork and become process group
1418    leader, and don't detach from controlling tty. Unix only.
1419   </para>
1420  </listitem>
1421  <listitem>
1422   <para>
1423    <emphasis>--pidfile FILE</emphasis>
1424
1425   </para>
1426   <para>
1427    On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
1428    <emphasis>FILE</emphasis> on exit. Failure to create or delete the
1429    <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
1430    option is given, no PID file will be used. Unix only.
1431   </para>
1432  </listitem>
1433  <listitem>
1434   <para>
1435    <emphasis>--user USER[.GROUP]</emphasis>
1436
1437   </para>
1438   <para>
1439    After (optionally) writing the PID file, assume the user  ID  of
1440    <emphasis>USER</emphasis>, and if included the GID of GROUP.  Exit if the
1441    privileges are not sufficient to do so. Unix only.
1442   </para>
1443  </listitem>
1444   <listitem>
1445   <para>
1446    <emphasis>--chroot</emphasis>
1447
1448   </para>
1449   <para>
1450    Before changing to the user ID given in the <emphasis>--user</emphasis> option,
1451    chroot to that user's home directory, i.e. make the kernel pretend to the &my-app;
1452    process that the directory tree starts there. If set up carefully, this can limit
1453    the impact of possible vulnerabilities in &my-app; to the files contained in that hierarchy.
1454    Unix only.
1455   </para>
1456  </listitem>
1457  <listitem>
1458   <para>
1459     <emphasis>configfile</emphasis>
1460   </para>
1461   <para>
1462     If no <emphasis>configfile</emphasis> is included on the command line,
1463     <application>Privoxy</application> will look for a file named
1464     <quote>config</quote> in the current directory (except on Win32
1465     where it will look for <quote>config.txt</quote> instead). Specify
1466     full path to avoid confusion. If no config file is found,
1467     <application>Privoxy</application> will fail to start.
1468   </para>
1469  </listitem>
1470
1471  </itemizedlist>
1472 </para>
1473
1474 <para>
1475  On <application>MS Windows</application> only there are two additional
1476  command-line options to allow <application>Privoxy</application> to install and
1477  run as a <emphasis>service</emphasis>. See the
1478 <link linkend="installation-pack-win">Window Installation section</link>
1479 for details.
1480 </para>
1481
1482 </sect2>
1483
1484 </sect1>
1485
1486 <!--  ~  End section  ~  -->
1487
1488
1489 <!--   ~~~~~       New section      ~~~~~     -->
1490 <sect1 id="configuration"><title>Privoxy Configuration</title>
1491  <para>
1492   All <application>Privoxy</application> configuration is stored
1493   in text files. These files can be edited with a text editor.
1494   Many important aspects of <application>Privoxy</application> can
1495   also be controlled easily with a web browser.
1496  </para>
1497
1498
1499 <!--   ~~~~~       New section      ~~~~~     -->
1500
1501 <sect2>
1502 <title>Controlling Privoxy with Your Web Browser</title>
1503 <para>
1504  <application>Privoxy</application>'s user interface can be reached through the special
1505  URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
1506  (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
1507  which is a built-in page and works without Internet access.
1508  You will see the following section:
1509
1510 </para>
1511
1512 <!-- Needs to be put in a table and colorized  -->
1513 <screen>
1514  <msgtext>
1515  <bridgehead renderas="sect2">&nbsp;&nbsp;&nbsp;&nbsp;Privoxy Menu</bridgehead>
1516
1517  <simplelist>
1518  <member>
1519   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/show-status">View & change the current configuration</ulink>
1520  </member>
1521  <member>
1522   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/show-version">View the source code version numbers</ulink>
1523  </member>
1524  <member>
1525   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
1526  </member>
1527  <member>
1528   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/show-url-info">Look up which actions apply to a URL and why</ulink>
1529  </member>
1530  <member>
1531   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
1532  </member>
1533  <member>
1534   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://www.privoxy.org/
1535   &p-version;/user-manual/">Documentation</ulink>
1536  </member>
1537  </simplelist>
1538  </msgtext>
1539 </screen>
1540
1541
1542 <para>
1543  This should be self-explanatory. Note the first item leads to an editor for the
1544  <link linkend="actions-file">actions files</link>, which is where the ad, banner,
1545  cookie, and URL blocking magic is configured as well as other advanced features of
1546  <application>Privoxy</application>. This is an easy way to adjust various
1547  aspects of <application>Privoxy</application> configuration. The actions
1548  file, and other configuration files, are explained in detail below.
1549 </para>
1550
1551 <para>
1552  <quote>Toggle Privoxy On or Off</quote> is handy for sites that might
1553  have problems with your current actions and filters. You can in fact use
1554  it as a test to see whether it is <application>Privoxy</application>
1555  causing the problem or not. <application>Privoxy</application> continues
1556  to run as a proxy in this case, but all manipulation is disabled, i.e.
1557  <application>Privoxy</application> acts like a normal forwarding proxy. There
1558  is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
1559  that you can toggle <application>Privoxy</application> with one click from
1560  your browser.
1561 </para>
1562
1563 </sect2>
1564
1565 <!--  ~  End section  ~  -->
1566
1567
1568
1569
1570 <!--   ~~~~~       New section      ~~~~~     -->
1571
1572 <sect2 id="confoverview">
1573 <title>Configuration Files Overview</title>
1574 <para>
1575  For Unix, *BSD and Linux, all configuration files are located in
1576  <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
1577  AmigaOS these are all in the same directory as the
1578  <application>Privoxy</application> executable. <![%p-not-stable;[ The name
1579  and number of configuration files has changed from previous versions, and is
1580  subject to change as development progresses.]]>
1581 </para>
1582
1583 <para>
1584  The installed defaults provide a reasonable starting point, though
1585  some settings may be aggressive by some standards. For the time being, the
1586  principle configuration files are:
1587 </para>
1588
1589 <para>
1590  <itemizedlist>
1591
1592   <listitem>
1593    <para>
1594      The <link linkend="config">main configuration file</link> is named <filename>config</filename>
1595      on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
1596      on Windows. This is a required file.
1597    </para>
1598   </listitem>
1599
1600   <listitem>
1601    <para>
1602     <filename>default.action</filename> (the main <link linkend="actions-file">actions file</link>)
1603     is used to define which <quote>actions</quote> relating to banner-blocking, images, pop-ups,
1604     content modification, cookie handling etc should be applied by default. It also defines many
1605     exceptions (both positive and negative) from this default set of actions that enable
1606     <application>Privoxy</application> to selectively eliminate the junk, and only the junk, on
1607     as many websites as possible.
1608    </para>
1609    <para>
1610     Multiple actions files may be defined in <filename>config</filename>. These
1611     are processed in the order they are defined. Local customizations and locally
1612     preferred exceptions to the default policies  as defined in
1613     <filename>default.action</filename> (which you will most probably want
1614     to define sooner or later) are probably best applied in
1615     <filename>user.action</filename>, where you can preserve them across
1616     upgrades. <filename>standard.action</filename> is for
1617     <application>Privoxy's</application> internal use.
1618    </para>
1619    <para>
1620     There is also a web based editor that can be accessed from
1621     <ulink
1622     url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
1623     (Shortcut: <ulink
1624     url="http://p.p/show-status">http://p.p/show-status</ulink>) for the
1625     various actions files.
1626    </para>
1627   </listitem>
1628
1629   <listitem>
1630    <para>
1631     <quote>Filter files</quote> (the <link linkend="filter-file">filter
1632     file</link>) can be used to re-write the raw page content, including
1633     viewable text as well as embedded HTML and JavaScript, and whatever else
1634     lurks on any given web page. The filtering jobs are only pre-defined here;
1635     whether to apply them or not is up to the actions files.
1636     <filename>default.filter</filename> includes various filters made
1637     available for use by the developers. Some are much more intrusive than
1638     others, and all should be used with caution. You may define additional
1639     filter files in <filename>config</filename> as you can with
1640     actions files. We suggest <filename>user.filter</filename> for any
1641     locally defined filters or customizations.
1642    </para>
1643   </listitem>
1644
1645  </itemizedlist>
1646 </para>
1647
1648 <para>
1649  The syntax of all configuration files has remained the same throughout the
1650  3.x series. There have been enhancements, but no changes that would preclude
1651  the use of any configuration file from one version to the next. (There is
1652  one exception: <link linkend="FAST-REDIRECTS">+fast-redirects</link> which
1653  has enhanced syntax and will require updating any local configs from earlier
1654  versions.)
1655 </para>
1656
1657 <para>
1658  All files use the <quote><literal>#</literal></quote> character to denote a
1659  comment (the rest of the line will be ignored) and understand line continuation
1660  through placing a backslash ("<literal>\</literal>") as the very last character
1661  in a line. If the <literal>#</literal> is preceded by a backslash, it looses
1662  its special function. Placing a <literal>#</literal> in front of an otherwise
1663  valid configuration line to prevent it from being interpreted is called "commenting
1664  out" that line. Blank lines are ignored.
1665 </para>
1666
1667 <para>
1668  The actions files and filter files
1669  can use Perl style <link linkend="regex">regular expressions</link> for
1670  maximum flexibility.
1671 </para>
1672
1673 <para>
1674  After making any changes, there is no need to restart
1675  <application>Privoxy</application> in order for the changes to take
1676  effect. <application>Privoxy</application> detects such changes
1677  automatically. Note, however, that it may take one or two additional
1678  requests for the change to take effect. When changing the listening address
1679  of <application>Privoxy</application>, these <quote>wake up</quote> requests
1680  must obviously be sent to the <emphasis>old</emphasis> listening address.
1681 </para>
1682
1683 <![%p-not-stable;[
1684 <para>
1685  While under development, the configuration content is subject to change.
1686  The below documentation may not be accurate by the time you read this.
1687  Also, what constitutes a <quote>default</quote> setting, may change, so
1688  please check all your configuration files on important issues.
1689 </para>
1690 ]]>
1691
1692 </sect2>
1693 </sect1>
1694 <!--  ~  End section  ~  -->
1695
1696
1697 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
1698
1699 <!-- **************************************************** -->
1700 <!-- Include config.sgml here -->
1701 <!-- This is where the entire config file is detailed. -->
1702  &config;
1703 <!-- end include  -->
1704
1705
1706 <!--  ~  End section  ~  -->
1707
1708
1709
1710 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
1711
1712 <sect1 id="actions-file"><title>Actions Files</title>
1713
1714 <para>
1715  The actions files are used to define what <emphasis>actions</emphasis>
1716  <application>Privoxy</application> takes for which URLs, and thus determines
1717  how ad images, cookies and various other aspects of HTTP content and
1718  transactions are handled, and on which sites (or even parts thereof).
1719  There are a number of such actions, with a wide range of functionality.
1720  Each action does something a little different.
1721  These actions give us a veritable arsenal of tools with which to exert
1722  our control, preferences and independence. Actions can be combined so that
1723  their effects are aggregated when applied against a given set of URLs.
1724 </para>
1725 <para>
1726  There
1727  are three action files included with <application>Privoxy</application> with
1728  differing purposes:
1729  </para>
1730
1731  <para>
1732   <itemizedlist>
1733    <listitem>
1734     <para>
1735      <filename>default.action</filename> - is the primary action file
1736      that sets the initial values for all actions. It is intended to
1737      provide a base level of functionality for
1738      <application>Privoxy's</application> array of features. So it is
1739      a set of broad rules that should work reasonably well as-is for most users.
1740      This is the file that the developers are keeping updated, and <link
1741      linkend="installation-keepupdated">making available to users</link>.
1742      The user's preferences as set in <filename>standard.action</filename>,
1743      e.g. either <literal>Cautious</literal> (the default),
1744      <literal>Medium</literal>, or <literal>Advanced</literal> (see
1745      below).
1746     </para>
1747    </listitem>
1748    <listitem>
1749     <para>
1750      <filename>user.action</filename> - is intended to be for local site
1751      preferences and exceptions. As an example, if your ISP or your bank
1752      has specific requirements, and need special handling, this kind of
1753      thing should go here. This file will not be upgraded.
1754     </para>
1755   </listitem>
1756    <listitem>
1757     <para>
1758      <filename>standard.action</filename> - is used by the web based editor
1759      at <ulink url="http://config.privoxy.org/edit-actions-list?f=default">
1760      http://config.privoxy.org/edit-actions-list?f=default</ulink>,
1761      to set various pre-defined sets of rules for the default actions section
1762      in <filename>default.action</filename>.
1763      </para>
1764      <para>
1765      <guibutton>Edit</guibutton>  <guibutton>Set to Cautious</guibutton> <guibutton>Set to Medium</guibutton>  <guibutton>Set to Advanced</guibutton>
1766      </para>
1767      <para>
1768      These have increasing levels of aggressiveness <emphasis>and have no
1769      influence on your browsing unless you select them explicitly in the
1770      editor</emphasis>. A default installation should be pre-set to
1771      <literal>Cautious</literal> (versions prior to 3.0.5 were set to
1772      <literal>Medium</literal>). New users should try this for a while before
1773      adjusting the settings to more aggressive levels. The more aggressive
1774      the settings, then the more likelihood there is of problems such as sites
1775      not working as they should.
1776      </para>
1777      <para>
1778       The <guibutton>Edit</guibutton> button allows you to turn each
1779       action on/off individually for fine-tuning. The <guibutton>Cautious</guibutton>
1780       button changes the actions list to low/safe settings which will activate
1781       a minimal set of &my-app;'s features, and subsequently there will be
1782       less of a chance for accidental problems. The <guibutton>Medium</guibutton>
1783       button sets the list to a medium level of ad blocking and a low level set of
1784       privacy features. The <guibutton>Advanced</guibutton> button
1785       sets the list to a high level of ad blocking and medium level of
1786       privacy. See the chart below. The latter three buttons over-ride
1787       any changes via with the <guibutton>Edit</guibutton> button. More
1788       fine-tuning can be done in the lower sections of this internal page.
1789      </para>
1790      <para>
1791      It is not recommend to edit the <filename>standard.action</filename> file
1792      itself.
1793     </para>
1794     <para>
1795      The default profiles, and their associated actions, as pre-defined in
1796      <filename>standard.action</filename> are:
1797     </para>
1798     <para>
1799     <table frame=all><title>Default Configurations</title>
1800     <tgroup cols=4 align=left colsep=1 rowsep=1>
1801     <colspec colname=c1>
1802     <colspec colname=c2>
1803     <colspec colname=c3>
1804     <colspec colname=c4>
1805     <thead>
1806     <row>
1807       <entry>Feature</entry>
1808       <entry>Cautious</entry>
1809       <entry>Medium</entry>
1810       <entry>Advanced</entry>
1811     </row>
1812     </thead>
1813     <!--  <tfoot> -->
1814     <!--  <row> -->
1815     <!--    <entry>f1</entry> -->
1816     <!--    <entry>f2</entry> -->
1817     <!--    <entry>f3</entry> -->
1818     <!--    <entry>f4</entry> -->
1819     <!--  </row> -->
1820     <!--  </tfoot> -->
1821     <tbody>
1822
1823     <row>
1824       <entry>Ad-blocking Aggressiveness</entry>
1825       <entry>medium</entry>
1826       <entry>high</entry>
1827       <entry>high</entry>
1828     </row>
1829
1830     <row>
1831       <entry>Ad-filtering by size</entry>
1832       <entry>no</entry>
1833       <entry>yes</entry>
1834       <entry>yes</entry>
1835     </row>
1836
1837     <row>
1838       <entry>Ad-filtering by link</entry>
1839       <entry>no</entry>
1840       <entry>no</entry>
1841       <entry>yes</entry>
1842     </row>
1843     <row>
1844       <entry>Pop-up killing</entry>
1845       <entry>blocks only</entry>
1846       <entry>blocks only</entry>
1847       <entry>blocks only</entry>
1848     </row>
1849
1850     <row>
1851       <entry>Privacy Features</entry>
1852       <entry>low</entry>
1853       <entry>medium</entry>
1854       <entry>medium/high</entry>
1855     </row>
1856
1857     <row>
1858       <entry>Cookie handling</entry>
1859       <entry>none</entry>
1860       <entry>session-only</entry>
1861       <entry>kill</entry>
1862     </row>
1863
1864     <row>
1865       <entry>Referer forging</entry>
1866       <entry>no</entry>
1867       <entry>yes</entry>
1868       <entry>yes</entry>
1869     </row>
1870
1871
1872     <row>
1873       <entry>GIF de-animation</entry>
1874       <entry>no</entry>
1875       <entry>yes</entry>
1876       <entry>yes</entry>
1877     </row>
1878
1879
1880     <row>
1881       <entry>Fast redirects</entry>
1882       <entry>no</entry>
1883       <entry>no</entry>
1884       <entry>yes</entry>
1885     </row>
1886
1887     <row>
1888       <entry>HTML taming</entry>
1889       <entry>no</entry>
1890       <entry>no</entry>
1891       <entry>yes</entry>
1892     </row>
1893
1894     <row>
1895       <entry>JavaScript taming</entry>
1896       <entry>no</entry>
1897       <entry>no</entry>
1898       <entry>yes</entry>
1899     </row>
1900
1901     <row>
1902       <entry>Web-bug killing</entry>
1903       <entry>no</entry>
1904       <entry>yes</entry>
1905       <entry>yes</entry>
1906     </row>
1907
1908     <row>
1909       <entry>Image tag reordering</entry>
1910       <entry>no</entry>
1911       <entry>no</entry>
1912       <entry>yes</entry>
1913     </row>
1914
1915     </tbody>
1916     </tgroup>
1917     </table>
1918     </para>
1919
1920    </listitem>
1921   </itemizedlist>
1922  </para>
1923
1924 <para>
1925  The list of actions files to be used are defined in the main configuration
1926  file, and are processed in the order they are defined (e.g.
1927  <filename>default.action</filename> is typically process before
1928  <filename>user.action</filename>). The content of these can all be viewed and
1929  edited from <ulink
1930  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
1931  The over-riding principle when applying actions, is that the last action that
1932  matches a given URL, wins. The broadest, most general rules go first
1933  (defined in <filename>default.action</filename>),
1934  followed by any exceptions (typically also in
1935  <filename>default.action</filename>), which are then followed lastly by any
1936  local preferences (typically in <emphasis>user</emphasis><filename>.action</filename>).
1937  Generally, <filename>user.action</filename> has the last word.
1938  </para>
1939
1940 <para>
1941  An actions file typically has multiple sections. If you want to use
1942  <quote>aliases</quote> in an actions file, you have to place the (optional)
1943  <link linkend="aliases">alias section</link> at the top of that file.
1944  Then comes the default set of rules which will apply universally to all
1945  sites and pages (be <emphasis>very careful</emphasis> with using such a
1946  universal set in <filename>user.action</filename> or any other actions file after
1947  <filename>default.action</filename>, because it will override the result
1948  from consulting any previous file). And then below that,
1949  exceptions to the defined universal policies. You can regard
1950  <filename>user.action</filename> as an appendix to <filename>default.action</filename>,
1951  with the advantage that is a separate file, which makes preserving your
1952  personal settings across <application>Privoxy</application> upgrades easier.
1953 </para>
1954
1955 <para>
1956  Actions can be used to block anything you want, including ads, banners, or
1957  just some obnoxious URL that you would rather not see. Cookies can be accepted
1958  or rejected, or accepted only during the current browser session (i.e. not
1959  written to disk), content can be modified, JavaScripts tamed, user-tracking
1960  fooled, and much more. See below for a <link linkend="actions">complete list
1961  of actions</link>.
1962 </para>
1963
1964 <!--   ~~~~~       New section      ~~~~~     -->
1965 <sect2>
1966 <title>Finding the Right Mix</title>
1967 <para>
1968  Note that some <link linkend="actions">actions</link>, like cookie suppression
1969  or script disabling, may render some sites unusable that rely on these
1970  techniques to work properly. Finding the right mix of actions is not always easy and
1971  certainly a matter of personal taste. And, things can always change, requiring
1972  refinements in the configuration. In general, it can be said that the more
1973  <quote>aggressive</quote> your default settings (in the top section of the
1974  actions file) are, the more exceptions for <quote>trusted</quote> sites you
1975  will have to make later. If, for example, you want to crunch all cookies per
1976  default, you'll have to make exceptions from that rule for sites that you
1977  regularly use and that require cookies for actually useful purposes, like maybe
1978  your bank, favorite shop, or newspaper.
1979 </para>
1980
1981 <para>
1982  We have tried to provide you with reasonable rules to start from in the
1983  distribution actions files. But there is no general rule of thumb on these
1984  things. There just are too many variables, and sites are constantly changing.
1985  Sooner or later you will want to change the rules (and read this chapter again :).
1986 </para>
1987 </sect2>
1988
1989 <!--   ~~~~~       New section      ~~~~~     -->
1990 <sect2>
1991 <title>How to Edit</title>
1992 <para>
1993  The easiest way to edit the actions files is with a browser by
1994  using our browser-based editor, which can be reached from <ulink
1995  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
1996  The editor allows both fine-grained control over every single feature on a
1997  per-URL basis, and easy choosing from wholesale sets of defaults like
1998  <quote>Cautious</quote>, <quote>Medium</quote> or <quote>Advanced</quote>.
1999  Warning: the <quote>Advanced</quote> setting is more aggressive, and
2000  will be more likely to cause problems for some sites. Experienced users only!
2001 </para>
2002
2003 <para>
2004  If you prefer plain text editing to GUIs, you can of course also directly edit the
2005  the actions files with your favorite text editor. Look at
2006  <filename>default.action</filename> which is richly commented with many
2007  good examples.
2008 </para>
2009 </sect2>
2010
2011
2012 <sect2 id="actions-apply">
2013 <title>How Actions are Applied to URLs</title>
2014 <para>
2015  Actions files are divided into sections. There are special sections,
2016  like the <quote><link linkend="aliases">alias</link></quote> sections which will
2017  be discussed later. For now let's concentrate on regular sections: They have a
2018  heading line (often split up to multiple lines for readability) which consist
2019  of a list of actions, separated by whitespace and enclosed in curly braces.
2020  Below that, there is a list of URL patterns, each on a separate line.
2021 </para>
2022
2023 <para>
2024  To determine which actions apply to a request, the URL of the request is
2025  compared to all patterns in each <quote>action file</quote> file. Every time it matches, the list of
2026  applicable actions for the URL is incrementally updated, using the heading
2027  of the section in which the pattern is located. If multiple matches for
2028  the same URL set the same action differently, the last match wins. If not,
2029  the effects are aggregated. E.g. a URL might match a regular section with
2030  a heading line of <literal>{
2031  +<link linkend="handle-as-image">handle-as-image</link> }</literal>,
2032  then later another one with just <literal>{
2033  +<link linkend="block">block</link> }</literal>, resulting
2034  in <emphasis>both</emphasis> actions to apply. And there may well be
2035  cases where you will want to combine actions together. Such a section then
2036  might look like:
2037 </para>
2038
2039  <para>
2040  <screen>
2041   { +<literal>handle-as-image</literal>  +<literal>block</literal> }
2042   # Block these as if they were images. Send no block page.
2043    banners.example.com
2044    media.example.com/.*banners
2045    .example.com/images/ads/</screen>
2046  </para>
2047
2048 <para>
2049  You can trace this process for any given URL by visiting <ulink
2050  url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
2051 </para>
2052
2053 <para>
2054  Examples and more detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
2055  Troubleshooting: Anatomy of an Action</link> section.
2056 </para>
2057 </sect2>
2058
2059 <!--   ~~~~~       New section      ~~~~~     -->
2060 <sect2 id="af-patterns">
2061 <title>Patterns</title>
2062 <para>
2063  As mentioned, <application>Privoxy</application> uses <quote>patterns</quote>
2064  to determine what <emphasis>actions</emphasis> might apply to which sites and
2065  pages your browser attempts to access. These <quote>patterns</quote> use wild
2066  card type <emphasis>pattern</emphasis> matching to achieve a high degree of
2067  flexibility. This allows one expression to be expanded and potentially match
2068  against many similar patterns.
2069 </para>
2070
2071 <para>
2072  Generally, a <application>Privoxy</application> pattern has the form
2073  <literal>&lt;domain&gt;/&lt;path&gt;</literal>, where both the
2074  <literal>&lt;domain&gt;</literal> and <literal>&lt;path&gt;</literal> are
2075  optional. (This is why the special <literal>/</literal> pattern matches all
2076  URLs). Note that the protocol portion of the URL pattern (e.g.
2077  <literal>http://</literal>) should <emphasis>not</emphasis> be included in
2078  the pattern. This is assumed already!
2079 </para>
2080 <para>
2081  The pattern matching syntax is different for the domain and path parts of
2082  the URL. The domain part uses a simple globbing type matching technique,
2083  while the path part uses a more flexible
2084  <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
2085   Expressions (PCRE)</quote></ulink> based syntax.
2086 </para>
2087
2088 <variablelist>
2089  <varlistentry>
2090   <term><literal>www.example.com/</literal></term>
2091   <listitem>
2092    <para>
2093     is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
2094     regardless of which document on that server is requested. So ALL pages in
2095     this domain would be covered by the scope of this action. Note that a
2096     simple <literal>example.com</literal> is different and would NOT match.
2097    </para>
2098   </listitem>
2099  </varlistentry>
2100  <varlistentry>
2101   <term><literal>www.example.com</literal></term>
2102   <listitem>
2103    <para>
2104     means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
2105     be omitted.
2106    </para>
2107   </listitem>
2108  </varlistentry>
2109  <varlistentry>
2110   <term><literal>www.example.com/index.html</literal></term>
2111   <listitem>
2112    <para>
2113     matches only the single document <literal>/index.html</literal>
2114     on <literal>www.example.com</literal>.
2115    </para>
2116   </listitem>
2117  </varlistentry>
2118  <varlistentry>
2119   <term><literal>/index.html</literal></term>
2120   <listitem>
2121    <para>
2122     matches the document <literal>/index.html</literal>, regardless of the domain,
2123     i.e. on <emphasis>any</emphasis> web server anywhere.
2124    </para>
2125   </listitem>
2126  </varlistentry>
2127  <varlistentry>
2128   <term><literal>index.html</literal></term>
2129   <listitem>
2130    <para>
2131     matches nothing, since it would be  interpreted as a domain name and
2132     there is no top-level domain called <literal>.html</literal>. So its
2133     a mistake.
2134    </para>
2135   </listitem>
2136  </varlistentry>
2137 </variablelist>
2138
2139
2140 <!--   ~~~~~       New section      ~~~~~     -->
2141 <sect3><title>The Domain Pattern</title>
2142
2143 <para>
2144  The matching of the domain part offers some flexible options: if the
2145  domain starts or ends with a dot, it becomes unanchored at that end.
2146  For example:
2147 </para>
2148
2149 <variablelist>
2150  <varlistentry>
2151   <term><literal>.example.com</literal></term>
2152   <listitem>
2153    <para>
2154     matches any domain that <emphasis>ENDS</emphasis> in
2155     <literal>.example.com</literal>
2156    </para>
2157   </listitem>
2158  </varlistentry>
2159  <varlistentry>
2160   <term><literal>www.</literal></term>
2161   <listitem>
2162    <para>
2163     matches any domain that <emphasis>STARTS</emphasis> with
2164     <literal>www.</literal>
2165    </para>
2166   </listitem>
2167  </varlistentry>
2168  <varlistentry>
2169   <term><literal>.example.</literal></term>
2170   <listitem>
2171    <para>
2172     matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>.
2173     And, by the way, also included would be any files or documents that exist
2174     within that domain since no path limitations are specified. (Correctly
2175     speaking: It matches any FQDN that contains <literal>example</literal> as
2176     a domain.) This might be <literal>www.example.com</literal>,
2177     <literal>news.example.de</literal>, or
2178     <literal>www.example.net/cgi/testing.pl</literal> for instance. All these
2179     cases are matched.
2180    </para>
2181   </listitem>
2182  </varlistentry>
2183 </variablelist>
2184
2185 <para>
2186  Additionally, there are wild-cards that you can use in the domain names
2187  themselves. These work similarly to shell globbing type wild-cards:
2188  <quote>*</quote> represents zero or more arbitrary characters (this is
2189  equivalent to the
2190  <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
2191  Expression</quote></ulink> based syntax of <quote>.*</quote>),
2192  <quote>?</quote>  represents any single character (this is equivalent to the
2193  regular expression syntax of a simple <quote>.</quote>), and you can define
2194  <quote>character classes</quote> in square brackets which is similar to
2195  the same regular expression technique. All of this can be freely mixed:
2196 </para>
2197
2198 <variablelist>
2199  <varlistentry>
2200   <term><literal>ad*.example.com</literal></term>
2201   <listitem>
2202    <para>
2203     matches <quote>adserver.example.com</quote>,
2204     <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
2205    </para>
2206   </listitem>
2207  </varlistentry>
2208  <varlistentry>
2209   <term><literal>*ad*.example.com</literal></term>
2210   <listitem>
2211    <para>
2212     matches all of the above, and then some.
2213    </para>
2214   </listitem>
2215  </varlistentry>
2216  <varlistentry>
2217   <term><literal>.?pix.com</literal></term>
2218   <listitem>
2219    <para>
2220     matches <literal>www.ipix.com</literal>,
2221     <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc.
2222    </para>
2223   </listitem>
2224  </varlistentry>
2225  <varlistentry>
2226   <term><literal>www[1-9a-ez].example.c*</literal></term>
2227   <listitem>
2228    <para>
2229      matches <literal>www1.example.com</literal>,
2230      <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>,
2231      <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis>
2232      <literal>wwww.example.com</literal>.
2233    </para>
2234   </listitem>
2235  </varlistentry>
2236 </variablelist>
2237
2238 <para>
2239  While flexibile, this is not the sophistication of full regular expression based syntax.
2240 </para>
2241
2242 </sect3>
2243
2244 <!--  ~  End section  ~  -->
2245
2246
2247 <!--   ~~~~~       New section      ~~~~~     -->
2248 <sect3><title>The Path Pattern</title>
2249
2250 <para>
2251  <application>Privoxy</application> uses Perl compatible (PCRE)
2252   <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
2253   Expression</quote></ulink> based syntax
2254  (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
2255  matching the path portion (after the slash), and is thus more flexible.
2256 </para>
2257
2258 <para>
2259  There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
2260  expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
2261  at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
2262  You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
2263  useful, which is available on-line at <ulink
2264  url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>.
2265 </para>
2266
2267 <para>
2268  Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
2269  i.e. it matches as if it would start with a <quote>^</quote> (regular expression speak
2270  for the beginning of a line).
2271 </para>
2272
2273 <para>
2274  Please also note that matching in the path is <emphasis>CASE INSENSITIVE</emphasis>
2275  by default, but you can switch to case sensitive at any point in the pattern by using the
2276  <quote>(?-i)</quote> switch: <literal>www.example.com/(?-i)PaTtErN.*</literal> will match
2277  only documents whose path starts with <literal>PaTtErN</literal> in
2278  <emphasis>exactly</emphasis> this capitalization.
2279 </para>
2280
2281 <variablelist>
2282  <varlistentry>
2283   <term><literal>.example.com/.*</literal></term>
2284   <listitem>
2285    <para>
2286      Is equivalent to just <quote>.example.com</quote>, since any documents
2287      within that domain are matched with or without the <quote>.*</quote>
2288      regular expression. This is redundant
2289    </para>
2290   </listitem>
2291  </varlistentry>
2292  <varlistentry>
2293   <term><literal>.example.com/.*/index.html</literal></term>
2294   <listitem>
2295    <para>
2296     Will match any page in the domain of <quote>example.com</quote> that is
2297     named <quote>index.html</quote>, and that is part of some path. For
2298     example, it matches <quote>www.example.com/testing/index.html</quote> but
2299     NOT <quote>www.example.com/index.html</quote> because the regular
2300     expression called for at least two <quote>/'s</quote>, thus the path
2301     requirement. It also would match
2302     <quote>www.example.com/testing/index_html</quote>, because of the
2303     special meta-character <quote>.</quote>.
2304    </para>
2305   </listitem>
2306  </varlistentry>
2307  <varlistentry>
2308   <term><literal>.example.com/(.*/)?index\.html</literal></term>
2309   <listitem>
2310    <para>
2311     This regular expression is conditional so it will match any page
2312     named <quote>index.html</quote> regardless of path which in this case can
2313     have one or more <quote>/'s</quote>. And this one must contain exactly
2314     <quote>.html</quote> (but does not have to end with that!).
2315    </para>
2316   </listitem>
2317  </varlistentry>
2318  <varlistentry>
2319   <term><literal>.example.com/(.*/)(ads|banners?|junk)</literal></term>
2320   <listitem>
2321    <para>
2322     This regular expression will match any path of <quote>example.com</quote>
2323     that contains any of the words <quote>ads</quote>, <quote>banner</quote>,
2324     <quote>banners</quote> (because of the <quote>?</quote>) or <quote>junk</quote>.
2325     The path does not have to end in these words, just contain them.
2326    </para>
2327   </listitem>
2328  </varlistentry>
2329  <varlistentry>
2330   <term><literal>.example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$</literal></term>
2331   <listitem>
2332    <para>
2333     This is very much the same as above, except now it must end in either
2334     <quote>.jpg</quote>, <quote>.jpeg</quote>, <quote>.gif</quote> or <quote>.png</quote>. So this
2335     one is limited to common image formats.
2336    </para>
2337   </listitem>
2338  </varlistentry>
2339
2340 </variablelist>
2341 <para>
2342  There are many, many good examples to be found in <filename>default.action</filename>,
2343  and more tutorials below in <link linkend="regex">Appendix on regular expressions</link>.
2344 </para>
2345
2346 </sect3>
2347
2348 </sect2>
2349
2350 <!--  ~  End section  ~  -->
2351
2352
2353 <!--   ~~~~~       New section      ~~~~~     -->
2354
2355 <sect2 id="actions">
2356 <title>Actions</title>
2357 <para>
2358  All actions are disabled by default, until they are explicitly enabled
2359  somewhere in an actions file. Actions are turned on if preceded with a
2360  <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
2361  <literal>+action</literal> means <quote>do that action</quote>, e.g.
2362  <literal>+block</literal> means <quote>please block URLs that match the
2363  following patterns</quote>, and <literal>-block</literal> means <quote>don't
2364  block URLs that match the following patterns, even if <literal>+block</literal>
2365  previously applied.</quote>
2366
2367 </para>
2368
2369 <para>
2370  Again, actions are invoked by placing them on a line, enclosed in curly braces and
2371  separated by whitespace, like in
2372  <literal>{+some-action -some-other-action{some-parameter}}</literal>,
2373  followed by a list of URL patterns, one per line, to which they apply.
2374  Together, the actions line and the following pattern lines make up a section
2375  of the actions file.
2376 </para>
2377
2378 <para>
2379  Actions fall into three categories:
2380 </para>
2381
2382 <para>
2383  <itemizedlist>
2384  <listitem>
2385   <para>
2386    Boolean, i.e the action can only be <quote>enabled</quote> or
2387    <quote>disabled</quote>. Syntax:
2388   </para>
2389   <para>
2390    <screen>
2391   +<replaceable class="function">name</replaceable>        # enable action <replaceable class="parameter">name</replaceable>
2392   -<replaceable class="function">name</replaceable>        # disable action <replaceable class="parameter">name</replaceable></screen>
2393   </para>
2394   <para>
2395    Example: <literal>+block</literal>
2396   </para>
2397  </listitem>
2398
2399
2400  <listitem>
2401   <para>
2402    Parameterized, where some value is required in order to enable this type of action.
2403    Syntax:
2404   </para>
2405   <para>
2406    <screen>
2407   +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}  # enable action and set parameter to <replaceable class="parameter">param</replaceable>,
2408                # overwriting parameter from previous match if necessary
2409   -<replaceable class="function">name</replaceable>         # disable action. The parameter can be omitted</screen>
2410   </para>
2411   <para>
2412    Note that if the URL matches multiple positive forms of a parameterized action,
2413    the last match wins, i.e. the params from earlier matches are simply ignored.
2414   </para>
2415   <para>
2416    Example: <literal>+hide-user-agent{ Mozilla 1.0 }</literal>
2417   </para>
2418  </listitem>
2419
2420  <listitem>
2421   <para>
2422    Multi-value. These look exactly like parameterized actions,
2423    but they behave differently: If the action applies multiple times to the
2424    same URL, but with different parameters, <emphasis>all</emphasis> the parameters
2425    from <emphasis>all</emphasis> matches are remembered. This is used for actions
2426    that can be executed for the same request repeatedly, like adding multiple
2427    headers, or filtering through multiple filters. Syntax:
2428   </para>
2429   <para>
2430    <screen>
2431   +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}   # enable action and add <replaceable class="parameter">param</replaceable> to the list of parameters
2432   -<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}   # remove the parameter <replaceable class="parameter">param</replaceable> from the list of parameters
2433                 # If it was the last one left, disable the action.
2434   <replaceable class="parameter">-name</replaceable>          # disable this action completely and remove all parameters from the list</screen>
2435   </para>
2436   <para>
2437    Examples: <literal>+add-header{X-Fun-Header: Some text}</literal> and
2438    <literal>+filter{html-annoyances}</literal>
2439   </para>
2440  </listitem>
2441
2442  </itemizedlist>
2443 </para>
2444
2445 <para>
2446  If nothing is specified in any actions file, no <quote>actions</quote> are
2447  taken. So in this case <application>Privoxy</application> would just be a
2448  normal, non-blocking, non-anonymizing proxy. You must specifically enable the
2449  privacy and blocking features you need (although the provided default actions
2450  files will give a good starting point).
2451 </para>
2452
2453 <para>
2454  Later defined actions always over-ride earlier ones.  So exceptions
2455  to any rules you make, should come in the latter part of the file (or
2456  in a file that is processed later when using multiple actions files such
2457  as <filename>user.action</filename>). For multi-valued actions, the actions
2458  are applied in the order they are specified. Actions files are processed in
2459  the order they are defined in <filename>config</filename> (the default
2460  installation has three actions files). It also quite possible for any given
2461  URL to match more than one <quote>pattern</quote> (because of wildcards and
2462  regular expressions), and thus to trigger more than one set of actions! Last
2463  match wins.
2464 </para>
2465
2466 <!-- start actions listing -->
2467 <para>
2468  The list of valid <application>Privoxy</application> actions are:
2469 </para>
2470
2471
2472 <!-- ********************************************************** -->
2473 <!-- Please note the below defined actions use id's that are    -->
2474 <!-- probably linked from other places, so please don't change. -->
2475 <!--                                                            -->
2476 <!-- ********************************************************** -->
2477
2478
2479 <!--   ~~~~~       New section      ~~~~~     -->
2480
2481 <sect3 renderas="sect4" id="add-header">
2482 <title>add-header</title>
2483
2484 <variablelist>
2485  <varlistentry>
2486   <term>Typical use:</term>
2487   <listitem>
2488    <para>Confuse log analysis, custom applications</para>
2489   </listitem>
2490  </varlistentry>
2491
2492  <varlistentry>
2493   <term>Effect:</term>
2494   <listitem>
2495    <para>
2496     Sends a user defined HTTP header to the web server.
2497    </para>
2498   </listitem>
2499  </varlistentry>
2500
2501  <varlistentry>
2502   <term>Type:</term>
2503   <!-- boolean, parameterized, Multi-value -->
2504   <listitem>
2505    <para>Multi-value.</para>
2506   </listitem>
2507  </varlistentry>
2508
2509  <varlistentry>
2510   <term>Parameter:</term>
2511   <listitem>
2512    <para>
2513     Any string value is possible. Validity of the defined HTTP headers is not checked.
2514     It is recommended that you use the <quote><literal>X-</literal></quote> prefix
2515     for custom headers.
2516    </para>
2517   </listitem>
2518  </varlistentry>
2519
2520 <varlistentry>
2521   <term>Notes:</term>
2522   <listitem>
2523    <para>
2524     This action may be specified multiple times, in order to define multiple
2525     headers. This is rarely needed for the typical user. If you don't know what
2526     <quote>HTTP headers</quote> are, you definitely don't need to worry about this
2527     one.
2528    </para>
2529   </listitem>
2530  </varlistentry>
2531
2532  <varlistentry>
2533   <term>Example usage:</term>
2534   <listitem>
2535     <para>
2536      <screen>+add-header{X-User-Tracking: sucks}</screen>
2537    </para>
2538   </listitem>
2539  </varlistentry>
2540 </variablelist>
2541 </sect3>
2542
2543
2544 <!--   ~~~~~       New section      ~~~~~     -->
2545 <sect3 renderas="sect4" id="block">
2546 <title>block</title>
2547
2548 <variablelist>
2549  <varlistentry>
2550   <term>Typical use:</term>
2551   <listitem>
2552    <para>Block ads or other unwanted content</para>
2553   </listitem>
2554  </varlistentry>
2555
2556  <varlistentry>
2557   <term>Effect:</term>
2558   <listitem>
2559    <para>
2560     Requests for URLs to which this action applies are blocked, i.e. the
2561     requests are trapped by &my-app; and the requested URL is never retrieved,
2562     but is answered locally with a substitute page or image, as determined by
2563     the <literal><link
2564     linkend="handle-as-image">handle-as-image</link></literal>,
2565     <literal><link
2566     linkend="set-image-blocker">set-image-blocker</link></literal>, and
2567     <literal><link
2568     linkend="handle-as-empty-document">handle-as-empty-document</link></literal> actions.
2569
2570    </para>
2571   </listitem>
2572  </varlistentry>
2573
2574  <varlistentry>
2575   <term>Type:</term>
2576   <!-- boolean, parameterized, Multi-value -->
2577   <listitem>
2578    <para>Boolean.</para>
2579   </listitem>
2580  </varlistentry>
2581
2582  <varlistentry>
2583   <term>Parameter:</term>
2584   <listitem>
2585    <para>N/A</para>
2586   </listitem>
2587  </varlistentry>
2588
2589 <varlistentry>
2590   <term>Notes:</term>
2591   <listitem>
2592    <para>
2593     <application>Privoxy</application> sends a special <quote>BLOCKED</quote> page
2594     for requests to blocked pages. This page contains links to find out why the request
2595     was blocked, and a click-through to the blocked content (the latter only if compiled with the
2596     force feature enabled). The <quote>BLOCKED</quote> page adapts to the available
2597     screen space -- it displays full-blown if space allows, or miniaturized and text-only
2598     if loaded into a small frame or window. If you are using <application>Privoxy</application>
2599     right now, you can take a look at the
2600     <ulink url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
2601     page</ulink>.
2602    </para>
2603    <para>
2604     A very important exception occurs if <emphasis>both</emphasis>
2605     <literal>block</literal> and <literal><link linkend="handle-as-image">handle-as-image</link></literal>,
2606     apply to the same request: it will then be replaced by an image. If
2607     <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
2608     (see below) also applies, the type of image will be determined by its parameter,
2609     if not, the standard checkerboard pattern is sent.
2610    </para>
2611    <para>
2612     It is important to understand this process, in order
2613     to understand how <application>Privoxy</application> deals with
2614     ads and other unwanted content. Blocking is a core feature, and one
2615     upon which various other features depend.
2616    </para>
2617    <para>
2618     The <literal><link linkend="filter">filter</link></literal>
2619     action can perform a very similar task, by <quote>blocking</quote>
2620     banner images and other content through rewriting the relevant URLs in the
2621     document's HTML source, so they don't get requested in the first place.
2622     Note that this is a totally different technique, and it's easy to confuse the two.
2623    </para>
2624   </listitem>
2625  </varlistentry>
2626
2627  <varlistentry>
2628   <term>Example usage (section):</term>
2629   <listitem>
2630     <para>
2631      <screen>{+block}
2632 # Block and replace with "blocked" page
2633  .nasty-stuff.example.com
2634
2635 {+block +handle-as-image}
2636 # Block and replace with image
2637  .ad.doubleclick.net
2638  .ads.r.us/banners/
2639
2640 {+block +handle-as-empty-document}
2641 # Block and then ignore
2642  adserver.exampleclick.net/.*\.js$</screen>
2643     </para>
2644   </listitem>
2645  </varlistentry>
2646
2647
2648 </variablelist>
2649 </sect3>
2650
2651
2652 <!--   ~~~~~       New section      ~~~~~     -->
2653 <sect3 renderas="sect4" id="content-type-overwrite">
2654 <!--
2655 new action
2656 -->
2657 <title>content-type-overwrite</title>
2658
2659 <variablelist>
2660  <varlistentry>
2661   <term>Typical use:</term>
2662   <listitem>
2663    <para>Stop useless download menus from popping up, or change the browser's rendering mode</para>
2664   </listitem>
2665  </varlistentry>
2666
2667  <varlistentry>
2668   <term>Effect:</term>
2669   <listitem>
2670    <para>
2671     Replaces the <quote>Content-Type:</quote> HTTP server header.
2672    </para>
2673   </listitem>
2674  </varlistentry>
2675
2676  <varlistentry>
2677   <term>Type:</term>
2678   <!-- Boolean, Parameterized, Multi-value -->
2679   <listitem>
2680    <para>Parameterized.</para>
2681   </listitem>
2682  </varlistentry>
2683
2684  <varlistentry>
2685   <term>Parameter:</term>
2686   <listitem>
2687    <para>
2688     Any string.
2689    </para>
2690   </listitem>
2691  </varlistentry>
2692
2693  <varlistentry>
2694   <term>Notes:</term>
2695   <listitem>
2696    <para>
2697     The <quote>Content-Type:</quote> HTTP server header is used by the
2698     browser to decide what to do with the document. The value of this
2699     header can cause the browser to open a download menu instead of
2700     displaying the document by itself, even if the document's format is
2701     supported by the browser.
2702    </para>
2703    <para>
2704     The declared content type can also affect which rendering mode
2705     the browser chooses. If XHTML is delivered as <quote>text/html</quote>,
2706     many browsers treat it as yet another broken HTML document.
2707     If it is send as <quote>application/xml</quote>, browsers with
2708     XHTML support will only display it, if the syntax is correct.
2709    </para>
2710    <para>
2711     If you see a web site that proudly uses XHTML buttons, but sets
2712     <quote>Content-Type: text/html</quote>, you can use &my-app;
2713     to overwrite it with <quote>application/xml</quote> and validate
2714     the web master's claim inside your XHTML-supporting browser.
2715     If the syntax is incorrect, the browser will complain loudly.
2716    </para>
2717    <para>
2718     You can also go the opposite direction: if your browser prints
2719     error messages instead of rendering a document falsely declared
2720     as XHTML, you can overwrite the content type with
2721     <quote>text/html</quote> and have it rendered as broken HTML document.
2722    </para>
2723    <para>
2724     By default <literal>content-type-overwrite</literal> only replaces
2725     <quote>Content-Type:</quote> headers that look like some kind of text.
2726     If you want to overwrite it unconditionally, you have to combine it with
2727     <literal><link linkend="force-text-mode">force-text-mode</link></literal>.
2728     This limitation exists for a reason, think twice before circumventing it.
2729    </para>
2730    <para>
2731     Most of the time it's easier to enable
2732     <literal><link linkend="filter-server-headers">filter-server-headers</link></literal>
2733     and replace this action with a custom regular expression. It allows you
2734     to activate it for every document of a certain site and it will still
2735     only replace the content types you aimed at.
2736    </para>
2737    <para>
2738     Of course you can apply <literal>content-type-overwrite</literal>
2739     to a whole site and then make URL based exceptions, but it's a lot
2740     more work to get the same precision.
2741    </para>
2742   </listitem>
2743  </varlistentry>
2744
2745  <varlistentry>
2746   <term>Example usage (sections):</term>
2747   <listitem>
2748     <para>
2749      <screen># Check if www.example.net/ really uses valid XHTML
2750 {+content-type-overwrite {application/xml}}
2751 www.example.net/
2752
2753 # but leave the content type unmodified if the URL looks like a style sheet
2754 {-content-type-overwrite}
2755 www.example.net/*.\.css$
2756 www.example.net/*.style
2757 </screen>
2758    </para>
2759   </listitem>
2760  </varlistentry>
2761 </variablelist>
2762 </sect3>
2763
2764
2765 <!--   ~~~~~       New section      ~~~~~     -->
2766 <sect3 renderas="sect4" id="crunch-client-header">
2767 <!--
2768 new action
2769 -->
2770 <title>crunch-client-header</title>
2771
2772 <variablelist>
2773  <varlistentry>
2774   <term>Typical use:</term>
2775   <listitem>
2776    <para>Remove a client header <application>Privoxy</application> has no dedicated action for.</para>
2777   </listitem>
2778  </varlistentry>
2779
2780  <varlistentry>
2781   <term>Effect:</term>
2782   <listitem>
2783    <para>
2784     Deletes every header sent by the client that contains the string the user supplied as parameter.
2785    </para>
2786   </listitem>
2787  </varlistentry>
2788
2789  <varlistentry>
2790   <term>Type:</term>
2791   <!-- Boolean, Parameterized, Multi-value -->
2792   <listitem>
2793    <para>Parameterized.</para>
2794   </listitem>
2795  </varlistentry>
2796
2797  <varlistentry>
2798   <term>Parameter:</term>
2799   <listitem>
2800    <para>
2801     Any string.
2802    </para>
2803   </listitem>
2804  </varlistentry>
2805
2806  <varlistentry>
2807   <term>Notes:</term>
2808   <listitem>
2809    <para>
2810     This action allows you to block client headers for which no dedicated
2811     <application>Privoxy</application> action exists.
2812     <application>Privoxy</application> will remove every client header that
2813     contains the string you supplied as parameter.
2814    </para>
2815    <para>
2816     Regular expressions are <emphasis>not supported</emphasis> and you can't
2817     use this action to block different headers in the same request, unless
2818     they contain the same string.
2819    </para>
2820    <para>
2821     <literal>crunch-client-header</literal> is only meant for quick tests.
2822     If you have to block several different headers, or only want to modify
2823     parts of them, you should enable
2824     <literal><link linkend="filter-client-headers">filter-client-headers</link></literal>
2825     and create your own filter.
2826    </para>
2827     <warning>
2828      <para>
2829       Don't block any header without understanding the consequences.
2830      </para>
2831     </warning>
2832   </listitem>
2833  </varlistentry>
2834
2835  <varlistentry>
2836   <term>Example usage (section):</term>
2837   <listitem>
2838     <para>
2839      <screen># Block the non-existent "Privacy-Violation:" client header
2840 {+crunch-client-header {Privacy-Violation:}}
2841 /
2842     </screen>
2843    </para>
2844   </listitem>
2845  </varlistentry>
2846 </variablelist>
2847 </sect3>
2848
2849
2850 <!--   ~~~~~       New section      ~~~~~     -->
2851 <sect3 renderas="sect4" id="crunch-if-none-match">
2852 <title>crunch-if-none-match</title>
2853 <!--
2854 new action
2855 -->
2856 <variablelist>
2857  <varlistentry>
2858   <term>Typical use:</term>
2859   <listitem>
2860    <para>Prevent yet another way to track the user's steps between sessions.</para>
2861   </listitem>
2862  </varlistentry>
2863
2864  <varlistentry>
2865   <term>Effect:</term>
2866   <listitem>
2867    <para>
2868     Deletes the <quote>If-None-Match:</quote> HTTP client header.
2869    </para>
2870   </listitem>
2871  </varlistentry>
2872
2873  <varlistentry>
2874   <term>Type:</term>
2875   <!-- Boolean, Parameterized, Multi-value -->
2876   <listitem>
2877    <para>Boolean.</para>
2878   </listitem>
2879  </varlistentry>
2880
2881  <varlistentry>
2882   <term>Parameter:</term>
2883   <listitem>
2884    <para>
2885     N/A
2886    </para>
2887   </listitem>
2888  </varlistentry>
2889
2890  <varlistentry>
2891   <term>Notes:</term>
2892   <listitem>
2893    <para>
2894     Removing the <quote>If-None-Match:</quote> HTTP client header
2895     is useful for filter testing, where you want to force a real
2896     reload instead of getting status code <quote>304</quote> which
2897     would cause the browser to use a cached copy of the page.
2898    </para>
2899    <para>
2900     It is also useful to make sure the header isn't used as a cookie
2901     replacement.
2902    </para>
2903    <para>
2904     Blocking the <quote>If-None-Match:</quote> header shouldn't cause any
2905     caching problems, as long as the <quote>If-Modified-Since:</quote> header
2906     isn't blocked as well.
2907    </para>
2908    <para>
2909     It is recommended to use this action together with
2910     <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
2911     and
2912     <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>.
2913    </para>
2914   </listitem>
2915  </varlistentry>
2916
2917  <varlistentry>
2918   <term>Example usage (section):</term>
2919   <listitem>
2920     <para>
2921      <screen># Let the browser revalidate cached documents without being tracked across sessions
2922 {+hide-if-modified-since {-60} \
2923 +overwrite-last-modified {randomize} \
2924 +crunch-if-none-match}
2925 /   </screen>
2926    </para>
2927   </listitem>
2928  </varlistentry>
2929 </variablelist>
2930 </sect3>
2931
2932
2933 <!--   ~~~~~       New section      ~~~~~     -->
2934 <sect3 renderas="sect4" id="crunch-incoming-cookies">
2935 <title>crunch-incoming-cookies</title>
2936
2937 <variablelist>
2938  <varlistentry>
2939   <term>Typical use:</term>
2940   <listitem>
2941    <para>
2942     Prevent the web server from setting any cookies on your system
2943    </para>
2944   </listitem>
2945  </varlistentry>
2946
2947  <varlistentry>
2948   <term>Effect:</term>
2949   <listitem>
2950    <para>
2951     Deletes any <quote>Set-Cookie:</quote> HTTP headers from server replies.
2952    </para>
2953   </listitem>
2954  </varlistentry>
2955
2956  <varlistentry>
2957   <term>Type:</term>
2958   <!-- Boolean, Parameterized, Multi-value -->
2959   <listitem>
2960    <para>Boolean.</para>
2961   </listitem>
2962  </varlistentry>
2963
2964  <varlistentry>
2965   <term>Parameter:</term>
2966   <listitem>
2967    <para>
2968     N/A
2969    </para>
2970   </listitem>
2971  </varlistentry>
2972
2973  <varlistentry>
2974   <term>Notes:</term>
2975   <listitem>
2976    <para>
2977     This action is only concerned with <emphasis>incoming</emphasis> cookies. For
2978     <emphasis>outgoing</emphasis> cookies, use
2979     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>.
2980     Use <emphasis>both</emphasis> to disable cookies completely.
2981    </para>
2982    <para>
2983     It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
2984     with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
2985     since it would prevent the session cookies from being set. See also
2986     <literal><link linkend="filter-content-cookies">filter-content-cookies</link></literal>.
2987    </para>
2988   </listitem>
2989  </varlistentry>
2990
2991  <varlistentry>
2992   <term>Example usage:</term>
2993   <listitem>
2994    <para>
2995     <screen>+crunch-incoming-cookies</screen>
2996    </para>
2997   </listitem>
2998  </varlistentry>
2999 </variablelist>
3000 </sect3>
3001
3002
3003 <!--   ~~~~~       New section      ~~~~~     -->
3004 <sect3 renderas="sect4" id="crunch-server-header">
3005 <title>crunch-server-header</title>
3006 <!--
3007 new action
3008 -->
3009 <variablelist>
3010  <varlistentry>
3011   <term>Typical use:</term>
3012   <listitem>
3013    <para>Remove a server header <application>Privoxy</application> has no dedicated action for.</para>
3014   </listitem>
3015  </varlistentry>
3016
3017  <varlistentry>
3018   <term>Effect:</term>
3019   <listitem>
3020    <para>
3021     Deletes every header sent by the server that contains the string the user supplied as parameter.
3022    </para>
3023   </listitem>
3024  </varlistentry>
3025
3026  <varlistentry>
3027   <term>Type:</term>
3028   <!-- Boolean, Parameterized, Multi-value -->
3029   <listitem>
3030    <para>Parameterized.</para>
3031   </listitem>
3032  </varlistentry>
3033
3034  <varlistentry>
3035   <term>Parameter:</term>
3036   <listitem>
3037    <para>
3038     Any string.
3039    </para>
3040   </listitem>
3041  </varlistentry>
3042
3043  <varlistentry>
3044   <term>Notes:</term>
3045   <listitem>
3046    <para>
3047     This action allows you to block server headers for which no dedicated
3048     <application>Privoxy</application> action exists. <application>Privoxy</application>
3049     will remove every server header that contains the string you supplied as parameter.
3050    </para>
3051    <para>
3052     Regular expressions are <emphasis>not supported</emphasis> and you can't
3053     use this action to block different headers in the same request, unless
3054     they contain the same string.
3055    </para>
3056    <para>
3057     <literal>crunch-server-header</literal> is only meant for quick tests.
3058     If you have to block several different headers, or only want to modify
3059     parts of them, you should enable
3060     <literal><link linkend="filter-server-headers">filter-server-headers</link></literal>
3061     and create your own filter.
3062    </para>
3063     <warning>
3064      <para>
3065      Don't block any header without understanding the consequences.
3066      </para>
3067     </warning>
3068   </listitem>
3069  </varlistentry>
3070
3071  <varlistentry>
3072   <term>Example usage (section):</term>
3073   <listitem>
3074     <para>
3075      <screen># Crunch server headers that try to prevent caching
3076 {+crunch-server-header {no-cache}}
3077 /   </screen>
3078    </para>
3079   </listitem>
3080  </varlistentry>
3081 </variablelist>
3082 </sect3>
3083
3084
3085 <!--   ~~~~~       New section      ~~~~~     -->
3086 <sect3 renderas="sect4" id="crunch-outgoing-cookies">
3087 <title>crunch-outgoing-cookies</title>
3088
3089 <variablelist>
3090  <varlistentry>
3091   <term>Typical use:</term>
3092   <listitem>
3093    <para>
3094     Prevent the web server from reading any cookies from your system
3095    </para>
3096   </listitem>
3097  </varlistentry>
3098
3099  <varlistentry>
3100   <term>Effect:</term>
3101   <listitem>
3102    <para>
3103     Deletes any <quote>Cookie:</quote> HTTP headers from client requests.
3104    </para>
3105   </listitem>
3106  </varlistentry>
3107
3108  <varlistentry>
3109   <term>Type:</term>
3110   <!-- Boolean, Parameterized, Multi-value -->
3111   <listitem>
3112    <para>Boolean.</para>
3113   </listitem>
3114  </varlistentry>
3115
3116  <varlistentry>
3117   <term>Parameter:</term>
3118   <listitem>
3119    <para>
3120     N/A
3121    </para>
3122   </listitem>
3123  </varlistentry>
3124
3125  <varlistentry>
3126   <term>Notes:</term>
3127   <listitem>
3128    <para>
3129     This action is only concerned with <emphasis>outgoing</emphasis> cookies. For
3130     <emphasis>incoming</emphasis> cookies, use
3131     <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>.
3132     Use <emphasis>both</emphasis> to disable cookies completely.
3133    </para>
3134    <para>
3135     It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
3136     with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
3137     since it would prevent the session cookies from being read.
3138    </para>
3139   </listitem>
3140  </varlistentry>
3141
3142  <varlistentry>
3143   <term>Example usage:</term>
3144   <listitem>
3145    <para>
3146     <screen>+crunch-outgoing-cookies</screen>
3147    </para>
3148   </listitem>
3149  </varlistentry>
3150
3151 </variablelist>
3152 </sect3>
3153
3154
3155 <!--   ~~~~~       New section      ~~~~~     -->
3156 <sect3 renderas="sect4" id="deanimate-gifs">
3157 <title>deanimate-gifs</title>
3158
3159 <variablelist>
3160  <varlistentry>
3161   <term>Typical use:</term>
3162   <listitem>
3163    <para>Stop those annoying, distracting animated GIF images.</para>
3164   </listitem>
3165  </varlistentry>
3166
3167  <varlistentry>
3168   <term>Effect:</term>
3169   <listitem>
3170    <para>
3171     De-animate GIF animations, i.e. reduce them to their first or last image.
3172    </para>
3173   </listitem>
3174  </varlistentry>
3175
3176  <varlistentry>
3177   <term>Type:</term>
3178   <!-- boolean, parameterized, Multi-value -->
3179   <listitem>
3180    <para>Parameterized.</para>
3181   </listitem>
3182  </varlistentry>
3183
3184  <varlistentry>
3185   <term>Parameter:</term>
3186   <listitem>
3187    <para>
3188     <quote>last</quote> or <quote>first</quote>
3189    </para>
3190   </listitem>
3191  </varlistentry>
3192
3193  <varlistentry>
3194   <term>Notes:</term>
3195   <listitem>
3196    <para>
3197     This will also shrink the images considerably (in bytes, not pixels!). If
3198     the option <quote>first</quote> is given, the first frame of the animation
3199     is used as the replacement. If <quote>last</quote> is given, the last
3200     frame of the animation is used instead, which probably makes more sense for
3201     most banner animations, but also has the risk of not showing the entire
3202     last frame (if it is only a delta to an earlier frame).
3203    </para>
3204    <para>
3205     You can safely use this action with patterns that will also match non-GIF
3206     objects, because no attempt will be made at anything that doesn't look like
3207     a GIF.
3208    </para>
3209   </listitem>
3210  </varlistentry>
3211
3212  <varlistentry>
3213   <term>Example usage:</term>
3214   <listitem>
3215     <para>
3216       <screen>+deanimate-gifs{last}</screen>
3217     </para>
3218   </listitem>
3219  </varlistentry>
3220 </variablelist>
3221 </sect3>
3222
3223 <!--   ~~~~~       New section      ~~~~~     -->
3224 <sect3 renderas="sect4" id="downgrade-http-version">
3225 <title>downgrade-http-version</title>
3226
3227 <variablelist>
3228  <varlistentry>
3229   <term>Typical use:</term>
3230   <listitem>
3231    <para>Work around (very rare) problems with HTTP/1.1</para>
3232   </listitem>
3233  </varlistentry>
3234
3235  <varlistentry>
3236   <term>Effect:</term>
3237   <listitem>
3238    <para>
3239     Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
3240    </para>
3241   </listitem>
3242  </varlistentry>
3243
3244  <varlistentry>
3245   <term>Type:</term>
3246   <!-- boolean, parameterized, Multi-value -->
3247   <listitem>
3248    <para>Boolean.</para>
3249   </listitem>
3250  </varlistentry>
3251
3252  <varlistentry>
3253   <term>Parameter:</term>
3254   <listitem>
3255    <para>
3256     N/A
3257    </para>
3258   </listitem>
3259  </varlistentry>
3260
3261 <varlistentry>
3262   <term>Notes:</term>
3263   <listitem>
3264    <para>
3265     This is a left-over from the time when <application>Privoxy</application>
3266     didn't support important HTTP/1.1 features well. It is left here for the
3267     unlikely case that you experience HTTP/1.1 related problems with some server
3268     out there. Not all (optional) HTTP/1.1 features are supported yet, so there
3269     is a chance you might need this action.
3270    </para>
3271   </listitem>
3272  </varlistentry>
3273
3274  <varlistentry>
3275   <term>Example usage (section):</term>
3276   <listitem>
3277     <para>
3278      <screen>{+downgrade-http-version}
3279 problem-host.example.com</screen>
3280     </para>
3281   </listitem>
3282  </varlistentry>
3283
3284 </variablelist>
3285 </sect3>
3286
3287 <!--   ~~~~~       New section      ~~~~~     -->
3288 <sect3 renderas="sect4" id="fast-redirects">
3289 <title>fast-redirects</title>
3290
3291 <variablelist>
3292  <varlistentry>
3293   <term>Typical use:</term>
3294   <listitem>
3295    <para>Fool some click-tracking scripts and speed up indirect links.</para>
3296   </listitem>
3297  </varlistentry>
3298
3299  <varlistentry>
3300   <term>Effect:</term>
3301   <listitem>
3302    <para>
3303     Detects redirection URLs and redirects the browser without contacting
3304     the redirection server first.
3305    </para>
3306   </listitem>
3307  </varlistentry>
3308
3309  <varlistentry>
3310   <term>Type:</term>
3311   <!-- boolean, parameterized, Multi-value -->
3312   <listitem>
3313    <para>Parameterized.</para>
3314   </listitem>
3315  </varlistentry>
3316
3317  <varlistentry>
3318   <term>Parameter:</term>
3319   <listitem>
3320    <itemizedlist>
3321     <listitem>
3322      <para>
3323       <quote>simple-check</quote> to just search for the string <quote>http://</quote>
3324       to detect redirection URLs.
3325      </para>
3326     </listitem>
3327     <listitem>
3328      <para>
3329       <quote>check-decoded-url</quote> to decode URLs (if necessary) before searching
3330       for redirection URLs.
3331      </para>
3332     </listitem>
3333    </itemizedlist>
3334   </listitem>
3335  </varlistentry>
3336
3337  <varlistentry>
3338   <term>Notes:</term>
3339   <listitem>
3340    <para>
3341     Many sites, like yahoo.com, don't just link to other sites. Instead, they
3342     will link to some script on their own servers, giving the destination as a
3343     parameter, which will then redirect you to the final target. URLs
3344     resulting from this scheme typically look like:
3345     <quote>http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/</quote>.
3346   </para>
3347    <para>
3348     Sometimes, there are even multiple consecutive redirects encoded in the
3349     URL. These redirections via scripts make your web browsing more traceable,
3350     since the server from which you follow such a link can see where you go
3351     to. Apart from that, valuable bandwidth and time is wasted, while your
3352     browser asks the server for one redirect after the other. Plus, it feeds
3353     the advertisers.
3354    </para>
3355    <para>
3356     This feature is currently not very smart and is scheduled for improvement.
3357     If it is enabled by default, you will have to create some exceptions to
3358     this action. It can lead to failures in several ways:
3359    </para>
3360    <para>
3361     Not every URLs with other URLs as parameters is evil.
3362     Some sites offer a real service that requires this information to work.
3363     For example a validation service needs to know, which document to validate.
3364     <literal>fast-redirects</literal> assumes that every URL parameter that
3365     looks like another URL is a redirection target, and will always redirect to
3366     the last one. Most of the time the assumption is correct, but if it isn't,
3367     the user gets redirected anyway.
3368    </para>
3369    <para>
3370     Another failure occurs if the URL contains other parameters after the URL parameter.
3371     The URL:
3372     <quote>http://www.example.org/?redirect=http%3a//www.example.net/&amp;foo=bar</quote>.
3373     contains the redirection URL <quote>http://www.example.net/</quote>,
3374     followed by another parameter. <literal>fast-redirects</literal> doesn't know that
3375     and will cause a redirect to <quote>http://www.example.net/&amp;foo=bar</quote>.
3376     Depending on the target server configuration, the parameter will be silently ignored
3377     or lead to a <quote>page not found</quote> error. It is possible to fix these redirected
3378     requests with <literal><link linkend="filter-client-headers">filter-client-headers</link></literal>
3379     but it requires a little effort.
3380    </para>
3381    <para>
3382     To detect a redirection URL, <literal>fast-redirects</literal> only
3383     looks for the string <quote>http://</quote>, either in plain text
3384     (invalid but often used) or encoded as <quote>http%3a//</quote>.
3385     Some sites use their own URL encoding scheme, encrypt the address
3386     of the target server or replace it with a database id. In theses cases
3387     <literal>fast-redirects</literal> is fooled and the request reaches the
3388     redirection server where it probably gets logged.
3389    </para>
3390   </listitem>
3391  </varlistentry>
3392
3393  <varlistentry>
3394   <term>Example usage:</term>
3395   <listitem>
3396     <para>
3397      <screen>
3398  { +fast-redirects{simple-check} }
3399    .example.com
3400
3401  { +fast-redirects{check-decoded-url} }
3402    another.example.com/testing</screen>
3403     </para>
3404   </listitem>
3405  </varlistentry>
3406
3407 </variablelist>
3408 </sect3>
3409
3410
3411 <!--   ~~~~~       New section      ~~~~~     -->
3412 <sect3 renderas="sect4" id="filter">
3413 <title>filter</title>
3414
3415 <variablelist>
3416  <varlistentry>
3417   <term>Typical use:</term>
3418   <listitem>
3419    <para>Get rid of HTML and JavaScript annoyances, banner advertisements (by size),
3420          do fun text replacements, add personalized effects, etc.</para>
3421   </listitem>
3422  </varlistentry>
3423
3424  <varlistentry>
3425   <term>Effect:</term>
3426   <listitem>
3427    <para>
3428     All files of text-based type, most notably HTML and
3429     JavaScript, to which this action applies, can be filtered on-the-fly
3430     through the specified regular expression based substitutions. (Note: as of
3431     version 3.0.3 plain text documents are exempted from filtering, because
3432     web servers often use the <literal>text/plain</literal> MIME type for all
3433     files whose type they don't know.) By default, filtering works only on the
3434     raw document content itself (that which can be seen with <literal>View
3435     Source</literal>),
3436     not the headers.
3437    </para>
3438   </listitem>
3439  </varlistentry>
3440
3441  <varlistentry>
3442   <term>Type:</term>
3443   <!-- boolean, parameterized, Multi-value -->
3444   <listitem>
3445    <para>Parameterized.</para>
3446   </listitem>
3447  </varlistentry>
3448
3449  <varlistentry>
3450   <term>Parameter:</term>
3451   <listitem>
3452    <para>
3453     The name of a filter, as defined in the <link linkend="filter-file">filter file</link>.
3454     Filters can be defined in one or more  files as defined by the
3455     <literal><link linkend="filterfile">filterfile</link></literal>
3456     option in the <link linkend="config">config file</link>.
3457     <filename>default.filter</filename> is the collection of filters
3458     supplied by the developers. Locally defined filters should go
3459     in their own file, such as <filename>user.filter</filename>.
3460    </para>
3461    <para>
3462      When used in its negative form,
3463      and without parameters, <emphasis>all</emphasis> filtering is completely disabled.
3464   </para>
3465   </listitem>
3466  </varlistentry>
3467
3468  <varlistentry>
3469   <term>Notes:</term>
3470   <listitem>
3471    <para>
3472     For your convenience, there are a number of pre-defined filters available
3473     in the distribution filter file that you can use. See the examples below for
3474     a list.
3475    </para>
3476    <para>
3477     Filtering requires buffering the page content, which may appear to
3478     slow down page rendering since nothing is displayed until all content has
3479     passed the filters. (It does not really take longer, but seems that way
3480     since the page is not incrementally displayed.) This effect will be more
3481     noticeable on slower connections.
3482    </para>
3483    <para>
3484    <quote>Rolling your own</quote>
3485     filters requires a knowledge of
3486      <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
3487      Expressions</quote></ulink> and
3488       <ulink url="http://en.wikipedia.org/wiki/Html"><quote>HTML</quote></ulink>.
3489     This is very powerful feature, and potentially very intrusive.
3490     Filters should be used with caution, and where an equivalent
3491     <quote>action</quote> is not available.
3492    </para>
3493    <para>
3494     The amount of data that can be filtered is limited to the
3495     <literal><link linkend="buffer-limit">buffer-limit</link></literal>
3496     option in the main <link linkend="config">config file</link>. The
3497     default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered
3498     data, and all pending data, is passed through unfiltered.
3499    </para>
3500    <para>
3501     Inappropriate MIME types, such as zipped files, are not filtered at all.
3502     (Again, only text-based types except plain text). Encrypted SSL data
3503     (from HTTPS servers) cannot be filtered either, since this would violate
3504     the integrity of the secure transaction. In some situations it might
3505     be necessary to protect certain text, like source code, from filtering
3506     by defining appropriate <literal>-filter</literal> exceptions.
3507    </para>
3508    <para>
3509     At this time, <application>Privoxy</application> cannot uncompress compressed
3510     documents. If you want filtering to work on all documents, even those that
3511     would normally be sent compressed, you must use the
3512     <literal><link linkend="prevent-compression">prevent-compression</link></literal>
3513     action in conjunction with <literal>filter</literal>.
3514    </para>
3515    <para>
3516     Filtering can achieve some of the same effects as the
3517     <literal><link linkend="block">block</link></literal>
3518     action, i.e. it can be used to block ads and banners. But the mechanism
3519     works quite differently. One effective use, is to block ad banners
3520     based on their size (see below), since many of these seem to be somewhat
3521     standardized.
3522    </para>
3523    <para>
3524     <link linkend="contact">Feedback</link> with suggestions for new or
3525     improved filters is particularly welcome!
3526    </para>
3527    <para>
3528     The below list has only the names and a one-line description of each
3529     predefined filter. There are <link linkend="predefined-filters">more
3530     verbose explanations</link> of what these filters do in the <link
3531     linkend="filter-file">filter file chapter</link>.
3532    </para>
3533   </listitem>
3534  </varlistentry>
3535
3536  <varlistentry>
3537   <term>Example usage (with filters from the distribution <filename>default.filter</filename> file).
3538   See <link linkend="PREDEFINED-FILTERS">the Predefined Filters section</link> for
3539   more explanation on each:</term>
3540   <listitem>
3541    <para>
3542     <anchor id="filter-js-annoyances">
3543     <screen>+filter{js-annoyances}       # Get rid of particularly annoying JavaScript abuse</screen>
3544    </para>
3545    <para>
3546     <anchor id="filter-js-events">
3547     <screen>+filter{js-events}           # Kill all JS event bindings (Radically destructive! Only for extra nasty sites)</screen>
3548    </para>
3549    <para>
3550     <anchor id="filter-html-annoyances">
3551     <screen>+filter{html-annoyances}     # Get rid of particularly annoying HTML abuse</screen>
3552    </para>
3553    <para>
3554     <anchor id="filter-content-cookies">
3555     <screen>+filter{content-cookies}     # Kill cookies that come in the HTML or JS content</screen>
3556    </para>
3557    <para>
3558     <anchor id="filter-refresh-tags">
3559     <screen>+filter{refresh-tags}        # Kill automatic refresh tags (for dial-on-demand setups)</screen>
3560    </para>
3561    <para>
3562     <anchor id="filter-unsolicited-popups">
3563     <screen>+filter{unsolicited-popups}  # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.</screen>
3564    </para>
3565    <para>
3566     <anchor id="filter-all-popups">
3567     <screen>+filter{all-popups}          # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.</screen>
3568    </para>
3569    <para>
3570     <anchor id="filter-img-reorder">
3571     <screen>+filter{img-reorder}         # Reorder attributes in &lt;img&gt; tags to make the banners-by-* filters more effective</screen>
3572    </para>
3573    <para>
3574     <anchor id="filter-banners-by-size">
3575     <screen>+filter{banners-by-size}     # Kill banners by size</screen>
3576    </para>
3577    <para>
3578     <anchor id="filter-banners-by-link">
3579     <screen>+filter{banners-by-link}     # Kill banners by their links to known clicktrackers</screen>
3580    </para>
3581    <para>
3582     <anchor id="filter-webbugs">
3583     <screen>+filter{webbugs}             # Squish WebBugs (1x1 invisible GIFs used for user tracking)</screen>
3584    </para>
3585    <para>
3586     <anchor id="filter-tiny-textforms">
3587     <screen>+filter{tiny-textforms}      # Extend those tiny textareas up to 40x80 and kill the hard wrap</screen>
3588    </para>
3589    <para>
3590     <anchor id="filter-jumping-windows">
3591     <screen>+filter{jumping-windows}     # Prevent windows from resizing and moving themselves</screen>
3592    </para>
3593    <para>
3594     <anchor id="filter-frameset-borders">
3595     <screen>+filter{frameset-borders}    # Give frames a border and make them resizeable</screen>
3596    </para>
3597    <para>
3598     <anchor id="filter-demoronizer">
3599     <screen>+filter{demoronizer}         # Fix MS's non-standard use of standard charsets</screen>
3600    </para>
3601    <para>
3602     <anchor id="filter-shockwave-flash">
3603     <screen>+filter{shockwave-flash}     # Kill embedded Shockwave Flash objects</screen>
3604    </para>
3605    <para>
3606     <anchor id="filter-quicktime-kioskmode">
3607     <screen>+filter{quicktime-kioskmode} # Make Quicktime movies savable</screen>
3608    </para>
3609    <para>
3610     <anchor id="filter-fun">
3611     <screen>+filter{fun}                 # Text replacements for subversive browsing fun!</screen>
3612    </para>
3613    <para>
3614     <anchor id="filter-crude-parental">
3615     <screen>+filter{crude-parental}      # Crude parental filtering (demo only)</screen>
3616    </para>
3617    <para>
3618     <anchor id="filter-ie-exploits">
3619     <screen>+filter{ie-exploits}         # Disable some known Internet Explorer bug exploits</screen>
3620    </para>
3621    <para>
3622     <anchor id="filter-site-specifics">
3623     <screen>+filter{site-specifics}      # Custom filters for specific site related problems</screen>
3624    </para>
3625    <para>
3626     <anchor id="filter-google">
3627     <screen>+filter{google}              # Removes text ads and other Google specific improvements</screen>
3628    </para>
3629    <para>
3630     <anchor id="filter-yahoo">
3631     <screen>+filter{yahoo}               # Removes text ads and other Yahoo specific improvements</screen>
3632    </para>
3633    <para>
3634     <anchor id="filter-msn">
3635     <screen>+filter{msn}                 # Removes text ads and other MSN specific improvements</screen>
3636    </para>
3637    <para>
3638     <anchor id="filter-blogspot">
3639     <screen>+filter{blogspot}            # Cleans up Blogspot blogs</screen>
3640    </para>
3641    <para>
3642     <anchor id="filter-html-to-xml">
3643     <screen>+filter{html-to-xml}         # Header filter to change the Content-Type from html to xml</screen>
3644    </para>
3645    <para>
3646     <anchor id="filter-xml-to-html">
3647     <screen>+filter{xml-to-html}         # Header filter to change the Content-Type from xml to html</screen>
3648    </para>
3649   </listitem>
3650  </varlistentry>
3651 </variablelist>
3652 </sect3>
3653
3654
3655 <!--   ~~~~~       New section      ~~~~~     -->
3656 <sect3 renderas="sect4" id="filter-client-headers">
3657 <title>filter-client-headers</title>
3658
3659 <variablelist>
3660  <varlistentry>
3661   <term>Typical use:</term>
3662   <listitem>
3663    <para>
3664    To apply filtering to the client's (browser's) headers
3665    </para>
3666   </listitem>
3667  </varlistentry>
3668
3669  <varlistentry>
3670   <term>Effect:</term>
3671   <listitem>
3672    <para>
3673     By default, <application>Privoxy's</application> filters only apply
3674     to the document content itself. This will extend those filters to
3675     include the client's headers as well.
3676    </para>
3677   </listitem>
3678  </varlistentry>
3679
3680  <varlistentry>
3681   <term>Type:</term>
3682   <!-- boolean, parameterized, Multi-value -->
3683   <listitem>
3684    <para>Boolean.</para>
3685   </listitem>
3686  </varlistentry>
3687
3688  <varlistentry>
3689   <term>Parameter:</term>
3690   <listitem>
3691    <para>
3692     N/A
3693    </para>
3694   </listitem>
3695  </varlistentry>
3696
3697 <varlistentry>
3698   <term>Notes:</term>
3699   <listitem>
3700    <para>
3701     Regular expressions can be used to filter headers as well. Check your
3702     filters closely before activating this action, as it can easily lead to broken
3703     requests.
3704    </para>
3705    <para>
3706     These filters are applied to each header on its own, not to them
3707     all at once. This makes it easier to diagnose problems, but on the downside
3708     you can't write filters that only change header x if header y's value is
3709     z.
3710    </para>
3711    <para>
3712     The filters are used after the other header actions have finished and can
3713     use their output as input.
3714    </para>
3715
3716    <para>
3717     Whenever possible one should specify <literal>^</literal>,
3718     <literal>$</literal>, the whole header name and the colon, to make sure
3719     the filter doesn't cause havoc to other headers or the
3720     page itself. For example if you want to transform
3721     <application>Galeon</application> User-Agents to
3722     <application>Firefox</application> User-Agents you
3723     shouldn't use:
3724 </para>
3725 <para>
3726 <screen>
3727 s@Galeon/\d\.\d\.\d @@
3728 </screen>
3729 </para><para>
3730     but:
3731 </para><para>
3732 <screen>
3733 s@^(User-Agent:.*) Galeon/\d\.\d\.\d (Firefox/\d\.\d\.\d\.\d)$@$1 $2@
3734 </screen>
3735 </para>
3736   </listitem>
3737  </varlistentry>
3738
3739  <varlistentry>
3740   <term>Example usage (section):</term>
3741   <listitem>
3742     <para>
3743      <screen>
3744 {+filter-client-headers +filter{test_filter}}
3745 problem-host.example.com
3746     </screen>
3747     </para>
3748   </listitem>
3749  </varlistentry>
3750
3751 </variablelist>
3752 </sect3>
3753
3754
3755 <!--   ~~~~~       New section      ~~~~~     -->
3756 <sect3 renderas="sect4" id="filter-server-headers">
3757 <title>filter-server-headers</title>
3758
3759 <variablelist>
3760  <varlistentry>
3761   <term>Typical use:</term>
3762   <listitem>
3763    <para>
3764    To apply filtering to the server's headers
3765    </para>
3766   </listitem>
3767  </varlistentry>
3768
3769  <varlistentry>
3770   <term>Effect:</term>
3771   <listitem>
3772    <para>
3773     By default, <application>Privoxy's</application> filters only apply
3774     to the document content itself. This will extend those filters to
3775     include the server's headers as well.
3776    </para>
3777   </listitem>
3778  </varlistentry>
3779
3780  <varlistentry>
3781   <term>Type:</term>
3782   <!-- boolean, parameterized, Multi-value -->
3783   <listitem>
3784    <para>Boolean.</para>
3785   </listitem>
3786  </varlistentry>
3787
3788  <varlistentry>
3789   <term>Parameter:</term>
3790   <listitem>
3791    <para>
3792     N/A
3793    </para>
3794   </listitem>
3795  </varlistentry>
3796
3797 <varlistentry>
3798   <term>Notes:</term>
3799   <listitem>
3800    <para>
3801     Similar to <literal>filter-client-headers</literal>, but works on
3802     the server instead. To filter both server and client, use both.
3803    </para>
3804    <para>
3805     As with <literal>filter-client-headers</literal>, check your
3806     filters before activating this action, as it can easily lead to broken
3807     requests.
3808    </para>
3809    <para>
3810     These filters are applied to each header on its own, not to them
3811     all at once. This makes it easier to diagnose problems, but on the downside
3812     you can't write filters that only change header x if header y's value is
3813     z.
3814    </para>
3815    <para>
3816     The filters are used after the other header actions have finished and can
3817     use their output as input.
3818    </para>
3819    <para>
3820     Remember too, whenever possible one should specify <literal>^</literal>,
3821     <literal>$</literal>, the whole header name and the colon, to make sure
3822     the filter doesn't cause havoc to other headers or the
3823     page itself. See above for example.
3824    </para>
3825
3826   </listitem>
3827  </varlistentry>
3828
3829  <varlistentry>
3830   <term>Example usage (section):</term>
3831   <listitem>
3832     <para>
3833      <screen>
3834 {+filter-server-headers +filter{test_filter}}
3835 problem-host.example.com
3836     </screen>
3837     </para>
3838   </listitem>
3839  </varlistentry>
3840
3841 </variablelist>
3842 </sect3>
3843
3844
3845 <!--   ~~~~~       New section      ~~~~~     -->
3846 <sect3 renderas="sect4" id="force-text-mode">
3847 <title>force-text-mode</title>
3848 <!--
3849 new action
3850 -->
3851 <variablelist>
3852  <varlistentry>
3853   <term>Typical use:</term>
3854   <listitem>
3855    <para>Force <application>Privoxy</application> to treat a document as if it was in some kind of <emphasis>text</emphasis> format.   </para>
3856   </listitem>
3857  </varlistentry>
3858
3859  <varlistentry>
3860   <term>Effect:</term>
3861   <listitem>
3862    <para>
3863     Declares a document as text, even if the <quote>Content-Type:</quote> isn't detected as such.
3864    </para>
3865   </listitem>
3866  </varlistentry>
3867
3868  <varlistentry>
3869   <term>Type:</term>
3870   <!-- Boolean, Parameterized, Multi-value -->
3871   <listitem>
3872    <para>Boolean.</para>
3873   </listitem>
3874  </varlistentry>
3875
3876  <varlistentry>
3877   <term>Parameter:</term>
3878   <listitem>
3879    <para>
3880     N/A
3881    </para>
3882   </listitem>
3883  </varlistentry>
3884
3885  <varlistentry>
3886   <term>Notes:</term>
3887   <listitem>
3888    <para>
3889     As explained <literal><link linkend="filter">above</link></literal>,
3890     <application>Privoxy</application> tries to only filter files that are
3891     in some kind of text format. The same restrictions apply to
3892     <literal><link linkend="content-type-overwrite">content-type-overwrite</link></literal>.
3893     <literal>force-text-mode</literal> declares a document as text,
3894     without looking at the <quote>Content-Type:</quote> first.
3895    </para>
3896    <warning>
3897     <para>
3898      Think twice before activating this action. Filtering binary data
3899      with regular expressions can cause file damage.
3900     </para>
3901    </warning>
3902   </listitem>
3903  </varlistentry>
3904
3905  <varlistentry>
3906   <term>Example usage:</term>
3907   <listitem>
3908    <para>
3909      <screen>
3910 +force-text-mode
3911      </screen>
3912    </para>
3913   </listitem>
3914  </varlistentry>
3915 </variablelist>
3916 </sect3>
3917
3918
3919 <!--   ~~~~~       New section      ~~~~~     -->
3920 <sect3 renderas="sect4" id="handle-as-empty-document">
3921 <title>handle-as-empty-document</title>
3922 <!--
3923 new action
3924 -->
3925 <variablelist>
3926  <varlistentry>
3927   <term>Typical use:</term>
3928   <listitem>
3929    <para>Mark URLs that should be replaced by empty documents <emphasis>if they get blocked</emphasis></para>
3930   </listitem>
3931  </varlistentry>
3932
3933  <varlistentry>
3934   <term>Effect:</term>
3935   <listitem>
3936    <para>
3937     This action alone doesn't do anything noticeable. It just marks URLs.
3938     If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
3939     the presence or absence of this mark decides whether an HTML <quote>blocked</quote>
3940     page, or an empty document will be sent to the client as a substitute for the blocked content.
3941     The <emphasis>empty</emphasis> document isn't literally empty, but actually contains a single space.
3942    </para>
3943   </listitem>
3944  </varlistentry>
3945
3946  <varlistentry>
3947   <term>Type:</term>
3948   <!-- Boolean, Parameterized, Multi-value -->
3949   <listitem>
3950    <para>Boolean.</para>
3951   </listitem>
3952  </varlistentry>
3953
3954  <varlistentry>
3955   <term>Parameter:</term>
3956   <listitem>
3957    <para>
3958     N/A
3959    </para>
3960   </listitem>
3961  </varlistentry>
3962
3963  <varlistentry>
3964   <term>Notes:</term>
3965   <listitem>
3966    <para>
3967     Some browsers complain about syntax errors if JavaScript documents
3968     are blocked with <application>Privoxy's</application>
3969     default HTML page; this option can be used to silence them.
3970    </para>
3971    <para>
3972     The content type for the empty document can be specified with
3973     <literal><link linkend="content-type-overwrite">content-type-overwrite{}</link></literal>,
3974     but usually this isn't necessary.
3975    </para>
3976   </listitem>
3977  </varlistentry>
3978
3979  <varlistentry>
3980   <term>Example usage:</term>
3981   <listitem>
3982    <para>
3983      <screen># Block all documents on example.org that end with ".js",
3984 # but send an empty document instead of the usual HTML message.
3985 {+block +handle-as-empty-document}
3986 example.org/.*\.js$
3987      </screen>
3988    </para>
3989   </listitem>
3990  </varlistentry>
3991 </variablelist>
3992 </sect3>
3993
3994
3995 <!--   ~~~~~       New section      ~~~~~     -->
3996 <sect3 renderas="sect4" id="handle-as-image">
3997 <title>handle-as-image</title>
3998
3999 <variablelist>
4000  <varlistentry>
4001   <term>Typical use:</term>
4002   <listitem>
4003    <para>Mark URLs as belonging to images (so they'll be replaced by images <emphasis>if they do get blocked</emphasis>, rather than HTML pages)</para>
4004   </listitem>
4005  </varlistentry>
4006
4007  <varlistentry>
4008   <term>Effect:</term>
4009   <listitem>
4010    <para>
4011     This action alone doesn't do anything noticeable. It just marks URLs as images.
4012     If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
4013     the presence or absence of this mark decides whether an HTML <quote>blocked</quote>
4014     page, or a replacement image (as determined by the <literal><link
4015     linkend="set-image-blocker">set-image-blocker</link></literal> action) will be sent to the
4016     client as a substitute for the blocked content.
4017    </para>
4018   </listitem>
4019  </varlistentry>
4020
4021  <varlistentry>
4022   <term>Type:</term>
4023   <!-- Boolean, Parameterized, Multi-value -->
4024   <listitem>
4025    <para>Boolean.</para>
4026   </listitem>
4027  </varlistentry>
4028
4029  <varlistentry>
4030   <term>Parameter:</term>
4031   <listitem>
4032    <para>
4033     N/A
4034    </para>
4035   </listitem>
4036  </varlistentry>
4037
4038  <varlistentry>
4039   <term>Notes:</term>
4040   <listitem>
4041    <para>
4042     The below generic example section is actually part of <filename>default.action</filename>.
4043     It marks all URLs with well-known image file name extensions as images and should
4044     be left intact.
4045    </para>
4046    <para>
4047     Users will probably only want to use the handle-as-image action in conjunction with
4048     <literal><link linkend="block">block</link></literal>, to block sources of banners, whose URLs don't
4049     reflect the file type, like in the second example section.
4050    </para>
4051    <para>
4052     Note that you cannot treat HTML pages as images in most cases. For instance, (in-line) ad
4053     frames require an HTML page to be sent, or they won't display properly.
4054     Forcing <literal>handle-as-image</literal> in this situation will not replace the
4055     ad frame with an image, but lead to error messages.
4056    </para>
4057   </listitem>
4058  </varlistentry>
4059
4060  <varlistentry>
4061   <term>Example usage (sections):</term>
4062   <listitem>
4063    <para>
4064      <screen># Generic image extensions:
4065 #
4066 {+handle-as-image}
4067 /.*\.(gif|jpg|jpeg|png|bmp|ico)$
4068
4069 # These don't look like images, but they're banners and should be
4070 # blocked as images:
4071 #
4072 {+block +handle-as-image}
4073 some.nasty-banner-server.com/junk.cgi?output=trash
4074
4075 # Banner source! Who cares if they also have non-image content?
4076 ad.doubleclick.net
4077 </screen>
4078    </para>
4079   </listitem>
4080  </varlistentry>
4081 </variablelist>
4082 </sect3>
4083
4084
4085 <!--   ~~~~~       New section      ~~~~~     -->
4086 <sect3 renderas="sect4" id="hide-accept-language">
4087 <title>hide-accept-language</title>
4088 <!--
4089 new action
4090 -->
4091 <variablelist>
4092  <varlistentry>
4093   <term>Typical use:</term>
4094   <listitem>
4095    <para>Pretend to use different language settings.</para>
4096   </listitem>
4097  </varlistentry>
4098
4099  <varlistentry>
4100   <term>Effect:</term>
4101   <listitem>
4102    <para>
4103     Deletes or replaces the <quote>Accept-Language:</quote> HTTP header in client requests.
4104    </para>
4105   </listitem>
4106  </varlistentry>
4107
4108  <varlistentry>
4109   <term>Type:</term>
4110   <!-- Boolean, Parameterized, Multi-value -->
4111   <listitem>
4112    <para>Parameterized.</para>
4113   </listitem>
4114  </varlistentry>
4115
4116  <varlistentry>
4117   <term>Parameter:</term>
4118   <listitem>
4119    <para>
4120     Keyword: <quote>block</quote>, or any user defined value.
4121    </para>
4122   </listitem>
4123  </varlistentry>
4124
4125  <varlistentry>
4126   <term>Notes:</term>
4127   <listitem>
4128    <para>
4129     Faking the browser's language settings can be useful to make a
4130     foreign User-Agent set with
4131     <literal><link linkend="hide-user-agent">hide-user-agent</link></literal>
4132     more believable.
4133    </para>
4134    <para>
4135     However some sites with content in different languages check the
4136     <quote>Accept-Language:</quote> to decide which one to take by default.
4137     Sometimes it isn't possible to later switch to another language without
4138     changing the <quote>Accept-Language:</quote> header first.
4139    </para>
4140    <para>
4141     Therefore it's a good idea to either only change the
4142     <quote>Accept-Language:</quote> header to languages you understand,
4143     or to languages that aren't wide spread.
4144    </para>
4145    <para>
4146     Before setting the <quote>Accept-Language:</quote> header
4147     to a rare language, you should consider that it helps to
4148     make your requests unique and thus easier to trace.
4149     If you don't plan to change this header frequently,
4150     you should stick to a common language.
4151    </para>
4152   </listitem>
4153  </varlistentry>
4154
4155  <varlistentry>
4156   <term>Example usage (section):</term>
4157   <listitem>
4158     <para>
4159      <screen># Pretend to use Canadian language settings.
4160 {+hide-accept-language{en-ca} \
4161 +hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \
4162 }
4163 /   </screen>
4164    </para>
4165   </listitem>
4166  </varlistentry>
4167 </variablelist>
4168 </sect3>
4169
4170
4171 <!--   ~~~~~       New section      ~~~~~     -->
4172 <sect3 renderas="sect4" id="hide-content-disposition">
4173 <title>hide-content-disposition</title>
4174 <!--
4175 new action
4176 -->
4177 <variablelist>
4178  <varlistentry>
4179   <term>Typical use:</term>
4180   <listitem>
4181    <para>Prevent download menus for content you prefer to view inside the browser.</para>
4182   </listitem>
4183  </varlistentry>
4184
4185  <varlistentry>
4186   <term>Effect:</term>
4187   <listitem>
4188    <para>
4189     Deletes or replaces the <quote>Content-Disposition:</quote> HTTP header set by some servers.
4190    </para>
4191   </listitem>
4192  </varlistentry>
4193
4194  <varlistentry>
4195   <term>Type:</term>
4196   <!-- Boolean, Parameterized, Multi-value -->
4197   <listitem>
4198    <para>Parameterized.</para>
4199   </listitem>
4200  </varlistentry>
4201
4202  <varlistentry>
4203   <term>Parameter:</term>
4204   <listitem>
4205    <para>
4206     Keyword: <quote>block</quote>, or any user defined value.
4207    </para>
4208   </listitem>
4209  </varlistentry>
4210
4211  <varlistentry>
4212   <term>Notes:</term>
4213   <listitem>
4214    <para>
4215     Some servers set the <quote>Content-Disposition:</quote> HTTP header for
4216     documents they assume you want to save locally before viewing them.
4217     The <quote>Content-Disposition:</quote> header contains the file name
4218     the browser is supposed to use by default.
4219    </para>
4220    <para>
4221     In most browsers that understand this header, it makes it impossible to
4222     <emphasis>just view</emphasis> the document, without downloading it first,
4223     even if it's just a simple text file or an image.
4224    </para>
4225    <para>
4226     Removing the <quote>Content-Disposition:</quote> header helps
4227     to prevent this annoyance, but some browsers additionally check the
4228     <quote>Content-Type:</quote> header, before they decide if they can
4229     display a document without saving it first. In these cases, you have
4230     to change this header as well, before the browser stops displaying
4231     download menus.
4232    </para>
4233    <para>
4234     It is also possible to change the server's file name suggestion
4235     to another one, but in most cases it isn't worth the time to set
4236     it up.
4237    </para>
4238   </listitem>
4239  </varlistentry>
4240
4241  <varlistentry>
4242   <term>Example usage:</term>
4243   <listitem>
4244     <para>
4245      <screen># Disarm the download link in Sourceforge's patch tracker
4246 {-filter\
4247 +content-type-overwrite {text/plain}\
4248 +hide-content-disposition {block} }
4249 .sourceforge.net/tracker/download.php</screen>
4250    </para>
4251   </listitem>
4252  </varlistentry>
4253 </variablelist>
4254 </sect3>
4255
4256
4257 <!--   ~~~~~       New section      ~~~~~     -->
4258 <sect3 renderas="sect4" id="hide-if-modified-since">
4259 <title>hide-if-modified-since</title>
4260 <!--
4261 new action
4262 -->
4263 <variablelist>
4264  <varlistentry>
4265   <term>Typical use:</term>
4266   <listitem>
4267    <para>Prevent yet another way to track the user's steps between sessions.</para>
4268   </listitem>
4269  </varlistentry>
4270
4271  <varlistentry>
4272   <term>Effect:</term>
4273   <listitem>
4274    <para>
4275     Deletes the <quote>If-Modified-Since:</quote> HTTP client header or modifies its value.
4276    </para>
4277   </listitem>
4278  </varlistentry>
4279
4280  <varlistentry>
4281   <term>Type:</term>
4282   <!-- Boolean, Parameterized, Multi-value -->
4283   <listitem>
4284    <para>Parameterized.</para>
4285   </listitem>
4286  </varlistentry>
4287
4288  <varlistentry>
4289   <term>Parameter:</term>
4290   <listitem>
4291    <para>
4292     Keyword: <quote>block</quote>, or a user defined value that specifies a range of hours.
4293    </para>
4294   </listitem>
4295  </varlistentry>
4296
4297  <varlistentry>
4298   <term>Notes:</term>
4299   <listitem>
4300    <para>
4301     Removing this header is useful for filter testing, where you want to force a real
4302     reload instead of getting status code <quote>304</quote>, which would cause the
4303     browser to use a cached copy of the page.
4304    </para>
4305    <para>
4306     Instead of removing the header, <literal>hide-if-modified-since</literal> can
4307     also add or subtract a random amount of time to/from the header's value.
4308     You specify a range of minutes where the random factor should be chosen from and
4309     <application>Privoxy</application> does the rest. A negative value means
4310     subtracting, a positive value adding.
4311    </para>
4312    <para>
4313     Randomizing the value of the <quote>If-Modified-Since:</quote> makes
4314     sure it isn't used as a cookie replacement, but you will run into
4315     caching problems if the random range is too high.
4316    </para>
4317    <para>
4318     It is a good idea to only use a small negative value and let
4319     <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>
4320     handle the greater changes.
4321    </para>
4322    <para>
4323     It is also recommended to use this action together with
4324     <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>.
4325    </para>
4326   </listitem>
4327  </varlistentry>
4328
4329  <varlistentry>
4330   <term>Example usage (section):</term>
4331   <listitem>
4332     <para>
4333      <screen># Let the browser revalidate without being tracked across sessions
4334 {+hide-if-modified-since {-60}\
4335 +overwrite-last-modified {randomize}\
4336 +crunch-if-none-match}
4337 /</screen>
4338    </para>
4339   </listitem>
4340  </varlistentry>
4341 </variablelist>
4342 </sect3>
4343
4344
4345 <!--   ~~~~~       New section      ~~~~~     -->
4346 <sect3 renderas="sect4" id="hide-forwarded-for-headers">
4347 <title>hide-forwarded-for-headers</title>
4348 <!--
4349 new action
4350 -->
4351 <variablelist>
4352  <varlistentry>
4353   <term>Typical use:</term>
4354   <listitem>
4355    <para>Improve privacy by hiding the true source of the request</para>
4356   </listitem>
4357  </varlistentry>
4358
4359  <varlistentry>
4360   <term>Effect:</term>
4361   <listitem>
4362    <para>
4363     Deletes any existing <quote>X-Forwarded-for:</quote> HTTP header from client requests,
4364     and prevents adding a new one.
4365    </para>
4366   </listitem>
4367  </varlistentry>
4368
4369  <varlistentry>
4370   <term>Type:</term>
4371   <!-- Boolean, Parameterized, Multi-value -->
4372   <listitem>
4373    <para>Boolean.</para>
4374   </listitem>
4375  </varlistentry>
4376
4377  <varlistentry>
4378   <term>Parameter:</term>
4379   <listitem>
4380    <para>
4381     N/A
4382    </para>
4383   </listitem>
4384  </varlistentry>
4385
4386  <varlistentry>
4387   <term>Notes:</term>
4388   <listitem>
4389    <para>
4390     It is fairly safe to leave this on.
4391    </para>
4392    <para>
4393     This action is scheduled for improvement: It should be able to generate forged
4394     <quote>X-Forwarded-for:</quote> headers using random IP addresses from a specified network,
4395     to make successive requests from the same client look like requests from a pool of different
4396     users sharing the same proxy.
4397    </para>
4398   </listitem>
4399  </varlistentry>
4400
4401  <varlistentry>
4402   <term>Example usage:</term>
4403   <listitem>
4404     <para>
4405      <screen>+hide-forwarded-for-headers</screen>
4406    </para>
4407   </listitem>
4408  </varlistentry>
4409 </variablelist>
4410 </sect3>
4411
4412
4413 <!--   ~~~~~       New section      ~~~~~     -->
4414 <sect3 renderas="sect4" id="hide-from-header">
4415 <title>hide-from-header</title>
4416
4417 <variablelist>
4418  <varlistentry>
4419   <term>Typical use:</term>
4420   <listitem>
4421    <para>Keep your (old and ill) browser from telling web servers your email address</para>
4422   </listitem>
4423  </varlistentry>
4424
4425  <varlistentry>
4426   <term>Effect:</term>
4427   <listitem>
4428    <para>
4429     Deletes any existing <quote>From:</quote> HTTP header, or replaces it with the
4430     specified string.
4431    </para>
4432   </listitem>
4433  </varlistentry>
4434
4435  <varlistentry>
4436   <term>Type:</term>
4437   <!-- Boolean, Parameterized, Multi-value -->
4438   <listitem>
4439    <para>Parameterized.</para>
4440   </listitem>
4441  </varlistentry>
4442
4443  <varlistentry>
4444   <term>Parameter:</term>
4445   <listitem>
4446    <para>
4447     Keyword: <quote>block</quote>, or any user defined value.
4448    </para>
4449   </listitem>
4450  </varlistentry>
4451
4452  <varlistentry>
4453   <term>Notes:</term>
4454   <listitem>
4455    <para>
4456     The keyword <quote>block</quote> will completely remove the header
4457     (not to be confused with the <literal><link linkend="block">block</link></literal>
4458     action).
4459    </para>
4460    <para>
4461     Alternately, you can specify any value you prefer to be sent to the web
4462     server. If you do, it is a matter of fairness not to use any address that
4463     is actually used by a real person.
4464    </para>
4465    <para>
4466     This action is rarely needed, as modern web browsers don't send
4467     <quote>From:</quote> headers anymore.
4468    </para>
4469   </listitem>
4470  </varlistentry>
4471
4472  <varlistentry>
4473   <term>Example usage:</term>
4474   <listitem>
4475    <para>
4476     <screen>+hide-from-header{block}</screen> or
4477     <screen>+hide-from-header{spam-me-senseless@sittingduck.example.com}</screen>
4478    </para>
4479   </listitem>
4480  </varlistentry>
4481 </variablelist>
4482 </sect3>
4483
4484
4485 <!--   ~~~~~       New section      ~~~~~     -->
4486 <sect3 renderas="sect4" id="hide-referrer">
4487 <title>hide-referrer</title>
4488 <anchor id="hide-referer">
4489 <variablelist>
4490  <varlistentry>
4491   <term>Typical use:</term>
4492   <listitem>
4493    <para>Conceal which link you followed to get to a particular site</para>
4494   </listitem>
4495  </varlistentry>
4496
4497  <varlistentry>
4498   <term>Effect:</term>
4499   <listitem>
4500    <para>
4501     Deletes the <quote>Referer:</quote> (sic) HTTP header from the client request,
4502     or replaces it with a forged one.
4503    </para>
4504   </listitem>
4505  </varlistentry>
4506
4507  <varlistentry>
4508   <term>Type:</term>
4509   <!-- Boolean, Parameterized, Multi-value -->
4510   <listitem>
4511    <para>Parameterized.</para>
4512   </listitem>
4513  </varlistentry>
4514
4515  <varlistentry>
4516   <term>Parameter:</term>
4517   <listitem>
4518    <itemizedlist>
4519     <listitem>
4520      <para><quote>conditional-block</quote> to delete the header completely if the host has changed.</para>
4521     </listitem>
4522     <listitem>
4523      <para><quote>block</quote> to delete the header unconditionally.</para>
4524     </listitem>
4525     <listitem>
4526      <para><quote>forge</quote> to pretend to be coming from the homepage of the server we are talking to.</para>
4527     </listitem>
4528     <listitem>
4529      <para>Any other string to set a user defined referrer.</para>
4530     </listitem>
4531    </itemizedlist>
4532   </listitem>
4533  </varlistentry>
4534
4535  <varlistentry>
4536   <term>Notes:</term>
4537   <listitem>
4538    <para>
4539     <literal>conditional-block</literal> is the only parameter,
4540     that isn't easily detected in the server's log file. If it blocks the
4541     referrer, the request will look like the visitor used a bookmark or
4542     typed in the address directly.
4543    </para>
4544    <para>
4545     Leaving the referrer unmodified for requests on the same host
4546     allows the server owner to see the visitor's <quote>click path</quote>,
4547     but in most cases she could also get that information by comparing
4548     other parts of the log file: for example the User-Agent if it isn't
4549     a very common one, or the user's IP address if it doesn't change between
4550     different requests.
4551    </para>
4552    <para>
4553     Always blocking the referrer, or using a custom one, can lead to
4554     failures on servers that check the referrer before they answer any
4555     requests, in an attempt to prevent their valuable content from being
4556     embedded or linked to elsewhere.
4557    </para>
4558    <para>
4559     Both <literal>conditional-block</literal> and <literal>forge</literal>
4560     will work with referrer checks, as long as content and valid referring page
4561     are on the same host. Most of the time that's the case.
4562    </para>
4563    <para>
4564     <literal>hide-referer</literal> is an alternate spelling of
4565     <literal>hide-referrer</literal> and the two can be can be freely
4566     substituted with each other. (<quote>referrer</quote> is the
4567     correct English spelling, however the HTTP specification has a bug - it
4568     requires it to be spelled as <quote>referer</quote>.)
4569    </para>
4570   </listitem>
4571  </varlistentry>
4572
4573  <varlistentry>
4574   <term>Example usage:</term>
4575   <listitem>
4576    <para>
4577      <screen>+hide-referrer{forge}</screen> or
4578      <screen>+hide-referrer{http://www.yahoo.com/}</screen>
4579    </para>
4580   </listitem>
4581  </varlistentry>
4582 </variablelist>
4583 </sect3>
4584
4585
4586 <!--   ~~~~~       New section      ~~~~~     -->
4587 <sect3 renderas="sect4" id="hide-user-agent">
4588 <title>hide-user-agent</title>
4589
4590 <variablelist>
4591  <varlistentry>
4592   <term>Typical use:</term>
4593   <listitem>
4594    <para>Conceal your type of browser and client operating system</para>
4595   </listitem>
4596  </varlistentry>
4597
4598  <varlistentry>
4599   <term>Effect:</term>
4600   <listitem>
4601    <para>
4602     Replaces the value of the <quote>User-Agent:</quote> HTTP header
4603     in client requests with the specified value.
4604    </para>
4605   </listitem>
4606  </varlistentry>
4607
4608  <varlistentry>
4609   <term>Type:</term>
4610   <!-- Boolean, Parameterized, Multi-value -->
4611   <listitem>
4612    <para>Parameterized.</para>
4613   </listitem>
4614  </varlistentry>
4615
4616  <varlistentry>
4617   <term>Parameter:</term>
4618   <listitem>
4619    <para>
4620     Any user-defined string.
4621    </para>
4622   </listitem>
4623  </varlistentry>
4624
4625  <varlistentry>
4626   <term>Notes:</term>
4627   <listitem>
4628    <warning>
4629     <para>
4630      This can lead to problems on web sites that depend on looking at this header in
4631      order to customize their content for different browsers (which, by the
4632      way, is <emphasis>NOT</emphasis> the right thing to do: good web sites
4633      work browser-independently).
4634      <!--
4635      <ulink url="http://www.javascriptkit.com/javaindex.shtml">smart way to do
4636      that</ulink>!).
4637      -->
4638     </para>
4639    </warning>
4640    <para>
4641     Using this action in multi-user setups or wherever different types of
4642     browsers will access the same <application>Privoxy</application> is
4643     <emphasis>not recommended</emphasis>. In single-user, single-browser
4644     setups, you might use it to delete your OS version information from
4645     the headers, because it is an invitation to exploit known bugs for your
4646     OS. It is also occasionally useful to forge this in order to access
4647     sites that won't let you in otherwise (though there may be a good
4648     reason in some cases). Example of this: some MSN sites will not
4649     let <application>Mozilla</application> enter, yet forging to a
4650     <application>Netscape 6.1</application> user-agent works just fine.
4651     (Must be just a silly MS goof, I'm sure :-).
4652    </para>
4653    <para>
4654     This action is scheduled for improvement.
4655    </para>
4656    </listitem>
4657  </varlistentry>
4658
4659  <varlistentry>
4660   <term>Example usage:</term>
4661   <listitem>
4662    <para>
4663      <screen>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</screen>
4664    </para>
4665   </listitem>
4666  </varlistentry>
4667 </variablelist>
4668 </sect3>
4669
4670
4671 <!--   ~~~~~       New section      ~~~~~     -->
4672 <sect3 renderas="sect4" id="inspect-jpegs">
4673 <title>inspect-jpegs</title>
4674 <!--
4675 new action
4676 -->
4677 <variablelist>
4678  <varlistentry>
4679   <term>Typical use:</term>
4680   <listitem>
4681    <para>To protect against the MS buffer over-run in JPEG processing</para>
4682   </listitem>
4683  </varlistentry>
4684
4685  <varlistentry>
4686   <term>Effect:</term>
4687   <listitem>
4688    <para>
4689     Protect against a known exploit
4690    </para>
4691   </listitem>
4692  </varlistentry>
4693
4694  <varlistentry>
4695   <term>Type:</term>
4696   <!-- Boolean, Parameterized, Multi-value -->
4697   <listitem>
4698    <para>Boolean.</para>
4699   </listitem>
4700  </varlistentry>
4701
4702  <varlistentry>
4703   <term>Parameter:</term>
4704   <listitem>
4705    <para>
4706     N/A
4707    </para>
4708   </listitem>
4709  </varlistentry>
4710
4711  <varlistentry>
4712   <term>Notes:</term>
4713   <listitem>
4714    <para>
4715     See Microsoft Security Bulletin MS04-028. JPEG images are one of the most
4716     common image types found across the Internet. The exploit as described can
4717     allow execution of code on the target system, giving an attacker access
4718     to the system in question by merely planting an altered JPEG image, which
4719     would have no obvious indications of what lurks inside. This action
4720     prevents unwanted intrusion.
4721    </para>
4722
4723   </listitem>
4724  </varlistentry>
4725
4726  <varlistentry>
4727   <term>Example usage:</term>
4728   <listitem>
4729    <para><screen>+inspect-jpegs</screen></para>
4730   </listitem>
4731  </varlistentry>
4732 </variablelist>
4733 </sect3>
4734
4735
4736
4737
4738 <!--   ~~~~~       New section      ~~~~~     -->
4739 <sect3 renderas="sect4" id="kill-popups">
4740 <title>kill-popups<anchor id="kill-popup"></title>
4741
4742 <variablelist>
4743  <varlistentry>
4744   <term>Typical use:</term>
4745   <listitem>
4746    <para>Eliminate those annoying pop-up windows (deprecated)</para>
4747   </listitem>
4748  </varlistentry>
4749
4750  <varlistentry>
4751   <term>Effect:</term>
4752   <listitem>
4753    <para>
4754     While loading the document, replace JavaScript code that opens
4755     pop-up windows with (syntactically neutral) dummy code on the fly.
4756    </para>
4757   </listitem>
4758  </varlistentry>
4759
4760  <varlistentry>
4761   <term>Type:</term>
4762   <!-- Boolean, Parameterized, Multi-value -->
4763   <listitem>
4764    <para>Boolean.</para>
4765   </listitem>
4766  </varlistentry>
4767
4768  <varlistentry>
4769   <term>Parameter:</term>
4770   <listitem>
4771    <para>
4772     N/A
4773    </para>
4774   </listitem>
4775  </varlistentry>
4776
4777  <varlistentry>
4778   <term>Notes:</term>
4779   <listitem>
4780    <para>
4781     This action is basically a built-in, hardwired special-purpose filter
4782     action, but there are important differences: For <literal>kill-popups</literal>,
4783     the document need not be buffered, so it can be incrementally rendered while
4784     downloading. But <literal>kill-popups</literal> doesn't catch as many pop-ups as
4785     <literal><link
4786     linkend="FILTER-ALL-POPUPS">filter{<replaceable>all-popups</replaceable>}</link></literal>
4787     does and is not as smart as <literal><link
4788     linkend="FILTER-UNSOLICITED-POPUPS">filter{<replaceable>unsolicited-popups</replaceable>}</link>
4789     </literal>is.
4790    </para>
4791    <para>
4792     Think of it as a fast and efficient replacement for a filter that you
4793     can use if you don't want any filtering at all. Note that it doesn't make
4794     sense to combine it with any <literal><link linkend="filter">filter</link></literal> action,
4795     since as soon as one <literal><link linkend="filter">filter</link></literal> applies,
4796     the whole document needs to be buffered anyway, which destroys the advantage of
4797     the <literal>kill-popups</literal> action over its filter equivalent.
4798    </para>
4799    <para>
4800     Killing all pop-ups unconditionally is problematic. Many shops and banks rely on
4801     pop-ups to display forms, shopping carts etc, and the <literal><link
4802     linkend="FILTER-UNSOLICITED-POPUPS">filter{<replaceable>unsolicited-popups</replaceable>}</link>
4803     </literal> does a better job of catching only the unwanted ones.
4804    </para>
4805    <para>
4806     If the only kind of pop-ups that you want to kill are exit consoles (those
4807     <emphasis>really nasty</emphasis> windows that appear when you close an other
4808     one), you might want to use
4809     <literal><link
4810     linkend="filter">filter</link>{<replaceable>js-annoyances</replaceable>}</literal>
4811     instead.
4812    </para>
4813    <para>
4814     This action is most appropriate for browsers that don't have any controls
4815     for unwanted pop-ups. Not recommended for general usage.
4816    </para>
4817
4818   <!--
4819    <para>
4820     An alternate spelling is <literal>+kill-popup</literal>, which is
4821     interchangeable.
4822    </para>
4823  -->
4824   </listitem>
4825  </varlistentry>
4826
4827  <varlistentry>
4828   <term>Example usage:</term>
4829   <listitem>
4830    <para><screen>+kill-popups</screen></para>
4831   </listitem>
4832  </varlistentry>
4833 </variablelist>
4834 </sect3>
4835
4836
4837 <!--   ~~~~~       New section      ~~~~~     -->
4838 <sect3 renderas="sect4" id="limit-connect">
4839 <title>limit-connect</title>
4840
4841 <variablelist>
4842  <varlistentry>
4843   <term>Typical use:</term>
4844   <listitem>
4845    <para>Prevent abuse of <application>Privoxy</application> as a TCP proxy relay or disable SSL for untrusted sites</para>
4846   </listitem>
4847  </varlistentry>
4848
4849  <varlistentry>
4850   <term>Effect:</term>
4851   <listitem>
4852    <para>
4853     Specifies to which ports HTTP CONNECT requests are allowable.
4854    </para>
4855   </listitem>
4856  </varlistentry>
4857
4858  <varlistentry>
4859   <term>Type:</term>
4860   <!-- Boolean, Parameterized, Multi-value -->
4861   <listitem>
4862    <para>Parameterized.</para>
4863   </listitem>
4864  </varlistentry>
4865
4866  <varlistentry>
4867   <term>Parameter:</term>
4868   <listitem>
4869    <para>
4870     A comma-separated list of ports or port ranges (the latter using dashes, with the minimum
4871     defaulting to 0 and the maximum to 65K).
4872    </para>
4873   </listitem>
4874  </varlistentry>
4875
4876  <varlistentry>
4877   <term>Notes:</term>
4878   <listitem>
4879    <para>
4880     By default, i.e. if no <literal>limit-connect</literal> action applies,
4881     <application>Privoxy</application> only allows HTTP CONNECT
4882     requests to port 443 (the standard, secure HTTPS port). Use
4883     <literal>limit-connect</literal> if more fine-grained control is desired
4884     for some or all destinations.
4885    </para>
4886    <para>
4887     The CONNECT methods exists in HTTP to allow access to secure websites
4888     (<quote>https://</quote> URLs) through proxies. It works very simply:
4889     the proxy connects to the server on the specified port, and then
4890     short-circuits its connections to the client and to the remote server.
4891     This can be a big security hole, since CONNECT-enabled proxies can be
4892     abused as TCP relays very easily.
4893   </para>
4894   <para>
4895    <application>Privoxy</application> relays HTTPS traffic without seeing
4896    the decoded content. Websites can leverage this limitation to circumvent &my-app;'s
4897    filters. By specifying an invalid port range you can disable HTTPS entirely.
4898    If you plan to disable SSL by default, consider enabling
4899    <literal><link linkend="treat-forbidden-connects-like-blocks ">treat-forbidden-connects-like-blocks</link></literal>
4900    as well, to be able to quickly create exceptions.
4901   </para>
4902   </listitem>
4903  </varlistentry>
4904
4905  <varlistentry>
4906   <term>Example usages:</term>
4907   <listitem>
4908    <!-- I had trouble getting the spacing to look right in my browser -->
4909    <!-- I probably have the wrong font setup, bollocks. -->
4910    <!-- Apparently the emphasis tag uses a proportional font no matter what -->
4911     <para>
4912      <screen>+limit-connect{443}                   # This is the default and need not be specified.
4913 +limit-connect{80,443}                # Ports 80 and 443 are OK.
4914 +limit-connect{-3, 7, 20-100, 500-}   # Ports less than 3, 7, 20 to 100 and above 500 are OK.
4915 +limit-connect{-}                     # All ports are OK
4916 +limit-connect{,}                     # No HTTPS/SSL traffic is allowed</screen>
4917    </para>
4918   </listitem>
4919  </varlistentry>
4920 </variablelist>
4921 </sect3>
4922
4923 <!--   ~~~~~       New section      ~~~~~     -->
4924 <sect3 renderas="sect4" id="prevent-compression">
4925 <title>prevent-compression</title>
4926
4927 <variablelist>
4928  <varlistentry>
4929   <term>Typical use:</term>
4930   <listitem>
4931    <para>
4932     Ensure that servers send the content uncompressed, so it can be
4933     passed through <literal><link linkend="filter">filter</link></literal>s.
4934    </para>
4935   </listitem>
4936  </varlistentry>
4937
4938  <varlistentry>
4939   <term>Effect:</term>
4940   <listitem>
4941    <para>
4942     Removes the Accept-Encoding header which can be used to ask for compressed transfer.
4943    </para>
4944   </listitem>
4945  </varlistentry>
4946
4947  <varlistentry>
4948   <term>Type:</term>
4949   <!-- Boolean, Parameterized, Multi-value -->
4950   <listitem>
4951    <para>Boolean.</para>
4952   </listitem>
4953  </varlistentry>
4954
4955  <varlistentry>
4956   <term>Parameter:</term>
4957   <listitem>
4958    <para>
4959     N/A
4960    </para>
4961   </listitem>
4962  </varlistentry>
4963
4964  <varlistentry>
4965   <term>Notes:</term>
4966   <listitem>
4967    <para>
4968     More and more websites send their content compressed by default, which
4969     is generally a good idea and saves bandwidth. But for the <literal><link
4970     linkend="filter">filter</link></literal>, <literal><link linkend="deanimate-gifs">deanimate-gifs</link></literal>
4971     and <literal><link linkend="kill-popups">kill-popups</link></literal> actions to work,
4972     <application>Privoxy</application> needs access to the  uncompressed data.
4973     Unfortunately, <application>Privoxy</application> can't yet(!)  uncompress, filter, and
4974     re-compress the content on the fly. So if you want to ensure that all websites, including
4975     those that normally compress, can be filtered, you need to use this action.
4976    </para>
4977    <para>
4978     This will slow down transfers from those websites, though. If you use any of the above-mentioned
4979     actions, you will typically want to use <literal>prevent-compression</literal> in conjunction
4980     with them.
4981    </para>
4982    <para>
4983     Note that some (rare) ill-configured sites don't handle requests for uncompressed
4984     documents correctly (they send an empty document body). If you use <literal>prevent-compression</literal>
4985     per default, you'll have to add exceptions for those sites. See the example for how to do that.
4986    </para>
4987   </listitem>
4988  </varlistentry>
4989
4990  <varlistentry>
4991   <term>Example usage (sections):</term>
4992   <listitem>
4993    <para>
4994     <screen># Set default:
4995 #
4996 {+prevent-compression}
4997 / # Match all sites
4998
4999 # Make exceptions for ill sites:
5000 #
5001 {-prevent-compression}
5002 www.debianhelp.org
5003 www.pclinuxonline.com</screen>
5004    </para>
5005   </listitem>
5006  </varlistentry>
5007
5008 </variablelist>
5009 </sect3>
5010
5011
5012 <!--   ~~~~~       New section      ~~~~~     -->
5013 <sect3 renderas="sect4" id="overwrite-last-modified">
5014 <title>overwrite-last-modified</title>
5015 <!--
5016 new action
5017 -->
5018 <variablelist>
5019  <varlistentry>
5020   <term>Typical use:</term>
5021   <listitem>
5022    <para>Prevent yet another way to track the user's steps between sessions.</para>
5023   </listitem>
5024  </varlistentry>
5025
5026  <varlistentry>
5027   <term>Effect:</term>
5028   <listitem>
5029    <para>
5030     Deletes the <quote>Last-Modified:</quote> HTTP server header or modifies its value.
5031    </para>
5032   </listitem>
5033  </varlistentry>
5034
5035  <varlistentry>
5036   <term>Type:</term>
5037   <!-- Boolean, Parameterized, Multi-value -->
5038   <listitem>
5039    <para>Parameterized.</para>
5040   </listitem>
5041  </varlistentry>
5042
5043  <varlistentry>
5044   <term>Parameter:</term>
5045   <listitem>
5046    <para>
5047     One of the keywords: <quote>block</quote>, <quote>reset-to-request-time</quote>
5048     and <quote>randomize</quote>
5049    </para>
5050   </listitem>
5051  </varlistentry>
5052
5053  <varlistentry>
5054   <term>Notes:</term>
5055   <listitem>
5056    <para>
5057     Removing the <quote>Last-Modified:</quote> header is useful for filter
5058     testing, where you want to force a real reload instead of getting status
5059     code <quote>304</quote>, which would cause the browser to reuse the old
5060     version of the page.
5061    </para>
5062    <para>
5063     The <quote>randomize</quote> option overwrites the value of the
5064     <quote>Last-Modified:</quote> header with a randomly chosen time
5065     between the original value and the current time. In theory the server
5066     could send each document with a different <quote>Last-Modified:</quote>
5067     header to track visits without using cookies. <quote>Randomize</quote>
5068     makes it impossible and the browser can still revalidate cached documents.
5069    </para>
5070    <para>
5071     <quote>reset-to-request-time</quote> overwrites the value of the
5072     <quote>Last-Modified:</quote> header with the current time. You could use
5073     this option together with
5074     <literal><link linkend="hide-if-modified-since">hided-if-modified-since</link></literal>
5075     to further customize your random range.
5076    </para>
5077    <para>
5078     The preferred parameter here is <quote>randomize</quote>. It is safe
5079     to use, as long as the time settings are more or less correct.
5080     If the server sets the <quote>Last-Modified:</quote> header to the time
5081     of the request, the random range becomes zero and the value stays the same.
5082     Therefore you should later randomize it a second time with
5083     <literal><link linkend="hide-if-modified-since">hided-if-modified-since</link></literal>,
5084     just to be sure.
5085    </para>
5086    <para>
5087     It is also recommended to use this action together with
5088     <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>.
5089    </para>
5090   </listitem>
5091  </varlistentry>
5092
5093  <varlistentry>
5094   <term>Example usage:</term>
5095   <listitem>
5096     <para>
5097      <screen># Let the browser revalidate without being tracked across sessions
5098 {+hide-if-modified-since {-60}\
5099 +overwrite-last-modified {randomize}\
5100 +crunch-if-none-match}
5101 /</screen>
5102    </para>
5103   </listitem>
5104  </varlistentry>
5105 </variablelist>
5106 </sect3>
5107
5108
5109 <!--   ~~~~~       New section      ~~~~~     -->
5110 <sect3 renderas="sect4" id="redirect">
5111 <title>redirect</title>
5112 <!--
5113 new action
5114 -->
5115 <variablelist>
5116  <varlistentry>
5117   <term>Typical use:</term>
5118   <listitem>
5119    <para>
5120     Redirect requests to other sites.
5121    </para>
5122   </listitem>
5123  </varlistentry>
5124
5125  <varlistentry>
5126   <term>Effect:</term>
5127   <listitem>
5128    <para>
5129     Convinces the browser that the requested document has been moved
5130     to another location and the browser should get it from there.
5131    </para>
5132   </listitem>
5133  </varlistentry>
5134
5135  <varlistentry>
5136   <term>Type:</term>
5137   <!-- Boolean, Parameterized, Multi-value -->
5138   <listitem>
5139    <para>Parameterized</para>
5140   </listitem>
5141  </varlistentry>
5142
5143  <varlistentry>
5144   <term>Parameter:</term>
5145   <listitem>
5146    <para>
5147     Any URL.
5148    </para>
5149   </listitem>
5150  </varlistentry>
5151
5152  <varlistentry>
5153   <term>Notes:</term>
5154   <listitem>
5155    <para>
5156     This action is useful to replace whole documents with ones of your
5157     choosing. This can be used to enforce safe surfing, or just as a simple
5158     convenience.
5159    </para>
5160    <para>
5161     You can do the same by combining the actions
5162     <literal><link linkend="block">block</link></literal>,
5163     <literal><link linkend="handle-as-image">handle-as-image</link></literal> and
5164     <literal><link linkend="set-image-blocker">set-image-blocker{URL}</link></literal>.
5165     It doesn't sound right for non-image documents, and that's why this action
5166     was created.
5167    </para>
5168    <para>
5169     This action will be ignored if you use it together with
5170     <literal><link linkend="block">block</link></literal>.
5171    </para>
5172   </listitem>
5173  </varlistentry>
5174
5175  <varlistentry>
5176   <term>Example usages:</term>
5177   <listitem>
5178    <para>
5179     <screen># Replace example.com's style sheet with another one
5180 { +redirect{http://localhost/css-replacements/example.com.css} }
5181  example.com/stylesheet.css
5182
5183 # Create a short, easy to remember nickname for a favorite site
5184 { +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
5185  a</screen>
5186    </para>
5187   </listitem>
5188  </varlistentry>
5189
5190 </variablelist>
5191 </sect3>
5192
5193
5194 <!--   ~~~~~       New section      ~~~~~     -->
5195 <sect3 renderas="sect4" id="send-vanilla-wafer">
5196 <title>send-vanilla-wafer</title>
5197
5198 <variablelist>
5199  <varlistentry>
5200   <term>Typical use:</term>
5201   <listitem>
5202    <para>
5203     Feed log analysis scripts with useless data.
5204    </para>
5205   </listitem>
5206  </varlistentry>
5207
5208  <varlistentry>
5209   <term>Effect:</term>
5210   <listitem>
5211    <para>
5212     Sends a cookie with each request stating that you do not accept any copyright
5213     on cookies sent to you, and asking the site operator not to track you.
5214    </para>
5215   </listitem>
5216  </varlistentry>
5217
5218  <varlistentry>
5219   <term>Type:</term>
5220   <!-- Boolean, Parameterized, Multi-value -->
5221   <listitem>
5222    <para>Boolean.</para>
5223   </listitem>
5224  </varlistentry>
5225
5226  <varlistentry>
5227   <term>Parameter:</term>
5228   <listitem>
5229    <para>
5230     N/A
5231    </para>
5232   </listitem>
5233  </varlistentry>
5234
5235  <varlistentry>
5236   <term>Notes:</term>
5237   <listitem>
5238    <para>
5239     The vanilla wafer is a (relatively) unique header and could conceivably be used to track you.
5240    </para>
5241    <para>
5242     This action is rarely used and not enabled in the default configuration.
5243    </para>
5244   </listitem>
5245  </varlistentry>
5246
5247  <varlistentry>
5248   <term>Example usage:</term>
5249   <listitem>
5250    <para>
5251      <screen>+send-vanilla-wafer</screen>
5252    </para>
5253   </listitem>
5254  </varlistentry>
5255
5256 </variablelist>
5257 </sect3>
5258
5259
5260 <!--   ~~~~~       New section      ~~~~~     -->
5261 <sect3 renderas="sect4" id="send-wafer">
5262 <title>send-wafer</title>
5263
5264 <variablelist>
5265  <varlistentry>
5266   <term>Typical use:</term>
5267   <listitem>
5268    <para>
5269     Send custom cookies or feed log analysis scripts with even more useless data.
5270    </para>
5271   </listitem>
5272  </varlistentry>
5273
5274  <varlistentry>
5275   <term>Effect:</term>
5276   <listitem>
5277    <para>
5278     Sends a custom, user-defined cookie with each request.
5279    </para>
5280   </listitem>
5281  </varlistentry>
5282
5283  <varlistentry>
5284   <term>Type:</term>
5285   <!-- Boolean, Parameterized, Multi-value -->
5286   <listitem>
5287    <para>Multi-value.</para>
5288   </listitem>
5289  </varlistentry>
5290
5291  <varlistentry>
5292   <term>Parameter:</term>
5293   <listitem>
5294    <para>
5295     A string of the form <quote><replaceable class="option">name</replaceable>=<replaceable
5296     class="parameter">value</replaceable></quote>.
5297    </para>
5298   </listitem>
5299  </varlistentry>
5300
5301  <varlistentry>
5302   <term>Notes:</term>
5303   <listitem>
5304    <para>
5305     Being multi-valued, multiple instances of this action can apply to the same request,
5306     resulting in multiple cookies being sent.
5307    </para>
5308    <para>
5309     This action is rarely used and not enabled in the default configuration.
5310    </para>
5311   </listitem>
5312  </varlistentry>
5313  <varlistentry>
5314   <term>Example usage (section):</term>
5315   <listitem>
5316    <para>
5317     <screen>{+send-wafer{UsingPrivoxy=true}}
5318 my-internal-testing-server.void</screen>
5319    </para>
5320   </listitem>
5321  </varlistentry>
5322 </variablelist>
5323 </sect3>
5324
5325
5326 <!--   ~~~~~       New section      ~~~~~     -->
5327 <sect3 renderas="sect4" id="session-cookies-only">
5328 <title>session-cookies-only</title>
5329
5330 <variablelist>
5331  <varlistentry>
5332   <term>Typical use:</term>
5333   <listitem>
5334    <para>
5335     Allow only temporary <quote>session</quote> cookies (for the current
5336     browser session <emphasis>only</emphasis>).
5337    </para>
5338   </listitem>
5339  </varlistentry>
5340
5341  <varlistentry>
5342   <term>Effect:</term>
5343   <listitem>
5344    <para>
5345     Deletes the <quote>expires</quote> field from <quote>Set-Cookie:</quote>
5346     server headers. Most browsers will not store such cookies permanently and
5347     forget them in between sessions.
5348    </para>
5349   </listitem>
5350  </varlistentry>
5351
5352 <varlistentry>
5353   <term>Type:</term>
5354   <!-- Boolean, Parameterized, Multi-value -->
5355   <listitem>
5356    <para>Boolean.</para>
5357   </listitem>
5358  </varlistentry>
5359
5360  <varlistentry>
5361   <term>Parameter:</term>
5362   <listitem>
5363    <para>
5364     N/A
5365    </para>
5366   </listitem>
5367  </varlistentry>
5368
5369  <varlistentry>
5370   <term>Notes:</term>
5371   <listitem>
5372    <para>
5373     This is less strict than <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> /
5374     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal> and allows you to browse
5375     websites that insist or rely on setting cookies, without compromising your privacy too badly.
5376    </para>
5377    <para>
5378     Most browsers will not permanently store cookies that have been processed by
5379     <literal>session-cookies-only</literal> and will forget about them between sessions.
5380     This makes profiling cookies useless, but won't break sites which require cookies so
5381     that you can log in for transactions. This is generally turned on for all
5382     sites, and is the recommended setting.
5383    </para>
5384    <para>
5385     It makes <emphasis>no sense at all</emphasis> to use <literal>session-cookies-only</literal>
5386     together with <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> or
5387     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>. If you do, cookies
5388     will be plainly killed.
5389    </para>
5390    <para>
5391     Note that it is up to the browser how it handles such cookies without an <quote>expires</quote>
5392     field. If you use an exotic browser, you might want to try it out to be sure.
5393    </para>
5394    <para>
5395     This setting also has no effect on cookies that may have been stored
5396     previously by the browser before starting <application>Privoxy</application>.
5397     These would have to be removed manually.
5398    </para>
5399    <para>
5400      <application>Privoxy</application> also uses
5401      the <link linkend="filter-content-cookies">content-cookies filter</link>
5402      to block some types of cookies. Content cookies are not effected by
5403      <literal>session-cookies-only</literal>.
5404    </para>
5405   </listitem>
5406  </varlistentry>
5407
5408  <varlistentry>
5409   <term>Example usage:</term>
5410   <listitem>
5411    <para>
5412      <screen>+session-cookies-only</screen>
5413    </para>
5414   </listitem>
5415  </varlistentry>
5416 </variablelist>
5417 </sect3>
5418
5419
5420 <!--   ~~~~~       New section      ~~~~~     -->
5421 <sect3 renderas="sect4" id="set-image-blocker">
5422 <title>set-image-blocker</title>
5423
5424 <variablelist>
5425  <varlistentry>
5426   <term>Typical use:</term>
5427   <listitem>
5428    <para>Choose the replacement for blocked images</para>
5429   </listitem>
5430  </varlistentry>
5431
5432  <varlistentry>
5433   <term>Effect:</term>
5434   <listitem>
5435    <para>
5436      This action alone doesn't do anything noticeable. If <emphasis>both</emphasis>
5437      <literal><link linkend="block">block</link></literal> <emphasis>and</emphasis> <literal><link
5438      linkend="handle-as-image">handle-as-image</link></literal> <emphasis>also</emphasis>
5439      apply, i.e. if the request is to be blocked as an image,
5440      <emphasis>then</emphasis> the parameter of this action decides what will be
5441      sent as a replacement.
5442    </para>
5443   </listitem>
5444  </varlistentry>
5445
5446  <varlistentry>
5447   <term>Type:</term>
5448   <!-- Boolean, Parameterized, Multi-value -->
5449   <listitem>
5450    <para>Parameterized.</para>
5451   </listitem>
5452  </varlistentry>
5453
5454  <varlistentry>
5455   <term>Parameter:</term>
5456   <listitem>
5457    <itemizedlist>
5458     <listitem>
5459      <para>
5460       <quote>pattern</quote> to send a built-in checkerboard pattern image. The image is visually
5461       decent, scales very well, and makes it obvious where banners were busted.
5462      </para>
5463     </listitem>
5464     <listitem>
5465      <para>
5466       <quote>blank</quote> to send a built-in transparent image. This makes banners disappear
5467       completely, but makes it hard to detect where <application>Privoxy</application> has blocked
5468       images on a given page and complicates troubleshooting if <application>Privoxy</application>
5469       has blocked innocent images, like navigation icons.
5470      </para>
5471     </listitem>
5472     <listitem>
5473      <para>
5474       <quote><replaceable class="parameter">target-url</replaceable></quote> to
5475       send a redirect to <replaceable class="parameter">target-url</replaceable>. You can redirect
5476       to any image anywhere, even in your local filesystem via <quote>file:///</quote> URL.
5477       (But note that not all browsers support redirecting to a local file system).
5478      </para>
5479      <para>
5480       A good application of redirects is to use special <application>Privoxy</application>-built-in
5481       URLs, which send the built-in images, as <replaceable class="parameter">target-url</replaceable>.
5482       This has the same visual effect as specifying <quote>blank</quote> or <quote>pattern</quote> in
5483       the first place, but enables your browser to cache the replacement image, instead of requesting
5484       it over and over again.
5485      </para>
5486     </listitem>
5487    </itemizedlist>
5488   </listitem>
5489  </varlistentry>
5490
5491  <varlistentry>
5492   <term>Notes:</term>
5493   <listitem>
5494    <para>
5495     The URLs for the built-in images are <quote>http://config.privoxy.org/send-banner?type=<replaceable
5496     class="parameter">type</replaceable></quote>, where <replaceable class="parameter">type</replaceable> is
5497     either <quote>blank</quote> or <quote>pattern</quote>.
5498    </para>
5499    <para>
5500     There is a third (advanced) type, called <quote>auto</quote>. It is <emphasis>NOT</emphasis> to be
5501     used in <literal>set-image-blocker</literal>, but meant for use from <link linkend="filter-file">filters</link>.
5502     Auto will select the type of image that would have applied to the referring page, had it been an image.
5503    </para>
5504   </listitem>
5505  </varlistentry>
5506
5507  <varlistentry>
5508   <term>Example usage:</term>
5509   <listitem>
5510    <para>
5511     Built-in pattern:
5512    </para>
5513    <para>
5514     <screen>+set-image-blocker{pattern}</screen>
5515    </para>
5516    <para>
5517     Redirect to the BSD devil:
5518    </para>
5519    <para>
5520     <screen>+set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}</screen>
5521    </para>
5522    <para>
5523     Redirect to the built-in pattern for better caching:
5524    </para>
5525    <para>
5526     <screen>+set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}</screen>
5527    </para>
5528   </listitem>
5529  </varlistentry>
5530 </variablelist>
5531 </sect3>
5532
5533
5534 <!--   ~~~~~       New section      ~~~~~     -->
5535 <sect3 renderas="sect4" id="treat-forbidden-connects-like-blocks">
5536 <title>treat-forbidden-connects-like-blocks</title>
5537 <!--
5538 new action
5539 -->
5540 <variablelist>
5541  <varlistentry>
5542   <term>Typical use:</term>
5543   <listitem>
5544    <para>Block forbidden connects with an easy to find error message.</para>
5545   </listitem>
5546  </varlistentry>
5547
5548  <varlistentry>
5549   <term>Effect:</term>
5550   <listitem>
5551    <para>
5552     If this action is enabled, <application>Privoxy</application> no longer
5553     makes a difference between forbidden connects and ordinary blocks.
5554    </para>
5555   </listitem>
5556  </varlistentry>
5557
5558  <varlistentry>
5559   <term>Type:</term>
5560   <!-- Boolean, Parameterized, Multi-value -->
5561   <listitem>
5562    <para>Boolean</para>
5563   </listitem>
5564  </varlistentry>
5565
5566  <varlistentry>
5567   <term>Parameter:</term>
5568   <listitem>
5569    <para>N/A</para>
5570   </listitem>
5571  </varlistentry>
5572
5573  <varlistentry>
5574   <term>Notes:</term>
5575   <listitem>
5576    <para>
5577     By default <application>Privoxy</application> answers
5578     <link linkend="limit-connect">forbidden <quote>Connect</quote> requests</link>
5579     with a short error message inside the headers. If the browser doesn't display
5580     headers (most don't), you just see an empty page.
5581    </para>
5582    <para>
5583     With this action enabled, <application>Privoxy</application> displays
5584     the message that is used for ordinary blocks instead. If you decide
5585     to make an exception for the page in question, you can do so by
5586     following the <quote>See why</quote> link.
5587    </para>
5588    <para>
5589     For <quote>Connect</quote> requests the clients tell
5590     <application>Privoxy</application> which host they are interested
5591     in, but not which document they plan to get later. As a result, the
5592     <quote>Go there anyway</quote> link becomes rather useless:
5593     it lets the client request the home page of the forbidden host
5594     through unencrypted HTTP, still using the port of the last request.
5595    </para>
5596    <para>
5597     If you previously configured <application>Privoxy</application> to do the
5598     request through a SSL tunnel, everything will work. Most likely you haven't
5599     and the server will respond with an error message because it is expecting
5600     HTTPS (SSL).
5601    </para>
5602   </listitem>
5603  </varlistentry>
5604
5605  <varlistentry>
5606   <term>Example usage:</term>
5607   <listitem>
5608    <para>
5609     <screen>+treat-forbidden-connects-like-blocks</screen>
5610    </para>
5611   </listitem>
5612  </varlistentry>
5613 </variablelist>
5614 </sect3>
5615
5616
5617 <!--   ~~~~~       New section      ~~~~~     -->
5618 <sect3>
5619 <title>Summary</title>
5620 <para>
5621  Note that many of these actions have the potential to cause a page to
5622  misbehave, possibly even not to display at all. There are many ways
5623  a site designer may choose to design his site, and what HTTP header
5624  content, and other criteria, he may depend on. There is no way to have hard
5625  and fast rules for all sites. See the <link
5626  linkend="ACTIONSANAT">Appendix</link> for a brief example on troubleshooting
5627  actions.
5628 </para>
5629 </sect3>
5630 </sect2>
5631
5632 <!--   ~~~~~       New section      ~~~~~     -->
5633 <sect2 id="aliases">
5634 <title>Aliases</title>
5635 <para>
5636  Custom <quote>actions</quote>, known to <application>Privoxy</application>
5637  as <quote>aliases</quote>, can be defined by combining other actions.
5638  These can in turn be invoked just like the built-in actions.
5639  Currently, an alias name can contain any character except space, tab,
5640  <quote>=</quote>,
5641  <quote>{</quote> and <quote>}</quote>, but we <emphasis>strongly
5642  recommend</emphasis> that you only use <quote>a</quote> to <quote>z</quote>,
5643  <quote>0</quote> to <quote>9</quote>, <quote>+</quote>, and <quote>-</quote>.
5644  Alias names are not case sensitive, and are not required to start with a
5645  <quote>+</quote> or <quote>-</quote> sign, since they are merely textually
5646  expanded.
5647 </para>
5648 <para>
5649  Aliases can be used throughout the actions file, but they <emphasis>must be
5650  defined in a special section at the top of the file!</emphasis>
5651  And there can only be one such section per actions file. Each actions file may
5652  have its own alias section, and the aliases defined in it are only visible
5653  within that file.
5654 </para>
5655 <para>
5656  There are two main reasons to use aliases: One is to save typing for frequently
5657  used combinations of actions, the other one is a gain in flexibility: If you
5658  decide once how you want to handle shops by defining an alias called
5659  <quote>shop</quote>, you can later change your policy on shops in
5660  <emphasis>one</emphasis> place, and your changes will take effect everywhere
5661  in the actions file where the <quote>shop</quote> alias is used. Calling aliases
5662  by their purpose also makes your actions files more readable.
5663 </para>
5664 <para>
5665  Currently, there is one big drawback to using aliases, though:
5666  <application>Privoxy</application>'s built-in web-based action file
5667  editor honors aliases when reading the actions files, but it expands
5668  them before writing. So the effects of your aliases are of course preserved,
5669  but the aliases themselves are lost when you edit sections that use aliases
5670  with it.
5671  This is likely to change in future versions of <application>Privoxy</application>.
5672 </para>
5673
5674 <para>
5675  Now let's define some aliases...
5676 </para>
5677
5678 <para>
5679  <screen>
5680  # Useful custom aliases we can use later.
5681  #
5682  # Note the (required!) section header line and that this section
5683  # must be at the top of the actions file!
5684  #
5685  {{alias}}
5686
5687  # These aliases just save typing later:
5688  # (Note that some already use other aliases!)
5689  #
5690  +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
5691  -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
5692  +block-as-image      = +block +handle-as-image
5693  mercy-for-cookies   = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
5694
5695  # These aliases define combinations of actions
5696  # that are useful for certain types of sites:
5697  #
5698  fragile     = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link> -<link linkend="KILL-POPUPS">kill-popups</link>
5699  shop        = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> -<link linkend="KILL-POPUPS">kill-popups</link>
5700
5701  # Short names for other aliases, for really lazy people ;-)
5702  #
5703  c0 = +crunch-all-cookies
5704  c1 = -crunch-all-cookies</screen>
5705 </para>
5706
5707 <para>
5708  ...and put them to use. These sections would appear in the lower part of an
5709  actions file and define exceptions to the default actions (as specified further
5710  up for the <quote>/</quote> pattern):
5711 </para>
5712
5713 <para>
5714  <screen>
5715  # These sites are either very complex or very keen on
5716  # user data and require minimal interference to work:
5717  #
5718  {fragile}
5719  .office.microsoft.com
5720  .windowsupdate.microsoft.com
5721  .nytimes.com
5722
5723  # Shopping sites:
5724  # Allow cookies (for setting and retrieving your customer data)
5725  #
5726  {shop}
5727  .quietpc.com
5728  .worldpay.com   # for quietpc.com
5729  .scan.co.uk
5730
5731  # These shops require pop-ups:
5732  #
5733  {shop -kill-popups -filter{all-popups}}
5734   .dabs.com
5735   .overclockers.co.uk</screen>
5736 </para>
5737
5738 <para>
5739  Aliases like <quote>shop</quote> and <quote>fragile</quote> are often used for
5740  <quote>problem</quote> sites that require some actions to be disabled
5741  in order to function properly.
5742 </para>
5743 </sect2>
5744 <!--
5745 hal stop here
5746 -->
5747 <!--   ~~~~~       New section      ~~~~~     -->
5748 <sect2 id="act-examples">
5749 <title>Actions Files Tutorial</title>
5750 <para>
5751  The above chapters have shown <link linkend="actions-file">which actions files
5752  there are and how they are organized</link>, how actions are <link
5753  linkend="actions">specified</link> and <link linkend="actions-apply">applied
5754  to URLs</link>, how <link linkend="af-patterns">patterns</link> work, and how to
5755  define and use <link linkend="aliases">aliases</link>. Now, let's look at an
5756  example <filename>default.action</filename> and <filename>user.action</filename>
5757  file and see how all these pieces come together:
5758 </para>
5759
5760 <sect3><title>default.action</title>
5761
5762 <para>
5763 Every config file should start with a short comment stating its purpose:
5764 </para>
5765
5766 <para>
5767  <screen># Sample default.action file &lt;ijbswa-developers@lists.sourceforge.net&gt;</screen>
5768 </para>
5769
5770 <para>
5771 Then, since this is the <filename>default.action</filename> file, the
5772 first section is a special section for internal use that you needn't
5773 change or worry about:
5774 </para>
5775
5776 <para>
5777  <screen>
5778 ##########################################################################
5779 # Settings -- Don't change! For internal Privoxy use ONLY.
5780 ##########################################################################
5781
5782 {{settings}}
5783 for-privoxy-version=3.0</screen>
5784 </para>
5785
5786 <para>
5787 After that comes the (optional) alias section. We'll use the example
5788 section from the above <link linkend="aliases">chapter on aliases</link>,
5789 that also explains why and how aliases are used:
5790 </para>
5791
5792 <para>
5793  <screen>
5794 ##########################################################################
5795 # Aliases
5796 ##########################################################################
5797 {{alias}}
5798
5799  # These aliases just save typing later:
5800  # (Note that some already use other aliases!)
5801  #
5802  +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
5803  -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
5804  +block-as-image      = +block +handle-as-image
5805  mercy-for-cookies   = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
5806
5807  # These aliases define combinations of actions
5808  # that are useful for certain types of sites:
5809  #
5810  fragile     = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link> -<link linkend="KILL-POPUPS">kill-popups</link>
5811  shop        = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> -<link linkend="KILL-POPUPS">kill-popups</link></screen>
5812 </para>
5813
5814 <para>
5815  Now come the regular sections, i.e. sets of actions, accompanied
5816  by URL patterns to which they apply. Remember <emphasis>all actions
5817  are disabled when matching starts</emphasis>, so we have to explicitly
5818  enable the ones we want.
5819 </para>
5820
5821 <para>
5822  The first regular section is probably the most important. It has only
5823  one pattern, <quote><literal>/</literal></quote>, but this pattern
5824  <link linkend="af-patterns">matches all URLs</link>. Therefore, the
5825  set of actions used in this <quote>default</quote> section <emphasis>will
5826  be applied to all requests as a start</emphasis>. It can  be partly or
5827  wholly overridden by later matches further down this file, or in user.action,
5828  but it will still be largely responsible for your overall browsing
5829  experience.
5830 </para>
5831
5832 <para>
5833  Again, at the start of matching, all actions are disabled, so there is
5834  no real need to disable any actions here, but we will do that nonetheless,
5835  to have a complete listing for your reference. (Remember: a <quote>+</quote>
5836  preceding the action name enables the action, a <quote>-</quote> disables!).
5837  Also note how this long line has been made more readable by splitting it into
5838  multiple lines with line continuation.
5839 </para>
5840
5841 <para>
5842  <screen>
5843 ##########################################################################
5844 # "Defaults" section:
5845 ##########################################################################
5846  { \
5847  -<link linkend="ADD-HEADER">add-header</link> \
5848  -<link linkend="BLOCK">block</link> \
5849  -<link linkend="CONTENT-TYPE-OVERWRITE">content-type-overwrite</link> \
5850  -<link linkend="CRUNCH-CLIENT-HEADER">crunch-client-header</link> \
5851  -<link linkend="CRUNCH-IF-NONE-MATCH">crunch-if-none-match</link> \
5852  -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> \
5853  -<link linkend="CRUNCH-SERVER-HEADER">crunch-server-header</link> \
5854  -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link> \
5855  +<link linkend="DEANIMATE-GIFS">deanimate-gifs</link> \
5856  -<link linkend="DOWNGRADE-HTTP-VERSION">downgrade-http-version</link> \
5857  -<link linkend="FAST-REDIRECTS">fast-redirects{check-decoded-url}</link> \
5858  -<link linkend="FILTER-JS-ANNOYANCES">filter{js-annoyances}</link> \
5859  -<link linkend="FILTER-JS-EVENTS">filter{js-events}</link> \
5860  +<link linkend="FILTER-HTML-ANNOYANCES">filter{html-annoyances}</link> \
5861  -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link> \
5862  +<link linkend="FILTER-REFRESH-TAGS">filter{refresh-tags}</link> \
5863  -<link linkend="FILTER-UNSOLICITED-POPUPS">filter{unsolicited-popups}</link> \
5864  -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> \
5865  -<link linkend="FILTER-IMG-REORDER">filter{img-reorder}</link> \
5866  -<link linkend="FILTER-BANNERS-BY-SIZE">filter{banners-by-size}</link> \
5867  -<link linkend="FILTER-BANNERS-BY-LINK">filter{banners-by-link}</link> \
5868  +<link linkend="FILTER-WEBBUGS">filter{webbugs}</link> \
5869  -<link linkend="FILTER-TINY-TEXTFORMS">filter{tiny-textforms}</link> \
5870  -<link linkend="FILTER-JUMPING-WINDOWS">filter{jumping-windows}</link> \
5871  -<link linkend="FILTER-FRAMESET-BORDERS">filter{frameset-borders}</link> \
5872  -<link linkend="FILTER-DEMORONIZER">filter{demoronizer}</link> \
5873  -<link linkend="FILTER-SHOCKWAVE-FLASH">filter{shockwave-flash}</link> \
5874  -<link linkend="FILTER-QUICKTIME-KIOSKMODE">filter{quicktime-kioskmode}</link> \
5875  -<link linkend="FILTER-FUN">filter{fun}</link> \
5876  -<link linkend="FILTER-CRUDE-PARENTAL">filter{crude-parental}</link> \
5877  +<link linkend="FILTER-IE-EXPLOITS">filter{ie-exploits}</link> \
5878  -<link linkend="FILTER-CLIENT-HEADERS">filter-client-headers</link> \
5879  -<link linkend="FILTER-SERVER-HEADERS">filter-server-headers</link> \
5880  -<link linkend="FILTER-GOOGLE">filter-google</link> \
5881  -<link linkend="FILTER-YAHOO">filter-yahoo</link> \
5882  -<link linkend="FILTER-MSN">filter-msn</link> \
5883  -<link linkend="FILTER-BLOGSPOT">filter-blogspot</link> \
5884  -<link linkend="FILTER-XML-TO-HTML">filter-xml-to-html</link> \
5885  -<link linkend="FILTER-HTML-TO-XML">filter-html-to-xml</link> \
5886  -<link linkend="FORCE-TEXT-MODE">force-text-mode</link> \
5887  -<link linkend="HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document</link> \
5888  -<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> \
5889  -<link linkend="HIDE-ACCEPT-LANGUAGE">hide-accept-language</link> \
5890  -<link linkend="HIDE-CONTENT-DISPOSITION">hide-content-disposition</link> \
5891  -<link linkend="HIDE-IF-MODIFIED-SINCE">hide-if-modified-since</link> \
5892  +<link linkend="HIDE-FORWARDED-FOR-HEADERS">hide-forwarded-for-headers</link> \
5893  +<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
5894  +<link linkend="HIDE-REFERER">hide-referrer{forge}</link> \
5895  -<link linkend="HIDE-USER-AGENT">hide-user-agent</link> \
5896  -<link linkend="INSPECT-JPEGS">inspect-jpegs</link> \
5897  -<link linkend="KILL-POPUPS">kill-popups</link> \
5898  -<link linkend="LIMIT-CONNECT">limit-connect</link> \
5899  +<link linkend="PREVENT-COMPRESSION">prevent-compression</link> \
5900  -<link linkend="OVERWRITE-LAST-MODIFIED">overwrite-last-modified</link> \
5901  -<link linkend="REDIRECT">redirect</link> \
5902  -<link linkend="SEND-VANILLA-WAFER">send-vanilla-wafer</link> \
5903  -<link linkend="SEND-WAFER">send-wafer</link> \
5904  +<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> \
5905  +<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
5906  -<link linkend="TREAT-FORBIDDEN-CONNECTS-LIKE-BLOCKS">treat-forbidden-connects-like-blocks</link> \
5907  }
5908  / # forward slash will match *all* potential URL patterns.</screen>
5909 </para>
5910
5911 <para>
5912  The default behavior is now set. Note that some actions, like not hiding
5913  the user agent, are part of a <quote>general policy</quote> that applies
5914  universally and won't get any exceptions defined later. Other choices,
5915  like not blocking (which is <emphasis>understandably</emphasis> the
5916  default!) need exceptions, i.e. we need to specify explicitly what we
5917  want to block in later sections.
5918 </para>
5919
5920 <para>
5921  The first of our specialized sections is concerned with <quote>fragile</quote>
5922  sites, i.e. sites that require minimum interference, because they are either
5923  very complex or very keen on tracking you (and have mechanisms in place that
5924  make them unusable for people who avoid being tracked). We will simply use
5925  our pre-defined <literal>fragile</literal> alias instead of stating the list
5926  of actions explicitly:
5927 </para>
5928
5929 <para>
5930  <screen>
5931 ##########################################################################
5932 # Exceptions for sites that'll break under the default action set:
5933 ##########################################################################
5934
5935 # "Fragile" Use a minimum set of actions for these sites (see alias above):
5936 #
5937 { fragile }
5938 .office.microsoft.com           # surprise, surprise!
5939 .windowsupdate.microsoft.com
5940 mail.google.com</screen>
5941 </para>
5942
5943 <para>
5944  Shopping sites are not as fragile, but they typically
5945  require cookies to log in, and pop-up windows for shopping
5946  carts or item details. Again, we'll use a pre-defined alias:
5947 </para>
5948
5949 <para>
5950  <screen>
5951 # Shopping sites:
5952 #
5953 { shop }
5954 .quietpc.com
5955 .worldpay.com   # for quietpc.com
5956 .jungle.com
5957 .scan.co.uk</screen>
5958 </para>
5959
5960 <!-- No longer needed BEGIN OF COMMENTED OUT BLOCK
5961
5962 <para>
5963  Then, there are sites which rely on pop-up windows (yuck!) to work.
5964  Since we made pop-up-killing our default above, we need to make exceptions
5965  now. <ulink url="http://www.mozilla.org/">Mozilla</ulink> users, who
5966  can turn on smart handling of unwanted pop-ups in their browsers, can
5967  safely choose
5968  -<literal><link linkend="FILTER-ALL-POPUPS">filter{popups}</link></literal> (and
5969  -<literal><link linkend="KILL-POPUPS">kill-popups</link></literal>) above
5970  and hence don't need this section. Anyway, disabling an already disabled
5971  action doesn't hurt, so we'll define our exceptions regardless of what was
5972  chosen in the defaults section:
5973 </para>
5974
5975 <para>
5976  <screen>
5977 # These sites require pop-ups too :(
5978 #
5979 { -<link linkend="KILL-POPUPS">kill-popups</link> -<link linkend="FILTER-ALL-POPUPS">filter{popups}</link> }
5980 .dabs.com
5981 .overclockers.co.uk
5982 .deutsche-bank-24.de</screen>
5983 </para>
5984
5985  END OF COMMENTED OUT BLOCK -->
5986
5987 <para>
5988  The <literal><link linkend="FAST-REDIRECTS">fast-redirects</link></literal>
5989  action, which we enabled per default above,  breaks some sites. So disable
5990  it for popular sites where we know it misbehaves:
5991 </para>
5992
5993 <para>
5994  <screen>
5995 { -<link linkend="FAST-REDIRECTS">fast-redirects</link> }
5996 login.yahoo.com
5997 edit.*.yahoo.com
5998 .google.com
5999 .altavista.com/.*(like|url|link):http
6000 .altavista.com/trans.*urltext=http
6001 .nytimes.com</screen>
6002 </para>
6003
6004 <para>
6005  It is important that <application>Privoxy</application> knows which
6006  URLs belong to images, so that <emphasis>if</emphasis> they are to
6007  be blocked, a substitute image can be sent, rather than an HTML page.
6008  Contacting the remote site to find out is not an option, since it
6009  would destroy the loading time advantage of banner blocking, and it
6010  would feed the advertisers (in terms of money <emphasis>and</emphasis>
6011  information). We can mark any URL as an image with the <literal><link
6012  linkend="handle-as-image">handle-as-image</link></literal> action,
6013  and marking all URLs that end in a known image file extension is a
6014  good start:
6015 </para>
6016
6017 <para>
6018  <screen>
6019 ##########################################################################
6020 # Images:
6021 ##########################################################################
6022
6023 # Define which file types will be treated as images, in case they get
6024 # blocked further down this file:
6025 #
6026 { +<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> }
6027 /.*\.(gif|jpe?g|png|bmp|ico)$</screen>
6028 </para>
6029
6030 <para>
6031  And then there are known banner sources. They often use scripts to
6032  generate the banners, so it won't be visible from the URL that the
6033  request is for an image. Hence we block them <emphasis>and</emphasis>
6034  mark them as images in one go, with the help of our
6035  <literal>+block-as-image</literal> alias defined above. (We could of
6036  course just as well use <literal>+<link linkend="block">block</link>
6037  +<link linkend="handle-as-image">handle-as-image</link></literal> here.)
6038  Remember that the type of the replacement image is chosen by the
6039  <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
6040  action. Since all URLs have matched the default section with its
6041  <literal>+<link linkend="set-image-blocker">set-image-blocker</link>{pattern}</literal>
6042  action before, it still applies and needn't be repeated:
6043 </para>
6044
6045 <para>
6046  <screen>
6047 # Known ad generators:
6048 #
6049 { +block-as-image }
6050 ar.atwola.com
6051 .ad.doubleclick.net
6052 .ad.*.doubleclick.net
6053 .a.yimg.com/(?:(?!/i/).)*$
6054 .a[0-9].yimg.com/(?:(?!/i/).)*$
6055 bs*.gsanet.com
6056 .qkimg.net</screen>
6057 </para>
6058
6059 <para>
6060  One of the most important jobs of <application>Privoxy</application>
6061  is to block banners. Many of these can be <quote>blocked</quote>
6062  by the <literal><link linkend="filter">filter</link>{banners-by-size}</literal>
6063  action, which we enabled above, and which deletes the references to banner
6064  images from the pages while they are loaded, so the browser doesn't request
6065  them anymore, and hence they don't need to be blocked here. But this naturally
6066  doesn't catch all banners, and some people choose not to use filters, so we
6067  need a comprehensive list of patterns for banner URLs here, and apply the
6068  <literal><link linkend="block">block</link></literal> action to them.
6069 </para>
6070 <para>
6071  First comes many generic patterns, which do most of the work, by
6072  matching typical domain and path name components of banners. Then comes
6073  a list of individual patterns for specific sites, which is omitted here
6074  to keep the example short:
6075 </para>
6076
6077 <para>
6078  <screen>
6079 ##########################################################################
6080 # Block these fine banners:
6081 ##########################################################################
6082 { <link linkend="BLOCK">+block</link> }
6083
6084 # Generic patterns:
6085 #
6086 ad*.
6087 .*ads.
6088 banner?.
6089 count*.
6090 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
6091 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
6092
6093 # Site-specific patterns (abbreviated):
6094 #
6095 .hitbox.com</screen>
6096 </para>
6097
6098 <para>
6099  It's quite remarkable how many advertisers actually call their banner
6100  servers ads.<replaceable>company</replaceable>.com, or call the directory
6101  in which the banners are stored simply <quote>banners</quote>. So the above
6102  generic patterns are surprisingly effective.
6103 </para>
6104 <para>
6105  But being very generic, they necessarily also catch URLs that we don't want
6106  to block. The pattern <literal>.*ads.</literal> e.g. catches
6107  <quote>nasty-<emphasis>ads</emphasis>.nasty-corp.com</quote> as intended,
6108  but also <quote>downlo<emphasis>ads</emphasis>.sourcefroge.net</quote> or
6109  <quote><emphasis>ads</emphasis>l.some-provider.net.</quote> So here come some
6110  well-known exceptions to the <literal>+<link linkend="BLOCK">block</link></literal>
6111  section above.
6112 </para>
6113 <para>
6114  Note that these are exceptions to exceptions from the default! Consider the URL
6115  <quote>downloads.sourcefroge.net</quote>: Initially, all actions are deactivated,
6116  so it wouldn't get blocked. Then comes the defaults section, which matches the
6117  URL, but just deactivates the <literal><link linkend="BLOCK">block</link></literal>
6118  action once again. Then it matches <literal>.*ads.</literal>, an exception to the
6119  general non-blocking policy, and suddenly
6120  <literal><link linkend="BLOCK">+block</link></literal> applies. And now, it'll match
6121  <literal>.*loads.</literal>, where <literal><link linkend="BLOCK">-block</link></literal>
6122  applies, so (unless it matches <emphasis>again</emphasis> further down) it ends up
6123  with no <literal><link linkend="BLOCK">block</link></literal> action applying.
6124 </para>
6125
6126 <para>
6127  <screen>
6128 ##########################################################################
6129 # Save some innocent victims of the above generic block patterns:
6130 ##########################################################################
6131
6132 # By domain:
6133 #
6134 { -<link linkend="BLOCK">block</link> }
6135 adv[io]*.  # (for advogato.org and advice.*)
6136 adsl.      # (has nothing to do with ads)
6137 adobe.     # (has nothing to do with ads either)
6138 ad[ud]*.   # (adult.* and add.*)
6139 .edu       # (universities don't host banners (yet!))
6140 .*loads.   # (downloads, uploads etc)
6141
6142 # By path:
6143 #
6144 /.*loads/
6145
6146 # Site-specific:
6147 #
6148 www.globalintersec.com/adv # (adv = advanced)
6149 www.ugu.com/sui/ugu/adv</screen>
6150 </para>
6151
6152 <para>
6153  Filtering source code can have nasty side effects,
6154  so make an exception for our friends at sourceforge.net,
6155  and all paths with <quote>cvs</quote> in them. Note that
6156  <literal>-<link linkend="FILTER">filter</link></literal>
6157  disables <emphasis>all</emphasis> filters in one fell swoop!
6158 </para>
6159
6160 <para>
6161  <screen>
6162 # Don't filter code!
6163 #
6164 { -<link linkend="FILTER">filter</link> }
6165 /(.*/)?cvs
6166 bugzilla.
6167 developer.
6168 wiki.
6169 .sourceforge.net</screen>
6170 </para>
6171
6172 <para>
6173  The actual <filename>default.action</filename> is of course much more
6174  comprehensive, but we hope this example made clear how it works.
6175 </para>
6176
6177 </sect3>
6178
6179 <sect3><title>user.action</title>
6180
6181 <para>
6182  So far we are painting with a broad brush by setting general policies,
6183  which would be a reasonable starting point for many people. Now,
6184  you might want to be more specific and have customized rules that
6185  are more suitable to your personal habits and preferences. These would
6186  be for narrowly defined situations like your ISP or your bank, and should
6187  be placed in <filename>user.action</filename>, which is parsed after all other
6188  actions files and hence has the last word, over-riding any previously
6189  defined actions. <filename>user.action</filename> is also a
6190  <emphasis>safe</emphasis> place for your personal settings, since
6191  <filename>default.action</filename> is actively maintained by the
6192  <application>Privoxy</application> developers and you'll probably want
6193  to install updated versions from time to time.
6194 </para>
6195
6196 <para>
6197  So let's look at a few examples of things that one might typically do in
6198  <filename>user.action</filename>:
6199 </para>
6200
6201
6202 <!-- brief sample user.action here -->
6203
6204 <para>
6205  <screen>
6206 # My user.action file. &lt;fred@foobar.com&gt;</screen>
6207 </para>
6208
6209 <para>
6210  As <link linkend="aliases">aliases</link> are local to the actions
6211  file that they are defined in, you can't use the ones from
6212  <filename>default.action</filename>, unless you repeat them here:
6213 </para>
6214
6215 <para>
6216  <screen>
6217 # Aliases are local to the file they are defined in.
6218 # (Re-)define aliases for this file:
6219 #
6220 {{alias}}
6221 #
6222 # These aliases just save typing later, and the alias names should
6223 # be self explanatory.
6224 #
6225 +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
6226 -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
6227  allow-all-cookies  = -crunch-all-cookies -session-cookies-only
6228  allow-popups       = -filter{all-popups} -kill-popups
6229 +block-as-image     = +block +handle-as-image
6230 -block-as-image     = -block
6231
6232 # These aliases define combinations of actions that are useful for
6233 # certain types of sites:
6234 #
6235 fragile     = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer -kill-popups
6236 shop        = -crunch-all-cookies allow-popups
6237
6238 # Allow ads for selected useful free sites:
6239 #
6240 allow-ads   = -block -filter{banners-by-size} -filter{banners-by-link}
6241
6242 # Alias for specific file types that are text, but might have conflicting
6243 # MIME types. We want the browser to force these to be text documents.
6244 handle-as-text = -<link linkend="FILTER">filter</link> +-<link linkend="content-type-overwrite">content-type-overwrite{text/plain}</link> +-<link linkend="FORCE-TEXT-MODE">force-text-mode</link> -<link linkend="HIDE-CONTENT-DISPOSITION">hide-content-disposition</link></screen>
6245
6246 </para>
6247
6248 <para>
6249  Say you have accounts on some sites that you visit regularly, and
6250  you don't want to have to log in manually each time. So you'd like
6251  to allow persistent cookies for these sites. The
6252  <literal>allow-all-cookies</literal> alias defined above does exactly
6253  that, i.e. it disables crunching of cookies in any direction, and the
6254  processing of cookies to make them only temporary.
6255 </para>
6256
6257 <para>
6258  <screen>
6259 { allow-all-cookies }
6260  sourceforge.net
6261  .yahoo.com
6262  .msdn.microsoft.com
6263  .redhat.com</screen>
6264 </para>
6265
6266 <para>
6267  Your bank is allergic to some filter, but you don't know which, so you disable them all:
6268 </para>
6269
6270 <para>
6271  <screen>
6272 { -<link linkend="FILTER">filter</link> }
6273  .your-home-banking-site.com</screen>
6274 </para>
6275
6276 <para>
6277  Some file types you may not want to filter for various reasons:
6278 </para>
6279
6280 <para>
6281  <screen>
6282 # Technical documentation is likely to contain strings that might
6283 # erroneously get altered by the JavaScript-oriented filters:
6284 #
6285 .tldp.org
6286 /(.*/)?selfhtml/
6287
6288 # And this stupid host sends streaming video with a wrong MIME type,
6289 # so that Privoxy thinks it is getting HTML and starts filtering:
6290 #
6291 stupid-server.example.com/</screen>
6292 </para>
6293
6294 <para>
6295  Example of a simple <link linkend="BLOCK">block</link> action. Say you've
6296  seen an ad on your favourite page on example.com that you want to get rid of.
6297  You have right-clicked the image, selected <quote>copy image location</quote>
6298  and pasted the URL below while removing the leading http://, into a
6299  <literal>{ +block }</literal> section. Note that <literal>{ +handle-as-image
6300  }</literal> need not be specified, since all URLs ending in
6301  <literal>.gif</literal> will be tagged as images by the general rules as set
6302  in default.action anyway:
6303 </para>
6304
6305 <para>
6306  <screen>
6307 { +<link linkend="BLOCK">block</link> }
6308  www.example.com/nasty-ads/sponsor.gif
6309  another.popular.site.net/more/junk/here/</screen>
6310 </para>
6311
6312 <para>
6313  The URLs of dynamically generated banners, especially from large banner
6314  farms, often don't use the well-known image file name extensions, which
6315  makes it impossible for <application>Privoxy</application> to guess
6316  the file type just by looking at the URL.
6317  You can use the <literal>+block-as-image</literal> alias defined above for
6318  these cases.
6319  Note that objects which match this rule but then turn out NOT to be an
6320  image are typically rendered as a <quote>broken image</quote> icon by the
6321  browser. Use cautiously.
6322 </para>
6323
6324 <para>
6325  <screen>
6326 { +block-as-image }
6327  .doubleclick.net
6328  .fastclick.net
6329  /Realmedia/ads/
6330  ar.atwola.com/</screen>
6331 </para>
6332
6333 <para>
6334  Now you noticed that the default configuration breaks Forbes Magazine,
6335  but you were too lazy to find out which action is the culprit, and you
6336  were again too lazy to give <link linkend="contact">feedback</link>, so
6337  you just used the <literal>fragile</literal> alias on the site, and
6338  -- <emphasis>whoa!</emphasis> -- it worked. The <literal>fragile</literal>
6339  aliases disables those actions that are most likely to break a site. Also,
6340  good for testing purposes to see if it is <application>Privoxy</application>
6341  that is causing the problem or not. We later find other regular sites
6342  that misbehave, and add those to our personalized list of troublemakers:
6343 </para>
6344
6345 <para>
6346 <screen>
6347 { fragile }
6348  .forbes.com
6349  webmail.example.com
6350  .mybank.com</screen>
6351 </para>
6352
6353 <para>
6354  You like the <quote>fun</quote> text replacements in <filename>default.filter</filename>,
6355  but it is disabled in the distributed actions file. (My colleagues on the team just
6356  don't have a sense of humour, that's why! ;-). So you'd like to turn it on in your private,
6357  update-safe config, once and for all:
6358 </para>
6359
6360 <para>
6361 <screen>
6362 { +<link linkend="filter-fun">filter{fun}</link> }
6363  / # For ALL sites!</screen>
6364 </para>
6365
6366 <para>
6367  Note that the above is not really a good idea: There are exceptions
6368  to the filters in <filename>default.action</filename> for things that
6369  really shouldn't be filtered, like code on CVS->Web interfaces. Since
6370  <filename>user.action</filename> has the last word, these exceptions
6371  won't be valid for the <quote>fun</quote> filtering specified here.
6372 </para>
6373
6374 <para>
6375  You might also worry about how your favourite free websites are
6376  funded, and find that they rely on displaying banner advertisements
6377  to survive. So you might want to specifically allow banners for those
6378  sites that you feel provide value to you:
6379 </para>
6380
6381 <para>
6382 <screen>
6383 { allow-ads }
6384  .sourceforge.net
6385  .slashdot.org
6386  .osdn.net</screen>
6387 </para>
6388
6389 <para>
6390  Note that <literal>allow-ads</literal> has been aliased to
6391  <literal>-<link linkend="block">block</link></literal>,
6392  <literal>-<link linkend="filter-banners-by-size">filter{banners-by-size}</link></literal>, and
6393  <literal>-<link linkend="filter-banners-by-link">filter{banners-by-link}</link></literal> above.
6394 </para>
6395
6396 <para>
6397  Invoke another alias here to force an over-ride of the MIME type <literal>
6398  application/x-sh</literal> which typically would open a download type
6399  dialog. In my case, I want to look at the shell script, and then I can save
6400  it should I choose to.
6401 </para>
6402
6403 <para>
6404 <screen>
6405 { handle-as-text }
6406  /.*\.sh$</screen>
6407 </para>
6408
6409 <para>
6410  <filename>user.action</filename> is generally the best place to define
6411  exceptions and additions to the default policies of
6412  <filename>default.action</filename>. Some actions are safe to have their
6413  default policies set here though. So let's set a default policy to have a
6414  <quote>blank</quote> image as opposed to the checkerboard pattern for
6415  <emphasis>ALL</emphasis> sites. <quote>/</quote> of course matches all URL
6416  paths and patterns:
6417 </para>
6418
6419 <para>
6420 <screen>
6421 { +<link linkend="set-image-blocker">set-image-blocker{blank}</link> }
6422 / # ALL sites</screen>
6423 </para>
6424
6425 </sect3>
6426 </sect2>
6427
6428 <!--  ~  End section  ~  -->
6429
6430 </sect1>
6431
6432 <!--  ~  End section  ~  -->
6433
6434 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
6435
6436 <sect1 id="filter-file">
6437 <title>Filter Files</title>
6438
6439 <para>
6440  On-the-fly text substitutions that can be invoked through the
6441  <literal><link linkend="filter">filter</link></literal> action need
6442  to be defined in a <quote>filter file</quote>. Once defined, they
6443  can then be invoked as an <quote>action</quote>. Multiple filter files can be
6444  defined through the <literal> <link
6445  linkend="filterfile">filterfile</link></literal> config directive. The filters
6446  as supplied by the developers will be found in
6447  <filename>default.filter</filename>. It is recommended that any locally
6448  defined or modified filters go in a separately defined file such as
6449  <filename>user.filter</filename>.
6450
6451 </para>
6452
6453 <para>
6454  Typical reasons for doing these kinds of substitutions are to eliminate
6455  common annoyances in HTML and JavaScript, such as pop-up windows,
6456  exit consoles, crippled windows without navigation tools, the
6457  infamous &lt;BLINK&gt; tag etc, to suppress images with certain
6458  width and height attributes (standard banner sizes or web-bugs),
6459  or just to have fun. The possibilities are endless.
6460 </para>
6461
6462 <para>
6463  Filtering works on any text-based document type, including
6464  HTML, JavaScript, CSS etc. (all <literal>text/*</literal>
6465  MIME types, <emphasis>except</emphasis> <literal>text/plain</literal>).
6466  Substitutions are made at the source level, so if you want to <quote>roll
6467  your own</quote> filters, you should first be familiar with HTML syntax,
6468  and, of course, regular expressions. By default, filters are only applied
6469  to the raw document content, but can be extended to the HTTP headers with
6470  the supplemental actions:
6471  <link linkend="filter-client-headers">filter-client-headers</link>  and
6472  <link linkend="filter-server-headers">filter-server-headers</link>.
6473 </para>
6474
6475 <para>
6476  Just like the <link linkend="actions-file">actions files</link>, the
6477  filter file is organized in sections, which are called <emphasis>filters</emphasis>
6478  here. Each filter consists of a heading line, that starts with the
6479  <emphasis>keyword</emphasis> <literal>FILTER:</literal>, followed by
6480  the filter's <emphasis>name</emphasis>, and a short (one line)
6481  <emphasis>description</emphasis> of what it does. Below that line
6482  come the <emphasis>jobs</emphasis>, i.e. lines that define the actual
6483  text substitutions. By convention, the name of a filter
6484  should describe what the filter <emphasis>eliminates</emphasis>. The
6485  comment is used in the <ulink url="http://config.privoxy.org/">web-based
6486  user interface</ulink>.
6487 </para>
6488
6489 <para>
6490  Once a filter called <replaceable>name</replaceable> has been defined
6491  in the filter file, it can be invoked by using an action of the form
6492  +<literal><link linkend="filter">filter</link>{<replaceable>name</replaceable>}</literal>
6493  in any <link linkend="actions-file">actions file</link>.
6494 </para>
6495
6496 <para>
6497  A filter header line for a filter called <quote>foo</quote> could look
6498  like this:
6499 </para>
6500
6501 <para>
6502  <screen>FILTER: foo Replace all "foo" with "bar"</screen>
6503 </para>
6504
6505 <para>
6506  Below that line, and up to the next header line, come the jobs that
6507  define what text replacements the filter executes. They are specified
6508  in a syntax that imitates <ulink url="http://www.perl.org/">Perl</ulink>'s
6509  <literal>s///</literal> operator. If you are familiar with Perl, you
6510  will find this to be quite intuitive, and may want to look at the
6511  PCRS documentation for the subtle differences to Perl behaviour. Most
6512  notably, the non-standard option letter <literal>U</literal> is supported,
6513  which turns the default to ungreedy matching.
6514 </para>
6515
6516 <para>
6517  If you are new to
6518   <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
6519   Expressions</quote></ulink>, you might want to take a look at
6520  the <link linkend="regex">Appendix on regular expressions</link>, and
6521  see the <ulink url="http://perldoc.perl.org/perlre.html">Perl
6522  manual</ulink> for
6523  <ulink url="http://perldoc.perl.org/perlop.html">the
6524  <literal>s///</literal> operator's syntax</ulink> and <ulink
6525  url="http://perldoc.perl.org/perlre.html">Perl-style regular
6526  expressions</ulink> in general.
6527  The below examples might also help to get you started.
6528 </para>
6529
6530
6531 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
6532
6533 <sect2><title>Filter File Tutorial</title>
6534 <para>
6535  Now, let's complete our <quote>foo</quote> filter. We have already defined
6536  the heading, but the jobs are still missing. Since all it does is to replace
6537  <quote>foo</quote> with <quote>bar</quote>, there is only one (trivial) job
6538  needed:
6539 </para>
6540
6541 <para>
6542  <screen>s/foo/bar/</screen>
6543 </para>
6544
6545 <para>
6546  But wait! Didn't the comment say that <emphasis>all</emphasis> occurrences
6547  of <quote>foo</quote> should be replaced? Our current job will only take
6548  care of the first <quote>foo</quote> on each page. For global substitution,
6549  we'll need to add the <literal>g</literal> option:
6550 </para>
6551
6552 <para>
6553  <screen>s/foo/bar/g</screen>
6554 </para>
6555
6556 <para>
6557  Our complete filter now looks like this:
6558 </para>
6559 <para>
6560  <screen>FILTER: foo Replace all "foo" with "bar"
6561 s/foo/bar/g</screen>
6562 </para>
6563
6564 <para>
6565  Let's look at some real filters for more interesting examples. Here you see
6566  a filter that protects against some common annoyances that arise from JavaScript
6567  abuse. Let's look at its jobs one after the other:
6568 </para>
6569
6570
6571 <para>
6572  <screen>
6573 FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse
6574
6575 # Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm
6576 #
6577 s|(&lt;script.*)document\.referrer(.*&lt;/script&gt;)|$1"Not Your Business!"$2|Usg</screen>
6578 </para>
6579
6580 <para>
6581  Following the header line and a comment, you see the job. Note that it uses
6582  <literal>|</literal> as the delimiter instead of <literal>/</literal>, because
6583  the pattern contains a forward slash, which would otherwise have to be escaped
6584  by a backslash (<literal>\</literal>).
6585 </para>
6586
6587 <para>
6588  Now, let's examine the pattern: it starts with the text <literal>&lt;script.*</literal>
6589  enclosed in parentheses. Since the dot matches any character, and <literal>*</literal>
6590  means: <quote>Match an arbitrary number of the element left of myself</quote>, this
6591  matches <quote>&lt;script</quote>, followed by <emphasis>any</emphasis> text, i.e.
6592  it matches the whole page, from the start of the first &lt;script&gt; tag.
6593 </para>
6594
6595 <para>
6596  That's more than we want, but the pattern continues: <literal>document\.referrer</literal>
6597  matches only the exact string <quote>document.referrer</quote>. The dot needed to
6598  be <emphasis>escaped</emphasis>, i.e. preceded by a backslash, to take away its
6599  special meaning as a joker, and make it just a regular dot. So far, the meaning is:
6600  Match from the start of the first &lt;script&gt; tag in a the page, up to, and including,
6601  the text <quote>document.referrer</quote>, if <emphasis>both</emphasis> are present
6602  in the page (and appear in that order).
6603 </para>
6604
6605 <para>
6606  But there's still more pattern to go. The next element, again enclosed in parentheses,
6607  is <literal>.*&lt;/script&gt;</literal>. You already know what <literal>.*</literal>
6608  means, so the whole pattern translates to: Match from the start of the first  &lt;script&gt;
6609  tag in a page to the end of the last &lt;script&gt; tag, provided that the text
6610  <quote>document.referrer</quote> appears somewhere in between.
6611 </para>
6612
6613 <para>
6614  This is still not the whole story, since we have ignored the options and the parentheses:
6615  The portions of the page matched by sub-patterns that are enclosed in parentheses, will be
6616  remembered and be available through the variables <literal>$1, $2, ...</literal> in
6617  the substitute. The <literal>U</literal> option switches to ungreedy matching, which means
6618  that the first <literal>.*</literal> in the pattern will only <quote>eat up</quote> all
6619  text in between <quote>&lt;script</quote> and the <emphasis>first</emphasis> occurrence
6620  of <quote>document.referrer</quote>, and that the second <literal>.*</literal> will
6621  only span the text up to the <emphasis>first</emphasis> <quote>&lt;/script&gt;</quote>
6622  tag. Furthermore, the <literal>s</literal> option says that the match may span
6623  multiple lines in the page, and the <literal>g</literal> option again means that the
6624  substitution is global.
6625 </para>
6626
6627 <para>
6628  So, to summarize, the pattern means: Match all scripts that contain the text
6629  <quote>document.referrer</quote>. Remember the parts of the script from
6630  (and including) the start tag up to (and excluding) the string
6631  <quote>document.referrer</quote> as <literal>$1</literal>, and the part following
6632  that string, up to and including the closing tag, as <literal>$2</literal>.
6633 </para>
6634
6635 <para>
6636  Now the pattern is deciphered, but wasn't this about substituting things? So
6637  lets look at the substitute: <literal>$1"Not Your Business!"$2</literal> is
6638  easy to read: The text remembered as <literal>$1</literal>, followed by
6639  <literal>"Not Your Business!"</literal> (<emphasis>including</emphasis>
6640  the quotation marks!), followed by the text remembered as <literal>$2</literal>.
6641  This produces an exact copy of the original string, with the middle part
6642  (the <quote>document.referrer</quote>) replaced by <literal>"Not Your
6643  Business!"</literal>.
6644 </para>
6645
6646 <para>
6647  The whole job now reads: Replace <quote>document.referrer</quote> by
6648  <literal>"Not Your Business!"</literal> wherever it appears inside a
6649  &lt;script&gt tag. Note that this job won't break JavaScript syntax,
6650  since both the original and the replacement are syntactically valid
6651  string objects. The script just won't have access to the referrer
6652  information anymore.
6653 </para>
6654
6655 <para>
6656  We'll show you two other jobs from the JavaScript taming department, but
6657  this time only point out the constructs of special interest:
6658 </para>
6659
6660 <para>
6661  <screen>
6662 # The status bar is for displaying link targets, not pointless blahblah
6663 #
6664 s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig</screen>
6665 </para>
6666
6667 <para>
6668  <literal>\s</literal> stands for whitespace characters (space, tab, newline,
6669  carriage return, form feed), so that <literal>\s*</literal> means: <quote>zero
6670  or more whitespace</quote>. The <literal>?</literal> in <literal>.*?</literal>
6671  makes this matching of arbitrary text ungreedy. (Note that the <literal>U</literal>
6672  option is not set). The <literal>['"]</literal> construct means: <quote>a single
6673  <emphasis>or</emphasis> a double quote</quote>. Finally, <literal>\1</literal> is
6674  a back-reference to the first parenthesis just like <literal>$1</literal> above,
6675  with the difference that in the <emphasis>pattern</emphasis>, a backslash indicates
6676  a back-reference, whereas in the <emphasis>substitute</emphasis>, it's the dollar.
6677 </para>
6678
6679 <para>
6680  So what does this job do? It replaces assignments of single- or double-quoted
6681  strings to the <quote>window.status</quote> object with a dummy assignment
6682  (using a variable name that is hopefully odd enough not to conflict with
6683  real variables in scripts). Thus, it catches many cases where e.g. pointless
6684  descriptions are displayed in the status bar instead of the link target when
6685  you move your mouse over links.
6686 </para>
6687
6688 <para>
6689  <screen>
6690 # Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
6691 #
6692 s/(&lt;body [^&gt;]*)onunload(.*&gt;)/$1never$2/iU</screen>
6693 </para>
6694
6695 <para>
6696  Including the
6697  <ulink url="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents">OnUnload
6698  event binding</ulink> in the HTML DOM was a <emphasis>CRIME</emphasis>.
6699  When I close a browser window, I want it to close and die. Basta.
6700  This job replaces the <quote>onunload</quote> attribute in
6701  <quote>&lt;body&gt</quote> tags with the dummy word <literal>never</literal>.
6702  Note that the <literal>i</literal> option makes the pattern matching
6703  case-insensitive. Also note that ungreedy matching alone doesn't always guarantee
6704  a minimal match: In the first parenthesis, we had to use <literal>[^&gt;]*</literal>
6705  instead of <literal>.*</literal> to prevent the match from exceeding the
6706  &lt;body&gt tag if it doesn't contain <quote>OnUnload</quote>, but the page's
6707  content does.
6708 </para>
6709
6710 <para>
6711  The last example is from the fun department:
6712 </para>
6713
6714 <para>
6715  <screen>
6716 FILTER: fun Fun text replacements
6717
6718 # Spice the daily news:
6719 #
6720 s/microsoft(?!\.com)/MicroSuck/ig</screen>
6721 </para>
6722
6723 <para>
6724  Note the <literal>(?!\.com)</literal> part (a so-called negative lookahead)
6725  in the job's pattern, which means: Don't match, if the string
6726  <quote>.com</quote> appears directly following <quote>microsoft</quote>
6727  in the page. This prevents links to microsoft.com from being trashed, while
6728  still replacing the word everywhere else.
6729 </para>
6730
6731 <para>
6732  <screen>
6733 # Buzzword Bingo (example for extended regex syntax)
6734 #
6735 s* industry[ -]leading \
6736 |  cutting[ -]edge \
6737 |  customer[ -]focused \
6738 |  market[ -]driven \
6739 |  award[ -]winning # Comments are OK, too! \
6740 |  high[ -]performance \
6741 |  solutions[ -]based \
6742 |  unmatched \
6743 |  unparalleled \
6744 |  unrivalled \
6745 *&lt;font color="red"&gt;&lt;b&gt;BINGO!&lt;/b&gt;&lt;/font&gt; \
6746 *igx</screen>
6747 </para>
6748
6749 <para>
6750  The <literal>x</literal> option in this job turns on extended syntax, and allows for
6751  e.g. the liberal use of (non-interpreted!) whitespace for nicer formatting.
6752 </para>
6753
6754 <para>
6755  You get the idea?
6756 </para>
6757 </sect2>
6758
6759 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
6760
6761 <sect2 id="predefined-filters"><title>The Pre-defined Filters</title>
6762
6763 <!--
6764
6765  Note each filter is also listed in the +filter action section above. Please
6766  keep these listings in sync.
6767
6768 -->
6769
6770 <para>
6771 The distribution <filename>default.filter</filename> file contains a selection of
6772 pre-defined filters for your convenience:
6773 </para>
6774
6775 <variablelist>
6776  <varlistentry>
6777   <term><emphasis>js-annoyances</emphasis></term>
6778   <listitem>
6779    <para>
6780     The purpose of this filter is to get rid of particularly annoying JavaScript abuse.
6781     To that end, it
6782    <itemizedlist>
6783     <listitem>
6784      <para>
6785       replaces JavaScript references to the browser's referrer information
6786       with the string "Not Your Business!". This compliments the <literal><link
6787       linkend="hide-referrer">hide-referrer</link></literal> action on the content level.
6788      </para>
6789     </listitem>
6790     <listitem>
6791      <para>
6792       removes the bindings to the DOM's
6793       <ulink url="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents">unload
6794       event</ulink> which we feel has no right to exist and is responsible for most <quote>exit consoles</quote>, i.e.
6795       nasty windows that pop up when you close another one.
6796      </para>
6797     </listitem>
6798     <listitem>
6799      <para>
6800       removes code that causes new windows to be opened with undesired properties, such as being
6801       full-screen, non-resizeable, without location, status or menu bar etc.
6802      </para>
6803     </listitem>
6804    </itemizedlist>
6805    </para>
6806    <para>
6807     Use with caution. This is an aggressive filter, and can break sites that
6808     rely heavily on JavaScript.
6809    </para>
6810   </listitem>
6811  </varlistentry>
6812
6813  <varlistentry>
6814   <term><emphasis>js-events</emphasis></term>
6815   <listitem>
6816    <para>
6817     This is a very radical measure. It removes virtually all JavaScript event bindings, which
6818     means that scripts can not react to user actions such as mouse movements or clicks, window
6819     resizing etc, anymore. Use with caution!
6820    </para>
6821    <para>
6822     We <emphasis>strongly discourage</emphasis> using this filter as a default since it breaks
6823     many legitimate scripts. It is meant for use only on extra-nasty sites (should you really
6824     need to go there).
6825    </para>
6826   </listitem>
6827  </varlistentry>
6828
6829 <varlistentry>
6830   <term><emphasis>html-annoyances</emphasis></term>
6831   <listitem>
6832    <para>
6833     This filter will undo many common instances of HTML based abuse.
6834    </para>
6835    <para>
6836     The <literal>BLINK</literal> and <literal>MARQUEE</literal> tags
6837     are neutralized (yeah baby!), and browser windows will be created as
6838     resizeable (as of course they should be!), and will have location,
6839     scroll and menu bars -- even if specified otherwise.
6840    </para>
6841   </listitem>
6842  </varlistentry>
6843
6844  <varlistentry>
6845   <term><emphasis>content-cookies</emphasis></term>
6846   <listitem>
6847    <para>
6848     Most cookies are set in the HTTP dialog, where they can be intercepted
6849     by the
6850     <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>
6851     and <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>
6852     actions. But web sites increasingly make use of HTML meta tags and JavaScript
6853     to sneak cookies to the browser on the content level.
6854    </para>
6855    <para>
6856     This filter disables most HTML and JavaScript code that reads or sets
6857     cookies. It cannot detect all clever uses of these types of code, so it
6858     should not be relied on as an absolute fix. Use it wherever you would also
6859     use the cookie crunch actions.
6860    </para>
6861   </listitem>
6862  </varlistentry>
6863
6864  <varlistentry>
6865   <term><emphasis>refresh tags</emphasis></term>
6866   <listitem>
6867    <para>
6868     Disable any refresh tags if the interval is greater than nine seconds (so
6869     that redirections done via refresh tags are not destroyed). This is useful
6870     for dial-on-demand setups, or for those who find this HTML feature
6871     annoying.
6872    </para>
6873   </listitem>
6874  </varlistentry>
6875
6876  <varlistentry>
6877   <term><emphasis>unsolicited-popups</emphasis></term>
6878   <listitem>
6879    <para>
6880     This filter attempts to prevent only <quote>unsolicited</quote> pop-up
6881     windows from opening, yet still allow pop-up windows that the user
6882     has explicitly chosen to open. It was added in version 3.0.1,
6883     as an improvement over earlier such filters.
6884    </para>
6885    <para>
6886     Technical note: The filter works by redefining the window.open JavaScript
6887     function to a dummy function, <literal>PrivoxyWindowOpen()</literal>,
6888     during the loading and rendering phase of each HTML page access, and
6889     restoring the function afterward.
6890    </para>
6891    <para>
6892     This is recommended only for browsers that cannot perform this function
6893     reliably themselves. And be aware that some sites require such windows
6894     in order to function normally. Use with caution.
6895    </para>
6896   </listitem>
6897  </varlistentry>
6898
6899  <varlistentry>
6900   <term><emphasis>all-popups</emphasis></term>
6901   <listitem>
6902    <para>
6903     Attempt to prevent <emphasis>all</emphasis> pop-up windows from opening.
6904     Note this should be used with even more discretion than the above, since
6905     it is more likely to break some sites that require pop-ups for normal
6906     usage. Use with caution.
6907    </para>
6908   </listitem>
6909  </varlistentry>
6910
6911  <varlistentry>
6912   <term><emphasis>img-reorder</emphasis></term>
6913   <listitem>
6914    <para>
6915     This is a helper filter that has no value if used alone. It makes the
6916     <literal>banners-by-size</literal> and <literal>banners-by-link</literal>
6917     (see below) filters more effective and should be enabled together with them.
6918    </para>
6919   </listitem>
6920  </varlistentry>
6921
6922  <varlistentry>
6923   <term><emphasis>banners-by-size</emphasis></term>
6924   <listitem>
6925    <para>
6926     This filter removes image tags purely based on what size they are. Fortunately
6927     for us, many ads and banner images tend to conform to certain standardized
6928     sizes, which makes this filter quite effective for ad stripping purposes.
6929    </para>
6930    <para>
6931     Occasionally this filter will cause false positives on images that are not ads,
6932     but just happen to be of one of the standard banner sizes.
6933    </para>
6934    <para>
6935     Recommended only for those who require extreme ad blocking. The default
6936     block rules should catch 95+% of all ads <emphasis>without</emphasis> this filter enabled.
6937    </para>
6938   </listitem>
6939  </varlistentry>
6940
6941  <varlistentry>
6942   <term><emphasis>banners-by-link</emphasis></term>
6943   <listitem>
6944    <para>
6945     This is an experimental filter that attempts to kill any banners if
6946     their URLs seem to point to known or suspected click trackers. It is currently
6947     not of much value and is not recommended for use by default.
6948    </para>
6949   </listitem>
6950  </varlistentry>
6951
6952  <varlistentry>
6953   <term><emphasis>webbugs</emphasis></term>
6954   <listitem>
6955    <para>
6956     Webbugs are small, invisible images (technically 1X1 GIF images), that
6957     are used to track users across websites, and collect information on them.
6958     As an HTML page is loaded by the browser, an embedded image tag causes the
6959     browser to contact a third-party site, disclosing the tracking information
6960     through the requested URL and/or cookies for that third-party domain, without
6961     the user ever becoming aware of the interaction with the third-party site.
6962     HTML-ized spam also uses a similar technique to verify email addresses.
6963    </para>
6964    <para>
6965     This filter removes the HTML code that loads such <quote>webbugs</quote>.
6966    </para>
6967   </listitem>
6968  </varlistentry>
6969
6970  <varlistentry>
6971   <term><emphasis>tiny-textforms</emphasis></term>
6972   <listitem>
6973    <para>
6974     A rather special-purpose filter that can be used to enlarge textareas (those
6975     multi-line text boxes in web forms) and turn off hard word wrap in them.
6976     It was written for the sourceforge.net tracker system where such boxes are
6977     a nuisance, but it can be handy on other sites, too.
6978    </para>
6979    <para>
6980     It is not recommended to use this filter as a default.
6981    </para>
6982   </listitem>
6983  </varlistentry>
6984
6985  <varlistentry>
6986   <term><emphasis>jumping-windows</emphasis></term>
6987   <listitem>
6988    <para>
6989     Many consider windows that move, or resize themselves to be abusive. This filter
6990     neutralizes the related JavaScript code. Note that some sites might not display
6991     or behave as intended when using this filter. Use with caution.
6992    </para>
6993   </listitem>
6994  </varlistentry>
6995
6996  <varlistentry>
6997   <term><emphasis>frameset-borders</emphasis></term>
6998   <listitem>
6999    <para>
7000     Some web designers seem to assume that everyone in the world will view their
7001     web sites using the same browser brand and version, screen resolution etc,
7002     because only that assumption could explain why they'd use static frame sizes,
7003     yet prevent their frames from being resized by the user, should they be too
7004     small to show their whole content.
7005    </para>
7006    <para>
7007     This filter removes the related HTML code. It should only be applied to sites
7008     which need it.
7009    </para>
7010   </listitem>
7011  </varlistentry>
7012
7013  <varlistentry>
7014   <term><emphasis>demoronizer</emphasis></term>
7015   <listitem>
7016    <para>
7017     Many Microsoft products that generate HTML use non-standard extensions (read:
7018     violations) of the ISO 8859-1 aka Latin-1 character set. This can cause those
7019     HTML documents to display with errors on standard-compliant platforms.
7020    </para>
7021    <para>
7022     This filter translates the MS-only characters into Latin-1 equivalents.
7023     It is not necessary when using MS products, and will cause corruption of
7024     all documents that use 8-bit character sets other than Latin-1. It's mostly
7025     worthwhile for Europeans on non-MS platforms, if weird garbage characters
7026     sometimes appear on some pages, or user agents that don't correct for this on
7027     the fly.
7028 <!--
7029     My version of Mozilla (ancient) shows litte square boxes for quote
7030     characters, and apostrophes on moronized pages. So many pages have this, I
7031     can read them fine now. HB 08/27/06
7032 -->
7033    </para>
7034   </listitem>
7035  </varlistentry>
7036
7037  <varlistentry>
7038   <term><emphasis>shockwave-flash</emphasis></term>
7039   <listitem>
7040    <para>
7041     A filter for shockwave haters. As the name suggests, this filter strips code
7042     out of web pages that is used to embed shockwave flash objects.
7043    </para>
7044    <para>
7045    </para>
7046   </listitem>
7047  </varlistentry>
7048
7049  <varlistentry>
7050   <term><emphasis>quicktime-kioskmode</emphasis></term>
7051   <listitem>
7052    <para>
7053     Change HTML code that embeds Quicktime objects so that kioskmode, which
7054     prevents saving, is disabled.
7055    </para>
7056   </listitem>
7057  </varlistentry>
7058
7059  <varlistentry>
7060   <term><emphasis>fun</emphasis></term>
7061   <listitem>
7062    <para>
7063     Text replacements for subversive browsing fun. Make fun of your favorite
7064     Monopolist or play buzzword bingo.
7065    </para>
7066   </listitem>
7067  </varlistentry>
7068
7069  <varlistentry>
7070   <term><emphasis>crude-parental</emphasis></term>
7071   <listitem>
7072    <para>
7073     A demonstration-only filter that shows how <application>Privoxy</application>
7074     can be used to delete web content on a keyword basis.
7075    </para>
7076   </listitem>
7077  </varlistentry>
7078
7079  <varlistentry>
7080   <term><emphasis>ie-exploits</emphasis></term>
7081   <listitem>
7082    <para>
7083     An experimental collection of text replacements to disable malicious HTML and JavaScript
7084     code that exploits known security holes in Internet Explorer.
7085    </para>
7086    <para>
7087     Presently, it only protects against Nimda and a cross-site scripting bug, and
7088     would need active maintenance to provide more substantial protection.
7089    </para>
7090   </listitem>
7091  </varlistentry>
7092
7093  <varlistentry>
7094   <term><emphasis>site-specifics</emphasis></term>
7095   <listitem>
7096    <para>
7097     Some web sites have very specific problems, the cure for which doesn't apply
7098     anywhere else, or could even cause damage on other sites.
7099    </para>
7100    <para>
7101     This is a collection of such site-specific cures which should only be applied
7102     to the sites they were intended for, which is what the supplied
7103     <filename>default.action</filename> file does. Users shouldn't need to change
7104     anything regarding this filter.
7105    </para>
7106   </listitem>
7107  </varlistentry>
7108
7109  <varlistentry>
7110   <term><emphasis>google</emphasis></term>
7111   <listitem>
7112    <para>
7113     A CSS based block for Google text ads. Also removes a width limitation
7114     and the toolbar advertisement.
7115    </para>
7116   </listitem>
7117  </varlistentry>
7118
7119   <varlistentry>
7120   <term><emphasis>yahoo</emphasis></term>
7121   <listitem>
7122    <para>
7123     Another CSS based block, this time for Yahoo text ads. And removes
7124     a width limitation as well.
7125    </para>
7126   </listitem>
7127  </varlistentry>
7128
7129   <varlistentry>
7130   <term><emphasis>msn</emphasis></term>
7131   <listitem>
7132    <para>
7133     Another CSS based block, this time for MSN text ads. And removes
7134     tracking URLs, as well as a width limitation.
7135    </para>
7136   </listitem>
7137  </varlistentry>
7138
7139  <varlistentry>
7140   <term><emphasis>blogspot</emphasis></term>
7141   <listitem>
7142    <para>
7143     Cleans up some Blogspot blogs. Read the fine print before using this one!
7144    </para>
7145    <para>
7146     This filter also intentionally removes some navigation stuff and sets the
7147     page width to 100%. As a result, some rounded <quote>corners</quote> would
7148     appear to early or not at all and as fixing this would require a browser
7149     that understands background-size (CSS3), they are removed instead.
7150    </para>
7151   </listitem>
7152  </varlistentry>
7153
7154   <varlistentry>
7155   <term><emphasis>xml-to-html</emphasis></term>
7156   <listitem>
7157    <para>
7158     Header filter to change the Content-Type from xml to html.
7159    </para>
7160   </listitem>
7161  </varlistentry>
7162   <varlistentry>
7163   <term><emphasis>html-to-xml</emphasis></term>
7164   <listitem>
7165    <para>
7166     Header filter to change the Content-Type from html to xml.
7167    </para>
7168   </listitem>
7169  </varlistentry>
7170
7171 <!--
7172  <varlistentry>
7173   <term><emphasis> </emphasis></term>
7174   <listitem>
7175    <para>
7176    </para>
7177    <para>
7178    </para>
7179   </listitem>
7180  </varlistentry>
7181 -->
7182 </variablelist>
7183
7184 </sect2>
7185 </sect1>
7186
7187 <!--  ~  End section  ~  -->
7188
7189
7190
7191 <!--   ~~~~~       New section      ~~~~~     -->
7192
7193 <sect1 id="templates">
7194 <title>Privoxy's Template Files</title>
7195 <para>
7196  All <application>Privoxy</application> built-in pages, i.e. error pages such as the
7197  <ulink url="http://show-the-404-error.page"><quote>404 - No Such Domain</quote>
7198  error page</ulink>, the <ulink
7199  url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
7200  page</ulink>
7201  and all pages of its <ulink url="http://config.privoxy.org/">web-based
7202  user interface</ulink>, are generated from <emphasis>templates</emphasis>.
7203  (<application>Privoxy</application> must be running for the above links to work as
7204  intended.)
7205 </para>
7206
7207 <para>
7208  These templates are stored in a subdirectory of the <link linkend="confdir">configuration
7209  directory</link> called <filename>templates</filename>. On Unixish platforms,
7210  this is typically
7211  <ulink url="file:///etc/privoxy/templates/"><filename>/etc/privoxy/templates/</filename></ulink>.
7212 </para>
7213
7214 <para>
7215  The templates are basically normal HTML files, but with place-holders (called symbols
7216  or exports), which <application>Privoxy</application> fills at run time. You can
7217  edit the templates with a normal text editor, should you want to customize them.
7218  (<emphasis>Not recommended for the casual user</emphasis>). Note that
7219  just like in configuration files, lines starting with <literal>#</literal> are
7220  ignored when the templates are filled in.
7221 </para>
7222
7223 <para>
7224  The place-holders are of the form <literal>@name@</literal>, and you will
7225  find a list of available symbols, which vary from template to template,
7226  in the comments at the start of each file. Note that these comments are not
7227  always accurate, and that it's probably best to look at the existing HTML
7228  code to find out which symbols are supported and what they are filled in with.
7229 </para>
7230
7231 <para>
7232  A special application of this substitution mechanism is to make whole
7233  blocks of HTML code disappear when a specific symbol is set. We use this
7234  for many purposes, one of them being to include the beta warning in all
7235  our user interface (CGI) pages when <application>Privoxy</application>
7236  is in an alpha or beta development stage:
7237 </para>
7238
7239 <para>
7240  <screen>
7241 &lt;!-- @if-unstable-start --&gt;
7242
7243   ... beta warning HTML code goes here ...
7244
7245 &lt;!-- if-unstable-end@ --&gt;</screen>
7246 </para>
7247
7248 <para>
7249  If the "unstable" symbol is set, everything in between and including
7250  <literal>@if-unstable-start</literal> and <literal>if-unstable-end@</literal>
7251  will disappear, leaving nothing but an empty comment:
7252 </para>
7253
7254 <para>
7255  <screen>&lt;!--  --&gt;</screen>
7256 </para>
7257
7258 <para>
7259  There's also an if-then-else construct and an <literal>#include</literal>
7260  mechanism, but you'll sure find out if you are inclined to edit the
7261  templates ;-)
7262 </para>
7263
7264 <para>
7265  All templates refer to a style located at
7266  <ulink url="http://config.privoxy.org/send-stylesheet"><literal>http://config.privoxy.org/send-stylesheet</literal></ulink>.
7267  This is, of course, locally served by <application>Privoxy</application>
7268  and the source for it can be found and edited in the
7269  <filename>cgi-style.css</filename> template.
7270 </para>
7271
7272 </sect1>
7273
7274 <!--  ~  End section  ~  -->
7275
7276
7277
7278 <!--   ~~~~~       New section      ~~~~~     -->
7279
7280 <sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
7281 Requests</title>
7282
7283 <!-- Include contacting.sgml boilerplate: -->
7284  &contacting;
7285 <!-- end boilerplate -->
7286
7287 </sect1>
7288
7289 <!--  ~  End section  ~  -->
7290
7291
7292 <!--   ~~~~~       New section      ~~~~~     -->
7293 <sect1 id="copyright"><title>Privoxy Copyright, License and History</title>
7294
7295 <!-- Include copyright.sgml: -->
7296  &copyright;
7297 <!-- end copyright -->
7298
7299 <!--   ~~~~~       New section      ~~~~~     -->
7300 <sect2><title>License</title>
7301 <!-- Include copyright.sgml: -->
7302  &license;
7303 <!-- end copyright -->
7304 </sect2>
7305 <!--  ~  End section  ~  -->
7306
7307
7308 <!--   ~~~~~       New section      ~~~~~     -->
7309
7310 <sect2 id="history"><title>History</title>
7311 <!-- Include history.sgml: -->
7312  &history;
7313 <!-- end history -->
7314 </sect2>
7315
7316 <sect2 id="authors"><title>Authors</title>
7317 <!-- Include p-authors.sgml: -->
7318  &p-authors;
7319 <!-- end authors -->
7320 </sect2>
7321
7322 </sect1>
7323
7324 <!--  ~  End section  ~  -->
7325
7326
7327 <!--   ~~~~~       New section      ~~~~~     -->
7328 <sect1 id="seealso"><title>See Also</title>
7329 <!-- Include seealso.sgml: -->
7330  &seealso;
7331 <!-- end seealso -->
7332 </sect1>
7333
7334
7335
7336 <!--   ~~~~~       New section      ~~~~~     -->
7337 <sect1 id="appendix"><title>Appendix</title>
7338
7339
7340 <!--   ~~~~~       New section      ~~~~~     -->
7341 <sect2 id="regex">
7342 <title>Regular Expressions</title>
7343 <para>
7344  <application>Privoxy</application> uses Perl-style <quote>regular
7345  expressions</quote> in its <link linkend="actions-file">actions
7346  files</link> and <link linkend="filter-file">filter file</link>,
7347  through the <ulink url="http://www.pcre.org/">PCRE</ulink> and
7348 <!--
7349  dead 08/27/06
7350  <ulink url="http://www.oesterhelt.org/pcrs/">PCRS</ulink> libraries.
7351 -->
7352  <application>PCRS</application> libraries.
7353 </para>
7354
7355 <para>
7356  If you are reading this, you probably don't understand what <quote>regular
7357  expressions</quote> are, or what they can do. So this will be a very brief
7358  introduction only. A full explanation would require a <ulink
7359  url="http://www.oreilly.com/catalog/regex/">book</ulink> ;-)
7360 </para>
7361
7362 <para>
7363  Regular expressions provide a language to describe patterns that can be
7364  run against strings of characters (letter, numbers, etc), to see if they
7365  match the string or not. The  patterns are themselves (sometimes complex)
7366  strings of literal characters, combined with  wild-cards, and other special
7367  characters, called meta-characters. The <quote>meta-characters</quote> have
7368  special meanings and are used to build complex patterns to be matched against.
7369  Perl Compatible Regular Expressions are an especially convenient
7370  <quote>dialect</quote> of the regular expression language.
7371 </para>
7372
7373 <para>
7374  To make a simple analogy, we do something similar when we use wild-card
7375  characters when listing files with the <command>dir</command> command in DOS.
7376  <literal>*.*</literal> matches all filenames. The <quote>special</quote>
7377  character here is the asterisk which matches any and all characters. We can be
7378  more specific and use <literal>?</literal> to match just individual
7379  characters. So <quote>dir file?.text</quote> would match
7380  <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
7381  matching, using a similar technique to <quote>regular expressions</quote>!
7382 </para>
7383
7384 <para>
7385  Regular expressions do essentially the same thing, but are much, much more
7386  powerful. There are many more <quote>special characters</quote> and ways of
7387  building complex patterns however. Let's look at a few of the common ones,
7388  and then some examples:
7389 </para>
7390
7391 <para><simplelist>
7392  <member>
7393   <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
7394   <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
7395  </member>
7396 </simplelist></para>
7397
7398 <para><simplelist>
7399  <member>
7400   <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
7401   times. Either/or.
7402  </member>
7403 </simplelist></para>
7404
7405 <para><simplelist>
7406  <member>
7407   <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
7408   times.
7409  </member>
7410 </simplelist></para>
7411
7412 <para><simplelist>
7413  <member>
7414   <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
7415   times.
7416  </member>
7417 </simplelist></para>
7418
7419 <para><simplelist>
7420  <member>
7421   <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
7422   the following character should be taken literally. This is used where one of the
7423   special characters (e.g. <quote>.</quote>) needs to be taken literally and
7424   not as a special meta-character. Example: <quote>example\.com</quote>, makes
7425   sure the period is recognized only as a period (and not expanded to its
7426   meta-character meaning of any single character).
7427  </member>
7428 </simplelist></para>
7429
7430 <para><simplelist>
7431  <member>
7432   <emphasis>[ ]</emphasis> - Characters enclosed in brackets will be matched if
7433   any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
7434   matches any numeric digit (zero through nine). As an example, we can combine
7435   this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
7436  </member>
7437 </simplelist></para>
7438
7439 <para><simplelist>
7440  <member>
7441   <emphasis>( )</emphasis> - parentheses are used to group a sub-expression,
7442   or multiple sub-expressions.
7443  </member>
7444 </simplelist></para>
7445
7446 <para><simplelist>
7447  <member>
7448   <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
7449   <quote>or</quote> conditional statement. A match is successful if the
7450   sub-expression on either side of <quote>|</quote> matches. As an example:
7451   <quote>/(this|that) example/</quote> uses grouping and the bar character
7452   and would match either <quote>this example</quote> or <quote>that
7453   example</quote>, and nothing else.
7454  </member>
7455 </simplelist></para>
7456
7457 <para>
7458  These are just some of the ones you are likely to use when matching URLs with
7459  <application>Privoxy</application>, and is a long way from a definitive
7460  list. This is enough to get us started with a few simple examples which may
7461  be more illuminating:
7462 </para>
7463
7464 <para>
7465  <emphasis><literal>/.*/banners/.*</literal></emphasis> - A  simple example
7466  that uses the common combination of <quote>.</quote> and <quote>*</quote> to
7467  denote any character, zero or more times. In other words, any string at all.
7468  So we start with a literal forward slash, then our regular expression pattern
7469  (<quote>.*</quote>) another literal forward slash, the string
7470  <quote>banners</quote>, another forward slash, and lastly another
7471  <quote>.*</quote>. We are building
7472  a directory path here. This will match any file with the path that has a
7473  directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
7474  any characters, and this could conceivably be more forward slashes, so it
7475  might expand into a much longer looking path. For example, this could match:
7476  <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
7477  <quote>/banners/annoying.html</quote>, or almost an infinite number of other
7478  possible combinations, just so it has <quote>banners</quote> in the path
7479  somewhere.
7480 </para>
7481
7482 <para>
7483  And now something a little more complex:
7484 </para>
7485
7486 <para>
7487  <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
7488  We have several literal forward slashes again (<quote>/</quote>), so we are
7489  building another expression that is a file path statement. We have another
7490  <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
7491  it matches our expression. The only true literal that <emphasis>must
7492  match</emphasis> our pattern is <application>adv</application>, together with
7493  the forward slashes. What comes after the <quote>adv</quote> string is the
7494  interesting part.
7495 </para>
7496
7497 <para>
7498  Remember the <quote>?</quote> means the preceding expression (either a
7499  literal character or anything grouped with <quote>(...)</quote> in this case)
7500  can exist or not, since this means either zero or one match. So
7501  <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
7502  individual sub-expressions: <quote>(er)</quote>,
7503  <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
7504  means <quote>or</quote>. We have two of those. For instance,
7505  <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
7506  <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
7507  attempt at matching as many variations of <quote>advertisement</quote>, and
7508  similar, as possible. So this would expand to match just <quote>adv</quote>,
7509  or <quote>advert</quote>, or <quote>adverts</quote>, or
7510  <quote>advertising</quote>, or <quote>advertisement</quote>, or
7511  <quote>advertisements</quote>. You get the idea. But it would not match
7512  <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
7513  changing our regular expression to:
7514  <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
7515  either spelling.
7516 </para>
7517
7518 <para>
7519  <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
7520  another path statement with forward slashes. Anything in the square brackets
7521  <quote>[ ]</quote> can be matched. This is using <quote>0-9</quote> as a
7522  shorthand expression to mean any digit one through nine. It is the same as
7523  saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
7524  means one or more of the preceding expression must be included. The preceding
7525  expression here is what is in the square brackets -- in this case, any digit
7526  one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
7527  This includes a <quote>|</quote>, so this needs to match the expression on
7528  either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
7529  side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
7530  since the <quote>?</quote> means the letter <quote>e</quote> is optional and
7531  can be matched once or not at all. So we are building an expression here to
7532  match image GIF or JPEG type image file. It must include the literal
7533  string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
7534  (which is now a literal, and not a special character, since it is escaped
7535  with <quote>\</quote>), and lastly either <quote>gif</quote>, or
7536  <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
7537  include: <quote>//advert1.jpg</quote>,
7538  <quote>/nasty/ads/advert1234.gif</quote>,
7539  <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
7540  <quote>advert1.gif</quote> (no leading slash), or
7541  <quote>/adverts232.jpg</quote> (the expression does not include an
7542  <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
7543  in the expression anywhere).
7544 </para>
7545
7546 <para>
7547  We are barely scratching the surface of regular expressions here so that you
7548  can understand the default <application>Privoxy</application>
7549  configuration files, and maybe use this knowledge to customize your own
7550  installation. There is much, much more that can be done with regular
7551  expressions. Now that you know enough to get started, you can learn more on
7552  your own :/
7553 </para>
7554
7555 <para>
7556  More reading on Perl Compatible Regular expressions:
7557  <ulink url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>
7558 </para>
7559
7560 <para>
7561  For information on regular expression based substitutions and their applications
7562  in filters, please see the <link linkend="filter-file">filter file tutorial</link>
7563  in this manual.
7564 </para>
7565 </sect2>
7566
7567 <!--  ~  End section  ~  -->
7568
7569
7570 <!--   ~~~~~       New section      ~~~~~     -->
7571 <sect2>
7572 <title>Privoxy's Internal Pages</title>
7573
7574 <para>
7575  Since <application>Privoxy</application> proxies each requested
7576  web page, it is easy for <application>Privoxy</application> to
7577  trap certain special URLs. In this way, we can talk directly to
7578  <application>Privoxy</application>, and see how it is
7579  configured, see how our rules are being applied, change these
7580  rules and other configuration options, and even turn
7581  <application>Privoxy's</application> filtering off, all with
7582  a web browser.
7583
7584 </para>
7585
7586 <para>
7587  The URLs listed below are the special ones that allow direct access
7588  to <application>Privoxy</application>. Of course,
7589  <application>Privoxy</application> must be running to access these. If
7590  not, you will get a friendly error message. Internet access is not
7591  necessary either.
7592 </para>
7593
7594 <para>
7595  <itemizedlist>
7596
7597  <listitem>
7598   <para>
7599    Privoxy main page:
7600   </para>
7601   <blockquote>
7602    <para>
7603      <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
7604    </para>
7605   </blockquote>
7606   <para>
7607    There is a shortcut: <ulink url="http://p.p/">http://p.p/</ulink> (But it
7608    doesn't provide a fall-back to a real page, in case the request is not
7609    sent through <application>Privoxy</application>)
7610   </para>
7611  </listitem>
7612
7613  <listitem>
7614   <para>
7615     Show information about the current configuration, including viewing and
7616     editing of actions files:
7617   </para>
7618    <blockquote>
7619    <para>
7620     <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
7621    </para>
7622   </blockquote>
7623  </listitem>
7624
7625  <listitem>
7626   <para>
7627     Show the source code version numbers:
7628   </para>
7629   <blockquote>
7630    <para>
7631     <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
7632    </para>
7633   </blockquote>
7634  </listitem>
7635
7636  <listitem>
7637   <para>
7638    Show the browser's request headers:
7639   </para>
7640   <blockquote>
7641    <para>
7642     <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
7643    </para>
7644   </blockquote>
7645  </listitem>
7646
7647  <listitem>
7648   <para>
7649    Show which actions apply to a URL and why:
7650   </para>
7651    <blockquote>
7652    <para>
7653     <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
7654    </para>
7655   </blockquote>
7656  </listitem>
7657
7658  <listitem>
7659   <para>
7660    Toggle Privoxy on or off. In this case, <quote>Privoxy</quote> continues
7661    to run, but only as a pass-through proxy, with no actions taking place:
7662   </para>
7663    <blockquote>
7664    <para>
7665     <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
7666    </para>
7667   </blockquote>
7668   <para>
7669    Short cuts. Turn off, then on:
7670   </para>
7671    <blockquote>
7672    <para>
7673      <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
7674    </para>
7675   </blockquote>
7676    <blockquote>
7677    <para>
7678      <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
7679    </para>
7680   </blockquote>
7681  </listitem>
7682
7683  </itemizedlist>
7684 </para>
7685
7686 <para>
7687  These may be bookmarked for quick reference. See next.
7688
7689 </para>
7690
7691 <sect3 id="bookmarklets">
7692 <title>Bookmarklets</title>
7693 <para>
7694  Below are some <quote>bookmarklets</quote> to allow you to easily access a
7695  <quote>mini</quote> version of some of <application>Privoxy's</application>
7696  special pages. They are designed for MS Internet Explorer, but should work
7697  equally well in Netscape, Mozilla, and other browsers which support
7698  JavaScript. They are designed to run directly from your bookmarks - not by
7699  clicking the links below (although that should work for testing).
7700 </para>
7701 <para>
7702  To save them, right-click the link and choose <quote>Add to Favorites</quote>
7703  (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
7704  the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
7705  Bookmarklet directly from your favorites/bookmarks. For even faster access,
7706  you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
7707  Toolbar</quote> (Netscape), and run them with a single click.
7708 </para>
7709
7710 <para>
7711  <itemizedlist>
7712
7713   <listitem>
7714    <para>
7715     <ulink
7716     url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&#38;set=enabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Enable</ulink>
7717    </para>
7718   </listitem>
7719
7720   <listitem>
7721    <para>
7722     <ulink
7723     url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&#38;set=disabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Disable</ulink>
7724    </para>
7725   </listitem>
7726
7727   <listitem>
7728    <para>
7729     <ulink
7730     url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&#38;set=toggle','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Toggle Privoxy</ulink> (Toggles between enabled and disabled)
7731    </para>
7732   </listitem>
7733
7734   <listitem>
7735    <para>
7736     <ulink
7737     url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y','ijbstatus','width=250,height=2,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy- View Status</ulink>
7738    </para>
7739   </listitem>
7740 <!--
7741   <listitem>
7742    <para>
7743     <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions/index.php?url='+escape(location.href),'Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Submit Actions File Feedback</ulink>
7744    </para>
7745   </listitem>
7746  -->
7747   <listitem>
7748    <para>
7749     <ulink url="javascript:void(window.open('http://config.privoxy.org/show-url-info?url='+escape(location.href),'Why').focus());">Privoxy - Why?</ulink>
7750    </para>
7751   </listitem>
7752  </itemizedlist>
7753 </para>
7754
7755 <para>
7756  Credit: The site which gave us the general idea for these bookmarklets is
7757  <ulink url="http://www.bookmarklets.com/">www.bookmarklets.com</ulink>. They
7758  have more information about bookmarklets.
7759 </para>
7760
7761
7762 </sect3>
7763
7764 </sect2>
7765
7766
7767 <!--   ~~~~~       New section      ~~~~~     -->
7768 <sect2 id="chain">
7769 <title>Chain of Events</title>
7770 <para>
7771  Let's take a quick look at the basic sequence of events when a web page is
7772  requested by your browser and <application>Privoxy</application> is on duty:
7773 </para>
7774
7775 <para>
7776  <itemizedlist>
7777  <listitem>
7778   <para>
7779    First, your web browser requests a web page. The browser knows to send
7780    the request to <application>Privoxy</application>, which will in turn,
7781    relay the request to the remote web server after passing the following
7782    tests:
7783   </para>
7784  </listitem>
7785  <listitem>
7786   <para>
7787    <application>Privoxy</application> traps any request for its own internal CGI
7788    pages (e.g <ulink url="http://p.p/">http://p.p/</ulink>) and sends the CGI page back to the browser.
7789   </para>
7790  </listitem>
7791  <listitem>
7792   <para>
7793    Next, <application>Privoxy</application> checks to see if the URL
7794    matches any <link
7795    linkend="BLOCK"><quote>+block</quote></link> patterns. If
7796    so, the URL is then blocked, and the remote web server will not be contacted.
7797    <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>
7798    is then checked and if it does not match, an
7799    HTML <quote>BLOCKED</quote> page is sent back. Otherwise, if it does match,
7800    an image is returned. The type of image depends on the setting of <link
7801    linkend="SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></link>
7802    (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
7803   </para>
7804  </listitem>
7805  <listitem>
7806   <para>
7807    Untrusted URLs are blocked. If URLs are being added to the
7808    <filename>trust</filename> file, then that is done.
7809   </para>
7810  </listitem>
7811  <listitem>
7812   <para>
7813    If the URL pattern matches the <link
7814    linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link> action,
7815    it is then processed. Unwanted parts of the requested URL are stripped.
7816   </para>
7817  </listitem>
7818  <listitem>
7819   <para>
7820    Now the rest of the client browser's request headers are processed. If any
7821    of these match any of the relevant actions (e.g. <link
7822    linkend="HIDE-USER-AGENT"><quote>+hide-user-agent</quote></link>,
7823    etc.), headers are suppressed or forged as determined by these actions and
7824    their parameters.
7825   </para>
7826  </listitem>
7827  <listitem>
7828   <para>
7829    Now the web server starts sending its response back (i.e. typically a web page and related
7830    data).
7831   </para>
7832  </listitem>
7833  <listitem>
7834   <para>
7835    First, the server headers are read and processed to determine, among other
7836    things, the MIME type (document type) and encoding. The headers are then
7837    filtered as determined by the
7838    <link linkend="CRUNCH-INCOMING-COOKIES"><quote>+crunch-incoming-cookies</quote></link>,
7839    <link linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>,
7840    and <link linkend="DOWNGRADE-HTTP-VERSION"><quote>+downgrade-http-version</quote></link>
7841    actions.
7842   </para>
7843  </listitem>
7844  <listitem>
7845   <para>
7846    If the <link linkend="KILL-POPUPS"><quote>+kill-popups</quote></link>
7847    action applies, and it is an HTML or JavaScript document, the popup-code in the
7848    response is filtered on-the-fly as it is received.
7849   </para>
7850  </listitem>
7851  <listitem>
7852   <para>
7853    If a <link linkend="FILTER"><quote>+filter</quote></link>
7854    or <link
7855    linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
7856    action applies (and the document type fits the action), the rest of the page is
7857    read into memory (up to a configurable limit). Then the filter rules (from
7858    <filename>default.filter</filename> and any other filter files) are
7859    processed against the buffered content. Filters are applied in the order
7860    they are specified in one of the filter files. Animated GIFs, if present,
7861    are reduced to either the first or last frame, depending on the action
7862    setting.The entire page, which is now filtered, is then sent by
7863    <application>Privoxy</application> back to your browser.
7864   </para>
7865   <para>
7866    If neither <link linkend="FILTER"><quote>+filter</quote></link>
7867    or <link
7868    linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
7869    matches, then <application>Privoxy</application> passes the raw data through
7870    to the client browser as it becomes available.
7871   </para>
7872  </listitem>
7873  <listitem>
7874   <para>
7875    As the browser receives the now (possibly filtered) page content, it
7876    reads and then requests any URLs that may be embedded within the page
7877    source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
7878    frames), sounds, etc. For each of these objects, the browser issues a new
7879    request. And each such request is in turn processed as above. Note that a
7880    complex web page may have many such embedded URLs.
7881   </para>
7882  </listitem>
7883
7884  </itemizedlist>
7885 </para>
7886
7887 </sect2>
7888
7889
7890 <!--   ~~~~~       New section      ~~~~~     -->
7891 <sect2 id="actionsanat">
7892 <title>Troubleshooting: Anatomy of an Action</title>
7893
7894 <para>
7895  The way <application>Privoxy</application> applies
7896  <link linkend="ACTIONS">actions</link> and <link linkend="FILTER">filters</link>
7897  to any given URL can be complex, and not always so
7898  easy to understand what is happening. And sometimes we need to be able to
7899  <emphasis>see</emphasis> just what <application>Privoxy</application> is
7900  doing. Especially, if something <application>Privoxy</application> is doing
7901  is causing us a problem inadvertently. It can be a little daunting to look at
7902  the actions and filters files themselves, since they tend to be filled with
7903  <link linkend="regex">regular expressions</link> whose consequences are not
7904  always so obvious.
7905 </para>
7906
7907 <para>
7908  One quick test to see if <application>Privoxy</application> is causing a problem
7909  or not, is to disable it temporarily. This should be the first troubleshooting
7910  step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
7911  and easy way to do this (be sure to flush caches afterward!). Looking at the
7912  logs is a good idea too.
7913 </para>
7914 <para>
7915  Another easy troubleshooting step to try is if you have done any
7916  customization of your installation, revert back to the installed
7917  defaults and see if that helps. There are times the developers get complaints
7918  about one thing or another, and the problem is more related to a customized
7919  configuration issue.
7920 </para>
7921
7922 <para>
7923  <application>Privoxy</application> also provides the
7924  <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
7925  page that can show us very specifically how <application>actions</application>
7926  are being applied to any given URL. This is a big help for troubleshooting.
7927 </para>
7928
7929 <para>
7930  First, enter one URL (or partial URL) at the prompt, and then
7931  <application>Privoxy</application> will tell us
7932  how the current configuration will handle it. This will not
7933  help with filtering effects (i.e. the <link
7934  linkend="FILTER"><quote>+filter</quote></link> action) from
7935  one of the filter files since this is handled very
7936  differently and not so easy to trap! It also will not tell you about any other
7937  URLs that may be embedded within the URL you are testing. For instance, images
7938  such as ads are expressed as URLs within the raw page source of HTML pages. So
7939  you will only get info for the actual URL that is pasted into the prompt area
7940  -- not any sub-URLs. If you want to know about embedded URLs like ads, you
7941  will have to dig those out of the HTML source. Use your browser's <quote>View
7942  Page Source</quote> option for this. Or right click on the ad, and grab the
7943  URL.
7944 </para>
7945
7946 <para>
7947  Let's try an example, <ulink url="http://google.com">google.com</ulink>,
7948  and look at it one section at a time in a sample configuration (your real
7949  configuration may vary):
7950 </para>
7951
7952 <para>
7953  <screen>
7954  Matches for http://google.com:
7955
7956  In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
7957
7958  {-add-header
7959  -block
7960  -content-type-overwrite
7961  -crunch-client-header
7962  -crunch-if-none-match
7963  -crunch-incoming-cookies
7964  -crunch-outgoing-cookies
7965  -crunch-server-header
7966  +deanimate-gifs {last}
7967  -downgrade-http-version
7968  +fast-redirects {check-decoded-url}
7969  -filter {js-events}
7970  -filter {content-cookies}
7971  -filter {all-popups}
7972  -filter {banners-by-link}
7973  -filter {tiny-textforms}
7974  -filter {frameset-borders}
7975  -filter {demoronizer}
7976  -filter {shockwave-flash}
7977  -filter {quicktime-kioskmode}
7978  -filter {fun}
7979  -filter {crude-parental}
7980  -filter {site-specifics}
7981  -filter {js-annoyances}
7982  -filter {html-annoyances}
7983  +filter {refresh-tags}
7984  -filter {unsolicited-popups}
7985  +filter {img-reorder}
7986  +filter {banners-by-size}
7987  +filter {webbugs}
7988  +filter {jumping-windows}
7989  +filter {ie-exploits}
7990  -filter {google}
7991  -filter {yahoo}
7992  -filter {msn}
7993  -filter {blogspot}
7994  -filter {xml-to-html}
7995  -filter {html-to-xml}
7996  -filter-client-headers
7997  -filter-server-headers
7998  -force-text-mode
7999  -handle-as-empty-document
8000  -handle-as-image
8001  -hide-accept-language
8002  -hide-content-disposition
8003  +hide-forwarded-for-headers
8004  +hide-from-header {block}
8005  -hide-if-modified-since
8006  +hide-referrer {forge}
8007  -hide-user-agent
8008  -inspect-jpegs
8009  -kill-popups
8010  -limit-connect
8011  -overwrite-last-modified
8012  +prevent-compression
8013  -redirect
8014  -send-vanilla-wafer
8015  -send-wafer
8016  +session-cookies-only
8017  +set-image-blocker {pattern}
8018  -treat-forbidden-connects-like-blocks }
8019 /
8020
8021  { -session-cookies-only }
8022  .google.com
8023
8024  { -fast-redirects }
8025  .google.com
8026
8027 In file: user.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
8028 (no matches in this file)
8029 </screen>
8030 </para>
8031
8032 <para>
8033  This is telling us how we have defined our
8034  <link linkend="ACTIONS"><quote>actions</quote></link>, and
8035  which ones match for our test case, <quote>google.com</quote>.
8036  Displayed is all the actions that are available to us. Remember,
8037  the <literal>+</literal> sign denotes <quote>on</quote>. <literal>-</literal>
8038  denotes <quote>off</quote>. So some are <quote>on</quote> here, but many
8039  are <quote>off</quote>. Each example we try may provide a slightly different
8040  end result, depending on our configuration directives.
8041 </para>
8042 <para>
8043  The first listing
8044   is for our <filename>default.action</filename> file. The large, multi-line
8045   listing, is how the actions are set to match for all URLs, i.e. our default
8046   settings. If you look at your <quote>actions</quote> file, this would be the
8047   section just below the <quote>aliases</quote> section near the top. This
8048   will apply to all URLs as signified by the single forward slash at the end
8049   of the listing -- <quote> / </quote>.
8050 </para>
8051
8052 <para>
8053  But we have defined additional actions that would be exceptions to these general
8054  rules, and then we list specific URLs (or patterns) that these exceptions
8055  would apply to. Last match wins. Just below this then are two explicit
8056  matches for <quote>.google.com</quote>. The first is negating our previous
8057  cookie setting, which was for <link
8058  linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>
8059  (i.e. not persistent). So we will allow persistent cookies for google, at
8060  least that is how it is in this example. The second turns
8061  <emphasis>off</emphasis> any <link
8062  linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link>
8063  action, allowing this to take place unmolested. Note that there is a leading
8064  dot here -- <quote>.google.com</quote>. This will match any hosts and
8065  sub-domains, in the google.com domain also, such as
8066  <quote>www.google.com</quote> or <quote>mail.google.com</quote>. But it would not
8067  match <quote>www.google.de</quote>! So, apparently, we have these two actions
8068  defined as exceptions to the general rules at the top somewhere in the lower
8069  part of our <filename>default.action</filename> file, and
8070  <quote>google.com</quote> is referenced somewhere in these latter sections.
8071 </para>
8072
8073 <para>
8074  Then, for our <filename>user.action</filename> file, we again have no hits.
8075  So there is nothing google-specific that we might have added to our own, local
8076  configuration. If there was, those actions would over-rule any actions from
8077  previously processed files, such as <filename>default.action</filename>.
8078  <filename>user.action</filename> typically has the last word. This is the
8079  best place to put hard and fast exceptions,
8080 </para>
8081
8082 <para>
8083  And finally we pull it all together in the bottom section and summarize how
8084  <application>Privoxy</application> is applying all its <quote>actions</quote>
8085  to <quote>google.com</quote>:
8086
8087 </para>
8088
8089 <para>
8090  <screen>
8091
8092  Final results:
8093
8094  -add-header
8095  -block
8096  -content-type-overwrite
8097  -crunch-client-header
8098  -crunch-if-none-match
8099  -crunch-incoming-cookies
8100  -crunch-outgoing-cookies
8101  -crunch-server-header
8102  +deanimate-gifs {last}
8103  -downgrade-http-version
8104  +fast-redirects {check-decoded-url}
8105  -filter {js-events}
8106  -filter {content-cookies}
8107  -filter {all-popups}
8108  -filter {banners-by-link}
8109  -filter {tiny-textforms}
8110  -filter {frameset-borders}
8111  -filter {demoronizer}
8112  -filter {shockwave-flash}
8113  -filter {quicktime-kioskmode}
8114  -filter {fun}
8115  -filter {crude-parental}
8116  -filter {site-specifics}
8117  -filter {js-annoyances}
8118  -filter {html-annoyances}
8119  +filter {refresh-tags}
8120  -filter {unsolicited-popups}
8121  +filter {img-reorder}
8122  +filter {banners-by-size}
8123  +filter {webbugs}
8124  +filter {jumping-windows}
8125  +filter {ie-exploits}
8126  -filter {google}
8127  -filter {yahoo}
8128  -filter {msn}
8129  -filter {blogspot}
8130  -filter {xml-to-html}
8131  -filter {html-to-xml}
8132  -filter-client-headers
8133  -filter-server-headers
8134  -force-text-mode
8135  -handle-as-empty-document
8136  -handle-as-image
8137  -hide-accept-language
8138  -hide-content-disposition
8139  +hide-forwarded-for-headers
8140  +hide-from-header {block}
8141  -hide-if-modified-since
8142  +hide-referrer {forge}
8143  -hide-user-agent
8144  -inspect-jpegs
8145  -kill-popups
8146  -limit-connect
8147  -overwrite-last-modified
8148  +prevent-compression
8149  -redirect
8150  -send-vanilla-wafer
8151  -send-wafer
8152  -session-cookies-only
8153  +set-image-blocker {pattern}
8154  -treat-forbidden-connects-like-blocks </screen>
8155 </para>
8156
8157 <para>
8158  Notice the only difference here to the previous listing, is to
8159  <quote>fast-redirects</quote> and <quote>session-cookies-only</quote>,
8160  which are activated specifically for this site in our configuration,
8161  and thus show in the <quote>Final Results</quote>.
8162 </para>
8163
8164 <para>
8165  Now another example, <quote>ad.doubleclick.net</quote>:
8166 </para>
8167
8168 <para>
8169  <screen>
8170
8171  { +block }
8172   ad*.
8173
8174  { +block }
8175   .ad.
8176
8177  { +block +handle-as-image }
8178   .[a-vx-z]*.doubleclick.net
8179 </screen>
8180 </para>
8181
8182 <para>
8183  We'll just show the interesting part here - the explicit matches. It is
8184  matched three different times. Two <quote>+block</quote> sections,
8185  and a <quote>+block +handle-as-image</quote>,
8186  which is the expanded form of one of our aliases that had been defined as:
8187  <quote>+block-as-image</quote>. (<link
8188  linkend="ALIASES"><quote>Aliases</quote></link> are defined in
8189  the first section of the actions file and typically used to combine more
8190  than one action.)
8191 </para>
8192
8193 <para>
8194  Any one of these would have done the trick and blocked this as an unwanted
8195  image. This is unnecessarily redundant since the last case effectively
8196  would also cover the first. No point in taking chances with these guys
8197  though ;-) Note that if you want an ad or obnoxious
8198  URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
8199  is done here -- as both a <link
8200  linkend="BLOCK"><quote>+block</quote></link>
8201  <emphasis>and</emphasis> an
8202  <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>.
8203  The custom alias <quote><literal>+block-as-image</literal></quote> just
8204  simplifies the process and make it more readable.
8205 </para>
8206
8207 <para>
8208  One last example. Let's try <quote>http://www.example.net/adsl/HOWTO/</quote>.
8209  This one is giving us problems. We are getting a blank page. Hmmm ...
8210 </para>
8211
8212 <para>
8213  <screen>
8214
8215  Matches for http://www.example.net/adsl/HOWTO/:
8216
8217  In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
8218
8219  {-add-header
8220   -block
8221   -content-type-overwrite
8222   -crunch-client-header
8223   -crunch-if-none-match
8224   -crunch-incoming-cookies
8225   -crunch-outgoing-cookies
8226   -crunch-server-header
8227   +deanimate-gifs
8228   -downgrade-http-version
8229   +fast-redirects {check-decoded-url}
8230   -filter {js-events}
8231   -filter {content-cookies}
8232   -filter {all-popups}
8233   -filter {banners-by-link}
8234   -filter {tiny-textforms}
8235   -filter {frameset-borders}
8236   -filter {demoronizer}
8237   -filter {shockwave-flash}
8238   -filter {quicktime-kioskmode}
8239   -filter {fun}
8240   -filter {crude-parental}
8241   -filter {site-specifics}
8242   -filter {js-annoyances}
8243   -filter {html-annoyances}
8244   +filter {refresh-tags}
8245   -filter {unsolicited-popups}
8246   +filter {img-reorder}
8247   +filter {banners-by-size}
8248   +filter {webbugs}
8249   +filter {jumping-windows}
8250   +filter {ie-exploits}
8251   -filter {google}
8252   -filter {yahoo}
8253   -filter {msn}
8254   -filter {blogspot}
8255   -filter {xml-to-html}
8256   -filter {html-to-xml}
8257   -filter-client-headers
8258   -filter-server-headers
8259   -force-text-mode
8260   -handle-as-empty-document
8261   -handle-as-image
8262   -hide-accept-language
8263   -hide-content-disposition
8264   +hide-forwarded-for-headers
8265   +hide-from-header{block}
8266   +hide-referer{forge}
8267   -hide-user-agent
8268   -inspect-jpegs
8269   -kill-popups
8270   -overwrite-last-modified
8271   +prevent-compression
8272   -redirect
8273   -send-vanilla-wafer
8274   -send-wafer
8275   +session-cookies-only
8276   +set-image-blocker{blank}
8277   -treat-forbidden-connects-like-blocks }
8278    /
8279
8280  { +block +handle-as-image }
8281   /ads
8282 </screen>
8283 </para>
8284
8285 <para>
8286  Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote> in our
8287  configuration! But we did not want this at all! Now we see why we get the
8288  blank page. It is actually triggering two different actions here, and
8289  the effects are aggregated so that the URL is blocked, and &my-app; is told
8290  to treat the block as if it were an image. But this is, of course, all wrong.
8291   We could now add a new action below this (or better in our own
8292   <filename>user.action</filename> file) that explicitly
8293   <emphasis>un</emphasis> blocks (
8294   <link linkend="BLOCK"><quote>{-block}</quote></link>) paths with
8295   <quote>adsl</quote> in them (remember, last match in the configuration
8296   wins). There are various ways to handle such exceptions. Example:
8297 </para>
8298
8299 <para>
8300  <screen>
8301
8302  { -block }
8303   /adsl
8304 </screen>
8305 </para>
8306
8307 <para>
8308  Now the page displays ;-)
8309  Remember to flush your browser's caches when making these kinds of changes to
8310  your configuration to insure that you get a freshly delivered page! Or, try
8311  using <literal>Shift+Reload</literal>.
8312 </para>
8313
8314 <para>
8315  But now what about a situation where we get no explicit matches like
8316  we did with:
8317 </para>
8318
8319 <para>
8320  <screen>
8321
8322  { +block +handle-as-image }
8323  /ads
8324 </screen>
8325 </para>
8326
8327 <para>
8328  That actually was very helpful and pointed us quickly to where the problem
8329  was. If you don't get this kind of match, then it means one of the default
8330  rules in the first section of <filename>default.action</filename> is causing
8331  the problem. This would require some guesswork, and maybe a little trial and
8332  error to isolate the offending rule. One likely cause would be one of the
8333  <link linkend="FILTER"><quote>+filter</quote></link> actions.
8334  These tend to be harder to troubleshoot.
8335  Try adding the URL for the site to one of aliases that turn off
8336  <link linkend="FILTER"><quote>+filter</quote></link>:
8337 </para>
8338
8339 <para>
8340  <screen>
8341
8342  { shop }
8343  .quietpc.com
8344  .worldpay.com   # for quietpc.com
8345  .jungle.com
8346  .scan.co.uk
8347  .forbes.com
8348 </screen>
8349 </para>
8350
8351 <para>
8352  <quote><literal>{ shop }</literal></quote> is an <quote>alias</quote> that expands to
8353  <quote><literal>{ -filter -session-cookies-only }</literal></quote>.
8354  Or you could do your own exception to negate filtering:
8355
8356 </para>
8357
8358 <para>
8359  <screen>
8360
8361  { -filter }
8362  # Disable ALL filter actions for sites in this section
8363  .forbes.com
8364  developer.ibm.com
8365  localhost
8366 </screen>
8367 </para>
8368
8369 <para>
8370  This would turn off all filtering for these sites. This is best
8371  put in <filename>user.action</filename>, for local site
8372  exceptions. Note that when a simple domain pattern is used by itself (without
8373  the subsequent path portion), all sub-pages within that domain are included
8374  automatcially in the scope of the action.
8375 </para>
8376
8377 <para>
8378  Images that are inexplicably being blocked, may well be hitting the
8379 <link linkend="FILTER-BANNERS-BY-SIZE"><quote>+filter{banners-by-size}</quote></link>
8380  rule, which assumes
8381  that images of certain sizes are ad banners (works well
8382  <emphasis>most of the time</emphasis>  since these tend to be standardized).
8383 </para>
8384
8385 <para>
8386  <quote><literal>{ fragile }</literal></quote> is an alias that disables most
8387  actions that are the most likely to cause trouble. This can be used as a
8388  last resort for problem sites.
8389 </para>
8390 <para>
8391  <screen>
8392
8393  { fragile }
8394  # Handle with care: easy to break
8395  mail.google.
8396  mybank.example.com</screen>
8397 </para>
8398
8399
8400 <para>
8401  <emphasis>Remember to flush caches!</emphasis> Note that the
8402  <literal>mail.google</literal> reference lacks the TLD portion (e.g.
8403  <quote>.com</quote>. This will effectively match any TLD with
8404  <literal>google</literal> in it, such as <literal>mail.google.de</literal>,
8405  just as an example.
8406 </para>
8407 <para>
8408  If this still does not work, you will have to go through the remaining
8409  actions one by one to find which one(s) is causing the problem.
8410 </para>
8411
8412 </sect2>
8413
8414 </sect1>
8415
8416  <!--
8417
8418  This program is free software; you can redistribute it
8419  and/or modify it under the terms of the GNU General
8420  Public License as published by the Free Software
8421  Foundation; either version 2 of the License, or (at
8422  your option) any later version.
8423
8424  This program is distributed in the hope that it will
8425  be useful, but WITHOUT ANY WARRANTY; without even the
8426  implied warranty of MERCHANTABILITY or FITNESS FOR A
8427  PARTICULAR PURPOSE.  See the GNU General Public
8428  License for more details.
8429
8430  The GNU General Public License should be included with
8431  this file.  If not, you can view it at
8432  http://www.gnu.org/copyleft/gpl.html
8433  or write to the Free Software Foundation, Inc.,
8434  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
8435  USA
8436
8437  $Log: user-manual.sgml,v $
8438  Revision 2.23  2006/10/02 22:43:53  hal9
8439  Contains new filter definitions from Fabian, and few other miscellaneous
8440  touch-ups.
8441
8442  Revision 2.22  2006/09/22 01:27:55  hal9
8443  Final commit of probably various minor changes here and there. Unless
8444  something changes this should be ready for pending release.
8445
8446  Revision 2.21  2006/09/20 03:21:36  david__schmidt
8447  Just the tiniest tweak.  Wafer thin!
8448
8449  Revision 2.20  2006/09/10 14:53:54  hal9
8450  Results of spell check. User manual has some updates to standard.actions file
8451  info.
8452
8453  Revision 2.19  2006/09/08 12:19:02  fabiankeil
8454  Adjust hide-if-modified-since example values
8455  to reflect the recent changes.
8456
8457  Revision 2.18  2006/09/08 02:38:57  hal9
8458  Various changes:
8459   -Fix a number of broken links.
8460   -Migrate the new Windows service command line options, and reference as
8461    needed.
8462   -Rebuild so that can be used with the new "user-manual" config capabilities.
8463   -Etc.
8464
8465  Revision 2.17  2006/09/05 13:25:12  david__schmidt
8466  Add Windows service invocation stuff (duplicated) in FAQ and in user manual under Windows startup.  One probably ought to reference the other.
8467
8468  Revision 2.16  2006/09/02 12:49:37  hal9
8469  Various small updates for new actions, filterfiles, etc.
8470
8471  Revision 2.15  2006/08/30 11:15:22  hal9
8472  More work on the new actions, especially filter-*-headers, and What's New
8473  section. User Manual is close to final form for 3.0.4 release. Some tinkering
8474  and proof reading left to do.
8475
8476  Revision 2.14  2006/08/29 10:59:36  hal9
8477  Add a "Whats New in this release" Section. Further work on multiple filter
8478  files, and assorted other minor changes.
8479
8480  Revision 2.13  2006/08/22 11:04:59  hal9
8481  Silence warnings and errors. This should build now. New filters were only
8482  stubbed in. More to be done.
8483
8484  Revision 2.12  2006/08/14 08:40:39  fabiankeil
8485  Documented new actions that were part of
8486  the "minor Privoxy improvements".
8487
8488  Revision 2.11  2006/07/18 14:48:51  david__schmidt
8489  Reorganizing the repository: swapping out what was HEAD (the old 3.1 branch)
8490  with what was really the latest development (the v_3_0_branch branch)
8491
8492  Revision 1.123.2.43  2005/05/23 09:59:10  hal9
8493  Fix typo 'loose'
8494
8495  Revision 1.123.2.42  2004/12/04 14:39:57  hal9
8496  Fix two minor typos per bug SF report.
8497
8498  Revision 1.123.2.41  2004/03/23 12:58:42  oes
8499  Fixed an inaccuracy
8500
8501  Revision 1.123.2.40  2004/02/27 12:48:49  hal9
8502  Add comment re: redirecting to local file system for set-image-blocker may
8503  is dependent on browser.
8504
8505  Revision 1.123.2.39  2004/01/30 22:31:40  oes
8506  Added a hint re bookmarklets to Quickstart section
8507
8508  Revision 1.123.2.38  2004/01/30 16:47:51  oes
8509  Some minor clarifications
8510
8511  Revision 1.123.2.37  2004/01/29 22:36:11  hal9
8512  Updates for no longer filtering text/plain, and demoronizer default settings,
8513  and copyright notice dates.
8514
8515  Revision 1.123.2.36  2003/12/10 02:26:26  hal9
8516  Changed the demoronizer filter description.
8517
8518  Revision 1.123.2.35  2003/11/06 13:36:37  oes
8519  Updated link to nightly CVS tarball
8520
8521  Revision 1.123.2.34  2003/06/26 23:50:16  hal9
8522  Add a small bit on filtering and problems re: source code being corrupted.
8523
8524  Revision 1.123.2.33  2003/05/08 18:17:33  roro
8525  Use apt-get instead of dpkg to install Debian package, which is more
8526  solid, uses the correct and most recent Debian version automatically.
8527
8528  Revision 1.123.2.32  2003/04/11 03:13:57  hal9
8529  Add small note about only one filterfile (as opposed to multiple actions
8530  files).
8531
8532  Revision 1.123.2.31  2003/03/26 02:03:43  oes
8533  Updated hard-coded copyright dates
8534
8535  Revision 1.123.2.30  2003/03/24 12:58:56  hal9
8536  Add new section on Predefined Filters.
8537
8538  Revision 1.123.2.29  2003/03/20 02:45:29  hal9
8539  More problems with \-\-chroot causing markup problems :(
8540
8541  Revision 1.123.2.28  2003/03/19 00:35:24  hal9
8542  Manual edit of revision log because 'chroot' (even inside a comment) was
8543  causing Docbook to hang here (due to double hyphen and the processor thinking
8544  it was a comment).
8545
8546  Revision 1.123.2.27  2003/03/18 19:37:14  oes
8547  s/Advanced|Radical/Adventuresome/g to avoid complaints re fun filter
8548
8549  Revision 1.123.2.26  2003/03/17 16:50:53  oes
8550  Added documentation for new chroot option
8551
8552  Revision 1.123.2.25  2003/03/15 18:36:55  oes
8553  Adapted to the new filters
8554
8555  Revision 1.123.2.24  2002/11/17 06:41:06  hal9
8556  Move default profiles table from FAQ to U-M, and other minor related changes.
8557  Add faq on cookies.
8558
8559  Revision 1.123.2.23  2002/10/21 02:32:01  hal9
8560  Updates to the user.action examples section. A few new ones.
8561
8562  Revision 1.123.2.22  2002/10/12 00:51:53  hal9
8563  Add demoronizer to filter section.
8564
8565  Revision 1.123.2.21  2002/10/10 04:09:35  hal9
8566  s/Advanced/Radical/ and added very brief note.
8567
8568  Revision 1.123.2.20  2002/10/10 03:49:21  hal9
8569  Add notes to session-cookies-only and Quickstart about pre-existing
8570  cookies. Also, note content-cookies work differently.
8571
8572  Revision 1.123.2.19  2002/09/26 01:25:36  hal9
8573  More explanation on Privoxy patterns, more on content-cookies and SSL.
8574
8575  Revision 1.123.2.18  2002/08/22 23:47:58  hal9
8576  Add 'Documentation' to Privoxy Menu shot in Configuration section to match
8577  CGIs.
8578
8579  Revision 1.123.2.17  2002/08/18 01:13:05  hal9
8580  Spell checked (only one typo this time!).
8581
8582  Revision 1.123.2.16  2002/08/09 19:20:54  david__schmidt
8583  Update to Mac OSX startup script name
8584
8585  Revision 1.123.2.15  2002/08/07 17:32:11  oes
8586  Converted some internal links from ulink to link for PDF creation; no content changed
8587
8588  Revision 1.123.2.14  2002/08/06 09:16:13  oes
8589  Nits re: actions file download
8590
8591  Revision 1.123.2.13  2002/08/02 18:23:19  g_sauthoff
8592  Just 2 small corrections to the Gentoo sections
8593
8594  Revision 1.123.2.12  2002/08/02 18:17:21  g_sauthoff
8595  Added 2 Gentoo sections
8596
8597  Revision 1.123.2.11  2002/07/26 15:20:31  oes
8598  - Added version info to title
8599  - Added info on new filters
8600  - Revised parts of the filter file tutorial
8601  - Added info on where to get updated actions files
8602
8603  Revision 1.123.2.10  2002/07/25 21:42:29  hal9
8604  Add brief notes on not proxying non-HTTP protocols.
8605
8606  Revision 1.123.2.9  2002/07/11 03:40:28  david__schmidt
8607
8608  Updated Mac OSX sections due to installation location change
8609
8610  Revision 1.123.2.8  2002/06/09 16:36:32  hal9
8611  Clarifications on filtering and MIME. Hardcode 'latest release' in index.html.
8612
8613  Revision 1.123.2.7  2002/06/09 00:29:34  hal9
8614  Touch ups on filtering, in actions section and Anatomy.
8615
8616  Revision 1.123.2.6  2002/06/06 23:11:03  hal9
8617  Fix broken link. Linkchecked all docs.
8618
8619  Revision 1.123.2.5  2002/05/29 02:01:02  hal9
8620  This is break out of the entire config section from u-m, so it can
8621  eventually be used to generate the comments, etc in the main config file
8622  so that these are in sync with each other.
8623
8624  Revision 1.123.2.4  2002/05/27 03:28:45  hal9
8625  Ooops missed something from David.
8626
8627  Revision 1.123.2.3  2002/05/27 03:23:17  hal9
8628  Fix FIXMEs for OS2 and OSX startup. Fix Redhat typos (should be Red Hat).
8629  That's a wrap, I think.
8630
8631  Revision 1.123.2.2  2002/05/26 19:02:09  hal9
8632  Move Amiga stuff around to take of FIXME in start up section.
8633
8634  Revision 1.123.2.1  2002/05/26 17:04:25  hal9
8635  -Spellcheck, very minor edits, and sync across branches
8636
8637  Revision 1.123  2002/05/24 23:19:23  hal9
8638  Include new image (Proxy setup). More fun with guibutton.
8639  Minor corrections/clarifications here and there.
8640
8641  Revision 1.122  2002/05/24 13:24:08  oes
8642  Added Bookmarklet for one-click pre-filled access to show-url-info
8643
8644  Revision 1.121  2002/05/23 23:20:17  oes
8645   - Changed more (all?) references to actions to the
8646     <literal><link> style.
8647   - Small fixes in the actions chapter
8648   - Small clarifications in the quickstart to ad blocking
8649   - Removed <emphasis> from <title>s since the new doc CSS
8650     renders them red (bad in TOC).
8651
8652  Revision 1.120  2002/05/23 19:16:43  roro
8653  Correct Debian specials (installation and startup).
8654
8655  Revision 1.119  2002/05/22 17:17:05  oes
8656  Added Security hint
8657
8658  Revision 1.118  2002/05/21 04:54:55  hal9
8659  -New Section: Quickstart to Ad Blocking
8660  -Reformat Actions Anatomy to match new CGI layout
8661
8662  Revision 1.117  2002/05/17 13:56:16  oes
8663   - Reworked & extended Templates chapter
8664   - Small changes to Regex appendix
8665   - #included authors.sgml into (C) and hist chapter
8666
8667  Revision 1.116  2002/05/17 03:23:46  hal9
8668  Fixing merge conflict in Quickstart section.
8669
8670  Revision 1.115  2002/05/16 16:25:00  oes
8671  Extended the Filter File chapter & minor fixes
8672
8673  Revision 1.114  2002/05/16 09:42:50  oes
8674  More ulink->link, added some hints to Quickstart section
8675
8676  Revision 1.113  2002/05/15 21:07:25  oes
8677  Extended and further commented the example actions files
8678
8679  Revision 1.112  2002/05/15 03:57:14  hal9
8680  Spell check. A few minor edits here and there for better syntax and
8681  clarification.
8682
8683  Revision 1.111  2002/05/14 23:01:36  oes
8684  Fixing the fixes
8685
8686  Revision 1.110  2002/05/14 19:10:45  oes
8687  Restored alphabetical order of actions
8688
8689  Revision 1.109  2002/05/14 17:23:11  oes
8690  Renamed the prevent-*-cookies actions, extended aliases section and moved it before the example AFs
8691
8692  Revision 1.108  2002/05/14 15:29:12  oes
8693  Completed proofreading the actions chapter
8694
8695  Revision 1.107  2002/05/12 03:20:41  hal9
8696  Small clarifications for 127.0.0.1 vs localhost for listen-address since this
8697  apparently an important distinction for some OS's.
8698
8699  Revision 1.106  2002/05/10 01:48:20  hal9
8700  This is mostly proposed copyright/licensing additions and changes. Docs
8701  are still GPL, but licensing and copyright are more visible. Also, copyright
8702  changed in doc header comments (eliminate references to JB except FAQ).
8703
8704  Revision 1.105  2002/05/05 20:26:02  hal9
8705  Sorting out license vs copyright in these docs.
8706
8707  Revision 1.104  2002/05/04 08:44:45  swa
8708  bumped version
8709
8710  Revision 1.103  2002/05/04 00:40:53  hal9
8711  -Remove the TOC first page kludge. It's fixed proper now in ldp.dsl.in.
8712  -Some minor additions to Quickstart.
8713
8714  Revision 1.102  2002/05/03 17:46:00  oes
8715  Further proofread & reactivated short build instructions
8716
8717  Revision 1.101  2002/05/03 03:58:30  hal9
8718  Move the user-manual config directive to top of section. Add note about
8719  Privoxy needing read permissions for configs, and write for logs.
8720
8721  Revision 1.100  2002/04/29 03:05:55  hal9
8722  Add clarification on differences of new actions files.
8723
8724  Revision 1.99  2002/04/28 16:59:05  swa
8725  more structure in starting section
8726
8727  Revision 1.98  2002/04/28 05:43:59  hal9
8728  This is the break up of configuration.html into multiple files. This
8729  will probably break links elsewhere :(
8730
8731  Revision 1.97  2002/04/27 21:04:42  hal9
8732  -Rewrite of Actions File example.
8733  -Add section for user-manual directive in config.
8734
8735  Revision 1.96  2002/04/27 05:32:00  hal9
8736  -Add short section to Filter Files to tie in with +filter action.
8737  -Start rewrite of examples in Actions Examples (not finished).
8738
8739  Revision 1.95  2002/04/26 17:23:29  swa
8740  bookmarks cleaned, changed structure of user manual, screen and programlisting cleanups, and numerous other changes that I forgot
8741
8742  Revision 1.94  2002/04/26 05:24:36  hal9
8743  -Add most of Andreas suggestions to Chain of Events section.
8744  -A few other minor corrections and touch up.
8745
8746  Revision 1.92  2002/04/25 18:55:13  hal9
8747  More catchups on new actions files, and new actions names.
8748  Other assorted cleanups, and minor modifications.
8749
8750  Revision 1.91  2002/04/24 02:39:31  hal9
8751  Add 'Chain of Events' section.
8752
8753  Revision 1.90  2002/04/23 21:41:25  hal9
8754  Linuxconf is deprecated on RH, substitute chkconfig.
8755
8756  Revision 1.89  2002/04/23 21:05:28  oes
8757  Added hint for startup on Red Hat
8758
8759  Revision 1.88  2002/04/23 05:37:54  hal9
8760  Add AmigaOS install stuff.
8761
8762  Revision 1.87  2002/04/23 02:53:15  david__schmidt
8763  Updated OSX installation section
8764  Added a few English tweaks here an there
8765
8766  Revision 1.86  2002/04/21 01:46:32  hal9
8767  Re-write actions section.
8768
8769  Revision 1.85  2002/04/18 21:23:23  hal9
8770  Fix ugly typo (mine).
8771
8772  Revision 1.84  2002/04/18 21:17:13  hal9
8773  Spell Redhat correctly (ie Red Hat). A few minor grammar corrections.
8774
8775  Revision 1.83  2002/04/18 18:21:12  oes
8776  Added RPM install detail
8777
8778  Revision 1.82  2002/04/18 12:04:50  oes
8779  Cosmetics
8780
8781  Revision 1.81  2002/04/18 11:50:24  oes
8782  Extended Install section - needs fixing by packagers
8783
8784  Revision 1.80  2002/04/18 10:45:19  oes
8785  Moved text to buildsource.sgml, renamed some filters, details
8786
8787  Revision 1.79  2002/04/18 03:18:06  hal9
8788  Spellcheck, and minor touchups.
8789
8790  Revision 1.78  2002/04/17 18:04:16  oes
8791  Proofreading part 2
8792
8793  Revision 1.77  2002/04/17 13:51:23  oes
8794  Proofreading, part one
8795
8796  Revision 1.76  2002/04/16 04:25:51  hal9
8797  -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
8798  -Note about proxy may need requests to re-read config files.
8799
8800  Revision 1.75  2002/04/12 02:08:48  david__schmidt
8801  Remove OS/2 building info... it is already in the developer-manual
8802
8803  Revision 1.74  2002/04/11 00:54:38  hal9
8804  Add small section on submitting actions.
8805
8806  Revision 1.73  2002/04/10 18:45:15  swa
8807  generated
8808
8809  Revision 1.72  2002/04/10 04:06:19  hal9
8810  Added actions feedback  to Bookmarklets section
8811
8812  Revision 1.71  2002/04/08 22:59:26  hal9
8813  Version update. Spell chkconfig correctly :)
8814
8815  Revision 1.70  2002/04/08 20:53:56  swa
8816  ?
8817
8818  Revision 1.69  2002/04/06 05:07:29  hal9
8819  -Add privoxy-man-page.sgml, for man page.
8820  -Add authors.sgml for AUTHORS (and p-authors.sgml)
8821  -Reworked various aspects of various docs.
8822  -Added additional comments to sub-docs.
8823
8824  Revision 1.68  2002/04/04 18:46:47  swa
8825  consistent look. reuse of copyright, history et. al.
8826
8827  Revision 1.67  2002/04/04 17:27:57  swa
8828  more single file to be included at multiple points. make maintaining easier
8829
8830  Revision 1.66  2002/04/04 06:48:37  hal9
8831  Structural changes to allow for conditional inclusion/exclusion of content
8832  based on entity toggles, e.g. 'entity % p-not-stable  "INCLUDE"'. And
8833  definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
8834  eventually be set by Makefile.
8835  More boilerplate text for use across multiple docs.
8836
8837  Revision 1.65  2002/04/03 19:52:07  swa
8838  enhance squid section due to user suggestion
8839
8840  Revision 1.64  2002/04/03 03:53:43  hal9
8841  A few minor bug fixes, and touch ups. Ready for review.
8842
8843  Revision 1.63  2002/04/01 16:24:49  hal9
8844  Define entities to include boilerplate text. See doc/source/*.
8845
8846  Revision 1.62  2002/03/30 04:15:53  hal9
8847  - Fix privoxy.org/config links.
8848  - Paste in Bookmarklets from Toggle page.
8849  - Move Quickstart nearer top, and minor rework.
8850
8851  Revision 1.61  2002/03/29 01:31:08  hal9
8852  Minor update.
8853
8854  Revision 1.60  2002/03/27 01:57:34  hal9
8855  Added more to Anatomy section.
8856
8857  Revision 1.59  2002/03/27 00:54:33  hal9
8858  Touch up intro for new name.
8859
8860  Revision 1.58  2002/03/26 22:29:55  swa
8861  we have a new homepage!
8862
8863  Revision 1.57  2002/03/24 20:33:30  hal9
8864  A few minor catch ups with name change.
8865
8866  Revision 1.56  2002/03/24 16:17:06  swa
8867  configure needs to be generated.
8868
8869  Revision 1.55  2002/03/24 16:08:08  swa
8870  we are too lazy to make a block-built
8871  privoxy logo. hence removed the option.
8872
8873  Revision 1.54  2002/03/24 15:46:20  swa
8874  name change related issue.
8875
8876  Revision 1.53  2002/03/24 11:51:00  swa
8877  name change. changed filenames.
8878
8879  Revision 1.52  2002/03/24 11:01:06  swa
8880  name change
8881
8882  Revision 1.51  2002/03/23 15:13:11  swa
8883  renamed every reference to the old name with foobar.
8884  fixed "application foobar application" tag, fixed
8885  "the foobar" with "foobar". left junkbustser in cvs
8886  comments and remarks to history untouched.
8887
8888  Revision 1.50  2002/03/23 05:06:21  hal9
8889  Touch up.
8890
8891  Revision 1.49  2002/03/21 17:01:05  hal9
8892  New section in Appendix.
8893
8894  Revision 1.48  2002/03/12 06:33:01  hal9
8895  Catching up to Andreas and re_filterfile changes.
8896
8897  Revision 1.47  2002/03/11 13:13:27  swa
8898  correct feedback channels
8899
8900  Revision 1.46  2002/03/10 00:51:08  hal9
8901  Added section on JB internal pages in Appendix.
8902
8903  Revision 1.45  2002/03/09 17:43:53  swa
8904  more distros
8905
8906  Revision 1.44  2002/03/09 17:08:48  hal9
8907  New section on Jon's actions file editor, and move some stuff around.
8908
8909  Revision 1.43  2002/03/08 00:47:32  hal9
8910  Added imageblock{pattern}.
8911
8912  Revision 1.42  2002/03/07 18:16:55  swa
8913  looks better
8914
8915  Revision 1.41  2002/03/07 16:46:43  hal9
8916  Fix a few markup problems for jade.
8917
8918  Revision 1.40  2002/03/07 16:28:39  swa
8919  provide correct feedback channels
8920
8921  Revision 1.39  2002/03/06 16:19:28  hal9
8922  Note on perceived filtering slowdown per FR.
8923
8924  Revision 1.38  2002/03/05 23:55:14  hal9
8925  Stupid I did it again. Double hyphen in comment breaks jade.
8926
8927  Revision 1.37  2002/03/05 23:53:49  hal9
8928  jade barfs on '- -' embedded in comments. - -user option broke it.
8929
8930  Revision 1.36  2002/03/05 22:53:28  hal9
8931  Add new - - user option.
8932
8933  Revision 1.35  2002/03/05 00:17:27  hal9
8934  Added section on command line options.
8935
8936  Revision 1.34  2002/03/04 19:32:07  oes
8937  Changed default port to 8118
8938
8939  Revision 1.33  2002/03/03 19:46:13  hal9
8940  Emphasis on where/how to report bugs, etc
8941
8942  Revision 1.32  2002/03/03 09:26:06  joergs
8943  AmigaOS changes, config is now loaded from PROGDIR: instead of
8944  AmiTCP:db/junkbuster/ if no configuration file is specified on the
8945  command line.
8946
8947  Revision 1.31  2002/03/02 22:45:52  david__schmidt
8948  Just tweaking
8949
8950  Revision 1.30  2002/03/02 22:00:14  hal9
8951  Updated 'New Features' list. Ran through spell-checker.
8952
8953  Revision 1.29  2002/03/02 20:34:07  david__schmidt
8954  Update OS/2 build section
8955
8956  Revision 1.28  2002/02/24 14:34:24  jongfoster
8957  Formatting changes.  Now changing the doctype to DocBook XML 4.1
8958  will work - no other changes are needed.
8959
8960  Revision 1.27  2002/01/11 14:14:32  hal9
8961  Added a very short section on Templates
8962
8963  Revision 1.26  2002/01/09 20:02:50  hal9
8964  Fix bug re: auto-detect config file changes.
8965
8966  Revision 1.25  2002/01/09 18:20:30  hal9
8967  Touch ups for *.action files.
8968
8969  Revision 1.24  2001/12/02 01:13:42  hal9
8970  Fix typo.
8971
8972  Revision 1.23  2001/12/02 00:20:41  hal9
8973  Updates for recent changes.
8974
8975  Revision 1.22  2001/11/05 23:57:51  hal9
8976  Minor update for startup now daemon mode.
8977
8978  Revision 1.21  2001/10/31 21:11:03  hal9
8979  Correct 2 minor errors
8980
8981  Revision 1.18  2001/10/24 18:45:26  hal9
8982  *** empty log message ***
8983
8984  Revision 1.17  2001/10/24 17:10:55  hal9
8985  Catching up with Jon's recent work, and a few other things.
8986
8987  Revision 1.16  2001/10/21 17:19:21  swa
8988  wrong url in documentation
8989
8990  Revision 1.15  2001/10/14 23:46:24  hal9
8991  Various minor changes. Fleshed out SEE ALSO section.
8992
8993  Revision 1.13  2001/10/10 17:28:33  hal9
8994  Very minor changes.
8995
8996  Revision 1.12  2001/09/28 02:57:04  hal9
8997  Ditto :/
8998
8999  Revision 1.11  2001/09/28 02:25:20  hal9
9000  Ditto.
9001
9002  Revision 1.9  2001/09/27 23:50:29  hal9
9003  A few changes. A short section on regular expression in appendix.
9004
9005  Revision 1.8  2001/09/25 00:34:59  hal9
9006  Some additions, and re-arranging.
9007
9008  Revision 1.7  2001/09/24 14:31:36  hal9
9009  Diddling.
9010
9011  Revision 1.6  2001/09/24 14:10:32  hal9
9012  Including David's OS/2 installation instructions.
9013
9014  Revision 1.2  2001/09/13 15:27:40  swa
9015  cosmetics
9016
9017  Revision 1.1  2001/09/12 15:36:41  swa
9018  source files for junkbuster documentation
9019
9020  Revision 1.3  2001/09/10 17:43:59  swa
9021  first proposal of a structure.
9022
9023  Revision 1.2  2001/06/13 14:28:31  swa
9024  docs should have an author.
9025
9026  Revision 1.1  2001/06/13 14:20:37  swa
9027  first import of project's documentation for the webserver.
9028
9029  -->
9030
9031 </article>