doc/source/user-manual.sgml

   1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
   2 <!entity % dummy "INCLUDE">
   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 p-version "2.9.14">
  12 <!entity p-status "beta">
  13 <!entity % p-not-stable "INCLUDE">
  14 <!entity % p-stable "IGNORE">
  15 <!entity % p-text "IGNORE">        <!-- define we are not a text only doc -->
  16 <!entity % p-doc "INCLUDE">        <!-- and we are a formal doc           -->
  17 <!entity % p-readme "IGNORE">
  18 <!entity % p-config "IGNORE">
  19 <!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml    -->
  20 ]>
  21 <!--
  22  File        :  $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
  23
  24  Purpose     :  user manual
  25                 This file belongs into
  26                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
  27
  28  $Id: user-manual.sgml,v 1.88 2002/04/23 05:37:54 hal9 Exp $
  29
  30  Written by and Copyright (C) 2001 the SourceForge
  31  Privoxy team. http://www.privoxy.org/
  32
  33  Based on the Internet Junkbuster originally written
  34  by and Copyright (C) 1997 Anonymous Coders and
  35  Junkbusters Corporation.  http://www.junkbusters.com
  36
  37
  38  ========================================================================
  39  NOTE: Please read developer-manual/documentation.html before touching
  40  anything in this, or other Privoxy documentation.
  41  ========================================================================
  42
  43 -->
  44
  45 <article id="index">
  46 <artheader>
  47 <title>Privoxy User Manual</title>
  48
  49 <pubdate>$Id: user-manual.sgml,v 1.88 2002/04/23 05:37:54 hal9 Exp $</pubdate>
  50
  51 <authorgroup>
  52  <author>
  53   <affiliation>
  54    <orgname>By: Privoxy Developers</orgname>
  55    </affiliation>
  56  </author>
  57 </authorgroup>
  58
  59 <abstract>
  60 <![%dummy;[
  61  <para>
  62  <comment>
  63   This is here to keep vim syntax file from breaking :/
  64   If I knew enough to fix it, I would.
  65   PLEASE DO NOT REMOVE! HB: hal@foobox.net
  66  </comment>
  67  </para>
  68 ]]>
  69
  70  <para>
  71   The user manual gives users information on how to install, configure and use
  72   <ulink
  73   url="http://www.privoxy.org/"><application>Privoxy</application></ulink>.
  74   </para>
  75
  76 <!-- Include privoxy.sgml boilerplate: -->
  77  &p-intro;
  78 <!-- end privoxy.sgml -->
  79
  80  <para>
  81   You can find the latest version of the user manual at  <ulink
  82   url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
  83   Please see the <ulink url="contact.html">Contact section</ulink> on how to
  84   contact the developers.
  85   </para>
  86
  87 <!--   <para> -->
  88 <!--    Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
  89 <!--   </para> -->
  90 </abstract>
  91
  92 </artheader>
  93
  94 <!--   ~~~~~       New section      ~~~~~     -->
  95 <sect1 id="intro" label=""><title></title>
  96 <!-- dummy section to force TOC on page by itself -->
  97 <!-- DO NOT REMOVE! please ;) -->
  98 <para> </para>
  99 </sect1>
 100
 101 <!--   ~~~~~       New section      ~~~~~     -->
 102
 103 <sect1 label="1" id="introduction"><title>Introduction</title>
 104 <para>
 105  This documentation is included with the current &p-status; version of
 106  <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[,
 107  and is mostly complete at this point. The most up to date reference for the
 108  time being is still the comments in the source files and in the individual
 109  configuration files. Development of version 3.0 is currently nearing
 110  completion, and includes many significant changes and enhancements over
 111  earlier versions. The target release date for
 112  stable v3.0 is <quote>soon</quote> ;-)]]>.
 113 </para>
 114
 115 <!-- include only in non-stable versions -->
 116 <![%p-not-stable;[
 117 <para>
 118  Since this is a &p-status; version, not all new features are well tested. This
 119  documentation may be slightly out of sync as a result (especially with
 120  CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
 121  not many!
 122 </para>
 123 ]]>
 124
 125 <!--   ~~~~~       New section      ~~~~~     -->
 126 <sect2 id="newfeatures">
 127 <title>New Features</title>
 128 <para>
 129  In addition to <application>Internet Junkbuster's</application> traditional
 130  features of ad and banner blocking and cookie management,
 131  <application>Privoxy</application> provides new features<![%p-not-stable;[,
 132  some of them currently under development]]>:
 133 </para>
 134
 135 <!-- Include newfeatures.sgml boilerplate here: -->
 136  &newfeatures;
 137 <!-- end boilerplate -->
 138 </sect2>
 139
 140 </sect1>
 141
 142 <!--  ~  End section  ~  -->
 143
 144
 145 <!--   ~~~~~       New section      ~~~~~     -->
 146 <sect1 id="installation"><title>Installation</title>
 147
 148 <para>
 149  <application>Privoxy</application> is available both in convenient pre-compiled
 150  packages for a wide range of operating systems, and as raw source code.
 151  For most users, we recommend using the packages, which can be downloaded from our
 152  <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink>.
 153 </para>
 154
 155 <para>
 156  If you like to live on the bleeding edge and are not afraid of using
 157  possibly unstable development versions, you can check out the up-to-the-minute
 158  version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
 159  CVS repository</ulink> or simply download <ulink
 160  url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">the nightly CVS
 161  tarball.</ulink>
 162 </para>
 163
 164 <!-- Include supported.sgml boilerplate -->
 165  &supported;
 166 <!-- end boilerplate -->
 167
 168 <!--   ~~~~~       New section      ~~~~~     -->
 169 <sect2 id="installation-packages"><title>Binary Packages</title>
 170
 171 <para>
 172  Note: If you have a previous <application>Junkbuster</application> or
 173  <application>Privoxy</application> installation on your system, you
 174  will need to remove it.  Some platforms do this for you as part
 175  of their installation procedure. (See below for your platform).
 176 </para>
 177
 178 <para>
 179  In any case <emphasis>be sure to backup your old configuration
 180  if it is valuable to you.</emphasis> See the
 181  <link linkend="upgradersnote">note to upgraders</link>.
 182 </para>
 183
 184 <para>
 185  How to install the binary packages depends on your operating system:
 186 </para>
 187
 188 <!--   ~~~~~       New section      ~~~~~     -->
 189 <sect3 id="installation-pack-rpm"><title>Red Hat and SuSE RPMs</title>
 190
 191 <para>
 192  RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
 193  and will use <filename>/etc/privoxy</filename> for the location
 194  of configuration files.
 195 </para>
 196
 197 <para>
 198  Note that on Red Hat, Privoxy will not be automatically started on system
 199  boot. You will need to enable that using linuxconf.
 200 </para>
 201
 202 <para>
 203  If you have problems with failed dependencies, try rebuilding the SRC RPM:
 204  <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm;</literal>. This
 205  will use your locally installed libraries and RPM version.
 206 </para>
 207
 208 <para>
 209  Also note that if you have a <application>Junkbuster</application> RPM installed
 210  on your system, you need to remove it first, because the packages conflict.
 211  Otherwise, RPM will try to remove <application>Junkbuster</application>
 212  automatically, before installing <application>Privoxy</application>.
 213 </para>
 214 </sect3>
 215
 216 <!--   ~~~~~       New section      ~~~~~     -->
 217 <sect3 id="installation-deb"><title>Debian</title>
 218 <para>
 219  FIXME.
 220 </para>
 221 </sect3>
 222
 223 <!--   ~~~~~       New section      ~~~~~     -->
 224 <sect3 id="installation-pack-win"><title>Windows</title>
 225
 226 <para>
 227  Just double-click the installer, which will guide you through
 228  the installation process.
 229 </para>
 230 </sect3>
 231
 232 <!--   ~~~~~       New section      ~~~~~     -->
 233 <sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, FreeBSD, HP-UX</title>
 234
 235 <para>
 236  Create a new directory, <literal>cd</literal> to it, then unzip and
 237  untar the archive. For the most part, you'll have to figure out where
 238  things go. FIXME.
 239 </para>
 240 </sect3>
 241
 242 <!--   ~~~~~       New section      ~~~~~     -->
 243 <sect3 id="installation-os2"><title>OS/2</title>
 244
 245 <para>
 246  First, make sure that no previous installations of
 247  <application>Junkbuster</application> and / or
 248  <application>Privoxy</application> are left on your
 249  system. You can do this by
 250 </para>
 251
 252 <para>
 253  Then, just double-click the WarpIN self-installing archive, which will
 254  guide you through the installation process. A shadow of the
 255  <application>Privoxy</application> executable will be placed in your
 256  startup folder so it will start automatically whenever OS/2 starts.
 257 </para>
 258
 259 <para>
 260  The directory you choose to install <application>Privoxy</application>
 261  into will contain all of the configuration files.
 262 </para>
 263 </sect3>
 264
 265 <!--   ~~~~~       New section      ~~~~~     -->
 266 <sect3 id="installation-mac"><title>Max OSX</title>
 267 <para>
 268  Unzip the downloaded package (you can either double-click on the file
 269  in the finder, or on the desktop if you downloaded it there).  Then,
 270  double-click on the package installer icon and follow the installation
 271  process.
 272  <application>Privoxy</application> will be installed in the subdirectory
 273  <literal>/Applications/Privoxy.app</literal>.
 274  <application>Privoxy</application> will set itself up to start
 275  automatically on system bringup via
 276  <literal>/System/Library/StartupItems/Privoxy</literal>.
 277 </para>
 278 </sect3>
 279
 280 <!--   ~~~~~       New section      ~~~~~     -->
 281 <sect3 id="installation-amiga"><title>AmigaOS</title>
 282 <para>
 283  Copy and then unpack the <filename>lha</filename> archive to a suitable location.
 284  All necessary files will be installed into <application>Privoxy</application>
 285  directory, including all configuration and log files. To uninstall, just
 286  remove this directory.
 287 </para>
 288 <para>
 289  Start <application>Privoxy</application> (with RUN &lt;&gt;NIL:) in your
 290  <filename>startnet</filename> script (AmiTCP), in
 291  <filename>s:user-startup</filename> (RoadShow), as startup program in your
 292  startup script (Genesis), or as startup action (Miami and MiamiDx).
 293  <application>Privoxy</application> will automatically quit when you quit your
 294  TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
 295  <application>Privoxy</application> is still running).
 296 </para>
 297 </sect3>
 298 </sect2>
 299
 300 <!--   ~~~~~       New section      ~~~~~     -->
 301 <sect2 id="installation-source"><title>Building from Source</title>
 302
 303 <!-- include buildsource.sgml boilerplate: -->
 304 &buildsource;
 305 <!-- end boilerplate -->
 306 </sect2>
 307
 308 </sect1>
 309
 310 <!--  ~  End section  ~  -->
 311
 312
 313 <!--   ~~~~~       New section      ~~~~~     -->
 314
 315 <sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
 316
 317
 318 <!--   ~~~~~       New section      ~~~~~     -->
 319 <sect2 id="upgradersnote">
 320 <title>Note to Upgraders</title>
 321 <para>
 322  There are very significant changes from older versions of
 323  <application>Junkbuster</application> to the current
 324  <application>Privoxy</application>. Configuration is substantially
 325  changed. <application>Junkbuster 2.0.x</application> and earlier
 326  configuration files will not migrate. The functionality of the old
 327  <filename>blockfile</filename>, <filename>cookiefile</filename> and
 328  <filename>imagelist</filename>, are now combined into the
 329  <quote>actions file</quote>  (<filename>default.action</filename>
 330  for most installations).
 331 </para>
 332 <para>
 333  A <quote>filter file</quote> (typically <filename>default.filter</filename>)
 334  is new as of <application>Privoxy 2.9.x</application>, and provides some
 335  of the new sophistication (explained below). <filename>config</filename> is
 336  much the same as before.
 337 </para>
 338 <para>
 339  If upgrading from a 2.0.x version, you will have to use the new config
 340  files, and possibly adapt any personal rules from your older files.
 341  When porting personal rules over from the old <filename>blockfile</filename>
 342  to the new actions file, please note that even the pattern syntax has
 343  changed. If upgrading from 2.9.x development versions, it is still
 344  recommended to use the new configuration files.
 345 </para>
 346 <para>
 347  A quick list of things to be aware of before upgrading:
 348 </para>
 349
 350 <para>
 351  <itemizedlist>
 352
 353  <listitem>
 354   <para>
 355    The default listening port is now 8118 due to a conflict with another
 356    service (NAS).
 357   </para>
 358  </listitem>
 359  <listitem>
 360   <para>
 361     Some installers may remove earlier versions completely. Save any
 362     important configuration files!
 363   </para>
 364  </listitem>
 365  <listitem>
 366   <para>
 367    <application>Privoxy</application> is controllable with a web browser
 368    at the special URL: <ulink
 369    url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
 370    (Shortcut: <ulink url="http://p.p/">http://p.p/</ulink>). Many
 371    aspects of configuration can be done here, including temporarily disabling
 372    <application>Privoxy</application>.
 373   </para>
 374  </listitem>
 375  <listitem>
 376   <para>
 377    The primary configuration file for cookie management, ad and banner
 378    blocking, and many other aspects of <application>Privoxy</application>
 379    configuration is <filename>default.action</filename>. It is strongly
 380    recommended to become familiar with the new actions concept below,
 381    before modifying this file.
 382   </para>
 383  </listitem>
 384   <listitem>
 385   <para>
 386 <!-- I think it is best to keep this somewhat vague, in case  -->
 387 <!-- the situation changes under our feet. -->
 388    Some installers may not automatically start
 389    <application>Privoxy</application> after installation.
 390   </para>
 391  </listitem>
 392
 393  </itemizedlist>
 394 </para>
 395
 396 </sect2>
 397
 398 <!--   ~~~~~       New section      ~~~~~     -->
 399 <sect2 id="startup">
 400 <title>Starting <application>Privoxy</application></title>
 401 <para>
 402  Before launching <application>Privoxy</application> for the first time, you
 403  will want to configure your browser(s) to use <application>Privoxy</application>
 404  as a HTTP and HTTPS proxy. The default is localhost for the proxy address,
 405  and port 8118 (earlier versions used port 8000). This is the one
 406  configuration step that must be done!
 407 </para>
 408
 409 <para>
 410  With <application>Netscape</application> (and
 411  <application>Mozilla</application>), this can be set under <literal>Edit
 412  -&gt; Preferences -&gt; Advanced -&gt; Proxies -&gt; HTTP Proxy</literal>.
 413  For <application>Internet Explorer</application>: <literal>Tools -&gt;
 414  Internet Properties -&gt; Connections -&gt; LAN Setting</literal>. Then,
 415  check <quote>Use Proxy</quote> and fill in the appropriate info (Address:
 416  localhost, Port: 8118). Include if HTTPS proxy support too.
 417 </para>
 418
 419 <para>
 420  After doing this, flush your browser's disk and memory caches to force a
 421  re-reading of all pages and to get rid of any ads that may be cached. You
 422  are now ready to start enjoying the benefits of using
 423  <application>Privoxy</application>!
 424 </para>
 425
 426
 427 <para>
 428  <application>Privoxy</application> is typically started by specifying the
 429  main configuration file to be used on the command line. Example Unix startup
 430  command:
 431 </para>
 432
 433 <para>
 434  <screen>
 435
 436  # /usr/sbin/privoxy /etc/privoxy/config
 437
 438  </screen>
 439 </para>
 440
 441 <para>
 442  See <link linkend="cmdoptions">below</link> for other command line options.
 443 </para>
 444
 445 <para>
 446  An init script is provided for SuSE and Red Hat.
 447 </para>
 448
 449 <para>
 450  For for SuSE: <command>rcprivoxy start</command>
 451 </para>
 452
 453 <para>
 454  For Red Hat and Debian: <command>/etc/rc.d/init.d/privoxy start</command>
 455 </para>
 456
 457
 458 <para>
 459  If no configuration file is specified on the command line,
 460  <application>Privoxy</application> will look for a file named
 461  <filename>config</filename> in the current directory. Except on Win32 where
 462  it will try <filename>config.txt</filename>. If no file is specified on the
 463  command line and no default configuration file can be found,
 464  <application>Privoxy</application> will fail to start.
 465 </para>
 466
 467
 468 <para>
 469  The included default configuration files should give a reasonable starting
 470  point. Most of the per site configuration is done in the
 471  <quote>actions</quote> files. These are where various cookie actions are
 472  defined, ad and banner blocking, and other aspects of
 473  <application>Privoxy</application> configuration. There are several such
 474  files included, with varying levels of aggressiveness.
 475 </para>
 476
 477 <para>
 478  You will probably want to keep an eye out for sites that require persistent
 479  cookies, and add these to <filename>default.action</filename> as needed. By
 480  default, most of these will be accepted only during the current browser
 481  session (aka <quote>session cookies</quote>), until you add them to the
 482  configuration. If you want the browser to handle this instead, you will need
 483  to edit <filename>default.action</filename> and disable this feature. If you
 484  use more than one browser, it would make more sense to let
 485  <application>Privoxy</application> handle this. In which case, the
 486  browser(s) should be set to accept all cookies.
 487 </para>
 488
 489 <para>
 490  Another feature where you will probably want to define exceptions for trusted
 491  sites is the popup-killing (through the <literal>+popup</literal> and
 492  <literal>+filter{popups}</literal> actions), because your favorite shopping,
 493  banking, or leisure site may need popups.
 494 </para>
 495
 496 <para>
 497  <application>Privoxy</application> is HTTP/1.1 compliant,  but not all of
 498  the optional 1.1 features are as yet supported. In the unlikely event that
 499  you experience inexplicable problems with browsers that use HTTP/1.1 per default
 500  (like <application>Mozilla</application> or recent versions of I.E.), you might
 501  try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit -&gt;
 502  Preferences -&gt; Debug -&gt; Networking</literal>.
 503  Alternatively, set the <quote>+downgrade</quote> config option in
 504  <filename>default.action</filename> which will downgrade your browser's HTTP
 505  requests from HTTP/1.1 to HTTP/1.0 before processing them.
 506 </para>
 507
 508 <para>
 509  After running <application>Privoxy</application> for a while, you can
 510  start to fine tune the configuration to suit your personal, or site,
 511  preferences and requirements. There are many, many aspects that can
 512  be customized. <quote>Actions</quote> (as specified in <filename>default.action</filename>)
 513  can be adjusted by pointing your browser to
 514  <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
 515  (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
 516  and then follow the link to <quote>edit the actions list</quote>.
 517  (This is an internal page and does not require Internet access.)
 518 </para>
 519
 520 <para>
 521  In fact, various aspects of <application>Privoxy</application>
 522  configuration can be viewed from this page, including
 523  current configuration parameters, source code version numbers,
 524  the browser's request headers, and <quote>actions</quote> that apply
 525  to a given URL. In addition to the <filename>default.action</filename> file
 526  editor mentioned above, <application>Privoxy</application> can also
 527  be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
 528 </para>
 529
 530 <para>
 531  If you encounter problems, try loading the page without
 532  <application>Privoxy</application>. If that helps, enter the URL where
 533  you have the problems into <ulink url="http://p.p/show-url-info">the browser
 534  based rule tracing utility</ulink>. See which rules apply and why, and
 535  then try turning them off for that site one after the other, until the problem
 536  is gone. When you have found the culprit, you might want to turn the rest on
 537  again.
 538 </para>
 539
 540 <para>
 541  If the above paragraph sounds gibberish to you, you might want to <ulink
 542  url="configuration.html#ACTIONSFILE">read more about the actions concept</ulink>
 543  or even dive deep into the <ulink url="appendix.html#ACTIONSANAT">Appendix
 544  on actions</ulink>.
 545 </para>
 546
 547 <para>
 548  If you can't get rid of the problem at all, think you've found a bug in
 549  Privoxy, want to propose a new feature or smarter rules, please see the
 550  chapter "Contacting the Developers, .." below.
 551 </para>
 552
 553 </sect2>
 554
 555
 556 <!--   ~~~~~       New section      ~~~~~     -->
 557 <sect2 id="cmdoptions">
 558 <title>Command Line Options</title>
 559 <para>
 560  <application>Privoxy</application> may be invoked with the following
 561  command-line options:
 562 </para>
 563
 564 <para>
 565  <itemizedlist>
 566
 567  <listitem>
 568   <para>
 569     <emphasis>--version</emphasis>
 570   </para>
 571   <para>
 572      Print version info and exit. Unix only.
 573   </para>
 574  </listitem>
 575  <listitem>
 576   <para>
 577     <emphasis>--help</emphasis>
 578   </para>
 579   <para>
 580    Print short usage info and exit. Unix only.
 581   </para>
 582  </listitem>
 583  <listitem>
 584   <para>
 585    <emphasis>--no-daemon</emphasis>
 586   </para>
 587   <para>
 588    Don't become a daemon, i.e. don't fork and become process group
 589    leader, and don't detach from controlling tty. Unix only.
 590   </para>
 591  </listitem>
 592  <listitem>
 593   <para>
 594    <emphasis>--pidfile FILE</emphasis>
 595
 596   </para>
 597   <para>
 598    On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
 599    <emphasis>FILE</emphasis> on exit. Failure to create or delete the
 600    <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
 601    option is given, no PID file will be used. Unix only.
 602   </para>
 603  </listitem>
 604  <listitem>
 605   <para>
 606    <emphasis>--user USER[.GROUP]</emphasis>
 607
 608   </para>
 609   <para>
 610    After (optionally) writing the PID file, assume the user  ID  of
 611    <emphasis>USER</emphasis>, and if included the GID of GROUP.  Exit if the
 612    privileges are not sufficient to do so. Unix only.
 613   </para>
 614  </listitem>
 615  <listitem>
 616   <para>
 617     <emphasis>configfile</emphasis>
 618   </para>
 619   <para>
 620     If no <emphasis>configfile</emphasis> is included on the command line,
 621     <application>Privoxy</application> will look for a file named
 622     <quote>config</quote> in the current directory (except on Win32
 623     where it will look for <quote>config.txt</quote> instead). Specify
 624     full path to avoid confusion. If no config file is found,
 625     <application>Privoxy</application> will fail to start.
 626   </para>
 627  </listitem>
 628
 629  </itemizedlist>
 630 </para>
 631
 632 </sect2>
 633
 634 </sect1>
 635
 636 <!--  ~  End section  ~  -->
 637
 638
 639 <!--   ~~~~~       New section      ~~~~~     -->
 640 <sect1 id="configuration"><title><application>Privoxy</application> Configuration</title>
 641  <para>
 642   All <application>Privoxy</application> configuration is stored
 643   in text files. These files can be edited with a text editor.
 644   Many important aspects of <application>Privoxy</application> can
 645   also be controlled easily with a web browser.
 646
 647  </para>
 648
 649
 650 <!--   ~~~~~       New section      ~~~~~     -->
 651
 652 <sect2>
 653 <title>Controlling <application>Privoxy</application> with Your Web Browser</title>
 654 <para>
 655  <application>Privoxy</application>'s user interface can be reached through the special
 656  URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
 657  (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
 658  which is a built-in page and works without Internet access.
 659  You will see the following section:
 660
 661 </para>
 662
 663 <para>
 664  <screen>
 665
 666 Please choose from the following options:
 667
 668     * Privoxy main page
 669     * Show information about the current configuration
 670     * Show the source code version numbers
 671     * Show the request headers.
 672     * Show which actions apply to a URL and why
 673     * Toggle Privoxy on or off
 674     * Edit the actions list
 675
 676  </screen>
 677 </para>
 678
 679 <para>
 680  This should be self-explanatory. Note the last item is an editor for the
 681  <quote>actions list</quote>, which is where much of the ad, banner, cookie,
 682  and URL blocking magic is configured as well as other advanced features of
 683  <application>Privoxy</application>. This is an easy way to adjust various
 684  aspects of <application>Privoxy</application> configuration. The actions
 685  file, and other configuration files, are explained in detail below.
 686 </para>
 687
 688 <para>
 689  <quote>Toggle Privoxy On or Off</quote> is handy for sites that might
 690  have problems with your current actions and filters. You can in fact use
 691  it as a test to see whether it is <application>Privoxy</application>
 692  causing the problem or not. <application>Privoxy</application> continues
 693  to run as a proxy in this case, but all filtering is disabled. There
 694  is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
 695  that you can toggle <application>Privoxy</application> with one click from
 696  your browser.
 697 </para>
 698
 699 </sect2>
 700
 701 <!--  ~  End section  ~  -->
 702
 703
 704
 705
 706 <!--   ~~~~~       New section      ~~~~~     -->
 707
 708 <sect2>
 709 <title>Configuration Files Overview</title>
 710 <para>
 711  For Unix, *BSD and Linux, all configuration files are located in
 712  <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
 713  AmigaOS these are all in the same directory as the
 714  <application>Privoxy</application> executable. <![%p-not-stable;[ The name
 715  and number of configuration files has changed from previous versions, and is
 716  subject to change as development progresses.]]>
 717 </para>
 718
 719 <para>
 720  The installed defaults provide a reasonable starting point, though possibly
 721  aggressive by some standards. For the time being, there are only three
 722  default configuration files (this may change in time):
 723 </para>
 724
 725 <para>
 726  <itemizedlist>
 727
 728   <listitem>
 729    <para>
 730      The main configuration file is named <filename>config</filename>
 731      on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
 732      on Windows.
 733    </para>
 734   </listitem>
 735
 736   <listitem>
 737    <para>
 738     <filename>default.action</filename> (the actions file) is used to define
 739     which of a set of various <quote>actions</quote> relating to images, banners,
 740     pop-ups, access restrictions, banners and cookies are to be applied, and where.
 741     There is a web based editor for this file that can be accessed at <ulink
 742     url="http://config.privoxy.org/edit-actions/">http://config.privoxy.org/edit-actions/</ulink>
 743     (Shortcut: <ulink url="http://p.p/edit-actions/">http://p.p/edit-actions/</ulink>).
 744     (Other actions files are included as well with differing levels of filtering
 745     and blocking, e.g. <filename>basic.action</filename>.)
 746    </para>
 747   </listitem>
 748
 749   <listitem>
 750    <para>
 751     <filename>default.filter</filename> (the filter file) can be used to re-write the raw
 752     page content, including viewable text as well as embedded HTML and JavaScript,
 753     and whatever else lurks on any given web page. The filtering jobs are only
 754     pre-defined here; whether to apply them or not is up to the actions file.
 755    </para>
 756   </listitem>
 757
 758  </itemizedlist>
 759 </para>
 760
 761 <para>
 762  All files use the <quote><literal>#</literal></quote> character to denote a
 763  comment (the rest of the line will be ignored) and understand line continuation
 764  through placing a backslash ("<literal>\</literal>") as the very last character
 765  in a line. If the <literal>#</literal> is preceded by a backslash, it looses
 766  its special function. Placing a <literal>#</literal> in front of an otherwise
 767  valid configuration line to prevent it from being interpreted is called "commenting
 768  out" that line.
 769 </para>
 770
 771 <para>
 772  <filename>default.action</filename> and <filename>default.filter</filename>
 773  can use Perl style <link linkend="regex">regular expressions</link> for
 774  maximum flexibility.
 775 </para>
 776
 777 <para>
 778  After making any changes, there is no need to restart
 779  <application>Privoxy</application> in order for the changes to take
 780  effect. <application>Privoxy</application> detects such changes
 781  automatically. Note, however, that it may take one or two additional
 782  requests for the change to take effect. When changing the listening address
 783  of <application>Privoxy</application>, these <quote>wake up</quote> requests
 784  must obviously be sent to the <emphasis>old</emphasis> listening address.
 785 </para>
 786
 787 <![%p-not-stable;[
 788 <para>
 789  While under development, the configuration content is subject to change.
 790  The below documentation may not be accurate by the time you read this.
 791  Also, what constitutes a <quote>default</quote> setting, may change, so
 792  please check all your configuration files on important issues.
 793 </para>
 794 ]]>
 795 </sect2>
 796
 797
 798 <!--   ~~~~~       New section      ~~~~~     -->
 799
 800 <sect2>
 801 <title>The Main Configuration File</title>
 802 <para>
 803  Again, the main configuration file is named <filename>config</filename> on
 804  Linux/Unix/BSD and OS/2, and <filename>config.txt</filename> on Windows.
 805  Configuration lines consist of an initial keyword followed by a list of
 806  values, all separated by whitespace (any number of spaces or tabs). For
 807  example:
 808 </para>
 809
 810 <para>
 811  <literal>
 812   <msgtext>
 813    <literallayout>
 814   <emphasis>confdir /etc/privoxy</emphasis>
 815    </literallayout>
 816   </msgtext>
 817  </literal>
 818 </para>
 819
 820 <para>
 821  Assigns the value <literal>/etc/privoxy</literal> to the option
 822  <literal>confdir</literal> and thus indicates that the configuration
 823  directory is named <quote>/etc/privoxy/</quote>.
 824 </para>
 825
 826 <para>
 827  All options in the config file except for <literal>confdir</literal> and
 828  <literal>logdir</literal> are optional. Watch out in the below description
 829  for what happens if you leave them unset.
 830 </para>
 831
 832 <para>
 833  The main config file controls all aspects of <application>Privoxy</application>'s
 834  operation that are not location dependent (i.e. they apply universally, no matter
 835  where you may be surfing).
 836 </para>
 837
 838
 839 <!--   ~~~~~       New section      ~~~~~     -->
 840
 841 <sect3>
 842 <title>Configuration and Log File Locations</title>
 843
 844 <para>
 845  <application>Privoxy</application> can (and normally does) use a number of
 846  other files for additional configuration and logging.
 847  This section of the configuration file tells <application>Privoxy</application>
 848  where to find those other files.
 849 </para>
 850
 851
 852 <sect4><title>confdir</title>
 853
 854 <variablelist>
 855  <varlistentry>
 856   <term>Specifies:</term>
 857   <listitem>
 858    <para>The directory where the other configuration files are located</para>
 859   </listitem>
 860  </varlistentry>
 861  <varlistentry>
 862   <term>Type of value:</term>
 863   <listitem>
 864    <para>Path name</para>
 865   </listitem>
 866  </varlistentry>
 867  <varlistentry>
 868   <term>Default value:</term>
 869   <listitem>
 870    <para>/etc/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
 871   </listitem>
 872  </varlistentry>
 873  <varlistentry>
 874   <term>Effect if unset:</term>
 875   <listitem>
 876    <para><emphasis>Mandatory</emphasis></para>
 877   </listitem>
 878  </varlistentry>
 879  <varlistentry>
 880   <term>Notes:</term>
 881   <listitem>
 882    <para>
 883     No trailing <quote><literal>/</literal></quote>, please
 884    </para>
 885    <para>
 886     When development goes modular and multi-user, the blocker, filter, and
 887     per-user config will be stored in subdirectories of <quote>confdir</quote>.
 888     For now, the configuration directory structure is flat, except for
 889     <filename>confdir/templates</filename>, where the HTML templates for CGI
 890     output reside (e.g. <application>Privoxy's</application> 404 error page).
 891    </para>
 892   </listitem>
 893  </varlistentry>
 894 </variablelist>
 895 </sect4>
 896
 897
 898 <sect4><title>logdir</title>
 899
 900 <variablelist>
 901  <varlistentry>
 902   <term>Specifies:</term>
 903   <listitem>
 904    <para>
 905     The directory where all logging takes place (i.e. where <filename>logfile</filename> and
 906     <filename>jarfile</filename> are located)
 907    </para>
 908   </listitem>
 909  </varlistentry>
 910  <varlistentry>
 911   <term>Type of value:</term>
 912   <listitem>
 913    <para>Path name</para>
 914   </listitem>
 915  </varlistentry>
 916  <varlistentry>
 917   <term>Default value:</term>
 918   <listitem>
 919    <para>/var/log/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
 920   </listitem>
 921  </varlistentry>
 922  <varlistentry>
 923   <term>Effect if unset:</term>
 924   <listitem>
 925    <para><emphasis>Mandatory</emphasis></para>
 926   </listitem>
 927  </varlistentry>
 928  <varlistentry>
 929   <term>Notes:</term>
 930   <listitem>
 931    <para>
 932     No trailing <quote><literal>/</literal></quote>, please
 933    </para>
 934   </listitem>
 935  </varlistentry>
 936 </variablelist>
 937 </sect4>
 938
 939 <sect4><title>actionsfile</title>
 940
 941 <variablelist>
 942  <varlistentry>
 943   <term>Specifies:</term>
 944   <listitem>
 945    <para>
 946     The actions file to use
 947    </para>
 948   </listitem>
 949  </varlistentry>
 950  <varlistentry>
 951   <term>Type of value:</term>
 952   <listitem>
 953    <para>File name, relative to <literal>confdir</literal></para>
 954   </listitem>
 955  </varlistentry>
 956  <varlistentry>
 957   <term>Default value:</term>
 958   <listitem>
 959    <para>default.action (Unix) <emphasis>or</emphasis> default.action.txt (Windows)</para>
 960   </listitem>
 961  </varlistentry>
 962  <varlistentry>
 963   <term>Effect if unset:</term>
 964   <listitem>
 965    <para>
 966     No action is taken at all. Simple neutral proxying.
 967    </para>
 968   </listitem>
 969  </varlistentry>
 970  <varlistentry>
 971   <term>Notes:</term>
 972   <listitem>
 973    <para>
 974     There is no point in using <application>Privoxy</application> without
 975     an actions file. There are three different actions files included in the
 976     distribution, with varying degrees of aggressiveness:
 977     <filename>default.action</filename>, <filename>intermediate.action</filename> and
 978     <filename>advanced.action</filename>.
 979    </para>
 980   </listitem>
 981  </varlistentry>
 982 </variablelist>
 983 </sect4>
 984
 985 <sect4><title>filterfile</title>
 986
 987 <variablelist>
 988  <varlistentry>
 989   <term>Specifies:</term>
 990   <listitem>
 991    <para>
 992     The filter file to use
 993    </para>
 994   </listitem>
 995  </varlistentry>
 996  <varlistentry>
 997   <term>Type of value:</term>
 998   <listitem>
 999    <para>File name, relative to <literal>confdir</literal></para>
1000   </listitem>
1001  </varlistentry>
1002  <varlistentry>
1003   <term>Default value:</term>
1004   <listitem>
1005    <para>default.filter (Unix) <emphasis>or</emphasis> default.filter.txt (Windows)</para>
1006   </listitem>
1007  </varlistentry>
1008  <varlistentry>
1009   <term>Effect if unset:</term>
1010   <listitem>
1011    <para>
1012     No textual content filtering takes place, i.e. all
1013     <literal>+filter{<replaceable class="parameter">name</replaceable>}</literal>
1014     actions in the actions file are turned off
1015    </para>
1016   </listitem>
1017  </varlistentry>
1018  <varlistentry>
1019   <term>Notes:</term>
1020   <listitem>
1021    <para>
1022     The <quote>default.filter</quote> file contains content modification rules
1023     that use <quote>regular expressions</quote>. These rules permit powerful
1024     changes on the content of Web pages, e.g., you could disable your favorite
1025     JavaScript annoyances, re-write the actual displayed text, or just have some
1026     fun replacing <quote>Microsoft</quote> with <quote>MicroSuck</quote> wherever
1027     it appears on a Web page.
1028    </para>
1029   </listitem>
1030  </varlistentry>
1031 </variablelist>
1032 </sect4>
1033
1034 <sect4><title>logfile</title>
1035
1036 <variablelist>
1037  <varlistentry>
1038   <term>Specifies:</term>
1039   <listitem>
1040    <para>
1041     The log file to use
1042    </para>
1043   </listitem>
1044  </varlistentry>
1045  <varlistentry>
1046   <term>Type of value:</term>
1047   <listitem>
1048    <para>File name, relative to <literal>logdir</literal></para>
1049   </listitem>
1050  </varlistentry>
1051  <varlistentry>
1052   <term>Default value:</term>
1053   <listitem>
1054    <para>logfile (Unix) <emphasis>or</emphasis> privoxy.log (Windows)</para>
1055   </listitem>
1056  </varlistentry>
1057  <varlistentry>
1058   <term>Effect if unset:</term>
1059   <listitem>
1060    <para>
1061     No log file is used, all log messages go to the console (<literal>stderr</literal>).
1062    </para>
1063   </listitem>
1064  </varlistentry>
1065  <varlistentry>
1066   <term>Notes:</term>
1067   <listitem>
1068    <para>
1069     The windows version will additionally log to the console.
1070    </para>
1071    <para>
1072     The logfile is where all logging and error messages are written. The level
1073     of detail and number of messages are set with the <literal>debug</literal>
1074     option (see below). The logfile can be useful for tracking down a problem with
1075     <application>Privoxy</application> (e.g., it's not blocking an ad you
1076     think it should block) but in most cases you probably will never look at it.
1077    </para>
1078    <para>
1079     Your logfile will grow indefinitely, and you will probably want to
1080     periodically remove it.  On Unix systems, you can do this with a cron job
1081     (see <quote>man cron</quote>). For Red Hat, a <command>logrotate</command>
1082     script has been included.
1083    </para>
1084    <para>
1085     On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
1086     +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
1087     the effect that cron.daily will automatically archive, gzip, and empty the
1088     log, when it exceeds 1M size.
1089    </para>
1090   </listitem>
1091  </varlistentry>
1092 </variablelist>
1093 </sect4>
1094
1095 <sect4><title>jarfile</title>
1096
1097 <variablelist>
1098  <varlistentry>
1099   <term>Specifies:</term>
1100   <listitem>
1101    <para>
1102     The file to store intercepted cookies in
1103    </para>
1104   </listitem>
1105  </varlistentry>
1106  <varlistentry>
1107   <term>Type of value:</term>
1108   <listitem>
1109    <para>File name, relative to <literal>logdir</literal></para>
1110   </listitem>
1111  </varlistentry>
1112  <varlistentry>
1113   <term>Default value:</term>
1114   <listitem>
1115    <para>jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</para>
1116   </listitem>
1117  </varlistentry>
1118  <varlistentry>
1119   <term>Effect if unset:</term>
1120   <listitem>
1121    <para>
1122     Intercepted cookies are not stored at all.
1123    </para>
1124   </listitem>
1125  </varlistentry>
1126  <varlistentry>
1127   <term>Notes:</term>
1128   <listitem>
1129    <para>
1130     The jarfile may grow to ridiculous sizes over time.
1131    </para>
1132   </listitem>
1133  </varlistentry>
1134 </variablelist>
1135 </sect4>
1136
1137 <sect4><title>trustfile</title>
1138
1139 <variablelist>
1140  <varlistentry>
1141   <term>Specifies:</term>
1142   <listitem>
1143    <para>
1144     The trust file to use
1145    </para>
1146   </listitem>
1147  </varlistentry>
1148  <varlistentry>
1149   <term>Type of value:</term>
1150   <listitem>
1151    <para>File name, relative to <literal>confdir</literal></para>
1152   </listitem>
1153  </varlistentry>
1154  <varlistentry>
1155   <term>Default value:</term>
1156   <listitem>
1157    <para><emphasis>Unset (commented out)</emphasis>. When activated: trust (Unix) <emphasis>or</emphasis> trust.txt (Windows)</para>
1158   </listitem>
1159  </varlistentry>
1160  <varlistentry>
1161   <term>Effect if unset:</term>
1162   <listitem>
1163    <para>
1164     The whole trust mechanism is turned off.
1165    </para>
1166   </listitem>
1167  </varlistentry>
1168  <varlistentry>
1169   <term>Notes:</term>
1170   <listitem>
1171    <para>
1172     The trust mechanism is an experimental feature for building white-lists and should
1173     be used with care. It is <emphasis>NOT</emphasis> recommended for the casual user.
1174    </para>
1175    <para>
1176     If you specify a trust file, <application>Privoxy</application> will only allow
1177     access to sites that are named in the trustfile.
1178     You can also mark sites as trusted referrers (with <literal>+</literal>), with
1179     the effect that access to untrusted sites will be granted, if a link from a
1180     trusted referrer was used.
1181     The link target will then be added to the <quote>trustfile</quote>.
1182     Possible applications include limiting Internet access for children.
1183    </para>
1184    <para>
1185     If you use <literal>+</literal> operator in the trust file, it may grow considerably over time.
1186    </para>
1187   </listitem>
1188  </varlistentry>
1189 </variablelist>
1190 </sect4>
1191
1192 </sect3>
1193
1194 <!--  ~  End section  ~  -->
1195
1196
1197
1198 <!--   ~~~~~       New section      ~~~~~     -->
1199
1200 <sect3>
1201 <title>Local Set-up Documentation</title>
1202
1203   <para>
1204     If you intend to operate <application>Privoxy</application> for more users
1205     that just yourself, it might be a good idea to let them know how to reach
1206     you, what you block and why you do that, your policies etc.
1207    </para>
1208
1209 <sect4><title>trust-info-url</title>
1210
1211 <variablelist>
1212  <varlistentry>
1213   <term>Specifies:</term>
1214   <listitem>
1215    <para>
1216     A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
1217    </para>
1218   </listitem>
1219  </varlistentry>
1220  <varlistentry>
1221   <term>Type of value:</term>
1222   <listitem>
1223    <para>URL</para>
1224   </listitem>
1225  </varlistentry>
1226  <varlistentry>
1227   <term>Default value:</term>
1228   <listitem>
1229    <para>Two example URL are provided</para>
1230   </listitem>
1231  </varlistentry>
1232  <varlistentry>
1233   <term>Effect if unset:</term>
1234   <listitem>
1235    <para>
1236     No links are displayed on the "untrusted" error page.
1237    </para>
1238   </listitem>
1239  </varlistentry>
1240  <varlistentry>
1241   <term>Notes:</term>
1242   <listitem>
1243    <para>
1244     The value of this option only matters if the experimental trust mechanism has been
1245     activated. (See <literal>trustfile</literal> above.)
1246    </para>
1247    <para>
1248     If you use the trust mechanism, it is a good idea to write up some on-line
1249     documentation about your trust policy and to specify the URL(s) here.
1250     Use multiple times for multiple URLs.
1251    </para>
1252    <para>
1253     The URL(s) should be added to the trustfile as well, so users don't end up
1254     locked out from the information on why they were locked out in the first place!
1255    </para>
1256   </listitem>
1257  </varlistentry>
1258 </variablelist>
1259 </sect4>
1260
1261 <sect4><title>admin-address</title>
1262
1263 <variablelist>
1264  <varlistentry>
1265   <term>Specifies:</term>
1266   <listitem>
1267    <para>
1268     An email address to reach the proxy administrator.
1269    </para>
1270   </listitem>
1271  </varlistentry>
1272  <varlistentry>
1273   <term>Type of value:</term>
1274   <listitem>
1275    <para>Email address</para>
1276   </listitem>
1277  </varlistentry>
1278  <varlistentry>
1279   <term>Default value:</term>
1280   <listitem>
1281    <para><emphasis>Unset</emphasis></para>
1282   </listitem>
1283  </varlistentry>
1284  <varlistentry>
1285   <term>Effect if unset:</term>
1286   <listitem>
1287    <para>
1288     No email address is displayed on error pages and the CGI user interface.
1289    </para>
1290   </listitem>
1291  </varlistentry>
1292  <varlistentry>
1293   <term>Notes:</term>
1294   <listitem>
1295     <para>
1296     If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
1297     are unset, the whole "Local Privoxy Support" box on all generated pages will
1298     not be shown.
1299    </para>
1300   </listitem>
1301  </varlistentry>
1302 </variablelist>
1303 </sect4>
1304
1305 <sect4><title>proxy-info-url</title>
1306
1307 <variablelist>
1308  <varlistentry>
1309   <term>Specifies:</term>
1310   <listitem>
1311    <para>
1312     A URL to documentation about the local <application>Privoxy</application> setup,
1313     configuration or policies.
1314    </para>
1315   </listitem>
1316  </varlistentry>
1317  <varlistentry>
1318   <term>Type of value:</term>
1319   <listitem>
1320    <para>URL</para>
1321   </listitem>
1322  </varlistentry>
1323  <varlistentry>
1324   <term>Default value:</term>
1325   <listitem>
1326    <para><emphasis>Unset</emphasis></para>
1327   </listitem>
1328  </varlistentry>
1329  <varlistentry>
1330   <term>Effect if unset:</term>
1331   <listitem>
1332    <para>
1333     No link to local documentation is displayed on error pages and the CGI user interface.
1334    </para>
1335   </listitem>
1336  </varlistentry>
1337  <varlistentry>
1338   <term>Notes:</term>
1339   <listitem>
1340    <para>
1341     If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
1342     are unset, the whole "Local Privoxy Support" box on all generated pages will
1343     not be shown.
1344    </para>
1345    <para>
1346     This URL shouldn't be blocked ;-)
1347    </para>
1348   </listitem>
1349  </varlistentry>
1350 </variablelist>
1351 </sect4>
1352
1353 </sect3>
1354 <!--  ~  End section  ~  -->
1355
1356 <!--   ~~~~~       New section      ~~~~~     -->
1357
1358 <sect3>
1359 <title>Debugging</title>
1360
1361  <para>
1362   These options are mainly useful when tracing a problem.
1363   Note that you might also want to invoke
1364   <application>Privoxy</application> with the <literal>--no-daemon</literal>
1365   command line option when debugging.
1366  </para>
1367
1368 <sect4><title>debug</title>
1369
1370 <variablelist>
1371  <varlistentry>
1372   <term>Specifies:</term>
1373   <listitem>
1374    <para>
1375     Key values that determine what information gets logged.
1376    </para>
1377   </listitem>
1378  </varlistentry>
1379  <varlistentry>
1380   <term>Type of value:</term>
1381   <listitem>
1382    <para>Integer values</para>
1383   </listitem>
1384  </varlistentry>
1385  <varlistentry>
1386   <term>Default value:</term>
1387   <listitem>
1388    <para>12289 (i.e.: URLs plus informational and warning messages)</para>
1389   </listitem>
1390  </varlistentry>
1391  <varlistentry>
1392   <term>Effect if unset:</term>
1393   <listitem>
1394    <para>
1395     Nothing gets logged.
1396    </para>
1397   </listitem>
1398  </varlistentry>
1399  <varlistentry>
1400   <term>Notes:</term>
1401   <listitem>
1402    <para>
1403     The available debug levels are:
1404    </para>
1405    <para>
1406     <programlisting>
1407   debug         1 # show each GET/POST/CONNECT request
1408   debug         2 # show each connection status
1409   debug         4 # show I/O status
1410   debug         8 # show header parsing
1411   debug        16 # log all data into the logfile
1412   debug        32 # debug force feature
1413   debug        64 # debug regular expression filter
1414   debug       128 # debug fast redirects
1415   debug       256 # debug GIF de-animation
1416   debug       512 # Common Log Format
1417   debug      1024 # debug kill pop-ups
1418   debug      4096 # Startup banner and warnings.
1419   debug      8192 # Non-fatal errors
1420     </programlisting>
1421    </para>
1422    <para>
1423     To select multiple debug levels, you can either add them or use
1424     multiple <literal>debug</literal> lines.
1425    </para>
1426    <para>
1427     A debug level of 1 is informative because it will show you each request
1428     as it happens. <emphasis>1, 4096 and 8192 are highly recommended</emphasis>
1429     so that you will notice when things go wrong. The other levels are probably
1430     only of interest if you are hunting down a specific problem. They can produce
1431     a hell of an output (especially 16).
1432     <!-- LOL -->
1433    </para>
1434    <para>
1435     The reporting of <emphasis>fatal</emphasis> errors (i.e. ones which crash
1436     <application>Privoxy</application>) is always on and cannot be disabled.
1437    </para>
1438    <para>
1439     If you want to use CLF (Common Log Format), you should set <quote>debug
1440     512</quote> <emphasis>ONLY</emphasis> and not enable anything else.
1441    </para>
1442   </listitem>
1443  </varlistentry>
1444 </variablelist>
1445 </sect4>
1446
1447 <sect4><title>single-threaded</title>
1448
1449 <variablelist>
1450  <varlistentry>
1451   <term>Specifies:</term>
1452   <listitem>
1453    <para>
1454     Whether to run only one server thread
1455    </para>
1456   </listitem>
1457  </varlistentry>
1458  <varlistentry>
1459   <term>Type of value:</term>
1460   <listitem>
1461    <para><emphasis>None</emphasis></para>
1462   </listitem>
1463  </varlistentry>
1464  <varlistentry>
1465   <term>Default value:</term>
1466   <listitem>
1467    <para><emphasis>Unset</emphasis></para>
1468   </listitem>
1469  </varlistentry>
1470  <varlistentry>
1471   <term>Effect if unset:</term>
1472   <listitem>
1473    <para>
1474     Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to
1475     serve multiple requests simultaneously.
1476    </para>
1477   </listitem>
1478  </varlistentry>
1479  <varlistentry>
1480   <term>Notes:</term>
1481   <listitem>
1482    <para>
1483     This option is only there for debug purposes and you should never
1484     need to use it. <emphasis>It will drastically reduce performance.</emphasis>
1485    </para>
1486   </listitem>
1487  </varlistentry>
1488 </variablelist>
1489 </sect4>
1490
1491 </sect3>
1492
1493 <!--   ~~~~~       New section      ~~~~~     -->
1494
1495 <sect3>
1496 <title>Access Control and Security</title>
1497
1498  <para>
1499   This section of the config file controls the security-relevant aspects
1500   of <application>Privoxy</application>'s configuration.
1501  </para>
1502
1503 <sect4><title>listen-address</title>
1504
1505 <variablelist>
1506  <varlistentry>
1507   <term>Specifies:</term>
1508   <listitem>
1509    <para>
1510     The IP address and TCP port on which <application>Privoxy</application> will
1511     listen for client requests.
1512    </para>
1513   </listitem>
1514  </varlistentry>
1515  <varlistentry>
1516   <term>Type of value:</term>
1517   <listitem>
1518    <para>[<replaceable class="parameter">IP-Address</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
1519   </listitem>
1520  </varlistentry>
1521  <varlistentry>
1522   <term>Default value:</term>
1523   <listitem>
1524    <para>localhost:8118</para>
1525   </listitem>
1526  </varlistentry>
1527  <varlistentry>
1528   <term>Effect if unset:</term>
1529   <listitem>
1530    <para>
1531     Bind to localhost (127.0.0.1), port 8118. This is suitable and recommended for
1532     home users who run <application>Privoxy</application> on the same machine as
1533     their browser.
1534    </para>
1535   </listitem>
1536  </varlistentry>
1537  <varlistentry>
1538   <term>Notes:</term>
1539   <listitem>
1540    <para>
1541     You will need to configure your browser(s) to this proxy address and port.
1542    </para>
1543    <para>
1544     If you already have another service running on port 8118, or if you want to
1545     serve requests from other machines (e.g. on your local network) as well, you
1546     will need to override the default.
1547    </para>
1548    <para>
1549     If you leave out the IP address, <application>Privoxy</application> will
1550     bind to all interfaces (addresses) on your machine and may become reachable
1551     from the Internet. In that case, consider using access control lists (acl's)
1552     (see <quote>ACLs</quote> below), or a firewall.
1553    </para>
1554   </listitem>
1555  </varlistentry>
1556  <varlistentry>
1557   <term>Example:</term>
1558   <listitem>
1559    <para>
1560      Suppose you are running <application>Privoxy</application> on
1561      a machine which has the address 192.168.0.1 on your local private network
1562      (192.168.0.0) and has another outside connection with a different address.
1563      You want it to serve requests from inside only:
1564    </para>
1565    <para>
1566     <programlisting>
1567   listen-address  192.168.0.1:8118
1568     </programlisting>
1569    </para>
1570   </listitem>
1571  </varlistentry>
1572 </variablelist>
1573 </sect4>
1574
1575 <sect4><title>toggle</title>
1576
1577 <variablelist>
1578  <varlistentry>
1579   <term>Specifies:</term>
1580   <listitem>
1581    <para>
1582     Initial state of "toggle" status
1583    </para>
1584   </listitem>
1585  </varlistentry>
1586  <varlistentry>
1587   <term>Type of value:</term>
1588   <listitem>
1589    <para>1 or 0</para>
1590   </listitem>
1591  </varlistentry>
1592  <varlistentry>
1593   <term>Default value:</term>
1594   <listitem>
1595    <para>1</para>
1596   </listitem>
1597  </varlistentry>
1598  <varlistentry>
1599   <term>Effect if unset:</term>
1600   <listitem>
1601    <para>
1602     Act as if toggled on
1603    </para>
1604   </listitem>
1605  </varlistentry>
1606  <varlistentry>
1607   <term>Notes:</term>
1608   <listitem>
1609    <para>
1610     If set to 0, <application>Privoxy</application> will start in
1611     <quote>toggled off</quote> mode, i.e. behave like a normal, content-neutral
1612     proxy. See <literal>enable-remote-toggle</literal>
1613     below. This is not really useful anymore, since toggling is much easier
1614     via <ulink url="http://config.privoxy.org/toggle">the web
1615     interface</ulink> then via editing the <filename>conf</filename> file.
1616    </para>
1617    <para>
1618     The windows version will only display the toggle icon in the system tray
1619     if this option is present.
1620    </para>
1621   </listitem>
1622  </varlistentry>
1623 </variablelist>
1624 </sect4>
1625
1626
1627 <sect4><title>enable-remote-toggle</title>
1628 <variablelist>
1629  <varlistentry>
1630   <term>Specifies:</term>
1631   <listitem>
1632    <para>
1633     Whether or not the <ulink url="http://config.privoxy.org/toggle">web-based toggle
1634     feature</ulink> may be used
1635    </para>
1636   </listitem>
1637  </varlistentry>
1638  <varlistentry>
1639   <term>Type of value:</term>
1640   <listitem>
1641    <para>0 or 1</para>
1642   </listitem>
1643  </varlistentry>
1644  <varlistentry>
1645   <term>Default value:</term>
1646   <listitem>
1647    <para>1</para>
1648   </listitem>
1649  </varlistentry>
1650  <varlistentry>
1651   <term>Effect if unset:</term>
1652   <listitem>
1653    <para>
1654     The web-based toggle feature is disabled.
1655    </para>
1656   </listitem>
1657  </varlistentry>
1658  <varlistentry>
1659   <term>Notes:</term>
1660   <listitem>
1661    <para>
1662     When toggled off, <application>Privoxy</application> acts like a normal,
1663     content-neutral proxy, i.e. it acts as if none of the actions applied to
1664     any URL.
1665    </para>
1666    <para>
1667     For the time being, access to the toggle feature can <emphasis>not</emphasis> be
1668     controlled separately by <quote>ACLs</quote> or HTTP authentication,
1669     so that everybody who can access <application>Privoxy</application> (see
1670     <quote>ACLs</quote> and <literal>listen-address</literal> above) can
1671     toggle it for all users. So this option is <emphasis>not recommended</emphasis>
1672     for multi-user environments with untrusted users.
1673    </para>
1674    <para>
1675     Note that you must have compiled <application>Privoxy</application> with
1676     support for this feature, otherwise this option has no effect.
1677    </para>
1678   </listitem>
1679  </varlistentry>
1680 </variablelist>
1681 </sect4>
1682
1683
1684 <sect4><title>enable-edit-actions</title>
1685 <variablelist>
1686  <varlistentry>
1687   <term>Specifies:</term>
1688   <listitem>
1689    <para>
1690     Whether or not the <ulink url="http://config.privoxy.org/edit-actions">web-based actions
1691     file editor</ulink> may be used
1692    </para>
1693   </listitem>
1694  </varlistentry>
1695  <varlistentry>
1696   <term>Type of value:</term>
1697   <listitem>
1698    <para>0 or 1</para>
1699   </listitem>
1700  </varlistentry>
1701  <varlistentry>
1702   <term>Default value:</term>
1703   <listitem>
1704    <para>1</para>
1705   </listitem>
1706  </varlistentry>
1707  <varlistentry>
1708   <term>Effect if unset:</term>
1709   <listitem>
1710    <para>
1711     The web-based actions file editor is disabled.
1712    </para>
1713   </listitem>
1714  </varlistentry>
1715  <varlistentry>
1716   <term>Notes:</term>
1717   <listitem>
1718    <para>
1719     For the time being, access to the editor can <emphasis>not</emphasis> be
1720     controlled separately by <quote>ACLs</quote> or HTTP authentication,
1721     so that everybody who can access <application>Privoxy</application> (see
1722     <quote>ACLs</quote> and <literal>listen-address</literal> above) can
1723     modify its configuration for all users. So this option is <emphasis>not
1724     recommended</emphasis> for multi-user environments with untrusted users.
1725    </para>
1726    <para>
1727     Note that you must have compiled <application>Privoxy</application> with
1728     support for this feature, otherwise this option has no effect.
1729    </para>
1730   </listitem>
1731  </varlistentry>
1732 </variablelist>
1733 </sect4>
1734
1735 <sect4><title>ACLs: permit-access and deny-access</title>
1736 <variablelist>
1737  <varlistentry>
1738   <term>Specifies:</term>
1739   <listitem>
1740    <para>
1741     Who can access what.
1742    </para>
1743   </listitem>
1744  </varlistentry>
1745  <varlistentry>
1746   <term>Type of value:</term>
1747   <listitem>
1748    <para>
1749     <replaceable class="parameter">src_addr</replaceable>[/<replaceable class="parameter">src_masklen</replaceable>]
1750     [<replaceable class="parameter">dst_addr</replaceable>[/<replaceable class="parameter">dst_masklen</replaceable>]]
1751    </para>
1752    <para>
1753     Where <replaceable class="parameter">src_addr</replaceable> and
1754    <replaceable class="parameter">dst_addr</replaceable> are IP addresses in dotted decimal notation or valid
1755     DNS names, and <replaceable class="parameter">src_masklen</replaceable> and
1756     <replaceable class="parameter">dst_masklen</replaceable> are subnet masks in CIDR notation, i.e. integer
1757     values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
1758     destination part are optional.
1759    </para>
1760   </listitem>
1761  </varlistentry>
1762  <varlistentry>
1763   <term>Default value:</term>
1764   <listitem>
1765    <para><emphasis>Unset</emphasis></para>
1766   </listitem>
1767  </varlistentry>
1768  <varlistentry>
1769   <term>Effect if unset:</term>
1770   <listitem>
1771    <para>
1772     Don't restrict access further than implied by <literal>listen-address</literal>
1773    </para>
1774   </listitem>
1775  </varlistentry>
1776  <varlistentry>
1777   <term>Notes:</term>
1778   <listitem>
1779    <para>
1780     Access controls are included at the request of ISPs and systems
1781     administrators, and <emphasis>are not usually needed by individual users</emphasis>.
1782     For a typical home user, it will normally suffice to ensure that
1783     <application>Privoxy</application> only listens on the localhost or internal (home)
1784     network address by means of the <literal>listen-address</literal> option.
1785    </para>
1786    <para>
1787     Please see the warnings in the FAQ that this proxy is not intended to be a substitute
1788     for a firewall or to encourage anyone to defer addressing basic security
1789     weaknesses.
1790    </para>
1791    <para>
1792     Multiple ACL lines are OK.
1793     If any ACLs are specified, then the <application>Privoxy</application>
1794     talks only to IP addresses that match at least one <literal>permit-access</literal> line
1795     and don't match any subsequent <literal>deny-access</literal> line. In other words, the
1796     last match wins, with the default being <literal>deny-access</literal>.
1797    </para>
1798    <para>
1799     If <application>Privoxy</application> is using a forwarder (see <literal>forward</literal> below)
1800     for a particular destination URL, the <replaceable class="parameter">dst_addr</replaceable>
1801     that is examined is the address of the forwarder and <emphasis>NOT</emphasis> the address
1802     of the ultimate target. This is necessary because it may be impossible for the local
1803     <application>Privoxy</application> to determine the IP address of the
1804     ultimate target (that's often what gateways are used for).
1805    </para>
1806    <para>
1807     You should prefer using IP addresses over DNS names, because the address lookups take
1808     time. All DNS names must resolve! You can <emphasis>not</emphasis> use domain patterns
1809     like <quote>*.org</quote> or partial domain names. If a DNS name resolves to multiple
1810     IP addresses, only the first one is used.
1811    </para>
1812    <para>
1813     Denying access to particular sites by ACL may have undesired side effects
1814     if the site in question is hosted on a machine which also hosts other sites.
1815    </para>
1816   </listitem>
1817  </varlistentry>
1818  <varlistentry>
1819   <term>Examples:</term>
1820   <listitem>
1821    <para>
1822     Explicitly define the default behavior if no ACL and
1823     <literal>listen-address</literal> are set: <quote>localhost</quote>
1824     is OK. The absence of a <replaceable class="parameter">dst_addr</replaceable> implies that
1825     <emphasis>all</emphasis> destination addresses are OK:
1826    </para>
1827    <para>
1828     <screen>
1829   permit-access  localhost
1830     </screen>
1831    </para>
1832    <para>
1833     Allow any host on the same class C subnet as www.privoxy.org access to
1834     nothing but www.example.com:
1835    </para>
1836    <para>
1837     <screen>
1838   permit-access  www.privoxy.org/24 www.example.com/32
1839     </screen>
1840    </para>
1841    <para>
1842     Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
1843     with the exception that 192.168.45.73 may not access www.dirty-stuff.example.com:
1844    </para>
1845    <para>
1846     <screen>
1847   permit-access  192.168.45.64/26
1848   deny-access    192.168.45.73    www.dirty-stuff.example.com
1849     </screen>
1850    </para>
1851   </listitem>
1852  </varlistentry>
1853 </variablelist>
1854 </sect4>
1855
1856 <sect4><title>buffer-limit</title>
1857
1858 <variablelist>
1859  <varlistentry>
1860   <term>Specifies:</term>
1861   <listitem>
1862    <para>
1863     Maximum size of the buffer for content filtering.
1864    </para>
1865   </listitem>
1866  </varlistentry>
1867  <varlistentry>
1868   <term>Type of value:</term>
1869   <listitem>
1870    <para>Size in Kbytes</para>
1871   </listitem>
1872  </varlistentry>
1873  <varlistentry>
1874   <term>Default value:</term>
1875   <listitem>
1876    <para>4096</para>
1877   </listitem>
1878  </varlistentry>
1879  <varlistentry>
1880   <term>Effect if unset:</term>
1881   <listitem>
1882    <para>
1883     Use a 4MB (4096 KB) limit.
1884    </para>
1885   </listitem>
1886  </varlistentry>
1887  <varlistentry>
1888   <term>Notes:</term>
1889   <listitem>
1890    <para>
1891     For content filtering, i.e. the <literal>+filter</literal> and
1892     <literal>+deanimate-gif</literal> actions, it is necessary that
1893     <application>Privoxy</application> buffers the entire document body.
1894     This can be potentially dangerous, since a server could just keep sending
1895     data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
1896     Hence this option.
1897    </para>
1898    <para>
1899     When a document buffer size reaches the <literal>buffer-limit</literal>, it is
1900     flushed to the client unfiltered and no further attempt to
1901     filter the rest of the document is made. Remember that there may be multiple threads
1902     running, which might require up to <literal>buffer-limit</literal> Kbytes
1903     <emphasis>each</emphasis>, unless you have enabled <quote>single-threaded</quote>
1904     above.
1905    </para>
1906   </listitem>
1907  </varlistentry>
1908 </variablelist>
1909 </sect4>
1910
1911 </sect3>
1912
1913 <!--  ~  End section  ~  -->
1914
1915
1916 <!--   ~~~~~       New section      ~~~~~     -->
1917
1918 <sect3 id="forwarding">
1919 <title>Forwarding</title>
1920
1921 <para>
1922  This feature allows routing of HTTP requests through a chain of
1923  multiple proxies.
1924  It can be used to better protect privacy and confidentiality when
1925  accessing specific domains by routing requests to those domains
1926  through an anonymous public proxy (see e.g. <ulink
1927  url="http://www.multiproxy.org/anon_list.htm">http://www.multiproxy.org/anon_list.htm</ulink>)
1928  Or to use a caching proxy to speed up browsing. Or chaining to a parent
1929  proxy may be necessary because the machine that <application>Privoxy</application>
1930  runs on has no direct Internet access.
1931 </para>
1932
1933 <para>
1934  Also specified here are SOCKS proxies. <application>Privoxy</application>
1935  supports the SOCKS 4 and SOCKS 4A protocols.
1936 </para>
1937
1938 <sect4><title>forward</title>
1939 <variablelist>
1940  <varlistentry>
1941   <term>Specifies:</term>
1942   <listitem>
1943    <para>
1944     To which parent HTTP proxy specific requests should be routed.
1945    </para>
1946   </listitem>
1947  </varlistentry>
1948  <varlistentry>
1949   <term>Type of value:</term>
1950   <listitem>
1951    <para>
1952     <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
1953     <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
1954    </para>
1955    <para>
1956     Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
1957     chapter on domain matching in the actions file),
1958     <replaceable class="parameter">http_parent</replaceable> is the address of the parent HTTP proxy
1959     as an IP addresses in dotted decimal notation or as a valid DNS name (or <quote>.</quote> to denote
1960     <quote>no forwarding</quote>, and the optional
1961     <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer
1962     values from 1 to 64535
1963    </para>
1964   </listitem>
1965  </varlistentry>
1966  <varlistentry>
1967   <term>Default value:</term>
1968   <listitem>
1969    <para><emphasis>Unset</emphasis></para>
1970   </listitem>
1971  </varlistentry>
1972  <varlistentry>
1973   <term>Effect if unset:</term>
1974   <listitem>
1975    <para>
1976     Don't use parent HTTP proxies.
1977    </para>
1978   </listitem>
1979  </varlistentry>
1980  <varlistentry>
1981   <term>Notes:</term>
1982   <listitem>
1983    <para>
1984     If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
1985     forwarded to another HTTP proxy but are made directly to the web servers.
1986    </para>
1987    <para>
1988     Multiple lines are OK, they are checked in sequence, and the last match wins.
1989    </para>
1990   </listitem>
1991  </varlistentry>
1992  <varlistentry>
1993   <term>Examples:</term>
1994   <listitem>
1995    <para>
1996     Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle):
1997    </para>
1998    <para>
1999     <screen>
2000   forward   .*     anon-proxy.example.org:8080
2001   forward   :443   .
2002     </screen>
2003    </para>
2004    <para>
2005     Everything goes to our example ISP's caching proxy, except for requests
2006     to that ISP's sites:
2007    </para>
2008    <para>
2009     <screen>
2010   forward   .*.                caching-proxy.example-isp.net:8000
2011   forward   .example-isp.net   .
2012     </screen>
2013    </para>
2014   </listitem>
2015  </varlistentry>
2016 </variablelist>
2017 </sect4>
2018
2019 <sect4><title>forward-socks4 and forward-socks4a</title>
2020 <variablelist>
2021  <varlistentry>
2022   <term>Specifies:</term>
2023   <listitem>
2024    <para>
2025     Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed.
2026    </para>
2027   </listitem>
2028  </varlistentry>
2029  <varlistentry>
2030   <term>Type of value:</term>
2031   <listitem>
2032    <para>
2033     <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
2034     <replaceable class="parameter">socks_proxy</replaceable>[/<replaceable class="parameter">port</replaceable>]
2035     <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
2036    </para>
2037    <para>
2038     Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
2039     chapter on domain matching in the actions file),
2040     <replaceable class="parameter">http_parent</replaceable> and <replaceable class="parameter">socks_proxy</replaceable>
2041     are IP addresses in dotted decimal notation or valid DNS names (<replaceable class="parameter">http_parent</replaceable>
2042     may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
2043     <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer values from 1 to 64535
2044    </para>
2045   </listitem>
2046  </varlistentry>
2047  <varlistentry>
2048   <term>Default value:</term>
2049   <listitem>
2050    <para><emphasis>Unset</emphasis></para>
2051   </listitem>
2052  </varlistentry>
2053  <varlistentry>
2054   <term>Effect if unset:</term>
2055   <listitem>
2056    <para>
2057     Don't use SOCKS proxies.
2058    </para>
2059   </listitem>
2060  </varlistentry>
2061  <varlistentry>
2062   <term>Notes:</term>
2063   <listitem>
2064    <para>
2065     Multiple lines are OK, they are checked in sequence, and the last match wins.
2066    </para>
2067    <para>
2068     The difference between <literal>forward-socks4</literal> and <literal>forward-socks4a</literal>
2069     is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
2070     server, while in SOCKS 4 it happens locally.
2071    </para>
2072    <para>
2073     If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
2074     forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
2075     a SOCKS proxy.
2076    </para>
2077   </listitem>
2078  </varlistentry>
2079  <varlistentry>
2080   <term>Examples:</term>
2081   <listitem>
2082    <para>
2083      From the company example.com, direct connections are made to all
2084      <quote>internal</quote> domains, but everything outbound goes through
2085      their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
2086      the Internet.
2087    </para>
2088    <para>
2089     <screen>
2090   forward-socks4a   .*.            socks-gw.example.com:1080  www-cache.example-isp.net:8080
2091   forward           .example.com   .
2092     </screen>
2093    </para>
2094    <para>
2095     A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
2096    </para>
2097    <para>
2098     <screen>
2099   forward-socks4   .*.            socks-gw.example.com:1080  .
2100     </screen>
2101    </para>
2102   </listitem>
2103  </varlistentry>
2104 </variablelist>
2105 </sect4>
2106
2107 <sect4><title>Advanced Forwarding Examples</title>
2108
2109 <para>
2110  If you have links to multiple ISPs that provide various special content
2111  only to their subscribers, you can configure multiple <application>Privoxies</application>
2112  which have connections to the respective ISPs to act as forwarders to each other, so that
2113  <emphasis>your</emphasis> users can see the internal content of all ISPs.
2114 </para>
2115
2116 <para>
2117  Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP connection to
2118  isp-b.net. Both run <application>Privoxy</application>. Their forwarding
2119  configuration can look like this:
2120 </para>
2121
2122 <para>
2123  host-a:
2124 </para>
2125
2126 <para>
2127  <screen>
2128   forward    .*.         .
2129   forward    .isp-b.net  host-b:8118
2130  </screen>
2131 </para>
2132
2133 <para>
2134  host-b:
2135 </para>
2136
2137 <para>
2138  <screen>
2139   forward    .*.         .
2140   forward    .isp-a.net  host-a:8118
2141  </screen>
2142 </para>
2143
2144 <para>
2145  Now, your users can set their browser's proxy to use either
2146  host-a or host-b and be able to browse the internal content
2147  of both isp-a and isp-b.
2148 </para>
2149
2150 <para>
2151  If you intend to chain <application>Privoxy</application> and
2152  <application>squid</application> locally, then chain as
2153  <literal>browser -> squid -> privoxy</literal> is the recommended way.
2154 </para>
2155
2156 <para>
2157  Assuming that <application>Privoxy</application> and <application>squid</application>
2158  run on the same box, your squid configuration could then look like this:
2159 </para>
2160
2161 <para>
2162  <screen>
2163   # Define Privoxy as parent proxy (without ICP)
2164   cache_peer 127.0.0.1 parent 8118 7 no-query
2165
2166   # Define ACL for protocol FTP
2167   acl ftp proto FTP
2168
2169   # Do not forward FTP requests to Privoxy
2170   always_direct allow ftp
2171
2172   # Forward all the rest to Privoxy
2173   never_direct allow all
2174  </screen>
2175 </para>
2176
2177 <para>
2178  You would then need to change your browser's proxy settings to <application>squid</application>'s address and port.
2179  Squid normally uses port 3128. If unsure consult <literal>http_port</literal> in <filename>squid.conf</filename>.
2180 </para>
2181
2182 </sect4>
2183
2184 </sect3>
2185
2186 <!--  ~  End section  ~  -->
2187
2188
2189 <!--   ~~~~~       New section      ~~~~~     -->
2190
2191 <sect3>
2192 <title>Windows GUI Options</title>
2193 <para>
2194  <application>Privoxy</application> has a number of options specific to the
2195  Windows GUI interface:
2196 </para>
2197
2198 <para>
2199  If <quote>activity-animation</quote> is set to 1, the
2200  <application>Privoxy</application> icon will animate when
2201  <quote>Privoxy</quote> is active. To turn off, set to 0.
2202 </para>
2203
2204 <para>
2205  <literal>
2206   <msgtext>
2207    <literallayout>
2208   <emphasis>activity-animation   1</emphasis>
2209    </literallayout>
2210   </msgtext>
2211  </literal>
2212 </para>
2213
2214 <para>
2215  If <quote>log-messages</quote> is set to 1,
2216  <application>Privoxy</application> will log messages to the console
2217  window:
2218 </para>
2219
2220 <para>
2221  <literal>
2222   <msgtext>
2223    <literallayout>
2224   <emphasis>log-messages       1</emphasis>
2225    </literallayout>
2226   </msgtext>
2227  </literal>
2228 </para>
2229
2230 <para>
2231  If <quote>log-buffer-size</quote> is set to 1, the size of the log buffer,
2232  i.e. the amount of memory used for the log messages displayed in the
2233  console window, will be limited to <quote>log-max-lines</quote> (see below).
2234 </para>
2235
2236 <para>
2237  Warning: Setting this to 0 will result in the buffer to grow infinitely and
2238  eat up all your memory!
2239 </para>
2240
2241 <para>
2242  <literal>
2243   <msgtext>
2244    <literallayout>
2245   <emphasis>log-buffer-size      1</emphasis>
2246    </literallayout>
2247   </msgtext>
2248  </literal>
2249 </para>
2250
2251 <para>
2252  <application>log-max-lines</application> is the maximum number of lines held
2253  in the log buffer. See above.
2254 </para>
2255
2256 <para>
2257  <literal>
2258   <msgtext>
2259    <literallayout>
2260   <emphasis>log-max-lines      200</emphasis>
2261    </literallayout>
2262   </msgtext>
2263  </literal>
2264 </para>
2265
2266 <para>
2267  If <quote>log-highlight-messages</quote> is set to 1,
2268  <application>Privoxy</application> will highlight portions of the log
2269  messages with a bold-faced font:
2270 </para>
2271
2272 <para>
2273  <literal>
2274   <msgtext>
2275    <literallayout>
2276   <emphasis>log-highlight-messages   1</emphasis>
2277    </literallayout>
2278   </msgtext>
2279  </literal>
2280 </para>
2281
2282 <para>
2283  The font used in the console window:
2284 </para>
2285
2286 <para>
2287  <literal>
2288   <msgtext>
2289    <literallayout>
2290   <emphasis>log-font-name        Comic Sans MS</emphasis>
2291    </literallayout>
2292   </msgtext>
2293  </literal>
2294 </para>
2295
2296 <para>
2297  Font size used in the console window:
2298 </para>
2299
2300 <para>
2301  <literal>
2302   <msgtext>
2303    <literallayout>
2304   <emphasis>log-font-size        8</emphasis>
2305    </literallayout>
2306   </msgtext>
2307  </literal>
2308 </para>
2309
2310 <para>
2311  <quote>show-on-task-bar</quote> controls whether or not
2312  <application>Privoxy</application> will appear as a button on the Task bar
2313  when minimized:
2314 </para>
2315
2316 <para>
2317  <literal>
2318   <msgtext>
2319    <literallayout>
2320   <emphasis>show-on-task-bar     0</emphasis>
2321    </literallayout>
2322   </msgtext>
2323  </literal>
2324 </para>
2325
2326 <para>
2327  If <quote>close-button-minimizes</quote> is set to 1, the Windows close
2328  button will minimize <application>Privoxy</application> instead of closing
2329  the program (close with the exit option on the File menu).
2330 </para>
2331
2332 <para>
2333  <literal>
2334   <msgtext>
2335    <literallayout>
2336   <emphasis>close-button-minimizes  1</emphasis>
2337    </literallayout>
2338   </msgtext>
2339  </literal>
2340 </para>
2341
2342 <para>
2343  The <quote>hide-console</quote> option is specific to the MS-Win console
2344  version of <application>Privoxy</application>. If this option is used,
2345  <application>Privoxy</application> will disconnect from and hide  the
2346  command console.
2347 </para>
2348
2349 <para>
2350  <literal>
2351   <msgtext>
2352    <literallayout>
2353   #hide-console
2354    </literallayout>
2355   </msgtext>
2356  </literal>
2357 </para>
2358
2359 </sect3>
2360 </sect2>
2361
2362 <!--  ~  End section  ~  -->
2363
2364
2365 <!--   ~~~~~       New section      ~~~~~     -->
2366 <sect2 id="actionsfile">
2367 <title>The Actions File</title>
2368
2369 <para>
2370  The actions file (<filename>default.action</filename>, formerly:
2371  <filename>actionsfile</filename> or <filename>ijb.action</filename>) is used
2372  to define what actions <application>Privoxy</application> takes for which
2373  URLs, and thus determines how ad images, cookies and various other aspects
2374  of HTTP content and transactions are handled on which sites (or even parts
2375  thereof).
2376 </para>
2377
2378 <para>
2379  Anything you want can blocked, including ads, banners, or just some obnoxious
2380  URL that you would rather not see. Cookies can be accepted or rejected, or
2381  accepted only during the current browser session (i.e. not written to disk),
2382  content can be modified, JavaScripts tamed, user-tracking fooled, and much more.
2383  See below for a complete list of available actions.
2384 </para>
2385
2386 <para>
2387  An actions file typically has sections. At the top, <quote>aliases</quote> are
2388  defined (discussed below), then the default set of rules which will apply
2389  universally to all sites and pages. And then below that is generally a lengthy
2390  set of exceptions to the defined universal policies.
2391 </para>
2392
2393 <!--   ~~~~~       New section      ~~~~~     -->
2394 <sect3>
2395 <title>Finding the Right Mix</title>
2396 <para>
2397  Note that some actions like cookie suppression or script disabling may
2398  render some sites unusable, which rely on these techniques to work properly.
2399  Finding the right mix of actions is not easy and certainly a matter of personal
2400  taste. In general, it can be said that the more <quote>aggressive</quote>
2401  your default settings (in the top section of the actions file) are,
2402  the more exceptions for <quote>trusted</quote> sites you will have to
2403  make later. If, for example, you want to kill popup windows per default, you'll
2404  have to make exceptions from that rule for sites that you regularly use
2405  and that require popups for actually useful content, like maybe your bank,
2406  favorite shop, or newspaper.
2407 </para>
2408
2409 <para>
2410  We have tried to provide you with reasonable rules to start from in the
2411  distribution actions file. But there is no general rule of thumb on these
2412  things. There just are too many variables, and sites are constantly changing.
2413  Sooner or later you will want to change the rules (and read this chapter).
2414 </para>
2415 </sect3>
2416
2417 <!--   ~~~~~       New section      ~~~~~     -->
2418 <sect3>
2419 <title>How to Edit</title>
2420 <para>
2421  The easiest way to edit the <quote>actions</quote> file is with a browser by
2422  using our browser-based editor, which is available at <ulink
2423  url="http://config.privoxy.org/edit-actions">http://config.privoxy.org/edit-actions</ulink>.
2424 </para>
2425
2426 <para>
2427  If you prefer plain text editing to GUIs, you can of course also directly edit the
2428  <filename>default.action</filename> file.
2429 </para>
2430 </sect3>
2431
2432
2433 <sect3>
2434 <title>How Actions are Applied to URLs</title>
2435 <para>
2436  The actions file is divided into sections. There are special sections,
2437  like the alias sections which will be discussed later. For now let's
2438  concentrate on regular sections: They have a heading line (often split
2439  up to multiple lines for readability) which consist of a list of actions,
2440  separated by whitespace and enclosed in curly braces. Below that, there
2441  is a list of URL patterns, each on a separate line.
2442 </para>
2443
2444 <para>
2445  To determine which actions apply to a request, the URL of the request is
2446  compared to all patterns in this file. Every time it matches, the list of
2447  applicable actions for the URL is incrementally updated, using the heading
2448  of the section in which the pattern is located. If multiple matches for
2449  the same URL set the same action differently, the last match wins.
2450 </para>
2451
2452 <para>
2453  You can trace this process by visiting <ulink
2454  url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
2455 </para>
2456
2457 <para>
2458  More detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
2459  Anatomy of an Action</link>.
2460 </para>
2461 </sect3>
2462
2463 <!--   ~~~~~       New section      ~~~~~     -->
2464 <sect3>
2465 <title>Patterns</title>
2466 <para>
2467  Generally, a pattern has the form <literal>&lt;domain&gt;/&lt;path&gt;</literal>,
2468  where both the <literal>&lt;domain&gt;</literal> and <literal>&lt;path&gt;</literal>
2469  are optional. (This is why the pattern <literal>/</literal> matches all URLs).
2470 </para>
2471
2472 <variablelist>
2473  <varlistentry>
2474   <term><literal>www.example.com/</literal></term>
2475   <listitem>
2476    <para>
2477     is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
2478     regardless of which document on that server is requested.
2479    </para>
2480   </listitem>
2481  </varlistentry>
2482  <varlistentry>
2483   <term><literal>www.example.com</literal></term>
2484   <listitem>
2485    <para>
2486     means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
2487     be omitted.
2488    </para>
2489   </listitem>
2490  </varlistentry>
2491  <varlistentry>
2492   <term><literal>www.example.com/index.html</literal></term>
2493   <listitem>
2494    <para>
2495     matches only the single document <literal>/index.html</literal>
2496     on <literal>www.example.com</literal>.
2497    </para>
2498   </listitem>
2499  </varlistentry>
2500  <varlistentry>
2501   <term><literal>/index.html</literal></term>
2502   <listitem>
2503    <para>
2504     matches the document <literal>/index.html</literal>, regardless of the domain,
2505     i.e. on <emphasis>any</emphasis> web server.
2506    </para>
2507   </listitem>
2508  </varlistentry>
2509  <varlistentry>
2510   <term><literal>index.html</literal></term>
2511   <listitem>
2512    <para>
2513     matches nothing, since it would be  interpreted as a domain name and
2514     there is no top-level domain called <literal>.html</literal>.
2515    </para>
2516   </listitem>
2517  </varlistentry>
2518 </variablelist>
2519
2520 <sect4><title>The Domain Pattern</title>
2521
2522 <para>
2523  The matching of the domain part offers some flexible options: if the
2524  domain starts or ends with a dot, it becomes unanchored at that end.
2525  For example:
2526 </para>
2527
2528 <variablelist>
2529  <varlistentry>
2530   <term><literal>.example.com</literal></term>
2531   <listitem>
2532    <para>
2533     matches any domain that <emphasis>ENDS</emphasis> in
2534     <literal>.example.com</literal>
2535    </para>
2536   </listitem>
2537  </varlistentry>
2538  <varlistentry>
2539   <term><literal>www.</literal></term>
2540   <listitem>
2541    <para>
2542     matches any domain that <emphasis>STARTS</emphasis> with
2543     <literal>www.</literal>
2544    </para>
2545   </listitem>
2546  </varlistentry>
2547  <varlistentry>
2548   <term><literal>.example.</literal></term>
2549   <listitem>
2550    <para>
2551     matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>
2552     (Correctly speaking: It matches any FQDN that contains <literal>example</literal> as a domain.)
2553    </para>
2554   </listitem>
2555  </varlistentry>
2556 </variablelist>
2557
2558 <para>
2559  Additionally, there are wild-cards that you can use in the domain names
2560  themselves. They work pretty similar to shell wild-cards: <quote>*</quote>
2561  stands for zero or more arbitrary characters, <quote>?</quote> stands for
2562  any single character, you can define character classes in square
2563  brackets and all of that can be freely mixed:
2564 </para>
2565
2566 <variablelist>
2567  <varlistentry>
2568   <term><literal>ad*.example.com</literal></term>
2569   <listitem>
2570    <para>
2571     matches <quote>adserver.example.com</quote>,
2572     <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
2573    </para>
2574   </listitem>
2575  </varlistentry>
2576  <varlistentry>
2577   <term><literal>*ad*.example.com</literal></term>
2578   <listitem>
2579    <para>
2580     matches all of the above, and then some.
2581    </para>
2582   </listitem>
2583  </varlistentry>
2584  <varlistentry>
2585   <term><literal>.?pix.com</literal></term>
2586   <listitem>
2587    <para>
2588     matches <literal>www.ipix.com</literal>,
2589     <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc.
2590    </para>
2591   </listitem>
2592  </varlistentry>
2593  <varlistentry>
2594   <term><literal>www[1-9a-ez].example.c*</literal></term>
2595   <listitem>
2596    <para>
2597      matches <literal>www1.example.com</literal>,
2598      <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>,
2599      <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis>
2600      <literal>wwww.example.com</literal>.
2601    </para>
2602   </listitem>
2603  </varlistentry>
2604 </variablelist>
2605
2606 </sect4>
2607
2608 <sect4><title>The Path Pattern</title>
2609
2610 <para>
2611  <application>Privoxy</application> uses Perl compatible regular expressions
2612  (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
2613  matching the path.
2614 </para>
2615
2616 <para>
2617  There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
2618  expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
2619  at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
2620  You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
2621  useful, which is available on-line at <ulink
2622  url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>.
2623 </para>
2624
2625 <para>
2626  Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
2627  i.e. it matches as if it would start with a <quote>^</quote>.
2628 </para>
2629
2630 <para>
2631  Please also note that matching in the path is case
2632  <emphasis>INSENSITIVE</emphasis> by default, but you can switch to case
2633  sensitive at any point in the pattern by using the
2634  <quote>(?-i)</quote> switch:
2635  <literal>www.example.com/(?-i)PaTtErN.*</literal> will match only
2636  documents whose path starts with <literal>PaTtErN</literal> in
2637  <emphasis>exactly</emphasis> this capitalization.
2638 </para>
2639 </sect4>
2640
2641 </sect3>
2642
2643 <!--  ~  End section  ~  -->
2644
2645
2646 <!--   ~~~~~       New section      ~~~~~     -->
2647
2648 <sect3 id="actions">
2649 <title>Actions</title>
2650 <para>
2651  Actions are enabled if preceded with a <quote>+</quote>, and disabled if
2652  preceded with a <quote>-</quote>. Actions are invoked by enclosing the
2653  action name in curly braces (e.g. {+some_action}), followed by a list of
2654  URLs (or patterns that match URLs) to which the action applies. There are
2655  three classes of actions:
2656 </para>
2657
2658 <para>
2659  <itemizedlist>
2660
2661  <listitem>
2662   <para>
2663    Boolean, i.e the action can only be <quote>on</quote> or
2664    <quote>off</quote>. Examples:
2665  </para>
2666   <para>
2667    <literal>
2668     <msgtext>
2669      <literallayout>
2670   <emphasis>{+name}</emphasis>        # enable this action
2671   <emphasis>{-name}</emphasis>        # disable this action
2672      </literallayout>
2673     </msgtext>
2674    </literal>
2675   </para>
2676  </listitem>
2677
2678
2679  <listitem>
2680   <para>
2681    Parameterized, e.g. <quote>+/-hide-user-agent{ Mozilla 1.0 }</quote>,
2682    where some value is required in order to enable this type of action.
2683    Examples:
2684   </para>
2685   <para>
2686    <literal>
2687     <msgtext>
2688      <literallayout>
2689   <emphasis>{+name{param}}</emphasis>  # enable action and set parameter to <quote>param</quote>
2690   <emphasis>{-name}</emphasis>         # disable action (<quote>parameter</quote>) can be omitted
2691      </literallayout>
2692     </msgtext>
2693    </literal>
2694   </para>
2695  </listitem>
2696
2697  <listitem>
2698   <para>
2699   <!-- oes, or someone, check this. Re-worded 04/20/02 HB. -->
2700    Multi-value, e.g. <quote>{+/-add-header{Name: value}}</quote> ot
2701    <quote>{+/-wafer{name=value}}</quote>), where some value needs to be defined
2702    in addition to simply enabling the actino. Examples:
2703   </para>
2704   <para>
2705    <literal>
2706     <msgtext>
2707      <literallayout>
2708   <emphasis>{+name{param=value}}</emphasis>   # enable action and set <quote>param</quote> to <quote>value</quote>
2709   <emphasis>{-name{param=value}}</emphasis>   # remove the parameter <quote>param</quote> completely
2710   <emphasis>{-name}</emphasis>                # disable this action totally and remove <application>param</application> too
2711      </literallayout>
2712     </msgtext>
2713    </literal>
2714   </para>
2715  </listitem>
2716
2717  </itemizedlist>
2718 </para>
2719
2720 <para>
2721  If nothing is specified in this file, no <quote>actions</quote> are taken.
2722  So in this case <application>Privoxy</application> would just be a
2723  normal, non-blocking, non-anonymizing proxy. You must specifically
2724  enable the privacy and blocking features you need (although the
2725  provided default <filename>default.action</filename> file will
2726  give a good starting point).
2727 </para>
2728
2729 <para>
2730  Later defined actions always over-ride earlier ones.  So exceptions
2731  to any rules you make, should come in the latter part of the file. For
2732  multi-valued actions, the actions are applied in the order they are
2733  specified.
2734 </para>
2735
2736 <!-- start actions listing -->
2737 <para>
2738  The list of valid <application>Privoxy</application> <quote>actions</quote> are:
2739 </para>
2740
2741
2742 <!-- ********************************************************** -->
2743 <!-- Please note the below defined actions use id's that are    -->
2744 <!-- probably linked from other places, so please don't change. -->
2745 <!--                                                            -->
2746 <!-- ********************************************************** -->
2747
2748
2749 <!--   ~~~~~       New section      ~~~~~     -->
2750
2751 <sect4 id="add-header">
2752 <title><emphasis>+add-header{Name: value}</emphasis></title>
2753
2754 <variablelist>
2755  <varlistentry>
2756   <term>Type:</term>
2757   <!-- boolean, parameterized, Multi-value -->
2758   <listitem>
2759    <para>Multi-value.</para>
2760   </listitem>
2761  </varlistentry>
2762
2763  <varlistentry>
2764   <term>Typical uses:</term>
2765   <listitem>
2766    <para>
2767     Send a user defined HTTP header to the web server.
2768    </para>
2769   </listitem>
2770  </varlistentry>
2771
2772  <varlistentry>
2773   <term>Possible values:</term>
2774   <listitem>
2775    <para>
2776     Any value is possible. Validity of the defined HTTP headers is not checked.
2777    </para>
2778   </listitem>
2779  </varlistentry>
2780
2781  <varlistentry>
2782   <term>Example usage:</term>
2783   <listitem>
2784     <literallayout>
2785      <emphasis>{+add-header{X-User-Tracking: sucks}}</emphasis>
2786      <emphasis>.example.com</emphasis>
2787     </literallayout>
2788   </listitem>
2789  </varlistentry>
2790
2791 <varlistentry>
2792   <term>Notes:</term>
2793   <listitem>
2794    <para>
2795     This action may be specified multiple times, in order to define multiple
2796     headers. This is rarely needed for the typical user. If you don't know what
2797     <quote>HTTP headers</quote> are, you definitely don't need to worry about this
2798     one.
2799    </para>
2800   </listitem>
2801  </varlistentry>
2802 </variablelist>
2803 </sect4>
2804
2805
2806 <!--   ~~~~~       New section      ~~~~~     -->
2807 <sect4 id="block">
2808 <title><emphasis>+block</emphasis></title>
2809
2810 <variablelist>
2811  <varlistentry>
2812   <term>Type:</term>
2813   <!-- boolean, parameterized, Multi-value -->
2814   <listitem>
2815    <para>Boolean.</para>
2816   </listitem>
2817  </varlistentry>
2818
2819  <varlistentry>
2820   <term>Typical uses:</term>
2821   <listitem>
2822    <para>
2823     Used to block a URL from reaching your browser. The URL may be
2824     anything, but is typically used to block ads or other obnoxious
2825     content.
2826    </para>
2827   </listitem>
2828  </varlistentry>
2829
2830  <varlistentry>
2831   <term>Possible values:</term>
2832   <listitem>
2833    <para>N/A</para>
2834   </listitem>
2835  </varlistentry>
2836
2837  <varlistentry>
2838   <term>Example usage:</term>
2839   <listitem>
2840     <literallayout>
2841      <emphasis>{+block}</emphasis>
2842      <emphasis>.example.com</emphasis>
2843      <emphasis>.ads.r.us</emphasis>
2844     </literallayout>
2845   </listitem>
2846  </varlistentry>
2847
2848 <varlistentry>
2849   <term>Notes:</term>
2850   <listitem>
2851    <para>
2852     <application>Privoxy</application> will display its
2853     special <quote>BLOCKED</quote> page if a URL matches one of the
2854     blocked patterns. If there is sufficient space, a large red
2855     banner will appear with a friendly message about why the page
2856     was blocked, and a way to go there anyway. If there is insufficient
2857     space a smaller blocked page will appear without the red banner.
2858     One exception is if the URL matches both <quote>+block</quote>
2859     and <quote>+image</quote>, then it can be handled by
2860     <quote>+image-blocker</quote> (see below).
2861    </para>
2862   </listitem>
2863  </varlistentry>
2864
2865 </variablelist>
2866 </sect4>
2867
2868
2869 <!--   ~~~~~       New section      ~~~~~     -->
2870 <sect4 id="deanimate-gifs">
2871 <title><emphasis>+deanimate-gifs</emphasis></title>
2872
2873 <variablelist>
2874  <varlistentry>
2875   <term>Type:</term>
2876   <!-- boolean, parameterized, Multi-value -->
2877   <listitem>
2878    <para>Parameterized.</para>
2879   </listitem>
2880  </varlistentry>
2881
2882  <varlistentry>
2883   <term>Typical uses:</term>
2884   <listitem>
2885    <para>
2886     To stop those annoying, distracting animated GIF images.
2887    </para>
2888   </listitem>
2889  </varlistentry>
2890
2891  <varlistentry>
2892   <term>Possible values:</term>
2893   <listitem>
2894    <para>
2895     <quote>last</quote> or <quote>first</quote>
2896    </para>
2897   </listitem>
2898  </varlistentry>
2899
2900  <varlistentry>
2901   <term>Example usage:</term>
2902   <listitem>
2903     <literallayout>
2904       <emphasis>{+deanimate-gifs{last}}</emphasis>
2905       <emphasis>.example.com</emphasis>
2906     </literallayout>
2907   </listitem>
2908  </varlistentry>
2909
2910  <varlistentry>
2911   <term>Notes:</term>
2912   <listitem>
2913    <para>
2914     De-animate all animated GIF images, i.e. reduce them to their last frame.
2915     This will also shrink the images considerably (in bytes, not pixels!). If
2916     the option <quote>first</quote> is given, the first frame of the animation
2917     is used as the replacement. If <quote>last</quote> is given, the last
2918     frame of the animation is used instead, which probably makes more sense for
2919     most banner animations, but also has the risk of not showing the entire
2920     last frame (if it is only a delta to an earlier frame).
2921    </para>
2922   </listitem>
2923  </varlistentry>
2924
2925 </variablelist>
2926 </sect4>
2927
2928 <!--   ~~~~~       New section      ~~~~~     -->
2929 <sect4 id="downgrade">
2930 <title><emphasis>+downgrade</emphasis></title>
2931
2932 <variablelist>
2933  <varlistentry>
2934   <term>Type:</term>
2935   <!-- boolean, parameterized, Multi-value -->
2936   <listitem>
2937    <para>Boolean.</para>
2938   </listitem>
2939  </varlistentry>
2940
2941  <varlistentry>
2942   <term>Typical uses:</term>
2943   <listitem>
2944    <para>
2945     <quote>+downgrade</quote> will downgrade HTTP/1.1 client requests to
2946     HTTP/1.0 and downgrade the responses as well.
2947    </para>
2948   </listitem>
2949  </varlistentry>
2950
2951  <varlistentry>
2952   <term>Possible values:</term>
2953   <listitem>
2954    <para>
2955     N/A
2956    </para>
2957   </listitem>
2958  </varlistentry>
2959
2960  <varlistentry>
2961   <term>Example usage:</term>
2962   <listitem>
2963     <literallayout>
2964      <emphasis>{+downgrade}</emphasis>
2965      <emphasis>.example.com</emphasis>
2966     </literallayout>
2967   </listitem>
2968  </varlistentry>
2969
2970  <varlistentry>
2971   <term>Notes:</term>
2972   <listitem>
2973    <para>
2974     Use this action for servers that use HTTP/1.1 protocol features that
2975     <application>Privoxy</application> doesn't handle well yet. HTTP/1.1 is
2976     only partially implemented. Default is not to downgrade requests. This is
2977     an infrequently needed action, and is used to help with problem sites only.
2978    </para>
2979   </listitem>
2980  </varlistentry>
2981
2982 </variablelist>
2983 </sect4>
2984
2985 <!--   ~~~~~       New section      ~~~~~     -->
2986 <sect4 id="fast-redirects">
2987 <title><emphasis>+fast-redirects</emphasis></title>
2988
2989 <variablelist>
2990  <varlistentry>
2991   <term>Type:</term>
2992   <!-- boolean, parameterized, Multi-value -->
2993   <listitem>
2994    <para>Boolean.</para>
2995   </listitem>
2996  </varlistentry>
2997
2998  <varlistentry>
2999   <term>Typical uses:</term>
3000   <listitem>
3001    <para>
3002     The <quote>+fast-redirects</quote> action enables interception of
3003     <quote>redirect</quote> requests from one server to another, which
3004     are used to track users.<application>Privoxy</application> can cut off
3005     all but the last valid URL in redirect request and send a local redirect
3006     back to your browser without contacting the intermediate site(s).
3007    </para>
3008   </listitem>
3009  </varlistentry>
3010
3011  <varlistentry>
3012   <term>Possible values:</term>
3013   <listitem>
3014    <para>
3015     N/A
3016    </para>
3017   </listitem>
3018  </varlistentry>
3019
3020  <varlistentry>
3021   <term>Example usage:</term>
3022   <listitem>
3023     <literallayout>
3024      <emphasis>{+fast-redirects}</emphasis>
3025      <emphasis>.example.com</emphasis>
3026     </literallayout>
3027   </listitem>
3028  </varlistentry>
3029
3030  <varlistentry>
3031   <term>Notes:</term>
3032   <listitem>
3033    <para>
3034     Many sites, like yahoo.com, don't just link to other sites. Instead, they
3035     will link to some script on their own server, giving the destination as a
3036     parameter, which will then redirect you to the final target. URLs
3037     resulting from this scheme typically look like:
3038     <emphasis>http://some.place/some_script?http://some.where-else</emphasis>.
3039   </para>
3040    <para>
3041     Sometimes, there are even multiple consecutive redirects encoded in the
3042     URL. These redirections via scripts make your web browsing more traceable,
3043     since the server from which you follow such a link can see where you go
3044     to. Apart from that, valuable bandwidth and time is wasted, while your
3045     browser ask the server for one redirect after the other. Plus, it feeds
3046     the advertisers.
3047    </para>
3048    <para>
3049     This is a normally on feature, and often requires exceptions for sites that
3050     are sensitive to defeating this mechanism.
3051    </para>
3052   </listitem>
3053  </varlistentry>
3054
3055 </variablelist>
3056 </sect4>
3057
3058
3059 <!--   ~~~~~       New section      ~~~~~     -->
3060 <sect4 id="filter">
3061 <title><emphasis>+filter</emphasis></title>
3062
3063 <variablelist>
3064  <varlistentry>
3065   <term>Type:</term>
3066   <!-- boolean, parameterized, Multi-value -->
3067   <listitem>
3068    <para>Parameterized.</para>
3069   </listitem>
3070  </varlistentry>
3071
3072  <varlistentry>
3073   <term>Typical uses:</term>
3074   <listitem>
3075    <para>
3076     Apply page filtering as defined by named sections of the
3077     <filename>default.filter</filename> file to the specified site(s).
3078     <quote>Filtering</quote> can be any modification of the raw
3079     page content, including re-writing or deletion.
3080    </para>
3081   </listitem>
3082  </varlistentry>
3083
3084  <varlistentry>
3085   <term>Possible values:</term>
3086   <listitem>
3087    <para>
3088     <quote>+filter</quote> must include the name of one of the section identifiers
3089     from <filename>default.filter</filename> (or whatever
3090     <emphasis>filterfile</emphasis> is specified in <filename>config</filename>).
3091    </para>
3092   </listitem>
3093  </varlistentry>
3094
3095  <varlistentry>
3096   <term>Example usage (from the current <filename>default.filter</filename>):</term>
3097   <listitem>
3098    <simplelist>
3099    <member>
3100     <emphasis>+filter{html-annoyances}</emphasis>:  Get rid of particularly annoying HTML abuse.
3101    </member>
3102   </simplelist>
3103   <simplelist>
3104    <member>
3105     <emphasis>+filter{js-annoyances}</emphasis>:    Get rid of particularly annoying JavaScript abuse
3106    </member>
3107   </simplelist>
3108   <simplelist>
3109    <member>
3110     <emphasis>+filter{content-cookies}</emphasis>:   Kill cookies that come in the HTML or JS content
3111    </member>
3112   </simplelist>
3113   <simplelist>
3114    <member>
3115     <emphasis>+filter{popups}</emphasis>:         Kill all popups in JS and HTML
3116    </member>
3117   </simplelist>
3118   <simplelist>
3119    <member>
3120     <emphasis>+filter{frameset-borders}</emphasis>: Give frames a border and make them resizable
3121    </member>
3122   </simplelist>
3123   <simplelist>
3124    <member>
3125     <emphasis>+filter{webbugs}</emphasis>:          Squish WebBugs (1x1 invisible GIFs used for user tracking)
3126    </member>
3127   </simplelist>
3128   <simplelist>
3129    <member>
3130     <emphasis>+filter{refresh-tags}</emphasis>:     Kill automatic refresh tags (for dial-on-demand setups)
3131    </member>
3132   </simplelist>
3133   <simplelist>
3134    <member>
3135     <emphasis>+filter{fun}</emphasis>:              Text replacements  for subversive browsing fun!
3136    </member>
3137   </simplelist>
3138   <simplelist>
3139    <member>
3140     <emphasis>+filter{nimda}</emphasis>:            Remove Nimda (virus) code.
3141    </member>
3142   </simplelist>
3143   <simplelist>
3144    <member>
3145     <emphasis>+filter{banners-by-size}</emphasis>:  Kill banners by size (<emphasis>very</emphasis> efficient!)
3146    </member>
3147   </simplelist>
3148   <simplelist>
3149    <member>
3150     <emphasis>+filter{shockwave-flash}</emphasis>:   Kill embedded Shockwave Flash objects
3151    </member>
3152   </simplelist>
3153   <simplelist>
3154    <member>
3155     <emphasis>+filter{crude-parental}</emphasis>:   Kill all web pages that contain the words "sex" or "warez"
3156    </member>
3157   </simplelist>
3158   </listitem>
3159  </varlistentry>
3160
3161  <varlistentry>
3162   <term>Notes:</term>
3163   <listitem>
3164    <para>
3165     This is potentially a very powerful feature! And requires a knowledge
3166     of regular expressions if you want to <quote>roll your own</quote>.
3167    </para>
3168    <para>
3169     Filtering requires buffering the page content, which may appear to
3170     slow down page rendering since nothing is displayed until all content has
3171     passed the filters. (It does not really take longer, but seems that way
3172     since the page is not incrementally displayed.) This effect will be more
3173     noticeable on slower connections.
3174    </para>
3175   </listitem>
3176  </varlistentry>
3177
3178 </variablelist>
3179 </sect4>
3180
3181
3182 <!--   ~~~~~       New section      ~~~~~     -->
3183 <sect4 id="hide-forwarded">
3184 <title><emphasis>+hide-forwarded</emphasis></title>
3185
3186 <variablelist>
3187  <varlistentry>
3188   <term>Type:</term>
3189   <!-- Boolean, Parameterized, Multi-value -->
3190   <listitem>
3191    <para>Boolean.</para>
3192   </listitem>
3193  </varlistentry>
3194
3195  <varlistentry>
3196   <term>Typical uses:</term>
3197   <listitem>
3198    <para>
3199     Block any existing X-Forwarded-for HTTP header, and do not add a new one.
3200    </para>
3201   </listitem>
3202  </varlistentry>
3203
3204  <varlistentry>
3205   <term>Possible values:</term>
3206   <listitem>
3207    <para>
3208     N/A
3209    </para>
3210   </listitem>
3211  </varlistentry>
3212
3213  <varlistentry>
3214   <term>Example usage:</term>
3215   <listitem>
3216     <literallayout>
3217      <emphasis>{+hide-forwarded}</emphasis>
3218      <emphasis>.example.com</emphasis>
3219     </literallayout>
3220   </listitem>
3221  </varlistentry>
3222
3223  <varlistentry>
3224   <term>Notes:</term>
3225   <listitem>
3226    <para>
3227     It is fairly safe to leave this on. It does not seem to break many sites.
3228    </para>
3229   </listitem>
3230  </varlistentry>
3231
3232 </variablelist>
3233 </sect4>
3234
3235
3236 <!--   ~~~~~       New section      ~~~~~     -->
3237 <sect4 id="hide-from">
3238 <title><emphasis>+hide-from</emphasis></title>
3239
3240 <variablelist>
3241  <varlistentry>
3242   <term>Type:</term>
3243   <!-- Boolean, Parameterized, Multi-value -->
3244   <listitem>
3245    <para>Parameterized.</para>
3246   </listitem>
3247  </varlistentry>
3248
3249  <varlistentry>
3250   <term>Typical uses:</term>
3251   <listitem>
3252    <para>
3253     To block the browser from sending your email address in a <quote>From:</quote>
3254     header.
3255    </para>
3256   </listitem>
3257  </varlistentry>
3258
3259  <varlistentry>
3260   <term>Possible values:</term>
3261   <listitem>
3262    <para>
3263     Keyword: <quote>block</quote>, or any user defined value.
3264    </para>
3265   </listitem>
3266  </varlistentry>
3267
3268  <varlistentry>
3269   <term>Example usage:</term>
3270   <listitem>
3271     <literallayout>
3272      <emphasis>{+hide-from{block}}</emphasis>
3273      <emphasis>.example.com</emphasis>
3274     </literallayout>
3275   </listitem>
3276  </varlistentry>
3277
3278  <varlistentry>
3279   <term>Notes:</term>
3280   <listitem>
3281    <para>
3282     The keyword <quote>block</quote> will completely remove the header.
3283     Alternately, you can specify any value you prefer to send to the web
3284     server.
3285    </para>
3286   </listitem>
3287  </varlistentry>
3288
3289 </variablelist>
3290 </sect4>
3291
3292
3293 <!--   ~~~~~       New section      ~~~~~     -->
3294 <sect4 id="hide-referer">
3295 <title><emphasis>+hide-referer</emphasis></title>
3296 <anchor id="hide-referrer">
3297
3298 <variablelist>
3299  <varlistentry>
3300   <term>Type:</term>
3301   <!-- Boolean, Parameterized, Multi-value -->
3302   <listitem>
3303    <para>Parameterized.</para>
3304   </listitem>
3305  </varlistentry>
3306
3307  <varlistentry>
3308   <term>Typical uses:</term>
3309   <listitem>
3310    <para>
3311      Don't send the <quote>Referer:</quote> (sic) HTTP header to the web site.
3312      Or, alternately send a forged header instead.
3313    </para>
3314   </listitem>
3315  </varlistentry>
3316
3317  <varlistentry>
3318   <term>Possible values:</term>
3319   <listitem>
3320    <para>
3321      Prevent the header from being sent with the keyword, <quote>block</quote>.
3322      Or, <quote>forge</quote> a URL to one from the same server as the request.
3323      Or, set to user defined value of your choice.
3324    </para>
3325   </listitem>
3326  </varlistentry>
3327
3328  <varlistentry>
3329   <term>Example usage:</term>
3330   <listitem>
3331     <literallayout>
3332      <emphasis>{+hide-referer{forge}}</emphasis>
3333      <emphasis>.example.com</emphasis>
3334     </literallayout>
3335   </listitem>
3336  </varlistentry>
3337
3338  <varlistentry>
3339   <term>Notes:</term>
3340   <listitem>
3341    <para>
3342     <quote>forge</quote> is the preferred option here, since some servers will
3343     not send images back otherwise.
3344    </para>
3345   <para>
3346    <quote>+hide-referrer</quote> is an alternate spelling of
3347    <quote>+hide-referer</quote>. It has the exact same parameters, and can be freely
3348    mixed with, <quote>+hide-referer</quote>. (<quote>referrer</quote> is the
3349    correct English spelling, however the HTTP specification has a bug - it
3350    requires it to be spelled as <quote>referer</quote>.)
3351   </para>
3352   </listitem>
3353  </varlistentry>
3354
3355 </variablelist>
3356 </sect4>
3357
3358
3359 <!--   ~~~~~       New section      ~~~~~     -->
3360 <sect4 id="hide-user-agent">
3361 <title><emphasis>+hide-user-agent</emphasis></title>
3362
3363 <variablelist>
3364  <varlistentry>
3365   <term>Type:</term>
3366   <!-- Boolean, Parameterized, Multi-value -->
3367   <listitem>
3368    <para>Parameterized.</para>
3369   </listitem>
3370  </varlistentry>
3371
3372  <varlistentry>
3373   <term>Typical uses:</term>
3374   <listitem>
3375    <para>
3376     To change the <quote>User-Agent:</quote> header so web servers can't tell
3377     your browser type. Who's business is it anyway?
3378    </para>
3379   </listitem>
3380  </varlistentry>
3381
3382  <varlistentry>
3383   <term>Possible values:</term>
3384   <listitem>
3385    <para>
3386     Any user defined string.
3387    </para>
3388   </listitem>
3389  </varlistentry>
3390
3391  <varlistentry>
3392   <term>Example usage:</term>
3393   <listitem>
3394     <literallayout>
3395      <emphasis>{+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}}</emphasis>
3396      <emphasis>.msn.com</emphasis>
3397     </literallayout>
3398   </listitem>
3399  </varlistentry>
3400
3401  <varlistentry>
3402   <term>Notes:</term>
3403   <listitem>
3404    <para>
3405      Warning! This breaks many web sites that depend on this in order
3406      to determine how the target browser will respond to various
3407      requests. Use with caution.
3408    </para>
3409   </listitem>
3410  </varlistentry>
3411
3412 </variablelist>
3413 </sect4>
3414
3415 <!--   ~~~~~       New section      ~~~~~     -->
3416 <sect4 id="image">
3417 <title><emphasis>+image</emphasis></title>
3418
3419 <variablelist>
3420  <varlistentry>
3421   <term>Type:</term>
3422   <!-- Boolean, Parameterized, Multi-value -->
3423   <listitem>
3424    <para>Boolean.</para>
3425   </listitem>
3426  </varlistentry>
3427
3428  <varlistentry>
3429   <term>Typical uses:</term>
3430   <listitem>
3431    <para>
3432     To define what <application>Privoxy</application> should treat
3433     automatically as an image.
3434    </para>
3435   </listitem>
3436  </varlistentry>
3437
3438  <varlistentry>
3439   <term>Possible values:</term>
3440   <listitem>
3441    <para>
3442     N/A
3443    </para>
3444   </listitem>
3445  </varlistentry>
3446
3447  <varlistentry>
3448   <term>Example usage:</term>
3449   <listitem>
3450     <literallayout>
3451      <emphasis>{+image}</emphasis>
3452      <emphasis>/.*\.(gif|jpg|jpeg|png|bmp|ico)</emphasis>
3453     </literallayout>
3454   </listitem>
3455  </varlistentry>
3456
3457  <varlistentry>
3458   <term>Notes:</term>
3459   <listitem>
3460    <para>
3461     This only has meaning if the URL (or pattern) also is
3462     <quote>+block</quote>ed, in which case a <quote>blocked</quote> image can
3463     be sent rather than a HTML page. (See <quote>+image-blocker{}</quote> below
3464     for the control over what is actually sent.)
3465    </para>
3466    <para>
3467     There is little reason to change the default definition for this.
3468    </para>
3469   </listitem>
3470  </varlistentry>
3471
3472 </variablelist>
3473 </sect4>
3474
3475
3476 <!--   ~~~~~       New section      ~~~~~     -->
3477 <sect4 id="image-blocker">
3478 <title><emphasis>+image-blocker</emphasis></title>
3479
3480 <variablelist>
3481  <varlistentry>
3482   <term>Type:</term>
3483   <!-- Boolean, Parameterized, Multi-value -->
3484   <listitem>
3485    <para>Parameterized.</para>
3486   </listitem>
3487  </varlistentry>
3488
3489  <varlistentry>
3490   <term>Typical uses:</term>
3491   <listitem>
3492    <para>
3493     Decide what to do with URLs that end up tagged with both <quote>{+block}</quote>
3494     and <quote>{+image}</quote>, e.g an advertisement.
3495    </para>
3496   </listitem>
3497  </varlistentry>
3498
3499  <varlistentry>
3500   <term>Possible values:</term>
3501   <listitem>
3502    <para>
3503     There are four available options: <quote>-image-blocker</quote> will send a HTML
3504     <quote>blocked</quote> page, usually resulting in a <quote>broken
3505     image</quote> icon. <quote>+image-blocker{blank}</quote> will send a 1x1
3506     transparent GIF image. <quote>+image-blocker{pattern}</quote> will send a
3507     checkerboard type pattern (the default). And finally,
3508     <quote>+image-blocker{http://xyz.com}</quote> will send a HTTP temporary
3509     redirect to the specified image. This has the advantage of the icon being
3510     being cached by the browser, which will speed up the display.
3511    </para>
3512   </listitem>
3513  </varlistentry>
3514
3515  <varlistentry>
3516   <term>Example usage:</term>
3517   <listitem>
3518     <literallayout>
3519      <emphasis>{+image-blocker{blank}}</emphasis>
3520      <emphasis>.example.com</emphasis>
3521     </literallayout>
3522   </listitem>
3523  </varlistentry>
3524
3525  <varlistentry>
3526   <term>Notes:</term>
3527   <listitem>
3528    <para>
3529     If you want <emphasis>invisible</emphasis> ads, they need to be both
3530     defined as <emphasis>images</emphasis> and <emphasis>blocked</emphasis>.
3531     And then, <quote>image-blocker</quote> should be set to
3532     <quote>blank</quote> for invisibility. Note you cannot treat HTML pages as
3533     images in most cases. For instance, frames require an HTML page to display.
3534     So a frame that is an ad, cannot be treated as an image. Forcing an
3535     <quote>image</quote> in this situation just will not work.
3536    </para>
3537   </listitem>
3538  </varlistentry>
3539
3540 </variablelist>
3541 </sect4>
3542
3543 <!--   ~~~~~       New section      ~~~~~     -->
3544 <sect4 id="limit-connect">
3545 <title><emphasis>+limit-connect</emphasis></title>
3546
3547 <variablelist>
3548  <varlistentry>
3549   <term>Type:</term>
3550   <!-- Boolean, Parameterized, Multi-value -->
3551   <listitem>
3552    <para>Parameterized.</para>
3553   </listitem>
3554  </varlistentry>
3555
3556  <varlistentry>
3557   <term>Typical uses:</term>
3558   <listitem>
3559    <para>
3560     By default, <application>Privoxy</application> only allows HTTP CONNECT
3561     requests to port 443 (the standard, secure HTTPS port). Use
3562     <quote>+limit-connect</quote> to disable this altogether, or to allow
3563     more ports.
3564    </para>
3565   </listitem>
3566  </varlistentry>
3567
3568  <varlistentry>
3569   <term>Possible values:</term>
3570   <listitem>
3571    <para>
3572     Any valid port number, or port number range.
3573    </para>
3574   </listitem>
3575  </varlistentry>
3576
3577  <varlistentry>
3578   <term>Example usages:</term>
3579   <listitem>
3580    <!-- I had trouble getting the spacing to look right in my browser -->
3581    <!-- I probably have the wrong font setup, bollocks. -->
3582     <literallayout>
3583      <emphasis>+limit-connect{443}</emphasis>                      # This is the default and need not be specified.
3584      <emphasis>+limit-connect{80,443}</emphasis>                 # Ports 80 and 443 are OK.
3585      <emphasis>+limit-connect{-3, 7, 20-100, 500-}</emphasis> # Port less than 3, 7, 20 to 100 and above 500 are OK.
3586     </literallayout>
3587   </listitem>
3588  </varlistentry>
3589
3590  <varlistentry>
3591   <term>Notes:</term>
3592   <listitem>
3593    <para>
3594     The CONNECT methods exists in HTTP to allow access to secure websites
3595     (https:// URLs) through proxies. It works very simply: the proxy connects
3596     to the server on the specified port, and then short-circuits its
3597     connections to the client <emphasis>and</emphasis> to the remote proxy.
3598     This can be a big security hole, since CONNECT-enabled proxies can be
3599     abused as TCP relays very easily.
3600   </para>
3601   <para>
3602    If you want to allow CONNECT for more ports than this, or want to forbid
3603    CONNECT altogether, you can specify a comma separated list of ports and
3604    port ranges (the latter using dashes, with the minimum defaulting to 0 and
3605    max to 65K).
3606   </para>
3607   <para>
3608    If you don't know what any of this means, there probably is no reason to
3609    change this one.
3610   </para>
3611   </listitem>
3612  </varlistentry>
3613
3614 </variablelist>
3615 </sect4>
3616
3617 <!--   ~~~~~       New section      ~~~~~     -->
3618 <sect4 id="no-compression">
3619 <title><emphasis>+no-compression</emphasis></title>
3620
3621 <variablelist>
3622  <varlistentry>
3623   <term>Type:</term>
3624   <!-- Boolean, Parameterized, Multi-value -->
3625   <listitem>
3626    <para>Boolean.</para>
3627   </listitem>
3628  </varlistentry>
3629
3630  <varlistentry>
3631   <term>Typical uses:</term>
3632   <listitem>
3633    <para>
3634     Prevent the specified websites from compressing HTTP data.
3635    </para>
3636   </listitem>
3637  </varlistentry>
3638
3639  <varlistentry>
3640   <term>Possible values:</term>
3641   <listitem>
3642    <para>
3643     N/A
3644    </para>
3645   </listitem>
3646  </varlistentry>
3647
3648  <varlistentry>
3649   <term>Example usage:</term>
3650   <listitem>
3651     <literallayout>
3652      <emphasis>{+no-compression}</emphasis>
3653      <emphasis>.example.com</emphasis>
3654     </literallayout>
3655   </listitem>
3656  </varlistentry>
3657
3658  <varlistentry>
3659   <term>Notes:</term>
3660   <listitem>
3661    <para>
3662     Some websites do this, which can be a problem for
3663     <application>Privoxy</application>, since <quote>+filter</quote>,
3664     <quote>+no-popup</quote> and <quote>+gif-deanimate</quote> will not work
3665     on compressed data. This will slow down connections to those websites,
3666     though. Default typically is to turn <quote>no-compression</quote> on.
3667    </para>
3668   </listitem>
3669  </varlistentry>
3670
3671 </variablelist>
3672 </sect4>
3673
3674 <!--   ~~~~~       New section      ~~~~~     -->
3675 <sect4 id="no-cookies-keep">
3676 <title><emphasis>+no-cookies-keep</emphasis></title>
3677
3678 <variablelist>
3679  <varlistentry>
3680   <term>Type:</term>
3681   <!-- Boolean, Parameterized, Multi-value -->
3682   <listitem>
3683    <para>Boolean.</para>
3684   </listitem>
3685  </varlistentry>
3686
3687  <varlistentry>
3688   <term>Typical uses:</term>
3689   <listitem>
3690    <para>
3691     Allow cookies for the current browser session only.
3692    </para>
3693   </listitem>
3694  </varlistentry>
3695
3696  <varlistentry>
3697   <term>Possible values:</term>
3698   <listitem>
3699    <para>
3700     N/A
3701    </para>
3702   </listitem>
3703  </varlistentry>
3704
3705  <varlistentry>
3706   <term>Example usage:</term>
3707   <listitem>
3708     <literallayout>
3709      <emphasis>{+no-cookies-keep}</emphasis>
3710      <emphasis>.example.com</emphasis>
3711     </literallayout>
3712   </listitem>
3713  </varlistentry>
3714
3715  <varlistentry>
3716   <term>Notes:</term>
3717   <listitem>
3718    <para>
3719     If websites set cookies, <quote>no-cookies-keep</quote> will make sure
3720     they are erased when you exit and restart your web browser. This makes
3721     profiling cookies useless, but won't break sites which require cookies so
3722     that you can log in for transactions. This is generally turned on for all
3723     sites. Sometimes referred to as <quote>session cookies</quote>.
3724    </para>
3725   </listitem>
3726  </varlistentry>
3727
3728 </variablelist>
3729 </sect4>
3730
3731
3732 <!--   ~~~~~       New section      ~~~~~     -->
3733 <sect4 id="no-cookies-read">
3734 <title><emphasis>+no-cookies-read</emphasis></title>
3735
3736 <variablelist>
3737  <varlistentry>
3738   <term>Type:</term>
3739   <!-- Boolean, Parameterized, Multi-value -->
3740   <listitem>
3741    <para>Boolean.</para>
3742   </listitem>
3743  </varlistentry>
3744
3745  <varlistentry>
3746   <term>Typical uses:</term>
3747   <listitem>
3748    <para>
3749     Explicitly prevent the web server from reading any cookies on your
3750     system.
3751    </para>
3752   </listitem>
3753  </varlistentry>
3754
3755  <varlistentry>
3756   <term>Possible values:</term>
3757   <listitem>
3758    <para>
3759     N/A
3760    </para>
3761   </listitem>
3762  </varlistentry>
3763
3764  <varlistentry>
3765   <term>Example usage:</term>
3766   <listitem>
3767     <literallayout>
3768      <emphasis>{+no-cookies-read}</emphasis>
3769      <emphasis>.example.com</emphasis>
3770     </literallayout>
3771   </listitem>
3772  </varlistentry>
3773
3774  <varlistentry>
3775   <term>Notes:</term>
3776   <listitem>
3777    <para>
3778     Often used in conjunction with <quote>+no-cookies-set</quote> to
3779     disable persistant cookies completely.
3780    </para>
3781   </listitem>
3782  </varlistentry>
3783
3784 </variablelist>
3785 </sect4>
3786
3787
3788 <!--   ~~~~~       New section      ~~~~~     -->
3789 <sect4 id="no-cookies-set">
3790 <title><emphasis>+no-cookies-set</emphasis></title>
3791
3792 <variablelist>
3793  <varlistentry>
3794   <term>Type:</term>
3795   <!-- Boolean, Parameterized, Multi-value -->
3796   <listitem>
3797    <para>Boolean.</para>
3798   </listitem>
3799  </varlistentry>
3800
3801  <varlistentry>
3802   <term>Typical uses:</term>
3803   <listitem>
3804    <para>
3805     Explicitly block the web server from sending cookies to your
3806     system.
3807    </para>
3808   </listitem>
3809  </varlistentry>
3810
3811  <varlistentry>
3812   <term>Possible values:</term>
3813   <listitem>
3814    <para>
3815     N/A
3816    </para>
3817   </listitem>
3818  </varlistentry>
3819
3820  <varlistentry>
3821   <term>Example usage:</term>
3822   <listitem>
3823     <literallayout>
3824      <emphasis>{+no-cookies-set}</emphasis>
3825      <emphasis>.example.com</emphasis>
3826     </literallayout>
3827   </listitem>
3828  </varlistentry>
3829
3830  <varlistentry>
3831   <term>Notes:</term>
3832   <listitem>
3833    <para>
3834     Often used in conjunction with <quote>+no-cookies-read</quote> to
3835     disable persistant cookies completely.
3836    </para>
3837   </listitem>
3838  </varlistentry>
3839
3840 </variablelist>
3841 </sect4>
3842
3843
3844 <!--   ~~~~~       New section      ~~~~~     -->
3845 <sect4 id="no-popup">
3846 <title><emphasis>+no-popup</emphasis></title>
3847 <anchor id="no-popups">
3848
3849 <variablelist>
3850  <varlistentry>
3851   <term>Type:</term>
3852   <!-- Boolean, Parameterized, Multi-value -->
3853   <listitem>
3854    <para>Boolean.</para>
3855   </listitem>
3856  </varlistentry>
3857
3858  <varlistentry>
3859   <term>Typical uses:</term>
3860   <listitem>
3861    <para>
3862     Stop those annoying JavaScript pop-up windows!
3863    </para>
3864   </listitem>
3865  </varlistentry>
3866
3867  <varlistentry>
3868   <term>Possible values:</term>
3869   <listitem>
3870    <para>
3871     N/A
3872    </para>
3873   </listitem>
3874  </varlistentry>
3875
3876  <varlistentry>
3877   <term>Example usage:</term>
3878   <listitem>
3879     <literallayout>
3880      <emphasis>{+no-popup}</emphasis>
3881      <emphasis>.example.com</emphasis>
3882     </literallayout>
3883   </listitem>
3884  </varlistentry>
3885
3886  <varlistentry>
3887   <term>Notes:</term>
3888   <listitem>
3889    <para>
3890     <quote>+no-popup</quote> uses a built in filter to disable pop-ups
3891     that use the <literal>window.open()</literal> function, etc.
3892    </para>
3893    <para>
3894     An alternate spelling is <quote>+no-popups</quote>, which is
3895     interchangeable.
3896    </para>
3897   </listitem>
3898  </varlistentry>
3899
3900 </variablelist>
3901 </sect4>
3902
3903
3904 <!--   ~~~~~       New section      ~~~~~     -->
3905 <sect4 id="vanilla-wafer">
3906 <title><emphasis>+vanilla-wafer</emphasis></title>
3907
3908 <variablelist>
3909  <varlistentry>
3910   <term>Type:</term>
3911   <!-- Boolean, Parameterized, Multi-value -->
3912   <listitem>
3913    <para>Boolean.</para>
3914   </listitem>
3915  </varlistentry>
3916
3917  <varlistentry>
3918   <term>Typical uses:</term>
3919   <listitem>
3920    <para>
3921     Sends a cookie for every site stating that you do not accept any copyright
3922     on cookies sent to you, and asking them not to track you.
3923    </para>
3924   </listitem>
3925  </varlistentry>
3926
3927  <varlistentry>
3928   <term>Possible values:</term>
3929   <listitem>
3930    <para>
3931     N/A
3932    </para>
3933   </listitem>
3934  </varlistentry>
3935
3936  <varlistentry>
3937   <term>Example usage:</term>
3938   <listitem>
3939     <literallayout>
3940      <emphasis>{+vanilla-wafer}</emphasis>
3941      <emphasis>.example.com</emphasis>
3942     </literallayout>
3943   </listitem>
3944  </varlistentry>
3945
3946  <varlistentry>
3947   <term>Notes:</term>
3948   <listitem>
3949    <para>
3950     This action only applies if you are using a <filename>jarfile</filename>
3951     for saving cookies. Of course, this is a (relatively) unique header and
3952     could be used to track you.
3953    </para>
3954   </listitem>
3955  </varlistentry>
3956
3957 </variablelist>
3958 </sect4>
3959
3960
3961 <!--   ~~~~~       New section      ~~~~~     -->
3962 <sect4 id="wafer">
3963 <title><emphasis>+wafer</emphasis></title>
3964
3965 <variablelist>
3966  <varlistentry>
3967   <term>Type:</term>
3968   <!-- Boolean, Parameterized, Multi-value -->
3969   <listitem>
3970    <para>Multi-value.</para>
3971   </listitem>
3972  </varlistentry>
3973
3974  <varlistentry>
3975   <term>Typical uses:</term>
3976   <listitem>
3977    <para>
3978     This allows you to send an arbitrary, user definable cookie.
3979    </para>
3980   </listitem>
3981  </varlistentry>
3982
3983  <varlistentry>
3984   <term>Possible values:</term>
3985   <listitem>
3986    <para>
3987     User specified cookie name and corresponding value.
3988    </para>
3989   </listitem>
3990  </varlistentry>
3991
3992  <varlistentry>
3993   <term>Example usage:</term>
3994   <listitem>
3995     <literallayout>
3996      <emphasis>{+wafer{name=value}}</emphasis>
3997      <emphasis>.example.com</emphasis>
3998     </literallayout>
3999   </listitem>
4000  </varlistentry>
4001
4002  <varlistentry>
4003   <term>Notes:</term>
4004   <listitem>
4005    <para>
4006     This can be specified multiple times in order to add as many cookies as you
4007     like.
4008    </para>
4009   </listitem>
4010  </varlistentry>
4011
4012 </variablelist>
4013 </sect4>
4014
4015
4016 <!--   ~~~~~       New section      ~~~~~     -->
4017 <sect4 id="act-examples" renderas="sect3">
4018 <title>Actions Examples</title>
4019 <para>
4020  Note that the meaning of any of the above examples is reversed by preceding
4021  the action with a <quote>-</quote>, in place of the <quote>+</quote>. Also,
4022  that some actions are turned on in the default section of the actions file,
4023  and require little to no additional configuration. These are just <quote>on</quote>.
4024  Some actions that are turned on the default section do typically require
4025  exceptions to be listed in the lower sections of actions file.
4026 </para>
4027
4028 <para>
4029  Some examples:
4030 </para>
4031
4032 <para>
4033  Turn off cookies by default, then allow a few through for specified sites:
4034 </para>
4035
4036 <para>
4037  <literal>
4038   <msgtext>
4039    <literallayout>
4040  # Turn off all persistent cookies
4041  { +no-cookies-read }
4042  { +no-cookies-set }
4043
4044  # Allow cookies for this browser session ONLY
4045  { +no-cookies-keep }
4046
4047  # Exceptions to the above, sites that benefit from persistent cookies
4048  # that saved from one browser session to the next.
4049  { -no-cookies-read }
4050  { -no-cookies-set }
4051  { -no-cookies-keep }
4052  .javasoft.com
4053  .sun.com
4054  .yahoo.com
4055  .msdn.microsoft.com
4056  .redhat.com
4057
4058  # Alternative way of saying the same thing
4059  {-no-cookies-set -no-cookies-read -no-cookies-keep}
4060  .sourceforge.net
4061  .sf.net
4062    </literallayout>
4063   </msgtext>
4064  </literal>
4065 </para>
4066
4067 <para>
4068  Now turn off <quote>fast redirects</quote>, and then we allow two exceptions:
4069 </para>
4070
4071 <para>
4072  <literal>
4073   <msgtext>
4074    <literallayout>
4075  # Turn them off!
4076  {+fast-redirects}
4077
4078  # Reverse it for these two sites, which don't work right without it.
4079  {-fast-redirects}
4080  www.ukc.ac.uk/cgi-bin/wac\.cgi\?
4081  login.yahoo.com
4082    </literallayout>
4083   </msgtext>
4084  </literal>
4085 </para>
4086
4087 <para>
4088  Turn on page filtering according to rules in the defined sections
4089  of <filename>default.filter</filename>, and make one exception for
4090  Sourceforge:
4091  </para>
4092
4093 <para>
4094  <literal>
4095   <msgtext>
4096    <literallayout>
4097  # Run everything through the filter file, using only the
4098  # specified sections:
4099  +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}\
4100  +filter{webbugs} +filter{nimda} +filter{banners-by-size}
4101
4102  # Then disable filtering of code from sourceforge!
4103  {-filter}
4104  .cvs.sourceforge.net
4105    </literallayout>
4106   </msgtext>
4107  </literal>
4108 </para>
4109
4110 <para>
4111  Now some URLs that we want <quote>blocked</quote> (normally generates
4112  the <quote>blocked</quote> banner). Many of these use
4113  <link linkend="regex">regular expressions</link> that will expand to match
4114  multiple URLs: </para>
4115
4116 <para>
4117  <literal>
4118   <msgtext>
4119    <literallayout>
4120   # Blocklist:
4121   {+block}
4122   /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g))
4123   /.*/(.*[-_.])?count(er)?(\.cgi|\.dll|\.exe|[?/])
4124   /.*/(ng)?adclient\.cgi
4125   /.*/(plain|live|rotate)[-_.]?ads?/
4126   /.*/(sponsor)s?[0-9]?/
4127   /.*/_?(plain|live)?ads?(-banners)?/
4128   /.*/abanners/
4129   /.*/ad(sdna_image|gifs?)/
4130   /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe)
4131   /.*/adbanners/
4132   /.*/adserver
4133   /.*/adstream\.cgi
4134   /.*/adv((er)?ts?|ertis(ing|ements?))?/
4135   /.*/banner_?ads/
4136   /.*/banners?/
4137   /.*/banners?\.cgi/
4138   /.*/cgi-bin/centralad/getimage
4139   /.*/images/addver\.gif
4140   /.*/images/marketing/.*\.(gif|jpe?g)
4141   /.*/popupads/
4142   /.*/siteads/
4143   /.*/sponsor.*\.gif
4144   /.*/sponsors?[0-9]?/
4145   /.*/advert[0-9]+\.jpg
4146   /Media/Images/Adds/
4147   /ad_images/
4148   /adimages/
4149   /.*/ads/
4150   /bannerfarm/
4151   /grafikk/annonse/
4152   /graphics/defaultAd/
4153   /image\.ng/AdType
4154   /image\.ng/transactionID
4155   /images/.*/.*_anim\.gif # alvin brattli
4156   /ip_img/.*\.(gif|jpe?g)
4157   /rotateads/
4158   /rotations/
4159   /worldnet/ad\.cgi
4160   /cgi-bin/nph-adclick.exe/
4161   /.*/Image/BannerAdvertising/
4162   /.*/ad-bin/
4163   /.*/adlib/server\.cgi
4164   /autoads/
4165    </literallayout>
4166   </msgtext>
4167  </literal>
4168 </para>
4169
4170 <para>
4171  Note that many of these actions have the potential to cause a page to
4172  misbehave, possibly even not to display at all. There are many ways
4173  a site designer may choose to design his site, and what HTTP header
4174  content he may depend on. There is no way to have hard and fast rules
4175  for all sites. See the <link linkend="ACTIONSANAT">Appendix</link>
4176  for a brief example on troubleshooting actions.
4177 </para>
4178 </sect4>
4179
4180 </sect3>
4181
4182 <!--  ~  End section  ~  -->
4183
4184
4185 <!--   ~~~~~       New section      ~~~~~     -->
4186 <sect3>
4187 <title>Aliases</title>
4188 <para>
4189  Custom <quote>actions</quote>, known to <application>Privoxy</application>
4190  as <quote>aliases</quote>, can be defined by combining other <quote>actions</quote>.
4191  These can in turn be invoked just like the built-in <quote>actions</quote>.
4192  Currently, an alias can contain any character except space, tab, <quote>=</quote>,
4193  <quote>{</quote> or <quote>}</quote>. But please use only <quote>a</quote>-
4194  <quote>z</quote>, <quote>0</quote>-<quote>9</quote>, <quote>+</quote>, and
4195  <quote>-</quote>. Alias names are not case sensitive, and
4196  <emphasis>must be defined  before anything</emphasis> else in the
4197  <filename>default.action</filename>file! And there can only be one set of
4198  <quote>aliases</quote> defined.
4199 </para>
4200
4201 <para>
4202  Now let's define a few aliases:
4203 </para>
4204
4205 <para>
4206  <literal>
4207   <msgtext>
4208    <literallayout>
4209  # Useful custom aliases we can use later. These must come first!
4210  {{alias}}
4211  +no-cookies = +no-cookies-set +no-cookies-read
4212  -no-cookies = -no-cookies-set -no-cookies-read
4213  fragile     = -block -no-cookies -filter -fast-redirects -hide-referer -no-popups
4214  shop        = -no-cookies -filter -fast-redirects
4215  +imageblock = +block +image
4216
4217  #For people who don't like to type too much:  ;-)
4218  c0 = +no-cookies
4219  c1 = -no-cookies
4220  c2 = -no-cookies-set +no-cookies-read
4221  c3 = +no-cookies-set -no-cookies-read
4222  #... etc.  Customize to your heart's content.
4223    </literallayout>
4224   </msgtext>
4225  </literal>
4226 </para>
4227
4228 <para>
4229  Some examples using our <quote>shop</quote> and <quote>fragile</quote>
4230  aliases from above:
4231 </para>
4232
4233 <para>
4234  <literal>
4235   <msgtext>
4236    <literallayout>
4237  # These sites are very complex and require
4238  # minimal interference.
4239  {fragile}
4240  .office.microsoft.com
4241  .windowsupdate.microsoft.com
4242  .nytimes.com
4243
4244  # Shopping sites - but we still want to block ads.
4245  {shop}
4246  .quietpc.com
4247  .worldpay.com   # for quietpc.com
4248  .jungle.com
4249  .scan.co.uk
4250
4251  # These shops require pop-ups also
4252  {shop -no-popups}
4253  .dabs.com
4254  .overclockers.co.uk
4255    </literallayout>
4256   </msgtext>
4257  </literal>
4258 </para>
4259
4260 <para>
4261  The <quote>shop</quote> and <quote>fragile</quote> aliases are often used for
4262  <quote>problem</quote> sites that require most actions to be disabled
4263  in order to function properly.
4264
4265 </para>
4266
4267 </sect3>
4268 </sect2>
4269
4270 <!--  ~  End section  ~  -->
4271
4272
4273 <!--   ~~~~~       New section      ~~~~~     -->
4274 <sect2 id="filterfile">
4275 <title>The Filter File</title>
4276 <para>
4277  Any web page can be dynamically modified with the filter file. This
4278  modification can be removal, or re-writing, of any web page content,
4279  including tags and non-visible content. The default filter file is
4280  <filename>default.filter</filename>, located in the config directory.
4281 </para>
4282
4283 <para>
4284  This is potentially a very powerful feature, and requires knowledge of both
4285  <quote>regular expression</quote> and HTML in order create custom
4286  filters. But, there are a number of useful filters included with
4287  <application>Privoxy</application> for many common situations.
4288 </para>
4289
4290 <para>
4291  The included example file is divided into sections. Each section begins
4292  with the <literal>FILTER</literal> keyword, followed by the identifier
4293  for that section, e.g. <quote>FILTER: webbugs</quote>. Each section performs
4294  a similar type of filtering, such as <quote>html-annoyances</quote>.
4295 </para>
4296
4297 <para>
4298  This file uses regular expressions to alter or remove any string in the
4299  target page. The expressions can only operate on one line at a time. Some
4300  examples from the included default <filename>default.filter</filename>:
4301 </para>
4302
4303 <para>
4304  Stop web pages from displaying annoying messages in the status bar by
4305  deleting such references:
4306 </para>
4307
4308 <para>
4309  <literal>
4310   <msgtext>
4311    <literallayout>
4312  FILTER: html-annoyances
4313
4314  # New browser windows should be resizeable and have a location and status
4315  # bar. Make it so.
4316  #
4317  s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig
4318  s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig
4319  s/scrolling="?(no|0|Auto)"?/scrolling=1/ig
4320  s/menubar="?(no|0)"?/menubar=1/ig
4321
4322  # The &lt;BLINK&gt; tag was a crime!
4323  #
4324  s*&lt;blink&gt;|&lt;/blink&gt;**ig
4325
4326  # Is this evil?
4327  #
4328  #s/framespacing="?(no|0)"?//ig
4329  #s/margin(height|width)=[0-9]*//gi
4330    </literallayout>
4331   </msgtext>
4332  </literal>
4333 </para>
4334
4335 <para>
4336  Just for kicks, replace any occurrence of <quote>Microsoft</quote> with
4337  <quote>MicroSuck</quote>, and have a little fun with topical buzzwords:
4338 </para>
4339
4340 <para>
4341  <literal>
4342   <msgtext>
4343    <literallayout>
4344  FILTER: fun
4345
4346  s/microsoft(?!.com)/MicroSuck/ig
4347
4348  # Buzzword Bingo:
4349  #
4350  s/industry-leading|cutting-edge|award-winning/&lt;font color=red&gt;&lt;b&gt;BINGO!&lt;/b&gt;&lt;/font&gt;/ig
4351    </literallayout>
4352   </msgtext>
4353  </literal>
4354 </para>
4355
4356 <para>
4357  Kill those pesky little web-bugs:
4358 </para>
4359
4360 <para>
4361  <literal>
4362   <msgtext>
4363    <literallayout>
4364  # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
4365  FILTER: webbugs
4366
4367  s/&lt;img\s+[^&gt;]*?(width|height)\s*=\s*['"]?1\D[^&gt;]*?(width|height)\s*=\s*['"]?1(\D[^&gt;]*?)?>/&lt;!-- Squished WebBug --&gt;/sig
4368    </literallayout>
4369   </msgtext>
4370  </literal>
4371 </para>
4372
4373 </sect2>
4374
4375 <!--  ~  End section  ~  -->
4376
4377
4378
4379 <!--   ~~~~~       New section      ~~~~~     -->
4380
4381 <sect2>
4382 <title>Templates</title>
4383 <para>
4384  When <application>Privoxy</application> displays one of its internal
4385  pages, such as a 404 Not Found error page, it uses the appropriate template.
4386  On Linux, BSD, and Unix, these are located in
4387  <filename>/etc/privoxy/templates</filename> by default. These may be
4388  customized, if desired. <filename>cgi-style.css</filename> is
4389  used to control the HTML attributes (fonts, etc).
4390 </para>
4391 <para>
4392  The default <quote>Blocked</quote> banner page with the bright red top
4393  banner, is called just <quote><filename>blocked</filename></quote>. This
4394  may be customized or replaced with something else if desired.
4395
4396 </para>
4397 </sect2>
4398
4399 </sect1>
4400
4401 <!--  ~  End section  ~  -->
4402
4403
4404
4405 <!--   ~~~~~       New section      ~~~~~     -->
4406
4407 <sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
4408 Requests</title>
4409
4410 <!-- Include contacting.sgml boilerplate: -->
4411  &contacting;
4412 <!-- end boilerplate -->
4413
4414
4415 <!--   ~~~~~       New section      ~~~~~     -->
4416 <sect2 id="submitactions">
4417 <title>Submitting Ads and <quote>Action</quote> Problems</title>
4418 <para>
4419  Ads and banners that are not stopped by <application>Privoxy</application>
4420  can be submitted to the developers by accessing a special page and filling
4421  out the brief, required form. Conversely, you can also report pages, images,
4422  etc. that <application>Privoxy</application> is blocking, but should not.
4423  The form itself does require Internet access.
4424 </para>
4425 <para>
4426  To do this, point your browser to <application>Privoxy</application>
4427  at <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
4428  (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>), and then select
4429  <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions','Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Actions file feedback system</ulink>,
4430  near the bottom of the page. Paste in the URL that is the cause of the
4431  unwanted behavior, and follow the prompts. The developers will
4432  try to incorporate a fix for the problem you reported into future versions.
4433 </para>
4434
4435 <para>
4436  New <filename>default.actions</filename> files will occasionally be made
4437  available based on your feedback. These
4438  will be announced on the
4439  <ulink
4440  url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce">ijbswa-announce</ulink>
4441  list.
4442 </para>
4443 </sect2>
4444
4445 </sect1>
4446
4447
4448 <!--   ~~~~~       New section      ~~~~~     -->
4449 <sect1 id="copyright"><title>Copyright and History</title>
4450
4451 <sect2><title>Copyright</title>
4452 <!-- Include copyright.sgml: -->
4453  &copyright;
4454 <!-- end copyright -->
4455 </sect2>
4456
4457 <!--  ~  End section  ~  -->
4458
4459
4460 <!--   ~~~~~       New section      ~~~~~     -->
4461
4462 <sect2 id="history"><title>History</title>
4463 <!-- Include history.sgml: -->
4464  &history;
4465 <!-- end history -->
4466 </sect2>
4467 </sect1>
4468
4469 <!--   ~~~~~       New section      ~~~~~     -->
4470 <sect1 id="seealso"><title>See Also</title>
4471 <!-- Include seealso.sgml: -->
4472  &seealso;
4473 <!-- end seealso -->
4474 </sect1>
4475
4476
4477
4478 <!--   ~~~~~       New section      ~~~~~     -->
4479 <sect1 id="appendix"><title>Appendix</title>
4480
4481
4482 <!--   ~~~~~       New section      ~~~~~     -->
4483 <sect2 id="regex">
4484 <title>Regular Expressions</title>
4485 <para>
4486  <application>Privoxy</application> can use <quote>regular expressions</quote>
4487  in various config files. Assuming support for <quote>pcre</quote> (Perl
4488  Compatible Regular Expressions) is compiled in, which is the default. Such
4489  configuration directives do not require regular expressions, but they can be
4490  used to increase flexibility by matching a pattern with wild-cards against
4491  URLs.
4492 </para>
4493
4494 <para>
4495  If you are reading this, you probably don't understand what <quote>regular
4496  expressions</quote> are, or what they can do. So this will be a very brief
4497  introduction only. A full explanation would require a book ;-)
4498 </para>
4499
4500 <para>
4501  <quote>Regular expressions</quote> is a way of matching one character
4502  expression against another to see if it matches or not. One of the
4503  <quote>expressions</quote> is a literal string of readable characters
4504  (letter, numbers, etc), and the other is a complex string of literal
4505  characters combined with wild-cards, and other special characters, called
4506  meta-characters. The <quote>meta-characters</quote> have special meanings and
4507  are used to build the complex pattern to be matched against. Perl Compatible
4508  Regular Expressions is an enhanced form of the regular expression language
4509  with backward compatibility.
4510 </para>
4511
4512 <para>
4513  To make a simple analogy, we do something similar when we use wild-card
4514  characters when listing files with the <command>dir</command> command in DOS.
4515  <literal>*.*</literal> matches all filenames. The <quote>special</quote>
4516  character here is the asterisk which matches any and all characters. We can be
4517  more specific and use <literal>?</literal> to match just individual
4518  characters. So <quote>dir file?.text</quote> would match
4519  <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
4520  matching, using a similar technique to <quote>regular expressions</quote>!
4521 </para>
4522
4523 <para>
4524  Regular expressions do essentially the same thing, but are much, much more
4525  powerful. There are many more <quote>special characters</quote> and ways of
4526  building complex patterns however. Let's look at a few of the common ones,
4527  and then some examples:
4528 </para>
4529
4530 <para><simplelist>
4531  <member>
4532   <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
4533   <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
4534  </member>
4535 </simplelist></para>
4536
4537 <para><simplelist>
4538  <member>
4539   <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
4540   times. Either/or.
4541  </member>
4542 </simplelist></para>
4543
4544 <para><simplelist>
4545  <member>
4546   <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
4547   times.
4548  </member>
4549 </simplelist></para>
4550
4551 <para><simplelist>
4552  <member>
4553   <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
4554   times.
4555  </member>
4556 </simplelist></para>
4557
4558 <para><simplelist>
4559  <member>
4560   <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
4561   the following character should be taken literally. This is used where one of the
4562   special characters (e.g. <quote>.</quote>) needs to be taken literally and
4563   not as a special meta-character. Example: <quote>example\.com</quote>, makes
4564   sure the period is recognized only as a period (and not expanded to its
4565   metacharacter meaning of any single character).
4566  </member>
4567 </simplelist></para>
4568
4569 <para><simplelist>
4570  <member>
4571   <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
4572   any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
4573   matches any numeric digit (zero through nine). As an example, we can combine
4574   this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
4575  </member>
4576 </simplelist></para>
4577
4578 <para><simplelist>
4579  <member>
4580   <emphasis>()</emphasis> - parentheses are used to group a sub-expression,
4581   or multiple sub-expressions.
4582  </member>
4583 </simplelist></para>
4584
4585 <para><simplelist>
4586  <member>
4587   <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
4588   <quote>or</quote> conditional statement. A match is successful if the
4589   sub-expression on either side of <quote>|</quote> matches. As an example:
4590   <quote>/(this|that) example/</quote> uses grouping and the bar character
4591   and would match either <quote>this example</quote> or <quote>that
4592   example</quote>, and nothing else.
4593  </member>
4594 </simplelist></para>
4595
4596 <para><simplelist>
4597  <member>
4598   <emphasis>s/string1/string2/g</emphasis> - This is used to rewrite strings of text.
4599   <quote>string1</quote> is replaced by <quote>string2</quote> in this
4600   example. There must of course be a match on <quote>string1</quote> first.
4601  </member>
4602 </simplelist></para>
4603
4604 <para>
4605  These are just some of the ones you are likely to use when matching URLs with
4606  <application>Privoxy</application>, and is a long way from a definitive
4607  list. This is enough to get us started with a few simple examples which may
4608  be more illuminating:
4609 </para>
4610
4611 <para>
4612  <emphasis><literal>/.*/banners/.*</literal></emphasis> - A  simple example
4613  that uses the common combination of <quote>.</quote> and <quote>*</quote> to
4614  denote any character, zero or more times. In other words, any string at all.
4615  So we start with a literal forward slash, then our regular expression pattern
4616  (<quote>.*</quote>) another literal forward slash, the string
4617  <quote>banners</quote>, another forward slash, and lastly another
4618  <quote>.*</quote>. We are building
4619  a directory path here. This will match any file with the path that has a
4620  directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
4621  any characters, and this could conceivably be more forward slashes, so it
4622  might expand into a much longer looking path. For example, this could match:
4623  <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
4624  <quote>/banners/annoying.html</quote>, or almost an infinite number of other
4625  possible combinations, just so it has <quote>banners</quote> in the path
4626  somewhere.
4627 </para>
4628
4629 <para>
4630  A now something a little more complex:
4631 </para>
4632
4633 <para>
4634  <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
4635  We have several literal forward slashes again (<quote>/</quote>), so we are
4636  building another expression that is a file path statement. We have another
4637  <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
4638  it matches our expression. The only true literal that <emphasis>must
4639  match</emphasis> our pattern is <application>adv</application>, together with
4640  the forward slashes. What comes after the <quote>adv</quote> string is the
4641  interesting part.
4642 </para>
4643
4644 <para>
4645  Remember the <quote>?</quote> means the preceding expression (either a
4646  literal character or anything grouped with <quote>(...)</quote> in this case)
4647  can exist or not, since this means either zero or one match. So
4648  <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
4649  individual sub-expressions: <quote>(er)</quote>,
4650  <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
4651  means <quote>or</quote>. We have two of those. For instance,
4652  <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
4653  <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
4654  attempt at matching as many variations of <quote>advertisement</quote>, and
4655  similar, as possible. So this would expand to match just <quote>adv</quote>,
4656  or <quote>advert</quote>, or <quote>adverts</quote>, or
4657  <quote>advertising</quote>, or <quote>advertisement</quote>, or
4658  <quote>advertisements</quote>. You get the idea. But it would not match
4659  <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
4660  changing our regular expression to:
4661  <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
4662  either spelling.
4663 </para>
4664
4665 <para>
4666  <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
4667  another path statement with forward slashes. Anything in the square brackets
4668  <quote>[]</quote> can be matched. This is using <quote>0-9</quote> as a
4669  shorthand expression to mean any digit one through nine. It is the same as
4670  saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
4671  means one or more of the preceding expression must be included. The preceding
4672  expression here is what is in the square brackets -- in this case, any digit
4673  one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
4674  This includes a <quote>|</quote>, so this needs to match the expression on
4675  either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
4676  side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
4677  since the <quote>?</quote> means the letter <quote>e</quote> is optional and
4678  can be matched once or not at all. So we are building an expression here to
4679  match image GIF or JPEG type image file. It must include the literal
4680  string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
4681  (which is now a literal, and not a special character, since it is escaped
4682  with <quote>\</quote>), and lastly either <quote>gif</quote>, or
4683  <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
4684  include: <quote>//advert1.jpg</quote>,
4685  <quote>/nasty/ads/advert1234.gif</quote>,
4686  <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
4687  <quote>advert1.gif</quote> (no leading slash), or
4688  <quote>/adverts232.jpg</quote> (the expression does not include an
4689  <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
4690  in the expression anywhere).
4691 </para>
4692
4693 <para>
4694  <emphasis><literal>s/microsoft(?!.com)/MicroSuck/i</literal></emphasis> - This is
4695  a substitution. <quote>MicroSuck</quote> will replace any occurrence of
4696  <quote>microsoft</quote>.  The <quote>i</quote> at the end of the expression
4697  means ignore case. The <quote>(?!.com)</quote> means
4698  the match should fail if <quote>microsoft</quote> is followed by
4699  <quote>.com</quote>. In other words, this acts like a <quote>NOT</quote>
4700  modifier. In case this is a hyperlink, we don't want to break it ;-).
4701 </para>
4702
4703 <para>
4704  We are barely scratching the surface of regular expressions here so that you
4705  can understand the default <application>Privoxy</application>
4706  configuration files, and maybe use this knowledge to customize your own
4707  installation. There is much, much more that can be done with regular
4708  expressions. Now that you know enough to get started, you can learn more on
4709  your own :/
4710 </para>
4711
4712 <para>
4713  More reading on Perl Compatible Regular expressions:
4714  <ulink url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>
4715 </para>
4716
4717 </sect2>
4718
4719 <!--  ~  End section  ~  -->
4720
4721
4722 <!--   ~~~~~       New section      ~~~~~     -->
4723 <sect2>
4724 <title><application>Privoxy</application>'s Internal Pages</title>
4725
4726 <para>
4727  Since <application>Privoxy</application> proxies each requested
4728  web page, it is easy for <application>Privoxy</application> to
4729  trap certain special URLs. In this way, we can talk directly to
4730  <application>Privoxy</application>, and see how it is
4731  configured, see how our rules are being applied, change these
4732  rules and other configuration options, and even turn
4733  <application>Privoxy's</application> filtering off, all with
4734  a web browser.
4735
4736 </para>
4737
4738 <para>
4739  The URLs listed below are the special ones that allow direct access
4740  to <application>Privoxy</application>. Of course,
4741  <application>Privoxy</application> must be running to access these. If
4742  not, you will get a friendly error message. Internet access is not
4743  necessary either.
4744 </para>
4745
4746 <para>
4747  <itemizedlist>
4748
4749  <listitem>
4750   <para>
4751    Privoxy main page:
4752   </para>
4753   <blockquote>
4754    <para>
4755      <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
4756    </para>
4757   </blockquote>
4758   <para>
4759    Alternately, this may be reached at <ulink
4760    url="http://p.p/">http://p.p/</ulink>, but this
4761    variation may not work as reliably as the above in some configurations.
4762   </para>
4763  </listitem>
4764
4765  <listitem>
4766   <para>
4767     Show information about the current configuration:
4768   </para>
4769    <blockquote>
4770    <para>
4771     <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
4772    </para>
4773   </blockquote>
4774  </listitem>
4775
4776  <listitem>
4777   <para>
4778     Show the source code version numbers:
4779   </para>
4780   <blockquote>
4781    <para>
4782     <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
4783    </para>
4784   </blockquote>
4785  </listitem>
4786
4787  <listitem>
4788   <para>
4789    Show the client's request headers:
4790   </para>
4791   <blockquote>
4792    <para>
4793     <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
4794    </para>
4795   </blockquote>
4796  </listitem>
4797
4798  <listitem>
4799   <para>
4800    Show which actions apply to a URL and why:
4801   </para>
4802    <blockquote>
4803    <para>
4804     <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
4805    </para>
4806   </blockquote>
4807  </listitem>
4808
4809  <listitem>
4810   <para>
4811    Toggle Privoxy on or off. In this case, <quote>Privoxy</quote> continues
4812    to run, but only as a pass-through proxy, with no actions taking place:
4813   </para>
4814    <blockquote>
4815    <para>
4816     <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
4817    </para>
4818   </blockquote>
4819   <para>
4820    Short cuts. Turn off, then on:
4821   </para>
4822    <blockquote>
4823    <para>
4824      <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
4825    </para>
4826   </blockquote>
4827    <blockquote>
4828    <para>
4829      <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
4830    </para>
4831   </blockquote>
4832  </listitem>
4833
4834  <listitem>
4835   <para>
4836    Edit the actions list file:
4837   </para>
4838    <blockquote>
4839    <para>
4840     <ulink url="http://config.privoxy.org/edit-actions">http://config.privoxy.org/edit-actions</ulink>
4841    </para>
4842   </blockquote>
4843  </listitem>
4844
4845  </itemizedlist>
4846 </para>
4847
4848 <para>
4849  These may be bookmarked for quick reference. See next.
4850
4851 </para>
4852
4853 <sect3 id="bookmarklets">
4854 <title>Bookmarklets</title>
4855 <para>
4856  Below are some <quote>bookmarklets</quote> to allow you to easily access a
4857  <quote>mini</quote> version of some of <application>Privoxy's</application>
4858  special pages. They are designed for MS Internet Explorer, but should work
4859  equally well in Netscape, Mozilla, and other browsers which support
4860  JavaScript. They are designed to run directly from your bookmarks - not by
4861  clicking the links below (although that should work for testing).
4862 </para>
4863 <para>
4864  To save them, right-click the link and choose <quote>Add to Favorites</quote>
4865  (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
4866  the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
4867  Bookmarklet directly from your favorites/bookmarks. For even faster access,
4868  you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
4869  Toolbar</quote> (Netscape), and run them with a single click.
4870 </para>
4871
4872 <para>
4873  <itemizedlist>
4874
4875   <listitem>
4876    <para>
4877     <ulink 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());">Enable Privoxy</ulink>
4878    </para>
4879   </listitem>
4880
4881   <listitem>
4882    <para>
4883     <ulink 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());">Disable Privoxy</ulink>
4884    </para>
4885   </listitem>
4886
4887   <listitem>
4888    <para>
4889     <ulink 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());">Toggle Privoxy</ulink> (Toggles between enabled and disabled)
4890    </para>
4891   </listitem>
4892
4893   <listitem>
4894    <para>
4895     <ulink 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());">View Privoxy Status</ulink>
4896    </para>
4897   </listitem>
4898
4899   <listitem>
4900    <para>
4901     <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions','Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Actions file feedback system</ulink>
4902    </para>
4903   </listitem>
4904
4905  </itemizedlist>
4906 </para>
4907
4908
4909
4910 <para>
4911  Credit: The site which gave me the general idea for these bookmarklets is
4912  <ulink url="http://www.bookmarklets.com">www.bookmarklets.com</ulink>. They
4913  have more information about bookmarklets.
4914 </para>
4915
4916
4917 </sect3>
4918
4919 </sect2>
4920
4921
4922 <!--   ~~~~~       New section      ~~~~~     -->
4923 <sect2 id="actionsanat">
4924 <title>Anatomy of an Action</title>
4925
4926 <para>
4927  The way <application>Privoxy</application> applies <quote>actions</quote>
4928  and <quote>filters</quote> to any given URL can be complex, and not always so
4929  easy to understand what is happening. And sometimes we need to be able to
4930  <emphasis>see</emphasis> just what <application>Privoxy</application> is
4931  doing. Especially, if something <application>Privoxy</application> is doing
4932  is causing us a problem inadvertently. It can be a little daunting to look at
4933  the actions and filters files themselves, since they tend to be filled with
4934  <quote>regular expressions</quote> whose consequences are not always
4935  so obvious.
4936 </para>
4937
4938 <para>
4939  One quick test to see if <application>Privoxy</application> is causing a problem
4940  or not, is to disable it temporarily. This should be the first troubleshooting
4941  step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
4942  and easy way to do this (be sure to flush caches afterwards!).
4943 </para>
4944
4945 <para>
4946  <application>Privoxy</application> also provides the
4947  <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
4948  page that can show us very specifically how <application>actions</application>
4949  are being applied to any given URL. This is a big help for troubleshooting.
4950 </para>
4951
4952 <para>
4953  First, enter one URL (or partial URL) at the prompt, and then
4954  <application>Privoxy</application> will tell us
4955  how the current configuration will handle it. This will not
4956  help with filtering effects from the <filename>default.filter</filename> file! It
4957  also will not tell you about any other URLs that may be embedded within the
4958  URL you are testing (i.e. a web page). For instance, images such as ads are expressed as URLs
4959  within the raw page source of HTML pages. So you will only get info for the
4960  actual URL that is pasted into the prompt area -- not any sub-URLs. If you
4961  want to know about embedded URLs like ads, you will have to dig those out of
4962  the HTML source. Use your browser's <quote>View Page Source</quote> option
4963  for this. Or right click on the ad, and grab the URL.
4964 </para>
4965
4966 <para>
4967  Let's look at an example, <ulink url="http://google.com">google.com</ulink>,
4968  one section at a time:
4969 </para>
4970
4971 <para>
4972  <screen>
4973  System default actions:
4974
4975  { -add-header -block -deanimate-gifs -downgrade -fast-redirects -filter
4976    -hide-forwarded -hide-from -hide-referer -hide-user-agent -image
4977    -image-blocker -limit-connect -no-compression -no-cookies-keep
4978    -no-cookies-read -no-cookies-set -no-popups -vanilla-wafer -wafer }
4979
4980  </screen>
4981 </para>
4982
4983 <para>
4984  This is the top section, and only tells us of the compiled in defaults. This
4985  is basically what <application>Privoxy</application> would do if there
4986  were not any <quote>actions</quote> defined, i.e. it does nothing. Every action
4987  is disabled. This is not particularly informative for our purposes here. OK,
4988  next section:
4989 </para>
4990
4991 <para>
4992  <screen>
4993
4994  Matches for http://google.com:
4995
4996  { -add-header -block +deanimate-gifs -downgrade +fast-redirects
4997    +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
4998    +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
4999    +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge}
5000    -hide-user-agent -image +image-blocker{blank} +no-compression
5001    +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups
5002    -vanilla-wafer -wafer }
5003    /
5004
5005  { -no-cookies-keep -no-cookies-read -no-cookies-set }
5006   .google.com
5007
5008  { -fast-redirects }
5009   .google.com
5010
5011  </screen>
5012 </para>
5013
5014 <para>
5015  This is much more informative, and tells us how we have defined our
5016  <quote>actions</quote>, and which ones match for our example,
5017  <quote>google.com</quote>. The first grouping shows our default
5018  settings, which would apply to all URLs. If you look at your <quote>actions</quote>
5019  file, this would be the section just below the <quote>aliases</quote> section
5020  near the top. This applies to all URLs as signified by the single forward
5021  slash -- <quote>/</quote>.
5022
5023 </para>
5024
5025 <para>
5026  These are the default actions we have enabled. But we can define additional
5027  actions that would be exceptions to these general rules, and then list
5028  specific URLs that these exceptions would apply to. Last match wins.
5029  Just below this then are two explicit matches for <quote>.google.com</quote>.
5030  The first is negating our various cookie blocking actions (i.e. we will allow
5031  cookies here). The second is allowing <quote>fast-redirects</quote>. Note
5032  that there is a leading dot here -- <quote>.google.com</quote>. This will
5033  match any hosts and sub-domains, in the google.com domain also, such as
5034  <quote>www.google.com</quote>. So, apparently, we have these actions defined
5035  somewhere in the lower part of our actions file, and
5036  <quote>google.com</quote> is referenced in these sections.
5037
5038 </para>
5039
5040 <para>
5041  And now we pull it altogether in the bottom section and summarize how
5042  <application>Privoxy</application> is applying all its <quote>actions</quote>
5043  to <quote>google.com</quote>:
5044
5045 </para>
5046
5047 <para>
5048  <screen>
5049
5050  Final results:
5051
5052  -add-header -block -deanimate-gifs -downgrade -fast-redirects
5053  +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
5054  +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
5055  +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge}
5056  -hide-user-agent -image +image-blocker{blank} -limit-connect +no-compression
5057  -no-cookies-keep -no-cookies-read -no-cookies-set +no-popups -vanilla-wafer
5058  -wafer
5059
5060  </screen>
5061 </para>
5062
5063 <para>
5064  Now another example, <quote>ad.doubleclick.net</quote>:
5065 </para>
5066
5067 <para>
5068  <screen>
5069
5070  { +block +image }
5071   .ad.doubleclick.net
5072
5073  { +block +image }
5074   ad*.
5075
5076  { +block +image }
5077   .doubleclick.net
5078
5079  </screen>
5080 </para>
5081
5082 <para>
5083  We'll just show the interesting part here, the explicit matches. It is
5084  matched three different times. Each as an <quote>+block +image</quote>,
5085  which is the expanded form of one of our aliases that had been defined as:
5086  <quote>+imageblock</quote>. (<quote>Aliases</quote> are defined in the
5087  first section of the actions file and typically used to combine more
5088  than one action.)
5089 </para>
5090
5091 <para>
5092  Any one of these would have done the trick and blocked this as an unwanted
5093  image. This is unnecessarily redundant since the last case effectively
5094  would also cover the first. No point in taking chances with these guys
5095  though ;-) Note that if you want an ad or obnoxious
5096  URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
5097  is done here -- as both a <quote>+block</quote> <emphasis>and</emphasis> an
5098  <quote>+image</quote>. The custom alias <quote>+imageblock</quote> does this
5099  for us.
5100 </para>
5101
5102 <para>
5103  One last example. Let's try <quote>http://www.rhapsodyk.net/adsl/HOWTO/</quote>.
5104  This one is giving us problems. We are getting a blank page. Hmmm...
5105 </para>
5106
5107 <para>
5108  <screen>
5109
5110  Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
5111
5112  { -add-header -block +deanimate-gifs -downgrade +fast-redirects
5113    +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
5114    +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
5115    +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge}
5116    -hide-user-agent -image +image-blocker{blank} +no-compression
5117    +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups
5118    -vanilla-wafer -wafer }
5119    /
5120
5121  { +block +image }
5122   /ads
5123
5124  </screen>
5125 </para>
5126
5127 <para>
5128  Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote>! But
5129  we did not want this at all! Now we see why we get the blank page. We could
5130  now add a new action below this that explicitly does <emphasis>not</emphasis>
5131  block (-block) pages with <quote>adsl</quote>. There are various ways to
5132  handle such exceptions. Example:
5133 </para>
5134
5135 <para>
5136  <screen>
5137
5138  { -block }
5139   /adsl
5140
5141  </screen>
5142 </para>
5143
5144 <para>
5145  Now the page displays ;-) Be sure to flush your browser's caches when
5146  making such changes. Or, try using <literal>Shift+Reload</literal>.
5147 </para>
5148
5149 <para>
5150  But now what about a situation where we get no explicit matches like
5151  we did with:
5152 </para>
5153
5154 <para>
5155  <screen>
5156
5157  { -block }
5158   /adsl
5159
5160  </screen>
5161 </para>
5162
5163 <para>
5164  That actually was very telling and pointed us quickly to where the problem
5165  was. If you don't get this kind of match, then it means one of the default
5166  rules in the first section is causing the problem. This would require some
5167  guesswork, and maybe a little trial and error to isolate the offending rule.
5168  One likely cause would be one of the <quote>{+filter}</quote> actions. Try
5169  adding the URL for the site to one of aliases that turn off <quote>+filter</quote>:
5170 </para>
5171
5172 <para>
5173  <screen>
5174
5175  {shop}
5176  .quietpc.com
5177  .worldpay.com   # for quietpc.com
5178  .jungle.com
5179  .scan.co.uk
5180  .forbes.com
5181
5182  </screen>
5183 </para>
5184
5185 <para>
5186  <quote>{shop}</quote> is an <quote>alias</quote> that expands to
5187  <quote>{ -filter -no-cookies -no-cookies-keep }</quote>. Or you could do
5188  your own exception to negate filtering:
5189
5190 </para>
5191
5192 <para>
5193  <screen>
5194
5195  {-filter}
5196  .forbes.com
5197
5198  </screen>
5199 </para>
5200
5201 <para>
5202  <quote>{fragile}</quote> is an alias that disables most actions. This can be
5203  used as a last resort for problem sites. Remember to flush caches! If this
5204  still does not work, you will have to go through the remaining actions one by
5205  one to find which one(s) is causing the problem.
5206 </para>
5207
5208 </sect2>
5209
5210 </sect1>
5211
5212  <!--
5213
5214  This program is free software; you can redistribute it
5215  and/or modify it under the terms of the GNU General
5216  Public License as published by the Free Software
5217  Foundation; either version 2 of the License, or (at
5218  your option) any later version.
5219
5220  This program is distributed in the hope that it will
5221  be useful, but WITHOUT ANY WARRANTY; without even the
5222  implied warranty of MERCHANTABILITY or FITNESS FOR A
5223  PARTICULAR PURPOSE.  See the GNU General Public
5224  License for more details.
5225
5226  The GNU General Public License should be included with
5227  this file.  If not, you can view it at
5228  http://www.gnu.org/copyleft/gpl.html
5229  or write to the Free Software Foundation, Inc., 59
5230  Temple Place - Suite 330, Boston, MA  02111-1307, USA.
5231
5232  $Log: user-manual.sgml,v $
5233  Revision 1.88  2002/04/23 05:37:54  hal9
5234  Add AmigaOS install stuff.
5235
5236  Revision 1.87  2002/04/23 02:53:15  david__schmidt
5237  Updated OSX installation section
5238  Added a few English tweaks here an there
5239
5240  Revision 1.86  2002/04/21 01:46:32  hal9
5241  Re-write actions section.
5242
5243  Revision 1.85  2002/04/18 21:23:23  hal9
5244  Fix ugly typo (mine).
5245
5246  Revision 1.84  2002/04/18 21:17:13  hal9
5247  Spell Redhat correctly (ie Red Hat). A few minor grammar corrections.
5248
5249  Revision 1.83  2002/04/18 18:21:12  oes
5250  Added RPM install detail
5251
5252  Revision 1.82  2002/04/18 12:04:50  oes
5253  Cosmetics
5254
5255  Revision 1.81  2002/04/18 11:50:24  oes
5256  Extended Install section - needs fixing by packagers
5257
5258  Revision 1.80  2002/04/18 10:45:19  oes
5259  Moved text to buildsource.sgml, renamed some filters, details
5260
5261  Revision 1.79  2002/04/18 03:18:06  hal9
5262  Spellcheck, and minor touchups.
5263
5264  Revision 1.78  2002/04/17 18:04:16  oes
5265  Proofreading part 2
5266
5267  Revision 1.77  2002/04/17 13:51:23  oes
5268  Proofreading, part one
5269
5270  Revision 1.76  2002/04/16 04:25:51  hal9
5271  -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
5272  -Note about proxy may need requests to re-read config files.
5273
5274  Revision 1.75  2002/04/12 02:08:48  david__schmidt
5275  Remove OS/2 building info... it is already in the developer-manual
5276
5277  Revision 1.74  2002/04/11 00:54:38  hal9
5278  Add small section on submitting actions.
5279
5280  Revision 1.73  2002/04/10 18:45:15  swa
5281  generated
5282
5283  Revision 1.72  2002/04/10 04:06:19  hal9
5284  Added actions feedback  to Bookmarklets section
5285
5286  Revision 1.71  2002/04/08 22:59:26  hal9
5287  Version update. Spell chkconfig correctly :)
5288
5289  Revision 1.70  2002/04/08 20:53:56  swa
5290  ?
5291
5292  Revision 1.69  2002/04/06 05:07:29  hal9
5293  -Add privoxy-man-page.sgml, for man page.
5294  -Add authors.sgml for AUTHORS (and p-authors.sgml)
5295  -Reworked various aspects of various docs.
5296  -Added additional comments to sub-docs.
5297
5298  Revision 1.68  2002/04/04 18:46:47  swa
5299  consistent look. reuse of copyright, history et. al.
5300
5301  Revision 1.67  2002/04/04 17:27:57  swa
5302  more single file to be included at multiple points. make maintaining easier
5303
5304  Revision 1.66  2002/04/04 06:48:37  hal9
5305  Structural changes to allow for conditional inclusion/exclusion of content
5306  based on entity toggles, e.g. 'entity % p-not-stable  "INCLUDE"'. And
5307  definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
5308  eventually be set by Makefile.
5309  More boilerplate text for use across multiple docs.
5310
5311  Revision 1.65  2002/04/03 19:52:07  swa
5312  enhance squid section due to user suggestion
5313
5314  Revision 1.64  2002/04/03 03:53:43  hal9
5315  A few minor bug fixes, and touch ups. Ready for review.
5316
5317  Revision 1.63  2002/04/01 16:24:49  hal9
5318  Define entities to include boilerplate text. See doc/source/*.
5319
5320  Revision 1.62  2002/03/30 04:15:53  hal9
5321  - Fix privoxy.org/config links.
5322  - Paste in Bookmarklets from Toggle page.
5323  - Move Quickstart nearer top, and minor rework.
5324
5325  Revision 1.61  2002/03/29 01:31:08  hal9
5326  Minor update.
5327
5328  Revision 1.60  2002/03/27 01:57:34  hal9
5329  Added more to Anatomy section.
5330
5331  Revision 1.59  2002/03/27 00:54:33  hal9
5332  Touch up intro for new name.
5333
5334  Revision 1.58  2002/03/26 22:29:55  swa
5335  we have a new homepage!
5336
5337  Revision 1.57  2002/03/24 20:33:30  hal9
5338  A few minor catch ups with name change.
5339
5340  Revision 1.56  2002/03/24 16:17:06  swa
5341  configure needs to be generated.
5342
5343  Revision 1.55  2002/03/24 16:08:08  swa
5344  we are too lazy to make a block-built
5345  privoxy logo. hence removed the option.
5346
5347  Revision 1.54  2002/03/24 15:46:20  swa
5348  name change related issue.
5349
5350  Revision 1.53  2002/03/24 11:51:00  swa
5351  name change. changed filenames.
5352
5353  Revision 1.52  2002/03/24 11:01:06  swa
5354  name change
5355
5356  Revision 1.51  2002/03/23 15:13:11  swa
5357  renamed every reference to the old name with foobar.
5358  fixed "application foobar application" tag, fixed
5359  "the foobar" with "foobar". left junkbustser in cvs
5360  comments and remarks to history untouched.
5361
5362  Revision 1.50  2002/03/23 05:06:21  hal9
5363  Touch up.
5364
5365  Revision 1.49  2002/03/21 17:01:05  hal9
5366  New section in Appendix.
5367
5368  Revision 1.48  2002/03/12 06:33:01  hal9
5369  Catching up to Andreas and re_filterfile changes.
5370
5371  Revision 1.47  2002/03/11 13:13:27  swa
5372  correct feedback channels
5373
5374  Revision 1.46  2002/03/10 00:51:08  hal9
5375  Added section on JB internal pages in Appendix.
5376
5377  Revision 1.45  2002/03/09 17:43:53  swa
5378  more distros
5379
5380  Revision 1.44  2002/03/09 17:08:48  hal9
5381  New section on Jon's actions file editor, and move some stuff around.
5382
5383  Revision 1.43  2002/03/08 00:47:32  hal9
5384  Added imageblock{pattern}.
5385
5386  Revision 1.42  2002/03/07 18:16:55  swa
5387  looks better
5388
5389  Revision 1.41  2002/03/07 16:46:43  hal9
5390  Fix a few markup problems for jade.
5391
5392  Revision 1.40  2002/03/07 16:28:39  swa
5393  provide correct feedback channels
5394
5395  Revision 1.39  2002/03/06 16:19:28  hal9
5396  Note on perceived filtering slowdown per FR.
5397
5398  Revision 1.38  2002/03/05 23:55:14  hal9
5399  Stupid I did it again. Double hyphen in comment breaks jade.
5400
5401  Revision 1.37  2002/03/05 23:53:49  hal9
5402  jade barfs on '- -' embedded in comments. - -user option broke it.
5403
5404  Revision 1.36  2002/03/05 22:53:28  hal9
5405  Add new - - user option.
5406
5407  Revision 1.35  2002/03/05 00:17:27  hal9
5408  Added section on command line options.
5409
5410  Revision 1.34  2002/03/04 19:32:07  oes
5411  Changed default port to 8118
5412
5413  Revision 1.33  2002/03/03 19:46:13  hal9
5414  Emphasis on where/how to report bugs, etc
5415
5416  Revision 1.32  2002/03/03 09:26:06  joergs
5417  AmigaOS changes, config is now loaded from PROGDIR: instead of
5418  AmiTCP:db/junkbuster/ if no configuration file is specified on the
5419  command line.
5420
5421  Revision 1.31  2002/03/02 22:45:52  david__schmidt
5422  Just tweaking
5423
5424  Revision 1.30  2002/03/02 22:00:14  hal9
5425  Updated 'New Features' list. Ran through spell-checker.
5426
5427  Revision 1.29  2002/03/02 20:34:07  david__schmidt
5428  Update OS/2 build section
5429
5430  Revision 1.28  2002/02/24 14:34:24  jongfoster
5431  Formatting changes.  Now changing the doctype to DocBook XML 4.1
5432  will work - no other changes are needed.
5433
5434  Revision 1.27  2002/01/11 14:14:32  hal9
5435  Added a very short section on Templates
5436
5437  Revision 1.26  2002/01/09 20:02:50  hal9
5438  Fix bug re: auto-detect config file changes.
5439
5440  Revision 1.25  2002/01/09 18:20:30  hal9
5441  Touch ups for *.action files.
5442
5443  Revision 1.24  2001/12/02 01:13:42  hal9
5444  Fix typo.
5445
5446  Revision 1.23  2001/12/02 00:20:41  hal9
5447  Updates for recent changes.
5448
5449  Revision 1.22  2001/11/05 23:57:51  hal9
5450  Minor update for startup now daemon mode.
5451
5452  Revision 1.21  2001/10/31 21:11:03  hal9
5453  Correct 2 minor errors
5454
5455  Revision 1.18  2001/10/24 18:45:26  hal9
5456  *** empty log message ***
5457
5458  Revision 1.17  2001/10/24 17:10:55  hal9
5459  Catching up with Jon's recent work, and a few other things.
5460
5461  Revision 1.16  2001/10/21 17:19:21  swa
5462  wrong url in documentation
5463
5464  Revision 1.15  2001/10/14 23:46:24  hal9
5465  Various minor changes. Fleshed out SEE ALSO section.
5466
5467  Revision 1.13  2001/10/10 17:28:33  hal9
5468  Very minor changes.
5469
5470  Revision 1.12  2001/09/28 02:57:04  hal9
5471  Ditto :/
5472
5473  Revision 1.11  2001/09/28 02:25:20  hal9
5474  Ditto.
5475
5476  Revision 1.9  2001/09/27 23:50:29  hal9
5477  A few changes. A short section on regular expression in appendix.
5478
5479  Revision 1.8  2001/09/25 00:34:59  hal9
5480  Some additions, and re-arranging.
5481
5482  Revision 1.7  2001/09/24 14:31:36  hal9
5483  Diddling.
5484
5485  Revision 1.6  2001/09/24 14:10:32  hal9
5486  Including David's OS/2 installation instructions.
5487
5488  Revision 1.2  2001/09/13 15:27:40  swa
5489  cosmetics
5490
5491  Revision 1.1  2001/09/12 15:36:41  swa
5492  source files for junkbuster documentation
5493
5494  Revision 1.3  2001/09/10 17:43:59  swa
5495  first proposal of a structure.
5496
5497  Revision 1.2  2001/06/13 14:28:31  swa
5498  docs should have an author.
5499
5500  Revision 1.1  2001/06/13 14:20:37  swa
5501  first import of project's documentation for the webserver.
5502
5503  -->
5504
5505 </article>