Bump copyright

[privoxy.git] / doc / source / user-manual.sgml

diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 0b6a664..b3e14d8 100644 (file)
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -13,7 +13,7 @@
 <!entity p-authors SYSTEM "p-authors.sgml">
 <!entity config SYSTEM "p-config.sgml">
 <!entity changelog SYSTEM "changelog.sgml">
 <!entity p-authors SYSTEM "p-authors.sgml">
 <!entity config SYSTEM "p-config.sgml">
 <!entity changelog SYSTEM "changelog.sgml">

-<!entity p-version "3.0.25">
+<!entity p-version "3.0.27">

 <!entity p-status "UNRELEASED">
 <!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc  -->
 <!entity % p-not-stable "INCLUDE">
 <!entity p-status "UNRELEASED">
 <!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc  -->
 <!entity % p-not-stable "INCLUDE">


@@ -36,9 +36,9 @@
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
 
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
 

- $Id: user-manual.sgml,v 2.202 2016/01/23 13:57:17 diem Exp $
+ $Id: user-manual.sgml,v 2.219 2017/04/20 11:11:43 fabiankeil Exp $

 
 

- Copyright (C) 2001-2014 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2017 Privoxy Developers https://www.privoxy.org/

  See LICENSE.
 
  ========================================================================
  See LICENSE.
 
  ========================================================================


@@ -57,12 +57,12 @@
  <subscript>
 <!-- Completely the wrong markup, but very little is allowed  -->
 <!-- in this part of an article. FIXME -->
  <subscript>
 <!-- Completely the wrong markup, but very little is allowed  -->
 <!-- in this part of an article. FIXME -->

- <link linkend="copyright">Copyright</link> &my-copy; 2001-2014 by
- <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
+ <link linkend="copyright">Copyright</link> &my-copy; 2001-2017 by
+ <ulink url="https://www.privoxy.org/">Privoxy Developers</ulink>

  </subscript>
 </pubdate>
 
  </subscript>
 </pubdate>
 

-<pubdate>$Id: user-manual.sgml,v 2.202 2016/01/23 13:57:17 diem Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.219 2017/04/20 11:11:43 fabiankeil Exp $</pubdate>

 
 <!--
 
 
 <!--
 


@@ -92,7 +92,7 @@ Hal.
  <para>
   The <citetitle>Privoxy User Manual</citetitle> gives users information on how to
   install, configure and use <ulink
  <para>
   The <citetitle>Privoxy User Manual</citetitle> gives users information on how to
   install, configure and use <ulink

-  url="http://www.privoxy.org/">Privoxy</ulink>.
+  url="https://www.privoxy.org/">Privoxy</ulink>.

  </para>
 
 <!-- Include privoxy.sgml boilerplate: -->
  </para>
 
 <!-- Include privoxy.sgml boilerplate: -->


@@ -101,14 +101,11 @@ Hal.
 
  <para>
   You can find the latest version of the <citetitle>Privoxy User Manual</citetitle> at  <ulink
 
  <para>
   You can find the latest version of the <citetitle>Privoxy User Manual</citetitle> at  <ulink

-  url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
+  url="https://www.privoxy.org/user-manual/">https://www.privoxy.org/user-manual/</ulink>.

   Please see the <link linkend="contact">Contact section</link> on how to
   contact the developers.
  </para>
 
   Please see the <link linkend="contact">Contact section</link> on how to
   contact the developers.
  </para>
 

-<!--   <para> -->
-<!--    Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
-<!--   </para> -->

 </abstract>
 
 </artheader>
 </abstract>
 
 </artheader>


@@ -162,7 +159,7 @@ Hal.
  <application>Privoxy</application> is available both in convenient pre-compiled
  packages for a wide range of operating systems, and as raw source code.
  For most users, we recommend using the packages, which can be downloaded from our
  <application>Privoxy</application> is available both in convenient pre-compiled
  packages for a wide range of operating systems, and as raw source code.
  For most users, we recommend using the packages, which can be downloaded from our

- <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project
+ <ulink url="https://sourceforge.net/projects/ijbswa/">Privoxy Project

  Page</ulink>.
 </para>
 
  Page</ulink>.
 </para>
 


@@ -351,14 +348,14 @@ How to install the binary packages depends on your operating system:
 <para>
  The most convenient way to obtain the <application>Privoxy</application> sources
  is to download the source tarball from our
 <para>
  The most convenient way to obtain the <application>Privoxy</application> sources
  is to download the source tarball from our

- <ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118&amp;package_id=10571">project download
+ <ulink url="https://sourceforge.net/projects/ijbswa/files/Sources/">project download

  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
  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
+ version directly from <ulink url="https://sourceforge.net/p/ijbswa/code/?source=navbar">the

  CVS repository</ulink>.
 <!--
  deprecated...out of business.
  CVS repository</ulink>.
 <!--
  deprecated...out of business.


@@ -379,8 +376,8 @@ How to install the binary packages depends on your operating system:
 <para>
  If you wish to receive an email notification whenever we release updates of
  <application>Privoxy</application> or the actions file, <ulink
 <para>
  If you wish to receive an email notification whenever we release updates of
  <application>Privoxy</application> or the actions file, <ulink

- url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce/">subscribe
- to our announce  mailing list</ulink>, ijbswa-announce@lists.sourceforge.net.
+ url="https://lists.privoxy.org/mailman/listinfo/privoxy-announce">subscribe
+ to our announce mailing list</ulink>, privoxy-announce@lists.privoxy.org.

 </para>
 
 <para>
 </para>
 
 <para>


@@ -1408,7 +1405,7 @@ for details.
 
 <!--   ~~~~~       New section      ~~~~~     -->
 
 
 <!--   ~~~~~       New section      ~~~~~     -->
 

-<sect2>
+<sect2 id="control-with-webbrowser">

 <title>Controlling Privoxy with Your Web Browser</title>
 <para>
  <application>Privoxy</application>'s user interface can be reached through the special
 <title>Controlling Privoxy with Your Web Browser</title>
 <para>
  <application>Privoxy</application>'s user interface can be reached through the special


@@ -1442,7 +1439,7 @@ for details.
  </member>
  <member>
   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink
  </member>
  <member>
   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink

-  url="http://www.privoxy.org/&p-version;/user-manual/">Documentation</ulink>
+  url="https://www.privoxy.org/&p-version;/user-manual/">Documentation</ulink>

  </member>
  </simplelist>
  </msgtext>
  </member>
  </simplelist>
  </msgtext>


@@ -1873,7 +1870,7 @@ for details.
 </para>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 </para>
 
 <!--   ~~~~~       New section      ~~~~~     -->

-<sect2>
+<sect2 id="right-mix">

 <title>Finding the Right Mix</title>
 <para>
  Note that some <link linkend="actions">actions</link>, like cookie suppression
 <title>Finding the Right Mix</title>
 <para>
  Note that some <link linkend="actions">actions</link>, like cookie suppression


@@ -1898,7 +1895,7 @@ for details.
 </sect2>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 </sect2>
 
 <!--   ~~~~~       New section      ~~~~~     -->

-<sect2>
+<sect2 id="how-to-edit">

 <title>How to Edit</title>
 <para>
  The easiest way to edit the actions files is with a browser by
 <title>How to Edit</title>
 <para>
  The easiest way to edit the actions files is with a browser by


@@ -2219,7 +2216,7 @@ for details.
 
 
 <!--   ~~~~~       New section      ~~~~~     -->
 
 
 <!--   ~~~~~       New section      ~~~~~     -->

-<sect3><title>The Path Pattern</title>
+<sect3 id="path-pattern"><title>The Path Pattern</title>

 
 <para>
  <application>Privoxy</application> uses <quote>modern</quote> POSIX 1003.2
 
 <para>
  <application>Privoxy</application> uses <quote>modern</quote> POSIX 1003.2


@@ -2319,18 +2316,18 @@ for details.
 
 
 <!--   ~~~~~       New section      ~~~~~     -->
 
 
 <!--   ~~~~~       New section      ~~~~~     -->

-<sect3 id="tag-pattern"><title>The Tag Pattern</title>
+<sect3 id="tag-pattern"><title>The Request Tag Pattern</title>

 
 <para>
 
 <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>
  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>,
  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>,


@@ -2346,15 +2343,15 @@ for details.
 </para>
 
 <para>
 </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>
  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>
 
  taggers look for headers that haven't already be parsed.
 </para>
 


@@ -2379,21 +2376,80 @@ for details.
 </sect3>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 </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>
 
 <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>
  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>
  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>

+</sect3>
+
+<!--   ~~~~~       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/client-tags">http://config.privoxy.org/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>
+
+</sect3>

 
 </sect2>
 
 
 </sect2>
 


@@ -2586,7 +2642,16 @@ for details.
   <term>Example usage:</term>
   <listitem>
     <para>
   <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>
    </para>
   </listitem>
  </varlistentry>


@@ -2957,6 +3022,21 @@ TAG:^User-Agent: MPlayer/
 TAG:^RANGE-REQUEST$
     </screen>
     </para>
 TAG:^RANGE-REQUEST$
     </screen>
     </para>

+    <para>
+     <screen>
+# Tag all requests with the client IP address
+#
+# (Technically the client IP address isn't included in the
+# client headers but client-header taggers can set it anyway.
+# For details see the tagger in default.filter)
+{+client-header-tagger{client-ip-address}}
+/
+
+# Change forwarding settings for requests coming from address 10.0.0.1
+{+forward-override{forward-socks5 127.0.1.2:2222 .}}
+TAG:^IP-ADDRESS: 10\.0\.0\.1$
+     </screen>
+    </para>

   </listitem>
  </varlistentry>
 
   </listitem>
  </varlistentry>
 


@@ -5434,7 +5514,7 @@ new action
 
 # Create a short, easy to remember nickname for a favorite site
 # (relies on the browser to accept and forward invalid URLs to &my-app;)
 
 # Create a short, easy to remember nickname for a favorite site
 # (relies on the browser to accept and forward invalid URLs to &my-app;)

-{ +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
+{ +redirect{https://www.privoxy.org/user-manual/actions-file.html} }

  a
 
 # Always use the expanded view for Undeadly.org articles
  a
 
 # Always use the expanded view for Undeadly.org articles


@@ -5858,7 +5938,7 @@ TAG:^image/
 
 
 <!--   ~~~~~       New section      ~~~~~     -->
 
 
 <!--   ~~~~~       New section      ~~~~~     -->

-<sect3>
+<sect3 id="summary">

 <title>Summary</title>
 <para>
  Note that many of these actions have the potential to cause a page to
 <title>Summary</title>
 <para>
  Note that many of these actions have the potential to cause a page to


@@ -6001,7 +6081,7 @@ hal stop here
  and <filename>user.action</filename> file and see how all these pieces come together:
 </para>
 
  and <filename>user.action</filename> file and see how all these pieces come together:
 </para>
 

-<sect3>
+<sect3 id="match-all">

 <title>match-all.action</title>
 <para>
  Remember <emphasis>all actions are disabled when matching starts</emphasis>,
 <title>match-all.action</title>
 <para>
  Remember <emphasis>all actions are disabled when matching starts</emphasis>,


@@ -6044,7 +6124,7 @@ hal stop here
 </para>
 </sect3>
 
 </para>
 </sect3>
 

-<sect3>
+<sect3 id="default-action">

 <title>default.action</title>
 
 <para>
 <title>default.action</title>
 
 <para>


@@ -6105,7 +6185,7 @@ for-privoxy-version=3.0.11</screen>
  The first of our specialized sections is concerned with <quote>fragile</quote>
  sites, i.e. sites that require minimum interference, because they are either
  very complex or very keen on tracking you (and have mechanisms in place that
  The first of our specialized sections is concerned with <quote>fragile</quote>
  sites, i.e. sites that require minimum interference, because they are either
  very complex or very keen on tracking you (and have mechanisms in place that

- make them unusable for people who avoid being tracked). We will simply use
+ make them unusable for people who avoid being tracked). We will use

  our pre-defined <literal>fragile</literal> alias instead of stating the list
  of actions explicitly:
 </para>
  our pre-defined <literal>fragile</literal> alias instead of stating the list
  of actions explicitly:
 </para>


@@ -6255,7 +6335,7 @@ count*.
 <para>
  It's quite remarkable how many advertisers actually call their banner
  servers ads.<replaceable>company</replaceable>.com, or call the directory
 <para>
  It's quite remarkable how many advertisers actually call their banner
  servers ads.<replaceable>company</replaceable>.com, or call the directory

- in which the banners are stored simply <quote>banners</quote>. So the above
+ in which the banners are stored literally <quote>banners</quote>. So the above

  generic patterns are surprisingly effective.
 </para>
 <para>
  generic patterns are surprisingly effective.
 </para>
 <para>


@@ -6333,7 +6413,7 @@ wiki.
 
 </sect3>
 
 
 </sect3>
 

-<sect3><title>user.action</title>
+<sect3 id="user-action"><title>user.action</title>

 
 <para>
  So far we are painting with a broad brush by setting general policies,
 
 <para>
  So far we are painting with a broad brush by setting general policies,


@@ -6711,8 +6791,10 @@ stupid-server.example.com/</screen>
 <para>
  The non-standard option letter <literal>D</literal> (dynamic) allows
  to use the variables $host, $origin (the IP address the request came from),
 <para>
  The non-standard option letter <literal>D</literal> (dynamic) allows
  to use the variables $host, $origin (the IP address the request came from),

- $path and $url. They will be replaced with the value they refer to before
- the filter is executed.
+ $path, $url and $listen-address (the address on which Privoxy accepted the
+ client request. Example: 127.0.0.1:8118).
+ They will be replaced with the value they refer to before the filter
+ is executed.

 </para>
 
 <para>
 </para>
 
 <para>


@@ -6747,7 +6829,7 @@ stupid-server.example.com/</screen>
 
 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
 
 
 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
 

-<sect2><title>Filter File Tutorial</title>
+<sect2 id="filter-file-tut"><title>Filter File Tutorial</title>

 <para>
  Now, let's complete our <quote>foo</quote> content filter. We have already defined
  the heading, but the jobs are still missing. Since all it does is to replace
 <para>
  Now, let's complete our <quote>foo</quote> content filter. We have already defined
  the heading, but the jobs are still missing. Since all it does is to replace


@@ -7469,9 +7551,10 @@ pre-defined filters for your convenience:
 </para>
 <para>
  External filters read the content from STDIN and write the rewritten
 </para>
 <para>
  External filters read the content from STDIN and write the rewritten

- content to STDOUT. The environment variables PRIVOXY_URL, PRIVOXY_PATH,
- PRIVOXY_HOST, PRIVOXY_ORIGIN can be used to get some details about the
- client request.
+ content to STDOUT.
+ The environment variables PRIVOXY_URL, PRIVOXY_PATH, PRIVOXY_HOST,
+ PRIVOXY_ORIGIN, PRIVOXY_LISTEN_ADDRESS can be used to get some details
+ about the client request.

 </para>
 <para>
  &my-app; will temporary store the content to filter in the
 </para>
 <para>
  &my-app; will temporary store the content to filter in the


@@ -7917,7 +8000,7 @@ Requests</title>
 
 
 <!--   ~~~~~       New section      ~~~~~     -->
 
 
 <!--   ~~~~~       New section      ~~~~~     -->

-<sect2>
+<sect2 id="internal-pages">

 <title>Privoxy's Internal Pages</title>
 
 <para>
 <title>Privoxy's Internal Pages</title>
 
 <para>