This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 1.108 2002/05/14 15:29:12 oes Exp $
+ $Id: user-manual.sgml,v 1.110 2002/05/14 19:10:45 oes Exp $
Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
See LICENSE.
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 1.108 2002/05/14 15:29:12 oes Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.110 2002/05/14 19:10:45 oes Exp $</pubdate>
<!--
</sect2>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
+<sect2 id="af-patterns">
<title>Patterns</title>
<para>
Generally, a pattern has the form <literal><domain>/<path></literal>,
</variablelist>
</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="crunch-incoming-cookies">
+<title><emphasis>crunch-incoming-cookies</emphasis></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.
+ </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-outgoing-cookies">
+<title><emphasis>crunch-outgoing-cookies</emphasis></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">
<term>Notes:</term>
<listitem>
<para>
- Warning! This breaks many web sites that depend on this in order
- to customize their content for the different browser types by looking
- at this header (which, btw, is <emphasis>NOT</emphasis> a smart way to
- do that!).
+ Warning! This breaks many web sites that in order to customize their
+ content for the different browser types depend on looking
+ at this header (which, btw, is <emphasis>NOT</emphasis> a <ulink
+ url="http://www.javascriptkit.com/javaindex.shtml">smart way to
+ do that</ulink>!).
</para>
<para>
Using this action in multi-user setups or wherever diffrerent types of
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="crunch-outgoing-cookies">
-<title><emphasis>crunch-outgoing-cookies</emphasis></title>
+<sect3 renderas="sect4" id="send-vanilla-wafer">
+<title><emphasis>send-vanilla-wafer</emphasis></title>
<variablelist>
<varlistentry>
<term>Typical use:</term>
<listitem>
<para>
- Prevent the web server from reading any cookies from your system
+ Feed log analysis scripts with useless data.
</para>
</listitem>
</varlistentry>
<term>Effect:</term>
<listitem>
<para>
- Deletes any <quote>Cookie:</quote> HTTP headers from client requests.
+ Sends a cookie with each request stating that you do not accept any copyright
+ on cookies sent to you, and asking the site operator not to track you.
</para>
</listitem>
</varlistentry>
<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.
+ The vanilla wafer is a (relatively) unique header and could conceivably be used to track you.
</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.
+ This action is rarely used and not enabled in the default configuration.
</para>
</listitem>
</varlistentry>
<term>Example usage:</term>
<listitem>
<para>
- <screen>+crunch-outgoing-cookies</screen>
+ <screen>+send-vanilla-wafer</screen>
</para>
</listitem>
</varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="crunch-incoming-cookies">
-<title><emphasis>crunch-incoming-cookies</emphasis></title>
+<sect3 renderas="sect4" id="send-wafer">
+<title><emphasis>send-wafer</emphasis></title>
<variablelist>
<varlistentry>
<term>Typical use:</term>
<listitem>
<para>
- Prevent the web server from setting any cookies on your system
+ Send custom cookies or feed log analysis scripts with even more useless data.
</para>
</listitem>
</varlistentry>
<term>Effect:</term>
<listitem>
<para>
- Deletes any <quote>Set-Cookie:</quote> HTTP headers from server replies.
+ Sends a custom, user-defined cookie with each request.
</para>
</listitem>
</varlistentry>
<term>Type:</term>
<!-- Boolean, Parameterized, Multi-value -->
<listitem>
- <para>Boolean.</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
<term>Parameter:</term>
<listitem>
<para>
- N/A
+ A string of the form <quote><replaceable class="option">name</replaceable>=<replaceable
+ class="parameter">value</replaceable></quote>.
</para>
</listitem>
</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.
+ Being multi-valued, multiple instances of this action can apply to the same request,
+ resulting in multiple cookies being sent.
</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.
+ This action is rarely used and not enabled in the default configuration.
</para>
</listitem>
</varlistentry>
-
<varlistentry>
- <term>Example usage:</term>
+ <term>Example usage (section):</term>
<listitem>
<para>
- <screen>+crunch-incoming-cookies</screen>
+ <screen>{+send-wafer{UsingPrivoxy=true}}
+my-internal-testing-server.void</screen>
</para>
</listitem>
</varlistentry>
</sect3>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="send-vanilla-wafer">
-<title><emphasis>send-vanilla-wafer</emphasis></title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>
- Feed log analysis scripts with useless data.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Sends a cookie with each request stating that you do not accept any copyright
- on cookies sent to you, and asking the site operator not to track you.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Boolean.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- N/A
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- The vanilla wafer is a (relatively) unique header and could conceivably be used to track you.
- </para>
- <para>
- This action is rarely used and not enabled in the default configuration.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>+send-vanilla-wafer</screen>
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="send-wafer">
-<title><emphasis>send-wafer</emphasis></title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>
- Send custom cookies or feed log analysis scripts with even more useless data.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Sends a custom, user-defined cookie with each request.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Multi-value.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- A string of the form <quote><replaceable class="option">name</replaceable>=<replaceable
- class="parameter">value</replaceable></quote>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Being multi-valued, multiple instances of this action can apply to the same request,
- resulting in multiple cookies being sent.
- </para>
- <para>
- This action is rarely used and not enabled in the default configuration.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Example usage (section):</term>
- <listitem>
- <para>
- <screen>{+send-wafer{UsingPrivoxy=true}}
-my-internal-testing-server.void</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="set-image-blocker">
<title><emphasis>set-image-blocker</emphasis></title>
There are two main reasons to use aliases: One is to save typing for frequently
used combinations of actions, the other one is a gain in flexibility: If you
decide once how you want to handle shops by defining an alias called
- <quote>shop</quote>, you can later chenge your policy on shops in
+ <quote>shop</quote>, you can later change your policy on shops in
<emphasis>one</emphasis> place, and your changes will take effect everywhere
in the actions file where the <quote>shop</quote> alias is used. Calling aliases
by their purpose also makes your actions files more readable.
<application>Privoxy</application>'s built-in web-based action file
editor honors aliases when reading the actions files, but it expands
them before writing. So the effects of your aliases are of course preserved,
- but the aliases themselves are lost when you edit the files this way.
+ but the aliases themselves are lost when you edit sections that use aliases
+ with it.
This is likely to change in future versions of <application>Privoxy</application>.
</para>
<sect2 id="act-examples">
<title>Sample Actions Files</title>
<para>
- Remember that the meaning of any of the above references is reversed by preceding
+ Remember that the meaning of each action is reversed by preceding
the action with a <quote>-</quote>, in place of the <quote>+</quote>. Also,
that some actions are turned on in the default section of the actions file,
and require little to no additional configuration. These are just <quote>on</quote>.
# defined they can be used just like any built-in action -- but within
# this file only! Aliases do not require a + or - sign.
##########################################################################
+{{alias}}
# Some useful aliases.
# Alias to turn off cookie handling, ie allow all cookies unmolested.
- -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies \
+#
+mercy-for-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies \
-session-cookies-only
# Alias to both block and treat as if an image for ad blocking
# purposes.
- +imageblock = +block +handle-as-image
-
-# Fragile sites should have the minimum changes:
- fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \
- -crunch-all-cookies -kill-popups
+#
++block-as-image = +block +handle-as-image
# Shops should be allowed to set persistent cookies
- shop = -filter -crunch-all-cookies -session-cookies-only
+#
+shop = -filter mercy-for-cookies
+# Fragile sites should receive minimum interference:
+#
+fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \
+ mercy-for-cookies -kill-popups
##########################################################################
-# Begin default action settings. Anything in this section will match
-# all URLs -- UNLESS we have exceptions that also match, defined below this
-# section. We will show all potential actions here whether they are on
-# or off. We could omit any disabled action if we wanted, since all
+# Matching starts here. Remember that at this time, all actions are
+# disabled, so we need to explicitly enable the ones we want.
+#
+# We begin with "default" action settings, i.e. we define a set of actions
+# for a pattern ("/") <link linkend="af-patterns">that matches all URLs</link>. This default set will be
+# applied to all requests as a start, and can be partly or wholly overridden
+# by later matches further down this file, or in user.action.
+#
+# We will show all potential actions here whether they are enabled
+# or not. We could omit any disabled action if we wanted, since all
# actions are 'off' by default anyway. Shown for completeness only.
# Actions are enabled if preceded by a '+', otherwise they are disabled
# (unless an alias has been defined without this).
# Allow persistent cookies for a few regular sites that we
# trust via our above alias. These will be saved from one browser session
# to the next. We are explicity turning off any and all cookie handling,
-# even though the cunch-*-cookies settings were disabled in our above
+# even though the crunch-*-cookies settings were disabled in our above
# default.action anyway. So cookies from these domains will come through
# unmolested.
{ -crunch-all-cookies }
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: user-manual.sgml,v $
+ Revision 1.110 2002/05/14 19:10:45 oes
+ Restored alphabetical order of actions
+
+ Revision 1.109 2002/05/14 17:23:11 oes
+ Renamed the prevent-*-cookies actions, extended aliases section and moved it before the example AFs
+
Revision 1.108 2002/05/14 15:29:12 oes
Completed proofreading the actions chapter
projects / privoxy.git / blobdiff