<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
-<!entity % dummy "INCLUDE">
+<!entity % dummy "IGNORE">
<!entity supported SYSTEM "supported.sgml">
<!entity newfeatures SYSTEM "newfeatures.sgml">
+<!entity p-intro SYSTEM "privoxy.sgml">
+<!entity seealso SYSTEM "seealso.sgml">
+<!entity buildsource SYSTEM "buildsource.sgml">
+<!entity contacting SYSTEM "contacting.sgml">
+<!entity history SYSTEM "history.sgml">
+<!entity copyright SYSTEM "copyright.sgml">
+<!entity license SYSTEM "license.sgml">
+<!entity p-version "2.9.15">
+<!entity p-status "beta">
+<!entity % p-not-stable "INCLUDE">
+<!entity % p-stable "IGNORE">
+<!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
+<!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
+<!entity % p-readme "IGNORE">
+<!entity % p-config "IGNORE">
+<!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml -->
+<!entity my-copy "©"> <!-- kludge for docbook2man -->
]>
<!--
File : $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
Purpose : user manual
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
-
- $Id: user-manual.sgml,v 1.62 2002/03/30 04:15:53 hal9 Exp $
- Written by and Copyright (C) 2001 the SourceForge
- Privoxy team. http://www.privoxy.org/
+ $Id: user-manual.sgml,v 1.114 2002/05/16 09:42:50 oes Exp $
- Based on the Internet Junkbuster originally written
- by and Copyright (C) 1997 Anonymous Coders and
- Junkbusters Corporation. http://www.junkbusters.com
--->
-
-<!--
-Sat 03/02/02 04:53:47 PM
+ Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
+ See LICENSE.
-This should be ready for BETA release.
+ ========================================================================
+ NOTE: Please read developer-manual/documentation.html before touching
+ anything in this, or other Privoxy documentation.
+ ========================================================================
-Hal Burgiss <hal@foobox.net>
-->
<article id="index">
<artheader>
+
<title>Privoxy User Manual</title>
-<pubdate>$Id: user-manual.sgml,v 1.62 2002/03/30 04:15:53 hal9 Exp $</pubdate>
+<pubdate>
+ <subscript>
+<!-- Completely the wrong markup, but very little is allowed -->
+<!-- in this part of an article. FIXME -->
+ <link linkend="copyright">Copyright</link> &my-copy; 2001, 2002 by
+ <ulink url="http://www.privoxy.org">Privoxy Developers</ulink>
+ </subscript>
+</pubdate>
+
+<pubdate>$Id: user-manual.sgml,v 1.114 2002/05/16 09:42:50 oes Exp $</pubdate>
+
+<!--
+
+Note: the following should generate a separate page, and a live link to it,
+all nicely done. But it doesn't for some mysterious reason. Please leave
+commented unless it can be fixed proper. For the time being, the
+copyright/license declarations will be in their own sgml.
+
+Hal.
+
+<copyright>
+ <year>2001</year>
+ <year>2002</year>
+ <holder>Privoxy Developers</holder>
+</copyright>
+
+<legalnotice id="legalnotice">
+ <para>
+ text goes here ........
+ </para>
+</legalnotice>
+
+-->
-<authorgroup>
- <author>
- <affiliation>
- <orgname>By: Privoxy Developers</orgname>
- </affiliation>
- </author>
-</authorgroup>
<abstract>
+
<![%dummy;[
<para>
<comment>
<para>
The user manual gives users information on how to install, configure and use
- <application>Privoxy</application>. <application>Privoxy</application> is a
- web proxy with advanced filtering capabilities for protecting privacy,
- filtering web page content, managing cookies, controlling access, and
- removing ads, banners, pop-ups and other obnoxious Internet
- Junk. <application>Privoxy</application> has a very flexible configuration
- and can be customized to suit individual needs and
- tastes. <application>Privoxy</application> has application for both
- stand-alone systems and multi-user networks.
+ <ulink
+ url="http://www.privoxy.org/"><application>Privoxy</application></ulink>.
</para>
+
+<!-- Include privoxy.sgml boilerplate: -->
+ &p-intro;
+<!-- end privoxy.sgml -->
+
<para>
-You can find the latest version of the user manual at <ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
+ You can find the latest version of the user manual at <ulink
+ url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
+ Please see the <ulink url="contact.html">Contact section</ulink> on how to
+ contact the developers.
</para>
<!-- <para> -->
</artheader>
-
<!-- ~~~~~ New section ~~~~~ -->
-
-<sect1 id="introduction"><title>Introduction</title>
-<para>
- <application>Privoxy</application> is a web proxy with advanced filtering
- capabilities for protecting privacy, filtering web page content, managing
- cookies, controlling access, and removing ads, banners, pop-ups and other
- obnoxious Internet junk. <application>Privoxy</application> has a very
- flexible configuration and can be customized to suit individual needs and
- tastes. <application>Privoxy</application> has application for both
- stand-alone systems and multi-user networks.
-</para>
-
-<para>
- <application>Privoxy</application> is based on the code of the
- <application>Internet Junkbuster</application>.
- <application>Junkbuster</application> was originally written by JunkBusters
- Corporation, and was released as free open-source software under the GNU GPL.
- Stefan Waldherr made many improvements, and started the SourceForge project
- to continue development.
-</para>
-
-<para>
- <application>Privoxy</application> continues the
- <application>Junkbuster</application> tradition, but adds many
- refinements and enhancements.
-</para>
-
+<sect1 label="1" id="introduction"><title>Introduction</title>
<para>
- This documentation is included with the current BETA version of
- <application>Privoxy</application> and is mostly complete at this
- point. The most up to date reference for the time being is still the comments
- in the source files and in the individual configuration files. Development
- of version 3.0 is currently nearing completion, and includes many significant
- changes and enhancements over earlier versions. The target release date for
- stable v3.0 is <quote>soon</quote> ;-)
+ This documentation is included with the current &p-status; version of
+ <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[,
+ and is mostly complete at this point. The most up to date reference for the
+ time being is still the comments in the source files and in the individual
+ configuration files. Development of version 3.0 is currently nearing
+ completion, and includes many significant changes and enhancements over
+ earlier versions. The target release date for
+ stable v3.0 is <quote>soon</quote> ;-)]]>.
</para>
+<!-- include only in non-stable versions -->
+<![%p-not-stable;[
<para>
- Since this is a BETA version, not all new features are well tested. This
+ Since this is a &p-status; version, not all new features are well tested. This
documentation may be slightly out of sync as a result (especially with
CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
not many!
</para>
-
+]]>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
-<title>New Features</title>
+<sect2 id="features"><title>Features</title>
<para>
In addition to <application>Internet Junkbuster's</application> traditional
- feature of ad and banner blocking and cookie management,
- <application>Privoxy</application> provides new features, some of them
- currently under development:
+ features of ad and banner blocking and cookie management,
+ <application>Privoxy</application> provides new features<![%p-not-stable;[,
+ some of them currently under development]]>:
</para>
-
-<!--
- Include newfeatures.sgml here:
--->
-
-&newfeatures;
-
+<!-- Include newfeatures.sgml boilerplate here: -->
+ &newfeatures;
+<!-- end boilerplate -->
</sect2>
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="installation"><title>Installation</title>
-<para>
- <application>Privoxy</application> is available as raw source code, or
- pre-compiled binaries. See the <ulink
- url="http://sourceforge.net/projects/ijbswa/">Privoxy Home Page</ulink>
- for binaries and current release info. <application>Privoxy</application>
- is also available via <ulink
- url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/current/">CVS</ulink>.
- This is the recommended approach at this time. But please be aware that CVS
- is constantly changing, and it may break in mysterious ways.
-</para>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-source"><title>Source</title>
<para>
- For gzipped tar archives, unpack the source:
+ <application>Privoxy</application> is available both in convenient pre-compiled
+ packages for a wide range of operating systems, and as raw source code.
+ For most users, we recommend using the packages, which can be downloaded from our
+ <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project
+ Page</ulink>.
</para>
<para>
- <screen>
- tar xzvf privoxy-2.9.13-beta-src* [.tgz or .tar.gz]
- cd privoxy-2.9.13-beta
- </screen>
+ Note: If you have a previous <application>Junkbuster</application> or
+ <application>Privoxy</application> installation on your system, you
+ will need to remove it. On some platforms, this may be done for you as part
+ of their installation procedure. (See below for your platform). In any case
+ <emphasis>be sure to backup your old configuration if it is valuable to
+ you.</emphasis> See the <link linkend="upgradersnote">note to
+ upgraders</link> section below.
</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="installation-packages"><title>Binary Packages</title>
<para>
- For retrieving the current CVS sources, you'll need the CVS
- package installed first. To download CVS source:
+How to install the binary packages depends on your operating system:
</para>
-<para>
- <screen>
- cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co current
- cd current
- </screen>
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-pack-rpm"><title>Red Hat, SuSE RPMs and Conectiva</title>
<para>
- This will create a directory named <filename>current/</filename>, which will
- contain the source tree.
+ RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
+ and will use <filename>/etc/privoxy</filename> for the location
+ of configuration files.
</para>
<para>
- Then, in either case, to build from tarball/CVS source:
+ Note that on Red Hat, <application>Privoxy</application> will
+ <emphasis>not</emphasis> be automatically started on system boot. You will
+ need to enable that using <command>chkconfig</command>,
+ <command>ntsysv</command>, or similar methods. Note that SuSE will
+automatically start Privoxy in the boot process.
</para>
<para>
- <screen>
- ./configure (--help to see options)
- make (the make from gnu, gmake for *BSD)
- su
- make -n install (to see where all the files will go)
- make install (to really install)
- </screen>
+ If you have problems with failed dependencies, try rebuilding the SRC RPM:
+ <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm;</literal>. This
+ will use your locally installed libraries and RPM version.
</para>
<para>
- For Redhat and SuSE Linux RPM packages, see below.
+ Also note that if you have a <application>Junkbuster</application> RPM installed
+ on your system, you need to remove it first, because the packages conflict.
+ Otherwise, RPM will try to remove <application>Junkbuster</application>
+ automatically, before installing <application>Privoxy</application>.
</para>
-
-</sect2>
-
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-rh"><title>Red Hat</title>
+<sect3 id="installation-deb"><title>Debian</title>
<para>
- To build Redhat RPM packages, install source as above. Then:
+ FIXME.
</para>
+</sect3>
-<para>
- <screen>
- autoheader
- autoconf
- ./configure
- make redhat-dist
- </screen>
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-pack-win"><title>Windows</title>
<para>
- This will create both binary and src RPMs in the usual places. Example:
+ Just double-click the installer, which will guide you through
+ the installation process. You will find the configuration files
+ in the same directory as you installed Privoxy in. We do not
+ use the registry of Windows.
</para>
+</sect3>
-<para>
- /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm
-</para>
-<para>
- /usr/src/redhat/SRPMS/privoxy-2.9.11-1.src.rpm
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, FreeBSD, HP-UX</title>
<para>
- To install, of course:
+ Create a new directory, <literal>cd</literal> to it, then unzip and
+ untar the archive. For the most part, you'll have to figure out where
+ things go. FIXME.
</para>
+</sect3>
-<para>
- <screen>
- rpm -Uvv /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm
- </screen>
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-os2"><title>OS/2</title>
<para>
- This will place the <application>Privoxy</application> configuration
- files in <filename>/etc/privoxy/</filename>, and log files in
- <filename>/var/log/privoxy/</filename>.
+ First, make sure that no previous installations of
+ <application>Junkbuster</application> and / or
+ <application>Privoxy</application> are left on your
+ system. You can do this by
</para>
-</sect2>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-suse"><title>SuSE</title>
<para>
- To build SuSE RPM packages, install source as above. Then:
+ Then, just double-click the WarpIN self-installing archive, which will
+ guide you through the installation process. A shadow of the
+ <application>Privoxy</application> executable will be placed in your
+ startup folder so it will start automatically whenever OS/2 starts.
</para>
<para>
- <screen>
- autoheader
- autoconf
- ./configure
- make suse-dist
- </screen>
+ The directory you choose to install <application>Privoxy</application>
+ into will contain all of the configuration files.
</para>
+</sect3>
-<para>
- This will create both binary and src RPMs in the usual places. Example:
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-mac"><title>Max OSX</title>
+<para>
+ Unzip the downloaded package (you can either double-click on the file
+ in the finder, or on the desktop if you downloaded it there). Then,
+ double-click on the package installer icon and follow the installation
+ process.
+ <application>Privoxy</application> will be installed in the subdirectory
+ <literal>/Applications/Privoxy.app</literal>.
+ <application>Privoxy</application> will set itself up to start
+ automatically on system bring-up via
+ <literal>/System/Library/StartupItems/Privoxy</literal>.
</para>
+</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-amiga"><title>AmigaOS</title>
<para>
- /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm
+ Copy and then unpack the <filename>lha</filename> archive to a suitable location.
+ All necessary files will be installed into <application>Privoxy</application>
+ directory, including all configuration and log files. To uninstall, just
+ remove this directory.
</para>
<para>
- /usr/src/packages/SRPMS/privoxy-2.9.11-1.src.rpm
+ Start <application>Privoxy</application> (with RUN <>NIL:) in your
+ <filename>startnet</filename> script (AmiTCP), in
+ <filename>s:user-startup</filename> (RoadShow), as startup program in your
+ startup script (Genesis), or as startup action (Miami and MiamiDx).
+ <application>Privoxy</application> will automatically quit when you quit your
+ TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
+ <application>Privoxy</application> is still running).
</para>
+</sect3>
+</sect2>
-<para>
- To install, of course:
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="installation-source"><title>Building from Source</title>
<para>
- <screen>
- rpm -Uvv /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm
- </screen>
+ The most convenient way to obtain the <application>Privoxy</application> sources
+ is to download the source tarball from our <ulink url="http://sf.net/projects/ijbswa/">project
+ page</ulink>.
</para>
<para>
- This will place the <application>Privoxy</application> configuration
- files in <filename>/etc/privoxy/</filename>, and log files in
- <filename>/var/log/privoxy/</filename>.
+ If you like to live on the bleeding edge and are not afraid of using
+ possibly unstable development versions, you can check out the up-to-the-minute
+ version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
+ CVS repository</ulink> or simply download <ulink
+ url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">the nightly CVS
+ tarball.</ulink>
</para>
-</sect2>
+<!-- include buildsource.sgml boilerplate: -->
+&buildsource;
+<!-- end boilerplate -->
+</sect2>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-os2"><title>OS/2</title>
+</sect1>
-<!--
-Thanx David Schmidt!
--->
+<!-- ~ End section ~ -->
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="upgradersnote">
+<title>Note to Upgraders</title>
<para>
- <application>Privoxy</application> is packaged in a WarpIN self-
- installing archive. The self-installing program will be named depending
- on the release version, something like:
- <filename>ijbos2_setup_1.2.3.exe</filename>. In order to install it, simply
- run this executable or double-click on its icon and follow the WarpIN
- installation panels. A shadow of the <application>Privoxy</application>
- executable will be placed in your startup folder so it will start
- automatically whenever OS/2 starts.
+ There are very significant changes from earlier
+ <application>Junkbuster</application> versions to the current
+ <application>Privoxy</application>. The number, names, syntax, and
+ purposes of configuration files have substantially changed.
+ <application>Junkbuster 2.0.x</application> configuration
+ files will not migrate, <application>Junkbuster 2.9.x</application>
+ and <application>Privoxy</application> configurations will need to be
+ ported. The functionalities of the old <filename>blockfile</filename>,
+ <filename>cookiefile</filename> and <filename>imagelist</filename>
+ are now combined into the <link linkend="actions-file"><quote>actions
+ files</quote></link>.
+ <filename>default.action</filename>, is the main actions file. Local
+ exceptions should best be put into <filename>user.action</filename>.
</para>
-
<para>
- The directory you choose to install <application>Privoxy</application>
- into will contain all of the configuration files.
+ A <link linkend="filter-file"><quote>filter file</quote></link> (typically
+ <filename>default.filter</filename>) is new as of <application>Privoxy
+ 2.9.x</application>, and provides some of the new sophistication (explained
+ below). <filename>config</filename> is much the same as before.
</para>
-
<para>
- If you would like to build binary images on OS/2 yourself, you will need
- a few Unix-like tools: autoconf, autoheader and sh. These tools will be
- used to create the required config.h file, which is not part of the
- source distribution because it differs based on platform. You will also
- need a compiler.
- The distribution has been created using IBM VisualAge compilers, but you
- can use any compiler you like. GCC/EMX has the disadvantage of needing
- to be single-threaded due to a limitation of EMX's implementation of the
- select() socket call.
+ If upgrading from a 2.0.x version, you will have to use the new config
+ files, and possibly adapt any personal rules from your older files.
+ When porting personal rules over from the old <filename>blockfile</filename>
+ to the new actions files, please note that even the pattern syntax has
+ changed. If upgrading from 2.9.x development versions, it is still
+ recommended to use the new configuration files.
</para>
-
<para>
- In addition to needing the source code distribution as outlined earlier,
- you will want to extract the <filename>os2seutp</filename> directory from CVS:
- <screen>
- cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
- </screen>
- This will create a directory named os2setup/, which will contain the
- <filename>Makefile.vac</filename> makefile and <filename>os2build.cmd</filename>
- which is used to completely create the binary distribution. The sequence
- of events for building the executable for yourself goes something like this:
- <screen>
- cd current
- autoheader
- autoconf
- sh configure
- cd ..\os2setup
- nmake -f Makefile.vac
- </screen>
- You will see this sequence laid out in <filename>os2build.cmd</filename>.
+ A quick list of things to be aware of before upgrading:
</para>
-</sect2>
+<para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The default listening port is now 8118 due to a conflict with another
+ service (NAS).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Some installers may remove earlier versions completely. Save any
+ important configuration files!
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>Privoxy</application> is controllable with a web browser
+ at the special URL: <ulink
+ url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
+ (Shortcut: <ulink url="http://p.p/">http://p.p/</ulink>). Many
+ aspects of configuration can be done here, including temporarily disabling
+ <application>Privoxy</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The primary configuration files for cookie management, ad and banner
+ blocking, and many other aspects of <application>Privoxy</application>
+ configuration are the <link linkend="actions-file">actions
+ files</link>. It is strongly recommended to become familiar with the new
+ actions concept below, before modifying these files. Locally defined rules
+ should go into <filename>user.action</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<!-- I think it is best to keep this somewhat vague, in case -->
+<!-- the situation changes under our feet. -->
+ Some installers may not automatically start
+ <application>Privoxy</application> after installation.
+ </para>
+ </listitem>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-win"><title>Windows</title>
-<para>Click-click. (I need help on this. Not a clue here. Also for
-configuration section below. HB.)
+ </itemizedlist>
</para>
-</sect2>
+</sect1>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-other"><title>Other</title>
+<sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
<para>
- Some quick notes on other Operating Systems.
-</para>
+ <itemizedlist>
-<para>
- For FreeBSD (and other *BSDs?), the build will require <command>gmake</command>
- instead of the included <command>make</command>. <command>gmake</command> is
- available from <ulink url="http://www.gnu.org">http://www.gnu.org</ulink>.
- The rest should be the same as above for Linux/Unix.
-</para>
+ <listitem>
+ <para>
+ If upgrading, from versions before 2.9.16, please back up any configuration
+ files. See the <link linkend="upgradersnote">Note to Upgraders</link> Section.
+ </para>
+</listitem>
-</sect2>
+ <listitem>
+ <para>
+ Install <application>Privoxy</application>. See the <link
+ linkend="installation">Installation Section</link> for platform specific
+ information.
+ </para>
+ </listitem>
-</sect1>
+ <listitem>
+ <para>
+ Advanced users and those who want to offer <application>Privoxy</application>
+ service to more than just their local machine should check the <link
+ linkend="config">main config file</link>, especially the <link
+ linkend="access-control">security-relevant</link> options.
+ </para>
+ </listitem>
-<!-- ~ End section ~ -->
+ <listitem>
+ <para>
+ Start <application>Privoxy</application>, if the installation program has
+ not done this already. See the section <link linkend="startup">Starting
+ <application>Privoxy</application></link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set your browser to use <application>Privoxy</application> as HTTP and HTTPS
+ proxy by setting the proxy configuration for address of
+ <literal>127.0.0.1</literal> and port <literal>8118</literal>.
+ (<application>Junkbuster</application> and earlier versions of
+ <application>Privoxy</application> used port 8000.) See the section <link
+ linkend="startup">Starting <application>Privoxy</application></link>.
+ </para>
+ </listitem>
-<!-- ~~~~~ New section ~~~~~ -->
+ <listitem>
+ <para>
+ Flush your browser's caches, to remove any cached ad images.
+ </para>
+</listitem>
-<sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
+ <listitem>
+ <para>
+ Enjoy surfing with enhanced comfort and privacy.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you experience ads that slipped through, innocent images that are
+ blocked, or otherwise feel the need to fine-tune <application>Privoxy's</application>
+ behaviour, take a look at the <link linkend="actions-file">actions files</link>.
+ As a quick start, you might find the <link linkend="act-examples">richly
+ commented examples</link> helpful. You can also view and edit the actions
+ files through the <ulink url="http://config.privoxy.org">web-based
+ user interface</ulink>. The Appendix <quote><link linkend="actionsanat">Anatomy of
+ an Action</link></quote> has hints how to debug actions that <quote>misbehave</quote>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Please see the section <link linkend="contact">Contacting the
+ Developers</link> on how to report bugs or problems with websites or to get
+ help.
+ </para>
+ </listitem>
+ </itemizedlist>
+</para>
+
+</sect1>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="startup">
+<title>Starting <application>Privoxy</application></title>
<para>
- Before launching <application>Privoxy</application> for the first time, you
- will want to configure your browser(s) to use <application>Privoxy</application>
- and the HTTP and HTTPS proxy. The default is localhost for the proxy address,
- and port 8118 (earlier versions used port 800). This is the one required
- configuration that must be done!
+ Before launching <application>Privoxy</application> for the first time, you
+ will want to configure your browser(s) to use
+ <application>Privoxy</application> as a HTTP and HTTPS proxy. The default is
+ 127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
+ used port 8000). This is the one configuration step that must be done!
</para>
<para>
With <application>Netscape</application> (and
<application>Mozilla</application>), this can be set under <literal>Edit
-> Preferences -> Advanced -> Proxies -> HTTP Proxy</literal>.
- For <application>Internet Explorer</application>: <literal>Tools >
+ For <application>Internet Explorer</application>: <literal>Tools ->
Internet Properties -> Connections -> LAN Setting</literal>. Then,
check <quote>Use Proxy</quote> and fill in the appropriate info (Address:
- localhost, Port: 8118). Include if HTTPS proxy support too.
+ 127.0.0.1, Port: 8118). Include if HTTPS proxy support too.
</para>
<para>
After doing this, flush your browser's disk and memory caches to force a
- re-reading of all pages and get rid of any ads that may be cached. You
+ re-reading of all pages and to get rid of any ads that may be cached. You
are now ready to start enjoying the benefits of using
- <application>Privoxy</application>.
+ <application>Privoxy</application>!
</para>
-
<para>
<application>Privoxy</application> is typically started by specifying the
- main configuration file to be used on the command line. Example Unix startup
- command:
+ main configuration file to be used on the command line. If no configuration
+ file is specified on the command line, <application>Privoxy</application>
+ will look for a file named <filename>config</filename> in the current
+ directory. Except on Win32 where it will try <filename>config.txt</filename>.
+</para>
+
+<sect2 id="start-redhatdebian">
+<title>RedHat, Conectiva and Debian</title>
+<para>
+We use a script. Note that RedHat does not start Privoxy upon booting per
+default. It will use the file <filename>/etc/privoxy/config</filename> as its
+main configuration file. FIXME: Debian??
+</para>
+<para>
+ <screen>
+ # /etc/rc.d/init.d/privoxy start
+</screen>
</para>
+</sect2>
+<sect2 id="start-suse">
+<title>SuSE</title>
+<para>
+We use a script. It will use the file <filename>/etc/privoxy/config</filename>
+as its main configuration file. Note that SuSE starts Privoxy upon booting
+your PC.
+</para>
+<para>
+ <screen>
+ # rcprivoxy start
+</screen>
+</para>
+</sect2>
+
+<sect2 id="start-windows">
+<title>Windows</title>
+<para>
+Click on the Privoxy Icon to start Privoxy. If no configuration file is
+ specified on the command line, <application>Privoxy</application> will look
+ for a file named <filename>config.txt</filename>. Note that Windows will
+ automatically start Privoxy upon booting you PC.
+</para>
+</sect2>
+
+<sect2 id="start-unices">
+<title>Solaris, NetBSD, FreeBSD, HP-UX and others</title>
+<para>
+Example Unix startup command:
+</para>
<para>
<screen>
-
# /usr/sbin/privoxy /etc/privoxy/config
-
- </screen>
+</screen>
</para>
+</sect2>
+<sect2 id="start-os2">
+<title>OS/2</title>
<para>
- An init script is provided for SuSE and Redhat.
+FIXME.
</para>
+</sect2>
+<sect2 id="start-macosx">
+<title>MAX OSX</title>
<para>
-For for SuSE: /etc/rc.d/privoxy start
+FIXME.
</para>
+</sect2>
+
+<sect2 id="start-amigaos">
+<title>AmigaOS</title>
<para>
-For RedHat: /etc/rc.d/init.d/privoxy start
+FIXME.
</para>
+</sect2>
+<!--
<para>
- If no configuration file is specified on the command line,
- <application>Privoxy</application> will look for a file named
- <filename>config</filename> in the current directory. Except on Win32 where
- it will try <filename>config.txt</filename>. If no file is specified on the
- command line and no default configuration file can be found,
- <application>Privoxy</application> will fail to start.
+ See the section <link linkend="cmdoptions">Command line options</link> for
+ furher info.
</para>
+must find a better place for this paragraph
<para>
The included default configuration files should give a reasonable starting
- point, though may be somewhat aggressive in blocking junk. Most of the
- per site configuration is done in the <quote>actions</quote> files. These
- are where various cookie actions are defined, ad and banner blocking,
- and other aspects of <application>Privoxy</application> configuration. There
- are several such files included, with varying levels of aggressiveness.
+ point. Most of the per site configuration is done in the
+ <ulink url="actions-file.html"><quote>actions</quote></ulink> files. These are
+ where various cookie actions are defined, ad and banner blocking, and other
+ aspects of <application>Privoxy</application> configuration. There are several
+ such files included, with varying levels of aggressiveness.
</para>
<para>
- You will probably want to keep an eye out for sites that require persistent
- cookies, and add these to <filename>default.action</filename> as needed. By
+ You will probably want to keep an eye out for sites for which you may prefer
+ persistent cookies, and add these to your actions configuration as needed. By
default, most of these will be accepted only during the current browser
- session, until you add them to the configuration. If you want the browser to
- handle this instead, you will need to edit
- <filename>default.action</filename> and disable this feature. If you use more
- than one browser, it would make more sense to let
- <application>Privoxy</application> handle this. In which case, the browser(s)
- should be set to accept all cookies.
+ session (aka <quote>session cookies</quote>), unless you add them to the
+ configuration. If you want the browser to handle this instead, you will need
+ to edit <filename>user.action</filename> (or through the web based interface)
+ and disable this feature. If you use more than one browser, it would make
+ more sense to let <application>Privoxy</application> handle this. In which
+ case, the browser(s) should be set to accept all cookies.
+</para>
+
+<para>
+ Another feature where you will probably want to define exceptions for trusted
+ sites is the popup-killing (through the <ulink
+ url="actions-file.html#KILL-POPUPS"><quote>+kill-popups</quote></ulink> and
+ <ulink
+ url="actions-file.html#FILTER-POPUPS"><quote>+filter{popups}</quote></ulink>
+ actions), because your favorite shopping, banking, or leisure site may need
+ popups (explained below).
</para>
<para>
- <application>Privoxy</application> is HTTP/1.1 compliant, but not all 1.1
- features are as yet implemented. If browsers that support HTTP/1.1 (like
- <application>Mozilla</application> or recent versions of I.E.) experience
- problems, you might try to force HTTP/1.0 compatibility. For Mozilla, look
- under <literal>Edit -> Preferences -> Debug -> Networking</literal>.
- Or set the <quote>+downgrade</quote> config option in
- <filename>default.action</filename>.
+ <application>Privoxy</application> is HTTP/1.1 compliant, but not all of
+ the optional 1.1 features are as yet supported. In the unlikely event that
+ you experience inexplicable problems with browsers that use HTTP/1.1 per default
+ (like <application>Mozilla</application> or recent versions of I.E.), you might
+ try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit ->
+ Preferences -> Debug -> Networking</literal>.
+ Alternatively, set the <quote>+downgrade-http-version</quote> config option in
+ <filename>default.action</filename> which will downgrade your browser's HTTP
+ requests from HTTP/1.1 to HTTP/1.0 before processing them.
</para>
<para>
After running <application>Privoxy</application> for a while, you can
start to fine tune the configuration to suit your personal, or site,
preferences and requirements. There are many, many aspects that can
- be customized. <quote>Actions</quote> (as specified in <filename>default.action</filename>)
+ be customized. <quote>Actions</quote>
can be adjusted by pointing your browser to
- <ulink url="http://p.p/">http://p.p/</ulink>,
- and then follow the link to <quote>edit the actions list</quote>.
+ <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
+ (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
+ and then follow the link to <quote>View & Change the Current Configuration</quote>.
(This is an internal page and does not require Internet access.)
</para>
configuration can be viewed from this page, including
current configuration parameters, source code version numbers,
the browser's request headers, and <quote>actions</quote> that apply
- to a given URL. In addition to the <filename>default.action</filename> file
+ to a given URL. In addition to the actions file
editor mentioned above, <application>Privoxy</application> can also
- be turned <quote>on</quote> and <quote>off</quote> from this page.
+ be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
</para>
<para>
- If you encounter problems, please verify it is a
- <application>Privoxy</application> bug, by disabling
- <application>Privoxy</application>, and then trying the same page.
- Also, try another browser if possible to eliminate browser or site
- problems. Before reporting it as a bug, see if there is not a configuration
- option that is enabled that is causing the page not to load. You can then add
- an exception for that page or site. For instance, try adding it to the
- <literal>{fragile}</literal> section of <filename>default.action</filename>.
- This will turn off most actions for this site. For more on troubleshooting
- problem sites, see the <ulink
- url="appendix.html#ACTIONSANAT">Appendix</ulink>. If a bug, please report it
- to the developers (see below).
+ If you encounter problems, try loading the page without
+ <application>Privoxy</application>. If that helps, enter the URL where
+ you have the problems into <ulink url="http://p.p/show-url-info">the browser
+ based rule tracing utility</ulink>. See which rules apply and why, and
+ then try turning them off for that site one after the other, until the problem
+ is gone. When you have found the culprit, you might want to turn the rest on
+ again.
</para>
+<para>
+ If the above paragraph sounds gibberish to you, you might want to <ulink
+ url="actions-file.html#ACTIONSFILE">read more about the actions concept</ulink>
+ or even dive deep into the <ulink url="appendix.html#ACTIONSANAT">Appendix
+ on actions</ulink>.
+</para>
-<!-- ~~~~~ New section ~~~~~ -->
+<para>
+ If you can't get rid of the problem at all, think you've found a bug in
+ Privoxy, want to propose a new feature or smarter rules, please see the
+ section <ulink url="contact.html"><quote>Contacting the
+ Developers</quote></ulink> below.
+</para>
-<sect2>
+-->
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="cmdoptions">
<title>Command Line Options</title>
<para>
<application>Privoxy</application> may be invoked with the following
<emphasis>--version</emphasis>
</para>
<para>
- Print version info and exit, Unix only.
+ Print version info and exit. Unix only.
</para>
</listitem>
<listitem>
<emphasis>--help</emphasis>
</para>
<para>
- Print a short usage info and exit, Unix only.
+ Print short usage info and exit. Unix only.
</para>
</listitem>
<listitem>
</para>
<para>
Don't become a daemon, i.e. don't fork and become process group
- leader, don't detach from controlling tty. Unix only.
+ leader, and don't detach from controlling tty. Unix only.
</para>
</listitem>
<listitem>
</para>
<para>
On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
- <emphasis>FILE</emphasis> on exit. Failiure to create or delete the
+ <emphasis>FILE</emphasis> on exit. Failure to create or delete the
<emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
option is given, no PID file will be used. Unix only.
</para>
<application>Privoxy</application> will look for a file named
<quote>config</quote> in the current directory (except on Win32
where it will look for <quote>config.txt</quote> instead). Specify
- full path to avoid confusion.
+ full path to avoid confusion. If no config file is found,
+ <application>Privoxy</application> will fail to start.
</para>
</listitem>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="configuration"><title><application>Privoxy</application> Configuration</title>
<para>
- All <application>Privoxy</application> configuration is kept
+ All <application>Privoxy</application> configuration is stored
in text files. These files can be edited with a text editor.
Many important aspects of <application>Privoxy</application> can
also be controlled easily with a web browser.
-
</para>
<sect2>
<title>Controlling <application>Privoxy</application> with Your Web Browser</title>
<para>
- <application>Privoxy</application> can be reached by the special
- URL <ulink url="http://p.p/">http://p.p/</ulink> (or alternately
- <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>),
- which is an internal page. You will see the following section:
+ <application>Privoxy</application>'s user interface can be reached through the special
+ URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
+ (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
+ which is a built-in page and works without Internet access.
+ You will see the following section:
</para>
-<para>
- <screen>
-
-Please choose from the following options:
+<!-- Needs to be put in a table and colorized -->
+<screen>
+ <msgtext>
+ <bridgehead renderas="sect2">Privoxy Menu</bridgehead>
- * Show information about the current configuration
- * Show the source code version numbers
- * Show the client's request headers.
- * Show which actions apply to a URL and why
- * Toggle Privoxy on or off
- * Edit the actions list
+ <simplelist>
+ <member>
+ ▪ <ulink url="http://config.privoxy.org/show-status">View & change the current configuration</ulink>
+ </member>
+ <member>
+ ▪ <ulink url="http://config.privoxy.org/show-version">View the source code version numbers</ulink>
+ </member>
+ <member>
+ ▪ <ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
+ </member>
+ <member>
+ ▪ <ulink url="http://config.privoxy.org/show-url-info">Look up which actions apply to a URL and why</ulink>
+ </member>
+ <member>
+ ▪ <ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
+ </member>
+ </simplelist>
+ </msgtext>
+</screen>
- </screen>
-</para>
<para>
- This should be self-explanatory. Note the last item is an editor for the
- <quote>actions list</quote>, which is where much of the ad, banner, cookie,
- and URL blocking magic is configured as well as other advanced features of
+ This should be self-explanatory. Note the first item leads to an editor for the
+ <link linkend="actions-file">actions files</link>, which is where the ad, banner,
+ cookie, and URL blocking magic is configured as well as other advanced features of
<application>Privoxy</application>. This is an easy way to adjust various
aspects of <application>Privoxy</application> configuration. The actions
file, and other configuration files, are explained in detail below.
- <application>Privoxy</application> will automatically detect any changes
- to these files.
</para>
<para>
<quote>Toggle Privoxy On or Off</quote> is handy for sites that might
- have problems with your current actions and filters, or just to test if
-
a site misbehaves, whether it is <application>Privoxy</application>
+ have problems with your current actions and filters. You can in fact use
+
it as a test to see whether it is <application>Privoxy</application>
causing the problem or not. <application>Privoxy</application> continues
- to run as a proxy in this case, but all filtering is disabled.
-
+ to run as a proxy in this case, but all manipulation is disabled, i.e.
+ <application>Privoxy</application> acts like a normal forwarding proxy. There
+ is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
+ that you can toggle <application>Privoxy</application> with one click from
+ your browser.
</para>
</sect2>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
+<sect2 id="confoverview">
<title>Configuration Files Overview</title>
<para>
For Unix, *BSD and Linux, all configuration files are located in
<filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
AmigaOS these are all in the same directory as the
- <application>Privoxy</application> executable. The name and number of
- configuration files has changed from previous versions, and is subject to
- change as development progresses.
+ <application>Privoxy</application> executable. <![%p-not-stable;[ The name
+ and number of configuration files has changed from previous versions, and is
+ subject to change as development progresses.]]>
</para>
<para>
- The installed defaults provide a reasonable starting point, though possibly
- aggressive by some standards. For the time being, there are only three
- default configuration files (this will change in time):
+ The installed defaults provide a reasonable starting point, though
+ some settings may be aggressive by some standards. For the time being, the
+ principle configuration files are:
</para>
<para>
<listitem>
<para>
- The main configuration file is named <filename>config</filename>
+ The <link linkend="config">main configuration file</link> is named <filename>config</filename>
on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
- on Windows.
+ on Windows. This is a required file.
</para>
</listitem>
<listitem>
<para>
- The <filename>default.action</filename> file is used to define various
- <quote>actions</quote> relating to images, banners, pop-ups, access
- restrictions, banners and cookies. There is a CGI based editor for this
- file that can be accessed via <ulink
- url="http://p.p">http://p.p</ulink>. (Other actions
- files are included as well with differing levels of filtering
- and blocking, e.g. <filename>ijb-basic.action</filename>.)
+ <filename>default.action</filename> (the main <link linkend="actions-file">actions file</link>)
+ is used to define which <quote>actions</quote> relating to banner-blocking, images, pop-ups,
+ content modification, cookie handling etc should be applied by default. It also defines many
+ exceptions (both positive and negative) from this default set of actions that enable
+ <application>Privoxy</application> to selectively eliminate the junk, and only the junk, on
+ as many websites as possible.
+ </para>
+ <para>
+ Multiple actions files may be defined in <filename>config</filename>. These
+ are processed in the order they are defined. Local customizations and locally
+ preferred exceptions to the default policies as defined in
+ <filename>default.action</filename> (which you will most probably want
+ to define sooner or later) are probably best applied in
+ <filename>user.action</filename>, where you can preserve them across
+ upgrades. <filename>standard.action</filename> is for
+ <application>Privoxy's</application> internal use.
+ </para>
+ <para>
+ There is also a web based editor that can be accessed from
+ <ulink
+ url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
+ (Shortcut: <ulink
+ url="http://p.p/show-status">http://p.p/show-status</ulink>) for the
+ various actions files.
</para>
</listitem>
<listitem>
<para>
- The <filename>default.filter</filename> file can be used to re-write the raw
- page content, including viewable text as well as embedded HTML and JavaScript,
- and whatever else lurks on any given web page.
+ <filename>default.filter</filename> (the <link linkend="filter-file">filter
+ file</link>) can be used to re-write the raw page content, including
+ viewable text as well as embedded HTML and JavaScript, and whatever else
+ lurks on any given web page. The filtering jobs are only pre-defined here;
+ whether to apply them or not is up to the actions files.
</para>
</listitem>
</para>
<para>
- <filename>default.action</filename> and <filename>default.filter</filename>
- can use Perl style regular expressions for maximum flexibility. All files use
- the <quote><literal>#</literal></quote> character to denote a comment. Such
- lines are not processed by <application>Privoxy</application>. After
- making any changes, there is no need to restart
+ All files use the <quote><literal>#</literal></quote> character to denote a
+ comment (the rest of the line will be ignored) and understand line continuation
+ through placing a backslash ("<literal>\</literal>") as the very last character
+ in a line. If the <literal>#</literal> is preceded by a backslash, it looses
+ its special function. Placing a <literal>#</literal> in front of an otherwise
+ valid configuration line to prevent it from being interpreted is called "commenting
+ out" that line.
+</para>
+
+<para>
+ The actions files and <filename>default.filter</filename>
+ can use Perl style <link linkend="regex">regular expressions</link> for
+ maximum flexibility.
+</para>
+
+<para>
+ After making any changes, there is no need to restart
<application>Privoxy</application> in order for the changes to take
- effect. <application>Privoxy</application> should detect such changes
- automatically.
+ effect. <application>Privoxy</application> detects such changes
+ automatically. Note, however, that it may take one or two additional
+ requests for the change to take effect. When changing the listening address
+ of <application>Privoxy</application>, these <quote>wake up</quote> requests
+ must obviously be sent to the <emphasis>old</emphasis> listening address.
</para>
+<![%p-not-stable;[
<para>
While under development, the configuration content is subject to change.
The below documentation may not be accurate by the time you read this.
Also, what constitutes a <quote>default</quote> setting, may change, so
please check all your configuration files on important issues.
</para>
+]]>
+
</sect2>
+</sect1>
+<!-- ~ End section ~ -->
-<!-- ~~~~~ New section ~~~~~ -->
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
-<sect2>
+<sect1 id="config">
<title>The Main Configuration File</title>
+
<para>
Again, the main configuration file is named <filename>config</filename> on
Linux/Unix/BSD and OS/2, and <filename>config.txt</filename> on Windows.
<literal>
<msgtext>
<literallayout>
- <emphasis>blockfile blocklist.ini</emphasis>
- </literallayout>
- </msgtext>
- </literal>
+ <emphasis>confdir /etc/privoxy</emphasis></literallayout>
+ </msgtext>
+ </literal>
</para>
<para>
- Indicates that the blockfile is named <quote>blocklist.ini</quote>. (A
- default installation does not use this.)
+ Assigns the value <literal>/etc/privoxy</literal> to the option
+ <literal>confdir</literal> and thus indicates that the configuration
+ directory is named <quote>/etc/privoxy/</quote>.
</para>
<para>
- A <quote><literal>#</literal></quote> indicates a comment. Any part of a
- line following a <quote><literal>#</literal></quote> is ignored, except if
- the <quote><literal>#</literal></quote> is preceded by a
- <quote><literal>\</literal></quote>.
+ All options in the config file except for <literal>confdir</literal> and
+ <literal>logdir</literal> are optional. Watch out in the below description
+ for what happens if you leave them unset.
</para>
<para>
- Thus, by placing a <quote><literal>#</literal></quote> at the start of an
- existing configuration line, you can make it a comment and it will be treated
- as if it weren't there. This is called <quote>commenting out</quote> an
- option and can be useful to turn off features: If you comment out the
- <quote>logfile</quote> line, <application>Privoxy</application> will not
- log to a file at all. Watch for the <quote>default:</quote> section in each
- explanation to see what happens if the option is left unset (or commented
- out).
+ The main config file controls all aspects of <application>Privoxy</application>'s
+ operation that are not location dependent (i.e. they apply universally, no matter
+ where you may be surfing).
</para>
-<para>
- Long lines can be continued on the next line by using a
- <quote><literal>\</literal></quote> as the very last character.
-</para>
-<para>
- There are various aspects of <application>Privoxy</application> behavior
- that can be tuned.
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="conf-log-loc">
+<title>Configuration and Log File Locations</title>
+
+<para>
+ <application>Privoxy</application> can (and normally does) use a number of
+ other files for additional configuration, help and logging.
+ This section of the configuration file tells <application>Privoxy</application>
+ where to find those other files.
+</para>
+
+<para>
+ The user running Privoxy, must have read permission for all
+ configuration files, and write permission to any files that would
+ be modified, such as log files.
+</para>
+
+<sect3 renderas="sect4" id="confdir"><title>confdir</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>The directory where the other configuration files are located</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>Path name</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>/etc/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para><emphasis>Mandatory</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ No trailing <quote><literal>/</literal></quote>, please
+ </para>
+ <para>
+ When development goes modular and multi-user, the blocker, filter, and
+ per-user config will be stored in subdirectories of <quote>confdir</quote>.
+ For now, the configuration directory structure is flat, except for
+ <filename>confdir/templates</filename>, where the HTML templates for CGI
+ output reside (e.g. <application>Privoxy's</application> 404 error page).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<sect3 renderas="sect4" id="logdir"><title>logdir</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The directory where all logging takes place (i.e. where <filename>logfile</filename> and
+ <filename>jarfile</filename> are located)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>Path name</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>/var/log/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para><emphasis>Mandatory</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ No trailing <quote><literal>/</literal></quote>, please
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="actionsfile"><title>
+actionsfile
+</title>
+<anchor id="default.action">
+<anchor id="standard.action">
+<anchor id="user.action">
+<!-- Note: slightly modified this section 04/28/02, hal. See NOTE. -->
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The <link linkend="actions-file">actions file(s)</link> to use
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>File name, relative to <literal>confdir</literal>, without the <literal>.action</literal> suffix</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default values:</term>
+ <listitem>
+ <simplelist>
+ <member>
+ <msgtext><literallayout> standard # Internal purposes, no editing recommended</literallayout></msgtext>
+ </member>
+ <member>
+ <msgtext><literallayout> default # Main actions file</literallayout></msgtext>
+ </member>
+ <member>
+ <msgtext><literallayout> user # User customizations</literallayout></msgtext>
+ </member>
+ </simplelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No actions are taken at all. Simple neutral proxying.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Multiple <literal>actionsfile</literal> lines are permitted, and are in fact recommended!
+ </para>
+ <para>
+ The default values include standard.action, which is used for internal
+ purposes and should be loaded, default.action, which is the
+ <quote>main</quote> actions file maintained by the developers, and
+ <filename>user.action</filename>, where you can make your personal additions.
+ </para>
+ <para>
+ Actions files are where all the per site and per URL configuration is done for
+ ad blocking, cookie management, privacy considerations, etc.
+ There is no point in using <application>Privoxy</application> without at
+ least one actions file.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="filterfile"><title>filterfile</title>
+<anchor id="default.filter">
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The <link linkend="filter-file">filter file</link> to use
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>File name, relative to <literal>confdir</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>default.filter (Unix) <emphasis>or</emphasis> default.filter.txt (Windows)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No textual content filtering takes place, i.e. all
+ <literal>+<link linkend="filter">filter</link>{<replaceable class="parameter">name</replaceable>}</literal>
+ actions in the actions files are turned neutral.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The <link linkend="filter-file">filter file</link> contains content modification
+ rules that use <link linkend="regex">regular expressions</link>. These rules permit
+ powerful changes on the content of Web pages, e.g., you could disable your favorite
+ JavaScript annoyances, re-write the actual displayed text, or just have some
+ fun replacing <quote>Microsoft</quote> with <quote>MicroSuck</quote> wherever
+ it appears on a Web page.
+ </para>
+ <para>
+ The
+ <literal>+<link linkend="filter">filter</link>{<replaceable class="parameter">name</replaceable>}</literal>
+ actions rely on the relevant filter (<replaceable class="parameter">name</replaceable>)
+ to be defined in the filter file!
+ </para>
+ <para>
+ A pre-defined filter file called <filename>default.filter</filename> that contains
+ a bunch of handy filters for common problems is included in the distribution.
+ See the section on the <literal><link linkend="filter">filter</link></literal>
+ action for a list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="logfile"><title>logfile</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The log file to use
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>File name, relative to <literal>logdir</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>logfile (Unix) <emphasis>or</emphasis> privoxy.log (Windows)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No log file is used, all log messages go to the console (<literal>stderr</literal>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The windows version will additionally log to the console.
+ </para>
+ <para>
+ The logfile is where all logging and error messages are written. The level
+ of detail and number of messages are set with the <literal>debug</literal>
+ option (see below). The logfile can be useful for tracking down a problem with
+ <application>Privoxy</application> (e.g., it's not blocking an ad you
+ think it should block) but in most cases you probably will never look at it.
+ </para>
+ <para>
+ Your logfile will grow indefinitely, and you will probably want to
+ periodically remove it. On Unix systems, you can do this with a cron job
+ (see <quote>man cron</quote>). For Red Hat, a <command>logrotate</command>
+ script has been included.
+ </para>
+ <para>
+ On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
+ +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
+ the effect that cron.daily will automatically archive, gzip, and empty the
+ log, when it exceeds 1M size.
+ </para>
+ <para>
+ Any log files must be writable by whatever user <application>Privoxy</application>
+ is being run as (default on UNIX, user id is <quote>privoxy</quote>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="jarfile"><title>jarfile</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The file to store intercepted cookies in
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>File name, relative to <literal>logdir</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Intercepted cookies are not stored at all.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The jarfile may grow to ridiculous sizes over time.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="trustfile"><title>trustfile</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The trust file to use
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>File name, relative to <literal>confdir</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset (commented out)</emphasis>. When activated: trust (Unix) <emphasis>or</emphasis> trust.txt (Windows)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ The whole trust mechanism is turned off.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The trust mechanism is an experimental feature for building white-lists and should
+ be used with care. It is <emphasis>NOT</emphasis> recommended for the casual user.
+ </para>
+ <para>
+ If you specify a trust file, <application>Privoxy</application> will only allow
+ access to sites that are named in the trustfile.
+ You can also mark sites as trusted referrers (with <literal>+</literal>), with
+ the effect that access to untrusted sites will be granted, if a link from a
+ trusted referrer was used.
+ The link target will then be added to the <quote>trustfile</quote>.
+ Possible applications include limiting Internet access for children.
+ </para>
+ <para>
+ If you use <literal>+</literal> operator in the trust file, it may grow considerably over time.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="local-set-up">
+<title>Local Set-up Documentation</title>
+
+ <para>
+ If you intend to operate <application>Privoxy</application> for more users
+ than just yourself, it might be a good idea to let them know how to reach
+ you, what you block and why you do that, your policies, etc.
+ </para>
+
+<sect3 renderas="sect4" id="user-manual"><title>user-manual</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Location of the <application>Privoxy</application> User Manual.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>A fully qualified URI</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ <ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/<replaceable class="parameter">version</replaceable>/user-manual/</ulink>
+ will be used, where <replaceable class="parameter">version</replaceable> is the <application>Privoxy</application> version.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The User Manual URI is used for help links from some of the internal CGI pages.
+ The manual itself is normally packaged with the binary distributions, so you probably want
+ to set this to a locally installed copy. For multi-user setups, you could provide a copy on
+ a local webserver for all your users and use the corresponding URL here.
+ </para>
+ <para>
+ Examples:
+ </para>
+ <para>
+ Unix, in local filesystem:
+ </para>
+ <para>
+ <screen>user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/</screen>
+ </para>
+ <para>
+ Any platform, on local webserver (called <quote>local-webserver</quote>):
+ </para>
+ <para>
+ <screen>user-manual http://local-webserver/privoxy-user-manual/</screen>
+ </para>
+ <warning>
+ <para>
+ If set, this option should be <emphasis>the first option in the config file</emphasis>, because
+ it is used while the config file is being read.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="trust-info-url"><title>trust-info-url</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>URL</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>Two example URL are provided</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No links are displayed on the "untrusted" error page.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The value of this option only matters if the experimental trust mechanism has been
+ activated. (See <link linkend="trustfile"><emphasis>trustfile</emphasis></link> above.)
+ </para>
+ <para>
+ If you use the trust mechanism, it is a good idea to write up some on-line
+ documentation about your trust policy and to specify the URL(s) here.
+ Use multiple times for multiple URLs.
+ </para>
+ <para>
+ The URL(s) should be added to the trustfile as well, so users don't end up
+ locked out from the information on why they were locked out in the first place!
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="admin-address"><title>admin-address</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ An email address to reach the proxy administrator.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>Email address</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No email address is displayed on error pages and the CGI user interface.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
+ are unset, the whole "Local Privoxy Support" box on all generated pages will
+ not be shown.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="proxy-info-url"><title>proxy-info-url</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ A URL to documentation about the local <application>Privoxy</application> setup,
+ configuration or policies.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>URL</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No link to local documentation is displayed on error pages and the CGI user interface.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
+ are unset, the whole "Local Privoxy Support" box on all generated pages will
+ not be shown.
+ </para>
+ <para>
+ This URL shouldn't be blocked ;-)
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+</sect2>
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="debugging">
+<title>Debugging</title>
+
+ <para>
+ These options are mainly useful when tracing a problem.
+ Note that you might also want to invoke
+ <application>Privoxy</application> with the <literal>--no-daemon</literal>
+ command line option when debugging.
+ </para>
+
+<sect3 renderas="sect4" id="debug"><title>debug</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Key values that determine what information gets logged to the
+ <link linkend="logfile"><emphasis>logfile</emphasis></link>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>Integer values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>12289 (i.e.: URLs plus informational and warning messages)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Nothing gets logged.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The available debug levels are:
+ </para>
+ <para>
+ <programlisting>
+ debug 1 # show each GET/POST/CONNECT request
+ debug 2 # show each connection status
+ debug 4 # show I/O status
+ debug 8 # show header parsing
+ debug 16 # log all data into the logfile
+ debug 32 # debug force feature
+ debug 64 # debug regular expression filter
+ debug 128 # debug fast redirects
+ debug 256 # debug GIF de-animation
+ debug 512 # Common Log Format
+ debug 1024 # debug kill pop-ups
+ debug 4096 # Startup banner and warnings.
+ debug 8192 # Non-fatal errors
+</programlisting>
+ </para>
+ <para>
+ To select multiple debug levels, you can either add them or use
+ multiple <literal>debug</literal> lines.
+ </para>
+ <para>
+ A debug level of 1 is informative because it will show you each request
+ as it happens. <emphasis>1, 4096 and 8192 are highly recommended</emphasis>
+ so that you will notice when things go wrong. The other levels are probably
+ only of interest if you are hunting down a specific problem. They can produce
+ a hell of an output (especially 16).
+ <!-- LOL -->
+ </para>
+ <para>
+ The reporting of <emphasis>fatal</emphasis> errors (i.e. ones which crash
+ <application>Privoxy</application>) is always on and cannot be disabled.
+ </para>
+ <para>
+ If you want to use CLF (Common Log Format), you should set <quote>debug
+ 512</quote> <emphasis>ONLY</emphasis> and not enable anything else.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="single-threaded"><title>single-threaded</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether to run only one server thread
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para><emphasis>None</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to
+ serve multiple requests simultaneously.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This option is only there for debug purposes and you should never
+ need to use it. <emphasis>It will drastically reduce performance.</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+</sect2>
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="access-control">
+<title>Access Control and Security</title>
+
+ <para>
+ This section of the config file controls the security-relevant aspects
+ of <application>Privoxy</application>'s configuration.
+ </para>
+
+<sect3 renderas="sect4" id="listen-address"><title>listen-address</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The IP address and TCP port on which <application>Privoxy</application> will
+ listen for client requests.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>[<replaceable class="parameter">IP-Address</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>127.0.0.1:8118</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Bind to 127.0.0.1 (localhost), port 8118. This is suitable and recommended for
+ home users who run <application>Privoxy</application> on the same machine as
+ their browser.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ You will need to configure your browser(s) to this proxy address and port.
+ </para>
+ <para>
+ If you already have another service running on port 8118, or if you want to
+ serve requests from other machines (e.g. on your local network) as well, you
+ will need to override the default.
+ </para>
+ <para>
+ If you leave out the IP address, <application>Privoxy</application> will
+ bind to all interfaces (addresses) on your machine and may become reachable
+ from the Internet. In that case, consider using access control lists (ACL's)
+ (see <quote>ACLs</quote> below), or a firewall.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Example:</term>
+ <listitem>
+ <para>
+ Suppose you are running <application>Privoxy</application> on
+ a machine which has the address 192.168.0.1 on your local private network
+ (192.168.0.0) and has another outside connection with a different address.
+ You want it to serve requests from inside only:
+ </para>
+ <para>
+ <programlisting>
+ listen-address 192.168.0.1:8118
+</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="toggle"><title>toggle</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Initial state of "toggle" status
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>1 or 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Act as if toggled on
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ If set to 0, <application>Privoxy</application> will start in
+ <quote>toggled off</quote> mode, i.e. behave like a normal, content-neutral
+ proxy where all ad blocking, filtering, etc are disabled. See
+ <literal>enable-remote-toggle</literal> below. This is not really useful
+ anymore, since toggling is much easier via <ulink
+ url="http://config.privoxy.org/toggle">the web interface</ulink> than via
+ editing the <filename>conf</filename> file.
+ </para>
+ <para>
+ The windows version will only display the toggle icon in the system tray
+ if this option is present.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<sect3 renderas="sect4" id="enable-remote-toggle"><title>enable-remote-toggle</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether or not the <ulink url="http://config.privoxy.org/toggle">web-based toggle
+ feature</ulink> may be used
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>0 or 1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ The web-based toggle feature is disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ When toggled off, <application>Privoxy</application> acts like a normal,
+ content-neutral proxy, i.e. it acts as if none of the actions applied to
+ any URL.
+ </para>
+ <para>
+ For the time being, access to the toggle feature can <emphasis>not</emphasis> be
+ controlled separately by <quote>ACLs</quote> or HTTP authentication,
+ so that everybody who can access <application>Privoxy</application> (see
+ <quote>ACLs</quote> and <literal>listen-address</literal> above) can
+ toggle it for all users. So this option is <emphasis>not recommended</emphasis>
+ for multi-user environments with untrusted users.
+ </para>
+ <para>
+ Note that you must have compiled <application>Privoxy</application> with
+ support for this feature, otherwise this option has no effect.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<sect3 renderas="sect4" id="enable-edit-actions"><title>enable-edit-actions</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether or not the <ulink url="http://config.privoxy.org/show-status">web-based actions
+ file editor</ulink> may be used
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>0 or 1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ The web-based actions file editor is disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ For the time being, access to the editor can <emphasis>not</emphasis> be
+ controlled separately by <quote>ACLs</quote> or HTTP authentication,
+ so that everybody who can access <application>Privoxy</application> (see
+ <quote>ACLs</quote> and <literal>listen-address</literal> above) can
+ modify its configuration for all users. So this option is <emphasis>not
+ recommended</emphasis> for multi-user environments with untrusted users.
+ </para>
+ <para>
+ Note that you must have compiled <application>Privoxy</application> with
+ support for this feature, otherwise this option has no effect.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="acls"><title>
+ACLs: permit-access and deny-access</title>
+<anchor id="permit-acces">
+<anchor id="deny-acces">
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Who can access what.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable class="parameter">src_addr</replaceable>[/<replaceable class="parameter">src_masklen</replaceable>]
+ [<replaceable class="parameter">dst_addr</replaceable>[/<replaceable class="parameter">dst_masklen</replaceable>]]
+ </para>
+ <para>
+ Where <replaceable class="parameter">src_addr</replaceable> and
+ <replaceable class="parameter">dst_addr</replaceable> are IP addresses in dotted decimal notation or valid
+ DNS names, and <replaceable class="parameter">src_masklen</replaceable> and
+ <replaceable class="parameter">dst_masklen</replaceable> are subnet masks in CIDR notation, i.e. integer
+ values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
+ destination part are optional.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Don't restrict access further than implied by <literal>listen-address</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Access controls are included at the request of ISPs and systems
+ administrators, and <emphasis>are not usually needed by individual users</emphasis>.
+ For a typical home user, it will normally suffice to ensure that
+ <application>Privoxy</application> only listens on the localhost
+ (127.0.0.1) or internal (home) network address by means of the
+ <link linkend="listen-address"><emphasis>listen-address</emphasis></link>
+ option.
+ </para>
+ <para>
+ Please see the warnings in the FAQ that this proxy is not intended to be a substitute
+ for a firewall or to encourage anyone to defer addressing basic security
+ weaknesses.
+ </para>
+ <para>
+ Multiple ACL lines are OK.
+ If any ACLs are specified, then the <application>Privoxy</application>
+ talks only to IP addresses that match at least one <literal>permit-access</literal> line
+ and don't match any subsequent <literal>deny-access</literal> line. In other words, the
+ last match wins, with the default being <literal>deny-access</literal>.
+ </para>
+ <para>
+ If <application>Privoxy</application> is using a forwarder (see <literal>forward</literal> below)
+ for a particular destination URL, the <replaceable class="parameter">dst_addr</replaceable>
+ that is examined is the address of the forwarder and <emphasis>NOT</emphasis> the address
+ of the ultimate target. This is necessary because it may be impossible for the local
+ <application>Privoxy</application> to determine the IP address of the
+ ultimate target (that's often what gateways are used for).
+ </para>
+ <para>
+ You should prefer using IP addresses over DNS names, because the address lookups take
+ time. All DNS names must resolve! You can <emphasis>not</emphasis> use domain patterns
+ like <quote>*.org</quote> or partial domain names. If a DNS name resolves to multiple
+ IP addresses, only the first one is used.
+ </para>
+ <para>
+ Denying access to particular sites by ACL may have undesired side effects
+ if the site in question is hosted on a machine which also hosts other sites.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ Explicitly define the default behavior if no ACL and
+ <literal>listen-address</literal> are set: <quote>localhost</quote>
+ is OK. The absence of a <replaceable class="parameter">dst_addr</replaceable> implies that
+ <emphasis>all</emphasis> destination addresses are OK:
+ </para>
+ <para>
+ <screen>
+ permit-access localhost
+</screen>
+ </para>
+ <para>
+ Allow any host on the same class C subnet as www.privoxy.org access to
+ nothing but www.example.com:
+ </para>
+ <para>
+ <screen>
+ permit-access www.privoxy.org/24 www.example.com/32
+</screen>
+ </para>
+ <para>
+ Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
+ with the exception that 192.168.45.73 may not access www.dirty-stuff.example.com:
+ </para>
+ <para>
+ <screen>
+ permit-access 192.168.45.64/26
+ deny-access 192.168.45.73 www.dirty-stuff.example.com
+</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="buffer-limit"><title>buffer-limit</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Maximum size of the buffer for content filtering.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>Size in Kbytes</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>4096</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Use a 4MB (4096 KB) limit.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ For content filtering, i.e. the <literal>+filter</literal> and
+ <literal>+deanimate-gif</literal> actions, it is necessary that
+ <application>Privoxy</application> buffers the entire document body.
+ This can be potentially dangerous, since a server could just keep sending
+ data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
+ Hence this option.
+ </para>
+ <para>
+ When a document buffer size reaches the <literal>buffer-limit</literal>, it is
+ flushed to the client unfiltered and no further attempt to
+ filter the rest of the document is made. Remember that there may be multiple threads
+ running, which might require up to <literal>buffer-limit</literal> Kbytes
+ <emphasis>each</emphasis>, unless you have enabled <quote>single-threaded</quote>
+ above.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="forwarding">
+<title>Forwarding</title>
+
+<para>
+ This feature allows routing of HTTP requests through a chain of
+ multiple proxies.
+ It can be used to better protect privacy and confidentiality when
+ accessing specific domains by routing requests to those domains
+ through an anonymous public proxy (see e.g. <ulink
+ url="http://www.multiproxy.org/anon_list.htm">http://www.multiproxy.org/anon_list.htm</ulink>)
+ Or to use a caching proxy to speed up browsing. Or chaining to a parent
+ proxy may be necessary because the machine that <application>Privoxy</application>
+ runs on has no direct Internet access.
+</para>
+
+<para>
+ Also specified here are SOCKS proxies. <application>Privoxy</application>
+ supports the SOCKS 4 and SOCKS 4A protocols.
+</para>
+
+<sect3 renderas="sect4" id="forward"><title>forward</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ To which parent HTTP proxy specific requests should be routed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
+ <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
+ </para>
+ <para>
+ Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
+ chapter on domain matching in the <filename>default.action</filename> file),
+ <replaceable class="parameter">http_parent</replaceable> is the address of the parent HTTP proxy
+ as an IP addresses in dotted decimal notation or as a valid DNS name (or <quote>.</quote> to denote
+ <quote>no forwarding</quote>, and the optional
+ <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer
+ values from 1 to 64535
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Don't use parent HTTP proxies.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
+ forwarded to another HTTP proxy but are made directly to the web servers.
+ </para>
+ <para>
+ Multiple lines are OK, they are checked in sequence, and the last match wins.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle):
+ </para>
+ <para>
+ <screen>
+ forward .* anon-proxy.example.org:8080
+ forward :443 .
+</screen>
+ </para>
+ <para>
+ Everything goes to our example ISP's caching proxy, except for requests
+ to that ISP's sites:
+ </para>
+ <para>
+ <screen>
+ forward .*. caching-proxy.example-isp.net:8000
+ forward .example-isp.net .
+</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="socks"><title>
+forward-socks4 and forward-socks4a</title>
+<anchor id="forward-socks4">
+<anchor id="forward-socks4a">
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
+ <replaceable class="parameter">socks_proxy</replaceable>[/<replaceable class="parameter">port</replaceable>]
+ <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
+ </para>
+ <para>
+ Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
+ chapter on domain matching in the <filename>default.action</filename> file),
+ <replaceable class="parameter">http_parent</replaceable> and <replaceable class="parameter">socks_proxy</replaceable>
+ are IP addresses in dotted decimal notation or valid DNS names (<replaceable class="parameter">http_parent</replaceable>
+ may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
+ <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer values from 1 to 64535
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Don't use SOCKS proxies.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Multiple lines are OK, they are checked in sequence, and the last match wins.
+ </para>
+ <para>
+ The difference between <literal>forward-socks4</literal> and <literal>forward-socks4a</literal>
+ is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
+ server, while in SOCKS 4 it happens locally.
+ </para>
+ <para>
+ If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
+ forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
+ a SOCKS proxy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ From the company example.com, direct connections are made to all
+ <quote>internal</quote> domains, but everything outbound goes through
+ their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
+ the Internet.
+ </para>
+ <para>
+ <screen>
+ forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
+ forward .example.com .
+</screen>
+ </para>
+ <para>
+ A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
+ </para>
+ <para>
+ <screen>
+ forward-socks4 .*. socks-gw.example.com:1080 .
+</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 renderas="sect4" id="advanced-forwarding-examples"><title>Advanced Forwarding Examples</title>
+
+<para>
+ If you have links to multiple ISPs that provide various special content
+ only to their subscribers, you can configure multiple <application>Privoxies</application>
+ which have connections to the respective ISPs to act as forwarders to each other, so that
+ <emphasis>your</emphasis> users can see the internal content of all ISPs.
+</para>
+
+<para>
+ Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP connection to
+ isp-b.net. Both run <application>Privoxy</application>. Their forwarding
+ configuration can look like this:
+</para>
+
+<para>
+ host-a:
+</para>
+
+<para>
+ <screen>
+ forward .*. .
+ forward .isp-b.net host-b:8118
+</screen>
+</para>
+
+<para>
+ host-b:
+</para>
+
+<para>
+ <screen>
+ forward .*. .
+ forward .isp-a.net host-a:8118
+</screen>
+</para>
+
+<para>
+ Now, your users can set their browser's proxy to use either
+ host-a or host-b and be able to browse the internal content
+ of both isp-a and isp-b.
+</para>
+
+<para>
+ If you intend to chain <application>Privoxy</application> and
+ <application>squid</application> locally, then chain as
+ <literal>browser -> squid -> privoxy</literal> is the recommended way.
+</para>
+
+<para>
+ Assuming that <application>Privoxy</application> and <application>squid</application>
+ run on the same box, your squid configuration could then look like this:
+</para>
+
+<para>
+ <screen>
+ # Define Privoxy as parent proxy (without ICP)
+ cache_peer 127.0.0.1 parent 8118 7 no-query
+
+ # Define ACL for protocol FTP
+ acl ftp proto FTP
+
+ # Do not forward FTP requests to Privoxy
+ always_direct allow ftp
+
+ # Forward all the rest to Privoxy
+ never_direct allow all</screen>
+</para>
+
+<para>
+ You would then need to change your browser's proxy settings to <application>squid</application>'s address and port.
+ Squid normally uses port 3128. If unsure consult <literal>http_port</literal> in <filename>squid.conf</filename>.
+</para>
+
+</sect3>
+
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="windows-gui">
+<title>Windows GUI Options</title>
+<para>
+ <application>Privoxy</application> has a number of options specific to the
+ Windows GUI interface:
+</para>
+
+<anchor id="activity-animation">
+<para>
+ If <quote>activity-animation</quote> is set to 1, the
+ <application>Privoxy</application> icon will animate when
+ <quote>Privoxy</quote> is active. To turn off, set to 0.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>activity-animation 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<anchor id="log-messages">
+<para>
+ If <quote>log-messages</quote> is set to 1,
+ <application>Privoxy</application> will log messages to the console
+ window:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>log-messages 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<anchor id="log-buffer-size">
+<para>
+ If <quote>log-buffer-size</quote> is set to 1, the size of the log buffer,
+ i.e. the amount of memory used for the log messages displayed in the
+ console window, will be limited to <quote>log-max-lines</quote> (see below).
+</para>
+
+<para>
+ Warning: Setting this to 0 will result in the buffer to grow infinitely and
+ eat up all your memory!
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>log-buffer-size 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<anchor id="log-max-lines">
+<para>
+ <application>log-max-lines</application> is the maximum number of lines held
+ in the log buffer. See above.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>log-max-lines 200</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<anchor id="log-highlight-messages">
+<para>
+ If <quote>log-highlight-messages</quote> is set to 1,
+ <application>Privoxy</application> will highlight portions of the log
+ messages with a bold-faced font:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>log-highlight-messages 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<anchor id="log-font-name">
+<para>
+ The font used in the console window:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>log-font-name Comic Sans MS</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<anchor id="log-font-size">
+<para>
+ Font size used in the console window:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>log-font-size 8</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<anchor id="show-on-task-bar">
+<para>
+ <quote>show-on-task-bar</quote> controls whether or not
+ <application>Privoxy</application> will appear as a button on the Task bar
+ when minimized:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>show-on-task-bar 0</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<anchor id="close-button-minimizes">
+<para>
+ If <quote>close-button-minimizes</quote> is set to 1, the Windows close
+ button will minimize <application>Privoxy</application> instead of closing
+ the program (close with the exit option on the File menu).
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>close-button-minimizes 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<anchor id="hide-console">
+<para>
+ The <quote>hide-console</quote> option is specific to the MS-Win console
+ version of <application>Privoxy</application>. If this option is used,
+ <application>Privoxy</application> will disconnect from and hide the
+ command console.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ #<emphasis>hide-console</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+</sect2>
+</sect1>
+
+<!-- ~ End section ~ -->
+
+
+
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+
+<sect1 id="actions-file"><title>Actions Files</title>
+
+<para>
+ The actions files are used to define what actions
+ <application>Privoxy</application> takes for which URLs, and thus determine
+ how ad images, cookies and various other aspects of HTTP content and
+ transactions are handled, and on which sites (or even parts thereof). There
+ are three such files included with <application>Privoxy</application> (as of
+ version 2.9.15), with differing purposes:
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename>default.action</filename> - is the primary action file
+ that sets the initial values for all actions. It is intended to
+ provide a base level of functionality for
+ <application>Privoxy's</application> array of features. So it is
+ a set of broad rules that should work reasonably well for users everywhere.
+ This is the file that the developers are keeping updated, and making
+ available to users.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>user.action</filename> - is intended to be for local site
+ preferences and exceptions. As an example, if your ISP or your bank
+ has specific requirements, and need special handling, this kind of
+ thing should go here. This file will not be upgraded.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>standard.action</filename> - is used by the web based editor,
+ to set various pre-defined sets of rules for the default actions section
+ in <filename>default.action</filename>. These have increasing levels of
+ aggressiveness <emphasis>and have no influence on your browsing unless
+ you select them explicitly in the editor</emphasis>. It is not recommend
+ to edit this file.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+<para>
+ The list of actions files to be used are defined in the main configuration
+ file, and are processed in the order they are defined. The content of these
+ can all be viewed and edited from <ulink
+ url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
+</para>
+
+<para>
+ An actions file typically has multiple sections. If you want to use
+ <quote>aliases</quote> in an actions file, you have to place the (optional)
+ <link linkend="aliases">alias section</link> at the top of that file.
+ Then comes the default set of rules which will apply universally to all
+ sites and pages (be <emphasis>very careful</emphasis> with using such a
+ universal set in <filename>user.action</filename> or any other actions file after
+ <filename>default.action</filename>, because it will override the result
+ from consulting any previous file). And then below that,
+ exceptions to the defined universal policies. You can regard
+ <filename>user.action</filename> as an appendix to <filename>default.action</filename>,
+ with the advantage that is a separate file, which makes preserving your
+ personal settings across <application>Privoxy</application> upgrades easier.
+</para>
+
+<para>
+ Actions can be used to block anything you want, including ads, banners, or
+ just some obnoxious URL that you would rather not see. Cookies can be accepted
+ or rejected, or accepted only during the current browser session (i.e. not
+ written to disk), content can be modified, JavaScripts tamed, user-tracking
+ fooled, and much more. See below for a <link linkend="actions">complete list
+ of actions</link>.
+</para>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2>
+<title>Finding the Right Mix</title>
+<para>
+ Note that some <link linkend="actions">actions</link>, like cookie suppression
+ or script disabling, may render some sites unusable that rely on these
+ techniques to work properly. Finding the right mix of actions is not always easy and
+ certainly a matter of personal taste. In general, it can be said that the more
+ <quote>aggressive</quote> your default settings (in the top section of the
+ actions file) are, the more exceptions for <quote>trusted</quote> sites you
+ will have to make later. If, for example, you want to kill popup windows per
+ default, you'll have to make exceptions from that rule for sites that you
+ regularly use and that require popups for actually useful content, like maybe
+ your bank, favorite shop, or newspaper.
+</para>
+
+<para>
+ We have tried to provide you with reasonable rules to start from in the
+ distribution actions files. But there is no general rule of thumb on these
+ things. There just are too many variables, and sites are constantly changing.
+ Sooner or later you will want to change the rules (and read this chapter again :).
+</para>
+</sect2>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2>
+<title>How to Edit</title>
+<para>
+ The easiest way to edit the actions files is with a browser by
+ using our browser-based editor, which can be reached from <ulink
+ url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
+ The editor allows both fine-grained control over every single feature on a
+ per-URL basis, and easy choosing from wholesale sets of defaults like
+ <quote>Cautious</quote>, <quote>Medium</quote> or <quote>Advanced</quote>.
+</para>
+
+<para>
+ If you prefer plain text editing to GUIs, you can of course also directly edit the
+ the actions files. Look at <filename>default.action</filename> which is richly
+ commented.
</para>
+</sect2>
+
+
+<sect2 id="actions-apply">
+<title>How Actions are Applied to URLs</title>
+<para>
+ Actions files are divided into sections. There are special sections,
+ like the <quote><link linkend="aliases">alias</link></quote> sections which will be discussed later. For now
+ let's concentrate on regular sections: They have a heading line (often split
+ up to multiple lines for readability) which consist of a list of actions,
+ separated by whitespace and enclosed in curly braces. Below that, there
+ is a list of URL patterns, each on a separate line.
+</para>
+
+<para>
+ To determine which actions apply to a request, the URL of the request is
+ compared to all patterns in each action file file. Every time it matches, the list of
+ applicable actions for the URL is incrementally updated, using the heading
+ of the section in which the pattern is located. If multiple matches for
+ the same URL set the same action differently, the last match wins. If not,
+ the effects are aggregated (e.g. a URL might match both the
+ <ulink url="actions-file.html#HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></ulink>
+ and <ulink url="actions-file.html#BLOCK"><quote>+block</quote></ulink> actions).
+
+</para>
+
+<para>
+ You can trace this process for any given URL by visiting <ulink
+ url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
+</para>
+
+<para>
+ More detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
+ Anatomy of an Action</link>.
+</para>
+</sect2>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="af-patterns">
+<title>Patterns</title>
+<para>
+ Generally, a pattern has the form <literal><domain>/<path></literal>,
+ where both the <literal><domain></literal> and <literal><path></literal>
+ are optional. (This is why the pattern <literal>/</literal> matches all URLs).
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><literal>www.example.com/</literal></term>
+ <listitem>
+ <para>
+ is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
+ regardless of which document on that server is requested.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>www.example.com</literal></term>
+ <listitem>
+ <para>
+ means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
+ be omitted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>www.example.com/index.html</literal></term>
+ <listitem>
+ <para>
+ matches only the single document <literal>/index.html</literal>
+ on <literal>www.example.com</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>/index.html</literal></term>
+ <listitem>
+ <para>
+ matches the document <literal>/index.html</literal>, regardless of the domain,
+ i.e. on <emphasis>any</emphasis> web server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>index.html</literal></term>
+ <listitem>
+ <para>
+ matches nothing, since it would be interpreted as a domain name and
+ there is no top-level domain called <literal>.html</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3><title>The Domain Pattern</title>
+
+<para>
+ The matching of the domain part offers some flexible options: if the
+ domain starts or ends with a dot, it becomes unanchored at that end.
+ For example:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><literal>.example.com</literal></term>
+ <listitem>
+ <para>
+ matches any domain that <emphasis>ENDS</emphasis> in
+ <literal>.example.com</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>www.</literal></term>
+ <listitem>
+ <para>
+ matches any domain that <emphasis>STARTS</emphasis> with
+ <literal>www.</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>.example.</literal></term>
+ <listitem>
+ <para>
+ matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>
+ (Correctly speaking: It matches any FQDN that contains <literal>example</literal> as a domain.)
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+ Additionally, there are wild-cards that you can use in the domain names
+ themselves. They work pretty similar to shell wild-cards: <quote>*</quote>
+ stands for zero or more arbitrary characters, <quote>?</quote> stands for
+ any single character, you can define character classes in square
+ brackets and all of that can be freely mixed:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><literal>ad*.example.com</literal></term>
+ <listitem>
+ <para>
+ matches <quote>adserver.example.com</quote>,
+ <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>*ad*.example.com</literal></term>
+ <listitem>
+ <para>
+ matches all of the above, and then some.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>.?pix.com</literal></term>
+ <listitem>
+ <para>
+ matches <literal>www.ipix.com</literal>,
+ <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>www[1-9a-ez].example.c*</literal></term>
+ <listitem>
+ <para>
+ matches <literal>www1.example.com</literal>,
+ <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>,
+ <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis>
+ <literal>wwww.example.com</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<!-- ~~~~~ New section ~~~~~ -->
+<!-- ~ End section ~ -->
-<sect3>
-<title>Defining Other Configuration Files</title>
-<para>
- <application>Privoxy</application> can use a number of other files to tell it
- what ads to block, what cookies to accept, etc. This section of the
- configuration file tells <application>Privoxy</application> where to find
- all those other files.
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3><title>The Path Pattern</title>
<para>
- On <application>Windows</application> and <application>AmigaOS</application>,
- <application>Privoxy</application> looks for these files in the same
- directory as the executable. On Unix and OS/2,
- <application>Privoxy</application> looks for these files in the current
- working directory. In either case, an absolute path name can be used to
- avoid problems.
+ <application>Privoxy</application> uses Perl compatible regular expressions
+ (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
+ matching the path.
</para>
<para>
- When development goes modular and multi-user, the blocker, filter, and
- per-user config will be stored in subdirectories of <quote>confdir</quote>.
- For now, only <filename>confdir/templates</filename> is used for storing HTML
- templates for CGI results.
+ There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
+ expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
+ at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
+ You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
+ useful, which is available on-line at <ulink
+ url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>.
</para>
<para>
- The location of the configuration files:
+ Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
+ i.e. it matches as if it would start with a <quote>^</quote> (regular expression speak
+ for the beginning of a line).
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>confdir /etc/privoxy</emphasis> # No trailing /, please.
- </literallayout>
- </msgtext>
- </literal>
+ Please also note that matching in the path is case
+ <emphasis>INSENSITIVE</emphasis> by default, but you can switch to case
+ sensitive at any point in the pattern by using the
+ <quote>(?-i)</quote> switch:
+ <literal>www.example.com/(?-i)PaTtErN.*</literal> will match only
+ documents whose path starts with <literal>PaTtErN</literal> in
+ <emphasis>exactly</emphasis> this capitalization.
</para>
+</sect3>
-<para>
- The directory where all logging (i.e. <filename>logfile</filename> and
- <filename>jarfile</filename>) takes place. No trailing
- <quote><literal>/</literal></quote>, please:
-</para>
+</sect2>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>logdir /var/log/privoxy</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<!-- ~ End section ~ -->
-<para>
- Note that all file specifications below are relative to
- the above two directories!
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="actions">
+<title>Actions</title>
<para>
- The <quote>default.action</quote> file contains patterns to specify the
- actions to apply to requests for each site. Default: Cookies to and from all
- destinations are kept only during the current browser session (i.e. they are
- not saved to disk). Pop-ups are disabled for all sites. All sites are
- filtered through selected sections of <quote>default.filter</quote>. No sites
- are blocked. <application>Privoxy</application> displays a checkboard type
- pattern for filtered ads and other images. The syntax of this file is
- explained in detail <link linkend="actionsfile">below</link>. Other
- <quote>actions</quote> files are included, and you are free to use any of
- them. They have varying degrees of aggressiveness.
+ All actions are disabled by default, until they are explicitly enabled
+ somewhere in an actions file. Actions are turned on if preceded with a
+ <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
+ <literal>+action</literal> means <quote>do that action</quote>, e.g.
+ <literal>+block</literal> means <quote>please block URLs that match the
+ following patterns</quote>, and <literal>-block</literal> means <quote>don't
+ block URLs that match the following patterns, even if <literal>+block</literal>
+ previously applied.</quote>
+
</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>actionsfile default.action</emphasis>
- </literallayout>
- </msgtext>
- </literal>
+<para>
+ Again, actions are invoked by placing them on a line, enclosed in curly braces and
+ separated by whitespace, like in
+ <literal>{+some-action -some-other-action{some-parameter}}</literal>,
+ followed by a list of URL patterns, one per line, to which they apply.
+ Together, the actions line and the following pattern lines make up a section
+ of the actions file.
</para>
-<para>
- The <quote>default.filter</quote> file contains content modification rules
- that use <quote>regular expressions</quote>. These rules permit powerful
- changes on the content of Web pages, e.g., you could disable your favorite
- JavaScript annoyances, re-write the actual displayed text, or just have some
- fun replacing <quote>Microsoft</quote> with <quote>MicroSuck</quote> wherever
- it appears on a Web page. Default: whatever the developers are playing with
- :-/
+<para>
+ There are three classes of actions:
</para>
<para>
- Filtering requires buffering the page content, which may appear to slow down
- page rendering since nothing is displayed until all content has passed
- the filters. (It does not really take longer, but seems that way since
- the page is not incrementally displayed.) This effect will be more noticeable
- on slower connections.
+ <itemizedlist>
+ <listitem>
+ <para>
+ Boolean, i.e the action can only be <quote>enabled</quote> or
+ <quote>disabled</quote>. Syntax:
+ </para>
+ <para>
+ <screen>
+ +<replaceable class="function">name</replaceable> # enable action <replaceable class="parameter">name</replaceable>
+ -<replaceable class="function">name</replaceable> # disable action <replaceable class="parameter">name</replaceable></screen>
+ </para>
+ <para>
+ Example: <literal>+block</literal>
+ </para>
+ </listitem>
-</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>filterfile default.filter</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <listitem>
+ <para>
+ Parameterized, where some value is required in order to enable this type of action.
+ Syntax:
+ </para>
+ <para>
+ <screen>
+ +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and set parameter to <replaceable class="parameter">param</replaceable>,
+ # overwriting parameter from previous match if necessary
+ -<replaceable class="function">name</replaceable> # disable action. The parameter can be omitted</screen>
+ </para>
+ <para>
+ Note that if the URL matches multiple positive forms of a parameterized action,
+ the last match wins, i.e. the params from earlier matches are simply ignored.
+ </para>
+ <para>
+ Example: <literal>+hide-user-agent{ Mozilla 1.0 }</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Multi-value. These look exactly like parameterized actions,
+ but they behave differently: If the action applies multiple times to the
+ same URL, but with different parameters, <emphasis>all</emphasis> the parameters
+ from <emphasis>all</emphasis> matches are remembered. This is used for actions
+ that can be executed for the same request repeatedly, like adding multiple
+ headers, or filtering through multiple filters. Syntax:
+ </para>
+ <para>
+ <screen>
+ +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and add <replaceable class="parameter">param</replaceable> to the list of parameters
+ -<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # remove the parameter <replaceable class="parameter">param</replaceable> from the list of parameters
+ # If it was the last one left, disable the action.
+ <replaceable class="parameter">-name</replaceable> # disable this action completely and remove all parameters from the list</screen>
+ </para>
+ <para>
+ Examples: <literal>+add-header{X-Fun-Header: Some text}</literal> and
+ <literal>+filter{html-annoyances}</literal>
+ </para>
+ </listitem>
-<para>
- The logfile is where all logging and error messages are written. The logfile
- can be useful for tracking down a problem with
- <application>Privoxy</application> (e.g., it's not blocking an ad you
- think it should block) but in most cases you probably will never look at it.
+ </itemizedlist>
</para>
<para>
- Your logfile will grow indefinitely, and you will probably want to
- periodically remove it. On Unix systems, you can do this with a cron job
- (see <quote>man cron</quote>). For Redhat, a <command>logrotate</command>
- script has been included.
+ If nothing is specified in any actions file, no <quote>actions</quote> are
+ taken. So in this case <application>Privoxy</application> would just be a
+ normal, non-blocking, non-anonymizing proxy. You must specifically enable the
+ privacy and blocking features you need (although the provided default actions
+ files will give a good starting point).
</para>
<para>
- On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
- +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
- the effect that cron.daily will automatically archive, gzip, and empty the
- log, when it exceeds 1M size.
+ Later defined actions always over-ride earlier ones. So exceptions
+ to any rules you make, should come in the latter part of the file (or
+ in a file that is processed later when using multiple actions files). For
+ multi-valued actions, the actions are applied in the order they are specified.
+ Actions files are processed in the order they are defined in
+ <filename>config</filename> (the default installation has three actions
+ files). It also quite possible for any given URL pattern to match more than
+ one pattern and thus more than one set of actions!
</para>
+<!-- start actions listing -->
<para>
- Default: Log to the a file named <filename>logfile</filename>.
- Comment out to disable logging.
+ The list of valid <application>Privoxy</application> actions are:
</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>logfile logfile</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-<para>
- The <quote>jarfile</quote> defines where
- <application>Privoxy</application> stores the cookies it intercepts. Note
- that if you use a <quote>jarfile</quote>, it may grow quite large. Default:
- Don't store intercepted cookies.
-</para>
+<!-- ********************************************************** -->
+<!-- Please note the below defined actions use id's that are -->
+<!-- probably linked from other places, so please don't change. -->
+<!-- -->
+<!-- ********************************************************** -->
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>#jarfile jarfile</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-<para>
- If you specify a <quote>trustfile</quote>,
- <application>Privoxy</application> will only allow access to sites that
- are named in the trustfile. You can also mark sites as trusted referrers,
- with the effect that access to untrusted sites will be granted, if a link
- from a trusted referrer was used. The link target will then be added to the
- <quote>trustfile</quote>. This is a very restrictive feature that typical
- users most probably want to leave disabled. Default: Disabled, don't use the
- trust mechanism.
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>#trustfile trust</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- If you use the trust mechanism, it is a good idea to write up some on-line
- documentation about your blocking policy and to specify the URL(s) here. They
- will appear on the page that your users receive when they try to access
- untrusted content. Use multiple times for multiple URLs. Default: Don't
- display links on the <quote>untrusted</quote> info page.
-</para>
+<sect3 renderas="sect4" id="add-header">
+<title><emphasis>add-header</emphasis></title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>trust-info-url http://www.your-site.com/why_we_block.html</emphasis>
- <emphasis>trust-info-url http://www.your-site.com/what_we_allow.html</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Confuse log analysis, custom applications</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Sends a user defined HTTP header to the web server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Multi-value.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ Any string value is possible. Validity of the defined HTTP headers is not checked.
+ It is recommended that you use the <quote><literal>X-</literal></quote> prefix
+ for custom headers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+<varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action may be specified multiple times, in order to define multiple
+ headers. This is rarely needed for the typical user. If you don't know what
+ <quote>HTTP headers</quote> are, you definitely don't need to worry about this
+ one.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+add-header{X-User-Tracking: sucks}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
</sect3>
-<!-- ~ End section ~ -->
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="block">
+<title><emphasis>block</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Block ads or other obnoxious content</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Requests for URLs to which this action applies are blocked, i.e. the requests are not
+ forwarded to the remote server, but answered locally with a substitute page or image,
+ as determined by the <literal><link linkend="handle-as-image">handle-as-image</link></literal>
+ and <literal><link linkend="set-image-blocker">set-image-blocker</link></literal> actions.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>N/A</para>
+ </listitem>
+ </varlistentry>
+
+<varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ <application>Privoxy</application> sends a special <quote>BLOCKED</quote> page
+ for requests to blocked pages. This page contains links to find out why the request
+ was blocked, and a click-through to the blocked content (the latter only if compiled with the
+ force feature enabled). The <quote>BLOCKED</quote> page adapts to the available
+ screen space -- it displays full-blown if space allows, or miniaturized and text-only
+ if loaded into a small frame or window. If you are using <application>Privoxy</application>
+ right now, you can take a look at the
+ <ulink url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
+ page</ulink>.
+ </para>
+ <para>
+ A very important exception occurs if <emphasis>both</emphasis>
+ <literal>block</literal> and <literal><link linkend="handle-as-image">handle-as-image</link></literal>,
+ apply to the same request: it will then be replaced by an image. If
+ <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
+ (see below) also applies, the type of image will be determined by its parameter,
+ if not, the standard checkerboard pattern is sent.
+ </para>
+ <para>
+ It is important to understand this process, in order
+ to understand how <application>Privoxy</application> deals with
+ ads and other unwanted content.
+ </para>
+ <para>
+ The <literal><link linkend="filter">filter</link></literal>
+ action can perform a very similar task, by <quote>blocking</quote>
+ banner images and other content through rewriting the relevant URLs in the
+ document's HTML source, so they don't get requested in the first place.
+ Note that this is a totally different technique, and it's easy to confuse the two.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>{+block} # Block and replace with "blocked" page
+.nasty-stuff.example.com
+
+{+block +handle-as-image} # Block and replace with image
+.ad.doubleclick.net
+.ads.r.us</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-incoming-cookies">
+<title><emphasis>crunch-incoming-cookies</emphasis></title>
-<sect3>
-<title>Other Configuration Options</title>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Prevent the web server from setting any cookies on your system
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- This part of the configuration file contains options that control how
- <application>Privoxy</application> operates.
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes any <quote>Set-Cookie:</quote> HTTP headers from server replies.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <quote>Admin-address</quote> should be set to the email address of the proxy
- administrator. It is used in many of the proxy-generated pages. Default:
- fill@me.in.please.
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>#admin-address fill@me.in.please</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action is only concerned with <emphasis>incoming</emphasis> cookies. For
+ <emphasis>outgoing</emphasis> cookies, use
+ <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>.
+ Use <emphasis>both</emphasis> to disable cookies completely.
+ </para>
+ <para>
+ It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
+ with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
+ since it would prevent the session cookies from being set.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <quote>Proxy-info-url</quote> can be set to a URL that contains more info
- about this <application>Privoxy</application> installation, it's
- configuration and policies. It is used in many of the proxy-generated pages
- and its use is highly recommended in multi-user installations, since your
- users will want to know why certain content is blocked or modified. Default:
- Don't show a link to on-line documentation.
-</para>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+crunch-incoming-cookies</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>proxy-info-url http://www.your-site.com/proxy.html</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-<para>
- <quote>Listen-address</quote> specifies the address and port where
- <application>Privoxy</application> will listen for connections from your
- Web browser. The default is to listen on the localhost port 8118, and
- this is suitable for most users. (In your web browser, under proxy
- configuration, list the proxy server as <quote>localhost</quote> and the
- port as <quote>8118</quote>).
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-outgoing-cookies">
+<title><emphasis>crunch-outgoing-cookies</emphasis></title>
-<para>
- If you already have another service running on port 8118, or if you want to
- serve requests from other machines (e.g. on your local network) as well, you
- will need to override the default. The syntax is
- <quote>listen-address [<ip-address>]:<port></quote>. If you leave
- out the IP address, <application>Privoxy</application> will bind to all
- interfaces (addresses) on your machine and may become reachable from the
- Internet. In that case, consider using access control lists (acl's) (see
- <quote>aclfile</quote> above), or a firewall.
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Prevent the web server from reading any cookies from your system
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- For example, suppose you are running <application>Privoxy</application> on
- a machine which has the address 192.168.0.1 on your local private network
- (192.168.0.0) and has another outside connection with a different address.
- You want it to serve requests from inside only:
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes any <quote>Cookie:</quote> HTTP headers from client requests.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>listen-address 192.168.0.1:8118</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
-<para>
- If you want it to listen on all addresses (including the outside
- connection):
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action is only concerned with <emphasis>outgoing</emphasis> cookies. For
+ <emphasis>incoming</emphasis> cookies, use
+ <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>.
+ Use <emphasis>both</emphasis> to disable cookies completely.
+ </para>
+ <para>
+ It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
+ with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
+ since it would prevent the session cookies from being read.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>listen-address :8118</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+crunch-outgoing-cookies</screen>
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- If you do this, consider using ACLs (see <quote>aclfile</quote> above). Note:
- you will need to point your browser(s) to the address and port that you have
- configured here. Default: localhost:8118 (127.0.0.1:8118).
-</para>
+</variablelist>
+</sect3>
-<para>
- The debug option sets the level of debugging information to log in the
- logfile (and to the console in the Windows version). A debug level of 1 is
- informative because it will show you each request as it happens. Higher
- levels of debug are probably only of interest to developers.
-</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- debug 1 # GPC = show each GET/POST/CONNECT request
- debug 2 # CONN = show each connection status
- debug 4 # IO = show I/O status
- debug 8 # HDR = show header parsing
- debug 16 # LOG = log all data into the logfile
- debug 32 # FRC = debug force feature
- debug 64 # REF = debug regular expression filter
- debug 128 # = debug fast redirects
- debug 256 # = debug GIF de-animation
- debug 512 # CLF = Common Log Format
- debug 1024 # = debug kill pop-ups
- debug 4096 # INFO = Startup banner and warnings.
- debug 8192 # ERROR = Non-fatal errors
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="deanimate-gifs">
+<title><emphasis>deanimate-gifs</emphasis></title>
-<para>
- It is <emphasis>highly recommended</emphasis> that you enable ERROR
- reporting (debug 8192), at least until v3.0 is released.
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Stop those annoying, distracting animated GIF images.</para>
+ </listitem>
+ </varlistentry>
-<para>
- The reporting of FATAL errors (i.e. ones which crash
- <application>Privoxy</application>) is always on and cannot be disabled.
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ De-animate GIF animations, i.e. reduce them to their first or last image.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- If you want to use CLF (Common Log Format), you should set <quote>debug
- 512</quote> ONLY, do not enable anything else.
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
-<para>
- Multiple <quote>debug</quote> directives, are OK - they're logical-OR'd
- together.
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ <quote>last</quote> or <quote>first</quote>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This will also shrink the images considerably (in bytes, not pixels!). If
+ the option <quote>first</quote> is given, the first frame of the animation
+ is used as the replacement. If <quote>last</quote> is given, the last
+ frame of the animation is used instead, which probably makes more sense for
+ most banner animations, but also has the risk of not showing the entire
+ last frame (if it is only a delta to an earlier frame).
+ </para>
+ <para>
+ You can safely use this action with patterns that will also match non-GIF
+ objects, because no attempt will be made at anything that doesn't look like
+ a GIF.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>debug 15 # same as setting the first 4 listed above</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+deanimate-gifs{last}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<para>
- Default:
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="downgrade-http-version">
+<title><emphasis>downgrade-http-version</emphasis></title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>debug 1 # URLs</emphasis>
- <emphasis>debug 4096 # Info</emphasis>
- <emphasis>debug 8192 # Errors - *we highly recommended enabling this*</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Work around (very rare) problems with HTTP/1.1</para>
+ </listitem>
+ </varlistentry>
-<para>
- <application>Privoxy</application> normally uses
- <quote>multi-threading</quote>, a software technique that permits it to
- handle many different requests simultaneously. In some cases you may wish to
- disable this -- particularly if you're trying to debug a problem. The
- <quote>single-threaded</quote> option forces
- <application>Privoxy</application> to handle requests sequentially.
- Default: Multi-threaded mode.
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>#single-threaded</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
-<para>
- <quote>toggle</quote> allows you to temporarily disable all
- <application>Privoxy's</application> filtering. Just set <quote>toggle
- 0</quote>.
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+<varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This is a left-over from the time when <application>Privoxy</application>
+ didn't support important HTTP/1.1 features well. It is left here for the
+ unlikely case that you experience HTTP/1.1 related problems with some server
+ out there. Not all (optional) HTTP/1.1 features are supported yet, so there
+ is a chance you might need this action.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- The Windows version of <application>Privoxy</application> puts an icon in
- the system tray, which also allows you to change this option. If you
- right-click on that icon (or select the <quote>Options</quote> menu), one
- choice is <quote>Enable</quote>. Clicking on enable toggles
- <application>Privoxy</application> on and off. This is useful if you want
- to temporarily disable <application>Privoxy</application>, e.g., to access
- a site that requires cookies which you would otherwise have blocked. This can also
- be toggled via a web browser at the <application>Privoxy</application>
- internal address of <ulink url="http://p.p">http://p.p</ulink> on
- any platform.
-</para>
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>{+downgrade-http-version}
+problem-host.example.com</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
-<para>
- <quote>toggle 1</quote> means <application>Privoxy</application> runs
- normally, <quote>toggle 0</quote> means that
- <application>Privoxy</application> becomes a non-anonymizing non-blocking
- proxy. Default: 1 (on).
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="fast-redirects">
+<title><emphasis>fast-redirects</emphasis></title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>toggle 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Fool some click-tracking scripts and speed up indirect links</para>
+ </listitem>
+ </varlistentry>
-<para>
- For content filtering, i.e. the <quote>+filter</quote> and
- <quote>+deanimate-gif</quote> actions, it is necessary that
- <application>Privoxy</application> buffers the entire document body.
- This can be potentially dangerous, since a server could just keep sending
- data indefinitely and wait for your RAM to exhaust. With nasty consequences.
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Cut off all but the last valid URL from requests.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- The <application>buffer-limit</application> option lets you set the maximum
- size in Kbytes that each buffer may use. When the documents buffer exceeds
- this size, it is flushed to the client unfiltered and no further attempt to
- filter the rest of it is made. Remember that there may multiple threads
- running, which might require increasing the <quote>buffer-limit</quote>
- Kbytes <emphasis>each</emphasis>, unless you have enabled
- <quote>single-threaded</quote> above.
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>buffer-limit 4069</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- To enable the web-based <filename>default.action</filename> file editor set
- <application>enable-edit-actions</application> to 1, or 0 to disable. Note
- that you must have compiled <application>Privoxy</application> with
- support for this feature, otherwise this option has no effect. This
- internal page can be reached at <ulink
- url="http://p.p">http://p.p</ulink>.
- </para>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Many sites, like yahoo.com, don't just link to other sites. Instead, they
+ will link to some script on their own servers, giving the destination as a
+ parameter, which will then redirect you to the final target. URLs
+ resulting from this scheme typically look like:
+ <emphasis>http://some.place/click-tracker.cgi?target=http://some.where.else</emphasis>.
+ </para>
+ <para>
+ Sometimes, there are even multiple consecutive redirects encoded in the
+ URL. These redirections via scripts make your web browsing more traceable,
+ since the server from which you follow such a link can see where you go
+ to. Apart from that, valuable bandwidth and time is wasted, while your
+ browser ask the server for one redirect after the other. Plus, it feeds
+ the advertisers.
+ </para>
+ <para>
+ This feature is currently not very smart and is scheduled for improvement.
+ It is likely to break some sites. You should expect to need possibly
+ many exceptions to this action, if it is enabled by default in
+ <filename>default.action</filename>. Some sites just don't work without
+ it.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Security note: If this is enabled, anyone who can use the proxy
- can edit the actions file, and their changes will affect all users.
- For shared proxies, you probably want to disable this. Default: enabled.
-</para>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>{+fast-redirects}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>enable-edit-actions 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</variablelist>
+</sect3>
-<para>
- Allow <application>Privoxy</application> to be toggled on and off
- remotely, using your web browser. Set <quote>enable-remote-toggle</quote>to
- 1 to enable, and 0 to disable. Note that you must have compiled
- <application>Privoxy</application> with support for this feature,
- otherwise this option has no effect.
-</para>
-<para>
- Security note: If this is enabled, anyone who can use the proxy can toggle
- it on or off (see <ulink url="http://p.p">http://p.p</ulink>), and
- their changes will affect all users. For shared proxies, you probably want to
- disable this. Default: enabled.
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="filter">
+<title><emphasis>filter</emphasis></title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>enable-remote-toggle 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Get rid of HTML and JavaScript annoyances, banner advertisements (by size), do fun text replacements, etc.</para>
+ </listitem>
+ </varlistentry>
-</sect3>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Text documents, including HTML and JavaScript, to which this action applies, are filtered on-the-fly
+ through the specified regular expression based substitutions.
+ </para>
+ </listitem>
+ </varlistentry>
-<!-- ~ End section ~ -->
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ The name of a filter, as defined in the <link linkend="filter-file">filter file</link>
+ (typically <filename>default.filter</filename>, set by the
+ <literal><link linkend="filterfile">filterfile</link></literal>
+ option in the <link linkend="config">config file</link>)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ For your convenience, there are a bunch of pre-defined filters available
+ in the distribution filter file that you can use. See the example below for
+ a list.
+ </para>
+ <para>
+ This is potentially a very powerful feature! But <quote>rolling your own</quote>
+ filters requires a knowledge of regular expressions and HTML.
+ </para>
+ <para>
+ Filtering requires buffering the page content, which may appear to
+ slow down page rendering since nothing is displayed until all content has
+ passed the filters. (It does not really take longer, but seems that way
+ since the page is not incrementally displayed.) This effect will be more
+ noticeable on slower connections.
+ </para>
+ <para>
+ At this time, <application>Privoxy</application> cannot (yet!) uncompress compressed
+ documents. If you want filtering to work on all documents, even those that
+ would normally be sent compressed, use the
+ <literal><link linkend="prevent-compression">prevent-compression</link></literal>
+ action in conjunction with <literal>filter</literal>.
+ </para>
+ <para>
+ Filtering can achieve some of the effects as the
+ <literal><link linkend="block">block</link></literal>
+ action, i.e. it can be used to block ads and banners.
+ </para>
+ <para>
+ <link linkend="contact">Feedback</link> with suggestions for new or improved filters is particularly
+ welcome!
+ </para>
+ </listitem>
+ </varlistentry>
-<!-- ~~~~~ New section ~~~~~ -->
+ <varlistentry>
+ <term>Example usage (with filters from the distribution <filename>default.filter</filename> file):</term>
+ <listitem>
+ <para>
+ <anchor id="filter-html-annoyances">
+ <screen>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse.</screen>
+ </para>
+ <para>
+ <anchor id="filter-js-annoyances">
+ <screen>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse</screen>
+ </para>
+ <para>
+ <anchor id="filter-banners-by-size">
+ <screen>+filter{banners-by-size} # Kill banners by size (<emphasis>very</emphasis> efficient!)</screen>
+ </para>
+ <para>
+ <anchor id="filter-content-cookies">
+ <screen>+filter{content-cookies} # Kill cookies that come sneaking in the HTML or JS content</screen>
+ </para>
+ <para>
+ <anchor id="filter-popups">
+ <screen>+filter{popups} # Kill all popups in JS and HTML</screen>
+ </para>
+ <para>
+ <anchor id="filter-webbugs">
+ <screen>+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking)</screen>
+ </para>
+ <para>
+ <anchor id="filter-fun">
+ <screen>+filter{fun} # Text replacements for subversive browsing fun!</screen>
+ </para>
+ <para>
+ <anchor id="filter-frameset-borders">
+ <screen>+filter{frameset-borders} # Give frames a border and make them resizeable</screen>
+ </para>
+ <para>
+ <anchor id="filter-refresh-tags">
+ <screen>+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups)</screen>
+ </para>
+ <para>
+ <anchor id="filter-nimda">
+ <screen>+filter{nimda} # Remove Nimda (virus) code.</screen>
+ </para>
+ <para>
+ <anchor id="filter-shockwave-flash">
+ <screen>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects</screen>
+ </para>
+ <para>
+ <anchor id="filter-crude-parental">
+ <screen>+filter{crude-parental} # Kill all web pages that contain the words "sex" or "warez"</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<sect3>
-<title>Access Control List (ACL)</title>
-<para>
- Access controls are included at the request of some ISPs and systems
- administrators, and are not usually needed by individual users. Please note
- the warnings in the FAQ that this proxy is not intended to be a substitute
- for a firewall or to encourage anyone to defer addressing basic security
- weaknesses.
-</para>
-<para>
- If no access settings are specified, the proxy talks to anyone that
- connects. If any access settings file are specified, then the proxy
- talks only to IP addresses permitted somewhere in this file and not
- denied later in this file.
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="handle-as-image">
+<title><emphasis>handle-as-image</emphasis></title>
-<para>
- Summary -- if using an ACL:
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Mark URLs as belonging to images (so they'll be replaced by images <emphasis>if they get blocked</emphasis>)</para>
+ </listitem>
+ </varlistentry>
- <simplelist>
- <member>
- Client must have permission to receive service.
- </member>
- </simplelist>
- <simplelist>
- <member>
- LAST match in ACL wins.
- </member>
- </simplelist>
- <simplelist>
- <member>
- Default behavior is to deny service.
- </member>
- </simplelist>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ This action alone doesn't do anything noticeable. It just marks URLs as images.
+ If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
+ the presence or absence of this mark decides whether an HTML <quote>blocked</quote>
+ page, or a replacement image (as determined by the <literal><link
+ linkend="set-image-blocker">set-image-blocker</link></literal> action) will be sent to the
+ client as a substitute for the blocked content.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- The syntax for an entry in the Access Control List is:
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- ACTION SRC_ADDR[/SRC_MASKLEN] [ DST_ADDR[/DST_MASKLEN] ]
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The below generic example section is actually part of <filename>default.action</filename>.
+ It marks all URLs with well-known image file name extensions as images and should
+ be left intact.
+ </para>
+ <para>
+ Users will probably only want to use the handle-as-image action in conjunction with
+ <literal><link linkend="block">block</link></literal>, to block sources of banners, whose URLs don't
+ reflect the file type, like in the second example section.
+ </para>
+ <para>
+ Note that you cannot treat HTML pages as images in most cases. For instance, (inline) ad
+ frames require an HTML page to be sent, or they won't display properly.
+ Forcing <literal>handle-as-image</literal> in this situation will not replace the
+ ad frame with an image, but lead to error messages.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Where the individual fields are:
-</para>
+ <varlistentry>
+ <term>Example usage (sections):</term>
+ <listitem>
+ <para>
+ <screen># Generic image extensions:
+#
+{+handle-as-image}
+/.*\.(gif|jpg|jpeg|png|bmp|ico)$
+
+# These don't look like images, but they're banners and should be
+# blocked as images:
+#
+{+block +handle-as-image}
+some.nasty-banner-server.com/junk.cgi?output=trash
+
+# Banner source! Who cares if they also have non-image content?
+ad.doubleclick.net
+</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>ACTION</emphasis> = <quote>permit-access</quote> or <quote>deny-access</quote>
- <emphasis>SRC_ADDR</emphasis> = client hostname or dotted IP address
- <emphasis>SRC_MASKLEN</emphasis> = number of bits in the subnet mask for the source
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="hide-forwarded-for-headers">
+<title><emphasis>hide-forwarded-for-headers</emphasis></title>
- <emphasis>DST_ADDR</emphasis> = server or forwarder hostname or dotted IP address
- <emphasis>DST_MASKLEN</emphasis> = number of bits in the subnet mask for the target
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Improve privacy by hiding the true source of the request</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes any existing <quote>X-Forwarded-for:</quote> HTTP header from client requests,
+ and prevents adding a new one.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- The field separator (FS) is whitespace (space or tab).
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
-<para>
- IMPORTANT NOTE: If <application>Privoxy</application> is using a
- forwarder (see below) or a gateway for a particular destination URL, the
- <literal>DST_ADDR</literal> that is examined is the address of the forwarder
- or the gateway and <emphasis>NOT</emphasis> the address of the ultimate
- target. This is necessary because it may be impossible for the local
- <application>Privoxy</application> to determine the address of the
- ultimate target (that's often what gateways are used for).
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ It is fairly safe to leave this on.
+ </para>
+ <para>
+ This action is scheduled for improvement: It should be able to generate forged
+ <quote>X-Forwarded-for:</quote> headers using random IP addresses from a specified network,
+ to make successive requests from the same client look like requests from a pool of different
+ users sharing the same proxy.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Here are a few examples to show how the ACL features work:
-</para>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+hide-forwarded-for-headers</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<para>
- <quote>localhost</quote> is OK -- no DST_ADDR implies that
- <emphasis>ALL</emphasis> destination addresses are OK:
-</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>permit-access localhost</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="hide-from-header">
+<title><emphasis>hide-from-header</emphasis></title>
-<para>
- A silly example to illustrate permitting any host on the class-C subnet with
- <application>Privoxy</application> to go anywhere:
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Keep your (old and ill) browser from telling web servers your email address</para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>permit-access www.privoxy.com/24</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes any existing <quote>From:</quote> HTTP header, or replaces it with the
+ specified string.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Except deny one particular IP address from using it at all:
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>deny-access ident.privoxy.com</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ Keyword: <quote>block</quote>, or any user defined value.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The keyword <quote>block</quote> will completely remove the header
+ (not to be confused with the <literal><link linkend="block">block</link></literal>
+ action).
+ </para>
+ <para>
+ Alternately, you can specify any value you prefer to be sent to the web
+ server. If you do, it is a matter of fairness not to use any address that
+ is actually used by a real person.
+ </para>
+ <para>
+ This action is rarely needed, as modern web browsers don't send
+ <quote>From:</quote> headers anymore.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- You can also specify an explicit network address and subnet mask.
- Explicit addresses do not have to be resolved to be used.
-</para>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+hide-from-header{block}</screen> or
+ <screen>+hide-from-header{spam-me-senseless@sittingduck.example.com}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>permit-access 207.153.200.0/24</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-<para>
- A subnet mask of 0 matches anything, so the next line permits everyone.
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="hide-referrer">
+<title><emphasis>hide-referrer</emphasis></title>
+<anchor id="hide-referer">
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Conceal which link you followed to get to a particular site</para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>permit-access 0.0.0.0/0</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes the <quote>Referer:</quote> (sic) HTTP header from the client request,
+ or replaces it with a forged one.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Note, you <emphasis>cannot</emphasis> say:
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>permit-access .org</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para><quote>block</quote> to delete the header completely.</para>
+ </listitem>
+ <listitem>
+ <para><quote>forge</quote> to pretend to be coming from the homepage of the server we are talking to.</para>
+ </listitem>
+ <listitem>
+ <para>Any other string to set a user defined referrer.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ <quote>forge</quote> is the preferred option here, since some servers will
+ not send images back otherwise, in an attempt to prevent their valuable
+ content from being embedded elsewhere (and hence, without being surrounded
+ by <emphasis>their</emphasis> banners).
+ </para>
+ <para>
+ <literal>hide-referer</literal> is an alternate spelling of
+ <literal>hide-referrer</literal> and the two can be can be freely
+ substituted with each other. (<quote>referrer</quote> is the
+ correct English spelling, however the HTTP specification has a bug - it
+ requires it to be spelled as <quote>referer</quote>.)
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- to allow all *.org domains. Every IP address listed must resolve fully.
-</para>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+hide-referrer{forge}</screen> or
+ <screen>+hide-referrer{http://www.yahoo.com/}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<para>
- An ISP may want to provide a <application>Privoxy</application> that is
- accessible by <quote>the world</quote> and yet restrict use of some of their
- private content to hosts on its internal network (i.e. its own subscribers).
- Say, for instance the ISP owns the Class-B IP address block 123.124.0.0 (a 16
- bit netmask). This is how they could do it:
-</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>permit-access 0.0.0.0/0 0.0.0.0/0</emphasis> # other clients can go anywhere
- # with the following exceptions:
-
- <emphasis>deny-access</emphasis> 0.0.0.0/0 123.124.0.0/16 # block all external requests for
- # sites on the ISP's network
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="hide-user-agent">
+<title><emphasis>hide-user-agent</emphasis></title>
- <emphasis>permit 0.0.0.0/0 www.my_isp.com</emphasis> # except for the ISP's main
- # web site
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Conceal your type of browser and client operating system</para>
+ </listitem>
+ </varlistentry>
- <emphasis>permit 123.124.0.0/16 0.0.0.0/0</emphasis> # the ISP's clients can go
- # anywhere
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Replaces the value of the <quote>User-Agent:</quote> HTTP header
+ in client requests with the specified value.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Note that if some hostnames are listed with multiple IP addresses,
- the primary value returned by DNS (via gethostbyname()) is used. Default:
- Anyone can access the proxy.
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
-</sect3>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ Any user-defined string.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <warning>
+ <para>
+ This breaks many web sites that depend on looking at this header in order
+ to customize their content for different browsers (which, by the
+ way, is <emphasis>NOT</emphasis> a <ulink
+ url="http://www.javascriptkit.com/javaindex.shtml">smart way to do
+ that</ulink>!).
+ </para>
+ </warning>
+ <para>
+ Using this action in multi-user setups or wherever different types of
+ browsers will access the same <application>Privoxy</application> is
+ <emphasis>not recommended</emphasis>. In single-user, single-browser
+ setups, you might use it to delete your OS version information from
+ the headers, because it is an invitation to exploit known bugs for your
+ OS. It is also occasionally useful to forge this in order to access
+ sites that won't let you in otherwise (though there may be a good
+ reason in some cases). Example of this: some MSN sites will not
+ let <application>Mozilla</application> enter, yet forging to a
+ <application>Netscape 6.1</application> user-agent works just fine.
+ (Must be just a silly MS goof, I'm sure :-).
+ </para>
+ <para>
+ This action is scheduled for improvement.
+ </para>
+ </listitem>
+ </varlistentry>
-<!-- ~ End section ~ -->
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="kill-popups">
+<title><emphasis>kill-popups<anchor id="kill-popup"></emphasis></title>
-<sect3 id="forwarding">
-<title>Forwarding</title>
-
-<para>
- This feature allows chaining of HTTP requests via multiple proxies.
- It can be used to better protect privacy and confidentiality when
- accessing specific domains by routing requests to those domains
- to a special purpose filtering proxy such as lpwa.com. Or to use
- a caching proxy to speed up browsing.
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Eliminate those annoying pop-up windows</para>
+ </listitem>
+ </varlistentry>
-<para>
- It can also be used in an environment with multiple networks to route
- requests via multiple gateways allowing transparent access to multiple
- networks without having to modify browser configurations.
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ While loading the document, replace JavaScript code that opens
+ pop-up windows with (syntactically neutral) dummy code on the fly.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Also specified here are SOCKS proxies. <application>Privoxy</application>
- SOCKS 4 and SOCKS 4A. The difference is that SOCKS 4A will resolve the target
- hostname using DNS on the SOCKS server, not our local DNS client.
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
-<para>
- The syntax of each line is:
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action is easily confused with the built-in, hardwired <literal><link linkend="filter">filter</link></literal>
+ action, but there are important differences: For <literal>kill-popups</literal>,
+ the document need not be buffered, so it can be incrementally rendered while
+ downloading. But <literal>kill-popups</literal> doesn't catch as many pop-ups as
+ <literal><link
+ linkend="filter">filter</link>{<replaceable>popups</replaceable>}</literal>
+ does.
+ </para>
+ <para>
+ Think of it as a fast and efficient replacement for a filter that you
+ can use if you don't want any filtering at all. Note that it doesn't make
+ sense to combine it with any <literal><link linkend="filter">filter</link></literal> action,
+ since as soon as one <literal><link linkend="filter">filter</link></literal> applies,
+ the whole document needs to be buffered anyway, which destroys the advantage of
+ the <literal>kill-popups</literal> action over its filter equivalent.
+ </para>
+ <para>
+ Killing all pop-ups is a dangerous business. Many shops and banks rely on
+ pop-ups to display forms, shopping carts etc, and killing only the unwanted pop-ups
+ would require artificial intelligence in <application>Privoxy</application>.
+ If the only kind of pop-ups that you want to kill are exit consoles (those
+ <emphasis>really nasty</emphasis> windows that appear when you close an other
+ one), you might want to use
+ <literal><link
+ linkend="filter">filter</link>{<replaceable>js-annoyances</replaceable>}</literal>
+ instead.
+ </para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward target_domain[:port] http_proxy_host[:port]</emphasis>
- <emphasis>forward-socks4 target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]</emphasis>
- <emphasis>forward-socks4a target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <!--
+ <para>
+ An alternate spelling is <literal>+kill-popup</literal>, which is
+ interchangeable.
+ </para>
+ -->
+ </listitem>
+ </varlistentry>
-<para>
- If http_proxy_host is <quote>.</quote>, then requests are not forwarded to a
- HTTP proxy but are made directly to the web servers.
-</para>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para><screen>+kill-popups</screen></para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<para>
- Lines are checked in sequence, and the last match wins.
-</para>
-<para>
- There is an implicit line equivalent to the following, which specifies that
- anything not finding a match on the list is to go out without forwarding
- or gateway protocol, like so:
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="limit-connect">
+<title><emphasis>limit-connect</emphasis></title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward .* . </emphasis># implicit
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Prevent abuse of <application>Privoxy</application> as a TCP proxy relay</para>
+ </listitem>
+ </varlistentry>
-<para>
- In the following common configuration, everything goes to Lucent's LPWA,
- except SSL on port 443 (which it doesn't handle):
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Specifies to which ports HTTP CONNECT requests are allowable.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward .* lpwa.com:8000</emphasis>
- <emphasis>forward :443 .</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
-<para>
-<!--
- See the FAQ for instructions on how to automate the login procedure for LPWA.
--->
- Some users have reported difficulties related to LPWA's use of
- <quote>.</quote> as the last element of the domain, and have said that this
- can be fixed with this:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward lpwa. lpwa.com:8000</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ A comma-separated list of ports or port ranges (the latter using dashes, with the minimum
+ defaulting to 0 and the maximum to 65K).
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- (NOTE: the syntax for specifying target_domain has changed since the
- previous paragraph was written -- it will not work now. More information
- is welcome.)
-</para>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ By default, i.e. if no <literal>limit-connect</literal> action applies,
+ <application>Privoxy</application> only allows HTTP CONNECT
+ requests to port 443 (the standard, secure HTTPS port). Use
+ <literal>limit-connect</literal> if more fine-grained control is desired
+ for some or all destinations.
+ </para>
+ <para>
+ The CONNECT methods exists in HTTP to allow access to secure websites
+ (<quote>https://</quote> URLs) through proxies. It works very simply:
+ the proxy connects to the server on the specified port, and then
+ short-circuits its connections to the client and to the remote server.
+ This can be a big security hole, since CONNECT-enabled proxies can be
+ abused as TCP relays very easily.
+ </para>
+ <para>
+ If you don't know what any of this means, there probably is no reason to
+ change this one, since the default is already very restrictive.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- In this fictitious example, everything goes via an ISP's caching proxy,
- except requests to that ISP:
-</para>
+ <varlistentry>
+ <term>Example usages:</term>
+ <listitem>
+ <!-- I had trouble getting the spacing to look right in my browser -->
+ <!-- I probably have the wrong font setup, bollocks. -->
+ <!-- Apparently the emphasis tag uses a proportional font no matter what -->
+ <para>
+ <screen>+limit-connect{443} # This is the default and need not be specified.
++limit-connect{80,443} # Ports 80 and 443 are OK.
++limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK.
++limit-connect{-} # All ports are OK (gaping security hole!)</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward .* caching.myisp.net:8000</emphasis>
- <emphasis>forward myisp.net .</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="prevent-compression">
+<title><emphasis>prevent-compression</emphasis></title>
-<para>
- For the @home network, we're told the forwarding configuration is this:
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Ensure that servers send the content uncompressed, so it can be
+ passed through <literal><link linkend="filter">filter</link></literal>s
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Adds a header to the request that asks for uncompressed transfer.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward .* proxy:8080</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
-<para>
- Also, we're told they insist on getting cookies and JavaScript, so you should
- allow cookies from home.com. We consider JavaScript a potential security risk.
- Java need not be enabled.
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ More and more websites send their content compressed by default, which
+ is generally a good idea and saves bandwidth. But for the <literal><link
+ linkend="filter">filter</link></literal>, <literal><link linkend="deanimate-gifs">deanimate-gifs</link></literal>
+ and <literal><link linkend="kill-popups">kill-popups</link></literal> actions to work,
+ <application>Privoxy</application> needs access to the uncompressed data.
+ Unfortunately, <application>Privoxy</application> can't yet(!) uncompress, filter, and
+ re-compress the content on the fly. So if you want to ensure that all websites, including
+ those that normally compress, can be filtered, you need to use this action.
+ </para>
+ <para>
+ This will slow down transfers from those websites, though. If you use any of the above-mentioned
+ actions, you will typically want to use <literal>prevent-compression</literal> in conjunction
+ with them.
+ </para>
+ <para>
+ Note that some (rare) ill-configured sites don't handle requests for uncompressed
+ documents correctly (they send an empty document body). If you use <literal>prevent-compression</literal>
+ per default, you'll have to add exceptions for those sites. See the example for how to do that.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- In this example direct connections are made to all <quote>internal</quote>
- domains, but everything else goes through Lucent's LPWA by way of the
- company's SOCKS gateway to the Internet.
-</para>
+ <varlistentry>
+ <term>Example usage (sections):</term>
+ <listitem>
+ <para>
+ <screen># Set default:
+#
+{+prevent-compression}
+/ # Match all sites
+
+# Make exceptions for ill sites:
+#
+{-prevent-compression}
+www.debianhelp.org
+www.pclinuxonline.com</screen>
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward-socks4 .* lpwa.com:8000 firewall.my_company.com:1080</emphasis>
- <emphasis>forward my_company.com .</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</variablelist>
+</sect3>
-<para>
- This is how you could set up a site that always uses SOCKS but no forwarders:
-</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward-socks4a .* . firewall.my_company.com:1080</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="send-vanilla-wafer">
+<title><emphasis>send-vanilla-wafer</emphasis></title>
-<para>
- An advanced example for network administrators:
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Feed log analysis scripts with useless data.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- If you have links to multiple ISPs that provide various special content to
- their subscribers, you can configure forwarding to pass requests to the
- specific host that's connected to that ISP so that everybody can see all
- of the content on all of the ISPs.
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Sends a cookie with each request stating that you do not accept any copyright
+ on cookies sent to you, and asking the site operator not to track you.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- This is a bit tricky, but here's an example:
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The vanilla wafer is a (relatively) unique header and could conceivably be used to track you.
+ </para>
+ <para>
+ This action is rarely used and not enabled in the default configuration.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- host-a has a PPP connection to isp-a.com. And host-b has a PPP connection to
- isp-b.com. host-a can run a <application>Privoxy</application> proxy with
- forwarding like this:
-</para>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+send-vanilla-wafer</screen>
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward .* .</emphasis>
- <emphasis>forward isp-b.com host-b:8118</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</variablelist>
+</sect3>
-<para>
- host-b can run a <application>Privoxy</application> proxy with forwarding
- like this:
-</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward .* .</emphasis>
- <emphasis>forward isp-a.com host-a:8118</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="send-wafer">
+<title><emphasis>send-wafer</emphasis></title>
-<para>
- Now, <emphasis>anyone</emphasis> on the Internet (including users on host-a
- and host-b) can set their browser's proxy to <emphasis>either</emphasis>
- host-a or host-b and be able to browse the content on isp-a or isp-b.
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Send custom cookies or feed log analysis scripts with even more useless data.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Here's another practical example, for University of Kent at
- Canterbury students with a network connection in their room, who
- need to use the University's Squid web cache.
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Sends a custom, user-defined cookie with each request.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward *. ssbcache.ukc.ac.uk:3128</emphasis> # Use the proxy, except for:
- <emphasis>forward .ukc.ac.uk . </emphasis> # Anything on the same domain as us
- <emphasis>forward * . </emphasis> # Host with no domain specified
- <emphasis>forward 129.12.*.* . </emphasis> # A dotted IP on our /16 network.
- <emphasis>forward 127.*.*.* . </emphasis> # Loopback address
- <emphasis>forward localhost.localdomain . </emphasis> # Loopback address
- <emphasis>forward www.ukc.mirror.ac.uk . </emphasis> # Specific host
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Multi-value.</para>
+ </listitem>
+ </varlistentry>
-<para>
- If you intend to chain <application>Privoxy</application> and
- <application>squid</application> locally, then chain as
- <literal>browser -> squid -> privoxy</literal> is the recommended way.
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ A string of the form <quote><replaceable class="option">name</replaceable>=<replaceable
+ class="parameter">value</replaceable></quote>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Being multi-valued, multiple instances of this action can apply to the same request,
+ resulting in multiple cookies being sent.
+ </para>
+ <para>
+ This action is rarely used and not enabled in the default configuration.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>{+send-wafer{UsingPrivoxy=true}}
+my-internal-testing-server.void</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<para>
- Your squid configuration could then look like this:
-</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- # Define Privoxy as parent cache
- <!-- per feedback from user...
- cache_peer 127.0.0.1 8118 parent 0 no-query
- -->
- cache_peer 127.0.0.1 parent 8118 0 no-query
-
- # Define ACL for protocol FTP
- acl FTP proto FTP
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="session-cookies-only">
+<title><emphasis>session-cookies-only</emphasis></title>
- # Do not forward ACL FTP to privoxy
- always_direct allow FTP
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Allow only temporary <quote>session</quote> cookies (for the current browser session <emphasis>only</emphasis>).
+ </para>
+ </listitem>
+ </varlistentry>
- # Do not forward ACL CONNECT (https) to privoxy
- always_direct allow CONNECT
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes the <quote>expires</quote> field from <quote>Set-Cookie:</quote> server headers.
+ Most browsers will not store such cookies permanently and forget them in between sessions.
+ </para>
+ </listitem>
+ </varlistentry>
- # Forward the rest to privoxy
- never_direct allow all
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
-</sect3>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This is less strict than <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> /
+ <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal> and allows you to browse
+ websites that insist or rely on setting cookies, without compromising your privacy too badly.
+ </para>
+ <para>
+ Most browsers will not permanently store cookies that have been processed by
+ <literal>session-cookies-only</literal> and will forget about them between sessions.
+ This makes profiling cookies useless, but won't break sites which require cookies so
+ that you can log in for transactions. This is generally turned on for all
+ sites, and is the recommended setting.
+ </para>
+ <para>
+ It makes <emphasis>no sense at all</emphasis> to use <literal>session-cookies-only</literal>
+ together with <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> or
+ <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>. If you do, cookies
+ will be plainly killed.
+ </para>
+ <para>
+ Note that it is up to the browser how it handles such cookies without an <quote>expires</quote>
+ field. If you use an exotic browser, you might want to try it out to be sure.
+ </para>
+ </listitem>
+ </varlistentry>
-<!-- ~ End section ~ -->
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+session-cookies-only</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="set-image-blocker">
+<title><emphasis>set-image-blocker</emphasis></title>
-<sect3>
-<title>Windows GUI Options</title>
-<!--
-Removed references to Win32. HB 09/23/01
--->
-<para>
- <application>Privoxy</application> has a number of options specific to the
- Windows GUI interface:
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Choose the replacement for blocked images</para>
+ </listitem>
+ </varlistentry>
-<para>
- If <quote>activity-animation</quote> is set to 1, the
- <application>Privoxy</application> icon will animate when
- <quote>Privoxy</quote> is active. To turn off, set to 0.
-</para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ This action alone doesn't do anything noticeable. If <emphasis>both</emphasis>
+ <literal><link linkend="block">block</link></literal> <emphasis>and</emphasis> <literal><link
+ linkend="handle-as-image">handle-as-image</link></literal> <emphasis>also</emphasis>
+ apply, i.e. if the request is to be blocked as an image,
+ <emphasis>then</emphasis> the parameter of this action decides what will be
+ sent as a replacement.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>activity-animation 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
-<para>
- If <quote>log-messages</quote> is set to 1,
- <application>Privoxy</application> will log messages to the console
- window:
-</para>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <quote>pattern</quote> to send a built-in checkerboard pattern image. The image is visually
+ decent, scales very well, and makes it obvious where banners were busted.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <quote>blank</quote> to send a built-in transparent image. This makes banners disappear
+ completely, but makes it hard to detect where <application>Privoxy</application> has blocked
+ images on a given page and complicates troubleshooting if <application>Privoxy</application>
+ has blocked innocent images, like navigation icons.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <quote><replaceable class="parameter">target-url</replaceable></quote> to
+ send a redirect to <replaceable class="parameter">target-url</replaceable>. You can redirect
+ to any image anywhere, even in your local filesystem (via <quote>file:///</quote> URL).
+ </para>
+ <para>
+ A good application of redirects is to use special <application>Privoxy</application>-built-in
+ URLs, which send the built-in images, as <replaceable class="parameter">target-url</replaceable>.
+ This has the same visual effect as specifying <quote>blank</quote> or <quote>pattern</quote> in
+ the first place, but enables your browser to cache the replacement image, instead of requesting
+ it over and over again.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The URLs for the built-in images are <quote>http://config.privoxy.org/send-banner?type=<replaceable
+ class="parameter">type</replaceable></quote>, where <replaceable class="parameter">type</replaceable> is
+ either <quote>blank</quote> or <quote>pattern</quote>.
+ </para>
+ <para>
+ There is a third (advanced) type, called <quote>auto</quote>. It is <emphasis>NOT</emphasis> to be
+ used in <literal>set-image-blocker</literal>, but meant for use from <link linkend="filter-file">filters</link>.
+ Auto will select the type of image that would have applied to the referring page, had it been an image.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>log-messages 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ Built-in pattern:
+ </para>
+ <para>
+ <screen>+set-image-blocker{pattern}</screen>
+ </para>
+ <para>
+ Redirect to the BSD devil:
+ </para>
+ <para>
+ <screen>+set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}</screen>
+ </para>
+ <para>
+ Redirect to the built-in pattern for better caching:
+ </para>
+ <para>
+ <screen>+set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<para>
- If <quote>log-buffer-size</quote> is set to 1, the size of the log buffer,
- i.e. the amount of memory used for the log messages displayed in the
- console window, will be limited to <quote>log-max-lines</quote> (see below).
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3>
+<title>Summary</title>
<para>
- Warning: Setting this to 0 will result in the buffer to grow infinitely and
- eat up all your memory!
+ Note that many of these actions have the potential to cause a page to
+ misbehave, possibly even not to display at all. There are many ways
+ a site designer may choose to design his site, and what HTTP header
+ content, and other criteria, he may depend on. There is no way to have hard
+ and fast rules for all sites. See the <link
+ linkend="ACTIONSANAT">Appendix</link> for a brief example on troubleshooting
+ actions.
</para>
+</sect3>
+</sect2>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="aliases">
+<title>Aliases</title>
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>log-buffer-size 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
+ Custom <quote>actions</quote>, known to <application>Privoxy</application>
+ as <quote>aliases</quote>, can be defined by combining other actions.
+ These can in turn be invoked just like the built-in actions.
+ Currently, an alias name can contain any character except space, tab,
+ <quote>=</quote>,
+ <quote>{</quote> and <quote>}</quote>, but we <emphasis>strongly
+ recommend</emphasis> that you only use <quote>a</quote> to <quote>z</quote>,
+ <quote>0</quote> to <quote>9</quote>, <quote>+</quote>, and <quote>-</quote>.
+ Alias names are not case sensitive, and are not required to start with a
+ <quote>+</quote> or <quote>-</quote> sign, since they are merely textually
+ expanded.
</para>
-
<para>
- <application>log-max-lines</application> is the maximum number of lines held
- in the log buffer. See above.
+ Aliases can be used throughout the actions file, but they <emphasis>must be
+ defined in a special section at the top of the file!</emphasis>
+ And there can only be one such section per actions file. Each actions file may
+ have its own alias section, and the aliases defined in it are only visible
+ within that file.
</para>
-
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>log-max-lines 200</emphasis>
- </literallayout>
- </msgtext>
- </literal>
+ There are two main reasons to use aliases: One is to save typing for frequently
+ used combinations of actions, the other one is a gain in flexibility: If you
+ decide once how you want to handle shops by defining an alias called
+ <quote>shop</quote>, you can later change your policy on shops in
+ <emphasis>one</emphasis> place, and your changes will take effect everywhere
+ in the actions file where the <quote>shop</quote> alias is used. Calling aliases
+ by their purpose also makes your actions files more readable.
</para>
-
<para>
- If <quote>log-highlight-messages</quote> is set to 1,
- <application>Privoxy</application> will highlight portions of the log
- messages with a bold-faced font:
+ Currently, there is one big drawback to using aliases, though:
+ <application>Privoxy</application>'s built-in web-based action file
+ editor honors aliases when reading the actions files, but it expands
+ them before writing. So the effects of your aliases are of course preserved,
+ but the aliases themselves are lost when you edit sections that use aliases
+ with it.
+ This is likely to change in future versions of <application>Privoxy</application>.
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>log-highlight-messages 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
+ Now let's define some aliases...
</para>
<para>
- The font used in the console window:
-</para>
+ <screen>
+ # Useful custom aliases we can use later.
+ #
+ # Note the (required!) section header line and that this section
+ # must be at the top of the actions file!
+ #
+ {{alias}}
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>log-font-name Comic Sans MS</emphasis>
- </literallayout>
- </msgtext>
- </literal>
+ # These aliases just save typing later:
+ # (Note that some already use other aliases!)
+ #
+ +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
+ -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
+ block-as-image = +block +handle-as-image
+ mercy-for-cookies = -crunch-all-cookies -session-cookies-only
+
+ # These aliases define combinations of actions
+ # that are useful for certain types of sites:
+ #
+ fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups
+ shop = -crunch-all-cookies -filter{popups} -kill-popups
+
+ # Short names for other aliases, for really lazy people ;-)
+ #
+ c0 = +crunch-all-cookies
+ c1 = -crunch-all-cookies</screen>
</para>
<para>
- Font size used in the console window:
+ ...and put them to use. These sections would appear in the lower part of an
+ actions file and define exceptions to the default actions (as specified further
+ up for the <quote>/</quote> pattern):
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>log-font-size 8</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <screen>
+ # These sites are either very complex or very keen on
+ # user data and require minimal interference to work:
+ #
+ {fragile}
+ .office.microsoft.com
+ .windowsupdate.microsoft.com
+ .nytimes.com
-<para>
- <quote>show-on-task-bar</quote> controls whether or not
- <application>Privoxy</application> will appear as a button on the Task bar
- when minimized:
+ # Shopping sites:
+ # Allow cookies (for setting and retrieving your customer data)
+ #
+ {shop}
+ .quietpc.com
+ .worldpay.com # for quietpc.com
+ .scan.co.uk
+
+ # These shops require pop-ups:
+ #
+ {shop -kill-popups -filter{popups}}
+ .dabs.com
+ .overclockers.co.uk</screen>
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>show-on-task-bar 0</emphasis>
- </literallayout>
- </msgtext>
- </literal>
+ Aliases like <quote>shop</quote> and <quote>fragile</quote> are often used for
+ <quote>problem</quote> sites that require some actions to be disabled
+ in order to function properly.
</para>
+</sect2>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="act-examples">
+<title>Actions Files Tutorial</title>
<para>
- If <quote>close-button-minimizes</quote> is set to 1, the Windows close
- button will minimize <application>Privoxy</application> instead of closing
- the program (close with the exit option on the File menu).
+ The above chapters have shown <link linkend="actions-file">which actions files
+ there are and how they are organized</link>, how actions are <link
+ linkend="actions">specified</link> and <link linkend="actions-apply">applied
+ to URLs</link>, how <link linkend="af-patterns">patterns</link> work, and how to
+ define and use <link linkend="aliases">aliases</link>. Now, let's look at an
+ example <filename>default.action</filename> and <filename>user.action</filename>
+ file and see how all these pieces come together:
</para>
+<sect3><title>default.action</title>
+
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>close-button-minimizes 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
+Every config file should start with a short comment stating its purpose:
</para>
<para>
- The <quote>hide-console</quote> option is specific to the MS-Win console
- version of <application>Privoxy</application>. If this option is used,
- <application>Privoxy</application> will disconnect from and hide the
- command console.
+ <screen># Sample default.action file <developers@privoxy.org></screen>
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- #hide-console
- </literallayout>
- </msgtext>
- </literal>
+Then, since this is the <filename>default.action</filename> file, the
+first section is a special section for internal use that you needn't
+change or worry about:
</para>
-</sect3>
-</sect2>
-
-<!-- ~ End section ~ -->
-
+<para>
+ <screen>
+##########################################################################
+# Settings -- Don't change! For internal Privoxy use ONLY.
+##########################################################################
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="actionsfile">
-<title>The Actions File</title>
+{{settings}}
+for-privoxy-version=3.0</screen>
+</para>
<para>
- The <quote>default.action</quote> file (formerly
- <filename>actionsfile</filename> or <filename>ijb.action</filename>) is used to define what actions
- <application>Privoxy</application> takes, and thus determines how images,
- cookies and various other aspects of HTTP content and transactions are
- handled. Images can be anything you want, including ads, banners, or just
- some obnoxious URL that you would rather not see. Cookies can be accepted
- or rejected, or accepted only during the current browser session (i.e.
- not written to disk). Changes to <filename>default.action</filename> should
- be immediately visible to <application>Privoxy</application> without
- the need to restart.
+After that comes the (optional) alias section. We'll use the example
+section from the above <link linkend="aliases">chapter on aliases</link>,
+that also explains why and how aliases are used:
</para>
<para>
- The easiest way to edit <quote>actions</quote> file is with a browser by
- loading <ulink url="http://p.p/">http://p.p/</ulink>, and then select
- <quote>Edit Actions List</quote>. A text editor can also be used.
+ <screen>
+##########################################################################
+# Aliases
+##########################################################################
+{{alias}}
+
+# These aliases just save typing later:
+# (Note that some already use other aliases!)
+#
++crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
+-crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
+block-as-image = +block +handle-as-image
+mercy-for-cookies = -crunch-all-cookies -session-cookies-only
+
+# These aliases define combinations of actions
+# that are useful for certain types of sites:
+#
+fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups
+shop = mercy-for-cookies -filter{popups} -kill-popups</screen>
</para>
<para>
- To determine which actions apply to a request, the URL of the request is
- compared to all patterns in this file. Every time it matches, the list of
- applicable actions for the URL is incrementally updated. You can trace
- this process by visiting <ulink
- url="http://p.p/show-url-info">http://p.p/show-url-info</ulink>.
+ Now come the regular sections, i.e. sets of actions, accompanied
+ by URL patterns to which they apply. Remember <emphasis>all actions
+ are disabled when matching starts</emphasis>, so we have to explicitly
+ enable the ones we want.
</para>
-
<para>
- There are four types of lines in this file: comments (begin with a
- <quote>#</quote> character), actions, aliases and patterns, all of which are
- explained below, as well as the configuration file syntax that
- <application>Privoxy</application> understands.
-
+ The first regular section is probably the most important. It has only
+ one pattern, <quote><literal>/</literal></quote>, but this pattern
+ <link linkend="af-patterns">matches all URLs.</link>. Therefore, the
+ set of actions used in this <quote>default</quote> section <emphasis>will
+ be applied to all requests as a start</emphasis>. It can be partly or
+ wholly overridden by later matches further down this file, or in user.action,
+ but it will still be largely responsible for your overall browsing
+ experience.
</para>
+<para>
+ Again, at the start of matching, all actions are disabled, so there is
+ no real need to disable any actions here, but we will do that nonetheless,
+ to have a complete listing for your reference. (Remember: A <quote>+</quote>
+ preceding the action name enables the action, a <quote>-</quote> disables!).
+ Also note how this long line has been made more readable by splitting it into
+ multiple lines with line continuation.
+</para>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3>
-<title>URL Domain and Path Syntax</title>
<para>
- Generally, a pattern has the form <domain>/<path>, where both the
- <domain> and <path> part are optional. If you only specify a
- domain part, the <quote>/</quote> can be left out:
+ <screen>
+##########################################################################
+# "Defaults" section:
+##########################################################################
+ { \
+ -<link linkend="ADD-HEADER">add-header</link> \
+ -<link linkend="BLOCK">block</link> \
+ -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> \
+ -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link> \
+ +<link linkend="DEANIMATE-GIFS">deanimate-gifs</link> \
+ -<link linkend="DOWNGRADE-HTTP-VERSION">downgrade-http-version</link> \
+ +<link linkend="FAST-REDIRECTS">fast-redirects</link> \
+ +<link linkend="FILTER-HTML-ANNOYANCES">filter{html-annoyances}</link> \
+ +<link linkend="FILTER-JS-ANNOYANCES">filter{js-annoyances}</link> \
+ -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link> \
+ +<link linkend="FILTER-POPUPS">filter{popups}</link> \
+ +<link linkend="FILTER-WEBBUGS">filter{webbugs}</link> \
+ -<link linkend="FILTER-REFRESH-TAGS">filter{refresh-tags}</link> \
+ -<link linkend="FILTER-FUN">filter{fun}</link> \
+ +<link linkend="FILTER-NIMDA">filter{nimda}</link> \
+ +<link linkend="FILTER-BANNERS-BY-SIZE">filter{banners-by-size}</link> \
+ -<link linkend="FILTER-SHOCKWAVE-FLASH">filter{shockwave-flash}</link> \
+ -<link linkend="FILTER-CRUDE-PARENTAL">filter{crude-parental}</link> \
+ -<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> \
+ +<link linkend="HIDE-FORWARDED-FOR-HEADERS">hide-forwarded-for-headers</link> \
+ +<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
+ +<link linkend="HIDE-REFERER">hide-referrer{forge}</link> \
+ -<link linkend="HIDE-USER-AGENT">hide-user-agent</link> \
+ -<link linkend="KILL-POPUPS">kill-popups</link> \
+ -<link linkend="LIMIT-CONNECT">limit-connect</link> \
+ +<link linkend="PREVENT-COMPRESSION">prevent-compression</link> \
+ -<link linkend="SEND-VANILLA-WAFER">send-vanilla-wafer</link> \
+ -<link linkend="SEND-WAFER">send-wafer</link> \
+ +<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> \
+ +<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
+ }
+ / # forward slash will match *all* potential URL patterns.</screen>
+</para>
+
+<para>
+ The default behavior is now set. Note that some actions, like not hiding
+ the user agent, are part of a <quote>general policy</quote> that applies
+ universally and won't get any exceptions defined later. Other choices,
+ like not blocking (which is <emphasis>understandably</emphasis> the
+ default!) need exceptions, i.e. we need to specify explicitly what we
+ want to block in later sections.
+ We will also want to make exceptions from our general pop-up-killing,
+ and use our defined aliases for that.
+</para>
+
+<para>
+ The first of our specialized sections is concerned with <quote>fragile</quote>
+ sites, i.e. sites that require minimum interference, because they are either
+ very complex or very keen on tracking you (and have mechanisms in place that
+ make them unusable for people who avoid being tracked). We will simply use
+ our pre-defined <literal>fragile</literal> alias instead of stating the list
+ of actions explicitly:
</para>
<para>
- <emphasis>www.example.com</emphasis> - is a domain only pattern and will match any request to
- <quote>www.example.com</quote>.
+ <screen>
+##########################################################################
+# Exceptions for sites that'll break under the default action set:
+##########################################################################
+
+# "Fragile" Use a minimum set of actions for these sites (see alias above):
+#
+{ fragile }
+.office.microsoft.com # surprise, surprise!
+.windowsupdate.microsoft.com</screen>
</para>
<para>
- <emphasis>www.example.com/</emphasis> - means exactly the same.
+ Shopping sites are not as fragile, but they typically
+ require cookies to log in, and pop-up windows for shopping
+ carts or item details. Again, we'll use a pre-defined alias:
</para>
-
+
<para>
- <emphasis>www.example.com/index.html</emphasis> - matches only the single
- document <quote>/index.html</quote> on <quote>www.example.com</quote>.
+ <screen>
+# Shopping sites:
+#
+{ shop }
+.quietpc.com
+.worldpay.com # for quietpc.com
+.jungle.com
+.scan.co.uk</screen>
</para>
<para>
- <emphasis>/index.html</emphasis> - matches the document <quote>/index.html</quote>, regardless of
- the domain.
+ Then, there are sites which rely on pop-up windows (yuck!) to work.
+ Since we made pop-up-killing our default above, we need to make exceptions
+ now. <ulink url="http://www.mozilla.org/">Mozilla</ulink> users, who
+ can turn on smart handling of unwanted pop-ups in their browsers, can
+ safely choose
+ -<literal><link linkend="FILTER-POPUPS">filter{popups}</link></literal> (and
+ -<literal><link linkend="KILL-POPUPS">kill-popups</link></literal>) above
+ and hence don't need this section. Anyway, disabling an already disabled
+ action doesn't hurt, so we'll define our exceptions regardless of what was
+ chosen in the defaults section:
</para>
<para>
- <emphasis>index.html</emphasis> - matches nothing, since it would be
- interpreted as a domain name and there is no top-level domain called
- <quote>.html</quote>.
+ <screen>
+# These sites require pop-ups too :(
+#
+{ -<link linkend="KILL-POPUPS">kill-popups</link> -<link linkend="FILTER-POPUPS">filter{popups}</link> }
+.dabs.com
+.overclockers.co.uk
+.deutsche-bank-24.de</screen>
</para>
<para>
- The matching of the domain part offers some flexible options: if the
- domain starts or ends with a dot, it becomes unanchored at that end.
- For example:
+ The <literal><link linkend="FAST-REDIRECTS">fast-redirects</link></literal>
+ action, which we enabled per default above, breaks some sites. So disable
+ it for popular sites where we know it misbehaves:
</para>
<para>
- <emphasis>.example.com</emphasis> - matches any domain that <emphasis>ENDS</emphasis> in
- <quote>.example.com</quote>.
+ <screen>
+{ -<link linkend="FAST-REDIRECTS">fast-redirects</link> }
+login.yahoo.com
+edit.*.yahoo.com
+.google.com
+.altavista.com/.*(like|url|link):http
+.altavista.com/trans.*urltext=http
+.nytimes.com</screen>
</para>
<para>
- <emphasis>www.</emphasis> - matches any domain that <emphasis>STARTS</emphasis> with
- <quote>www</quote>.
+ It is important that <application>Privoxy</application> knows which
+ URLs belong to images, so that <emphasis>if</emphasis> they are to
+ be blocked, a substitute image can be sent, rather than an HTML page.
+ Contacting the remote site to find out is not an option, since it
+ would destroy the loading time advantage of banner blocking, and it
+ would feed the advertisers (in terms of money <emphasis>and</emphasis>
+ information). We can mark any URL as an image with the <literal><link
+ linkend="handle-as-image">handle-as-image</link></literal> action,
+ and marking all URLs that end in a known image file extension is a
+ good start:
</para>
<para>
- Additionally, there are wild-cards that you can use in the domain names
- themselves. They work pretty similar to shell wild-cards: <quote>*</quote>
- stands for zero or more arbitrary characters, <quote>?</quote> stands for
- any single character. And you can define character classes in square
- brackets and they can be freely mixed:
+ <screen>
+##########################################################################
+# Images:
+##########################################################################
+
+# Define which file types will be treated as images, in case they get
+# blocked further down this file:
+#
+{ +<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> }
+/.*\.(gif|jpe?g|png|bmp|ico)$</screen>
</para>
<para>
- <emphasis>ad*.example.com</emphasis> - matches <quote>adserver.example.com</quote>,
- <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>.
+ And then there are known banner sources. They often use scripts to
+ generate the banners, so it won't be visible from the URL that the
+ request is for an image. Hence we block them <emphasis>and</emphasis>
+ mark them as images in one go, with the help of our
+ <literal>block-as-image</literal> alias defined above. (We could of
+ course just as well use <literal>+<link linkend="block">block</link>
+ +<link linkend="handle-as-image">handle-as-image</link></literal> here.)
+ Remember that the type of the replacement image is chosen by the
+ <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
+ action. Since all URLs have matched the default section with its
+ <literal>+<link linkend="set-image-blocker">set-image-blocker</link>{pattern}</literal>
+ action before, it still applies and needn't be repeated:
</para>
<para>
- <emphasis>*ad*.example.com</emphasis> - matches all of the above, and then some.
+ <screen>
+# Known ad generators:
+#
+{ block-as-image }
+ar.atwola.com
+.ad.doubleclick.net
+.ad.*.doubleclick.net
+.a.yimg.com/(?:(?!/i/).)*$
+.a[0-9].yimg.com/(?:(?!/i/).)*$
+bs*.gsanet.com
+bs*.einets.com
+.qkimg.net</screen>
</para>
<para>
- <emphasis>.?pix.com</emphasis> - matches <quote>www.ipix.com</quote>,
- <quote>pictures.epix.com</quote>, <quote>a.b.c.d.e.upix.com</quote>, etc.
+ One of the most important jobs of <application>Privoxy</application>
+ is to block banners. A huge bunch of them are already <quote>blocked</quote>
+ by the <literal><link linkend="filter">filter</link>{banners-by-size}</literal>
+ action, which we enabled above, and which deletes the references to banner
+ images from the pages while they are loaded, so the browser doesn't request
+ them anymore, and hence they don't need to be blocked here. But this naturally
+ doesn't catch all banners, and some people choose not to use filters, so we
+ need a comprehensive list of patterns for banner URLs here, and apply the
+ <literal><link linkend="block">block</link></literal> action to them.
</para>
-
<para>
- <emphasis>www[1-9a-ez].example.com</emphasis> - matches <quote>www1.example.com</quote>,
- <quote>www4.example.com</quote>, <quote>wwwd.example.com</quote>,
- <quote>wwwz.example.com</quote>, etc., but <emphasis>not</emphasis>
- <quote>wwww.example.com</quote>.
+ First comes a bunch of generic patterns, which do most of the work, by
+ matching typical domain and path name components of banners. Then comes
+ a list of individual patterns for specific sites, which is omitted here
+ to keep the example short:
</para>
<para>
- If <application>Privoxy</application> was compiled with
- <quote>pcre</quote> support (default), Perl compatible regular expressions
- can be used. See the <filename>pcre/docs/</filename> directory or <quote>man
- perlre</quote> (also available on <ulink
- url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>)
- for details. A brief discussion of regular expressions is in the
- <link linkend="regex">Appendix</link>. For instance:
+ <screen>
+##########################################################################
+# Block these fine banners:
+##########################################################################
+{ <link linkend="BLOCK">+block</link> }
+
+# Generic patterns:
+#
+ad*.
+.*ads.
+banner?.
+count*.
+/.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
+/(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
+
+# Site-specific patterns (abbreviated):
+#
+.hitbox.com</screen>
</para>
<para>
- <emphasis>/.*/advert[0-9]+\.jpe?g</emphasis> - would match a URL from any
- domain, with any path that includes <quote>advert</quote> followed
- immediately by one or more digits, then a <quote>.</quote> and ending in
- either <quote>jpeg</quote> or <quote>jpg</quote>. So we match
- <quote>example.com/ads/advert2.jpg</quote>, and
- <quote>www.example.com/ads/banners/advert39.jpeg</quote>, but not
- <quote>www.example.com/ads/banners/advert39.gif</quote> (no gifs in the
- example pattern).
+ You wouldn't believe how many advertisers actually call their banner
+ servers ads.<replaceable>company</replaceable>.com, or call the directory
+ in which the banners are stored simply <quote>banners</quote>. So the above
+ generic patterns are surprisingly effective.
</para>
-
<para>
- Please note that matching in the path is case
- <emphasis>INSENSITIVE</emphasis> by default, but you can switch to case
- sensitive at any point in the pattern by using the
- <quote>(?-i)</quote> switch:
+ But being very generic, they necessarily also catch URLs that we don't want
+ to block. The pattern <literal>.*ads.</literal> e.g. catches
+ <quote>nasty-<emphasis>ads</emphasis>.nasty-corp.com</quote> as intended,
+ but also <quote>downlo<emphasis>ads</emphasis>.sourcefroge.net</quote> or
+ <quote><emphasis>ads</emphasis>l.some-provider.net.</quote> So here come some
+ well-known exceptions to the <literal>+<link linkend="BLOCK">block</link></literal>
+ section above.
</para>
-
<para>
- <emphasis>www.example.com/(?-i)PaTtErN.*</emphasis> - will match only
- documents whose path starts with <quote>PaTtErN</quote> in
- <emphasis>exactly</emphasis> this capitalization.
+ Note that these are exceptions to exceptions from the default! Consider the URL
+ <quote>downloads.sourcefroge.net</quote>: Initially, all actions are deactivated,
+ so it wouldn't get blocked. Then comes the defaults section, which matches the
+ URL, but just deactivates the <literal><link linkend="BLOCK">block</link></literal>
+ action once again. Then it matches <literal>.*ads.</literal>, an exception to the
+ general non-blocking policy, and suddenly
+ <literal><link linkend="BLOCK">+block</link></literal> applies. And now, it'll match
+ <literal>.*loads.</literal>, where <literal><link linkend="BLOCK">-block</link></literal>
+ applies, so (unless it matches <emphasis>again</emphasis> further down) it ends up
+ with no <literal><link linkend="BLOCK">block</link></literal> action applying.
</para>
-</sect3>
-
-<!-- ~ End section ~ -->
+<para>
+ <screen>
+##########################################################################
+# Save some innocent victims of the above generic block patterns:
+##########################################################################
+# By domain:
+#
+{ -<link linkend="BLOCK">block</link> }
+adv[io]*. # (for advogato.org and advice.*)
+adsl. # (has nothing to do with ads)
+ad[ud]*. # (adult.* and add.*)
+.edu # (universities don't host banners (yet!))
+.*loads. # (downloads, uploads etc)
+# By path:
+#
+/.*loads/
-<!-- ~~~~~ New section ~~~~~ -->
+# Site-specific:
+#
+www.globalintersec.com/adv # (adv = advanced)
+www.ugu.com/sui/ugu/adv</screen>
+</para>
-<sect3>
-<title>Actions</title>
<para>
- Actions are enabled if preceded with a <quote>+</quote>, and disabled if
- preceded with a <quote>-</quote>. Actions are invoked by enclosing the
- action name in curly braces (e.g. {+some_action}), followed by a list of
- URLs to which the action applies. There are three classes of actions:
+ Filtering source code can have nasty side effects,
+ so make an exception for our friends at sourceforge.net,
+ and all paths with <quote>cvs</quote> in them. Note that
+ <literal>-<link linkend="FILTER">filter</link></literal>
+ disables <emphasis>all</emphasis> filters in one fell swoop!
</para>
<para>
- <itemizedlist>
+ <screen>
+# Don't filter code!
+#
+{ -<link linkend="FILTER">filter</link> }
+/.*cvs
+.sourceforge.net</screen>
+</para>
- <listitem>
- <para>
- Boolean (e.g. <quote>+/-block</quote>):
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>{+name}</emphasis> # enable this action
- <emphasis>{-name}</emphasis> # disable this action
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
+<para>
+ The actual <filename>default.action</filename> is of course more
+ comprehensive, but we hope this example made clear how it works.
+</para>
+</sect3>
- <listitem>
- <para>
- parameterized (e.g. <quote>+/-hide-user-agent</quote>):
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>{+name{param}}</emphasis> # enable action and set parameter to <quote>param</quote>
- <emphasis>{-name}</emphasis> # disable action
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Multi-value (e.g. <quote>{+/-add-header{Name: value}}</quote>, <quote>{+/-wafer{name=value}}</quote>):
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>{+name{param}}</emphasis> # enable action and add parameter <quote>param</quote>
- <emphasis>{-name{param}}</emphasis> # remove the parameter <quote>param</quote>
- <emphasis>{-name}</emphasis> # disable this action totally
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
+<sect3><title>user.action</title>
- </itemizedlist>
+<para>
+ So far we are painting with a broad brush by setting general policies,
+ which would be a reasonable starting point for many people. Now,
+ you'd maybe want to be more specific and have customized rules that
+ are more suitable to your personal habits and preferences. These would
+ be for narrowly defined situations like your ISP or your bank, and should
+ be placed in <filename>user.action</filename>, which is parsed after all other
+ actions files and hence has the last word, over-riding any previously
+ defined actions. <filename>user.action</filename> is also a
+ <emphasis>safe</emphasis> place for your personal settings, since
+ <filename>default.action</filename> is actively maintained by the
+ <application>Privoxy</application> developers and you'll probably want
+ to install updated versions from time to time.
</para>
<para>
- If nothing is specified in this file, no <quote>actions</quote> are taken.
- So in this case <application>Privoxy</application> would just be a
- normal, non-blocking, non-anonymizing proxy. You must specifically
- enable the privacy and blocking features you need (although the
- provided default <filename>default.action</filename> file will
- give a good starting point).
+ So let's look at a few examples of things that one might typically do in
+ <filename>user.action</filename>:
</para>
+
+<!-- brief sample user.action here -->
+
<para>
- Later defined actions always over-ride earlier ones. For multi-valued
- actions, the actions are applied in the order they are specified.
+ <screen>
+# My user.action file. <fred@foobar.com></screen>
</para>
<para>
- The list of valid <application>Privoxy</application> <quote>actions</quote> are:
+ As <link linkend="aliases">aliases</link> are local to the actions
+ file that they are defined in, you can't use the ones from
+ <filename>default.action</filename>, unless you repeat them here:
</para>
<para>
- <itemizedlist>
-
- <listitem>
- <para>
- Add the specified HTTP header, which is not checked for validity.
- You may specify this many times to specify many different headers:
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+add-header{Name: value}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- Block this URL totally. In a default installation, a <quote>blocked</quote>
- URL will result in bright red banner that says <quote>BLOCKED</quote>,
- with a reason why it is being blocked.
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+block</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- De-animate all animated GIF images, i.e. reduce them to their last frame.
- This will also shrink the images considerably (in bytes, not pixels!). If
- the option <quote>first</quote> is given, the first frame of the animation
- is used as the replacement. If <quote>last</quote> is given, the last frame
- of the animation is used instead, which probably makes more sense for most
- banner animations, but also has the risk of not showing the entire last
- frame (if it is only a delta to an earlier frame).
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+deanimate-gifs{last}</emphasis>
- <emphasis>+deanimate-gifs{first}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <quote>+downgrade</quote> will downgrade HTTP/1.1 client requests to
- HTTP/1.0 and downgrade the responses as well. Use this action for servers
- that use HTTP/1.1 protocol features that
- <application>Privoxy</application> doesn't handle well yet. HTTP/1.1
- is only partially implemented. Default is not to downgrade requests.
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+downgrade</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
+ <screen>
+# (Re-)define aliases for this file:
+#
+{{alias}}
+-crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
+mercy-for-cookies = -crunch-all-cookies -session-cookies-only
+fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups
+shop = mercy-for-cookies -filter{popups} -kill-popups
+allow-ads = -block -filter{banners-by-size} # (see below)</screen>
- <listitem>
- <para>
- Many sites, like yahoo.com, don't just link to other sites. Instead, they
- will link to some script on their own server, giving the destination as a
- parameter, which will then redirect you to the final target. URLs resulting
- from this scheme typically look like:
- http://some.place/some_script?http://some.where-else.
- </para>
- <para>
- Sometimes, there are even multiple consecutive redirects encoded in the
- URL. These redirections via scripts make your web browsing more traceable,
- since the server from which you follow such a link can see where you go to.
- Apart from that, valuable bandwidth and time is wasted, while your browser
- ask the server for one redirect after the other. Plus, it feeds the
- advertisers.
- </para>
- <para>
- The <quote>+fast-redirects</quote> option enables interception of these
- types of requests by <application>Privoxy</application>, who will cut off
- all but the last valid URL in the request and send a local redirect back to
- your browser without contacting the intermediate site(s).
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+fast-redirects</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Apply the filters in the <literal>section_header</literal>
- section of the <filename>default.filter</filename> file to the site(s).
- <filename>default.filter</filename> sections are grouped according to like
- functionality.
- </para>
-
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+filter{section_header}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
-
- <para>
- Filter sections that are pre-defined in the supplied
- <filename>default.filter</filename> include:
- </para>
+</para>
- <blockquote>
- <simplelist>
- <member>
- <emphasis>html-annoyances</emphasis>: Get rid of particularly annoying HTML abuse.
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>js-annoyances</emphasis>: Get rid of particularly annoying JavaScript abuse
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>no-poups</emphasis>: Kill all popups in JS and HTML
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>frameset-borders</emphasis>: Give frames a border
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>webbugs</emphasis>: Squish WebBugs (1x1 invisible GIFs used for user tracking)
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>no-refresh</emphasis>: Automatic refresh sucks on auto-dialup lines
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>fun</emphasis>: Text replacements for subversive browsing fun!
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>nimda</emphasis>: Remove (virus) Nimda code.
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>banners-by-size</emphasis>: Kill banners by size
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>crude-parental</emphasis>: Kill all web pages that contain the words "sex" or "warez"
- </member>
- </simplelist>
- </blockquote>
+<para>
+ Say you have accounts on some sites that you visit regularly, and
+ you don't want to have to log in manually each time. So you'd like
+ to allow persistent cookies for these sites. The
+ <literal>mercy-for-cookies</literal> alias defined above does exactly
+ that, i.e. it disables crunching of cookies in any direction, and
+ processing of cookies to make them temporary.
+</para>
- </listitem>
+<para>
+ <screen>
+{ mercy-for-cookies }
+sunsolve.sun.com
+slashdot.org
+.yahoo.com
+.msdn.microsoft.com
+.redhat.com</screen>
+</para>
- <listitem>
- <para>
- Block any existing X-Forwarded-for header, and do not add a new one:
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+hide-forwarded</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
+<para>
+ Your bank needs popups and is allergic to some filter, but you don't
+ know which, so you disable them all:
+</para>
- <listitem>
- <para>
- If the browser sends a <quote>From:</quote> header containing your e-mail
- address, this either completely removes the header (<quote>block</quote>), or
- changes it to the specified e-mail address.
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+hide-from{block}</emphasis>
- <emphasis>+hide-from{spam@sittingduck.xqq}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Don't send the <quote>Referer:</quote> (sic) header to the web site. You
- can block it, forge a URL to the same server as the request (which is
- preferred because some sites will not send images otherwise) or set it to a
- constant string of your choice.
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+hide-referer{block}</emphasis>
- <emphasis>+hide-referer{forge}</emphasis>
- <emphasis>+hide-referer{http://nowhere.com}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Alternative spelling of <quote>+hide-referer</quote>. It has the same
- parameters, and can be freely mixed with, <quote>+hide-referer</quote>.
- (<quote>referrer</quote> is the correct English spelling, however the HTTP
- specification has a bug - it requires it to be spelled <quote>referer</quote>.)
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+hide-referrer{...}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
+<para>
+ <screen>
+{ -<link linkend="FILTER">filter</link> -<link linkend="KILL-POPUPS">kill-popups</link> }
+.your-home-banking-site.com</screen>
+</para>
- <listitem>
- <para>
- Change the <quote>User-Agent:</quote> header so web servers can't tell your
- browser type. Warning! This breaks many web sites. Specify the
- user-agent value you want. Example, pretend to be using Netscape on
- Linux:
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+hide-user-agent{Mozilla (X11; I; Linux 2.0.32 i586)}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- <!--
- <para>
- Or to identify yourself explicitly as a <application>Privoxy</application> user:
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+hide-user-agent{Privoxy/1.0}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- (Don't change the version number from 1.0 - after all, why tell them?)
- <para>
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+hide-user-agent{browser-type}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
--->
- </listitem>
+<para>
+ While browsing the web with <application>Privoxy</application> you
+ noticed some ads that sneaked through, but you were too lazy to
+ report them through our fine and easy <link linkend="contact">feedback</link>
+ system, so you have added them here:
+</para>
- <listitem>
- <para>
- Treat this URL as an image. This only matters if it's also <quote>+block</quote>ed,
- in which case a <quote>blocked</quote> image can be sent rather than a HTML page.
- See <quote>+image-blocker{}</quote> below for the control over what is actually sent.
- If you want <emphasis>invisible</emphasis> ads, they should be defined as
- <emphasis>images</emphasis> and <emphasis>blocked</emphasis>. And also,
- <quote>image-blocker</quote> should be set to <quote>blank</quote>.
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+image</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para> Decides what to do with URLs that end up tagged with <quote>{+block
- +image}</quote>, e.g an advertizement. There are five options.
- <quote>-image-blocker</quote> will send a HTML <quote>blocked</quote> page,
- usually resulting in a <quote>broken image</quote> icon.
-<!-- <quote>+image-blocker{logo}</quote> will send a -->
-<!-- <application>Privoxy</application> logo -->
-<!-- image. -->
-<quote>+image-blocker{blank}</quote> will send a 1x1 transparent GIF
-image. And finally, <quote>+image-blocker{http://xyz.com}</quote> will send a
-HTTP temporary redirect to the specified image. This has the advantage of the
-icon being being cached by the browser, which will speed up the display.
-<quote>+image-blocker{pattern}</quote> will send a checkboard type pattern
-<!-- , -->
-<!-- which scales better than the logo (which can get blocky if the browser -->
-<!-- enlarges it too much). -->
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
-<!-- <emphasis>+image-blocker{logo}</emphasis> -->
- <emphasis>+image-blocker{blank}</emphasis>
- <emphasis>+image-blocker{pattern}</emphasis>
- <emphasis>+image-blocker{http://p.p/send-banner}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- By default (i.e. in the absence of a <quote>+limit-connect</quote>
- action), <application>Privoxy</application> will only allow CONNECT
- requests to port 443, which is the standard port for https as a
- precaution.
- </para>
-
- <para>
- The CONNECT methods exists in HTTP to allow access to secure websites
- (https:// URLs) through proxies. It works very simply: the proxy
- connects to the server on the specified port, and then short-circuits
- its connections to the client <emphasis>and</emphasis> to the remote proxy.
- This can be a big security hole, since CONNECT-enabled proxies can
- be abused as TCP relays very easily.
- </para>
-
- <para>
- If you want to allow CONNECT for more ports than this, or want to forbid
- CONNECT altogether, you can specify a comma separated list of ports and
- port ranges (the latter using dashes, with the minimum defaulting to 0 and
- max to 65K):
- </para>
+<para>
+ <screen>
+{ +<link linkend="BLOCK">block</link> }
+www.a-popular-site.com/some/unobvious/path
+another.popular.site.net/more/junk/here/</screen>
+</para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+limit-connect{443} # This is the default and need no be specified.</emphasis>
- <emphasis>+limit-connect{80,443} # Ports 80 and 443 are OK.</emphasis>
- <emphasis>+limit-connect{-3, 7, 20-100, 500-} # Port less than 3, 7, 20 to 100</emphasis>
- <emphasis> #and above 500 are OK.</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
+<para>
+ Note that, assuming the banners in the above example have regular image
+ extensions (most do),
+ <literal>+<link linkend="HANDLE-AS-IMAGE">handle-as-image</link></literal>
+ need not be specified, since all URLs ending in these extensions will
+ already have been tagged as images in the relevant section of
+ <filename>default.action</filename> by now.
+</para>
- </listitem>
-
- <listitem>
- <para>
- <quote>+no-compression</quote> prevents the website from compressing the
- data. Some websites do this, which can be a problem for
- <application>Privoxy</application>, since <quote>+filter</quote>,
- <quote>+no-popup</quote> and <quote>+gif-deanimate</quote> will not work on
- compressed data. This will slow down connections to those websites,
- though. Default is <quote>nocompression</quote> is turned on.
- </para>
+<para>
+ Then you noticed that the default configuration breaks Forbes Magazine,
+ but you were too lazy to find out which action is the culprit, and you
+ were again too lazy to give <link linkend="contact">feedback</link>, so
+ you just used the <literal>fragile</literal> alias on the site, and
+ -- whoa! -- it worked:
+</para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+nocompression</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- If the website sets cookies, <quote>no-cookies-keep</quote> will make sure
- they are erased when you exit and restart your web browser. This makes
- profiling cookies useless, but won't break sites which require cookies so
- that you can log in for transactions. Default: on.
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+no-cookies-keep</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Prevent the website from reading cookies:
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+no-cookies-read</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Prevent the website from setting cookies:
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+no-cookies-set</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Filter the website through a built-in filter to disable those obnoxious
- JavaScript pop-up windows via window.open(), etc. The two alternative
- spellings are equivalent.
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+no-popup</emphasis>
- <emphasis>+no-popups</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- This action only applies if you are using a <filename>jarfile</filename>
- for saving cookies. It sends a cookie to every site stating that you do not
- accept any copyright on cookies sent to you, and asking them not to track
- you. Of course, this is a (relatively) unique header they could use to
- track you.
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+vanilla-wafer</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- This allows you to add an arbitrary cookie. It can be specified multiple
- times in order to add as many cookies as you like.
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+wafer{name=value}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
+<para>
+<screen>
+{ fragile }
+.forbes.com</screen>
+</para>
- </itemizedlist>
+<para>
+ You like the <quote>fun</quote> text replacements in <filename>default.filter</filename>,
+ but it is disabled in the distributed actions file. (My colleagues on the team just
+ don't have a sense of humour, that's why! ;-). So you'd like to turn it on in your private,
+ update-safe config, once and for all:
</para>
<para>
- The meaning of any of the above is reversed by preceding the action with a
- <quote>-</quote>, in place of the <quote>+</quote>.
+<screen>
+{ +<link linkend="filter-fun">filter{fun}</link> }
+/ # For ALL sites!</screen>
</para>
<para>
- Some examples:
+ Note that the above is not really a good idea: There are exceptions
+ to the filters in <filename>default.action</filename> for things that
+ really shouldn't be filtered, like code on CVS->Web interfaces. Since
+ <filename>user.action</filename> has the last word, these exceptions
+ won't be valid for the <quote>fun</quote> filtering specified here.
</para>
<para>
- Turn off cookies by default, then allow a few through for specified sites:
+ Finally, you might think about how your favourite free websites are
+ funded, and find that they rely on displaying banner advertisements
+ to survive. So you might want to specifically allow banners for those
+ sites that you feel provide value to you:
</para>
-
+
<para>
- <literal>
- <msgtext>
- <literallayout>
- # Turn off all persistent cookies
- { +no-cookies-read }
- { +no-cookies-set }
- # Allow cookies for this browser session ONLY
- { +no-cookies-keep }
-
- # Exceptions to the above, sites that benefit from persistent cookies
- { -no-cookies-read }
- { -no-cookies-set }
- { -no-cookies-keep }
- .javasoft.com
- .sun.com
- .yahoo.com
- .msdn.microsoft.com
- .redhat.com
-
- # Alternative way of saying the same thing
- {-no-cookies-set -no-cookies-read -no-cookies-keep}
- .sourceforge.net
- .sf.net
- </literallayout>
- </msgtext>
- </literal>
+<screen>
+{ allow-ads }
+.sourceforge.net
+.slashdot.org
+.osdn.net</screen>
</para>
<para>
- Now turn off <quote>fast redirects</quote>, and then we allow two exceptions:
+ Note that <literal>allow-ads</literal> has been aliased to
+ <literal>-<link linkend="block">block</link></literal>
+ <literal>-<link linkend="filter-banners-by-size">filter{banners-by-size}</link></literal>
+ above.
</para>
+</sect3>
+</sect2>
+
+<!-- ~ End section ~ -->
+
+</sect1>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+
+<sect1 id="filter-file">
+<title>The Filter File</title>
<para>
- <literal>
- <msgtext>
- <literallayout>
- # Turn them off!
- {+fast-redirects}
-
- # Reverse it for these two sites, which don't work right without it.
- {-fast-redirects}
- www.ukc.ac.uk/cgi-bin/wac\.cgi\?
- login.yahoo.com
- </literallayout>
- </msgtext>
- </literal>
+ All text substitutions that can be invoked through the
+ <literal><link linkend="filter">filter</link></literal> action
+ must first be defined in the filter file, which is typically
+ called <filename>default.filter</filename> and which can be
+ selected through the <literal>
+ <link linkend="filterfile">filterfile</link></literal> config
+ option.
</para>
<para>
- Turn on page filtering according to rules in the defined sections
- of <filename>refilterfile</filename>, and make one exception for
- sourceforge:
- </para>
+ Typical reasons for doing such substitutions are to eliminate
+ common annoyances in HTML and JavaScript, such as pop-up windows,
+ exit consoles, crippled windows without navigation tools, the
+ infamous <BLINK> tag etc, to suppress images with certain
+ width and height attributes (standard banner sizes or web-bugs),
+ or just to have fun. The possibilities are endless.
+</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- # Run everything through the filter file, using only the
- # specified sections:
- +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}\
- +filter{webbugs} +filter{nimda} +filter{banners-by-size}
-
- # Then disable filtering of code from sourceforge!
- {-filter}
- .cvs.sourceforge.net
- </literallayout>
- </msgtext>
- </literal>
+ Filtering works on any text-based document type, including plain
+ text, HTML, JavaScript, CSS etc. (all <literal>text/*</literal>
+ MIME types). Substitutions are made at the source level, so if
+ you want to <quote>roll your own</quote> filters, you should be
+ familiar with HTML syntax.
</para>
<para>
- Now some URLs that we want <quote>blocked</quote>, ie we won't see them.
- Many of these use regular expressions that will expand to match multiple
- URLs:
+ Just like the <link linkend="actions-file">actions files</link>, the
+ filter file is organized in sections, which are called <emphasis>filters</emphasis>
+ here. Each filter consists of a heading line, that starts with the
+ <emphasis>keyword</emphasis> <literal>FILTER:</literal>, followed by
+ the filter's <emphasis>name</emphasis>, and a short (one line)
+ <emphasis>description</emphasis> of what it does. Below that line
+ come the <emphasis>jobs</emphasis>, i.e. lines that define the actual
+ text substitutions. By convention, the name of a filter
+ should describe what the filter <emphasis>eliminates</emphasis>. The
+ comment is used in the <ulink url="http://config.privoxy.org/">web-based
+ user interface</ulink>.
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- # Blocklist:
- {+block}
- /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g))
- /.*/(.*[-_.])?count(er)?(\.cgi|\.dll|\.exe|[?/])
- /.*/(ng)?adclient\.cgi
- /.*/(plain|live|rotate)[-_.]?ads?/
- /.*/(sponsor)s?[0-9]?/
- /.*/_?(plain|live)?ads?(-banners)?/
- /.*/abanners/
- /.*/ad(sdna_image|gifs?)/
- /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe)
- /.*/adbanners/
- /.*/adserver
- /.*/adstream\.cgi
- /.*/adv((er)?ts?|ertis(ing|ements?))?/
- /.*/banner_?ads/
- /.*/banners?/
- /.*/banners?\.cgi/
- /.*/cgi-bin/centralad/getimage
- /.*/images/addver\.gif
- /.*/images/marketing/.*\.(gif|jpe?g)
- /.*/popupads/
- /.*/siteads/
- /.*/sponsor.*\.gif
- /.*/sponsors?[0-9]?/
- /.*/advert[0-9]+\.jpg
- /Media/Images/Adds/
- /ad_images/
- /adimages/
- /.*/ads/
- /bannerfarm/
- /grafikk/annonse/
- /graphics/defaultAd/
- /image\.ng/AdType
- /image\.ng/transactionID
- /images/.*/.*_anim\.gif # alvin brattli
- /ip_img/.*\.(gif|jpe?g)
- /rotateads/
- /rotations/
- /worldnet/ad\.cgi
- /cgi-bin/nph-adclick.exe/
- /.*/Image/BannerAdvertising/
- /.*/ad-bin/
- /.*/adlib/server\.cgi
- /autoads/
- </literallayout>
- </msgtext>
- </literal>
+ Once a filter called <replaceable>name</replaceable> has been defined
+ in the filter file, it can be invoked by using an action of the form
+ +<literal><link linkend="filter">filter</link>{<replaceable>name</replaceable>}</literal>
+ in any <link linkend="actions-file">actions file</link>.
+</para>
+
+<para>
+ A filter header line for a filter called <quote>foo</quote> could look
+ like this:
</para>
<para>
- Note that many of these actions have the potential to cause a page to
- misbehave, possibly even not to display at all. There are many ways
- a site designer may choose to design his site, and what HTTP header
- content he may depend on. There is no way to have hard and fast rules
- for all sites. See the <link linkend="ACTIONSANAT">Appendix</link>
- for a brief example on troubleshooting actions.
+ <screen>FILTER: foo Replace all "foo" with "bar"</screen>
+</para>
+<para>
+ Below that line, and up to the next header line, come the jobs that
+ define what text replacements the filter executes. They are specified
+ in a syntax that imitates <ulink url="http://www.perl.org/">Perl</ulink>'s
+ <literal>s///</literal> operator. If you are familiar with Perl, you
+ will find this to be quite intuitive, and may want to look at the
+ <ulink url="http://www.oesterhelt.org/pcrs/pcrs.1.html">PCRS man page</ulink>
+ for the subtle differences to Perl behaviour. Most notably, the non-standard
+ option letter <literal>U</literal> is supported, which turns the default
+ to ungreedy matching.
</para>
-</sect3>
+<para>
+ If you are new to regular expressions, you might want to take a look at
+ the <link linkend="regex">Appendix on regular expressions</link>, and
+ see the <ulink url="http://perldoc.com/perl5.6.1/pod/perl.html">Perl
+ manual</ulink> for
+ <ulink url="http://perldoc.com/perl5.6.1/pod/perlop.html#s-PATTERN-REPLACEMENT-egimosx">the
+ <literal>s///</literal> operator's syntax</ulink> and <ulink
+ url="http://perldoc.com/perl5.6.1/pod/perlre.html">Perl-style regular
+ expressions</ulink> in general.
+ The below examples might also help to get you started.
+</para>
-<!-- ~ End section ~ -->
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+<sect2><title>Filter File Tutorial</title>
+<para>
+ Now, let's complete our <quote>foo</quote> filter. We have already defined
+ the heading, but the jobs are still missing. Since all it does is to replace
+ <quote>foo</quote> with <quote>bar</quote>, there is only one (trivial) job
+ needed:
+</para>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3>
-<title>Aliases</title>
<para>
- Custom <quote>actions</quote>, known to <application>Privoxy</application>
- as <quote>aliases</quote>, can be defined by combining other <quote>actions</quote>.
- These can in turn be invoked just like the built-in <quote>actions</quote>.
- Currently, an alias can contain any character except space, tab, <quote>=</quote>,
- <quote>{</quote> or <quote>}</quote>. But please use only <quote>a</quote>-
- <quote>z</quote>, <quote>0</quote>-<quote>9</quote>, <quote>+</quote>, and
- <quote>-</quote>. Alias names are not case sensitive, and
- <emphasis>must be defined before anything</emphasis> else in the
- <filename>default.action</filename>file ! And there can only be one set of
- <quote>aliases</quote> defined.
+ <screen>s/foo/bar/</screen>
</para>
<para>
- Now let's define a few aliases:
+ But wait! Didn't the comment say that <emphasis>all</emphasis> occurrences
+ of <quote>foo</quote> should be replaced? Our current job will only take
+ care of the first <quote>foo</quote> on each page. For global substitution,
+ we'll need to add the <literal>g</literal> option:
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- # Useful customer aliases we can use later. These must come first!
- {{alias}}
- +no-cookies = +no-cookies-set +no-cookies-read
- -no-cookies = -no-cookies-set -no-cookies-read
- fragile = -block -no-cookies -filter -fast-redirects -hide-referer -no-popups
- shop = -no-cookies -filter -fast-redirects
- +imageblock = +block +image
-
- #For people who don't like to type too much: ;-)
- c0 = +no-cookies
- c1 = -no-cookies
- c2 = -no-cookies-set +no-cookies-read
- c3 = +no-cookies-set -no-cookies-read
- #... etc. Customize to your heart's content.
- </literallayout>
- </msgtext>
- </literal>
+ <screen>s/foo/bar/g</screen>
</para>
<para>
- Some examples using our <quote>shop</quote> and <quote>fragile</quote>
- aliases from above:
+ Our complete filter now looks like this:
+</para>
+<para>
+ <screen>FILTER: foo Replace all "foo" with "bar"
+s/foo/bar/g</screen>
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- # These sites are very complex and require
- # minimal interference.
- {fragile}
- .office.microsoft.com
- .windowsupdate.microsoft.com
- .nytimes.com
+ Let's look at some real filters for more interesting examples. Here you see
+ a filter that protects against some common annoyances that arise from JavaScript
+ abuse. Let's look at its jobs one after the other:
+</para>
- # Shopping sites - still want to block ads.
- {shop}
- .quietpc.com
- .worldpay.com # for quietpc.com
- .jungle.com
- .scan.co.uk
- # These shops require pop-ups
- {shop -no-popups}
- .dabs.com
- .overclockers.co.uk
- </literallayout>
- </msgtext>
- </literal>
+<para>
+ <screen>
+FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse
+
+# Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm
+#
+s|(<script.*)document\.referrer(.*</script>)|$1"Not Your Business!"$2|Usg</screen>
</para>
-</sect3>
-</sect2>
+<para>
+ Following the header line and a comment, you see the job. Note that it uses
+ <literal>|</literal> as the delimiter instead of <literal>/</literal>, because
+ the pattern contains a forward slash, which would otherwise have to be escaped
+ by a backslash (<literal>\</literal>).
+</para>
-<!-- ~ End section ~ -->
+<para>
+ Now, let's examine the pattern: it starts with the text <literal><script.*</literal>
+ enclosed in parentheses. Since the dot matches any character, and <literal>*</literal>
+ means: <quote>Match an arbitrary number of the element left of myself</quote>, this
+ matches <quote><script</quote>, followed by <emphasis>any</emphasis> text, i.e.
+ it matches the whole page, from the start of the first <script> tag.
+</para>
+<para>
+ That's more than we want, but the pattern continues: <literal>document\.referrer</literal>
+ matches only the exact string <quote>document.referrer</quote>. The dot needed to
+ be <emphasis>escaped</emphasis>, i.e. preceded by a backslash, to take away its
+ special meaning as a joker, and make it just a regular dot. So far, the meaning is:
+ Match from the start of the first <script> tag in a the page, up to, and including,
+ the text <quote>document.referrer</quote>, if <emphasis>both</emphasis> are present
+ in the page (and appear in that order).
+</para>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="filterfile">
-<title>The Filter File</title>
<para>
- Any web page can be dynamically modified with the filter file. This
- modification can be removal, or re-writing, of any web page content,
- including tags and non-visible content. The default filter file is
- <filename>default.filter</filename>, located in the config directory.
+ But there's still more pattern to go. The next element, again enclosed in parentheses,
+ is <literal>.*</script></literal>. You already know what <literal>.*</literal>
+ means, so the whole pattern translates to: Match from the start of the first <script>
+ tag in a page to the end of the last <script> tag, provided that the text
+ <quote>document.referrer</quote> appears somewhere in between.
</para>
<para>
- The included example file is divided into sections. Each section begins
- with the <literal>FILTER</literal> keyword, followed by the identifier
- for that section, e.g. <quote>FILTER: webbugs</quote>. Each section performs
- a similar type of filtering, such as <quote>html-annoyances</quote>.
+ This is still not the whole story, since we have ignored the options and the parentheses:
+ The portions of the page matched by sub-patterns that are enclosed in parentheses, will be
+ remembered and be available through the variables <literal>$1, $2, ...</literal> in
+ the substitute. The <literal>U</literal> option switches to ungreedy matching, which means
+ that the first <literal>.*</literal> in the pattern will only <quote>eat up</quote> all
+ text in between <quote><script</quote> and the <emphasis>first</emphasis> occurrence
+ of <quote>document.referrer</quote>, and that the second <literal>.*</literal> will
+ only span the text up to the <emphasis>first</emphasis> <quote></script></quote>
+ tag. Furthermore, the <literal>s</literal> option says that the match may span
+ multiple lines in the page, and the <literal>g</literal> option again means that the
+ substitution is global.
+</para>
+<para>
+ So, to summarize, the pattern means: Match all scripts that contain the text
+ <quote>document.referrer</quote>. Remember the parts of the script from
+ (and including) the start tag up to (and excluding) the string
+ <quote>document.referrer</quote> as <literal>$1</literal>, and the part following
+ that string, up to and including the closing tag, as <literal>$2</literal>.
</para>
<para>
- This file uses regular expressions to alter or remove any string in the
- target page. The expressions can only operate on one line at a time. Some
- examples from the included default <filename>default.filter</filename>:
+ Now the pattern is deciphered, but wasn't this about substituting things? So
+ lets look at the substitute: <literal>$1"Not Your Business!"$2</literal> is
+ easy to read: The text remembered as <literal>$1</literal>, followed by
+ <literal>"Not Your Business!"</literal> (<emphasis>including</emphasis>
+ the quotation marks!), followed by the text remembered as <literal>$2</literal>.
+ This produces an exact copy of the original string, with the middle part
+ (the <quote>document.referrer</quote>) replaced by <literal>"Not Your
+ Business!"</literal>.
</para>
<para>
- Stop web pages from displaying annoying messages in the status bar by
- deleting such references:
+ The whole job now reads: Replace <quote>document.referrer</quote> by
+ <literal>"Not Your Business!"</literal> wherever it appears inside a
+ <script> tag. Note that this job won't break JavaScript syntax,
+ since both the original and the replacement are syntactically valid
+ string objects. The script just won't have access to the referrer
+ information anymore.
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- FILTER: html-annoyances
+ We'll show you two other jobs from the JavaScript taming department, but
+ this time only point out the constructs of special interest:
+</para>
- # New browser windows should be resizeable and have a location and status
- # bar. Make it so.
- #
- s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig
- s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig
- s/scrolling="?(no|0|Auto)"?/scrolling=1/ig
- s/menubar="?(no|0)"?/menubar=1/ig
+<para>
+ <screen>
+# The status bar is for displaying link targets, not pointless blahblah
+#
+s/window\.status\s*=\s*['"].*?['"]/dUmMy=1/ig</screen>
+</para>
- # The <BLINK> tag was a crime!
- #
- s*<blink>|</blink>**ig
+<para>
+ <literal>\s</literal> stands for whitespace characters (space, tab, newline,
+ carriage return, form feed), so that <literal>\s*</literal> means: <quote>zero
+ or more whitespace</quote>. The <literal>?</literal> in <literal>.*?</literal>
+ makes this matching of arbitrary text ungreedy. (Note that the <literal>U</literal>
+ option is not set). The <literal>['"]</literal> construct means: <quote>a single
+ <emphasis>or</emphasis> a double quote</quote>.
+</para>
- # Is this evil?
- #
- #s/framespacing="?(no|0)"?//ig
- #s/margin(height|width)=[0-9]*//gi
- </literallayout>
- </msgtext>
- </literal>
+<para>
+ So what does this job do? It replaces assignments of single- or double-quoted
+ strings to the <quote>window.status</quote> object with a dummy assignment
+ (using a variable name that is hopefully odd enough not to conflict with
+ real variables in scripts). Thus, it catches many cases where e.g. pointless
+ descriptions are displayed in the status bar instead of the link target when
+ you move your mouse over links.
+</para>
+
+<para>
+ <screen>
+# Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
+#
+s/(<body .*)onunload(.*>)/$1never$2/iU</screen>
</para>
<para>
- Just for kicks, replace any occurrence of <quote>Microsoft</quote> with
- <quote>MicroSuck</quote>, and have a little fun with topical buzzwords:
+ Including the
+ <ulink url="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents">OnUnload
+ event binding</ulink> in the HTML DOM was a <emphasis>CRIME</emphasis>.
+ When I close a browser window, I want it to close and die. Basta.
+ This job replaces the <quote>onunload</quote> attribute in
+ <quote><body></quote> tags with the dummy word <literal>never</literal>.
+ Note that the <literal>i</literal> option makes the pattern matching
+ case-insensitive.
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- FILTER: fun
+ The last example is from the fun department:
+</para>
- s/microsoft(?!.com)/MicroSuck/ig
+<para>
+ <screen>
+FILTER: fun Fun text replacements
- # Buzzword Bingo:
- #
- s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></font>/ig
- </literallayout>
- </msgtext>
- </literal>
+# Spice the daily news:
+#
+s/microsoft(?!\.com)/MicroSuck/ig</screen>
</para>
<para>
- Kill those pesky little web-bugs:
+ Note the <literal>(?!\.com)</literal> part (a so-called negative lookahead)
+ in the job's pattern, which means: Don't match, if the string
+ <quote>.com</quote> appears directly following <quote>microsoft</quote>
+ in the page. This prevents links to microsoft.com from being messed, while
+ still replacing the word everywhere else.
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
- FILTER: webbugs
+ <screen>
+# Buzzword Bingo (example for extended regex syntax)
+#
+s* industry[ -]leading \
+| cutting[ -]edge \
+| award[ -]winning # Comments are OK, too! \
+| high[ -]performance \
+| solutions[ -]based \
+| unmatched \
+| unparalleled \
+| unrivalled \
+*<font color="red"><b>BINGO!</b></font> \
+*igx</screen>
+</para>
- s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1(\D[^>]*?)?>/<!-- Squished WebBug -->/sig
- </literallayout>
- </msgtext>
- </literal>
+<para>
+ The <literal>x</literal> option in this job turns on extended syntax, and allows for
+ e.g. the liberal use of (non-interpreted!) whitespace for nicer formatting.
</para>
+<para>
+ You get the idea?
+</para>
</sect2>
+</sect1>
<!-- ~ End section ~ -->
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
+<sect1 id="templates">
<title>Templates</title>
<para>
When <application>Privoxy</application> displays one of its internal
- pages, such as a 404 Not Found error page, it uses the appropriate template.
- On Linux, BSD, and Unix, these are located in
- <filename>/etc/privoxy/templates</filename> by default. These may be
- customized, if desired.
-
+ pages, such as a <ulink url="http://bogus_404_page.com">404 Not Found error page</ulink>
+ (<application>Privoxy</application> must be running for link to work as
+ intended), it uses the appropriate template. On Linux, BSD, and Unix, these
+ are located in <filename>/etc/privoxy/templates</filename> by default. These
+ may be customized, if desired. <filename>cgi-style.css</filename> is used to
+ control the HTML attributes (fonts, etc).
+</para>
+<para>
+ The default
+ <ulink
+ url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html">Blocked
+ </ulink> (<application>Privoxy</application> needs to be running for page to
+ display) banner page with the bright red top banner, is called just
+ <quote><filename>blocked</filename></quote>. This may be customized or
+ replaced with something else if desired (not recommended for the casual
+ user).
</para>
-</sect2>
</sect1>
<sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
Requests</title>
-<para>
-We value your feedback. However, to provide you with the best support,
-please note:
-
- <itemizedlist>
-
- <listitem><para>Use the <ulink url="http://sourceforge.net/tracker/?group_id=11118&atid=211118">Sourceforge support forum</ulink> to get
- help.</para></listitem>
-
- <listitem><para>Submit bugs only thru our <ulink url="http://sourceforge.net/tracker/?group_id=11118&atid=111118">Sourceforge bug
- forum</ulink>.
- </para>
- <para>
- Make sure that the bug has not already been submitted. Please try to
- verify that it is a <application>Privoxy</application> bug, and not a
- browser or site bug first. If you are using your own custom configuration,
- please try the stock configs to see if the problem is a configuration
- related bug. And if not using the latest development snapshot, please try
- the latest one. Or even better, CVS sources. Please be sure to include the
- <application>Privoxy</application>/<application>Junkbuster</application>
- version, platform, browser, any pertinent log data, any other relevant
- details (please be specific) and, if possible, some way to reproduce the
- bug.
- </para>
- </listitem>
-
- <listitem><para>Submit feature requests only thru our <ulink
- url="http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse">Sourceforge feature request forum</ulink>.</para></listitem>
-
-
- </itemizedlist>
-
-</para>
-
-<para>
-For any other issues, feel free to use the <ulink url="http://sourceforge.net/mail/?group_id=11118">mailing lists</ulink>.
-</para>
-<para>
- Anyone interested in actively participating in development and related
- discussions can join the appropriate mailing list
- <ulink url="http://sourceforge.net/mail/?group_id=11118">here</ulink>.
- Archives are available here too.
-</para>
+<!-- Include contacting.sgml boilerplate: -->
+ &contacting;
+<!-- end boilerplate -->
</sect1>
+<!-- ~ End section ~ -->
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="copyright"><title>Copyright and History</title>
-<sect2>
-<title>License</title>
-<para>
- <application>Privoxy</application> is free software; you can
- redistribute it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either version 2 of the
- License, or (at your option) any later version.
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="copyright"><title><application>Privoxy</application> Copyright, License and History</title>
-<para>
- This program is distributed in the hope that it will be useful, but WITHOUT
- ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
- FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
- details, which is available from <ulink
- url="http://www.gnu.org/copyleft/gpl.html">the Free Software Foundation,
- Inc</ulink>, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-</para>
+<!-- Include copyright.sgml: -->
+ ©right;
+<!-- end copyright -->
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2><title>License</title>
+<!-- Include copyright.sgml: -->
+ &license;
+<!-- end copyright -->
</sect2>
-
<!-- ~ End section ~ -->
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="history">
-<title>History</title>
-<para>
- <application>Privoxy</application> is evolved, and derived from,
- <application>the Internet Junkbuster</application>, with many
- improvments and enhancements over the original.
-</para>
-
-<para>
- <application>Junkbuster</application> was originally written by Anonymous
- Coders and <ulink
- url="http://www.junkbusters.com">Junkbuster's
- Corporation</ulink>, and was released as free open-source software under the
- GNU GPL. <ulink url="http://www.waldherr.org/junkbuster/">Stefan
- Waldherr</ulink> made many improvements, and started the <ulink
- url="http://sourceforge.net/projects/ijbswa/">SourceForge project
- Privoxy</ulink> to rekindle development. There are now several active
- developers contributing. The last stable release of
- <application>Junkbuster</application> was v2.0.2, which has now
- grown whiskers ;-).
-</para>
-
+<sect2 id="history"><title>History</title>
+<!-- Include history.sgml: -->
+ &history;
+<!-- end history -->
</sect2>
-
</sect1>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="seealso"><title>See also</title>
-<para>
-
- <simplelist>
- <member>
- <ulink url="http://sourceforge.net/projects/ijbswa">http://sourceforge.net/projects/ijbswa</ulink>,
- the Project Page for <application>Privoxy</application>.
- </member>
- </simplelist>
- <simplelist>
- <member>
- <ulink url="http://www.privoxy.org/">http://www.privoxy.org/</ulink>
- </member>
- </simplelist>
- <simplelist>
- <member>
- <ulink url="http://p.p/">http://p.p/</ulink>
- </member>
- </simplelist>
- <simplelist>
- <member>
- <ulink url="http://www.junkbusters.com/ht/en/cookies.html">http://www.junkbusters.com/ht/en/cookies.html</ulink>
- </member>
- </simplelist>
- <simplelist>
- <member>
- <ulink url="http://www.waldherr.org/junkbuster/">http://www.waldherr.org/junkbuster/</ulink>
- </member>
- </simplelist>
- <simplelist>
- <member>
- <ulink url="http://privacy.net/analyze/">http://privacy.net/analyze/</ulink>
- </member>
- </simplelist>
- <simplelist>
- <member>
- <ulink url="http://www.squid-cache.org/">http://www.squid-cache.org/</ulink>
- </member>
- </simplelist>
+<!-- ~ End section ~ -->
-</para>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="seealso"><title>See Also</title>
+<!-- Include seealso.sgml: -->
+ &seealso;
+<!-- end seealso -->
</sect1>
and then some examples:
</para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
<quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
times. Either/or.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
times.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
times.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
the following character should be taken literally. This is used where one of the
special characters (e.g. <quote>.</quote>) needs to be taken literally and
- not as a special meta-character.
+ not as a special meta-character. Example: <quote>example\.com</quote>, makes
+ sure the period is recognized only as a period (and not expanded to its
+ meta-character meaning of any single character).
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
- any of the enclosed characters are encountered.
+ any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
+ matches any numeric digit (zero through nine). As an example, we can combine
+ this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>()</emphasis> - parentheses are used to group a sub-expression,
or multiple sub-expressions.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>|</emphasis> - The <quote>bar</quote> character works like an
<quote>or</quote> conditional statement. A match is successful if the
- sub-expression on either side of <quote>|</quote> matches.
+ sub-expression on either side of <quote>|</quote> matches. As an example:
+ <quote>/(this|that) example/</quote> uses grouping and the bar character
+ and would match either <quote>this example</quote> or <quote>that
+ example</quote>, and nothing else.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>s/string1/string2/g</emphasis> - This is used to rewrite strings of text.
<quote>string1</quote> is replaced by <quote>string2</quote> in this
- example.
+ example. There must of course be a match on <quote>string1</quote> first.
</member>
-</simplelist>
+</simplelist></para>
<para>
These are just some of the ones you are likely to use when matching URLs with
<listitem>
<para>
- Show information about the current configuration:
+ Show information about the current configuration, including viewing and
+ editing of actions files:
</para>
<blockquote>
<para>
<listitem>
<para>
- Show the client's request headers:
+ Show the browser's request headers:
</para>
<blockquote>
<para>
</para>
</blockquote>
</listitem>
-
- <listitem>
- <para>
- Edit the actions list file:
- </para>
- <blockquote>
- <para>
- <ulink url="http://config.privoxy.org/edit-actions">http://config.privoxy.org/edit-actions</ulink>
- </para>
- </blockquote>
- </listitem>
</itemizedlist>
</para>
<para>
- These may be bookmarked for quick reference.
+ These may be bookmarked for quick reference. See next.
</para>
<sect3 id="bookmarklets">
<title>Bookmarklets</title>
<para>
- Here are some bookmarklets to allow you to easily access a
- <quote>mini</quote> version of this page. They are designed for MS Internet
- Explorer, but should work equally well in Netscape, Mozilla, and other
- browsers which support JavaScript. They are designed to run directly from
- your bookmarks - not by clicking the links below (although that will work for
- testing).
+ Below are some <quote>bookmarklets</quote> to allow you to easily access a
+ <quote>mini</quote> version of some of <application>Privoxy's</application>
+ special pages. They are designed for MS Internet Explorer, but should work
+ equally well in Netscape, Mozilla, and other browsers which support
+ JavaScript. They are designed to run directly from your bookmarks - not by
+ clicking the links below (although that should work for testing).
</para>
<para>
To save them, right-click the link and choose <quote>Add to Favorites</quote>
(IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
- Bookmarklet directly from your favourites/bookmarks. For even faster access,
+ Bookmarklet directly from your favorites/bookmarks. For even faster access,
you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
Toolbar</quote> (Netscape), and run them with a single click.
</para>
<listitem>
<para>
- <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&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>
+ <ulink
+ url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=enabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Enable</ulink>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <ulink
+ url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=disabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Disable</ulink>
</para>
</listitem>
<listitem>
<para>
- <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&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>
+ <ulink
+ url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=toggle','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Toggle Privoxy</ulink> (Toggles between enabled and disabled)
</para>
</listitem>
<listitem>
<para>
- <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&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)
+ <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());">Privoxy- View Status</ulink>
</para>
</listitem>
<listitem>
<para>
- <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>
+ <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());">Privoxy - Submit Filter Feedback</ulink>
</para>
</listitem>
</itemizedlist>
</para>
+
+
<para>
Credit: The site which gave me the general idea for these bookmarklets is
<ulink url="http://www.bookmarklets.com">www.bookmarklets.com</ulink>. They
</sect2>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="chain">
+<title>Chain of Events</title>
+<para>
+ Let's take a quick look at the basic sequence of events when a web page is
+ requested by your browser and <application>Privoxy</application> is on duty:
+</para>
+
+<para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ First, your web browser requests a web page. The browser knows to send
+ the request to <application>Privoxy</application>, which will in turn,
+ relay the request to the remote web server after passing the following
+ tests:
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>Privoxy</application> traps any request for its own internal CGI
+ pages (e.g http://p.p/) and sends the CGI page back to the browser.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Next, <application>Privoxy</application> checks to see if the URL
+ matches any <link
+ linkend="BLOCK"><quote>+block</quote></link> patterns. If
+ so, the URL is then blocked, and the remote web server will not be contacted.
+ <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>
+ is then checked and if it does not match, an
+ HTML <quote>BLOCKED</quote> page is sent back. Otherwise, if it does match,
+ an image is returned. The type of image depends on the setting of <link
+ linkend="SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></link>
+ (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Untrusted URLs are blocked. If URLs are being added to the
+ <filename>trust</filename> file, then that is done.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the URL pattern matches the <link
+ linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link> action,
+ it is then processed. Unwanted parts of the requested URL are stripped.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Now the rest of the client browser's request headers are processed. If any
+ of these match any of the relevant actions (e.g. <link
+ linkend="HIDE-USER-AGENT"><quote>+hide-user-agent</quote></link>,
+ etc.), headers are suppressed or forged as determined by these actions and
+ their parameters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Now the web server starts sending its response back (i.e. typically a web page and related
+ data).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ First, the server headers are read and processed to determine, among other
+ things, the MIME type (document type) and encoding. The headers are then
+ filtered as deterimed by the
+ <link linkend="CRUNCH-INCOMING-COOKIES"><quote>+crunch-incoming-cookies</quote></link>,
+ <link linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>,
+ and <link linkend="DOWNGRADE-HTTP-VERSION"><quote>+downgrade-http-version</quote></link>
+ actions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the <link linkend="KILL-POPUPS"><quote>+kill-popups</quote></link>
+ action applies, and it is an HTML or JavaScript document, the popup-code in the
+ response is filtered on-the-fly as it is received.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If a <link linkend="FILTER"><quote>+filter</quote></link>
+ or <link
+ linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
+ action applies (and the document type fits the action), the rest of the page is
+ read into memory (up to a configurable limit). Then the filter rules (from
+ <filename>default.filter</filename>) are processed against the buffered
+ content. Filters are applied in the order they are specified in the
+ <filename>default.filter</filename> file. Animated GIFs, if present, are
+ reduced to either the first or last frame, depending on the action
+ setting.The entire page, which is now filtered, is then sent by
+ <application>Privoxy</application> back to your browser.
+ </para>
+ <para>
+ If neither <link linkend="FILTER"><quote>+filter</quote></link>
+ or <link
+ linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
+ matches, then <application>Privoxy</application> passes the raw data through
+ to the client browser as it becomes available.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ As the browser receives the now (probably filtered) page content, it
+ reads and then requests any URLs that may be embedded within the page
+ source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
+ frames), sounds, etc. For each of these objects, the browser issues a new
+ request. And each such request is in turn processed as above. Note that a
+ complex web page may have many such embedded URLs.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+</sect2>
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="actionsanat">
<title>Anatomy of an Action</title>
<para>
- The way <application>Privoxy</application> applies <quote>actions</quote>
- and <quote>filters</quote> to any given URL can be complex, and not always so
+ The way <application>Privoxy</application> applies
+ <link linkend="ACTIONS"><quote>actions</quote></link>
+ and <link linkend="FILTER"><quote>filters</quote></link>
+ to any given URL can be complex, and not always so
easy to understand what is happening. And sometimes we need to be able to
<emphasis>see</emphasis> just what <application>Privoxy</application> is
doing. Especially, if something <application>Privoxy</application> is doing
- is causing us a problem inadvertantly. It can be a little daunting to look at
+ is causing us a problem inadvertently. It can be a little daunting to look at
the actions and filters files themselves, since they tend to be filled with
<quote>regular expressions</quote> whose consequences are not always
- so obvious. <application>Privoxy</application> provides the
+ so obvious.
+</para>
+
+<para>
+ One quick test to see if <application>Privoxy</application> is causing a problem
+ or not, is to disable it temporarily. This should be the first troubleshooting
+ step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
+ and easy way to do this (be sure to flush caches afterward!).
+</para>
+
+<para>
+ <application>Privoxy</application> also provides the
<ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
page that can show us very specifically how <application>actions</application>
are being applied to any given URL. This is a big help for troubleshooting.
- </para>
+</para>
<para>
First, enter one URL (or partial URL) at the prompt, and then
<application>Privoxy</application> will tell us
how the current configuration will handle it. This will not
- help with filtering effects from the <filename>default.filter</filename> file! It
- also will not tell you about any other URLs that may be embedded within the
- URL you are testing. For instance, images such as ads are expressed as URLs
- within the raw page source of HTML pages. So you will only get info for the
- actual URL that is pasted into the prompt area -- not any sub-URLs. If you
- want to know about embedded URLs like ads, you will have to dig those out of
- the HTML source. Use your browser's <quote>View Page Source</quote> option
- for this.
+ help with filtering effects (i.e. the <link
+ linkend="FILTER"><quote>+filter</quote></link> action) from
+ the <filename>default.filter</filename> file since this is handled very
+ differently and not so easy to trap! It also will not tell you about any other
+ URLs that may be embedded within the URL you are testing. For instance, images
+ such as ads are expressed as URLs within the raw page source of HTML pages. So
+ you will only get info for the actual URL that is pasted into the prompt area
+ -- not any sub-URLs. If you want to know about embedded URLs like ads, you
+ will have to dig those out of the HTML source. Use your browser's <quote>View
+ Page Source</quote> option for this. Or right click on the ad, and grab the
+ URL.
</para>
<para>
- Let's
look at an example, <ulink url="http://google.com">google.com</ulink>,
- one section at a time:
+ Let's
try an example, <ulink url="http://google.com">google.com</ulink>,
+ and look at it one section at a time:
</para>
<para>
<screen>
- System default actions:
-
- { -add-header -block -deanimate-gifs -downgrade -fast-redirects -filter
- -hide-forwarded -hide-from -hide-referer -hide-user-agent -image
- -image-blocker -limit-connect -no-compression -no-cookies-keep
- -no-cookies-read -no-cookies-set -no-popups -vanilla-wafer -wafer }
-
- </screen>
-</para>
-
-<para>
- This is the top section, and only tells us of the compiled in defaults. This
- is basically what <application>Privoxy</application> would do if there
- were not any <quote>actions</quote> defined, i.e. it does nothing. Every action
- is disabled. This is not particularly informative for our purposes here. OK,
- next section:
-</para>
+ Matches for http://google.com:
-<para>
- <screen>
+--- File standard ---
+(no matches in this file)
- Matches for http://google.com:
+--- File default ---
- { -add-header -block +deanimate-gifs -downgrade +fast-redirects
- +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
- +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
- +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge}
- -hide-user-agent -image +image-blocker{blank} +no-compression
- +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups
- -vanilla-wafer -wafer }
- /
+{ -add-header -block +deanimate-gifs{last} -downgrade-http-version +fast-redirects
+ -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}
+ +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}
+ +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}
+ +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}
+ -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect
+ +prevent-compression +session-cookies-only -crunch-outgoing-cookies
+ -crunch-incoming-cookies -kill-popups -send-vanilla-wafer -send-wafer }
+/
- { -no-cookies-keep -no-cookies-read -no-cookies-set }
- .google.com
+ { -session-cookies-only }
+ .google.com
{ -fast-redirects }
- .google.com
+ .google.com
- </screen>
+--- File user ---
+(no matches in this file)
+</screen>
</para>
<para>
- This is much more informative, and tells us how we have defined our
- <quote>actions</quote>, and which ones match for our example,
- <quote>google.com</quote>. The first grouping shows our default
- settings, which would apply to all URLs. If you look at your <quote>actions</quote>
- file, this would be the section just below the <quote>aliases</quote> section
- near the top. This applies to all URLs as signified by the single forward
- slash -- <quote>/</quote>.
-
+ This tells us how we have defined our
+ <link linkend="ACTIONS"><quote>actions</quote></link>, and
+ which ones match for our example, <quote>google.com</quote>. The first listing
+ is any matches for the <filename>standard.action</filename> file. No hits at
+ all here on <quote>standard</quote>. Then next is <quote>default</quote>, or
+ our <filename>default.action</filename> file. The large, multi-line listing,
+ is how the actions are set to match for all URLs, i.e. our default settings.
+ If you look at your <quote>actions</quote> file, this would be the section
+ just below the <quote>aliases</quote> section near the top. This will apply to
+ all URLs as signified by the single forward slash at the end of the listing
+ -- <quote>/</quote>.
</para>
<para>
- These are the default actions we have enabled. But we can define additional
- actions that would be exceptions to these general rules, and then list
- specific URLs that these exceptions would apply to. Last match wins.
- Just below this then are two explict matches for <quote>.google.com</quote>.
- The first is negating our various cookie blocking actions (i.e. we will allow
- cookies here). The second is allowing <quote>fast-redirects</quote>. Note
- that there is a leading dot here -- <quote>.google.com</quote>. This will
- match any hosts and sub-domains, in the google.com domain also, such as
- <quote>www.google.com</quote>. So, apparently, we have these actions defined
- somewhere in the lower part of our actions file, and
- <quote>google.com</quote> is referenced in these sections.
+ But we can define additional actions that would be exceptions to these general
+ rules, and then list specific URLs (or patterns) that these exceptions would
+ apply to. Last match wins. Just below this then are two explicit matches for
+ <quote>.google.com</quote>. The first is negating our previous cookie setting,
+ which was for <link
+ linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>
+ (i.e. not persistent). So we will allow persistent cookies for google. The
+ second turns <emphasis>off</emphasis> any
+ <link
+ linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link>
+ action, allowing this to take place unmolested. Note that there is a leading
+ dot here -- <quote>.google.com</quote>. This will match any hosts and
+ sub-domains, in the google.com domain also, such as
+ <quote>www.google.com</quote>. So, apparently, we have these two actions
+ defined somewhere in the lower part of our <filename>default.action</filename>
+ file, and <quote>google.com</quote> is referenced somewhere in these latter
+ sections.
+</para>
+<para>
+ Then, for our <filename>user.action</filename> file, we again have no hits.
</para>
<para>
- And now we pull it altogether in the bottom section and summarize how
- <application>Privoxy</application> is appying all its <quote>actions</quote>
+ And finally we pull it all together in the bottom section and summarize how
+ <application>Privoxy</application> is applying all its <quote>actions</quote>
to <quote>google.com</quote>:
</para>
<screen>
Final results:
+ -add-header -block +deanimate-gifs{last} -downgrade-http-version -fast-redirects
+ -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}
+ +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}
+ +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}
+ +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}
+ -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect
+ +prevent-compression -session-cookies-only -crunch-outgoing-cookies
+ -crunch-incoming-cookies -kill-popups -send-vanilla-wafer -send-wafer
+</screen>
+</para>
- -add-header -block -deanimate-gifs -downgrade -fast-redirects
- +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
- +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
- +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge}
- -hide-user-agent -image +image-blocker{blank} -limit-connect +no-compression
- -no-cookies-keep -no-cookies-read -no-cookies-set +no-popups -vanilla-wafer
- -wafer
-
- </screen>
+<para>
+ Notice the only difference here to the previous listing, is to
+ <quote>fast-redirects</quote> and <quote>session-cookies-only</quote>.
</para>
<para>
<para>
<screen>
- { +block +image }
+ { +block +handle-as-image }
.ad.doubleclick.net
- { +block +image }
+ { +block +handle-as-image }
ad*.
- { +block +image }
+ { +block +handle-as-image }
.doubleclick.net
-
- </screen>
+</screen>
</para>
<para>
We'll just show the interesting part here, the explicit matches. It is
- matched three different times. Each as an <quote>+block +image</quote>,
+ matched three different times. Each as an <quote>+block +handle-as-image</quote>,
which is the expanded form of one of our aliases that had been defined as:
- <quote>+imageblock</quote>. (<quote>Aliases</quote> are defined in the
- first section of the actions file and typically used to combine more
+ <quote>+imageblock</quote>. (<link
+ linkend="ALIASES"><quote>Aliases</quote></link> are defined in
+ the first section of the actions file and typically used to combine more
than one action.)
</para>
would also cover the first. No point in taking chances with these guys
though ;-) Note that if you want an ad or obnoxious
URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
- is done here -- as both a <quote>+block</quote> <emphasis>and</emphasis> an
- <quote>+image</quote>. The custom alias <quote>+imageblock</quote> does this
- for us.
+ is done here -- as both a <link
+ linkend="BLOCK"><quote>+block</quote></link>
+ <emphasis>and</emphasis> an
+ <link
+ linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>.
+ The custom alias <quote>+imageblock</quote> just simplifies the process and make
+ it more readable.
</para>
<para>
Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
- { -add-header -block +deanimate-gifs -downgrade +fast-redirects
- +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
+ { -add-header -block +deanimate-gifs -downgrade-http-version +fast-redirects
+ +filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}
+filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
- +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge}
- -hide-user-agent -image +image-blocker{blank} +no-compression
- +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups
- -vanilla-wafer -wafer }
+ +filter{fun} +hide-forwarded-for-headers +hide-from-header{block}
+ +hide-referer{forge} -hide-user-agent -handle-as-image +set-image-blocker{blank}
+ +prevent-compression +session-cookies-only -crunch-incoming-cookies
+ -crunch-outgoing-cookies +kill-popups -send-vanilla-wafer -send-wafer }
/
- { +block +image }
+ { +block +handle-as-image }
/ads
-
- </screen>
+</screen>
</para>
<para>
Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote>! But
we did not want this at all! Now we see why we get the blank page. We could
- now add a new action below this that explictly does <emphasis>not</emphasis>
- block (-block) pages with <quote>adsl</quote>. There are various ways to
- handle such exceptions. Example:
+ now add a new action below this that explicitly does <emphasis>not</emphasis>
+ block (<quote>{-block}</quote>) paths with <quote>adsl</quote>. There are
+ various ways to handle such exceptions. Example:
</para>
<para>
{ -block }
/adsl
-
- </screen>
+</screen>
</para>
<para>
- Now the page displays ;-)
-
+ Now the page displays ;-) Be sure to flush your browser's caches when
+ making such changes. Or, try using <literal>Shift+Reload</literal>.
</para>
<para>
But now what about a situation where we get no explicit matches like
we did with:
-
</para>
<para>
<screen>
- { -block }
- /adsl
-
- </screen>
+ { +block +handle-as-image }
+ /ads
+</screen>
</para>
<para>
.jungle.com
.scan.co.uk
.forbes.com
-
- </screen>
+</screen>
</para>
<para>
<quote>{shop}</quote> is an <quote>alias</quote> that expands to
- <quote>{ -filter -no-cookies -no-cookies-keep }</quote>. Or you could do
- your own exception to negate filtering:
+ <quote>{ -filter -session-cookies-only }</quote>.
+ Or you could do your own exception to negate filtering:
</para>
{-filter}
.forbes.com
-
- </screen>
+</screen>
+</para>
+
+<para>
+ This would probably be most appropriately put in <filename>user.action</filename>,
+ for local site exceptions.
+</para>
+
+<para>
+ <quote>{fragile}</quote> is an alias that disables most actions. This can be
+ used as a last resort for problem sites. Remember to flush caches! If this
+ still does not work, you will have to go through the remaining actions one by
+ one to find which one(s) is causing the problem.
</para>
</sect2>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: user-manual.sgml,v $
+ Revision 1.114 2002/05/16 09:42:50 oes
+ More ulink->link, added some hints to Quickstart section
+
+ Revision 1.113 2002/05/15 21:07:25 oes
+ Extended and further commented the example actions files
+
+ Revision 1.112 2002/05/15 03:57:14 hal9
+ Spell check. A few minor edits here and there for better syntax and
+ clarification.
+
+ Revision 1.111 2002/05/14 23:01:36 oes
+ Fixing the fixes
+
+ Revision 1.110 2002/05/14 19:10:45 oes
+ Restored alphabetical order of actions
+
+ Revision 1.109 2002/05/14 17:23:11 oes
+ Renamed the prevent-*-cookies actions, extended aliases section and moved it before the example AFs
+
+ Revision 1.108 2002/05/14 15:29:12 oes
+ Completed proofreading the actions chapter
+
+ Revision 1.107 2002/05/12 03:20:41 hal9
+ Small clarifications for 127.0.0.1 vs localhost for listen-address since this
+ apparently an important distinction for some OS's.
+
+ Revision 1.106 2002/05/10 01:48:20 hal9
+ This is mostly proposed copyright/licensing additions and changes. Docs
+ are still GPL, but licensing and copyright are more visible. Also, copyright
+ changed in doc header comments (eliminate references to JB except FAQ).
+
+ Revision 1.105 2002/05/05 20:26:02 hal9
+ Sorting out license vs copyright in these docs.
+
+ Revision 1.104 2002/05/04 08:44:45 swa
+ bumped version
+
+ Revision 1.103 2002/05/04 00:40:53 hal9
+ -Remove the TOC first page kludge. It's fixed proper now in ldp.dsl.in.
+ -Some minor additions to Quickstart.
+
+ Revision 1.102 2002/05/03 17:46:00 oes
+ Further proofread & reactivated short build instructions
+
+ Revision 1.101 2002/05/03 03:58:30 hal9
+ Move the user-manual config directive to top of section. Add note about
+ Privoxy needing read permissions for configs, and write for logs.
+
+ Revision 1.100 2002/04/29 03:05:55 hal9
+ Add clarification on differences of new actions files.
+
+ Revision 1.99 2002/04/28 16:59:05 swa
+ more structure in starting section
+
+ Revision 1.98 2002/04/28 05:43:59 hal9
+ This is the break up of configuration.html into multiple files. This
+ will probably break links elsewhere :(
+
+ Revision 1.97 2002/04/27 21:04:42 hal9
+ -Rewrite of Actions File example.
+ -Add section for user-manual directive in config.
+
+ Revision 1.96 2002/04/27 05:32:00 hal9
+ -Add short section to Filter Files to tie in with +filter action.
+ -Start rewrite of examples in Actions Examples (not finished).
+
+ Revision 1.95 2002/04/26 17:23:29 swa
+ bookmarks cleaned, changed structure of user manual, screen and programlisting cleanups, and numerous other changes that I forgot
+
+ Revision 1.94 2002/04/26 05:24:36 hal9
+ -Add most of Andreas suggestions to Chain of Events section.
+ -A few other minor corrections and touch up.
+
+ Revision 1.92 2002/04/25 18:55:13 hal9
+ More catchups on new actions files, and new actions names.
+ Other assorted cleanups, and minor modifications.
+
+ Revision 1.91 2002/04/24 02:39:31 hal9
+ Add 'Chain of Events' section.
+
+ Revision 1.90 2002/04/23 21:41:25 hal9
+ Linuxconf is deprecated on RH, substitute chkconfig.
+
+ Revision 1.89 2002/04/23 21:05:28 oes
+ Added hint for startup on Red Hat
+
+ Revision 1.88 2002/04/23 05:37:54 hal9
+ Add AmigaOS install stuff.
+
+ Revision 1.87 2002/04/23 02:53:15 david__schmidt
+ Updated OSX installation section
+ Added a few English tweaks here an there
+
+ Revision 1.86 2002/04/21 01:46:32 hal9
+ Re-write actions section.
+
+ Revision 1.85 2002/04/18 21:23:23 hal9
+ Fix ugly typo (mine).
+
+ Revision 1.84 2002/04/18 21:17:13 hal9
+ Spell Redhat correctly (ie Red Hat). A few minor grammar corrections.
+
+ Revision 1.83 2002/04/18 18:21:12 oes
+ Added RPM install detail
+
+ Revision 1.82 2002/04/18 12:04:50 oes
+ Cosmetics
+
+ Revision 1.81 2002/04/18 11:50:24 oes
+ Extended Install section - needs fixing by packagers
+
+ Revision 1.80 2002/04/18 10:45:19 oes
+ Moved text to buildsource.sgml, renamed some filters, details
+
+ Revision 1.79 2002/04/18 03:18:06 hal9
+ Spellcheck, and minor touchups.
+
+ Revision 1.78 2002/04/17 18:04:16 oes
+ Proofreading part 2
+
+ Revision 1.77 2002/04/17 13:51:23 oes
+ Proofreading, part one
+
+ Revision 1.76 2002/04/16 04:25:51 hal9
+ -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
+ -Note about proxy may need requests to re-read config files.
+
+ Revision 1.75 2002/04/12 02:08:48 david__schmidt
+ Remove OS/2 building info... it is already in the developer-manual
+
+ Revision 1.74 2002/04/11 00:54:38 hal9
+ Add small section on submitting actions.
+
+ Revision 1.73 2002/04/10 18:45:15 swa
+ generated
+
+ Revision 1.72 2002/04/10 04:06:19 hal9
+ Added actions feedback to Bookmarklets section
+
+ Revision 1.71 2002/04/08 22:59:26 hal9
+ Version update. Spell chkconfig correctly :)
+
+ Revision 1.70 2002/04/08 20:53:56 swa
+ ?
+
+ Revision 1.69 2002/04/06 05:07:29 hal9
+ -Add privoxy-man-page.sgml, for man page.
+ -Add authors.sgml for AUTHORS (and p-authors.sgml)
+ -Reworked various aspects of various docs.
+ -Added additional comments to sub-docs.
+
+ Revision 1.68 2002/04/04 18:46:47 swa
+ consistent look. reuse of copyright, history et. al.
+
+ Revision 1.67 2002/04/04 17:27:57 swa
+ more single file to be included at multiple points. make maintaining easier
+
+ Revision 1.66 2002/04/04 06:48:37 hal9
+ Structural changes to allow for conditional inclusion/exclusion of content
+ based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
+ definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
+ eventually be set by Makefile.
+ More boilerplate text for use across multiple docs.
+
+ Revision 1.65 2002/04/03 19:52:07 swa
+ enhance squid section due to user suggestion
+
+ Revision 1.64 2002/04/03 03:53:43 hal9
+ A few minor bug fixes, and touch ups. Ready for review.
+
+ Revision 1.63 2002/04/01 16:24:49 hal9
+ Define entities to include boilerplate text. See doc/source/*.
+
Revision 1.62 2002/03/30 04:15:53 hal9
- Fix privoxy.org/config links.
- Paste in Bookmarklets from Toggle page.
projects / privoxy.git / blobdiff