Add another +redirect{} example: a shortcut for illumos bugs

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

diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index ee40787..b073142 100644 (file)
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -13,11 +13,11 @@
 <!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.21">
-<!entity p-status "stable">
+<!entity p-version "3.0.22">
+<!entity p-status "UNRELEASED">

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

-<!entity % p-not-stable "IGNORE">
-<!entity % p-stable "INCLUDE">
+<!entity % p-not-stable "INCLUDE">
+<!entity % p-stable "IGNORE">

 <!entity % p-text "IGNORE">        <!-- define we are not a text only doc -->
 <!entity % p-doc "INCLUDE">        <!-- and we are a formal doc           -->
 <!entity % p-readme "IGNORE">
 <!entity % p-text "IGNORE">        <!-- define we are not a text only doc -->
 <!entity % p-doc "INCLUDE">        <!-- and we are a formal doc           -->
 <!entity % p-readme "IGNORE">


@@ -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.180 2014/05/05 09:48:36 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.190 2014/07/14 13:37:08 fabiankeil Exp $

 
 

- Copyright (C) 2001-2013 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2014 Privoxy Developers http://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-2013 by
+ <link linkend="copyright">Copyright</link> &my-copy; 2001-2014 by

  <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
  </subscript>
 </pubdate>
 
  <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
  </subscript>
 </pubdate>
 

-<pubdate>$Id: user-manual.sgml,v 2.180 2014/05/05 09:48:36 fabiankeil Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.190 2014/07/14 13:37:08 fabiankeil Exp $</pubdate>

 
 <!--
 
 
 <!--
 


@@ -3601,6 +3601,94 @@ problem-host.example.com</screen>
 </variablelist>
 </sect3>
 
 </variablelist>
 </sect3>
 

+<!--   ~~~~~       New section      ~~~~~     -->
+<sect3 renderas="sect4" id="external-filter">
+<title>external-filter</title>
+
+<variablelist>
+ <varlistentry>
+  <term>Typical use:</term>
+  <listitem>
+   <para>Modify content using a programming language of your choice.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Effect:</term>
+  <listitem>
+   <para>
+    All instances of text-based type, most notably HTML and JavaScript, to which
+    this action applies, can be filtered on-the-fly through the specified external
+    filter.
+    By default 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 an external content filter, as defined in the
+    <link linkend="filter-file">filter file</link>.
+    External filters can be defined in one or more files as defined by the
+    <literal><link linkend="filterfile">filterfile</link></literal>
+    option in the <link linkend="config">config file</link>.
+   </para>
+   <para>
+    When used in its negative form,
+    and without parameters, <emphasis>all</emphasis> filtering with external
+    filters is completely disabled.
+  </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    External filters are scripts or programs that can modify the content in
+    case common <literal><link linkend="filter">filters</link></literal>
+    aren't powerful enough. With the exception that this action doesn't
+    use pcrs-based filters, the notes in the
+    <literal><link linkend="filter">filter</link></literal> section apply.
+   </para>
+   <warning>
+    <para>
+     Currently external filters are executed with &my-app;'s privileges.
+     Only use external filters you understand and trust.
+    </para>
+   </warning>
+   <para>
+    This feature is experimental, the <literal><link
+    linkend="external-filter-syntax">syntax</link></literal>
+    may change in the future.
+   </para>
+
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+   <para>
+    <screen>+external-filter{fancy-filter}</screen>
+   </para>
+  </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+

 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 renderas="sect4" id="fast-redirects">
 <title>fast-redirects</title>
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 renderas="sect4" id="fast-redirects">
 <title>fast-redirects</title>


@@ -5280,9 +5368,15 @@ new action
     <link linkend="filter-file">filter file</link> section.
    </para>
    <para>
     <link linkend="filter-file">filter file</link> section.
    </para>
    <para>

-    This action will be ignored if you use it together with
-    <literal><link linkend="block">block</link></literal>.
-    It can be combined with
+    Requests can't be blocked and redirected at the same time,
+    applying this action together with
+    <literal><link linkend="block">block</link></literal>
+    is a configuration error. Currently the request is blocked
+    and an error message logged, the behavior may change in the
+    future and result in Privoxy rejecting the action file.
+   </para>
+   <para>
+    This action can be combined with

     <literal><link linkend="fast-redirects">fast-redirects{check-decoded-url}</link></literal>
     to redirect to a decoded version of a rewritten URL.
    </para>
     <literal><link linkend="fast-redirects">fast-redirects{check-decoded-url}</link></literal>
     to redirect to a decoded version of a rewritten URL.
    </para>


@@ -5325,6 +5419,19 @@ undeadly.org/cgi\?action=article&amp;sid=\d*$
 {+redirect{s@^http://[^/]*/results\.aspx\?q=([^&amp;]*).*@http://search.yahoo.com/search?p=$1@}}
 search.msn.com//results\.aspx\?q=
 
 {+redirect{s@^http://[^/]*/results\.aspx\?q=([^&amp;]*).*@http://search.yahoo.com/search?p=$1@}}
 search.msn.com//results\.aspx\?q=
 

+# Redirect http://example.com/&amp;bla=fasel&amp;toChange=foo (and any other value but "bar")
+# to       http://example.com/&amp;bla=fasel&amp;toChange=bar
+#
+# The URL pattern makes sure that the following request isn't redirected again.
+{+redirect{s@toChange=[^&amp;]+@toChange=bar@}}
+example.com/.*toChange=(?!bar)
+
+# Add a shortcut to look up illumos bugs
+{+redirect{s@^http://i([0-9]+)/.*@https://www.illumos.org/issues/$1@}}
+# Redirected URL = http://i4974/
+# Redirect Destination = https://www.illumos.org/issues/4974
+i[0-9][0-9][0-9][0-9]*/
+

 # Redirect remote requests for this manual
 # to the local version delivered by Privoxy
 {+redirect{s@^http://www@http://config@}}
 # Redirect remote requests for this manual
 # to the local version delivered by Privoxy
 {+redirect{s@^http://www@http://config@}}


@@ -5493,6 +5600,14 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
 # Tag every request with the content type declared by the server
 {+server-header-tagger{content-type}}
 /
 # Tag every request with the content type declared by the server
 {+server-header-tagger{content-type}}
 /

+
+# If the response has a tag starting with 'image/' enable an external
+# filter that only applies to images.
+#
+# Note that the filter is not available by default, it's just a
+# <literal><link linkend="external-filter-syntax">silly example</link></literal>.
+{+external-filter{rotate-image} +force-text-mode}
+TAG:^image/

     </screen>
     </para>
   </listitem>
     </screen>
     </para>
   </listitem>


@@ -6453,7 +6568,7 @@ stupid-server.example.com/</screen>
 </para>
 
 <para>
 </para>
 
 <para>

- &my-app; supports three different filter actions:
+ &my-app; supports three different pcrs-based filter actions:

  <literal><link linkend="filter">filter</link></literal> to
  rewrite the content that is send to the client,
  <literal><link linkend="client-header-filter">client-header-filter</link></literal>
  <literal><link linkend="filter">filter</link></literal> to
  rewrite the content that is send to the client,
  <literal><link linkend="client-header-filter">client-header-filter</link></literal>


@@ -6473,6 +6588,13 @@ stupid-server.example.com/</screen>
  applying actions through sections with <link linkend="tag-pattern">tag-patterns</link>.
 </para>
 
  applying actions through sections with <link linkend="tag-pattern">tag-patterns</link>.
 </para>
 

+<para>
+ Finally &my-app; supports the
+ <literal><link linkend="external-filter">external-filter</link></literal> action
+ to enable <literal><link linkend="external-filter-syntax">external filters</link></literal>
+ written in proper programming languages.
+</para>
+

 
 <para>
  Multiple filter files can be defined through the <literal> <link
 
 <para>
  Multiple filter files can be defined through the <literal> <link


@@ -6557,12 +6679,12 @@ 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. The will be replaced with the value they refer to before
+ $path and $url. They will be replaced with the value they refer to before

  the filter is executed.
 </para>
 
 <para>
  the filter is executed.
 </para>
 
 <para>

- Note that '$' is a bad choice as delimiter for dynamic filters as you
+ Note that '$' is a bad choice for a delimiter in a dynamic filter as you

  might end up with unintended variables if you use a variable name
  directly after the delimiter. Variables will be resolved without
  escaping anything, therefore you also have to be careful not to chose
  might end up with unintended variables if you use a variable name
  directly after the delimiter. Variables will be resolved without
  escaping anything, therefore you also have to be careful not to chose


@@ -6572,7 +6694,7 @@ stupid-server.example.com/</screen>
 
 <para>
  The non-standard option letter <literal>T</literal> (trivial) prevents
 
 <para>
  The non-standard option letter <literal>T</literal> (trivial) prevents

- parsing for backreferences in the substitute. Use if you want to include
+ parsing for backreferences in the substitute. Use it if you want to include

  text like '$&' in your substitute without quoting.
 </para>
 
  text like '$&' in your substitute without quoting.
 </para>
 


@@ -7290,6 +7412,78 @@ pre-defined filters for your convenience:
 </variablelist>
 
 </sect2>
 </variablelist>
 
 </sect2>

+
+<!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
+<sect2 id="external-filter-syntax"><title>External filter syntax</title>
+<para>
+ External filters are scripts or programs that can modify the content in
+ case common <literal><link linkend="filter">filters</link></literal>
+ aren't powerful enough.
+</para>
+<para>
+ External filters can be written in any language the platform &my-app; runs
+ on supports.
+</para>
+<para>
+ They are controlled with the
+ <literal><link linkend="external-filter">external-filter</link></literal> action
+ and have to be defined in the <literal><link linkend="filterfile">filterfile</link></literal>
+ first.
+</para>
+<para>
+ The header looks like any other filter, but instead of pcrs jobs, external
+ filters contain a single job which can be a program or a shell script (which
+ may call other scripts or programs).
+</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.
+</para>
+<para>
+ &my-app; will temporary store the content to filter in the
+ <literal><link linkend="temporary-directory">temporary-directory</link></literal>.
+</para>
+<para>
+ <screen>
+EXTERNAL-FILTER: cat Pointless example filter that doesn't actually modify the content
+/bin/cat
+
+# Incorrect reimplementation of the filter above in POSIX shell.
+#
+# Note that it's a single job that spans multiple lines, the line
+# breaks are not passed to the shell, thus the semicolons are required.
+#
+# If the script isn't trivial, it is recommended to put it into an external file.
+#
+# In general, writing external filters entirely in POSIX shell is not
+# considered a good idea.
+EXTERNAL-FILTER: cat2 Pointless example filter that despite its name may actually modify the content
+while read line; \
+do \
+  echo "$line"; \
+done
+
+EXTERNAL-FILTER: rotate-image Rotate an image by 180 degree. Test filter with limited value.
+/usr/local/bin/convert - -rotate 180 -
+
+EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The coordinates may need adjustment.
+/usr/local/bin/convert - -pointsize 16 -fill white  -annotate +17+418 "[citation needed]" -
+</screen>
+</para>
+
+<warning>
+ <para>
+  Currently external filters are executed with &my-app;'s privileges!
+  Only use external filters you understand and trust.
+ </para>
+</warning>
+<para>
+ External filters are experimental and the syntax may change in the future.
+</para>
+</sect2>
+

 </sect1>
 
 <!--  ~  End section  ~  -->
 </sect1>
 
 <!--  ~  End section  ~  -->