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