-<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+<!entity % dummy "INCLUDE">
+<!entity supported SYSTEM "supported.sgml">
+<!entity newfeatures SYSTEM "newfeatures.sgml">
+<!entity p-intro SYSTEM "privoxy.sgml">
+<!entity seealso SYSTEM "seealso.sgml">
+<!entity buildsource SYSTEM "buildsource.sgml">
+<!entity contacting SYSTEM "contacting.sgml">
+<!entity history SYSTEM "history.sgml">
+<!entity copyright SYSTEM "copyright.sgml">
+<!entity p-version "2.9.13">
+<!entity p-status "BETA">
+<!entity % p-not-stable "INCLUDE"> <!-- set to IGNORE for stable release -->
+<!entity % p-stable "IGNORE"> <!-- set INCLUDE for stable release -->
+<!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
+<!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
+<!entity % p-readme "IGNORE">
+<!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml -->
+]>
<!--
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
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.1 2001/09/12 15:36:41 swa Exp $
+ $Id: user-manual.sgml,v 1.66 2002/04/04 06:48:37 hal9 Exp $
Written by and Copyright (C) 2001 the SourceForge
- IJBSWA team. http://ijbswa.sourceforge.net
+ 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
+
-->
<article id="index">
<artheader>
-<title>Junkbuster User Manual</title>
+<title>Privoxy User Manual</title>
-<pubdate>$Id: user-manual.sgml,v 1.1 2001/09/12 15:36:41 swa Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.66 2002/04/04 06:48:37 hal9 Exp $</pubdate>
<authorgroup>
<author>
<affiliation>
- <orgname>By: Junkbuster Developers</orgname>
+ <orgname>By: Privoxy Developers</orgname>
</affiliation>
</author>
</authorgroup>
<abstract>
+<![%dummy;[
<para>
- The user manual gives the users information on how to install and
-configure the Internet Junkbuster. The Internet Junkbuster is an application
-that provides privacy and security to the user of the world wide web.
+ <comment>
+ This is here to keep vim syntax file from breaking :/
+ If I knew enough to fix it, I would.
+ PLEASE DO NOT REMOVE! HB: hal@foobox.net
+ </comment>
</para>
+]]>
+
<para>
-You can find the latest version of the user manual at <ulink url="http://ijbswa.sourceforge.net/doc/user-manual/">http://ijbswa.sourceforge.net/doc/user-manual/</ulink>.
- </para>
+ The user manual gives users information on how to install, configure and use
+ <application>Privoxy</application>.
+ </para>
+
+<!--
+ Include privoxy.sgml boilerplate:
+-->
+ &p-intro;
<para>
- Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>.
- </para>
+ You can find the latest version of the user manual at <ulink
+ url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
+ </para>
+
+<!-- <para> -->
+<!-- Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
+<!-- </para> -->
</abstract>
+
</artheader>
+
<!-- ~~~~~ New section ~~~~~ -->
+
<sect1 id="introduction"><title>Introduction</title>
-<para>To be filled.
+
+<para>
+ This documentation is included with the current &p-status; version of
+ <application>Privoxy</application> and is mostly complete at this
+ point. The most up to date reference for the time being is still the comments
+ in the source files and in the individual configuration files. Development
+ of version 3.0 is currently nearing completion, and includes many significant
+ changes and enhancements over earlier versions. The target release date for
+ stable v3.0 is <quote>soon</quote> ;-)
</para>
-</sect1>
+
+<![%p-not-stable;[
+<!-- include only in non-stable versions -->
+<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
+ CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
+ not many!
+</para>
+]]>
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="quickstart"><title>Quickstart to Using Junkbuster</title>
-<para>To be filled.
+<sect2>
+<title>New Features</title>
+<para>
+ In addition to <application>Internet Junkbuster's</application> traditional
+ feature of ad and banner blocking and cookie management,
+ <application>Privoxy</application> provides new features<![%p-not-stable;[,
+ some of them currently under development]]>:
</para>
+
+<!-- Include newfeatures.sgml boilerplate here: -->
+ &newfeatures;
+<!-- end boilerplate -->
+
+</sect2>
+
</sect1>
+<!-- ~ End section ~ -->
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="installation"><title>Installation</title>
-<para>To be filled.
+<para>
+ <application>Privoxy</application> is available as raw source code (tarball
+ or via CVS), or pre-compiled binaries for various platforms. See the <ulink
+ url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink> for
+ the most up to date release information.
+ <application>Privoxy</application> is also available via <ulink
+ url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/current/">CVS</ulink>.
+ <![%p-not-stable;[This is the recommended approach at this time.]]> But
+ please be aware that CVS is constantly changing, and it may break in
+ mysterious ways.
</para>
+<!-- Include supported.sgml boilerplate -->
+ &supported;
+<!-- end boilerplate -->
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-rh"><title>Red Hat</title>
-<para>To be filled.
+<sect2 id="installation-source"><title>Source</title>
+
+
+<!-- include buildsource.sgml boilerplate: -->
+ &buildsource;
+<!-- end boilerplate -->
+
+<para>
+ For Redhat and SuSE Linux RPM packages, see below.
</para>
-</sect2>
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-suse"><title>SuSE</title>
-<para>To be filled.
+<sect3 id="installation-rh"><title>Red Hat</title>
+<para>
+ To build Redhat RPM packages from source, install source as above. Then:
+</para>
+
+<para>
+ <screen>
+ autoheader
+ autoconf
+ ./configure
+ make redhat-dist
+ </screen>
+</para>
+
+<para>
+ This will create both binary and src RPMs in the usual places. Example:
</para>
-</sect2>
+
+<para>
+ /usr/src/redhat/RPMS/i686/privoxy-&p-version;-1.i686.rpm
+</para>
+<para>
+ /usr/src/redhat/SRPMS/privoxy-&p-version;-1.src.rpm
+</para>
+
+<para>
+ To install, of course:
+</para>
+
+<para>
+ <screen>
+ rpm -Uvv /usr/src/redhat/RPMS/i686/privoxy-&p-version;-1.i686.rpm
+ </screen>
+</para>
+
+<para>
+ This will place the <application>Privoxy</application> configuration
+ files in <filename>/etc/privoxy/</filename>, and log files in
+ <filename>/var/log/privoxy/</filename>. Run
+ <command>ckconfig privoxy on</command> to have
+ <application>Privoxy</application> start automatically during init.
+
+</para>
+
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-win"><title>Windows</title>
-<para>To be filled.
+<sect3 id="installation-suse"><title>SuSE</title>
+<para>
+ To build SuSE RPM packages, install source as above. Then:
</para>
-</sect2>
+
+<para>
+ <screen>
+ autoheader
+ autoconf
+ ./configure
+ make suse-dist
+ </screen>
+</para>
+
+<para>
+ This will create both binary and src RPMs in the usual places. Example:
+</para>
+
+<para>
+ /usr/src/packages/RPMS/i686/privoxy-&p-version;-1.i686.rpm
+</para>
+<para>
+ /usr/src/packages/SRPMS/privoxy-&p-version;-1.src.rpm
+</para>
+
+<para>
+ To install, of course:
+</para>
+
+<para>
+ <screen>
+ rpm -Uvv /usr/src/packages/RPMS/i686/privoxy-&p-version;-1.i686.rpm
+ </screen>
+</para>
+
+<para>
+ This will place the <application>Privoxy</application> configuration
+ files in <filename>/etc/privoxy/</filename>, and log files in
+ <filename>/var/log/privoxy/</filename>.
+</para>
+
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-os2"><title>OS/2</title>
+
+<!--
+Thanx David Schmidt!
+-->
+
+<para>
+ <application>Privoxy</application> is packaged in a WarpIN self-
+ installing archive. The self-installing program will be named depending
+ on the release version, something like:
+ <filename>privoxyos2_setup_&p-version;.exe</filename>. In order to install it, simply
+ run this executable or double-click on its icon and follow the WarpIN
+ installation panels. A shadow of the <application>Privoxy</application>
+ executable will be placed in your startup folder so it will start
+ automatically whenever OS/2 starts.
+</para>
+
+<para>
+ The directory you choose to install <application>Privoxy</application>
+ into will contain all of the configuration files.
+</para>
+
+<para>
+ If you would like to build binary images on OS/2 yourself, you will need
+ a few Unix-like tools: autoconf, autoheader and sh. These tools will be
+ used to create the required config.h file, which is not part of the
+ source distribution because it differs based on platform. You will also
+ need a compiler.
+ The distribution has been created using IBM VisualAge compilers, but you
+ can use any compiler you like. GCC/EMX has the disadvantage of needing
+ to be single-threaded due to a limitation of EMX's implementation of the
+ select() socket call.
+</para>
+
+<para>
+ In addition to needing the source code distribution as outlined earlier,
+ you will want to extract the <filename>os2seutp</filename> directory from CVS:
+ <screen>
+ cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
+ </screen>
+ This will create a directory named os2setup/, which will contain the
+ <filename>Makefile.vac</filename> makefile and <filename>os2build.cmd</filename>
+ which is used to completely create the binary distribution. The sequence
+ of events for building the executable for yourself goes something like this:
+ <screen>
+ cd current
+ autoheader
+ autoconf
+ sh configure
+ cd ..\os2setup
+ nmake -f Makefile.vac
+ </screen>
+ You will see this sequence laid out in <filename>os2build.cmd</filename>.
+</para>
+
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-win"><title>Windows</title>
+<para>Click-click. (I need help on this. Not a clue here. Also for
+configuration section below. HB.)
+</para>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-other"><title>Other</title>
-<para>To be filled.
+<sect3 id="installation-other"><title>Other</title>
+<para>
+ Some quick notes on other Operating Systems.
+</para>
+
+<para>
+ For FreeBSD (and other *BSDs?), the build will require <command>gmake</command>
+ instead of the included <command>make</command>. <command>gmake</command> is
+ available from <ulink url="http://www.gnu.org">http://www.gnu.org</ulink>.
+ The rest should be the same as above for Linux/Unix.
</para>
+
+</sect3>
</sect2>
</sect1>
+<!-- ~ End section ~ -->
+
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="configuration"><title>Configuration</title>
-<para>To be filled.
+
+<sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
+<para>
+ Before launching <application>Privoxy</application> for the first time, you
+ will want to configure your browser(s) to use <application>Privoxy</application>
+ as a HTTP and HTTPS proxy. The default is localhost for the proxy address,
+ and port 8118 (earlier versions used port 800). This is the one required
+ configuration that must be done!
+</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>
+
+<para>
+ After doing this, flush your browser's disk and memory caches to force a
+ re-reading of all pages and get rid of any ads that may be cached. You
+ are now ready to start enjoying the benefits of using
+ <application>Privoxy</application>.
+</para>
+
+
+<para>
+ <application>Privoxy</application> is typically started by specifying the
+ main configuration file to be used on the command line. Example Unix startup
+ command:
+</para>
+
+<para>
+ <screen>
+
+ # /usr/sbin/privoxy /etc/privoxy/config
+
+ </screen>
+</para>
+
+<para>
+ An init script is provided for SuSE and Redhat.
+</para>
+
+<para>
+For for SuSE: /etc/rc.d/privoxy start
</para>
-</sect1>
+
+<para>
+For RedHat: /etc/rc.d/init.d/privoxy start
+</para>
+
+
+<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.
+</para>
+
+
+<para>
+ The included default configuration files should give a reasonable starting
+ point, though may be somewhat aggressive in blocking junk. Most of the
+ per site configuration is done in the <quote>actions</quote> files. These
+ are where various cookie actions are defined, ad and banner blocking,
+ and other aspects of <application>Privoxy</application> configuration. There
+ are several such files included, with varying levels of aggressiveness.
+</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
+ default, most of these will be accepted only during the current browser
+ session, until you add them to the configuration. If you want the browser to
+ handle this instead, you will need to edit
+ <filename>default.action</filename> and disable this feature. If you use more
+ than one browser, it would make more sense to let
+ <application>Privoxy</application> handle this. In which case, the browser(s)
+ should be set to accept all cookies.
+</para>
+
+<para>
+ <application>Privoxy</application> is HTTP/1.1 compliant, but not all 1.1
+ features are as yet implemented. If browsers that support HTTP/1.1 (like
+ <application>Mozilla</application> or recent versions of I.E.) experience
+ problems, you might try to force HTTP/1.0 compatibility. For Mozilla, look
+ under <literal>Edit -> Preferences -> Debug -> Networking</literal>.
+ Or set the <quote>+downgrade</quote> config option in
+ <filename>default.action</filename>.
+</para>
+
+<para>
+ After running <application>Privoxy</application> for a while, you can
+ start to fine tune the configuration to suit your personal, or site,
+ preferences and requirements. There are many, many aspects that can
+ be customized. <quote>Actions</quote> (as specified in <filename>default.action</filename>)
+ can be adjusted by pointing your browser to
+ <ulink url="http://p.p/">http://p.p/</ulink>,
+ and then follow the link to <quote>edit the actions list</quote>.
+ (This is an internal page and does not require Internet access.)
+</para>
+
+<para>
+ In fact, various aspects of <application>Privoxy</application>
+ 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
+ editor mentioned above, <application>Privoxy</application> can also
+ be turned <quote>on</quote> and <quote>off</quote> from this page.
+</para>
+
+<para>
+ If you encounter problems, please verify it is a
+ <application>Privoxy</application> bug, by disabling
+ <application>Privoxy</application>, and then trying the same page.
+ Also, try another browser if possible to eliminate browser or site
+ problems. Before reporting it as a bug, see if there is not a configuration
+ option that is enabled that is causing the page not to load. You can then add
+ an exception for that page or site. For instance, try adding it to the
+ <literal>{fragile}</literal> section of <filename>default.action</filename>.
+ This will turn off most actions for this site. For more on troubleshooting
+ problem sites, see the <ulink
+ url="appendix.html#ACTIONSANAT">Appendix</ulink>. If a bug, please report it
+ to the developers (see below).
+</para>
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="contact"><title>Contact the developers</title>
-<para>To be filled. mention the support forums as the primary channel of
-communication (bugs, feature requests, etc.)
+
+<sect2>
+<title>Command Line Options</title>
+<para>
+ <application>Privoxy</application> may be invoked with the following
+ command-line options:
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <emphasis>--version</emphasis>
+ </para>
+ <para>
+ Print version info and exit, Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--help</emphasis>
+ </para>
+ <para>
+ Print a short usage info and exit, Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--no-daemon</emphasis>
+ </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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--pidfile FILE</emphasis>
+
+ </para>
+ <para>
+ On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
+ <emphasis>FILE</emphasis> on exit. Failiure to create or delete the
+ <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
+ option is given, no PID file will be used. Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--user USER[.GROUP]</emphasis>
+
+ </para>
+ <para>
+ After (optionally) writing the PID file, assume the user ID of
+ <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>
+ <para>
+ <emphasis>configfile</emphasis>
+ </para>
+ <para>
+ If no <emphasis>configfile</emphasis> is included on the command line,
+ <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.
+ </para>
+ </listitem>
+
+ </itemizedlist>
</para>
+
+</sect2>
+
</sect1>
+<!-- ~ End section ~ -->
+
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="copyright"><title>Copyright and History</title>
-<para>To be filled.
+<sect1 id="configuration"><title><application>Privoxy</application> 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>
+<para>
+ <application>Privoxy</application> can be reached by the special
+ URL <ulink url="http://p.p/">http://p.p/</ulink> (or alternately
+ <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>),
+ which is an internal page. You will see the following section:
+
</para>
-</sect1>
+
+<para>
+ <screen>
+
+Please choose from the following options:
+
+ * Show information about the current configuration
+ * Show the source code version numbers
+ * Show the client's request headers.
+ * Show which actions apply to a URL and why
+ * Toggle Privoxy on or off
+ * Edit the actions list
+
+ </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
+ <application>Privoxy</application>. This is an easy way to adjust various
+ aspects of <application>Privoxy</application> configuration. The actions
+ file, and other configuration files, are explained in detail below.
+ <application>Privoxy</application> will automatically detect any changes
+ to these files.
+</para>
+
+<para>
+ <quote>Toggle Privoxy On or Off</quote> is handy for sites that might
+ have problems with your current actions and filters, or just to test if
+ a site misbehaves, whether it is <application>Privoxy</application>
+ causing the problem or not. <application>Privoxy</application> continues
+ to run as a proxy in this case, but all filtering is disabled.
+
+</para>
+
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="seealso"><title>See also</title>
-<para>To be filled.
+
+<sect2>
+<title>Configuration Files Overview</title>
+<para>
+ For Unix, *BSD and Linux, all configuration files are located in
+ <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
+ AmigaOS these are all in the same directory as the
+ <application>Privoxy</application> executable. The name and number of
+ configuration files has changed from previous versions, and is subject to
+ change as development progresses.
</para>
-</sect1>
- <!--
+<para>
+ The installed defaults provide a reasonable starting point, though possibly
+ aggressive by some standards. For the time being, there are only three
+ default configuration files (this will change in time):
+</para>
- This program is free software; you can redistribute it
- and/or modify it under the terms of the GNU General
- Public License as published by the Free Software
- Foundation; either version 2 of the License, or (at
- your option) any later version.
+<para>
+ <itemizedlist>
- This program is distributed in the hope that it will
- be useful, but WITHOUT ANY WARRANTY; without even the
- implied warranty of MERCHANTABILITY or FITNESS FOR A
- PARTICULAR PURPOSE. See the GNU General Public
- License for more details.
+ <listitem>
+ <para>
+ The main configuration file is named <filename>config</filename>
+ on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
+ on Windows.
+ </para>
+ </listitem>
- 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.
+ <listitem>
+ <para>
+ The <filename>default.action</filename> file is used to define various
+ <quote>actions</quote> relating to images, banners, pop-ups, access
+ restrictions, banners and cookies. There is a CGI based editor for this
+ file that can be accessed via <ulink
+ url="http://p.p">http://p.p</ulink>. (Other actions
+ files are included as well with differing levels of filtering
+ and blocking, e.g. <filename>basic.action</filename>.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <filename>default.filter</filename> file can be used to re-write the raw
+ page content, including viewable text as well as embedded HTML and JavaScript,
+ and whatever else lurks on any given web page.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+<para>
+ <filename>default.action</filename> and <filename>default.filter</filename>
+ can use Perl style regular expressions for maximum flexibility. All files use
+ the <quote><literal>#</literal></quote> character to denote a comment. Such
+ lines are not processed by <application>Privoxy</application>. After
+ making any changes, there is no need to restart
+ <application>Privoxy</application> in order for the changes to take
+ effect. <application>Privoxy</application> should detect such changes
+ automatically.
+</para>
+
+<para>
+ While under development, the configuration content is subject to change.
+ The below documentation may not be accurate by the time you read this.
+ Also, what constitutes a <quote>default</quote> setting, may change, so
+ please check all your configuration files on important issues.
+</para>
+</sect2>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<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>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>blockfile blocklist.ini</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Indicates that the blockfile is named <quote>blocklist.ini</quote>. (A
+ default installation does not use this.)
+</para>
+
+<para>
+ A <quote><literal>#</literal></quote> indicates a comment. Any part of a
+ line following a <quote><literal>#</literal></quote> is ignored, except if
+ the <quote><literal>#</literal></quote> is preceded by a
+ <quote><literal>\</literal></quote>.
+</para>
+
+<para>
+ Thus, by placing a <quote><literal>#</literal></quote> at the start of an
+ existing configuration line, you can make it a comment and it will be treated
+ as if it weren't there. This is called <quote>commenting out</quote> an
+ option and can be useful to turn off features: If you comment out the
+ <quote>logfile</quote> line, <application>Privoxy</application> will not
+ log to a file at all. Watch for the <quote>default:</quote> section in each
+ explanation to see what happens if the option is left unset (or commented
+ out).
+</para>
+
+<para>
+ Long lines can be continued on the next line by using a
+ <quote><literal>\</literal></quote> as the very last character.
+</para>
+
+<para>
+ There are various aspects of <application>Privoxy</application> behavior
+ that can be tuned.
+</para>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3>
+<title>Defining Other Configuration Files</title>
+
+<para>
+ <application>Privoxy</application> can use a number of other files to tell it
+ what ads to block, what cookies to accept, and perform other functions. This
+ section of the configuration file tells <application>Privoxy</application>
+ where to find all those other files.
+</para>
+
+<para>
+ On <application>Windows</application> and <application>AmigaOS</application>,
+ <application>Privoxy</application> looks for these files in the same
+ directory as the executable. On Unix and OS/2,
+ <application>Privoxy</application> looks for these files in the current
+ working directory. In either case, an absolute path name can be used to
+ avoid problems.
+</para>
+
+<para>
+ When development goes modular and multi-user, the blocker, filter, and
+ per-user config will be stored in subdirectories of <quote>confdir</quote>.
+ For now, only <filename>confdir/templates</filename> is used for storing HTML
+ templates for CGI results.
+</para>
+
+<para>
+ The location of the configuration files:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>confdir /etc/privoxy</emphasis> # No trailing /, please.
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ The directory where all logging (i.e. <filename>logfile</filename> and
+ <filename>jarfile</filename>) takes place. No trailing
+ <quote><literal>/</literal></quote>, please:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>logdir /var/log/privoxy</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Note that all file specifications below are relative to
+ the above two directories!
+</para>
+
+<para>
+ The <quote>default.action</quote> file contains patterns to specify the
+ actions to apply to requests for each site. Default: Cookies to and from all
+ destinations are kept only during the current browser session (i.e. they are
+ not saved to disk). Pop-ups are disabled for all sites. All sites are
+ filtered through selected sections of <quote>default.filter</quote>. No sites
+ are blocked. <application>Privoxy</application> displays a checkboard type
+ pattern for filtered ads and other images. The syntax of this file is
+ explained in detail <link linkend="actionsfile">below</link>. Other
+ <quote>actions</quote> files are included, and you are free to use any of
+ them. They have varying degrees of aggressiveness.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>actionsfile default.action</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ The <quote>default.filter</quote> file contains content modification rules
+ that use <quote>regular expressions</quote>. These rules permit powerful
+ changes on the content of Web pages, e.g., you could disable your favorite
+ JavaScript annoyances, re-write the actual displayed text, or just have some
+ fun replacing <quote>Microsoft</quote> with <quote>MicroSuck</quote> wherever
+ it appears on a Web page. Default: whatever the developers are playing with
+ :-/
+</para>
+
+<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>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>filterfile default.filter</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ The logfile is where all logging and error messages are written. The logfile
+ can be useful for tracking down a problem with
+ <application>Privoxy</application> (e.g., it's not blocking an ad you
+ think it should block) but in most cases you probably will never look at it.
+</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.
+</para>
+
+<para>
+ Default: Log to the a file named <filename>logfile</filename>.
+ Comment out to disable logging.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>logfile logfile</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ The <quote>jarfile</quote> defines where
+ <application>Privoxy</application> stores the cookies it intercepts. Note
+ that if you use a <quote>jarfile</quote>, it may grow quite large. Default:
+ Don't store intercepted cookies.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>#jarfile jarfile</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If you specify a <quote>trustfile</quote>,
+ <application>Privoxy</application> will only allow access to sites that
+ are named in the trustfile. You can also mark sites as trusted referrers,
+ with the effect that access to untrusted sites will be granted, if a link
+ from a trusted referrer was used. The link target will then be added to the
+ <quote>trustfile</quote>. This is a very restrictive feature that typical
+ users most probably want to leave disabled. Default: Disabled, don't use the
+ trust mechanism.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>#trustfile trust</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If you use the trust mechanism, it is a good idea to write up some on-line
+ documentation about your blocking policy and to specify the URL(s) here. They
+ will appear on the page that your users receive when they try to access
+ untrusted content. Use multiple times for multiple URLs. Default: Don't
+ display links on the <quote>untrusted</quote> info page.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>trust-info-url http://www.example.com/why_we_block.html</emphasis>
+ <emphasis>trust-info-url http://www.example.com/what_we_allow.html</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3>
+<title>Other Configuration Options</title>
+
+<para>
+ This part of the configuration file contains options that control how
+ <application>Privoxy</application> operates.
+</para>
+
+<para>
+ <quote>Admin-address</quote> should be set to the email address of the proxy
+ administrator. It is used in many of the proxy-generated pages. Default:
+ fill@me.in.please.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>#admin-address fill@me.in.please</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ <quote>Proxy-info-url</quote> can be set to a URL that contains more info
+ about this <application>Privoxy</application> installation, it's
+ configuration and policies. It is used in many of the proxy-generated pages
+ and its use is highly recommended in multi-user installations, since your
+ users will want to know why certain content is blocked or modified. Default:
+ Don't show a link to on-line documentation.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>proxy-info-url http://www.example.com/proxy.html</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ <quote>Listen-address</quote> specifies the address and port where
+ <application>Privoxy</application> will listen for connections from your
+ Web browser. The default is to listen on the localhost port 8118, and
+ this is suitable for most users. (In your web browser, under proxy
+ configuration, list the proxy server as <quote>localhost</quote> and the
+ port as <quote>8118</quote>).
+</para>
+
+<para>
+ If you already have another service running on port 8118, or if you want to
+ serve requests from other machines (e.g. on your local network) as well, you
+ will need to override the default. The syntax is
+ <quote>listen-address [<ip-address>]:<port></quote>. If you leave
+ out the IP address, <application>Privoxy</application> will bind to all
+ interfaces (addresses) on your machine and may become reachable from the
+ Internet. In that case, consider using access control lists (acl's) (see
+ <quote>aclfile</quote> above), or a firewall.
+</para>
+
+<para>
+ For example, suppose you are running <application>Privoxy</application> on
+ a machine which has the address 192.168.0.1 on your local private network
+ (192.168.0.0) and has another outside connection with a different address.
+ You want it to serve requests from inside only:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>listen-address 192.168.0.1:8118</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If you want it to listen on all addresses (including the outside
+ connection):
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>listen-address :8118</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If you do this, consider using ACLs (see <quote>aclfile</quote> above). Note:
+ you will need to point your browser(s) to the address and port that you have
+ configured here. Default: localhost:8118 (127.0.0.1:8118).
+</para>
+
+<para>
+ The debug option sets the level of debugging information to log in the
+ logfile (and to the console in the Windows version). A debug level of 1 is
+ informative because it will show you each request as it happens. Higher
+ levels of debug are probably only of interest to developers.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ debug 1 # GPC = show each GET/POST/CONNECT request
+ debug 2 # CONN = show each connection status
+ debug 4 # IO = show I/O status
+ debug 8 # HDR = show header parsing
+ debug 16 # LOG = log all data into the logfile
+ debug 32 # FRC = debug force feature
+ debug 64 # REF = debug regular expression filter
+ debug 128 # = debug fast redirects
+ debug 256 # = debug GIF de-animation
+ debug 512 # CLF = Common Log Format
+ debug 1024 # = debug kill pop-ups
+ debug 4096 # INFO = Startup banner and warnings.
+ debug 8192 # ERROR = Non-fatal errors
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ It is <emphasis>highly recommended</emphasis> that you enable ERROR
+ reporting (debug 8192), at least until v3.0 is released.
+</para>
+
+<para>
+ The reporting of FATAL errors (i.e. ones which crash
+ <application>Privoxy</application>) is always on and cannot be disabled.
+</para>
+
+<para>
+ If you want to use CLF (Common Log Format), you should set <quote>debug
+ 512</quote> ONLY, do not enable anything else.
+</para>
+
+<para>
+ Multiple <quote>debug</quote> directives, are OK - they're logical-OR'd
+ together.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>debug 15 # same as setting the first 4 listed above</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Default:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>debug 1 # URLs</emphasis>
+ <emphasis>debug 4096 # Info</emphasis>
+ <emphasis>debug 8192 # Errors - *we highly recommended enabling this*</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ <application>Privoxy</application> normally uses
+ <quote>multi-threading</quote>, a software technique that permits it to
+ handle many different requests simultaneously. In some cases you may wish to
+ disable this -- particularly if you're trying to debug a problem. The
+ <quote>single-threaded</quote> option forces
+ <application>Privoxy</application> to handle requests sequentially.
+ Default: Multi-threaded mode.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>#single-threaded</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ <quote>toggle</quote> allows you to temporarily disable all
+ <application>Privoxy's</application> filtering. Just set <quote>toggle
+ 0</quote>.
+</para>
+
+<para>
+ The Windows version of <application>Privoxy</application> puts an icon in
+ the system tray, which also allows you to change this option. If you
+ right-click on that icon (or select the <quote>Options</quote> menu), one
+ choice is <quote>Enable</quote>. Clicking on enable toggles
+ <application>Privoxy</application> on and off. This is useful if you want
+ to temporarily disable <application>Privoxy</application>, e.g., to access
+ a site that requires cookies which you would otherwise have blocked. This can also
+ be toggled via a web browser at the <application>Privoxy</application>
+ internal address of <ulink url="http://p.p">http://p.p</ulink> on
+ any platform.
+</para>
+
+<para>
+ <quote>toggle 1</quote> means <application>Privoxy</application> runs
+ normally, <quote>toggle 0</quote> means that
+ <application>Privoxy</application> becomes a non-anonymizing non-blocking
+ proxy. Default: 1 (on).
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>toggle 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ For content filtering, i.e. the <quote>+filter</quote> and
+ <quote>+deanimate-gif</quote> actions, it is necessary that
+ <application>Privoxy</application> buffers the entire document body.
+ This can be potentially dangerous, since a server could just keep sending
+ data indefinitely and wait for your RAM to exhaust. With nasty consequences.
+</para>
+
+<para>
+ The <application>buffer-limit</application> option lets you set the maximum
+ size in Kbytes that each buffer may use. When the documents buffer exceeds
+ this size, it is flushed to the client unfiltered and no further attempt to
+ filter the rest of it is made. Remember that there may multiple threads
+ running, which might require increasing the <quote>buffer-limit</quote>
+ Kbytes <emphasis>each</emphasis>, unless you have enabled
+ <quote>single-threaded</quote> above.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>buffer-limit 4069</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ To enable the web-based <filename>default.action</filename> file editor set
+ <application>enable-edit-actions</application> to 1, or 0 to disable. Note
+ that you must have compiled <application>Privoxy</application> with
+ support for this feature, otherwise this option has no effect. This
+ internal page can be reached at <ulink
+ url="http://p.p">http://p.p</ulink>.
+ </para>
+
+<para>
+ Security note: If this is enabled, anyone who can use the proxy
+ can edit the actions file, and their changes will affect all users.
+ For shared proxies, you probably want to disable this. Default: enabled.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>enable-edit-actions 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Allow <application>Privoxy</application> to be toggled on and off
+ remotely, using your web browser. Set <quote>enable-remote-toggle</quote>to
+ 1 to enable, and 0 to disable. Note that you must have compiled
+ <application>Privoxy</application> with support for this feature,
+ otherwise this option has no effect.
+</para>
+
+<para>
+ Security note: If this is enabled, anyone who can use the proxy can toggle
+ it on or off (see <ulink url="http://p.p">http://p.p</ulink>), and
+ their changes will affect all users. For shared proxies, you probably want to
+ disable this. Default: enabled.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>enable-remote-toggle 1</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3>
+<title>Access Control List (ACL)</title>
+<para>
+ Access controls are included at the request of some ISPs and systems
+ administrators, and are not usually needed by individual users. Please note
+ the warnings in the FAQ that this proxy is not intended to be a substitute
+ for a firewall or to encourage anyone to defer addressing basic security
+ weaknesses.
+</para>
+
+<para>
+ If no access settings are specified, the proxy talks to anyone that
+ connects. If any access settings file are specified, then the proxy
+ talks only to IP addresses permitted somewhere in this file and not
+ denied later in this file.
+</para>
+
+<para>
+ Summary -- if using an ACL:
+</para>
+
+ <simplelist>
+ <member>
+ Client must have permission to receive service.
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ LAST match in ACL wins.
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ Default behavior is to deny service.
+ </member>
+ </simplelist>
+
+<para>
+ The syntax for an entry in the Access Control List is:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ ACTION SRC_ADDR[/SRC_MASKLEN] [ DST_ADDR[/DST_MASKLEN] ]
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Where the individual fields are:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>ACTION</emphasis> = <quote>permit-access</quote> or <quote>deny-access</quote>
+
+ <emphasis>SRC_ADDR</emphasis> = client hostname or dotted IP address
+ <emphasis>SRC_MASKLEN</emphasis> = number of bits in the subnet mask for the source
+
+ <emphasis>DST_ADDR</emphasis> = server or forwarder hostname or dotted IP address
+ <emphasis>DST_MASKLEN</emphasis> = number of bits in the subnet mask for the target
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+
+<para>
+ The field separator (FS) is whitespace (space or tab).
+</para>
+
+<para>
+ IMPORTANT NOTE: If <application>Privoxy</application> is using a
+ forwarder (see below) or a gateway for a particular destination URL, the
+ <literal>DST_ADDR</literal> that is examined is the address of the forwarder
+ or the gateway and <emphasis>NOT</emphasis> the address of the ultimate
+ target. This is necessary because it may be impossible for the local
+ <application>Privoxy</application> to determine the address of the
+ ultimate target (that's often what gateways are used for).
+</para>
+
+<para>
+ Here are a few examples to show how the ACL features work:
+</para>
+
+<para>
+ <quote>localhost</quote> is OK -- no DST_ADDR implies that
+ <emphasis>ALL</emphasis> destination addresses are OK:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>permit-access localhost</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ A silly example to illustrate permitting any host on the class-C subnet with
+ <application>Privoxy</application> to go anywhere:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>permit-access www.privoxy.com/24</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Except deny one particular IP address from using it at all:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>deny-access ident.privoxy.com</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ You can also specify an explicit network address and subnet mask.
+ Explicit addresses do not have to be resolved to be used.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>permit-access 207.153.200.0/24</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ A subnet mask of 0 matches anything, so the next line permits everyone.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>permit-access 0.0.0.0/0</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Note, you <emphasis>cannot</emphasis> say:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>permit-access .org</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ to allow all *.org domains. Every IP address listed must resolve fully.
+</para>
+
+<para>
+ An ISP may want to provide a <application>Privoxy</application> that is
+ accessible by <quote>the world</quote> and yet restrict use of some of their
+ private content to hosts on its internal network (i.e. its own subscribers).
+ Say, for instance the ISP owns the Class-B IP address block 123.124.0.0 (a 16
+ bit netmask). This is how they could do it:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>permit-access 0.0.0.0/0 0.0.0.0/0</emphasis> # other clients can go anywhere
+ # with the following exceptions:
+
+ <emphasis>deny-access</emphasis> 0.0.0.0/0 123.124.0.0/16 # block all external requests for
+ # sites on the ISP's network
+
+ <emphasis>permit 0.0.0.0/0 www.my_isp.com</emphasis> # except for the ISP's main
+ # web site
+
+ <emphasis>permit 123.124.0.0/16 0.0.0.0/0</emphasis> # the ISP's clients can go
+ # anywhere
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Note that if some hostnames are listed with multiple IP addresses,
+ the primary value returned by DNS (via gethostbyname()) is used. Default:
+ Anyone can access the proxy.
+</para>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 id="forwarding">
+<title>Forwarding</title>
+
+<para>
+ This feature allows chaining of HTTP requests via multiple proxies.
+ It can be used to better protect privacy and confidentiality when
+ accessing specific domains by routing requests to those domains
+ to a special purpose filtering proxy such as lpwa.com. Or to use
+ a caching proxy to speed up browsing.
+</para>
+
+<para>
+ It can also be used in an environment with multiple networks to route
+ requests via multiple gateways allowing transparent access to multiple
+ networks without having to modify browser configurations.
+</para>
+
+<para>
+ Also specified here are SOCKS proxies. <application>Privoxy</application>
+ SOCKS 4 and SOCKS 4A. The difference is that SOCKS 4A will resolve the target
+ hostname using DNS on the SOCKS server, not our local DNS client.
+</para>
+
+<para>
+ The syntax of each line is:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward target_domain[:port] http_proxy_host[:port]</emphasis>
+ <emphasis>forward-socks4 target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]</emphasis>
+ <emphasis>forward-socks4a target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ If http_proxy_host is <quote>.</quote>, then requests are not forwarded to a
+ HTTP proxy but are made directly to the web servers.
+</para>
+
+<para>
+ Lines are checked in sequence, and the last match wins.
+</para>
+
+<para>
+ There is an implicit line equivalent to the following, which specifies that
+ anything not finding a match on the list is to go out without forwarding
+ or gateway protocol, like so:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward .* . </emphasis># implicit
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ In the following common configuration, everything goes to Lucent's LPWA,
+ except SSL on port 443 (which it doesn't handle):
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward .* lpwa.com:8000</emphasis>
+ <emphasis>forward :443 .</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+<!--
+ See the FAQ for instructions on how to automate the login procedure for LPWA.
+-->
+ Some users have reported difficulties related to LPWA's use of
+ <quote>.</quote> as the last element of the domain, and have said that this
+ can be fixed with this:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward lpwa. lpwa.com:8000</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ (NOTE: the syntax for specifying target_domain has changed since the
+ previous paragraph was written -- it will not work now. More information
+ is welcome.)
+</para>
+
+<para>
+ In this fictitious example, everything goes via an ISP's caching proxy,
+ except requests to that ISP:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward .* caching.myisp.net:8000</emphasis>
+ <emphasis>forward myisp.net .</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ For the @home network, we're told the forwarding configuration is this:
+</para>
+
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward .* proxy:8080</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Also, we're told they insist on getting cookies and JavaScript, so you should
+ allow cookies from home.com. We consider JavaScript a potential security risk.
+ Java need not be enabled.
+</para>
+
+<para>
+ In this example direct connections are made to all <quote>internal</quote>
+ domains, but everything else goes through Lucent's LPWA by way of the
+ company's SOCKS gateway to the Internet.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward-socks4 .* lpwa.com:8000 firewall.my_company.com:1080</emphasis>
+ <emphasis>forward my_company.com .</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ This is how you could set up a site that always uses SOCKS but no forwarders:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward-socks4a .* . firewall.my_company.com:1080</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ An advanced example for network administrators:
+</para>
+
+<para>
+ If you have links to multiple ISPs that provide various special content to
+ their subscribers, you can configure forwarding to pass requests to the
+ specific host that's connected to that ISP so that everybody can see all
+ of the content on all of the ISPs.
+</para>
+
+<para>
+ This is a bit tricky, but here's an example:
+</para>
+
+
+<para>
+ host-a has a PPP connection to isp-a.com. And host-b has a PPP connection to
+ isp-b.com. host-a can run a <application>Privoxy</application> proxy with
+ forwarding like this:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward .* .</emphasis>
+ <emphasis>forward isp-b.com host-b:8118</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ host-b can run a <application>Privoxy</application> proxy with forwarding
+ like this:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward .* .</emphasis>
+ <emphasis>forward isp-a.com host-a:8118</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Now, <emphasis>anyone</emphasis> on the Internet (including users on host-a
+ and host-b) can set their browser's proxy to <emphasis>either</emphasis>
+ host-a or host-b and be able to browse the content on isp-a or isp-b.
+</para>
+
+<para>
+ Here's another practical example, for University of Kent at
+ Canterbury students with a network connection in their room, who
+ need to use the University's Squid web cache.
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>forward *. ssbcache.ukc.ac.uk:3128</emphasis> # Use the proxy, except for:
+ <emphasis>forward .ukc.ac.uk . </emphasis> # Anything on the same domain as us
+ <emphasis>forward * . </emphasis> # Host with no domain specified
+ <emphasis>forward 129.12.*.* . </emphasis> # A dotted IP on our /16 network.
+ <emphasis>forward 127.*.*.* . </emphasis> # Loopback address
+ <emphasis>forward localhost.localdomain . </emphasis> # Loopback address
+ <emphasis>forward www.ukc.mirror.ac.uk . </emphasis> # Specific host
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<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>
+Your squid configuration could then look like this (assuming that the IP
+address of the box is <literal>192.168.0.1</literal> ):
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # Define Privoxy as parent cache
+ <!-- per feedback from user...
+ cache_peer 127.0.0.1 8118 parent 0 no-query
+ -->
+ cache_peer 192.168.0.1 parent 8118 0 no-query
+
+ # don't listen to the whole world
+ http_port 192.168.0.1:3128
+
+ # define the local lan
+ acl mylocallan src 192.168.0.1-192.168.0.5/255.255.255.255
+
+ # grant access for http to local lan
+ http_access allow mylocallan
+
+ # Define ACL for protocol FTP
+ acl FTP proto FTP
+
+ # Do not forward ACL FTP to privoxy
+ always_direct allow FTP
+
+ # Do not forward ACL CONNECT (https) to privoxy
+ always_direct allow CONNECT
+
+ # Forward the rest to privoxy
+ never_direct allow all
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3>
+<title>Windows GUI Options</title>
+<!--
+Removed references to Win32. HB 09/23/01
+-->
+<para>
+ <application>Privoxy</application> has a number of options specific to the
+ Windows GUI interface:
+</para>
+
+<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 <quote>default.action</quote> file (formerly
+ <filename>actionsfile</filename> or <filename>ijb.action</filename>) is used
+ to define what actions <application>Privoxy</application> takes, and thus
+ determines how ad images, cookies and various other aspects of HTTP content
+ and transactions are handled. These can be accepted or rejected for all
+ sites, or just those sites you choose. See below for a complete list of
+ actions.
+</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).
+ Changes to <filename>default.action</filename> should be immediately visible
+ to <application>Privoxy</application> without the need to restart.
+</para>
+
+<para>
+ Note that some sites may misbehave, or possibly not work at all with some
+ actions. This may require some tinkering with the rules to get the most
+ mileage of <application>Privoxy's</application> features, and still be
+ able to see and enjoy just what you want to. There is no general rule of
+ thumb on these things. There just are too many variables, and sites are
+ always changing.
+
+</para>
+
+<para>
+ The easiest way to edit the <quote>actions</quote> file is with a browser by
+ loading <ulink url="http://p.p/">http://p.p/</ulink>, and then select
+ <quote>Edit Actions List</quote>. A text editor can also be used.
+</para>
+
+<para>
+ To determine which actions apply to a request, the URL of the request is
+ compared to all patterns in this file. Every time it matches, the list of
+ applicable actions for the URL is incrementally updated. You can trace
+ this process by visiting <ulink
+ url="http://p.p/show-url-info">http://p.p/show-url-info</ulink>.
+</para>
+
+
+<para>
+ There are four types of lines in this file: comments (begin with a
+ <quote>#</quote> character), actions, aliases and patterns, all of which are
+ explained below, as well as the configuration file syntax that
+ <application>Privoxy</application> understands.
+
+</para>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3>
+<title>URL Domain and Path Syntax</title>
+<para>
+ Generally, a pattern has the form <domain>/<path>, where both the
+ <domain> and <path> part are optional. If you only specify a
+ domain part, the <quote>/</quote> can be left out:
+</para>
+
+<para>
+ <emphasis>www.example.com</emphasis> - is a domain only pattern and will match any request to
+ <quote>www.example.com</quote>.
+</para>
+
+<para>
+ <emphasis>www.example.com/</emphasis> - means exactly the same.
+</para>
+
+<para>
+ <emphasis>www.example.com/index.html</emphasis> - matches only the single
+ document <quote>/index.html</quote> on <quote>www.example.com</quote>.
+</para>
+
+<para>
+ <emphasis>/index.html</emphasis> - matches the document <quote>/index.html</quote>,
+ regardless of the domain. So would match any page named <quote>index.html</quote>
+ on any site.
+</para>
+
+<para>
+ <emphasis>index.html</emphasis> - matches nothing, since it would be
+ interpreted as a domain name and there is no top-level domain called
+ <quote>.html</quote>.
+</para>
+
+<para>
+ The matching of the domain part offers some flexible options: if the
+ domain starts or ends with a dot, it becomes unanchored at that end.
+ For example:
+</para>
+
+<para>
+ <emphasis>.example.com</emphasis> - matches any domain or sub-domain that
+ <emphasis>ENDS</emphasis> in <quote>.example.com</quote>.
+</para>
+
+<para>
+ <emphasis>www.</emphasis> - matches any domain that <emphasis>STARTS</emphasis> with
+ <quote>www</quote>.
+</para>
+
+<para>
+ Additionally, there are wild-cards that you can use in the domain names
+ themselves. They work pretty similar to shell wild-cards: <quote>*</quote>
+ stands for zero or more arbitrary characters, <quote>?</quote> stands for
+ any single character. And you can define character classes in square
+ brackets and they can be freely mixed:
+</para>
+
+<para>
+ <emphasis>ad*.example.com</emphasis> - matches <quote>adserver.example.com</quote>,
+ <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>.
+</para>
+
+<para>
+ <emphasis>*ad*.example.com</emphasis> - matches all of the above, and then some.
+</para>
+
+<para>
+ <emphasis>.?pix.com</emphasis> - matches <quote>www.ipix.com</quote>,
+ <quote>pictures.epix.com</quote>, <quote>a.b.c.d.e.upix.com</quote>, etc.
+</para>
+
+<para>
+ <emphasis>www[1-9a-ez].example.com</emphasis> - matches <quote>www1.example.com</quote>,
+ <quote>www4.example.com</quote>, <quote>wwwd.example.com</quote>,
+ <quote>wwwz.example.com</quote>, etc., but <emphasis>not</emphasis>
+ <quote>wwww.example.com</quote>.
+</para>
+
+<para>
+ If <application>Privoxy</application> was compiled with
+ <quote>pcre</quote> support (the default), Perl compatible regular expressions
+ can be used. These are more flexible and powerful than other types
+ of <quote>regular expressions</quote>. See the <filename>pcre/docs/</filename> directory or <quote>man
+ perlre</quote> (also available on <ulink
+ url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>)
+ for details. A brief discussion of regular expressions is in the
+ <link linkend="regex">Appendix</link>. For instance:
+</para>
+
+<para>
+ <emphasis>/.*/advert[0-9]+\.jpe?g</emphasis> - would match a URL from any
+ domain, with any path that includes <quote>advert</quote> followed
+ immediately by one or more digits, then a <quote>.</quote> and ending in
+ either <quote>jpeg</quote> or <quote>jpg</quote>. So we match
+ <quote>example.com/ads/advert2.jpg</quote>, and
+ <quote>www.example.com/ads/banners/advert39.jpeg</quote>, but not
+ <quote>www.example.com/ads/banners/advert39.gif</quote> (no gifs in the
+ example pattern).
+</para>
+
+<para>
+ Please note that matching in the path is case
+ <emphasis>INSENSITIVE</emphasis> by default, but you can switch to case
+ sensitive at any point in the pattern by using the
+ <quote>(?-i)</quote> switch:
+</para>
+
+<para>
+ <emphasis>www.example.com/(?-i)PaTtErN.*</emphasis> - will match only
+ documents whose path starts with <quote>PaTtErN</quote> in
+ <emphasis>exactly</emphasis> this capitalization.
+</para>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<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>
+
+<para>
+ <itemizedlist>
+
+ <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>
+
+
+ <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>
+
+ </itemizedlist>
+</para>
+
+<para>
+ If nothing is specified in this file, no <quote>actions</quote> are taken.
+ So in this case <application>Privoxy</application> would just be a
+ normal, non-blocking, non-anonymizing proxy. You must specifically
+ enable the privacy and blocking features you need (although the
+ provided default <filename>default.action</filename> file will
+ give a good starting point).
+</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. For
+ multi-valued actions, the actions are applied in the order they are
+ specified.
+</para>
+
+<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:
+ http://some.place/some_script?http://some.where-else.
+ </para>
+ <para>
+ Sometimes, there are even multiple consecutive redirects encoded in the
+ URL. These redirections via scripts make your web browsing more traceable,
+ since the server from which you follow such a link can see where you go to.
+ Apart from that, valuable bandwidth and time is wasted, while your browser
+ ask the server for one redirect after the other. Plus, it feeds the
+ advertisers.
+ </para>
+ <para>
+ The <quote>+fast-redirects</quote> option enables interception of these
+ types of requests by <application>Privoxy</application>, who will cut off
+ all but the last valid URL in the request and send a local redirect back to
+ your browser without contacting the intermediate site(s).
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ <emphasis>+fast-redirects</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Apply the filters in the <literal>section_header</literal>
+ section of the <filename>default.filter</filename> file to the site(s).
+ <filename>default.filter</filename> sections are grouped according to like
+ functionality. <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>
+
+ <para>
+ Filter sections that are pre-defined in the supplied
+ <filename>default.filter</filename> include:
+ </para>
+
+ <blockquote>
+ <simplelist>
+ <member>
+ <emphasis>html-annoyances</emphasis>: Get rid of particularly annoying HTML abuse.
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>js-annoyances</emphasis>: Get rid of particularly annoying JavaScript abuse
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>no-poups</emphasis>: Kill all popups in JS and HTML
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>frameset-borders</emphasis>: Give frames a border
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>webbugs</emphasis>: Squish WebBugs (1x1 invisible GIFs used for user tracking)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>no-refresh</emphasis>: Automatic refresh sucks on auto-dialup lines
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>fun</emphasis>: Text replacements for subversive browsing fun!
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>nimda</emphasis>: Remove (virus) Nimda code.
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>banners-by-size</emphasis>: Kill banners by size
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>crude-parental</emphasis>: Kill all web pages that contain the words "sex" or "warez"
+ </member>
+ </simplelist>
+ </blockquote>
+
+ </listitem>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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. 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 advertizement. There are five options.
+ <quote>-image-blocker</quote> will send a HTML <quote>blocked</quote> page,
+ usually resulting in a <quote>broken image</quote> icon.
+<!-- <quote>+image-blocker{logo}</quote> will send a -->
+<!-- <application>Privoxy</application> logo -->
+<!-- image. -->
+<quote>+image-blocker{blank}</quote> will send a 1x1 transparent GIF
+image. And finally, <quote>+image-blocker{http://xyz.com}</quote> will send a
+HTTP temporary redirect to the specified image. This has the advantage of the
+icon being being cached by the browser, which will speed up the display.
+<quote>+image-blocker{pattern}</quote> will send a checkboard type pattern
+<!-- , -->
+<!-- which scales better than the logo (which can get blocky if the browser -->
+<!-- enlarges it too much). -->
+ </para>
+ <para>
+ <literal>
+ <msgtext>
+ <literallayout>
+<!-- <emphasis>+image-blocker{logo}</emphasis> -->
+ <emphasis>+image-blocker{blank}</emphasis>
+ <emphasis>+image-blocker{pattern}</emphasis>
+ <emphasis>+image-blocker{http://p.p/send-banner}</emphasis>
+ </literallayout>
+ </msgtext>
+ </literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ By default (i.e. in the absence of a <quote>+limit-connect</quote>
+ action), <application>Privoxy</application> will only allow CONNECT
+ requests to port 443, which is the standard port for https as a
+ precaution.
+ </para>
+
+ <para>
+ The CONNECT methods exists in HTTP to allow access to secure websites
+ (https:// URLs) through proxies. It works very simply: the proxy
+ connects to the server on the specified port, and then short-circuits
+ its connections to the client <emphasis>and</emphasis> to the remote proxy.
+ This can be a big security hole, since CONNECT-enabled proxies can
+ be abused as TCP relays very easily.
+ </para>
+
+ <para>
+ If you want to allow CONNECT for more ports than this, or want to forbid
+ CONNECT altogether, you can specify a comma separated list of ports and
+ port ranges (the latter using dashes, with the minimum defaulting to 0 and
+ max to 65K):
+ </para>
+
+ <para>
+ <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>
+
+ </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>
+ <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>
+
+ </itemizedlist>
+</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>.
+</para>
+
+<para>
+ Some examples:
+</para>
+
+<para>
+ Turn off cookies by default, then allow a few through for specified sites:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # Turn off all persistent cookies
+ { +no-cookies-read }
+ { +no-cookies-set }
+ # Allow cookies for this browser session ONLY
+ { +no-cookies-keep }
+
+ # Exceptions to the above, sites that benefit from persistent cookies
+ { -no-cookies-read }
+ { -no-cookies-set }
+ { -no-cookies-keep }
+ .javasoft.com
+ .sun.com
+ .yahoo.com
+ .msdn.microsoft.com
+ .redhat.com
+
+ # Alternative way of saying the same thing
+ {-no-cookies-set -no-cookies-read -no-cookies-keep}
+ .sourceforge.net
+ .sf.net
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Now turn off <quote>fast redirects</quote>, and then we allow two exceptions:
+</para>
+
+<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>
+
+<para>
+ Turn on page filtering according to rules in the defined sections
+ of <filename>refilterfile</filename>, and make one exception for
+ sourceforge:
+ </para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # Run everything through the filter file, using only the
+ # specified sections:
+ +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}\
+ +filter{webbugs} +filter{nimda} +filter{banners-by-size}
+
+ # Then disable filtering of code from sourceforge!
+ {-filter}
+ .cvs.sourceforge.net
+ </literallayout>
+ </msgtext>
+ </literal>
+</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>
+
+<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>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ 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>
+
+<para>
+ Now let's define a few aliases:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # Useful customer aliases we can use later. These must come first!
+ {{alias}}
+ +no-cookies = +no-cookies-set +no-cookies-read
+ -no-cookies = -no-cookies-set -no-cookies-read
+ fragile = -block -no-cookies -filter -fast-redirects -hide-referer -no-popups
+ shop = -no-cookies -filter -fast-redirects
+ +imageblock = +block +image
+
+ #For people who don't like to type too much: ;-)
+ c0 = +no-cookies
+ c1 = -no-cookies
+ c2 = -no-cookies-set +no-cookies-read
+ c3 = +no-cookies-set -no-cookies-read
+ #... etc. Customize to your heart's content.
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Some examples using our <quote>shop</quote> and <quote>fragile</quote>
+ aliases from above:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ # These sites are very complex and require
+ # minimal interference.
+ {fragile}
+ .office.microsoft.com
+ .windowsupdate.microsoft.com
+ .nytimes.com
+
+ # Shopping sites - still want to block ads.
+ {shop}
+ .quietpc.com
+ .worldpay.com # for quietpc.com
+ .jungle.com
+ .scan.co.uk
+
+ # These shops require pop-ups
+ {shop -no-popups}
+ .dabs.com
+ .overclockers.co.uk
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<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.
+
+</para>
+
+</sect3>
+</sect2>
+
+<!-- ~ 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>
+
+<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>.
+</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>:
+</para>
+
+<para>
+ Stop web pages from displaying annoying messages in the status bar by
+ deleting such references:
+</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>
+</para>
+
+<para>
+ Just for kicks, replace any occurrence of <quote>Microsoft</quote> with
+ <quote>MicroSuck</quote>, and have a little fun with topical buzzwords:
+</para>
+
+<para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ FILTER: fun
+
+ s/microsoft(?!.com)/MicroSuck/ig
+
+ # Buzzword Bingo:
+ #
+ s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></font>/ig
+ </literallayout>
+ </msgtext>
+ </literal>
+</para>
+
+<para>
+ Kill those pesky little web-bugs:
+</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>
+</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.
+</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>
+</sect2>
+
+</sect1>
+
+<!-- ~ End section ~ -->
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
+Requests</title>
+
+<!-- Include contacting.sgml boilerplate: -->
+
+ &contacting;
+
+<!-- end boilerplate -->
+
+</sect1>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="copyright"><title>Copyright and History</title>
+
+<sect2><title>Copyright</title>
+<!-- Include copyright.sgml: -->
+ ©right;
+<!-- end copyright -->
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="history"><title>History</title>
+<!-- Include history.sgml: -->
+ &history;
+<!-- end history -->
+</sect2>
+</sect1>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="seealso"><title>See Also</title>
+<!-- Include seealso.sgml: -->
+ &seealso;
+<!-- end seealso -->
+</sect1>
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="appendix"><title>Appendix</title>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<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.
+</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 ;-)
+</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.
+</para>
+
+<para>
+ To make a simple analogy, we do something similar when we use wild-card
+ characters when listing files with the <command>dir</command> command in DOS.
+ <literal>*.*</literal> matches all filenames. The <quote>special</quote>
+ character here is the asterisk which matches any and all characters. We can be
+ more specific and use <literal>?</literal> to match just individual
+ characters. So <quote>dir file?.text</quote> would match
+ <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
+ matching, using a similar technique to <quote>regular expressions</quote>!
+</para>
+
+<para>
+ Regular expressions do essentially the same thing, but are much, much more
+ powerful. There are many more <quote>special characters</quote> and ways of
+ building complex patterns however. Let's look at a few of the common ones,
+ and then some examples:
+</para>
+
+<simplelist>
+ <member>
+ <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
+ <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
+ times. Either/or.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
+ times.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
+ times.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
+ the following character should be taken literally. This is used where one of the
+ special characters (e.g. <quote>.</quote>) needs to be taken literally and
+ not as a special meta-character.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
+ any of the enclosed characters are encountered.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>()</emphasis> - parentheses are used to group a sub-expression,
+ or multiple sub-expressions.
+ </member>
+</simplelist>
+
+<simplelist>
+ <member>
+ <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
+ <quote>or</quote> conditional statement. A match is successful if the
+ sub-expression on either side of <quote>|</quote> matches.
+ </member>
+</simplelist>
+
+<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.
+ </member>
+</simplelist>
+
+<para>
+ These are just some of the ones you are likely to use when matching URLs with
+ <application>Privoxy</application>, and is a long way from a definitive
+ list. This is enough to get us started with a few simple examples which may
+ be more illuminating:
+</para>
+
+<para>
+ <emphasis><literal>/.*/banners/.*</literal></emphasis> - A simple example
+ that uses the common combination of <quote>.</quote> and <quote>*</quote> to
+ denote any character, zero or more times. In other words, any string at all.
+ So we start with a literal forward slash, then our regular expression pattern
+ (<quote>.*</quote>) another literal forward slash, the string
+ <quote>banners</quote>, another forward slash, and lastly another
+ <quote>.*</quote>. We are building
+ a directory path here. This will match any file with the path that has a
+ directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
+ any characters, and this could conceivably be more forward slashes, so it
+ might expand into a much longer looking path. For example, this could match:
+ <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
+ <quote>/banners/annoying.html</quote>, or almost an infinite number of other
+ possible combinations, just so it has <quote>banners</quote> in the path
+ somewhere.
+</para>
+
+<para>
+ A now something a little more complex:
+</para>
+
+<para>
+ <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
+ We have several literal forward slashes again (<quote>/</quote>), so we are
+ building another expression that is a file path statement. We have another
+ <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
+ it matches our expression. The only true literal that <emphasis>must
+ match</emphasis> our pattern is <application>adv</application>, together with
+ the forward slashes. What comes after the <quote>adv</quote> string is the
+ interesting part.
+</para>
+
+<para>
+ Remember the <quote>?</quote> means the preceding expression (either a
+ literal character or anything grouped with <quote>(...)</quote> in this case)
+ can exist or not, since this means either zero or one match. So
+ <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
+ individual sub-expressions: <quote>(er)</quote>,
+ <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
+ means <quote>or</quote>. We have two of those. For instance,
+ <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
+ <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
+ attempt at matching as many variations of <quote>advertisement</quote>, and
+ similar, as possible. So this would expand to match just <quote>adv</quote>,
+ or <quote>advert</quote>, or <quote>adverts</quote>, or
+ <quote>advertising</quote>, or <quote>advertisement</quote>, or
+ <quote>advertisements</quote>. You get the idea. But it would not match
+ <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
+ changing our regular expression to:
+ <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
+ either spelling.
+</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
+ 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
+ expression here is what is in the square brackets -- in this case, any digit
+ one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
+ This includes a <quote>|</quote>, so this needs to match the expression on
+ either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
+ side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
+ since the <quote>?</quote> means the letter <quote>e</quote> is optional and
+ can be matched once or not at all. So we are building an expression here to
+ match image GIF or JPEG type image file. It must include the literal
+ string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
+ (which is now a literal, and not a special character, since it is escaped
+ with <quote>\</quote>), and lastly either <quote>gif</quote>, or
+ <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
+ include: <quote>//advert1.jpg</quote>,
+ <quote>/nasty/ads/advert1234.gif</quote>,
+ <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
+ <quote>advert1.gif</quote> (no leading slash), or
+ <quote>/adverts232.jpg</quote> (the expression does not include an
+ <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
+ 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>
+ configuration files, and maybe use this knowledge to customize your own
+ installation. There is much, much more that can be done with regular
+ expressions. Now that you know enough to get started, you can learn more on
+ your own :/
+</para>
+
+<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>
+</para>
+
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2>
+<title><application>Privoxy</application>'s Internal Pages</title>
+
+<para>
+ Since <application>Privoxy</application> proxies each requested
+ web page, it is easy for <application>Privoxy</application> to
+ trap certain special URLs. In this way, we can talk directly to
+ <application>Privoxy</application>, and see how it is
+ configured, see how our rules are being applied, change these
+ rules and other configuration options, and even turn
+ <application>Privoxy's</application> filtering off, all with
+ a web browser.
+
+</para>
+
+<para>
+ The URLs listed below are the special ones that allow direct access
+ to <application>Privoxy</application>. Of course,
+ <application>Privoxy</application> must be running to access these. If
+ not, you will get a friendly error message. Internet access is not
+ necessary either.
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Privoxy main page:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
+ </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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Show information about the current configuration:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
+ </para>
+ </blockquote>
+ </listitem>
+
+ <listitem>
+ <para>
+ Show the source code version numbers:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
+ </para>
+ </blockquote>
+ </listitem>
+
+ <listitem>
+ <para>
+ Show the client's request headers:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
+ </para>
+ </blockquote>
+ </listitem>
+
+ <listitem>
+ <para>
+ Show which actions apply to a URL and why:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
+ </para>
+ </blockquote>
+ </listitem>
+
+ <listitem>
+ <para>
+ Toggle Privoxy on or off. In this case, <quote>Privoxy</quote> continues
+ to run, but only as a pass-through proxy, with no actions taking place:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
+ </para>
+ </blockquote>
+ <para>
+ Short cuts. Turn off, then on:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
+ </para>
+ </blockquote>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
+ </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.
+
+</para>
+
+<sect3 id="bookmarklets">
+<title>Bookmarklets</title>
+<para>
+ Here are some bookmarklets to allow you to easily access a
+ <quote>mini</quote> version of this page. They are designed for MS Internet
+ Explorer, but should work equally well in Netscape, Mozilla, and other
+ browsers which support JavaScript. They are designed to run directly from
+ your bookmarks - not by clicking the links below (although that will work for
+ testing).
+</para>
+<para>
+ To save them, right-click the link and choose <quote>Add to Favorites</quote>
+ (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
+ the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
+ Bookmarklet directly from your favourites/bookmarks. For even faster access,
+ you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
+ Toolbar</quote> (Netscape), and run them with a single click.
+</para>
+
+<para>
+ <itemizedlist>
+
+ <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>
+ </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>
+ </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)
+ </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>
+ </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
+ have more information about bookmarklets.
+</para>
+
+
+</sect3>
+
+</sect2>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="actionsanat">
+<title>Anatomy of an Action</title>
+
+<para>
+ The way <application>Privoxy</application> applies <quote>actions</quote>
+ and <quote>filters</quote> to any given URL can be complex, and not always so
+ easy to understand what is happening. And sometimes we need to be able to
+ <emphasis>see</emphasis> just what <application>Privoxy</application> is
+ doing. Especially, if something <application>Privoxy</application> is doing
+ is causing us a problem inadvertantly. It can be a little daunting to look at
+ 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
+ <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>
+ First, enter one URL (or partial URL) at the prompt, and then
+ <application>Privoxy</application> will tell us
+ how the current configuration will handle it. This will not
+ help with filtering effects from the <filename>default.filter</filename> file! It
+ also will not tell you about any other URLs that may be embedded within the
+ URL you are testing. For instance, images such as ads are expressed as URLs
+ within the raw page source of HTML pages. So you will only get info for the
+ actual URL that is pasted into the prompt area -- not any sub-URLs. If you
+ want to know about embedded URLs like ads, you will have to dig those out of
+ the HTML source. Use your browser's <quote>View Page Source</quote> option
+ for this.
+</para>
+
+<para>
+ Let's look at an example, <ulink url="http://google.com">google.com</ulink>,
+ one section at a time:
+</para>
+
+<para>
+ <screen>
+ System default actions:
+
+ { -add-header -block -deanimate-gifs -downgrade -fast-redirects -filter
+ -hide-forwarded -hide-from -hide-referer -hide-user-agent -image
+ -image-blocker -limit-connect -no-compression -no-cookies-keep
+ -no-cookies-read -no-cookies-set -no-popups -vanilla-wafer -wafer }
+
+ </screen>
+</para>
+
+<para>
+ This is the top section, and only tells us of the compiled in defaults. This
+ is basically what <application>Privoxy</application> would do if there
+ were not any <quote>actions</quote> defined, i.e. it does nothing. Every action
+ is disabled. This is not particularly informative for our purposes here. OK,
+ next section:
+</para>
+
+<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>
+</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>.
+
+</para>
+
+<para>
+ These are the default actions we have enabled. But we can define additional
+ actions that would be exceptions to these general rules, and then list
+ specific URLs that these exceptions would apply to. Last match wins.
+ Just below this then are two explict matches for <quote>.google.com</quote>.
+ The first is negating our various cookie blocking actions (i.e. we will allow
+ cookies here). The second is allowing <quote>fast-redirects</quote>. Note
+ that there is a leading dot here -- <quote>.google.com</quote>. This will
+ match any hosts and sub-domains, in the google.com domain also, such as
+ <quote>www.google.com</quote>. So, apparently, we have these actions defined
+ somewhere in the lower part of our actions file, and
+ <quote>google.com</quote> is referenced in these sections.
+
+</para>
+
+<para>
+ And now we pull it altogether in the bottom section and summarize how
+ <application>Privoxy</application> is appying all its <quote>actions</quote>
+ to <quote>google.com</quote>:
+
+</para>
+
+<para>
+ <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>
+</para>
+
+<para>
+ Now another example, <quote>ad.doubleclick.net</quote>:
+</para>
+
+<para>
+ <screen>
+
+ { +block +image }
+ .ad.doubleclick.net
+
+ { +block +image }
+ ad*.
+
+ { +block +image }
+ .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>,
+ 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
+ than one action.)
+</para>
+
+<para>
+ Any one of these would have done the trick and blocked this as an unwanted
+ image. This is unnecessarily redundant since the last case effectively
+ 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.
+</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...
+</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 }
+ /
+
+ { +block +image }
+ /ads
+
+ </screen>
+</para>
+
+<para>
+ Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote>! But
+ we did not want this at all! Now we see why we get the blank page. We could
+ now add a new action below this that explictly does <emphasis>not</emphasis>
+ block (-block) pages with <quote>adsl</quote>. There are various ways to
+ handle such exceptions. Example:
+</para>
+
+<para>
+ <screen>
+
+ { -block }
+ /adsl
+
+ </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>.
+
+</para>
+
+<para>
+ But now what about a situation where we get no explicit matches like
+ we did with:
+
+</para>
+
+<para>
+ <screen>
+
+ { -block }
+ /adsl
+
+ </screen>
+</para>
+
+<para>
+ That actually was very telling 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>:
+</para>
+
+<para>
+ <screen>
+
+ {shop}
+ .quietpc.com
+ .worldpay.com # for quietpc.com
+ .jungle.com
+ .scan.co.uk
+ .forbes.com
+
+ </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:
+
+</para>
+
+<para>
+ <screen>
+
+ {-filter}
+ .forbes.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.
+</para>
+
+</sect2>
+
+</sect1>
+
+ <!--
+
+ This program is free software; you can redistribute it
+ and/or modify it under the terms of the GNU General
+ Public License as published by the Free Software
+ Foundation; either version 2 of the License, or (at
+ your option) any later version.
+
+ This program is distributed in the hope that it will
+ be useful, but WITHOUT ANY WARRANTY; without even the
+ implied warranty of MERCHANTABILITY or FITNESS FOR A
+ PARTICULAR PURPOSE. See the GNU General Public
+ License for more details.
+
+ 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.
+
+ $Log: user-manual.sgml,v $
+ Revision 1.66 2002/04/04 06:48:37 hal9
+ Structural changes to allow for conditional inclusion/exclusion of content
+ based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
+ definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
+ eventually be set by Makefile.
+ More boilerplate text for use across multiple docs.
+
+ Revision 1.65 2002/04/03 19:52:07 swa
+ enhance squid section due to user suggestion
+
+ Revision 1.64 2002/04/03 03:53:43 hal9
+ A few minor bug fixes, and touch ups. Ready for review.
+
+ Revision 1.63 2002/04/01 16:24:49 hal9
+ Define entities to include boilerplate text. See doc/source/*.
+
+ Revision 1.62 2002/03/30 04:15:53 hal9
+ - Fix privoxy.org/config links.
+ - Paste in Bookmarklets from Toggle page.
+ - Move Quickstart nearer top, and minor rework.
+
+ Revision 1.61 2002/03/29 01:31:08 hal9
+ Minor update.
+
+ Revision 1.60 2002/03/27 01:57:34 hal9
+ Added more to Anatomy section.
+
+ Revision 1.59 2002/03/27 00:54:33 hal9
+ Touch up intro for new name.
+
+ Revision 1.58 2002/03/26 22:29:55 swa
+ we have a new homepage!
+
+ Revision 1.57 2002/03/24 20:33:30 hal9
+ A few minor catch ups with name change.
+
+ Revision 1.56 2002/03/24 16:17:06 swa
+ configure needs to be generated.
+
+ Revision 1.55 2002/03/24 16:08:08 swa
+ we are too lazy to make a block-built
+ privoxy logo. hence removed the option.
+
+ Revision 1.54 2002/03/24 15:46:20 swa
+ name change related issue.
+
+ Revision 1.53 2002/03/24 11:51:00 swa
+ name change. changed filenames.
+
+ Revision 1.52 2002/03/24 11:01:06 swa
+ name change
+
+ Revision 1.51 2002/03/23 15:13:11 swa
+ renamed every reference to the old name with foobar.
+ fixed "application foobar application" tag, fixed
+ "the foobar" with "foobar". left junkbustser in cvs
+ comments and remarks to history untouched.
+
+ Revision 1.50 2002/03/23 05:06:21 hal9
+ Touch up.
+
+ Revision 1.49 2002/03/21 17:01:05 hal9
+ New section in Appendix.
+
+ Revision 1.48 2002/03/12 06:33:01 hal9
+ Catching up to Andreas and re_filterfile changes.
+
+ Revision 1.47 2002/03/11 13:13:27 swa
+ correct feedback channels
+
+ Revision 1.46 2002/03/10 00:51:08 hal9
+ Added section on JB internal pages in Appendix.
+
+ Revision 1.45 2002/03/09 17:43:53 swa
+ more distros
+
+ Revision 1.44 2002/03/09 17:08:48 hal9
+ New section on Jon's actions file editor, and move some stuff around.
+
+ Revision 1.43 2002/03/08 00:47:32 hal9
+ Added imageblock{pattern}.
+
+ Revision 1.42 2002/03/07 18:16:55 swa
+ looks better
+
+ Revision 1.41 2002/03/07 16:46:43 hal9
+ Fix a few markup problems for jade.
+
+ Revision 1.40 2002/03/07 16:28:39 swa
+ provide correct feedback channels
+
+ Revision 1.39 2002/03/06 16:19:28 hal9
+ Note on perceived filtering slowdown per FR.
+
+ Revision 1.38 2002/03/05 23:55:14 hal9
+ Stupid I did it again. Double hyphen in comment breaks jade.
+
+ Revision 1.37 2002/03/05 23:53:49 hal9
+ jade barfs on '- -' embedded in comments. - -user option broke it.
+
+ Revision 1.36 2002/03/05 22:53:28 hal9
+ Add new - - user option.
+
+ Revision 1.35 2002/03/05 00:17:27 hal9
+ Added section on command line options.
+
+ Revision 1.34 2002/03/04 19:32:07 oes
+ Changed default port to 8118
+
+ Revision 1.33 2002/03/03 19:46:13 hal9
+ Emphasis on where/how to report bugs, etc
+
+ Revision 1.32 2002/03/03 09:26:06 joergs
+ AmigaOS changes, config is now loaded from PROGDIR: instead of
+ AmiTCP:db/junkbuster/ if no configuration file is specified on the
+ command line.
+
+ Revision 1.31 2002/03/02 22:45:52 david__schmidt
+ Just tweaking
+
+ Revision 1.30 2002/03/02 22:00:14 hal9
+ Updated 'New Features' list. Ran through spell-checker.
+
+ Revision 1.29 2002/03/02 20:34:07 david__schmidt
+ Update OS/2 build section
+
+ Revision 1.28 2002/02/24 14:34:24 jongfoster
+ Formatting changes. Now changing the doctype to DocBook XML 4.1
+ will work - no other changes are needed.
+
+ Revision 1.27 2002/01/11 14:14:32 hal9
+ Added a very short section on Templates
+
+ Revision 1.26 2002/01/09 20:02:50 hal9
+ Fix bug re: auto-detect config file changes.
+
+ Revision 1.25 2002/01/09 18:20:30 hal9
+ Touch ups for *.action files.
+
+ Revision 1.24 2001/12/02 01:13:42 hal9
+ Fix typo.
+
+ Revision 1.23 2001/12/02 00:20:41 hal9
+ Updates for recent changes.
+
+ Revision 1.22 2001/11/05 23:57:51 hal9
+ Minor update for startup now daemon mode.
+
+ Revision 1.21 2001/10/31 21:11:03 hal9
+ Correct 2 minor errors
+
+ Revision 1.18 2001/10/24 18:45:26 hal9
+ *** empty log message ***
+
+ Revision 1.17 2001/10/24 17:10:55 hal9
+ Catching up with Jon's recent work, and a few other things.
+
+ Revision 1.16 2001/10/21 17:19:21 swa
+ wrong url in documentation
+
+ Revision 1.15 2001/10/14 23:46:24 hal9
+ Various minor changes. Fleshed out SEE ALSO section.
+
+ Revision 1.13 2001/10/10 17:28:33 hal9
+ Very minor changes.
+
+ Revision 1.12 2001/09/28 02:57:04 hal9
+ Ditto :/
+
+ Revision 1.11 2001/09/28 02:25:20 hal9
+ Ditto.
+
+ Revision 1.9 2001/09/27 23:50:29 hal9
+ A few changes. A short section on regular expression in appendix.
+
+ Revision 1.8 2001/09/25 00:34:59 hal9
+ Some additions, and re-arranging.
+
+ Revision 1.7 2001/09/24 14:31:36 hal9
+ Diddling.
+
+ Revision 1.6 2001/09/24 14:10:32 hal9
+ Including David's OS/2 installation instructions.
+
+ Revision 1.2 2001/09/13 15:27:40 swa
+ cosmetics
- $Log: user-manual.sgml,v $
Revision 1.1 2001/09/12 15:36:41 swa
source files for junkbuster documentation
projects / privoxy.git / blobdiff