<!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 contacting SYSTEM "contacting.sgml">
<!entity history SYSTEM "history.sgml">
<!entity copyright SYSTEM "copyright.sgml">
-<!entity p-version "2.9.14">
-<!entity p-status "beta">
-<!entity % p-not-stable "INCLUDE">
-<!entity % p-stable "IGNORE">
+<!entity license SYSTEM "license.sgml">
+<!entity p-authors SYSTEM "p-authors.sgml">
+<!entity config SYSTEM "p-config.sgml">
+<!entity p-version "3.0.7">
+<!entity p-status "stable">
+<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
+<!entity % p-not-stable "IGNORE">
+<!entity % p-stable "INCLUDE">
<!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 % user-man "IGNORE">
+<!entity % config-file "IGNORE">
<!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml -->
+<!entity my-copy "©"> <!-- kludge for docbook2man -->
+<!entity % draft "IGNORE"> <!-- WIP stuff -->
+<!entity my-app "<application>Privoxy</application>">
]>
<!--
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.78 2002/04/17 18:04:16 oes Exp $
- Written by and Copyright (C) 2001 the SourceForge
- Privoxy team. http://www.privoxy.org/
-
- Based on the Internet Junkbuster originally written
- by and Copyright (C) 1997 Anonymous Coders and
- Junkbusters Corporation. http://www.junkbusters.com
+ $Id: user-manual.sgml,v 2.31 2007/06/02 14:01:37 fabiankeil Exp $
+ Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/
+ See LICENSE.
========================================================================
NOTE: Please read developer-manual/documentation.html before touching
<article id="index">
<artheader>
-<title>Privoxy User Manual</title>
-<pubdate>$Id: user-manual.sgml,v 1.78 2002/04/17 18:04:16 oes Exp $</pubdate>
+<title>Privoxy &p-version; User Manual</title>
+
+<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 - 2007 by
+ <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
+ </subscript>
+</pubdate>
+
+<pubdate>$Id: user-manual.sgml,v 2.31 2007/06/02 14:01:37 fabiankeil 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.
+
+
+-->
-<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
- <ulink
- url="http://www.privoxy.org/"><application>Privoxy</application></ulink>.
- </para>
+ The <citetitle>Privoxy User Manual</citetitle> gives users information on how to
+
install, configure and use <ulink
+ url="http://www.privoxy.org/">Privoxy</ulink>.
+ </para>
<!-- Include privoxy.sgml boilerplate: -->
&p-intro;
<!-- end privoxy.sgml -->
<para>
- You can find the latest version of the
user manual at <ulink
+ You can find the latest version of the
<citetitle>Privoxy User Manual</citetitle> 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
+ Please see the <link linkend="contact">Contact section</link> on how to
contact the developers.
- </para>
+ </para>
<!-- <para> -->
<!-- Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
</artheader>
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="intro" label=""><title></title>
-<!-- dummy section to force TOC on page by itself -->
-<!-- DO NOT REMOVE! please ;) -->
-<para> </para>
-</sect1>
-
-<!-- ~~~~~ New section ~~~~~ -->
-
<sect1 label="1" id="introduction"><title>Introduction</title>
-
<para>
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> ;-)]]>.
+ configuration files. Development of a new version is currently nearing
+ completion, and includes significant changes and enhancements over
+ earlier versions. ]]>.
</para>
-<![%p-not-stable;[
<!-- include only in non-stable versions -->
+<![%p-not-stable;[
<para>
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
]]>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="newfeatures">
-<title>New Features</title>
+<sect2 id="features"><title>Features</title>
<para>
- In addition to <application>Internet Junkbuster's</application> traditional
- features of ad and banner blocking and cookie management,
- <application>Privoxy</application> provides new features<![%p-not-stable;[,
- some of them currently under development]]>:
-<anchor id="testing"/>
+ In addition to the core
+ features of ad blocking and
+ <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> management,
+ <application>Privoxy</application> provides many supplemental
+ features<![%p-not-stable;[, some of them currently under development]]>,
+ that give the end-user more control, more privacy and more freedom:
</para>
-
<!-- Include newfeatures.sgml boilerplate here: -->
&newfeatures;
<!-- end boilerplate -->
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="installation"><title>Installation</title>
+
<para>
<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>.
+ <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project
+ Page</ulink>.
</para>
+
<para>
- 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>
+ Note:
+ On some platforms, the installer may remove previously installed versions, if
+ found. (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>
-<!-- Include supported.sgml boilerplate -->
- &supported;
-<!-- end boilerplate -->
-
-<!-- ~~~~~ New section ~~~~~ -->
+<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="installation-packages"><title>Binary Packages</title>
<para>
- Binary packages can be downloaded from our <ulink
- url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink>.
+How to install the binary packages depends on your operating system:
</para>
+<!-- XXX: The installation sections should be sorted -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-pack-rpm"><title>Red Hat and Fedora RPMs</title>
+
<para>
- How to install them depends on your operating system:
+ 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>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-pack-rpm"><title>Redhat and SuSE RPMs</title>
+<para>
+ 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.
+</para>
<para>
- RPMs can be installed with <literal>rpm -Uvh <name-of-rpm.rpm></literal>,
- and will use <filename>/etc/privoxy</filename> for configuration files.
+ 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>
-
Note that if you have a <application>Junkbuster</application> RPM installed
+
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 if found, before installing <application>Privoxy</application>.
</para>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, HP-UX</title>
-
+<sect3 id="installation-deb"><title>Debian</title>
<para>
- 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.
+ DEBs can be installed with <literal>apt-get install privoxy</literal>,
+ and will use <filename>/etc/privoxy</filename> for the location of
+ configuration files.
</para>
</sect3>
<para>
Just double-click the installer, which will guide you through
- the installation process.
+ the installation process. You will find the configuration files
+ in the same directory as you installed <application>Privoxy</application> in.
+</para>
+<para>
+ Version 3.0.4 introduced full <application>Windows</application> service
+ functionality. On Windows only, the <application>Privoxy</application>
+ program has two new command line arguments to install and uninstall
+ <application>Privoxy</application> as a <emphasis>service</emphasis>.
+</para>
+ <variablelist>
+ <varlistentry>
+ <term>Arguments:</term>
+ <listitem>
+ <para>
+ <replaceable class="parameter">--install</replaceable>[:<replaceable class="parameter">service_name</replaceable>]
+ </para>
+ <para>
+ <replaceable class="parameter">--uninstall</replaceable>[:<replaceable class="parameter">service_name</replaceable>]
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ After invoking <application>Privoxy</application> with
+ <command>--install</command>, you will need to bring up the
+ <application>Windows</application> service console to assign the user you
+ want <application>Privoxy</application> to run under, and whether or not you
+ want it to run whenever the system starts. You can start the
+ <application>Windows</application> services console with the following
+ command: <command>services.msc</command>. If you do not take the manual step
+ of modifying <application>Privoxy's</application> service settings, it will
+ not start. Note too that you will need to give Privoxy a user account that
+ actually exists, or it will not be permitted to
+ write to its log and configuration files.
+</para>
+
+</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, HP-UX</title>
+
+<para>
+ 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, more info needed? -->
</para>
</sect3>
<sect3 id="installation-os2"><title>OS/2</title>
<para>
- Just double-click the WarpIN self-installing archive, which will guide
- you through the installation process. A shadow of the
+ First, make sure that no previous installations of
+ <application>Junkbuster</application> and / or
+ <application>Privoxy</application> are left on your
+ system. Check that no <application>Junkbuster</application>
+ or <application>Privoxy</application> objects are in
+ your startup folder.
+
+</para>
+
+<para>
+ 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>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-deb"><title>Debian</title>
+<sect3 id="installation-mac"><title>Mac OSX</title>
<para>
- FIXME.
+ Unzip the downloaded file (you can either double-click on the file
+ from the finder, or from the desktop if you downloaded it there).
+ Then, double-click on the package installer icon named
+ <literal>Privoxy.pkg</literal>
+ and follow the installation process.
+ <application>Privoxy</application> will be installed in the folder
+ <literal>/Library/Privoxy</literal>.
+ It will start automatically whenever you start up. To prevent it from
+ starting automatically, remove or rename the folder
+ <literal>/Library/StartupItems/Privoxy</literal>.
+</para>
+<para>
+ To start Privoxy by hand, double-click on
+ <literal>StartPrivoxy.command</literal> in the
+ <literal>/Library/Privoxy</literal> folder.
+ Or, type this command in the Terminal:
+</para>
+<para>
+ <screen>
+ /Library/Privoxy/StartPrivoxy.command
+ </screen>
+</para>
+<para>
+ You will be prompted for the administrator password.
</para>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 id="installation-amiga"><title>AmigaOS</title>
<para>
- Unpack the <literal>.lha</literal> archive, then FIXME.
+ 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>
+</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-tbz"><title>FreeBSD</title>
+
+<para>
+ Privoxy is part of FreeBSD's Ports Collection, you can build and install
+ it with <literal>cd /usr/ports/www/privoxy; make install clean</literal>.
+</para>
+<para>
+ If you don't use the ports, you can fetch and install
+ the package with <literal>pkg_add -r privoxy</literal>.
+</para>
+<para>
+ The port skeleton and the package can also be downloaded from the
+ <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">File Release
+ Page</ulink>, but if you're interested in stable releases only you don't
+ gain anything by using them.
</para>
</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installattion-gentoo"><title>Gentoo</title>
+<para>
+ Gentoo source packages (Ebuilds) for <application>Privoxy</application> are
+ contained in the Gentoo Portage Tree (they are not on the download page,
+ but there is a Gentoo section, where you can see when a new
+ <application>Privoxy</application> Version is added to the Portage Tree).
+</para>
+<para>
+ Before installing <application>Privoxy</application> under Gentoo just do
+ first <literal>emerge rsync</literal> to get the latest changes from the
+ Portage tree. With <literal>emerge privoxy</literal> you install the latest
+ version.
+</para>
+<para>
+ Configuration files are in <filename>/etc/privoxy</filename>, the
+ documentation is in <filename>/usr/share/doc/privoxy-&p-version;</filename>
+ and the Log directory is in <filename>/var/log/privoxy</filename>.
+</para>
+</sect3>
+
</sect2>
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="installation-source"><title>Building from Source</title>
+<para>
+ The most convenient way to obtain the <application>Privoxy</application> sources
+ is to download the source tarball from our
+ <ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118&package_id=10571">project download
+ page</ulink>.
+</para>
+
+<para>
+ 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>.
+<!--
+ deprecated...out of business.
+ or simply download <ulink
+ url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.bz2">the nightly CVS
+ tarball.</ulink>
+-->
+</para>
+
<!-- include buildsource.sgml boilerplate: -->
&buildsource;
<!-- end boilerplate -->
+</sect2>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="installation-keepupdated"><title>Keeping your Installation Up-to-Date</title>
+<para>
+ As user feedback comes in and development continues, we will make updated versions
+ of both the main <link linkend="actions-file">actions file</link> (as a <ulink
+ url="http://sourceforge.net/project/showfiles.php?group_id=11118&release_id=103670">separate
+ package</ulink>) and the software itself (including the actions file) available for
+ download.
+</para>
+
+<para>
+ If you wish to receive an email notification whenever we release updates of
+ <application>Privoxy</application> or the actions file, <ulink
+ url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce/">subscribe
+ to our announce mailing list</ulink>, ijbswa-announce@lists.sourceforge.net.
+</para>
+
<para>
- For more detailed instructions, on how to build Redhat and SuSE RPMs,
- Windows self-extracting installers etc, and for building from CVS sources,
- please consult the <ulink url="../developer-manual/newrelease.html">developer
- manual</ulink>.
+ In order not to lose your personal changes and adjustments when updating
+ to the latest <literal>default.action</literal> file we <emphasis>strongly
+ recommend</emphasis> that you use <literal>user.action</literal> and
+ <literal>user.filter</literal> for your local
+ customizations of <application>Privoxy</application>. See the <link
+ linkend="actions-file">Chapter on actions files</link> for details.
</para>
+
</sect2>
+
</sect1>
<!-- ~ End section ~ -->
-
<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="whatsnew">
+<title>What's New in this Release</title>
+<para>
+ There are many improvements and new features since <application>Privoxy 3.0.6</application>, the last stable release:
+</para>
+
+<para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Header filtering can be done with dedicated header filters now. As a result
+ the actions <quote>filter-client-headers</quote> and <quote>filter-server-headers</quote>
+ that were introduced with <application>Privoxy 3.0.5</application> to apply
+ the content filters to the headers as, well have been removed again.
+ </para>
+ </listitem>
+
+<!-- pre-3.0.6 changes:
+ <listitem>
+ <para>
+ There are a number of new <link linkend="actions-file">actions</link>:
+ </para>
+
+ <para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal><link linkend="content-type-overwrite">content-type-overwrite</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="crunch-client-header">crunch-client-header</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="crunch-server-header">crunch-server-header</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="filter-client-headers">filter-client-headers</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="filter-server-headers">filter-server-headers</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="force-text-mode">force-text-mode</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="handle-as-empty-document">handle-as-empty-document</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="hide-accept-language">hide-accept-language</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="hide-content-disposition">hide-content-disposition</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="inspect-jpegs">inspect-jpegs</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="redirect">redirect</link></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><link linkend="treat-forbidden-connects-like-blocks">treat-forbidden-connects-like-blocks</link></literal>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ <para>
+ In addition, <literal><link linkend="fast-redirects">fast-redirects</link></literal>
+ has been significantly improved with enhanced syntax.
+ </para>
+ <para>
+ And <literal><link linkend="hide-referrer">hide-referrer</link></literal>
+ has a new option, <literal>conditional block</literal>.
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>
+ <application>MS-Windows</application> versions can now be
+ <link
+ linkend="installation-pack-win">installed and
+ started as a <emphasis>Windows service</emphasis></link>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename>config</filename> has two new options:
+ <link
+ linkend="enable-remote-http-toggle">enable-remote-http-toggle</link>,
+ and <link
+ linkend="forwarded-connect-retries">forwarded-connect-retries</link>.
+ </para>
+ <para>
+ And there is improved handling of the <link
+ linkend="user-manual">user-manual</link>
+ option, for placing documentation and help files on the local system.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ There are six new <link linkend="FILTER">filters</link>.
+ </para>
+ </listitem>
-<sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
+ <listitem>
+ <para>
+ Actions files problems and suggestions are now being directed to:
+ <ulink url="http://sourceforge.net/tracker/?group_id=11118&atid=460288">http://sourceforge.net/tracker/?group_id=11118&atid=460288</ulink>.
+ Please use this to report such configuration related problems as missed
+ ads, sites that don't function properly due to one action or another,
+ innocent images being blocked, etc.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ In addition, there are numerous bug fixes and significant enhancements,
+ including error pages should no longer be cached if the problem is fixed,
+ much better DNS error handling, various logging improvements, and
+ configuration updates for better ad blocking and junk elimination.
+ </para>
+ </listitem>
+-->
+ </itemizedlist>
+</para>
<!-- ~~~~~ New section ~~~~~ -->
+
<sect2 id="upgradersnote">
<title>Note to Upgraders</title>
+
<para>
- There are very significant changes from older versions of
- <application>Junkbuster</application> to the current
- <application>Privoxy</application>. Configuration is substantially
- changed. <application>Junkbuster 2.0.x</application> and earlier
- configuration files will not migrate. The functionality of the old
- <filename>blockfile</filename>, <filename>cookiefile</filename> and
- <filename>imagelist</filename>, are now combined into the
- <quote>actions file</quote> (<filename>default.action</filename>
- for most installations).
-</para>
-<para>
- A <quote>filter file</quote> (typically <filename>default.filter</filename>)
- is new with <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 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 file, 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>
- A quick list of things to be aware of before upgrading:
+ A quick list of things to be aware of before upgrading from earlier
+ versions of <application>Privoxy</application>:
</para>
<para>
<itemizedlist>
<listitem>
- <para>
- The default listening port is now 8118 due to a conflict with another
- service (NAS).
+ <para>
+ Some installers may remove earlier versions completely, including
+ configuration files. Save any important configuration files!
</para>
- </listitem>
+ </listitem>
<listitem>
<para>
- Some installers may remove earlier versions completely. Save any
- important configuration files!
+ On the other hand, other installers may not overwrite any existing configuration
+ files, thinking you will want to do that. You may want to manually check
+ your saved files against the newer versions to see if the improvements have
+ merit, or whether there are new options that you may want to consider.
+ There are a number of new features, but most won't be available unless
+ these features are incorporated into your configuration somehow.
</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>
+ <para>
+ See the full documentation on
+ <literal><link linkend="fast-redirects">fast-redirects</link></literal>
+ which has changed syntax, and will require adjustments to local configs,
+ such as <filename>user.action</filename>. You must reference the new
+ syntax:
+ </para>
+ <para>
+ <screen>
+ { +fast-redirects{check-decoded-url} }
+ .example.com
+ mybank.com
+ .google.</screen>
+</para>
+
+ </listitem>
<listitem>
+ <para>
+ The <filename>jarfile</filename>,
+ <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> logger, is off by default now.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ What constitutes a <quote>default</quote> configuration has changed,
+ and you may want to review which actions are <quote>on</quote> by
+ default. This is primarily a matter of emphasis, but some features
+ you may have been used to, may now be <quote>off</quote> by default.
+ There are also a number of new actions and filters you may want to
+ consider, most of which are not fully incorporated into the default
+ settings as yet (see above).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The default actions setting is now <literal>Cautious</literal>. Previous
+ releases had a default setting of <literal>Medium</literal>. Experienced
+ users may want to adjust this, as it is fairly conservative by &my-app;
+ standards and past practices. See <ulink
+ url="http://config.privoxy.org/edit-actions-list?f=default">
+ http://config.privoxy.org/edit-actions-list?f=default</ulink>. New users
+ should try the default settings for a while before turning up the volume.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The default setting has filtering turned <emphasis>off</emphasis>, which
+ subsequently means that compression is <emphasis>on</emphasis>. Remember
+ that filtering does not work on compressed pages, so if you use, or want to
+ use, filtering, you will need to force compression off. Example:
+ </para>
+ <para>
+ <screen>
+ { +<link linkend="filter">filter</link>{google} +<link linkend="prevent-compression">prevent-compression</link> }
+ .google.</screen>
+ </para>
+ <para>
+ Or if you use a number of filters, or filter many sites, you may just want
+ to turn off compression for all sites in
+ <filename>default.action</filename> (or
+ <filename>user.action</filename>).
+ </para>
+
+ </listitem>
+
+ <listitem>
<para>
- The primary configuration file for cookie management, ad and banner
- blocking, and many other aspects of <application>Privoxy</application>
- configuration is <filename>default.action</filename>. It is strongly
- recommended to become familiar with the new actions concept below,
- before modifying this file.
+ Also, <link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> is
+ off by default now. If you've liked this feature in the past, you may want
+ to turn it back on in <filename>user.action</filename> now.
</para>
- </listitem>
+ </listitem>
+
+
<listitem>
<para>
<!-- I think it is best to keep this somewhat vague, in case -->
</para>
</listitem>
+
</itemizedlist>
</para>
-
</sect2>
+</sect1>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="startup">
-<title>Starting <application>Privoxy</application></title>
+<sect1 id="quickstart"><title>Quickstart to Using Privoxy</title>
<para>
- 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 localhost for the proxy address,
- and port 8118 (earlier versions used port 8000). This is the one required
- configuration 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 ->
- 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.
-</para>
+ <itemizedlist>
-<para>
- After doing this, flush your browser's disk and memory caches to force a
- 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>.
-</para>
+ <listitem>
+ <para>
+ Install <application>Privoxy</application>. See the <link
+ linkend="installation">Installation Section</link> below for platform specific
+ information.
+ </para>
+ </listitem>
+ <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. These are
+ off by default.
+ </para>
+ </listitem>
-<para>
- <application>Privoxy</application> is typically started by specifying the
- main configuration file to be used on the command line. Example Unix startup
- command:
-</para>
+ <listitem>
+ <para>
+ Start <application>Privoxy</application>, if the installation program has
+ not done this already (may vary according to platform). See the section
+ <link linkend="startup">Starting <application>Privoxy</application></link>.
+ </para>
+ </listitem>
-<para>
- <screen>
-
- # /usr/sbin/privoxy /etc/privoxy/config
-
- </screen>
-</para>
+ <listitem>
+ <para>
+ Set your browser to use <application>Privoxy</application> as HTTP and
+ HTTPS (SSL) <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>
+ by setting the proxy configuration for address of
+ <literal>127.0.0.1</literal> and port <literal>8118</literal>.
+ <emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or
+ any protocols besides HTTP and HTTPS (SSL)! It won't work!
+ </para>
+ </listitem>
-<para>
- An init script is provided for SuSE and Redhat.
-</para>
+ <listitem>
+ <para>
+ Flush your browser's disk and memory caches, to remove any cached ad images.
+ If using <application>Privoxy</application> to manage
+ <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
+ you should remove any currently stored cookies too.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A default installation should provide a reasonable starting point for
+ most. There will undoubtedly be occasions where you will want to adjust the
+ configuration, but that can be dealt with as the need arises. Little
+ to no initial configuration is required in most cases.
+ </para>
+ <para>
+ See the <link linkend="configuration">Configuration section</link> for more
+ configuration options, and how to customize your installation.
+ You might also want to look at the <link
+ linkend="quickstart-ad-blocking">next section</link> for a quick
+ introduction to how <application>Privoxy</application> blocks ads and
+ banners.
+</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you experience ads that slip through, innocent images that are
+ blocked, or otherwise feel the need to fine-tune
+ <application>Privoxy's</application> behavior, 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">Troubleshooting: Anatomy of an
+ Action</link></quote> has hints on how to understand and debug actions that
+ <quote>misbehave</quote>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ For easy access to &my-app;'s most important controls, drag the provided
+ <link linkend="bookmarklets">Bookmarklets</link> into your browser's
+ personal toolbar.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Please see the section <link linkend="contact">Contacting the
+ Developers</link> on how to report bugs, problems with websites or to get
+ help.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Now enjoy surfing with enhanced control, comfort and privacy!
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="quickstart-ad-blocking">
+<title>Quickstart to Ad Blocking</title>
+<!--
+ NOTE: This section is deliberately redundant for those that don't
+ want to read the whole thing (which is getting lengthy).
+-->
+<para>
+ Ad blocking is but one of <application>Privoxy's</application>
+ array of features. Many of these features are for the technically minded advanced
+ user. But, ad and banner blocking is surely common ground for everybody.
+</para>
+<para>
+ This section will provide a quick summary of ad blocking so
+ you can get up to speed quickly without having to read the more extensive
+ information provided below, though this is highly recommended.
+</para>
+<para>
+ First a bit of a warning ... blocking ads is much like blocking SPAM: the
+ more aggressive you are about it, the more likely you are to block
+ things that were not intended. And the more likely that some things
+ may not work as intended. So there is a trade off here. If you want
+ extreme ad free browsing, be prepared to deal with more
+ <quote>problem</quote> sites, and to spend more time adjusting the
+ configuration to solve these unintended consequences. In short, there is
+ not an easy way to eliminate <emphasis>all</emphasis> ads. Either take
+ the easy way and settle for <emphasis>most</emphasis> ads blocked with the
+ default configuration, or jump in and tweak it for your personal surfing
+ habits and preferences.
+</para>
+<para>
+ Secondly, a brief explanation of <application>Privoxy's </application>
+ <quote>actions</quote>. <quote>Actions</quote> in this context, are
+ the directives we use to tell <application>Privoxy</application> to perform
+ some task relating to WWW transactions (i.e. web browsing). We tell
+ <application>Privoxy</application> to take some <quote>action</quote>. Each
+ action has a unique name and function. While there are many potential
+ <application>actions</application> in <application>Privoxy's</application>
+ arsenal, only a few are used for ad blocking. <link
+ linkend="actions">Actions</link>, and <link linkend="actions-file">action
+ configuration files</link>, are explained in depth below.
+</para>
+<para>
+ Actions are specified in <application>Privoxy's</application> configuration,
+ followed by one or more URLs to which the action should apply. URLs
+ can actually be URL type <link linkend="af-patterns">patterns</link> that use
+ wildcards so they can apply potentially to a range of similar URLs. The
+ actions, together with the URL patterns are called a section.
+</para>
+<para>
+ When you connect to a website, the full URL will either match one or more
+ of the sections as defined in <application>Privoxy's</application> configuration,
+ or not. If so, then <application>Privoxy</application> will perform the
+ respective actions. If not, then nothing special happens. Furthermore, web
+ pages may contain embedded, secondary URLs that your web browser will
+ use to load additional components of the page, as it parses the
+ original page's HTML content. An ad image for instance, is just an URL
+ embedded in the page somewhere. The image itself may be on the same server,
+ or a server somewhere else on the Internet. Complex web pages will have many
+ such embedded URLs. &my-app; can deal with each URL individually, so, for
+ instance, the main page text is not touched, but images from such-and-such
+ server are blocked.
+</para>
+
+<para>
+ The most important actions for basic ad blocking are: <literal><link
+ linkend="block">block</link></literal>, <literal><link
+ linkend="handle-as-image">handle-as-image</link></literal>,
+ <literal><link
+ linkend="handle-as-empty-document">handle-as-empty-document</link></literal>,and
+ <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>:
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal><link linkend="block">block</link></literal> - this is perhaps
+ the single most used action, and is particularly important for ad blocking.
+ This action stops any contact between your browser and any URL patterns
+ that match this action's configuration. It can be used for blocking ads,
+ but also anything that is determined to be unwanted. By itself, it simply
+ stops any communication with the remote server and sends
+ <application>Privoxy</application>'s own built-in BLOCKED page instead to
+ let you now what has happened (with some exceptions, see below).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal><link linkend="handle-as-image">handle-as-image</link></literal> -
+ tells <application>Privoxy</application> to treat this URL as an image.
+ <application>Privoxy</application>'s default configuration already does this
+ for all common image types (e.g. GIF), but there are many situations where this
+ is not so easy to determine. So we'll force it in these cases. This is particularly
+ important for ad blocking, since only if we know that it's an image of
+ some kind, can we replace it with an image of our choosing, instead of the
+ <application>Privoxy</application> BLOCKED page (which would only result in
+ a <quote>broken image</quote> icon). There are some limitations to this
+ though. For instance, you can't just brute-force an image substitution for
+ an entire HTML page in most situations.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal><link linkend="handle-as-empty-document">handle-as-empty-document</link></literal> -
+ sends an empty document instead of <application>Privoxy's</application>
+ normal BLOCKED HTML page. This is useful for file types that are neither
+ HTML nor images, such as blocking JavaScript files.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal><link
+ linkend="set-image-blocker">set-image-blocker</link></literal> - tells
+ <application>Privoxy</application> what to display in place of an ad image that
+ has hit a block rule. For this to come into play, the URL must match a
+ <literal><link linkend="block">block</link></literal> action somewhere in the
+ configuration, <emphasis>and</emphasis>, it must also match an
+ <literal><link linkend="handle-as-image">handle-as-image</link></literal> action.
+ </para>
+ <para>
+ The configuration options on what to display instead of the ad are:
+ </para>
+ <simplelist>
+ <member>
+ <emphasis>pattern</emphasis> - a checkerboard pattern, so that an ad
+ replacement is obvious. This is the default.
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>blank</emphasis> - A very small empty GIF image is displayed.
+ This is the so-called <quote>invisible</quote> configuration option.
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>http://<URL></emphasis> - A redirect to any image anywhere
+ of the user's choosing (advanced usage).
+ </member>
+ </simplelist>
+ </listitem>
+
+</itemizedlist>
+</para>
+
+<para>
+ The quickest way to adjust any of these settings is with your browser through
+ the special <application>Privoxy</application> editor at <ulink
+ url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
+ (shortcut: <ulink url="http://p.p/">http://p.p/show-status</ulink>). This
+ is an internal page, and does not require Internet access. Select the
+ appropriate <quote>actions</quote> file, and click
+ <quote><guibutton>Edit</guibutton></quote>. It is best to put personal or
+ local preferences in <filename>user.action</filename> since this is not
+ meant to be overwritten during upgrades, and will over-ride the settings in
+ other files. Here you can insert new <quote>actions</quote>, and URLs for ad
+ blocking or other purposes, and make other adjustments to the configuration.
+ <application>Privoxy</application> will detect these changes automatically.
+</para>
+
+<para>
+ A quick and simple step by step example:
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Right click on the ad image to be blocked, then select
+ <quote><guimenuitem>Copy Link Location</guimenuitem></quote> from the
+ pop-up menu.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set your browser to
+ <ulink
+ url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Find <filename>user.action</filename> in the top section, and click
+ on <quote><guibutton>Edit</guibutton></quote>:
+ </para>
+
+ <!-- image of editor and actions files selections -->
+ <para>
+ <figure pgwide="0" float="0"><title>Actions Files in Use</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="files-in-use.jpg" format="jpg">
+ </imageobject>
+ <textobject>
+ <phrase>[ Screenshot of Actions Files in Use ]</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You should have a section with only
+ <literal><link linkend="block">block</link></literal> listed under
+ <quote>Actions:</quote>.
+ If not, click a <quote><guibutton>Insert new section below</guibutton></quote>
+ button, and in the new section that just appeared, click the
+ <guibutton>Edit</guibutton> button right under the word <quote>Actions:</quote>.
+ This will bring up a list of all actions. Find
+ <literal><link linkend="block">block</link></literal> near the top, and click
+ in the <quote>Enabled</quote> column, then <quote><guibutton>Submit</guibutton></quote>
+ just below the list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Now, in the <literal><link linkend="block">block</link></literal> actions section,
+ click the <quote><guibutton>Add</guibutton></quote> button, and paste the URL the
+ browser got from <quote><guimenuitem>Copy Link Location</guimenuitem></quote>.
+ Remove the <literal>http://</literal> at the beginning of the URL. Then, click
+ <quote><guibutton>Submit</guibutton></quote> (or
+ <quote><guibutton>OK</guibutton></quote> if in a pop-up window).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Now go back to the original page, and press <keycap>SHIFT-Reload</keycap>
+ (or flush all browser caches). The image should be gone now.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+<para>
+ This is a very crude and simple example. There might be good reasons to use a
+ wildcard pattern match to include potentially similar images from the same
+ site. For a more extensive explanation of <quote>patterns</quote>, and
+ the entire actions concept, see <link linkend="actions-file">the Actions
+ section</link>.
+</para>
+
+<para>
+ For advanced users who want to hand edit their config files, you might want
+ to now go to the <link linkend="act-examples">Actions Files Tutorial</link>.
+ The ideas explained therein also apply to the web-based editor.
+</para>
+<para>
+ There are also various
+ <link linkend="filter">filters</link> that can be used for ad blocking
+ (filters are a special subset of actions). These
+ fall into the <quote>advanced</quote> usage category, and are explained in
+ depth in later sections.
+</para>
+
+</sect2>
+
+</sect1>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="startup">
+<title>Starting Privoxy</title>
+<para>
+ 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 (SSL)
+ <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>. 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 <emphasis>that must be done
+</emphasis>!
+</para>
+<para>
+ Please note that <application>Privoxy</application> can only proxy HTTP and
+ HTTPS traffic. It will not work with FTP or other protocols.
+</para>
+
+ <!-- image of Mozilla Proxy configuration -->
+ <para>
+ <figure pgwide="0" float="0"><title>Proxy Configuration Showing
+ Mozilla/Netscape HTTP and HTTPS (SSL) Settings</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="proxy_setup.jpg" format="jpg">
+ </imageobject>
+ <textobject>
+ <phrase>[ Screenshot of Mozilla Proxy Configuration ]</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </para>
+
+
+<para>
+ With <application>Firefox</application>, this is typically set under:
+</para>
+
+<literallayout>
+ <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> -> <guibutton>General</guibutton> -> <guibutton>Connection Settings</guibutton> -> <guibutton>Manual Proxy Configuration</guibutton>
+
+</literallayout>
+
+<para>
+ Or optionally on some platforms:
+</para>
+
+<literallayout>
+ <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>General</guibutton> -> <guibutton>Connection Settings</guibutton> -> <guibutton>Manual Proxy Configuration</guibutton>
+
+</literallayout>
+
+
+<para>
+ With <application>Netscape</application> (and
+ <application>Mozilla</application>), this can be set under:
+</para>
+
+
+<literallayout>
+<!-- Mix ascii and gui art, something for everybody -->
+<!-- spacing on this is tricky -->
+ <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Proxies</guibutton> -> <guibutton>HTTP Proxy</guibutton>
+
+</literallayout>
+
+<para>
+ For <application>Internet Explorer v.5-6</application>:
+</para>
+
+<literallayout>
+ <guibutton>Tools</guibutton> -> <guibutton>Internet Options</guibutton> -> <guibutton>Connections</guibutton> -> <guibutton>LAN Settings</guibutton>
+</literallayout>
+
+<para>
+ Then, check <quote>Use Proxy</quote> and fill in the appropriate info
+ (Address: 127.0.0.1, Port: 8118). Include HTTPS (SSL), if you want HTTPS
+ proxy support too (sometimes labeled <quote>Secure</quote>). Make sure any
+ checkboxes like <quote>Use the same proxy server for all protocols</quote> is
+ <emphasis>UNCHECKED</emphasis>. You want only HTTP and HTTPS (SSL)!
+</para>
+
+ <!-- image of IE Proxy configuration -->
+ <para>
+ <figure pgwide="0" float="0"><title>Proxy Configuration Showing
+ Internet Explorer HTTP and HTTPS (Secure) Settings</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="proxy2.jpg" format="jpg">
+ </imageobject>
+ <textobject>
+ <phrase>[ Screenshot of IE Proxy Configuration ]</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </para>
+
+
+<para>
+ After doing this, flush your browser's disk and memory caches to force a
+ re-reading of all pages and to get rid of any ads that may be cached. Remove
+ any <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
+ if you want <application>Privoxy</application> to manage that. You are now
+ ready to start enjoying the benefits of using
+ <application>Privoxy</application>!
+</para>
+
+<para>
+ <application>Privoxy</application> itself is typically started by specifying the
+ 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-redhat">
+<title>Red Hat and Fedora</title>
+<para>
+ A default Red Hat installation may not start &my-app; upon boot. It will use
+ the file <filename>/etc/privoxy/config</filename> as its main configuration
+ file.
+</para>
+<para>
+ <screen>
+ # /etc/rc.d/init.d/privoxy start
+</screen>
+</para>
+<para>
+ Or ...
+</para>
+<para>
+ <screen>
+ # service privoxy start
+</screen>
+</para>
+</sect2>
+
+<sect2 id="start-debian">
+<title>Debian</title>
+<para>
+ We use a script. Note that Debian typically starts &my-app; upon booting per
+ default. It will use the file
+ <filename>/etc/privoxy/config</filename> as its main configuration
+ file.
+</para>
+<para>
+ <screen>
+ # /etc/init.d/privoxy start
+</screen>
+</para>
+</sect2>
+
+<!--
+ omitting 10/31/06 HB
+
+<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 &my-app; Icon to start <application>Privoxy</application>. 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 &my-app; when the system starts if you chose that option
+ when installing.
+</para>
+<para>
+ <application>Privoxy</application> can run with full Windows service functionality.
+ On Windows only, the &my-app; program has two new command line arguments
+ to install and uninstall &my-app; as a service. See the
+ <link linkend="installation-pack-win">Windows Installation
+ instructions</link> for details.
+</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>
+</para>
+</sect2>
+
+<sect2 id="start-os2">
+<title>OS/2</title>
+<para>
+ During installation, <application>Privoxy</application> is configured to
+ start automatically when the system restarts. You can start it manually by
+ double-clicking on the <application>Privoxy</application> icon in the
+ <application>Privoxy</application> folder.
+</para>
+</sect2>
+
+<sect2 id="start-macosx">
+<title>Mac OSX</title>
+<para>
+ During installation, <application>Privoxy</application> is configured to
+ start automatically when the system restarts. To start &my-app; manually,
+ double-click on the <literal>StartPrivoxy.command</literal> icon in the
+ <literal>/Library/Privoxy</literal> folder. Or, type this command
+ in the Terminal:
+</para>
+<para>
+ <screen>
+ /Library/Privoxy/StartPrivoxy.command
+ </screen>
+</para>
+<para>
+ You will be prompted for the administrator password.
+</para>
+</sect2>
+
+
+<sect2 id="start-amigaos">
+<title>AmigaOS</title>
<para>
- For for SuSE: <command>rcprivoxy start</command>
+ 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>
+</sect2>
+<sect2 id="start-gentoo">
+<title>Gentoo</title>
+<para>
+ A script is again used. It will use the file <filename>/etc/privoxy/config
+ </filename> as its main configuration file.
+</para>
+<para>
+ <screen>
+ /etc/init.d/privoxy start
+ </screen>
+</para>
<para>
- For RedHat: <command>/etc/rc.d/init.d/privoxy start</command>
+ Note that <application>Privoxy</application> is not automatically started at
+ boot time by default. You can change this with the <literal>rc-update</literal>
+ command.
+</para>
+<para>
+ <screen>
+ rc-update add privoxy default
+ </screen>
</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
+ further info.
</para>
+must find a better place for this paragraph
<para>
The included default configuration files should give a reasonable starting
point. 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.
+ <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 (aka <quote>session cookies</quote>), until you add them to the
+ 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>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.
+ 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 <literal>+popup</literal> and
- <literal>+filter{popups}</literal> actions), because your favorite shopping,
- banking, or leisure site may need popups.
+ 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>
(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</quote> config option in
+ 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>
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://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>edit the actions list</quote>.
+ 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> (toggled) from this page.
</para>
</para>
<para>
- If the above paragraph sounds gibberish to you, you might want to <ulink
- url="configuration.html#ACTIONSFILE">read more about the actions concept</ulink>
- or even dive deep into the <ulink url="appendix.html#ACTIONSANAT">Appendix
- on actions</ulink>.
+ If the above paragraph sounds gibberish to you, you might want to <link
+ linkend="actions-file">read more about the actions concept</link>
+ or even dive deep into the <link linkend="actionsanat">Appendix
+ on actions</link>.
</para>
<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
- chapter "Contacting the Developers, .." below.
+ section <link linkend="contact"><quote>Contacting the
+ Developers</quote></link> below.
</para>
-</sect2>
-
+-->
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
+<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>
<emphasis>USER</emphasis>, and if included the GID of GROUP. Exit if the
privileges are not sufficient to do so. Unix only.
</para>
- </listitem>
- <listitem>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--chroot</emphasis>
+
+ </para>
+ <para>
+ Before changing to the user ID given in the <emphasis>--user</emphasis> option,
+ chroot to that user's home directory, i.e. make the kernel pretend to the &my-app;
+ process that the directory tree starts there. If set up carefully, this can limit
+ the impact of possible vulnerabilities in &my-app; to the files contained in that hierarchy.
+ Unix only.
+ </para>
+ </listitem>
+ <listitem>
<para>
<emphasis>configfile</emphasis>
</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>
</itemizedlist>
</para>
+<para>
+ On <application>MS Windows</application> only there are two additional
+ command-line options to allow <application>Privoxy</application> to install and
+ run as a <emphasis>service</emphasis>. See the
+<link linkend="installation-pack-win">Window Installation section</link>
+for details.
+</para>
+
</sect2>
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="configuration"><title><application>Privoxy</application> Configuration</title>
+<sect1 id="configuration"><title>Privoxy Configuration</title>
<para>
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>
<!-- ~~~~~ New section ~~~~~ -->
<sect2>
-<title>Controlling <application>Privoxy</application> with Your Web Browser</title>
+<title>Controlling Privoxy with Your Web Browser</title>
<para>
<application>Privoxy</application>'s user interface can be reached through the special
URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
</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>
- * Privoxy main page
- * Show information about the current configuration
- * Show the source code version numbers
- * Show the 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>
+ <member>
+ ▪ <ulink url="http://www.privoxy.org/
+ &p-version;/user-manual/">Documentation</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.
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. There
- is even a toggle Bookmarklet offered, so that you can toggle
- <application>Privoxy</application> with one click from your browser.
-
+ 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
</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 may 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>
- <filename>default.action</filename> (the actions file) is used to define
- which of a set of various <quote>actions</quote> relating to images, banners,
- pop-ups, access restrictions, banners and cookies are to be applied where.
- There is a web based editor for this file that can be accessed at <ulink
- url="http://config.privoxy.org/edit-actions/">http://config.privoxy.org/edit-actions/</ulink>
- (Shortcut: <ulink url="http://p.p/edit-actions/">http://p.p/edit-actions/</ulink>).
- (Other actions files are included as well with differing levels of filtering
- and blocking, e.g. <filename>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 only 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>
- <filename>default.filter</filename> (the filter 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. The filtering jobs are only
- pre-defined here; whether to apply them or not is up to the actions file.
+ <quote>Filter files</quote> (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.
+ <filename>default.filter</filename> includes various filters made
+ available for use by the developers. Some are much more intrusive than
+ others, and all should be used with caution. You may define additional
+ filter files in <filename>config</filename> as you can with
+ actions files. We suggest <filename>user.filter</filename> for any
+ locally defined filters or customizations.
</para>
</listitem>
</itemizedlist>
</para>
+<para>
+ The syntax of all configuration files has remained the same throughout the
+ 3.x series. There have been enhancements, but no changes that would preclude
+ the use of any configuration file from one version to the next. (There is
+ one exception: <link linkend="FAST-REDIRECTS">+fast-redirects</link> which
+ has enhanced syntax and will require updating any local configs from earlier
+ versions.)
+</para>
+
<para>
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
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.
+ out" that line. Blank lines are ignored.
</para>
<para>
- <filename>default.action</filename> and <filename>default.filter</filename>
- can use Perl style regular expressions for maximum flexibility.
+ The actions files and filter files
+ can use Perl style <link linkend="regex">regular expressions</link> for
+ maximum flexibility.
</para>
<para>
please check all your configuration files on important issues.
</para>
]]>
+
</sect2>
+</sect1>
+<!-- ~ End section ~ -->
-<!-- ~~~~~ New section ~~~~~ -->
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+
+<!-- **************************************************** -->
+<!-- Include config.sgml here -->
+<!-- This is where the entire config file is detailed. -->
+ &config;
+<!-- end include -->
+
+
+<!-- ~ End section ~ -->
+
+
+
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+
+<sect1 id="actions-file"><title>Actions Files</title>
-<sect2>
-<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.
- Configuration lines consist of an initial keyword followed by a list of
- values, all separated by whitespace (any number of spaces or tabs). For
- example:
-</para>
+ The actions files are used to define what <emphasis>actions</emphasis>
+ <application>Privoxy</application> takes for which URLs, and thus determines
+ 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 a number of such actions, with a wide range of functionality.
+ Each action does something a little different.
+ These actions give us a veritable arsenal of tools with which to exert
+ our control, preferences and independence. Actions can be combined so that
+ their effects are aggregated when applied against a given set of URLs.
+</para>
+<para>
+ There
+ are three action files included with <application>Privoxy</application> 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 as-is for most users.
+ This is the file that the developers are keeping updated, and <link
+ linkend="installation-keepupdated">making available to users</link>.
+ The user's preferences as set in <filename>standard.action</filename>,
+ e.g. either <literal>Cautious</literal> (the default),
+ <literal>Medium</literal>, or <literal>Advanced</literal> (see
+ below).
+ </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 only by the web based editor
+ at <ulink url="http://config.privoxy.org/edit-actions-list?f=default">
+ http://config.privoxy.org/edit-actions-list?f=default</ulink>,
+ to set various pre-defined sets of rules for the default actions section
+ in <filename>default.action</filename>.
+ </para>
+ <para>
+ <guibutton>Edit</guibutton> <guibutton>Set to Cautious</guibutton> <guibutton>Set to Medium</guibutton> <guibutton>Set to Advanced</guibutton>
+ </para>
+ <para>
+ These have increasing levels of aggressiveness <emphasis>and have no
+ influence on your browsing unless you select them explicitly in the
+ editor</emphasis>. A default installation should be pre-set to
+ <literal>Cautious</literal> (versions prior to 3.0.5 were set to
+ <literal>Medium</literal>). New users should try this for a while before
+ adjusting the settings to more aggressive levels. The more aggressive
+ the settings, then the more likelihood there is of problems such as sites
+ not working as they should.
+ </para>
+ <para>
+ The <guibutton>Edit</guibutton> button allows you to turn each
+ action on/off individually for fine-tuning. The <guibutton>Cautious</guibutton>
+ button changes the actions list to low/safe settings which will activate
+ ad blocking and a minimal set of &my-app;'s features, and subsequently
+ there will be less of a chance for accidental problems. The
+ <guibutton>Medium</guibutton> button sets the list to a medium level of
+ other features and a low level set of privacy features. The
+ <guibutton>Advanced</guibutton> button sets the list to a high level of
+ ad blocking and medium level of privacy. See the chart below. The latter
+ three buttons over-ride any changes via with the
+ <guibutton>Edit</guibutton> button. More fine-tuning can be done in the
+ lower sections of this internal page.
+ </para>
+ <para>
+ It is not recommend to edit the <filename>standard.action</filename> file
+ itself.
+ </para>
+ <para>
+ The default profiles, and their associated actions, as pre-defined in
+ <filename>standard.action</filename> are:
+ </para>
+ <para>
+ <table frame=all><title>Default Configurations</title>
+ <tgroup cols=4 align=left colsep=1 rowsep=1>
+ <colspec colname=c1>
+ <colspec colname=c2>
+ <colspec colname=c3>
+ <colspec colname=c4>
+ <thead>
+ <row>
+ <entry>Feature</entry>
+ <entry>Cautious</entry>
+ <entry>Medium</entry>
+ <entry>Advanced</entry>
+ </row>
+ </thead>
+ <!-- <tfoot> -->
+ <!-- <row> -->
+ <!-- <entry>f1</entry> -->
+ <!-- <entry>f2</entry> -->
+ <!-- <entry>f3</entry> -->
+ <!-- <entry>f4</entry> -->
+ <!-- </row> -->
+ <!-- </tfoot> -->
+ <tbody>
+
+ <row>
+ <entry>Ad-blocking Aggressiveness</entry>
+ <entry>medium</entry>
+ <entry>high</entry>
+ <entry>high</entry>
+ </row>
+
+ <row>
+ <entry>Ad-filtering by size</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>Ad-filtering by link</entry>
+ <entry>no</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>Pop-up killing</entry>
+ <entry>blocks only</entry>
+ <entry>blocks only</entry>
+ <entry>blocks only</entry>
+ </row>
+
+ <row>
+ <entry>Privacy Features</entry>
+ <entry>low</entry>
+ <entry>medium</entry>
+ <entry>medium/high</entry>
+ </row>
+
+ <row>
+ <entry>Cookie handling</entry>
+ <entry>none</entry>
+ <entry>session-only</entry>
+ <entry>kill</entry>
+ </row>
+
+ <row>
+ <entry>Referer forging</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ </row>
+
+
+ <row>
+ <entry>GIF de-animation</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ </row>
+
+
+ <row>
+ <entry>Fast redirects</entry>
+ <entry>no</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>HTML taming</entry>
+ <entry>no</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>JavaScript taming</entry>
+ <entry>no</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>Web-bug killing</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>Image tag reordering</entry>
+ <entry>no</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+ </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 (e.g.
+ <filename>default.action</filename> is typically processed before
+ <filename>user.action</filename>). 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>.
+ The over-riding principle when applying actions, is that the last action that
+ matches a given URL, wins. The broadest, most general rules go first
+ (defined in <filename>default.action</filename>),
+ followed by any exceptions (typically also in
+ <filename>default.action</filename>), which are then followed lastly by any
+ local preferences (typically in <emphasis>user</emphasis><filename>.action</filename>).
+ Generally, <filename>user.action</filename> has the last word.
+ </para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>confdir /etc/privoxy</emphasis>
- </literallayout>
- </msgtext>
- </literal>
+ 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>
- 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>.
+ 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. And, things can always change, requiring
+ refinements in the configuration. 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 crunch all cookies per
+ default, you'll have to make exceptions from that rule for sites that you
+ regularly use and that require cookies for actually useful purposes, like maybe
+ your bank, favorite shop, or newspaper.
</para>
<para>
- 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.
+ 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 main config file controls all aspects of <application>Privoxy</application>'s
- operation that are not location dependent (i.e. they apply to all URLs, no matter
- where you may be surfing).
+ 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>.
+ Warning: the <quote>Advanced</quote> setting is more aggressive, and
+ will be more likely to cause problems for some sites. Experienced users only!
</para>
+<para>
+ If you prefer plain text editing to GUIs, you can of course also directly edit the
+ the actions files with your favorite text editor. Look at
+ <filename>default.action</filename> which is richly commented with many
+ good examples.
+</para>
+</sect2>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3>
-<title>Configuration and Log File Locations</title>
+<sect2 id="actions-apply">
+<title>How Actions are Applied to Requests</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 and tag patterns, each on a separate line.
+</para>
<para>
- <application>Privoxy</application> can (and normally does) use a number of
- other files for additional configuration and logging.
- This section of the configuration file tells <application>Privoxy</application>
- where to find those other files.
+ To determine which actions apply to a request, the URL of the request is
+ compared to all URL patterns in each <quote>action file</quote>.
+ Every time it matches, the list of applicable actions for the request is
+ incrementally updated, using the heading of the section in which the
+ pattern is located. The same is done again for tags and tag patterns later on.
</para>
+<para>
+ If multiple applying sections set the same action differently,
+ the last match wins. If not, the effects are aggregated.
+ E.g. a URL might match a regular section with a heading line of <literal>{
+ +<link linkend="handle-as-image">handle-as-image</link> }</literal>,
+ then later another one with just <literal>{
+ +<link linkend="block">block</link> }</literal>, resulting
+ in <emphasis>both</emphasis> actions to apply. And there may well be
+ cases where you will want to combine actions together. Such a section then
+ might look like:
+</para>
-<sect4><title>confdir</title>
+ <para>
+ <screen>
+ { +<literal>handle-as-image</literal> +<literal>block</literal> }
+ # Block these as if they were images. Send no block page.
+ banners.example.com
+ media.example.com/.*banners
+ .example.com/images/ads/</screen>
+ </para>
-<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>
-</sect4>
+<para>
+ You can trace this process for URL patterns and any given URL by visiting <ulink
+ url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
+</para>
+<para>
+ Examples and more detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
+ Troubleshooting: Anatomy of an Action</link> section.
+</para>
+</sect2>
-<sect4><title>logdir</title>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="af-patterns">
+<title>Patterns</title>
+<para>
+ As mentioned, <application>Privoxy</application> uses <quote>patterns</quote>
+ to determine what <emphasis>actions</emphasis> might apply to which sites and
+ pages your browser attempts to access. These <quote>patterns</quote> use wild
+ card type <emphasis>pattern</emphasis> matching to achieve a high degree of
+ flexibility. This allows one expression to be expanded and potentially match
+ against many similar patterns.
+</para>
+
+<para>
+ Generally, a URL pattern has the form
+ <literal><domain>/<path></literal>, where both the
+ <literal><domain></literal> and <literal><path></literal> are
+ optional. (This is why the special <literal>/</literal> pattern matches all
+ URLs). Note that the protocol portion of the URL pattern (e.g.
+ <literal>http://</literal>) should <emphasis>not</emphasis> be included in
+ the pattern. This is assumed already!
+</para>
+<para>
+ The pattern matching syntax is different for the domain and path parts of
+ the URL. The domain part uses a simple globbing type matching technique,
+ while the path part uses a more flexible
+ <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+ Expressions (PCRE)</quote></ulink> based syntax.
+</para>
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term><literal>www.example.com/</literal></term>
<listitem>
<para>
- The directory where all logging takes place (i.e. where <filename>logfile</filename> and
- <filename>jarfile</filename> are located)
+ 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. So ALL pages in
+ this domain would be covered by the scope of this action. Note that a
+ simple <literal>example.com</literal> is different and would NOT match.
</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>
+ <term><literal>www.example.com</literal></term>
<listitem>
<para>
- No trailing <quote><literal>/</literal></quote>, please
+ means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
+ be omitted.
</para>
</listitem>
</varlistentry>
-</variablelist>
-</sect4>
-
-<sect4><title>actionsfile</title>
-
-<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term><literal>www.example.com/index.html</literal></term>
<listitem>
<para>
- The actions file to use
+ matches only the single document <literal>/index.html</literal>
+ on <literal>www.example.com</literal>.
</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.action (Unix) <emphasis>or</emphasis> default.action.txt (Windows)</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
+ <term><literal>/index.html</literal></term>
<listitem>
<para>
- No action is taken at all. Simple neutral proxying.
+ matches the document <literal>/index.html</literal>, regardless of the domain,
+ i.e. on <emphasis>any</emphasis> web server anywhere.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Notes:</term>
+ <term><literal>index.html</literal></term>
<listitem>
<para>
- There is no point in using <application>Privoxy</application> without
- an actions file. There are three different actions files included in the
- distribution, with varying degrees of aggressiveness:
- <filename>default.action</filename>, <filename>intermediate.action</filename> and
- <filename>advanced.action</filename>.
+ matches nothing, since it would be interpreted as a domain name and
+ there is no top-level domain called <literal>.html</literal>. So its
+ a mistake.
</para>
</listitem>
</varlistentry>
</variablelist>
-</sect4>
-<sect4><title>filterfile</title>
+
+<!-- ~~~~~ 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>Specifies:</term>
+ <term><literal>.example.com</literal></term>
<listitem>
<para>
- The filter file to use
+ matches any domain that <emphasis>ENDS</emphasis> in
+ <literal>.example.com</literal>
</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>
+ <term><literal>www.</literal></term>
<listitem>
<para>
- No textual content filtering takes place, i.e. all
- <literal>+filter{<replaceable class="parameter">name</replaceable>}</literal>
- actions in the actions file are turned off
+ matches any domain that <emphasis>STARTS</emphasis> with
+ <literal>www.</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Notes:</term>
+ <term><literal>.example.</literal></term>
<listitem>
<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.
+ matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>.
+ And, by the way, also included would be any files or documents that exist
+ within that domain since no path limitations are specified. (Correctly
+ speaking: It matches any FQDN that contains <literal>example</literal> as
+ a domain.) This might be <literal>www.example.com</literal>,
+ <literal>news.example.de</literal>, or
+ <literal>www.example.net/cgi/testing.pl</literal> for instance. All these
+ cases are matched.
</para>
</listitem>
</varlistentry>
</variablelist>
-</sect4>
-<sect4><title>logfile</title>
+<para>
+ Additionally, there are wild-cards that you can use in the domain names
+ themselves. These work similarly to shell globbing type wild-cards:
+ <quote>*</quote> represents zero or more arbitrary characters (this is
+ equivalent to the
+ <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+ Expression</quote></ulink> based syntax of <quote>.*</quote>),
+ <quote>?</quote> represents any single character (this is equivalent to the
+ regular expression syntax of a simple <quote>.</quote>), and you can define
+ <quote>character classes</quote> in square brackets which is similar to
+ the same regular expression technique. All of this can be freely mixed:
+</para>
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term><literal>ad*.example.com</literal></term>
<listitem>
<para>
- The log file to use
+ matches <quote>adserver.example.com</quote>,
+ <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
</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>
+ <term><literal>*ad*.example.com</literal></term>
<listitem>
- <para>logfile (Unix) <emphasis>or</emphasis> privoxy.log (Windows)</para>
+ <para>
+ matches all of the above, and then some.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Effect if unset:</term>
+ <term><literal>.?pix.com</literal></term>
<listitem>
<para>
- No log file is used, all log messages go to the console (<literal>stderr</literal>).
+ 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>Notes:</term>
+ <term><literal>www[1-9a-ez].example.c*</literal></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 Redhat, 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.
+ 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>
-</sect4>
-<sect4><title>jarfile</title>
+<para>
+ While flexible, this is not the sophistication of full regular expression based syntax.
+</para>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3><title>The Path Pattern</title>
+
+<para>
+ <application>Privoxy</application> uses Perl compatible (PCRE)
+ <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+ Expression</quote></ulink> based syntax
+ (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
+ matching the path portion (after the slash), and is thus more flexible.
+</para>
+
+<para>
+ 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://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>.
+</para>
+
+<para>
+ 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>
+ Please also note that matching in the path is <emphasis>CASE 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>
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term><literal>.example.com/.*</literal></term>
<listitem>
<para>
- The file to store intercepted cookies in
+ Is equivalent to just <quote>.example.com</quote>, since any documents
+ within that domain are matched with or without the <quote>.*</quote>
+ regular expression. This is redundant
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Type of value:</term>
+ <term><literal>.example.com/.*/index.html</literal></term>
<listitem>
- <para>File name, relative to <literal>logdir</literal></para>
+ <para>
+ Will match any page in the domain of <quote>example.com</quote> that is
+ named <quote>index.html</quote>, and that is part of some path. For
+ example, it matches <quote>www.example.com/testing/index.html</quote> but
+ NOT <quote>www.example.com/index.html</quote> because the regular
+ expression called for at least two <quote>/'s</quote>, thus the path
+ requirement. It also would match
+ <quote>www.example.com/testing/index_html</quote>, because of the
+ special meta-character <quote>.</quote>.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Default value:</term>
+ <term><literal>.example.com/(.*/)?index\.html</literal></term>
<listitem>
- <para>jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</para>
+ <para>
+ This regular expression is conditional so it will match any page
+ named <quote>index.html</quote> regardless of path which in this case can
+ have one or more <quote>/'s</quote>. And this one must contain exactly
+ <quote>.html</quote> (but does not have to end with that!).
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Effect if unset:</term>
+ <term><literal>.example.com/(.*/)(ads|banners?|junk)</literal></term>
<listitem>
<para>
- Intercepted cookies are not stored at all.
+ This regular expression will match any path of <quote>example.com</quote>
+ that contains any of the words <quote>ads</quote>, <quote>banner</quote>,
+ <quote>banners</quote> (because of the <quote>?</quote>) or <quote>junk</quote>.
+ The path does not have to end in these words, just contain them.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Notes:</term>
+ <term><literal>.example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$</literal></term>
<listitem>
<para>
- The jarfile may grow to ridiculous sizes over time.
+ This is very much the same as above, except now it must end in either
+ <quote>.jpg</quote>, <quote>.jpeg</quote>, <quote>.gif</quote> or <quote>.png</quote>. So this
+ one is limited to common image formats.
</para>
</listitem>
</varlistentry>
+
</variablelist>
-</sect4>
+<para>
+ There are many, many good examples to be found in <filename>default.action</filename>,
+ and more tutorials below in <link linkend="regex">Appendix on regular expressions</link>.
+</para>
-<sect4><title>trustfile</title>
+</sect3>
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="tag-pattern"><title>The Tag Pattern</title>
+
+<para>
+ Tag patterns are used to change the applying actions based on the
+ request's tags. Tags can be created with either the
+ <link linkend="CLIENT-HEADER-FILTER">client-header-tagger</link>
+ or the <link linkend="SERVER-HEADER-FILTER">server-header-tagger</link> action.
+</para>
+
+<para>
+ Tag patterns have to start with <quote>TAG:</quote>, so &my-app;
+ can tell them apart from URL patterns. Everything after the colon
+ including white space, is interpreted as a regular expression with
+ path patterns syntax, except that tag patterns aren't left-anchored
+ automatically (Privoxy doesn't silently add a <quote>^</quote>,
+ you have to do it yourself if you need it).
+</para>
+
+<para>
+ To match all requests that are tagged with <quote>foo</quote>
+ your pattern line should be <quote>TAG:^foo$</quote>,
+ <quote>TAG:foo</quote> would work as well, but it would also
+ match requests whose tags contain <quote>foo</quote> somewhere.
+</para>
+
+<para>
+ Sections can contain URL and tag patterns at the same time,
+ but tag patterns are checked after the URL patterns and thus
+ always overrule them, even if they are located before the URL patterns.
+</para>
+
+<para>
+ Once a new tag is added, Privoxy checks right away if it's matched by one
+ of the tag patterns and updates the action settings accordingly. As a result
+ tags can be used to activate other tagger actions, as long as these other
+ taggers look for headers that haven't already be parsed.
+</para>
+
+<para>
+ For example you could tag client requests which use the POST method,
+ use this tag to activate another tagger that adds a tag if cookies
+ are send, and then block based on the cookie tag. However if you'd
+ reverse the position of the described taggers, and activated the method
+ tagger based on the cookie tagger, no method tags would be created.
+ The method tagger would look for the request line, but at the time
+ the cookie tag is created the request line has already been parsed.
+</para>
+
+<para>
+ While this is a limitation you should be aware of, this kind of
+ indirection is seldom needed anyway and even the example doesn't
+ make too much sense.
+</para>
+
+</sect3>
+
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="actions">
+<title>Actions</title>
+<para>
+ 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>
+ 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>
+ Actions fall into three categories:
+</para>
+
+<para>
+ <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>
+
+
+ <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>
+
+ </itemizedlist>
+</para>
+
+<para>
+ 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>
+ 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 such
+ as <filename>user.action</filename>). 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 to match more than one <quote>pattern</quote> (because of wildcards and
+ regular expressions), and thus to trigger more than one set of actions! Last
+ match wins.
+</para>
+
+<!-- start actions listing -->
+<para>
+ The list of valid <application>Privoxy</application> actions are:
+</para>
+
+
+<!-- ********************************************************** -->
+<!-- Please note the below defined actions use id's that are -->
+<!-- probably linked from other places, so please don't change. -->
+<!-- -->
+<!-- ********************************************************** -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="add-header">
+<title>add-header</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
<listitem>
- <para>
- The trust file to use
- </para>
+ <para>Confuse log analysis, custom applications</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</term>
<listitem>
- <para>File name, relative to <literal>confdir</literal></para>
+ <para>
+ Sends a user defined HTTP header to the web server.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
<listitem>
- <para><emphasis>Unset (commented out)</emphasis>. When activated: trust (Unix) <emphasis>or</emphasis> trust.txt (Windows)</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
<para>
- The whole trust mechanism is turned off.
+ 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>
+
+<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.
+ 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>
- <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.
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+add-header{X-User-Tracking: sucks}</screen>
</para>
</listitem>
</varlistentry>
</variablelist>
-</sect4>
-
</sect3>
-<!-- ~ End section ~ -->
-
-
<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3>
-<title>Local Set-up Documentation</title>
-
- <para>
- If you intend to operate <application>Privoxy</application> for more users
- that 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>
-
-<sect4><title>trust-info-url</title>
+<sect3 renderas="sect4" id="block">
+<title>block</title>
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term>Typical use:</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>
+ <para>Block ads or other unwanted content</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</term>
<listitem>
- <para>URL</para>
+ <para>
+ Requests for URLs to which this action applies are blocked, i.e. the
+ requests are trapped by &my-app; and the requested URL is never retrieved,
+ but is answered locally with a substitute page or image, as determined by
+ the <literal><link
+ linkend="handle-as-image">handle-as-image</link></literal>,
+ <literal><link
+ linkend="set-image-blocker">set-image-blocker</link></literal>, and
+ <literal><link
+ linkend="handle-as-empty-document">handle-as-empty-document</link></literal> actions.
+
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Two example URL are provided</para>
+ <para>Boolean.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
- <para>
- No links are displayed on the "untrusted" error page.
- </para>
+ <para>N/A</para>
</listitem>
</varlistentry>
- <varlistentry>
+
+<varlistentry>
<term>Notes:</term>
<listitem>
<para>
- The value of this option only matters if the experimental trust mechanism has been
- activated. (See <literal>trustfile</literal> above.)
+ <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>
- 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.
+ It is important to understand this process, in order
+ to understand how <application>Privoxy</application> deals with
+ ads and other unwanted content. Blocking is a core feature, and one
+ upon which various other features depend.
</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!
+ 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/banners/
+
+{+block +handle-as-empty-document}
+# Block and then ignore
+ adserver.exampleclick.net/.*\.js$</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
</variablelist>
-</sect4>
+</sect3>
+
-<sect4><title>admin-address</title>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="client-header-filter">
+<title>client-header-filter</title>
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term>Typical use:</term>
<listitem>
<para>
- An email address to reach the proxy administrator.
+ Rewrite or remove single client headers.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</term>
<listitem>
- <para>Email address</para>
+ <para>
+ All client headers to which this action applies are filtered on-the-fly through
+ the specified regular expression based substitutions.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
<listitem>
- <para><emphasis>Unset</emphasis></para>
+ <para>Parameterized.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
<para>
- No email address is displayed on error pages and the CGI user interface.
+ The name of a client-header filter, as defined in one of the
+ <link linkend="filter-file">filter files</link>.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>Notes:</term>
+ <listitem>
+ <para>
+ Client-header filters are applied to each header on its own, not to
+ all at once. This makes it easier to diagnose problems, but on the downside
+ you can't write filters that only change header x if header y's value is z.
+ You can do that by using tags though.
+ </para>
+ <para>
+ Client-header filters are executed after the other header actions have finished
+ and use their output as input.
+ </para>
+ <para>
+ Please refer to the <link linkend="filter-file">filter file chapter</link>
+ to learn which client-header filters are available by default, and how to
+ create your own.
+ </para>
+
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</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>
+ <screen>
+{+client-header-filter{hide-tor-exit-notation}}
+.exit/
+ </screen>
+ </para>
</listitem>
</varlistentry>
+
</variablelist>
-</sect4>
+</sect3>
+
-<sect4><title>proxy-info-url</title>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="client-header-tagger">
+<title>client-header-tagger</title>
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term>Typical use:</term>
<listitem>
<para>
- A URL to documentation about the local <application>Privoxy</application> setup,
- configuration or policies.
+ Block requests based on their headers.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</term>
<listitem>
- <para>URL</para>
+ <para>
+ Client headers to which this action applies are filtered on-the-fly through
+ the specified regular expression based substitutions, the result is used as
+ tag.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
<listitem>
- <para><emphasis>Unset</emphasis></para>
+ <para>Parameterized.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
<para>
- No link to local documentation is displayed on error pages and the CGI user interface.
+ The name of a client-header tagger, as defined in one of the
+ <link linkend="filter-file">filter files</link>.
</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>
+ Client-header taggers are applied to each header on its own,
+ and as the header isn't modified, each tagger <quote>sees</quote>
+ the original.
+ </para>
<para>
- This URL shouldn't be blocked ;-)
- </para>
+ Client-header taggers are the first actions that are executed
+ and their tags can be used to control every other action.
+ </para>
+
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>
+# Tag every request with the User-Agent header
+{+client-header-filter{user-agent}}
+/
+ </screen>
+ </para>
</listitem>
</varlistentry>
-</variablelist>
-</sect4>
+</variablelist>
</sect3>
-<!-- ~ End section ~ -->
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3>
-<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>
-<sect4><title>debug</title>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="content-type-overwrite">
+<!--
+new action
+-->
+<title>content-type-overwrite</title>
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term>Typical use:</term>
<listitem>
- <para>
- Key values that determine what information gets logged.
- </para>
+ <para>Stop useless download menus from popping up, or change the browser's rendering mode</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</term>
<listitem>
- <para>Integer values</para>
+ <para>
+ Replaces the <quote>Content-Type:</quote> HTTP server header.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
<listitem>
- <para>12289 (i.e.: URLs plus informational and warning messages)</para>
+ <para>Parameterized.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
<para>
- Nothing gets logged.
- </para>
+ Any string.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>Notes:</term>
<listitem>
<para>
- The available debug levels are:
+ The <quote>Content-Type:</quote> HTTP server header is used by the
+ browser to decide what to do with the document. The value of this
+ header can cause the browser to open a download menu instead of
+ displaying the document by itself, even if the document's format is
+ supported by the browser.
</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>
+ The declared content type can also affect which rendering mode
+ the browser chooses. If XHTML is delivered as <quote>text/html</quote>,
+ many browsers treat it as yet another broken HTML document.
+ If it is send as <quote>application/xml</quote>, browsers with
+ XHTML support will only display it, if the syntax is correct.
</para>
<para>
- To select multiple debug levels, you can either add them or use
- multiple <literal>debug</literal> lines.
+ If you see a web site that proudly uses XHTML buttons, but sets
+ <quote>Content-Type: text/html</quote>, you can use &my-app;
+ to overwrite it with <quote>application/xml</quote> and validate
+ the web master's claim inside your XHTML-supporting browser.
+ If the syntax is incorrect, the browser will complain loudly.
</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 -->
+ You can also go the opposite direction: if your browser prints
+ error messages instead of rendering a document falsely declared
+ as XHTML, you can overwrite the content type with
+ <quote>text/html</quote> and have it rendered as broken HTML document.
</para>
<para>
- The reporting of <emphasis>fatal</emphasis> errors (i.e. ones which crash
- <application>Privoxy</application>) is always on and cannot be disabled.
+ By default <literal>content-type-overwrite</literal> only replaces
+ <quote>Content-Type:</quote> headers that look like some kind of text.
+ If you want to overwrite it unconditionally, you have to combine it with
+ <literal><link linkend="force-text-mode">force-text-mode</link></literal>.
+ This limitation exists for a reason, think twice before circumventing it.
</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.
+ Most of the time it's easier to replace this action with a custom
+ <literal><link linkend="server-header-filter">server-header filter</link></literal>.
+ It allows you to activate it for every document of a certain site and it will still
+ only replace the content types you aimed at.
</para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4><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.
+ Of course you can apply <literal>content-type-overwrite</literal>
+ to a whole site and then make URL based exceptions, but it's a lot
+ more work to get the same precision.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Notes:</term>
+ <term>Example usage (sections):</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>
+ <screen># Check if www.example.net/ really uses valid XHTML
+{ +content-type-overwrite{application/xml} }
+www.example.net/
+
+# but leave the content type unmodified if the URL looks like a style sheet
+{-content-type-overwrite}
+www.example.net/.*\.css$
+www.example.net/.*style
+</screen>
</para>
</listitem>
</varlistentry>
</variablelist>
-</sect4>
-
</sect3>
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3>
-<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>
-<sect4><title>listen-address</title>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-client-header">
+<!--
+new action
+-->
+<title>crunch-client-header</title>
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term>Typical use:</term>
<listitem>
- <para>
- The IP address and TCP port on which <application>Privoxy</application> will
- listen for client requests.
- </para>
+ <para>Remove a client header <application>Privoxy</application> has no dedicated action for.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</term>
<listitem>
- <para>[<replaceable class="parameter">IP-Address</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
+ <para>
+ Deletes every header sent by the client that contains the string the user supplied as parameter.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
<listitem>
- <para>localhost:8118</para>
+ <para>Parameterized.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
<para>
- Bind to localhost (127.0.0.1), port 8118. This is suitable and recommended for
- home users who run <application>Privoxy</application> on the same machine as
- their browser.
- </para>
+ Any string.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>Notes:</term>
<listitem>
<para>
- You will need to configure your browser(s) to this proxy address and port.
+ This action allows you to block client headers for which no dedicated
+ <application>Privoxy</application> action exists.
+ <application>Privoxy</application> will remove every client header that
+ contains the string you supplied as parameter.
</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.
+ Regular expressions are <emphasis>not supported</emphasis> and you can't
+ use this action to block different headers in the same request, unless
+ they contain the same string.
</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>
+ <literal>crunch-client-header</literal> is only meant for quick tests.
+ If you have to block several different headers, or only want to modify
+ parts of them, you should use a
+ <literal><link linkend="client-header-filter">client-header filter</link></literal>.
+ </para>
+ <warning>
+ <para>
+ Don't block any header without understanding the consequences.
+ </para>
+ </warning>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Example:</term>
+ <term>Example usage (section):</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>
+ <screen># Block the non-existent "Privacy-Violation:" client header
+{ +crunch-client-header{Privacy-Violation:} }
+/
+ </screen>
</para>
</listitem>
</varlistentry>
</variablelist>
-</sect4>
+</sect3>
-<sect4><title>toggle</title>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-if-none-match">
+<title>crunch-if-none-match</title>
+<!--
+new action
+-->
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term>Typical use:</term>
<listitem>
- <para>
- Initial state of "toggle" status
- </para>
+ <para>Prevent yet another way to track the user's steps between sessions.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</term>
<listitem>
- <para>1 or 0</para>
+ <para>
+ Deletes the <quote>If-None-Match:</quote> HTTP client header.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
<listitem>
- <para>1</para>
+ <para>Boolean.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
<para>
- Act as if toggled on
- </para>
+ N/A
+ </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. 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> then via editing the <filename>conf</filename> file.
+ Removing the <quote>If-None-Match:</quote> HTTP client header
+ is useful for filter testing, where you want to force a real
+ reload instead of getting status code <quote>304</quote> which
+ would cause the browser to use a cached copy of the page.
+ </para>
+ <para>
+ It is also useful to make sure the header isn't used as a cookie
+ replacement.
</para>
<para>
- The windows version will only display the toggle icon in the system tray
- if this option is present.
+ Blocking the <quote>If-None-Match:</quote> header shouldn't cause any
+ caching problems, as long as the <quote>If-Modified-Since:</quote> header
+ isn't blocked as well.
+ </para>
+ <para>
+ It is recommended to use this action together with
+ <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
+ and
+ <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen># Let the browser revalidate cached documents without being tracked across sessions
+{ +hide-if-modified-since{-60} \
+ +overwrite-last-modified{randomize} \
+ +crunch-if-none-match}
+/ </screen>
</para>
</listitem>
</varlistentry>
</variablelist>
-</sect4>
+</sect3>
-<sect4><title>enable-remote-toggle</title>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-incoming-cookies">
+<title>crunch-incoming-cookies</title>
+
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term>Typical use:</term>
<listitem>
<para>
- Whether or not the <ulink url="http://config.privoxy.org/toggle">web-based toggle
- feature</ulink> may be used
+ Prevent the web server from setting any cookies on your system
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</term>
<listitem>
- <para>0 or 1</para>
+ <para>
+ Deletes any <quote>Set-Cookie:</quote> HTTP headers from server replies.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
<listitem>
- <para>1</para>
+ <para>Boolean.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
<para>
- The web-based toggle feature is disabled.
+ N/A
</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.
+ 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>
- 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.
+ 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. See also
+ <literal><link linkend="filter-content-cookies">filter-content-cookies</link></literal>.
</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
<para>
- Note that you must have compiled <application>Privoxy</application> with
- support for this feature, otherwise this option has no effect.
+ <screen>+crunch-incoming-cookies</screen>
</para>
</listitem>
</varlistentry>
</variablelist>
-</sect4>
+</sect3>
-<sect4><title>enable-edit-actions</title>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-server-header">
+<title>crunch-server-header</title>
+<!--
+new action
+-->
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term>Typical use:</term>
<listitem>
- <para>
- Whether or not the <ulink url="http://config.privoxy.org/edit-actions">web-based actions
- file editor</ulink> may be used
- </para>
+ <para>Remove a server header <application>Privoxy</application> has no dedicated action for.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</term>
<listitem>
- <para>0 or 1</para>
+ <para>
+ Deletes every header sent by the server that contains the string the user supplied as parameter.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
<listitem>
- <para>1</para>
+ <para>Parameterized.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
<para>
- The web-based actions file editor is disabled.
- </para>
+ Any string.
+ </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.
+ This action allows you to block server headers for which no dedicated
+ <application>Privoxy</application> action exists. <application>Privoxy</application>
+ will remove every server header that contains the string you supplied as parameter.
</para>
<para>
- Note that you must have compiled <application>Privoxy</application> with
- support for this feature, otherwise this option has no effect.
+ Regular expressions are <emphasis>not supported</emphasis> and you can't
+ use this action to block different headers in the same request, unless
+ they contain the same string.
+ </para>
+ <para>
+ <literal>crunch-server-header</literal> is only meant for quick tests.
+ If you have to block several different headers, or only want to modify
+ parts of them, you should use a custom
+ <literal><link linkend="server-header-filter">server-header filter</link></literal>.
+ </para>
+ <warning>
+ <para>
+ Don't block any header without understanding the consequences.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen># Crunch server headers that try to prevent caching
+{ +crunch-server-header{no-cache} }
+/ </screen>
</para>
</listitem>
</varlistentry>
</variablelist>
-</sect4>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-outgoing-cookies">
+<title>crunch-outgoing-cookies</title>
-<sect4><title>ACLs: permit-access and deny-access</title>
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term>Typical use:</term>
<listitem>
<para>
- Who can access what.
+ Prevent the web server from reading any cookies from your system
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</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.
+ Deletes any <quote>Cookie:</quote> HTTP headers from client requests.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
<listitem>
- <para><emphasis>Unset</emphasis></para>
+ <para>Boolean.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
<para>
- Don't restrict access further than implied by <literal>listen-address</literal>
+ N/A
</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 or internal (home)
- network address by means of the <literal>listen-address</literal> 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).
+ 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>
- 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.
+ 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>
+
<varlistentry>
- <term>Examples:</term>
+ <term>Example usage:</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>
+ <screen>+crunch-outgoing-cookies</screen>
</para>
</listitem>
</varlistentry>
+
</variablelist>
-</sect4>
+</sect3>
+
-<sect4><title>buffer-limit</title>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="deanimate-gifs">
+<title>deanimate-gifs</title>
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term>Typical use:</term>
<listitem>
- <para>
- Maximum size of the buffer for content filtering.
- </para>
+ <para>Stop those annoying, distracting animated GIF images.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</term>
<listitem>
- <para>Size in Kbytes</para>
+ <para>
+ De-animate GIF animations, i.e. reduce them to their first or last image.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>4096</para>
+ <para>Parameterized.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
<para>
- Use a 4MB (4096 KB) limit.
+ <quote>last</quote> or <quote>first</quote>
</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.
+ 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>
- 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.
+ 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>
-</variablelist>
-</sect4>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+deanimate-gifs{last}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
</sect3>
-<!-- ~ End section ~ -->
-
-
<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="downgrade-http-version">
+<title>downgrade-http-version</title>
-<sect3 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>
-
-<sect4><title>forward</title>
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term>Typical use:</term>
<listitem>
- <para>
- To which parent HTTP proxy specific requests should be routed.
- </para>
+ <para>Work around (very rare) problems with HTTP/1.1</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</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 actions 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
+ Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
<listitem>
- <para><emphasis>Unset</emphasis></para>
+ <para>Boolean.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
<para>
- Don't use parent HTTP proxies.
+ N/A
</para>
</listitem>
</varlistentry>
- <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.
+ 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>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>{+downgrade-http-version}
+problem-host.example.com</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="fast-redirects">
+<title>fast-redirects</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Fool some click-tracking scripts and speed up indirect links.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
<para>
- Multiple lines are OK, they are checked in sequence, and the last match wins.
+ Detects redirection URLs and redirects the browser without contacting
+ the redirection server first.
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <quote>simple-check</quote> to just search for the string <quote>http://</quote>
+ to detect redirection URLs.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <quote>check-decoded-url</quote> to decode URLs (if necessary) before searching
+ for redirection URLs.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
- <term>Examples:</term>
+ <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:
+ <quote>http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/</quote>.
+ </para>
<para>
- Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle):
+ 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 asks the server for one redirect after the other. Plus, it feeds
+ the advertisers.
</para>
<para>
- <screen>
- forward .* anon-proxy.example.org:8080
- forward :443 .
- </screen>
+ This feature is currently not very smart and is scheduled for improvement.
+ If it is enabled by default, you will have to create some exceptions to
+ this action. It can lead to failures in several ways:
</para>
<para>
- Everything goes to our example ISP's caching proxy, except for requests
- to that ISP's sites:
+ Not every URLs with other URLs as parameters is evil.
+ Some sites offer a real service that requires this information to work.
+ For example a validation service needs to know, which document to validate.
+ <literal>fast-redirects</literal> assumes that every URL parameter that
+ looks like another URL is a redirection target, and will always redirect to
+ the last one. Most of the time the assumption is correct, but if it isn't,
+ the user gets redirected anyway.
</para>
<para>
- <screen>
- forward .*. caching-proxy.example-isp.net:8000
- forward .example-isp.net .
- </screen>
+ Another failure occurs if the URL contains other parameters after the URL parameter.
+ The URL:
+ <quote>http://www.example.org/?redirect=http%3a//www.example.net/&foo=bar</quote>.
+ contains the redirection URL <quote>http://www.example.net/</quote>,
+ followed by another parameter. <literal>fast-redirects</literal> doesn't know that
+ and will cause a redirect to <quote>http://www.example.net/&foo=bar</quote>.
+ Depending on the target server configuration, the parameter will be silently ignored
+ or lead to a <quote>page not found</quote> error. You can prevent this problem by
+ first using the <literal><link linkend="redirect">redirect</link></literal> action
+ to remove the last part of the URL, but it requires a little effort.
</para>
+ <para>
+ To detect a redirection URL, <literal>fast-redirects</literal> only
+ looks for the string <quote>http://</quote>, either in plain text
+ (invalid but often used) or encoded as <quote>http%3a//</quote>.
+ Some sites use their own URL encoding scheme, encrypt the address
+ of the target server or replace it with a database id. In theses cases
+ <literal>fast-redirects</literal> is fooled and the request reaches the
+ redirection server where it probably gets logged.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>
+ { +fast-redirects{simple-check} }
+ .example.com
+
+ { +fast-redirects{check-decoded-url} }
+ another.example.com/testing</screen>
+ </para>
</listitem>
</varlistentry>
+
</variablelist>
-</sect4>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="filter">
+<title>filter</title>
-<sect4><title>forward-socks4 and forward-socks4a</title>
<variablelist>
<varlistentry>
- <term>Specifies:</term>
+ <term>Typical use:</term>
<listitem>
- <para>
- Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed.
- </para>
+ <para>Get rid of HTML and JavaScript annoyances, banner advertisements (by size),
+ do fun text replacements, add personalized effects, etc.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Type of value:</term>
+ <term>Effect:</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 actions 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
+ All instances of text-based type, most notably HTML and JavaScript, to which
+ this action applies, can be filtered on-the-fly through the specified regular
+ expression based substitutions. (Note: as of version 3.0.3 plain text documents
+ are exempted from filtering, because web servers often use the
+ <literal>text/plain</literal> MIME type for all files whose type they don't know.)
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Default value:</term>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
<listitem>
- <para><emphasis>Unset</emphasis></para>
+ <para>Parameterized.</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Effect if unset:</term>
+ <term>Parameter:</term>
<listitem>
<para>
- Don't use SOCKS proxies.
+ The name of a content filter, as defined in the <link linkend="filter-file">filter file</link>.
+ Filters can be defined in one or more files as defined by the
+ <literal><link linkend="filterfile">filterfile</link></literal>
+ option in the <link linkend="config">config file</link>.
+ <filename>default.filter</filename> is the collection of filters
+ supplied by the developers. Locally defined filters should go
+ in their own file, such as <filename>user.filter</filename>.
</para>
+ <para>
+ When used in its negative form,
+ and without parameters, <emphasis>all</emphasis> filtering is completely disabled.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>Notes:</term>
<listitem>
<para>
- Multiple lines are OK, they are checked in sequence, and the last match wins.
+ For your convenience, there are a number of pre-defined filters available
+ in the distribution filter file that you can use. See the examples below for
+ a list.
+ </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>
+ <quote>Rolling your own</quote>
+ filters requires a knowledge of
+ <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+ Expressions</quote></ulink> and
+ <ulink url="http://en.wikipedia.org/wiki/Html"><quote>HTML</quote></ulink>.
+ This is very powerful feature, and potentially very intrusive.
+ Filters should be used with caution, and where an equivalent
+ <quote>action</quote> is not available.
+ </para>
+ <para>
+ The amount of data that can be filtered is limited to the
+ <literal><link linkend="buffer-limit">buffer-limit</link></literal>
+ option in the main <link linkend="config">config file</link>. The
+ default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered
+ data, and all pending data, is passed through unfiltered.
+ </para>
+ <para>
+ Inappropriate MIME types, such as zipped files, are not filtered at all.
+ (Again, only text-based types except plain text). Encrypted SSL data
+ (from HTTPS servers) cannot be filtered either, since this would violate
+ the integrity of the secure transaction. In some situations it might
+ be necessary to protect certain text, like source code, from filtering
+ by defining appropriate <literal>-filter</literal> exceptions.
</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.
+ Compressed content can't be filtered either, unless &my-app;
+ is compiled with zlib support (requires at least &my-app; 3.0.7),
+ in which case &my-app; will decompress the content before filtering
+ it.
</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.
+ If you use a &my-app; version without zlib support, but want filtering to work on
+ as much documents as possible, even those that would normally be sent compressed,
+ you must use the <literal><link linkend="prevent-compression">prevent-compression</link></literal>
+ action in conjunction with <literal>filter</literal>.
+ </para>
+ <para>
+ Content filtering can achieve some of the same effects as the
+ <literal><link linkend="block">block</link></literal>
+ action, i.e. it can be used to block ads and banners. But the mechanism
+ works quite differently. One effective use, is to block ad banners
+ based on their size (see below), since many of these seem to be somewhat
+ standardized.
+ </para>
+ <para>
+ <link linkend="contact">Feedback</link> with suggestions for new or
+ improved filters is particularly welcome!
+ </para>
+ <para>
+ The below list has only the names and a one-line description of each
+ predefined filter. There are <link linkend="predefined-filters">more
+ verbose explanations</link> of what these filters do in the <link
+ linkend="filter-file">filter file chapter</link>.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term>Examples:</term>
+ <term>Example usage (with filters from the distribution <filename>default.filter</filename> file).
+ See <link linkend="PREDEFINED-FILTERS">the Predefined Filters section</link> for
+ more explanation on each:</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.
+ <anchor id="filter-js-annoyances">
+ <screen>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse</screen>
</para>
<para>
- <screen>
- forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
- forward .example.com .
- </screen>
+ <anchor id="filter-js-events">
+ <screen>+filter{js-events} # Kill all JS event bindings (Radically destructive! Only for extra nasty sites)</screen>
</para>
<para>
- A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
+ <anchor id="filter-html-annoyances">
+ <screen>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse</screen>
</para>
<para>
- <screen>
- forward-socks4 .*. socks-gw.example.com:1080 .
- </screen>
+ <anchor id="filter-content-cookies">
+ <screen>+filter{content-cookies} # Kill cookies that come in the HTML or JS content</screen>
</para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4><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
- on both isp-a or 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>
-
-</sect4>
-
+ <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-unsolicited-popups">
+ <screen>+filter{unsolicited-popups} # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.</screen>
+ </para>
+ <para>
+ <anchor id="filter-all-popups">
+ <screen>+filter{all-popups} # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.</screen>
+ </para>
+ <para>
+ <anchor id="filter-img-reorder">
+ <screen>+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective</screen>
+ </para>
+ <para>
+ <anchor id="filter-banners-by-size">
+ <screen>+filter{banners-by-size} # Kill banners by size</screen>
+ </para>
+ <para>
+ <anchor id="filter-banners-by-link">
+ <screen>+filter{banners-by-link} # Kill banners by their links to known clicktrackers</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-tiny-textforms">
+ <screen>+filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap</screen>
+ </para>
+ <para>
+ <anchor id="filter-jumping-windows">
+ <screen>+filter{jumping-windows} # Prevent windows from resizing and moving themselves</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-demoronizer">
+ <screen>+filter{demoronizer} # Fix MS's non-standard use of standard charsets</screen>
+ </para>
+ <para>
+ <anchor id="filter-shockwave-flash">
+ <screen>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects</screen>
+ </para>
+ <para>
+ <anchor id="filter-quicktime-kioskmode">
+ <screen>+filter{quicktime-kioskmode} # Make Quicktime movies savable</screen>
+ </para>
+ <para>
+ <anchor id="filter-fun">
+ <screen>+filter{fun} # Text replacements for subversive browsing fun!</screen>
+ </para>
+ <para>
+ <anchor id="filter-crude-parental">
+ <screen>+filter{crude-parental} # Crude parental filtering (demo only)</screen>
+ </para>
+ <para>
+ <anchor id="filter-ie-exploits">
+ <screen>+filter{ie-exploits} # Disable some known Internet Explorer bug exploits</screen>
+ </para>
+ <para>
+ <anchor id="filter-site-specifics">
+ <screen>+filter{site-specifics} # Custom filters for specific site related problems</screen>
+ </para>
+ <para>
+ <anchor id="filter-google">
+ <screen>+filter{google} # Removes text ads and other Google specific improvements</screen>
+ </para>
+ <para>
+ <anchor id="filter-yahoo">
+ <screen>+filter{yahoo} # Removes text ads and other Yahoo specific improvements</screen>
+ </para>
+ <para>
+ <anchor id="filter-msn">
+ <screen>+filter{msn} # Removes text ads and other MSN specific improvements</screen>
+ </para>
+ <para>
+ <anchor id="filter-blogspot">
+ <screen>+filter{blogspot} # Cleans up Blogspot blogs</screen>
+ </para>
+ <para>
+ <anchor id="filter-no-ping">
+ <screen>+filter{no-ping} # Removes non-standard ping attributes from anchor and area tags</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
</sect3>
-<!-- ~ End section ~ -->
-
<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3>
-<title>Windows GUI Options</title>
+<sect3 renderas="sect4" id="force-text-mode">
+<title>force-text-mode</title>
<!--
-Removed references to Win32. HB 09/23/01
+new action
-->
-<para>
- <application>Privoxy</application> has a number of options specific to the
- Windows GUI interface:
-</para>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<para>
- Font size used in the console window:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>log-font-size 8</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<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>
-
-<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>
-
-<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>
- #hide-console
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-</sect3>
-</sect2>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="actionsfile">
-<title>The Actions File</title>
-
-<para>
- The actions file (<filename>default.action</filename>, formerly:
- <filename>actionsfile</filename> or <filename>ijb.action</filename>) is used
- to define what actions <application>Privoxy</application> takes for which
- URLs, and thus determines how ad images, cookies and various other aspects
- of HTTP content and transactions are handled on which sites (or even parts
- thereof).
-</para>
-
-<para>
- Anything you want can blocked, 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 complete list of available actions.
-</para>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3>
-<title>Finding the Right Mix</title>
-<para>
- Note that some actions like cookie suppression or script disabling may
- render some sites unusable, which rely on these techniques to work properly.
- Finding the right mix of actions is not easy and 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 file. 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).
-</para>
-</sect3>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3>
-<title>How to Edit</title>
-<para>
- The easiest way to edit the <quote>actions</quote> file is with a browser by
- using our browser-based editor, which is available at <ulink
- url="http://config.privoxy.org/edit-actions">http://config.privoxy.org/edit-actions</ulink>.
-</para>
-
-<para>
- If you prefer plain text editing to GUIs, you can of course also directly edit the
- <filename>default.action</filename> file.
-</para>
-</sect3>
-
-
-<sect3>
-<title>How Actions are Applied to URLs</title>
-<para>
- The actions file is divided into sections. There are special sections,
- like the alias 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 this 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.
-</para>
-
-<para>
- You can trace this process 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>
-</sect3>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3>
-<title>Patterns</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:
-</para>
-
<variablelist>
<varlistentry>
- <term><literal>www.example.com</literal></term>
+ <term>Typical use:</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>
+ <para>Force <application>Privoxy</application> to treat a document as if it was in some kind of <emphasis>text</emphasis> format. </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><literal>www.example.com/</literal></term>
+ <term>Effect:</term>
<listitem>
<para>
- means exactly the same.
- </para>
+ Declares a document as text, even if the <quote>Content-Type:</quote> isn't detected as such.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><literal>www.example.com/index.html</literal></term>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
<listitem>
<para>
- matches only the single document <literal>/index.html</literal>
- on <literal>www.example.com</literal>.
+ N/A
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><literal>/index.html</literal></term>
+ <term>Notes:</term>
<listitem>
<para>
- matches the document <literal>/index.html</literal>, regardless of the domain,
- i.e. on <emphasis>any</emphasis> web server.
- </para>
+ As explained <literal><link linkend="filter">above</link></literal>,
+ <application>Privoxy</application> tries to only filter files that are
+ in some kind of text format. The same restrictions apply to
+ <literal><link linkend="content-type-overwrite">content-type-overwrite</link></literal>.
+ <literal>force-text-mode</literal> declares a document as text,
+ without looking at the <quote>Content-Type:</quote> first.
+ </para>
+ <warning>
+ <para>
+ Think twice before activating this action. Filtering binary data
+ with regular expressions can cause file damage.
+ </para>
+ </warning>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><literal>index.html</literal></term>
+ <term>Example usage:</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>.
+ <screen>
++force-text-mode
+ </screen>
</para>
</listitem>
</varlistentry>
</variablelist>
+</sect3>
-<sect4><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>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="forward-override">
+<title>forward-override</title>
+<!--
+new action
+-->
<variablelist>
<varlistentry>
- <term><literal>.example.com</literal></term>
+ <term>Typical use:</term>
<listitem>
- <para>
- matches any domain that <emphasis>ENDS</emphasis> in
- <literal>.example.com</literal>
- </para>
+ <para>Change the forwarding settings based on User-Agent or request origin</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><literal>www.</literal></term>
+ <term>Effect:</term>
<listitem>
<para>
- matches any domain that <emphasis>STARTS</emphasis> with
- <literal>www.</literal>
- </para>
+ Overrules the forward directives in the configuration files.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><literal>.example.</literal></term>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
<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>
+ <para>Multi-value.</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>
+ <term>Parameter:</term>
<listitem>
- <para>
- matches <quote>adserver.example.com</quote>,
- <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
- </para>
+ <itemizedlist>
+ <listitem>
+ <para><quote>forward .</quote> to use a direct connection without any additional proxies.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <quote>forward 127.0.0.1:8123</quote> to use the HTTP proxy listening at 127.0.0.1 port 8123.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <quote>forward-socks4a 127.0.0.1:9050 .</quote> to use the socks4a proxy listening at 127.0.0.1 port 9050.
+ Replace <quote>forward-socks4a</quote> with <quote>forward-socks4</quote> to use a socks4 connection (with local DNS
+ resolution) instead.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <quote>forward-socks4a 127.0.0.1:9050 proxy.example.org:8000</quote> to use the socks4a proxy
+ listening at 127.0.0.1 port 9050 to reach the HTTP proxy listening at proxy.example.org port 8000.
+ Replace <quote>forward-socks4a</quote> with <quote>forward-socks4</quote> to use a socks4 connection (with local DNS
+ resolution) instead.
+ </para>
+ </listitem>
+ </itemizedlist>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><literal>*ad*.example.com</literal></term>
+ <term>Notes:</term>
<listitem>
<para>
- matches all of the above, and then some.
+ This action takes parameters similar to the <!-- I hope this link actual works -->
+ <link linkend="forwarding">forward</link> directives in the configuration
+ file, but without the URL pattern. It can be used as replacement, but normally it's only
+ used in cases where matching based on the request URL isn't sufficient.
</para>
+ <warning>
+ <para>
+ Please read the description for the <link linkend="forwarding">forward</link> directives before
+ using this action. Forwarding to the wrong people will reduce your privacy and increase the
+ chances of man-in-the-middle attacks.
+ </para>
+ <para>
+ If the ports are missing or invalid, default values will be used. This might change
+ in the future and you shouldn't rely on it. Otherwise incorrect syntax causes Privoxy
+ to exit.
+ </para>
+ <para>
+ Use the <ulink url="http://config.privoxy.org/show-url-info">show-url-info CGI page</ulink>
+ to verify that your forward settings do what you thought the do.
+ </para>
+ </warning>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><literal>.?pix.com</literal></term>
+ <term>Example usage:</term>
<listitem>
<para>
- matches <literal>www.ipix.com</literal>,
- <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc.
+ <screen>
+# Always use direct connections for requests previously tagged as
+# <quote>User-Agent: fetch libfetch/2.0</quote> and make sure
+# resuming downloads continues to work.
+# This way you can continue to use Tor for your normal browsing,
+# without overloading the Tor network with your FreeBSD ports updates
+# or downloads of bigger files like ISOs.
+{+forward-override{forward .} \
+ -hide-if-modified-since \
+ -overwrite-last-modified \
+}
+TAG:^User-Agent: fetch libfetch/2.0$
+ </screen>
</para>
</listitem>
</varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="handle-as-empty-document">
+<title>handle-as-empty-document</title>
+<!--
+new action
+-->
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Mark URLs that should be replaced by empty documents <emphasis>if they get blocked</emphasis></para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
- <term><literal>www[1-9a-ez].example.c*</literal></term>
+ <term>Effect:</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>.
+ This action alone doesn't do anything noticeable. It just marks URLs.
+ 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 an empty document will be sent to the client as a substitute for the blocked content.
+ The <emphasis>empty</emphasis> document isn't literally empty, but actually contains a single space.
</para>
</listitem>
</varlistentry>
-</variablelist>
-</sect4>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
-<sect4><title>The Path Pattern</title>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <application>Privoxy</application> uses Perl compatible regular expressions
- (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
- matching the path.
-</para>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Some browsers complain about syntax errors if JavaScript documents
+ are blocked with <application>Privoxy's</application>
+ default HTML page; this option can be used to silence them.
+ And of course this action can also be used to eliminate the &my-app;
+ BLOCKED message in frames.
+ </para>
+ <para>
+ The content type for the empty document can be specified with
+ <literal><link linkend="content-type-overwrite">content-type-overwrite{}</link></literal>,
+ but usually this isn't necessary.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- 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>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen># Block all documents on example.org that end with ".js",
+# but send an empty document instead of the usual HTML message.
+{+block +handle-as-empty-document}
+example.org/.*\.js$
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<para>
- Note that the pattern is automatically left-anchored at the <quote>/</quote>,
- i.e. it matches as if it would start with a <quote>^</quote>.
-</para>
-<para>
- 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>
-</sect4>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="handle-as-image">
+<title>handle-as-image</title>
-</sect3>
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Mark URLs as belonging to images (so they'll be replaced by images <emphasis>if they do get blocked</emphasis>, rather than HTML pages)</para>
+ </listitem>
+ </varlistentry>
-<!-- ~ End section ~ -->
+ <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>
+ <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 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, (in-line) 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>
-<!-- ~~~~~ New section ~~~~~ -->
+ <varlistentry>
+ <term>Example usage (sections):</term>
+ <listitem>
+ <para>
+ <screen># Generic image extensions:
+#
+{+handle-as-image}
+/.*\.(gif|jpg|jpeg|png|bmp|ico)$
-<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:
-</para>
+# 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
-<para>
- <itemizedlist>
+# Banner source! Who cares if they also have non-image content?
+ad.doubleclick.net
+</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
- <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>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="hide-accept-language">
+<title>hide-accept-language</title>
+<!--
+new action
+-->
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Pretend to use different language settings.</para>
+ </listitem>
+ </varlistentry>
- <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>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes or replaces the <quote>Accept-Language:</quote> HTTP header in client requests.
+ </para>
+ </listitem>
+ </varlistentry>
- </itemizedlist>
-</para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
-<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).
-</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>
+ Faking the browser's language settings can be useful to make a
+ foreign User-Agent set with
+ <literal><link linkend="hide-user-agent">hide-user-agent</link></literal>
+ more believable.
+ </para>
+ <para>
+ However some sites with content in different languages check the
+ <quote>Accept-Language:</quote> to decide which one to take by default.
+ Sometimes it isn't possible to later switch to another language without
+ changing the <quote>Accept-Language:</quote> header first.
+ </para>
+ <para>
+ Therefore it's a good idea to either only change the
+ <quote>Accept-Language:</quote> header to languages you understand,
+ or to languages that aren't wide spread.
+ </para>
+ <para>
+ Before setting the <quote>Accept-Language:</quote> header
+ to a rare language, you should consider that it helps to
+ make your requests unique and thus easier to trace.
+ If you don't plan to change this header frequently,
+ you should stick to a common language.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Later defined actions always over-ride earlier ones. So exceptions
- to any rules you make, should come in the latter part of the file. For
- multi-valued actions, the actions are applied in the order they are
- specified.
-</para>
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen># Pretend to use Canadian language settings.
+{+hide-accept-language{en-ca} \
++hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \
+}
+/ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
-<para>
- The list of valid <application>Privoxy</application> <quote>actions</quote> are:
-</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, and an option to see it anyway.
- The page displayed for this is the <quote>blocked</quote> template
- file.
- </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>
-
- <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:
- <emphasis>http://some.place/some_script?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>
- 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>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="hide-content-disposition">
+<title>hide-content-disposition</title>
+<!--
+new action
+-->
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Prevent download menus for content you prefer to view inside the browser.</para>
+ </listitem>
+ </varlistentry>
- <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. <application>Filters</application> can be used to
- re-write any of the raw page content. This is a potentially a
- very powerful feature!
- </para>
-
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+filter{section_header}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes or replaces the <quote>Content-Disposition:</quote> HTTP header set by some servers.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- Filter sections that are pre-defined in the supplied
- <filename>default.filter</filename> include:
- </para>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
- <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-popups</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>
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ Keyword: <quote>block</quote>, or any user defined value.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Some servers set the <quote>Content-Disposition:</quote> HTTP header for
+ documents they assume you want to save locally before viewing them.
+ The <quote>Content-Disposition:</quote> header contains the file name
+ the browser is supposed to use by default.
+ </para>
+ <para>
+ In most browsers that understand this header, it makes it impossible to
+ <emphasis>just view</emphasis> the document, without downloading it first,
+ even if it's just a simple text file or an image.
+ </para>
+ <para>
+ Removing the <quote>Content-Disposition:</quote> header helps
+ to prevent this annoyance, but some browsers additionally check the
+ <quote>Content-Type:</quote> header, before they decide if they can
+ display a document without saving it first. In these cases, you have
+ to change this header as well, before the browser stops displaying
+ download menus.
+ </para>
+ <para>
+ It is also possible to change the server's file name suggestion
+ to another one, but in most cases it isn't worth the time to set
+ it up.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen># Disarm the download link in Sourceforge's patch tracker
+{ -filter \
+ +content-type-overwrite{text/plain}\
+ +hide-content-disposition{block} }
+ .sourceforge.net/tracker/download\.php</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="hide-if-modified-since">
+<title>hide-if-modified-since</title>
+<!--
+new action
+-->
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Prevent yet another way to track the user's steps between sessions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes the <quote>If-Modified-Since:</quote> HTTP client header or modifies its value.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ Keyword: <quote>block</quote>, or a user defined value that specifies a range of hours.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Removing this header is useful for filter testing, where you want to force a real
+ reload instead of getting status code <quote>304</quote>, which would cause the
+ browser to use a cached copy of the page.
+ </para>
+ <para>
+ Instead of removing the header, <literal>hide-if-modified-since</literal> can
+ also add or subtract a random amount of time to/from the header's value.
+ You specify a range of minutes where the random factor should be chosen from and
+ <application>Privoxy</application> does the rest. A negative value means
+ subtracting, a positive value adding.
+ </para>
+ <para>
+ Randomizing the value of the <quote>If-Modified-Since:</quote> makes
+ sure it isn't used as a cookie replacement, but you will run into
+ caching problems if the random range is too high.
+ </para>
+ <para>
+ It is a good idea to only use a small negative value and let
+ <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>
+ handle the greater changes.
+ </para>
+ <para>
+ It is also recommended to use this action together with
+ <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen># Let the browser revalidate without being tracked across sessions
+{ +hide-if-modified-since{-60} \
+ +overwrite-last-modified{randomize} \
+ +crunch-if-none-match}
+/</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="hide-forwarded-for-headers">
+<title>hide-forwarded-for-headers</title>
+<!--
+new action
+-->
+<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>
+
+ <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>
+ 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>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+hide-forwarded-for-headers</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="hide-from-header">
+<title>hide-from-header</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Keep your (old and ill) browser from telling web servers your email address</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes any existing <quote>From:</quote> HTTP header, or replaces it with the
+ specified string.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <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>
+
+ <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>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="hide-referrer">
+<title>hide-referrer</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>
+
+ <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>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para><quote>conditional-block</quote> to delete the header completely if the host has changed.</para>
+ </listitem>
+ <listitem>
+ <para><quote>block</quote> to delete the header unconditionally.</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>
+ <literal>conditional-block</literal> is the only parameter,
+ that isn't easily detected in the server's log file. If it blocks the
+ referrer, the request will look like the visitor used a bookmark or
+ typed in the address directly.
+ </para>
+ <para>
+ Leaving the referrer unmodified for requests on the same host
+ allows the server owner to see the visitor's <quote>click path</quote>,
+ but in most cases she could also get that information by comparing
+ other parts of the log file: for example the User-Agent if it isn't
+ a very common one, or the user's IP address if it doesn't change between
+ different requests.
+ </para>
+ <para>
+ Always blocking the referrer, or using a custom one, can lead to
+ failures on servers that check the referrer before they answer any
+ requests, in an attempt to prevent their valuable content from being
+ embedded or linked to elsewhere.
+ </para>
+ <para>
+ Both <literal>conditional-block</literal> and <literal>forge</literal>
+ will work with referrer checks, as long as content and valid referring page
+ are on the same host. Most of the time that's the case.
+ </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>
+
+ <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>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="hide-user-agent">
+<title>hide-user-agent</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Conceal your type of browser and client operating system</para>
+ </listitem>
+ </varlistentry>
+
+ <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>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ Any user-defined string.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <warning>
+ <para>
+ This can lead to problems on 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> the right thing to do: good web sites
+ work browser-independently).
+ <!--
+ <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>
+
+ <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="inspect-jpegs">
+<title>inspect-jpegs</title>
+<!--
+new action
+-->
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>To protect against the MS buffer over-run in JPEG processing</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Protect against a known exploit
+ </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>
+ See Microsoft Security Bulletin MS04-028. JPEG images are one of the most
+ common image types found across the Internet. The exploit as described can
+ allow execution of code on the target system, giving an attacker access
+ to the system in question by merely planting an altered JPEG image, which
+ would have no obvious indications of what lurks inside. This action
+ prevents unwanted intrusion.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para><screen>+inspect-jpegs</screen></para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="kill-popups">
+<title>kill-popups<anchor id="kill-popup"></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Eliminate those annoying pop-up windows (deprecated)</para>
+ </listitem>
+ </varlistentry>
+
+ <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>
+
+ <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>
+ This action is basically a built-in, hardwired special-purpose filter
+ 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-ALL-POPUPS">filter{<replaceable>all-popups</replaceable>}</link></literal>
+ does and is not as smart as <literal><link
+ linkend="FILTER-UNSOLICITED-POPUPS">filter{<replaceable>unsolicited-popups</replaceable>}</link>
+ </literal>is.
+ </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 unconditionally is problematic. Many shops and banks rely on
+ pop-ups to display forms, shopping carts etc, and the <literal><link
+ linkend="FILTER-UNSOLICITED-POPUPS">filter{<replaceable>unsolicited-popups</replaceable>}</link>
+ </literal> does a better job of catching only the unwanted ones.
+ </para>
+ <para>
+ 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>
+ This action is most appropriate for browsers that don't have any controls
+ for unwanted pop-ups. Not recommended for general usage.
+ </para>
+
+ <!--
+ <para>
+ An alternate spelling is <literal>+kill-popup</literal>, which is
+ interchangeable.
+ </para>
+ -->
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para><screen>+kill-popups</screen></para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="limit-connect">
+<title>limit-connect</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Prevent abuse of <application>Privoxy</application> as a TCP proxy relay or disable SSL for untrusted sites</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Specifies to which ports HTTP CONNECT requests are allowable.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <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>
+
+ <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>
+ <application>Privoxy</application> relays HTTPS traffic without seeing
+ the decoded content. Websites can leverage this limitation to circumvent &my-app;'s
+ filters. By specifying an invalid port range you can disable HTTPS entirely.
+ If you plan to disable SSL by default, consider enabling
+ <literal><link linkend="treat-forbidden-connects-like-blocks ">treat-forbidden-connects-like-blocks</link></literal>
+ as well, to be able to quickly create exceptions.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <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
++limit-connect{,} # No HTTPS/SSL traffic is allowed</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="prevent-compression">
+<title>prevent-compression</title>
+
+<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>
+ Removes the Accept-Encoding header which can be used to ask for compressed transfer.
+ </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>
+ More and more websites send their content compressed by default, which
+ is generally a good idea and saves bandwidth. But 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 need
+ access to the uncompressed data.
+ </para>
+ <para>
+ When compiled with zlib support (available since &my-app; 3.0.7), content that should be
+ filtered is decompressed on-the-fly and you don't have to worry about this action.
+ If you are using an older &my-app; version, or one that hasn't been compiled with zlib
+ support, this action can be used to convince the server to send the content uncompressed.
+ </para>
+ <para>
+ Most text-based instances compress very well, the size is seldom decreased by less than 50%,
+ for markup-heavy instances like news feeds saving more than 90% of the original size isn't
+ unusual.
+ </para>
+ <para>
+ Not using compression will therefore slow down the transfer, and you should only
+ enable this action if you really need it. As of &my-app; 3.0.7 it's disabled in all
+ predefined action settings.
+ </para>
+ <para>
+ Note that some (rare) ill-configured sites don't handle requests for uncompressed
+ documents correctly. Broken PHP applications tend to send an empty document body,
+ some IIS versions only send the beginning of the content. If you enable
+ <literal>prevent-compression</literal> per default, you might want to add
+ exceptions for those sites. See the example for how to do that.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (sections):</term>
+ <listitem>
+ <para>
+ <screen>
+# Selectively turn off compression, and enable a filter
+#
+{ +filter{tiny-textforms} +prevent-compression }
+# Match only these sites
+ .google.
+ sourceforge.net
+ sf.net
+
+# Or instead, we could set a universal default:
+#
+{ +prevent-compression }
+ / # Match all sites
+
+# Then maybe make exceptions for broken sites:
+#
+{ -prevent-compression }
+.compusa.com/</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="overwrite-last-modified">
+<title>overwrite-last-modified</title>
+<!--
+new action
+-->
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Prevent yet another way to track the user's steps between sessions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes the <quote>Last-Modified:</quote> HTTP server header or modifies its value.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ One of the keywords: <quote>block</quote>, <quote>reset-to-request-time</quote>
+ and <quote>randomize</quote>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Removing the <quote>Last-Modified:</quote> header is useful for filter
+ testing, where you want to force a real reload instead of getting status
+ code <quote>304</quote>, which would cause the browser to reuse the old
+ version of the page.
+ </para>
+ <para>
+ The <quote>randomize</quote> option overwrites the value of the
+ <quote>Last-Modified:</quote> header with a randomly chosen time
+ between the original value and the current time. In theory the server
+ could send each document with a different <quote>Last-Modified:</quote>
+ header to track visits without using cookies. <quote>Randomize</quote>
+ makes it impossible and the browser can still revalidate cached documents.
+ </para>
+ <para>
+ <quote>reset-to-request-time</quote> overwrites the value of the
+ <quote>Last-Modified:</quote> header with the current time. You could use
+ this option together with
+ <literal><link linkend="hide-if-modified-since">hided-if-modified-since</link></literal>
+ to further customize your random range.
+ </para>
+ <para>
+ The preferred parameter here is <quote>randomize</quote>. It is safe
+ to use, as long as the time settings are more or less correct.
+ If the server sets the <quote>Last-Modified:</quote> header to the time
+ of the request, the random range becomes zero and the value stays the same.
+ Therefore you should later randomize it a second time with
+ <literal><link linkend="hide-if-modified-since">hided-if-modified-since</link></literal>,
+ just to be sure.
+ </para>
+ <para>
+ It is also recommended to use this action together with
+ <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen># Let the browser revalidate without being tracked across sessions
+{ +hide-if-modified-since{-60} \
+ +overwrite-last-modified{randomize} \
+ +crunch-if-none-match}
+/</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="redirect">
+<title>redirect</title>
+<!--
+new action
+-->
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Redirect requests to other sites.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Convinces the browser that the requested document has been moved
+ to another location and the browser should get it from there.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ An absolute URL or a single pcrs command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Requests to which this action applies are answered with a
+ HTTP redirect to URLs of your choosing. The new URL is
+ either provided as parameter, or derived by applying a
+ single pcrs command to the original URL.
+ </para>
+ <para>
+ This action will be ignored if you use it together with
+ <literal><link linkend="block">block</link></literal>.
+ It can be combined with
+ <literal><link linkend="fast-redirects">fast-redirects{check-decoded-url}</link></literal>
+ to redirect to a decoded version of a rewritten URL.
+ </para>
+ <para>
+ Use this action carefully, make sure not to create redirection loops
+ and be aware that using your own redirects might make it
+ possible to fingerprint your requests.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usages:</term>
+ <listitem>
+ <para>
+ <screen># Replace example.com's style sheet with another one
+{ +redirect{http://localhost/css-replacements/example.com.css} }
+ example.com/stylesheet\.css
+
+# Create a short, easy to remember nickname for a favorite site
+# (relies on the browser accept and forward invalid URLs to &my-app;)
+{ +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
+ a
+
+# Always use the expanded view for Undeadly.org articles
+# (Note the $ at the end of the URL pattern to make sure
+# the request for the rewritten URL isn't redirected as well)
+{+redirect{s@$@&mode=expanded@}}
+undeadly.org/cgi\?action=article&sid=\d*$</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="send-vanilla-wafer">
+<title>send-vanilla-wafer</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Feed log analysis scripts with useless data.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <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>
+
+ <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>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+send-vanilla-wafer</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="send-wafer">
+<title>send-wafer</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Send custom cookies or feed log analysis scripts with even more useless data.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Sends a custom, user-defined cookie with each request.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Multi-value.</para>
+ </listitem>
+ </varlistentry>
+
+ <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>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="server-header-filter">
+<title>server-header-filter</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Rewrite or remove single server headers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ All server headers to which this action applies are filtered on-the-fly
+ through the specified regular expression based substitutions.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ The name of a server-header filter, as defined in one of the
+ <link linkend="filter-file">filter files</link>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Server-header filters are applied to each header on its own, not to
+ all at once. This makes it easier to diagnose problems, but on the downside
+ you can't write filters that only change header x if header y's value is z.
+ You can do that by using tags though.
+ </para>
+ <para>
+ Server-header filters are executed after the other header actions have finished
+ and use their output as input.
+ </para>
+ <para>
+ Please refer to the <link linkend="filter-file">filter file chapter</link>
+ to learn which server-header filters are available by default, and how to
+ create your own.
+ </para>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>
+{+server-header-filter{html-to-xml}}
+example.org/xml-instance-that-is-delivered-as-html
+
+{+server-header-filter{xml-to-html}}
+example.org/instance-that-is-delivered-as-xml-but-is-not
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="server-header-tagger">
+<title>server-header-tagger</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Disable or disable filters based on the Content-Type header.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Server headers to which this action applies are filtered on-the-fly through
+ the specified regular expression based substitutions, the result is used as
+ tag.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ The name of a server-header tagger, as defined in one of the
+ <link linkend="filter-file">filter files</link>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Server-header taggers are applied to each header on its own,
+ and as the header isn't modified, each tagger <quote>sees</quote>
+ the original.
+ </para>
+ <para>
+ Server-header taggers are executed before all other header actions
+ that modify server headers. Their tags can be used to control
+ all of the other server-header actions, the content filters
+ and the crunch actions (<link linkend="redirect">redirect</link>
+ and <link linkend="block">block</link>).
+ </para>
+ <para>
+ Obviously crunching based on tags created by server-header taggers
+ doesn't prevent the request from showing up in the server's log file.
+ </para>
+
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>
+# Tag every request with the declared content type
+{+client-header-filter{content-type}}
+/
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="session-cookies-only">
+<title>session-cookies-only</title>
+
+<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>
+
+ <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>
+
+<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>
+ 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>
+ <para>
+ This setting also has no effect on cookies that may have been stored
+ previously by the browser before starting <application>Privoxy</application>.
+ These would have to be removed manually.
+ </para>
+ <para>
+ <application>Privoxy</application> also uses
+ the <link linkend="filter-content-cookies">content-cookies filter</link>
+ to block some types of cookies. Content cookies are not effected by
+ <literal>session-cookies-only</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <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>set-image-blocker</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Choose the replacement for blocked images</para>
+ </listitem>
+ </varlistentry>
+
+ <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>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <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.
+ (But note that not all browsers support redirecting to a local file system).
+ </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>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ Built-in pattern:
+ </para>
+ <para>
+ <screen>+set-image-blocker{pattern}</screen>
+ </para>
+ <para>
+ Redirect to the BSD daemon:
+ </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>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="treat-forbidden-connects-like-blocks">
+<title>treat-forbidden-connects-like-blocks</title>
+<!--
+new action
+-->
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Block forbidden connects with an easy to find error message.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ If this action is enabled, <application>Privoxy</application> no longer
+ makes a difference between forbidden connects and ordinary blocks.
+ </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>
+ By default <application>Privoxy</application> answers
+ <link linkend="limit-connect">forbidden <quote>Connect</quote> requests</link>
+ with a short error message inside the headers. If the browser doesn't display
+ headers (most don't), you just see an empty page.
+ </para>
+ <para>
+ With this action enabled, <application>Privoxy</application> displays
+ the message that is used for ordinary blocks instead. If you decide
+ to make an exception for the page in question, you can do so by
+ following the <quote>See why</quote> link.
+ </para>
+ <para>
+ For <quote>Connect</quote> requests the clients tell
+ <application>Privoxy</application> which host they are interested
+ in, but not which document they plan to get later. As a result, the
+ <quote>Go there anyway</quote> wouldn't work and is therefore suppressed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+treat-forbidden-connects-like-blocks</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3>
+<title>Summary</title>
+<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, 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>
+ 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>
+ 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>
+ 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>
+ 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.
+</para>
+
+<para>
+ Now let's define some aliases...
+</para>
+
+<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}}
+
+ # These aliases just save typing later:
+ # (Note that some already use other aliases!)
+ #
+ +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
+ -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
+ +block-as-image = +block +handle-as-image
+ allow-all-cookies = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
+
+ # These aliases define combinations of actions
+ # that are useful for certain types of sites:
+ #
+ fragile = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link> -<link linkend="KILL-POPUPS">kill-popups</link> -<link linkend="PREVENT-COMPRESSION">prevent-compression</link>
+
+ shop = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> -<link linkend="KILL-POPUPS">kill-popups</link>
+
+ # Short names for other aliases, for really lazy people ;-)
+ #
+ c0 = +crunch-all-cookies
+ c1 = -crunch-all-cookies</screen>
+</para>
+
+<para>
+ ...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>
+ <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
+ # Gmail is really mail.google.com, not gmail.com
+ mail.google.com
+
+ # Shopping sites:
+ # Allow cookies (for setting and retrieving your customer data)
+ #
+ {shop}
+ .quietpc.com
+ .worldpay.com # for quietpc.com
+ mybank.example.com
+
+ # These shops require pop-ups:
+ #
+ {-kill-popups -filter{all-popups} -filter{unsolicited-popups}}
+ .dabs.com
+ .overclockers.co.uk</screen>
+</para>
+
+<para>
+ Aliases like <quote>shop</quote> and <quote>fragile</quote> are typically used for
+ <quote>problem</quote> sites that require more than one action to be disabled
+ in order to function properly.
+</para>
+</sect2>
+<!--
+hal stop here
+-->
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="act-examples">
+<title>Actions Files Tutorial</title>
+<para>
+ 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>
+Every config file should start with a short comment stating its purpose:
+</para>
+
+<para>
+ <screen># Sample default.action file <ijbswa-developers@lists.sourceforge.net></screen>
+</para>
+
+<para>
+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>
+
+<para>
+ <screen>
+##########################################################################
+# Settings -- Don't change! For internal Privoxy use ONLY.
+##########################################################################
+
+{{settings}}
+for-privoxy-version=3.0</screen>
+</para>
+
+<para>
+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>
+ <screen>
+##########################################################################
+# Aliases
+##########################################################################
+{{alias}}
+
+ # These aliases just save typing later:
+ # (Note that some already use other aliases!)
+ #
+ +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
+ -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
+ +block-as-image = +block +handle-as-image
+ mercy-for-cookies = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
+
+ # These aliases define combinations of actions
+ # that are useful for certain types of sites:
+ #
+ fragile = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link> -<link linkend="KILL-POPUPS">kill-popups</link>
+ shop = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> -<link linkend="KILL-POPUPS">kill-popups</link></screen>
+</para>
+
+<para>
+ 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>
+ 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>
+
+<para>
+ <screen>
+##########################################################################
+# "Defaults" section:
+##########################################################################
+ { \
+ -<link linkend="ADD-HEADER">add-header</link> \
+ -<link linkend="CLIENT-HEADER-FILTER">client-header-filter{hide-tor-exit-notation}</link> \
+ -<link linkend="BLOCK">block</link> \
+ -<link linkend="CONTENT-TYPE-OVERWRITE">content-type-overwrite</link> \
+ -<link linkend="CRUNCH-CLIENT-HEADER">crunch-client-header</link> \
+ -<link linkend="CRUNCH-IF-NONE-MATCH">crunch-if-none-match</link> \
+ -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> \
+ -<link linkend="CRUNCH-SERVER-HEADER">crunch-server-header</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{check-decoded-url}</link> \
+ -<link linkend="FILTER-JS-ANNOYANCES">filter{js-annoyances}</link> \
+ -<link linkend="FILTER-JS-EVENTS">filter{js-events}</link> \
+ +<link linkend="FILTER-HTML-ANNOYANCES">filter{html-annoyances}</link> \
+ -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link> \
+ +<link linkend="FILTER-REFRESH-TAGS">filter{refresh-tags}</link> \
+ -<link linkend="FILTER-UNSOLICITED-POPUPS">filter{unsolicited-popups}</link> \
+ -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> \
+ -<link linkend="FILTER-IMG-REORDER">filter{img-reorder}</link> \
+ -<link linkend="FILTER-BANNERS-BY-SIZE">filter{banners-by-size}</link> \
+ -<link linkend="FILTER-BANNERS-BY-LINK">filter{banners-by-link}</link> \
+ +<link linkend="FILTER-WEBBUGS">filter{webbugs}</link> \
+ -<link linkend="FILTER-TINY-TEXTFORMS">filter{tiny-textforms}</link> \
+ -<link linkend="FILTER-JUMPING-WINDOWS">filter{jumping-windows}</link> \
+ -<link linkend="FILTER-FRAMESET-BORDERS">filter{frameset-borders}</link> \
+ -<link linkend="FILTER-DEMORONIZER">filter{demoronizer}</link> \
+ -<link linkend="FILTER-SHOCKWAVE-FLASH">filter{shockwave-flash}</link> \
+ -<link linkend="FILTER-QUICKTIME-KIOSKMODE">filter{quicktime-kioskmode}</link> \
+ -<link linkend="FILTER-FUN">filter{fun}</link> \
+ -<link linkend="FILTER-CRUDE-PARENTAL">filter{crude-parental}</link> \
+ +<link linkend="FILTER-IE-EXPLOITS">filter{ie-exploits}</link> \
+ -<link linkend="FILTER-GOOGLE">filter{google}</link> \
+ -<link linkend="FILTER-YAHOO">filter{yahoo}</link> \
+ -<link linkend="FILTER-MSN">filter{msn}</link> \
+ -<link linkend="FILTER-BLOGSPOT">filter{blogspot}</link> \
+ -<link linkend="FILTER-NO-PING">filter{no-ping}</link> \
+ -<link linkend="FORCE-TEXT-MODE">force-text-mode</link> \
+ -<link linkend="HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document</link> \
+ -<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> \
+ -<link linkend="HIDE-ACCEPT-LANGUAGE">hide-accept-language</link> \
+ -<link linkend="HIDE-CONTENT-DISPOSITION">hide-content-disposition</link> \
+ -<link linkend="HIDE-IF-MODIFIED-SINCE">hide-if-modified-since</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="INSPECT-JPEGS">inspect-jpegs</link> \
+ -<link linkend="KILL-POPUPS">kill-popups</link> \
+ -<link linkend="LIMIT-CONNECT">limit-connect</link> \
+ +<link linkend="PREVENT-COMPRESSION">prevent-compression</link> \
+ -<link linkend="OVERWRITE-LAST-MODIFIED">overwrite-last-modified</link> \
+ -<link linkend="REDIRECT">redirect</link> \
+ -<link linkend="SEND-VANILLA-WAFER">send-vanilla-wafer</link> \
+ -<link linkend="SEND-WAFER">send-wafer</link> \
+ -<link linkend="SERVER-HEADER-FILTER">server-header-filter{xml-to-html}</link> \
+ -<link linkend="SERVER-HEADER-FILTER">server-header-filter{html-to-xml}</link> \
+ +<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> \
+ +<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
+ -<link linkend="TREAT-FORBIDDEN-CONNECTS-LIKE-BLOCKS">treat-forbidden-connects-like-blocks</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.
+</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>
+ <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
+mail.google.com</screen>
+</para>
+
+<para>
+ 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>
+ <screen>
+# Shopping sites:
+#
+{ shop }
+.quietpc.com
+.worldpay.com # for quietpc.com
+.jungle.com
+.scan.co.uk</screen>
+</para>
+
+<!-- No longer needed BEGIN OF COMMENTED OUT BLOCK
+
+<para>
+ 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-ALL-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>
+ <screen>
+# These sites require pop-ups too :(
+#
+{ -<link linkend="KILL-POPUPS">kill-popups</link> -<link linkend="FILTER-ALL-POPUPS">filter{popups}</link> }
+.dabs.com
+.overclockers.co.uk
+.deutsche-bank-24.de</screen>
+</para>
+
+ END OF COMMENTED OUT BLOCK -->
+
+<para>
+ 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>
+ <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>
+ 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>
+ <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>
+ 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>
+ <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
+.qkimg.net</screen>
+</para>
+
+<para>
+ One of the most important jobs of <application>Privoxy</application>
+ is to block banners. Many of these can be <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>
+ First comes many 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>
+ <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>
+ It's quite remarkable 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>
+ 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>
+ 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>
+
+<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)
+adobe. # (has nothing to do with ads either)
+ad[ud]*. # (adult.* and add.*)
+.edu # (universities don't host banners (yet!))
+.*loads. # (downloads, uploads etc)
+
+# By path:
+#
+/.*loads/
+
+# Site-specific:
+#
+www.globalintersec.com/adv # (adv = advanced)
+www.ugu.com/sui/ugu/adv</screen>
+</para>
+
+<para>
+ 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>
+ <screen>
+# Don't filter code!
+#
+{ -<link linkend="FILTER">filter</link> }
+/(.*/)?cvs
+bugzilla.
+developer.
+wiki.
+.sourceforge.net</screen>
+</para>
+
+<para>
+ The actual <filename>default.action</filename> is of course much more
+ comprehensive, but we hope this example made clear how it works.
+</para>
+
+</sect3>
+
+<sect3><title>user.action</title>
+
+<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 might 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>
+ 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>
+ <screen>
+# My user.action file. <fred@foobar.com></screen>
+</para>
+
+<para>
+ 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>
+ <screen>
+# Aliases are local to the file they are defined in.
+# (Re-)define aliases for this file:
+#
+{{alias}}
+#
+# These aliases just save typing later, and the alias names should
+# be self explanatory.
+#
++crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
+-crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
+ allow-all-cookies = -crunch-all-cookies -session-cookies-only
+ allow-popups = -filter{all-popups} -kill-popups
++block-as-image = +block +handle-as-image
+-block-as-image = -block
+
+# These aliases define combinations of actions that are useful for
+# certain types of sites:
+#
+fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer -kill-popups
+shop = -crunch-all-cookies allow-popups
+
+# Allow ads for selected useful free sites:
+#
+allow-ads = -block -filter{banners-by-size} -filter{banners-by-link}
+
+# Alias for specific file types that are text, but might have conflicting
+# MIME types. We want the browser to force these to be text documents.
+handle-as-text = -<link linkend="FILTER">filter</link> +-<link linkend="content-type-overwrite">content-type-overwrite{text/plain}</link> +-<link linkend="FORCE-TEXT-MODE">force-text-mode</link> -<link linkend="HIDE-CONTENT-DISPOSITION">hide-content-disposition</link></screen>
+
+</para>
+
+<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>allow-all-cookies</literal> alias defined above does exactly
+ that, i.e. it disables crunching of cookies in any direction, and the
+ processing of cookies to make them only temporary.
+</para>
+
+<para>
+ <screen>
+{ allow-all-cookies }
+ sourceforge.net
+ .yahoo.com
+ .msdn.microsoft.com
+ .redhat.com</screen>
+</para>
+
+<para>
+ Your bank is allergic to some filter, but you don't know which, so you disable them all:
+</para>
+
+<para>
+ <screen>
+{ -<link linkend="FILTER">filter</link> }
+ .your-home-banking-site.com</screen>
+</para>
+
+<para>
+ Some file types you may not want to filter for various reasons:
+</para>
+
+<para>
+ <screen>
+# Technical documentation is likely to contain strings that might
+# erroneously get altered by the JavaScript-oriented filters:
+#
+.tldp.org
+/(.*/)?selfhtml/
+
+# And this stupid host sends streaming video with a wrong MIME type,
+# so that Privoxy thinks it is getting HTML and starts filtering:
+#
+stupid-server.example.com/</screen>
+</para>
+
+<para>
+ Example of a simple <link linkend="BLOCK">block</link> action. Say you've
+ seen an ad on your favourite page on example.com that you want to get rid of.
+ You have right-clicked the image, selected <quote>copy image location</quote>
+ and pasted the URL below while removing the leading http://, into a
+ <literal>{ +block }</literal> section. Note that <literal>{ +handle-as-image
+ }</literal> need not be specified, since all URLs ending in
+ <literal>.gif</literal> will be tagged as images by the general rules as set
+ in default.action anyway:
+</para>
+
+<para>
+ <screen>
+{ +<link linkend="BLOCK">block</link> }
+ www.example.com/nasty-ads/sponsor\.gif
+ another.popular.site.net/more/junk/here/</screen>
+</para>
+
+<para>
+ The URLs of dynamically generated banners, especially from large banner
+ farms, often don't use the well-known image file name extensions, which
+ makes it impossible for <application>Privoxy</application> to guess
+ the file type just by looking at the URL.
+ You can use the <literal>+block-as-image</literal> alias defined above for
+ these cases.
+ Note that objects which match this rule but then turn out NOT to be an
+ image are typically rendered as a <quote>broken image</quote> icon by the
+ browser. Use cautiously.
+</para>
+
+<para>
+ <screen>
+{ +block-as-image }
+ .doubleclick.net
+ .fastclick.net
+ /Realmedia/ads/
+ ar.atwola.com/</screen>
+</para>
+
+<para>
+ Now 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
+ -- <emphasis>whoa!</emphasis> -- it worked. The <literal>fragile</literal>
+ aliases disables those actions that are most likely to break a site. Also,
+ good for testing purposes to see if it is <application>Privoxy</application>
+ that is causing the problem or not. We later find other regular sites
+ that misbehave, and add those to our personalized list of troublemakers:
+</para>
+
+<para>
+<screen>
+{ fragile }
+ .forbes.com
+ webmail.example.com
+ .mybank.com</screen>
+</para>
+
+<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>
+<screen>
+{ +<link linkend="filter-fun">filter{fun}</link> }
+ / # For ALL sites!</screen>
+</para>
+
+<para>
+ 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>
+ You might also worry 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>
+<screen>
+{ allow-ads }
+ .sourceforge.net
+ .slashdot.org
+ .osdn.net</screen>
+</para>
+
+<para>
+ 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>, and
+ <literal>-<link linkend="filter-banners-by-link">filter{banners-by-link}</link></literal> above.
+</para>
+
+<para>
+ Invoke another alias here to force an over-ride of the MIME type <literal>
+ application/x-sh</literal> which typically would open a download type
+ dialog. In my case, I want to look at the shell script, and then I can save
+ it should I choose to.
+</para>
+
+<para>
+<screen>
+{ handle-as-text }
+ /.*\.sh$</screen>
+</para>
+
+<para>
+ <filename>user.action</filename> is generally the best place to define
+ exceptions and additions to the default policies of
+ <filename>default.action</filename>. Some actions are safe to have their
+ default policies set here though. So let's set a default policy to have a
+ <quote>blank</quote> image as opposed to the checkerboard pattern for
+ <emphasis>ALL</emphasis> sites. <quote>/</quote> of course matches all URL
+ paths and patterns:
+</para>
+
+<para>
+<screen>
+{ +<link linkend="set-image-blocker">set-image-blocker{blank}</link> }
+/ # ALL sites</screen>
+</para>
+
+</sect3>
+</sect2>
+
+<!-- ~ End section ~ -->
+
+</sect1>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+
+<sect1 id="filter-file">
+<title>Filter Files</title>
+
+<para>
+ On-the-fly text substitutions need
+ to be defined in a <quote>filter file</quote>. Once defined, they
+ can then be invoked as an <quote>action</quote>.
+</para>
+
+<para>
+ &my-app; supports three different filter actions:
+ <literal><link linkend="filter">filter</link></literal> to
+ rewrite the content that is send to the client,
+ <literal><link linkend="client-header-filter">client-header-filter</link></literal>
+ to rewrite headers that are send by the client, and
+ <literal><link linkend="server-header-filter">server-header-filter</link></literal>
+ to rewrite headers that are send by the server, and
+</para>
+
+<para>
+ &my-app; also supports two tagger actions:
+ <literal><link linkend="client-header-tagger">client-header-tagger</link></literal>
+ and
+ <literal><link linkend="server-header-tagger">server-header-tagger</link></literal>.
+ Taggers and filters use the same syntax in the filter files, the differnce
+ is that taggers don't modify the text they are filtering, but use a rewritten
+ version of the filtered text as tag. The tags can then be used to change the
+ applying actions through sections with <link linkend="tag-pattern">tag-patterns</link>.
+</para>
+
+
+<para>
+ Multiple filter files can be defined through the <literal> <link
+ linkend="filterfile">filterfile</link></literal> config directive. The filters
+ as supplied by the developers will be found in
+ <filename>default.filter</filename>. It is recommended that any locally
+ defined or modified filters go in a separately defined file such as
+ <filename>user.filter</filename>.
+
+</para>
+
+<para>
+ Command tasks for content filters 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.
+</para>
+
+<para>
+ Content filtering works on any text-based document type, including
+ HTML, JavaScript, CSS etc. (all <literal>text/*</literal>
+ MIME types, <emphasis>except</emphasis> <literal>text/plain</literal>).
+ Substitutions are made at the source level, so if you want to <quote>roll
+ your own</quote> filters, you should first be familiar with HTML syntax,
+ and, of course, regular expressions.
+</para>
+
+<para>
+ 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 one of the
+ <emphasis>keywords</emphasis> <literal>FILTER:</literal>,
+ <literal>CLIENT-HEADER-FILTER:</literal> or <literal>SERVER-HEADER-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>
+ 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>
+ Filter definitions start with a header line that contains the filter
+ type, the filter name and the filter description.
+ A content filter header line for a filter called <quote>foo</quote> could look
+ like this:
+</para>
+
+<para>
+ <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
+ PCRS documentation 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>
+
+<para>
+ If you are new to
+ <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+ Expressions</quote></ulink>, you might want to take a look at
+ the <link linkend="regex">Appendix on regular expressions</link>, and
+ see the <ulink url="http://perldoc.perl.org/perlre.html">Perl
+ manual</ulink> for
+ <ulink url="http://perldoc.perl.org/perlop.html">the
+ <literal>s///</literal> operator's syntax</ulink> and <ulink
+ url="http://perldoc.perl.org/perlre.html">Perl-style regular
+ expressions</ulink> in general.
+ The below examples might also help to get you started.
+</para>
+
+
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+
+<sect2><title>Filter File Tutorial</title>
+<para>
+ Now, let's complete our <quote>foo</quote> content 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>
+
+<para>
+ <screen>s/foo/bar/</screen>
+</para>
+
+<para>
+ 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>
+ <screen>s/foo/bar/g</screen>
+</para>
+
+<para>
+ Our complete filter now looks like this:
+</para>
+<para>
+ <screen>FILTER: foo Replace all "foo" with "bar"
+s/foo/bar/g</screen>
+</para>
+
+<para>
+ 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>
+
+
+<para>
+ <screen>
+FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse
- <para>
- Note: 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.
+# 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>
- </listitem>
+<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>
- <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>
+ 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>
- <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, user defined 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>
+ 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>
- <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>
+ 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>
- <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>. Note you
- cannot treat HTML pages as images in most cases. For instance, frames
- require an HTML page to display. So a frame that is an ad, cannot be
- treated as an image. Forcing an <quote>image</quote> in this
- situation just will not work.
- </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 advertisement. There are four 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 checkerboard 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>
+ 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>
- <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>
+ 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>
- </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>no-compression</quote> is turned on.
- </para>
+<para>
+ 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>
- <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>
+ 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>
- </itemizedlist>
+<para>
+ We'll show you two other jobs from the JavaScript taming department, but
+ this time only point out the constructs of special interest:
</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>
+# The status bar is for displaying link targets, not pointless blahblah
+#
+s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig</screen>
</para>
<para>
- Some examples:
+ <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>. Finally, <literal>\1</literal> is
+ a back-reference to the first parenthesis just like <literal>$1</literal> above,
+ with the difference that in the <emphasis>pattern</emphasis>, a backslash indicates
+ a back-reference, whereas in the <emphasis>substitute</emphasis>, it's the dollar.
</para>
<para>
- Turn off cookies by default, then allow a few through for specified sites:
+ 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>
- <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
+ <screen>
+# Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
+#
+s/(<body [^>]*)onunload(.*>)/$1never$2/iU</screen>
+</para>
+
+<para>
+ 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. Also note that ungreedy matching alone doesn't always guarantee
+ a minimal match: In the first parenthesis, we had to use <literal>[^>]*</literal>
+ instead of <literal>.*</literal> to prevent the match from exceeding the
+ <body> tag if it doesn't contain <quote>OnUnload</quote>, but the page's
+ content does.
+</para>
+
+<para>
+ The last example is from the fun department:
+</para>
+
+<para>
+ <screen>
+FILTER: fun Fun text replacements
+
+# Spice the daily news:
+#
+s/microsoft(?!\.com)/MicroSuck/ig</screen>
+</para>
+
+<para>
+ 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 trashed, while
+ still replacing the word everywhere else.
+</para>
+
+<para>
+ <screen>
+# Buzzword Bingo (example for extended regex syntax)
+#
+s* industry[ -]leading \
+| cutting[ -]edge \
+| customer[ -]focused \
+| market[ -]driven \
+| award[ -]winning # Comments are OK, too! \
+| high[ -]performance \
+| solutions[ -]based \
+| unmatched \
+| unparalleled \
+| unrivalled \
+*<font color="red"><b>BINGO!</b></font> \
+*igx</screen>
+</para>
+
+<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>
+
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+
+<sect2 id="predefined-filters"><title>The Pre-defined Filters</title>
+
+<!--
+
+ Note each filter is also listed in the +filter action section above. Please
+ keep these listings in sync.
+
+-->
+
+<para>
+The distribution <filename>default.filter</filename> file contains a selection of
+pre-defined filters for your convenience:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><emphasis>js-annoyances</emphasis></term>
+ <listitem>
+ <para>
+ The purpose of this filter is to get rid of particularly annoying JavaScript abuse.
+ To that end, it
+ <itemizedlist>
+ <listitem>
+ <para>
+ replaces JavaScript references to the browser's referrer information
+ with the string "Not Your Business!". This compliments the <literal><link
+ linkend="hide-referrer">hide-referrer</link></literal> action on the content level.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ removes the bindings to the DOM's
+ <ulink url="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents">unload
+ event</ulink> which we feel has no right to exist and is responsible for most <quote>exit consoles</quote>, i.e.
+ nasty windows that pop up when you close another one.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ removes code that causes new windows to be opened with undesired properties, such as being
+ full-screen, non-resizeable, without location, status or menu bar etc.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Use with caution. This is an aggressive filter, and can break sites that
+ rely heavily on JavaScript.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>js-events</emphasis></term>
+ <listitem>
+ <para>
+ This is a very radical measure. It removes virtually all JavaScript event bindings, which
+ means that scripts can not react to user actions such as mouse movements or clicks, window
+ resizing etc, anymore. Use with caution!
+ </para>
+ <para>
+ We <emphasis>strongly discourage</emphasis> using this filter as a default since it breaks
+ many legitimate scripts. It is meant for use only on extra-nasty sites (should you really
+ need to go there).
+ </para>
+ </listitem>
+ </varlistentry>
+
+<varlistentry>
+ <term><emphasis>html-annoyances</emphasis></term>
+ <listitem>
+ <para>
+ This filter will undo many common instances of HTML based abuse.
+ </para>
+ <para>
+ The <literal>BLINK</literal> and <literal>MARQUEE</literal> tags
+ are neutralized (yeah baby!), and browser windows will be created as
+ resizeable (as of course they should be!), and will have location,
+ scroll and menu bars -- even if specified otherwise.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>content-cookies</emphasis></term>
+ <listitem>
+ <para>
+ Most cookies are set in the HTTP dialog, where they can be intercepted
+ by the
+ <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>
+ and <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>
+ actions. But web sites increasingly make use of HTML meta tags and JavaScript
+ to sneak cookies to the browser on the content level.
+ </para>
+ <para>
+ This filter disables most HTML and JavaScript code that reads or sets
+ cookies. It cannot detect all clever uses of these types of code, so it
+ should not be relied on as an absolute fix. Use it wherever you would also
+ use the cookie crunch actions.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>refresh tags</emphasis></term>
+ <listitem>
+ <para>
+ Disable any refresh tags if the interval is greater than nine seconds (so
+ that redirections done via refresh tags are not destroyed). This is useful
+ for dial-on-demand setups, or for those who find this HTML feature
+ annoying.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>unsolicited-popups</emphasis></term>
+ <listitem>
+ <para>
+ This filter attempts to prevent only <quote>unsolicited</quote> pop-up
+ windows from opening, yet still allow pop-up windows that the user
+ has explicitly chosen to open. It was added in version 3.0.1,
+ as an improvement over earlier such filters.
+ </para>
+ <para>
+ Technical note: The filter works by redefining the window.open JavaScript
+ function to a dummy function, <literal>PrivoxyWindowOpen()</literal>,
+ during the loading and rendering phase of each HTML page access, and
+ restoring the function afterward.
+ </para>
+ <para>
+ This is recommended only for browsers that cannot perform this function
+ reliably themselves. And be aware that some sites require such windows
+ in order to function normally. Use with caution.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>all-popups</emphasis></term>
+ <listitem>
+ <para>
+ Attempt to prevent <emphasis>all</emphasis> pop-up windows from opening.
+ Note this should be used with even more discretion than the above, since
+ it is more likely to break some sites that require pop-ups for normal
+ usage. Use with caution.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>img-reorder</emphasis></term>
+ <listitem>
+ <para>
+ This is a helper filter that has no value if used alone. It makes the
+ <literal>banners-by-size</literal> and <literal>banners-by-link</literal>
+ (see below) filters more effective and should be enabled together with them.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>banners-by-size</emphasis></term>
+ <listitem>
+ <para>
+ This filter removes image tags purely based on what size they are. Fortunately
+ for us, many ads and banner images tend to conform to certain standardized
+ sizes, which makes this filter quite effective for ad stripping purposes.
+ </para>
+ <para>
+ Occasionally this filter will cause false positives on images that are not ads,
+ but just happen to be of one of the standard banner sizes.
+ </para>
+ <para>
+ Recommended only for those who require extreme ad blocking. The default
+ block rules should catch 95+% of all ads <emphasis>without</emphasis> this filter enabled.
+ </para>
+ </listitem>
+ </varlistentry>
- # Alternative way of saying the same thing
- {-no-cookies-set -no-cookies-read -no-cookies-keep}
- .sourceforge.net
- .sf.net
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term><emphasis>banners-by-link</emphasis></term>
+ <listitem>
+ <para>
+ This is an experimental filter that attempts to kill any banners if
+ their URLs seem to point to known or suspected click trackers. It is currently
+ not of much value and is not recommended for use by default.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Now turn off <quote>fast redirects</quote>, and then we allow two exceptions:
-</para>
+ <varlistentry>
+ <term><emphasis>webbugs</emphasis></term>
+ <listitem>
+ <para>
+ Webbugs are small, invisible images (technically 1X1 GIF images), that
+ are used to track users across websites, and collect information on them.
+ As an HTML page is loaded by the browser, an embedded image tag causes the
+ browser to contact a third-party site, disclosing the tracking information
+ through the requested URL and/or cookies for that third-party domain, without
+ the user ever becoming aware of the interaction with the third-party site.
+ HTML-ized spam also uses a similar technique to verify email addresses.
+ </para>
+ <para>
+ This filter removes the HTML code that loads such <quote>webbugs</quote>.
+ </para>
+ </listitem>
+ </varlistentry>
-<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>
-</para>
+ <varlistentry>
+ <term><emphasis>tiny-textforms</emphasis></term>
+ <listitem>
+ <para>
+ A rather special-purpose filter that can be used to enlarge textareas (those
+ multi-line text boxes in web forms) and turn off hard word wrap in them.
+ It was written for the sourceforge.net tracker system where such boxes are
+ a nuisance, but it can be handy on other sites, too.
+ </para>
+ <para>
+ It is not recommended to use this filter as a default.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Turn on page filtering according to rules in the defined sections
- of <filename>default.filter</filename>, and make one exception for
- Sourceforge:
- </para>
+ <varlistentry>
+ <term><emphasis>jumping-windows</emphasis></term>
+ <listitem>
+ <para>
+ Many consider windows that move, or resize themselves to be abusive. This filter
+ neutralizes the related JavaScript code. Note that some sites might not display
+ or behave as intended when using this filter. Use with caution.
+ </para>
+ </listitem>
+ </varlistentry>
-<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>
-</para>
-
-<para>
- Now some URLs that we want <quote>blocked</quote> (normally generates
- the <quote>blocked</quote> banner). Many of these use regular expressions
- that will expand to match multiple URLs:
-</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>
-</para>
+ <varlistentry>
+ <term><emphasis>frameset-borders</emphasis></term>
+ <listitem>
+ <para>
+ Some web designers seem to assume that everyone in the world will view their
+ web sites using the same browser brand and version, screen resolution etc,
+ because only that assumption could explain why they'd use static frame sizes,
+ yet prevent their frames from being resized by the user, should they be too
+ small to show their whole content.
+ </para>
+ <para>
+ This filter removes the related HTML code. It should only be applied to sites
+ which need it.
+ </para>
+ </listitem>
+ </varlistentry>
-<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.
-</para>
+ <varlistentry>
+ <term><emphasis>demoronizer</emphasis></term>
+ <listitem>
+ <para>
+ Many Microsoft products that generate HTML use non-standard extensions (read:
+ violations) of the ISO 8859-1 aka Latin-1 character set. This can cause those
+ HTML documents to display with errors on standard-compliant platforms.
+ </para>
+ <para>
+ This filter translates the MS-only characters into Latin-1 equivalents.
+ It is not necessary when using MS products, and will cause corruption of
+ all documents that use 8-bit character sets other than Latin-1. It's mostly
+ worthwhile for Europeans on non-MS platforms, if weird garbage characters
+ sometimes appear on some pages, or user agents that don't correct for this on
+ the fly.
+<!--
+ My version of Mozilla (ancient) shows litte square boxes for quote
+ characters, and apostrophes on moronized pages. So many pages have this, I
+ can read them fine now. HB 08/27/06
+-->
+ </para>
+ </listitem>
+ </varlistentry>
-</sect3>
+ <varlistentry>
+ <term><emphasis>shockwave-flash</emphasis></term>
+ <listitem>
+ <para>
+ A filter for shockwave haters. As the name suggests, this filter strips code
+ out of web pages that is used to embed shockwave flash objects.
+ </para>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
-<!-- ~ End section ~ -->
+ <varlistentry>
+ <term><emphasis>quicktime-kioskmode</emphasis></term>
+ <listitem>
+ <para>
+ Change HTML code that embeds Quicktime objects so that kioskmode, which
+ prevents saving, is disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>fun</emphasis></term>
+ <listitem>
+ <para>
+ Text replacements for subversive browsing fun. Make fun of your favorite
+ Monopolist or play buzzword bingo.
+ </para>
+ </listitem>
+ </varlistentry>
-<!-- ~~~~~ 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.
-</para>
+ <varlistentry>
+ <term><emphasis>crude-parental</emphasis></term>
+ <listitem>
+ <para>
+ A demonstration-only filter that shows how <application>Privoxy</application>
+ can be used to delete web content on a keyword basis.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Now let's define a few aliases:
-</para>
+ <varlistentry>
+ <term><emphasis>ie-exploits</emphasis></term>
+ <listitem>
+ <para>
+ An experimental collection of text replacements to disable malicious HTML and JavaScript
+ code that exploits known security holes in Internet Explorer.
+ </para>
+ <para>
+ Presently, it only protects against Nimda and a cross-site scripting bug, and
+ would need active maintenance to provide more substantial protection.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- # Useful custom 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
+ <varlistentry>
+ <term><emphasis>site-specifics</emphasis></term>
+ <listitem>
+ <para>
+ Some web sites have very specific problems, the cure for which doesn't apply
+ anywhere else, or could even cause damage on other sites.
+ </para>
+ <para>
+ This is a collection of such site-specific cures which should only be applied
+ to the sites they were intended for, which is what the supplied
+ <filename>default.action</filename> file does. Users shouldn't need to change
+ anything regarding this filter.
+ </para>
+ </listitem>
+ </varlistentry>
- #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>
-</para>
+ <varlistentry>
+ <term><emphasis>google</emphasis></term>
+ <listitem>
+ <para>
+ A CSS based block for Google text ads. Also removes a width limitation
+ and the toolbar advertisement.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>yahoo</emphasis></term>
+ <listitem>
+ <para>
+ Another CSS based block, this time for Yahoo text ads. And removes
+ a width limitation as well.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- Some examples using our <quote>shop</quote> and <quote>fragile</quote>
- aliases from above:
-</para>
+ <varlistentry>
+ <term><emphasis>msn</emphasis></term>
+ <listitem>
+ <para>
+ Another CSS based block, this time for MSN text ads. And removes
+ tracking URLs, as well as a width limitation.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- # These sites are very complex and require
- # minimal interference.
- {fragile}
- .office.microsoft.com
- .windowsupdate.microsoft.com
- .nytimes.com
+ <varlistentry>
+ <term><emphasis>blogspot</emphasis></term>
+ <listitem>
+ <para>
+ Cleans up some Blogspot blogs. Read the fine print before using this one!
+ </para>
+ <para>
+ This filter also intentionally removes some navigation stuff and sets the
+ page width to 100%. As a result, some rounded <quote>corners</quote> would
+ appear to early or not at all and as fixing this would require a browser
+ that understands background-size (CSS3), they are removed instead.
+ </para>
+ </listitem>
+ </varlistentry>
- # Shopping sites - still want to block ads.
- {shop}
- .quietpc.com
- .worldpay.com # for quietpc.com
- .jungle.com
- .scan.co.uk
+ <varlistentry>
+ <term><emphasis>xml-to-html</emphasis></term>
+ <listitem>
+ <para>
+ Server-header filter to change the Content-Type from xml to html.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>html-to-xml</emphasis></term>
+ <listitem>
+ <para>
+ Server-header filter to change the Content-Type from html to xml.
+ </para>
+ </listitem>
+ </varlistentry>
- # These shops require pop-ups
- {shop -no-popups}
- .dabs.com
- .overclockers.co.uk
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <varlistentry>
+ <term><emphasis>no-ping</emphasis></term>
+ <listitem>
+ <para>
+ Removes the non-standard <literal>ping</literal> attribute from
+ anchor and area HTML tags.
+ </para>
+ </listitem>
+ </varlistentry>
-<para>
- The <quote>shop</quote> and <quote>fragile</quote> aliases are often used for
- <quote>problem</quote> sites that require most actions to be disabled
- in order to function properly.
+ <varlistentry>
+ <term><emphasis>hide-tor-exit-notation</emphasis></term>
+ <listitem>
+ <para>
+ Client-header filter to remove the <command>Tor</command> exit node notation
+ found in Host and Referer headers.
+ </para>
+ <para>
+ If &my-app; and <command>Tor</command> are chained and &my-app;
+ is configured to use socks4a, one can use <quote>http://www.example.org.foobar.exit/</quote>
+ to access the host <quote>www.example.org</quote> through the
+ <command>Tor</command> exit node <quote>foobar</quote>.
+ </para>
+ <para>
+ As the HTTP client isn't aware of this notation, it treats the
+ whole string <quote>www.example.org.foobar.exit</quote> as host and uses it
+ for the <quote>Host</quote> and <quote>Referer</quote> headers. From the
+ server's point of view the resulting headers are invalid and can cause problems.
+ </para>
+ <para>
+ An invalid <quote>Referer</quote> header can trigger <quote>hot-linking</quote>
+ protections, an invalid <quote>Host</quote> header will make it impossible for
+ the server to find the right vhost (several domains hosted on the same IP address).
+ </para>
+ <para>
+ This client-header filter removes the <quote>foo.exit</quote> part in those headers
+ to prevent the mentioned problems. Note that it only modifies
+ the HTTP headers, it doesn't make it impossible for the server
+ to detect your <command>Tor</command> exit node based on the IP address
+ the request is coming from.
+ </para>
+ </listitem>
+ </varlistentry>
-</para>
+<!--
+ <varlistentry>
+ <term><emphasis> </emphasis></term>
+ <listitem>
+ <para>
+ </para>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+-->
+</variablelist>
-</sect3>
</sect2>
+</sect1>
<!-- ~ End section ~ -->
-<!-- ~~~~~ 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.
-</para>
-<para>
- This is potentially a very powerful feature, and requires knowledge of both
- <quote>regular expression</quote> and HTML in order create custom
- filters. But, there are a number of useful filters included with
- <application>Privoxy</application> for many common situations.
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="templates">
+<title>Privoxy's Template Files</title>
<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>.
+ All <application>Privoxy</application> built-in pages, i.e. error pages such as the
+ <ulink url="http://show-the-404-error.page"><quote>404 - No Such Domain</quote>
+ error page</ulink>, the <ulink
+ url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
+ page</ulink>
+ and all pages of its <ulink url="http://config.privoxy.org/">web-based
+ user interface</ulink>, are generated from <emphasis>templates</emphasis>.
+ (<application>Privoxy</application> must be running for the above links to work as
+ intended.)
</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>:
+ These templates are stored in a subdirectory of the <link linkend="confdir">configuration
+ directory</link> called <filename>templates</filename>. On Unixish platforms,
+ this is typically
+ <ulink url="file:///etc/privoxy/templates/"><filename>/etc/privoxy/templates/</filename></ulink>.
</para>
<para>
- Stop web pages from displaying annoying messages in the status bar by
- deleting such references:
+ The templates are basically normal HTML files, but with place-holders (called symbols
+ or exports), which <application>Privoxy</application> fills at run time. You can
+ edit the templates with a normal text editor, should you want to customize them.
+ (<emphasis>Not recommended for the casual user</emphasis>). Note that
+ just like in configuration files, lines starting with <literal>#</literal> are
+ ignored when the templates are filled in.
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- FILTER: html-annoyances
-
- # 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
-
- # The <BLINK> tag was a crime!
- #
- s*<blink>|</blink>**ig
-
- # Is this evil?
- #
- #s/framespacing="?(no|0)"?//ig
- #s/margin(height|width)=[0-9]*//gi
- </literallayout>
- </msgtext>
- </literal>
+ The place-holders are of the form <literal>@name@</literal>, and you will
+ find a list of available symbols, which vary from template to template,
+ in the comments at the start of each file. Note that these comments are not
+ always accurate, and that it's probably best to look at the existing HTML
+ code to find out which symbols are supported and what they are filled in with.
</para>
<para>
- Just for kicks, replace any occurrence of <quote>Microsoft</quote> with
- <quote>MicroSuck</quote>, and have a little fun with topical buzzwords:
+ A special application of this substitution mechanism is to make whole
+ blocks of HTML code disappear when a specific symbol is set. We use this
+ for many purposes, one of them being to include the beta warning in all
+ our user interface (CGI) pages when <application>Privoxy</application>
+ is in an alpha or beta development stage:
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- FILTER: fun
+ <screen>
+<!-- @if-unstable-start -->
- s/microsoft(?!.com)/MicroSuck/ig
+ ... beta warning HTML code goes here ...
- # Buzzword Bingo:
- #
- s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></font>/ig
- </literallayout>
- </msgtext>
- </literal>
+<!-- if-unstable-end@ --></screen>
</para>
<para>
- Kill those pesky little web-bugs:
+ If the "unstable" symbol is set, everything in between and including
+ <literal>@if-unstable-start</literal> and <literal>if-unstable-end@</literal>
+ will disappear, leaving nothing but an empty comment:
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
- FILTER: webbugs
-
- s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1(\D[^>]*?)?>/<!-- Squished WebBug -->/sig
- </literallayout>
- </msgtext>
- </literal>
+ <screen><!-- --></screen>
</para>
-</sect2>
-
-<!-- ~ End section ~ -->
-
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2>
-<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. <filename>cgi-style.css</filename> is
- used to control the HTML attributes (fonts, etc).
+ There's also an if-then-else construct and an <literal>#include</literal>
+ mechanism, but you'll sure find out if you are inclined to edit the
+ templates ;-)
</para>
-<para>
- The default <quote>Blocked</quote> 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.
+<para>
+ All templates refer to a style located at
+ <ulink url="http://config.privoxy.org/send-stylesheet"><literal>http://config.privoxy.org/send-stylesheet</literal></ulink>.
+ This is, of course, locally served by <application>Privoxy</application>
+ and the source for it can be found and edited in the
+ <filename>cgi-style.css</filename> template.
</para>
-</sect2>
</sect1>
&contacting;
<!-- end boilerplate -->
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="submitactions">
-<title>Submitting Ads and <quote>Action</quote> Problems</title>
-<para>
- Ads and banners that are not stopped by <application>Privoxy</application>
- can be submitted to the developers by accessing a special page and filling
- out the brief, required form. Conversely, you can also report pages, images,
- etc. that <application>Privoxy</application> is blocking, but should not.
- The form itself does require Internet access.
-</para>
-<para>
- To do this, point your browser to <application>Privoxy</application>
- at <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
- (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>), and then select
- <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions','Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Actions file feedback system</ulink>,
- near the bottom of the page. Paste in the URL that is the cause of the
- unwanted behavior, and follow the prompts. The developers will
- try to incorporate a fix for the problem you reported into future versions.
-</para>
-
-<para>
- New <filename>default.actions</filename> files will occasionally be made
- available based on your feedback. These
- will be announced on the
- <ulink
- url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce">ijbswa-announce</ulink>
- list.
-</para>
-</sect2>
-
</sect1>
+<!-- ~ End section ~ -->
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="copyright"><title>Copyright and History</title>
+<sect1 id="copyright"><title>Privoxy Copyright, License and History</title>
-<sect2><title>Copyright</title>
<!-- Include copyright.sgml: -->
©right;
<!-- end copyright -->
-</sect2>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2><title>License</title>
+<!-- Include copyright.sgml: -->
+ &license;
+<!-- end copyright -->
+</sect2>
<!-- ~ End section ~ -->
&history;
<!-- end history -->
</sect2>
+
+<sect2 id="authors"><title>Authors</title>
+<!-- Include p-authors.sgml: -->
+ &p-authors;
+<!-- end authors -->
+</sect2>
+
</sect1>
+<!-- ~ End section ~ -->
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="seealso"><title>See Also</title>
<!-- Include seealso.sgml: -->
<sect2 id="regex">
<title>Regular Expressions</title>
<para>
- <application>Privoxy</application> can use <quote>regular expressions</quote>
- in various config files. Assuming support for <quote>pcre</quote> (Perl
- Compatible Regular Expressions) is compiled in, which is the default. Such
- configuration directives do not require regular expressions, but they can be
- used to increase flexibility by matching a pattern with wild-cards against
- URLs.
+ <application>Privoxy</application> uses Perl-style <quote>regular
+ expressions</quote> in its <link linkend="actions-file">actions
+ files</link> and <link linkend="filter-file">filter file</link>,
+ through the <ulink url="http://www.pcre.org/">PCRE</ulink> and
+<!--
+ dead 08/27/06
+ <ulink url="http://www.oesterhelt.org/pcrs/">PCRS</ulink> libraries.
+-->
+ <application>PCRS</application> libraries.
</para>
<para>
If you are reading this, you probably don't understand what <quote>regular
expressions</quote> are, or what they can do. So this will be a very brief
- introduction only. A full explanation would require a book ;-)
+ introduction only. A full explanation would require a <ulink
+ url="http://www.oreilly.com/catalog/regex/">book</ulink> ;-)
</para>
<para>
- <quote>Regular expressions</quote> is a way of matching one character
- expression against another to see if it matches or not. One of the
- <quote>expressions</quote> is a literal string of readable characters
- (letter, numbers, etc), and the other is a complex string of literal
- characters combined with wild-cards, and other special characters, called
- meta-characters. The <quote>meta-characters</quote> have special meanings and
- are used to build the complex pattern to be matched against. Perl Compatible
- Regular Expressions is an enhanced form of the regular expression language
- with backward compatibility.
+ Regular expressions provide a language to describe patterns that can be
+ run against strings of characters (letter, numbers, etc), to see if they
+ match the string or not. The patterns are themselves (sometimes complex)
+ strings of literal characters, combined with wild-cards, and other special
+ characters, called meta-characters. The <quote>meta-characters</quote> have
+ special meanings and are used to build complex patterns to be matched against.
+ Perl Compatible Regular Expressions are an especially convenient
+ <quote>dialect</quote> of the regular expression language.
</para>
<para>
<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></para>
<para><simplelist>
<member>
- <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
- any of the enclosed characters are encountered.
+ <emphasis>[ ]</emphasis> - Characters enclosed in brackets will be matched if
+ 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></para>
<para><simplelist>
<member>
- <emphasis>()</emphasis> - parentheses are used to group a sub-expression,
+ <emphasis>( )</emphasis> - parentheses are used to group a sub-expression,
or multiple sub-expressions.
</member>
</simplelist></para>
<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.
- </member>
-</simplelist></para>
-
-<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.
+ 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></para>
</para>
<para>
- A now something a little more complex:
+ And now something a little more complex:
</para>
<para>
<para>
<emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
another path statement with forward slashes. Anything in the square brackets
- <quote>[]</quote> can be matched. This is using <quote>0-9</quote> as a
+ <quote>[ ]</quote> can be matched. This is using <quote>0-9</quote> as a
shorthand expression to mean any digit one through nine. It is the same as
saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
means one or more of the preceding expression must be included. The preceding
in the expression anywhere).
</para>
-<para>
- <emphasis><literal>s/microsoft(?!.com)/MicroSuck/i</literal></emphasis> - This is
- a substitution. <quote>MicroSuck</quote> will replace any occurrence of
- <quote>microsoft</quote>. The <quote>i</quote> at the end of the expression
- means ignore case. The <quote>(?!.com)</quote> means
- the match should fail if <quote>microsoft</quote> is followed by
- <quote>.com</quote>. In other words, this acts like a <quote>NOT</quote>
- modifier. In case this is a hyperlink, we don't want to break it ;-).
-</para>
-
<para>
We are barely scratching the surface of regular expressions here so that you
can understand the default <application>Privoxy</application>
<para>
More reading on Perl Compatible Regular expressions:
- <ulink url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>
+ <ulink url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>
</para>
+<para>
+ For information on regular expression based substitutions and their applications
+ in filters, please see the <link linkend="filter-file">filter file tutorial</link>
+ in this manual.
+</para>
</sect2>
<!-- ~ End section ~ -->
<!-- ~~~~~ New section ~~~~~ -->
<sect2>
-<title><application>Privoxy</application>'s Internal Pages</title>
+<title>Privoxy's Internal Pages</title>
<para>
Since <application>Privoxy</application> proxies each requested
</para>
</blockquote>
<para>
- Alternately, this may be reached at <ulink
- url="http://p.p/">http://p.p/</ulink>, but this
- variation may not work as reliably as the above in some configurations.
+ There is a shortcut: <ulink url="http://p.p/">http://p.p/</ulink> (But it
+ doesn't provide a fall-back to a real page, in case the request is not
+ sent through <application>Privoxy</application>)
</para>
</listitem>
<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>
<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());">Disable Privoxy</ulink>
+ <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=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&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','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: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:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions','Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Actions file feedback system</ulink>
+ <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions/index.php?url='+escape(location.href),'Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Submit Actions File Feedback</ulink>
+ </para>
+ </listitem>
+ -->
+ <listitem>
+ <para>
+ <ulink url="javascript:void(window.open('http://config.privoxy.org/show-url-info?url='+escape(location.href),'Why').focus());">Privoxy - Why?</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
+ Credit: The site which gave us the general idea for these bookmarklets is
+ <ulink url="http://www.bookmarklets.com/">www.bookmarklets.com</ulink>. They
have more information about bookmarklets.
</para>
</sect2>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="chain">
+<title>Chain of Events</title>
+<para>
+ Let's take a quick look at how some of <application>Privoxy's</application>
+ core features are triggered, and the ensuing sequence of events when a web
+ page is requested by your browser:
+</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 <ulink url="http://p.p/">http://p.p/</ulink>) 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>
+ and
+ <link linkend="HANDLE-AS-EMPTY-DOCUMENT"><quote>+handle-as-empty-document</quote></link>
+ are then checked, and if there is no match, an
+ HTML <quote>BLOCKED</quote> page is sent back to the browser. Otherwise, if
+ it does match, an image is returned for the former, and an empty text
+ document for the latter. The type of image would depend 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).
+ </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 determined 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 any <link linkend="FILTER"><quote>+filter</quote></link> action
+ 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> and any other filter files) are
+ processed against the buffered content. Filters are applied in the order
+ they are specified in one of the filter files. 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 a <link linkend="FILTER"><quote>+filter</quote></link> action
+ 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 (possibly 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
+ separate request (this is easily viewable in <application>Privoxy's</application>
+ logs). And each such request is in turn processed just as above. Note that a
+ complex web page will have many, many such embedded URLs. If these
+ secondary requests are to a different server, then quite possibly a very
+ differing set of actions is triggered.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+<para>
+ NOTE: This is somewhat of a simplistic overview of what happens with each URL
+ request. For the sake of brevity and simplicity, we have focused on
+ <application>Privoxy's</application> core features only.
+</para>
+
+</sect2>
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="actionsanat">
-<title>Anatomy of an Action</title>
+<title>Troubleshooting: 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">actions</link> and <link linkend="FILTER">filters</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 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
+ <link linkend="regex">regular expressions</link> whose consequences are not
+ always 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!). Looking at the
+ logs is a good idea too.
+</para>
+<para>
+ Another easy troubleshooting step to try is if you have done any
+ customization of your installation, revert back to the installed
+ defaults and see if that helps. There are times the developers get complaints
+ about one thing or another, and the problem is more related to a customized
+ configuration issue.
+</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 (i.e. a web page). 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.
+ help with filtering effects (i.e. the <link
+ linkend="FILTER"><quote>+filter</quote></link> action) from
+ one of the filter files 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 in a sample configuration (your real
+ configuration may vary):
</para>
<para>
<screen>
- System default actions:
+ Matches for http://google.com:
- { -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 }
+ In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
+
+ {-add-header
+ -block
+ -client-header-filter{hide-tor-exit-notation}
+ -content-type-overwrite
+ -crunch-client-header
+ -crunch-if-none-match
+ -crunch-incoming-cookies
+ -crunch-outgoing-cookies
+ -crunch-server-header
+ +deanimate-gifs {last}
+ -downgrade-http-version
+ +fast-redirects {check-decoded-url}
+ -filter {js-events}
+ -filter {content-cookies}
+ -filter {all-popups}
+ -filter {banners-by-link}
+ -filter {tiny-textforms}
+ -filter {frameset-borders}
+ -filter {demoronizer}
+ -filter {shockwave-flash}
+ -filter {quicktime-kioskmode}
+ -filter {fun}
+ -filter {crude-parental}
+ -filter {site-specifics}
+ -filter {js-annoyances}
+ -filter {html-annoyances}
+ +filter {refresh-tags}
+ -filter {unsolicited-popups}
+ +filter {img-reorder}
+ +filter {banners-by-size}
+ +filter {webbugs}
+ +filter {jumping-windows}
+ +filter {ie-exploits}
+ -filter {google}
+ -filter {yahoo}
+ -filter {msn}
+ -filter {blogspot}
+ -filter {no-ping}
+ -force-text-mode
+ -handle-as-empty-document
+ -handle-as-image
+ -hide-accept-language
+ -hide-content-disposition
+ +hide-forwarded-for-headers
+ +hide-from-header {block}
+ -hide-if-modified-since
+ +hide-referrer {forge}
+ -hide-user-agent
+ -inspect-jpegs
+ -kill-popups
+ -limit-connect
+ -overwrite-last-modified
+ +prevent-compression
+ -redirect
+ -send-vanilla-wafer
+ -send-wafer
+ -server-header-filter{xml-to-html}
+ -server-header-filter{html-to-xml}
+ +session-cookies-only
+ +set-image-blocker {pattern}
+ -treat-forbidden-connects-like-blocks }
+/
- </screen>
+ { -session-cookies-only }
+ .google.com
+
+ { -fast-redirects }
+ .google.com
+
+In file: user.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
+(no matches in this file)
+</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:
+ This is telling us how we have defined our
+ <link linkend="ACTIONS"><quote>actions</quote></link>, and
+ which ones match for our test case, <quote>google.com</quote>.
+ Displayed is all the actions that are available to us. Remember,
+ the <literal>+</literal> sign denotes <quote>on</quote>. <literal>-</literal>
+ denotes <quote>off</quote>. So some are <quote>on</quote> here, but many
+ are <quote>off</quote>. Each example we try may provide a slightly different
+ end result, depending on our configuration directives.
</para>
-
<para>
- <screen>
-
- Matches for http://google.com:
-
- { -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 }
- /
-
- { -no-cookies-keep -no-cookies-read -no-cookies-set }
- .google.com
-
- { -fast-redirects }
- .google.com
-
- </screen>
+ The first listing
+ is for 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>
- 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>.
-
+ But we have defined additional actions that would be exceptions to these general
+ rules, and then we 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, at
+ least that is how it is in this example. 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> or <quote>mail.google.com</quote>. But it would not
+ match <quote>www.google.de</quote>! So, apparently, we have these two actions
+ defined as exceptions to the general rules at the top 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>
- 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 explicit 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.
-
+ Then, for our <filename>user.action</filename> file, we again have no hits.
+ So there is nothing google-specific that we might have added to our own, local
+ configuration. If there was, those actions would over-rule any actions from
+ previously processed files, such as <filename>default.action</filename>.
+ <filename>user.action</filename> typically has the last word. This is the
+ best place to put hard and fast exceptions,
</para>
<para>
- And now we pull it altogether in the bottom section and summarize how
+ 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>:
<screen>
Final results:
-
- -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>
+
+ -add-header
+ -block
+ -client-header-filter{hide-tor-exit-notation}
+ -content-type-overwrite
+ -crunch-client-header
+ -crunch-if-none-match
+ -crunch-incoming-cookies
+ -crunch-outgoing-cookies
+ -crunch-server-header
+ +deanimate-gifs {last}
+ -downgrade-http-version
+ +fast-redirects {check-decoded-url}
+ -filter {js-events}
+ -filter {content-cookies}
+ -filter {all-popups}
+ -filter {banners-by-link}
+ -filter {tiny-textforms}
+ -filter {frameset-borders}
+ -filter {demoronizer}
+ -filter {shockwave-flash}
+ -filter {quicktime-kioskmode}
+ -filter {fun}
+ -filter {crude-parental}
+ -filter {site-specifics}
+ -filter {js-annoyances}
+ -filter {html-annoyances}
+ +filter {refresh-tags}
+ -filter {unsolicited-popups}
+ +filter {img-reorder}
+ +filter {banners-by-size}
+ +filter {webbugs}
+ +filter {jumping-windows}
+ +filter {ie-exploits}
+ -filter {google}
+ -filter {yahoo}
+ -filter {msn}
+ -filter {blogspot}
+ -filter {no-ping}
+ -force-text-mode
+ -handle-as-empty-document
+ -handle-as-image
+ -hide-accept-language
+ -hide-content-disposition
+ +hide-forwarded-for-headers
+ +hide-from-header {block}
+ -hide-if-modified-since
+ +hide-referrer {forge}
+ -hide-user-agent
+ -inspect-jpegs
+ -kill-popups
+ -limit-connect
+ -overwrite-last-modified
+ +prevent-compression
+ -redirect
+ -send-vanilla-wafer
+ -send-wafer
+ -server-header-filter{xml-to-html}
+ -server-header-filter{html-to-xml}
+ -session-cookies-only
+ +set-image-blocker {pattern}
+ -treat-forbidden-connects-like-blocks </screen>
+</para>
+
+<para>
+ Notice the only difference here to the previous listing, is to
+ <quote>fast-redirects</quote> and <quote>session-cookies-only</quote>,
+ which are activated specifically for this site in our configuration,
+ and thus show in the <quote>Final Results</quote>.
</para>
<para>
<para>
<screen>
- { +block +image }
- .ad.doubleclick.net
-
- { +block +image }
+ { +block }
ad*.
- { +block +image }
- .doubleclick.net
+ { +block }
+ .ad.
- </screen>
+ { +block +handle-as-image }
+ .[a-vx-z]*.doubleclick.net
+</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>,
+ We'll just show the interesting part here - the explicit matches. It is
+ matched three different times. Two <quote>+block</quote> sections,
+ and a <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>+block-as-image</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><literal>+block-as-image</literal></quote> just
+ simplifies the process and make it more readable.
</para>
<para>
- One last example. Let's try <quote>http://www.rhapsodyk.net/adsl/HOWTO/</quote>.
- This one is giving us problems. We are getting a blank page. Hmmm...
+ One last example. Let's try <quote>http://www.example.net/adsl/HOWTO/</quote>.
+ This one is giving us problems. We are getting a blank page. Hmmm ...
</para>
<para>
<screen>
- 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}
- +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 }
+ Matches for http://www.example.net/adsl/HOWTO/:
+
+ In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
+
+ {-add-header
+ -block
+ -client-header-filter{hide-tor-exit-notation}
+ -content-type-overwrite
+ -crunch-client-header
+ -crunch-if-none-match
+ -crunch-incoming-cookies
+ -crunch-outgoing-cookies
+ -crunch-server-header
+ +deanimate-gifs
+ -downgrade-http-version
+ +fast-redirects {check-decoded-url}
+ -filter {js-events}
+ -filter {content-cookies}
+ -filter {all-popups}
+ -filter {banners-by-link}
+ -filter {tiny-textforms}
+ -filter {frameset-borders}
+ -filter {demoronizer}
+ -filter {shockwave-flash}
+ -filter {quicktime-kioskmode}
+ -filter {fun}
+ -filter {crude-parental}
+ -filter {site-specifics}
+ -filter {js-annoyances}
+ -filter {html-annoyances}
+ +filter {refresh-tags}
+ -filter {unsolicited-popups}
+ +filter {img-reorder}
+ +filter {banners-by-size}
+ +filter {webbugs}
+ +filter {jumping-windows}
+ +filter {ie-exploits}
+ -filter {google}
+ -filter {yahoo}
+ -filter {msn}
+ -filter {blogspot}
+ -filter {no-ping}
+ -force-text-mode
+ -handle-as-empty-document
+ -handle-as-image
+ -hide-accept-language
+ -hide-content-disposition
+ +hide-forwarded-for-headers
+ +hide-from-header{block}
+ +hide-referer{forge}
+ -hide-user-agent
+ -inspect-jpegs
+ -kill-popups
+ -overwrite-last-modified
+ +prevent-compression
+ -redirect
+ -send-vanilla-wafer
+ -send-wafer
+ -server-header-filter{xml-to-html}
+ -server-header-filter{html-to-xml}
+ +session-cookies-only
+ +set-image-blocker{blank}
+ -treat-forbidden-connects-like-blocks }
/
- { +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 explicitly does <emphasis>not</emphasis>
- block (-block) pages with <quote>adsl</quote>. There are various ways to
- handle such exceptions. Example:
+ Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote> in our
+ configuration! But we did not want this at all! Now we see why we get the
+ blank page. It is actually triggering two different actions here, and
+ the effects are aggregated so that the URL is blocked, and &my-app; is told
+ to treat the block as if it were an image. But this is, of course, all wrong.
+ We could now add a new action below this (or better in our own
+ <filename>user.action</filename> file) that explicitly
+ <emphasis>un</emphasis> blocks (
+ <link linkend="BLOCK"><quote>{-block}</quote></link>) paths with
+ <quote>adsl</quote> in them (remember, last match in the configuration
+ wins). There are various ways to handle such exceptions. Example:
</para>
<para>
{ -block }
/adsl
-
- </screen>
+</screen>
</para>
<para>
- Now the page displays ;-) Be sure to flush your browser's caches when
- making such changes. Or, try using <literal>Shift+Reload</literal>.
+ Now the page displays ;-)
+ Remember to flush your browser's caches when making these kinds of changes to
+ your configuration to insure that you get a freshly delivered page! Or, try
+ using <literal>Shift+Reload</literal>.
</para>
<para>
<para>
<screen>
- { -block }
- /adsl
-
- </screen>
+ { +block +handle-as-image }
+ /ads
+</screen>
</para>
<para>
- That actually was very telling and pointed us quickly to where the problem
+ That actually was very helpful and pointed us quickly to where the problem
was. If you don't get this kind of match, then it means one of the default
- rules in the first section is causing the problem. This would require some
- guesswork, and maybe a little trial and error to isolate the offending rule.
- One likely cause would be one of the <quote>{+filter}</quote> actions. Try
- adding the URL for the site to one of aliases that turn off <quote>+filter</quote>:
+ rules in the first section of <filename>default.action</filename> is causing
+ the problem. This would require some guesswork, and maybe a little trial and
+ error to isolate the offending rule. One likely cause would be one of the
+ <link linkend="FILTER"><quote>+filter</quote></link> actions.
+ These tend to be harder to troubleshoot.
+ Try adding the URL for the site to one of aliases that turn off
+ <link linkend="FILTER"><quote>+filter</quote></link>:
</para>
<para>
<screen>
- {shop}
+ { shop }
.quietpc.com
.worldpay.com # for quietpc.com
.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><literal>{ shop }</literal></quote> is an <quote>alias</quote> that expands to
+ <quote><literal>{ -filter -session-cookies-only }</literal></quote>.
+ Or you could do your own exception to negate filtering:
</para>
<para>
<screen>
- {-filter}
+ { -filter }
+ # Disable ALL filter actions for sites in this section
.forbes.com
-
- </screen>
+ developer.ibm.com
+ localhost
+</screen>
+</para>
+
+<para>
+ This would turn off all filtering for these sites. This is best
+ put in <filename>user.action</filename>, for local site
+ exceptions. Note that when a simple domain pattern is used by itself (without
+ the subsequent path portion), all sub-pages within that domain are included
+ automatically in the scope of the action.
+</para>
+
+<para>
+ Images that are inexplicably being blocked, may well be hitting the
+<link linkend="FILTER-BANNERS-BY-SIZE"><quote>+filter{banners-by-size}</quote></link>
+ rule, which assumes
+ that images of certain sizes are ad banners (works well
+ <emphasis>most of the time</emphasis> since these tend to be standardized).
+</para>
+
+<para>
+ <quote><literal>{ fragile }</literal></quote> is an alias that disables most
+ actions that are the most likely to cause trouble. This can be used as a
+ last resort for problem sites.
+</para>
+<para>
+ <screen>
+
+ { fragile }
+ # Handle with care: easy to break
+ mail.google.
+ mybank.example.com</screen>
</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.
+ <emphasis>Remember to flush caches!</emphasis> Note that the
+ <literal>mail.google</literal> reference lacks the TLD portion (e.g.
+ <quote>.com</quote>. This will effectively match any TLD with
+ <literal>google</literal> in it, such as <literal>mail.google.de</literal>,
+ just as an example.
+</para>
+<para>
+ 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>
The GNU General Public License should be included with
this file. If not, you can view it at
http://www.gnu.org/copyleft/gpl.html
- or write to the Free Software Foundation, Inc., 59
- Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ or write to the Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+ USA
$Log: user-manual.sgml,v $
+ Revision 2.31 2007/06/02 14:01:37 fabiankeil
+ Start to document forward-override{}.
+
+ Revision 2.30 2007/04/25 15:10:36 fabiankeil
+ - Describe installation for FreeBSD.
+ - Start to document taggers and tag patterns.
+ - Don't confuse devils and daemons.
+
+ Revision 2.29 2007/04/05 11:47:51 fabiankeil
+ Some updates regarding header filtering,
+ handling of compressed content and redirect's
+ support for pcrs commands.
+
+ Revision 2.28 2006/12/10 23:42:48 hal9
+ Fix various typos reported by Adam P. Thanks.
+
+ Revision 2.27 2006/11/14 01:57:47 hal9
+ Dump all docs prior to 3.0.6 release. Various minor changes to faq and user
+ manual.
+
+ Revision 2.26 2006/10/24 11:16:44 hal9
+ Add new filters.
+
+ Revision 2.25 2006/10/18 10:50:33 hal9
+ Add note that since filters are off in Cautious, compression is ON. Turn off
+ compression to make filters work on all sites.
+
+ Revision 2.24 2006/10/03 11:13:54 hal9
+ More references to the new filters. Include html this time around.
+
+ Revision 2.23 2006/10/02 22:43:53 hal9
+ Contains new filter definitions from Fabian, and few other miscellaneous
+ touch-ups.
+
+ Revision 2.22 2006/09/22 01:27:55 hal9
+ Final commit of probably various minor changes here and there. Unless
+ something changes this should be ready for pending release.
+
+ Revision 2.21 2006/09/20 03:21:36 david__schmidt
+ Just the tiniest tweak. Wafer thin!
+
+ Revision 2.20 2006/09/10 14:53:54 hal9
+ Results of spell check. User manual has some updates to standard.actions file
+ info.
+
+ Revision 2.19 2006/09/08 12:19:02 fabiankeil
+ Adjust hide-if-modified-since example values
+ to reflect the recent changes.
+
+ Revision 2.18 2006/09/08 02:38:57 hal9
+ Various changes:
+ -Fix a number of broken links.
+ -Migrate the new Windows service command line options, and reference as
+ needed.
+ -Rebuild so that can be used with the new "user-manual" config capabilities.
+ -Etc.
+
+ Revision 2.17 2006/09/05 13:25:12 david__schmidt
+ Add Windows service invocation stuff (duplicated) in FAQ and in user manual under Windows startup. One probably ought to reference the other.
+
+ Revision 2.16 2006/09/02 12:49:37 hal9
+ Various small updates for new actions, filterfiles, etc.
+
+ Revision 2.15 2006/08/30 11:15:22 hal9
+ More work on the new actions, especially filter-*-headers, and What's New
+ section. User Manual is close to final form for 3.0.4 release. Some tinkering
+ and proof reading left to do.
+
+ Revision 2.14 2006/08/29 10:59:36 hal9
+ Add a "Whats New in this release" Section. Further work on multiple filter
+ files, and assorted other minor changes.
+
+ Revision 2.13 2006/08/22 11:04:59 hal9
+ Silence warnings and errors. This should build now. New filters were only
+ stubbed in. More to be done.
+
+ Revision 2.12 2006/08/14 08:40:39 fabiankeil
+ Documented new actions that were part of
+ the "minor Privoxy improvements".
+
+ Revision 2.11 2006/07/18 14:48:51 david__schmidt
+ Reorganizing the repository: swapping out what was HEAD (the old 3.1 branch)
+ with what was really the latest development (the v_3_0_branch branch)
+
+ Revision 1.123.2.43 2005/05/23 09:59:10 hal9
+ Fix typo 'loose'
+
+ Revision 1.123.2.42 2004/12/04 14:39:57 hal9
+ Fix two minor typos per bug SF report.
+
+ Revision 1.123.2.41 2004/03/23 12:58:42 oes
+ Fixed an inaccuracy
+
+ Revision 1.123.2.40 2004/02/27 12:48:49 hal9
+ Add comment re: redirecting to local file system for set-image-blocker may
+ is dependent on browser.
+
+ Revision 1.123.2.39 2004/01/30 22:31:40 oes
+ Added a hint re bookmarklets to Quickstart section
+
+ Revision 1.123.2.38 2004/01/30 16:47:51 oes
+ Some minor clarifications
+
+ Revision 1.123.2.37 2004/01/29 22:36:11 hal9
+ Updates for no longer filtering text/plain, and demoronizer default settings,
+ and copyright notice dates.
+
+ Revision 1.123.2.36 2003/12/10 02:26:26 hal9
+ Changed the demoronizer filter description.
+
+ Revision 1.123.2.35 2003/11/06 13:36:37 oes
+ Updated link to nightly CVS tarball
+
+ Revision 1.123.2.34 2003/06/26 23:50:16 hal9
+ Add a small bit on filtering and problems re: source code being corrupted.
+
+ Revision 1.123.2.33 2003/05/08 18:17:33 roro
+ Use apt-get instead of dpkg to install Debian package, which is more
+ solid, uses the correct and most recent Debian version automatically.
+
+ Revision 1.123.2.32 2003/04/11 03:13:57 hal9
+ Add small note about only one filterfile (as opposed to multiple actions
+ files).
+
+ Revision 1.123.2.31 2003/03/26 02:03:43 oes
+ Updated hard-coded copyright dates
+
+ Revision 1.123.2.30 2003/03/24 12:58:56 hal9
+ Add new section on Predefined Filters.
+
+ Revision 1.123.2.29 2003/03/20 02:45:29 hal9
+ More problems with \-\-chroot causing markup problems :(
+
+ Revision 1.123.2.28 2003/03/19 00:35:24 hal9
+ Manual edit of revision log because 'chroot' (even inside a comment) was
+ causing Docbook to hang here (due to double hyphen and the processor thinking
+ it was a comment).
+
+ Revision 1.123.2.27 2003/03/18 19:37:14 oes
+ s/Advanced|Radical/Adventuresome/g to avoid complaints re fun filter
+
+ Revision 1.123.2.26 2003/03/17 16:50:53 oes
+ Added documentation for new chroot option
+
+ Revision 1.123.2.25 2003/03/15 18:36:55 oes
+ Adapted to the new filters
+
+ Revision 1.123.2.24 2002/11/17 06:41:06 hal9
+ Move default profiles table from FAQ to U-M, and other minor related changes.
+ Add faq on cookies.
+
+ Revision 1.123.2.23 2002/10/21 02:32:01 hal9
+ Updates to the user.action examples section. A few new ones.
+
+ Revision 1.123.2.22 2002/10/12 00:51:53 hal9
+ Add demoronizer to filter section.
+
+ Revision 1.123.2.21 2002/10/10 04:09:35 hal9
+ s/Advanced/Radical/ and added very brief note.
+
+ Revision 1.123.2.20 2002/10/10 03:49:21 hal9
+ Add notes to session-cookies-only and Quickstart about pre-existing
+ cookies. Also, note content-cookies work differently.
+
+ Revision 1.123.2.19 2002/09/26 01:25:36 hal9
+ More explanation on Privoxy patterns, more on content-cookies and SSL.
+
+ Revision 1.123.2.18 2002/08/22 23:47:58 hal9
+ Add 'Documentation' to Privoxy Menu shot in Configuration section to match
+ CGIs.
+
+ Revision 1.123.2.17 2002/08/18 01:13:05 hal9
+ Spell checked (only one typo this time!).
+
+ Revision 1.123.2.16 2002/08/09 19:20:54 david__schmidt
+ Update to Mac OSX startup script name
+
+ Revision 1.123.2.15 2002/08/07 17:32:11 oes
+ Converted some internal links from ulink to link for PDF creation; no content changed
+
+ Revision 1.123.2.14 2002/08/06 09:16:13 oes
+ Nits re: actions file download
+
+ Revision 1.123.2.13 2002/08/02 18:23:19 g_sauthoff
+ Just 2 small corrections to the Gentoo sections
+
+ Revision 1.123.2.12 2002/08/02 18:17:21 g_sauthoff
+ Added 2 Gentoo sections
+
+ Revision 1.123.2.11 2002/07/26 15:20:31 oes
+ - Added version info to title
+ - Added info on new filters
+ - Revised parts of the filter file tutorial
+ - Added info on where to get updated actions files
+
+ Revision 1.123.2.10 2002/07/25 21:42:29 hal9
+ Add brief notes on not proxying non-HTTP protocols.
+
+ Revision 1.123.2.9 2002/07/11 03:40:28 david__schmidt
+
+ Updated Mac OSX sections due to installation location change
+
+ Revision 1.123.2.8 2002/06/09 16:36:32 hal9
+ Clarifications on filtering and MIME. Hardcode 'latest release' in index.html.
+
+ Revision 1.123.2.7 2002/06/09 00:29:34 hal9
+ Touch ups on filtering, in actions section and Anatomy.
+
+ Revision 1.123.2.6 2002/06/06 23:11:03 hal9
+ Fix broken link. Linkchecked all docs.
+
+ Revision 1.123.2.5 2002/05/29 02:01:02 hal9
+ This is break out of the entire config section from u-m, so it can
+ eventually be used to generate the comments, etc in the main config file
+ so that these are in sync with each other.
+
+ Revision 1.123.2.4 2002/05/27 03:28:45 hal9
+ Ooops missed something from David.
+
+ Revision 1.123.2.3 2002/05/27 03:23:17 hal9
+ Fix FIXMEs for OS2 and OSX startup. Fix Redhat typos (should be Red Hat).
+ That's a wrap, I think.
+
+ Revision 1.123.2.2 2002/05/26 19:02:09 hal9
+ Move Amiga stuff around to take of FIXME in start up section.
+
+ Revision 1.123.2.1 2002/05/26 17:04:25 hal9
+ -Spellcheck, very minor edits, and sync across branches
+
+ Revision 1.123 2002/05/24 23:19:23 hal9
+ Include new image (Proxy setup). More fun with guibutton.
+ Minor corrections/clarifications here and there.
+
+ Revision 1.122 2002/05/24 13:24:08 oes
+ Added Bookmarklet for one-click pre-filled access to show-url-info
+
+ Revision 1.121 2002/05/23 23:20:17 oes
+ - Changed more (all?) references to actions to the
+ <literal><link> style.
+ - Small fixes in the actions chapter
+ - Small clarifications in the quickstart to ad blocking
+ - Removed <emphasis> from <title>s since the new doc CSS
+ renders them red (bad in TOC).
+
+ Revision 1.120 2002/05/23 19:16:43 roro
+ Correct Debian specials (installation and startup).
+
+ Revision 1.119 2002/05/22 17:17:05 oes
+ Added Security hint
+
+ Revision 1.118 2002/05/21 04:54:55 hal9
+ -New Section: Quickstart to Ad Blocking
+ -Reformat Actions Anatomy to match new CGI layout
+
+ Revision 1.117 2002/05/17 13:56:16 oes
+ - Reworked & extended Templates chapter
+ - Small changes to Regex appendix
+ - #included authors.sgml into (C) and hist chapter
+
+ Revision 1.116 2002/05/17 03:23:46 hal9
+ Fixing merge conflict in Quickstart section.
+
+ Revision 1.115 2002/05/16 16:25:00 oes
+ Extended the Filter File chapter & minor fixes
+
+ 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
projects / privoxy.git / blobdiff