<!entity contacting SYSTEM "contacting.sgml">
<!entity history SYSTEM "history.sgml">
<!entity copyright SYSTEM "copyright.sgml">
-<!entity p-version "2.9.14">
+<!entity license SYSTEM "license.sgml">
+<!entity p-version "2.9.15">
<!entity p-status "beta">
<!entity % p-not-stable "INCLUDE">
<!entity % p-stable "IGNORE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 1.98 2002/04/28 05:43:59 hal9 Exp $
+ $Id: user-manual.sgml,v 1.104 2002/05/04 08:44:45 swa Exp $
Written by and Copyright (C) 2001 the SourceForge
Privoxy team. http://www.privoxy.org/
<article id="index">
<artheader>
+
<title>Privoxy User Manual</title>
-<pubdate>$Id: user-manual.sgml,v 1.98 2002/04/28 05:43:59 hal9 Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.104 2002/05/04 08:44:45 swa Exp $</pubdate>
+
+<copyright>
+ <year>2001</year>
+ <year>2002</year>
+ <holder>Privoxy Developers</holder>
+</copyright>
+
+
+<!--
+
+Note: this should generate a separate page, and a live link to it.
+But it doesn't for some mysterious reason. Please leave commented
+unless it can be fixed proper. For the time being, the copyright
+statement will be in copyright.smgl.
+
+Hal.
+
+<legalnotice id="legalnotice">
+ <para>
+ text goes here ........
+ </para>
+</legalnotice>
+
+-->
+<!--
<authorgroup>
<author>
<affiliation>
</affiliation>
</author>
</authorgroup>
-
+-->
<abstract>
<![%dummy;[
<para>
</artheader>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="intro" label=""><title></title>
-<!-- dummy section to force TOC on page by itself -->
-<!-- DO NOT REMOVE! please ;) -->
-<para> </para>
-</sect1>
-
<!-- ~~~~~ New section ~~~~~ -->
<sect1 label="1" id="introduction"><title>Introduction</title>
<para>
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>. For installing and compiling the source code, please look
- into our Developer Manual.
-</para>
-
-<para>
- If you like to live on the bleeding edge and are not afraid of using
- possibly unstable development versions, you can check out the up-to-the-minute
- version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
- CVS repository</ulink> or simply download <ulink
- url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">the nightly CVS
- tarball.</ulink> Again, we refer you to the Developer Manual.
+ Page</ulink>.
</para>
-<!-- Include supported.sgml boilerplate -->
- &supported;
-<!-- end boilerplate -->
-
<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>
In any case <emphasis>be sure to backup your old configuration
if it is valuable to you.</emphasis> See the
<link linkend="upgradersnote">note to upgraders</link> section
below.
</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="installation-packages"><title>Binary Packages</title>
+<para>
+How to install the binary packages depends on your operating system:
+</para>
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-pack-rpm"><title>Red Hat 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>,
Otherwise, RPM will try to remove <application>Junkbuster</application>
automatically, before installing <application>Privoxy</application>.
</para>
-</sect2>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-deb"><title>Debian</title>
+<sect3 id="installation-deb"><title>Debian</title>
<para>
FIXME.
</para>
-</sect2>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-pack-win"><title>Windows</title>
+<sect3 id="installation-pack-win"><title>Windows</title>
<para>
Just double-click the installer, which will guide you through
in the same directory as you installed Privoxy in. We do not
use the registry of Windows.
</para>
-</sect2>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-pack-bintgz"><title>Solaris, NetBSD, FreeBSD, HP-UX</title>
+<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>
-</sect2>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-os2"><title>OS/2</title>
+<sect3 id="installation-os2"><title>OS/2</title>
<para>
First, make sure that no previous installations of
The directory you choose to install <application>Privoxy</application>
into will contain all of the configuration files.
</para>
-</sect2>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-mac"><title>Max OSX</title>
+<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,
automatically on system bring-up via
<literal>/System/Library/StartupItems/Privoxy</literal>.
</para>
-</sect2>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-amiga"><title>AmigaOS</title>
+<sect3 id="installation-amiga"><title>AmigaOS</title>
<para>
Copy and then unpack the <filename>lha</filename> archive to a suitable location.
All necessary files will be installed into <application>Privoxy</application>
TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
<application>Privoxy</application> is still running).
</para>
+</sect3>
</sect2>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="installation-source"><title>Building from Source</title>
+
+<para>
+ The most convenient way to obtain the <application>Privoxy</application> sources
+ is to download the source tarball from our <ulink url="http://sf.net/projects/ijbswa/">project
+ page</ulink>.
+</para>
+
+<para>
+ If you like to live on the bleeding edge and are not afraid of using
+ possibly unstable development versions, you can check out the up-to-the-minute
+ version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
+ CVS repository</ulink> or simply download <ulink
+ url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">the nightly CVS
+ tarball.</ulink>
+</para>
+
+<!-- include buildsource.sgml boilerplate: -->
+&buildsource;
+<!-- end boilerplate -->
+
+
+
+</sect2>
+
</sect1>
<!-- ~ End section ~ -->
<sect1 id="upgradersnote">
<title>Note to Upgraders</title>
<para>
- There are very significant changes from older versions of
- <application>Junkbuster</application> to the current
- <application>Privoxy</application>. Configuration is substantially
- changed. <application>Junkbuster 2.0.x</application> and earlier
- configuration files will not migrate. The functionality of the old
- <filename>blockfile</filename>, <filename>cookiefile</filename> and
- <filename>imagelist</filename>, are now combined into the
- <ulink url="actions-file.html"><quote>actions files</quote></ulink>.
+ There are very significant changes from earlier
+ <application>Junkbuster</application> versions to the current
+ <application>Privoxy</application>. The number, names, syntax, and
+ purposes of configuration files have substantially changed.
+ <application>Junkbuster 2.0.x</application> configuration
+ files will not migrate, <application>Junkbuster 2.9.x</application>
+ and <application>Privoxy</application> configurations will need to be
+ ported. The functionalities of the old <filename>blockfile</filename>,
+ <filename>cookiefile</filename> and <filename>imagelist</filename>
+ are now combined into the <ulink url="actions-file.html"><quote>actions
+ files</quote></ulink>.
<filename>default.action</filename>, is the main actions file. Local
exceptions should best be put into <filename>user.action</filename>.
</para>
<listitem>
<para>
- Install <application>Privoxy</application>. See the section <link linkend="installation">Installing</link>.
+ If upgrading, please back up any configuration files. See
+ the <link linkend="upgradersnote">Note to Upgraders</link> Section.
</para>
+</listitem>
+ <listitem>
+ <para>
+ Install <application>Privoxy</application>. See the <link
+ linkend="installation">Installation Section</link> for platform specific
+ information.
+ </para>
</listitem>
<listitem>
<para>
- Start <application>Privoxy</application>. See the section <link linkend="startup">Starting <application>Privoxy</application></link>.
+ Start <application>Privoxy</application>, if the installation program has
+ not done this already. See the section <link linkend="startup">Starting
+ <application>Privoxy</application></link>.
</para>
</listitem>
<listitem>
<para>
- Change your browser's configuration to use the proxy <literal>localhost</literal> on port
- <literal>8118</literal>. See the section <link linkend="startup">Starting <application>Privoxy</application></link>.
+ Set your browser to use <application>Privoxy</application> as HTTP and HTTPS
+ proxy by setting the proxy configuration for address of
+ <literal>localhost</literal> and port <literal>8118</literal>.
+ (<application>Junkbuster</application> and earlier versions of
+ <application>Privoxy</application> used port 8000.) See the section <link
+ linkend="startup">Starting <application>Privoxy</application></link>.
</para>
</listitem>
<listitem>
<para>
- Enjoy surfing with enhanced comfort and privacy. Please see the section
- <link linkend="contact">Contacting the Developers</link> on how to report
- bugs or problems with websites or to get help. You may want to change the
- file <filename>user.action</filename> to further tweak your new browsing
- experience.
+ Flush your browser's caches, to remove any cached ad images.
</para>
- </listitem>
+</listitem>
+
+ <listitem>
+ <para>
+ Enjoy surfing with enhanced comfort and privacy. You may want to customize the
+ <link linkend="actions-file"><filename>user.action</filename></link> file to
+ personalize your new browsing experience. See the <link
+ linkend="configuration">Configuration section</link> for more configuration
+ options, and how to further customize your installation.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you experience problems with sites that <quote>misbehave</quote>, see
+ the <link linkend="actionsanat">Anatomy of an Action</link> section in the
+ Appendix.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Please see the section <link linkend="contact">Contacting the
+ Developers</link> on how to report bugs or problems with websites or to get
+ help.
+ </para>
+ </listitem>
</itemizedlist>
</para>
<para>
Another feature where you will probably want to define exceptions for trusted
sites is the popup-killing (through the <ulink
- url="actions-file.html#KILL-POPUPS"><quote>+kill-popups</quote></ulink>and
+ url="actions-file.html#KILL-POPUPS"><quote>+kill-popups</quote></ulink> and
<ulink
url="actions-file.html#FILTER-POPUPS"><quote>+filter{popups}</quote></ulink>
actions), because your favorite shopping, banking, or leisure site may need
<para>
This should be self-explanatory. Note the first item leads to an editor for the
- <quote>actions list</quote>, which is where the ad, banner, cookie,
- and URL blocking magic is configured as well as other advanced features of
+ <link linkend="actions-file">actions files</link>, which is where the ad, banner,
+ cookie, and URL blocking magic is configured as well as other advanced features of
<application>Privoxy</application>. This is an easy way to adjust various
aspects of <application>Privoxy</application> configuration. The actions
file, and other configuration files, are explained in detail below.
have problems with your current actions and filters. You can in fact use
it as a test to see whether it is <application>Privoxy</application>
causing the problem or not. <application>Privoxy</application> continues
- to run as a proxy in this case, but all filtering is disabled. There
+ to run as a proxy in this case, but all manipulation is disabled, i.e.
+ <application>Privoxy</application> acts like a normal forwarding proxy. There
is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
that you can toggle <application>Privoxy</application> with one click from
your browser.
<listitem>
<para>
- The main configuration file is named <link linkend="config">config</link>
+ The <link linkend="config">main configuration file</link> is named <filename>config</filename>
on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
on Windows. This is a required file.
</para>
<listitem>
<para>
- <filename>default.action</filename> (the main <link linkend="actions-file">actions file</link>) is used to define
- the default settings for various <quote>actions</quote> relating to images, banners,
- pop-ups, access restrictions, banners and cookies.
+ <filename>default.action</filename> (the main <link linkend="actions-file">actions file</link>)
+ is used to define which <quote>actions</quote> relating to banner-blocking, images, pop-ups,
+ content modification, cookie handling etc should be applied by default. It also defines many
+ exceptions (both positive and negative) from this default set of actions that enable
+ <application>Privoxy</application> to selectively eliminate the junk, and only the junk, on
+ as many websites as possible.
</para>
<para>
Multiple actions files may be defined in <filename>config</filename>. These
are processed in the order they are defined. Local customizations and locally
- preferred exceptions to the default policies as defined in
- <filename>default.action</filename> are probably best applied in
- <filename>user.action</filename>, which should be preserved across
- upgrades. <filename>standard.action</filename> is also included. This is mostly
- for <application>Privoxy's</application> internal use.
+ preferred exceptions to the default policies as defined in
+ <filename>default.action</filename> (which you will most propably want
+ to define sooner or later) are probably best applied in
+ <filename>user.action</filename>, where you can preserve them across
+ upgrades. <filename>standard.action</filename> is for
+ <application>Privoxy's</application> internal use.
</para>
<para>
There is also a web based editor that can be accessed from
<ulink
- url="http://config.privoxy.org/show-status/">http://config.privoxy.org/show-status/</ulink>
+ url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
(Shortcut: <ulink
- url="http://p.p/show-status/">http://p.p/show-status/</ulink>) for the
+ url="http://p.p/show-status">http://p.p/show-status</ulink>) for the
various actions files.
</para>
</listitem>
<para>
All files use the <quote><literal>#</literal></quote> character to denote a
- comment (the rest of the line will be ignored) angd understand line continuation
+ comment (the rest of the line will be ignored) and understand line continuation
through placing a backslash ("<literal>\</literal>") as the very last character
in a line. If the <literal>#</literal> is preceded by a backslash, it looses
its special function. Placing a <literal>#</literal> in front of an otherwise
<literal>
<msgtext>
<literallayout>
- <emphasis>confdir /etc/privoxy</emphasis>
- </literallayout>
+ <emphasis>confdir /etc/privoxy</emphasis></literallayout>
</msgtext>
</literal>
</para>
where to find those other files.
</para>
+<para>
+ The user running Privoxy, must have read permission for all
+ configuration files, and write permission to any files that would
+ be modified, such as log files.
+</para>
<sect3 renderas="sect4" id="confdir"><title>confdir</title>
<term>Specifies:</term>
<listitem>
<para>
- The <link linkend="actions">actions</link> file(s) to use
+ The <link linkend="actions-file">actions file(s)</link> to use
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type of value:</term>
<listitem>
- <para>File name, relative to <literal>confdir</literal></para>
+ <para>File name, relative to <literal>confdir</literal>, without the <literal>.action</literal> suffix</para>
</listitem>
</varlistentry>
<varlistentry>
<listitem>
<simplelist>
<member>
- <msgtext><literallayout> standard # Internal purposes, recommended not editing</literallayout></msgtext>
+ <msgtext><literallayout> standard # Internal purposes, no editing recommended</literallayout></msgtext>
</member>
<member>
<msgtext><literallayout> default # Main actions file</literallayout></msgtext>
<para>
No textual content filtering takes place, i.e. all
<literal>+filter{<replaceable class="parameter">name</replaceable>}</literal>
- actions in the actions files are turned off
+ actions in the actions files are turned neutral.
</para>
</listitem>
</varlistentry>
the effect that cron.daily will automatically archive, gzip, and empty the
log, when it exceeds 1M size.
</para>
+ <para>
+ Any log files must be writable by whatever user <application>Privoxy</application>
+ is being run as (default on UNIX, user id is <quote>privoxy</quote>).
+ </para>
</listitem>
</varlistentry>
</variablelist>
</varlistentry>
</variablelist>
</sect3>
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="local-set-up">
+<title>Local Set-up Documentation</title>
+
+ <para>
+ If you intend to operate <application>Privoxy</application> for more users
+ that just yourself, it might be a good idea to let them know how to reach
+ you, what you block and why you do that, your policies etc.
+ </para>
<sect3 renderas="sect4" id="user-manual"><title>user-manual</title>
<variablelist>
<varlistentry>
<term>Default value:</term>
<listitem>
- <para><ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink></para>
+ <para><emphasis>Unset</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Effect if unset:</term>
<listitem>
<para>
- The default will be used.
+ <ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/<replaceable class="parameter">version</replaceable>/user-manual/</ulink>
+ will be used, where <replaceable class="parameter">version</replaceable> is the <application>Privoxy</application> version.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes:</term>
<listitem>
- <para>
- The User Manual is used for help hints from some of the internal CGI pages.
- It is normally packaged with the binary distributions, and would make more
- sense to have this pointed at a locally installed copy.
+ <para>
+ The User Manual URI is used for help links from some of the internal CGI pages.
+ The manual itself is normally packaged with the binary distributions, so you propably want
+ to set this to a locally installed copy. For multi-user setups, you could provide a copy on
+ a local webserver for all your users and use the corresponding URL here.
</para>
<para>
- A more useful example (Unix):
+ Examples:
</para>
- <para>
- <emphasis>user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/</emphasis>
+ <para>
+ Unix, in local filesystem:
</para>
- </listitem>
+ <para>
+ <screen>user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/</screen>
+ </para>
+ <para>
+ Any platform, on local webserver (called <quote>local-webserver</quote>):
+ </para>
+ <para>
+ <screen>user-manual http://local-webserver/privoxy-user-manual/</screen>
+ </para>
+ <warning>
+ <para>
+ If set, this option should be <emphasis>the first option in the config file</emphasis>, because
+ it is used while the config file is being read.
+ </para>
+ </warning>
+ </listitem>
</varlistentry>
</variablelist>
</sect3>
-</sect2>
-
-<!-- ~ End section ~ -->
-
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2 id="local-set-up">
-<title>Local Set-up Documentation</title>
-
- <para>
- If you intend to operate <application>Privoxy</application> for more users
- that just yourself, it might be a good idea to let them know how to reach
- you, what you block and why you do that, your policies etc.
- </para>
-
<sect3 renderas="sect4" id="trust-info-url"><title>trust-info-url</title>
<variablelist>
<para>
The actions files are used to define what actions
- <application>Privoxy</application> takes for which URLs, and thus determines
+ <application>Privoxy</application> takes for which URLs, and thus determine
how ad images, cookies and various other aspects of HTTP content and
transactions are handled, and on which sites (or even parts thereof). There
- are three such files included with <application>Privoxy</application>,
- with slightly different purposes. <filename>default.action</filename> sets
- the default policies. <filename>standard.action</filename> is used by
- <application>Privoxy</application> and the web based editor to set
- pre-defined values (and normally should not be edited). Local exceptions
- are best done in <filename>user.action</filename>. The content of these
- can all be viewed and edited from <ulink
- url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
+ are three such files included with <application>Privoxy</application> (as of
+ version 2.9.15), with differing purposes:
</para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename>standard.action</filename> - is used by the web based editor,
+ to set various pre-defined sets of rules for the default actions section
+ in <filename>default.action</filename>. These have increasing levels of
+ aggressiveness <emphasis>and have no influence on your browsing unless
+ you select them explicitly in the editor</emphasis>. It is not recommend
+ to edit this file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>default.action</filename> - is the primary action file
+ that sets the initial values for all actions. It is intended to
+ provide a base level of functionality for
+ <application>Privoxy's</application> array of features. So it is
+ a set of broad rules that should work reasonably well for users everywhere.
+ This is the file that the developers are keeping updated, and making
+ available to users.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>user.action</filename> - is intended to be for local site
+ preferences and exceptions. As an example, if your ISP or your bank
+ has specific requirements, and need special handling, this kind of
+ thing should go here. This file will not be upgraded.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
-<para>
- Anything you want can be blocked, including ads, banners, or just some obnoxious
- URL that you would rather not see is done here. Cookies can be accepted or rejected, or
- accepted only during the current browser session (i.e. not written to disk),
- content can be modified, JavaScripts tamed, user-tracking fooled, and much more.
- See below for a complete list of available actions.
+<para>
+ The list of actions files to be used are defined in the main configuration
+ file, and are processed in the order they are defined. The content of these
+ can all be viewed and edited from <ulink
+ url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
</para>
<para>
- An actions file typically has sections. Near the top, <quote>aliases</quote> are
- optionally defined (discussed <ulink
- url="actions-file.html#ALIASES">below</ulink>), then the default set of rules
- which will apply universally to all sites and pages. And then below that,
- exceptions to the defined universal policies.
+ An actions file typically has multiple sections. If you want to use
+ <quote>aliases</quote> in an actions file, you have to place the (optional)
+ <link linkend="aliases">alias section</link> at the top of that file.
+ Then comes the default set of rules which will apply universally to all
+ sites and pages (be <emphasis>very careful</emphasis> with using such a
+ universal set in <filename>user.action</filename> or any other actions file after
+ <filename>default.action</filename>, because it will override the result
+ from consulting any previous file). And then below that,
+ exceptions to the defined universal policies. You can regard
+ <filename>user.action</filename> as an appendix to <filename>default.action</filename>,
+ with the advantage that is a separate file, which makes preserving your
+ personal settings across <application>Privoxy</application> upgrades easier.
+</para>
+
+<para>
+ Actions can be used to block anything you want, including ads, banners, or
+ just some obnoxious URL that you would rather not see. Cookies can be accepted
+ or rejected, or accepted only during the current browser session (i.e. not
+ written to disk), content can be modified, JavaScripts tamed, user-tracking
+ fooled, and much more. See below for a <link linkend="actions">complete list
+ of actions</link>.
</para>
<!-- ~~~~~ New section ~~~~~ -->
<sect2>
<title>How to Edit</title>
<para>
- The easiest way to edit the <quote>actions</quote> files is with a browser by
+ The easiest way to edit the actions files is with a browser by
using our browser-based editor, which can be reached from <ulink
url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
+ The editor allows both fine-grained control over every single feature on a
+ per-URL basis, and easy choosing from wholesale sets of defaults like
+ <quote>Cautious</quote>, <quote>Medium</quote> or <quote>Advanced</quote>.
</para>
<para>
If you prefer plain text editing to GUIs, you can of course also directly edit the
- the actions files.
+ the actions files. Look at <filename>default.action</filename> which is richly
+ commented.
</para>
</sect2>
<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
+ compared to all patterns in each action file file. Every time it matches, the list of
applicable actions for the URL is incrementally updated, using the heading
of the section in which the pattern is located. If multiple matches for
the same URL set the same action differently, the last match wins. If not,
</para>
<para>
- You can trace this process by visiting <ulink
+ You can trace this process
for any given URL by visiting <ulink
url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
</para>
All actions are disabled by default, until they are explicitly enabled
somewhere in an actions file. Actions are turned on if preceded with a
<quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
- <quote>+action</quote> means <quote>do that action</quote>, e.g.
- <quote>+block</quote> means please <quote>block the following URL
- patterns</quote>.
+ <literal>+action</literal> means <quote>do that action</quote>, e.g.
+ <literal>+block</literal> means <quote>please block URLs that match the
+ following patterns</quote>, and <literal>-block</literal> means <quote>don't
+ block URLs that match the following patterns, even if <literal>+block</literal>
+ previously applied.</quote>
+
+</para>
+
+<para>
+ Again, actions are invoked by placing them on a line, enclosed in curly braces and
+ separated by whitespace, like in
+ <literal>{+some-action -some-other-action{some-parameter}}</literal>,
+ followed by a list of URL patterns, one per line, to which they apply.
+ Together, the actions line and the following pattern lines make up a section
+ of the actions file.
</para>
<para>
- Actions 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:
+ There are three classes of actions:
</para>
<para>
<itemizedlist>
-
<listitem>
<para>
- Boolean, i.e the action can only be <quote>on</quote> or
- <quote>off</quote>. Examples:
- </para>
+ Boolean, i.e the action can only be <quote>enabled</quote> or
+ <quote>disabled</quote>. Syntax:
+ </para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>{+name}</emphasis> # enable this action
- <emphasis>{-name}</emphasis> # disable this action
- </literallayout>
- </msgtext>
- </literal>
+ <screen>
+ +<replaceable class="function">name</replaceable> # enable action <replaceable class="parameter">name</replaceable>
+ -<replaceable class="function">name</replaceable> # disable action <replaceable class="parameter">name</replaceable></screen>
+ </para>
+ <para>
+ Example: <literal>+block</literal>
</para>
</listitem>
<listitem>
<para>
- Parameterized, e.g. <quote>+/-hide-user-agent{ Mozilla 1.0 }</quote>,
- where some value is required in order to enable this type of action.
- Examples:
+ Parameterized, where some value is required in order to enable this type of action.
+ Syntax:
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>{+name{param}}</emphasis> # enable action and set parameter to <quote>param</quote>
- <emphasis>{-name}</emphasis> # disable action (<quote>parameter</quote>) can be omitted
- </literallayout>
- </msgtext>
- </literal>
+ <screen>
+ +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and set parameter to <replaceable class="parameter">param</replaceable>,
+ # overwriting parameter from previous match if necessary
+ -<replaceable class="function">name</replaceable> # disable action. The parameter can be omitted</screen>
+ </para>
+ <para>
+ Note that if the URL matches multiple positive forms of a parameterized action,
+ the last match wins, i.e. the params from earlier matches are simply ignored.
+ </para>
+ <para>
+ Example: <literal>+hide-user-agent{ Mozilla 1.0 }</literal>
</para>
</listitem>
<listitem>
<para>
- <!-- oes, or someone, check this. Re-worded 04/20/02 HB. -->
- Multi-value, e.g. <quote>{+/-add-header{Name: value}}</quote> or
- <quote>{+/-send-wafer{name=value}}</quote>), where some value needs to be defined
- in addition to simply enabling the action. Examples:
+ Multi-value. These look exactly like parameterized actions,
+ but they behave differently: If the action applies multiple times to the
+ same URL, but with different parameters, <emphasis>all</emphasis> the parameters
+ from <emphasis>all</emphasis> matches are remembered. This is used for actions
+ that can be executed for the same request repeatedly, like adding multiple
+ headers, or filtering through multiple filters. Syntax:
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- <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>
+ <screen>
+ +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and add <replaceable class="parameter">param</replaceable> to the list of parameters
+ -<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # remove the parameter <replaceable class="parameter">param</replaceable> from the list of parameters
+ # If it was the last one left, disable the action.
+ <replaceable class="parameter">-name</replaceable> # disable this action completely and remove all parameters from the list</screen>
+ </para>
+ <para>
+ Examples: <literal>+add-header{X-Fun-Header: Some text}</literal> and
+ <literal>+filter{html-annoyances}</literal>
</para>
</listitem>
Actions files are processed in the order they are defined in
<filename>config</filename> (the default installation has three actions
files). It also quite possible for any given URL pattern to match more than
- one action!
+ one pattern and thus more than one set of actions!
</para>
<!-- start actions listing -->
<para>
- The list of valid <application>Privoxy</application> <quote>actions</quote> are:
+ The list of valid <application>Privoxy</application> actions are:
</para>
</varlistentry>
<varlistentry>
- <term>Typical uses:</term>
+ <term>Purpose and typical uses:</term>
<listitem>
<para>
- Send a user defined HTTP header to the web server.
+ Send a user defined HTTP header to the web server. Can be used to confuse log analysis.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Any value is possible. Validity of the defined HTTP headers is not checked.
+ It is recommended that you use the <quote><literal>X-</literal></quote> prefix
+ for custom headers.
</para>
</listitem>
</varlistentry>
<listitem>
<literallayout>
<emphasis>{+add-header{X-User-Tracking: sucks}}</emphasis>
- <emphasis>.example.com</emphasis>
- </literallayout>
+ <emphasis>.example.com</emphasis></literallayout>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term>Typical uses:</term>
+ <term>Purpose and 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.
+ Requests for URLs to which this action applies are blocked, i.e. the requests are not
+ forwarded to the remote server, but answered locally with a substitute page or image,
+ as determined by the <link linkend="handle-as-image">handle-as-image</link> and
+ <link linkend="set-image-blocker">set-image-blocker</link> actions.
+ It is typically used to block ads or other obnoxious content.
</para>
</listitem>
</varlistentry>
{ <ulink url="actions-file.html#BLOCK">+block</ulink> }
www.my-isp-example.com/logo[0-9].gif
+
# Say the site where you do your homebanking needs to open
# popup windows, but you have chosen to kill popups by
# default. This will allow it for your-example-bank.com:
{ <ulink url="actions-file.html#FILTER-POPUPS">-filter{popups}</ulink> <ulink url="actions-file.html#KILL-POPUPS">-kill-popups</ulink> }
.my-example-bank.com
+
# This site is delicate, and requires kid-glove
# treatment.
{ fragile }
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="copyright"><title>Copyright and History</title>
+<sect1 id="copyright"><title>Copyright, License and History</title>
<sect2><title>Copyright</title>
<!-- Include copyright.sgml: -->
©right;
<!-- end copyright -->
</sect2>
+<!-- ~ End section ~ -->
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2><title>License</title>
+<!-- Include copyright.sgml: -->
+ &license;
+<!-- end copyright -->
+</sect2>
<!-- ~ End section ~ -->
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: user-manual.sgml,v $
+ Revision 1.104 2002/05/04 08:44:45 swa
+ bumped version
+
+ Revision 1.103 2002/05/04 00:40:53 hal9
+ -Remove the TOC first page kludge. It's fixed proper now in ldp.dsl.in.
+ -Some minor additions to Quickstart.
+
+ Revision 1.102 2002/05/03 17:46:00 oes
+ Further proofread & reactivated short build instructions
+
+ Revision 1.101 2002/05/03 03:58:30 hal9
+ Move the user-manual config directive to top of section. Add note about
+ Privoxy needing read permissions for configs, and write for logs.
+
+ Revision 1.100 2002/04/29 03:05:55 hal9
+ Add clarification on differences of new actions files.
+
+ Revision 1.99 2002/04/28 16:59:05 swa
+ more structure in starting section
+
Revision 1.98 2002/04/28 05:43:59 hal9
This is the break up of configuration.html into multiple files. This
will probably break links elsewhere :(
projects / privoxy.git / blobdiff