+ <listitem>
+ <para>
+ <emphasis>--version</emphasis>
+ </para>
+ <para>
+ Print version info and exit. Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--help</emphasis>
+ </para>
+ <para>
+ Print short usage info and exit. Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--no-daemon</emphasis>
+ </para>
+ <para>
+ Don't become a daemon, i.e. don't fork and become process group
+ leader, and don't detach from controlling tty. Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--pidfile FILE</emphasis>
+
+ </para>
+ <para>
+ On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
+ <emphasis>FILE</emphasis> on exit. 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>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--user USER[.GROUP]</emphasis>
+
+ </para>
+ <para>
+ After (optionally) writing the PID file, assume the user ID of
+ <emphasis>USER</emphasis>, and if included the GID of GROUP. Exit if the
+ privileges are not sufficient to do so. Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--chroot</emphasis>
+
+ </para>
+ <para>
+ Before changing to the user ID given in the <emphasis>--user</emphasis> option,
+ chroot to that user's home directory, i.e. make the kernel pretend to the Privoxy
+ process that the directory tree starts there. If set up carefully, this can limit
+ the impact of possible vulnerabilities in Privoxy to the files contained in that hierarchy.
+ Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>configfile</emphasis>
+ </para>
+ <para>
+ If no <emphasis>configfile</emphasis> is included on the command line,
+ <application>Privoxy</application> will look for a file named
+ <quote>config</quote> in the current directory (except on Win32
+ where it will look for <quote>config.txt</quote> instead). Specify
+ full path to avoid confusion. If no config file is found,
+ <application>Privoxy</application> will fail to start.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+</sect2>
+
+</sect1>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="configuration"><title><application>Privoxy</application> Configuration</title>
+ <para>
+ All <application>Privoxy</application> configuration is stored
+ in text files. These files can be edited with a text editor.
+ Many important aspects of <application>Privoxy</application> can
+ also be controlled easily with a web browser.
+ </para>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2>
+<title>Controlling <application>Privoxy</application> with Your Web Browser</title>
+<para>
+ <application>Privoxy</application>'s user interface can be reached through the special
+ URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
+ (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
+ which is a built-in page and works without Internet access.
+ You will see the following section:
+
+</para>
+
+<!-- Needs to be put in a table and colorized -->
+<screen>
+ <msgtext>
+ <bridgehead renderas="sect2"> Privoxy Menu</bridgehead>
+
+ <simplelist>
+ <member>
+ ▪ <ulink url="http://config.privoxy.org/show-status">View & change the current configuration</ulink>
+ </member>
+ <member>
+ ▪ <ulink url="http://config.privoxy.org/show-version">View the source code version numbers</ulink>
+ </member>
+ <member>
+ ▪ <ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
+ </member>
+ <member>
+ ▪ <ulink url="http://config.privoxy.org/show-url-info">Look up which actions apply to a URL and why</ulink>
+ </member>
+ <member>
+ ▪ <ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
+ </member>
+ <member>
+ ▪ <ulink url="http://www.privoxy.org/&p-version;/user-manual/">Documentation</ulink>
+ </member>
+ </simplelist>
+ </msgtext>
+</screen>
+
+
+<para>
+ This should be self-explanatory. Note the first item leads to an editor for the
+ <link linkend="actions-file">actions files</link>, which is where the ad, banner,
+ cookie, and URL blocking magic is configured as well as other advanced features of
+ <application>Privoxy</application>. This is an easy way to adjust various
+ aspects of <application>Privoxy</application> configuration. The actions
+ file, and other configuration files, are explained in detail below.
+</para>
+
+<para>
+ <quote>Toggle Privoxy On or Off</quote> is handy for sites that might
+ 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 manipulation is disabled, i.e.
+ <application>Privoxy</application> acts like a normal forwarding proxy. There
+ is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
+ that you can toggle <application>Privoxy</application> with one click from
+ your browser.
+</para>
+
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="confoverview">
+<title>Configuration Files Overview</title>
+<para>
+ For Unix, *BSD and Linux, all configuration files are located in
+ <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
+ AmigaOS these are all in the same directory as the
+ <application>Privoxy</application> executable. <![%p-not-stable;[ The name
+ and number of configuration files has changed from previous versions, and is
+ subject to change as development progresses.]]>
+</para>
+
+<para>
+ The installed defaults provide a reasonable starting point, though
+ some settings may be aggressive by some standards. For the time being, the
+ principle configuration files are:
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ 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>
+
+ <listitem>
+ <para>
+ <filename>default.action</filename> (the main <link linkend="actions-file">actions file</link>)
+ is used to define which <quote>actions</quote> relating to banner-blocking, images, pop-ups,
+ content modification, cookie handling etc should be applied by default. It also defines many
+ exceptions (both positive and negative) from this default set of actions that enable
+ <application>Privoxy</application> to selectively eliminate the junk, and only the junk, on
+ as many websites as possible.
+ </para>
+ <para>
+ Multiple actions files may be defined in <filename>config</filename>. These
+ are processed in the order they are defined. Local customizations and locally
+ preferred exceptions to the default policies as defined in
+ <filename>default.action</filename> (which you will most probably want
+ to define sooner or later) are probably best applied in
+ <filename>user.action</filename>, where you can preserve them across
+ upgrades. <filename>standard.action</filename> is for
+ <application>Privoxy's</application> internal use.
+ </para>
+ <para>
+ There is also a web based editor that can be accessed from
+ <ulink
+ url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
+ (Shortcut: <ulink
+ url="http://p.p/show-status">http://p.p/show-status</ulink>) for the
+ various actions files.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename>default.filter</filename> (the <link linkend="filter-file">filter
+ file</link>) can be used to re-write the raw page content, including
+ viewable text as well as embedded HTML and JavaScript, and whatever else
+ lurks on any given web page. The filtering jobs are only pre-defined here;
+ whether to apply them or not is up to the actions files. Only one filter
+ file may be defined.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+<para>
+ All files use the <quote><literal>#</literal></quote> character to denote a
+ comment (the rest of the line will be ignored) and understand line continuation
+ through placing a backslash ("<literal>\</literal>") as the very last character
+ in a line. If the <literal>#</literal> is preceded by a backslash, it looses
+ its special function. Placing a <literal>#</literal> in front of an otherwise
+ valid configuration line to prevent it from being interpreted is called "commenting
+ out" that line.
+</para>
+
+<para>
+ The actions files and <filename>default.filter</filename>
+ can use Perl style <link linkend="regex">regular expressions</link> for
+ maximum flexibility.
+</para>
+
+<para>
+ After making any changes, there is no need to restart
+ <application>Privoxy</application> in order for the changes to take
+ effect. <application>Privoxy</application> detects such changes
+ automatically. Note, however, that it may take one or two additional
+ requests for the change to take effect. When changing the listening address
+ of <application>Privoxy</application>, these <quote>wake up</quote> requests
+ must obviously be sent to the <emphasis>old</emphasis> listening address.
+</para>
+
+<![%p-not-stable;[
+<para>
+ While under development, the configuration content is subject to change.
+ The below documentation may not be accurate by the time you read this.
+ Also, what constitutes a <quote>default</quote> setting, may change, so
+ please check all your configuration files on important issues.
+</para>
+]]>
+
+</sect2>
+</sect1>
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+
+<!-- **************************************************** -->
+<!-- Include config.sgml here -->
+<!-- This is where the entire config file is detailed. -->
+ &config;
+<!-- end include -->
+
+
+<!-- ~ End section ~ -->
+
+
+
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+
+<sect1 id="actions-file"><title>Actions Files</title>
+
+<para>
+ The actions files are used to define what actions
+ <application>Privoxy</application> takes for which URLs, and thus determine
+ how ad images, cookies and various other aspects of HTTP content and
+ transactions are handled, and on which sites (or even parts thereof). There
+ are three such files included with <application>Privoxy</application>
+ with differing purposes:
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename>default.action</filename> - is the primary action file
+ that sets the initial values for all actions. It is intended to
+ provide a base level of functionality for
+ <application>Privoxy's</application> array of features. So it is
+ a set of broad rules that should work reasonably well for users everywhere.
+ This is the file that the developers are keeping updated, and <link
+ linkend="installation-keepupdated">making available to users</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>user.action</filename> - is intended to be for local site
+ preferences and exceptions. As an example, if your ISP or your bank
+ has specific requirements, and need special handling, this kind of
+ thing should go here. This file will not be upgraded.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>standard.action</filename> - is used by the web based editor,
+ to set various pre-defined sets of rules for the default actions section
+ in <filename>default.action</filename>. These have increasing levels of
+ aggressiveness <emphasis>and have no influence on your browsing unless
+ you select them explicitly in the editor</emphasis>. It is not recommend
+ to edit this file.
+ </para>
+ <para>
+ The default profiles, and their associated actions, as pre-defined in
+ <filename>standard.action</filename> are:
+ </para>
+ <para>
+ <table frame=all><title>Default Configurations</title>
+ <tgroup cols=4 align=left colsep=1 rowsep=1>
+ <colspec colname=c1>
+ <colspec colname=c2>
+ <colspec colname=c3>
+ <colspec colname=c4>
+ <thead>
+ <row>
+ <entry>Feature</entry>
+ <entry>Cautious</entry>
+ <entry>Medium</entry>
+ <entry>Adventuresome</entry>
+ </row>
+ </thead>
+ <!-- <tfoot> -->
+ <!-- <row> -->
+ <!-- <entry>f1</entry> -->
+ <!-- <entry>f2</entry> -->
+ <!-- <entry>f3</entry> -->
+ <!-- <entry>f4</entry> -->
+ <!-- </row> -->
+ <!-- </tfoot> -->
+ <tbody>
+
+ <row>
+ <entry>Ad-blocking by URL</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>Ad-filtering by size</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>GIF de-animation</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>Referer forging</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>Cookie handling</entry>
+ <entry>none</entry>
+ <entry>session-only</entry>
+ <entry>kill</entry>
+ </row>
+
+ <row>
+ <entry>Pop-up killing</entry>
+ <entry>unsolicited</entry>
+ <entry>unsolicited</entry>
+ <entry>all</entry>
+ </row>
+
+ <row>
+ <entry>Fast redirects</entry>
+ <entry>no</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>HTML taming</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>JavaScript taming</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>Web-bug killing</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>Fun text replacements</entry>
+ <entry>no</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>Image tag reordering</entry>
+ <entry>no</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>Ad-filtering by link</entry>
+ <entry>no</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ </row>
+
+ <row>
+ <entry>Demoronizer</entry>
+ <entry>no</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ </row>
+
+
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ </listitem>
+ </itemizedlist>
+ </para>
+
+<para>
+ The list of actions files to be used are defined in the main configuration
+ file, and are processed in the order they are defined (e.g.
+ <filename>default.action</filename> is typically process before
+ <filename>user.action</filename>). The content of these can all be viewed and
+ edited from <ulink
+ url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
+</para>
+
+<para>
+ An actions file typically has multiple sections. If you want to use
+ <quote>aliases</quote> in an actions file, you have to place the (optional)
+ <link linkend="aliases">alias section</link> at the top of that file.
+ Then comes the default set of rules which will apply universally to all
+ sites and pages (be <emphasis>very careful</emphasis> with using such a
+ universal set in <filename>user.action</filename> or any other actions file after
+ <filename>default.action</filename>, because it will override the result
+ from consulting any previous file). And then below that,
+ exceptions to the defined universal policies. You can regard
+ <filename>user.action</filename> as an appendix to <filename>default.action</filename>,
+ with the advantage that is a separate file, which makes preserving your
+ personal settings across <application>Privoxy</application> upgrades easier.
+</para>
+
+<para>
+ Actions can be used to block anything you want, including ads, banners, or
+ just some obnoxious URL that you would rather not see. Cookies can be accepted
+ or rejected, or accepted only during the current browser session (i.e. not
+ written to disk), content can be modified, JavaScripts tamed, user-tracking
+ fooled, and much more. See below for a <link linkend="actions">complete list
+ of actions</link>.
+</para>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2>
+<title>Finding the Right Mix</title>
+<para>
+ Note that some <link linkend="actions">actions</link>, like cookie suppression
+ or script disabling, may render some sites unusable that rely on these
+ techniques to work properly. Finding the right mix of actions is not always easy and
+ certainly a matter of personal taste. In general, it can be said that the more
+ <quote>aggressive</quote> your default settings (in the top section of the
+ actions file) are, the more exceptions for <quote>trusted</quote> sites you
+ will have to make later. If, for example, you want to crunch all cookies per
+ default, you'll have to make exceptions from that rule for sites that you
+ regularly use and that require cookies for actually useful puposes, like maybe
+ your bank, favorite shop, or newspaper.
+</para>
+
+<para>
+ We have tried to provide you with reasonable rules to start from in the
+ distribution actions files. But there is no general rule of thumb on these
+ things. There just are too many variables, and sites are constantly changing.
+ Sooner or later you will want to change the rules (and read this chapter again :).
+</para>
+</sect2>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2>
+<title>How to Edit</title>
+<para>
+ The easiest way to edit the actions files is with a browser by
+ using our browser-based editor, which can be reached from <ulink
+ url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
+ The editor allows both fine-grained control over every single feature on a
+ per-URL basis, and easy choosing from wholesale sets of defaults like
+ <quote>Cautious</quote>, <quote>Medium</quote> or <quote>Adventuresome</quote>.
+ Warning: the <quote>Adventuresome</quote> setting is not only more aggressive,
+ but includes settings that are fun and subversive, and which some may find of
+ dubious merit!
+</para>
+
+<para>
+ If you prefer plain text editing to GUIs, you can of course also directly edit the
+ the actions files. Look at <filename>default.action</filename> which is richly
+ commented.
+</para>
+</sect2>
+
+
+<sect2 id="actions-apply">
+<title>How Actions are Applied to URLs</title>
+<para>
+ Actions files are divided into sections. There are special sections,
+ like the <quote><link linkend="aliases">alias</link></quote> sections which will
+ be discussed later. For now let's concentrate on regular sections: They have a
+ heading line (often split up to multiple lines for readability) which consist
+ of a list of actions, separated by whitespace and enclosed in curly braces.
+ Below that, there is a list of URL patterns, each on a separate line.
+</para>
+
+<para>
+ To determine which actions apply to a request, the URL of the request is
+ compared to all patterns in each <quote>action file</quote> file. Every time it matches, the list of
+ applicable actions for the URL is incrementally updated, using the heading
+ of the section in which the pattern is located. If multiple matches for
+ the same URL set the same action differently, the last match wins. If not,
+ the effects are aggregated. E.g. a URL might match a regular section with
+ a heading line of <literal>{
+ +<link linkend="handle-as-image">handle-as-image</link> }</literal>,
+ then later another one with just <literal>{
+ +<link linkend="block">block</link> }</literal>, resulting
+ in <emphasis>both</emphasis> actions to apply.
+</para>
+
+<para>
+ You can trace this process for any given URL by visiting <ulink
+ url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
+</para>
+
+<para>
+ More detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
+ Anatomy of an Action</link>.
+</para>
+</sect2>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="af-patterns">
+<title>Patterns</title>
+<para>
+ As mentioned, <application>Privoxy</application> uses <quote>patterns</quote>
+ to determine what actions might apply to which sites and pages your browser
+ attempts to access. These <quote>patterns</quote> use wild card type
+ <emphasis>pattern</emphasis> matching to achieve a high degree of
+ flexibility. This allows one expression to be expanded and potentially match
+ against many similar patterns.
+</para>
+
+<para>
+ Generally, a <application>Privoxy</application> pattern has the form
+ <literal><domain>/<path></literal>, where both the
+ <literal><domain></literal> and <literal><path></literal> are
+ optional. (This is why the special <literal>/</literal> pattern matches all
+ URLs). Note that the protocol portion of the URL pattern (e.g.
+ <literal>http://</literal>) should <emphasis>not</emphasis> be included in
+ the pattern. This is assumed already!
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><literal>www.example.com/</literal></term>
+ <listitem>
+ <para>
+ is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
+ regardless of which document on that server is requested.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>www.example.com</literal></term>
+ <listitem>
+ <para>
+ means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
+ be omitted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>www.example.com/index.html</literal></term>
+ <listitem>
+ <para>
+ matches only the single document <literal>/index.html</literal>
+ on <literal>www.example.com</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>/index.html</literal></term>
+ <listitem>
+ <para>
+ matches the document <literal>/index.html</literal>, regardless of the domain,
+ i.e. on <emphasis>any</emphasis> web server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>index.html</literal></term>
+ <listitem>
+ <para>
+ matches nothing, since it would be interpreted as a domain name and
+ there is no top-level domain called <literal>.html</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3><title>The Domain Pattern</title>
+
+<para>
+ The matching of the domain part offers some flexible options: if the
+ domain starts or ends with a dot, it becomes unanchored at that end.
+ For example:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><literal>.example.com</literal></term>
+ <listitem>
+ <para>
+ matches any domain that <emphasis>ENDS</emphasis> in
+ <literal>.example.com</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>www.</literal></term>
+ <listitem>
+ <para>
+ matches any domain that <emphasis>STARTS</emphasis> with
+ <literal>www.</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>.example.</literal></term>
+ <listitem>
+ <para>
+ matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>
+ (Correctly speaking: It matches any FQDN that contains <literal>example</literal> as a domain.)
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+ Additionally, there are wild-cards that you can use in the domain names
+ themselves. They work pretty similar to shell wild-cards: <quote>*</quote>
+ stands for zero or more arbitrary characters, <quote>?</quote> stands for
+ any single character, you can define character classes in square
+ brackets and all of that can be freely mixed:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><literal>ad*.example.com</literal></term>
+ <listitem>
+ <para>
+ matches <quote>adserver.example.com</quote>,
+ <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>*ad*.example.com</literal></term>
+ <listitem>
+ <para>
+ matches all of the above, and then some.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>.?pix.com</literal></term>
+ <listitem>
+ <para>
+ matches <literal>www.ipix.com</literal>,
+ <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>www[1-9a-ez].example.c*</literal></term>
+ <listitem>
+ <para>
+ matches <literal>www1.example.com</literal>,
+ <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>,
+ <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis>
+ <literal>wwww.example.com</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect3>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3><title>The Path Pattern</title>
+
+<para>
+ <application>Privoxy</application> uses Perl compatible regular expressions
+ (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
+ matching the path.
+</para>
+
+<para>
+ There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
+ expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
+ at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
+ You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
+ useful, which is available on-line at <ulink
+ url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>.
+</para>
+
+<para>
+ Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
+ i.e. it matches as if it would start with a <quote>^</quote> (regular expression speak
+ for the beginning of a line).
+</para>
+
+<para>
+ Please also note that matching in the path is <emphasis>CASE INSENSITIVE</emphasis>
+ by default, but you can switch to case sensitive at any point in the pattern by using the
+ <quote>(?-i)</quote> switch: <literal>www.example.com/(?-i)PaTtErN.*</literal> will match
+ only documents whose path starts with <literal>PaTtErN</literal> in
+ <emphasis>exactly</emphasis> this capitalization.
+</para>
+</sect3>
+
+</sect2>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="actions">
+<title>Actions</title>
+<para>
+ All actions are disabled by default, until they are explicitly enabled
+ somewhere in an actions file. Actions are turned on if preceded with a
+ <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
+ <literal>+action</literal> means <quote>do that action</quote>, e.g.
+ <literal>+block</literal> means <quote>please block URLs that match the
+ following patterns</quote>, and <literal>-block</literal> means <quote>don't
+ block URLs that match the following patterns, even if <literal>+block</literal>
+ previously applied.</quote>
+
+</para>
+
+<para>
+ Again, actions are invoked by placing them on a line, enclosed in curly braces and
+ separated by whitespace, like in
+ <literal>{+some-action -some-other-action{some-parameter}}</literal>,
+ followed by a list of URL patterns, one per line, to which they apply.
+ Together, the actions line and the following pattern lines make up a section
+ of the actions file.
+</para>
+
+<para>
+ There are three classes of actions:
+</para>
+
+<para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Boolean, i.e the action can only be <quote>enabled</quote> or
+ <quote>disabled</quote>. Syntax:
+ </para>
+ <para>
+ <screen>
+ +<replaceable class="function">name</replaceable> # enable action <replaceable class="parameter">name</replaceable>
+ -<replaceable class="function">name</replaceable> # disable action <replaceable class="parameter">name</replaceable></screen>
+ </para>
+ <para>
+ Example: <literal>+block</literal>
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ Parameterized, where some value is required in order to enable this type of action.
+ Syntax:
+ </para>
+ <para>
+ <screen>
+ +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and set parameter to <replaceable class="parameter">param</replaceable>,
+ # overwriting parameter from previous match if necessary
+ -<replaceable class="function">name</replaceable> # disable action. The parameter can be omitted</screen>
+ </para>
+ <para>
+ Note that if the URL matches multiple positive forms of a parameterized action,
+ the last match wins, i.e. the params from earlier matches are simply ignored.
+ </para>
+ <para>
+ Example: <literal>+hide-user-agent{ Mozilla 1.0 }</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Multi-value. These look exactly like parameterized actions,
+ but they behave differently: If the action applies multiple times to the
+ same URL, but with different parameters, <emphasis>all</emphasis> the parameters
+ from <emphasis>all</emphasis> matches are remembered. This is used for actions
+ that can be executed for the same request repeatedly, like adding multiple
+ headers, or filtering through multiple filters. Syntax:
+ </para>
+ <para>
+ <screen>
+ +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and add <replaceable class="parameter">param</replaceable> to the list of parameters
+ -<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # remove the parameter <replaceable class="parameter">param</replaceable> from the list of parameters
+ # If it was the last one left, disable the action.
+ <replaceable class="parameter">-name</replaceable> # disable this action completely and remove all parameters from the list</screen>
+ </para>
+ <para>
+ Examples: <literal>+add-header{X-Fun-Header: Some text}</literal> and
+ <literal>+filter{html-annoyances}</literal>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+<para>
+ If nothing is specified in any actions file, no <quote>actions</quote> are
+ taken. So in this case <application>Privoxy</application> would just be a
+ normal, non-blocking, non-anonymizing proxy. You must specifically enable the
+ privacy and blocking features you need (although the provided default actions
+ files will give a good starting point).
+</para>
+
+<para>
+ Later defined actions always over-ride earlier ones. So exceptions
+ to any rules you make, should come in the latter part of the file (or
+ in a file that is processed later when using multiple actions files). For
+ multi-valued actions, the actions are applied in the order they are specified.
+ Actions files are processed in the order they are defined in
+ <filename>config</filename> (the default installation has three actions
+ files). It also quite possible for any given URL pattern to match more than
+ one pattern and thus more than one set of actions!
+</para>
+
+<!-- start actions listing -->
+<para>
+ The list of valid <application>Privoxy</application> actions are:
+</para>
+
+
+<!-- ********************************************************** -->
+<!-- Please note the below defined actions use id's that are -->
+<!-- probably linked from other places, so please don't change. -->
+<!-- -->
+<!-- ********************************************************** -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="add-header">
+<title>add-header</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Confuse log analysis, custom applications</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Sends a user defined HTTP header to the web server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Multi-value.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ Any string value is possible. Validity of the defined HTTP headers is not checked.
+ It is recommended that you use the <quote><literal>X-</literal></quote> prefix
+ for custom headers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+<varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action may be specified multiple times, in order to define multiple
+ headers. This is rarely needed for the typical user. If you don't know what
+ <quote>HTTP headers</quote> are, you definitely don't need to worry about this
+ one.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+add-header{X-User-Tracking: sucks}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="block">
+<title>block</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Block ads or other obnoxious content</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Requests for URLs to which this action applies are blocked, i.e. the requests are not
+ forwarded to the remote server, but answered locally with a substitute page or image,
+ as determined by the <literal><link linkend="handle-as-image">handle-as-image</link></literal>
+ and <literal><link linkend="set-image-blocker">set-image-blocker</link></literal> actions.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>N/A</para>
+ </listitem>
+ </varlistentry>
+
+<varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ <application>Privoxy</application> sends a special <quote>BLOCKED</quote> page
+ for requests to blocked pages. This page contains links to find out why the request
+ was blocked, and a click-through to the blocked content (the latter only if compiled with the
+ force feature enabled). The <quote>BLOCKED</quote> page adapts to the available
+ screen space -- it displays full-blown if space allows, or miniaturized and text-only
+ if loaded into a small frame or window. If you are using <application>Privoxy</application>
+ right now, you can take a look at the
+ <ulink url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
+ page</ulink>.
+ </para>
+ <para>
+ A very important exception occurs if <emphasis>both</emphasis>
+ <literal>block</literal> and <literal><link linkend="handle-as-image">handle-as-image</link></literal>,
+ apply to the same request: it will then be replaced by an image. If
+ <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
+ (see below) also applies, the type of image will be determined by its parameter,
+ if not, the standard checkerboard pattern is sent.
+ </para>
+ <para>
+ It is important to understand this process, in order
+ to understand how <application>Privoxy</application> deals with
+ ads and other unwanted content.
+ </para>
+ <para>
+ The <literal><link linkend="filter">filter</link></literal>
+ action can perform a very similar task, by <quote>blocking</quote>
+ banner images and other content through rewriting the relevant URLs in the
+ document's HTML source, so they don't get requested in the first place.
+ Note that this is a totally different technique, and it's easy to confuse the two.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>{+block} # Block and replace with "blocked" page
+.nasty-stuff.example.com
+
+{+block +handle-as-image} # Block and replace with image
+.ad.doubleclick.net
+.ads.r.us</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="content-type-overwrite">
+<title>content-type-overwrite</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Stop useless download menus from popping up, or change the browser's rendering mode</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Replaces the <quote>Content-Type:</quote> HTTP server header.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ Any string.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The <quote>Content-Type:</quote> HTTP server header is used by the
+ browser to decide what to do with the document. The value of this
+ header can cause the browser to open a download menu instead of
+ displaying the document by itself, even if the document's format is
+ supported by the browser.
+ </para>
+ <para>
+ The declared content type can also affect which rendering mode
+ the browser chooses. If XHTML is delivered as <quote>text/html</quote>,
+ many browsers treat it as yet another broken HTML document.
+ If it is send as <quote>application/xml</quote>, browsers with
+ XHTML support will only display it, if the syntax is correct.
+ </para>
+ <para>
+ If you see a web site that proudly uses XHTML buttons, but sets
+ <quote>Content-Type: text/html</quote>, you can use Privoxy
+ to overwrite it with <quote>application/xml</quote> and validate
+ the web master's claim inside your XHTML-supporting browser.
+ If the syntax is incorrect, the browser will complain loudly.
+ </para>
+ <para>
+ You can also go the opposite direction: if your browser prints
+ error messages instead of rendering a document falsely declared
+ as XHTML, you can overwrite the content type with
+ <quote>text/html</quote> and have it rendered as broken HTML document.
+ </para>
+ <para>
+ By default <literal>content-type-overwrite</literal> only replaces
+ <quote>Content-Type:</quote> headers that look like some kind of text.
+ If you want to overwrite it unconditionally, you have to combine it with
+ <literal><link linkend="force-text-mode">force-text-mode</link></literal>.
+ This limitation exists for a reason, think twice before circumventing it.
+ </para>
+ <para>
+ Most of the time it's easier to enable
+ <literal><link linkend="filter-server-headers">filter-server-headers</link></literal>
+ and replace this action with a custom regular expression. It allows you
+ to activate it for every document of a certain site and it will still
+ only replace the content types you aimed at.
+ </para>
+ <para>
+ Of course you can apply <literal>content-type-overwrite</literal>
+ to a whole site and then make URL based exceptions, but it's a lot
+ more work to get the same precision.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (sections):</term>
+ <listitem>
+ <para>
+ <screen># Check if www.example.net/ really uses valid XHTML
+{+content-type-overwrite {application/xml}}
+www.example.net/
+# but leave the content type unmodified if the URL looks like a style sheet
+{-content-type-overwrite}
+www.example.net/*.\.css$
+www.example.net/*.style
+</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-client-header">
+<title>crunch-server-header</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Remove a client header <application>Privoxy</application> has no dedicated action for.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes every header send by the client that contains the string the user supplied as parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ Any string.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action allows you to block client headers for which no dedicated
+ <application>Privoxy</application> action exists.
+ <application>Privoxy</application> will remove every client header that
+ contains the string you supplied as parameter.
+ </para>
+ <para>
+ Regular expressions are <emphasis>not supported</emphasis> and you can't
+ use this action to block different headers in the same request, unless
+ they contain the same string.
+ </para>
+ <para>
+ <literal>crunch-client-header</literal> is only meant for quick tests.
+ If you have to block several different headers, or only want to modify
+ parts of them, you should enable
+ <literal><link linkend="filter-client-headers">filter-client-headers</link></literal>
+ and create your own filter.
+ </para>
+ <para>
+ <warning>
+ Don't block any header without understanding the consequences.
+ </warning>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen># Block the non-existent "Privacy-Violation:" client header
+{+crunch-client-header {Privacy-Violation:}}
+/
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-if-none-match">
+<title>crunch-if-none-match</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Prevent yet another way to track the user's steps between sessions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes the <quote>If-None-Match:</quote> HTTP client header.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Removing the <quote>If-None-Match:</quote> HTTP client header
+ is useful for filter testing, where you want to force a real
+ reload instead of getting status code <quote>304</quote> which
+ would cause the browser to use a cached copy of the page.
+ </para>
+ <para>
+ It is also useful to make sure the header isn't used as a cookie
+ replacement.
+ </para>
+ <para>
+ Blocking the <quote>If-None-Match:</quote> header shouldn't cause any
+ caching problems, as long as the <quote>If-Modified-Since:</quote> header
+ isn't blocked as well.
+ </para>
+ <para>
+ It is recommended to use this action together with
+ <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
+ and
+ <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen># Let the browser revalidate cached documents without being tracked across sessions
+{+hide-if-modified-since {-1} \
++overwrite-last-modified {randomize} \
++crunch-if-none-match}
+/ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-incoming-cookies">
+<title>crunch-incoming-cookies</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Prevent the web server from setting any cookies on your system
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes any <quote>Set-Cookie:</quote> HTTP headers from server replies.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action is only concerned with <emphasis>incoming</emphasis> cookies. For
+ <emphasis>outgoing</emphasis> cookies, use
+ <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>.
+ Use <emphasis>both</emphasis> to disable cookies completely.
+ </para>
+ <para>
+ It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
+ with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
+ since it would prevent the session cookies from being set. See also
+ <literal><link linkend="filter-content-cookies">filter-content-cookies</link></literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+crunch-incoming-cookies</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-server-header">
+<title>crunch-server-header</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Remove a server header <application>Privoxy</application> has no dedicated action for.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes every header send by the server that contains the string the user supplied as parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ Any string.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action allows you to block server headers for which no dedicated
+ <application>Privoxy</application> action exists. <application>Privoxy</application>
+ will remove every server header that contains the string you supplied as parameter.
+ </para>
+ <para>
+ Regular expressions are <emphasis>not supported</emphasis> and you can't
+ use this action to block different headers in the same request, unless
+ they contain the same string.
+ </para>
+ <para>
+ <literal>crunch-server-header</literal> is only meant for quick tests.
+ If you have to block several different headers, or only want to modify
+ parts of them, you should enable
+ <literal><link linkend="filter-server-headers">filter-server-headers</link></literal>
+ and create your own filter.
+ </para>
+ <para>
+ <warning>
+ Don't block any header without understanding the consequences.
+ </warning>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen># Crunch server headers that try to prevent caching
+{+crunch-server-header {no-cache}}
+/ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-outgoing-cookies">
+<title>crunch-outgoing-cookies</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>
+ Prevent the web server from reading any cookies from your system
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Deletes any <quote>Cookie:</quote> HTTP headers from client requests.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action is only concerned with <emphasis>outgoing</emphasis> cookies. For
+ <emphasis>incoming</emphasis> cookies, use
+ <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>.
+ Use <emphasis>both</emphasis> to disable cookies completely.
+ </para>
+ <para>
+ It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
+ with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
+ since it would prevent the session cookies from being read.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+crunch-outgoing-cookies</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="deanimate-gifs">
+<title>deanimate-gifs</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Stop those annoying, distracting animated GIF images.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ De-animate GIF animations, i.e. reduce them to their first or last image.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ <quote>last</quote> or <quote>first</quote>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This will also shrink the images considerably (in bytes, not pixels!). If
+ the option <quote>first</quote> is given, the first frame of the animation
+ is used as the replacement. If <quote>last</quote> is given, the last
+ frame of the animation is used instead, which probably makes more sense for
+ most banner animations, but also has the risk of not showing the entire
+ last frame (if it is only a delta to an earlier frame).
+ </para>
+ <para>
+ You can safely use this action with patterns that will also match non-GIF
+ objects, because no attempt will be made at anything that doesn't look like
+ a GIF.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+deanimate-gifs{last}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="downgrade-http-version">
+<title>downgrade-http-version</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Work around (very rare) problems with HTTP/1.1</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+<varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This is a left-over from the time when <application>Privoxy</application>
+ didn't support important HTTP/1.1 features well. It is left here for the
+ unlikely case that you experience HTTP/1.1 related problems with some server
+ out there. Not all (optional) HTTP/1.1 features are supported yet, so there
+ is a chance you might need this action.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <para>
+ <screen>{+downgrade-http-version}
+problem-host.example.com</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="fast-redirects">
+<title>fast-redirects</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Fool some click-tracking scripts and speed up indirect links.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Detects redirection URLs and redirects the browser without contacting
+ the redirection server first.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <quote>simple-check</quote> to just search for the string <quote>http://</quote>
+ to detect redirection URLs.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <quote>check-decoded-url</quote> to decode URLs (if necessary) before searching
+ for redirection URLs.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Many sites, like yahoo.com, don't just link to other sites. Instead, they
+ will link to some script on their own servers, giving the destination as a
+ parameter, which will then redirect you to the final target. URLs
+ resulting from this scheme typically look like:
+ <quote>http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/</quote>.
+ </para>
+ <para>
+ Sometimes, there are even multiple consecutive redirects encoded in the
+ URL. These redirections via scripts make your web browsing more traceable,
+ since the server from which you follow such a link can see where you go
+ to. Apart from that, valuable bandwidth and time is wasted, while your
+ browser asks the server for one redirect after the other. Plus, it feeds
+ the advertisers.
+ </para>
+ <para>
+ This feature is currently not very smart and is scheduled for improvement.
+ If it is enabled by default, you will have to create some exceptions to
+ this action. It can lead to failures in several ways:
+ </para>
+ <para>
+ Not every URLs with other URLs as parameters is evil.
+ Some sites offer a real service that requires this information to work.
+ For example a validation service needs to know, which document to validate.
+ <literal>fast-redirects</literal> assumes that every URL parameter that
+ looks like another URL is a redirection target, and will always redirect to
+ the last one. Most of the time the assumption is correct, but if it isn't,
+ the user gets redirected anyway.
+ </para>
+ <para>
+ Another failure occurs if the URL contains other parameters after the URL parameter.
+ The URL:
+ <quote>http://www.example.org/?redirect=http%3a//www.example.net/&foo=bar</quote>.
+ contains the redirection URL <quote>http://www.example.net/</quote>,
+ followed by another parameter. <literal>fast-redirects</literal> doesn't know that
+ and will cause a redirect to <quote>http://www.example.net/&foo=bar</quote>.
+ Depending on the target server configuration, the parameter will be silently ignored
+ or lead to a <quote>page not found</quote> error. It is possible to fix these redirected
+ requests with <literal><link linkend="filter-client-headers">filter-client-headers</link></literal>
+ but it requires a little effort.
+ </para>
+ <para>
+ To detect a redirection URL, <literal>fast-redirects</literal> only
+ looks for the string <quote>http://</quote>, either in plain text
+ (invalid but often used) or encoded as <quote>http%3a//</quote>.
+ Some sites use their own URL encoding scheme, encrypt the address
+ of the target server or replace it with a database id. In theses cases
+ <literal>fast-redirects</literal> is fooled and the request reaches the
+ redirection server where it probably gets logged.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+fast-redirects{simple-check}</screen>
+ </para>
+ <para>
+ <screen>+fast-redirects{check-decoded-url}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="filter">
+<title>filter</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Get rid of HTML and JavaScript annoyances, banner advertisements (by size), do fun text replacements, etc.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ All files of text-based type, most notably HTML and JavaScript, to which this
+ action applies, are filtered on-the-fly through the specified regular expression
+ based substitutions. (Note: as of version 3.0.3 plain text documents
+ are exempted from filtering, because web servers often use the
+ <literal>text/plain</literal> MIME type for all files whose type they
+ don't know.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ The name of a filter, as defined in the <link linkend="filter-file">filter file</link>
+ (typically <filename>default.filter</filename>, set by the
+ <literal><link linkend="filterfile">filterfile</link></literal>
+ option in the <link linkend="config">config file</link>). When used in its negative form,
+ and without parameters, filtering is completely disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ For your convenience, there are a number of pre-defined filters available
+ in the distribution filter file that you can use. See the examples below for
+ a list.
+ </para>
+ <para>
+ Filtering requires buffering the page content, which may appear to
+ slow down page rendering since nothing is displayed until all content has
+ passed the filters. (It does not really take longer, but seems that way
+ since the page is not incrementally displayed.) This effect will be more
+ noticeable on slower connections.
+ </para>
+ <para>
+ This is very powerful feature, but <quote>rolling your own</quote>
+ filters requires a knowledge of regular expressions and HTML.
+ </para>
+ <para>
+ The amount of data that can be filtered is limited to the
+ <literal><link linkend="buffer-limit">buffer-limit</link></literal>
+ option in the main <link linkend="config">config file</link>. The
+ default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered
+ data, and all pending data, is passed through unfiltered.
+ </para>
+ <para>
+ Inadequate MIME types, such as zipped files, are not filtered at all.
+ (Again, only text-based types except plain text). Encrypted SSL data
+ (from HTTPS servers) cannot be filtered either, since this would violate
+ the integrity of the secure transaction. In some situations it might
+ be necessary to protect certain text, like source code, from filtering
+ by defining appropriate <literal>-filter</literal> sections.
+ </para>
+ <para>
+ At this time, <application>Privoxy</application> cannot (yet!) uncompress compressed
+ documents. If you want filtering to work on all documents, even those that
+ would normally be sent compressed, use the
+ <literal><link linkend="prevent-compression">prevent-compression</link></literal>
+ action in conjunction with <literal>filter</literal>.
+ </para>
+ <para>
+ Filtering can achieve some of the same effects as the
+ <literal><link linkend="block">block</link></literal>
+ action, i.e. it can be used to block ads and banners. But the mechanism
+ works quite differently. One effective use, is to block ad banners
+ based on their size (see below), since many of these seem to be somewhat
+ standardized.
+ </para>
+ <para>
+ <link linkend="contact">Feedback</link> with suggestions for new or
+ improved filters is particularly welcome!
+ </para>
+ <para>
+ The below list has only the names and a one-line description of each
+ predefined filter. There are <link linkend="predefined-filters">more
+ verbose explanations</link> of what these filters do in the <link
+ linkend="filter-file">filter file chapter</link>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (with filters from the distribution <filename>default.filter</filename> file).
+ See <link linkend="PREDEFINED-FILTERS">the Predefined Filters section</link> for
+ more explanation on each:</term>
+ <listitem>
+ <para>
+ <anchor id="filter-js-annoyances">
+ <screen>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse</screen>
+ </para>
+ <para>
+ <anchor id="filter-js-events">
+ <screen>+filter{js-events} # Kill all JS event bindings (Radically destructive! Only for extra nasty sites)</screen>
+ </para>
+ <para>
+ <anchor id="filter-html-annoyances">
+ <screen>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse</screen>
+ </para>
+ <para>
+ <anchor id="filter-content-cookies">
+ <screen>+filter{content-cookies} # Kill cookies that come in the HTML or JS content</screen>
+ </para>
+ <para>
+ <anchor id="filter-refresh-tags">
+ <screen>+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups)</screen>
+ </para>
+ <para>
+ <anchor id="filter-unsolicited-popups">
+ <screen>+filter{unsolicited-popups} # Disable only unsolicited pop-up windows</screen>
+ </para>
+ <para>
+ <anchor id="filter-all-popups">
+ <screen>+filter{all-popups} # Kill all popups in JavaScript and HTML</screen>
+ </para>
+ <para>
+ <anchor id="filter-img-reorder">
+ <screen>+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective</screen>
+ </para>
+ <para>
+ <anchor id="filter-banners-by-size">
+ <screen>+filter{banners-by-size} # Kill banners by size</screen>
+ </para>
+ <para>
+ <anchor id="filter-banners-by-link">
+ <screen>+filter{banners-by-link} # Kill banners by their links to known clicktrackers</screen>
+ </para>
+ <para>
+ <anchor id="filter-webbugs">
+ <screen>+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking)</screen>
+ </para>
+ <para>
+ <anchor id="filter-tiny-textforms">
+ <screen>+filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap</screen>
+ </para>
+ <para>
+ <anchor id="filter-jumping-windows">
+ <screen>+filter{jumping-windows} # Prevent windows from resizing and moving themselves</screen>
+ </para>
+ <para>
+ <anchor id="filter-frameset-borders">
+ <screen>+filter{frameset-borders} # Give frames a border and make them resizable</screen>
+ </para>
+ <para>
+ <anchor id="filter-demoronizer">
+ <screen>+filter{demoronizer} # Fix MS's non-standard use of standard charsets</screen>
+ </para>
+ <para>
+ <anchor id="filter-shockwave-flash">
+ <screen>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects</screen>
+ </para>
+ <para>
+ <anchor id="filter-quicktime-kioskmode">
+ <screen>+filter{quicktime-kioskmode} # Make Quicktime movies saveable</screen>
+ </para>
+ <para>
+ <anchor id="filter-fun">
+ <screen>+filter{fun} # Text replacements for subversive browsing fun!</screen>
+ </para>
+ <para>
+ <anchor id="filter-crude-parental">
+ <screen>+filter{crude-parental} # Crude parental filtering (demo only)</screen>
+ </para>
+ <para>
+ <anchor id="filter-ie-exploits">
+ <screen>+filter{ie-exploits} # Disable some known Internet Explorer bug exploits</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="force-text-mode">
+<title>force-text-mode</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Force <application>Privoxy</application> to treat a document as if it was in some kind of text format.</emphasis></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Declares a document as text, even if the <quote>Content-Type:</quote> isn't detected as such.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ As explained <literal><link linkend="filter">above</link></literal>,
+ <application>Privoxy</application> tries to only filter files that are
+ in some kind of text format. The same restrictions apply to
+ <literal><link linkend="content-type-overwrite">content-type-overwrite</link></literal>.
+ <literal>force-text-mode</literal> declares a document as text,
+ without looking at the <quote>Content-Type:</quote> first.
+ </para>
+ <warning>
+ <para>
+ Think twice before activating this action. Filtering binary data
+ with regular expressions can cause file damages.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>
++force-text-mode
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="handle-as-empty-document">
+<title>handle-as-empty-document</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Mark URLs that should be replaced by empty documents <emphasis>if they get blocked</emphasis></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>