<!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
<!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
<!entity % p-readme "IGNORE">
+<!entity % p-config "IGNORE">
<!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml -->
]>
<!--
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 1.77 2002/04/17 13:51:23 oes Exp $
+ $Id: user-manual.sgml,v 1.90 2002/04/23 21:41:25 hal9 Exp $
Written by and Copyright (C) 2001 the SourceForge
Privoxy team. http://www.privoxy.org/
<artheader>
<title>Privoxy User Manual</title>
-<pubdate>$Id: user-manual.sgml,v 1.77 2002/04/17 13:51:23 oes Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.90 2002/04/23 21:41:25 hal9 Exp $</pubdate>
<authorgroup>
<author>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 label="1" id="introduction"><title>Introduction</title>
-
<para>
This documentation is included with the current &p-status; version of
<application>Privoxy</application>, v.&p-version;<![%p-not-stable;[,
stable v3.0 is <quote>soon</quote> ;-)]]>.
</para>
-<![%p-not-stable;[
<!-- include only in non-stable versions -->
+<![%p-not-stable;[
<para>
Since this is a &p-status; version, not all new features are well tested. This
documentation may be slightly out of sync as a result (especially with
<title>New Features</title>
<para>
In addition to <application>Internet Junkbuster's</application> traditional
- feature of ad and banner blocking and cookie management,
+ features of ad and banner blocking and cookie management,
<application>Privoxy</application> provides new features<![%p-not-stable;[,
some of them currently under development]]>:
-<anchor id="testing"/>
</para>
<!-- Include newfeatures.sgml boilerplate here: -->
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="installation"><title>Installation</title>
+
<para>
<application>Privoxy</application> is available both in convenient pre-compiled
packages for a wide range of operating systems, and as raw source code.
For most users, we recommend using the packages, which can be downloaded from our
<ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink>.
</para>
+
<para>
If you like to live on the bleeding edge and are not afraid of using
possibly unstable development versions, you can check out the up-to-the-minute
</para>
<!-- Include supported.sgml boilerplate -->
-&supported;
+ &supported;
<!-- end boilerplate -->
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="installation-packages"><title>Binary Packages</title>
+
+<para>
+ Note: If you have a previous <application>Junkbuster</application> or
+ <application>Privoxy</application> installation on your system, you
+ will need to remove it. Some platforms do this for you as part
+ of their installation procedure. (See below for your platform).
+</para>
+
<para>
- The packages can be downloaded from our <ulink
- url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink>.
+ In any case <emphasis>be sure to backup your old configuration
+ if it is valuable to you.</emphasis> See the
+ <link linkend="upgradersnote">note to upgraders</link>.
</para>
<para>
- How to install them depends on your operating system:
+ How to install the binary packages depends on your operating system:
</para>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-pack-rpm"><title>Redhat and SuSE RPMs</title>
+<sect3 id="installation-pack-rpm"><title>Red Hat and SuSE RPMs</title>
+
+<para>
+ RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
+ and will use <filename>/etc/privoxy</filename> for the location
+ of configuration files.
+</para>
<para>
- RPMs can be installed with <literal>rpm -i <name-of-rpm.rpm></literal>,
- and will use <filename>/etc/privoxy</filename> for configuration files.
+ Note that on Red Hat, <application>Privoxy</application> will not be
+ automatically started on system boot. You will need to enable that using
+ <command>chkconfig</command>, <command>ntsysv</command>, or similar method.
</para>
<para>
- Note that if you have a Junkbuster RPM installed on your system, you
- need to remove it first, because the packages conflict.
+ If you have problems with failed dependencies, try rebuilding the SRC RPM:
+ <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm;</literal>. This
+ will use your locally installed libraries and RPM version.
+</para>
+
+<para>
+ Also note that if you have a <application>Junkbuster</application> RPM installed
+ on your system, you need to remove it first, because the packages conflict.
+ Otherwise, RPM will try to remove <application>Junkbuster</application>
+ automatically, before installing <application>Privoxy</application>.
</para>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, HP-UX</title>
-
+<sect3 id="installation-deb"><title>Debian</title>
<para>
- Create a new directory, <literal>cd</literal> to it, then unzip and
- untar the archive. For the most part, you'll have to figure out where
- things go. FIXME.
+ FIXME.
</para>
</sect3>
</para>
</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, FreeBSD, HP-UX</title>
+
+<para>
+ Create a new directory, <literal>cd</literal> to it, then unzip and
+ untar the archive. For the most part, you'll have to figure out where
+ things go. FIXME.
+</para>
+</sect3>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3 id="installation-os2"><title>OS/2</title>
<para>
- Just double-click the WarpIN self-installing archive, which will guide
- you through the installation process. A shadow of the
+ First, make sure that no previous installations of
+ <application>Junkbuster</application> and / or
+ <application>Privoxy</application> are left on your
+ system. You can do this by
+</para>
+
+<para>
+ Then, just double-click the WarpIN self-installing archive, which will
+ guide you through the installation process. A shadow of the
<application>Privoxy</application> executable will be placed in your
startup folder so it will start automatically whenever OS/2 starts.
</para>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-deb"><title>Debian</title>
-<para>
- FIXME.
+<sect3 id="installation-mac"><title>Max OSX</title>
+<para>
+ Unzip the downloaded package (you can either double-click on the file
+ in the finder, or on the desktop if you downloaded it there). Then,
+ double-click on the package installer icon and follow the installation
+ process.
+ <application>Privoxy</application> will be installed in the subdirectory
+ <literal>/Applications/Privoxy.app</literal>.
+ <application>Privoxy</application> will set itself up to start
+ automatically on system bringup via
+ <literal>/System/Library/StartupItems/Privoxy</literal>.
</para>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 id="installation-amiga"><title>AmigaOS</title>
<para>
- Unpack the <literal>.lha</literal> archive, then FIXME.
+ Copy and then unpack the <filename>lha</filename> archive to a suitable location.
+ All necessary files will be installed into <application>Privoxy</application>
+ directory, including all configuration and log files. To uninstall, just
+ remove this directory.
+</para>
+<para>
+ Start <application>Privoxy</application> (with RUN <>NIL:) in your
+ <filename>startnet</filename> script (AmiTCP), in
+ <filename>s:user-startup</filename> (RoadShow), as startup program in your
+ startup script (Genesis), or as startup action (Miami and MiamiDx).
+ <application>Privoxy</application> will automatically quit when you quit your
+ TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
+ <application>Privoxy</application> is still running).
</para>
</sect3>
</sect2>
<!-- include buildsource.sgml boilerplate: -->
&buildsource;
<!-- end boilerplate -->
-
-<para>
- For more detailed instructions, on how to build Redhat and SuSE RPMs,
- Windows self-extracting installers etc, please consult the <ulink
- url="../developer-manual/newrelease.html">developer manual</ulink>.
-</para>
</sect2>
</sect1>
</para>
<para>
A <quote>filter file</quote> (typically <filename>default.filter</filename>)
- is new
with <application>Privoxy 2.9.x</application>, and provides some
- of the new sophisticaton (explained below). <filename>config</filename> is
+ is new
as of <application>Privoxy 2.9.x</application>, and provides some
+ of the new sophistication (explained below). <filename>config</filename> is
much the same as before.
</para>
<para>
files, and possibly adapt any personal rules from your older files.
When porting personal rules over from the old <filename>blockfile</filename>
to the new actions file, please note that even the pattern syntax has
- changed.
- If upgrading from 2.9.x development versions, it is still recommended
- to use the new configuration files.
+ changed. If upgrading from 2.9.x development versions, it is still
+ recommended to use the new configuration files.
</para>
<para>
A quick list of things to be aware of before upgrading:
The primary configuration file for cookie management, ad and banner
blocking, and many other aspects of <application>Privoxy</application>
configuration is <filename>default.action</filename>. It is strongly
- recommended to make oneself familiar with the new actions concept below
- before modifying that file.
+ recommended to become familiar with the new actions concept below,
+ before modifying this file.
</para>
</listitem>
<listitem>
Before launching <application>Privoxy</application> for the first time, you
will want to configure your browser(s) to use <application>Privoxy</application>
as a HTTP and HTTPS proxy. The default is localhost for the proxy address,
- and port 8118 (earlier versions used port 8000). This is the one required
- configuration that must be done!
+ and port 8118 (earlier versions used port 8000). This is the one
+ configuration step that must be done!
</para>
<para>
<para>
After doing this, flush your browser's disk and memory caches to force a
- re-reading of all pages and get rid of any ads that may be cached. You
+ re-reading of all pages and to get rid of any ads that may be cached. You
are now ready to start enjoying the benefits of using
- <application>Privoxy</application>.
+ <application>Privoxy</application>!
</para>
</para>
<para>
- An init script is provided for SuSE and Redhat.
+ See <link linkend="cmdoptions">below</link> for other command line options.
+</para>
+
+<para>
+ An init script is provided for SuSE and Red Hat.
</para>
<para>
</para>
<para>
- For RedHat: <command>/etc/rc.d/init.d/privoxy start</command>
+ For Red Hat and Debian: <command>/etc/rc.d/init.d/privoxy start</command>
</para>
</para>
<para>
- Another feature where you will propably want to define exceptions for trusted
+ Another feature where you will probably want to define exceptions for trusted
sites is the popup-killing (through the <literal>+popup</literal> and
- <literal>+filter{popups}</literal> actions), because your favourite shopping,
+ <literal>+filter{popups}</literal> actions), because your favorite shopping,
banking, or leisure site may need popups.
</para>
try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit ->
Preferences -> Debug -> Networking</literal>.
Alternatively, set the <quote>+downgrade</quote> config option in
- <filename>default.action</filename> which will downgrade you brower's HTTP
+ <filename>default.action</filename> which will downgrade your browser's HTTP
requests from HTTP/1.1 to HTTP/1.0 before processing them.
</para>
If you encounter problems, try loading the page without
<application>Privoxy</application>. If that helps, enter the URL where
you have the problems into <ulink url="http://p.p/show-url-info">the browser
- based rule tracing utility</ulink>. Watch out which rules apply and why, and
+ based rule tracing utility</ulink>. See which rules apply and why, and
then try turning them off for that site one after the other, until the problem
is gone. When you have found the culprit, you might want to turn the rest on
again.
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
+<sect2 id="cmdoptions">
<title>Command Line Options</title>
<para>
<application>Privoxy</application> may be invoked with the following
<emphasis>--version</emphasis>
</para>
<para>
- Print version info and exit, Unix only.
+ Print version info and exit. Unix only.
</para>
</listitem>
<listitem>
<emphasis>--help</emphasis>
</para>
<para>
- Print a short usage info and exit, Unix only.
+ Print short usage info and exit. Unix only.
</para>
</listitem>
<listitem>
</para>
<para>
Don't become a daemon, i.e. don't fork and become process group
- leader, don't detach from controlling tty. Unix only.
+ leader, and don't detach from controlling tty. Unix only.
</para>
</listitem>
<listitem>
</para>
<para>
On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
- <emphasis>FILE</emphasis> on exit. Failiure to create or delete the
+ <emphasis>FILE</emphasis> on exit. Failure to create or delete the
<emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
option is given, no PID file will be used. Unix only.
</para>
<application>Privoxy</application> will look for a file named
<quote>config</quote> in the current directory (except on Win32
where it will look for <quote>config.txt</quote> instead). Specify
- full path to avoid confusion.
+ full path to avoid confusion. If no config file is found,
+ <application>Privoxy</application> will fail to start.
</para>
</listitem>
<application>Privoxy</application>'s user interface can be reached through the special
URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
(shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
- which is a built-in page and works without internet access.
+ which is a built-in page and works without Internet access.
You will see the following section:
</para>
it as a test to see whether it is <application>Privoxy</application>
causing the problem or not. <application>Privoxy</application> continues
to run as a proxy in this case, but all filtering is disabled. There
- is even a toggle Bookmarklet offered, so that you can toggle
- <application>Privoxy</application> with one click from your browser.
-
+ is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
+ that you can toggle <application>Privoxy</application> with one click from
+ your browser.
</para>
</sect2>
<para>
<filename>default.action</filename> (the actions file) is used to define
which of a set of various <quote>actions</quote> relating to images, banners,
- pop-ups, access restrictions, banners and cookies are to be applied where.
+ pop-ups, access restrictions, banners and cookies are to be applied, and where.
There is a web based editor for this file that can be accessed at <ulink
url="http://config.privoxy.org/edit-actions/">http://config.privoxy.org/edit-actions/</ulink>
(Shortcut: <ulink url="http://p.p/edit-actions/">http://p.p/edit-actions/</ulink>).
<para>
<filename>default.action</filename> and <filename>default.filter</filename>
- can use Perl style regular expressions for maximum flexibility.
+ can use Perl style <link linkend="regex">regular expressions</link> for
+ maximum flexibility.
</para>
<para>
<para>
The main config file controls all aspects of <application>Privoxy</application>'s
- operation that are not location dependent (i.e. that apply invariantly no matter
- where in the web you are surfing).
+ operation that are not location dependent (i.e. they apply universally, no matter
+ where you may be surfing).
</para>
<para>
<application>Privoxy</application> can (and normally does) use a number of
- other files for addidtional configuration and logging.
+ other files for additional configuration and logging.
This section of the configuration file tells <application>Privoxy</application>
where to find those other files.
</para>
<para>
When development goes modular and multi-user, the blocker, filter, and
per-user config will be stored in subdirectories of <quote>confdir</quote>.
- For now, the configuration dir structure is flat, except for
+ For now, the configuration directory structure is flat, except for
<filename>confdir/templates</filename>, where the HTML templates for CGI
- output reside.
+ output reside (e.g. <application>Privoxy's</application> 404 error page).
</para>
</listitem>
</varlistentry>
<sect4><title>actionsfile</title>
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- The actions file to use
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>File name, relative to <literal>confdir</literal></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>default.action (Unix) <emphasis>or</emphasis> default.action.txt (Windows)</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- No action is taken at all. Simple neutral proxying.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- There is no point in using <application>Privoxy</application> without
- an actions file.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4><title>actionsfile</title>
-
<variablelist>
<varlistentry>
<term>Specifies:</term>
<listitem>
<para>
There is no point in using <application>Privoxy</application> without
- an actions file. There are three diffrent actions files included in the
+ an actions file. There are three different actions files included in the
distribution, with varying degrees of aggressiveness:
<filename>default.action</filename>, <filename>intermediate.action</filename> and
<filename>advanced.action</filename>.
<term>Notes:</term>
<listitem>
<para>
- The windows version will additionally log to the console
+ The windows version will additionally log to the console.
</para>
<para>
The logfile is where all logging and error messages are written. The level
<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>
+ (see <quote>man cron</quote>). For Red Hat, a <command>logrotate</command>
script has been included.
</para>
<para>
<term>Effect if unset:</term>
<listitem>
<para>
- The whole trust mechansim is turned off.
+ The whole trust mechanism is turned off.
</para>
</listitem>
</varlistentry>
<term>Notes:</term>
<listitem>
<para>
- The trust mechansim is an experimental feature for building whitelists and should
+ The trust mechanism is an experimental feature for building white-lists and should
be used with care. It is <emphasis>NOT</emphasis> recommended for the casual user.
</para>
<para>
the effect that access to untrusted sites will be granted, if a link from a
trusted referrer was used.
The link target will then be added to the <quote>trustfile</quote>.
- Possible applications include limiting internet access for children.
+ Possible applications include limiting Internet access for children.
</para>
<para>
If you use <literal>+</literal> operator in the trust file, it may grow considerably over time.
<!-- ~~~~~ New section ~~~~~ -->
<sect3>
-<title>Local Setup Documentation</title>
+<title>Local Set-up Documentation</title>
<para>
If you intend to operate <application>Privoxy</application> for more users
activated. (See <literal>trustfile</literal> above.)
</para>
<para>
- If you use the trust mechanism, it is a good idea to write up some online
+ If you use the trust mechanism, it is a good idea to write up some on-line
documentation about your trust policy and to specify the URL(s) here.
Use multiple times for multiple URLs.
</para>
<term>Specifies:</term>
<listitem>
<para>
- Keys that determine what information gets logged.
+ Key values that determine what information gets logged.
</para>
</listitem>
</varlistentry>
as it happens. <emphasis>1, 4096 and 8192 are highly recommended</emphasis>
so that you will notice when things go wrong. The other levels are probably
only of interest if you are hunting down a specific problem. They can produce
- a hell of output (especially 16).
+ a hell of an output (especially 16).
+ <!-- LOL -->
</para>
<para>
The reporting of <emphasis>fatal</emphasis> errors (i.e. ones which crash
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>[<replaceable class="parameter">IP-Adddress</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
+ <para>[<replaceable class="parameter">IP-Address</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
</listitem>
</varlistentry>
<varlistentry>
If you leave out the IP address, <application>Privoxy</application> will
bind to all interfaces (addresses) on your machine and may become reachable
from the Internet. In that case, consider using access control lists (acl's)
- (see <quote>Acls</quote> below), or a firewall.
+ (see <quote>ACLs</quote> below), or a firewall.
</para>
</listitem>
</varlistentry>
</para>
<para>
For the time being, access to the toggle feature can <emphasis>not</emphasis> be
- controlled separately by <quote>Acls</quote> or HTTP authentication,
+ controlled separately by <quote>ACLs</quote> or HTTP authentication,
so that everybody who can access <application>Privoxy</application> (see
- <quote>Acls</quote> and <literal>listen-address</literal> above) can
+ <quote>ACLs</quote> and <literal>listen-address</literal> above) can
toggle it for all users. So this option is <emphasis>not recommended</emphasis>
for multi-user environments with untrusted users.
</para>
<listitem>
<para>
For the time being, access to the editor can <emphasis>not</emphasis> be
- controlled separately by <quote>Acls</quote> or HTTP authentication,
+ controlled separately by <quote>ACLs</quote> or HTTP authentication,
so that everybody who can access <application>Privoxy</application> (see
- <quote>Acls</quote> and <literal>listen-address</literal> above) can
+ <quote>ACLs</quote> and <literal>listen-address</literal> above) can
modify its configuration for all users. So this option is <emphasis>not
recommended</emphasis> for multi-user environments with untrusted users.
</para>
</variablelist>
</sect4>
-<sect4><title>Acls: permit-access and deny-access</title>
+<sect4><title>ACLs: permit-access and deny-access</title>
<variablelist>
<varlistentry>
<term>Specifies:</term>
weaknesses.
</para>
<para>
- Multiple acl lines are OK.
- If any
acls are specified, then the <application>Privoxy</application>
+ Multiple ACL lines are OK.
+ If any
ACLs are specified, then the <application>Privoxy</application>
talks only to IP addresses that match at least one <literal>permit-access</literal> line
and don't match any subsequent <literal>deny-access</literal> line. In other words, the
last match wins, with the default being <literal>deny-access</literal>.
IP addresses, only the first one is used.
</para>
<para>
- Denying access to particular sites by acl may have undesired side effects
+ Denying access to particular sites by ACL may have undesired side effects
if the site in question is hosted on a machine which also hosts other sites.
</para>
</listitem>
<term>Examples:</term>
<listitem>
<para>
- Explicitly define the defauklt behaviour if no acl and
+ Explicitly define the default behavior if no ACL and
<literal>listen-address</literal> are set: <quote>localhost</quote>
is OK. The absence of a <replaceable class="parameter">dst_addr</replaceable> implies that
<emphasis>all</emphasis> destination addresses are OK:
through an anonymous public proxy (see e.g. <ulink
url="http://www.multiproxy.org/anon_list.htm">http://www.multiproxy.org/anon_list.htm</ulink>)
Or to use a caching proxy to speed up browsing. Or chaining to a parent
- proxy may be necessary because the mac
kine that <application>Privoxy</application>
- runs on has no direct internet access.
+ proxy may be necessary because the mac
hine that <application>Privoxy</application>
+ runs on has no direct Internet access.
</para>
<para>
<term>Examples:</term>
<listitem>
<para>
- From the company example.com, direct connections are made to all <quote>internal</quote>
- domains, but everything outbound goes through their ISP's proxy by way example.com's
- corporate SOCKS 4A gateway to the Internet.
+ From the company example.com, direct connections are made to all
+ <quote>internal</quote> domains, but everything outbound goes through
+ their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
+ the Internet.
</para>
<para>
<screen>
</para>
<para>
- Now, you users can set their browser's proxy to use either
+ Now, your users can set their browser's proxy to use either
host-a or host-b and be able to browse the internal content
- on both isp-a or isp-b.
+ of both isp-a and isp-b.
</para>
<para>
<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:
See below for a complete list of available actions.
</para>
+<para>
+ An actions file typically has sections. At the top, <quote>aliases</quote> are
+ defined (discussed below), then the default set of rules which will apply
+ universally to all sites and pages. And then below that is generally a lengthy
+ set of exceptions to the defined universal policies.
+</para>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3>
<title>Finding the Right Mix</title>
<para>
Note that some actions like cookie suppression or script disabling may
render some sites unusable, which rely on these techniques to work properly.
- Finding the right mix of actions is not easy and sure a matter of personal
+ Finding the right mix of actions is not easy and certainly a matter of personal
taste. In general, it can be said that the more <quote>aggressive</quote>
your default settings (in the top section of the actions file) are,
- the more exceptions for <quote>trustes</quote> sites you will have to
+ the more exceptions for <quote>trusted</quote> sites you will have to
make later. If, for example, you want to kill popup windows per default, you'll
have to make exceptions from that rule for sites that you regularly use
and that require popups for actually useful content, like maybe your bank,
- favourite shop, or newspaper.
+ favorite shop, or newspaper.
</para>
<para>
<sect3>
<title>How Actions are Applied to URLs</title>
<para>
- The actions file is separated into sections. There are special sections,
- like the alias sections which will be discussed later. For now let's
- concentrate on regular sectiions: They have a heading line (often split
+ The actions file is divided into sections. There are special sections,
+ like the <quote>alias</quote> sections which will be discussed later. For now
+ let's concentrate on regular sections: They have a heading line (often split
up to multiple lines for readability) which consist of a list of actions,
separated by whitespace and enclosed in curly braces. Below that, there
is a list of URL patterns, each on a separate line.
</para>
<para>
- More detail on this is provided in the Appendix <quote>Anatomy of an Action</quote>.
+ More detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
+ Anatomy of an Action</link>.
</para>
</sect3>
<sect3>
<title>Patterns</title>
<para>
- Generally, a pattern has the form <domain>/<path>, where both the
- <domain> and <path> part are optional. If you only specify a
- domain part, the <quote>/</quote> can be left out:
+ Generally, a pattern has the form <literal><domain>/<path></literal>,
+ where both the <literal><domain></literal> and <literal><path></literal>
+ are optional. (This is why the pattern <literal>/</literal> matches all URLs).
</para>
<variablelist>
<varlistentry>
- <term><literal>www.example.com</literal></term>
+ <term><literal>www.example.com/</literal></term>
<listitem>
<para>
- is a domain only pattern and will match any request to <literal>www.example.com</literal>,
+ is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
regardless of which document on that server is requested.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>www.example.com/</literal></term>
+ <term><literal>www.example.com</literal></term>
<listitem>
<para>
- means exactly the same.
+ means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
+ be omitted.
</para>
</listitem>
</varlistentry>
</para>
<para>
- There is an <link linkend="regex">Appendix</link> with a brief quickstart into regular
- expressions, and full (very technical) documentation on PCRE regex syntax is available online
+ There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
+ expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
- useful, which is available online at <ulink
+ useful, which is available on
-line at <ulink
url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>.
</para>
<para>
- Note that the pattern is automatically left-anchored at the <quote>/</quote>,
+ Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
i.e. it matches as if it would start with a <quote>^</quote>.
</para>
<!-- ~ End section ~ -->
-
<!-- ~~~~~ New section ~~~~~ -->
-<sect3>
+<sect3 id="actions">
<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:
+ preceded with a <quote>-</quote>. So a <quote>+action</quote> means
+ <quote>do that action</quote>, e.g. <quote>+block</quote> means please
+ <quote>block the following URLs and/or patterns</quote>. All actions are
+ disabled by default, until they are explicitly enabled somewhere in an actions
+ file.
+</para>
+
+<para>
+ Actions are invoked by enclosing the action name in curly braces (e.g.
+ {+some_action}), followed by a list of URLs (or patterns that match URLs) to
+ which the action applies. There are three classes of actions:
</para>
<para>
<listitem>
<para>
- Boolean (e.g. <quote>+/-block</quote>):
- </para>
+ Boolean, i.e the action can only be <quote>on</quote> or
+ <quote>off</quote>. Examples:
+ </para>
<para>
<literal>
<msgtext>
<listitem>
<para>
- parameterized (e.g. <quote>+/-hide-user-agent</quote>):
+ Parameterized, e.g. <quote>+/-hide-user-agent{ Mozilla 1.0 }</quote>,
+ where some value is required in order to enable this type of action.
+ Examples:
</para>
<para>
<literal>
<msgtext>
<literallayout>
<emphasis>{+name{param}}</emphasis> # enable action and set parameter to <quote>param</quote>
- <emphasis>{-name}</emphasis> # disable action
+ <emphasis>{-name}</emphasis> # disable action (<quote>parameter</quote>) can be omitted
</literallayout>
</msgtext>
</literal>
<listitem>
<para>
- Multi-value (e.g. <quote>{+/-add-header{Name: value}}</quote>, <quote>{+/-wafer{name=value}}</quote>):
+ <!-- oes, or someone, check this. Re-worded 04/20/02 HB. -->
+ Multi-value, e.g. <quote>{+/-add-header{Name: value}}</quote> ot
+ <quote>{+/-wafer{name=value}}</quote>), where some value needs to be defined
+ in addition to simply enabling the actino. Examples:
</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
+ <emphasis>{+name{param=value}}</emphasis> # enable action and set <quote>param</quote> to <quote>value</quote>
+ <emphasis>{-name{param=value}}</emphasis> # remove the parameter <quote>param</quote> completely
+ <emphasis>{-name}</emphasis> # disable this action totally and remove <application>param</application> too
</literallayout>
</msgtext>
</literal>
specified.
</para>
+<!-- start actions listing -->
<para>
The list of valid <application>Privoxy</application> <quote>actions</quote> are:
</para>
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- Add the specified HTTP header, which is not checked for validity.
- You may specify this many times to specify many different headers:
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+add-header{Name: value}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- Block this URL totally. In a default installation, a <quote>blocked</quote>
- URL will result in bright red banner that says <quote>BLOCKED</quote>,
- with a reason why it is being blocked, and an option to see it anyway.
- The page displayed for this is the <quote>blocked</quote> template
- file.
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+block</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- De-animate all animated GIF images, i.e. reduce them to their last frame.
- This will also shrink the images considerably (in bytes, not pixels!). If
- the option <quote>first</quote> is given, the first frame of the animation
- is used as the replacement. If <quote>last</quote> is given, the last frame
- of the animation is used instead, which probably makes more sense for most
- banner animations, but also has the risk of not showing the entire last
- frame (if it is only a delta to an earlier frame).
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+deanimate-gifs{last}</emphasis>
- <emphasis>+deanimate-gifs{first}</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <quote>+downgrade</quote> will downgrade HTTP/1.1 client requests to
- HTTP/1.0 and downgrade the responses as well. Use this action for servers
- that use HTTP/1.1 protocol features that
- <application>Privoxy</application> doesn't handle well yet. HTTP/1.1
- is only partially implemented. Default is not to downgrade requests.
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+downgrade</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Many sites, like yahoo.com, don't just link to other sites. Instead, they
- will link to some script on their own server, giving the destination as a
- parameter, which will then redirect you to the final target. URLs resulting
- from this scheme typically look like:
- <emphasis>http://some.place/some_script?http://some.where-else</emphasis>.
- </para>
- <para>
- Sometimes, there are even multiple consecutive redirects encoded in the
- URL. These redirections via scripts make your web browsing more traceable,
- since the server from which you follow such a link can see where you go to.
- Apart from that, valuable bandwidth and time is wasted, while your browser
- ask the server for one redirect after the other. Plus, it feeds the
- advertisers.
- </para>
- <para>
- The <quote>+fast-redirects</quote> option enables interception of these
- types of requests by <application>Privoxy</application>, who will cut off
- all but the last valid URL in the request and send a local redirect back to
- your browser without contacting the intermediate site(s).
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+fast-redirects</emphasis>
- </literallayout>
- </msgtext>
- </literal>
- </para>
- </listitem>
-
- <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>
+<!-- ********************************************************** -->
+<!-- Please note the below defined actions use id's that are -->
+<!-- probably linked from other places, so please don't change. -->
+<!-- -->
+<!-- ********************************************************** -->
- <blockquote>
- <simplelist>
- <member>
- <emphasis>html-annoyances</emphasis>: Get rid of particularly annoying HTML abuse.
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>js-annoyances</emphasis>: Get rid of particularly annoying JavaScript abuse
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>no-poups</emphasis>: Kill all popups in JS and HTML
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>frameset-borders</emphasis>: Give frames a border
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>webbugs</emphasis>: Squish WebBugs (1x1 invisible GIFs used for user tracking)
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>no-refresh</emphasis>: Automatic refresh sucks on auto-dialup lines
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>fun</emphasis>: Text replacements for subversive browsing fun!
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>nimda</emphasis>: Remove (virus) Nimda code.
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>banners-by-size</emphasis>: Kill banners by size
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>crude-parental</emphasis>: Kill all web pages that contain the words "sex" or "warez"
- </member>
- </simplelist>
- </blockquote>
- <para>
- Note: Filtering requires buffering the page content, which may appear to slow down
- page rendering since nothing is displayed until all content has passed
- the filters. (It does not really take longer, but seems that way since
- the page is not incrementally displayed.) This effect will be more noticeable
- on slower connections.
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
- </listitem>
+<sect4 id="add-header">
+<title><emphasis>+add-header{Name: value}</emphasis></title>
- <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>
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Multi-value.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ Send a user defined HTTP header to the web server.
+ </para>
+ </listitem>
+ </varlistentry>
- <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>
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ Any value is possible. Validity of the defined HTTP headers is not checked.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+add-header{X-User-Tracking: sucks}}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+<varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action may be specified multiple times, in order to define multiple
+ headers. This is rarely needed for the typical user. If you don't know what
+ <quote>HTTP headers</quote> are, you definitely don't need to worry about this
+ one.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="block">
+<title><emphasis>+block</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ Used to block a URL from reaching your browser. The URL may be
+ anything, but is typically used to block ads or other obnoxious
+ content.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>N/A</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+block}</emphasis>
+ <emphasis>.example.com</emphasis>
+ <emphasis>.ads.r.us</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+<varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ <application>Privoxy</application> will display its
+ special <quote>BLOCKED</quote> page if a URL matches one of the
+ blocked patterns. If there is sufficient space, a large red
+ banner will appear with a friendly message about why the page
+ was blocked, and a way to go there anyway. If there is insufficient
+ space a smaller blocked page will appear without the red banner.
+ One exception is if the URL matches both <quote>+block</quote>
+ and <quote>+image</quote>, then it can be handled by
+ <quote>+image-blocker</quote> (see below).
+ </para>
+ <para>
+ The <quote>+filter</quote> action can also perform some of the
+ same functionality as <quote>+block</quote>, but by virtue of very
+ different programming techniques, and is typically used for different
+ reasons.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="deanimate-gifs">
+<title><emphasis>+deanimate-gifs</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ To stop those annoying, distracting animated GIF images.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ <quote>last</quote> or <quote>first</quote>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+deanimate-gifs{last}}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <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>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="downgrade">
+<title><emphasis>+downgrade</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ <quote>+downgrade</quote> will downgrade HTTP/1.1 client requests to
+ HTTP/1.0 and downgrade the responses as well.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+downgrade}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ 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. This is
+ an infrequently needed action, and is used to help with problem sites only.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="fast-redirects">
+<title><emphasis>+fast-redirects</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ The <quote>+fast-redirects</quote> action enables interception of
+ <quote>redirect</quote> requests from one server to another, which
+ are used to track users.<application>Privoxy</application> can cut off
+ all but the last valid URL in redirect request and send a local redirect
+ back to your browser without contacting the intermediate site(s).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+fast-redirects}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Many sites, like yahoo.com, don't just link to other sites. Instead, they
+ will link to some script on their own server, giving the destination as a
+ parameter, which will then redirect you to the final target. URLs
+ resulting from this scheme typically look like:
+ <emphasis>http://some.place/some_script?http://some.where-else</emphasis>.
</para>
- </listitem>
+ <para>
+ Sometimes, there are even multiple consecutive redirects encoded in the
+ URL. These redirections via scripts make your web browsing more traceable,
+ since the server from which you follow such a link can see where you go
+ to. Apart from that, valuable bandwidth and time is wasted, while your
+ browser ask the server for one redirect after the other. Plus, it feeds
+ the advertisers.
+ </para>
+ <para>
+ This is a normally on feature, and often requires exceptions for sites that
+ are sensitive to defeating this mechanism.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="filter">
+<title><emphasis>+filter</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ Apply page filtering as defined by named sections of the
+ <filename>default.filter</filename> file to the specified site(s).
+ <quote>Filtering</quote> can be any modification of the raw
+ page content, including re-writing or deletion of content.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ <quote>+filter</quote> must include the name of one of the section identifiers
+ from <filename>default.filter</filename> (or whatever
+ <emphasis>filterfile</emphasis> is specified in <filename>config</filename>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (from the current <filename>default.filter</filename>):</term>
+ <listitem>
+ <simplelist>
+ <member>
+ <emphasis>+filter{html-annoyances}</emphasis>: Get rid of particularly annoying HTML abuse.
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>+filter{js-annoyances}</emphasis>: Get rid of particularly annoying JavaScript abuse
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>+filter{content-cookies}</emphasis>: Kill cookies that come in the HTML or JS content
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>+filter{popups}</emphasis>: Kill all popups in JS and HTML
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>+filter{frameset-borders}</emphasis>: Give frames a border and make them resizable
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>+filter{webbugs}</emphasis>: Squish WebBugs (1x1 invisible GIFs used for user tracking)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>+filter{refresh-tags}</emphasis>: Kill automatic refresh tags (for dial-on-demand setups)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>+filter{fun}</emphasis>: Text replacements for subversive browsing fun!
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>+filter{nimda}</emphasis>: Remove Nimda (virus) code.
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>+filter{banners-by-size}</emphasis>: Kill banners by size (<emphasis>very</emphasis> efficient!)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>+filter{shockwave-flash}</emphasis>: Kill embedded Shockwave Flash objects
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <emphasis>+filter{crude-parental}</emphasis>: Kill all web pages that contain the words "sex" or "warez"
+ </member>
+ </simplelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This is potentially a very powerful feature! And requires a knowledge
+ of regular expressions if you want to <quote>roll your own</quote>.
+ Filtering operates on a line by line basis.
+ </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>
+ Filtering can achieve some of the effects as the <quote>+block</quote>
+ action, i.e. it can be used to block ads and banners. In the overall
+ scheme of things, filtering is one of the last things <quote>Privoxy</quote>
+ does with a web page. So other actions are applied first.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="hide-forwarded">
+<title><emphasis>+hide-forwarded</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ Block any existing X-Forwarded-for HTTP header, and do not add a new one.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
- <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>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+hide-forwarded}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ It is fairly safe to leave this on. It does not seem to break many sites.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="hide-from">
+<title><emphasis>+hide-from</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ To block the browser from sending your email address in a <quote>From:</quote>
+ header.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ Keyword: <quote>block</quote>, or any user defined value.
+ </para>
+ </listitem>
+ </varlistentry>
- <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>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+hide-from{block}}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
- <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>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The keyword <quote>block</quote> will completely remove the header.
+ Alternately, you can specify any value you prefer to send to the web
+ server.
+ </para>
+ </listitem>
+ </varlistentry>
- <listitem>
+</variablelist>
+</sect4>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="hide-referer">
+<title><emphasis>+hide-referer</emphasis></title>
+<anchor id="hide-referrer">
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ Don't send the <quote>Referer:</quote> (sic) HTTP header to the web site.
+ Or, alternately send a forged header instead.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ Prevent the header from being sent with the keyword, <quote>block</quote>.
+ Or, <quote>forge</quote> a URL to one from the same server as the request.
+ Or, set to user defined value of your choice.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+hide-referer{forge}}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ <quote>forge</quote> is the preferred option here, since some servers will
+ not send images back otherwise.
+ </para>
<para>
- Treat this URL as an image. This only matters if it's also <quote>+block</quote>ed,
- in which case a <quote>blocked</quote> image can be sent rather than a HTML page.
- See <quote>+image-blocker{}</quote> below for the control over what is actually sent.
- If you want <emphasis>invisible</emphasis> ads, they should be defined as
- <emphasis>images</emphasis> and <emphasis>blocked</emphasis>. And also,
- <quote>image-blocker</quote> should be set to <quote>blank</quote>. Note you
- cannot treat HTML pages as images in most cases. For instance, frames
- require an HTML page to display. So a frame that is an ad, cannot be
- treated as an image. Forcing an <quote>image</quote> in this
- situation just will not work.
- </para>
- <para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>+image</emphasis>
- </literallayout>
- </msgtext>
- </literal>
+ <quote>+hide-referrer</quote> is an alternate spelling of
+ <quote>+hide-referer</quote>. It has the exact 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 as <quote>referer</quote>.)
</para>
- </listitem>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="hide-user-agent">
+<title><emphasis>+hide-user-agent</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ To change the <quote>User-Agent:</quote> header so web servers can't tell
+ your browser type. Who's business is it anyway?
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ Any user defined string.
+ </para>
+ </listitem>
+ </varlistentry>
- <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>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}}</emphasis>
+ <emphasis>.msn.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Warning! This breaks many web sites that depend on this in order
+ to determine how the target browser will respond to various
+ requests. Use with caution.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="image">
+<title><emphasis>+image</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ To define what <application>Privoxy</application> should treat
+ automatically as an image.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+image}</emphasis>
+ <emphasis>/.*\.(gif|jpg|jpeg|png|bmp|ico)</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This only has meaning if the URL (or pattern) also is
+ <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.)
+ </para>
+ <para>
+ There is little reason to change the default definition for this.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="image-blocker">
+<title><emphasis>+image-blocker</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ Decide what to do with URLs that end up tagged with both <quote>{+block}</quote>
+ and <quote>{+image}</quote>, e.g an advertisement.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ There are four available 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{blank}</quote> will send a 1x1
+ transparent GIF image. <quote>+image-blocker{pattern}</quote> will send a
+ checkerboard type pattern (the default). 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.
+ </para>
+ </listitem>
+ </varlistentry>
- <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>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+image-blocker{blank}}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ If you want <emphasis>invisible</emphasis> ads, they need to be both
+ defined as <emphasis>images</emphasis> and <emphasis>blocked</emphasis>.
+ And then, <quote>image-blocker</quote> should be set to
+ <quote>blank</quote> for invisibility. Note you cannot treat HTML pages as
+ images in most cases. For instance, frames require an HTML page to display.
+ So a frame that is an ad, cannot be treated as an image. Forcing an
+ <quote>image</quote> in this situation just will not work.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="limit-connect">
+<title><emphasis>+limit-connect</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ By default, <application>Privoxy</application> only allows HTTP CONNECT
+ requests to port 443 (the standard, secure HTTPS port). Use
+ <quote>+limit-connect</quote> to disable this altogether, or to allow
+ more ports.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ Any valid port number, or port number range.
+ </para>
+ </listitem>
+ </varlistentry>
- <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.
+ <varlistentry>
+ <term>Example usages:</term>
+ <listitem>
+ <!-- I had trouble getting the spacing to look right in my browser -->
+ <!-- I probably have the wrong font setup, bollocks. -->
+ <literallayout>
+ <emphasis>+limit-connect{443}</emphasis> # This is the default and need not be specified.
+ <emphasis>+limit-connect{80,443}</emphasis> # Ports 80 and 443 are OK.
+ <emphasis>+limit-connect{-3, 7, 20-100, 500-}</emphasis> # Port less than 3, 7, 20 to 100 and above 500 are OK.
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <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):
+ max to 65K).
+ </para>
+ <para>
+ If you don't know what any of this means, there probably is no reason to
+ change this one.
</para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="no-compression">
+<title><emphasis>+no-compression</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ Prevent the specified websites from compressing HTTP data.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+no-compression}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ 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 typically is to turn <quote>no-compression</quote> on.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="no-cookies-keep">
+<title><emphasis>+no-cookies-keep</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ Allow cookies for the current browser session only.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+no-cookies-keep}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ If websites set 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. This is generally turned on for all
+ sites. Sometimes referred to as <quote>session cookies</quote>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="no-cookies-read">
+<title><emphasis>+no-cookies-read</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ Explicitly prevent the web server from reading any cookies on your
+ system.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+no-cookies-read}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Often used in conjunction with <quote>+no-cookies-set</quote> to
+ disable persistant cookies completely.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="no-cookies-set">
+<title><emphasis>+no-cookies-set</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ Explicitly block the web server from sending cookies to your
+ system.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+no-cookies-set}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Often used in conjunction with <quote>+no-cookies-read</quote> to
+ disable persistant cookies completely.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="no-popup">
+<title><emphasis>+no-popup</emphasis></title>
+<anchor id="no-popups">
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ Stop those annoying JavaScript pop-up windows!
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+no-popup}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ <quote>+no-popup</quote> uses a built in filter to disable pop-ups
+ that use the <literal>window.open()</literal> function, etc.
+ </para>
+ <para>
+ An alternate spelling is <quote>+no-popups</quote>, which is
+ interchangeable.
+ </para>
+ </listitem>
+ </varlistentry>
- <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>
+</variablelist>
+</sect4>
- </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>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="vanilla-wafer">
+<title><emphasis>+vanilla-wafer</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ Sends a cookie for every site stating that you do not accept any copyright
+ on cookies sent to you, and asking them not to track you.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
- <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>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+vanilla-wafer}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action only applies if you are using a <filename>jarfile</filename>
+ for saving cookies. Of course, this is a (relatively) unique header and
+ could be used to track you.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="wafer">
+<title><emphasis>+wafer</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Multi-value.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Typical uses:</term>
+ <listitem>
+ <para>
+ This allows you to send an arbitrary, user definable cookie.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Possible values:</term>
+ <listitem>
+ <para>
+ User specified cookie name and corresponding value.
+ </para>
+ </listitem>
+ </varlistentry>
- <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>
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <literallayout>
+ <emphasis>{+wafer{name=value}}</emphasis>
+ <emphasis>.example.com</emphasis>
+ </literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This can be specified multiple times in order to add as many cookies as you
+ like.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
- </itemizedlist>
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect4 id="act-examples" renderas="sect3">
+<title>Actions Examples</title>
<para>
- The meaning of any of the above is reversed by preceding the action with a
- <quote>-</quote>, in place of the <quote>+</quote>.
+ Note that the meaning of any of the above examples is reversed by preceding
+ the action with a <quote>-</quote>, in place of the <quote>+</quote>. Also,
+ that some actions are turned on in the default section of the actions file,
+ and require little to no additional configuration. These are just <quote>on</quote>.
+ Some actions that are turned on the default section do typically require
+ exceptions to be listed in the lower sections of actions file.
</para>
<para>
# 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
+ # that saved from one browser session to the next.
{ -no-cookies-read }
{ -no-cookies-set }
{ -no-cookies-keep }
<para>
Turn on page filtering according to rules in the defined sections
- of <filename>refilterfile</filename>, and make one exception for
- sourceforge:
+ of <filename>default.filter</filename>, and make one exception for
+ Sourceforge:
</para>
<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>
+ the <quote>blocked</quote> banner). Many of these use
+ <link linkend="regex">regular expressions</link> that will expand to match
+ multiple URLs: </para>
<para>
<literal>
for all sites. See the <link linkend="ACTIONSANAT">Appendix</link>
for a brief example on troubleshooting actions.
</para>
+</sect4>
</sect3>
.windowsupdate.microsoft.com
.nytimes.com
- # Shopping sites - still want to block ads.
+ # Shopping sites - but we still want to block ads.
{shop}
.quietpc.com
.worldpay.com # for quietpc.com
.jungle.com
.scan.co.uk
- # These shops require pop-ups
+ # These shops require pop-ups also
{shop -no-popups}
.dabs.com
.overclockers.co.uk
<emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
the following character should be taken literally. This is used where one of the
special characters (e.g. <quote>.</quote>) needs to be taken literally and
- not as a special meta-character.
+ not as a special meta-character. Example: <quote>example\.com</quote>, makes
+ sure the period is recognized only as a period (and not expanded to its
+ metacharacter meaning of any single character).
</member>
</simplelist></para>
<para><simplelist>
<member>
<emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
- any of the enclosed characters are encountered.
+ any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
+ matches any numeric digit (zero through nine). As an example, we can combine
+ this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
</member>
</simplelist></para>
<member>
<emphasis>|</emphasis> - The <quote>bar</quote> character works like an
<quote>or</quote> conditional statement. A match is successful if the
- sub-expression on either side of <quote>|</quote> matches.
+ sub-expression on either side of <quote>|</quote> matches. As an example:
+ <quote>/(this|that) example/</quote> uses grouping and the bar character
+ and would match either <quote>this example</quote> or <quote>that
+ example</quote>, and nothing else.
</member>
</simplelist></para>
<member>
<emphasis>s/string1/string2/g</emphasis> - This is used to rewrite strings of text.
<quote>string1</quote> is replaced by <quote>string2</quote> in this
- example.
+ example. There must of course be a match on <quote>string1</quote> first.
</member>
</simplelist></para>
</para>
<para>
- These may be bookmarked for quick reference.
+ These may be bookmarked for quick reference. See next.
</para>
To save them, right-click the link and choose <quote>Add to Favorites</quote>
(IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
- Bookmarklet directly from your favourites/bookmarks. For even faster access,
+ Bookmarklet directly from your favorites/bookmarks. For even faster access,
you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
Toolbar</quote> (Netscape), and run them with a single click.
</para>
</sect2>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="chain">
+<title>Chain of Events</title>
+<para>
+ Let's take a quick look at the basic sequence of events when a web page is
+ requested by your browser and <application>Privoxy</application> is on duty:
+</para>
+
+<para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ First, the web browser requests a page, and this request is intercepted by
+ <application>Privoxy</application> immediately.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>Privoxy</application> traps any request for internal CGI
+ pages (e.g http://p.p/) and relays these back to the browser.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the URL matches a <quote>+block</quote> pattern, then it is blocked
+ and the banner displayed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Untrusted URLs are blocked. If URLs are being added to the
+ <filename>trust</filename> file, then that is done.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <quote>+fast-redirect</quote> is processed, stripping unwanted parts
+ of the request web page URL.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ At this point, <application>Privoxy</application> relays the request to the
+ web server, and requests the page (assuming nothing up to this point has
+ prevented getting us from this far).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The first few hundred bytes are read from the web server and
+ <quote>+kill-popups</quote> is processed, if enabled.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <quote>+filter</quote> applies, the rest of the page is read into
+ memory and then the filters are processed. Filters are applied in the order they
+ are specified in the <filename>default.filter</filename> file. The entire
+ page, which is now filtered, is then sent by
+ <application>Privoxy</application> to your browser.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ As the browser receives the filtered page content, it will read and request any
+ embedded URLs on the page, e.g. an ad image. As the browser requests these
+ secondary URLs from whatever server they may be on,
+ <application>Privoxy</application> handles these same as above, and the process
+ is repeated for each such URL. Note that a fancy web page may have many, many
+ such URLs for graphics, frames, etc.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+</sect2>
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="actionsanat">
<title>Anatomy of an Action</title>
easy to understand what is happening. And sometimes we need to be able to
<emphasis>see</emphasis> just what <application>Privoxy</application> is
doing. Especially, if something <application>Privoxy</application> is doing
- is causing us a problem inadvertantly. It can be a little daunting to look at
+ is causing us a problem inadvertently. It can be a little daunting to look at
the actions and filters files themselves, since they tend to be filled with
<quote>regular expressions</quote> whose consequences are not always
- so obvious. <application>Privoxy</application> provides the
+ so obvious.
+</para>
+
+<para>
+ One quick test to see if <application>Privoxy</application> is causing a problem
+ or not, is to disable it temporarily. This should be the first troubleshooting
+ step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
+ and easy way to do this (be sure to flush caches afterwards!).
+</para>
+
+<para>
+ <application>Privoxy</application> also provides the
<ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
page that can show us very specifically how <application>actions</application>
are being applied to any given URL. This is a big help for troubleshooting.
- </para>
+</para>
<para>
First, enter one URL (or partial URL) at the prompt, and then
<application>Privoxy</application> will tell us
how the current configuration will handle it. This will not
- help with filtering effects from the <filename>default.filter</filename> file! It
- also will not tell you about any other URLs that may be embedded within the
- URL you are testing. For instance, images such as ads are expressed as URLs
- within the raw page source of HTML pages. So you will only get info for the
- actual URL that is pasted into the prompt area -- not any sub-URLs. If you
- want to know about embedded URLs like ads, you will have to dig those out of
- the HTML source. Use your browser's <quote>View Page Source</quote> option
- for this. Or right click on the ad, and grab the URL.
+ help with filtering effects (i.e. the <quote>+filter</quote> action) from the
+ <filename>default.filter</filename> file since this is handled very differently
+ and not so easy to trap! It also will not tell you about any other URLs that
+ may be embedded within the URL you are testing (i.e. a web page). For
+ instance, images such as ads are expressed as URLs within the raw page source
+ of HTML pages. So you will only get info for the actual URL that is pasted
+ into the prompt area -- not any sub-URLs. If you want to know about embedded
+ URLs like ads, you will have to dig those out of the HTML source. Use your
+ browser's <quote>View Page Source</quote> option for this. Or right click on
+ the ad, and grab the URL.
</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>.
+ Just below this then are two explicit matches for <quote>.google.com</quote>.
The first is negating our various cookie blocking actions (i.e. we will allow
cookies here). The second is allowing <quote>fast-redirects</quote>. Note
that there is a leading dot here -- <quote>.google.com</quote>. This will
<para>
And now we pull it altogether in the bottom section and summarize how
- <application>Privoxy</application> is appying all its <quote>actions</quote>
+ <application>Privoxy</application> is applying all its <quote>actions</quote>
to <quote>google.com</quote>:
</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>
+ now add a new action below this that explicitly does <emphasis>not</emphasis>
block (-block) pages with <quote>adsl</quote>. There are various ways to
handle such exceptions. Example:
</para>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: user-manual.sgml,v $
+ Revision 1.90 2002/04/23 21:41:25 hal9
+ Linuxconf is deprecated on RH, substitute chkconfig.
+
+ Revision 1.89 2002/04/23 21:05:28 oes
+ Added hint for startup on Red Hat
+
+ Revision 1.88 2002/04/23 05:37:54 hal9
+ Add AmigaOS install stuff.
+
+ Revision 1.87 2002/04/23 02:53:15 david__schmidt
+ Updated OSX installation section
+ Added a few English tweaks here an there
+
+ Revision 1.86 2002/04/21 01:46:32 hal9
+ Re-write actions section.
+
+ Revision 1.85 2002/04/18 21:23:23 hal9
+ Fix ugly typo (mine).
+
+ Revision 1.84 2002/04/18 21:17:13 hal9
+ Spell Redhat correctly (ie Red Hat). A few minor grammar corrections.
+
+ Revision 1.83 2002/04/18 18:21:12 oes
+ Added RPM install detail
+
+ Revision 1.82 2002/04/18 12:04:50 oes
+ Cosmetics
+
+ Revision 1.81 2002/04/18 11:50:24 oes
+ Extended Install section - needs fixing by packagers
+
+ Revision 1.80 2002/04/18 10:45:19 oes
+ Moved text to buildsource.sgml, renamed some filters, details
+
+ Revision 1.79 2002/04/18 03:18:06 hal9
+ Spellcheck, and minor touchups.
+
+ Revision 1.78 2002/04/17 18:04:16 oes
+ Proofreading part 2
+
Revision 1.77 2002/04/17 13:51:23 oes
Proofreading, part one
projects / privoxy.git / blobdiff