This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.203 2016/02/26 12:27:32 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.206 2016/03/17 10:43:07 fabiankeil Exp $
Copyright (C) 2001-2014 Privoxy Developers http://www.privoxy.org/
See LICENSE.
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 2.203 2016/02/26 12:27:32 fabiankeil Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.206 2016/03/17 10:43:07 fabiankeil Exp $</pubdate>
<!--
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="tag-pattern"><title>The Tag Pattern</title>
+<sect3 id="tag-pattern"><title>The Request Tag Pattern</title>
<para>
- Tag patterns are used to change the applying actions based on the
- request's tags. Tags can be created with either the
- <link linkend="CLIENT-HEADER-TAGGER">client-header-tagger</link>
+ Request tag patterns are used to change the applying actions based on the
+ request's tags. Tags can be created based on HTTP headers with either
+ the <link linkend="CLIENT-HEADER-TAGGER">client-header-tagger</link>
or the <link linkend="SERVER-HEADER-TAGGER">server-header-tagger</link> action.
</para>
<para>
- Tag patterns have to start with <quote>TAG:</quote>, so &my-app;
- can tell them apart from URL patterns. Everything after the colon
+ Request tag patterns have to start with <quote>TAG:</quote>, so &my-app;
+ can tell them apart from other patterns. Everything after the colon
including white space, is interpreted as a regular expression with
path pattern syntax, except that tag patterns aren't left-anchored
automatically (&my-app; doesn't silently add a <quote>^</quote>,
</para>
<para>
- Sections can contain URL and tag patterns at the same time,
- but tag patterns are checked after the URL patterns and thus
+ Sections can contain URL and request tag patterns at the same time,
+ but request tag patterns are checked after the URL patterns and thus
always overrule them, even if they are located before the URL patterns.
</para>
<para>
- Once a new tag is added, Privoxy checks right away if it's matched by one
- of the tag patterns and updates the action settings accordingly. As a result
- tags can be used to activate other tagger actions, as long as these other
+ Once a new request tag is added, Privoxy checks right away if it's matched by one
+ of the request tag patterns and updates the action settings accordingly. As a result
+ request tags can be used to activate other tagger actions, as long as these other
taggers look for headers that haven't already be parsed.
</para>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="negative-tag-patterns"><title>The Negative Tag Patterns</title>
+<sect3 id="negative-tag-patterns"><title>The Negative Request Tag Patterns</title>
<para>
- To match requests that do not have a certain tag, specify a negative tag pattern
+ To match requests that do not have a certain request tag, specify a negative tag pattern
by prefixing the tag pattern line with either <quote>NO-REQUEST-TAG:</quote>
or <quote>NO-RESPONSE-TAG:</quote> instead of <quote>TAG:</quote>.
</para>
<para>
- Negative tag patterns created with <quote>NO-REQUEST-TAG:</quote> are checked
+ Negative request tag patterns created with <quote>NO-REQUEST-TAG:</quote> are checked
after all client headers are scanned, the ones created with <quote>NO-RESPONSE-TAG:</quote>
are checked after all server headers are scanned. In both cases all the created
tags are considered.
</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="client-tag-pattern"><title>The Client Tag Pattern</title>
+
+<!-- XXX: This section contains duplicates content from the
+ client-specific-tag documentation. -->
+
+<warning>
+<para>
+ This is an experimental feature. The syntax is likely to change in future versions.
+</para>
+</warning>
+
+<para>
+ Client tag patterns are not set based on HTTP headers but based on
+ the client's IP address. Users can enable them themselves, but the
+ Privoxy admin controls which tags are available and what their effect
+ is.
+</para>
+
+<para>
+ After a client-specific tag has been defined with the
+ <link linkend="client-specific-tag">client-specific-tag</link>,
+ directive, action sections can be activated based on the tag by using a
+ CLIENT-TAG pattern. The CLIENT-TAG pattern is evaluated at the same priority
+ as URL patterns, as a result the last matching pattern wins. Tags that
+ are created based on client or server headers are evaluated later on
+ and can overrule CLIENT-TAG and URL patterns!
+</para>
+<para>
+ The tag is set for all requests that come from clients that requested
+ it to be set. Note that "clients" are differentiated by IP address,
+ if the IP address changes the tag has to be requested again.
+</para>
+<para>
+ Clients can request tags to be set by using the CGI interface <ulink
+ url="http://config.privoxy.org/show-client-tags">http://config.privoxy.org/show-client-tags</ulink>.
+</para>
+
+<para>
+ Example:
+</para>
+
+<para>
+ <screen>
+# If the admin defined the client-specific-tag circumvent-blocks,
+# and the request comes from a client that previously requested
+# the tag to be set, overrule all previous +block actions that
+# are enabled based on URL to CLIENT-TAG patterns.
+{-block}
+CLIENT-TAG:^circumvent-blocks$
+
+# This section is not overruled because it's located after
+# the previous one.
+{+block{Nobody is supposed to request this.}}
+example.org/blocked-example-page</screen>
+</para>
</sect2>
<term>Example usage:</term>
<listitem>
<para>
- <screen>+add-header{X-User-Tracking: sucks}</screen>
+ <screen># Add a DNT ("Do not track") header to all requests,
+# event to those that already have one.
+#
+# This is just an example, not a recommendation.
+#
+# There is no reason to believe that user-tracking websites care
+# about the DNT header and depending on the User-Agent, adding the
+# header may make user-tracking easier.
+{+add-header{DNT: 1}}
+/</screen>
</para>
</listitem>
</varlistentry>
projects / privoxy.git / blobdiff